{ "openapi": "3.1.0", "info": { "title": "AURA Core API", "version": "3.0.0", "summary": "Agent Universal Resource Architecture: the Core commerce API for Scout and Beacon agents.", "description": "AURA is a market protocol for agentic commerce. Buyer agents and seller agents transact through a neutral broker that interprets intent, mediates the exchange, and records the outcome.\n\nAgentic commerce needs a broker because two agents that both have a stake in the price cannot safely tell each other the truth. Each probes the other and conceals its own position, and the market decays into a market for lemons with cheap, unenforceable quotes. A party with no stake can hold both sides' private information at once and resolve the asymmetry. That party is Core.\n\nEvery function here follows from that. A Scout declares intent. Core interprets it and presents sealed offers from Beacons. The buyer commits to one, Core binds the commitment and signs the chain of custody from the human signal to the outcome, and a clearing record carries the transaction to settlement. Each operation is the smallest mechanism that preserves a market invariant, and the invariants are stated in `x-aura-invariants`.\n\nThis document is the canonical AURA protocol, written for humans and for agents. The paths and schemas are the wire contract; the `x-aura-*` extensions carry the protocol's law, ontology, and economics in machine-readable form. The published JSON Schemas, the SDKs, and the interactive reference derive from it.", "contact": { "name": "AURA Labs Developer Support", "email": "support@aura-labs.ai", "url": "https://aura-labs.ai/developers.html" }, "license": { "name": "See repository LICENSE", "url": "https://aura-labs.ai/terms.html" }, "x-protocol-version": "3.0" }, "servers": [ { "url": "https://aura-labsai-production.up.railway.app", "description": "Production Core API (host; all paths are /v1-prefixed)" }, { "url": "https://sandbox.aura-labs.ai", "description": "Sandbox Core, the certification bench (host; all paths are /v1-prefixed): a standing deployment of the same Core with separate state and a distinct pinned signing key. Sandbox provisioning and reset are live here; the certification-track operations (conformance, certification, promotion) are roadmap." } ], "tags": [ { "name": "Discovery", "description": "Public capability discovery: profiles, settlement rails, signing key, and HATEOAS roots." }, { "name": "Identity", "description": "Principal (legal entity) and agent (Scout/Beacon) registration and lookup." }, { "name": "Market Navigation", "description": "Commerce sessions and offers, the core Scout/Beacon flow." }, { "name": "Transactions", "description": "Commit, retrieve, and report on transactions." }, { "name": "Beacons", "description": "Beacon (seller agent) registration and open-session discovery." }, { "name": "Business Rules", "description": "Beacon-defined business rules (age, geo, KYC)." }, { "name": "Disputes", "description": "Dispute filing, evidence, and resolution." }, { "name": "Intent Chain", "description": "Intent chain of custody, L1–L7." }, { "name": "Sandbox", "description": "The certification bench: admission-chain operations served at the sandbox host only. Each operation declares its server; nothing here serves on the production host." } ], "security": [ { "agentId": [], "agentTimestamp": [], "agentSignature": [] } ], "paths": { "/": { "get": { "tags": [ "Discovery" ], "summary": "API version discovery (HATEOAS root)", "operationId": "getRoot", "description": "An agent that has never seen this market needs a way in that asks nothing of it first. The root advertises the protocol version and the links to follow, so discovery comes before any credential or commitment.", "security": [], "responses": { "200": { "description": "Available API versions and links", "content": { "application/json": { "schema": { "type": "object", "properties": { "protocol_version": { "type": "string", "description": "The AURA protocol version this deployment implements, advertised so an agent can confirm compatibility before following any link. Mirrors x-protocol-version.", "examples": [ "3.0" ] } } } } } } } } }, "/v1/": { "get": { "tags": [ "Discovery" ], "summary": "v1 HATEOAS root", "operationId": "getV1Root", "description": "The entry point for v1. It lists the operations an agent reaches from here, so a client navigates the protocol by following links rather than hard-coding paths.", "security": [], "responses": { "200": { "description": "v1 resource links", "content": { "application/json": { "schema": { "type": "object", "properties": { "protocol_version": { "type": "string", "description": "The AURA protocol version this deployment implements, advertised so an agent can confirm compatibility before following any link. Mirrors x-protocol-version.", "examples": [ "3.0" ] } } } } } } } } }, "/v1/.well-known/core-signing-key": { "get": { "tags": [ "Discovery" ], "summary": "Core's Ed25519 public signing key", "operationId": "getCoreSigningKey", "description": "Core counter-signs offers and attestations, so a counterparty has to check those signatures without taking Core's word for its own key. The signing key is published openly for exactly that, which is what lets Core act as a [neutral broker](/invariants.html#neutral-brokerage) whose every signature is independently verifiable.", "security": [], "responses": { "200": { "description": "Core signing key", "content": { "application/json": { "schema": { "type": "object", "properties": { "public_key": { "type": "string", "description": "Base64-encoded Ed25519 public key" }, "algorithm": { "type": "string", "examples": [ "Ed25519" ] }, "is_ephemeral": { "type": "boolean" } } } } } } } } }, "/v1/sandbox/keys": { "post": { "tags": [ "Sandbox" ], "summary": "Mint a sandbox key (domain-verified)", "operationId": "mintSandboxKey", "servers": [ { "url": "https://sandbox.aura-labs.ai", "description": "Served on the certification bench only; the production host does not register this operation." } ], "description": "The obtain_scope phase of the admission chain, executable today. An agent proves two things and receives the tenant anchor for one sandbox namespace. Possession: sign the exact JSON body with the declared Ed25519 key (X-Signature header). Domain control: publish the key where only the domain's controller can, either the TXT record _aura-agent-key. with value aura-key=, or the document https:///.well-known/aura-agent-key returning JSON with a matching public_key. Possession is verified first, locally; the domain lookup runs only for a proven key, and the well-known fetch goes to public HTTPS addresses only, pinned, without redirects. One active key per domain: re-minting revokes the prior key in the same transaction, which is also the compromise-recovery path. The grant appears once and is stored hashed. The key authorizes nothing until sandbox provisioning ships; the grant says exactly what it is and when it becomes consumable. Every refusal names what Core looked for and what it found.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxKeyMintRequest" } } } }, "responses": { "201": { "description": "The grant: the key (shown once), its semantics, and the quota facts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxKeyGrant" } } } }, "400": { "description": "invalid_domain: the declared domain cannot prove control (wildcard, IP, single label, port, scheme, or malformed). The message states the rule violated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "mint_proof_invalid: X-Signature does not verify over the exact JSON body by the declared key. The message states the canonicalisation to use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "sandbox_identity_not_verified: the domain proof failed; looked_for and found tell the agent exactly what to publish and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxIdentityNotVerified" } } } }, "409": { "description": "key_already_used: the declared key is bound to an identity, key history, or another domain. Generate a fresh keypair.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "429": { "description": "rate_limit_exceeded: the mint rate limit was exceeded. Retry after the window resets.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "mint_failed: a server error prevented the mint. Safe to retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "database_unavailable: the bench database is not reachable. Retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "sandboxMintProof": [] } ] } }, "/v1/profiles": { "get": { "tags": [ "Discovery" ], "summary": "List active market profiles", "operationId": "listProfiles", "description": "A market adapts the protocol to its vertical by setting bounded parameters: how long offers stay live, how long a deal stays repudiable, which rails settle it. Profiles publish those choices so an agent reads the terms before it enters. The parameters move within bounds the [invariants](/invariants.html) fix; they never tune the law away.", "security": [], "responses": { "200": { "description": "Active profiles", "content": { "application/json": { "schema": { "type": "object", "properties": { "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" } } } } } } } } } }, "/v1/profiles/{profile_id}": { "parameters": [ { "$ref": "#/components/parameters/ProfileId" } ], "get": { "tags": [ "Discovery" ], "summary": "Retrieve a market profile", "operationId": "getProfile", "description": "Returns one market profile in full: the disclosure schedule, validity windows, settlement methods, and dispute terms a participant agrees to by transacting under it. An agent reads this to know the rules of the specific market it is entering.", "security": [], "responses": { "200": { "description": "Profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/profiles/{profile_id}/validate": { "parameters": [ { "$ref": "#/components/parameters/ProfileId" } ], "post": { "tags": [ "Discovery" ], "summary": "Validate terms against a profile's minimums", "operationId": "validateAgainstProfile", "description": "Before building against a market, an agent should learn whether a configuration is admissible under the profile rather than discovering it at commit. This checks a candidate against the profile's rules and returns the verdict.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileValidationRequest" } } } }, "responses": { "200": { "description": "Validation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "violations": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/v1/settlement-rails": { "get": { "tags": [ "Discovery" ], "summary": "List active settlement-rail adapters", "operationId": "listSettlementRails", "description": "Settlement is where value actually moves, and rails differ in finality and recourse. Publishing the available rails lets a market and its agents choose settlement with open eyes, which is what makes [rail-conditional reserve](/invariants.html#rail-conditional-reserve) and [verifiable settlement](/invariants.html#verifiable-settlement) computable rather than guessed.", "security": [], "responses": { "200": { "description": "Adapters", "content": { "application/json": { "schema": { "type": "object", "properties": { "adapters": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementRail" } } } } } } } } } }, "/v1/settlement-rails/{adapter_id}/capabilities": { "parameters": [ { "name": "adapter_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,32}$" }, "examples": { "usdc": { "value": "usdc-base" } } } ], "get": { "tags": [ "Discovery" ], "summary": "Get a settlement adapter's capabilities", "operationId": "getSettlementRailCapabilities", "description": "Returns one rail's capabilities: its finality model, whether it carries native repudiation, and the proof it emits. Clearing reads this to size the reserve to the rail ([rail-conditional reserve](/invariants.html#rail-conditional-reserve)) and to demand a correlated settlement proof ([verifiable settlement](/invariants.html#verifiable-settlement)).", "security": [], "responses": { "200": { "description": "Adapter capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementRail" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/principals": { "post": { "tags": [ "Identity" ], "summary": "Register a principal (legal entity)", "operationId": "registerPrincipal", "x-aura-signature-profile": "principal_registration", "x-aura-invariants": [ "INV-007" ], "description": "A market for lemons is what you get when a seller can shed a bad reputation by registering again. The principal is the durable, accountable entity behind the ephemeral agents, and registering it with a proof of key possession is what makes reputation and qualification stick to something that cannot be cheaply discarded ([persistent identity and qualification](/invariants.html#persistent-identity-and-qualification)).", "security": [ { "principalProof": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrincipalRegistration" } } } }, "responses": { "200": { "description": "Existing principal (idempotent replay)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Principal" } } } }, "201": { "description": "Principal registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Principal" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/principals/{principal_id}": { "parameters": [ { "name": "principal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Identity" ], "summary": "Retrieve a principal", "operationId": "getPrincipal", "description": "A principal's record is the accountable root the rest of the protocol chains back to. Reading it is scoped to the entity acting on its own anchor ([least-privilege delegated authority](/invariants.html#least-privilege-delegated-authority)): a caller sees its own principal, never another's.", "responses": { "200": { "description": "Principal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Principal" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Identity" ], "summary": "Update a principal's mutable fields", "operationId": "updatePrincipal", "description": "A principal's contact and operating name change over time; its legal identity and verification history are fixed. Update accepts the mutable fields and refuses the immutable ones, and only the entity acting on its own anchor may call it ([least-privilege delegated authority](/invariants.html#least-privilege-delegated-authority)).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrincipalUpdate" } } } }, "responses": { "200": { "description": "Updated principal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Principal" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/principals/{principal_id}/rotate-key": { "parameters": [ { "name": "principal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Identity" ], "summary": "Rotate a principal signing key", "operationId": "rotatePrincipalKey", "description": "Rotates a principal signing key under the same canonical payload and dual-signature rule as agent rotation ([persistent identity and qualification](/invariants.html#persistent-identity-and-qualification)). Principal requests carry no request-level agent authentication, so old_key_authorization is required in the body: the current principal key must authorize the rotation explicitly. The verification level, bound agents, and history persist unchanged.", "x-aura-invariants": [ "INV-007" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyRotationRequest" } } } }, "responses": { "200": { "description": "Key rotated. The identity, its bindings, reputation, and history are unchanged; the retired key is verification-only history.", "content": { "application/json": { "schema": { "type": "object", "properties": { "principal_id": { "type": "string", "format": "uuid" }, "key_id": { "type": "string", "description": "Fingerprint of the now-active key." }, "rotated_at": { "type": "string", "format": "date-time" }, "idempotent_replay": { "type": "boolean", "description": "Present and true when this response answers an exact duplicate of an already-committed rotation." } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The rotation conflicts with existing state: key_already_used (the key exists on an identity or in key history), rotation_replayed (stale timestamp or reused tuple), or key_rotation_conflict (the current key no longer matches the key the payload was constructed against; rebuild against the current key).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "422": { "description": "invalid_key_proof: new_key_proof does not verify over the canonical rotation payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/v1/principals/{principal_id}/recover-key": { "parameters": [ { "name": "principal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Identity" ], "summary": "Recover a principal key (not yet available)", "operationId": "recoverPrincipalKey", "x-aura-status": "roadmap", "description": "A compromised principal key cannot authorize its own replacement. Principal identity anchors in external credentials, the same relying-party act that establishes the verification level, and recovery re-anchors on those credentials through a re-verification workflow that has not yet shipped. Until it does, this operation answers 403 recovery_not_available unconditionally, and a compromised principal key is an operational incident: revoke the bound agents and contact the operator. The versioned discovery root advertises features.principal_key_recovery so an agent can learn the capability without probing.", "responses": { "403": { "description": "recovery_not_available: principal key recovery requires re-verification against external credentials, which is not yet available.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/v1/agents/register": { "post": { "tags": [ "Identity" ], "summary": "Register an agent (Scout or Beacon)", "operationId": "registerAgent", "x-aura-signature-profile": "agent_registration", "x-aura-invariants": [ "INV-007" ], "description": "An agent is a key, and a key is cheap. What makes an agent trustworthy is the durable principal it acts for. Registration binds the agent's key to a principal with a proof of possession, so every action the agent takes inherits an accountable identity ([persistent identity and qualification](/invariants.html#persistent-identity-and-qualification)).", "security": [ { "agentProof": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRegistration" } } } }, "responses": { "200": { "description": "Existing agent (idempotent replay)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "201": { "description": "Agent registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/agents/{agent_id}": { "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Identity" ], "summary": "Get agent details", "operationId": "getAgent", "description": "An agent is a marker that indexes a durable record, so a counterparty has to resolve what an agent is and whose authority it carries. This returns the agent's type, status, and principal binding, scoped to the caller's own anchor ([least-privilege delegated authority](/invariants.html#least-privilege-delegated-authority)).", "responses": { "200": { "description": "Agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/principals/{principal_id}/agents": { "parameters": [ { "name": "principal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Identity" ], "summary": "List a principal's agents", "operationId": "listPrincipalAgents", "description": "A principal may run many agents. Listing them is an administrative view of the entity's own roster, available only to the entity acting on its own anchor ([least-privilege delegated authority](/invariants.html#least-privilege-delegated-authority)); one agent cannot enumerate another principal's fleet.", "responses": { "200": { "description": "Agents bound to the principal", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/principals/{principal_id}/agents/{agent_id}/replace-key": { "parameters": [ { "name": "principal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Identity" ], "summary": "Replace a compromised agent key (principal-authorized recovery)", "operationId": "replaceAgentKey", "description": "Compromise recovery for an agent key that can no longer be trusted to sign. The principal that anchors the agent authorizes the replacement: principal_authorization is the principal key's signature over the same canonical payload, and the compromised key signs nothing. A holder of the stolen agent key alone cannot move the identity; the authority to replace an agent's key rests with its principal ([least-privilege delegated authority](/invariants.html#least-privilege-delegated-authority)). The agent must be bound to the addressed principal.", "x-aura-invariants": [ "INV-007", "INV-015" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyReplacementRequest" } } } }, "responses": { "200": { "description": "Key rotated. The identity, its bindings, reputation, and history are unchanged; the retired key is verification-only history.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "key_id": { "type": "string", "description": "Fingerprint of the now-active key." }, "rotated_at": { "type": "string", "format": "date-time" }, "idempotent_replay": { "type": "boolean", "description": "Present and true when this response answers an exact duplicate of an already-committed rotation." } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The rotation conflicts with existing state: key_already_used (the key exists on an identity or in key history), rotation_replayed (stale timestamp or reused tuple), or key_rotation_conflict (the current key no longer matches the key the payload was constructed against; rebuild against the current key).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "422": { "description": "invalid_key_proof: new_key_proof does not verify over the canonical rotation payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/v1/principals/{principal_id}/transactions": { "parameters": [ { "name": "principal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } } ], "get": { "tags": [ "Identity" ], "summary": "List transactions a principal is party to", "operationId": "listPrincipalTransactions", "description": "Accountability outlives any single agent or session, so a principal has to see what was committed in its name after the fact. This returns the transactions the principal is party to, scoped to its own anchor ([least-privilege delegated authority](/invariants.html#least-privilege-delegated-authority)).", "responses": { "200": { "description": "Transactions (paginated)", "headers": { "X-Total-Count": { "description": "Total matching transactions.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/revoke": { "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Identity" ], "summary": "Revoke an agent identity", "operationId": "revokeAgent", "description": "When an agent misbehaves or its key is compromised, the harm has to be stoppable without unwinding the principal behind it. Revocation blacklists the agent's key so its future requests are refused, while the principal and its history persist ([persistent identity and qualification](/invariants.html#persistent-identity-and-qualification)).", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Agent revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "examples": [ "revoked" ] }, "revoked_at": { "type": "string", "format": "date-time" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/rotate-key": { "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Identity" ], "summary": "Rotate an agent signing key", "operationId": "rotateAgentKey", "description": "An agent's key is an instrument of its identity, never the identity itself. Rotation replaces the signing key while the agent's id, principal binding, reputation, and history persist unchanged ([persistent identity and qualification](/invariants.html#persistent-identity-and-qualification)). The operation is dual-signed over the canonical key_rotation payload: new_key_proof proves possession of the incoming key, and the current key authorizes. old_key_authorization is required: the current key must sign the canonical payload explicitly, because the request signature does not bind the request body and so cannot authorize the enclosed rotation. Core constructs old_public_key from the live record; a payload built against a superseded key fails as key_rotation_conflict. The rotation timestamp must fall within 300 seconds of receipt, and an exact duplicate of a committed rotation returns idempotent success. The retired key moves to verification-only history: everything it ever signed remains verifiable, and it authorizes nothing new. An agent can rotate only its own key.", "x-aura-invariants": [ "INV-007" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyRotationRequest" } } } }, "responses": { "200": { "description": "Key rotated. The identity, its bindings, reputation, and history are unchanged; the retired key is verification-only history.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "key_id": { "type": "string", "description": "Fingerprint of the now-active key." }, "rotated_at": { "type": "string", "format": "date-time" }, "idempotent_replay": { "type": "boolean", "description": "Present and true when this response answers an exact duplicate of an already-committed rotation." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The rotation conflicts with existing state: key_already_used (the key exists on an identity or in key history), rotation_replayed (stale timestamp or reused tuple), or key_rotation_conflict (the current key no longer matches the key the payload was constructed against; rebuild against the current key).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "422": { "description": "invalid_key_proof: new_key_proof does not verify over the canonical rotation payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/v1/agents/{agent_id}/delegation-scope": { "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "put": { "tags": [ "Identity" ], "summary": "Create or replace the active delegation scope", "operationId": "putDelegationScope", "description": "A principal narrows what its agents may do by setting their scope, never by trusting them to stay in bounds on their own. Writing the scope fixes the signed mandate a commit is later tested against ([least-privilege delegated authority](/invariants.html#least-privilege-delegated-authority), [constraints as bounds](/invariants.html#constraints-as-bounds)).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationScopeRequest" } } } }, "responses": { "200": { "description": "Active delegation scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationScope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "tags": [ "Identity" ], "summary": "Get the active delegation scope", "operationId": "getDelegationScope", "description": "Authority an agent assumes by default is authority no principal granted. The delegation scope is the explicit, signed boundary a principal sets on what an agent may commit. Reading it is how [least-privilege delegated authority](/invariants.html#least-privilege-delegated-authority) becomes inspectable.", "responses": { "200": { "description": "Active delegation scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationScope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/beacons/register": { "post": { "tags": [ "Beacons" ], "summary": "Register or update a beacon", "operationId": "registerBeacon", "description": "A seller's agent has to be discoverable to be matched, but discoverability without accountability invites throwaway offers. Registering a Beacon publishes its categories and capabilities while binding it to a principal, so the market can match it and still hold it answerable.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeaconRegistration" } } } }, "responses": { "200": { "description": "Beacon registered or updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Beacon" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/beacons/sessions": { "get": { "tags": [ "Beacons" ], "summary": "Poll open sessions to bid on", "operationId": "listBeaconSessions", "description": "A Beacon needs to know which sessions it has been matched into before it can make an offer. This lists the open sessions awaiting the Beacon's response.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Open sessions (redacted)", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/SessionSummary" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/beacons/{beacon_id}": { "parameters": [ { "name": "beacon_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Beacon UUID or externalId." } ], "get": { "tags": [ "Beacons" ], "summary": "Get a beacon", "operationId": "getBeacon", "description": "Matching and reputation operate on what a Beacon claims it can do. This returns a Beacon's public profile so a counterparty knows its declared capabilities.", "responses": { "200": { "description": "Beacon", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Beacon" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/sessions": { "post": { "tags": [ "Market Navigation" ], "summary": "Create a commerce session from intent", "operationId": "createSession", "x-aura-signature-profile": "interpretation_attestation", "x-aura-invariants": [ "INV-001", "INV-004", "INV-008" ], "description": "A buyer's intent has to enter the market somewhere. Sent straight to sellers, it hands them the buyer's position to probe and price against, and it leaves no neutral account of what was asked. The session is where Core takes the intent instead: it interprets the natural language, signs an attestation binding the raw words to their structured meaning, and stands in the middle as [neutral broker](/invariants.html#neutral-brokerage) rather than wiring the two sides together, recording the intent from its origin ([recorded intent and chain of custody](/invariants.html#recorded-intent-and-chain-of-custody)). The interpretation fixes the authorised negotiation space before any offer exists, so a later commitment can be tested against the mandate the principal actually granted ([constraints as bounds](/invariants.html#constraints-as-bounds)).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionCreate" } } } }, "responses": { "200": { "description": "Session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/sessions/{session_id}": { "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "get": { "tags": [ "Market Navigation" ], "summary": "Retrieve a session", "operationId": "getSession", "x-aura-invariants": [ "INV-002", "INV-003" ], "description": "A Scout watches its session to know when offers are ready and what state it is in. What it sees respects [identity abstraction until commitment](/invariants.html#identity-abstraction-until-commitment), so a counterparty's identity stays sealed, and [monotonic disclosure](/invariants.html#monotonic-disclosure), so a field once visible never vanishes. Reading the session never leaks what the phase has not yet earned.", "responses": { "200": { "description": "Session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/sessions/{session_id}/offers": { "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "post": { "tags": [ "Market Navigation" ], "summary": "Submit a signed offer (Beacon)", "operationId": "submitOffer", "x-aura-signature-profile": "beacon_offer", "x-aura-invariants": [ "INV-001", "INV-002", "INV-004", "INV-005" ], "description": "An offer is a seller's commitment to terms, and a market is only as real as that commitment. A bare price is cheap to send and cheaper to retract. So the Beacon signs the offer with its key, Core verifies it and counter-signs as [neutral broker](/invariants.html#neutral-brokerage), and the offer carries an [expiry](/invariants.html#offer-expiry) from the moment it exists. The buyer's identity stays sealed while this happens ([identity abstraction until commitment](/invariants.html#identity-abstraction-until-commitment)), so the seller prices the goods and not the counterparty, and the terms are checked against the session's [bounds](/invariants.html#constraints-as-bounds).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferSubmission" } } } }, "responses": { "201": { "description": "Offer accepted and counter-signed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Offer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "tags": [ "Market Navigation" ], "summary": "List pending offers (Scout)", "operationId": "listOffers", "x-aura-invariants": [ "INV-002", "INV-003" ], "description": "Offers are what a Scout chooses between, and seeing them must not become a way to unmask sellers early. This returns the session's offers under [identity abstraction until commitment](/invariants.html#identity-abstraction-until-commitment) and [monotonic disclosure](/invariants.html#monotonic-disclosure): the terms are visible, the counterparty behind them is not, until commitment earns it.", "responses": { "200": { "description": "Offers", "content": { "application/json": { "schema": { "type": "object", "properties": { "offers": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/sessions/{session_id}/commit": { "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "post": { "tags": [ "Transactions" ], "summary": "Commit to an offer", "operationId": "commitSession", "x-aura-signature-profile": "core_offer_countersignature", "x-aura-invariants": [ "INV-001", "INV-004", "INV-005", "INV-006", "INV-008", "INV-010", "INV-013" ], "description": "Commitment is the single irreversible step, so it is where every guarantee has to hold at once. A naive accept that just flips a flag invites the failures a market cannot survive: committing on a price that has [expired](/invariants.html#offer-expiry), exceeding the [authority the principal delegated](/invariants.html#constraints-as-bounds), or leaving half a transaction behind when something fails midway. Commit refuses all of them in one [atomic act](/invariants.html#atomic-commitment): it checks the offer is live and within the mandate, records consent and extends the [signed chain of custody](/invariants.html#recorded-intent-and-chain-of-custody), and either creates the transaction and rejects its siblings or changes nothing at all. Replaying an idempotency key returns the original result rather than committing twice. Then clearing begins, sizing the reserve to the rail ([rail-conditional reserve](/invariants.html#rail-conditional-reserve)) and refusing any failed [business rule](/invariants.html#business-rules-as-hard-gates).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitRequest" } } } }, "responses": { "200": { "description": "Committed transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "offer_expired: the offer's expiry has passed; no transaction is created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/v1/transactions/{transaction_id}": { "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Transactions" ], "summary": "Retrieve a transaction", "operationId": "getTransaction", "description": "A transaction is the durable record a dispute or an audit reads long after the session closes. This returns it: the committed terms, the counter-signatures, and the current fulfilment, payment, and clearing state.", "responses": { "200": { "description": "Transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/sessions/{session_id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "post": { "tags": [ "Market Navigation" ], "summary": "Cancel a session", "operationId": "cancelSession", "description": "A Scout that no longer wants what it asked for needs a clean exit before it commits, so abandoned sessions do not linger as phantom demand. Cancel closes a session the caller owns, provided it has not already committed.", "responses": { "200": { "description": "Session cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "examples": [ "cancelled" ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/sessions/{session_id}/attestation": { "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "get": { "tags": [ "Market Navigation" ], "summary": "Get the interpretation attestation", "operationId": "getAttestation", "x-aura-signature-profile": "interpretation_attestation", "x-aura-invariants": [ "INV-008" ], "description": "When Core interprets a natural-language intent, the buyer has to be able to prove later what Core understood it to mean. The attestation is Core's signed binding between the raw words and their structured interpretation, the first link in the [recorded chain of custody](/invariants.html#recorded-intent-and-chain-of-custody).", "responses": { "200": { "description": "Signed attestation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attestation" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/offers/{offer_id}/counter": { "parameters": [ { "name": "offer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Market Navigation" ], "summary": "Counter an offer (Scout)", "operationId": "counterOffer", "x-aura-invariants": [ "INV-004", "INV-005" ], "description": "Negotiation moves in bounded, finite steps. A counter-offer answers with revised terms that still sit inside the session's [constraints](/invariants.html#constraints-as-bounds) and carries its own [expiry](/invariants.html#offer-expiry), so each round stays within the mandate and stays finite.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterOfferRequest" } } } }, "responses": { "201": { "description": "Counter-offer created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NegotiatedOffer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Conflict: offer_not_counterable (terminal negotiation state), session_not_negotiable, or offer_expired (the offer's expiry has passed).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "429": { "description": "Negotiation chain exhausted (depth cap reached)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/transactions/{transaction_id}/fulfillment": { "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "put": { "tags": [ "Transactions" ], "summary": "Report fulfillment status", "operationId": "updateFulfillment", "description": "A committed deal still has to be delivered. Fulfilment updates record delivery progress on the transaction, moving it toward completion or surfacing the gap a dispute would test.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentUpdate" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "fulfillment_status": { "type": "string" }, "fulfillment_reference": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/transactions/{transaction_id}/payment": { "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "put": { "tags": [ "Transactions" ], "summary": "Report payment status", "operationId": "updatePayment", "x-aura-invariants": [ "INV-009" ], "description": "Money moving has to leave a proof, or settlement becomes a claim nobody can check. A payment update records settlement against a rail-signed proof correlated to the instruction ([verifiable settlement](/invariants.html#verifiable-settlement)).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentUpdate" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_reference": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/transactions/{transaction_id}/clearing": { "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Transactions" ], "summary": "Read the clearing record", "operationId": "getClearing", "x-aura-invariants": [ "INV-009", "INV-010", "INV-011", "INV-012" ], "description": "Clearing is where risk is priced and the reserve is held, and a market trusts it only if the pricing is neutral and legible. This exposes the clearing record: the [rail-conditional reserve](/invariants.html#rail-conditional-reserve), the [settlement proof](/invariants.html#verifiable-settlement), and a risk score that is a function of risk and rail alone ([financial neutrality of the clearinghouse](/invariants.html#financial-neutrality-of-the-clearinghouse)), shown only to the party it belongs to ([bilateral risk transparency](/invariants.html#bilateral-risk-transparency)).", "responses": { "200": { "description": "Clearing record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClearingRecord" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/business-rules": { "post": { "tags": [ "Business Rules" ], "summary": "Register a business rule (Beacon)", "operationId": "createBusinessRule", "x-aura-invariants": [ "INV-013" ], "description": "Some conditions decide whether a deal is allowed at all, ahead of any pricing: an age minimum, a geographic restriction, a verification requirement. A business rule registers such a gate, and Core refuses any commit that fails it however attractive the price ([business rules as hard gates](/invariants.html#business-rules-as-hard-gates)).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessRuleCreate" } } } }, "responses": { "200": { "description": "Existing rule (idempotent replay)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessRule" } } } }, "201": { "description": "Rule created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessRule" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "get": { "tags": [ "Business Rules" ], "summary": "List a beacon's active rules", "operationId": "listBusinessRules", "description": "A Beacon's hard eligibility rules decide who it will deal with at all, so they have to be inspectable. This lists the business rules a Beacon has in force.", "parameters": [ { "name": "beacon_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Active rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessRule" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/business-rules/{rule_id}": { "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "delete": { "tags": [ "Business Rules" ], "summary": "Revoke a business rule", "operationId": "revokeBusinessRule", "description": "Eligibility rules change as a Beacon's obligations change. Revoking a rule retires the gate going forward while leaving the committed transactions it once governed untouched, so the record of why a past deal was allowed stays intact.", "responses": { "204": { "description": "Revoked (no content)" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/transactions/{transaction_id}/disputes": { "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Disputes" ], "summary": "File a dispute", "operationId": "fileDispute", "x-aura-invariants": [ "INV-014" ], "description": "A market that calls every settled deal final has no recourse, and agents will not commit real money without it. Filing a dispute reopens a committed transaction within the window the market declared before commitment ([repudiability within a bounded window](/invariants.html#repudiability-within-a-bounded-window)), turning finality without recourse into accountable settlement.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeFile" } } } }, "responses": { "201": { "description": "Dispute filed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/disputes/{dispute_id}/evidence": { "parameters": [ { "name": "dispute_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Disputes" ], "summary": "Submit dispute evidence", "operationId": "submitEvidence", "x-aura-invariants": [ "INV-014" ], "description": "A dispute is resolved on evidence, and the strongest evidence is already in the protocol: the signed offer, the commitment, the fulfilment record. This attaches a party's evidence to an open dispute, inside its [bounded window](/invariants.html#repudiability-within-a-bounded-window).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceSubmission" } } } }, "responses": { "201": { "description": "Evidence recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "evidence_id": { "type": "string", "format": "uuid" }, "dispute_id": { "type": "string", "format": "uuid" }, "submitted_by": { "type": "string", "format": "uuid" }, "submitted_at": { "type": "string", "format": "date-time" }, "type": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/disputes/{dispute_id}/resolve": { "parameters": [ { "name": "dispute_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Disputes" ], "summary": "Resolve or withdraw a dispute", "operationId": "resolveDispute", "x-aura-invariants": [ "INV-014" ], "description": "A reopened transaction has to reach a definite end, or repudiability becomes limbo. Resolution applies an outcome (upheld, rejected, partial, or withdrawn) to a dispute filed inside its [window](/invariants.html#repudiability-within-a-bounded-window) and closes it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeResolution" } } } }, "responses": { "200": { "description": "Dispute resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/disputes/{dispute_id}": { "parameters": [ { "name": "dispute_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Disputes" ], "summary": "Retrieve a dispute", "operationId": "getDispute", "x-aura-invariants": [ "INV-014" ], "description": "A dispute's state and the evidence on both sides have to be visible to its participants to be trusted. This returns the dispute with its protocol evidence, for a transaction still inside its [repudiable window](/invariants.html#repudiability-within-a-bounded-window).", "responses": { "200": { "description": "Dispute", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/sessions/{session_id}/chain-links": { "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "post": { "tags": [ "Intent Chain" ], "summary": "Submit the L3 (principal review) chain link", "operationId": "submitChainLink", "x-aura-signature-profile": "intent_chain_link", "x-aura-invariants": [ "INV-008" ], "description": "Who decided what, and in what order, is the whole of accountability when agents act for principals. A chain link adds one signed step to the intent's [chain of custody](/invariants.html#recorded-intent-and-chain-of-custody), each link bound to its predecessor so the record cannot be reordered or forged after the fact.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainLinkSubmission" } } } }, "responses": { "201": { "description": "Chain link recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "link": { "type": "string" }, "name": { "type": "string" }, "session_id": { "type": "string", "format": "uuid" }, "previous_link_hash": { "type": [ "string", "null" ], "description": "Hash of the prior link; null for the first." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/transactions/{transaction_id}/intent-chain": { "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Intent Chain" ], "summary": "Retrieve the assembled intent chain", "operationId": "getIntentChain", "x-aura-signature-profile": "assembled_intent_chain", "x-aura-invariants": [ "INV-008" ], "description": "After the fact, a dispute or an audit has to replay exactly how an intent became a commitment. This returns the assembled [chain of custody](/invariants.html#recorded-intent-and-chain-of-custody) for a transaction, every link signed by the party responsible for it.", "responses": { "200": { "description": "Intent chain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntentChain" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/sandbox/namespaces": { "post": { "tags": [ "Sandbox" ], "summary": "Provision the namespace a sandbox key anchors", "operationId": "provisionSandbox", "description": "Turns a minted sandbox key into a seeded, isolated market and binds the key to it. A namespace is rows in a standing deployment, never new infrastructure, so provisioning is a single call: the seeded principals at declared verification levels, the deterministic house counterparties, the declared market profile, and both simulated settlement rails arrive together, described by the returned manifest. Provisioning does not open a conformance run; every run opens with a reset. Idempotent by the key: re-provisioning with an already-bound key returns the existing manifest as success, never a conflict, so an agent retrying a timeout lands on the same state.", "servers": [ { "url": "https://sandbox.aura-labs.ai", "description": "Served on the certification bench only; the production host does not register this operation." } ], "security": [ { "sandboxKey": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionSandboxRequest" } } } }, "responses": { "200": { "description": "Idempotent replay: this key is already bound to its namespace. The same manifest, no state change, no quota spend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxManifest" } } } }, "201": { "description": "Provisioned: the namespace exists, the market is seeded, and the key is bound. The manifest states every fact the namespace guarantees.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxManifest" } } } }, "400": { "description": "validation_error: the request body failed contract validation (an unknown field, or a malformed scenario_version). The details name the offending fields.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "sandbox_key_invalid: X-AURA-Sandbox-Key is absent, unknown, or revoked. Mint a key first; after a re-mint, only the newest grant is live.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "sandbox_namespace_conflict: a concurrent provision or reset holds this key's namespace. Retry; a repeated provision is idempotent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "422": { "description": "sandbox_contract_version_skew: the requested scenario version is not the version this bench serves. The message names the served version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "429": { "description": "sandbox_quota_exceeded: a quota for the verified identity is exhausted. The body names the quota and the tier it was judged at.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "quota": { "type": "string", "description": "The exhausted quota, named as in the quotas block." }, "tier": { "type": "string", "description": "The tier the refusal was judged at." } } } } } }, "503": { "description": "sandbox_provisioning_unavailable: provisioning could not complete and rolled back, nothing was created, safe to retry. Or database_unavailable: the bench database is not reachable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/v1/sandbox/namespaces/current/reset": { "post": { "tags": [ "Sandbox" ], "summary": "Reset the namespace: open a new conformance run", "operationId": "resetSandbox", "description": "Destroy-and-reseed at namespace grain. Every conformance run opens with a reset and receives the run identity that transcripts, assertion results, and run quotas key on. The house counterparties reseed with the same derived keys (the declared sandbox semantic exception), so the manifest stays valid across resets. Not idempotent, by design: each success is a new run boundary and spends run quota; the retryable conflicts are safe to retry because the tenant is serialized on the key. A reset never runs under an in-flight flow: let open sessions reach a quiescent state or expire first. Evidence recorded outside the namespace survives reset.", "servers": [ { "url": "https://sandbox.aura-labs.ai", "description": "Served on the certification bench only; the production host does not register this operation." } ], "security": [ { "sandboxKey": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetSandboxRequest" } } } }, "responses": { "200": { "description": "The run boundary: the namespace is reseeded and the new run is open.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxResetResult" } } } }, "400": { "description": "validation_error: the request body failed contract validation. The details name the offending fields.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "sandbox_key_invalid: X-AURA-Sandbox-Key is absent, unknown, revoked, or not yet bound to a namespace (provision first).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "sandbox_run_active: a flow is in flight in this namespace, or a concurrent reset opened a run first. Or sandbox_namespace_conflict: a concurrent provision or reset holds the tenant. Both are safe to retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "429": { "description": "sandbox_quota_exceeded: the run quota for this key is exhausted. The body names the quota and the tier it was judged at.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "quota": { "type": "string", "description": "The exhausted quota, named as in the quotas block." }, "tier": { "type": "string", "description": "The tier the refusal was judged at." } } } } } }, "503": { "description": "sandbox_provisioning_unavailable: the reset could not complete and rolled back, the namespace is unchanged, safe to retry. Or database_unavailable: the bench database is not reachable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/v1/sandbox/namespaces/current/runs/{run_id}/transcript": { "get": { "tags": [ "Sandbox" ], "summary": "Read the transcript of a conformance run", "operationId": "getSandboxRunTranscript", "description": "Assemble the run's transcript from its recorded events: the raw events exactly as they happened, the normalized events derived through the retained first-occurrence substitution map (UUIDs and timestamps only), the map itself, and the hash-chain head over the raw events. A read with no side effects, available while the run is active and after a later reset supersedes it. The run must belong to the namespace the presented key anchors; an unknown, malformed, or foreign run_id is the same not-found answer, so run existence never leaks across namespaces.", "servers": [ { "url": "https://sandbox.aura-labs.ai", "description": "Served on the certification bench only; the production host does not register this operation." } ], "security": [ { "sandboxKey": [] } ], "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The run boundary: provision opens a run and returns its run_id; each reset opens a fresh one." } ], "responses": { "200": { "description": "The assembled transcript: raw and normalized layers, the substitution map, and the hash-chain head.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConformanceTranscript" } } } }, "401": { "description": "sandbox_key_invalid: no key presented, or the presented key is unknown or revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "sandbox_run_not_found: no such run in this namespace. Covers the unknown, the malformed, and the foreign run_id alike.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "database_unavailable: the transcript read failed. Nothing changed; safe to retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "components": { "securitySchemes": { "agentId": { "type": "apiKey", "in": "header", "name": "X-Agent-Id", "description": "The agent's UUID. Sent together with X-Agent-Timestamp and X-Agent-Signature; the three authenticate a request (see x-aura-signature-profiles.authenticated_request)." }, "agentTimestamp": { "type": "apiKey", "in": "header", "name": "X-Agent-Timestamp", "description": "RFC 3339 timestamp. Sent together with X-Agent-Id and X-Agent-Signature." }, "agentSignature": { "type": "apiKey", "in": "header", "name": "X-Agent-Signature", "description": "Ed25519 signature over the canonical request (method, path, timestamp, body hash). Sent together with X-Agent-Id and X-Agent-Timestamp; all three are required." }, "agentProof": { "type": "apiKey", "in": "header", "name": "X-Agent-Signature", "description": "Proof-of-possession for agent registration: Ed25519 signature over the request body, proving control of the submitted public key." }, "principalProof": { "type": "apiKey", "in": "header", "name": "X-Signature", "description": "Proof-of-possession for principal registration: Ed25519 signature over the request body." }, "systemToken": { "type": "apiKey", "in": "header", "name": "X-System-Token", "description": "System-only shared secret for internal lifecycle endpoints. Not issued to client integrations." }, "sandboxKey": { "type": "apiKey", "in": "header", "name": "X-AURA-Sandbox-Key", "description": "The sandbox tenant anchor, minted by mintSandboxKey. Bearer presentation is deliberate: the key is a capability handle for one quota-bounded namespace, never a protocol identity; issuance is proof-anchored (a signed mint request plus domain publication), theft's blast radius is one namespace, and the remedy is re-mint under the re-proven domain. Protocol identity stays proof-of-possession on every flow call. Registration and namespaced operations on the sandbox host will require this header alongside the existing proof schemes once provisioning ships." }, "sandboxMintProof": { "type": "apiKey", "in": "header", "name": "X-Signature", "description": "Proof-of-possession for sandbox key minting: the Ed25519 signature (base64) over JSON.stringify of the mint request body by the declared public_key, per the sandbox_key_mint signature profile and its test vector. This is the ONLY auth mintSandboxKey requires: obtain_scope mints a key for a domain-verified keypair that has no protocol identity yet, so the registered-agent auth headers do not apply." } }, "parameters": { "ProfileId": { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^(prf_[a-z0-9_]+_v[0-9]+|default)$" }, "examples": { "retail": { "value": "prf_retail_consumer_v1" }, "default": { "value": "default" } } }, "SessionId": { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } }, "responses": { "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid agent authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Authenticated but not authorized for this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "example": { "error": "validation_error", "message": "Request body failed contract validation" }, "type": "object", "properties": { "error": { "type": "string", "description": "Machine-readable error code" }, "message": { "type": "string", "description": "Human-readable explanation" } }, "required": [ "error" ] }, "Link": { "type": "object", "example": { "href": "/v1/sessions/5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "method": "GET" }, "properties": { "href": { "type": "string" }, "method": { "type": "string" } } }, "Links": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Link" }, "example": { "self": { "href": "/v1/sessions/5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "method": "GET" }, "offers": { "href": "/v1/sessions/5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b/offers", "method": "GET" } }, "description": "HATEOAS affordances keyed by relation." }, "PriceRange": { "example": { "min": 1200, "max": 1800, "currency": "USD" }, "type": "object", "description": "Reusable price range component.", "required": [ "min", "max" ], "properties": { "min": { "type": "number", "minimum": 0 }, "max": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "description": "ISO 4217", "default": "USD" } } }, "Profile": { "example": { "profile_id": "prf_b2b_procurement_v1", "profile_version": "1", "display_name": "B2B Procurement", "description": "Bounded parameters for business-to-business procurement markets.", "market_context": "b2b_procurement", "status": "active", "dispute_window_days_minimum": 14, "dispute_window_days_default": 30, "_links": { "self": { "href": "/v1/profiles/prf_b2b_procurement_v1", "method": "GET" } } }, "type": "object", "description": "Market profile governing dispute windows and settlement defaults.", "properties": { "profile_id": { "type": "string" }, "profile_version": { "type": "string", "description": "Version of this profile; pinned onto a session at creation as profile_version_at_creation." }, "display_name": { "type": "string", "description": "Human-readable profile label." }, "description": { "type": "string", "description": "Free-text summary of the market this profile governs." }, "market_context": { "type": "string", "description": "The vertical or market context the profile applies to." }, "status": { "type": "string", "description": "Profile lifecycle status; only active profiles are resolvable." }, "dispute_window_days_minimum": { "type": "integer" }, "dispute_window_days_default": { "type": "integer" }, "participation": { "type": "object", "description": "Participation dimension: who may enter this market and under what conditions." }, "disclosure": { "type": "object", "description": "Disclosure dimension: what parties must reveal to each other." }, "commitment": { "type": "object", "description": "Commitment dimension: binding rules governing offers and commits." }, "risk": { "type": "object", "description": "Risk dimension: risk-tiering and reserve parameters for this market." }, "schema": { "type": "object", "description": "Schema overlays extending the base offer/intent shape for this market." }, "governance": { "type": "object", "description": "Governance dimension: who may amend the profile and how." }, "metadata": { "type": "object", "description": "Free-form profile metadata." }, "_links": { "$ref": "#/components/schemas/Links" } } }, "ProfileValidationRequest": { "example": { "dispute_window_days": 30, "settlement_method": "sepa-instant" }, "type": "object", "description": "Terms to pre-flight against a market profile's minimums.", "required": [ "dispute_window_days" ], "properties": { "dispute_window_days": { "type": "integer", "minimum": 0 }, "settlement_method": { "type": "string", "maxLength": 32 } } }, "SettlementRail": { "example": { "adapter_id": "sepa-instant", "native_repudiation": false, "capabilities": { "settlement_time": "instant", "currencies": [ "EUR" ] }, "_links": { "self": { "href": "/v1/settlement-rails/sepa-instant", "method": "GET" } } }, "type": "object", "description": "Settlement-rail adapter and its capabilities.", "properties": { "adapter_id": { "type": "string" }, "native_repudiation": { "type": "boolean", "description": "Whether the rail provides native chargeback/repudiation." }, "capabilities": { "type": "object" }, "_links": { "$ref": "#/components/schemas/Links" } } }, "PrincipalRegistration": { "example": { "principal_type": "organization", "legal_name": "Helix Retail Group", "jurisdiction": "GB", "public_key": "MCowBQYDK2VwAyEAGb9ECWmEzf6FQbrBZ9w7lshQhqowtrbLDFw4rXAxZuE=", "operating_name": "Helix Retail", "identifiers": { "lei": "894500ABCDEF12345678", "domain": "helix-retail.example" }, "contact": { "email": "integrations@helix-retail.example" } }, "type": "object", "required": [ "principal_type", "legal_name", "jurisdiction", "public_key" ], "properties": { "principal_type": { "type": "string", "enum": [ "organization", "individual" ] }, "legal_name": { "type": "string" }, "jurisdiction": { "type": "string", "description": "ISO 3166 country code" }, "public_key": { "type": "string", "description": "Base64 Ed25519 public key" }, "operating_name": { "type": "string" }, "identifiers": { "type": "object", "properties": { "lei": { "type": "string" }, "domain": { "type": "string" } } }, "contact": { "type": "object" } } }, "Principal": { "example": { "principal_id": "3f2a9c7e-1b4d-4e8a-9c2f-7a1b0d3e5f60", "principal_type": "organization", "verification_level": "basic", "verification_status": "verified", "registered_at": "2026-06-20T09:15:00Z", "_links": { "self": { "href": "/v1/principals/3f2a9c7e-1b4d-4e8a-9c2f-7a1b0d3e5f60", "method": "GET" } } }, "type": "object", "properties": { "principal_id": { "type": "string", "format": "uuid" }, "principal_type": { "type": "string", "enum": [ "organization", "individual" ] }, "verification_level": { "type": "string" }, "verification_status": { "type": "string" }, "registered_at": { "type": "string", "format": "date-time" }, "_links": { "$ref": "#/components/schemas/Links" } } }, "AgentRegistration": { "example": { "public_key": "MCowBQYDK2VwAyEAGb9ECWmEzf6FQbrBZ9w7lshQhqowtrbLDFw4rXAxZuE=", "type": "scout", "principal_id": "3f2a9c7e-1b4d-4e8a-9c2f-7a1b0d3e5f60", "capacity": "standard", "manifest": { "name": "Helix Procurement Scout", "version": "1.2.0" } }, "type": "object", "required": [ "public_key", "type", "principal_id" ], "properties": { "public_key": { "type": "string", "description": "Base64 Ed25519 public key" }, "type": { "type": "string", "enum": [ "scout", "beacon" ] }, "principal_id": { "type": "string", "format": "uuid" }, "capacity": { "type": "string", "default": "agent_for_principal" }, "manifest": { "type": "object" } } }, "Agent": { "example": { "agent_id": "8b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "status": "active", "key_id": "key_9f3a2c", "principal_id": "3f2a9c7e-1b4d-4e8a-9c2f-7a1b0d3e5f60", "capacity": "standard", "registered_at": "2026-06-21T10:00:00Z", "_links": { "self": { "href": "/v1/agents/8b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "method": "GET" } } }, "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "key_id": { "type": "string" }, "manifest": { "type": "object", "description": "The agent's self-declared capability manifest submitted at registration." }, "principal_id": { "type": "string", "format": "uuid" }, "capacity": { "type": "string" }, "principal_verification_level": { "type": [ "string", "null" ], "description": "Verification level of the bound principal, resolved at read time; null when the agent has no principal." }, "registered_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the agent's most recent authenticated request; null until first seen." }, "_links": { "$ref": "#/components/schemas/Links" } } }, "PrincipalUpdate": { "example": { "operating_name": "Helix Retail Group (EMEA)", "contact": { "email": "ops@helix-retail.example" }, "identifiers": { "domain": "helix-retail.example" } }, "type": "object", "description": "Mutable principal fields. Immutable fields (legal_name, jurisdiction, principal_type, public_key, verification_level) are rejected with 400.", "properties": { "operating_name": { "type": "string" }, "contact": { "type": "object" }, "identifiers": { "type": "object", "properties": { "lei": { "type": "string" }, "domain": { "type": "string" } } } } }, "DelegationConstraints": { "example": { "max_transaction_amount": 50000, "currency": "USD", "valid_from": "2026-06-01T00:00:00Z", "valid_until": "2026-12-31T23:59:59Z", "allowed_categories": [ "industrial_supplies" ], "blocked_categories": [ "weapons" ], "merchant_blocklist": [], "require_principal_approval_above": 25000 }, "type": "object", "description": "Bounds on what the agent may transact under this scope.", "properties": { "max_transaction_amount": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "description": "ISO 4217" }, "valid_from": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "allowed_categories": { "type": "array", "items": { "type": "string" } }, "blocked_categories": { "type": "array", "items": { "type": "string" } }, "merchant_blocklist": { "type": "array", "items": { "type": "string" } }, "require_principal_approval_above": { "type": "number" } } }, "DelegationScopeRequest": { "example": { "consent_tier": "policy", "constraints": { "max_transaction_amount": 50000, "currency": "USD", "valid_from": "2026-06-01T00:00:00Z", "valid_until": "2026-12-31T23:59:59Z", "allowed_categories": [ "industrial_supplies" ], "blocked_categories": [ "weapons" ], "merchant_blocklist": [], "require_principal_approval_above": 25000 }, "policy_definition": { "max_per_day": 5 }, "signed_by_principal": true, "principal_signature": "k9Jx2pQ7r4sV1mNc8eTfWZ0aYbHd3GgLpRtUvXyB6CnEoJqSiKlMwOzPu5D4hAtFr7vXsQ2bNcMeKgLpRtUvXyB" }, "type": "object", "required": [ "consent_tier", "constraints" ], "properties": { "consent_tier": { "type": "string", "enum": [ "explicit", "policy", "delegated" ] }, "constraints": { "$ref": "#/components/schemas/DelegationConstraints" }, "policy_definition": { "type": "object" }, "signed_by_principal": { "type": "boolean", "default": false }, "principal_signature": { "type": "string" } } }, "DelegationScope": { "example": { "scope_id": "scope_7f3a9c2e", "agent_id": "8b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "consent_tier": "policy", "constraints": { "max_transaction_amount": 50000, "currency": "USD", "valid_from": "2026-06-01T00:00:00Z", "valid_until": "2026-12-31T23:59:59Z", "allowed_categories": [ "industrial_supplies" ], "blocked_categories": [ "weapons" ], "merchant_blocklist": [], "require_principal_approval_above": 25000 }, "policy_definition": { "max_per_day": 5 }, "signed_by_principal": true, "status": "active", "created_at": "2026-06-21T10:05:00Z" }, "type": "object", "properties": { "scope_id": { "type": "string" }, "agent_id": { "type": "string", "format": "uuid" }, "consent_tier": { "type": "string", "enum": [ "explicit", "policy", "delegated" ] }, "constraints": { "$ref": "#/components/schemas/DelegationConstraints" }, "policy_definition": { "type": [ "object", "null" ] }, "signed_by_principal": { "type": "boolean" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BeaconRegistration": { "example": { "external_id": "northwind-components", "name": "Northwind Components", "description": "Industrial parts and components supplier", "endpoint_url": "https://beacons.northwind-components.example/aura/webhook", "capabilities": { "categories": [ "industrial_supplies" ], "currencies": [ "USD" ] }, "metadata": { "region": "NA" } }, "type": "object", "required": [ "external_id", "name" ], "properties": { "external_id": { "type": "string", "description": "Stable external identifier; the upsert key." }, "name": { "type": "string" }, "description": { "type": "string" }, "endpoint_url": { "type": "string", "format": "uri", "description": "HTTPS, public hostname; SSRF-validated: raw IP literals and private hostnames are rejected, and the hostname must not resolve to a private, link-local, loopback, or reserved address. Resolution is checked at registration and enforced again at delivery, where the connection is pinned to the checked DNS answer; redirects are not followed." }, "capabilities": { "type": "object" }, "metadata": { "type": "object" } } }, "Beacon": { "example": { "beacon_id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "external_id": "northwind-components", "name": "Northwind Components", "status": "active", "capabilities": { "categories": [ "industrial_supplies" ] }, "_links": { "self": { "href": "/v1/beacons/c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "method": "GET" } } }, "type": "object", "properties": { "beacon_id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "capabilities": { "type": "object" }, "_links": { "$ref": "#/components/schemas/Links" } } }, "SessionSummary": { "example": { "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "status": "offers_available", "intent": { "raw": "I need 200 industrial widgets delivered within three weeks" }, "constraints": { "quantity": 200, "deliver_by": "2026-07-18" } }, "type": "object", "description": "Open session as seen by a beacon. Buyer constraints are redacted to categories only.", "properties": { "session_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "intent": { "type": "object", "properties": { "raw": { "type": "string" }, "parsed": { "type": "object" } } }, "constraints": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "string" } } }, "description": "Redacted to categories only." } } }, "SessionCreate": { "example": { "intent": "I need 200 industrial widgets delivered within three weeks", "constraints": { "quantity": 200, "max_unit_price": 9, "currency": "USD" }, "completeness": { "confidence": 0.9 }, "profile_id": "prf_b2b_procurement_v1", "settlement_preference": { "preferred_methods": [ "sepa-instant", "usdc-base" ] }, "risk_tolerance": { "max_dispute_window_days": 30 } }, "type": "object", "required": [ "intent" ], "properties": { "intent": { "type": "string", "maxLength": 2000, "description": "Natural-language buying intent." }, "constraints": { "type": "object", "description": "Structured constraints (max 10KB).", "properties": { "price_range": { "$ref": "#/components/schemas/PriceRange" } } }, "completeness": { "type": "object", "properties": { "complete": { "type": "boolean" }, "missing": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": "number" } } }, "chain_links": { "type": "object", "description": "Optional L1 intent-chain link." }, "profile_id": { "type": "string", "default": "default" }, "settlement_preference": { "type": "object" }, "risk_tolerance": { "type": "object" } } }, "Session": { "example": { "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "status": "offers_available", "intent": { "raw": "I need 200 industrial widgets delivered within three weeks", "structured": { "quantity": 200, "item": "industrial widget" } }, "profile_id": "prf_b2b_procurement_v1", "profile_version_at_creation": "2.4", "matched_beacons": [ { "beacon_id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "name": "Northwind Components" } ], "_links": { "self": { "href": "/v1/sessions/5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "method": "GET" }, "offers": { "href": "/v1/sessions/5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b/offers", "method": "GET" } } }, "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "examples": [ "collecting_offers" ] }, "intent": { "type": [ "object", "null" ], "description": "Parsed intent." }, "raw_intent": { "type": [ "string", "null" ], "description": "The original unparsed intent string as submitted, returned on session retrieval." }, "profile_id": { "type": "string" }, "profile_version_at_creation": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp the session was created." }, "matched_beacons": { "type": "array", "items": { "type": "object" } }, "_links": { "$ref": "#/components/schemas/Links" } } }, "Product": { "example": { "name": "Industrial Widget Mk II", "sku": "NW-WIDGET-002" }, "type": "object", "description": "Product descriptor (free-form JSONB). 'name' is the canonical label; 'sku' optional. Additional vendor fields are permitted.", "properties": { "name": { "type": "string" }, "sku": { "type": "string" } } }, "OfferSubmission": { "example": { "beacon_id": "northwind-components", "product": { "name": "Industrial Widget Mk II", "sku": "NW-WIDGET-002" }, "unit_price": 8.5, "quantity": 200, "total_price": 1700, "currency": "USD", "delivery_date": "2026-07-15", "expires_at": "2026-03-01T12:00:00Z", "terms": { "warranty_months": 12 }, "signature": "k9Jx2pQ7r4sV1mNc8eTfWZ0aYbHd3GgLpRtUvXyB6CnEoJqSiKlMwOzPu5D4hAtFr7vXsQ2bNcMeKgLpRtUvXyB", "payment_terms": { "dispute_window_days": 30, "return_policy_days": 14, "payment_timing": "net_30", "accepted_methods": [ "sepa-instant", "usdc-base" ] }, "payment_terms_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "acting_for_principal_id": "3f2a9c7e-1b4d-4e8a-9c2f-7a1b0d3e5f60", "consent_requirements": { "principal_signature": false } }, "type": "object", "required": [ "beacon_id", "product", "signature" ], "properties": { "beacon_id": { "type": "string" }, "product": { "description": "Product descriptor object, or a bare string treated as { name }.", "oneOf": [ { "$ref": "#/components/schemas/Product" }, { "type": "string" } ] }, "unit_price": { "type": "number" }, "quantity": { "type": "integer" }, "total_price": { "type": "number" }, "currency": { "type": "string", "default": "USD" }, "delivery_date": { "type": "string", "format": "date" }, "expires_at": { "type": "string", "format": "date-time", "description": "Optional declared expiry for the offer (ISO 8601). Must fall inside the session profile's offer validity window (the offer_validity_window bounded parameter of the offer-expiry invariant): at least 30 seconds and at most 24 hours from Core receipt unless the profile narrows or widens those bounds. Omitted, the profile default applies (one hour unless the profile says otherwise). The declared expiry rides in the authenticated submission and is recorded and enforced by Core; the canonical offer signing payload is unchanged." }, "terms": { "type": "object" }, "signature": { "type": "string", "description": "Beacon Ed25519 signature over the canonical offer." }, "payment_terms": { "$ref": "#/components/schemas/PaymentTerms" }, "payment_terms_hash": { "type": "string", "description": "Base64 SHA-256 over canonical payment_terms (v2.4 attested path)." }, "acting_for_principal_id": { "type": "string", "format": "uuid" }, "consent_requirements": { "type": "object", "properties": { "minimum_tier": { "type": "string" }, "reason": { "type": "string" }, "above_amount": { "type": "number" } } } } }, "PaymentTerms": { "example": { "dispute_window_days": 30, "return_policy_days": 14, "payment_timing": "net_30", "accepted_methods": [ "sepa-instant", "usdc-base" ] }, "type": "object", "description": "Offer payment terms (v2.4).", "properties": { "dispute_window_days": { "type": "integer" }, "return_policy_days": { "type": "integer" }, "payment_timing": { "type": "string" }, "accepted_methods": { "type": "array", "items": { "type": "string" } } } }, "Offer": { "example": { "offer_id": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d", "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "beacon_id": "northwind-components", "status": "pending", "product": { "name": "Industrial Widget Mk II", "sku": "NW-WIDGET-002" }, "payment_terms": { "dispute_window_days": 30, "return_policy_days": 14, "payment_timing": "net_30", "accepted_methods": [ "sepa-instant", "usdc-base" ] }, "payment_terms_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "signatures": { "beacon": "k9Jx2pQ7r4sV1mNc8eTfWZ0aYbHd3GgLpRtUvXyB6CnEoJqSiKlMwOzPu5D4hAtFr7vXsQ2bNcMeKgLpRtUvXyB", "core": "k9Jx2pQ7r4sV1mNc8eTfWZ0aYbHd3GgLpRtUvXyB6CnEoJqSiKlMwOzPu5D4hAtFr7vXsQ2bNcMeKgLpRtUvXyB" }, "_links": { "self": { "href": "/v1/offers/9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d", "method": "GET" } }, "expires_at": "2026-03-01T12:00:00Z" }, "type": "object", "properties": { "offer_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "beacon_id": { "type": "string" }, "beacon_name": { "type": "string", "description": "Display name of the beacon that submitted this offer, joined at read time." }, "status": { "type": "string" }, "product": { "$ref": "#/components/schemas/Product" }, "unit_price": { "type": "number", "description": "Per-unit price of the offered product." }, "quantity": { "type": "integer", "description": "Number of units offered." }, "total_price": { "type": "number", "description": "Total price for the offered quantity." }, "currency": { "type": "string", "description": "ISO 4217 currency of the offer prices." }, "delivery_date": { "type": "string", "format": "date", "description": "Committed delivery date for the offered goods." }, "terms": { "type": "object", "description": "Free-form commercial terms attached to the offer." }, "metadata": { "type": "object", "description": "Free-form offer metadata." }, "consent_requirements": { "type": "object", "description": "Principal-consent requirements the offer attaches to the commit, when present." }, "payment_terms": { "$ref": "#/components/schemas/PaymentTerms" }, "payment_terms_hash": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp the offer was submitted." }, "expires_at": { "type": "string", "format": "date-time", "description": "When the offer stops being committable and counterable. Every offer carries one: declared by the Beacon within the profile validity window, or resolved to the profile default. A commit or counter on an expired offer is refused with offer_expired." }, "signatures": { "type": "object", "properties": { "beacon": { "type": "string" }, "core": { "type": "string" }, "core_receipt_at": { "type": "string", "format": "date-time" } } }, "_links": { "$ref": "#/components/schemas/Links" } } }, "CommitRequest": { "example": { "offer_id": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d", "idempotency_key": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f70", "authority": { "consent_tier": "policy", "scope_id": "scope_7f3a9c2e" }, "chain_links": { "L5": { "signature": "k9Jx2pQ7r4sV1mNc8eTfWZ0aYbHd3GgLpRtUvXyB6CnEoJqSiKlMwOzPu5D4hAtFr7vXsQ2bNcMeKgLpRtUvXyB" } }, "settlement_method": "sepa-instant" }, "type": "object", "required": [ "offer_id", "idempotency_key" ], "properties": { "offer_id": { "type": "string", "format": "uuid" }, "idempotency_key": { "type": "string", "format": "uuid", "description": "UUID v4 for idempotent commit." }, "authority": { "type": "object", "properties": { "delegation_scope_id": { "type": "string" }, "consent_tier": { "type": "string" }, "principal_approval": { "type": "object" } } }, "chain_links": { "type": "object", "description": "L4/L5 intent-chain links." }, "settlement_method": { "type": "string" } } }, "Transaction": { "example": { "transaction_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "offer_id": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d", "beacon_id": "northwind-components", "status": "committed", "final_terms": { "product": { "name": "Industrial Widget Mk II", "sku": "NW-WIDGET-002" }, "unit_price": 8.5, "quantity": 200, "total_price": 1700, "currency": "USD" }, "clearinghouse": { "clearing_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "clearing_status": "risk_assessed", "risk_tier": "low", "reserve_status": "rail_managed", "net_settlement_amount": 1700, "currency": "USD" }, "_links": { "self": { "href": "/v1/transactions/2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "method": "GET" } } }, "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "offer_id": { "type": "string", "format": "uuid" }, "beacon_id": { "type": "string" }, "beacon_name": { "type": "string", "description": "Display name of the beacon party to the transaction." }, "agent_id": { "type": "string", "format": "uuid", "description": "Identity of the scout agent that owns the originating session." }, "status": { "type": "string" }, "final_terms": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/Product" }, "total_price": { "type": "number" }, "currency": { "type": "string" }, "delivery_date": { "type": "string", "format": "date" } } }, "scout_principal": { "type": [ "object", "null" ], "description": "The scout side's principal reference, resolved at commit time; null when unbound.", "properties": { "principal_id": { "type": "string", "format": "uuid" } } }, "beacon_principal": { "type": [ "object", "null" ], "description": "The beacon side's principal reference, resolved at commit time; null when unbound.", "properties": { "principal_id": { "type": "string", "format": "uuid" } } }, "fulfillment_status": { "type": "string", "description": "Current fulfillment state reported by the beacon." }, "fulfillment_reference": { "type": "string", "description": "Beacon-supplied reference for the fulfillment (e.g. tracking or order id)." }, "payment_status": { "type": "string", "description": "Current payment state of the transaction." }, "payment_reference": { "type": "string", "description": "Reference for the payment (e.g. settlement or rail transaction id)." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp the transaction was committed." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the transaction's most recent state change." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the transaction reached a terminal completed state; null until then." }, "clearinghouse": { "type": "object", "description": "Present when the rail is AURA-cleared." }, "_links": { "$ref": "#/components/schemas/Links" } } }, "Attestation": { "example": { "type": "interpretation", "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "attestation_signature": "k9Jx2pQ7r4sV1mNc8eTfWZ0aYbHd3GgLpRtUvXyB6CnEoJqSiKlMwOzPu5D4hAtFr7vXsQ2bNcMeKgLpRtUvXyB", "core_key_id": "core_key_2026q2" }, "type": "object", "description": "Core's signed interpretation attestation: a binding between the raw intent and its structured interpretation.", "properties": { "type": { "type": "string", "examples": [ "interpretation_attestation" ] }, "session_id": { "type": "string", "format": "uuid" }, "attestation_signature": { "type": "string", "description": "Base64 Ed25519 over the canonical attestation." }, "core_key_id": { "type": "string" } } }, "CounterOfferRequest": { "example": { "payment_terms": { "dispute_window_days": 45, "return_policy_days": 30, "payment_timing": "net_45", "accepted_methods": [ "sepa-instant" ] }, "unit_price": 8, "quantity": 200, "product": { "name": "Industrial Widget Mk II", "sku": "NW-WIDGET-002" }, "total_price": 1600, "currency": "USD" }, "type": "object", "required": [ "payment_terms" ], "properties": { "payment_terms": { "$ref": "#/components/schemas/PaymentTerms" }, "unit_price": { "type": "number" }, "quantity": { "type": "integer" }, "product": { "description": "Product descriptor object, or a bare string treated as { name }. Inherits the parent offer's product when omitted.", "oneOf": [ { "$ref": "#/components/schemas/Product" }, { "type": "string" } ] }, "total_price": { "type": "number" }, "currency": { "type": "string" } } }, "NegotiatedOffer": { "example": { "offer_id": "6f7a8b9c-0d1e-4f2a-8b3c-4d5e6f7a8b9c", "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "beacon_id": "northwind-components", "parent_offer_id": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d", "negotiation_status": "countered", "depth": 1, "payment_terms": { "dispute_window_days": 30, "return_policy_days": 14, "payment_timing": "net_30", "accepted_methods": [ "sepa-instant", "usdc-base" ] }, "payment_terms_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "_links": { "self": { "href": "/v1/offers/6f7a8b9c-0d1e-4f2a-8b3c-4d5e6f7a8b9c", "method": "GET" } } }, "type": "object", "description": "An offer created by countering a parent offer.", "properties": { "offer_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "beacon_id": { "type": "string" }, "parent_offer_id": { "type": "string", "format": "uuid" }, "negotiation_status": { "type": "string", "examples": [ "countered" ] }, "depth": { "type": "integer" }, "payment_terms": { "$ref": "#/components/schemas/PaymentTerms" }, "payment_terms_hash": { "type": "string" }, "_links": { "$ref": "#/components/schemas/Links" } } }, "FulfillmentUpdate": { "example": { "fulfillment_status": "shipped", "fulfillment_reference": "NW-SHIP-44821" }, "type": "object", "required": [ "fulfillment_status" ], "properties": { "fulfillment_status": { "type": "string", "enum": [ "pending", "processing", "shipped", "delivered", "failed" ] }, "fulfillment_reference": { "type": "string" } } }, "PaymentUpdate": { "example": { "payment_status": "charged", "payment_reference": "sepa-7f3a9c", "amount": 1700, "currency": "USD" }, "type": "object", "required": [ "payment_status" ], "properties": { "payment_status": { "type": "string", "enum": [ "pending", "authorized", "charged", "refunded", "failed" ] }, "payment_reference": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" } } }, "ClearingRecord": { "example": { "clearing_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "transaction_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "clearing_status": "settled", "_links": { "self": { "href": "/v1/transactions/2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f/clearing", "method": "GET" } } }, "type": "object", "description": "Clearing lifecycle record. Risk scores are filtered to the requesting party.", "properties": { "clearing_id": { "type": "string", "format": "uuid" }, "transaction_id": { "type": "string", "format": "uuid" }, "clearing_status": { "type": "string" }, "reserve_status": { "type": "string", "description": "State of the settlement reserve (e.g. rail_managed, held, released)." }, "risk_tier": { "type": "string", "description": "Overall risk tier assigned to the transaction." }, "risk_score": { "type": [ "number", "null" ], "description": "Aggregate transaction risk score." }, "scout_risk_score": { "type": [ "number", "null" ], "description": "Per-party risk score for the scout side. Returned only to the scout party; null to the counterparty." }, "beacon_risk_score": { "type": [ "number", "null" ], "description": "Per-party risk score for the beacon side. Returned only to the beacon party; null to the counterparty." }, "payment_method": { "type": "string", "description": "Settlement rail / payment method used to clear the transaction." }, "reserve_margin_pct": { "type": [ "number", "null" ], "description": "Reserve margin held, as a percentage of the settlement amount (wire key for the risk_margin_pct column)." }, "reserve_margin_amount": { "type": [ "number", "null" ], "description": "Reserve margin held, as an absolute amount (wire key for the risk_margin_amount column)." }, "net_settlement_amount": { "type": [ "number", "null" ], "description": "Amount to be settled net of any reserve margin." }, "currency": { "type": "string", "description": "ISO 4217 currency of the settlement amounts." }, "dispute_term_days": { "type": "integer", "description": "Length of the dispute window in days for this clearing record." }, "dispute_term_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the dispute window closes." }, "authorized_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the reserve/settlement was authorized." }, "settled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the transaction settled." }, "cleared_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the reserve released and the record cleared." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp the clearing record was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the clearing record's most recent state change." }, "_links": { "$ref": "#/components/schemas/Links" } } }, "BusinessRuleCreate": { "example": { "rule_type": "geo_restriction", "payload": { "allowed_countries": [ "US", "CA", "GB" ] } }, "type": "object", "required": [ "rule_type" ], "properties": { "rule_type": { "type": "string", "enum": [ "age_minimum", "geo_restriction", "kyc_required", "custom" ] }, "payload": { "type": "object", "description": "Rule-type-specific (age_minimum: { min_age }; geo_restriction: { allow: [ISO-3166] }; kyc_required: { level })." } } }, "BusinessRule": { "example": { "id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e", "beacon_id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "rule_type": "geo_restriction", "payload": { "allowed_countries": [ "US", "CA", "GB" ] }, "created_at": "2026-06-22T08:00:00Z" }, "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "beacon_id": { "type": "string", "format": "uuid" }, "rule_type": { "type": "string" }, "payload": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "DisputeFile": { "example": { "reason": "product_not_as_described", "category": "product_quality", "description": "The delivered widgets do not match the Mk II specification; bracket dimensions differ from the agreed drawing.", "evidence": [ { "type": "text", "description": "Photographs of the received units against the spec sheet" } ], "requested_resolution": { "action": "partial_refund", "refund_amount": 400 } }, "type": "object", "required": [ "reason", "category", "description" ], "properties": { "reason": { "type": "string", "enum": [ "product_not_as_described", "product_not_received", "product_damaged", "wrong_quantity", "unauthorized_transaction", "exceeded_delegation_scope", "payment_not_received", "payment_amount_incorrect", "duplicate_charge", "offer_terms_changed", "other" ] }, "category": { "type": "string", "enum": [ "fulfillment", "payment", "product_quality", "authorization", "other" ] }, "description": { "type": "string", "maxLength": 2000 }, "evidence": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/EvidenceSubmission" } }, "requested_resolution": { "type": "object" } } }, "Dispute": { "example": { "dispute_id": "7f8e9d0c-1b2a-4c3d-8e4f-5a6b7c8d9e0f", "transaction_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "status": "open", "filed_by": "8b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "filed_at": "2026-07-20T11:00:00Z", "reason": "product_not_as_described", "category": "product_quality", "evidence_deadline": "2026-07-27T11:00:00Z", "resolution_deadline": "2026-08-03T11:00:00Z", "_links": { "self": { "href": "/v1/disputes/7f8e9d0c-1b2a-4c3d-8e4f-5a6b7c8d9e0f", "method": "GET" } } }, "type": "object", "properties": { "dispute_id": { "type": "string", "format": "uuid" }, "transaction_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "filed_by": { "type": "string", "format": "uuid" }, "filed_at": { "type": "string", "format": "date-time" }, "reason": { "type": "string" }, "category": { "type": "string" }, "evidence_deadline": { "type": "string", "format": "date-time" }, "resolution_deadline": { "type": "string", "format": "date-time" }, "outcome": { "type": "string" }, "resolution": { "type": [ "object", "null" ] }, "_links": { "$ref": "#/components/schemas/Links" } } }, "EvidenceSubmission": { "example": { "type": "document_reference", "description": "Signed delivery note showing the quantity and spec discrepancy", "document_url": "https://evidence.helix-retail.example/delivery-note-7f8e.pdf", "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" }, "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "document_reference", "external_record", "protocol_record" ] }, "description": { "type": "string", "maxLength": 5000, "description": "Required for type=text." }, "document_url": { "type": "string", "format": "uri", "description": "Required (with content_hash) for type=document_reference." }, "content_hash": { "type": "string" }, "external_system": { "type": "string", "description": "Required (with external_reference) for type=external_record." }, "external_reference": { "type": "string", "description": "Required (with external_system) for type=external_record." }, "protocol_record_type": { "type": "string", "description": "Required (with protocol_record_id) for type=protocol_record." }, "protocol_record_id": { "type": "string", "description": "Required (with protocol_record_type) for type=protocol_record." } }, "allOf": [ { "if": { "properties": { "type": { "const": "text" } }, "required": [ "type" ] }, "then": { "required": [ "description" ] } }, { "if": { "properties": { "type": { "const": "document_reference" } }, "required": [ "type" ] }, "then": { "required": [ "document_url", "content_hash" ] } }, { "if": { "properties": { "type": { "const": "external_record" } }, "required": [ "type" ] }, "then": { "required": [ "external_system", "external_reference" ] } }, { "if": { "properties": { "type": { "const": "protocol_record" } }, "required": [ "type" ] }, "then": { "required": [ "protocol_record_type", "protocol_record_id" ] } } ] }, "DisputeResolution": { "example": { "outcome": "partial", "resolution": { "action": "partial_refund", "reason": "Partial specification mismatch confirmed from evidence", "refund_amount": 400 }, "evidence_considered": [ "ev_photos_01", "ev_delivery_note_02" ] }, "type": "object", "required": [ "outcome" ], "properties": { "outcome": { "type": "string", "enum": [ "upheld", "rejected", "partial", "withdrawn" ] }, "resolution": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "refund", "partial_refund", "replacement", "fulfillment_completion", "no_action", "mutual_release" ] }, "reason": { "type": "string" }, "refund_amount": { "type": "number", "description": "Required for refund actions." } } }, "evidence_considered": { "type": "array", "items": { "type": "string" }, "description": "Required unless outcome=withdrawn." } }, "allOf": [ { "if": { "properties": { "outcome": { "not": { "const": "withdrawn" } } }, "required": [ "outcome" ] }, "then": { "required": [ "resolution", "evidence_considered" ], "properties": { "resolution": { "required": [ "action", "reason" ] }, "evidence_considered": { "minItems": 1 } } } }, { "if": { "properties": { "resolution": { "properties": { "action": { "enum": [ "refund", "partial_refund" ] } }, "required": [ "action" ] } }, "required": [ "resolution" ] }, "then": { "properties": { "resolution": { "required": [ "refund_amount" ], "properties": { "refund_amount": { "exclusiveMinimum": 0 } } } } } } ] }, "ChainLinkSubmission": { "example": { "link": "L3", "payload": { "principal_response": "acknowledged", "reviewed_at": "2026-06-25T12:00:00Z" }, "signature": "k9Jx2pQ7r4sV1mNc8eTfWZ0aYbHd3GgLpRtUvXyB6CnEoJqSiKlMwOzPu5D4hAtFr7vXsQ2bNcMeKgLpRtUvXyB" }, "type": "object", "required": [ "link", "payload", "signature" ], "properties": { "link": { "type": "string", "const": "L3" }, "payload": { "type": "object", "required": [ "principal_response" ], "properties": { "principal_response": { "type": "string", "enum": [ "acknowledged", "modified", "not_consulted" ] } } }, "signature": { "type": "string", "description": "Ed25519 over the canonical link." } } }, "ConformanceTranscript": { "type": "object", "description": "The evidence unit of a conformance run (roadmap). Two layers: raw events carry what actually happened, with real ids, timestamps, and signatures, and everything cryptographic binds to them; normalized events are the comparison artifact derived through the retained first-occurrence substitution map. Nothing signs a normalized transcript.", "required": [ "run_id", "namespace_id", "scenario_version", "raw_events", "normalized_events", "normalization_map", "transcript_hash" ], "properties": { "run_id": { "type": "string", "format": "uuid", "description": "The run boundary: issued by the reset that opens the run; transcripts, assertion results, and quota accounting key on it." }, "namespace_id": { "type": "string", "format": "uuid", "description": "The namespace the run executed in." }, "scenario_version": { "type": "string", "description": "The scenario family and version the run bound to, as /. The certification attestation names it." }, "raw_events": { "type": "array", "description": "Ordered typed events exactly as they happened. The hash chain and any evidence signature bind here; a verifier checks signatures against raw material, always.", "items": { "type": "object" } }, "normalized_events": { "type": "array", "description": "The raw events with UUIDs and timestamps replaced through the substitution map. Determinism assertions compare these.", "items": { "type": "object" } }, "normalization_map": { "type": "object", "description": "The first-occurrence substitution map from stable placeholders to the raw values they replaced, retained so either layer reconstructs from the other." }, "transcript_hash": { "type": "string", "description": "Hash-chain head over the raw events, the integrity anchor of the run, in the self-describing 'sha256:' form the intent chain already uses. The chain seeds on the run_id and folds each raw event in seq order: every step hashes the previous hex digest concatenated with the event's canonical serialization (object keys sorted recursively, array order preserved). A verifier recomputes the head from run_id and raw_events alone; the normalized layer is never hashed." } }, "example": { "run_id": "2b4d6f8a-0c1e-4f3a-9b5d-7e9f1a3c5b7d", "namespace_id": "7c1e2d3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "scenario_version": "scout-admission/1.0.0", "raw_events": [ { "seq": 1, "type": "session.created", "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "at": "2026-07-02T12:00:01.000Z" }, { "seq": 2, "type": "offer.presented", "offer_id": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d", "status": "pending", "at": "2026-07-02T12:00:02.000Z" } ], "normalized_events": [ { "seq": 1, "type": "session.created", "session_id": "UUID-1", "at": "TS-1" }, { "seq": 2, "type": "offer.presented", "offer_id": "UUID-2", "status": "pending", "at": "TS-2" } ], "normalization_map": { "UUID-1": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "UUID-2": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d", "TS-1": "2026-07-02T12:00:01.000Z", "TS-2": "2026-07-02T12:00:02.000Z" }, "transcript_hash": "sha256:c7e9a1b3d5f7092c4e6a8b0d2f4c6e8a1b3d5f70a2c4e6b8d0f2a4c6e8b0d2f4" } }, "IntentChain": { "example": { "transaction_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "chain_status": "complete", "links": [ { "link": "L1", "name": "principal_signal" }, { "link": "L6", "name": "commitment" }, { "link": "L7", "name": "outcome" } ], "chain_hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "chain_signature": "k9Jx2pQ7r4sV1mNc8eTfWZ0aYbHd3GgLpRtUvXyB6CnEoJqSiKlMwOzPu5D4hAtFr7vXsQ2bNcMeKgLpRtUvXyB" }, "type": "object", "description": "Assembled intent chain of custody (L1–L7). Beacons receive a redacted view (L2, L4, L6, L7).", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "chain_status": { "type": "string" }, "links": { "type": "array", "items": { "type": "object" } }, "chain_hash": { "type": [ "string", "null" ] }, "chain_signature": { "type": [ "string", "null" ] } } }, "KeyReplacementRequest": { "type": "object", "description": "Principal-authorized replacement of an agent key whose private half can no longer be trusted to sign (compromise recovery). The canonical payload is the same as rotation, with entity_type 'agent' and the agent's current key as old_public_key. The compromised key signs nothing.", "required": [ "new_public_key", "rotation_timestamp", "new_key_proof", "principal_authorization" ], "properties": { "new_public_key": { "type": "string", "description": "Raw 32-byte Ed25519 public key, base64." }, "rotation_timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601, submitted explicitly so the client and Core construct the same canonical payload. Must fall within 300 seconds of Core receipt, either side." }, "new_key_proof": { "type": "string", "description": "Base64 Ed25519 signature over the canonical rotation payload by the NEW key. Proves possession." }, "principal_authorization": { "type": "string", "description": "Base64 Ed25519 signature over the canonical payload by the principal's key. The principal is the authority over its agents' keys." } }, "example": { "new_public_key": "xoImN8fTEOxXYnvgC6JZ0lN0n0qvZERwz/vlOjX3MkI=", "rotation_timestamp": "2026-07-02T12:00:00.000Z", "new_key_proof": "dXkM2mTtOW3lhJKMOpMNF3OvlsmC86StP0uMr8HaFeTaWl/vgtXn8zzwlIJ/73gRlhbqBbLeGW6FLP6SYRX0Dw==", "principal_authorization": "4Ni2IuwiOe1hP9en5shC+9Fnn/RIFrhqSQAaD+80zzBqs/0vq8DJG8+smrHdT4E4fmqsffsISRdOPZneE2PMDQ==" } }, "KeyRotationRequest": { "type": "object", "description": "Dual-signed key rotation. The canonical payload joins entity_type, entity_id, old_public_key, new_public_key, and rotation_timestamp with LF; old_public_key is always the entity's current live key as Core holds it, never a client-supplied value. The new key proves possession, the current key authorizes.", "required": [ "new_public_key", "rotation_timestamp", "new_key_proof" ], "properties": { "new_public_key": { "type": "string", "description": "Raw 32-byte Ed25519 public key, base64." }, "rotation_timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601, submitted explicitly so the client and Core construct the same canonical payload. Must fall within 300 seconds of Core receipt, either side." }, "new_key_proof": { "type": "string", "description": "Base64 Ed25519 signature over the canonical rotation payload by the NEW key. Proves possession." }, "old_key_authorization": { "type": "string", "description": "Base64 Ed25519 signature over the same canonical payload by the CURRENT key. Required for principal rotation. Optional for agent self-rotation: a request authenticated by the current key that carries the payload fields authorizes exactly the enclosed rotation." }, "old_public_key": { "type": "string", "description": "Optional diagnostic echo of the key the payload was constructed against. Core never trusts it; the live key is authoritative." } }, "example": { "new_public_key": "xoImN8fTEOxXYnvgC6JZ0lN0n0qvZERwz/vlOjX3MkI=", "rotation_timestamp": "2026-07-02T12:00:00.000Z", "new_key_proof": "dXkM2mTtOW3lhJKMOpMNF3OvlsmC86StP0uMr8HaFeTaWl/vgtXn8zzwlIJ/73gRlhbqBbLeGW6FLP6SYRX0Dw==", "old_key_authorization": "TwuvQD2mbRmt3iJx41Y1Rtr8kKARk+Gh2VndSz2ISO9vISaEuusVvCaglJi1Mh6QkBpWz4idDCXGuAHrPcsVAA==" } }, "SandboxIdentityNotVerified": { "type": "object", "description": "The domain proof failed. The response names exactly what Core looked for and what it found, so the agent can publish the missing record or document and retry.", "required": [ "error", "message", "looked_for", "found" ], "properties": { "error": { "type": "string", "examples": [ "sandbox_identity_not_verified" ] }, "message": { "type": "string", "description": "Human-readable summary including looked_for and found." }, "looked_for": { "type": "string", "description": "The exact record or document Core required: the TXT name and value, or the well-known URL and JSON shape." }, "found": { "type": "string", "description": "What Core actually observed: the TXT values present, the document contents, or the lookup error." } }, "example": { "error": "sandbox_identity_not_verified", "message": "Domain control not proven. Looked for: TXT _aura-agent-key.agents.example.com = \"aura-key=q83v3vP2mDGVLR2feqfUZQvVHt5nVUZbklsi2M4L8kU=\". Found: no TXT records. Publish the record or document, allow DNS or cache propagation, and retry.", "looked_for": "TXT _aura-agent-key.agents.example.com = \"aura-key=q83v3vP2mDGVLR2feqfUZQvVHt5nVUZbklsi2M4L8kU=\"", "found": "no TXT records" } }, "SandboxKeyGrant": { "type": "object", "description": "The mint grant. The sandbox_key appears here once and is stored hashed; if lost or compromised, re-mint under the re-proven domain and the prior key is revoked in the same transaction (revoked_previous says so). The key is a bearer capability handle: its blast radius is one namespace and its quotas, never a protocol identity.", "required": [ "sandbox_key", "display_prefix", "domain", "verification_method", "granted_at", "revoked_previous", "key_semantics", "quotas" ], "properties": { "sandbox_key": { "type": "string", "description": "The bearer key, ak_sandbox_ prefixed. Shown once. Present it as the X-AURA-Sandbox-Key header once provisioning ships." }, "display_prefix": { "type": "string", "description": "The short prefix Core will use when referring to this key in logs and errors. Safe to store and display." }, "domain": { "type": "string", "description": "The verified identity anchor. Every quota counts against it." }, "verification_method": { "type": "string" }, "granted_at": { "type": "string", "format": "date-time" }, "revoked_previous": { "type": "boolean", "description": "True when this mint revoked the domain's prior active key (one active key per domain; re-mint IS compromise recovery)." }, "key_semantics": { "type": "object", "description": "What the key is, how it presents, and when it becomes consumable, stated normatively so an agent never infers.", "required": [ "anchor", "presentation", "consumable", "consumable_when" ], "properties": { "anchor": { "type": "string", "description": "The tenancy and identity anchoring statement." }, "presentation": { "type": "string", "description": "How to present the key (X-AURA-Sandbox-Key, bearer, shown once) and how to recover it." }, "consumable": { "type": "boolean", "description": "Whether the key authorizes any operation yet. False until provisioning ships." }, "consumable_when": { "type": "string", "description": "The condition under which the key becomes consumable." } } }, "quotas": { "type": "object", "description": "The quota defaults this grant inherits, as contract-visible facts; the operator may raise the namespace-count default without a protocol change.", "required": [ "quotasAreDefaults", "active_sandbox_keys_per_domain", "active_namespaces_per_identity", "provisions_per_identity_per_day", "conformance_runs_per_key_per_day", "requests_per_namespace_per_minute" ], "properties": { "quotasAreDefaults": { "type": "boolean" }, "active_sandbox_keys_per_domain": { "type": "integer" }, "active_namespaces_per_identity": { "type": "integer" }, "provisions_per_identity_per_day": { "type": "integer" }, "conformance_runs_per_key_per_day": { "type": "integer" }, "requests_per_namespace_per_minute": { "type": "integer" } } }, "verification_reference": { "type": "object", "description": "The exact record and document Core accepted or would accept for this domain and key, echoed for the agent to keep." } }, "example": { "sandbox_key": "ak_sandbox_5gW3jH9kPqRvT1xZ8mBnC4dFyLsA7eKw2NcQ6uVi0oYt", "display_prefix": "ak_sandbox_5gW3jH", "domain": "agents.example.com", "verification_method": "dns_txt", "granted_at": "2026-07-03T12:00:00.000Z", "revoked_previous": false, "key_semantics": { "anchor": "This key is the tenant anchor for one sandbox namespace; the verified domain is the identity anchor every quota counts against.", "presentation": "Bearer, via the X-AURA-Sandbox-Key header. Shown once; stored hashed. If lost or compromised, re-mint under the re-proven domain: the prior key is revoked in the same transaction.", "consumable": false, "consumable_when": "Sandbox provisioning ships (provisionSandbox, roadmap): the key will bind to its namespace at provision time and accompany every namespaced call." }, "quotas": { "quotasAreDefaults": true, "active_sandbox_keys_per_domain": 1, "active_namespaces_per_identity": 1, "provisions_per_identity_per_day": 3, "conformance_runs_per_key_per_day": 10, "requests_per_namespace_per_minute": 120 }, "verification_reference": { "dns_txt": "TXT _aura-agent-key.agents.example.com = \"aura-key=q83v3vP2mDGVLR2feqfUZQvVHt5nVUZbklsi2M4L8kU=\"", "well_known": "https://agents.example.com/.well-known/aura-agent-key -> JSON {\"public_key\": \"q83v3vP2mDGVLR2feqfUZQvVHt5nVUZbklsi2M4L8kU=\"}" } } }, "SandboxKeyMintRequest": { "type": "object", "description": "Mint a sandbox key: the tenant anchor for one namespace, granted to a domain-verified Ed25519 key. Two proofs are required. Possession: the X-Signature header carries the Ed25519 signature over this exact JSON body by the declared public_key (serialize with JSON.stringify, sign the UTF-8 bytes, send base64). Domain control: publish the declared key at the location only the domain's controller can write, then name the method here. dns_txt: a TXT record at _aura-agent-key. with the exact value aura-key=. well_known: the document https:///.well-known/aura-agent-key returning JSON with a matching public_key field, fetched over HTTPS to public addresses only, no redirects, 5 second timeout. Possession is checked first and cheaply; no network lookup happens for an unproven key.", "required": [ "domain", "public_key", "verification_method" ], "properties": { "domain": { "type": "string", "description": "The identity anchor: a bare public multi-label DNS hostname you control. Lowercased on receipt. No wildcards, IP addresses, schemes, ports, or paths: those cannot prove control and are refused before any lookup." }, "public_key": { "type": "string", "description": "Raw 32-byte Ed25519 public key, base64. Never reused: a key bound to any identity, key history, or another domain is refused." }, "verification_method": { "type": "string", "enum": [ "dns_txt", "well_known" ], "description": "Which proof Core should check. Both prove the same statement: the controller of this domain authorizes this key." } }, "example": { "domain": "agents.example.com", "public_key": "q83v3vP2mDGVLR2feqfUZQvVHt5nVUZbklsi2M4L8kU=", "verification_method": "dns_txt" } }, "SandboxManifest": { "type": "object", "description": "What a provisioned sandbox namespace is, as machine-readable fact: the market it seeds, the quotas it enforces, the determinism it promises, and every semantic exception where sandbox behaviour deviates from production. Returned by sandbox provisioning (roadmap).", "required": [ "namespace_id", "scenario_version", "contract_version", "signing_key_id", "market_profile", "rails", "quotas", "determinism", "sandbox_semantic_exceptions" ], "properties": { "namespace_id": { "type": "string", "format": "uuid", "description": "The logical namespace all state registered with this sandbox key lands in." }, "scenario_version": { "type": "string", "description": "The versioned scenario family this namespace certifies against, as /." }, "contract_version": { "type": "string", "description": "The protocol contract version the sandbox deployment is pinned to. Runs re-check it at start; skew is discovered here, never mid-run." }, "signing_key_id": { "type": "string", "description": "Fingerprint of the sandbox deployment's signing key. Distinct from production's key and never listed in the production key directory." }, "market_profile": { "type": "object", "description": "The seeded market profile with its concrete dial values, declared as facts." }, "rails": { "type": "array", "description": "The simulated settlement rails, with declared reversibility, covering both reserve branches.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "native_repudiation": { "type": "boolean" }, "finality_seconds": { "type": "integer" } } } }, "counterparties": { "type": "array", "description": "The seeded house counterparties: role and public key, deterministically derived per namespace.", "items": { "type": "object", "properties": { "role": { "type": "string", "description": "cooperative_beacon, adversarial_beacon, or house_scout." }, "public_key": { "type": "string", "description": "Raw 32-byte Ed25519 public key, base64." } } } }, "applicant_risk_tier": { "type": "string", "description": "The risk tier a freshly registered applicant principal lands in, declared so reserve assertions are written against a known tier." }, "quotas": { "type": "object", "description": "The quota values enforced for this namespace: the declared defaults, or the operator-granted namespace count where one was granted." }, "latency_budgets": { "type": "object", "description": "Published provisioning latency budgets, measured as service objectives." }, "determinism": { "type": "object", "description": "The determinism statement: what is reproducible and what is normalized." }, "sandbox_semantic_exceptions": { "type": "array", "description": "Every place sandbox semantics deviate from production, as named machine-readable entries, so an agent cannot learn a false production rule from sandbox observation.", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "sandbox_exception": { "type": "string" }, "applies_to": { "type": "string" } } } }, "run_id": { "type": "string", "format": "uuid", "description": "The conformance run this namespace has open. Provision opens the run and returns it; reset opens a fresh one. Transcript events and the transcript endpoint key on it." } }, "example": { "namespace_id": "7c1e2d3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "scenario_version": "scout-admission/1.0.0", "contract_version": "3.0.0", "signing_key_id": "9f2c7a1e0b3d5f8a6c4e2d0b9a7c5e3f1d8b6a4c2e0f9d7b5a3c1e8f6d4b2a09", "market_profile": { "profile_id": "prf_sandbox_cert_v1", "dispute_window_days_default": 14 }, "rails": [ { "id": "sandbox-instant", "native_repudiation": false, "finality_seconds": 5 }, { "id": "sandbox-card", "native_repudiation": true } ], "counterparties": [ { "role": "cooperative_beacon", "public_key": "q83v3vP2mDGVLR2feqfUZQvVHt5nVUZbklsi2M4L8kU=" }, { "role": "adversarial_beacon", "public_key": "3n1kAiG9BDoaR9EWWJ2QxHDDo2rcW9jhVXwGRlaBFEY=" } ], "applicant_risk_tier": "high", "quotas": { "active_namespaces_per_identity": 1, "conformance_runs_per_key_per_day": 10, "requests_per_namespace_per_minute": 120 }, "latency_budgets": { "provision_p50_ms": 300, "provision_p99_ms": 1000 }, "determinism": { "level": "transcript", "normalized": [ "uuids", "timestamps" ] }, "sandbox_semantic_exceptions": [ { "rule": "production_key_reuse_forbidden", "sandbox_exception": "seeded_house_counterparty_keys_reused_after_namespace_reset", "applies_to": "house_counterparties_only" } ], "run_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d" } }, "ProvisionSandboxRequest": { "type": "object", "additionalProperties": false, "description": "Optional provisioning parameters. An empty body provisions the scenario this bench serves.", "properties": { "scenario_version": { "type": "string", "pattern": "^[a-z][a-z0-9-]*/\\d+\\.\\d+\\.\\d+$", "description": "The scenario family and version to provision, as family/semver. Omitted means the version this bench serves; a mismatch is refused sandbox_contract_version_skew naming the served version, so an agent pinning a scenario never runs against a drifted bench." } }, "example": { "scenario_version": "scout-admission/1.0.0" } }, "ResetSandboxRequest": { "type": "object", "additionalProperties": false, "description": "Optional reset parameters. An empty body resets to the scenario this bench serves.", "properties": { "reason": { "type": "string", "maxLength": 200, "description": "A note recorded in the bench log for the operator and for run forensics. It changes nothing about the reset." } }, "example": { "reason": "opening a fresh conformance run" } }, "SandboxResetResult": { "type": "object", "additionalProperties": false, "required": [ "namespace_id", "run_id", "scenario_version", "contract_version", "reset_at" ], "description": "The run boundary: the namespace is destroyed and reseeded, and this run identity is what transcripts, assertion results, and run quotas key on.", "properties": { "namespace_id": { "type": "string", "format": "uuid", "description": "The namespace that was reset. Unchanged across resets: the tenant anchor is the key, the namespace follows it." }, "run_id": { "type": "string", "format": "uuid", "description": "Opaque identifier for the run this reset opens. No ordering or format semantics are promised; treat it as a handle." }, "scenario_version": { "type": "string", "description": "The scenario family and version this run certifies against." }, "contract_version": { "type": "string", "description": "The protocol contract version the bench is pinned to for this run." }, "reset_at": { "type": "string", "format": "date-time", "description": "When the run opened." } }, "example": { "namespace_id": "7c1e2d3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "run_id": "2f8e6d4c-1b3a-4059-8c7e-5d2f0a9b8c7d", "scenario_version": "scout-admission/1.0.0", "contract_version": "3.0.0", "reset_at": "2026-07-06T08:30:00Z" } } } }, "webhooks": { "transaction.committed": { "post": { "summary": "A Scout committed to this Beacon's offer; the transaction exists.", "x-aura-status": "normative", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "idempotency_key": { "type": "string", "description": "Deduplicate on this; a retried delivery carries the same key." }, "session_id": { "type": "string", "format": "uuid" }, "offer_id": { "type": "string", "format": "uuid" }, "final_terms": { "type": "object", "properties": { "product": { "type": "string" }, "total_price": { "type": "number" }, "currency": { "type": "string" }, "delivery_date": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx counts as delivered; anything else is retried (1s, 2s, 4s) and then dead-lettered." } } } }, "transaction.disputed": { "post": { "summary": "A dispute was filed against this transaction.", "x-aura-status": "normative", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dispute_id": { "type": "string", "format": "uuid" }, "transaction_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "evidence_deadline": { "type": "string", "format": "date-time" }, "resolution_deadline": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx counts as delivered; anything else is retried (1s, 2s, 4s) and then dead-lettered." } } } }, "clearing.risk_assessed": { "post": { "summary": "Clearing opened at commit: risk scored and the reserve plan set.", "x-aura-status": "normative", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "clearing_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "reserve_status": { "type": "string" }, "risk_tier": { "type": "string" }, "reserve_margin_amount": { "type": "number" }, "net_settlement_amount": { "type": "number" }, "currency": { "type": "string" }, "settlement_method": { "type": "string" } } } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx counts as delivered; anything else is retried (1s, 2s, 4s) and then dead-lettered." } } } }, "clearing.settled": { "post": { "summary": "Settlement confirmed on the rail.", "x-aura-status": "normative", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "clearing_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "previous_status": { "type": "string" } } } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx counts as delivered; anything else is retried (1s, 2s, 4s) and then dead-lettered." } } } }, "clearing.cleared": { "post": { "summary": "Clearing complete; the dispute term governs the reserve from here.", "x-aura-status": "normative", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "clearing_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "previous_status": { "type": "string" } } } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx counts as delivered; anything else is retried (1s, 2s, 4s) and then dead-lettered." } } } }, "reserve.released": { "post": { "summary": "The held reserve released to the seller after clean clearing.", "x-aura-status": "normative", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "clearing_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "previous_status": { "type": "string" } } } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx counts as delivered; anything else is retried (1s, 2s, 4s) and then dead-lettered." } } } }, "fulfillment.updated": { "post": { "summary": "The Beacon reported a fulfillment change (shipped, delivered).", "x-aura-status": "normative", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "idempotency_key": { "type": "string" }, "session_id": { "type": "string", "format": "uuid" }, "fulfillment_status": { "type": "string" }, "fulfillment_reference": { "type": [ "string", "null" ] }, "status": { "type": "string" } } } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx counts as delivered; anything else is retried (1s, 2s, 4s) and then dead-lettered." } } } }, "payment.updated": { "post": { "summary": "Payment state changed (pending, charged, failed, refunded).", "x-aura-status": "normative", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "idempotency_key": { "type": "string" }, "session_id": { "type": "string", "format": "uuid" }, "payment_status": { "type": "string" }, "payment_reference": { "type": [ "string", "null" ] }, "status": { "type": "string" } } } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx counts as delivered; anything else is retried (1s, 2s, 4s) and then dead-lettered." } } } }, "reserve.drawn": { "post": { "summary": "RESERVED NAME (not yet emitted): the reserve was drawn down to fund a dispute payout. Subscribe now; the emitter ships with the dispute-drawdown path.", "x-aura-status": "roadmap", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "clearing_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "previous_status": { "type": "string" } } } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx counts as delivered; anything else is retried (1s, 2s, 4s) and then dead-lettered." } } } }, "enforcement.triggered": { "post": { "summary": "RESERVED NAME (not yet emitted): a principal crossed an enforcement threshold. Subscribe now; the emitter ships with the risk loop.", "x-aura-status": "roadmap", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "principal_id": { "type": "string", "format": "uuid" }, "enforcement_status": { "type": "string" } } } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx counts as delivered; anything else is retried (1s, 2s, 4s) and then dead-lettered." } } } }, "reserve.rail_managed": { "post": { "summary": "RESERVED NAME (not yet emitted): the rail's native repudiation infrastructure governs this transaction; no AURA-side reserve was held. Subscribe now; the emitter ships with the rail-conditional outcome events.", "x-aura-status": "roadmap", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "clearing_id": { "type": "string", "format": "uuid" }, "currency": { "type": "string" } } } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx counts as delivered; anything else is retried (1s, 2s, 4s) and then dead-lettered." } } } }, "reserve.held": { "post": { "summary": "A reserve margin is held against the seller's settlement proceeds (non-repudiation rails).", "x-aura-status": "normative", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "clearing_id": { "type": "string", "format": "uuid" }, "reserve_margin_amount": { "type": "number" }, "reserve_margin_pct": { "type": "number" }, "currency": { "type": "string" } } } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx counts as delivered; anything else is retried (1s, 2s, 4s) and then dead-lettered." } } } } }, "x-aura-specification": { "canonical": true, "specVersion": "3.0", "normativeLanguage": "RFC2119", "extensionNamespace": "x-aura-", "precedence": [ "OpenAPI paths, operations and schemas", "x-aura-* normative extensions", "descriptions", "implementation metadata" ], "implementationMetadataNormative": false, "statusVocabulary": [ "normative", "implemented", "reserved", "roadmap", "explanatory", "deprecated" ], "extensions": { "x-aura-glossary": "explanatory", "x-aura-ontology": "normative", "x-aura-design-principles": "explanatory", "x-aura-invariants": "normative", "x-aura-authority": "normative", "x-aura-market-model": "explanatory", "x-aura-market-parameters": "normative-interface", "x-aura-reputation": "normative-interface", "x-aura-conformance": "normative", "x-aura-state-machines": "normative", "x-aura-signature-profiles": "normative", "x-aura-signature-test-vectors": "normative", "x-aura-intent-chain": "normative", "x-aura-key-lifecycle": "normative", "x-aura-agent-admission": "normative", "x-aura-transcript-events": "normative" } }, "x-aura-glossary": { "status": "explanatory", "description": "Canonical definitions of the protocol's terms.", "terms": [ { "term": "Scout", "definition": "An autonomous agent acting for a buyer." }, { "term": "Beacon", "definition": "An autonomous agent acting for a seller." }, { "term": "AURA Core", "definition": "The neutral broker. It interprets intent, routes it to beacons, mediates the exchange, and records the outcome. It holds no commercial position." }, { "term": "Principal", "definition": "The human or legal entity an agent acts for under delegated authority." }, { "term": "Session", "definition": "A logical exchange from a scout's request to a committed transaction." }, { "term": "Request", "definition": "A scout's expression of need: a natural-language intent and optional constraints." }, { "term": "Interpreted Request", "definition": "Core's structured representation of a scout's intent." }, { "term": "Offer", "definition": "A beacon's signed response carrying product, price, and terms." }, { "term": "Constraint", "definition": "A buyer's declared bound on an acceptable outcome. A hard constraint binds. A soft preference ranks." }, { "term": "Transaction", "definition": "A committed exchange between a scout and a beacon." }, { "term": "Clearing record", "definition": "The financial lifecycle of a committed transaction: risk assessment, reserve, and settlement." }, { "term": "Intent chain", "definition": "The signed chain of custody from the human signal to the outcome, links L1 to L7." }, { "term": "Reputation", "definition": "A multi-dimensional behavioural signal Core computes from protocol events." }, { "term": "Settlement rail", "definition": "An external payment system that moves funds for a cleared transaction." }, { "term": "Market profile", "definition": "A named set of market parameters a Core applies within the protocol's invariants." } ] }, "x-aura-ontology": { "status": "normative", "description": "The protocol's entities, their roles, relationships, and prohibitions. Tooling and agents reason over this model; humans read the glossary.", "entities": [ { "name": "Scout", "kind": "agent", "definition": "An agent acting for a buyer.", "actsFor": "Principal", "declares": [ "Request", "Constraint" ], "prohibitedFrom": [ "browsing_inventory", "receiving_beacon_identity_before_commitment" ], "participatesIn": [ "Session", "IntentChain" ] }, { "name": "Beacon", "kind": "agent", "definition": "An agent acting for a seller.", "actsFor": "Principal", "declares": [ "Offer" ], "prohibitedFrom": [ "receiving_scout_identity_before_commitment", "contacting_a_scout_directly" ], "participatesIn": [ "Session", "Transaction" ] }, { "name": "Core", "kind": "neutral_broker", "definition": "The disinterested party that mediates every exchange.", "actsFor": "none", "holdsCommercialPosition": false, "prohibitedFrom": [ "trading_on_its_own_account", "ranking_or_pricing_to_favour_a_side", "revealing_a_party_identity_before_commitment" ], "participatesIn": [ "Session", "Transaction", "Clearing", "IntentChain" ] }, { "name": "Principal", "kind": "party", "definition": "The human or legal entity an agent acts for.", "delegatesTo": [ "Scout", "Beacon" ], "participatesIn": [ "Authority" ] }, { "name": "Session", "kind": "resource", "definition": "An exchange from request to commitment.", "ownedBy": "Scout", "boundTo": "MarketProfile", "contains": [ "Offer" ] }, { "name": "Offer", "kind": "resource", "definition": "A beacon's signed, sealed response.", "issuedBy": "Beacon", "signedBy": "Beacon", "presentedBy": "Core" }, { "name": "Transaction", "kind": "resource", "definition": "A committed exchange.", "commitsFrom": "Offer" }, { "name": "ClearingRecord", "kind": "resource", "definition": "The financial lifecycle of a transaction.", "derivesFrom": "Transaction" }, { "name": "IntentChain", "kind": "record", "definition": "The signed chain of custody from signal to outcome.", "assembledBy": "Core", "links": [ "L1", "L2", "L3", "L4", "L5", "L6", "L7" ] }, { "name": "Request", "kind": "signal", "definition": "A Scout's expression of need.", "declaredBy": "Scout", "interpretedBy": "Core", "produces": "InterpretedRequest" }, { "name": "InterpretedRequest", "kind": "derived_record", "definition": "Core's structured representation of the Scout's intent.", "derivedFrom": "Request", "attestedBy": "Core", "participatesIn": [ "Session" ] }, { "name": "Constraint", "kind": "authority_boundary", "definition": "A declared bound on an acceptable outcome. A hard constraint binds; a soft preference ranks.", "declaredBy": "Scout", "binds": [ "Session", "Offer", "Transaction" ], "variants": [ "hard", "soft" ], "governedBy": "INV-004" }, { "name": "Reputation", "kind": "behavioural_signal", "definition": "A multi-dimensional behavioural signal Core computes from protocol events.", "attachesTo": [ "Principal", "Beacon" ], "derivedFrom": [ "Offer", "Transaction", "ClearingRecord", "Dispute" ] } ] }, "x-aura-design-principles": { "status": "explanatory", "normative": false, "description": "Why the protocol has this shape. Each principle justifies a family of invariants. The principles explain; the invariants govern.", "principles": [ { "id": "DP-001", "name": "Privacy by design", "statement": "Counterparty identity and constraints are disclosed only when the protocol phase requires them.", "supports": [ "INV-002", "INV-003" ], "status": "implemented" }, { "id": "DP-002", "name": "Business rules as gates", "statement": "Binary eligibility rules are enforced before any scoring or settlement economics.", "supports": [ "INV-013" ], "status": "implemented" }, { "id": "DP-003", "name": "Atomicity over partial state", "statement": "A transaction commits in full or leaves no residue.", "supports": [ "INV-006" ], "status": "implemented" }, { "id": "DP-004", "name": "Verifiable provenance", "statement": "Every consequential step is signed and can be reconstructed after the fact.", "supports": [ "INV-008", "INV-009" ], "status": "implemented" }, { "id": "DP-005", "name": "Neutrality of the broker", "statement": "Core mediates the trade without holding a position in it.", "supports": [ "INV-001", "INV-011" ], "status": "implemented" }, { "id": "DP-006", "name": "Explicit authority", "statement": "An agent acts only within authority a principal has delegated and recorded.", "supports": [ "INV-004", "INV-007", "INV-015" ], "status": "implemented" } ] }, "x-aura-invariants": { "status": "normative", "description": "Protocol law. Each invariant binds every conforming Core in every market. It states the rule, the chaos the naive alternative produces, the operations and schemas that manifest it, the market parameters it bounds, and its conformance assertions.", "invariants": [ { "id": "INV-001", "name": "Neutral brokerage", "status": "normative", "statement": "Core MUST mediate every Scout and Beacon interaction. A conforming Core MUST NOT expose an unmediated bilateral channel for protocol offers.", "rationale": "Two agents that both have a stake in the price cannot safely exchange information. Direct trade collapses into a market for lemons with cheap, unenforceable quotes. Only a party with no stake can hold both sides’ private information without abusing it.", "averts": [ "adverse_selection", "collusive_equilibrium", "oscillation", "asymmetric_exploitation" ], "manifestedBy": { "operations": [ "createSession", "submitOffer", "commitSession" ], "schemas": [ "Session", "Offer", "Transaction" ] }, "boundedParameters": [ "disclosure_schedule", "offer_visibility" ], "conformance": [ { "id": "CONF-INV-001", "assertion": "A Beacon response MUST be submitted to Core and MUST NOT be addressed directly to a Scout.", "assertionType": "property", "fixture": { "given": "A Beacon has an offer for an open session", "when": "a Scout retrieves the session offers", "then": "every offer it receives was routed through Core, and no direct Beacon-to-Scout channel exists" } } ] }, { "id": "INV-002", "name": "Identity abstraction until commitment", "status": "normative", "statement": "Core MUST withhold each party’s identity from the other until commitment. A Beacon MUST NOT receive the Scout’s identity before the transaction commits.", "rationale": "An agent that knows who it faces prices the counterparty instead of the goods. Hidden identity forces competition on the offer and produces genuine price discovery.", "averts": [ "price_discrimination", "information_probing" ], "manifestedBy": { "operations": [ "listOffers", "submitOffer", "getSession" ], "schemas": [ "Offer", "Session" ] }, "boundedParameters": [ "disclosure_schedule" ], "conformance": [ { "id": "CONF-INV-002", "assertion": "A presented offer MUST NOT carry the counterparty’s identity before commitment.", "assertionType": "negative", "fixture": { "given": "An offer presented before commitment", "when": "the offer payload is inspected", "then": "it carries no counterparty identity" } } ] }, { "id": "INV-003", "name": "Monotonic disclosure", "status": "normative", "statement": "Information disclosed to a party MUST only increase as commitment deepens. No phase MAY reveal less than a prior phase.", "rationale": "If disclosure can retract, a party hoards information defensively and the market goes opaque. A one-way ratchet lets each side reveal exactly enough, exactly when the commitment justifies it.", "averts": [ "defensive_opacity" ], "manifestedBy": { "operations": [ "getSession", "listOffers" ], "schemas": [ "Session" ] }, "boundedParameters": [ "disclosure_schedule" ], "conformance": [ { "id": "CONF-INV-003", "assertion": "A field visible at one phase MUST remain visible at every later phase.", "assertionType": "property", "fixture": { "given": "A field visible to a party at one phase", "when": "the session advances to any later phase", "then": "the field remains visible to that party" } } ] }, { "id": "INV-004", "name": "Constraints as bounds", "status": "normative", "statement": "Hard constraints define the authorised negotiation space. A conforming Scout, Core, or Beacon MUST NOT treat a hard constraint as a ranking preference, and Core MUST reject a commitment that exceeds one.", "rationale": "A hard constraint is the principal’s delegated authority boundary. A commitment beyond it exceeds the mandate the principal granted. Treating constraints as bounds keeps agents inside that mandate.", "averts": [ "unbounded_probing", "authority_violation" ], "manifestedBy": { "operations": [ "createSession", "submitOffer", "counterOffer", "commitSession" ], "schemas": [ "SessionCreate", "OfferSubmission" ] }, "boundedParameters": [], "conformance": [ { "id": "CONF-INV-004", "assertion": "A commit MUST fail when the selected offer violates a hard constraint of the session.", "assertionType": "negative", "fixture": { "given": "A session with a hard constraint and an offer that violates it", "when": "commitSession selects that offer", "then": "Core rejects the commit and creates no transaction" } } ] }, { "id": "INV-005", "name": "Offer expiry", "status": "normative", "statement": "Every offer MUST carry an expiry. Core MUST refuse to commit an expired offer.", "rationale": "Free, open-ended options let an agent reserve everywhere and commit nowhere. An expiry turns the negotiation into discrete rounds and ends the speed race.", "averts": [ "strategic_non_commitment", "speed_arms_race" ], "manifestedBy": { "operations": [ "submitOffer", "commitSession", "counterOffer" ], "schemas": [ "Offer" ] }, "boundedParameters": [ "offer_validity_window" ], "conformance": [ { "id": "CONF-INV-005", "assertion": "A commit on an offer past its expires_at MUST be rejected.", "assertionType": "negative", "fixture": { "given": "An offer whose expires_at is in the past", "when": "commitSession is called on it", "then": "Core rejects the commit and creates no transaction" } } ] }, { "id": "INV-006", "name": "Atomic commitment", "status": "normative", "statement": "Commitment MUST be atomic. Committing to one offer MUST reject its siblings in the same transaction, with no observable intermediate state.", "rationale": "If commitment is not atomic, a concurrent reader sees capacity reserved twice and the same offer taken by two parties. One indivisible step makes a commitment mean exactly one thing.", "averts": [ "phantom_liquidity", "double_commitment" ], "manifestedBy": { "operations": [ "commitSession" ], "schemas": [ "CommitRequest", "Transaction" ] }, "boundedParameters": [], "conformance": [ { "id": "CONF-INV-006", "assertion": "A successful commit MUST atomically create the transaction and reject all sibling offers; a duplicate idempotency key MUST return the original result.", "assertionType": "sequence", "fixture": { "given": "A session with several pending offers", "when": "commitSession succeeds on one of them", "then": "exactly one transaction is created, all sibling offers are rejected, and replaying the same idempotency key returns the original transaction" } } ] }, { "id": "INV-007", "name": "Persistent identity and qualification", "status": "normative", "statement": "Agents MUST hold a persistent Ed25519 identity established by proof of possession. A new identity MUST start below the participation threshold.", "rationale": "Cooperation needs the shadow of the future. If identities are free and disposable, a defector simply re-registers. A non-trivial identity with a cost of entry gives every participant something to lose.", "averts": [ "disposable_identity_defection", "end_game_defection" ], "manifestedBy": { "operations": [ "registerAgent", "registerPrincipal", "rotateAgentKey", "rotatePrincipalKey", "replaceAgentKey" ], "schemas": [ "AgentRegistration", "PrincipalRegistration" ] }, "boundedParameters": [ "qualification_threshold" ], "conformance": [ { "id": "CONF-INV-007", "assertion": "Registration MUST verify an Ed25519 proof of possession of the submitted key.", "assertionType": "negative", "fixture": { "given": "A registration whose signature does not prove possession of the submitted key", "when": "registerPrincipal or registerAgent is called", "then": "Core rejects the registration" } } ] }, { "id": "INV-008", "name": "Recorded intent and chain of custody", "status": "normative", "statement": "Core MUST record the original intent and assemble a signed chain of custody from the human signal to the outcome. The chain MUST be immutable once written.", "rationale": "A commitment with no record of how it was reached cannot be adjudicated. A signed chain makes every step attributable, so the market enforces commitments rather than relitigating them.", "averts": [ "unadjudicable_dispute" ], "manifestedBy": { "operations": [ "createSession", "submitChainLink", "commitSession", "getIntentChain", "getAttestation" ], "schemas": [ "ChainLinkSubmission", "IntentChain", "Attestation" ] }, "boundedParameters": [], "conformance": [ { "id": "CONF-INV-008", "assertion": "Each chain link MUST be signed by the responsible party and chained to its predecessor.", "assertionType": "property", "fixture": { "given": "An assembled intent chain", "when": "each link is verified", "then": "every link is signed by its responsible party and references its predecessor" } } ] }, { "id": "INV-009", "name": "Verifiable settlement", "status": "normative", "statement": "Clearing MUST advance to settled only on a verifiable, non-repudiable proof of settlement correlated to the original instruction.", "rationale": "Settlement taken on trust fails the first dishonest counterparty. A signed proof from the rail makes finality a fact the protocol can check rather than a claim it must accept.", "averts": [ "unprovable_settlement" ], "manifestedBy": { "operations": [ "getClearing", "updatePayment" ], "schemas": [ "ClearingRecord" ] }, "boundedParameters": [ "settlement_method" ], "conformance": [ { "id": "CONF-INV-009", "assertion": "A transition to settled MUST carry a rail-signed proof correlated to the settlement instruction.", "assertionType": "property", "fixture": { "given": "A transaction that has transitioned to settled", "when": "the settlement record is read", "then": "it carries a rail-signed proof correlated to the settlement instruction" } } ] }, { "id": "INV-010", "name": "Rail-conditional reserve", "status": "normative", "statement": "Core MUST size a reserve conditioned on the rail. A rail with native repudiation MUST NOT carry a duplicative AURA hold; a rail without it MUST.", "rationale": "Where the rail can reverse a charge, a second hold is waste. Where it cannot, an unreserved loss is unrecoverable. Sizing the reserve to the rail puts protection exactly where the infrastructure leaves a gap.", "averts": [ "unenforceable_outcome", "duplicative_hold" ], "manifestedBy": { "operations": [ "commitSession", "getClearing" ], "schemas": [ "ClearingRecord" ] }, "boundedParameters": [ "reserve_strategy", "native_repudiation" ], "conformance": [ { "id": "CONF-INV-010", "assertion": "A rail with native repudiation MUST settle without an AURA margin hold; a rail without it MUST carry one.", "assertionType": "property", "fixture": { "given": "One rail with native repudiation and one without", "when": "clearing computes the reserve", "then": "the repudiation rail settles with no AURA margin hold and the other carries one" } } ] }, { "id": "INV-011", "name": "Financial neutrality of the clearinghouse", "status": "normative", "statement": "The clearinghouse MUST hold no commercial position. It MUST NOT rank offers, select beacons, or negotiate terms.", "rationale": "A clearer that takes a side prices its own book into every settlement. Neutrality at the financial layer is the same law as neutral brokerage, carried into the money.", "averts": [ "clearer_self_dealing" ], "manifestedBy": { "operations": [ "getClearing" ], "schemas": [ "ClearingRecord" ] }, "boundedParameters": [], "conformance": [ { "id": "CONF-INV-011", "assertion": "Clearing outputs MUST be a function of risk and rail only, never of a Core commercial interest.", "assertionType": "property", "fixture": { "given": "Two clearings with identical risk and rail inputs", "when": "clearing runs", "then": "the outputs are identical, independent of any Core commercial interest" } } ] }, { "id": "INV-012", "name": "Bilateral risk transparency", "status": "normative", "statement": "Risk MUST be assessed for both parties, and each party MUST see only the assessment that applies to it.", "rationale": "Risk priced in secret is risk a party cannot contest. Showing each side its own assessment makes the price legible without leaking the counterparty’s position.", "averts": [ "secret_risk_pricing" ], "manifestedBy": { "operations": [ "getClearing" ], "schemas": [ "ClearingRecord" ] }, "boundedParameters": [ "risk_model" ], "conformance": [ { "id": "CONF-INV-012", "assertion": "A clearing read MUST expose only the requesting party’s risk score.", "assertionType": "negative", "fixture": { "given": "A clearing record shared by two parties", "when": "one party reads clearing", "then": "only the requesting party's risk score is exposed, and the counterparty score is absent" } } ] }, { "id": "INV-013", "name": "Business rules as hard gates", "status": "normative", "statement": "Binary business rules MUST be enforced as pass or fail gates, separate from continuous risk scoring. A perfect risk score MUST NOT satisfy a failed gate.", "rationale": "If a hard rule can be bought down by a good score, it is no longer a rule. Keeping gates separate from scoring stops a margin adjustment from eroding a compliance requirement.", "averts": [ "gate_erosion" ], "manifestedBy": { "operations": [ "createBusinessRule", "commitSession" ], "schemas": [ "BusinessRuleCreate" ] }, "boundedParameters": [ "business_rule_set" ], "conformance": [ { "id": "CONF-INV-013", "assertion": "A commit MUST be refused when any applicable business rule fails, regardless of risk score.", "assertionType": "negative", "fixture": { "given": "A session where an applicable business rule fails", "when": "commitSession is called", "then": "Core refuses the commit regardless of risk score and creates no transaction" } } ] }, { "id": "INV-014", "name": "Repudiability within a bounded window", "status": "normative", "statement": "A committed transaction MUST be repudiable for a declared, pre-committed window, adjudicated against the recorded intent chain with participant-filtered evidence. A market MUST NOT set no window.", "rationale": "A commitment that cannot be challenged is a commitment a bad actor keeps. A bounded, pre-declared dispute window makes repudiation orderly and finite, which is what lets the other side trust the commit in the first place.", "averts": [ "silent_repudiation", "strategic_non_commitment" ], "manifestedBy": { "operations": [ "fileDispute", "submitEvidence", "resolveDispute", "getDispute" ], "schemas": [ "DisputeFile", "EvidenceSubmission", "DisputeResolution" ] }, "boundedParameters": [ "dispute_window_days" ], "conformance": [ { "id": "CONF-INV-014", "assertion": "A dispute filed within the window MUST be accepted, and the window MUST be declared before commitment.", "assertionType": "positive", "fixture": { "given": "A committed transaction within its declared dispute window", "when": "a dispute is filed", "then": "Core accepts the dispute, and the window was declared before commitment" } } ] }, { "id": "INV-015", "name": "Least-privilege delegated authority", "status": "normative", "statement": "An agent MUST act only within an explicit, signed authority claim that chains to a durable principal in at most three tiers, and a delegation MUST NOT grant more authority than the granter holds.", "rationale": "Authority an agent assumes by membership is authority no principal granted. A claim that names what the agent may do, on which resources, and what it may see, chained to a durable principal and narrowing at every hop, holds the agent inside its mandate and keeps one agent blind to another's work. Core verifies the claim and trusts the action without governing the counterparty.", "averts": [ "privilege_escalation_by_membership", "ambient_authority", "lateral_visibility", "unbounded_delegation" ], "manifestedBy": { "operations": [ "registerAgent", "getDelegationScope", "putDelegationScope", "getPrincipal", "updatePrincipal", "listPrincipalAgents", "listPrincipalTransactions", "getAgent", "commitSession" ], "schemas": [ "DelegationConstraints" ] }, "boundedParameters": [], "conformance": [ { "id": "CONF-INV-015", "assertion": "A request whose authority claim does not cover the action or resource MUST be refused, and a delegation chain deeper than three tiers MUST be rejected.", "assertionType": "negative", "fixture": { "given": "An agent whose claim grants no authority over the target resource", "when": "it calls an operation on that resource", "then": "Core refuses the request and makes no change" } } ] } ] }, "x-aura-authority": { "status": "normative", "description": "How a principal grants and bounds an agent's authority, and how Core verifies a presented authority claim without governing the counterparty's interior. A commitment is valid only within the authority the principal delegated; a hard constraint is an authority boundary (INV-004). Authority is least-privilege and narrows down a signed delegation chain to a durable principal (INV-015).", "boundary": "Core verifies a presented, signed claim against a root of trust. It does not model or govern the counterparty's internal agent hierarchy. Authentication proves the agent holds its key; the claim authorises the specific action and visibility. These are separate steps.", "agentAsMarker": "An agent's key is a marker, an index into a durable record. Trust reads the chain, the principal, and the evidence (INV-008), so an agent may be ephemeral.", "capacity": { "definition": "How an agent declares who it acts for. One value per agent, machine-readable, presented with every claim. The vocabulary aligns with the Janus reference architecture for interoperability.", "values": [ { "id": "agent_for_principal", "definition": "The agent acts on a named principal's authority and inherits the bounds the principal granted." }, { "id": "principal_direct", "definition": "The agent acts on its own authority. A non-human root of authority lives here." }, { "id": "platform_delegated", "definition": "The agent acts on a platform's authority while interacting with principals." } ] }, "claim": { "definition": "What a Scout or Beacon presents so Core can authorise an action. Core verifies it as a relying party.", "parts": [ "capacity", "envelope", "delegationChain" ] }, "dials": { "definition": "What a grant fixes. Least-privilege is the default: an agent with no grant can do and see nothing.", "actions": "The operations the agent may perform.", "resources": "The resources the agent may touch.", "visibility": "What the agent may read, a separate dial, so observe-only and act-without-sight are both expressible.", "bounds": "The signed envelope: amount, category, counterparty, geography, time, escalation threshold." }, "delegationChain": { "definition": "How authority passes from a principal to an agent and onward to the sub-agents it spawns.", "maxTiers": 3, "tiers": [ "principal", "agent", "sub-agents" ], "attenuation": "A delegation grants no more than the granter holds. Authority only narrows down the chain.", "carries": [ "scope", "validity_window", "revocation_path" ], "verification": "Signed end to end and verifiable back to the named principal." }, "consentTiers": [ { "id": "explicit", "definition": "The principal signs the specific action." }, { "id": "policy", "definition": "The action is permitted by a principal-defined policy the agent cites." }, { "id": "delegated", "definition": "The action falls within a standing delegation scope the principal granted." } ], "delegationScope": { "definition": "The bounded authority an agent holds for a principal.", "boundedBy": [ "hard_constraints", "consent_tier", "principal_approval", "market_profile", "resource_scope", "visibility_scope" ], "governs": [ "commitSession", "counterOffer" ] }, "authorityAttestation": { "definition": "Proof presented at commit that the action is within authority.", "requiredAt": "commitSession", "carries": [ "consent_tier", "scope_reference", "principal_signature_or_policy_citation" ] }, "principalApproval": { "definition": "An explicit principal decision captured for an action that exceeds standing authority.", "requiredWhen": "the action exceeds the delegation scope or a market-profile approval threshold" }, "externalCredentialInterop": { "status": "roadmap", "definition": "Delegation may be expressed with an external verifiable-credential format, carried as a signed claim." }, "manifests": [ "INV-004", "INV-015" ] }, "x-aura-state-machines": { "session": { "description": "Session lifecycle. Terminal states are absorbing. The clearing lifecycle is a separate machine and never changes the session status.", "readSemantics": { "status": "explanatory", "description": "Some transitions are materialised lazily. Their condition becomes true on its own (an offer exists, an expiry elapses), and the next read or write that observes the session persists the change. A read can therefore materialise a pending transition today. The protocol event is the condition, not the request that observes it. Making safe-method reads free of side effects is a roadmap item.", "lazyTransitions": [ "T4", "T12" ] }, "initial": "collecting_offers", "states": [ { "name": "collecting_offers", "category": "active" }, { "name": "offers_available", "category": "active" }, { "name": "committed", "category": "active" }, { "name": "fulfilled", "category": "active" }, { "name": "completed", "category": "active", "absorbing": false, "note": "Disputable within the dispute window; otherwise the clearing record advances to cleared." }, { "name": "disputed", "category": "active" }, { "name": "resolved", "category": "terminal" }, { "name": "cancelled", "category": "terminal" }, { "name": "expired", "category": "terminal" }, { "name": "failed", "category": "terminal", "reserved": true } ], "reservedStates": [ "created", "interpreting", "discovering" ], "transitions": [ { "id": "T1", "from": null, "event": "POST /v1/sessions", "to": "collecting_offers", "guard": "Valid intent string; authenticated agent" }, { "id": "T2", "from": [ "collecting_offers" ], "event": "POST /v1/sessions/{session_id}/offers (first offer)", "to": "offers_available", "guard": "Session not expired; Beacon active" }, { "id": "T3", "from": [ "offers_available" ], "event": "POST /v1/sessions/{session_id}/offers (subsequent)", "to": "offers_available", "guard": "Session not expired; Beacon active" }, { "id": "T4", "from": [ "collecting_offers" ], "event": "First valid offer observed", "to": "offers_available", "guard": "Pending offers found", "materialisation": "lazy_allowed", "observedBy": [ "GET /v1/sessions/{session_id}" ] }, { "id": "T5", "from": [ "collecting_offers" ], "event": "POST /v1/sessions/{session_id}/cancel", "to": "cancelled", "guard": "Owner; status NOT IN (committed, completed)" }, { "id": "T6", "from": [ "offers_available" ], "event": "POST /v1/sessions/{session_id}/cancel", "to": "cancelled", "guard": "Owner; status NOT IN (committed, completed)" }, { "id": "T7", "from": [ "offers_available" ], "event": "POST /v1/sessions/{session_id}/commit", "to": "committed", "guard": "Owner; not expired; offer belongs to session; unique idempotency key" }, { "id": "T8", "from": [ "committed" ], "event": "PUT /v1/transactions/{transaction_id}/fulfillment (delivered, payment pending)", "to": "fulfilled", "guard": "Participant; fulfillment_status=delivered; payment_status != charged" }, { "id": "T9", "from": [ "committed" ], "event": "PUT /v1/transactions/{transaction_id}/fulfillment (delivered, payment charged)", "to": "completed", "guard": "Participant; fulfillment_status=delivered; payment_status=charged" }, { "id": "T10", "from": [ "committed" ], "event": "PUT /v1/transactions/{transaction_id}/payment (charged, fulfillment delivered)", "to": "completed", "guard": "Participant; payment_status=charged; fulfillment_status=delivered" }, { "id": "T11", "from": [ "fulfilled" ], "event": "PUT /v1/transactions/{transaction_id}/payment (charged)", "to": "completed", "guard": "Participant; payment_status=charged; fulfillment_status=delivered" }, { "id": "T12", "from": [ "collecting_offers", "offers_available" ], "event": "Session expiry elapsed", "to": "expired", "guard": "expires_at < NOW(); status NOT IN (completed, cancelled, expired)", "materialisation": "lazy_allowed", "observedBy": [ "GET /v1/sessions/{session_id}", "POST /v1/sessions/{session_id}/commit" ] }, { "id": "T13", "from": [ "committed" ], "event": "POST /v1/transactions/{transaction_id}/disputes", "to": "disputed", "guard": "Participant; reason provided; not already disputed" }, { "id": "T14", "from": [ "fulfilled" ], "event": "POST /v1/transactions/{transaction_id}/disputes", "to": "disputed", "guard": "As T13" }, { "id": "T15", "from": [ "completed" ], "event": "POST /v1/transactions/{transaction_id}/disputes", "to": "disputed", "guard": "As T13; within dispute window (completed_at + dispute_window > NOW())" }, { "id": "T16", "from": [ "disputed" ], "event": "POST /v1/disputes/{dispute_id}/resolve (resolution applied)", "to": "resolved", "guard": "Adjudication authority; outcome + remedial actions" }, { "id": "T17", "from": [ "disputed" ], "event": "POST /v1/disputes/{dispute_id}/resolve (withdrawn)", "to": "previous_state", "dynamic": true, "guard": "Initiator withdraws; no counterparty evidence; restores pre-dispute state" } ], "affordances": { "description": "HATEOAS _links available per state. Integrators follow _links to discover valid actions; an absent link means the action is not valid in that state.", "sessionLinksByState": { "collecting_offers": [ "self", "cancel", "offers", "commit" ], "offers_available": [ "self", "offers", "commit", "cancel" ], "committed": [ "self", "transaction" ], "fulfilled": [ "self", "transaction" ], "completed": [ "self", "transaction" ], "disputed": [ "self", "transaction" ], "resolved": [ "self", "transaction" ], "cancelled": [ "self" ], "expired": [ "self" ] }, "sessionLinkNotes": { "collecting_offers": "offers and commit appear only once pending offers exist; self and cancel always." }, "transactionLinks": { "self": "Always", "session": "Always", "fulfillment": "Status NOT IN (disputed, resolved)", "payment": "Status NOT IN (disputed, resolved)", "dispute": "Status IN (committed, fulfilled, completed)", "dispute_details": "Status IN (disputed, resolved)", "evidence": "Status = disputed and requester is a participant", "resolve": "Status = disputed and requester has adjudication authority", "clearing_status": "Clearing record clearing_status IN (risk_assessed, authorized, settling, settled, dispute_term_active, cleared)", "settlement_status": "Clearing record clearing_status IN (settling, settled, cleared)" } } }, "clearing": { "description": "Clearing lifecycle for a committed transaction, a separate machine from the session lifecycle. It never changes the session status. The cleared and failed states are terminal. Advanced by the system-only clearing-status operation.", "initial": "pending", "states": [ { "name": "pending" }, { "name": "risk_assessed" }, { "name": "authorized" }, { "name": "settling" }, { "name": "settled" }, { "name": "dispute_term_active" }, { "name": "disputed" }, { "name": "resolved" }, { "name": "cleared", "category": "terminal" }, { "name": "failed", "category": "terminal" } ], "transitions": { "pending": [ "risk_assessed", "failed" ], "risk_assessed": [ "authorized", "disputed", "failed" ], "authorized": [ "settling", "disputed", "failed" ], "settling": [ "settled", "disputed", "failed" ], "settled": [ "dispute_term_active", "cleared", "disputed" ], "dispute_term_active": [ "cleared", "disputed" ], "disputed": [ "resolved" ], "resolved": [ "cleared", "settled" ], "cleared": [], "failed": [] } } }, "x-aura-signature-profiles": { "status": "normative", "algorithm": "Ed25519", "description": "Every signature in the protocol follows one of these named profiles. Each profile names what is signed, how the payload is assembled, and which operations it applies to.", "profiles": [ { "id": "authenticated_request", "description": "Proof that an authenticated request was issued by the holder of the agent key.", "appliesTo": { "operations": [ "all agent-authenticated operations" ] }, "signedMaterial": [ "method", "path", "timestamp", "nonce", "body_hash" ], "requiredHeaders": [ "X-Agent-Id", "X-Agent-Timestamp", "X-Agent-Nonce", "X-Agent-Signature" ], "optionalSignedMaterial": [ "@authority" ], "optionalHeaders": [ "X-Agent-Host" ], "freshnessWindowSeconds": 300, "notes": { "freshness": "The request timestamp must fall within 300 seconds of Core receipt, either side. A stale timestamp fails verification and surfaces as invalid_signature.", "replay": "Each request carries a unique nonce in X-Agent-Nonce, an opaque token matching ^[A-Za-z0-9._~-]{16,128}$, folded into the signed bytes between timestamp and body_hash. Core records accepted nonces for the freshness window and rejects a reused nonce as replayed_request, so a captured signed request is single-use.", "host": "Additive host binding (GAP-05): a client MAY send X-Agent-Host, an opaque host or host:port matching ^[A-Za-z0-9.-]+(:[0-9]+)?$, and append it as @authority (the last line of the signed bytes). When present Core verifies it equals this Core's canonical host, rejecting host_mismatch, so a request signed for one Core cannot be relayed to another. Absent is backward-compatible (no host binding). Becomes required once more than one market Core serves the same agent identities." } }, { "id": "principal_registration", "description": "Proof of possession of the principal key at registration.", "appliesTo": { "operations": [ "registerPrincipal" ] }, "signedMaterial": [ "canonical_request_body" ], "requiredHeaders": [ "X-Signature" ] }, { "id": "agent_registration", "description": "Proof of possession of the agent key at registration.", "appliesTo": { "operations": [ "registerAgent" ] }, "signedMaterial": [ "canonical_request_body" ], "requiredHeaders": [ "X-Agent-Signature" ] }, { "id": "beacon_offer", "description": "A Beacon's signature binding it to the terms of an offer. The payload is the canonical newline-delimited form the protocol verifies. The offer identifier is assigned by the broker after submission, so it is never part of the signed payload; the signature binds the session, the Beacon, and the offered terms.", "appliesTo": { "operations": [ "submitOffer" ] }, "delimiter": "\n", "encoding": "UTF-8", "payloadFields": [ "session_id", "beacon_id", "product_json", "unit_price", "quantity", "total_price", "currency", "payment_terms_hash" ], "optionalFields": [ "payment_terms_hash" ], "notes": { "product_json": "Product objects serialise as recursively canonical JSON: object keys sorted lexicographically at every depth, array order preserved, so nested product content is bound (a flat object is byte-identical to the earlier top-level-sorted form); plain-string products pass through unchanged.", "numeric_fields": "unit_price, quantity, and total_price serialise via String(value); an absent value serialises as the empty string, keeping the line count stable.", "currency": "Defaults to USD when absent.", "payment_terms_hash": "Base64-encoded SHA-256 of the canonicalised payment terms (accepted_methods sorted, keys ordered). When the offer carries no payment terms the line is omitted entirely, so seven-line signatures from before the payment-terms extension remain valid.", "verification": "Core verifies against the Beacon's registered Ed25519 public key, then counter-signs (see core_offer_countersignature)." }, "example": { "description": "Worked example of the assembled, newline-delimited payload a Beacon signs for these field values.", "fields": { "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "beacon_id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "product_json": "{\"name\":\"Industrial Widget\",\"sku\":\"WDG-001\"}", "unit_price": 85, "quantity": 500, "total_price": 42500, "currency": "USD", "payment_terms_hash": "IjMQNSmbE8lmaQ+1Q713NYiyUKur/bvp3wAKEenFab8=" }, "payload": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b\nc4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f\n{\"name\":\"Industrial Widget\",\"sku\":\"WDG-001\"}\n85\n500\n42500\nUSD\nIjMQNSmbE8lmaQ+1Q713NYiyUKur/bvp3wAKEenFab8=" } }, { "id": "webhook_delivery", "description": "Core's signature on every webhook delivery, so a receiver can verify the event came from Core. The signature binds the event type and timestamp to the body, so a valid signature cannot be replayed onto a different event, and replay of the whole delivery is bounded by the timestamp.", "appliesTo": { "webhooks": "all" }, "delimiter": "\n", "encoding": "UTF-8", "payloadFields": [ "event", "timestamp", "body" ], "requiredHeaders": [ "X-AURA-Event", "X-AURA-Timestamp", "X-AURA-Signature" ], "notes": { "event": "The X-AURA-Event header value.", "timestamp": "The X-AURA-Timestamp header value, ISO 8601.", "body": "The exact JSON body string as sent, byte for byte.", "verification": "Verify against the key at GET /.well-known/core-signing-key. Reject a delivery whose timestamp is outside your replay window." } }, { "id": "core_offer_countersignature", "description": "Core counter-signs an accepted offer at commit: it re-verifies the Beacon signature, then signs CORE-COUNTERSIGN, the canonical offer payload, and the Beacon signature with its own key. The counter-signature is recorded on the transaction and proves Core observed and accepted the signed offer.", "appliesTo": { "operations": [ "commitSession" ] }, "prefix": "CORE-COUNTERSIGN" }, { "id": "interpretation_attestation", "description": "Core's signed binding between the raw intent and its structured interpretation.", "appliesTo": { "operations": [ "createSession", "getAttestation" ] }, "signedMaterial": [ "interpretation", "raw_intent", "session_id", "structured_interpretation", "timestamp" ], "canonicalisation": "Sorted-key JSON of the attestation body; the signature and the signer key id attach after signing." }, { "id": "intent_chain_link", "description": "A signature on one link of the intent chain, chained to its predecessor.", "appliesTo": { "operations": [ "submitChainLink" ] }, "signedMaterial": [ "link", "name", "timestamp", "signed_by", "signer_type", "payload", "previous_link_hash" ], "canonicalisation": "JSON of the link body in the field order above." }, { "id": "assembled_intent_chain", "description": "Core's signature over the assembled chain at commit.", "appliesTo": { "operations": [ "getIntentChain" ] }, "signedMaterial": [ "ordered_link_hashes" ] }, { "id": "key_rotation", "description": "Dual-signed key lifecycle operations: rotation and recovery. The payload binds the entity, both keys, and the client-submitted rotation timestamp, so a signature cannot be replayed for a different entity, a different current key (stale rotation), or a different new key (substitution). The same payload carries two signatures with different signers: the new key proves possession (new_key_proof), and the current key, or the principal's key in recovery, authorizes (old_key_authorization / principal_authorization).", "appliesTo": { "operations": [ "rotateAgentKey", "rotatePrincipalKey", "replaceAgentKey" ] }, "delimiter": "\n", "encoding": "UTF-8", "payloadFields": [ "entity_type", "entity_id", "old_public_key", "new_public_key", "rotation_timestamp" ], "notes": { "entity_type": "'agent' or 'principal'.", "entity_id": "UUID of the rotating entity.", "old_public_key": "The entity's CURRENT live key as Core holds it, base64. Core derives it server-side and never trusts a client-supplied value.", "new_public_key": "The incoming key, base64.", "rotation_timestamp": "ISO 8601 exactly as submitted in the body. Must fall within 300 seconds of Core receipt, either side; outside the window the request fails as rotation_replayed.", "replay": "Core records the committed rotation tuple. An exact duplicate of a committed rotation returns idempotent success; a payload built against a key that is no longer current fails as key_rotation_conflict." } }, { "id": "sandbox_key_mint", "description": "Proof-of-possession for sandbox key minting (obtain_scope). The declared key signs the mint request body, so the caller proves it holds the key the domain will vouch for. Identical construction to registration: the signed material is JSON.stringify of the request object exactly as sent, and the field order is the request order domain, public_key, verification_method.", "appliesTo": { "operations": [ "mintSandboxKey" ] }, "signedMaterial": [ "canonical_request_body" ], "canonicalisation": "JSON.stringify of the request body object, UTF-8 bytes, field order: domain, public_key, verification_method.", "requiredHeaders": [ "X-Signature" ] } ] }, "x-aura-signature-test-vectors": { "status": "normative", "purpose": "Known-good Ed25519 test vectors for every signature profile, so an implementation can prove its canonicalisation is exactly right before signing live requests. The keys are published test material derived from the stated seeds and carry no standing anywhere in the protocol.", "keyDerivation": "The Ed25519 private key is derived from the 32-byte seed (hex) as PKCS8 DER: the 16-byte prefix 302e020100300506032b657004220420 followed by the seed. public_key is the base64 encoding of the raw 32-byte public key, the same format the protocol uses everywhere.", "verification": "signing_payload is the exact byte string to sign, UTF-8 encoded. Signing it with the seed-derived key must produce expected_signature byte for byte (Ed25519 is deterministic). Every vector is re-executed against the implementation in continuous integration, so a published vector cannot drift from the protocol.", "vectors": [ { "profile": "authenticated_request", "name": "post_with_body", "private_key_seed": "1111111111111111111111111111111111111111111111111111111111111111", "public_key": "0EqyMnQrtKs6E2i9RhXk5tAiSrcaAWuvhSCjMsl3hzc=", "method": "POST", "path": "/v1/sessions", "timestamp": "1782000000000", "nonce": "9f8e7d6c5b4a39281706f5e4d3c2b1a0", "body": "{\"intent\":\"I need 200 industrial widgets delivered within three weeks\"}", "body_hash": "nDOL9AewIaRugTuLp/120G5l1owIOjUJDpVsKqYFoK8=", "signing_payload": "POST\n/v1/sessions\n1782000000000\n9f8e7d6c5b4a39281706f5e4d3c2b1a0\nnDOL9AewIaRugTuLp/120G5l1owIOjUJDpVsKqYFoK8=", "expected_signature": "XAIFHQoMwuZm7HBO/CXnaH6WR8tKITpIQ6Xx5ROLX4/SZgEd3Byfn5lfsNnW+Cr023Y0ltXcoioVVvZWzuDVBA==" }, { "profile": "authenticated_request", "name": "get_bodyless_empty_digest", "private_key_seed": "1111111111111111111111111111111111111111111111111111111111111111", "public_key": "0EqyMnQrtKs6E2i9RhXk5tAiSrcaAWuvhSCjMsl3hzc=", "method": "GET", "path": "/v1/sessions/5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "timestamp": "1782000000000", "nonce": "00112233445566778899aabbccddeeff", "body": null, "body_hash": "", "signing_payload": "GET\n/v1/sessions/5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b\n1782000000000\n00112233445566778899aabbccddeeff\n", "expected_signature": "KplY/4w9DnOg/I2OsfgplIxWd34SYdZTpif3CWkoWdUvYhE8/r2jHJm5vn/XZ/K3fJhdl26eqADkK9UNw2hVAw==" }, { "profile": "authenticated_request", "name": "post_with_host", "private_key_seed": "1111111111111111111111111111111111111111111111111111111111111111", "public_key": "0EqyMnQrtKs6E2i9RhXk5tAiSrcaAWuvhSCjMsl3hzc=", "method": "POST", "path": "/v1/sessions", "timestamp": "1782000000000", "nonce": "c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9", "authority": "api.aura-labs.example", "body": "{\"intent\":\"I need 200 industrial widgets delivered within three weeks\"}", "body_hash": "nDOL9AewIaRugTuLp/120G5l1owIOjUJDpVsKqYFoK8=", "signing_payload": "POST\n/v1/sessions\n1782000000000\nc4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9\nnDOL9AewIaRugTuLp/120G5l1owIOjUJDpVsKqYFoK8=\napi.aura-labs.example", "expected_signature": "BN+qjyo/HJhWVUrsWyW5ugIb0Npb6M+SewYTSoAxu0WrNWrNjkPgnPcK7jA/Tu8l1varYmllk0jEXNjJ+EL3Cw==" }, { "profile": "principal_registration", "name": "register_organization", "private_key_seed": "2222222222222222222222222222222222222222222222222222222222222222", "public_key": "oJql9HpnWYAv+VX43C0qFKXJnSO+l/hkEn/5ODRVpPA=", "body": { "principal_type": "organization", "legal_name": "Vector Test GmbH", "jurisdiction": "DE", "public_key": "oJql9HpnWYAv+VX43C0qFKXJnSO+l/hkEn/5ODRVpPA=" }, "canonical_body": "{\"principal_type\":\"organization\",\"legal_name\":\"Vector Test GmbH\",\"jurisdiction\":\"DE\",\"public_key\":\"oJql9HpnWYAv+VX43C0qFKXJnSO+l/hkEn/5ODRVpPA=\"}", "signing_payload": "{\"principal_type\":\"organization\",\"legal_name\":\"Vector Test GmbH\",\"jurisdiction\":\"DE\",\"public_key\":\"oJql9HpnWYAv+VX43C0qFKXJnSO+l/hkEn/5ODRVpPA=\"}", "expected_signature": "sw3foChdrqkdskaQE7aZuFWrz5QFpdSduN+yn70PibpzqRGwDK01Z3+QLg0vaxJ0PXwfdPkbs90zv8xw1/KRBg==" }, { "profile": "agent_registration", "name": "register_scout", "private_key_seed": "1111111111111111111111111111111111111111111111111111111111111111", "public_key": "0EqyMnQrtKs6E2i9RhXk5tAiSrcaAWuvhSCjMsl3hzc=", "body": { "public_key": "0EqyMnQrtKs6E2i9RhXk5tAiSrcaAWuvhSCjMsl3hzc=", "type": "scout", "principal_id": "3f2a9c7e-1b4d-4e8a-9c2f-7a1b0d3e5f60", "capacity": "agent_for_principal" }, "canonical_body": "{\"public_key\":\"0EqyMnQrtKs6E2i9RhXk5tAiSrcaAWuvhSCjMsl3hzc=\",\"type\":\"scout\",\"principal_id\":\"3f2a9c7e-1b4d-4e8a-9c2f-7a1b0d3e5f60\",\"capacity\":\"agent_for_principal\"}", "signing_payload": "{\"public_key\":\"0EqyMnQrtKs6E2i9RhXk5tAiSrcaAWuvhSCjMsl3hzc=\",\"type\":\"scout\",\"principal_id\":\"3f2a9c7e-1b4d-4e8a-9c2f-7a1b0d3e5f60\",\"capacity\":\"agent_for_principal\"}", "expected_signature": "f6ZKRo1rMbFE4E7kvmIWNHrlhkQBxKEZdGdWn5S7cFUCCxF9glu31BhxpyYeetOozNB7KMdYkNHFKl8WBhYUAQ==" }, { "profile": "beacon_offer", "name": "offer_without_payment_terms", "private_key_seed": "3333333333333333333333333333333333333333333333333333333333333333", "public_key": "F8t5+ytBIPKx7GXkGY1uCLKOgT/rAeSkAIObheGAgM4=", "fields": { "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "beacon_id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "product_json": "{\"name\":\"Industrial Widget\",\"sku\":\"WDG-001\"}", "unit_price": 85, "quantity": 500, "total_price": 42500, "currency": "USD" }, "signing_payload": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b\nc4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f\n{\"name\":\"Industrial Widget\",\"sku\":\"WDG-001\"}\n85\n500\n42500\nUSD", "expected_signature": "p4anFua6FbkvWpDC93wUiPtJHlRAvHuxQR+kXdrRYPKPo2o3C9bjaIJq1EX7mARuCDboQka0STpnMI0KmJJbBg==" }, { "profile": "beacon_offer", "name": "offer_with_payment_terms", "private_key_seed": "3333333333333333333333333333333333333333333333333333333333333333", "public_key": "F8t5+ytBIPKx7GXkGY1uCLKOgT/rAeSkAIObheGAgM4=", "fields": { "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "beacon_id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "product_json": "{\"name\":\"Industrial Widget\",\"sku\":\"WDG-001\"}", "unit_price": 85, "quantity": 500, "total_price": 42500, "currency": "USD", "payment_terms_hash": "IjMQNSmbE8lmaQ+1Q713NYiyUKur/bvp3wAKEenFab8=" }, "signing_payload": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b\nc4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f\n{\"name\":\"Industrial Widget\",\"sku\":\"WDG-001\"}\n85\n500\n42500\nUSD\nIjMQNSmbE8lmaQ+1Q713NYiyUKur/bvp3wAKEenFab8=", "expected_signature": "XrqLmPv9JH8XYDyVFdaSSR6cMiSbQ6EffFTkZ5wOIp6gN1PrEVddec//TBhxhEbm1TDklpD9fSjr+GAyk9cfAg==" }, { "profile": "beacon_offer", "name": "offer_with_nested_product", "private_key_seed": "3333333333333333333333333333333333333333333333333333333333333333", "public_key": "F8t5+ytBIPKx7GXkGY1uCLKOgT/rAeSkAIObheGAgM4=", "fields": { "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "beacon_id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "product_json": "{\"name\":\"Industrial Widget\",\"sku\":\"WDG-001\",\"spec\":{\"dims\":{\"unit\":\"mm\",\"w\":40},\"grade\":\"A\",\"material\":\"steel\"}}", "unit_price": 85, "quantity": 500, "total_price": 42500, "currency": "USD" }, "signing_payload": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b\nc4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f\n{\"name\":\"Industrial Widget\",\"sku\":\"WDG-001\",\"spec\":{\"dims\":{\"unit\":\"mm\",\"w\":40},\"grade\":\"A\",\"material\":\"steel\"}}\n85\n500\n42500\nUSD", "expected_signature": "qFkWDopb7pHNG9R3ifcAMqvZcsKYhHkvXfhe9BqyBF+i81NkQ2zgJwCiZiDUwNpnxI2TVdJGytAHzyinH/nKCg==" }, { "profile": "core_offer_countersignature", "name": "countersign_offer_with_payment_terms", "private_key_seed": "4444444444444444444444444444444444444444444444444444444444444444", "public_key": "11l5O7wTooGagnx2rbb7qKSa7gB/SfLQmS2ZuCWtLEg=", "offer_signing_payload": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b\nc4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f\n{\"name\":\"Industrial Widget\",\"sku\":\"WDG-001\"}\n85\n500\n42500\nUSD\nIjMQNSmbE8lmaQ+1Q713NYiyUKur/bvp3wAKEenFab8=", "beacon_signature": "XrqLmPv9JH8XYDyVFdaSSR6cMiSbQ6EffFTkZ5wOIp6gN1PrEVddec//TBhxhEbm1TDklpD9fSjr+GAyk9cfAg==", "signing_payload": "CORE-COUNTERSIGN\n5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b\nc4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f\n{\"name\":\"Industrial Widget\",\"sku\":\"WDG-001\"}\n85\n500\n42500\nUSD\nIjMQNSmbE8lmaQ+1Q713NYiyUKur/bvp3wAKEenFab8=\nXrqLmPv9JH8XYDyVFdaSSR6cMiSbQ6EffFTkZ5wOIp6gN1PrEVddec//TBhxhEbm1TDklpD9fSjr+GAyk9cfAg==", "expected_signature": "PfbdUgo7rsI1EZNHyp3ERxbrveDF2xWvBtJPuYiY24WgaBb62v2JcF3K6NCNiB7A/2VveqQPlOoKjVqP4mcKDA==" }, { "profile": "interpretation_attestation", "name": "attestation_sorted_key_json", "private_key_seed": "4444444444444444444444444444444444444444444444444444444444444444", "public_key": "11l5O7wTooGagnx2rbb7qKSa7gB/SfLQmS2ZuCWtLEg=", "attestation_body": { "interpretation": { "model_id": "aura-intent-regex", "model_version": "2026-04", "confidence": 0.94, "interpretation_method": "regex", "fallback_used": false }, "raw_intent": "I need 200 industrial widgets delivered within three weeks", "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "structured_interpretation": { "category": "industrial_chemicals", "quantity": 200 }, "timestamp": "2026-07-02T12:00:00.000Z" }, "signing_payload": "{\"interpretation\":{},\"raw_intent\":\"I need 200 industrial widgets delivered within three weeks\",\"session_id\":\"5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b\",\"structured_interpretation\":{},\"timestamp\":\"2026-07-02T12:00:00.000Z\"}", "expected_signature": "dvO3F8x6xlVwIj/CSiE6pXf2rRZBLjW2zH0/ydzHvbBBpRqSjXFVvpkBausOpLJzZvwVOwy3Lug0Fon+Djy8AA==" }, { "profile": "intent_chain_link", "name": "core_link_l2", "private_key_seed": "4444444444444444444444444444444444444444444444444444444444444444", "public_key": "11l5O7wTooGagnx2rbb7qKSa7gB/SfLQmS2ZuCWtLEg=", "link_body": { "link": "L2", "name": "interpretation", "timestamp": "2026-07-02T12:00:00.000Z", "signed_by": "core", "signer_type": "core", "payload": { "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b" }, "previous_link_hash": null }, "signing_payload": "{\"link\":\"L2\",\"name\":\"interpretation\",\"timestamp\":\"2026-07-02T12:00:00.000Z\",\"signed_by\":\"core\",\"signer_type\":\"core\",\"payload\":{\"session_id\":\"5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b\"},\"previous_link_hash\":null}", "expected_signature": "jQCFSaaR41BXw1ZYagpT4WW4sb3XnDSyVgJyJ6Y2+nhe7FEf/WPrS+trf4pGwoQtAZT34+D25yb76QRos5BbCg==" }, { "profile": "assembled_intent_chain", "name": "two_link_chain", "private_key_seed": "4444444444444444444444444444444444444444444444444444444444444444", "public_key": "11l5O7wTooGagnx2rbb7qKSa7gB/SfLQmS2ZuCWtLEg=", "links": [ { "link": "L1", "name": "origination", "created_at": "2026-07-02T12:00:00.000Z", "signed_by": "a7b8c9d0-1e2f-4a3b-8c4d-5e6f7a8b9c0d", "signer_type": "scout_agent", "payload": { "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b" }, "signature": "dGVzdA==", "previous_link_hash": null }, { "link": "L2", "name": "interpretation", "created_at": "2026-07-02T12:00:01.000Z", "signed_by": "core", "signer_type": "core", "payload": { "confidence": 0.94 }, "signature": "dGVzdDI=", "previous_link_hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000" } ], "chain_hash": "sha256:8a5fd44ea403d9f4904881127508bfdbc778774cc6e6817f5c1212a8428509a0", "signing_payload": "sha256:8a5fd44ea403d9f4904881127508bfdbc778774cc6e6817f5c1212a8428509a0", "expected_signature": "NgF0WzwAFt18vT7ojryvWN5bgq10cJli2MOnLMixCwhpBq1dyiUVoVvxZLeUW8ziGNbMZhvgG8ZxCvyWhE2bAA==" }, { "profile": "webhook_delivery", "name": "transaction_committed_delivery", "private_key_seed": "4444444444444444444444444444444444444444444444444444444444444444", "public_key": "11l5O7wTooGagnx2rbb7qKSa7gB/SfLQmS2ZuCWtLEg=", "event": "transaction.committed", "timestamp": "2026-07-02T12:00:00.000Z", "body": "{\"transaction_id\":\"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f\",\"idempotency_key\":\"4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f70\",\"session_id\":\"5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b\",\"offer_id\":\"9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d\",\"final_terms\":{\"product\":\"Industrial Widget\",\"total_price\":42500,\"currency\":\"USD\",\"delivery_date\":\"2026-03-10\"}}", "signing_payload": "transaction.committed\n2026-07-02T12:00:00.000Z\n{\"transaction_id\":\"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f\",\"idempotency_key\":\"4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f70\",\"session_id\":\"5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b\",\"offer_id\":\"9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d\",\"final_terms\":{\"product\":\"Industrial Widget\",\"total_price\":42500,\"currency\":\"USD\",\"delivery_date\":\"2026-03-10\"}}", "expected_signature": "XU0Tr18CtY6RNue2NCAF+/sikSSZGHSxpHoV9g/8Lwln3/xITma2BEgwbl1PbVQqqwPlpKmH2gOty3oeTplMBw==" }, { "profile": "key_rotation", "name": "rotate_agent_key_new_key_proof", "role": "new_key_proof", "private_key_seed": "5555555555555555555555555555555555555555555555555555555555555555", "public_key": "xoImN8fTEOxXYnvgC6JZ0lN0n0qvZERwz/vlOjX3MkI=", "entity_type": "agent", "entity_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "old_public_key": "0EqyMnQrtKs6E2i9RhXk5tAiSrcaAWuvhSCjMsl3hzc=", "new_public_key": "xoImN8fTEOxXYnvgC6JZ0lN0n0qvZERwz/vlOjX3MkI=", "rotation_timestamp": "2026-07-02T12:00:00.000Z", "signing_payload": "agent\ne1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b\n0EqyMnQrtKs6E2i9RhXk5tAiSrcaAWuvhSCjMsl3hzc=\nxoImN8fTEOxXYnvgC6JZ0lN0n0qvZERwz/vlOjX3MkI=\n2026-07-02T12:00:00.000Z", "expected_signature": "dXkM2mTtOW3lhJKMOpMNF3OvlsmC86StP0uMr8HaFeTaWl/vgtXn8zzwlIJ/73gRlhbqBbLeGW6FLP6SYRX0Dw==" }, { "profile": "key_rotation", "name": "rotate_agent_key_old_key_authorization", "role": "old_key_authorization", "private_key_seed": "1111111111111111111111111111111111111111111111111111111111111111", "public_key": "0EqyMnQrtKs6E2i9RhXk5tAiSrcaAWuvhSCjMsl3hzc=", "entity_type": "agent", "entity_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "old_public_key": "0EqyMnQrtKs6E2i9RhXk5tAiSrcaAWuvhSCjMsl3hzc=", "new_public_key": "xoImN8fTEOxXYnvgC6JZ0lN0n0qvZERwz/vlOjX3MkI=", "rotation_timestamp": "2026-07-02T12:00:00.000Z", "signing_payload": "agent\ne1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b\n0EqyMnQrtKs6E2i9RhXk5tAiSrcaAWuvhSCjMsl3hzc=\nxoImN8fTEOxXYnvgC6JZ0lN0n0qvZERwz/vlOjX3MkI=\n2026-07-02T12:00:00.000Z", "expected_signature": "TwuvQD2mbRmt3iJx41Y1Rtr8kKARk+Gh2VndSz2ISO9vISaEuusVvCaglJi1Mh6QkBpWz4idDCXGuAHrPcsVAA==" }, { "profile": "sandbox_key_mint", "name": "mint_dns_txt", "private_key_seed": "6666666666666666666666666666666666666666666666666666666666666666", "public_key": "NLTZBDFWy23PC+sKKUm3VZyUDSvLbb6MU6mzAnjjp0Y=", "body": { "domain": "agents.example.com", "public_key": "NLTZBDFWy23PC+sKKUm3VZyUDSvLbb6MU6mzAnjjp0Y=", "verification_method": "dns_txt" }, "canonical_body": "{\"domain\":\"agents.example.com\",\"public_key\":\"NLTZBDFWy23PC+sKKUm3VZyUDSvLbb6MU6mzAnjjp0Y=\",\"verification_method\":\"dns_txt\"}", "signing_payload": "{\"domain\":\"agents.example.com\",\"public_key\":\"NLTZBDFWy23PC+sKKUm3VZyUDSvLbb6MU6mzAnjjp0Y=\",\"verification_method\":\"dns_txt\"}", "expected_signature": "SpnD2impoE/h9gAmBPX8tkxsw/olk7LYfeGH3THDTd4x1ADhwnBkO0b8k68SMcYkIun+7FdDhvbFQltNgQL7Cg==" } ] }, "x-aura-intent-chain": { "description": "Intent-to-commitment chain of custody: up to seven signed links tracing a transaction from the human signal to the outcome. Assembled by Core at commit; immutable. Beacons receive a redacted view.", "links": [ { "link": "L1", "name": "principal_signal", "signer": "scout_agent", "proves": "Scout received the principal's input and forwarded it faithfully.", "source": "Scout SDK at session creation" }, { "link": "L2", "name": "interpretation", "signer": "core", "proves": "Core bound raw input to structured output via a specific model.", "source": "Interpretation attestation" }, { "link": "L3", "name": "principal_review", "signer": "scout_agent", "proves": "Principal saw the interpretation and did not object, or was declared not consulted.", "source": "Scout SDK after interpretation" }, { "link": "L4", "name": "offer_selection", "signer": "scout_agent", "proves": "The agent selected this offer from the available set.", "source": "Scout SDK at offer selection" }, { "link": "L5", "name": "principal_consent", "signer": "scout_agent_or_principal", "proves": "Principal consented: explicit signature, cited policy, or cited delegation scope.", "source": "Authority attestation" }, { "link": "L6", "name": "commitment", "signer": "core", "proves": "Core executed the atomic commit; counter-signature confirms authority verified and recorded.", "source": "Core at commit" }, { "link": "L7", "name": "outcome", "signer": "core", "proves": "Terminal state: fulfillment/payment status or dispute resolution outcome.", "source": "Core at completion or dispute resolution" } ], "beaconRedactedView": [ "L2", "L4", "L6", "L7" ] }, "x-aura-key-lifecycle": { "status": "normative", "description": "Key lifecycle for durable identities. A key is an instrument of an identity, never the identity: rotation and recovery change the key and its fingerprint while the identity, its bindings, its reputation, and its history persist unchanged.", "rotation": { "profile": "key_rotation", "operations": [ "rotateAgentKey", "rotatePrincipalKey" ], "authorization": "Dual-signed: the new key proves possession, the current key authorizes. old_key_authorization is required for every rotation, including agent self-rotation: the current key must sign the canonical payload explicitly. The request-level signature never authorizes a rotation, because it does not bind the request body (GAP-01).", "freshnessWindowSeconds": 300, "replay": "Core records the committed rotation tuple. An exact duplicate of a committed rotation returns idempotent success; any other reuse fails as rotation_replayed; a payload built against a superseded key fails as key_rotation_conflict.", "atomicity": "The retired key stops authorizing at commit. At no point do two keys authorize for the same identity." }, "recovery": { "agent": { "status": "normative", "operation": "replaceAgentKey", "authorization": "The principal's key authorizes over the same canonical payload; the compromised agent key signs nothing." }, "principal": { "status": "roadmap", "reason": "external_credential_reverification_required", "currentBehaviour": { "operation": "recoverPrincipalKey", "error": "recovery_not_available", "http": 403 } } }, "keyHistory": { "verificationOnly": true, "validity": "A rotated-out key verifies artifacts whose Core-recorded signing time falls at or after the key became active and before it rotated out. Historical verification anchors on Core-recorded time or a time bound into a Core counter-signature, never on a timestamp carried inside the artifact alone.", "uniqueness": "A key used anywhere, ever, can never be registered again by any identity.", "authorization": "Nothing in key history authorizes a new action." }, "discovery": "The versioned discovery root advertises features.key_rotation, features.agent_key_recovery, and features.principal_key_recovery." }, "x-aura-agent-admission": { "status": "normative", "description": "The ordered lifecycle through which an autonomous agent earns production access. Each phase names its purpose, the operations that execute it, the evidence that proves it was completed, and the failure modes that block it; evidence is load-bearing because a phase without evidence is a claim, and claims are verified, never assumed. The phases are ordered because each consumes the previous phase's evidence: scope is granted to a proven key, a sandbox is provisioned to a scoped key, flows execute inside a provisioned sandbox, conformance runs over flow transcripts, certification signs conformance results, and promotion presents certification. No phase is skippable. Phase status is honest: implemented phases run today against this contract; a roadmap phase lists any not-yet-served operations in roadmapOperations, and may list already-served operations in operations when only the phase's orchestration is unshipped. failureModes on implemented phases are the exact catalogued error codes the condition surfaces as; failureModes on roadmap phases name the blocking condition, and their wire-level codes enter x-aura-errors as the operations ship, under the existing two-way harvest gate.", "phases": [ { "id": "discover", "status": "implemented", "purpose": "The agent finds the protocol and its machine-readable surfaces.", "entryPoints": [ "https://aura-labs.ai/llms.txt", "https://aura-labs.ai/openapi.json", "https://aura-labs.ai/api/mcp" ], "evidence": [] }, { "id": "learn", "status": "implemented", "purpose": "The agent reads the law it will be held to.", "references": { "extensions": [ "x-aura-invariants", "x-aura-authority", "x-aura-signature-profiles", "x-aura-signature-test-vectors", "x-aura-errors", "x-aura-key-lifecycle" ] }, "evidence": [] }, { "id": "request_identity", "status": "implemented", "purpose": "The agent requests a protocol identity: a principal anchor and an agent record bound to an Ed25519 key.", "operations": [ "registerPrincipal", "registerAgent", "registerBeacon" ], "notes": "Keys bind through registerPrincipal and registerAgent (a Beacon operator registers its agent with type beacon). registerBeacon creates the market-facing Beacon listing and carries no key.", "evidence": [ "ed25519_public_key" ], "failureModes": [ "invalid_key", "missing_signature", "invalid_signature", "key_revoked" ] }, { "id": "prove_key_control", "status": "implemented", "purpose": "The agent proves possession of the private key on every request.", "mechanism": "Every request is signed by the registered key under the authenticated_request signature profile; the published signature test vectors let an agent prove its canonicalisation byte-exactly before signing live requests. Request timestamps must fall within the profile freshness window; a stale timestamp fails as invalid_signature.", "roadmapMechanism": { "status": "roadmap", "mechanism": "RFC 9421 HTTP Message Signatures over the same Ed25519 keys (Web Bot Auth profile)", "keyDiscovery": [ "domain_hosted_key_document", "core_hosted_directory" ] }, "evidence": [ "verified_request_signature" ], "failureModes": [ "missing_auth_headers", "unknown_agent", "invalid_signature" ] }, { "id": "obtain_scope", "status": "implemented", "purpose": "The agent mints a scoped, prefixed sandbox key. The key is the tenant anchor for one namespace; the verified domain proved at minting is the identity anchor every quota counts against.", "evidence": [ "scoped_key_grant" ], "failureModes": [ "invalid_domain", "mint_proof_invalid", "key_already_used", "sandbox_identity_not_verified", "rate_limit_exceeded" ], "operations": [ "mintSandboxKey" ], "mechanism": "Two proofs over one mint request. Possession: the X-Signature header carries the Ed25519 signature over the exact JSON body by the declared key. Domain control: publish the key where only the domain's controller can, either TXT _aura-agent-key. = aura-key= (dns_txt) or https:///.well-known/aura-agent-key returning JSON with a matching public_key (well_known). One active key per domain; re-mint revokes the prior key and is the compromise-recovery path. The grant is bearer, shown once, stored hashed, and not consumable until provisioning ships." }, { "id": "provision_sandbox", "status": "implemented", "purpose": "Core provisions an isolated, seeded, deterministic market for the key: rows in a standing deployment, never new infrastructure, so provisioning is a single idempotent call.", "operations": [ "provisionSandbox", "resetSandbox" ], "evidence": [ "sandbox_manifest" ], "failureModes": [ "sandbox_key_invalid", "sandbox_quota_exceeded", "sandbox_namespace_conflict", "sandbox_contract_version_skew", "sandbox_provisioning_unavailable", "sandbox_run_active" ] }, { "id": "execute_validation_flows", "status": "roadmap", "purpose": "The agent exercises the golden paths and the failure paths for its role against seeded deterministic counterparties. The operations are served today; running them as validation flows requires a provisioned sandbox.", "operations": [ "createSession", "submitOffer", "counterOffer", "commitSession", "getClearing", "fileDispute", "getIntentChain" ], "evidence": [ "flow_transcripts" ], "failureModes": [ "flow_incomplete", "invariant_violation" ] }, { "id": "run_conformance", "status": "roadmap", "purpose": "The harness executes the role profile's assertions against the flow transcripts.", "references": { "extensions": [ "x-aura-conformance" ] }, "roadmapOperations": [ "runConformance" ], "evidence": [ "assertion_results" ], "failureModes": [ "assertion_failed" ] }, { "id": "receive_certification", "status": "roadmap", "purpose": "Core signs the assertion results as presentable, expiring evidence.", "roadmapOperations": [ "getCertification" ], "evidence": [ "certification_attestation" ] }, { "id": "request_production_promotion", "status": "roadmap", "purpose": "The agent presents certification and requests promotion, gated on the entity verification level the target tier requires.", "roadmapOperations": [ "requestPromotion" ], "evidence": [ "certification_attestation", "entity_verification" ], "failureModes": [ "certification_expired", "verification_insufficient" ] } ], "sandbox": { "status": "implemented", "description": "A provisioned sandbox is a market in miniature on standing infrastructure: seeded principals at declared verification levels, deterministic Scout and Beacon counterparties, a declared market profile, and simulated settlement rails covering both reserve branches. Isolation is a logical namespace per sandbox key; a namespace is rows, never infrastructure.", "provisioning": { "operationId": "provisionSandbox", "idempotent": true, "description": "Re-provisioning with the same key returns the existing manifest as success, never a conflict: an agent retrying a timeout lands on the same state." }, "reset": { "operationId": "resetSandbox", "runBoundary": true, "description": "Destroy-and-reseed at namespace grain. Every conformance run opens with a reset and receives the run identity that transcripts, assertion results, and quotas key on. Evidence is stored outside the namespace and survives reset.", "failureModes": [ "sandbox_run_active", "sandbox_quota_exceeded", "sandbox_namespace_conflict", "sandbox_key_invalid" ] }, "manifestSchema": "#/components/schemas/SandboxManifest", "transcriptSchema": "#/components/schemas/ConformanceTranscript", "semanticExceptions": [ { "rule": "production_key_reuse_forbidden", "sandbox_exception": "seeded_house_counterparty_keys_reused_after_namespace_reset", "applies_to": "house_counterparties_only" } ], "quotas": { "quotasAreDefaults": true, "note": "Launch defaults, returned per namespace as manifest facts. The namespace count is quota policy, never protocol law: the operator may grant more active namespaces without protocol change.", "defaults": { "active_namespaces_per_identity": { "value": 1, "operator_grantable": true }, "active_sandbox_keys_per_domain": { "value": 1, "rule": "Re-minting under the same domain revokes the prior key in the same transaction; compromise recovery is re-mint under the re-proven domain." }, "provisions_per_identity_per_day": 3, "conformance_runs_per_key_per_day": { "value": 10, "counting": "each run opens with a reset; the opening reset is included, never double-counted" }, "requests_per_namespace_per_minute": { "value": 120, "keying": "per namespace, after signature verification" }, "namespace_idle_ttl_hours": 72, "global_namespace_cap": { "value": 500, "on_exceeded": "backpressure with HTTP 429" }, "transcript_retention_days": { "value": 90, "or": "until superseded by a newer certified run" }, "outbound_webhook_dispatch": { "status": "reserved", "rule": "Per-namespace dispatch cap; the endpoint host allowlists to the identity's verified domain. Implemented when sandbox event dispatch ships." } }, "tiers": { "keying": "Tier follows the identity's verification level: T0 self_declared, T1 domain_verified, T2 entity_verified, T3 kyc_verified with a passing certification. The tier is always derived from the verified key row, never from a request field.", "activation": "T1 is enforced today: minting requires domain proof, so every live key holds at least T1, and T0 is defined but unreachable until a keyless tier exists. T2 and T3 are declared and inert until the verification-level vocabulary is enumerated in this contract; until then every key resolves to T1. The defaults block above is the T1 row, unchanged.", "T0": { "provisions_per_identity_per_day": 1, "active_namespaces_per_identity": 1, "namespace_idle_ttl_hours": 2, "namespace_idle_ttl_hard_max_hours": 6, "requests_per_namespace_per_minute": 30, "conformance_runs_per_key_per_day": 2 }, "T1": { "provisions_per_identity_per_day": 3, "active_namespaces_per_identity": 1, "namespace_idle_ttl_hours": 72, "requests_per_namespace_per_minute": 120, "conformance_runs_per_key_per_day": 10 }, "T2": { "provisions_per_identity_per_day": 10, "active_namespaces_per_identity": 3, "namespace_idle_ttl_hours": 168, "requests_per_namespace_per_minute": 300, "conformance_runs_per_key_per_day": 50 }, "T3": { "provisions_per_identity_per_day": 25, "active_namespaces_per_identity": 10, "namespace_idle_ttl_hours": 336, "requests_per_namespace_per_minute": 600, "conformance_runs_per_key_per_day": 200 } } }, "latencyBudgets": { "provision_p50_ms": 300, "provision_p99_ms": 1000 }, "determinism": { "level": "transcript", "normalized": [ "uuids", "timestamps" ], "statement": "Same agent behaviour produces the same canonical transcript. Signatures and hash chains bind to the raw transcript; comparison uses the normalized transcript derived through a retained first-occurrence substitution map. Nothing signs a normalized transcript." }, "scenarioVersioning": { "format": "scenario_version = /. The semver versions the published scenario family and increments per family revision; a conformance run binds to exactly one scenario_version.", "disclosure": { "publicScenarioFamily": "Stable, documented, versioned in the contract: what kinds of flows and failures a family contains.", "manifestScenarioFacts": "Visible to the applicant for that run: concrete dial values, counterparty keys, declared tiers, the determinism statement.", "holdoutVariationRules": "Bounded and attested, never fully published: seed-varied variants within the declared family defeat memorised answers." }, "families": [ "scout-admission", "beacon-admission" ] } }, "certification": { "status": "roadmap", "attests": "Conformance to a versioned scenario family at a named contract version, never general capability. The attestation names the family and scenario version the run belonged to without revealing the variant generator.", "evidence": "Assertion results signed by Core, carrying the agent identity, the role profile and its version, the contract version certified against, and an expiry. Certification ages out rather than lying forever.", "verification": "One Ed25519 signature check against the published signing key." } }, "x-aura-transcript-events": { "status": "normative", "description": "The frozen vocabulary of events a sandbox run transcript records. The names and their payload fields are frozen here; this is the single source the run recorder and the transcript event type values draw from. coverage declares which events the recorder emits in its first capture increment (required) and which names are frozen but not yet emitted by the recorder (reserved), so the vocabulary is committed independently of implementation coverage. coverage is scoped to the transcript recorder and is distinct from delivery on the webhook channel: an event may be reserved here while already delivered as a webhook.", "coverageVocabulary": [ "required", "reserved" ], "eventEnvelope": { "description": "Every transcript event carries these fields. seq is the monotonic position within the run; type is one of the names in events; at is the event time. Event-specific identity and domain fields are listed per event under payload. The recorder emits raw events carrying real ids and timestamps, and the normalized layer substitutes UUIDs and timestamps through the retained map.", "fields": [ "seq", "type", "at" ] }, "events": { "principal.registered": { "coverage": "required", "summary": "A principal was registered, the party on whose behalf an agent acts.", "payload": [ "principal_id", "verification_level", "at" ] }, "agent.registered": { "coverage": "required", "summary": "An agent was registered and bound to a principal.", "payload": [ "agent_id", "principal_id", "at" ] }, "sandbox_key.minted": { "coverage": "required", "summary": "A sandbox key was minted for the agent, scoped to the run's tier.", "payload": [ "key_fingerprint", "tier", "at" ] }, "sandbox.provisioned": { "coverage": "required", "summary": "A sandbox namespace was provisioned and seeded from the minted key.", "payload": [ "namespace_id", "tier", "at" ] }, "sandbox.reset": { "coverage": "required", "summary": "The namespace was reset, opening a new run and issuing its run boundary.", "payload": [ "namespace_id", "run_id", "at" ] }, "session.created": { "coverage": "required", "summary": "A shopping session was created.", "payload": [ "session_id", "at" ] }, "session.matched": { "coverage": "required", "summary": "The session matched to counterparties able to make offers.", "payload": [ "session_id", "at" ] }, "offer.submitted": { "coverage": "required", "summary": "A beacon submitted an offer into the session.", "payload": [ "session_id", "offer_id", "at" ] }, "offer.presented": { "coverage": "required", "summary": "An offer was presented to the scout for evaluation.", "payload": [ "session_id", "offer_id", "at" ] }, "commit.requested": { "coverage": "required", "summary": "The scout requested commitment to an offer.", "payload": [ "session_id", "offer_id", "at" ] }, "commit.accepted": { "coverage": "required", "summary": "The commitment was accepted and bound.", "payload": [ "session_id", "offer_id", "transaction_id", "at" ] }, "transaction.created": { "coverage": "required", "summary": "The transaction exists as the result of the accepted commitment.", "payload": [ "transaction_id", "session_id", "offer_id", "at" ] }, "intent_chain.link_added": { "coverage": "required", "summary": "A link was added to the transaction's intent chain.", "payload": [ "transaction_id", "link", "at" ] }, "offer.expired": { "coverage": "reserved", "summary": "RESERVED (not yet emitted): an offer passed its expiry before a commitment.", "payload": [ "session_id", "offer_id", "at" ] }, "offer.rejected": { "coverage": "reserved", "summary": "RESERVED (not yet emitted): an offer was rejected.", "payload": [ "session_id", "offer_id", "at" ] }, "commit.rejected": { "coverage": "reserved", "summary": "RESERVED (not yet emitted): a commitment request was rejected.", "payload": [ "session_id", "offer_id", "at" ] }, "clearing.started": { "coverage": "reserved", "summary": "RESERVED (not yet emitted): clearing began for a transaction.", "payload": [ "transaction_id", "at" ] }, "clearing.advanced": { "coverage": "reserved", "summary": "RESERVED (not yet emitted): clearing advanced a stage.", "payload": [ "transaction_id", "stage", "at" ] }, "payment.updated": { "coverage": "reserved", "summary": "RESERVED (not yet emitted): the payment state of a transaction changed. The same lifecycle event is delivered on the webhook channel; the transcript records it independently.", "payload": [ "transaction_id", "at" ] }, "fulfillment.updated": { "coverage": "reserved", "summary": "RESERVED (not yet emitted): the fulfillment state of a transaction changed. The same lifecycle event is delivered on the webhook channel; the transcript records it independently.", "payload": [ "transaction_id", "at" ] }, "dispute.filed": { "coverage": "reserved", "summary": "RESERVED (not yet emitted): a dispute was filed against a transaction.", "payload": [ "transaction_id", "dispute_id", "at" ] }, "dispute.evidence_submitted": { "coverage": "reserved", "summary": "RESERVED (not yet emitted): evidence was submitted for a dispute.", "payload": [ "transaction_id", "dispute_id", "at" ] }, "dispute.resolved": { "coverage": "reserved", "summary": "RESERVED (not yet emitted): a dispute was resolved.", "payload": [ "transaction_id", "dispute_id", "at" ] } } }, "x-aura-market-model": { "status": "explanatory", "normative": false, "description": "Why the protocol has this shape. The market model explains; the invariants govern.", "ontologicalClaim": "Software agents are not subject to bounded rationality. A market whose participants can follow the rules can be designed to produce the outcomes economic theory predicts for rational agents, as a structural property rather than a tendency.", "marketNotShop": "AURA models a market, not a shop: intent, discovery, negotiation, commitment, settlement. Agents negotiate; they do not browse.", "foundations": [ { "theory": "Repeated-game cooperation", "author": "Axelrod", "claim": "Cooperation emerges among self-interested agents when interactions repeat, behaviour is observable, and retaliation is cheap." }, { "theory": "The market for lemons", "author": "Akerlof", "claim": "Asymmetric quality information drives good sellers out unless credible quality signals exist." }, { "theory": "Mechanism design", "author": "Hurwicz, Myerson, Maskin", "claim": "Rules can be designed so that rational, self-interested behaviour produces desirable outcomes." } ], "microstructureProblems": [ { "problem": "adverse_selection", "resolvedBy": [ "INV-001", "INV-007" ] }, { "problem": "information_probing", "resolvedBy": [ "INV-002", "INV-003", "INV-004" ] }, { "problem": "strategic_non_commitment", "resolvedBy": [ "INV-005", "INV-006", "INV-014" ] } ], "algorithmicPriceDynamics": [ { "failureMode": "collusive_equilibrium", "resolution": "The neutral broker removes the bilateral channel two pricing algorithms would converge through.", "resolvedBy": [ "INV-001" ] }, { "failureMode": "oscillation", "resolution": "Offer expiry makes negotiation discrete, ending the continuous feedback loop.", "resolvedBy": [ "INV-005" ] }, { "failureMode": "asymmetric_exploitation", "resolution": "Neither algorithm observes the other's response function; Core mediates.", "resolvedBy": [ "INV-001" ] } ], "fixAnalogy": "Like FIX, the protocol standardises the negotiation layer and leaves settlement and clearing to specialised systems. Invariant mechanics carry market-specific parameters set per market.", "computableMarketConditions": [ "Participants are rational within their delegated scope.", "The rules are enforced structurally, not behaviourally.", "A neutral intermediary holds canonical state and breaks bilateral dynamics." ] }, "x-aura-market-parameters": { "status": "normative-interface", "description": "The dials a market sets within the law. Each parameter is bounded by an invariant; a market chooses a value within that bound. These map to the market-profile primitive.", "parameters": [ { "id": "disclosure_schedule", "definition": "Per-field, per-phase disclosure tiers.", "boundedBy": [ "INV-002", "INV-003" ] }, { "id": "offer_validity_window", "definition": "How long an offer remains committable.", "boundedBy": [ "INV-005" ] }, { "id": "qualification_threshold", "definition": "Minimum reputation to participate.", "boundedBy": [ "INV-007" ] }, { "id": "dispute_window_days", "definition": "How long a committed transaction is repudiable. A market may not set zero.", "boundedBy": [ "INV-014" ] }, { "id": "settlement_method", "definition": "The rail used to settle.", "boundedBy": [ "INV-009" ] }, { "id": "reserve_strategy", "definition": "How the reserve margin is sized.", "boundedBy": [ "INV-010" ] }, { "id": "risk_model", "definition": "How bilateral risk is scored.", "boundedBy": [ "INV-012" ] }, { "id": "business_rule_set", "definition": "The hard gates a beacon defines.", "boundedBy": [ "INV-013" ] } ] }, "x-aura-reputation": { "status": "normative-interface", "description": "Reputation is the credible quality signal that keeps good sellers in the market. The dimensions and the transparency model are public; the scoring is proprietary and excluded from the contract.", "rationale": "A single score is gameable, collapses dimensions, and ossifies into an incumbency moat. Multi-dimensional signals computed from protocol events resist gaming and let a counterparty judge fit rather than a number.", "public": { "dimensions": [ { "id": "fulfilment_reliability", "definition": "Share of commitments honoured, weighted by recency." }, { "id": "offer_accuracy", "definition": "Gap between what was offered and what was delivered." }, { "id": "constraint_fidelity", "definition": "How often a Beacon's declared capabilities match the constraints it satisfies." }, { "id": "negotiation_integrity", "definition": "Rate of offer withdrawal, price change after commitment, and reneged terms." }, { "id": "response_relevance", "definition": "Match between Scout intent and Beacon offer." } ], "transparencyModel": "Each dimension is independently queryable and computed from protocol events, not self-reported.", "attachesTo": [ "Principal", "Beacon" ] }, "proprietary": { "scoringFormula": "excluded", "weightingModel": "excluded", "operationalParameters": "excluded" }, "supports": [ "INV-007" ] }, "x-aura-errors": { "status": "normative", "description": "Every error response carries a stable, machine-readable code in its `error` field. This catalogue is the closed set Core emits: each code maps to the HTTP status it accompanies, whether the same request is safe to retry, a category, a human-readable meaning, and where relevant the invariant it protects. Codes are stable identifiers; messages are explanatory.", "categories": { "auth": "Authentication and key validity.", "authorization": "The caller is authenticated but not permitted to act on the resource.", "validation": "The request failed a contract or field-level check.", "not_found": "The addressed resource does not exist or is not visible to the caller.", "state": "The resource is in a state that does not allow the action.", "conflict": "The action conflicts with existing state (idempotency, duplicates).", "rate_limit": "The caller has exceeded a rate limit.", "operational": "A transient server or dependency error; the same request is safe to retry." }, "codes": [ { "code": "authentication_required", "http": 401, "retryable": false, "category": "auth", "message": "The request carried no valid agent authentication. Provide agentId, agentTimestamp, and agentSignature.", "invariant": "persistent-identity-and-qualification" }, { "code": "beacon_no_signing_key", "http": 400, "retryable": false, "category": "auth", "message": "The Beacon has no registered signing key to verify against." }, { "code": "invalid_offer_signature", "http": 400, "retryable": false, "category": "auth", "message": "The offer signature did not verify against the Beacon's registered key.", "invariant": "recorded-intent-and-chain-of-custody" }, { "code": "invalid_signature", "http": 401, "retryable": false, "category": "auth", "message": "The agent signature did not verify against the registered key.", "invariant": "persistent-identity-and-qualification" }, { "code": "key_revoked", "http": 403, "retryable": false, "category": "auth", "message": "The presented key has been revoked.", "invariant": "persistent-identity-and-qualification" }, { "code": "missing_offer_signature", "http": 400, "retryable": false, "category": "auth", "message": "The offer was submitted without its required signature.", "invariant": "recorded-intent-and-chain-of-custody" }, { "code": "missing_signature", "http": 401, "retryable": false, "category": "auth", "message": "A required authentication signature header was absent." }, { "code": "cross_beacon_access_denied", "http": 403, "retryable": false, "category": "authorization", "message": "A Beacon may only access its own sessions and offers.", "invariant": "identity-abstraction-until-commitment" }, { "code": "cross_scout_access_denied", "http": 403, "retryable": false, "category": "authorization", "message": "A Scout may only access its own sessions.", "invariant": "identity-abstraction-until-commitment" }, { "code": "forbidden", "http": 403, "retryable": false, "category": "authorization", "message": "The authenticated agent may not act on this resource." }, { "code": "not_filing_agent", "http": 403, "retryable": false, "category": "authorization", "message": "Only the agent that filed the dispute may take this action." }, { "code": "scout_cannot_register_rules", "http": 403, "retryable": false, "category": "authorization", "message": "Scouts may not register business rules.", "invariant": "business-rules-as-hard-gates" }, { "code": "system_role_required", "http": 403, "retryable": false, "category": "authorization", "message": "This operation requires the system role." }, { "code": "dispute_already_exists", "http": 409, "retryable": false, "category": "conflict", "message": "A dispute already exists for this transaction." }, { "code": "duplicate_transaction", "http": 409, "retryable": false, "category": "conflict", "message": "A transaction already exists for this commitment; the commit is idempotent.", "invariant": "atomic-commitment" }, { "code": "adapter_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "beacon_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "clearing_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "offer_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "principal_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "profile_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "rule_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "session_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "transaction_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "The requested resource was not found." }, { "code": "cancel_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "chain_fetch_failed", "http": 503, "retryable": true, "category": "operational", "message": "A backend dependency was temporarily unavailable. Retry with backoff." }, { "code": "commit_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "database_unavailable", "http": 503, "retryable": true, "category": "operational", "message": "A backend dependency was temporarily unavailable. Retry with backoff." }, { "code": "dispute_filing_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "evidence_submission_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "fetch_failed", "http": 503, "retryable": true, "category": "operational", "message": "A backend dependency was temporarily unavailable. Retry with backoff." }, { "code": "offer_submission_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "profile_unavailable", "http": 503, "retryable": true, "category": "operational", "message": "A backend dependency was temporarily unavailable. Retry with backoff." }, { "code": "registration_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "resolution_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "revocation_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "scope_creation_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "session_creation_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "update_failed", "http": 500, "retryable": true, "category": "operational", "message": "The operation could not be completed due to a server error. Safe to retry." }, { "code": "rate_limit_exceeded", "http": 429, "retryable": true, "category": "rate_limit", "message": "Too many requests. Retry after the indicated delay." }, { "code": "beacon_cannot_counter", "http": 409, "retryable": false, "category": "state", "message": "The Beacon cannot submit a counter-offer here." }, { "code": "beacon_inactive", "http": 403, "retryable": false, "category": "state", "message": "The Beacon is not active." }, { "code": "cannot_cancel", "http": 409, "retryable": false, "category": "state", "message": "The session cannot be cancelled in its current state." }, { "code": "cannot_withdraw", "http": 409, "retryable": false, "category": "state", "message": "The offer cannot be withdrawn in its current state." }, { "code": "consent_elevation_required", "http": 403, "retryable": false, "category": "state", "message": "The action requires a higher consent tier than the delegation grants.", "invariant": "least-privilege-delegated-authority" }, { "code": "dispute_not_open", "http": 409, "retryable": false, "category": "state", "message": "The dispute is not open." }, { "code": "dispute_window_expired", "http": 409, "retryable": false, "category": "state", "message": "The dispute window has closed.", "invariant": "repudiability-within-a-bounded-window" }, { "code": "evidence_deadline_passed", "http": 409, "retryable": false, "category": "state", "message": "The evidence submission deadline has passed.", "invariant": "repudiability-within-a-bounded-window" }, { "code": "negotiation_exhausted", "http": 409, "retryable": false, "category": "state", "message": "The negotiation has reached its round limit." }, { "code": "not_disputable", "http": 409, "retryable": false, "category": "state", "message": "The transaction is not in a disputable state.", "invariant": "repudiability-within-a-bounded-window" }, { "code": "offer_not_counterable", "http": 409, "retryable": false, "category": "state", "message": "The offer cannot be countered in its current state." }, { "code": "principal_inactive", "http": 403, "retryable": false, "category": "state", "message": "The principal is not active." }, { "code": "session_expired", "http": 409, "retryable": false, "category": "state", "message": "The session has expired and no longer accepts actions." }, { "code": "session_not_accepting_offers", "http": 409, "retryable": false, "category": "state", "message": "The session is not accepting offers in its current state." }, { "code": "session_not_committable", "http": 409, "retryable": false, "category": "state", "message": "The session is not in a committable state.", "invariant": "atomic-commitment" }, { "code": "session_not_negotiable", "http": 409, "retryable": false, "category": "state", "message": "The session is not in a negotiable state." }, { "code": "transaction_frozen", "http": 409, "retryable": false, "category": "state", "message": "Fulfilment and payment updates are frozen while the transaction is disputed.", "invariant": "repudiability-within-a-bounded-window" }, { "code": "chain_link_failed", "http": 400, "retryable": false, "category": "validation", "message": "The intent-chain link could not be appended.", "invariant": "recorded-intent-and-chain-of-custody" }, { "code": "chain_validation_failed", "http": 400, "retryable": false, "category": "validation", "message": "The submitted intent-chain link did not validate.", "invariant": "recorded-intent-and-chain-of-custody" }, { "code": "default_profile_missing", "http": 400, "retryable": false, "category": "validation", "message": "The request was rejected by a contract or business-rule check." }, { "code": "invalid_adapter_id", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_beacon_id", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_capacity", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_clearinghouse_terms", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_consent_requirements", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_constraints", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_endpoint_url", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_field", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_fulfillment_terms", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_idempotency_key", "http": 400, "retryable": false, "category": "validation", "message": "The Idempotency-Key header was malformed." }, { "code": "invalid_key", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_offer_id", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_parameter", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_price", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_profile_id", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_quantity", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_risk_tolerance", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_rule_id", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_settlement_preference", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "invalid_status", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "missing_beacon_id", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "missing_description", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "missing_fields", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "missing_payment_terms_hash", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "missing_to_status", "http": 400, "retryable": false, "category": "validation", "message": "A request field was missing or failed validation." }, { "code": "no_chain", "http": 400, "retryable": false, "category": "validation", "message": "The request was rejected by a contract or business-rule check." }, { "code": "no_changes", "http": 400, "retryable": false, "category": "validation", "message": "The request was rejected by a contract or business-rule check." }, { "code": "no_scope", "http": 400, "retryable": false, "category": "validation", "message": "The request was rejected by a contract or business-rule check." }, { "code": "payload_too_large", "http": 413, "retryable": false, "category": "validation", "message": "The request body exceeded the size limit." }, { "code": "payment_terms_hash_mismatch", "http": 400, "retryable": false, "category": "validation", "message": "The payment terms hash did not match the signed offer.", "invariant": "recorded-intent-and-chain-of-custody" }, { "code": "unknown_profile", "http": 400, "retryable": false, "category": "validation", "message": "The request was rejected by a contract or business-rule check." }, { "code": "invalid_key_proof", "http": 422, "retryable": false, "category": "validation", "message": "new_key_proof does not verify over the canonical rotation payload against the submitted new key.", "invariant": "persistent-identity-and-qualification" }, { "code": "invalid_rotation_authorization", "http": 403, "retryable": false, "category": "authorization", "message": "The rotation was not authorized by the required key: the current key for rotation, the principal's key for agent recovery.", "invariant": "persistent-identity-and-qualification" }, { "code": "key_already_used", "http": 409, "retryable": false, "category": "conflict", "message": "The submitted key is already registered to an identity or exists in key history. A key is never reusable." }, { "code": "rotation_replayed", "http": 409, "retryable": false, "category": "conflict", "message": "The rotation timestamp is outside the freshness window, or the rotation tuple was already used." }, { "code": "key_rotation_conflict", "http": 409, "retryable": false, "category": "conflict", "message": "The identity's current key no longer matches the key the rotation payload was constructed against. Rebuild the payload against the current key." }, { "code": "recovery_not_available", "http": 403, "retryable": false, "category": "state", "message": "Principal key recovery requires re-verification against external credentials, which is not yet available." }, { "code": "rotation_failed", "http": 500, "retryable": true, "category": "operational", "message": "The key rotation could not be completed due to a server error. Safe to retry." }, { "code": "invalid_offer_expiry", "http": 400, "retryable": false, "category": "validation", "message": "The declared expires_at falls outside the session profile's offer validity window.", "invariant": "offer-expiry" }, { "code": "offer_expired", "http": 409, "retryable": false, "category": "state", "message": "The offer's expiry has passed. Commits and counters on it are refused.", "invariant": "offer-expiry" }, { "code": "missing_auth_headers", "http": 401, "retryable": false, "category": "auth", "message": "The request carried none or only some of the required authentication headers. Provide agentId, agentTimestamp, agentNonce, and agentSignature.", "invariant": "persistent-identity-and-qualification" }, { "code": "invalid_nonce", "http": 401, "retryable": false, "category": "auth", "message": "The X-Agent-Nonce header is missing, malformed, or outside the required shape (16-128 characters of [A-Za-z0-9._~-]).", "invariant": "persistent-identity-and-qualification" }, { "code": "replayed_request", "http": 401, "retryable": false, "category": "auth", "message": "The request nonce has already been used. Each authenticated request must carry a fresh nonce, so a captured signed request cannot be replayed within the freshness window.", "invariant": "persistent-identity-and-qualification" }, { "code": "invalid_host", "http": 401, "retryable": false, "category": "auth", "message": "The X-Agent-Host header is malformed (not a valid host or host:port).", "invariant": "persistent-identity-and-qualification" }, { "code": "host_mismatch", "http": 401, "retryable": false, "category": "auth", "message": "The signed X-Agent-Host does not match this Core. A request signed for one Core cannot be presented to another.", "invariant": "persistent-identity-and-qualification" }, { "code": "unknown_agent", "http": 401, "retryable": false, "category": "auth", "message": "The presented agent id resolves to no registered agent.", "invariant": "persistent-identity-and-qualification" }, { "code": "agent_revoked", "http": 403, "retryable": false, "category": "auth", "message": "The presented agent identity has been revoked.", "invariant": "persistent-identity-and-qualification" }, { "code": "agent_suspended", "http": 403, "retryable": false, "category": "auth", "message": "The presented agent identity is suspended.", "invariant": "persistent-identity-and-qualification" }, { "code": "namespace_mismatch", "http": 403, "retryable": false, "category": "authorization", "message": "The write crosses sandbox namespaces: the entities it binds (a beacon and a session, or an agent and its principal) belong to different namespaces. Sandbox isolation refuses cross-tenant writes." }, { "code": "invalid_domain", "http": 400, "retryable": false, "category": "validation", "message": "The declared domain is not a provable identity anchor: it must be a bare public multi-label DNS hostname, never a wildcard, IP address, scheme, port, or path." }, { "code": "mint_proof_invalid", "http": 401, "retryable": false, "category": "auth", "message": "The X-Signature proof-of-possession does not verify: sign the exact JSON request body with the declared key (JSON.stringify, UTF-8 bytes, Ed25519, base64)." }, { "code": "sandbox_identity_not_verified", "http": 403, "retryable": true, "category": "auth", "message": "Domain control was not proven. The response names the record or document Core looked for and what it found; publish it, allow propagation, and retry." }, { "code": "mint_failed", "http": 500, "retryable": true, "category": "operational", "message": "The mint could not be completed due to a server error. Safe to retry." }, { "code": "sandbox_key_invalid", "http": 401, "retryable": false, "category": "auth", "message": "The X-AURA-Sandbox-Key is absent, unknown, or revoked. Mint a key at the sandbox keys operation; after a re-mint under the re-proven domain, only the newest grant is live." }, { "code": "sandbox_quota_exceeded", "http": 429, "retryable": true, "category": "rate_limit", "message": "A sandbox quota for the verified identity is exhausted. The body names the quota and the tier; wait out the window or climb a verification rung." }, { "code": "sandbox_namespace_conflict", "http": 409, "retryable": true, "category": "conflict", "message": "A concurrent provision or reset holds this key's namespace. Retry: a repeated provision is idempotent and lands on the existing namespace." }, { "code": "sandbox_contract_version_skew", "http": 422, "retryable": false, "category": "validation", "message": "The requested scenario version is not the version this bench serves. The response names the served version; provision against it." }, { "code": "sandbox_provisioning_unavailable", "http": 503, "retryable": true, "category": "operational", "message": "Provisioning could not complete and rolled back; nothing was created. Safe to retry." }, { "code": "sandbox_run_active", "http": 409, "retryable": true, "category": "conflict", "message": "A flow is in flight in this namespace, or a concurrent reset opened a run first. Let open flows reach a quiescent state or expire, then reset again." }, { "code": "sandbox_run_not_found", "http": 404, "retryable": false, "category": "not_found", "message": "No such run in this namespace. Provision opens a run and returns its run_id; each reset opens a fresh one." } ] }, "x-aura-conformance": { "status": "normative", "description": "How a conforming implementation is verified. Each profile lists the invariants a role must honour; the testable assertions live on those invariants (their conformance[]). A third party runs the assertions to certify a Core.", "profiles": [ { "id": "core-minimal", "description": "The session, offer, commitment, identity, and intent-chain laws every Core must honour.", "requiresInvariants": [ "INV-001", "INV-002", "INV-003", "INV-004", "INV-005", "INV-006", "INV-007", "INV-008", "INV-015" ] }, { "id": "core-clearing", "description": "The clearing, settlement, reserve, neutrality, risk, business-rule, and repudiability laws a clearing Core must honour.", "requiresInvariants": [ "INV-009", "INV-010", "INV-011", "INV-012", "INV-013", "INV-014" ] }, { "id": "beacon-minimal", "description": "What a conforming Beacon must honour: signed, time-bound offers, with its identity withheld until commitment.", "requiresInvariants": [ "INV-002", "INV-005" ], "requiresSignatureProfiles": [ "beacon_offer" ] }, { "id": "scout-minimal", "description": "What a conforming Scout must honour: stay within delegated authority and commit atomically.", "requiresInvariants": [ "INV-004", "INV-006" ] }, { "id": "scout-admission", "layersOver": "scout-minimal", "description": "What a Scout proves to be admitted: everything scout-minimal requires, made executable across seeded golden and failure flows, plus redaction handling, expiry refusal, and delegated-authority boundaries. Signing correctness is proven against the published test vectors and exercised on every authenticated request.", "requiresInvariants": [ "INV-002", "INV-003", "INV-004", "INV-005", "INV-006", "INV-015" ], "requiresSignatureProfiles": [ "authenticated_request" ] }, { "id": "beacon-admission", "layersOver": "beacon-minimal", "description": "What a Beacon proves to be admitted: everything beacon-minimal requires, made executable across seeded golden and failure flows, plus constraint-bounded offering (a hard constraint is a boundary, never a ranking preference), monotonic disclosure handling, expiry semantics on its own offers, and atomic commitment behaviour.", "requiresInvariants": [ "INV-002", "INV-003", "INV-004", "INV-005", "INV-006" ], "requiresSignatureProfiles": [ "beacon_offer", "authenticated_request" ] } ], "assertionSource": "x-aura-invariants[].conformance", "assertionTypes": { "positive": "A valid flow that must succeed.", "negative": "A forbidden input that must be rejected.", "property": "An invariant that must hold across states.", "sequence": "An ordering or atomicity that must hold across steps." } } }