{
  "schemaVersion": "1.0",
  "title": "Gateway",
  "description": "Use this page to understand how the reviewed gateway converts a native AIP envelope plus transport-established trust into the context used by the runtime. It explains where signatures, replay protection, identity and tenant resolution, quer",
  "canonical": "https://getaip.org/docs/architecture/gateway",
  "route": "/docs/architecture/gateway",
  "source": "docs/architecture/gateway.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Architecture and Security",
  "documentType": "Architecture",
  "language": "en",
  "revision": {
    "lastReviewedRevision": "d7cce13d1d555644d04a4d73c66c95b113737635",
    "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb",
    "basis": "frontmatter"
  },
  "downloads": {
    "md": "/docs/download/architecture/gateway.md",
    "txt": "/docs/download/architecture/gateway.txt",
    "json": "/docs/download/architecture/gateway.json",
    "pdf": "/docs/download/architecture/gateway.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Gateway\ndescription: Understand how trusted ingress becomes authorized runtime context and correlated native AIP responses\nkind: explanation\naudience: developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"d7cce13d1d555644d04a4d73c66c95b113737635\"\n---\n\n# Gateway\n\nUse this page to understand how the reviewed gateway converts a native AIP\nenvelope plus transport-established trust into the context used by the runtime.\nIt explains where signatures, replay protection, identity and tenant resolution,\nquery authorization, delegation, callbacks, and response correlation belong.\n\nThe page describes version `2.0.0` of the Rust workspace at source revision\n`d7cce13d1d555644d04a4d73c66c95b113737635`. `aip-gateway` is a library\ncomposition boundary. It is not itself an HTTP, NATS, MCP, or A2A server, and\nits process placement is not prescribed by AIP 1.0.\n\n## Place the gateway between ingress and lifecycle\n\nTransports authenticate connections or credentials and decode bytes. Profiles\nmap a bounded foreign protocol into native AIP. The gateway receives the native\nenvelope, establishes trusted message context, applies cross-message policy, and\nselects the runtime operation. The runtime owns lifecycle state and execution.\n\n| Boundary | Gateway responsibility | Responsibility kept elsewhere |\n|---|---|---|\n| Ingress | Accept a signed native envelope or an explicitly authenticated edge result | Listener, token, certificate, NATS peer, MCP, or A2A authentication |\n| Trust | Bind signer or authenticated actor, reject replay, and resolve tenant, identity, and credential context | Deployment identity directory and credential material |\n| Authorization | Apply operational object, action context, tenant, principal, and session checks before dispatch | Capability policy and lifecycle decisions inside the runtime |\n| Dispatch | Map every native message family to its runtime, discovery, session, query, or observation operation | Durable stores, workers, handlers, and provider execution |\n| Egress | Correlate native responses and enforce remote peer or callback destination policy | Public route serialization and deployment network controls |\n\nCompatibility profiles do not bypass this boundary. Their authenticated hosts\nconstruct native envelopes and call a trusted gateway entrypoint; they do not\ncreate a second action lifecycle.\n\n## Choose one of four ingress trust entrypoints\n\nThe library exposes four entrypoints so the caller cannot silently mix payload\nclaims with transport evidence.\n\n| Entrypoint | Trust supplied by caller | Gateway behavior |\n|---|---|---|\n| `handle_envelope` | None | Verify the envelope signature and trusted DID binding under policy, then claim replay state |\n| `handle_authenticated_envelope` | One already authenticated in-process principal | Replace `Envelope.from`, synthesize authenticated actor context, and claim replay state |\n| `handle_verified_envelope` | Authenticated actor plus optional verified tenant and credential handle | Replace `Envelope.from`, project trusted tenant and credential context, and claim replay state |\n| `handle_resolved_envelope` | Complete validated `ResolvedIdentity` from a trusted edge | Replace `Envelope.from`, install its actor, tenant, credential, and identity context, and claim replay state |\n\nThe default policy is fail closed: signed envelopes are required, payload\nidentity is not trusted, action senders are required, and message replay is\nrejected. The gateway's signer registry adds the independent DID-to-principal\ntrust decision after signature verification proves key possession.\n\nAn explicit local-development constructor disables signature enforcement and\nallows payload identity. Its source contract says it must not serve a\nnetwork-facing deployment.\n\nAlready authenticated entrypoints skip native envelope-signature verification\nbecause their caller owns that edge decision. They still apply replay claims,\nquery authorization, and runtime policy. The resolved entrypoint trusts its\ncaller to have completed identity consistency; other action paths invoke the\nconfigured resolver when policy requires it.\n\n## Follow the ordered request pipeline\n\n~~~mermaid\nflowchart LR\n    E[\"Native envelope\"] --> A[\"Authenticate edge or signed DID\"]\n    A --> R[\"Claim message replay window\"]\n    R --> I[\"Resolve trusted action identity\"]\n    I --> C[\"Build MessageContext\"]\n    C --> Q[\"Authorize operational query\"]\n    Q --> D[\"Dispatch native message family\"]\n    D --> L[\"Runtime or discovery owner\"]\n    L --> O[\"Correlated response envelope\"]\n~~~\n\nThe text equivalent is:\n\n1. The caller supplies either a raw native envelope or transport-authenticated\n   actor state through the matching entrypoint.\n2. The gateway verifies the native signature and trusted principal binding when\n   that work was not completed by the edge.\n3. It rejects messages outside the configured past or future time window and\n   claims the message ID in the selected replay store when replay rejection is\n   enabled.\n4. For an action or delegated child action, it resolves deployment-owned\n   identity when the capability or request requires it. A cancellation can\n   request operational tenant context through the same resolver.\n5. It builds one `MessageContext` from envelope correlation data and verified\n   actor, tenant, credential, and identity values.\n6. It applies query and session policy before selecting the message-family\n   branch.\n7. It invokes the runtime or discovery owner and creates a native response with\n   the original session and correlation coordinates.\n\nMetrics count the received envelope and action before policy evaluation. They\ndo not establish that authentication, authorization, or execution succeeded.\n\n## Authenticate a native signer independently of payload claims\n\nFor `handle_envelope`, the gateway verifies the Ed25519 signature carried in\nthe envelope security object and obtains its DID. The DID must already map to a\ntrusted AIP principal. `Envelope.from` must match that principal's ID and kind.\n\nA self-generated DID, a valid signature, or a matching payload sender is not\nsufficient alone. The trust registry supplies the deployment decision that the\nkey may act as that principal.\n\nAuthenticated-edge entrypoints overwrite `Envelope.from` with the actor they\nreceived. A payload cannot retain a different sender after the edge has\nestablished identity.\n\n## Claim replay before resolving authority\n\nWhen replay rejection is enabled, the gateway checks `sent_at` against the\nconfigured retention window and maximum future skew. It then claims the\n`message_id` in the runtime replay store until the calculated expiration.\n\nThe claim occurs before identity resolution and dispatch. A duplicate ID or an\nout-of-window timestamp fails without repeating the action, query, or\nobservation branch. Disabling replay rejection is an explicit policy change; an\nauthenticated actor does not disable it automatically.\n\nReplay protection is message-level evidence. Provider idempotency and uncertain\noutcome reconciliation remain separate runtime and connector responsibilities.\n\n## Resolve identity only when required\n\nFor a root action and the child action inside a delegation request, identity\nresolution runs when any of these conditions holds:\n\n- the action carries an identity claim that requires verification;\n- a fleet policy enables resolution for a capability absent from the bounded\n  local manifest;\n- the capability ID is explicitly marked as identity-required; or\n- the local capability contract requires a credential, accepted issuer, or\n  credential scope.\n\nThe deployment-owned resolver receives the authenticated actor, the claimed\nidentity, and the accepted credential rules. It may return a verified tenant,\nan opaque credential handle, and a normalized identity context.\n\nThe gateway then enforces these invariants:\n\n- the resolver cannot replace the transport actor's principal ID or kind;\n- resolved scopes must be a subset of the transport-authenticated scopes;\n- the verified tenant and credential handle must validate;\n- a required credential must exist and use an accepted issuer and scopes;\n- a tenant carried by the credential must match verified tenant membership; and\n- tenant or credential values already present in resolved identity cannot\n  conflict with their verified forms.\n\nThe gateway restores the original authenticated actor after validation and\nprojects only canonical verified tenant and credential references. The resolver\nnever receives permission to elevate the edge actor.\n\nThe default resolver denies resolution. A deployment that enables fleet lookup,\nidentity claims, or credential-bearing capabilities must install an appropriate\ntrusted resolver.\n\n## Authorize operational reads and selectors\n\nBefore message-family dispatch, the gateway requires a sender for operational\nmessages and applies `QueryAuthorizationService` to query operations. The\nauthorization request identifies:\n\n- the authenticated actor and optional verified tenant;\n- the object family and requested operation;\n- an optional selected principal;\n- an optional tenant selector; and\n- the actor's effective scopes.\n\nMissing membership, tenant mismatch, insufficient authority, and protected\naudit access become typed authorization errors. If both the envelope and the\nrequest carry a session ID, the values must match.\n\nThis query gate does not replace action governance. The runtime still evaluates\ncapability contracts, idempotency, approvals, transactions, and handler\nadmission for executable work.\n\n## Dispatch by owner, not by transport\n\nThe gateway's native message match is exhaustive, but its branches fall into a\nsmall set of ownership patterns.\n\n| Message purpose | Gateway action | State owner |\n|---|---|---|\n| Handshake | Verify that the declared client matches the authenticated actor, negotiate profile and capability intersections, and create a secure session | Runtime session service |\n| Manifest request | Filter and return the bounded local manifest | Gateway local composition |\n| Received manifest | Validate it as a remote observation without publishing it as a callable local implementation | Remote observation registry and event log |\n| Action or delegated child action | Require an actor and submit the trusted context | Runtime scheduler and selected handler |\n| Lifecycle or operational query | Apply query policy and call the context-aware runtime view | Corresponding durable runtime service |\n| Result, status, event, audit, receipt, or remote view | Ingest or record the authenticated observation | Runtime lifecycle and event stores |\n| Cancel, approval, transaction, escalation, or channel work | Select the corresponding runtime transition | Dedicated runtime service |\n\nAn action can return a terminal `ActionResult` or a queued `Ack`; the gateway\ndoes not infer completion from the transport request. Errors from the runtime\nare mapped into typed AIP error envelopes by the caller-facing boundary.\n\nThe response helper copies the request session and correlation IDs, identifies\nthe local manifest agent as sender, and addresses the authenticated actor. It\ndoes not itself guarantee that every embedding signs the returned envelope;\ntransport and peer-specific code own that requirement.\n\n## Admit local capabilities atomically\n\nA network-facing gateway that declares callable local capabilities uses the\nconstructor that admits the manifest and complete handler map before the\ngateway becomes observable. Invalid schema, binding, implementation claim, or\nprojected identifier fails the composition without publishing partial discovery\nor handler state.\n\nOutbound or frozen connectors can similarly discover a manifest, create one\nhandler per non-resource capability, and atomically admit the manifest-handler\nset before becoming registered for readiness.\n\nThis library capability does not mean the primary `getaip-server` bundles product\nadapters. Its target fleet composition uses product-neutral catalog and remote\nhandler services, while explicitly trusted local modules use the startup-frozen\nlocal path.\n\n## Separate handshake, discovery, and action authority\n\nA handshake requires transport-established identity. The declared client must\nmatch the authenticated actor, and the gateway accepts only the intersection of\nrequested and configured profiles. With no compatible profile, it returns a\nrejected handshake response rather than creating a session.\n\nAn accepted handshake creates a secure runtime session and returns its resume\ntoken plus the requested capability intersection present in the local manifest.\nThis negotiation does not grant a later action permission or prove provider\nreadiness.\n\nA received remote manifest passes manifest admission and is stored as a remote\nobservation. It does not join the local callable catalog or install an action\nhandler. Discovery, identity, authorization, and implementation admission remain\nseparate decisions.\n\n## Route delegation without weakening the child action\n\nA delegated child action passes through the same identity-resolution boundary\nas a root action. The request target must be the local gateway or a configured\nremote route.\n\nStatic routes selected by delegate principal or child capability take\nprecedence. Connector-owned delegation routers are consulted only when no\nstatic route matches. If neither external path accepts the request, the runtime\ncan use its local delegation path only for the local target.\n\nNative HTTP and NATS peer bindings sign outbound envelopes and authenticate the\nexpected response principal, DID, and trust domain. HTTP destinations are\nchecked against URL, host, DNS, redirect, address-range, timeout, response-size,\nand optional private-PKI policy. Transport retry does not change the delegation\nidentity.\n\n## Protect callback egress independently\n\nThe callback dispatcher selects native HTTP, native NATS, in-process SSE, or an\nA2A push profile. Externally delivered native callbacks require a configured\nsigner. HTTP and NATS destinations pass the deployment's destination policy;\nin-process SSE is keyed by correlation ID.\n\nA2A push credentials can be sealed with a deployment-provided AES-256-GCM key\nbefore durable storage. Every gateway replica that may recover those callbacks\nneeds the same key. Callback destination authorization, credential encryption,\ndelivery retries, and action completion are distinct states.\n\n## Interpret readiness narrowly\n\n`GatewayReadiness` probes runtime storage and every connector registered in the\ngateway's local connector map. It reports ready only when all those checks pass.\n\nThat result does not cover an external profile edge, registry, remote connector\nhost, provider, callback target, or deployment load balancer. The daemon composes\nadditional fleet and process-level readiness outside the library report.\n\n## Failure ownership and non-implications\n\n| Failure | Owning decision |\n|---|---|\n| Invalid or untrusted native signature | Reject at raw-envelope authentication |\n| Duplicate or stale message ID | Reject at replay claim before dispatch |\n| Resolver actor or scope substitution | Reject identity resolution |\n| Required tenant or credential evidence is missing | Reject trusted-context construction |\n| Unauthorized query or session selector mismatch | Reject before message-family routing |\n| Invalid local manifest-handler set | Reject gateway construction or connector registration atomically |\n| Runtime storage, governance, or handler failure | Return a typed runtime-derived AIP error |\n| Remote peer or callback destination failure | Retain the runtime's delivery or delegation evidence for bounded retry or recovery |\n\nThe gateway does not own product data-transfer objects, provider credentials,\nprovider APIs, listener authentication configuration, durable store algorithms,\nor deployment topology. Source support for an entrypoint or egress profile does\nnot prove that a deployment enabled, secured, or qualified it.\n\n## Related pages\n\n- [Runtime](runtime.md)\n- [Security model](security-model.md)\n- [Identity and trust](../concepts/identity-and-trust.md)\n- [HTTP API](../reference/http-api.md)\n- [Transport bindings](../reference/transport-bindings.md)\n",
    "text": "Gateway\n\nUse this page to understand how the reviewed gateway converts a native AIP\nenvelope plus transport-established trust into the context used by the runtime.\nIt explains where signatures, replay protection, identity and tenant resolution,\nquery authorization, delegation, callbacks, and response correlation belong.\n\nThe page describes version 2.0.0 of the Rust workspace at source revision\nd7cce13d1d555644d04a4d73c66c95b113737635. aip-gateway is a library\ncomposition boundary. It is not itself an HTTP, NATS, MCP, or A2A server, and\nits process placement is not prescribed by AIP 1.0.\n\nPlace the gateway between ingress and lifecycle\n\nTransports authenticate connections or credentials and decode bytes. Profiles\nmap a bounded foreign protocol into native AIP. The gateway receives the native\nenvelope, establishes trusted message context, applies cross-message policy, and\nselects the runtime operation. The runtime owns lifecycle state and execution.\n\n| Boundary | Gateway responsibility | Responsibility kept elsewhere |\n\n| Ingress | Accept a signed native envelope or an explicitly authenticated edge result | Listener, token, certificate, NATS peer, MCP, or A2A authentication |\n| Trust | Bind signer or authenticated actor, reject replay, and resolve tenant, identity, and credential context | Deployment identity directory and credential material |\n| Authorization | Apply operational object, action context, tenant, principal, and session checks before dispatch | Capability policy and lifecycle decisions inside the runtime |\n| Dispatch | Map every native message family to its runtime, discovery, session, query, or observation operation | Durable stores, workers, handlers, and provider execution |\n| Egress | Correlate native responses and enforce remote peer or callback destination policy | Public route serialization and deployment network controls |\n\nCompatibility profiles do not bypass this boundary. Their authenticated hosts\nconstruct native envelopes and call a trusted gateway entrypoint; they do not\ncreate a second action lifecycle.\n\nChoose one of four ingress trust entrypoints\n\nThe library exposes four entrypoints so the caller cannot silently mix payload\nclaims with transport evidence.\n\n| Entrypoint | Trust supplied by caller | Gateway behavior |\n\n| handleenvelope | None | Verify the envelope signature and trusted DID binding under policy, then claim replay state |\n| handleauthenticatedenvelope | One already authenticated in-process principal | Replace Envelope.from, synthesize authenticated actor context, and claim replay state |\n| handleverifiedenvelope | Authenticated actor plus optional verified tenant and credential handle | Replace Envelope.from, project trusted tenant and credential context, and claim replay state |\n| handleresolvedenvelope | Complete validated ResolvedIdentity from a trusted edge | Replace Envelope.from, install its actor, tenant, credential, and identity context, and claim replay state |\n\nThe default policy is fail closed: signed envelopes are required, payload\nidentity is not trusted, action senders are required, and message replay is\nrejected. The gateway's signer registry adds the independent DID-to-principal\ntrust decision after signature verification proves key possession.\n\nAn explicit local-development constructor disables signature enforcement and\nallows payload identity. Its source contract says it must not serve a\nnetwork-facing deployment.\n\nAlready authenticated entrypoints skip native envelope-signature verification\nbecause their caller owns that edge decision. They still apply replay claims,\nquery authorization, and runtime policy. The resolved entrypoint trusts its\ncaller to have completed identity consistency; other action paths invoke the\nconfigured resolver when policy requires it.\n\nFollow the ordered request pipeline\n\nmermaid\nflowchart LR\n    E[\"Native envelope\"] --> A[\"Authenticate edge or signed DID\"]\n    A --> R[\"Claim message replay window\"]\n    R --> I[\"Resolve trusted action identity\"]\n    I --> C[\"Build MessageContext\"]\n    C --> Q[\"Authorize operational query\"]\n    Q --> D[\"Dispatch native message family\"]\n    D --> L[\"Runtime or discovery owner\"]\n    L --> O[\"Correlated response envelope\"]\n\nThe text equivalent is:\n1. The caller supplies either a raw native envelope or transport-authenticated\n   actor state through the matching entrypoint.\n2. The gateway verifies the native signature and trusted principal binding when\n   that work was not completed by the edge.\n3. It rejects messages outside the configured past or future time window and\n   claims the message ID in the selected replay store when replay rejection is\n   enabled.\n4. For an action or delegated child action, it resolves deployment-owned\n   identity when the capability or request requires it. A cancellation can\n   request operational tenant context through the same resolver.\n5. It builds one MessageContext from envelope correlation data and verified\n   actor, tenant, credential, and identity values.\n6. It applies query and session policy before selecting the message-family\n   branch.\n7. It invokes the runtime or discovery owner and creates a native response with\n   the original session and correlation coordinates.\n\nMetrics count the received envelope and action before policy evaluation. They\ndo not establish that authentication, authorization, or execution succeeded.\n\nAuthenticate a native signer independently of payload claims\n\nFor handleenvelope, the gateway verifies the Ed25519 signature carried in\nthe envelope security object and obtains its DID. The DID must already map to a\ntrusted AIP principal. Envelope.from must match that principal's ID and kind.\n\nA self-generated DID, a valid signature, or a matching payload sender is not\nsufficient alone. The trust registry supplies the deployment decision that the\nkey may act as that principal.\n\nAuthenticated-edge entrypoints overwrite Envelope.from with the actor they\nreceived. A payload cannot retain a different sender after the edge has\nestablished identity.\n\nClaim replay before resolving authority\n\nWhen replay rejection is enabled, the gateway checks sentat against the\nconfigured retention window and maximum future skew. It then claims the\nmessageid in the runtime replay store until the calculated expiration.\n\nThe claim occurs before identity resolution and dispatch. A duplicate ID or an\nout-of-window timestamp fails without repeating the action, query, or\nobservation branch. Disabling replay rejection is an explicit policy change; an\nauthenticated actor does not disable it automatically.\n\nReplay protection is message-level evidence. Provider idempotency and uncertain\noutcome reconciliation remain separate runtime and connector responsibilities.\n\nResolve identity only when required\n\nFor a root action and the child action inside a delegation request, identity\nresolution runs when any of these conditions holds:\n• the action carries an identity claim that requires verification;\n• a fleet policy enables resolution for a capability absent from the bounded\n  local manifest;\n• the capability ID is explicitly marked as identity-required; or\n• the local capability contract requires a credential, accepted issuer, or\n  credential scope.\n\nThe deployment-owned resolver receives the authenticated actor, the claimed\nidentity, and the accepted credential rules. It may return a verified tenant,\nan opaque credential handle, and a normalized identity context.\n\nThe gateway then enforces these invariants:\n• the resolver cannot replace the transport actor's principal ID or kind;\n• resolved scopes must be a subset of the transport-authenticated scopes;\n• the verified tenant and credential handle must validate;\n• a required credential must exist and use an accepted issuer and scopes;\n• a tenant carried by the credential must match verified tenant membership; and\n• tenant or credential values already present in resolved identity cannot\n  conflict with their verified forms.\n\nThe gateway restores the original authenticated actor after validation and\nprojects only canonical verified tenant and credential references. The resolver\nnever receives permission to elevate the edge actor.\n\nThe default resolver denies resolution. A deployment that enables fleet lookup,\nidentity claims, or credential-bearing capabilities must install an appropriate\ntrusted resolver.\n\nAuthorize operational reads and selectors\n\nBefore message-family dispatch, the gateway requires a sender for operational\nmessages and applies QueryAuthorizationService to query operations. The\nauthorization request identifies:\n• the authenticated actor and optional verified tenant;\n• the object family and requested operation;\n• an optional selected principal;\n• an optional tenant selector; and\n• the actor's effective scopes.\n\nMissing membership, tenant mismatch, insufficient authority, and protected\naudit access become typed authorization errors. If both the envelope and the\nrequest carry a session ID, the values must match.\n\nThis query gate does not replace action governance. The runtime still evaluates\ncapability contracts, idempotency, approvals, transactions, and handler\nadmission for executable work.\n\nDispatch by owner, not by transport\n\nThe gateway's native message match is exhaustive, but its branches fall into a\nsmall set of ownership patterns.\n\n| Message purpose | Gateway action | State owner |\n\n| Handshake | Verify that the declared client matches the authenticated actor, negotiate profile and capability intersections, and create a secure session | Runtime session service |\n| Manifest request | Filter and return the bounded local manifest | Gateway local composition |\n| Received manifest | Validate it as a remote observation without publishing it as a callable local implementation | Remote observation registry and event log |\n| Action or delegated child action | Require an actor and submit the trusted context | Runtime scheduler and selected handler |\n| Lifecycle or operational query | Apply query policy and call the context-aware runtime view | Corresponding durable runtime service |\n| Result, status, event, audit, receipt, or remote view | Ingest or record the authenticated observation | Runtime lifecycle and event stores |\n| Cancel, approval, transaction, escalation, or channel work | Select the corresponding runtime transition | Dedicated runtime service |\n\nAn action can return a terminal ActionResult or a queued Ack; the gateway\ndoes not infer completion from the transport request. Errors from the runtime\nare mapped into typed AIP error envelopes by the caller-facing boundary.\n\nThe response helper copies the request session and correlation IDs, identifies\nthe local manifest agent as sender, and addresses the authenticated actor. It\ndoes not itself guarantee that every embedding signs the returned envelope;\ntransport and peer-specific code own that requirement.\n\nAdmit local capabilities atomically\n\nA network-facing gateway that declares callable local capabilities uses the\nconstructor that admits the manifest and complete handler map before the\ngateway becomes observable. Invalid schema, binding, implementation claim, or\nprojected identifier fails the composition without publishing partial discovery\nor handler state.\n\nOutbound or frozen connectors can similarly discover a manifest, create one\nhandler per non-resource capability, and atomically admit the manifest-handler\nset before becoming registered for readiness.\n\nThis library capability does not mean the primary getaip-server bundles product\nadapters. Its target fleet composition uses product-neutral catalog and remote\nhandler services, while explicitly trusted local modules use the startup-frozen\nlocal path.\n\nSeparate handshake, discovery, and action authority\n\nA handshake requires transport-established identity. The declared client must\nmatch the authenticated actor, and the gateway accepts only the intersection of\nrequested and configured profiles. With no compatible profile, it returns a\nrejected handshake response rather than creating a session.\n\nAn accepted handshake creates a secure runtime session and returns its resume\ntoken plus the requested capability intersection present in the local manifest.\nThis negotiation does not grant a later action permission or prove provider\nreadiness.\n\nA received remote manifest passes manifest admission and is stored as a remote\nobservation. It does not join the local callable catalog or install an action\nhandler. Discovery, identity, authorization, and implementation admission remain\nseparate decisions.\n\nRoute delegation without weakening the child action\n\nA delegated child action passes through the same identity-resolution boundary\nas a root action. The request target must be the local gateway or a configured\nremote route.\n\nStatic routes selected by delegate principal or child capability take\nprecedence. Connector-owned delegation routers are consulted only when no\nstatic route matches. If neither external path accepts the request, the runtime\ncan use its local delegation path only for the local target.\n\nNative HTTP and NATS peer bindings sign outbound envelopes and authenticate the\nexpected response principal, DID, and trust domain. HTTP destinations are\nchecked against URL, host, DNS, redirect, address-range, timeout, response-size,\nand optional private-PKI policy. Transport retry does not change the delegation\nidentity.\n\nProtect callback egress independently\n\nThe callback dispatcher selects native HTTP, native NATS, in-process SSE, or an\nA2A push profile. Externally delivered native callbacks require a configured\nsigner. HTTP and NATS destinations pass the deployment's destination policy;\nin-process SSE is keyed by correlation ID.\n\nA2A push credentials can be sealed with a deployment-provided AES-256-GCM key\nbefore durable storage. Every gateway replica that may recover those callbacks\nneeds the same key. Callback destination authorization, credential encryption,\ndelivery retries, and action completion are distinct states.\n\nInterpret readiness narrowly\n\nGatewayReadiness probes runtime storage and every connector registered in the\ngateway's local connector map. It reports ready only when all those checks pass.\n\nThat result does not cover an external profile edge, registry, remote connector\nhost, provider, callback target, or deployment load balancer. The daemon composes\nadditional fleet and process-level readiness outside the library report.\n\nFailure ownership and non-implications\n\n| Failure | Owning decision |\n\n| Invalid or untrusted native signature | Reject at raw-envelope authentication |\n| Duplicate or stale message ID | Reject at replay claim before dispatch |\n| Resolver actor or scope substitution | Reject identity resolution |\n| Required tenant or credential evidence is missing | Reject trusted-context construction |\n| Unauthorized query or session selector mismatch | Reject before message-family routing |\n| Invalid local manifest-handler set | Reject gateway construction or connector registration atomically |\n| Runtime storage, governance, or handler failure | Return a typed runtime-derived AIP error |\n| Remote peer or callback destination failure | Retain the runtime's delivery or delegation evidence for bounded retry or recovery |\n\nThe gateway does not own product data-transfer objects, provider credentials,\nprovider APIs, listener authentication configuration, durable store algorithms,\nor deployment topology. Source support for an entrypoint or egress profile does\nnot prove that a deployment enabled, secured, or qualified it.\n\nRelated pages\n• Runtime (runtime.md)\n• Security model (security-model.md)\n• Identity and trust (../concepts/identity-and-trust.md)\n• HTTP API (../reference/http-api.md)\n• Transport bindings (../reference/transport-bindings.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "24f6176458d211ef117128872a27e960717a80002ad514154db1faeb75432beb"
  }
}