@synapsor/runner 1.5.3 → 1.5.4

package/docs/mcp-clients.md

@@ -115,19 +115,25 @@ metadata preserves the canonical dotted Synapsor capability name.
 ## Streamable HTTP
 
 ```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
+
 synapsor-runner mcp serve \
   --transport streamable-http \
   --alias-mode openai \
   --host 127.0.0.1 \
   --port 8766 \
   --config ./synapsor.runner.json \
-  --store ./.synapsor/local.db
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
 ```
 
 Connect a standard Streamable HTTP MCP client to
-`http://127.0.0.1:8766/mcp`. Keep it on loopback for local development. For a
-network deployment, terminate TLS, require authentication, restrict network
-access, and follow the [production guide](production.md).
+`http://127.0.0.1:8766/mcp` with `Authorization: Bearer` loaded from the same
+protected environment value. Keep it on loopback for local development. A
+non-loopback listener refuses to bind without direct TLS, an explicitly trusted
+TLS proxy, or authenticated emergency break glass. Shared deployments require
+identity-provider-issued signed claims. Follow [HTTP MCP](http-mcp.md) and the
+[production guide](production.md).
 
 Use `--alias-mode openai` for the OpenAI Agents SDK. Omit it for clients that
 accept canonical dotted names, or use `--alias-mode both` only during a planned

package/docs/openai-agents-sdk.md

@@ -8,7 +8,7 @@ surface.
 ## Start Runner
 
 ```bash
-export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+export SYNAPSOR_RUNNER_HTTP_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
 
 npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
   --config ./synapsor.runner.json \
@@ -17,6 +17,11 @@ npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
   --alias-mode openai
 ```
 
+For this loopback/single-service example, the operator provisions that same
+opaque value to the Runner process and the Python client through protected
+environment injection. HTTP `Bearer` describes how the credential is sent; it
+does not make the opaque value a JWT, and Runner does not issue it.
+
 `--alias-mode openai` is important because OpenAI function/tool names cannot
 contain dots. Runner exposes names such as `billing__inspect_invoice` to the
 model and maps calls back to canonical Synapsor capability names such as
@@ -28,7 +33,8 @@ model and maps calls back to canonical Synapsor capability names such as
 npx -y -p @synapsor/runner synapsor-runner mcp client-config \
   --client openai-agents \
   --config ./synapsor.runner.json \
-  --store ./.synapsor/local.db
+  --store ./.synapsor/local.db \
+  --client-access-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
 ```
 
 The generated output includes:
@@ -41,6 +47,14 @@ The generated output includes:
 It does not include database URLs, passwords, write credentials, API keys, or
 bearer token values.
 
+For a shared deployment, configure `http_claims`, asymmetric `session_auth`, and
+`http_security.oauth_resource`, then use a separate env name such as
+`SYNAPSOR_MCP_ACCESS_TOKEN`. Your configured identity provider issues that
+short-lived token for the protected-resource audience; Runner validates it on
+every request but never stores end-user passwords or issues/refreshes tokens.
+The generated client URL is the configured HTTPS protected resource. See
+[HTTP MCP](http-mcp.md) for the complete profile and TLS/proxy requirements.
+
 ## Sanity Check
 
 Before giving the agent a real task, ask it to inspect one known object and

package/docs/production.md

@@ -421,6 +421,36 @@ synapsor-runner activity search --proposal wrp_... --store ./.synapsor/local.db
 
 ## Deployment Recipes
 
+### Networked MCP boundary
+
+Prefer stdio when one local client can launch Runner. For Streamable HTTP,
+choose the deployment profile before binding:
+
+- loopback: authenticated opaque endpoint token by default;
+- remote single-tenant: direct TLS or an explicitly trusted TLS proxy, plus one
+  high-entropy rotated service token;
+- shared multi-user/tenant: direct TLS or trusted proxy, asymmetric signed JWT
+  sessions, exact issuer/audience/resource, verified tenant/principal claims,
+  and RFC 9728 protected-resource metadata.
+
+An opaque token is generated by the operator and provisioned to server and
+authorized client through environment/secret-manager injection. Runner does not
+issue it. In a shared deployment, the configured external identity provider
+issues short-lived access tokens; Runner verifies them but does not store user
+passwords or issue refresh tokens. See [HTTP MCP](http-mcp.md) before exposing a
+listener outside loopback.
+
+Run the transport-specific doctor check before serving:
+
+```bash
+synapsor-runner doctor \
+  --config ./synapsor.runner.json \
+  --transport streamable-http \
+  --host 0.0.0.0 \
+  --trusted-tls-proxy \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+```
+
 ### Docker Compose Shape
 
 Use Compose to run the MCP server next to your app and database network. Keep
@@ -436,14 +466,20 @@ export SYNAPSOR_SECRET_MAP='{
 }'
 
 synapsor-runner mcp serve-streamable-http \
+  --host 0.0.0.0 \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
+  --trusted-tls-proxy \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
   --secrets-provider aws-secretsmanager-cli \
   --secret-map-env SYNAPSOR_SECRET_MAP
 ```
 
 The AWS provider shells out to `aws secretsmanager get-secret-value`; the runner
