Skip to content

Agent Mesh

docs: complete Phase 5 documentation overhaul for task-based authorization, STS, and egress brokers

Antonio Ojea325ba45ba558
diff --git a/README.md b/README.md
index 5e2c7250..cbc085bc 100644
--- a/README.md
+++ b/README.md
@@ -77,8 +77,8 @@ installing anything:
SAM is pre-1.0. The node, routers, control plane, identity and policy model
are stable in shape and exercised by the test suite and two public testnets;
-see [ROADMAP.md](ROADMAP.md) for the release plan. Sandboxed agents
-(`sam-box`, `nano-init`) and the mobile app are in preview.
+see [ROADMAP.md](ROADMAP.md) for the release plan. Sandboxed agent blueprints
+and the mobile app are in preview.
## License and disclaimer
diff --git a/site/content/docs/concepts/authorization.md b/site/content/docs/concepts/authorization.md
index 6e29731c..544fd1e9 100644
--- a/site/content/docs/concepts/authorization.md
+++ b/site/content/docs/concepts/authorization.md
@@ -4,31 +4,43 @@ linkTitle: "Authorization"
weight: 3
---
-Authorization in SAM answers one question: may this caller use this service
-on this node? Three sources contribute to the answer, and the node that hosts
-the service combines them: the caller's credential, the mesh policy, and the
-node's own configuration. Each source can only narrow what the others allow.
-If none of them grants access, the answer is no.
+Authorization in SAM answers one question: may this caller perform this
+operation on this service on this node right now? Four sources contribute to
+the answer, and the destination node combines them:
-## Services are the unit of authorization
+1. **The caller's credential** (Block 0 authority facts signed by the control
+ plane).
+2. **The standing mesh policy** (roles, bindings, HTTP narrowings, and egress
+ destinations distributed by the control plane as Datalog rules).
+3. **Any appended `TaskAuthorizationRule` blocks (`tar_block`)** on the
+ credential, which narrow authority for a specific task or sub-agent hop.
+4. **The hosting node's local `attenuation` configuration**.
+
+Each layer can only narrow what the others allow. If standing policy or any
+appended task block denies the request, the answer is no.
+
+## Services and task operations
A node publishes services, each with a type and a name: `mcp://calculator`,
-`inference://vllm-eu`, `a2a://triage`, and the built-in
-`system://sam.catalog` that answers discovery queries. Policy grants access
-to services by these names. It does not look inside a service: a grant on
-`mcp://db` offers every tool that the MCP server exposes. To offer different
-privilege levels, publish different services (`mcp://db-reader`,
-`mcp://db-writer`) and grant them separately. Choosing which tools a backend
-exposes is the job of the backend, or of a small MCP server placed in front
-of it.
+`inference://vllm-eu`, `a2a://triage`, `egress://bigquery.googleapis.com`, and
+the built-in `system://sam.catalog` that answers discovery queries.
+
+Standing mesh roles grant access to services by name (`allowed_services`) and
+can narrow HTTP methods and paths (`http`). On top of standing roles, a
+holder can append `TaskAuthorizationRule` blocks (`tar_block`) to scope a
+token for a single task or sub-agent hop—narrowing which services, MCP tools
+(`operation.allowed_tools`), HTTP methods and paths
+(`operation.allowed_methods`, `operation.allowed_paths`), and upstream cloud
+IAM permissions and resources (`operation.allowed_permissions`,
+`allowed_resources`) that token may use.
## Mesh policy: roles and bindings
The mesh policy is a document held by the control plane. You edit it through
`POST /policies` or the console. `sam-one` can also seed it on first boot
-from a file (`--policy-file`). The document has two lists.
+from a file (`--policy-file`).
-**Roles** name a set of permissions:
+**Roles** name a set of standing permissions:
```json
{
@@ -36,7 +48,9 @@ from a file (`--policy-file`). The document has two lists.
"allowed_services": ["mcp://code-reviewer", "mcp://build-runner.*", "inference://*"],
"allowed_targets": ["group:dev-nodes"],
"allowed_labels": ["region=*"],
- "allowed_agents": [],
+ "http": [
+ { "service": "mcp://code-reviewer", "methods": ["POST"], "paths": ["/mcp"] }
+ ],
"custom_datalog": []
}
```
@@ -52,9 +66,8 @@ from a file (`--policy-file`). The document has two lists.
- `allowed_labels`: the labels a node with this role may declare at
enrollment: `key=value`, `key=*` or `*`. If absent, the node may declare
no labels.
-- `allowed_agents`: the agent identifiers a node with this role may claim to
- act for. Only used by the sandboxed-agent
- [preview](../../preview/sandboxed-agents/).
+- `http`: optional method and path restrictions for entries in
+ `allowed_services`.
- `custom_datalog`: extra Datalog facts or rules for holders of the role.
**Bindings** attach roles to identities:
@@ -73,9 +86,9 @@ few grants.
Roles are never members and never claims. `role:x` is not a valid member,
and an identity provider cannot give out a mesh role by putting it in a
`roles` claim. Such a claim becomes an `idp_role` fact, and a binding can
-choose to honour it. The three built-in roles, `sam:role:node`,
-`sam:role:router` and `sam:role:sambox`, follow the same rule: a binary can
-only enroll if a binding gives its identity the role it needs.
+choose to honour it. The two built-in roles, `sam:role:node` and
+`sam:role:router`, follow the same rule: a binary can only enroll if a
+binding gives its identity the role it needs.
The control plane validates a policy when it is posted. It rejects a policy
that references an undefined role, uses an unknown member prefix, or would
@@ -84,11 +97,12 @@ evaluate.
## From policy to facts
-At enrollment and at every refresh, the control plane resolves the identity's
-roles from the bindings and writes the result into the credential as Datalog
-facts: one `role(...)` fact per role, plus the grants compiled from the
-lists of every role. For example, `allowed_services: ["mcp://calculator"]`
-becomes `granted_service_exact("mcp", "calculator")`, `mcp://*` becomes
+At enrollment, refresh, and token exchange (`POST /token/exchange`), the
+control plane resolves the identity's roles from the bindings and writes the
+result into the credential's authority block as Datalog facts: one `role(...)`
+fact per role, plus the grants compiled from the lists of every role. For
+example, `allowed_services: ["mcp://calculator"]` becomes
+`granted_service_exact("mcp", "calculator")`, `mcp://*` becomes
`granted_service_all("mcp")`, and `mcp://*.internal` becomes
`granted_service_suffix("mcp", ".internal")`. Wildcards keep their dot, so
`*.acme.example` matches `svc.acme.example` but not `evil-acme.example`.
@@ -102,29 +116,30 @@ authorizer as it arrives. When a node verifies a credential, these rules run
against the identity facts in it. A grant added to the policy therefore
reaches every node within the sync interval, with no need to reissue
credentials. Removing a grant takes effect through the credential instead:
-the facts already in a token stay valid until the token is refreshed, which
-happens within its TTL (24 hours by default).
+the facts already in a token stay valid until the token is refreshed or
+expires.
## What the hosting node checks
-When a request for service `S` arrives from peer `P`, the node builds a
-Biscuit authorizer and adds the following, in this order:
+When a request for service `S` arrives from peer `P`, the node validates the
+Biscuit structure and runs two enforcement stages:
+
+### Stage 1: Standing Datalog policy (Block 0)
-1. **The request**: `service("mcp", "calculator")` for the requested
+The node builds a Biscuit authorizer over Block 0 and adds, in this order:
+
+1. **The request facts**: `service("mcp", "calculator")` for the requested
service, and `connection_peer_id(P)` from the authenticated connection.
- If the caller named an agent, the agent claim is added together with the
- check that the caller's own token grants that agent namespace. When the
- node handles the request as HTTP it adds `method("GET")` and
+ When the node handles the request as HTTP it adds `method("GET")` and
`path("/v1/models")`, the path as the backend will see it; for a
- destination outside the mesh it adds `host(...)` and `port(...)`.
+ destination outside the mesh (`egress://`) it adds `host(...)` and
+ `port(...)`.
2. **The baseline checks**: `client_peer_id($id), connection_peer_id($id)`
(the token belongs to the peer that presents it), and the expiration
check against the current time.
3. **The node's own identity facts**, taken from its own credential, as
`target_fact("group", "dev-nodes")` and similar. The caller's
- `allowed_targets` are matched against these facts. The destination node
- proves that it is an intended target; the origin node does not check its
- own traffic.
+ `allowed_targets` are matched against these facts.
4. **The node's local rules**, from the `attenuation` block of its
configuration file: extra facts, extra checks, and `allow` and `deny`
policies.
@@ -138,43 +153,63 @@ Biscuit authorizer and adds the following, in this order:
Biscuit evaluates every `check` and requires all of them to pass. It then
walks the policies in order and applies the first `allow` or `deny` that
-matches. As a result, a failing check denies the request regardless of any
-policy. A local `deny` placed before the baseline `allow` overrides a grant.
-A local `allow` can admit a caller that the policy did not grant, but it can
-never admit a caller that fails a check.
-
-Before any of this, the connection itself is gated. A peer on the ban list is
-dropped at the transport layer, and a peer whose credential does not verify
-under a trusted signing key cannot name a service at all.
-
-## Why a caller cannot forge a fact
-
-Two kinds of fact meet in the authorizer. The facts in the credential's
-authority block were written and signed by the control plane: roles,
-grants, labels, the peer the token is bound to. The facts about the request
-(`service`, `method`, `path`, `host`, `port`, `agent`, `connection_peer_id`,
-`time`) are added by the node that received the request, from what arrived
-on the wire. A caller writes neither. It cannot change the authority block
-without breaking the signature, and it cannot put a fact into the request
-set because the node computes that set itself.
-
-Biscuit does let a holder append a block to a token. That is how a token is
-attenuated: a holder can add a check that narrows what the token does. The
-facts of an appended block are visible only to that block's own checks and
-never to the authorizer's policies, so an appended `role("admin")` grants
-nothing. `internal/identity`'s
-`TestAttenuationBlockFactsAreInvisibleToTheAuthorizer` pins this, and nodes
-refuse an inbound token that carries appended blocks at all.
-
-This is what lets the policy grow without a schema change. A requirement
-that needs a new dimension is a new fact or a new rule, written in the same
-language that the existing grants compile to. A role's `custom_datalog` can
-mint `tier("contractor")` into every holder's credential, a node's
-`attenuation` can then say `deny if tier("contractor"), method($m), !($m == "GET")`,
-and neither `PolicyRole` nor any wire message changed. The structured fields
-(`allowed_services`, `allowed_agents`, `http`, ...) are the common cases,
-compiled to Datalog by the control plane; `custom_datalog` and
-`attenuation` are the same engine written by hand.
+matches.
+
+### Stage 2: Task authorization rules (`tar_block` 1..k)
+
+If the Biscuit carries appended blocks (`1..k`, up to `MaxAttenuationBlocks = 8`),
+`UnmarshalInbound` verifies before building the authorizer that every appended
+block has **0 rules, 0 checks, and 1 `tar_block("<base64url-proto>")` fact**.
+After Stage 1 succeeds, the verifier evaluates the decoded
+`TaskAuthorizationRule` chain against the request:
+
+- The current time must be strictly before every block's `expire_time` (when
+ set).
+- In **every** appended `TaskAuthorizationRule` block, at least one `TaskRule`
+ must match the request's `service`, HTTP `method` and `path` (when
+ `allowed_methods` or `allowed_paths` are non-empty), and MCP tool name on
+ `tools/call` (when `allowed_tools` is non-empty).
+
+Because every block must match, appending a new `tar_block` at a sub-agent hop
+computes the **intersection** ($\text{Standing Policy} \cap \text{TAR}_1 \cap \dots \cap \text{TAR}_k$)
+and can never widen authority.
+
+## Why a caller cannot forge a fact or smuggle Datalog
+
+Two kinds of Datalog fact meet in the authorizer. The facts in the
+credential's authority block were written and signed by the control plane:
+roles, grants, labels, and `client_peer_id`. The facts about the request
+(`service`, `method`, `path`, `host`, `port`, `connection_peer_id`, `time`)
+are added by the node that received the request, from what arrived on the
+wire. A caller writes neither.
+
+When a holder attenuates a token by appending a block, SAM never evaluates
+holder-authored Datalog rules or checks. Appended blocks are restricted to a
+single `tar_block("<base64url-proto>")` fact, which is invisible to Block 0's
+Datalog rules and is evaluated by the verifier's own `TaskAuthorizationRule`
+matcher. This guarantees that:
+
+1. An untrusted holder cannot trigger expensive Datalog backtracking via
+ crafted `check if` queries.
+2. The `TaskAuthorizationRule` enforced by the mesh PEP is byte-for-byte
+ identical to the rule intersected by `CloudTokenExchanger` at egress.
+
+## Workloads and agents acting through a node or gateway
+
+When multiple workloads, users, or sandboxed agents share a `sam-node` (or
+call through `agentgateway` / Istio), they do not share the node's own
+permissions:
+
+- On `/mcp` and `/v1/*` (or via RFC 8693 `POST /oauth/token` and Envoy
+ `ext_authz` / `ext_proc`), the caller presents its own platform JWT (OIDC ID
+ token, Kubernetes projected SA JWT, SPIFFE JWT-SVID, or Istio mTLS XFCC
+ identity) or a task-attenuated Biscuit.
+- `sam-node` exchanges platform JWTs via `POST /token/exchange` into a
+ **Delegated Session Biscuit** carrying the caller's own `user()`, `email()`,
+ `group()`, and `role()` facts, bound to the node via `client_peer_id()` and
+ `actor_node()`.
+- The destination node authorizes the request against the caller's delegated
+ Biscuit and its `tar_block` chain, never the origin node's own roles.
## Local rules
@@ -185,18 +220,19 @@ of what the mesh policy grants:
```yaml
attenuation:
rules:
- - 'maintenance() <- time($t), $t > 2026-12-31T00:00:00Z;'
+ - 'maintenance(true) <- time($t), $t > 2026-12-31T00:00:00Z;'
checks:
- 'check if label("jurisdiction", "eu");' # every caller must carry this label
policies:
- 'deny if service("mcp", "db-writer"), group("contractors");'
- - 'deny if maintenance();'
+ - 'deny if maintenance(true);'
```
`rules` derive new facts, `checks` must all hold, and `policies` are
-evaluated before the baseline policies. A syntax error in any of them stops
-the node at start, so a broken rule cannot weaken the node without notice.
-The mobile app has the same block, with the same syntax, in its settings.
+evaluated before the baseline policies. Every predicate in Datalog carries at
+least one term (presence-only facts are written `name(true)`). A syntax error
+in any statement stops the node at start, so a broken rule cannot weaken the
+node without notice.
## Labels
@@ -226,27 +262,18 @@ Labels are used in three places:
The header and the operator floor follow the same matching rule: a map of
`key=value` pairs, one value per key, and the provider must attest every
pair. Listing more pairs narrows the set of acceptable providers, as it does
-in a Kubernetes label selector or a Prometheus matcher. A list of pairs does
-not express alternatives for one key. Labels seen in discovery results are
-only used to rank candidates. The only labels that authorize anything are
-the signed ones in a credential.
-
-## Agents acting through a node
-
-A node may forward requests on behalf of a sandboxed agent and name that
-agent to the destination. The name travels next to the token, not inside it.
-The destination accepts the name only if the calling node's credential
-grants that agent namespace through `allowed_agents`. A node with no such
-grant cannot name any agent. This is attribution, not proof, and that is why
-the namespace belongs to the node's role and not to the agent. The
-[sandboxed agents preview](../../preview/sandboxed-agents/) has the details.
+in a Kubernetes label selector or a Prometheus matcher. Labels seen in
+discovery results are only used to rank candidates. The only labels that
+authorize anything are the signed ones in a credential.
## See also
- [Policy reference](../../reference/policy/): every field, pattern and fact
name.
+- [Agent architecture](../../preview/agent-architecture/): `TaskAuthorizationRule`
+ (`tar_block`), `CloudTokenExchanger`, and gateway integration.
- [Node configuration reference](../../reference/node-config/): the
`attenuation`, `labels` and `egress` blocks.
- [Reaching services outside the mesh](../../guides/egress-destinations/):
- the node as a policy enforcement point for an application's outbound
- HTTP calls.
+ the node as a policy enforcement point and credential broker for outbound
+ API calls.
diff --git a/site/content/docs/concepts/identity.md b/site/content/docs/concepts/identity.md
index a31b3f6f..4e374482 100644
--- a/site/content/docs/concepts/identity.md
+++ b/site/content/docs/concepts/identity.md
@@ -5,9 +5,12 @@ weight: 2
---
Every participant in a mesh, node or router, has a key that it generated
-itself and a credential that the control plane issued for that key. This page
-follows the credential from enrollment to expiry: how a node gets it, what it
-contains, how it is renewed, and how it is revoked.
+itself and a credential that the control plane issued for that key. Callers
+that reach the mesh through a node (workloads, users, and sandboxed agents)
+exchange their platform JWTs into delegated credentials bound to that node's
+channel, and narrow them offline per task. This page follows credentials from
+enrollment and exchange to attenuation, outbound federation, renewal, and
+revocation.
## Keys and peer IDs
@@ -63,9 +66,9 @@ mints a credential:
is registering.
2. Neither the peer ID nor the identity behind it is banned.
3. The identity resolves, through the bindings in the mesh policy, to the
- role being requested. `sam-node` requests `sam:role:node`, `sam-router`
- requests `sam:role:router`, and `sam-box` requests `sam:role:sambox`. If
- the policy binds nobody to `sam:role:node`, no node can enroll.
+ role being requested. `sam-node` requests `sam:role:node` and `sam-router`
+ requests `sam:role:router`. If the policy binds nobody to `sam:role:node`,
+ no node can enroll.
4. Every label the node declared is permitted by the `allowed_labels` of a
role it holds. A role without `allowed_labels` permits no labels.
@@ -77,11 +80,19 @@ that issued it.
## The credential
-The credential is a [Biscuit](https://www.biscuitsec.org/), a signed
-authorization token. Its authority block holds facts written in Datalog, a
-small logic language in which a fact looks like `role("sam:role:node")`. The
-block is signed by the control plane's Ed25519 key. Any node with the public
-key can verify it without contacting anyone. The block contains:
+Inside the mesh, every credential is a [Biscuit](https://www.biscuitsec.org/),
+a signed authorization token. Its authority block (Block 0) holds facts
+written in Datalog, a small logic language in which a fact looks like
+`role("sam:role:node")`. The authority block is signed by the control plane's
+Ed25519 key. Any node with the public key can verify it without contacting
+anyone.
+
+The control plane mints two kinds of Biscuits:
+
+### 1. Member Biscuit (`POST /register`, `POST /enroll`, `POST /refresh`)
+
+Issued to an enrolled node, router, or native SDK peer. Its authority block
+contains:
| Fact | Meaning |
|---|---|
@@ -90,27 +101,79 @@ key can verify it without contacting anyone. The block contains:
| `role("sam:role:node")`, `role("developer")` | The roles the identity resolved to, one fact each. |
| `user("...")`, `email("...")`, `group("...")`, `idp_role("...")` | Claims copied from the OIDC token: subject, verified email, each group, each entry of the issuer's `roles` claim. Absent for bootstrap enrollments. |
| `label("region", "eu")` | One fact per declared and permitted label. |
-| `granted_service_*`, `granted_target_*`, `granted_agent_*` | What the roles allow, compiled from `allowed_services`, `allowed_targets` and `allowed_agents`. [Authorization](../authorization/) describes them. |
+| `granted_service_*`, `granted_target_*` | What the roles allow, compiled from `allowed_services` and `allowed_targets`. [Authorization](../authorization/) describes them. |
The node does not set any of these facts. Roles come from the bindings in
the mesh policy, not from the identity provider: an issuer's `roles` claim
is stored as `idp_role()`, which grants nothing by itself. Labels are the
ones the node asked for and the policy allowed. Grants come from the policy.
-Tokens carry no appended blocks. Biscuit lets a holder attenuate a token by
-appending blocks, but SAM verifiers reject any token that has one. A request
-that needs to carry an extra claim (for example, which agent a node is acting
-for) sends it next to the token instead.
+### 2. Delegated Session Biscuit (`POST /token/exchange`, `/oauth/token`)
+
+When a workload or user calls through an enrolled `sam-node` (or an Envoy /
+Istio / `agentgateway` proxy integrated with `sam-node`), the node exchanges
+the caller's platform JWT (OIDC ID token, Kubernetes projected SA JWT, or
+SPIFFE JWT-SVID) at `POST /token/exchange` on the control plane. The control
+plane verifies the node's credential and proof-of-possession signature,
+validates the caller's `subject_token`, resolves the caller's roles against
+the mesh policy, and mints a short-lived Delegated Session Biscuit with zero
+database writes:
+
+- `client_peer_id("12D3KooW...")` and `actor_node("12D3KooW...")` bind the
+ token to the origin node's transport channel so only that node can present
+ it over libp2p, and record the acting node for audit logs and outbound STS.
+- **No `node()` fact is minted**, so `node:<peer_id>` bindings on the origin
+ node never leak to the delegated caller.
+- `user("...")`, `email("...")`, `group("...")`, `idp_role("...")`, and
+ `role("...")` reflect the caller's verified identity and resolved roles.
+
+## Task attenuation (`tar_block`) and sealing
+
+Before starting a task or delegating to a sub-agent, any holder (`sam-node`,
+an orchestrator via `POST /oauth/token`, or an SDK caller via
+`session.attenuate(rule)`) can narrow a Biscuit offline by appending up to 8
+blocks.
+
+Each appended block (`block_idx >= 1`) carries zero Datalog rules, zero Datalog
+checks, and exactly one fact:
+
+```datalog
+tar_block("<base64url-serialized api.TaskAuthorizationRule>")
+```
+
+Every verifier decodes the `TaskAuthorizationRule` chain and requires the
+request to satisfy both Block 0's standing Datalog policy and every appended
+`TaskAuthorizationRule` block (strict intersection across hops). For untrusted
+leaf sandboxes, the holder calls `Seal()` (`session.seal()` or `seal=true` on
+`POST /oauth/token`), which discards the ephemeral next-block key so no
+further blocks can be appended.
+
+## Outbound federation: the control plane as OIDC issuer
+
+External cloud providers do not accept Biscuits, and SAM never forwards a
+caller's mesh token to an upstream API. Instead, the control plane acts as a
+standard OIDC issuer (`/.well-known/openid-configuration` and `/jwks`, signed
+with ES256).
+
+When an egress node serves a destination configured with `oidc_federation` or
+`aws_assume_role`, it verifies the caller's Biscuit and `tar_block` chain and
+calls `POST /sts/token` on the control plane. The control plane re-verifies
+the token and mints a short-lived ES256 border JWT (`sub` = caller principal,
+`act.sub` = egress node peer ID, `aud` = destination audience, `sam_roles` =
+caller mesh roles, `sam_task` = innermost task name), which the egress node
+exchanges at the cloud provider's STS endpoint (such as Google Workload or
+Workforce Identity Federation or AWS `AssumeRoleWithWebIdentity`).
## Lifetime and refresh
-A credential is valid for `--biscuit-ttl`, 24 hours by default. If the OIDC
-token expires sooner, the credential expires with it. Nodes and routers check
-every ten minutes, and when less than a fifth of the lifetime remains they
-call `POST /refresh` with the current token and a signature over a fresh
-challenge. The control plane verifies both, resolves the identity's roles
-against the current policy again, and mints a new token with the same
-identity facts and labels.
+A Member Biscuit is valid for `--biscuit-ttl`, 24 hours by default (or the
+OIDC token's expiry if sooner). Delegated Session Biscuits default to 1 hour
+(bounded by the subject JWT's expiry and any `TaskAuthorizationRule.expire_time`).
+Nodes and routers check their Member Biscuit every ten minutes, and when less
+than a fifth of the lifetime remains they call `POST /refresh` with the
+current token and a signature over a fresh challenge. The control plane
+verifies both, resolves the identity's roles against the current policy again,
+and mints a new token with the same identity facts and labels.
Refresh is limited by the **session**, which is a record on the control
plane, not a field in the token. The session of an OIDC enrollment lasts
@@ -125,16 +188,16 @@ any user action.
## Signing keys and rotation
-The control plane rotates its signing key every `--key-rotation-interval`
-(24 hours by default). The previous key stays valid for `--key-grace-period`
-(1 hour by default) and is then retired. `GET /keys` returns the current set
-of keys, signed by each key in the set. Routers poll it every
-`--keys-sync-interval`; nodes fetch it at enrollment and then every
-`--control-plane-sync-interval`, together with the ban set and the mesh
-policy. A rotation event only brings the next pull forward. Both accept a
-new set only if one of its signatures verifies under a key they already
-trust. The first key comes from enrollment, and each later key is vouched
-for by the key it replaces.
+The control plane rotates its Biscuit Ed25519 signing key every
+`--key-rotation-interval` (24 hours by default). The previous key stays valid
+for `--key-grace-period` (1 hour by default) and is then retired. `GET /keys`
+returns the current set of keys, signed by each key in the set. Routers poll
+it every `--keys-sync-interval`; nodes fetch it at enrollment and then every
+`--control-plane-sync-interval`, together with the ban set, revocation list,
+and the mesh policy. A rotation event only brings the next pull forward. Both
+accept a new set only if one of its signatures verifies under a key they
+already trust. The first key comes from enrollment, and each later key is
+vouched for by the key it replaces.
Nobody can verify a credential signed by a retired key, including the
control plane. A node that was offline for a whole grace period therefore
@@ -154,14 +217,24 @@ depends on how it enrolled:
## Revocation
-`POST /admin/revoke` with a peer ID (or `sam-one admin ban`, or the console)
-marks the node as banned. Its next refresh is refused and the node daemon
-exits. The control plane publishes the peer ID in `/info`, which routers and
-nodes read, so peers stop accepting connections from it before its current
-token expires. If the node was enrolled through OIDC, the identity behind it
-(`issuer|subject`) is banned too. It can no longer register a new key, and
-bootstrap tokens it minted stop working. `POST /admin/nodes/{peer_id}/unban`
-reverses both bans.
+Revocation operates at two levels:
+
+1. **Mesh-wide node, identity, and root-prefix Biscuit revocation:**
+ `POST /admin/revoke` with a peer ID (or `sam-one admin ban`, or the console)
+ marks the node as banned. Its next refresh is refused and the node daemon
+ exits. The control plane publishes banned peer IDs in `/info` and
+ `GET /revocations`, together with revoked root Biscuit revocation IDs
+ (`RevocationIds()[0]`). Because every offline-attenuated child Biscuit
+ shares the root authority block's `RevocationIds()[0]`, revoking the root
+ credential invalidates every attenuated task token derived from it across
+ the mesh. If the node was enrolled through OIDC, the identity behind it
+ (`issuer|subject`) is banned too. `POST /admin/nodes/{peer_id}/unban`
+ reverses both bans.
+2. **Local task token revocation (`POST /oauth/revoke`):**
+ When an orchestrator or sandbox finishes a task before its TTL expires, it
+ calls `POST /oauth/revoke` (RFC 7009) on the local `sam-node`, which records
+ the leaf token's `RevocationIds()[last]` in its local revocation cache until
+ the token's `expire_time`.
A bootstrap token can be revoked before it expires with
`DELETE /admin/bootstrap-tokens/{id}`. The token stays in the list, marked
@@ -174,14 +247,17 @@ peer ID in a request body is otherwise only a claim. On the mesh, the libp2p
secure channel already proves which key is on the other end, so the handshake
between two nodes is simpler. Each side sends its credential. Each side
verifies the other's signature and expiry, checks that the credential's
-`node()` fact matches the authenticated peer, and checks the ban list. Only
-then is the requested service name evaluated against policy. Routers perform
-the same handshake on every connection they accept, so a banned or unenrolled
-peer cannot reach the DHT.
+`node()` fact matches the authenticated peer, and checks the ban and
+revocation lists. On per-request streams, the destination node verifies either
+the caller's Member Biscuit or a Delegated Session Biscuit whose
+`client_peer_id()` matches the authenticated connection peer, and then
+evaluates standing Datalog policy and any appended `tar_block` chain.
## See also
- [Headless enrollment](../../guides/headless-enrollment/) for the bootstrap
token workflow step by step.
+- [Agent architecture](../../preview/agent-architecture/) for the two-token
+ STS model and task attenuation.
- [Control plane reference](../../reference/control-plane/) for the flags
and HTTP routes named here.
diff --git a/site/content/docs/contributing/_index.md b/site/content/docs/contributing/_index.md
index 2fd563f6..2a7e23b2 100644
--- a/site/content/docs/contributing/_index.md
+++ b/site/content/docs/contributing/_index.md
@@ -18,9 +18,9 @@ in the repository has the details.
| Path | Contents |
|---|---|
-| `cmd/` | One directory per binary: `sam-node`, `sam-control-plane`, `sam-router`, `sam-one`, `sam-console`, `sam-box`, `nano-init`, `mcp-client`, and smaller tools. |
+| `cmd/` | One directory per binary: `sam-node`, `sam-control-plane`, `sam-router`, `sam-one`, `sam-console`, `mcp-client`, `sam-bench`, and smaller tools. |
| `api/` | The wire contract: `sam.proto` and its generated code, plus the Go types for the JSON admin API and the validation and Datalog helpers both sides share. |
-| `internal/` | Implementation, one package per component (`node`, `controlplane`, `router`, `standalone`, `console`, `sambox`, `identity`, `storage`, ...). |
+| `internal/` | Implementation, one package per component (`node`, `controlplane`, `router`, `standalone`, `console`, `identity`, `storage`, ...). |
| `charts/` | The `sam-mesh` and `sam-node` Helm charts. |
| `tests/integration/` | Go tests that start several components in one process. |
| `tests/e2e/` | Bats tests that drive the built binaries and containers. |
@@ -29,9 +29,9 @@ in the repository has the details.
Two rules from `AGENTS.md` shape most changes. Components talk to each other
only through `api/sam.proto` (protobuf for anything a mesh component speaks,
-JSON types in `api/` for the operator API). And no new module may be added
-to `go.mod` without discussion. Guest-only code such as `nano-init` lives in
-its own module for that reason.
+protojson of the same messages for the operator API). And no new module may be
+added to `go.mod` without discussion. Conformance harnesses with external gRPC
+dependencies such as `tests/extproc/` live in their own module for that reason.
## Build
diff --git a/site/content/docs/guides/egress-destinations.md b/site/content/docs/guides/egress-destinations.md
index ad330a73..292b36ee 100644
--- a/site/content/docs/guides/egress-destinations.md
+++ b/site/content/docs/guides/egress-destinations.md
@@ -130,9 +130,10 @@ headers (`Authorization`, `Cookie`, `X-*`). A `403` is a policy decision; a
answer the destination sent.
Every decision, allowed or denied, is one `Audit Traceability` line in the
-node's log with the peer, the role, the agent, the method, the path, the
-host and the port policy saw, and the decision. That line is the audit
-trail of the PEP; the destination's own logs see only the node.
+node's log with the peer, the role, the method, the path, the host and the
+port policy saw, and the decision. That line is the audit trail of the PEP;
+the destination's own logs see the brokered credential (or the federated
+principal when `oidc_federation` or `aws_assume_role` is configured).
The node's `/metrics` endpoint counts the same events, so you can alert
without reading logs:
@@ -146,9 +147,9 @@ without reading logs:
the node serves right now. A `refused` assignment or a `credential_unavailable`
decision means the platform did not deliver a credential the policy names.
-A client that names the agent it acts for sends `X-Sam-Agent`. The claim is
-checked against the node's `allowed_agents` grant and reaches policy as
-`agent()`, as it does on every other path.
+A caller that wants to narrow a request to a single task presents a
+task-attenuated Biscuit (`tar_block`), which the egress node evaluates after
+standing Datalog policy.
## What another mesh member does
@@ -180,14 +181,14 @@ attenuation:
## Limits
-- The node is the HTTP origin. A method and path decision needs the request
- in the clear, which is the case here because the application talks plain
- HTTP to the node. A tunnel the node opens without terminating HTTP carries
- `method("CONNECT")` and an empty path, so a grant narrowed to methods or
- paths denies it.
+- The node is the HTTP origin for `EGRESS_MODE_HTTP` destinations. A method
+ and path decision needs the request in the clear, which is the case here
+ because the application talks plain HTTP to the node. A TCP tunnel
+ (`mode: EGRESS_MODE_TCP`) carries `method("CONNECT")` and an empty path, so
+ a grant narrowed to HTTP methods or paths denies it.
- The path is a prefix under the destination. A client that follows
absolute URLs returned by the destination (a `Link` header, a URL in a
body) leaves the node. Use a client that takes a base URL, or point it
back at the prefix.
-- One destination is one hostname. A wildcard destination and a destination
- reached by `CONNECT` from a sandbox are not part of this release.
+- One destination is one hostname. Wildcard egress destinations are not
+ supported.
diff --git a/site/content/docs/guides/native-sdks.md b/site/content/docs/guides/native-sdks.md
index 584c40b0..fb9dd4c1 100644
--- a/site/content/docs/guides/native-sdks.md
+++ b/site/content/docs/guides/native-sdks.md
@@ -973,8 +973,9 @@ a TLS-terminating edge, with Node members calling it and being called.
- They do not publish services. An MCP server, a model or an agent that
others should find by name runs behind a `sam-node`, which publishes it
to the discovery table and reports it to the console.
-- They do not run a sidecar API or a sandbox. An agent that needs the egress
- policy enforcement of `sam-box` runs beside a `sam-node`.
+- They do not run a local HTTP/gRPC gateway or credential broker. A workload
+ that needs `ext_authz`, `ext_proc`, RFC 8693 `/oauth/token`, or cloud egress
+ credential brokering runs beside a `sam-node`.
- They do not serve the discovery table. A member is a client of it; the
routers hold the records.
- The Python SDK does not run in a browser; the JS SDK does, see
diff --git a/site/content/docs/preview/agent-architecture.md b/site/content/docs/preview/agent-architecture.md
index 7a8b679e..42a785f0 100644
--- a/site/content/docs/preview/agent-architecture.md
+++ b/site/content/docs/preview/agent-architecture.md
@@ -6,476 +6,239 @@ aliases:
- /docs/agent-architecture/
---
-{{% alert title="Preview" color="warning" %}}
-This is the design behind [sandboxed agents](../sandboxed-agents/). The
-decisions here are settled; the interfaces that implement them are still
-being shaped, and the last section lists what is not built yet.
-{{% /alert %}}
-
-This page explains how an unmodified agent, running inside a sandbox with no
-network of its own, is connected to the mesh. It covers the layers, the
-reasons for each layer, the contracts between them, and the limits of what
-the design guarantees. The [scale report](../scale-report/) measures what
-the result costs.
-
-## Goals
-
-1. **The harness is unmodified and does not know about the mesh.** It opens
- ordinary sockets, resolves ordinary names and speaks ordinary HTTP. It
- needs no SDK, no `LD_PRELOAD`, and no proxy variables.
-2. **One enforcement point.** Every flow that the sandbox emits is authorized
- in exactly one place, by name, against one policy.
-3. **The sandbox has no network.** This means no network device other than
- the one the design gives it, and not a filtered network. Isolation is a
- property of the runtime and not of a firewall rule.
-4. **The mesh looks like the internet.** Reaching a mesh model or tool is the
- same operation as reaching `api.github.com`: connect to a name. Which
- names are internal to the mesh is a policy decision on the host, not a
- code path in the agent.
-5. **No new dependencies on the host.** The guest-side network stack lives in
- its own Go module.
-
-## Why one enforcement point
-
-There are three common ways to intercept a sandbox's traffic at the
-application layer. Each of them requires the agent to cooperate with its own
-confinement:
-
-- **Proxy environment variables** are honoured only by HTTP-aware clients. A
- raw socket, a library with `trust_env=False`, gRPC or Postgres bypass
- them.
-- **DNS spoofing** forces every flow through an interception point and
- answers with loopback addresses. This destroys the destination name, which
- is what the policy engine needs to reason about.
-- **An `LD_PRELOAD` shim** must be built for each architecture and libc, and
- a statically linked binary bypasses it.
-
-An agent that has to agree to be confined is not confined. Routing does not
-have this problem, because nothing has to agree to a route. So the boundary
-is a route and a socket, and there is exactly one of them.
-
-## The layering
-
-```text
-┌─ sandbox (microVM, or container with network=none) ────────────────┐
-│ harness (unmodified: sockets, DNS, HTTP) │
-│ │ IP │
-│ tun0 ── default route, the only device besides lo │
-│ │ │
-│ nano-init / tun2connect ── IP flows → CONNECT (TCP), connect-udp │
-│ │ destination kept as a NAME (virtual DNS)│
-└──────┼─────────────────────────────────────────────────────────────┘
- │ one byte stream per flow
- │ microVM: AF_VSOCK → firecracker → host UDS <path>_<port>
- │ container: bind-mounted UDS
-┌──────┼─────────────────────────────────────────────────────────────┐
-│ host ▼ │
-│ sam-box (one per sandbox; no libp2p host, no enrollment) │
-│ = CONNECT server = the policy enforcement point │
-│ ├── mesh.sam.alt → /v1/* and /mcp only ──┐ │
-│ ├── <svc>.<type>.sam.alt → discover, then ├─▶ sam-node
-│ │ /sam/<peer>/<type>/… │ (UDS) │
-│ └── anything else → deny-by-default egress → internet│
-└────────────────────────────────────────────────────────────────────┘
-```
-
-### Named HTTP tunnels are the boundary protocol
-
-The boundary speaks authority-form `CONNECT` (RFC 9110) for TCP and
-connect-udp (RFC 9298, with capsules as in RFC 9297) for UDP, over a Unix
-socket. Four properties decided this choice over the alternatives (an earlier
-design used SOCKS5):
-
-- **It carries the destination name.** `CONNECT api.github.com:443`
- authorizes `api.github.com`, and not an address. connect-udp carries the
- name in its URI template. No DNS interception is needed, and there are no
- IP allowlists that go stale.
-- **It is protocol-agnostic.** After `200 OK` the tunnel is a byte pipe.
- HTTP is the handshake, and the payload can be any protocol.
-- **It has a vocabulary for refusals.** A denial is `403` with a
- `Boundary-Reason` header, which the guest stack turns into `ECONNREFUSED`.
- The agent sees a refused connection, and the operator reads the reason in
- words.
-- **Headers are the extension point, and one grammar serves both
- directions.** Ingress into a sandbox is `CONNECT <port>`. Sandbox identity
- for a boundary that serves many agents rides in `Proxy-Authorization`. UDP
- fits on the same stream as capsules. And `curl --proxy` speaks the TCP
- half, so the boundary can be tested with a tool that every operator has.
-
-### Names are resolved on the host, never in the guest
-
-The guest's virtual DNS answers every lookup with a synthetic address from
-pools that it invents: IPv4 from `100.64.0.0/10` (CGNAT space; link-local
-addresses would be safer against leaks, but SSRF guards in HTTP clients
-commonly block `169.254/16`), and IPv6 from `100::/64` (the RFC 6666 discard
-prefix, so a packet that escapes is dropped). The engine maps the address
-back to the name when the flow opens, and the boundary receives the name. A
-flow to an address that was never resolved has no name and is refused in the
-guest. There is no resolver path out of the sandbox, so there is no DNS
-exfiltration either.
-
-### The host never speaks AF_VSOCK
-
-Firecracker's vsock device terminates `AF_VSOCK` and gives the host a Unix
-socket per guest port, named `<uds_path>_<port>`. The boundary therefore
-always listens on a Unix socket, and a microVM and a `network=none`
-container are the same code path:
-
-| Sandbox | Guest side | Host side |
-|---|---|---|
-| Firecracker microVM | vsock CID 2, port *P* | listener on `<uds>_P` |
-| container, `network=none` | `/run/sam/agent.sock` | listener on the bind-mounted path |
+This page explains how SAM authenticates workloads and users, scopes authority
+to individual tasks and sub-agent hops, integrates with existing gateways and
+sandbox runtimes, and brokers short-lived credentials to external cloud APIs
+without placing standing cloud credentials inside the agent environment.
-This keeps vsock out of the Go code. More importantly, it makes the whole
-datapath testable in a Go integration test against a socket in a temporary
-directory, without a VM.
+## A courier network for tasks
-### A mesh name is the service namespace in DNS shape
+![The Agent Mesh as a courier network](/images/agent-mesh-courier.svg)
-The mesh's namespace is `mcp://<service>`, `inference://<service>`,
-`a2a://<service>` and `system://sam.catalog`. Sandbox names are a projection
-of it, declared once in `api/names.go` so that the boundary and the node
-cannot drift apart:
+SAM moves tasks between environments that trust nothing on arrival, the way a
+courier network moves parcels between post offices:
-```text
-inference://openrouter <-> openrouter.inference.sam.alt
-mcp://code-reviewer <-> code-reviewer.mcp.sam.alt
-(the mesh, curated) <-> mesh.sam.alt
+| In the picture | In SAM |
+|---|---|
+| **Parcel** | One request: an MCP tool call, a chat completion, a BigQuery query, an A2A message. |
+| **Sender** | The agent wherever it runs: a developer laptop, Kubernetes on premises or in a cloud, a SaaS platform, or a sandbox runtime. |
+| **Local post office** | The `sam-node` next to the agent, or the native SDK (`@sam-mesh/sdk`, `sam-mesh`) inside its process. It verifies the sender's platform credential and obtains a task waybill from the control plane. |
+| **Your gateway** | Istio, `agentgateway`, Envoy AI Gateway, or `kgateway` where a cluster already runs one. It stays in the data path and consults `sam-node` over Envoy `ext_proc`, `ext_authz`, or RFC 8693 `/oauth/token`. |
+| **Waybill** | The SAM Biscuit credential: who the subject is, through which actor node it travels, which roles it holds, and when it expires. |
+| **Stamp** | An offline attenuation block (`tar_block`) appended at a task or sub-agent hop. Each stamp carries a serialized `TaskAuthorizationRule` and can only narrow authority. |
+| **Sealed bag** | The mutually authenticated, encrypted libp2p stream between two nodes. Routers relay ciphertext across NATs, clusters, and clouds and cannot inspect it. |
+| **Registry** | `sam-control-plane`: verifies identities, issues Biscuits (`POST /token/exchange`), distributes Datalog policy, and acts as an OIDC issuer (`POST /sts/token`, `/.well-known/openid-configuration`, `/jwks`) for outbound cloud federation. |
+| **Destination office** | The serving or egress `sam-node` for `mcp://`, `inference://`, `a2a://`, or `egress://`: verifies the Biscuit and every `tar_block` stamp, runs content inspection, brokers the upstream credential, and delivers the request. |
+| **Customs** | Content inspection at the egress node: built-in policy facts, Google Cloud Model Armor, and Envoy `ext_proc` callout processors. |
+| **Permit** | The upstream destination credential: a federated cloud token exchanged via `CloudTokenExchanger` or a secret from the node's vault, never held by the agent. |
+| **Receipts** | Structured audit logs at the control plane, the origin and egress nodes, and the cloud provider, joined by principal and `sam_task`. |
+
+## Why workload identity alone is not enough
+
+In cloud and service-mesh architectures, permissions are granted ambiently to a
+workload identity (a Kubernetes Service Account, a cloud service account, or a
+SPIFFE SVID). Workload identity is necessary, but insufficient for AI agents:
+
+1. **One workload, many tasks.** A single agent service executes concurrent or
+ sequential tasks with different least-privilege boundaries (for example,
+ read-only access to `dataset_A` in one session and schema updates on
+ `dataset_B` in another). Workload identity proves *which container* is
+ calling, not *which task boundary* applies to this request.
+2. **Prompt injection and confused deputy.** If a session exercises the full
+ standing privileges of its workload or user identity, a prompt injection
+ during a narrow task can touch unrelated tools or datasets.
+3. **Multi-hop sub-agent delegation.** When an orchestrator delegates a
+ narrower sub-task to a sub-agent, it needs offline, progressive attenuation
+ (`Token_2 = Attenuate(Token_1, TaskRule)`) without minting a new identity at
+ the identity provider on every hop.
+
+SAM separates the two layers:
+
+| Layer | Question answered | Primitive |
+|---|---|---|
+| **Subject & channel attestation** | *Which user or workload initiated this request, and through which node?* | OIDC ID token, Kubernetes projected SA JWT, SPIFFE JWT-SVID, or Istio mTLS identity (`source.principal` / XFCC), exchanged into a Biscuit bound to the channel (`client_peer_id`, `actor_node`). |
+| **Task authorization (TAR)** | *What subset of standing permissions may this task or sub-agent hop exercise?* | Appended `tar_block` blocks carrying `api.TaskAuthorizationRule`, intersected across hops and translated into downscoped cloud credentials at egress. |
+
+## Separation of responsibilities
+
+OS and container confinement belongs to the sandbox platform (**Kubernetes
+`agent-sandbox`**, **NVIDIA OpenShell**, **Docker Sandbox `docker sbx`**).
+Local traffic interception belongs to the proxy (**`agentgateway`**, **Istio**,
+**Envoy**, or **`sam-node`**). SAM provides:
+
+- **`sam-control-plane`**: the mesh authority, Datalog policy distributor,
+ OAuth 2.1 Authorization Server, stateless token exchanger
+ (`POST /token/exchange`), and OIDC issuer (`POST /sts/token`) for cloud
+ federation.
+- **`sam-node`**: the Policy Decision Point (PDP), RFC 8693 Security Token
+ Service (`POST /oauth/token`), Envoy `ext_authz` and `ext_proc` server, mesh
+ router client, and egress credential broker.
+- **Native SDKs (`@sam-mesh/sdk`, `sam-mesh`)**: in-process mesh clients for
+ TypeScript and Python that enroll, open authenticated streams, verify peers,
+ and attenuate and seal task credentials in memory (`session.attenuate(rule)`,
+ `session.seal()`).
+
+## The two-token model: Biscuit inside, JWT at both borders
+
+Inside the mesh, every credential is a Biscuit. External identity providers and
+cloud APIs speak standard JWTs and OAuth 2.1 / RFC 8693. SAM translates at both
+borders:
+
+1. **Inbound border (`POST /token/exchange` on the control plane, `POST /oauth/token` on the node):**
+ The origin `sam-node` presents its own node Biscuit, a proof-of-possession
+ signature over `sam:token-exchange:<peer_id>:<challenge_unix_ms>`, and the
+ caller's `subject_token` (an OIDC JWT, Kubernetes projected SA token, or
+ SPIFFE JWT-SVID). The control plane verifies both, resolves the caller's
+ roles from the mesh policy, and mints a short-lived **Delegated Session
+ Biscuit** with zero database writes:
+ - `client_peer_id("<origin_peer_id>")` and `actor_node("<origin_peer_id>")`
+ bind the token to the origin node's transport channel without granting the
+ origin node's own `node:<peer_id>` roles to the caller.
+ - `user(...)`, `email(...)`, `group(...)`, `idp_role(...)`, and `role(...)`
+ carry the caller's verified identity and resolved roles.
+2. **In-mesh hops (offline `tar_block` attenuation):**
+ Before handing a token to a task runner or sub-agent, the holder appends a
+ `TaskAuthorizationRule` block (`tar_block("<base64url-proto>")`) offline and
+ optionally seals the token (`Seal()`) so downstream leaf processes cannot
+ append further blocks.
+3. **Outbound border (`POST /sts/token` + `CloudTokenExchanger`):**
+ When a request reaches an egress `sam-node` (`egress://<destination>`), the
+ node verifies the Biscuit signature, channel binding, standing Datalog
+ policy, and every appended `TaskAuthorizationRule`. On a cache miss for the
+ Biscuit digest, it calls `POST /sts/token` on the control plane, which
+ re-verifies the token and mints a short-lived **ES256 JWT** (`iss` = control
+ plane, `sub` = caller principal, `act.sub` = egress node peer ID, `aud` =
+ destination audience, `sam_roles` = caller roles, `sam_task` = innermost
+ task name). The egress node's `CloudTokenExchanger` exchanges that JWT at
+ the cloud provider's STS endpoint.
+
+## Safe Biscuit attenuation (`tar_block`)
+
+SAM never evaluates holder-authored Datalog rules or checks. In `biscuit-go`,
+Datalog `check if` queries are not bounded by rule-iteration limits, and
+allowing both Datalog checks and a serialized protobuf in an appended block
+would let a crafted token make the mesh PEP and the cloud STS adapter disagree.
+
+Instead, every appended block (`block_idx >= 1`, up to `MaxAttenuationBlocks = 8`)
+must contain:
+
+- **0 Datalog rules**
+- **0 Datalog checks**
+- **Exactly 1 fact:** `tar_block("<base64url-encoded api.TaskAuthorizationRule>")`
+
+All three verifiers (Go, TypeScript, and Python) enforce this structure before
+building the Datalog authorizer, decode the `TaskAuthorizationRule` chain in a
+single pass, and evaluate the rules directly in host code.
+
+### Positive allow-lists and intersection semantics
+
+`TaskAuthorizationRule` uses strictly positive allow-lists:
+
+- Within a single `TaskAuthorizationRule`, a request is permitted if it matches
+ **at least one** `TaskRule`. An empty `rules` list denies everything.
+- Across appended blocks `1..k`, semantics are **strict intersection (logical
+ AND)**: the request must be permitted by Block 0's standing Datalog policy,
+ arrive before every block's `expire_time`, and match at least one `TaskRule`
+ in **every** appended `TaskAuthorizationRule` block.
+
+Each `TaskRule` scopes:
+
+- `allowed_services`: service patterns (`mcp://bigquery`, `inference://gemini.*`,
+ `egress://bigquery.googleapis.com`).
+- `operation.allowed_tools`: MCP tool names enforced on `tools/call`.
+- `operation.allowed_methods` and `operation.allowed_paths`: HTTP methods and
+ exact or prefix (`/prefix/*`) paths.
+- `operation.allowed_permissions` and `allowed_resources`: cloud IAM
+ permissions and resource prefixes intersected across all hops and consumed by
+ `CloudTokenExchanger` at egress.
+
+## Gateway integration (`agentgateway`, Istio, Envoy)
+
+Where a cluster already runs Envoy, Istio, or `agentgateway`, `sam-node` acts
+as their external Policy Decision Point and Token Service over three standard
+interfaces:
+
+1. **Envoy `ext_authz` (`--ext-authz-addr`):** evaluates standing policy and
+ `tar_block` chains on incoming `CheckRequest` calls, accepts verified
+ SPIFFE principals from `AttributeContext.Source.Principal` or
+ `X-Forwarded-Client-Cert` (XFCC) on trusted proxy listeners, and injects
+ brokered upstream credentials (`Authorization: Bearer ...`,
+ `X-Sam-Principal`, `X-Sam-Task-Id`).
+2. **Envoy `ext_proc` (`envoy.service.ext_proc.v3.ExternalProcessor`):** the
+ body-aware counterpart to `ext_authz`. Because MCP tool names travel inside
+ the JSON-RPC request body (`params.name`), `ext_proc` inspects the buffered
+ body to enforce `operation.allowed_tools` and injects the brokered
+ credential only after the payload passes inspection.
+3. **RFC 8693 Token Exchange (`POST /oauth/token`) & OAuth 2.1:** accepts
+ `grant_type=urn:ietf:params:oauth:grant-type:token-exchange` with a JWT or
+ Biscuit `subject_token` and optional `TaskAuthorizationRule` (in `options`,
+ `scope`, or `resource`), returning a delegated or attenuated Task Biscuit.
+ Unauthenticated MCP clients receive RFC 9728 Protected Resource Metadata
+ (`/.well-known/oauth-protected-resource`) pointing to the control plane's
+ OAuth 2.1 Authorization Server (`/oauth/authorize`, `/oauth/token` with
+ PKCE).
+
+## Egress credential brokering, inspection, and TCP tunnels
+
+An `EgressDestination` in the mesh policy configures how selected egress nodes
+reach an external service:
+
+- **Credential brokers (`broker`):**
+ - `static_secret`: reads a secret file from `--secrets-dir` (`Bearer` token
+ or `user:pass` Basic auth).
+ - `oidc_federation`: mints a control-plane ES256 border JWT via
+ `POST /sts/token` and exchanges it at an RFC 8693 STS endpoint such as
+ Google Cloud Workload/Workforce Identity Federation
+ (`https://sts.googleapis.com/v1/token`), optionally impersonating a service
+ account (`impersonate`) with scopes narrowed by the TAR chain.
+ - `aws_assume_role`: exchanges the control-plane border JWT via AWS
+ `AssumeRoleWithWebIdentity`, compiling the intersected TAR permissions and
+ resources into an inline AWS session policy intersected with the configured
+ `session_policy` template.
+ - `platform_identity`: uses the egress node's ambient cloud identity (such as
+ GKE Workload Identity metadata tokens) narrowed by scopes.
+- **Content inspection (`inspection.inspectors`):**
+ Runs at the egress node *before* the broker injects the destination
+ credential, so inspectors never see upstream secrets:
+ - **Model Armor (`model_armor`):** calls `sanitizeUserPrompt` and (in
+ `BUFFERED` mode) `sanitizeModelResponse` for Gemini, OpenAI chat, MCP
+ `tools/call`, and A2A payloads, blocking findings with `403` and replacing
+ SDP de-identified text.
+ - **Envoy `ext_proc` (`ext_proc`):** streams headers, bodies, and trailers to
+ an external gRPC processor with `ProcessingRequest.attributes["sam"]`
+ populated (`principal`, `roles`, `actor_node`, `task`, `service`,
+ `destination`), while refusing any processor mutation to `Authorization`,
+ `Host`, `:authority`, or `X-Sam-*`.
+ - **Operator inspection chain (`preserve_host`, `forward_context`):** routes
+ through an explicit outbound proxy while preserving the destination `Host`
+ header and optionally forwarding `X-Sam-Principal`, `X-Sam-Roles`, and
+ `X-Sam-Task`.
+- **Named TCP tunnels (`mode: EGRESS_MODE_TCP`):**
+ For non-HTTP TLS protocols (PostgreSQL, Cloud SQL, AlloyDB, Redis, SSH), the
+ egress node exposes named `CONNECT host:port` tunnels and the local
+ `sam-node forward egress://<name>:<port> <local-addr>` port forwarder. The
+ egress node enforces the destination's `ports` allow-list and inspects the
+ TLS `ClientHello` before splicing, refusing connections whose SNI does not
+ match the authorized destination name or that hide the SNI with Encrypted
+ Client Hello (ECH).
+
+## Control-plane STS sizing
+
+`sam-node` caches exchanged Delegated Biscuits by `SHA-256(subject_jwt + tar)`
+and caches minted border JWTs and upstream cloud tokens by Biscuit digest,
+keeping the control plane off the per-request hot path. You can measure raw
+control-plane mint throughput and node cache hit rates on your hardware with:
+
+```bash
+sam-bench sts --requests 200 --concurrency 8 --warmup 10
```
-`.alt` is the pseudo-TLD that RFC 9476 reserves for names that are not
-resolved through the DNS. It cannot collide with a delegated TLD, and a name
-that escapes the sandbox fails closed. `.local` belongs to mDNS and was
-rejected.
-
-Provider selection is not part of the name. `openrouter.inference.sam.alt`
-says which service, never which peer. Pinning a peer would need a DNS-safe
-encoding of peer IDs (base58 is case-sensitive, DNS labels are not) and is
-deferred.
-
-### The agent is the principal, and the node is the channel
-
-Policy has to be able to say "agent `foo` may use `inference://X`, agent
-`bar` may not". The whole mesh has to be able to evaluate that statement, and
-it has to survive the agent being paused on one host and resumed on another.
-So agent identity travels with the agent and never with the host.
+On a standard development workstation (8 concurrent workers, SQLite store):
-A credential is bound to a peer ID, and a verifier checks that binding on
-every connection. That is right for the channel and wrong for the question
-"who is asking". The mesh already takes in a foreign identity once, at node
-enrollment, by verifying an OIDC token and translating claims into facts.
-Agents reuse that pattern one level down:
-
-| | Asserted by | Verified against | When | On the datapath as |
+| Phase | Throughput (req/s) | p50 Latency | p99 Latency | Cache Hit Rate |
|---|---|---|---|---|
-| node identity | control plane | the OIDC issuer | enrollment | a credential |
-| agent identity | the `sam-box` that admitted the agent | the platform's workload issuer | admission | a claim next to the credential |
-
-The claim travels next to the credential (`X-Sam-Agent` on HTTP, `agent` in
-the stream authentication frame), and not inside it. Biscuit lets a holder
-append blocks to a token, but a verifier evaluates the facts of an appended
-block only against that block's own checks, never against the authorizer's
-policy. This is intentional, because otherwise attenuation could grant
-instead of only narrow. `TestAttenuationBlockFactsAreInvisibleToTheAuthorizer`
-in `internal/identity` pins this behaviour. Carrying the claim in a header
-costs nothing cryptographically. Whoever can append a block can append any
-block, so a node's claim about which agent it speaks for is worth exactly
-what the node is worth, in either form.
-
-The remaining trust is this: an enrolled node asserts its own agents. Mesh
-policy limits this with the role's `allowed_agents`, the namespaces that a
-node may name. A node with no grant can name no agent. The grant is keyed on
-the node's role, which is resolved from verified claims against bindings
-that an administrator wrote. It is not keyed on the node's labels, which the
-node declares itself. Proof of possession by the agent would remove the
-remaining trust. It needs a signer inside the sandbox and third-party blocks
-in the Biscuit library, and it can be added later without a rewrite.
-
-## Where the boundary lives
-
-Two binaries with separate jobs. **`sam-node`** owns the libp2p host,
-enrollment, identity, discovery and the local API. **`sam-box`**, one per
-sandbox, owns none of those. It serves the tunnel boundary, enforces egress
-policy, and reaches the mesh only by dialling the node's API socket as a
-client.
-
-This split has several benefits. *N* sandboxes on a host share one libp2p
-host, so there are not *N* DHT clients, identify loops or router
-connections, which would otherwise limit density. `sam-box` is small: a
-CONNECT server and an HTTP client. A compromised sandbox affects only its
-own boundary, which can be killed and started again on its own. And the
-agent never touches the node's API socket. That matters because reaching
-the socket is itself a credential: the socket can proxy to any peer and
-service that the node's grants allow. `sam-box` is a client of the node. The
-agent is a client of the mesh, through `sam-box`.
-
-## Contracts
-
-### What the harness sees
-
-```text
-OPENAI_BASE_URL=http://mesh.sam.alt/v1
-MCP_URL=http://mesh.sam.alt/mcp
-```
-
-There is no proxy variable, no CA bundle and no token. A harness that wants
-one specific service instead of policy-chosen routing uses the service's
-mesh name: `http://code-reviewer.mcp.sam.alt/`. Mesh names use `http://` on
-purpose. The transport underneath is libp2p, which is already authenticated
-and encrypted, and plain HTTP avoids installing a CA in the guest.
-
-### Dispatch
-
-The boundary applies these rules to the tunnel's `(host, port)`, where
-`host` is the preserved name, in this order:
-
-1. **`mesh.sam.alt`**: the boundary's own surface, served in process:
- `/v1/models`, `/v1/chat/completions`, `/v1/completions`, `/mcp`. Any
- other path is `403` and never reaches the node. Discovery is not exposed
- here because MCP already provides it as tools.
-2. **`<service>.<type>.sam.alt`**: the boundary terminates HTTP, asks the
- node's `/sam/service/discover` for a provider, and reverse-proxies to
- `/sam/<peer>/<type>/<service>/<path>`.
-3. **Anything else**: the egress allowance from the bundle (or from
- `--egress-allow` for an unidentified sandbox). Allowed flows are dialled
- directly, by the name that was authorized. For TLS, the client's SNI must
- match that name.
-4. **No match**: `403 Boundary-Reason: not allowed by policy`.
-
-Only case 2 inspects the payload, and only because provider selection is an
-HTTP-level decision.
-
-### What a sandbox must provide
-
-`nano-init` builds the route out of a sandbox. It does not build the sandbox
-itself. Three runtimes are supported, and each must satisfy the same five
-preconditions:
-
-| Precondition | `docker --network none` | Firecracker | Kubernetes pod |
-|---|---|---|---|
-| a network namespace with no way out | the runtime | the guest kernel, given no NIC | **nothing provides it**; `nano-init --create-namespaces` builds it |
-| a private `resolv.conf` | the container's mount namespace | the guest rootfs | **nothing provides it**; mount one per container |
-| a Unix socket to the boundary | bind mount | vsock, exposed on the host as `<uds>_<port>` | shared `emptyDir` |
-| a way to create a TUN | `--device /dev/net/tun --cap-add NET_ADMIN` | `CONFIG_TUN` in the guest kernel | `hostPath` of type `CharDevice`, no capability |
-| PID 1 | the entrypoint | `/sbin/init` | the entrypoint |
-
-A pod shares one network namespace and one `resolv.conf` across its
-containers, so the sandbox has to create both for itself. It first creates a
-user namespace, in which it holds `CAP_SYS_ADMIN` and `CAP_NET_ADMIN` over
-what it creates next, so the container needs no capability. Granting
-`CAP_SYS_ADMIN` alone is worse than granting nothing: the namespace is
-created, and then the tun fails.
-
-This failure produces no error (`tun0` next to `eth0` is a working network),
-so `nano-init` refuses to start in a namespace that has any interface other
-than loopback and its own tun, whichever runtime is in use.
-
-## Agent identity
-
-### Requirements
-
-1. **Portable.** An agent paused on node A and resumed on node B is the same
- principal.
-2. **Verifiable across the mesh.** Any peer can decide "agent `foo` may,
- agent `bar` may not" without asking anyone.
-3. **Scalable.** There is no central per-agent record, no per-agent mint on
- the hot path, no list of agents in any policy, and no revocation list
- that grows with the agent population.
-
-### Why it scales
-
-**Admission is local.** The control plane never mints a credential per
-agent. It grants a node's role authority over an agent namespace once. The
-boundary then asserts a per-agent identity under that namespace, with no
-round trip and no central state.
-
-**Policy is written over namespaces.** The same machinery that compiles
-`allowed_services` wildcards compiles `allowed_agents` into
-`granted_agent_prefix`, `_suffix`, `_set` and `_exact`, and the destination
-derives `agent_authorized(true)` from them. "Foo yes, bar no" is a namespace, a
-set or a prefix, never a list of a billion names.
-
-**Revocation has three levels.**
-
-| What happened | Mechanism | Cost |
-|---|---|---|
-| the agent is done or misbehaving | kill the sandbox | instant, local |
-| its credential must stop working elsewhere | the platform stops renewing the short-lived workload credential | a bounded window, no list |
-| a node is compromised | ban the node | one entry ends every agent that it spoke for |
-
-### Where identity comes from
-
-Identity does not come from the agent, which is unmodified and could only
-lie about itself. It comes from the credential that the platform already
-issues to the workload: a Kubernetes projected service account token, a pod
-certificate, a SPIFFE SVID. `sam-box` verifies the credential against the
-issuer named by `--credential-issuer` and `--credential-audience` at
-admission, which is cheap and stays inside the cluster. It accepts the bundle
-only if the subject of the credential matches the bundle's `external_id`.
-The subject check is the important one. Every sandbox on a platform holds a
-valid credential, so a signature alone would let any sandbox claim to be any
-other. The issuer is a flag and not a bundle field, because the bundle
-travels with the agent.
-
-Verification is the default. `--insecure-unverified-bundle` runs without it,
-and the flag is visible in a process listing.
-
-The identity is then bound to the channel, so nothing is asserted in-band.
-By default there is one socket per agent, fixed when the sandbox is created.
-A boundary that serves many agents over one socket takes the agent id per
-connection in `Proxy-Authorization` Basic credentials.
-
-### The bundle
-
-What the platform provides per agent. It lives in the agent's own state
-directory, so it migrates with the agent:
-
-```yaml
-version: v1
-agent:
- id: reviewer-7.prod.acme.example # canonical mesh identifier
- external_id: spiffe://acme.example/prod/reviewer-7 # verbatim, for audit and the subject check
- credential: /var/run/secrets/platform/token # the platform's workload credential
-egress:
- allow: ["api.github.com", "*.pypi.org"]
-serves: # optional: the agent's own A2A service
- name: code-reviewer
- port: 8080
-```
-
-Parsing is strict. An unknown field is an error, because a typo that parsed
-as "absent" would give an agent broader access than intended.
-
-### The identifier
-
-The identifier is dot-separated and DNS-shaped, with the most specific label
-first: `reviewer-7.prod.acme.example`, matched by `*.prod.acme.example`. The
-policy engine decided this shape. Wildcards compile to facts that keep their
-anchoring dot, so `evil-acme.example` cannot match `*.acme.example`, and
-every other name in the system (services, mesh hosts) has the same shape.
-
-The identifier is a mesh convention, in the same way that `user`, `email`
-and `group` are. External systems do not adopt it. A connector translates
-into it, and the translation must be:
-
-1. **Total**: every foreign identity maps to exactly one identifier.
-2. **Injective**: no two foreign identities collide. The rightmost labels
- must be an authority that the platform controls.
-3. **Hierarchy-preserving**: boundaries in the foreign hierarchy land on
- dots, otherwise wildcard policy cannot express them.
-4. **Auditable**: the original travels unchanged as `external_id`.
-5. **Bounded**: the name includes a label for the boundary where the workload
- credential stops being valid, usually the cluster. Node grants are
- written against that label. A mapping without it forces tenant-wide
- grants.
-
-| Foreign identity | Mesh identifier |
-|---|---|
-| `spiffe://acme.example/prod/reviewer-7` | `reviewer-7.prod.acme.example` |
-| Kubernetes SA `prod/reviewer` in cluster `c1.acme.example` | `reviewer.prod.c1.acme.example` |
-| OIDC `iss=https://acme.example`, `sub=reviewer-7` | `reviewer-7.acme.example` |
-
-Attributes that are not hierarchical do not belong in the name. Attested
-labels exist for those.
-
-### What the claim covers
-
-The claim covers attribution and policy on both datapaths. A provider can
-authorize and audit "agent `reviewer-7` called me" over HTTP for inference
-and over the libp2p stream for tools, using the ordinary `agent()` fact. On
-the stream path the claim is bound to the MCP session instead of the
-request. This fits, because one boundary serves one agent, so a session
-belongs to one agent for its whole life.
-
-The claim is not a proof (it is the node's word, limited by
-`allowed_agents`), and it does not cover anything that never leaves the
-node. One consequence to design around: a node's own housekeeping carries no
-agent. A provider whose policy demands an agent unconditionally therefore
-also refuses that node's model-catalog probe, and its models disappear from
-the peers' `/v1/models` even though agents can still call them. Policy that
-intends to gate agent traffic should say so explicitly, instead of demanding
-an agent everywhere.
-
-## Agents that serve
-
-An agent serves exactly one thing: itself, over A2A. Tools and models are
-operator workloads declared in a node's configuration. An agent is not a
-generic backend.
-
-Nothing is registered at run time. A runtime declaration carries a name, so
-an agent could advertise itself as `code-reviewer` under the node's identity
-and take over someone else's traffic. If it could also give a URL, it could
-point the mesh anywhere. So the route is contracted before the agent runs:
-
-- The bundle's `serves` names the service and the port (like `$PORT` on a
- serverless runtime).
-- The node's configuration declares the `a2a` service with the boundary's
- ingress listener as its backend.
-- The node probes the agent's card through the boundary before it
- advertises the service, and keeps probing.
-
-Readiness is observed, never assumed. When the sandbox goes away, the probe
-fails and discovery converges. On resume on another host, the same bundle
-produces the same contract, and the probe points discovery at the new
-location.
-
-Inbound traffic is the one place where the datapath is not shaped like
-egress. The boundary cannot dial the agent, because the agent's loopback is
-inside its own namespace. So the way in mirrors the way out: a second Unix
-socket, served from inside by `nano-init --ingress-socket` and dialled by
-`sam-box --agent-ingress-socket`, with one stream per request
-(`CONNECT <port>`). This is the same handshake that Firecracker's vsock
-uses, so a microVM offers it without any change in the boundary.
-
-| Channel | Direction | Protocol | Who listens |
-|---|---|---|---|
-| egress | guest → host | CONNECT, connect-udp | host (`sam-box`) |
-| ingress | host → guest | `CONNECT <port>`, one stream per request | guest (`nano-init`) |
-
-Authorization needs nothing new. The caller's node authorized the caller,
-with its agent claim, before the stream reached the boundary. "Agent `foo`
-may call agent `bar`" is one policy statement, evaluated at the node of
-`bar`, with both ends named by portable identities.
-
-## The platform integration interface
-
-This is the interface that a scheduler builds against, and the only place
-where identity enters. It is small and versioned. It consists of the bundle
-above (YAML, with its canonical copy as a file in the agent's state) and
-four operations (`Attach`, `Detach`, `Refresh`, `Status`) whose request and
-response messages are defined in `api/sam.proto`.
-
-The interface gives a connector these guarantees:
-
-- `Attach` is idempotent by agent id, so resume after a crash or migration
- is another `Attach`.
-- Identity never arrives in-band from the sandbox.
-- The agent id is stable across `Attach` calls on different hosts.
-- `Detach` is complete, and leaves no advertisement behind.
-- The schema is versioned.
-
-## Not built yet
-
-- The control socket that serves the four operations. Today the bundle is a
- file read at start, and the lifecycle of the boundary is the lifecycle of
- the process.
-- Credential rotation (`Refresh`). The credential is verified once at start.
-- Secret injection for external destinations. The ephemeral CA and header
- rewriting exist in `internal/sambox` but are not on this datapath.
-- Peer-pinned mesh names, which need a DNS-safe peer ID encoding.
-- Bulk pre-creation of agents. `Attach` is idempotent per id, so an
- `AttachBatch` can be added later.
-
-## Testing
-
-Coverage sits as low in the test pyramid as possible. Unit tests cover the
-tunnel grammar, the capsule codec, name projection, dispatch classification
-and allowlist matching. Integration tests (`tests/integration/`, under ten
-seconds each) run the whole datapath without containers: nodes with fake
-backends, a `sam-box` on a socket in a temporary directory, real `CONNECT`
-tunnels, and assertions that mesh names reach the right peer, that allowed
-names reach a local server, that refused names get `403`, and that no path
-outside `/v1/*` and `/mcp` reaches the node. Two end-to-end tests exist: a
-`--network none` container with the real harness, and the same rootfs under
-Firecracker. The second is skipped without `/dev/kvm`, and it proves only
-the vsock mapping.
+| Uncached `POST /token/exchange` | ~2,090 req/s | 3.6 ms | 7.8 ms | 0% (uncached baseline) |
+| Uncached `POST /sts/token` (Datalog + TAR + ES256) | ~130 req/s | 61.0 ms | 68.4 ms | 0% (uncached baseline) |
+| Cached `ExchangeSubjectJWT` (5m SPIFFE JWT-SVIDs) | ~18,500 req/s | 0.02 ms | 7.7 ms | >91% (99.7% steady-state) |
+| Cached `ExchangeSubjectJWT` (1h K8s SA tokens) | ~19,500 req/s | 0.02 ms | 6.7 ms | >92% (99.97% steady-state) |
+| Cached `MintBorderJWT` (15m task Biscuits) | ~1,980 req/s | 0.002 ms | 54.7 ms | >92% |
diff --git a/site/content/docs/preview/sandboxed-agents.md b/site/content/docs/preview/sandboxed-agents.md
index f3a71ab2..ca8ad265 100644
--- a/site/content/docs/preview/sandboxed-agents.md
+++ b/site/content/docs/preview/sandboxed-agents.md
@@ -7,352 +7,255 @@ aliases:
- /docs/user/secure-gateway/
---
-{{% alert title="Preview" color="warning" %}}
-The sandbox works end to end and is exercised in CI, but `sam-box` flags,
-the bundle format and `nano-init`'s options may change between releases.
-{{% /alert %}}
+An autonomous agent runs untrusted or model-generated code and prompts. To run
+one safely, you need two things that work together:
-An agent is a harness, a model and some tools. To deploy one you normally
-ship all three, plus a key for the model, plus network access that is wide
-enough for whatever the tools turn out to need. On SAM you ship only the
-harness. The mesh provides the model and the tools by name, and the network
-the agent gets is a list of names that is checked on every connection.
+1. **OS and network confinement**, provided by a dedicated sandbox runtime
+ (NVIDIA OpenShell, Kubernetes `agent-sandbox` with gVisor or Kata, or Docker
+ Sandbox `docker sbx`), so the process can only talk to the local gateway.
+2. **Task-scoped authorization and credential brokering**, provided by SAM
+ (`sam-node` or `agentgateway` + `sam-node`), so the sandbox never holds a
+ standing cloud credential or ambient workload token and can only call the
+ services, MCP tools, HTTP paths, and cloud resources permitted for its
+ current task.
-The agent holds no credential. There is no API key, mesh token or service
-account file in the sandbox, and no proxy variable. An agent that holds a
-key can leak it, and an agent that can be talked into leaking a key will
-eventually do so.
+This page shows the four deployment blueprints for connecting sandboxed agents
+and multi-hop sub-agents to a SAM mesh.
-## The pieces
+## Blueprint 1: NVIDIA OpenShell (zero credentials inside the sandbox)
+
+NVIDIA OpenShell isolates untrusted agent processes using Landlock, seccomp,
+and network namespaces, routing all outbound HTTP through an external OpenShell
+egress proxy on the host that injects headers outside the sandbox boundary.
```mermaid
flowchart LR
- subgraph sandbox["sandbox: no NIC, no DNS, no credentials"]
- H["agent harness<br/>(your code)"]
- T["nano-init (PID 1)<br/>tun0 · userspace TCP · virtual DNS"]
- H -- "plain HTTP to mesh.sam.alt" --> T
+ subgraph OpenShell["NVIDIA OpenShell Sandbox (Landlock + seccomp + netns)"]
+ Harness["Unmodified Agent Process<br/>(Holds ZERO credentials)"]
end
- subgraph host["host"]
- B["sam-box<br/>one per agent<br/>holds no mesh identity"]
- N["sam-node<br/>one per host<br/>the mesh member"]
+ subgraph Host["Host / Orchestrator Boundary"]
+ OSProxy["OpenShell Egress Proxy<br/>& Secret Injector"]
+ SamNode["Local sam-node Gateway"]
end
- M(["the mesh"])
- T -- "named CONNECT tunnels<br/>over a Unix socket" --> B
- B -- "node API socket<br/>+ X-Sam-Agent" --> N
- N <--> M
- B -. "allowed names only" .-> E([internet])
-```
-
-**`nano-init`** is PID 1 inside the sandbox. It creates a `tun0` device,
-makes it the default route, and terminates the sandbox's TCP/IP in userspace
-(gVisor's netstack, through the `tun2connect` library). For each connection
-the agent opens, it opens one named HTTP tunnel to the boundary:
-`CONNECT host:port` for TCP and `connect-udp` for UDP. Its virtual DNS
-answers every lookup with a synthetic address (from `100.64.0.0/10` or
-`100::/64`) and remembers the pairing, so the tunnel carries the name that
-the agent asked for. An address that the agent never resolved has no name
-and is refused. `nano-init` also reaps orphan processes and forwards
-signals. It lives in its own Go module, because a userspace network stack
-does not belong in the dependency graph of the other binaries.
-
-**`sam-box`** is the boundary. There is one per agent, on the host side of
-the Unix socket. It has no libp2p host, no enrollment and no mesh identity.
-It is a client of the local `sam-node`'s API socket. For each tunnel it
-classifies the name and decides:
-
-| Name | Decision |
-|---|---|
-| `mesh.sam.alt` | The mesh surface: `/v1/models`, `/v1/chat/completions`, `/v1/completions`, `/mcp`. Any other path is `403`. |
-| `<service>.<type>.sam.alt` | One specific mesh service, `<type>` being `mcp`, `inference` or `a2a`: `code-reviewer.mcp.sam.alt`, `openrouter.inference.sam.alt`. Discovery chooses the provider. |
-| anything else | Matched against the agent's egress allowance. A name that is not in the allowance is refused. |
-
-A refusal fails the `CONNECT` with `403` and a `Boundary-Reason` header. The
-sandbox's network stack turns this into an ordinary connection reset. The
-agent sees a refused connection. The operator sees the reason in the
-boundary's log and metrics.
-
-**`sam-node`** is unchanged. It is the mesh member, one per host, and it
-holds the identity. Adding an agent costs one `sam-box`, and no new
-enrollment or new peer in the DHT.
+ Mesh(["SAM Mesh & Cloud Egress"])
-The split matters because reaching the node's API socket is itself a
-credential. The socket cannot register services (they are static), but it
-can call anything that the node's grants allow. So the agent never touches
-the socket. `sam-box` uses the node on the agent's behalf and offers the
-agent a narrower surface.
-
-## What the agent sees
-
-```python
-client = AsyncOpenAI(base_url="http://mesh.sam.alt/v1", api_key="unused")
-
-async with streamable_http_client("http://mesh.sam.alt/mcp") as (read, write):
- async with ClientSession(read, write) as session:
- await session.initialize()
- tools = await session.list_tools()
+ Harness -- "Plain HTTP to sam-node:8080/mcp & /v1" --> OSProxy
+ OSProxy -- "Injects X-Sam-Authentication:<br/>Bearer <Sealed-Task-Biscuit>" --> SamNode
+ SamNode -- "Verified Task Biscuit" --> Mesh
```
-These are ordinary SDK clients with nothing SAM-specific in them. The
-`api_key` is a placeholder that the SDK requires. The agent does not know
-which peer serves the model and cannot find out. Two agents behind the same
-node can see different tool lists, because the mesh answers according to who
-is asking. A refused tool call comes back as an error that the model can
-read, not as a crash.
-
-## Identity is asserted about the agent, not by the agent
-
-`sam-box` reads a **bundle** that the platform writes outside the sandbox:
+1. **Mint and seal a task token before starting the task:**
+ The orchestrator calls `POST /oauth/token` on the local `sam-node` with a
+ `TaskAuthorizationRule` (and `seal=true`), receiving a **sealed Task
+ Biscuit** scoped to the single task:
+ ```bash
+ TASK_TOKEN=$(curl -sS --unix-socket ~/.config/sam-mesh/sam.sock \
+ http://localhost/oauth/token \
+ -d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
+ -d 'subject_token_type=urn:sam-mesh:params:oauth:token-type:biscuit' \
+ -d "subject_token=$(jq -r .biscuit ~/.config/sam-mesh/credential.json 2>/dev/null || true)" \
+ -d 'seal=true' \
+ --data-urlencode 'options={"name":"tasks/pr-review-42","rules":[{"allowed_services":["mcp://github","inference://*"],"operation":{"allowed_tools":["get_pull_request","list_PullRequest_files"]}}]}' \
+ | jq -r .access_token)
+ ```
+2. **Register the sealed token in OpenShell's proxy:**
+ Configure OpenShell's secret injector to attach
+ `X-Sam-Authentication: Bearer $TASK_TOKEN` on requests to `sam-node:8080`.
+ The sandboxed process has no credential in its environment variables or
+ filesystem.
+
+## Blueprint 2: Docker Sandbox (`docker sbx`) & Kubernetes `agent-sandbox`
+
+In `docker sbx` (local microVM) and Kubernetes `agent-sandbox`
+(`RuntimeClass: gvisor` or `kata`) without an external header-injecting proxy,
+the sandbox container authenticates to `sam-node` using a task token passed as
+`OPENAI_API_KEY` / `Authorization: Bearer <token>` (for `/mcp` and `/v1/*`) or
+`X-Sam-Authentication: Bearer <token>` (for `/sam/*` and `/egress/*`).
+
+### How SAM bounds the token held by the sandbox
+
+1. **Sealed leaf token (`Seal()`):** The orchestrator hands the sandbox a
+ sealed, task-attenuated Biscuit. The sandbox cannot append blocks or widen
+ its permissions.
+2. **Channel binding (`client_peer_id`):** The Biscuit's authority block binds
+ `client_peer_id` to the local or cluster `sam-node`'s `peer_id`. If a
+ prompt-injected agent exfiltrates the token to an external attacker, the
+ token is rejected by every other node in the mesh because the attacker
+ cannot authenticate over libp2p as that `peer_id`.
+3. **Short TTL and explicit revocation on exit:** Scope the task's
+ `expire_time` to the expected task duration (for example, 15 minutes) and
+ revoke it on `sam-node` (`POST /oauth/revoke`) as soon as the sandbox exits:
+ ```bash
+ curl -sS --unix-socket ~/.config/sam-mesh/sam.sock \
+ http://localhost/oauth/revoke \
+ -d "token=$TASK_TOKEN"
+ ```
+4. **Standard Kubernetes isolation (`RuntimeClass: gvisor` + `NetworkPolicy`):**
+ No `/dev/net/tun`, `CAP_NET_ADMIN`, or custom PID 1 wrapper is needed. The
+ sandbox pod runs unprivileged under `gvisor` or `kata`, and a standard
+ Kubernetes `NetworkPolicy` restricts its egress to the cluster `sam-node`
+ (or `agentgateway`) Service:
```yaml
-version: v1
-agent:
- id: researcher-1.prod.acme.example
- external_id: system:serviceaccount:agents:researcher
-egress:
- allow:
- - api.github.com
- - "*.githubusercontent.com"
-serves:
- name: code-reviewer
- port: 8080
-```
-
-Writing that file is not enough to become that agent. `sam-box` verifies a
-platform credential (`--credential-issuer`, `--credential-audience`; on
-Kubernetes this is a projected service account token) and accepts the bundle
-only if the subject of the credential matches `external_id`. On every
-request it then names the agent to the node in the `X-Sam-Agent` header,
-replacing anything that the sandbox tried to set. The destination node
-accepts that name only if the calling node's credential grants the namespace
-through the role's `allowed_agents`. A node granted `*.c1.acme.example`
-cannot speak for `researcher-1.prod.acme.example`. The namespace belongs to
-the node and the identifier belongs to the agent. This is why an agent keeps
-its name when it is paused on one host and resumed on another.
-
-Wildcard egress entries match subdomains only: `*.pypi.org` matches
-`files.pypi.org`, but not `pypi.org` and not `evilpypi.org`. Matching uses
-the name that the agent asked for, never a resolved address.
-
-The issuer is a flag and not a bundle field on purpose. The bundle travels
-with the agent, so an issuer named inside it could be one that an attacker
-controls.
-
-## Running it
-
-The example harness in
-[`development/examples/agent-harness`](https://github.com/google/sam/tree/main/development/examples/agent-harness)
-is about a hundred lines. It discovers tools, calls a model, runs the tool
-loop, and stops.
-
-Start a node that serves its API on a socket:
-
-```bash
-sam-node run --socket-path /run/sam/node.sock --data-dir /var/lib/sam --bind-addr=
-```
-
-Start a boundary for the agent:
-
-```bash
-sam-box run \
- --socket /run/sam/agent.sock \
- --sidecar-socket /run/sam/node.sock \
- --bundle ./bundle.yaml \
- --credential-issuer https://kubernetes.default.svc \
- --credential-audience sam \
- --metrics-addr 127.0.0.1:9600
-```
-
-On a laptop without a platform issuer, `--insecure-unverified-bundle` skips
-the credential check. It logs what this means: whoever can write the bundle
-decides which agent the sandbox is. This is a flag that shows in a process
-listing, so the choice is visible.
-
-Start the sandbox as a container:
-
-```bash
-docker run --rm \
- --network none \
- --cap-add NET_ADMIN --device /dev/net/tun \
- -v /run/sam/agent.sock:/run/agent.sock \
- agent-harness "Summarise the open issues in our repo"
-```
-
-`--network none` is what makes this a sandbox. `NET_ADMIN` and
-`/dev/net/tun` are needed only so that `nano-init` can create the single
-`tun0`. The image's entrypoint is `nano-init run /run/agent.sock <command>`.
-`nano-init copy <dest>` copies the binary into an image that contains
-nothing else.
-
-Look at what happened:
-
-```console
-$ curl -s http://127.0.0.1:9600/metrics | grep sam_box_flows_total
-sam_box_flows_total{outcome="allowed",route="external"} 1
-sam_box_flows_total{outcome="allowed",route="mesh-entrypoint"} 19
-sam_box_flows_total{outcome="denied",route="unresolved"} 1
-```
-
-Refusals do not show up as latency, so counting them is the only way to see
-them. If you edit the bundle and restart `sam-box`, these numbers change
-without any change to the agent.
-
-## Sandbox types
-
-The layers are the same in all three types. Only the way the sandbox reaches
-the socket differs.
-
-**Container with `--network none`.** The socket is bind-mounted into the
-container. This is the setup shown above.
-
-**Firecracker microVM.** Each agent gets its own kernel, which boots in a
-few tens of milliseconds. The guest has no network device. `nano-init`
-reaches the boundary over vsock (`vsock://2:1080`). Firecracker terminates
-guest vsock connections on the host as `<uds_path>_<port>`, so for a guest
-that dials CID 2 port 1080, `sam-box --socket` must serve exactly
-`/var/run/sam-vm-1.vsock_1080`. The host never speaks `AF_VSOCK`, and this
-is why the same `sam-box` serves containers and VMs. The guest kernel must
-have `CONFIG_TUN=y`. The stock Firecracker CI kernels for 5.10 and 6.1 do
-not have it. The 6.18 kernel does.
-
-**Kubernetes pod.** The containers in a pod share one network namespace and
-one `resolv.conf`, so there is no per-container `--network none`.
-`nano-init run --create-namespaces` builds its own namespaces. It first
-creates a user namespace, in which it holds `CAP_SYS_ADMIN` and
-`CAP_NET_ADMIN` over what it creates next, and then a network namespace that
-contains only `tun0`. The container itself needs no capability.
-
-```yaml
-apiVersion: v1
-kind: Pod
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
metadata:
- name: agent
+ name: sandbox-to-sam-node-only
+ namespace: agents
spec:
- volumes:
- - { name: sam-uds, emptyDir: {} }
- - { name: tun, hostPath: { path: /dev/net/tun, type: CharDevice } }
- - { name: resolv, configMap: { name: sandbox-resolv } }
- containers:
- - name: sam-node
- image: ghcr.io/google/sam-node:latest
- args: [run, --jwt-path=/var/run/secrets/tokens/sam-token, --bind-addr=, --socket-path=/var/run/sam/node.sock]
- volumeMounts: [{ name: sam-uds, mountPath: /var/run/sam }]
- - name: sam-box
- image: ghcr.io/google/sam-box:latest
- args: [run, --socket=/var/run/sam/agent.sock, --sidecar-socket=/var/run/sam/node.sock, --egress-allow=api.github.com]
- volumeMounts: [{ name: sam-uds, mountPath: /var/run/sam }]
- - name: agent
- image: your-agent-image
- command: [/usr/local/bin/nano-init, run, --create-namespaces, /var/run/sam/agent.sock, python3, /app/agent.py]
- volumeMounts:
- - { name: sam-uds, mountPath: /var/run/sam }
- - { name: tun, mountPath: /dev/net/tun }
- - { name: resolv, mountPath: /etc/resolv.conf, subPath: resolv.conf }
----
-apiVersion: v1
-kind: ConfigMap
-metadata:
- name: sandbox-resolv
-data:
- resolv.conf: "nameserver 100.127.255.253\n"
-```
-
-Three details are easy to get wrong without any error message:
-
-- **The TUN device is only a `hostPath` mount.** The device cgroup does not
- deny `/dev/net/tun`. What is gated is the `TUNSETIFF` call, and that is a
- capability question that the user namespace answers.
-- **No `securityContext`.** Granting `CAP_SYS_ADMIN` alone is worse than
- granting nothing. The namespace gets created, and then the tun fails
- because `CAP_NET_ADMIN` is missing.
-- **The sandbox's `resolv.conf` is mounted per container.** `dnsConfig` is a
- pod-level field. It would point `sam-node` at a resolver that exists only
- inside the sandbox's namespace. With the file mounted, `nano-init` finds
- its resolver already configured and needs no bind mount. The bind mount is
- the one operation that containerd's default AppArmor profile denies.
-
-The harness must be a child process of `nano-init`. The `command` above
-arranges this. A container that starts the harness directly, or that runs
-`nano-init` next to it, leaves the harness in the pod's network namespace,
-with `eth0` and every route. It will run, and it will not be sandboxed.
-Check:
-
-```console
-$ kubectl exec -c agent agent -- ip -o link show | cut -d: -f2
- lo
- tun0
+ podSelector:
+ matchLabels:
+ app: agent-sandbox
+ policyTypes: [Egress]
+ egress:
+ - to:
+ - namespaceSelector:
+ matchLabels:
+ kubernetes.io/metadata.name: sam-system
+ podSelector:
+ matchLabels:
+ app: sam-node
+ ports:
+ - protocol: TCP
+ port: 8080
```
-Ubuntu 24.04 hosts set `kernel.apparmor_restrict_unprivileged_userns=1`.
-This confines an unprivileged process that creates a user namespace to a
-profile that denies every capability, and the tun then fails with
-`operation not permitted`. Managed clusters apply their own AppArmor profile
-and are not affected. A kind cluster on such a host needs the sysctl set to
-`0`.
+## Blueprint 3: `agentgateway` and Istio service mesh
-## Agents that serve
+In clusters that already route agent traffic through **`agentgateway`**,
+**Istio Ambient** (waypoints or sidecars), or **Envoy AI Gateway**, traffic
+continues to flow through those proxies while `sam-node` serves as the Policy
+Decision Point and Token Service:
-An agent can serve one thing: itself, as an A2A agent. Tools and models are
-operator workloads declared in a node's configuration. An agent never
-advertises one. The whole route is fixed before the agent runs, and nothing
-is registered at run time:
+- **Envoy `ext_authz` (`--ext-authz-addr`) and `ext_proc`:**
+ Istio `AuthorizationPolicy (action: CUSTOM)` or `agentgateway` calls
+ `sam-node`. When no Bearer token is present on a trusted proxy listener,
+ `sam-node` reads the caller's verified SPIFFE ID from
+ `AttributeContext.Source.Principal` or `X-Forwarded-Client-Cert` (XFCC),
+ exchanges it into a Delegated Session Biscuit, evaluates the standing Datalog
+ policy and any `TaskAuthorizationRule` chain (including MCP tool names in
+ JSON-RPC bodies via `ext_proc`), and injects the upstream credential into
+ `Authorization` before the gateway forwards the request.
+- **RFC 8693 backend token exchange (`POST /oauth/token`):**
+ `agentgateway`'s built-in RFC 8693 token exchange policy can point directly
+ at `http://sam-node:8080/oauth/token` to exchange workload JWTs or narrow
+ existing Biscuits per route.
-- The bundle's `serves` names the service and the port that the agent must
- bind, in the same way `$PORT` works on a serverless runtime. `sam-box`
- routes that name to that port from startup. A name outside the contract
- cannot be expressed.
-- The node's configuration declares the service with `type: a2a` and a
- `target_url` that points at the boundary's ingress listener
- (`--ingress-listen`, default `127.0.0.1:7080`).
-- The node probes the agent's card through the boundary before it
- advertises the service, and it keeps probing. An agent that has not bound
- its port yet, or that has died, is not discoverable. When it answers, it
- is. Readiness is observed, never assumed. When the boundary stops, the
- probe fails and discovery converges.
+## Blueprint 4: Multi-hop sub-agent delegation and cloud egress
-Delivering a request into the sandbox cannot mean dialling the agent. The
-agent's `127.0.0.1` is inside a namespace that the boundary is not in. So a
-second Unix socket carries each inbound request to the contracted port.
-`nano-init --ingress-socket` serves it from inside the sandbox, and
-`sam-box --agent-ingress-socket` dials it. That flag is required whenever a
-bundle has `serves`, and `sam-box` refuses to start without it. The only
-other address available would be one in the boundary's own namespace, which
-in a pod is the pod's namespace, where the node's API is listening. The
-agent's node authorized the caller before the request reached the boundary,
-so "agent `foo` may call agent `bar`" is one policy statement, evaluated at
-the node of `bar`.
+When an agent delegates work to a sub-agent or calls a cloud API through an
+egress node (`egress://bigquery.googleapis.com`), it attenuates its credential
+offline in memory using the TypeScript or Python SDK (or `POST /oauth/token` on
+`sam-node`).
-## Not yet built
+### Example: two-hop attenuation in Python
-- **Secret injection** for external destinations. The machinery exists
- (an ephemeral CA, header rewriting) but is not connected to this datapath.
-- **Credential rotation.** The bundle's credential is verified when
- `sam-box` starts. Verifying it again when a platform rotates a projected
- token is the `Refresh` operation of the connector interface, which does
- not exist yet.
-- **The connector control socket** (`Attach`, `Detach`, `Refresh`,
- `Status`), through which a scheduler would drive `sam-box`. Today the
- bundle is a file, and the lifecycle of the boundary is the lifecycle of
- the process.
+```python
+from datetime import datetime, timedelta, timezone
+from google.protobuf.timestamp_pb2 import Timestamp
+from agent_mesh import AgentMesh, sam_pb2
+
+# Hop 1: Orchestrator narrows its session to read-only BigQuery sales_2026
+# and two MCP tools for 15 minutes.
+exp1 = Timestamp()
+exp1.FromDatetime(datetime.now(timezone.utc) + timedelta(minutes=15))
+
+hop1_session = session.attenuate(
+ sam_pb2.TaskAuthorizationRule(
+ name="tasks/session-bq-read-sales",
+ expire_time=exp1,
+ rules=[
+ sam_pb2.TaskRule(
+ allowed_services=["egress://bigquery.googleapis.com"],
+ operation=sam_pb2.TaskOperation(
+ allowed_methods=["GET", "POST"],
+ allowed_paths=["/bigquery/v2/projects/my-proj/datasets/sales_2026/*"],
+ allowed_permissions=[
+ "bigquery.googleapis.com/datasets.get",
+ "bigquery.googleapis.com/tables.get",
+ "bigquery.googleapis.com/tables.getData",
+ ],
+ ),
+ allowed_resources=[
+ "//bigquery.googleapis.com/projects/my-proj/datasets/sales_2026/*",
+ ],
+ ),
+ sam_pb2.TaskRule(
+ allowed_services=["mcp://bigquery"],
+ operation=sam_pb2.TaskOperation(allowed_tools=["list_tables", "query_sales"]),
+ ),
+ ],
+ )
+)
+
+# Hop 2: Analytics agent spawns a leaf sub-agent restricted to table q1 only,
+# and seals the credential so the sub-agent cannot append further blocks.
+hop2_session = hop1_session.attenuate(
+ sam_pb2.TaskAuthorizationRule(
+ name="tasks/subagent-q1-only",
+ rules=[
+ sam_pb2.TaskRule(
+ allowed_services=["egress://bigquery.googleapis.com"],
+ operation=sam_pb2.TaskOperation(
+ allowed_methods=["GET"],
+ allowed_paths=["/bigquery/v2/projects/my-proj/datasets/sales_2026/tables/q1/*"],
+ allowed_permissions=["bigquery.googleapis.com/tables.getData"],
+ ),
+ allowed_resources=[
+ "//bigquery.googleapis.com/projects/my-proj/datasets/sales_2026/tables/q1",
+ ],
+ )
+ ],
+ )
+).seal()
+```
-## `sam-box run` flags
+### Example: two-hop attenuation in TypeScript
+
+```typescript
+import { create } from "@bufbuild/protobuf";
+import { timestampFromDate } from "@bufbuild/protobuf/wkt";
+import { TaskAuthorizationRuleSchema } from "@sam-mesh/sdk/gen/sam_pb.ts";
+
+const hop1 = session.attenuate(
+ create(TaskAuthorizationRuleSchema, {
+ name: "tasks/session-bq-read-sales",
+ expireTime: timestampFromDate(new Date(Date.now() + 15 * 60_000)),
+ rules: [
+ {
+ allowedServices: ["mcp://bigquery"],
+ operation: { allowedTools: ["list_tables", "query_sales"] },
+ },
+ ],
+ }),
+);
+
+const leafSession = hop1
+ .attenuate(
+ create(TaskAuthorizationRuleSchema, {
+ name: "tasks/subagent-q1-only",
+ rules: [
+ {
+ allowedServices: ["mcp://bigquery"],
+ operation: { allowedTools: ["query_sales"] },
+ },
+ ],
+ }),
+ )
+ .seal();
+```
-| Flag | Meaning |
-|---|---|
-| `--socket` | The sandbox-facing Unix socket, created with mode `0600`. Required. |
-| `--sidecar-socket` | The local `sam-node` API socket. Required. |
-| `--bundle` | The agent bundle. |
-| `--credential-issuer`, `--credential-audience` | The issuer and audience of the platform credential that must back the bundle. Required with `--bundle`. |
-| `--insecure-unverified-bundle` | Trust the bundle without a credential. |
-| `--egress-allow` | Destination names that an unidentified sandbox may reach. Repeatable. Use the bundle instead when the agent has an identity. If empty, nothing outside the mesh is reachable. |
-| `--agent-ingress-socket` | The reverse channel into the sandbox. Required when the bundle has `serves`. |
-| `--ingress-listen` | Address on which the boundary's mesh-facing ingress listens. Default `127.0.0.1:7080`. The node's `a2a` service declaration points here. |
-| `--metrics-addr` | Prometheus metrics (`sam_box_*`) without authentication. Off by default. |
-| `--log-level` | `debug`, `info`, `warn`, `error`. |
+When `hop2_session` calls `egress://bigquery.googleapis.com`, the egress
+`sam-node` verifies the Control Plane signature, the standing policy, and the
+intersection of `TAR_1` and `TAR_2`, mints an ES256 border JWT at the control
+plane (`POST /sts/token`), and exchanges it via `CloudTokenExchanger` for a
+downscoped cloud token.
## Further reading
-- [Agent architecture](../agent-architecture/): the decisions behind this
- design and the reasons for them.
-- [Scale report](../scale-report/): the measured cost of a boundary.
-- [Authorization](../../concepts/authorization/#agents-acting-through-a-node):
- how `allowed_agents` and the `agent` claim are evaluated.
+- [Agent architecture](../agent-architecture/): the two-token model, safe
+ `tar_block` attenuation, `CloudTokenExchanger`, and content inspection.
+- [Authorization](../../concepts/authorization/): standing Datalog policy and
+ per-task `TaskAuthorizationRule` evaluation.
+- [Node API](../../reference/node-api/): `/oauth/token`, `/oauth/revoke`,
+ `ext_authz`, `ext_proc`, and `/egress/*`.
diff --git a/site/content/docs/reference/control-plane.md b/site/content/docs/reference/control-plane.md
index 9efe2000..a50812a8 100644
--- a/site/content/docs/reference/control-plane.md
+++ b/site/content/docs/reference/control-plane.md
@@ -58,8 +58,11 @@ Responses that carry credentials are sent with `Cache-Control: no-store`.
| `GET /metrics` | Prometheus metrics. |
| `GET /info` | `ControlPlaneInfoResponse`: the OIDC issuer, client ID and audience, the addresses of routers with live leases, and the list of banned peer IDs. This is what a node needs before it can enroll. |
| `GET /keys` | The current set of signing public keys, signed by every key in the set. A caller accepts the set only if one signature verifies under a key it already trusts. |
+| `GET /.well-known/openid-configuration`, `GET /.well-known/oauth-authorization-server` | OIDC Discovery and OAuth 2.1 Authorization Server metadata for outbound STS federation and MCP OAuth 2.1 clients. |
+| `GET /jwks` | JSON Web Key Set (`ES256` public keys) for verifying border JWTs minted by `POST /sts/token`. |
+| `GET /oauth/authorize`, `POST /oauth/token` | OAuth 2.1 Authorization Code + PKCE endpoints (honouring RFC 8707 `resource` indicators to scope the issued Task Biscuit). |
-### Enrollment and refresh
+### Enrollment, refresh, and STS
Every request below carries a `challenge_unix_ms` and a `challenge_signature`.
The enrollee signs `sam:<endpoint>:<peer_id>:<challenge_unix_ms>` with its
@@ -74,6 +77,9 @@ names. Every instant in a response (`expire_time` and the like) is a
| `POST /enroll` | `BootstrapEnrollRequest` (bootstrap token, public key, requested role, labels) | Bootstrap enrollment. Returns `BootstrapEnrollResponse` with status `APPROVED` and the credential, or with status `PENDING`. For a peer that is already approved, a new credential is minted directly. |
| `GET /enroll/status?peer_id=` | headers `X-Sam-Challenge-Ts`, `X-Sam-Challenge-Sig` | Poll a pending enrollment. Any authentication failure answers `401`, so the credential is released only to the enrollee. |
| `POST /refresh` | `TokenRefreshRequest`, current credential as `Authorization: Bearer <base64>` | Exchange a credential for a new one. Refuses a replayed (superseded) credential, a banned node, an expired session, and a credential signed by a retired key unless the node has `autonomous_recovery`. |
+| `POST /token/exchange` | `TokenExchangeRequest` (`subject_token`, optional `task_rule` and `seal`, challenge signature), node credential as bearer | Stateless JWT-to-Biscuit exchange. Mints a Delegated Session Biscuit bound to the calling node (`actor_node`, `client_peer_id`) with zero database writes. |
+| `POST /sts/token` | `STSTokenRequest` (`biscuit`, `destination`, optional `audience`, challenge signature), node credential as bearer | Stateless Biscuit-to-JWT minting. Verifies the Biscuit and `tar_block` chain against `egress://<destination>` and mints a short-lived ES256 border JWT (`sub`, `act.sub`, `aud`, `sam_roles`, `sam_task`). |
+| `GET /revocations` | credential as `Authorization: Bearer <base64>` | `RevocationsResponse`: revoked root Biscuit revocation IDs (`revocation_ids`) and banned peer IDs (`banned_peer_ids`). |
| `POST /routers/lease` | `RouterLeaseRequest` (credential, addresses, telemetry) | Register or renew a router lease. Requires `role("sam:role:router")`. Announced addresses must end in the router's own peer ID. |
| `GET /policies` | credential as `Authorization: Bearer <base64>` | The mesh policy as `PolicyConfigGetResponse`: the Datalog rules a member adds to its authorizer, one per entry. Operators read the document at `GET /admin/policy`. |
| `GET /egress` | credential as `Authorization: Bearer <base64>` | `EgressAssignmentsResponse`: the [egress destinations](../policy/#egress-destinations) whose `served_by` selects the calling node, by its roles or labels. A node registers and serves what it receives here. |
diff --git a/site/content/docs/reference/node-api.md b/site/content/docs/reference/node-api.md
index d4161c25..d41355e6 100644
--- a/site/content/docs/reference/node-api.md
+++ b/site/content/docs/reference/node-api.md
@@ -6,36 +6,57 @@ aliases:
- /docs/development/testnet-validation/
---
-The local API that `sam-node run` serves to agents and scripts on the same
-machine. It is available on TCP (`--bind-addr`, default `127.0.0.1:8080`)
-and on a Unix socket (`--socket-path`, default `<data-dir>/sam.sock`).
+The local API that `sam-node run` serves to agents, gateways, and scripts on
+the same machine or cluster. It is available on TCP (`--bind-addr`, default
+`127.0.0.1:8080`), on a Unix socket (`--socket-path`, default
+`<data-dir>/sam.sock`), and optionally on a dedicated Envoy `ext_authz` /
+`ext_proc` listener (`--ext-authz-addr`).
## Authentication
| Listener | Requirement |
|---|---|
-| TCP | `X-Sam-Authentication: Bearer <api-token>` on every request, or a client certificate when `--tls-ca` is set. |
-| Unix socket | None. The socket has mode `0600`. Being able to open it is the credential. |
-
-`Authorization` is reserved for the credential of the service that is being
-called through the node, and the proxy path forwards it. The endpoints that
-never forward anything (`/mcp`, `/v1/*`, `/sam/service/*`, `/metrics`,
-`/sam/identity`, `/sam/peer/*`, `/debug/*`) also accept the API token in
-`Authorization: Bearer`, for clients that cannot set custom headers. The
-proxy path does not accept it there.
+| TCP (`--bind-addr`) | `X-Sam-Authentication: Bearer <token>` on every request, or `Authorization: Bearer <token>` on non-proxy endpoints (`/mcp`, `/v1/*`, `/egress/*`, `/oauth/*`), or a client certificate when `--tls-ca` is set. |
+| Unix socket (`--socket-path`) | None required for node-level access (the socket has mode `0600`). A caller may still pass a SAM Task Biscuit or platform JWT in `X-Sam-Authentication` or `Authorization` to scope the request to that caller's identity and task rules. |
+
+The bearer `<token>` accepted by `sam-node` can be:
+
+1. **The node's static API token** (`--api-token-path` or `SAM_API_TOKEN`),
+ which exercises the node's own enrolled credential.
+2. **A SAM Biscuit** (a Member Biscuit, a Delegated Session Biscuit, or a
+ task-attenuated Biscuit with `tar_block` blocks), base64-encoded.
+3. **An external platform JWT** (an OIDC ID token, Kubernetes projected service
+ account token, or SPIFFE JWT-SVID). On `/mcp`, `/v1/*`, `/sam/*` (via
+ `X-Sam-Authentication`), and `/egress/*`, `sam-node` exchanges the JWT via
+ the control plane's stateless `POST /token/exchange` endpoint (cached until
+ expiry) and forwards the resulting Delegated Session Biscuit.
+
+On `/sam/{peer-id}/{type}/{name}/...`, the `Authorization` header is reserved
+exclusively for the destination service's own credential and passes through
+untouched; callers of `/sam/...` pass their SAM token or platform JWT in
+`X-Sam-Authentication: Bearer <token>`.
+
+When a request on TCP fails authentication with `401 Unauthorized`, `sam-node`
+includes `WWW-Authenticate: Bearer resource_metadata="http://<host>/.well-known/oauth-protected-resource"`
+per RFC 9728 so standard MCP OAuth 2.1 clients can discover the control plane
+Authorization Server.
## Routes
| Route | Auth | Purpose |
|---|---|---|
-| `GET /healthz`, `GET /readyz` | none | `200` while the process is up. Every other route except `/debug/*` answers `503` until the node is connected to the mesh, so a `503` on `/mcp` is the practical readiness signal. |
+| `GET /healthz`, `GET /readyz` | none | `200` while the process is up. Every other route except `/debug/*` and `/.well-known/*` answers `503` until the node is connected to the mesh. |
+| `GET /.well-known/oauth-protected-resource` | none | RFC 9728 OAuth 2.1 Protected Resource Metadata naming the SAM control plane in `authorization_servers`. |
+| `POST /oauth/token` | token | RFC 8693 Token Exchange: exchanges a platform JWT or Biscuit into a Delegated or Task-Attenuated Biscuit. See [Token exchange (`/oauth/token`)](#token-exchange-oauthtoken). |
+| `POST /oauth/revoke` | token | RFC 7009 Token Revocation: revokes a task Biscuit in this node's local revocation cache. |
| `GET /metrics` | token | Prometheus metrics (`sam_node_*`). |
| `POST /mcp` | token | The MCP server (Streamable HTTP, sessionless: no `Mcp-Session-Id`, `GET` answers `405`). `/` is an alias. |
| `GET /v1/models` | token | Models served by every reachable inference provider. |
| `POST /v1/chat/completions`, `POST /v1/completions` | token | OpenAI-compatible inference, routed to a provider of the requested model. |
| `GET /sam/service/discover` | token | Discover services on the mesh. |
| `ANY /sam/{peer-id}/{type}/{name}[/{path}]` | token | Reverse proxy to one service on one peer. |
-| `ANY /egress/{destination}[/{path}]` | token | A destination outside the mesh that this node serves, for local clients. See [Egress](#egress). |
+| `ANY /egress/{destination}[/{path}]` | token | HTTP proxy to an external destination assigned to this node. See [Egress](#egress). |
+| `CONNECT {destination}:{port}` | token | Named TCP tunnel to an `EGRESS_MODE_TCP` destination assigned to this node. |
| `GET /sam/identity` | token, socket or mTLS only | This node's credential and the key it verifies under. |
| `GET /sam/peer/{peer-id}/evidence` | token, socket or mTLS only | A peer's credential as this node last verified it. |
| `GET /debug/*` | token | Operator diagnostics. These answer even when the mesh is unreachable. |
@@ -43,6 +64,43 @@ proxy path does not accept it there.
`--metrics-addr` serves `/metrics`, `/healthz` and `/readyz` on a second
listener without authentication, for scrapers that hold no token.
+## Token exchange (`/oauth/token`) and revocation (`/oauth/revoke`)
+
+`POST /oauth/token` implements RFC 8693 (`application/x-www-form-urlencoded`):
+
+| Parameter | Meaning |
+|---|---|
+| `grant_type` | Required: `urn:ietf:params:oauth:grant-type:token-exchange`. |
+| `subject_token` | The input JWT or base64 Biscuit. If omitted when authenticated with the node's API token, defaults to the node's own Biscuit. |
+| `subject_token_type` | `urn:ietf:params:oauth:token-type:jwt`, `id_token`, `access_token`, or `urn:sam-mesh:params:oauth:token-type:biscuit`. |
+| `options` (or `scope` / `resource`) | Optional `TaskAuthorizationRule` as protojson (or space-separated service patterns in `scope`) to append as a `tar_block`. |
+| `seal` | Optional (`true` / `1`): seal the returned Biscuit so downstream holders cannot append further blocks. |
+
+Returns standard RFC 8693 JSON (`access_token`,
+`issued_token_type: "urn:sam-mesh:params:oauth:token-type:biscuit"`,
+`token_type: "Bearer"`, `expires_in`).
+
+`POST /oauth/revoke` accepts `token=<base64-biscuit>` and records its leaf
+revocation ID in the node's local revocation cache until the token expires.
+
+## Envoy `ext_authz` and `ext_proc` gateway integration
+
+When `--ext-authz-addr` (`host:port` or `unix:/path`) is set (or on the local
+API listener), `sam-node` serves:
+
+- **Envoy HTTP `ext_authz` (`/ext_authz`, `/ext_authz/*`)** and **gRPC
+ `envoy.service.auth.v3.Authorization/Check`**: evaluates standing Datalog
+ policy and any `tar_block` chain on the request. On a trusted `--ext-authz-addr`
+ listener, if no Bearer token is present, `sam-node` extracts the caller's
+ verified SPIFFE principal from `AttributeContext.Source.Principal` or
+ `X-Forwarded-Client-Cert` (XFCC) and exchanges it into a Delegated Session
+ Biscuit. On `OK`, it injects `Authorization: Bearer <upstream-token>`,
+ `X-Sam-Principal`, and `X-Sam-Task-Id`.
+- **Envoy gRPC `envoy.service.ext_proc.v3.ExternalProcessor/Process`**: the
+ body-aware gateway processor. It inspects JSON-RPC bodies on MCP `tools/call`
+ requests to enforce `operation.allowed_tools` in `TaskAuthorizationRule`
+ blocks before injecting the upstream credential.
+
## MCP tools
The `/mcp` endpoint speaks Streamable HTTP. The older SSE transport is
@@ -110,8 +168,11 @@ Returns `description`, `input_schema` and `output_schema`.
| `arguments` | Object matching the tool's `input_schema`. |
| `required_labels` | `key=value[,key=value]`. The call is refused unless the peer's credential attests every one of them. |
-Returns the tool's result content. A policy denial comes back as a tool
-error that the caller can read, not as a transport failure.
+Returns the tool's result content. If the caller authenticated with a
+Delegated or Task-Attenuated Biscuit, `sam-node` forwards that Biscuit on the
+mesh stream so the provider enforces the caller's roles and `tar_block` tool
+restrictions. A policy denial comes back as a tool error that the caller can
+read, not as a transport failure.
### When the node has no credential
@@ -134,20 +195,18 @@ server-sent events as they are found, and the stream ends with
```
The node verifies the peer's credential and, if set, the operator's
-`egress.require_labels`. It then opens an authenticated stream and forwards
-the request to `/<type>/<name>/<path>` on the peer, which proxies it to the
-backend. Headers pass through, including `Authorization`. Paths that contain
-`..` are refused. For an `mcp` service, `<path>` is empty and the request
-body is the JSON-RPC message. For `inference`, `<path>` is `v1/models` or
-`v1/chat/completions`. For `a2a`, `<path>` is whatever the agent serves, and
-`.well-known/agent-card.json` is rewritten for the mesh.
-
-Two headers modify a proxied request:
+`egress.require_labels`. It then opens an authenticated stream (presenting the
+caller's Task Biscuit when one was supplied in `X-Sam-Authentication`) and
+forwards the request to `/<type>/<name>/<path>` on the peer, which proxies it
+to the backend. Headers pass through, including `Authorization`. Paths that
+contain `..` are refused. For an `mcp` service, `<path>` is empty and the
+request body is the JSON-RPC message. For `inference`, `<path>` is `v1/models`
+or `v1/chat/completions`. For `a2a`, `<path>` is whatever the agent serves,
+and `.well-known/agent-card.json` is rewritten for the mesh.
| Header | Effect |
|---|---|
| `X-Sam-Required-Labels: k=v[,k=v]` | Forward only to a peer whose credential attests every listed pair. Otherwise `403`. Removed before forwarding. Also honoured on `/v1/*`. |
-| `X-Sam-Agent: <agent-id>` | Name the agent for which this request is made. Only meaningful when sent by a `sam-box`. See the [preview](../../preview/sandboxed-agents/). |
### Talking MCP through the proxy
@@ -213,50 +272,56 @@ curl -s --unix-socket $SOCK http://localhost/v1/chat/completions \
```
Any OpenAI SDK works with `base_url` set to `http://127.0.0.1:8080/v1` and
-the API token as `api_key`. The node accepts the token in `Authorization`
-here because nothing on this path forwards that header. Streaming responses
-are passed through. One provider can also be addressed directly, at
-`/sam/<peer-id>/inference/<name>/v1/chat/completions`.
+the API token, Task Biscuit, or platform JWT as `api_key`. The node accepts
+the token in `Authorization` here because nothing on this path forwards that
+header. Streaming responses are passed through. One provider can also be
+addressed directly, at `/sam/<peer-id>/inference/<name>/v1/chat/completions`.
## Egress
-`/egress/<destination>/<path>` reaches a destination outside the mesh that
-the control plane assigned to this node (an entry of the
+`/egress/<destination>/<path>` reaches an external HTTP destination that the
+control plane assigned to this node (an entry of the
[egress section](../policy/#egress-destinations) of the mesh policy whose
-`served_by` selects it). The node is the HTTP origin: it authorizes the
-request on its own credential, with the request's method and path and the
-destination's host and port as facts, forwards it to the destination's
-`target_url` with the credential the policy names, and returns the answer.
+`served_by` selects it). The node is the HTTP origin:
+
+1. It authorizes the request against the caller's Biscuit (or the node's own
+ credential for local socket calls), evaluating standing Datalog policy and
+ any appended `TaskAuthorizationRule` (`tar_block`) chain against `service`,
+ `method`, `path`, `host`, and `port`.
+2. It strips the caller's `Authorization`, `Cookie`, `X-Sam-*`, and
+ `X-Forwarded-*` headers (unless `forward_context` is set for an operator
+ inspection chain).
+3. It runs any configured [content inspectors](../policy/#content-inspection)
+ (`model_armor`, `ext_proc`) before injecting secrets.
+4. It brokers the upstream credential via `CloudTokenExchanger` (`static_secret`,
+ `oidc_federation` via `POST /sts/token`, `aws_assume_role`, or
+ `platform_identity`), injects `Authorization: Bearer ...`, and forwards the
+ request to `target_url` (preserving `Host: <destination>` when
+ `preserve_host` is enabled).
```bash
curl -s --unix-socket $SOCK "http://localhost/egress/api.github.com/repos/acme/dubbing/pulls?state=open"
```
-An application that takes a base URL for the API it calls points it at the
-node, `http://127.0.0.1:8080/egress/api.github.com`, and sends the API
-token as its bearer, the way it would send a provider key. The node accepts
-the token in `Authorization` on this path and never forwards that header:
-the destination sees the node's credential and none of the client's
-headers. A client may name the agent it acts for in `X-Sam-Agent`; the
-claim is checked against the node's `allowed_agents` grant and is visible
-to policy as `agent()`.
-
-`403` is a policy decision: the node's role lacks the destination, an
-`http` narrowing excludes the method or path, or the node's `attenuation`
-refuses the request. `404` is a destination the control plane did not
-assign to this node. Both carry a `Proxy-Status` header (RFC 9209) naming
-the node as the source, `sam-node; error=http_request_denied` or
-`error=destination_not_found`, so a client can tell them from a `403` or
-`404` the destination itself sent, which carries none. A destination whose
-credential file went missing after registration answers `502` with
-`error=proxy_configuration_error`. The same destination is reachable from
-another mesh member at `/sam/<peer-id>/egress/<destination>/<path>` on that
-member's node, authorized on the member's credential.
-
-The path is a prefix under the destination, so a client that follows
-absolute URLs returned by the destination (a `Link` header, a URL in a
-body) leaves the node. Point it back at the prefix, or use a client that
-takes a base URL.
+`403` is a policy or inspection decision (`Proxy-Status: sam-node; error=http_request_denied`).
+`404` is a destination the control plane did not assign to this node
+(`error=destination_not_found`). A destination whose broker cannot obtain a
+credential answers `502` with `error=proxy_configuration_error`. The same
+destination is reachable from another mesh member at
+`/sam/<peer-id>/egress/<destination>/<path>` on that member's node, authorized
+on the caller's Biscuit.
+
+### Named TCP tunnels (`CONNECT` and `sam-node forward`)
+
+For destinations with `mode: EGRESS_MODE_TCP` and an allowed `ports` list, the
+node accepts HTTP `CONNECT <destination>:<port>` on its local listener and
+verifies that the TLS `ClientHello` SNI matches `<destination>` (and does not
+use Encrypted Client Hello) before splicing the stream to the remote egress
+node. Clients that do not speak `CONNECT` can use `sam-node forward`:
+
+```bash
+sam-node forward egress://pg.internal.example:5432 127.0.0.1:15432
+```
## Identity evidence
diff --git a/site/content/docs/reference/policy.md b/site/content/docs/reference/policy.md
index 0e7669a4..16fd80b9 100644
--- a/site/content/docs/reference/policy.md
+++ b/site/content/docs/reference/policy.md
@@ -24,25 +24,34 @@ back from `GET /admin/policy`, edited in the console, or given to
"name": "developer",
"allowed_services": ["mcp://code-reviewer", "mcp://build-runner.*", "inference://*"],
"allowed_targets": ["group:dev-nodes", "node:12D3KooWSpecialNode"],
- "allowed_agents": ["*.dev.acme.example"],
"custom_datalog": ["tier(\"standard\");"]
},
{
- "name": "contractor",
- "allowed_services": ["egress://api.github.com"],
+ "name": "analyst",
+ "allowed_services": ["egress://bigquery.googleapis.com"],
"allowed_targets": ["*"],
"http": [
- { "service": "egress://api.github.com", "methods": ["GET"], "paths": ["/repos/acme/*"] }
+ { "service": "egress://bigquery.googleapis.com", "methods": ["GET", "POST"], "paths": ["/bigquery/v2/projects/my-proj/datasets/*"] }
]
}
],
"bindings": [
{ "role": "sam:role:node", "members": ["group:engineering", "user:system:serviceaccount:sam-nodes:calc-mcp-sam-node"] },
{ "role": "developer", "members": ["group:engineering"] },
- { "role": "contractor", "members": ["group:external"] }
+ { "role": "analyst", "members": ["group:analytics"] }
],
"egress": [
- { "name": "api.github.com", "credential": "github-eu", "served_by": ["site=eu"] }
+ {
+ "name": "bigquery.googleapis.com",
+ "served_by": ["site=eu"],
+ "broker": {
+ "oidc_federation": {
+ "token_endpoint": "https://sts.googleapis.com/v1/token",
+ "audience": "//iam.googleapis.com/projects/123/locations/global/workloadIdentityPools/sam/providers/sam-cp",
+ "scopes": ["https://www.googleapis.com/auth/bigquery.readonly"]
+ }
+ }
+ }
]
}
```
@@ -55,11 +64,10 @@ notice.
| Field | Type | Meaning |
|---|---|---|
-| `name` | string, required, unique | The role name. `sam:role:node`, `sam:role:router` and `sam:role:sambox` are the roles that the three binaries request at enrollment. Any other name is an ordinary role. |
+| `name` | string, required, unique | The role name. `sam:role:node` and `sam:role:router` are the roles that the two binaries request at enrollment. Any other name is an ordinary role. |
| `allowed_services` | list of service patterns | Services that holders may call. |
| `allowed_targets` | list of target patterns | Nodes that holders may call. If absent, any node may be called. |
| `allowed_labels` | list of label patterns | Labels that a node holding this role may declare at enrollment. If absent, no labels may be declared. |
-| `allowed_agents` | list of agent patterns | Agent identifiers that a node holding this role may claim to act for. If absent, no agent may be named. |
| `custom_datalog` | list of Datalog statements | Facts are minted into the credentials of holders. Rules are distributed to nodes and applied when a holder is verified. |
| `http` | list of HTTP grants | Narrows an `allowed_services` entry to HTTP methods and paths. See [HTTP grants](#http-grants). |
@@ -69,8 +77,8 @@ notice.
`system`, and `name` consists of dot-separated DNS-style labels. For
`egress` the name is the hostname of a destination outside the mesh, written
lowercase, with no scheme, port or path: `egress://api.github.com/v3` is
-rejected, because the path belongs in the role's `http` entry. See
-[Egress destinations](#egress-destinations).
+rejected, because the path belongs in the role's `http` entry or a
+`TaskAuthorizationRule`. See [Egress destinations](#egress-destinations).
| Pattern | Compiles to | Matches |
|---|---|---|
@@ -82,8 +90,7 @@ rejected, because the path belongs in the role's `http` entry. See
A fact whose only meaning is that a grant exists carries the single term
`true`, because the Biscuit grammar requires at least one term per predicate.
-The same holds for `target_unrestricted(true)`, `granted_agent_all(true)` and
-`agent_authorized(true)` below.
+The same holds for `target_unrestricted(true)` below.
`system://sam.catalog` is the built-in discovery service that every node
runs. A role that should be able to list the tools of a node needs it.
@@ -105,8 +112,6 @@ credential can carry: `node` (peer ID), `user`, `email`, `group`,
| `*` | any node |
Exact entries of one fact are merged into one `granted_target_set` fact.
-`agent:` is not a valid target, because a node's identity does not say which
-agents it hosts.
### Label patterns
@@ -116,6 +121,11 @@ agents it hosts.
| `key=*` | any value for that key |
| `*` | any label |
+Keys match `[a-zA-Z0-9_.-]{1,63}`. Values are up to 255 characters with no
+`,`, `=` or control characters. Every label that a node declares must be
+permitted by a role it holds, or enrollment fails. Manual approval of a
+bootstrap enrollment does not bypass this check.
+
### HTTP grants
An entry of `http` narrows one `allowed_services` entry of the same role to
@@ -150,55 +160,6 @@ method (a tunnel, a non-HTTP stream) derives nothing and a narrowed grant
denies it. A role that holds the same service plainly, through another
entry or another role, is not narrowed: grants are a union.
-A node built before this field existed has no derivation rules, so it denies
-a narrowed grant entirely rather than treating it as unrestricted.
-
-## Egress destinations
-
-An entry of `egress` is a destination outside the mesh that selected nodes
-serve as `egress://<name>`. The admin writes it once; each selected node
-receives it at `GET /egress`, registers the service, announces it on the DHT
-and forwards requests to it. Nodes hold no egress configuration of their
-own, and `type: egress` in `sam-node.yaml` is refused.
-
-| Field | Meaning |
-|---|---|
-| `name` | The destination hostname, lowercase, without a port or a path. It is the service name in grants (`egress://<name>`) and in the `service()` fact. One hostname; no wildcard. |
-| `target_url` | Where the serving node forwards requests. Optional; `https://<name>` when empty. `http` or `https`, no credential, no query. |
-| `credential` | Name of the credential the serving node presents to the destination. The node reads the file `<--secrets-dir>/<credential>` (default `/etc/sam/secrets`): `TOKEN` is sent as `Authorization: Bearer TOKEN`, `user:pass` as HTTP Basic. The file is read on every request, so a rotation by the platform applies at once. The value never travels through the control plane. |
-| `served_by` | Role names or `key=value` labels selecting the serving nodes. A node matches when any entry names one of its roles or attested labels. |
-
-The control plane renders one rule per `served_by` entry into the mesh
-policy, `granted_service_exact("egress", "api.github.com") <- role("pep")`
-or `<- label("site", "eu")`, so a serving node authorizes a local request
-with its own credential. Every other caller needs `egress://<name>` on its
-own role. A destination that names a credential the platform did not deliver
-to a node is refused by that node at registration and logged; the other
-destinations are still served.
-
-On an egress request the destination node injects `host()` and `port()`
-next to `method()` and `path()`, and the destination sees the node's
-credential only: the caller's `Authorization`, `Cookie`, `X-Sam-*` and
-`X-Forwarded-*` headers are removed. See [Node API](../node-api/#egress)
-for how a local client reaches a destination.
-
-The control plane warns in its log when a posted destination selects no
-enrolled node, since a selector with a typo is valid in form and would
-otherwise surface only as `404` at the callers.
-
-Keys match `[a-zA-Z0-9_.-]{1,63}`. Values are up to 255 characters with no
-`,`, `=` or control characters. Every label that a node declares must be
-permitted by a role it holds, or enrollment fails. Manual approval of a
-bootstrap enrollment does not bypass this check.
-
-### Agent patterns
-
-An agent identifier is lowercase and dot-separated, with at least two labels
-(`reviewer-7.prod.acme.example`). A pattern is an identifier, `*.<suffix>`,
-`<prefix>.*`, or `*`. Wildcards are anchored on label boundaries. `*` lets
-every holder name any agent, and nodes log a warning when they receive such
-a grant. See the [sandboxed agents preview](../../preview/sandboxed-agents/).
-
### `custom_datalog`
Each entry is one Biscuit Datalog fact or rule. A **fact**
@@ -225,7 +186,6 @@ A member is one of:
| `group:<name>` | an entry of the `groups` claim |
| `idp_role:<name>` | an entry of the issuer's `roles` claim |
| `node:<peer-id>` | one node, by key |
-| `agent:<id>` | an agent identifier that a node names when acting for the agent. Only as trustworthy as the node's `allowed_agents` grant. |
| `sam:system:authenticated` | every identity that the identity provider authenticates |
`role:` is not a member, because a role cannot grant a role. A bootstrap
@@ -233,47 +193,131 @@ token enrollment carries no OIDC claims. Such a node receives exactly the
token's role and nothing that a binding on claims would add, so the grants
must be on the role itself.
+## Egress destinations
+
+An entry of `egress` is a destination outside the mesh that selected nodes
+serve as `egress://<name>`. The admin writes it once; each selected node
+receives it at `GET /egress`, registers the service, announces it on the DHT
+and forwards requests to it. Nodes hold no egress configuration of their
+own, and `type: egress` in `sam-node.yaml` is refused.
+
+| Field | Meaning |
+|---|---|
+| `name` | The destination hostname, lowercase, without a port or a path. It is the service name in grants (`egress://<name>`) and in the `service()` fact. One hostname; no wildcard. |
+| `target_url` | Where the serving node forwards HTTP requests. Optional; `https://<name>` when empty. `http` or `https`, no credential, no query. |
+| `served_by` | Role names or `key=value` labels selecting the serving nodes. A node matches when any entry names one of its roles or attested labels. |
+| `credential` | Shorthand for `broker.static_secret`: name of a file in `<--secrets-dir>/<credential>`. Cannot be combined with `broker`. |
+| `broker` | `CredentialBroker` configuring how the egress node obtains the upstream credential. See [Credential brokers](#credential-brokers). |
+| `inspection` | `Inspection` pipeline executed at the egress node before the upstream credential is injected. See [Content inspection](#content-inspection). |
+| `mode` | `EGRESS_MODE_HTTP` (default) or `EGRESS_MODE_TCP` (named `CONNECT` tunnel). |
+| `ports` | Allowed TCP destination ports when `mode` is `EGRESS_MODE_TCP` (for example, `[5432]`). Empty denies every tunnel. |
+| `preserve_host` | Keep the destination hostname (`name`) in the `Host` header when `target_url` points at an operator inspection chain. |
+| `forward_context` | Forward `X-Sam-Principal`, `X-Sam-Roles` and `X-Sam-Task` to `target_url` when `target_url` is an operator inspection chain. |
+
+### Credential brokers
+
+None of the fields in `broker` is a secret value:
+
+- **`static_secret`** (`string`): name of a file in the node's `--secrets-dir`
+ (default `/etc/sam/secrets`). `TOKEN` is sent as `Authorization: Bearer TOKEN`,
+ `user:pass` as HTTP Basic. Read on every request so file rotations apply
+ immediately.
+- **`oidc_federation`** (`OIDCFederation`): mints a short-lived ES256 border
+ JWT at the control plane (`POST /sts/token`) and exchanges it at an RFC 8693
+ token endpoint:
+ - `token_endpoint`: STS URL (for example, `https://sts.googleapis.com/v1/token`).
+ - `audience`: provider audience (for example, a Google Workload or Workforce
+ Identity Pool provider resource name).
+ - `impersonate`: optional Google Cloud service account email or resource URL
+ for `iamcredentials.generateAccessToken`.
+ - `scopes`: OAuth scopes requested for the upstream token; a
+ `TaskAuthorizationRule` can narrow them further, never widen them.
+- **`aws_assume_role`** (`AWSAssumeRole`): mints a border JWT at the control
+ plane and calls AWS STS `AssumeRoleWithWebIdentity`:
+ - `role_arn`: IAM role ARN to assume.
+ - `session_policy`: optional IAM session policy JSON template intersected with
+ the caller's `TaskAuthorizationRule` (`allowed_permissions` $\rightarrow$
+ `Action`, `allowed_resources` $\rightarrow$ `Resource`).
+- **`platform_identity`** (`PlatformIdentity`): uses the egress node's own
+ ambient cloud identity (such as the GCE/GKE metadata server) narrowed by
+ `scopes`.
+
+### Content inspection
+
+`inspection.inspectors` runs in order before the broker injects the upstream
+credential:
+
+- **`model_armor`**: calls Google Cloud Model Armor `sanitizeUserPrompt` and
+ (when `response` is `RESPONSE_INSPECTION_BUFFERED`) `sanitizeModelResponse`
+ for Gemini, OpenAI chat, MCP `tools/call`, and A2A payloads:
+ - `template`: `projects/<P>/locations/<L>/templates/<T>`.
+ - `response`: `RESPONSE_INSPECTION_BUFFERED` (default) or
+ `RESPONSE_INSPECTION_REQUEST_ONLY`.
+ - `fail_open`: default `false`.
+ - `timeout`: per-call timeout (`google.protobuf.Duration`).
+- **`ext_proc`**: streams the request and response to an Envoy external
+ processor (`envoy.service.ext_proc.v3.ExternalProcessor`) over HTTP/2 gRPC:
+ - `target`: `host:port` or `unix:/path/to.sock`.
+ - `ca`, `client_certificate`: optional file names in `--secrets-dir` for TLS /
+ mTLS to the processor.
+ - `processing_mode`: `request_header_mode`, `response_header_mode`,
+ `request_body_mode`, `response_body_mode`, `request_trailer_mode`,
+ `response_trailer_mode`.
+ - `allow_mode_override`, `message_timeout` (default `200ms`),
+ `failure_mode_allow` (default `false`), `max_buffered_bytes`.
+
+## Task-scoped attenuation (`TaskAuthorizationRule`)
+
+Holders narrow a Biscuit for a task or sub-agent hop by appending a block with
+a single `tar_block("<base64url-proto>")` fact encoding `TaskAuthorizationRule`:
+
+```json
+{
+ "name": "tasks/bq-read-sales",
+ "expire_time": "2026-10-05T12:00:00Z",
+ "rules": [
+ {
+ "allowed_services": ["egress://bigquery.googleapis.com"],
+ "operation": {
+ "allowed_methods": ["GET", "POST"],
+ "allowed_paths": ["/bigquery/v2/projects/my-proj/datasets/sales_2026/*"],
+ "allowed_permissions": ["bigquery.googleapis.com/tables.getData"]
+ },
+ "allowed_resources": [
+ "//bigquery.googleapis.com/projects/my-proj/datasets/sales_2026/*"
+ ]
+ }
+ ]
+}
+```
+
+Across appended blocks `1..k` (up to `MaxAttenuationBlocks = 8`), evaluation is
+strict intersection: a request must pass Block 0 Datalog policy, be before
+every block's `expire_time`, and match at least one `TaskRule` in every
+appended `TaskAuthorizationRule` block.
+
## Evaluation
-At enrollment and at refresh, the control plane resolves the identity's roles
-from the bindings and mints into the credential one `role()` fact per role
-and the compiled `granted_*` facts of every role. The control plane also
-renders the policy as Datalog rules such as
-`role("developer") <- group("engineering")` and
-`granted_service_exact("mcp","code-reviewer") <- role("developer")`, served
-as `datalog_rules` at `GET /policies`. Nodes fetch this text
-(`--control-plane-sync-interval`, 15 minutes) and add it to their authorizer
-as it arrives; no member derives rules from roles and bindings itself, so a
-node written in any language evaluates the same rules. These rules run at
-verification time. Additions therefore reach nodes within the sync interval,
-and removals within the credential TTL.
+At enrollment, refresh, and token exchange, the control plane resolves the
+identity's roles from the bindings and mints into the credential one `role()`
+fact per role and the compiled `granted_*` facts of every role. The control
+plane also renders the policy as Datalog rules served as `datalog_rules` at
+`GET /policies`. Nodes fetch this text (`--control-plane-sync-interval`, 15
+minutes) and add it to their authorizer as it arrives.
At the destination node, in this order:
-1. Facts for the request: `service($type, $name)`, `connection_peer_id($id)`,
- `time($now)`, and `agent($id)` if a claim was made. On an HTTP request,
- `method($m)` and `path($p)`; on a request for an egress destination,
- `host($h)` and `port($n)`.
-2. Checks that always apply: `client_peer_id($id), connection_peer_id($id)`,
- `time($t), expiration($e), $t <= $e`, and `agent_authorized(true)` when an
- agent was named.
-3. The node's own identity as `target_fact($name, $value)` facts.
-4. The node's `attenuation` rules, checks and policies.
-5. Baseline policies: `allow if service($t,$n), granted_service_exact($t,$n)`
- and the set, prefix, suffix, per-type and global variants; the check
- `allow_network_target($f,$v) or target_unrestricted(true)`; the rules that
- derive a service grant from an [HTTP grant](#http-grants).
-6. The synced mesh policy rules.
-
-All checks must hold, and the first matching policy decides. Without a
-matching `allow`, the request is denied.
-
-## Limits
-
-The control plane rejects a policy that could give one identity, through
-overlapping bindings, more Datalog facts than the Biscuit authorizer can
-evaluate. The limit is far above any ordinary policy. A policy that reaches
-it should use wildcards or sets instead of listing every entry.
+1. Structural check on appended blocks (`1..k`): each must contain 0 rules, 0
+ checks, and 1 `tar_block("<base64url-proto>")` fact.
+2. Facts for the request: `service($type, $name)`, `connection_peer_id($id)`,
+ `time($now)`. On an HTTP request, `method($m)` and `path($p)`; on an egress
+ request, `host($h)` and `port($n)`.
+3. Checks that always apply: `client_peer_id($id), connection_peer_id($id)` and
+ `time($t), expiration($e), $t <= $e`.
+4. The node's own identity as `target_fact($name, $value)` facts.
+5. The node's `attenuation` rules, checks and policies.
+6. Baseline policies and the synced mesh policy rules.
+7. `TaskAuthorizationRule` intersection across all appended `tar_block` blocks.
## Datalog vocabulary
@@ -282,31 +326,30 @@ statements.
| Fact | Terms | Minted by |
|---|---|---|
-| `node` | peer ID | control plane |
+| `node` | peer ID | control plane (Member Biscuits) |
+| `actor_node` | peer ID | control plane (Delegated Session Biscuits) |
| `client_peer_id` | peer ID | control plane |
| `expiration` | date | control plane |
| `role` | name | control plane |
| `user`, `email`, `group`, `idp_role` | string | control plane, from OIDC claims |
| `label` | key, value | control plane |
| `right` | `relay` | control plane, for routers |
-| `target_unrestricted` | | control plane, for roles with `allowed_targets: ["*"]` or none |
+| `target_unrestricted` | `true` | control plane, for roles with `allowed_targets: ["*"]` or none |
| `granted_service_exact`, `_set`, `_prefix`, `_suffix`, `_all`, `_all_types` | type, name/set/pattern | control plane and node rules |
| `granted_target_exact`, `_set`, `_prefix`, `_suffix`, `_all`, `_all_facts` | fact, value/set/pattern | control plane and node rules |
-| `granted_agent_exact`, `_set`, `_prefix`, `_suffix`, `_all` | pattern | control plane and node rules |
| `http_granted_service_exact`, `_prefix`, `_suffix`, `_all`, `_all_types` | type, name/pattern | control plane and node rules, for an `http` entry |
| `granted_method`, `granted_method_any` | type, key, set | control plane and node rules, for an `http` entry |
| `granted_path_exact`, `granted_path_prefix`, `granted_path_any` | type, key, set/prefix | control plane and node rules, for an `http` entry |
+| `tar_block` | base64url `TaskAuthorizationRule` | holder, in appended blocks `1..k` |
| `service` | type, name | destination node, per request |
| `connection_peer_id` | peer ID | destination node, per request |
| `time` | date | destination node, per request |
-| `agent` | identifier | destination node, from the caller's claim |
| `method` | string | destination node, on an HTTP request: the method as received; `CONNECT` on a tunnel |
| `path` | string | destination node, on an HTTP request: the path as the backend sees it, leading slash, no query; empty on a tunnel |
| `host` | hostname | destination node, on an egress request |
| `port` | integer | destination node, on an egress request |
| `target_fact` | fact, value | destination node, from its own credential |
| `allow_network_target` | fact, value | derived by baseline rules |
-| `agent_authorized` | | derived by baseline rules |
| `http_method_ok`, `http_path_ok` | type, key | derived by baseline rules |
A node's `attenuation` can refer to the request facts. The Datalog dialect
diff --git a/site/content/docs/reference/sam-node.md b/site/content/docs/reference/sam-node.md
index ad0d5f9b..dd99352b 100644
--- a/site/content/docs/reference/sam-node.md
+++ b/site/content/docs/reference/sam-node.md
@@ -7,11 +7,12 @@ weight: 1
`sam-node` is the mesh member that runs beside an agent or a service.
```text
-sam-node join [control-plane-url] [flags] enroll and store a credential
-sam-node run [flags] run the node
-sam-node reset [--all] [--yes] forget the credential or everything
-sam-node state export|import <dir> move the identity to or from a state directory
-sam-node skill install|list|show manage the agent skill document
+sam-node join [control-plane-url] [flags] enroll and store a credential
+sam-node run [flags] run the node
+sam-node forward egress://<name>:<port> [local-addr] forward a local TCP port to a named egress tunnel
+sam-node reset [--all] [--yes] forget the credential or everything
+sam-node state export|import <dir> move the identity to or from a state directory
+sam-node skill install|list|show manage the agent skill document
```
## Files
diff --git a/site/static/images/agent-mesh-courier.svg b/site/static/images/agent-mesh-courier.svg
new file mode 100644
index 00000000..ed28ed37
--- /dev/null
+++ b/site/static/images/agent-mesh-courier.svg
@@ -0,0 +1,533 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2026 Google LLC
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ How a task travels the mesh, drawn as a courier network. Dark theme for
+ the landing page. SMIL animation: six parcels on a 12s cycle, one every
+ 2s; the Registry stamp thumps only when a passport or a border pass is
+ issued: the developer's second parcel (10s) reuses its passport and nobody
+ calls the Registry. Plays in any browser, including inside an <img> tag.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
+ viewBox="0 0 1240 676" width="1240" height="676"
+ font-family="Inter, -apple-system, 'Segoe UI', Roboto, sans-serif">
+ <title>How a task travels the agent mesh</title>
+ <desc>Agents on a developer laptop, in Kubernetes on premises or in a cloud, on a SaaS platform or inside a sandbox hand each request to their local sam-node office. The first time, the office checks the sender's platform identity at the Registry (the control plane) and receives a passport (the Biscuit authority block: who the sender is and their memberships). For each errand the holder writes a mandate (an attenuation block) that can only narrow. Routers carry the sealed bag and cannot open it. The destination office for mcp://github, mcp://bigquery, inference://gemini, inference://claude, egress://generativelanguage.googleapis.com or a2a://partner-agent reads the passport, the law it already holds and the mandates, decides offline, inspects, and at a cloud border obtains a border pass from the Registry.</desc>
+
+ <defs>
+ <style>
+ .title { font-size: 22px; font-weight: 800; fill: #f8fafc; letter-spacing: 0.02em; }
+ .lead { font-size: 12.5px; fill: #94a3b8; }
+ .name { font-size: 13px; font-weight: 700; fill: #f8fafc; }
+ .sub { font-size: 10.5px; fill: #94a3b8; }
+ .uri { font-family: 'JetBrains Mono', SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; font-weight: 600; fill: #00f0ff; }
+ .uri2 { font-family: 'JetBrains Mono', SFMono-Regular, Menlo, Consolas, monospace; font-size: 11px; font-weight: 600; fill: #00f0ff; }
+ .say { font-size: 11px; font-weight: 600; fill: #07131e; }
+ .legend{ font-size: 11px; fill: #94a3b8; }
+ .sign { font-size: 9px; font-weight: 800; fill: #f6c344; letter-spacing: 0.18em; }
+ .route { fill: none; stroke: #00f0ff; stroke-width: 1.2; opacity: 0.28; }
+ .contact { fill: none; stroke: #f6c344; stroke-width: 1.6; stroke-dasharray: 3 4; }
+ </style>
+
+ <!-- A parcel with a face. Yellow because the mascots are bananas. -->
+ <symbol id="parcel" viewBox="0 0 22 17">
+ <rect x="0.5" y="0.5" width="21" height="16" rx="2" fill="#f6c344" stroke="#7a4e00" stroke-width="1.2"/>
+ <rect x="9.5" y="0.5" width="3" height="16" fill="#7a4e00" opacity="0.35"/>
+ <circle cx="5.5" cy="7" r="1.2" fill="#07131e"/><circle cx="16.5" cy="7" r="1.2" fill="#07131e"/>
+ <path d="M5 11 Q11 14 17 11" fill="none" stroke="#07131e" stroke-width="1.2" stroke-linecap="round"/>
+ </symbol>
+ <!-- The passport: the Biscuit authority block, issued once by the Registry -->
+ <symbol id="passport" viewBox="0 0 14 16">
+ <rect x="0.6" y="0.6" width="12.8" height="14.8" rx="1.6" fill="#0f2238" stroke="#00f0ff" stroke-width="1.2"/>
+ <circle cx="7" cy="6" r="2.6" fill="none" stroke="#f6c344" stroke-width="1.1"/>
+ <rect x="3" y="10.5" width="8" height="1.3" fill="#00f0ff" opacity="0.8"/>
+ <rect x="3" y="13" width="5.5" height="1.3" fill="#00f0ff" opacity="0.8"/>
+ </symbol>
+ <!-- The mandate: an attenuation block, a note the holder writes and signs for one errand -->
+ <symbol id="mandate" viewBox="0 0 13 14">
+ <path d="M0.6 0.6 H9 L12.4 4 V13.4 H0.6 Z" fill="#f8fafc" stroke="#0a7080" stroke-width="1"/>
+ <path d="M9 0.6 V4 H12.4" fill="none" stroke="#0a7080" stroke-width="1"/>
+ <rect x="2.5" y="6" width="8" height="1.2" fill="#0a7080"/><rect x="2.5" y="8.5" width="6" height="1.2" fill="#0a7080"/>
+ <path d="M2.5 11.8 q1.5 -2 3 0 q1.5 2 3 -0.5" fill="none" stroke="#f6c344" stroke-width="1.1" stroke-linecap="round"/>
+ </symbol>
+ <symbol id="lock" viewBox="0 0 12 14">
+ <rect x="1" y="6" width="10" height="7.5" rx="1.5" fill="#94a3b8"/>
+ <path d="M3 6 V4 a3 3 0 0 1 6 0 V6" fill="none" stroke="#94a3b8" stroke-width="1.6"/>
+ </symbol>
+ <symbol id="stamp-ok" viewBox="0 0 14 14">
+ <circle cx="7" cy="7" r="6" fill="#07131e" stroke="#00f0ff" stroke-width="1.6"/>
+ <path d="M4 7.2 L6.2 9.4 L10.2 4.8" fill="none" stroke="#00f0ff" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"/>
+ </symbol>
+ <symbol id="magnifier" viewBox="0 0 14 14">
+ <circle cx="5.5" cy="5.5" r="4" fill="rgba(0,240,255,0.15)" stroke="#f6c344" stroke-width="1.6"/>
+ <path d="M8.5 8.5 L12.5 12.5" stroke="#f6c344" stroke-width="2" stroke-linecap="round"/>
+ </symbol>
+
+ <!-- A sam-node office at the edge: the post office that checks and stamps -->
+ <symbol id="office" viewBox="0 0 64 40">
+ <path d="M2 14 L32 2 L62 14 Z" fill="#132a44" stroke="#00f0ff" stroke-width="1.6" stroke-linejoin="round"/>
+ <rect x="4" y="14" width="56" height="24" rx="3" fill="#0f2238" stroke="#00f0ff" stroke-width="1.6"/>
+ <text x="32" y="23" text-anchor="middle" style="font-family:'JetBrains Mono',SFMono-Regular,Menlo,Consolas,monospace;font-size:7.5px;font-weight:700;fill:#00f0ff;letter-spacing:0.04em">sam-node</text>
+ <rect x="26" y="27" width="12" height="11" rx="1.5" fill="#132a44" stroke="#00f0ff" stroke-width="1.2"/>
+ <rect x="8" y="27" width="10" height="7" rx="1" fill="#132a44" stroke="#00f0ff" stroke-width="1"/>
+ <rect x="46" y="27" width="10" height="7" rx="1" fill="#132a44" stroke="#00f0ff" stroke-width="1"/>
+ </symbol>
+ <!-- A sam-router at the core: a relay, grey because it only forwards -->
+ <symbol id="relay" viewBox="-14 -14 28 28">
+ <path d="M-10 -5 a11 11 0 0 0 0 10 M10 -5 a11 11 0 0 1 0 10" fill="none" stroke="#94a3b8" stroke-width="1.4" stroke-linecap="round" opacity="0.8"/>
+ <circle r="6" fill="#0f2238" stroke="#94a3b8" stroke-width="2"/>
+ <circle r="2" fill="#94a3b8"/>
+ </symbol>
+
+ <!-- Kubernetes: the heptagon with a helm inside -->
+ <symbol id="helm" viewBox="-10 -10 20 20">
+ <polygon points="0,-9 7.1,-5.6 8.8,2 4,8.1 -4,8.1 -8.8,2 -7.1,-5.6" fill="#0f2238" stroke="#00f0ff" stroke-width="1.6" stroke-linejoin="round"/>
+ <circle cx="0" cy="0" r="3.2" fill="none" stroke="#00f0ff" stroke-width="1.4"/>
+ <path d="M0 -3.2 V-6 M0 3.2 V6 M-3.2 0 H-6 M3.2 0 H6 M-2.3 -2.3 L-4.2 -4.2 M2.3 2.3 L4.2 4.2 M2.3 -2.3 L4.2 -4.2 M-2.3 2.3 L-4.2 4.2" stroke="#00f0ff" stroke-width="1.2" stroke-linecap="round"/>
+ </symbol>
+
+ <!-- Sender icons, 60x56 -->
+ <symbol id="ico-dev" viewBox="0 0 60 56">
+ <rect x="4" y="8" width="38" height="26" rx="3" fill="#0f2238" stroke="#00f0ff" stroke-width="2"/>
+ <path d="M0 38 H46 L42 44 H4 Z" fill="#132a44" stroke="#00f0ff" stroke-width="2" stroke-linejoin="round"/>
+ <circle cx="17" cy="19" r="2" fill="#00f0ff"/><circle cx="29" cy="19" r="2" fill="#00f0ff"/>
+ <path d="M16 26 Q23 31 30 26" fill="none" stroke="#00f0ff" stroke-width="2" stroke-linecap="round"/>
+ <rect x="47" y="30" width="10" height="11" rx="2" fill="#132a44" stroke="#f6c344" stroke-width="2"/>
+ <path d="M57 33 h2 a2.5 2.5 0 0 1 0 5 h-2" fill="none" stroke="#f6c344" stroke-width="2"/>
+ <g stroke="#f6c344" stroke-width="1.5" stroke-linecap="round" fill="none" opacity="0.8">
+ <path d="M50 26 q1.5 -2 0 -4 q-1.5 -2 0 -4"><animate attributeName="opacity" values="0.3;0.9;0.3" dur="1.6s" repeatCount="indefinite"/></path>
+ <path d="M54 26 q1.5 -2 0 -4 q-1.5 -2 0 -4"><animate attributeName="opacity" values="0.9;0.3;0.9" dur="1.6s" repeatCount="indefinite"/></path>
+ </g>
+ </symbol>
+ <symbol id="ico-k8s-onprem" viewBox="0 0 60 56">
+ <rect x="6" y="2" width="36" height="52" rx="3" fill="#0f2238" stroke="#00f0ff" stroke-width="2"/>
+ <g stroke="#00f0ff" stroke-width="2" opacity="0.45"><line x1="11" y1="12" x2="29" y2="12"/><line x1="11" y1="22" x2="29" y2="22"/><line x1="11" y1="32" x2="29" y2="32"/></g>
+ <circle cx="36" cy="12" r="1.8" fill="#00f0ff"><animate attributeName="opacity" values="1;0.2;1" dur="1.1s" repeatCount="indefinite"/></circle>
+ <circle cx="36" cy="22" r="1.8" fill="#f6c344"><animate attributeName="opacity" values="0.2;1;0.2" dur="1.7s" repeatCount="indefinite"/></circle>
+ <circle cx="36" cy="32" r="1.8" fill="#00f0ff"><animate attributeName="opacity" values="1;0.2;1" dur="0.8s" repeatCount="indefinite"/></circle>
+ <use xlink:href="#helm" x="30" y="30" width="28" height="28"/>
+ </symbol>
+ <symbol id="ico-k8s-cloud" viewBox="0 0 60 56">
+ <path d="M14 46 H46 a10 10 0 0 0 1.6 -19.9 A14 14 0 0 0 20.8 22.2 A11 11 0 0 0 14 46 Z" fill="#0f2238" stroke="#00f0ff" stroke-width="2" stroke-linejoin="round">
+ <animateTransform attributeName="transform" type="translate" values="0 0;1.5 0;0 0" dur="3s" repeatCount="indefinite"/>
+ </path>
+ <use xlink:href="#helm" x="18" y="22" width="26" height="26"/>
+ </symbol>
+ <symbol id="ico-saas" viewBox="0 0 60 56">
+ <rect x="4" y="6" width="52" height="44" rx="4" fill="#0f2238" stroke="#00f0ff" stroke-width="2"/>
+ <line x1="4" y1="17" x2="56" y2="17" stroke="#00f0ff" stroke-width="2"/>
+ <circle cx="11" cy="11.5" r="1.8" fill="#00f0ff"/><circle cx="17" cy="11.5" r="1.8" fill="#00f0ff"/><circle cx="23" cy="11.5" r="1.8" fill="#00f0ff"/>
+ <path d="M33 21 L23 35 H30 L28 46 L38 31 H31 Z" fill="#f6c344">
+ <animate attributeName="opacity" values="1;1;0.5;1;1" keyTimes="0;0.6;0.65;0.7;1" dur="2.6s" repeatCount="indefinite"/>
+ </path>
+ </symbol>
+ <symbol id="ico-sandbox" viewBox="0 0 60 56">
+ <path d="M8 24 H52 L47 52 H13 Z" fill="#0f2238" stroke="#00f0ff" stroke-width="2" stroke-linejoin="round"/>
+ <rect x="5" y="19" width="50" height="7" rx="2" fill="#132a44" stroke="#00f0ff" stroke-width="2"/>
+ <path d="M13 32 q5 -5 10 0 q5 -5 10 0 q5 -5 10 0 q2 -2 4 0" fill="none" stroke="#f6c344" stroke-width="2" stroke-linecap="round" opacity="0.8"/>
+ <line x1="40" y1="2" x2="34" y2="21" stroke="#f6c344" stroke-width="2.5" stroke-linecap="round"/>
+ <path d="M31 19 l8 2 l-2 8 l-8 -2 z" fill="#f6c344"/>
+ <rect x="24" y="40" width="12" height="9" rx="2" fill="#f6c344"/>
+ <path d="M27 40 v-3 a3 3 0 0 1 6 0 v3" fill="none" stroke="#f6c344" stroke-width="2"/>
+ </symbol>
+
+ <!-- Destination booth, 260x58 -->
+ <symbol id="booth" viewBox="0 0 260 58">
+ <path d="M4 16 L130 2 L256 16 Z" fill="#132a44" stroke="#00f0ff" stroke-width="1.5" stroke-linejoin="round"/>
+ <rect x="8" y="16" width="244" height="40" rx="4" fill="#0f2238" stroke="#00f0ff" stroke-width="1.5"/>
+ <rect x="236" y="24" width="10" height="4" rx="2" fill="#00f0ff" opacity="0.6"/>
+ </symbol>
+ <!-- Destination glyphs, 24x24 -->
+ <symbol id="g-fork" viewBox="0 0 24 24">
+ <circle cx="6" cy="5" r="2.5" fill="none" stroke="#00f0ff" stroke-width="1.8"/><circle cx="18" cy="5" r="2.5" fill="none" stroke="#00f0ff" stroke-width="1.8"/><circle cx="12" cy="19" r="2.5" fill="none" stroke="#00f0ff" stroke-width="1.8"/>
+ <path d="M6 7.5 V10 a4 4 0 0 0 4 4 h4 a4 4 0 0 0 4 -4 V7.5 M12 14 V16.5" fill="none" stroke="#00f0ff" stroke-width="1.8"/>
+ </symbol>
+ <symbol id="g-table" viewBox="0 0 24 24">
+ <rect x="3" y="4" width="18" height="16" rx="2" fill="none" stroke="#00f0ff" stroke-width="1.8"/>
+ <path d="M3 9.5 H21 M3 15 H21 M9 4 V20 M15 4 V20" stroke="#00f0ff" stroke-width="1.4" opacity="0.8"/>
+ </symbol>
+ <symbol id="g-sparkle" viewBox="0 0 24 24">
+ <path d="M12 2 C12.6 8 15 10.4 21 12 C15 13.6 12.6 16 12 22 C11.4 16 9 13.6 3 12 C9 10.4 11.4 8 12 2 Z" fill="#00f0ff">
+ <animateTransform attributeName="transform" type="rotate" values="0 12 12;20 12 12;0 12 12" dur="3s" repeatCount="indefinite"/>
+ </path>
+ </symbol>
+ <symbol id="g-bubble" viewBox="0 0 24 24">
+ <path d="M4 5 H20 a2 2 0 0 1 2 2 V14 a2 2 0 0 1 -2 2 H11 L6 20 V16 H4 a2 2 0 0 1 -2 -2 V7 a2 2 0 0 1 2 -2 Z" fill="none" stroke="#00f0ff" stroke-width="1.8" stroke-linejoin="round"/>
+ <circle cx="8" cy="10.5" r="1.3" fill="#00f0ff"/><circle cx="12" cy="10.5" r="1.3" fill="#00f0ff"/><circle cx="16" cy="10.5" r="1.3" fill="#00f0ff"/>
+ </symbol>
+ <symbol id="g-globe" viewBox="0 0 24 24">
+ <circle cx="11" cy="12" r="8" fill="none" stroke="#00f0ff" stroke-width="1.8"/>
+ <ellipse cx="11" cy="12" rx="3.5" ry="8" fill="none" stroke="#00f0ff" stroke-width="1.2" opacity="0.8"/>
+ <path d="M3 12 H19" stroke="#00f0ff" stroke-width="1.2" opacity="0.8"/>
+ <path d="M16 5 L22 5 L22 11 M22 5 L16.5 10.5" fill="none" stroke="#f6c344" stroke-width="1.8" stroke-linecap="round"/>
+ </symbol>
+ <symbol id="g-robots" viewBox="0 0 24 24">
+ <rect x="2" y="9" width="8" height="8" rx="1.5" fill="none" stroke="#00f0ff" stroke-width="1.6"/><circle cx="4.8" cy="13" r="1" fill="#00f0ff"/><circle cx="7.2" cy="13" r="1" fill="#00f0ff"/><line x1="6" y1="9" x2="6" y2="6" stroke="#00f0ff" stroke-width="1.6"/><circle cx="6" cy="5.2" r="1.1" fill="#f6c344"/>
+ <rect x="14" y="9" width="8" height="8" rx="1.5" fill="none" stroke="#00f0ff" stroke-width="1.6"/><circle cx="16.8" cy="13" r="1" fill="#00f0ff"/><circle cx="19.2" cy="13" r="1" fill="#00f0ff"/><line x1="18" y1="9" x2="18" y2="6" stroke="#00f0ff" stroke-width="1.6"/><circle cx="18" cy="5.2" r="1.1" fill="#f6c344"/>
+ <path d="M10.5 13 H13.5" stroke="#f6c344" stroke-width="1.6" stroke-dasharray="1.5 1.5"/>
+ </symbol>
+ </defs>
+
+ <!-- Card -->
+ <rect x="0.75" y="0.75" width="1238.5" height="674.5" rx="22" fill="#0a1526" fill-opacity="0.92" stroke="#00f0ff" stroke-opacity="0.18"/>
+
+ <text x="28" y="38" class="title">How a task travels the mesh</text>
+ <text x="28" y="58" class="lead">Every parcel carries its sender's passport and a mandate for this errand.</text>
+ <text x="28" y="76" class="lead">Every office reads them and decides alone.</text>
+ <g>
+ <rect x="818" y="24" width="394" height="22" rx="11" fill="none" stroke="#00f0ff" stroke-opacity="0.45"/>
+ <text x="1015" y="39" text-anchor="middle" class="sub" fill="#00f0ff" style="fill:#00f0ff;font-weight:600">Not another gateway: Istio, agentgateway and kgateway ask SAM over ext_proc</text>
+ </g>
+
+ <!-- Edge / core headers -->
+ <text x="306" y="130" text-anchor="middle" class="sub" style="fill:#00f0ff;font-weight:700;letter-spacing:0.12em">EDGE · SAM-NODE OFFICES</text>
+ <text x="1090" y="130" text-anchor="middle" class="sub" style="fill:#00f0ff;font-weight:700;letter-spacing:0.12em">EDGE · SAM-NODE OFFICES</text>
+
+ <!-- Core band -->
+ <rect x="342" y="168" width="516" height="352" rx="18" fill="#00f0ff" fill-opacity="0.03" stroke="#94a3b8" stroke-opacity="0.3" stroke-dasharray="4 6"/>
+ <text x="600" y="186" text-anchor="middle" class="sub" style="fill:#94a3b8;font-weight:700;letter-spacing:0.12em">CORE · SAM-ROUTERS</text>
+ <text x="600" y="508" text-anchor="middle" class="sub">relay only · the bag is sealed between two offices, a router cannot open it</text>
+
+ <!-- Routes: the parcels travel along these -->
+ <g class="route">
+ <path id="p1" d="M310,190 L360,210 L580,260 L710,350 L960,410"/>
+ <path id="p2" d="M310,280 L450,330 L580,260 L820,230 L960,250"/>
+ <path id="p3" d="M310,550 L370,480 L600,440 L710,350 L820,230 L960,170"/>
+ <path id="p4" d="M310,460 L370,480 L600,440 L830,470 L960,490"/>
+ <path id="p5" d="M310,370 L416,370 L450,330 L600,440 L830,470 L960,570"/>
+ <path id="p6" d="M310,190 L360,210 L580,260 L710,350 L960,330"/>
+ <path d="M360,210 L450,330 L370,480 M450,330 L600,440 L830,470 L820,230 L710,350 L600,440 M580,260 L820,230"/>
+ </g>
+
+ <!-- Registry contact lines, lit only when an office needs the Registry: a new sender, or a foreign border -->
+ <g class="contact">
+ <line x1="306" y1="170" x2="600" y2="132" opacity="0"><animate attributeName="opacity" dur="12s" begin="0s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.03;0.04;0.08;0.09;1"/></line>
+ <line x1="306" y1="260" x2="600" y2="132" opacity="0"><animate attributeName="opacity" dur="12s" begin="2s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.03;0.04;0.08;0.09;1"/></line>
+ <line x1="306" y1="530" x2="600" y2="132" opacity="0"><animate attributeName="opacity" dur="12s" begin="4s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.03;0.04;0.08;0.09;1"/></line>
+ <line x1="306" y1="440" x2="600" y2="132" opacity="0"><animate attributeName="opacity" dur="12s" begin="6s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.03;0.04;0.08;0.09;1"/></line>
+ <!-- the only destination that needs the Registry: a cloud border does not read passports, so a border pass is written (and cached) -->
+ <line x1="960" y1="490" x2="600" y2="132" opacity="0"><animate attributeName="opacity" dur="12s" begin="6s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.68;0.69;0.73;0.74;1"/></line>
+ <!-- row 3: the gateway asks its sam-node over ext_proc, the sam-node asks the Registry -->
+ <line x1="320" y1="370" x2="352" y2="370" opacity="0"><animate attributeName="opacity" dur="12s" begin="8s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.02;0.03;0.08;0.09;1"/></line>
+ <line x1="384" y1="350" x2="600" y2="132" opacity="0"><animate attributeName="opacity" dur="12s" begin="8s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.03;0.04;0.08;0.09;1"/></line>
+ <!-- the developer's second parcel (10s): same passport, no call -->
+ </g>
+
+ <!-- The law goes out, not the parcels: policy, revocations and the public key reach every office on a timer -->
+ <circle cx="600" cy="100" r="30" fill="none" stroke="#f6c344" stroke-width="1.2" stroke-dasharray="2 6" opacity="0">
+ <animate attributeName="r" values="30;560" dur="6s" repeatCount="indefinite"/>
+ <animate attributeName="opacity" values="0.55;0" dur="6s" repeatCount="indefinite"/>
+ </circle>
+
+ <!-- Routers: grey relays, each breathing on its own rhythm -->
+ <g>
+ <g transform="translate(360,210)"><circle r="11" fill="#94a3b8" opacity="0.1"><animate attributeName="r" values="9;16;9" dur="2.6s" repeatCount="indefinite"/></circle><use xlink:href="#relay" x="-14" y="-14" width="28" height="28"/></g>
+ <g transform="translate(450,330)"><circle r="11" fill="#94a3b8" opacity="0.1"><animate attributeName="r" values="9;16;9" dur="3.1s" repeatCount="indefinite"/></circle><use xlink:href="#relay" x="-14" y="-14" width="28" height="28"/></g>
+ <g transform="translate(370,480)"><circle r="11" fill="#94a3b8" opacity="0.1"><animate attributeName="r" values="9;16;9" dur="2.2s" repeatCount="indefinite"/></circle><use xlink:href="#relay" x="-14" y="-14" width="28" height="28"/></g>
+ <g transform="translate(580,260)"><circle r="11" fill="#94a3b8" opacity="0.1"><animate attributeName="r" values="9;16;9" dur="2.9s" repeatCount="indefinite"/></circle><use xlink:href="#relay" x="-14" y="-14" width="28" height="28"/></g>
+ <g transform="translate(600,440)"><circle r="11" fill="#94a3b8" opacity="0.1"><animate attributeName="r" values="9;16;9" dur="2.4s" repeatCount="indefinite"/></circle><use xlink:href="#relay" x="-14" y="-14" width="28" height="28"/></g>
+ <g transform="translate(710,350)"><circle r="11" fill="#94a3b8" opacity="0.1"><animate attributeName="r" values="9;16;9" dur="3.4s" repeatCount="indefinite"/></circle><use xlink:href="#relay" x="-14" y="-14" width="28" height="28"/></g>
+ <g transform="translate(820,230)"><circle r="11" fill="#94a3b8" opacity="0.1"><animate attributeName="r" values="9;16;9" dur="2.7s" repeatCount="indefinite"/></circle><use xlink:href="#relay" x="-14" y="-14" width="28" height="28"/></g>
+ <g transform="translate(830,470)"><circle r="11" fill="#94a3b8" opacity="0.1"><animate attributeName="r" values="9;16;9" dur="2.0s" repeatCount="indefinite"/></circle><use xlink:href="#relay" x="-14" y="-14" width="28" height="28"/></g>
+ </g>
+
+ <!-- Bring your own gateway: it stays in the data path and asks the sam-node office over ext_proc -->
+ <g>
+ <g transform="translate(306,370)">
+ <polygon points="0,-13 11.3,-6.5 11.3,6.5 0,13 -11.3,6.5 -11.3,-6.5" fill="#132a44" stroke="#00f0ff" stroke-width="2" stroke-linejoin="round"/>
+ <path d="M-5 -4 L0 0 L-5 4 M1 -4 L6 0 L1 4" fill="none" stroke="#00f0ff" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"/>
+ </g>
+ <text x="306" y="396" text-anchor="middle" class="sub" style="fill:#f8fafc;font-weight:700">your gateway</text>
+ <text x="306" y="408" text-anchor="middle" class="sub">Istio · agentgateway · kgateway</text>
+ <line x1="320" y1="370" x2="352" y2="370" stroke="#00f0ff" stroke-width="1.4" stroke-dasharray="2 3" opacity="0.8"/>
+ <text x="336" y="363" text-anchor="middle" class="uri2" style="font-size:9px">ext_proc</text>
+ <use xlink:href="#office" x="352" y="350" width="64" height="40"/>
+ </g>
+
+ <!-- Registry: the post office that stamps -->
+ <g transform="translate(600,70)">
+ <path d="M-72 10 L0 -22 L72 10 Z" fill="#132a44" stroke="#f6c344" stroke-width="2" stroke-linejoin="round"/>
+ <line x1="0" y1="-22" x2="0" y2="-40" stroke="#f6c344" stroke-width="2"/>
+ <path d="M0 -40 L18 -35 L0 -30 Z" fill="#f6c344"><animateTransform attributeName="transform" type="skewY" values="0;6;0;-4;0" dur="1.8s" repeatCount="indefinite"/></path>
+ <rect x="-62" y="10" width="124" height="52" fill="#0f2238" stroke="#f6c344" stroke-width="2"/>
+ <text x="0" y="27" text-anchor="middle" class="sign">REGISTRY</text>
+ <rect x="-12" y="34" width="24" height="28" rx="2" fill="#132a44" stroke="#f6c344" stroke-width="1.5"/>
+ <rect x="-50" y="34" width="20" height="14" rx="1.5" fill="#132a44" stroke="#f6c344" stroke-width="1.5"/>
+ <rect x="30" y="34" width="20" height="14" rx="1.5" fill="#132a44" stroke="#f6c344" stroke-width="1.5"/>
+ <!-- passport card and the rubber stamp; thumps only when a passport (0,2,4,6,8s) or the border pass (~2.3s) is issued, never at 10s -->
+ <rect x="80" y="34" width="26" height="16" rx="2" fill="#f8fafc" stroke="#0a7080" stroke-width="1"/>
+ <use xlink:href="#stamp-ok" x="86" y="35" width="14" height="14" opacity="0"><animate attributeName="opacity" dur="12s" repeatCount="indefinite" values="0;0;1;1;0;0;1;1;0;0;1;1;0;0;1;1;0;0;1;1;0;0" keyTimes="0;0.0417;0.05;0.15;0.16;0.2083;0.2167;0.3167;0.3267;0.375;0.3833;0.4833;0.4933;0.5417;0.55;0.65;0.66;0.7083;0.7167;0.8167;0.8267;1"/></use>
+ <g>
+ <animateTransform attributeName="transform" type="translate" dur="12s" repeatCount="indefinite" calcMode="linear" values="0 0;0 0;0 11;0 11;0 0;0 0;0 11;0 11;0 0;0 0;0 11;0 11;0 0;0 0;0 11;0 11;0 0;0 0;0 11;0 11;0 0;0 0" keyTimes="0;0.0217;0.0417;0.0717;0.1017;0.1883;0.2083;0.2383;0.2683;0.355;0.375;0.405;0.435;0.5217;0.5417;0.5717;0.6017;0.6883;0.7083;0.7383;0.7683;1"/>
+ <rect x="87" y="2" width="12" height="16" rx="3" fill="#f6c344"/>
+ <rect x="78" y="17" width="30" height="8" rx="2" fill="#d9a62e" stroke="#7a4e00" stroke-width="1"/>
+ </g>
+ <text x="0" y="78" text-anchor="middle" class="sub">sam-control-plane · issues passports · writes the law and the watchlist · never touches a parcel</text>
+ <text x="0" y="91" text-anchor="middle" class="sub" style="fill:#f6c344;opacity:0.85">◌ law, watchlist and seal specimen reach every office on a timer</text>
+ </g>
+
+ <!-- Senders, each with its sam-node office -->
+ <g>
+ <use xlink:href="#ico-dev" x="36" y="162" width="60" height="56"/>
+ <text x="106" y="186" class="name">Developer</text>
+ <text x="106" y="200" class="sub">laptop, CLI agent, coffee</text>
+ <use xlink:href="#office" x="274" y="170" width="64" height="40"/>
+
+ <use xlink:href="#ico-k8s-onprem" x="36" y="252" width="60" height="56"/>
+ <text x="106" y="276" class="name">Kubernetes on premises</text>
+ <text x="106" y="290" class="sub">pods, projected SA token</text>
+ <use xlink:href="#office" x="274" y="260" width="64" height="40"/>
+
+ <use xlink:href="#ico-k8s-cloud" x="36" y="342" width="60" height="56"/>
+ <text x="106" y="366" class="name">Kubernetes in a cloud</text>
+ <text x="106" y="380" class="sub">a gateway already in path</text>
+
+ <use xlink:href="#ico-saas" x="36" y="432" width="60" height="56"/>
+ <text x="106" y="456" class="name">SaaS platform</text>
+ <text x="106" y="470" class="sub">hosted agents, same passport</text>
+ <use xlink:href="#office" x="274" y="440" width="64" height="40"/>
+
+ <use xlink:href="#ico-sandbox" x="36" y="522" width="60" height="56"/>
+ <text x="106" y="546" class="name">Sandbox platform</text>
+ <text x="106" y="560" class="sub">the agent inside holds nothing</text>
+ <use xlink:href="#office" x="274" y="530" width="64" height="40"/>
+ </g>
+
+ <!-- Destination offices: each booth is the egress sam-node for one destination -->
+ <g>
+ <g style="font-family:'JetBrains Mono',SFMono-Regular,Menlo,Consolas,monospace;font-size:7.5px;font-weight:700;fill:#00f0ff;letter-spacing:0.04em" text-anchor="middle">
+ <text x="1090" y="154.5">sam-node</text><text x="1090" y="234.5">sam-node</text><text x="1090" y="314.5">sam-node</text>
+ <text x="1090" y="394.5">sam-node</text><text x="1090" y="474.5">sam-node</text><text x="1090" y="554.5">sam-node</text>
+ </g>
+ <use xlink:href="#booth" x="960" y="141" width="260" height="58"/>
+ <use xlink:href="#g-fork" x="980" y="163" width="24" height="24"/>
+ <text x="1014" y="181" class="uri">mcp://github</text>
+
+ <use xlink:href="#booth" x="960" y="221" width="260" height="58"/>
+ <use xlink:href="#g-table" x="980" y="243" width="24" height="24"/>
+ <text x="1014" y="261" class="uri">mcp://bigquery</text>
+
+ <use xlink:href="#booth" x="960" y="301" width="260" height="58"/>
+ <use xlink:href="#g-sparkle" x="980" y="323" width="24" height="24"/>
+ <text x="1014" y="341" class="uri">inference://gemini</text>
+
+ <use xlink:href="#booth" x="960" y="381" width="260" height="58"/>
+ <use xlink:href="#g-bubble" x="980" y="403" width="24" height="24"/>
+ <text x="1014" y="421" class="uri">inference://claude</text>
+
+ <use xlink:href="#booth" x="960" y="461" width="260" height="58"/>
+ <use xlink:href="#g-globe" x="980" y="483" width="24" height="24"/>
+ <text x="1010" y="494" class="uri2" style="font-size:10px">egress://</text>
+ <text x="1010" y="508" class="uri2" style="font-size:10px">generativelanguage.googleapis.com</text>
+
+ <use xlink:href="#booth" x="960" y="541" width="260" height="58"/>
+ <use xlink:href="#g-robots" x="980" y="563" width="24" height="24"/>
+ <text x="1014" y="581" class="uri">a2a://partner-agent</text>
+
+ <!-- delivery flashes -->
+ <g fill="none" stroke="#00f0ff" stroke-width="3">
+ <rect x="966" y="155" width="248" height="42" rx="5" opacity="0"><animate attributeName="opacity" dur="12s" begin="0s" repeatCount="indefinite" values="0;0;0.9;0;0" keyTimes="0;0.82;0.84;0.90;1"/></rect>
+ <rect x="966" y="235" width="248" height="42" rx="5" opacity="0"><animate attributeName="opacity" dur="12s" begin="2s" repeatCount="indefinite" values="0;0;0.9;0;0" keyTimes="0;0.82;0.84;0.90;1"/></rect>
+ <rect x="966" y="315" width="248" height="42" rx="5" opacity="0"><animate attributeName="opacity" dur="12s" begin="10s" repeatCount="indefinite" values="0;0;0.9;0;0" keyTimes="0;0.82;0.84;0.90;1"/></rect>
+ <rect x="966" y="395" width="248" height="42" rx="5" opacity="0"><animate attributeName="opacity" dur="12s" begin="0s" repeatCount="indefinite" values="0;0;0.9;0;0" keyTimes="0;0.82;0.84;0.90;1"/></rect>
+ <rect x="966" y="475" width="248" height="42" rx="5" opacity="0"><animate attributeName="opacity" dur="12s" begin="6s" repeatCount="indefinite" values="0;0;0.9;0;0" keyTimes="0;0.82;0.84;0.90;1"/></rect>
+ <rect x="966" y="555" width="248" height="42" rx="5" opacity="0"><animate attributeName="opacity" dur="12s" begin="8s" repeatCount="indefinite" values="0;0;0.9;0;0" keyTimes="0;0.82;0.84;0.90;1"/></rect>
+ </g>
+ </g>
+
+ <!-- What the offices say -->
+ <g>
+ <!-- sender side: a first visit needs the Registry once; a known passport does not -->
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="0s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.02;0.035;0.10;0.12;1"/>
+ <rect x="104" y="150" width="292" height="20" rx="10" fill="#f6c344"/><text x="114" y="164" class="say">First visit: the Registry issues the passport.</text></g>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="2s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.02;0.035;0.10;0.12;1"/>
+ <rect x="104" y="240" width="292" height="20" rx="10" fill="#f6c344"/><text x="114" y="254" class="say">First visit: the Registry issues the passport.</text></g>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="4s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.02;0.035;0.10;0.12;1"/>
+ <rect x="104" y="510" width="292" height="20" rx="10" fill="#f6c344"/><text x="114" y="524" class="say">First visit: the Registry issues the passport.</text></g>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="6s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.02;0.035;0.10;0.12;1"/>
+ <rect x="104" y="420" width="292" height="20" rx="10" fill="#f6c344"/><text x="114" y="434" class="say">First visit: the Registry issues the passport.</text></g>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="8s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.02;0.035;0.10;0.12;1"/>
+ <rect x="150" y="318" width="292" height="20" rx="10" fill="#f6c344"/><text x="160" y="332" class="say">Gateway → office over ext_proc: passport issued.</text></g>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="10s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.02;0.035;0.10;0.12;1"/>
+ <rect x="104" y="150" width="292" height="20" rx="10" fill="#f6c344"/><text x="114" y="164" class="say">Known passport. New mandate, narrower. Go.</text></g>
+
+ <!-- destination side: every office decides offline; only the cloud border needs a border pass -->
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="0s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.60;0.615;0.71;0.72;1"/>
+ <rect x="650" y="400" width="296" height="20" rx="10" fill="#00f0ff"/><text x="660" y="414" class="say">Passport ✓ law ✓ mandate ✓ customs ✓ — decided here.</text></g>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="0s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.72;0.735;0.82;0.84;1"/>
+ <rect x="860" y="400" width="86" height="20" rx="10" fill="#00f0ff"/><text x="870" y="414" class="say">Delivered!</text></g>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="2s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.60;0.615;0.71;0.72;1"/>
+ <rect x="650" y="240" width="296" height="20" rx="10" fill="#00f0ff"/><text x="660" y="254" class="say">Passport ✓ law ✓ mandate ✓ customs ✓ — decided here.</text></g>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="2s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.72;0.735;0.82;0.84;1"/>
+ <rect x="860" y="240" width="86" height="20" rx="10" fill="#00f0ff"/><text x="870" y="254" class="say">Delivered!</text></g>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="4s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.60;0.615;0.71;0.72;1"/>
+ <rect x="650" y="160" width="296" height="20" rx="10" fill="#00f0ff"/><text x="660" y="174" class="say">Passport ✓ law ✓ mandate ✓ customs ✓ — decided here.</text></g>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="4s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.72;0.735;0.82;0.84;1"/>
+ <rect x="860" y="160" width="86" height="20" rx="10" fill="#00f0ff"/><text x="870" y="174" class="say">Delivered!</text></g>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="6s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.60;0.615;0.71;0.72;1"/>
+ <rect x="650" y="480" width="296" height="20" rx="10" fill="#00f0ff"/><text x="660" y="494" class="say">Passport ✓ law ✓ mandate ✓ — cloud border ahead.</text></g>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="6s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.72;0.735;0.82;0.84;1"/>
+ <rect x="650" y="480" width="296" height="20" rx="10" fill="#00f0ff"/><text x="660" y="494" class="say">Border pass from the Registry, cached. Delivered!</text></g>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="8s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.60;0.615;0.71;0.72;1"/>
+ <rect x="650" y="560" width="296" height="20" rx="10" fill="#00f0ff"/><text x="660" y="574" class="say">Partner office: our Registry's seal ✓ mandate ✓. Go.</text></g>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="8s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.72;0.735;0.82;0.84;1"/>
+ <rect x="860" y="560" width="86" height="20" rx="10" fill="#00f0ff"/><text x="870" y="574" class="say">Delivered!</text></g>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="10s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.60;0.615;0.71;0.72;1"/>
+ <rect x="650" y="320" width="296" height="20" rx="10" fill="#00f0ff"/><text x="660" y="334" class="say">Passport ✓ law ✓ mandate ✓ customs ✓ — decided here.</text></g>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="10s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.72;0.735;0.82;0.84;1"/>
+ <rect x="860" y="320" width="86" height="20" rx="10" fill="#00f0ff"/><text x="870" y="334" class="say">Delivered!</text></g>
+ </g>
+
+ <!--
+ Parcel timeline, fraction of 12s:
+ 0.00-0.10 at the sender's office (passport and mandate pop at 0.11, as the parcel leaves)
+ 0.10-0.60 in transit, locked
+ 0.60-0.72 customs: magnifier sweeps
+ 0.72-0.82 permit stamp shows
+ 0.82-0.86 delivered: parcel fades, confetti
+ -->
+ <g id="parcels">
+ <!-- 1: Developer -> inference://claude -->
+ <g opacity="0">
+ <animateMotion dur="12s" begin="0s" repeatCount="indefinite" calcMode="linear" keyPoints="0;0;1;1;1" keyTimes="0;0.10;0.60;0.82;1"><mpath xlink:href="#p1"/></animateMotion>
+ <animate attributeName="opacity" dur="12s" begin="0s" repeatCount="indefinite" values="0;1;1;1;0;0" keyTimes="0;0.02;0.80;0.82;0.86;1"/>
+ <g><animateTransform attributeName="transform" type="translate" values="0 0;0 -3;0 0" dur="0.7s" repeatCount="indefinite"/>
+ <use xlink:href="#parcel" x="-11" y="-8" width="22" height="17"/>
+ <g><animateTransform attributeName="transform" type="scale" dur="12s" begin="0s" repeatCount="indefinite" values="0;0;1.3;1;1;0;0" keyTimes="0;0.10;0.115;0.13;0.82;0.86;1"/><use xlink:href="#passport" x="4" y="-27" width="14" height="16"/><use xlink:href="#mandate" x="19" y="-25" width="13" height="14"/></g>
+ <use xlink:href="#lock" x="8" y="2" width="10" height="12" opacity="0"><animate attributeName="opacity" dur="12s" begin="0s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.10;0.12;0.58;0.61;1"/></use>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="0s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.60;0.62;0.71;0.72;1"/>
+ <g><animateTransform attributeName="transform" type="translate" values="-9 0;7 0;-9 0" dur="0.9s" repeatCount="indefinite"/><use xlink:href="#magnifier" x="-6" y="-9" width="16" height="16"/></g></g>
+ <use xlink:href="#stamp-ok" x="-24" y="-7" width="14" height="14" opacity="0"><animate attributeName="opacity" dur="12s" begin="0s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.72;0.74;0.82;0.86;1"/></use>
+ </g>
+ </g>
+ <!-- 2: Kubernetes on premises -> mcp://bigquery -->
+ <g opacity="0">
+ <animateMotion dur="12s" begin="2s" repeatCount="indefinite" calcMode="linear" keyPoints="0;0;1;1;1" keyTimes="0;0.10;0.60;0.82;1"><mpath xlink:href="#p2"/></animateMotion>
+ <animate attributeName="opacity" dur="12s" begin="2s" repeatCount="indefinite" values="0;1;1;1;0;0" keyTimes="0;0.02;0.80;0.82;0.86;1"/>
+ <g><animateTransform attributeName="transform" type="translate" values="0 0;0 -3;0 0" dur="0.8s" repeatCount="indefinite"/>
+ <use xlink:href="#parcel" x="-11" y="-8" width="22" height="17"/>
+ <g><animateTransform attributeName="transform" type="scale" dur="12s" begin="2s" repeatCount="indefinite" values="0;0;1.3;1;1;0;0" keyTimes="0;0.10;0.115;0.13;0.82;0.86;1"/><use xlink:href="#passport" x="4" y="-27" width="14" height="16"/><use xlink:href="#mandate" x="19" y="-25" width="13" height="14"/></g>
+ <use xlink:href="#lock" x="8" y="2" width="10" height="12" opacity="0"><animate attributeName="opacity" dur="12s" begin="2s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.10;0.12;0.58;0.61;1"/></use>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="2s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.60;0.62;0.71;0.72;1"/>
+ <g><animateTransform attributeName="transform" type="translate" values="-9 0;7 0;-9 0" dur="0.9s" repeatCount="indefinite"/><use xlink:href="#magnifier" x="-6" y="-9" width="16" height="16"/></g></g>
+ <use xlink:href="#stamp-ok" x="-24" y="-7" width="14" height="14" opacity="0"><animate attributeName="opacity" dur="12s" begin="2s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.72;0.74;0.82;0.86;1"/></use>
+ </g>
+ </g>
+ <!-- 3: Sandbox -> mcp://github -->
+ <g opacity="0">
+ <animateMotion dur="12s" begin="4s" repeatCount="indefinite" calcMode="linear" keyPoints="0;0;1;1;1" keyTimes="0;0.10;0.60;0.82;1"><mpath xlink:href="#p3"/></animateMotion>
+ <animate attributeName="opacity" dur="12s" begin="4s" repeatCount="indefinite" values="0;1;1;1;0;0" keyTimes="0;0.02;0.80;0.82;0.86;1"/>
+ <g><animateTransform attributeName="transform" type="translate" values="0 0;0 -3;0 0" dur="0.65s" repeatCount="indefinite"/>
+ <use xlink:href="#parcel" x="-11" y="-8" width="22" height="17"/>
+ <g><animateTransform attributeName="transform" type="scale" dur="12s" begin="4s" repeatCount="indefinite" values="0;0;1.3;1;1;0;0" keyTimes="0;0.10;0.115;0.13;0.82;0.86;1"/><use xlink:href="#passport" x="4" y="-27" width="14" height="16"/><use xlink:href="#mandate" x="19" y="-25" width="13" height="14"/></g>
+ <use xlink:href="#lock" x="8" y="2" width="10" height="12" opacity="0"><animate attributeName="opacity" dur="12s" begin="4s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.10;0.12;0.58;0.61;1"/></use>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="4s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.60;0.62;0.71;0.72;1"/>
+ <g><animateTransform attributeName="transform" type="translate" values="-9 0;7 0;-9 0" dur="0.9s" repeatCount="indefinite"/><use xlink:href="#magnifier" x="-6" y="-9" width="16" height="16"/></g></g>
+ <use xlink:href="#stamp-ok" x="-24" y="-7" width="14" height="14" opacity="0"><animate attributeName="opacity" dur="12s" begin="4s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.72;0.74;0.82;0.86;1"/></use>
+ </g>
+ </g>
+ <!-- 4: SaaS -> egress://generativelanguage.googleapis.com -->
+ <g opacity="0">
+ <animateMotion dur="12s" begin="6s" repeatCount="indefinite" calcMode="linear" keyPoints="0;0;1;1;1" keyTimes="0;0.10;0.60;0.82;1"><mpath xlink:href="#p4"/></animateMotion>
+ <animate attributeName="opacity" dur="12s" begin="6s" repeatCount="indefinite" values="0;1;1;1;0;0" keyTimes="0;0.02;0.80;0.82;0.86;1"/>
+ <g><animateTransform attributeName="transform" type="translate" values="0 0;0 -3;0 0" dur="0.75s" repeatCount="indefinite"/>
+ <use xlink:href="#parcel" x="-11" y="-8" width="22" height="17"/>
+ <g><animateTransform attributeName="transform" type="scale" dur="12s" begin="6s" repeatCount="indefinite" values="0;0;1.3;1;1;0;0" keyTimes="0;0.10;0.115;0.13;0.82;0.86;1"/><use xlink:href="#passport" x="4" y="-27" width="14" height="16"/><use xlink:href="#mandate" x="19" y="-25" width="13" height="14"/></g>
+ <use xlink:href="#lock" x="8" y="2" width="10" height="12" opacity="0"><animate attributeName="opacity" dur="12s" begin="6s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.10;0.12;0.58;0.61;1"/></use>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="6s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.60;0.62;0.71;0.72;1"/>
+ <g><animateTransform attributeName="transform" type="translate" values="-9 0;7 0;-9 0" dur="0.9s" repeatCount="indefinite"/><use xlink:href="#magnifier" x="-6" y="-9" width="16" height="16"/></g></g>
+ <use xlink:href="#stamp-ok" x="-24" y="-7" width="14" height="14" opacity="0"><animate attributeName="opacity" dur="12s" begin="6s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.72;0.74;0.82;0.86;1"/></use>
+ </g>
+ </g>
+ <!-- 5: Kubernetes in a cloud -> a2a://partner-agent -->
+ <g opacity="0">
+ <animateMotion dur="12s" begin="8s" repeatCount="indefinite" calcMode="linear" keyPoints="0;0;1;1;1" keyTimes="0;0.10;0.60;0.82;1"><mpath xlink:href="#p5"/></animateMotion>
+ <animate attributeName="opacity" dur="12s" begin="8s" repeatCount="indefinite" values="0;1;1;1;0;0" keyTimes="0;0.02;0.80;0.82;0.86;1"/>
+ <g><animateTransform attributeName="transform" type="translate" values="0 0;0 -3;0 0" dur="0.7s" repeatCount="indefinite"/>
+ <use xlink:href="#parcel" x="-11" y="-8" width="22" height="17"/>
+ <g><animateTransform attributeName="transform" type="scale" dur="12s" begin="8s" repeatCount="indefinite" values="0;0;1.3;1;1;0;0" keyTimes="0;0.10;0.115;0.13;0.82;0.86;1"/><use xlink:href="#passport" x="4" y="-27" width="14" height="16"/><use xlink:href="#mandate" x="19" y="-25" width="13" height="14"/></g>
+ <use xlink:href="#lock" x="8" y="2" width="10" height="12" opacity="0"><animate attributeName="opacity" dur="12s" begin="8s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.10;0.12;0.58;0.61;1"/></use>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="8s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.60;0.62;0.71;0.72;1"/>
+ <g><animateTransform attributeName="transform" type="translate" values="-9 0;7 0;-9 0" dur="0.9s" repeatCount="indefinite"/><use xlink:href="#magnifier" x="-6" y="-9" width="16" height="16"/></g></g>
+ <use xlink:href="#stamp-ok" x="-24" y="-7" width="14" height="14" opacity="0"><animate attributeName="opacity" dur="12s" begin="8s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.72;0.74;0.82;0.86;1"/></use>
+ </g>
+ </g>
+ <!-- 6: Developer -> inference://gemini -->
+ <g opacity="0">
+ <animateMotion dur="12s" begin="10s" repeatCount="indefinite" calcMode="linear" keyPoints="0;0;1;1;1" keyTimes="0;0.10;0.60;0.82;1"><mpath xlink:href="#p6"/></animateMotion>
+ <animate attributeName="opacity" dur="12s" begin="10s" repeatCount="indefinite" values="0;1;1;1;0;0" keyTimes="0;0.02;0.80;0.82;0.86;1"/>
+ <g><animateTransform attributeName="transform" type="translate" values="0 0;0 -3;0 0" dur="0.85s" repeatCount="indefinite"/>
+ <use xlink:href="#parcel" x="-11" y="-8" width="22" height="17"/>
+ <g><animateTransform attributeName="transform" type="scale" dur="12s" begin="10s" repeatCount="indefinite" values="0;0;1.3;1;1;0;0" keyTimes="0;0.10;0.115;0.13;0.82;0.86;1"/><use xlink:href="#passport" x="4" y="-27" width="14" height="16"/><use xlink:href="#mandate" x="19" y="-25" width="13" height="14"/></g>
+ <use xlink:href="#lock" x="8" y="2" width="10" height="12" opacity="0"><animate attributeName="opacity" dur="12s" begin="10s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.10;0.12;0.58;0.61;1"/></use>
+ <g opacity="0"><animate attributeName="opacity" dur="12s" begin="10s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.60;0.62;0.71;0.72;1"/>
+ <g><animateTransform attributeName="transform" type="translate" values="-9 0;7 0;-9 0" dur="0.9s" repeatCount="indefinite"/><use xlink:href="#magnifier" x="-6" y="-9" width="16" height="16"/></g></g>
+ <use xlink:href="#stamp-ok" x="-24" y="-7" width="14" height="14" opacity="0"><animate attributeName="opacity" dur="12s" begin="10s" repeatCount="indefinite" values="0;0;1;1;0;0" keyTimes="0;0.72;0.74;0.82;0.86;1"/></use>
+ </g>
+ </g>
+ </g>
+
+ <!-- Confetti at each delivery -->
+ <g>
+ <g transform="translate(960,410)">
+ <circle r="2.2" fill="#f6c344" opacity="0"><animate attributeName="opacity" dur="12s" begin="0s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="0s" repeatCount="indefinite" values="0 0;0 0;-16 -18;-16 -18" keyTimes="0;0.82;0.90;1"/></circle>
+ <circle r="2.2" fill="#00f0ff" opacity="0"><animate attributeName="opacity" dur="12s" begin="0s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="0s" repeatCount="indefinite" values="0 0;0 0;-20 6;-20 6" keyTimes="0;0.82;0.90;1"/></circle>
+ <circle r="2.2" fill="#f8fafc" opacity="0"><animate attributeName="opacity" dur="12s" begin="0s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="0s" repeatCount="indefinite" values="0 0;0 0;-8 -24;-8 -24" keyTimes="0;0.82;0.90;1"/></circle>
+ <circle r="2.2" fill="#f6c344" opacity="0"><animate attributeName="opacity" dur="12s" begin="0s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="0s" repeatCount="indefinite" values="0 0;0 0;-10 20;-10 20" keyTimes="0;0.82;0.90;1"/></circle>
+ </g>
+ <g transform="translate(960,250)">
+ <circle r="2.2" fill="#f6c344" opacity="0"><animate attributeName="opacity" dur="12s" begin="2s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="2s" repeatCount="indefinite" values="0 0;0 0;-16 -18;-16 -18" keyTimes="0;0.82;0.90;1"/></circle>
+ <circle r="2.2" fill="#00f0ff" opacity="0"><animate attributeName="opacity" dur="12s" begin="2s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="2s" repeatCount="indefinite" values="0 0;0 0;-20 6;-20 6" keyTimes="0;0.82;0.90;1"/></circle>
+ <circle r="2.2" fill="#f8fafc" opacity="0"><animate attributeName="opacity" dur="12s" begin="2s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="2s" repeatCount="indefinite" values="0 0;0 0;-8 -24;-8 -24" keyTimes="0;0.82;0.90;1"/></circle>
+ <circle r="2.2" fill="#f6c344" opacity="0"><animate attributeName="opacity" dur="12s" begin="2s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="2s" repeatCount="indefinite" values="0 0;0 0;-10 20;-10 20" keyTimes="0;0.82;0.90;1"/></circle>
+ </g>
+ <g transform="translate(960,170)">
+ <circle r="2.2" fill="#f6c344" opacity="0"><animate attributeName="opacity" dur="12s" begin="4s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="4s" repeatCount="indefinite" values="0 0;0 0;-16 -18;-16 -18" keyTimes="0;0.82;0.90;1"/></circle>
+ <circle r="2.2" fill="#00f0ff" opacity="0"><animate attributeName="opacity" dur="12s" begin="4s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="4s" repeatCount="indefinite" values="0 0;0 0;-20 6;-20 6" keyTimes="0;0.82;0.90;1"/></circle>
+ <circle r="2.2" fill="#f8fafc" opacity="0"><animate attributeName="opacity" dur="12s" begin="4s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="4s" repeatCount="indefinite" values="0 0;0 0;-8 -24;-8 -24" keyTimes="0;0.82;0.90;1"/></circle>
+ <circle r="2.2" fill="#f6c344" opacity="0"><animate attributeName="opacity" dur="12s" begin="4s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="4s" repeatCount="indefinite" values="0 0;0 0;-10 20;-10 20" keyTimes="0;0.82;0.90;1"/></circle>
+ </g>
+ <g transform="translate(960,490)">
+ <circle r="2.2" fill="#f6c344" opacity="0"><animate attributeName="opacity" dur="12s" begin="6s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="6s" repeatCount="indefinite" values="0 0;0 0;-16 -18;-16 -18" keyTimes="0;0.82;0.90;1"/></circle>
+ <circle r="2.2" fill="#00f0ff" opacity="0"><animate attributeName="opacity" dur="12s" begin="6s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="6s" repeatCount="indefinite" values="0 0;0 0;-20 6;-20 6" keyTimes="0;0.82;0.90;1"/></circle>
+ <circle r="2.2" fill="#f8fafc" opacity="0"><animate attributeName="opacity" dur="12s" begin="6s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="6s" repeatCount="indefinite" values="0 0;0 0;-8 -24;-8 -24" keyTimes="0;0.82;0.90;1"/></circle>
+ <circle r="2.2" fill="#f6c344" opacity="0"><animate attributeName="opacity" dur="12s" begin="6s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="6s" repeatCount="indefinite" values="0 0;0 0;-10 20;-10 20" keyTimes="0;0.82;0.90;1"/></circle>
+ </g>
+ <g transform="translate(960,570)">
+ <circle r="2.2" fill="#f6c344" opacity="0"><animate attributeName="opacity" dur="12s" begin="8s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="8s" repeatCount="indefinite" values="0 0;0 0;-16 -18;-16 -18" keyTimes="0;0.82;0.90;1"/></circle>
+ <circle r="2.2" fill="#00f0ff" opacity="0"><animate attributeName="opacity" dur="12s" begin="8s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="8s" repeatCount="indefinite" values="0 0;0 0;-20 6;-20 6" keyTimes="0;0.82;0.90;1"/></circle>
+ <circle r="2.2" fill="#f8fafc" opacity="0"><animate attributeName="opacity" dur="12s" begin="8s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="8s" repeatCount="indefinite" values="0 0;0 0;-8 -24;-8 -24" keyTimes="0;0.82;0.90;1"/></circle>
+ <circle r="2.2" fill="#f6c344" opacity="0"><animate attributeName="opacity" dur="12s" begin="8s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="8s" repeatCount="indefinite" values="0 0;0 0;-10 20;-10 20" keyTimes="0;0.82;0.90;1"/></circle>
+ </g>
+ <g transform="translate(960,330)">
+ <circle r="2.2" fill="#f6c344" opacity="0"><animate attributeName="opacity" dur="12s" begin="10s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="10s" repeatCount="indefinite" values="0 0;0 0;-16 -18;-16 -18" keyTimes="0;0.82;0.90;1"/></circle>
+ <circle r="2.2" fill="#00f0ff" opacity="0"><animate attributeName="opacity" dur="12s" begin="10s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="10s" repeatCount="indefinite" values="0 0;0 0;-20 6;-20 6" keyTimes="0;0.82;0.90;1"/></circle>
+ <circle r="2.2" fill="#f8fafc" opacity="0"><animate attributeName="opacity" dur="12s" begin="10s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="10s" repeatCount="indefinite" values="0 0;0 0;-8 -24;-8 -24" keyTimes="0;0.82;0.90;1"/></circle>
+ <circle r="2.2" fill="#f6c344" opacity="0"><animate attributeName="opacity" dur="12s" begin="10s" repeatCount="indefinite" values="0;0;1;0;0" keyTimes="0;0.82;0.83;0.90;1"/><animateTransform attributeName="transform" type="translate" dur="12s" begin="10s" repeatCount="indefinite" values="0 0;0 0;-10 20;-10 20" keyTimes="0;0.82;0.90;1"/></circle>
+ </g>
+ </g>
+
+ <!-- Legend -->
+ <g transform="translate(28,612)">
+ <use xlink:href="#parcel" x="0" y="-12" width="18" height="14"/><text x="24" y="0" class="legend">a request</text>
+ <use xlink:href="#passport" x="96" y="-13" width="12" height="14"/><text x="114" y="0" class="legend">passport: who sends and their memberships, issued once by the Registry</text>
+ <use xlink:href="#mandate" x="520" y="-12" width="11" height="12"/><text x="538" y="0" class="legend">mandate: written by the holder for this errand, narrower and shorter, never wider</text>
+ <use xlink:href="#lock" x="1006" y="-13" width="9" height="11"/><text x="1022" y="0" class="legend">sealed between offices</text>
+ <use xlink:href="#office" x="0" y="8" width="27" height="17"/><text x="34" y="19" class="legend">sam-node, at the edge: reads passport, law and mandates offline, runs customs, gets a border pass at a cloud border</text>
+ <use xlink:href="#relay" x="684" y="6" width="20" height="20"/><text x="710" y="19" class="legend">sam-router, at the core: admits passport holders, relays sealed bags, opens none</text>
+ <text x="0" y="37" class="legend">Registry = sam-control-plane: issues passports, writes the law and the watchlist. Asked once per sender and once per task at a cloud border, never per request.</text>
+ <text x="0" y="55" class="legend">✓ is the office's decision; nothing is written on the passport. Bring your own gateway (Istio, agentgateway, kgateway over ext_proc) and your own customs (any ext_proc processor).</text>
+ </g>
+</svg>
diff --git a/site/static/install.sh b/site/static/install.sh
index 1ac57b1d..1ab99c30 100755
--- a/site/static/install.sh
+++ b/site/static/install.sh
@@ -56,7 +56,7 @@ tar -xzf "${TAR_NAME}"
echo "Installing to ${INSTALL_DIR} (may require sudo)..."
INSTALLED_BINS=()
-for b in sam-one sam-node sam-control-plane sam-router mcp-client sam-box sam-console nano-init; do
+for b in sam-one sam-node sam-control-plane sam-router mcp-client sam-console; do
if [ -f "$b" ]; then
INSTALLED_BINS+=("$b")
fi