-logs only how many target env vars were loaded or skipped.
+logs only how many target env vars were loaded or skipped. This command assumes
+`http_security.deployment: single_tenant`, an exact `allowed_hosts` list, and a
+TLS proxy on a private hop. Use asymmetric claim-bound identity instead for a
+shared user/tenant service.
 
 ```yaml
 services:
@@ -453,22 +489,30 @@ services:
     command: >
       sh -lc "npm install -g @synapsor/runner &&
       synapsor-runner up --review --config /config/synapsor.runner.json
-      --store /data/local.db --host 0.0.0.0 --port 8766"
+      --store /data/local.db --host 0.0.0.0 --port 8766
+      --trusted-tls-proxy --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN"
     environment:
       SYNAPSOR_DATABASE_READ_URL: ${SYNAPSOR_DATABASE_READ_URL}
       SYNAPSOR_DATABASE_WRITE_URL: ${SYNAPSOR_DATABASE_WRITE_URL}
       SYNAPSOR_TENANT_ID: ${SYNAPSOR_TENANT_ID}
       SYNAPSOR_PRINCIPAL: ${SYNAPSOR_PRINCIPAL}
+      SYNAPSOR_RUNNER_HTTP_TOKEN: ${SYNAPSOR_RUNNER_HTTP_TOKEN}
     volumes:
       - ./synapsor.runner.json:/config/synapsor.runner.json:ro
       - synapsor-runner-data:/data
-    ports:
-      - "8766:8766"
+    expose:
+      - "8766"
 
 volumes:
   synapsor-runner-data:
 ```
 
+This shape deliberately does not publish the Runner port to the host. Put a
+TLS-terminating proxy on the same private container network, publish only that
+proxy, preserve the reviewed external Host, and prevent direct client access to
+Runner. If Runner itself owns TLS, replace `--trusted-tls-proxy` with protected
+`--tls-cert-env`/`--tls-key-env` PEM references.
+
 ### systemd Shape
 
 ```ini
@@ -491,10 +535,20 @@ PrivateTmp=true
 WantedBy=multi-user.target
 ```
 
-Put database credentials in `/etc/synapsor-runner.env` or your system secret
-manager, not in `synapsor.runner.json`.
+Put database credentials and the random loopback endpoint token in
+`/etc/synapsor-runner.env` or your system secret manager, not in
+`synapsor.runner.json`. The systemd command binds loopback, so a local trusted
+proxy may connect to it without exposing cleartext Bearer traffic on the
+network.
 
-## TLS And SSL
+## TLS, mTLS, And Database SSL
+
+For MCP HTTP, Runner-owned TLS reads certificate/key PEM only from named
+environment variables. Optional mTLS verifies client certificates against an
+explicit CA and supplements Bearer authentication; it does not replace
+per-session tenant/principal identity in a shared service. A trusted proxy must
+be protected from direct bypass and must not inject forwarded tenant/principal
+headers as authority.
 
 For staging or production-like databases:
 
@@ -507,6 +561,17 @@ For staging or production-like databases:
 For disposable local Docker fixtures, `sslmode=disable` is acceptable when the
 database is bound to loopback and contains only test data.
 
+Rotate credentials independently:
+
+- opaque endpoint token: active plus at most one previous env during rollout;
+- HS256 session key: active plus one previous key, only for controlled use;
+- asymmetric JWT key: publish a new `kid`, honor bounded JWKS cache/cooldown,
+  then retire the old public key after clients rotate;
+- TLS certificate and mTLS client CA: roll protected PEM material and restart
+  instances without changing tenant identity;
+- database and handler credentials: rotate their separate env/secret-manager
+  entries without reusing an MCP or Cloud credential.
+
 ## Health And Doctor
 
 Run these before exposing tools to an agent:

package/docs/release-notes.md

@@ -10,7 +10,48 @@ npx -y -p @synapsor/runner synapsor-runner demo --quick
 The OSS runner command is `synapsor-runner`. The `synapsor` command is reserved
 for the Synapsor Cloud CLI.
 
-## 1.5.3 (prepared, not published)
+## 1.5.4 (prepared, not published)
+
+### Networked MCP authentication hardening
+
+- Local stdio still opens no network listener and needs no HTTP credential.
+  Loopback HTTP remains authenticated by default with an operator-provisioned
+  opaque token.
+- Remote HTTP now refuses to bind over an undeclared cleartext channel. Operators
+  must use Runner-owned TLS, explicitly declare a trusted TLS proxy, or select an
+  authenticated and prominently diagnosed break-glass posture.
+- Opaque endpoint tokens are constrained to local or explicit single-tenant use.
+  Remote use requires adequate entropy; one active and one previous env-provided
+  value support bounded rotation without logging either value.
+- Shared deployments require signed per-session identity and `http_claims`
+  trusted context. Runner revalidates issuer, audience/resource, time, scope,
+  tenant, principal, signature, and algorithm on every request and rejects token
+  or identity swaps inside an MCP session.
+- RFC 9728 protected-resource metadata and Bearer challenges let compatible MCP
+  clients discover the configured external authorization server. Runner verifies
+  access tokens but does not implement user login or token issuance.
+- TLS/mTLS preflight, public-only bounded JWKS handling, exact Origin/Host checks,
+  request/session bounds, doctor diagnostics, client recipes, and fleet examples
+  now share one documented deployment ladder.
+- `lifecycle`, `lifecycle show`, and `lifecycle show latest` now inspect the
+  newest complete proposal lifecycle without an id. Filters and known
+  proposal/evidence/replay/job/intent/receipt/audit handles resolve a stable,
+  read-only `synapsor.lifecycle-view.v1` domain document across local SQLite
+  and shared PostgreSQL runtime stores.
+- DSL UPDATE authoring now requires an exact `CONFLICT GUARD <column>` instead
+  of silently choosing projection hashing. A reviewer-visible weak compatibility
+  clause remains only for ordinary single-row source-DB UPDATE and is rejected
+  for the stronger operation modes.
+- Runner rejects canonical `FROM SESSION` with
+  `SESSION_BINDING_UNSUPPORTED` rather than treating its key as a process
+  environment variable. Explicit ENVIRONMENT, verified HTTP_CLAIM, verified
+  CLOUD_SESSION, and STATIC_DEV behavior remains distinct.
+
+Prepared package versions: `@synapsor/runner@1.5.4` and
+`@synapsor/dsl@1.4.4`. `@synapsor/spec@1.4.2` and the Cloud CLI are
+unchanged. Nothing has been published by this repository change.
+
+## 1.5.3 (published 2026-07-21)
 
 ### Intent to Safe Action
 
@@ -37,8 +78,8 @@ for the Synapsor Cloud CLI.
 - The first two README screens, public website, article, discovery routes, and
   36-second evidence-backed demo now lead with the own-project Data PR path.
 
-Prepared package version: `@synapsor/runner@1.5.3`. Spec, DSL, and Cloud CLI
-packages are unchanged. Nothing has been published by this repository change.
+Published package version: `@synapsor/runner@1.5.3`. Spec, DSL, and Cloud CLI
+packages were unchanged.
 
 ## 1.5.2 (prepared, not published)
 

package/docs/runner-bundles.md

@@ -67,8 +67,13 @@ npx -y -p @synapsor/runner synapsor-runner cloud sync latest \
 
 For the OpenAI Agents SDK, use the included TypeScript examples. Their stdio
 command enables `--alias-mode openai`; the Streamable HTTP example includes the
-matching server command. Claude, Cursor, and generic templates use canonical
-dotted capability names.
+matching server command and reads its Bearer credential from
+`SYNAPSOR_RUNNER_HTTP_TOKEN`. The generic HTTP template uses the same environment
+reference. Neither file embeds a credential value. An operator generates and
+provisions the opaque token to the Runner process and authorized client; use a
+signed identity-provider token instead for shared multi-user deployments. See
+[HTTP MCP](http-mcp.md). Claude, Cursor, and generic stdio templates use
+canonical dotted capability names and need no HTTP credential.
 
 Approval and writeback remain outside the model-facing MCP tool surface. Use
 `proposals`, `apply`, `receipts`, and `replay` from a trusted operator shell.

package/docs/runner-config-reference.md

@@ -36,6 +36,7 @@ Unknown keys fail when `strict` is true (the default).
 | `approvals` | No | Local approval overrides. |
 | `operator_identity` | No | Verified operator identity and apply-role wiring for approve/reject/apply. |
 | `session_auth` | HTTP claims | HS256 development or asymmetric RS256/ES256 session-token verification. |
+| `http_security` | Networked HTTP | Deployment profile, protected channel, endpoint-token env names, OAuth protected-resource metadata, exact Origin/Host policy, and request/session bounds. |
 | `rate_limits` | No | Operational fixed-window limits; fleet-wide only with shared `runtime_store`. |
 | `metrics` | No | Separately authorized scrapeable HTTP metrics. Disabled by default. |
 | `graduated_trust` | No | Off-by-default, operator-only policy recommendation criteria and kill switch. |
@@ -212,8 +213,16 @@ Providers are `environment`, `static_dev`, `http_claims`, and `cloud_session`.
 Capabilities may reference a context by name. The model never receives tenant
 or principal as an overridable argument.
 
-For multi-tenant Streamable HTTP services, use `http_claims` plus signed
-session auth:
+The language-neutral canonical contract can preserve a `session` binding for
+implementations such as C++/Cloud that own a typed session boundary. Runner has
+no generic web-session provider and rejects it with
+`SESSION_BINDING_UNSUPPORTED`; it never treats the key as an environment
+variable. Use `environment` for local stdio, verified `http_claims` for shared
+Streamable HTTP, or verified `cloud_session` for Cloud embedding.
+
+For controlled loopback development, `http_claims` can use an HS256 session
+token. Runner holds the symmetric signing/verification secret in this mode, so
+it is not the recommended shared production profile:
 
 ```json
 {
@@ -229,7 +238,7 @@ session auth:
     "secret_env": "SYNAPSOR_SESSION_JWT_SECRET",
     "previous_secret_env": "SYNAPSOR_PREVIOUS_SESSION_JWT_SECRET",
     "issuer": "https://identity.example",
-    "audience": "synapsor-runner"
+    "audience": "https://runner.example/mcp"
   }
 }
 ```
@@ -239,16 +248,24 @@ the active secret first, then the previous secret. Existing MCP sessions remain
 bound to the exact token fingerprint, so clients cannot swap tenant/principal
 identity inside an initialized session.
 
-For networked deployments prefer asymmetric public-key verification:
+For a shared networked deployment, use asymmetric public-key verification and
+declare the protected resource and channel explicitly:
 
 ```json
 {
+  "trusted_context": {
+    "provider": "http_claims",
+    "values": {
+      "tenant_id_key": "tenant_id",
+      "principal_key": "sub"
+    }
+  },
   "session_auth": {
     "provider": "jwt_asymmetric",
-    "algorithms": ["RS256"],
+    "algorithms": ["RS256", "ES256"],
     "jwks_url_env": "SYNAPSOR_SESSION_JWKS_URL",
     "issuer": "https://identity.example",
-    "audience": "synapsor-runner",
+    "audience": "https://runner.example/mcp",
     "tenant_claim": "tenant_id",
     "principal_claim": "sub",
     "clock_skew_seconds": 30,
@@ -256,6 +273,19 @@ For networked deployments prefer asymmetric public-key verification:
     "jwks_cooldown_seconds": 30,
     "fetch_timeout_ms": 3000,
     "max_response_bytes": 1048576
+  },
+  "http_security": {
+    "deployment": "shared",
+    "channel": "trusted_tls_proxy",
+    "oauth_resource": {
+      "resource": "https://runner.example/mcp",
+      "authorization_servers": ["https://identity.example"],
+      "scopes_supported": ["synapsor:mcp"],
+      "required_scopes": ["synapsor:mcp"],
+      "resource_name": "Synapsor Runner"
+    },
+    "allowed_origins": ["https://agent-console.example"],
+    "allowed_hosts": ["runner.example"]
   }
 }
 ```
@@ -268,6 +298,66 @@ rejected. Every effective named context in an `http_claims` server must bind
 tenant and principal from claims; environment/static contradictions fail with
 `TRUSTED_CONTEXT_PROVIDER_CONFLICT` before serving.
 
+`session_auth` verifies identity; it does not issue access tokens. The external
+identity provider identified by `issuer` issues a short-lived token whose
+audience is the exact protected-resource URL. Runner fetches only public JWKS
+material and validates the configured claims on every request. Required OAuth
+scopes are declared under `http_security.oauth_resource`.
+
+## HTTP security
+
+`http_security` is Runner deployment wiring, not part of a portable contract:
+
+```json
+{
+  "http_security": {
+    "deployment": "single_tenant",
+    "channel": "trusted_tls_proxy",
+    "static_token": {
+      "active_env": "SYNAPSOR_RUNNER_HTTP_TOKEN",
+      "previous_env": "SYNAPSOR_RUNNER_HTTP_TOKEN_PREVIOUS"
+    },
+    "allowed_origins": ["https://agent-console.example"],
+    "allowed_hosts": ["runner.internal.example"],
+    "limits": {
+      "max_request_bytes": 65536,
+      "max_header_bytes": 8192,
+      "max_sessions": 500,
+      "session_idle_timeout_seconds": 300,
+      "request_timeout_ms": 15000,
+      "headers_timeout_ms": 5000,
+      "keep_alive_timeout_ms": 5000,
+      "max_connections": 1000
+    }
+  }
+}
+```
+
+- `deployment` is `loopback`, `single_tenant`, or `shared`. Shared requires
+  verified signed `http_claims`, exact issuer/audience, and RFC 9728
+  `oauth_resource` metadata.
+- `channel` is `direct_tls`, `trusted_tls_proxy`, or the explicitly unsafe
+  `insecure_http_break_glass`. A non-loopback listener without one refuses to
+  bind. Break glass remains authenticated.
+- `static_token` names one active and optionally one previous environment
+  variable. It is opaque service access for loopback/single-tenant use, not
+  tenant identity. Values never belong in config.
+- `oauth_resource.resource` is the exact HTTPS MCP endpoint and must equal
+  `session_auth.audience`. `authorization_servers` names external issuers;
+  Runner does not implement login or token refresh.
+- `allowed_origins` contains exact browser origins; an omitted browser Origin
+  remains valid for native clients. Wildcards are forbidden.
+- `allowed_hosts` contains exact direct/public Host authorities. Forwarded Host
+  and forwarded identity headers are not trusted automatically.
+- `limits` bounds bodies, headers, concurrent sessions/connections, idle
+  sessions, and HTTP timing. Defaults are documented in [HTTP MCP](http-mcp.md).
+
+Runner-owned TLS certificate, key, and optional client-CA PEM values are passed
+by environment references on the serve command (`--tls-cert-env`,
+`--tls-key-env`, `--tls-ca-env`, `--require-client-cert`). Private TLS material
+does not go in this JSON file. A trusted-proxy channel assumes firewall/private
+network controls prevent clients from bypassing that proxy.
+
 ## Contracts and embedded capabilities
 
 ```json

package/docs/running-a-runner-fleet.md

@@ -1,6 +1,6 @@
 # Running A Small Runner Fleet
 
-Synapsor Runner 1.1 supports a bounded small-fleet deployment. It does not
+Synapsor Runner supports a bounded small-fleet deployment. It does not
 turn the OSS package into Synapsor Cloud and it does not promise an unbounded,
 multi-region, or SLA-backed control plane.
 
@@ -32,7 +32,7 @@ model-facing approval/apply tools as blockers. Audit is a static review, not a
 security proof; follow it with `tools preview`, `doctor`, and the live fleet
 verification.
 
-## What 1.1 Guarantees
+## What The Bounded Fleet Guarantees
 
 With `storage.shared_postgres.mode = "runtime_store"`:
 
@@ -116,7 +116,7 @@ Use asymmetric verification for a networked fleet:
     "algorithms": ["RS256"],
     "jwks_url_env": "SYNAPSOR_SESSION_JWKS_URL",
     "issuer": "https://identity.example",
-    "audience": "synapsor-runner",
+    "audience": "https://runner.example/mcp",
     "tenant_claim": "tenant_id",
     "principal_claim": "sub",
     "clock_skew_seconds": 30,
@@ -124,10 +124,28 @@ Use asymmetric verification for a networked fleet:
     "jwks_cooldown_seconds": 30,
     "fetch_timeout_ms": 3000,
     "max_response_bytes": 1048576
+  },
+  "http_security": {
+    "deployment": "shared",
+    "channel": "trusted_tls_proxy",
+    "oauth_resource": {
+      "resource": "https://runner.example/mcp",
+      "authorization_servers": ["https://identity.example"],
+      "scopes_supported": ["synapsor:mcp"],
+      "required_scopes": ["synapsor:mcp"]
+    },
+    "allowed_hosts": ["runner.example"],
+    "allowed_origins": ["https://agent-console.example"]
   }
 }
 ```
 
+The external identity provider issues the short-lived client JWT for resource
+`https://runner.example/mcp`; Runner only verifies it. The load balancer must
+terminate TLS and prevent direct access to the private Runner listeners. If
+Runner owns TLS instead, use protected certificate/key env references and set
+`channel` to `direct_tls`.
+
 Every served capability context must bind tenant and principal from
 `HTTP_CLAIM`. Runner rejects an environment-bound contract mixed into this
 server with `TRUSTED_CONTEXT_PROVIDER_CONFLICT` before tools are served.
@@ -147,6 +165,12 @@ material. Unknown `kid` triggers at most one controlled refresh. For offline
 deployments, configure one public PEM through `public_key_env` or
 `public_key_path`; never place a private key in Runner config.
 
+Runner publishes RFC 9728 protected-resource metadata at the path derived from
+the public resource and returns scope-aware Bearer challenges. The identity
+provider, not Runner, owns user login, client registration, token issuance, and
+refresh. An MCP session ID is only protocol state; every request is
+reauthenticated and remains pinned to the initialized credential identity.
+
 ## Ledger And Source Pools
 
 ```json
@@ -329,12 +353,13 @@ configured handler timeout. A hard kill is recoverable through leases and
 source-side idempotency receipts, but should remain an incident signal.
 
 Rotate JWKS keys by publishing the new `kid`, waiting at least the configured
-cache lifetime, switching issuers, then retiring the old key. Rotate metrics,
-handler, database, and ledger credentials independently through their named
-environment variables.
+cache lifetime while issuers sign with the new key, then retiring the old key.
+Do not casually change the issuer or protected-resource audience during a key
+rotation. Rotate TLS/mTLS, metrics, handler, database, and ledger credentials
+independently through their named environment variables.
 
-Only homogeneous Runner 1.1 instances are verified by `test:fleet`. Mixed
-1.0/1.1 operation is not claimed. For rolling upgrades:
+Only homogeneous Runner instances at the release under test are verified by
+`test:fleet`. Mixed-version operation is not claimed. For rolling upgrades:
 
 1. back up and verify the ledger;
 2. run schema/config validation with the target version;
@@ -351,8 +376,12 @@ roll back the full fleet. Never mix versions merely because both are `1.x`.
 
 ## TLS Boundary
 
-Terminate public TLS or mTLS at a trusted load balancer, or configure Runner's
-tested TLS/mTLS options directly. Keep Runner-to-database TLS verification on,
-use private networking where possible, restrict `/metrics`, and never forward
-untrusted identity headers as claims. The bearer JWT itself, not a proxy-added
-tenant header, is the session authority.
+Terminate public TLS or mTLS at a trusted load balancer and declare
+`channel: trusted_tls_proxy`, or configure Runner's tested TLS/mTLS options
+directly. A proxy declaration is a security assertion: firewall the private
+listener so clients cannot bypass the proxy, protect the private hop, and
+preserve an allowed Host. Keep Runner-to-database TLS verification on, use
+private networking where possible, and restrict `/metrics` separately. The
+verified Bearer JWT itself, not a proxy-added tenant/principal header, is the
+session authority. See [HTTP MCP](http-mcp.md) for channel flags, limits, and
+doctor checks.

package/docs/security-boundary.md

@@ -39,17 +39,52 @@ The model does not receive:
 - contract activation tools;
 - approval tools;
 - commit/writeback tools;
+- MCP endpoint tokens, JWTs, refresh tokens, client secrets, or TLS keys;
 - trusted tenant or principal authority as ordinary model arguments.
 
+## Network transport and identity
+
+Local stdio is the preferred one-client path. The MCP client launches Runner and
+communicates over the child process's standard input/output, so Runner opens no
+network listener and HTTP authentication does not apply.
+
+A listening HTTP endpoint has no inherent client identity. Runner therefore
+requires Bearer authentication by default. On loopback or an explicitly
+single-tenant service, Bearer may carry one high-entropy opaque endpoint token;
+that token only answers "may this service call the endpoint?" and is not a user
+or tenant identity. Shared services require signed per-session JWTs, preferably
+RS256/ES256 from an external identity provider, with exact issuer,
+audience/resource, time, scope, tenant, and principal validation on every
+request. An MCP session ID only routes protocol state and never authenticates a
+caller.
+
+Non-loopback HTTP refuses to bind unless Runner owns TLS, an explicitly trusted
+TLS proxy protects the public and private hops, or an authenticated emergency
+cleartext break-glass mode is selected. TLS protects the channel; mTLS also
+authenticates a workload certificate but does not replace per-user/tenant claims
+in a shared service. Exact Origin and Host policy, request/session limits, and
+credential-pinned MCP sessions narrow browser, DNS-rebinding, exhaustion, and
+session-swap attacks.
+
+These controls remain independent: transport authentication permits endpoint
+access; verified session claims provide tenant/principal context; the contract
+authorizes semantic capabilities; database roles/RLS constrain the connection;
+operator identity authorizes activation, approval, apply, reconcile, and
+revert. See [HTTP MCP](http-mcp.md).
+
 Reviewed aggregate tools expose one scalar only. Their function, column,
 tenant key, optional equality selection, and minimum-group threshold are fixed
 in the contract; the model receives no predicate arguments or member rows.
 Suppression reduces single-record inference but does not replace statistical
 privacy review. See [Bounded Aggregate Reads](aggregate-reads.md).
 
-Trusted context comes from local configuration, environment bindings, or Cloud
-session context in Cloud mode. Tenant, principal, and authorization scope must
-not be accepted from the model as authority.
+Trusted context comes from operator-controlled process bindings for local or
+explicitly single-tenant use, verified signed HTTP claims for a shared service,
+or verified Cloud session context in Cloud mode. Tenant, principal, and
+authorization scope must not be accepted from the model as authority.
+Canonical `SESSION` content is rejected by Runner with
+`SESSION_BINDING_UNSUPPORTED`; Runner never aliases it to environment values,
+arbitrary headers, MCP metadata, or model arguments.
 
 With a shared credential, these checks are application-level enforcement and
 depend on Runner's fixed predicate implementation. Optional PostgreSQL RLS mode