@synapsor/runner 1.5.3 → 1.5.4

package/docs/store-lifecycle.md

@@ -33,20 +33,108 @@ sqlite3 -readonly ./.synapsor/local.db '.tables'
 Do not mutate the database directly. Its internal tables may change between
 releases and are not a public storage API; use Runner commands for automation.
 
-## Inspect the ledger
+## Inspect one complete lifecycle
 
-| Question | Command |
+Start with no id:
+
+```bash
+synapsor-runner lifecycle --store ./.synapsor/local.db
+```
+
+`lifecycle`, `lifecycle show`, and `lifecycle show latest` are exact aliases.
+They choose the newest proposal deterministically by `created_at` descending,
+then proposal id as the tie-breaker. The default view answers:
+
+- what capability and business object the model requested;
+- which trusted tenant and principal scoped it;
+- approval state and progress;
+- whether a writeback job or intent exists;
+- the latest guarded outcome and whether the source changed;
+- replay and Cloud-link status; and
+- the next safe read-only or operator command.
+
+Use `--details` for one causal proposal-to-receipt/replay timeline, or `--json`
+for one stable `synapsor.lifecycle-view.v1` JSON document:
+
+```bash
+synapsor-runner lifecycle --details --store ./.synapsor/local.db
+synapsor-runner lifecycle --json --store ./.synapsor/local.db
+```
+
+The JSON is a domain view, not a dump of internal SQLite/PostgreSQL tables.
+Absent stages are represented explicitly as empty arrays or `null`; Runner
+does not fabricate a job, receipt, replay, or Cloud synchronization.
+
+### Browse and filter without copying ids
+
+```bash
+synapsor-runner lifecycle list --limit 20 --store ./.synapsor/local.db
+synapsor-runner lifecycle show --object invoice:INV-3001 --details --store ./.synapsor/local.db
+synapsor-runner lifecycle list --tenant acme --capability billing.propose_late_fee_waiver
+synapsor-runner lifecycle show --principal support-agent-17 --status applied
+```
+
+List/show support tenant, principal, capability, business object, status/state,
+and time-window filters. Filtered `show` selects the newest match and reports
+the total match count; use `lifecycle list` to browse all matches. List JSON
+uses `synapsor.lifecycle-list.v1`.
+
+### Start from any handle you already have
+
+```bash
+synapsor-runner lifecycle show wrp_... --details
+synapsor-runner lifecycle show ev_... --details
+synapsor-runner lifecycle show replay_... --details
+synapsor-runner lifecycle show wbj_... --details
+synapsor-runner lifecycle show wbi:wbj_... --details
+synapsor-runner lifecycle show receipt:42 --details
+synapsor-runner lifecycle show audit:17 --details
+```
+
+Runner resolves proposal, evidence, replay, writeback-job, writeback-intent,
+receipt, and query-audit handles to the owning proposal. Numeric receipt and
+query-audit ids require the `receipt:` or `audit:` namespace; a bare number is
+rejected rather than guessed.
+
+Lifecycle inspection is read-only. It does not contact the source database or
+Cloud, create a writeback job, acquire a worker lease, approve, apply, reconcile,
+retry, or synchronize anything. It applies the same tenant/principal visibility
+rules and secret/kept-out-field protections as the focused views.
+
+### Shared PostgreSQL runtime store
+
+For `storage.shared_postgres.mode = "runtime_store"`, pass the reviewed config:
+
+```bash
+synapsor-runner lifecycle --config ./synapsor.runner.json
+synapsor-runner lifecycle show --object invoice:INV-3001 --details \
+  --config ./synapsor.runner.json
+```
+
+Runner reuses the existing bounded read bridge to the authoritative shared
+ledger. It does not create or synchronize a persistent local mirror during
+inspection. Connection failures fail safely; the command never falls back to an
+unrelated local store.
+
+## Focused inspection commands
+
+The existing commands remain useful when you need one record type:
+
+| Question | Focused command |
 | --- | --- |
-| What did the model propose? | `synapsor-runner proposals show <proposal-id> --details` |
+| What did the model propose? | `synapsor-runner proposals show latest --details` |
 | What data supported it? | `synapsor-runner evidence list --proposal <proposal-id>` then `evidence show <evidence-id> --details` |
 | What query was run? | `synapsor-runner query-audit list --proposal <proposal-id>` |
-| Who approved or rejected it? | `synapsor-runner proposals show <proposal-id> --details` |
 | Did guarded writeback apply? | `synapsor-runner receipts list --proposal <proposal-id>` |
-| What happened end to end? | `synapsor-runner replay show --proposal <proposal-id> --details` |
+| What replay snapshot exists? | `synapsor-runner replay show latest --details` |
 | What happened to one object? | `synapsor-runner activity search --object invoice:INV-3001` |
 | What are the latest events? | `synapsor-runner events tail` |
 | How large is the store? | `synapsor-runner store stats --store ./.synapsor/local.db` |
 
+`proposals writeback-job` is intentionally absent from inspection examples:
+it materializes a job and is therefore an operator mutation, not a read-only
+view.
+
 ## Server leases
 
 MCP server modes write a small lease file next to the store:

package/examples/openai-agents-http/README.md

@@ -40,7 +40,7 @@ OpenAI Agents Streamable HTTP example smoke passed.
 export DATABASE_URL="<postgres-or-mysql-read-url>"
 export SYNAPSOR_TENANT_ID="acme"
 export SYNAPSOR_PRINCIPAL="openai_agent_demo"
-export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-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 \
@@ -49,6 +49,10 @@ npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
   --alias-mode openai
 ```
 
+The operator must provision that same opaque value to the authorized client.
+It is endpoint access for this loopback/single-service example, not user or
+tenant identity. Do not put it in source code or the client config.
+
 ## Terminal 2: Run The Agent
 
 ```bash
@@ -58,7 +62,7 @@ pip install -r requirements.txt
 
 export OPENAI_API_KEY="..."
 export SYNAPSOR_RUNNER_HTTP_URL="http://127.0.0.1:8766/mcp"
-export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-token"
+read -rsp "Provisioned Synapsor endpoint token: " SYNAPSOR_MCP_ACCESS_TOKEN; printf '\n'; export SYNAPSOR_MCP_ACCESS_TOKEN
 export SYNAPSOR_INVOICE_ID="INV-3001"
 
 python agent.py
@@ -74,5 +78,7 @@ Expected behavior:
 - no SQL/write/approval tool is exposed to the model;
 - evidence/query audit are saved in the local Runner store.
 
-For production-like deployment, keep HTTP MCP behind private networking/TLS,
-bearer auth, and rate limits. See [HTTP MCP](../../docs/http-mcp.md).
+For production-like deployment, non-loopback HTTP requires Runner TLS or an
+explicitly trusted TLS proxy. A shared user/tenant service uses a short-lived
+signed access token from an external identity provider rather than distributing
+one opaque token. See [HTTP MCP](../../docs/http-mcp.md).

package/examples/openai-agents-http/agent.py

@@ -13,14 +13,14 @@ except ImportError as exc:
 
 
 async def main() -> None:
-    required = ["OPENAI_API_KEY", "SYNAPSOR_RUNNER_HTTP_URL", "SYNAPSOR_RUNNER_HTTP_TOKEN"]
+    required = ["OPENAI_API_KEY", "SYNAPSOR_RUNNER_HTTP_URL", "SYNAPSOR_MCP_ACCESS_TOKEN"]
     missing = [name for name in required if not os.environ.get(name)]
     if missing:
         raise SystemExit(f"Missing required environment variables: {', '.join(missing)}")
 
     invoice_id = os.environ.get("SYNAPSOR_INVOICE_ID", "INV-3001")
     mcp_url = os.environ["SYNAPSOR_RUNNER_HTTP_URL"]
-    token = os.environ["SYNAPSOR_RUNNER_HTTP_TOKEN"]
+    token = os.environ["SYNAPSOR_MCP_ACCESS_TOKEN"]
 
     async with MCPServerStreamableHttp(
         params={

package/examples/runner-fleet/Dockerfile

@@ -1,11 +1,16 @@
 FROM node:22-bookworm-slim
 
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends openssl \
+  && rm -rf /var/lib/apt/lists/*
+
 RUN corepack enable && corepack prepare pnpm@10.14.0 --activate
 
 WORKDIR /app
 COPY . .
 RUN corepack pnpm install --frozen-lockfile \
-  && corepack pnpm build:runner-package
+  && corepack pnpm build:runner-package \
+  && chmod +x examples/runner-fleet/start-tls-runner.sh
 
-ENTRYPOINT ["node", "apps/runner/dist/cli.js"]
+ENTRYPOINT ["examples/runner-fleet/start-tls-runner.sh"]
 CMD ["mcp", "serve", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8766", "--config", "/config/synapsor.runner.json"]

package/examples/runner-fleet/README.md

@@ -2,8 +2,11 @@
 
 This synthetic fixture starts Postgres, MySQL, and two stateless Streamable
 HTTP Runner services. Both Runners share one bounded Postgres runtime ledger.
-The committed passwords and HS256 key are disposable local-demo values. Never
-reuse them outside this fixture.
+Each container generates a one-day self-signed certificate at startup so the
+non-loopback Runner listener exercises direct TLS rather than insecure HTTP.
+The committed database passwords and HS256 key are disposable local-demo
+values. Never reuse them outside this fixture; production should use a trusted
+certificate and asymmetric identity-provider tokens.
 
 From the repository root:
 
@@ -16,9 +19,9 @@ docker compose --profile fleet -f examples/runner-fleet/docker-compose.yml ps
 Check both instances:
 
 ```bash
-curl --fail http://127.0.0.1:8871/healthz
-curl --fail http://127.0.0.1:8871/readyz
-curl --fail http://127.0.0.1:8872/readyz
+curl --fail --insecure https://127.0.0.1:8871/healthz
+curl --fail --insecure https://127.0.0.1:8871/readyz
+curl --fail --insecure https://127.0.0.1:8872/readyz
 ```
 
 The MCP endpoint requires a claim-bearing development JWT. Generate one for
@@ -28,8 +31,9 @@ the fixture only:
 node examples/runner-fleet/mint-dev-token.mjs acme local-agent
 ```
 
-The production path should use `jwt_asymmetric` with an explicit RS256/ES256
-allowlist and a trusted JWKS URL or public PEM. See
+`--insecure` is acceptable only for this synthetic self-signed fixture. The
+production path should use a trusted TLS chain and `jwt_asymmetric` with an
+explicit RS256/ES256 allowlist plus a trusted JWKS URL or public PEM. See
 [Running A Runner Fleet](../../docs/running-a-runner-fleet.md).
 
 Run the stronger automated verification instead of treating a green Compose

package/examples/runner-fleet/docker-compose.yml

@@ -46,11 +46,11 @@ services:
       SYNAPSOR_SESSION_JWT_SECRET: synthetic-fleet-session-secret-change-before-use-0001
       SYNAPSOR_METRICS_TOKEN: synthetic-fleet-metrics-token-change-before-use
     ports:
-      - "8871:8766"
+      - "127.0.0.1:8871:8766"
     volumes:
       - ./synapsor.runner.json:/config/synapsor.runner.json:ro
     healthcheck:
-      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:8766/readyz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      test: ["CMD-SHELL", "NODE_TLS_REJECT_UNAUTHORIZED=0 node -e \"fetch('https://127.0.0.1:8766/readyz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\""]
       interval: 2s
       timeout: 5s
       retries: 30
@@ -66,11 +66,11 @@ services:
         condition: service_healthy
     environment: *runner_environment
     ports:
-      - "8872:8766"
+      - "127.0.0.1:8872:8766"
     volumes:
       - ./synapsor.runner.json:/config/synapsor.runner.json:ro
     healthcheck:
-      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:8766/readyz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      test: ["CMD-SHELL", "NODE_TLS_REJECT_UNAUTHORIZED=0 node -e \"fetch('https://127.0.0.1:8766/readyz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\""]
       interval: 2s
       timeout: 5s
       retries: 30

package/examples/runner-fleet/mint-dev-token.mjs

@@ -9,7 +9,7 @@ const payload = {
   sub: subject,
   tenant_id: tenant,
   iss: "https://fleet.example.invalid",
-  aud: "synapsor-runner-fleet",
+  aud: "https://runner-fleet.example.invalid/mcp",
   iat: now,
   exp: now + 600,
 };

package/examples/runner-fleet/start-tls-runner.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+tls_dir="${SYNAPSOR_FLEET_TLS_DIR:-/tmp/synapsor-runner-tls}"
+mkdir -p "$tls_dir"
+chmod 700 "$tls_dir"
+
+openssl req -x509 -newkey rsa:2048 -sha256 -nodes -days 1 \
+  -subj "/CN=localhost" \
+  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1" \
+  -keyout "$tls_dir/server.key" \
+  -out "$tls_dir/server.crt" \
+  >/dev/null 2>&1
+chmod 600 "$tls_dir/server.key" "$tls_dir/server.crt"
+
+export SYNAPSOR_FLEET_TLS_CERT_PEM="$(<"$tls_dir/server.crt")"
+export SYNAPSOR_FLEET_TLS_KEY_PEM="$(<"$tls_dir/server.key")"
+
+exec node apps/runner/dist/cli.js "$@" \
+  --tls-cert-env SYNAPSOR_FLEET_TLS_CERT_PEM \
+  --tls-key-env SYNAPSOR_FLEET_TLS_KEY_PEM

package/examples/runner-fleet/synapsor.runner.json

@@ -36,11 +36,37 @@
     "provider": "jwt_hs256",
     "secret_env": "SYNAPSOR_SESSION_JWT_SECRET",
     "issuer": "https://fleet.example.invalid",
-    "audience": "synapsor-runner-fleet",
+    "audience": "https://runner-fleet.example.invalid/mcp",
     "tenant_claim": "tenant_id",
     "principal_claim": "sub",
     "clock_skew_seconds": 10
   },
+  "http_security": {
+    "deployment": "shared",
+    "oauth_resource": {
+      "resource": "https://runner-fleet.example.invalid/mcp",
+      "authorization_servers": ["https://fleet.example.invalid"],
+      "resource_name": "Synthetic Synapsor Runner fleet"
+    },
+    "allowed_hosts": [
+      "127.0.0.1:8766",
+      "127.0.0.1:8871",
+      "127.0.0.1:8872",
+      "localhost:8766",
+      "localhost:8871",
+      "localhost:8872"
+    ],
+    "limits": {
+      "max_request_bytes": 65536,
+      "max_header_bytes": 8192,
+      "max_sessions": 100,
+      "session_idle_timeout_seconds": 120,
+      "request_timeout_ms": 15000,
+      "headers_timeout_ms": 5000,
+      "keep_alive_timeout_ms": 5000,
+      "max_connections": 200
+    }
+  },
   "rate_limits": {
     "enabled": true,
     "default": { "requests": 20, "window_seconds": 60 },

package/examples/support-plan-credit/README.md

@@ -252,13 +252,16 @@ verification gate.
 For Streamable HTTP, run:
 
 ```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 examples/support-plan-credit/synapsor.runner.json \
-  --store ./tmp/support-plan-credit/local.db
+  --store ./tmp/support-plan-credit/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
 ```
 
 The OpenAI client receives `support__inspect_customer` and
@@ -266,6 +269,8 @@ The OpenAI client receives `support__inspect_customer` and
 tool metadata and results. For Claude, Cursor, or generic MCP clients, omit
 `--alias-mode openai` to expose `support.inspect_customer` and
 `support.propose_plan_credit`. Approval and apply remain outside MCP.
+The HTTP client reads the same opaque endpoint token from its protected
+environment; no token value belongs in the checked-in recipe.
 
 ## How The Policy Is Governed
 

package/examples/support-plan-credit/mcp-client-examples/generic-streamable-http.json

@@ -1,5 +1,8 @@
 {
   "name": "synapsor-runner",
   "transport": "streamable-http",
-  "url": "http://127.0.0.1:8766/mcp"
+  "url": "http://127.0.0.1:8766/mcp",
+  "headers_from_env": {
+    "Authorization": "Bearer $SYNAPSOR_RUNNER_HTTP_TOKEN"
+  }
 }

package/examples/support-plan-credit/mcp-client-examples/openai-agents-streamable-http.ts

@@ -1,9 +1,13 @@
 import { Agent, MCPServerStreamableHttp, run } from "@openai/agents";
 
 // Start Runner with --alias-mode openai so model-visible tool names are valid OpenAI function names.
+const token = process.env.SYNAPSOR_RUNNER_HTTP_TOKEN;
+if (!token) throw new Error("set SYNAPSOR_RUNNER_HTTP_TOKEN in the launching environment");
+
 const synapsor = new MCPServerStreamableHttp({
   name: "Synapsor Runner",
   url: "http://127.0.0.1:8766/mcp",
+  requestInit: { headers: { Authorization: `Bearer ${token}` } },
 });
 
 await synapsor.connect();

package/examples/support-plan-credit/synapsor.contract.json

@@ -182,9 +182,6 @@
           "mode": "human",
           "required_role": "support_reviewer"
         },
-        "conflict_guard": {
-          "weak_guard_ack": true
-        },
         "numeric_bounds": {
           "amount_cents": {
             "maximum": 50000,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "1.5.3",
+  "version": "1.5.4",
   "description": "Stop giving AI agents execute_sql; expose reviewed Postgres/MySQL MCP actions with proposals, approval, writeback, and replay.",
   "license": "Apache-2.0",
   "type": "module",

package/schemas/synapsor.runner.schema.json

@@ -293,6 +293,80 @@
         "max_response_bytes": { "type": "integer", "minimum": 1024, "maximum": 10485760 }
       }
     },
+    "http_security": {
+      "description": "Runner-only deployment security for networked MCP. Credential values remain in environment or secret-manager wiring and never enter portable contracts.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "deployment": {
+          "description": "Trust topology. shared requires signed per-session http_claims identity; single_tenant may use one opaque service token.",
+          "enum": ["loopback", "single_tenant", "shared"]
+        },
+        "channel": {
+          "description": "How a remote listener is protected in transit. insecure_http_break_glass is unsafe and still requires authentication.",
+          "enum": ["direct_tls", "trusted_tls_proxy", "insecure_http_break_glass"]
+        },
+        "static_token": {
+          "description": "Environment-variable names for the current opaque endpoint token and at most one previous rotation token.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "active_env": { "$ref": "#/$defs/env_name" },
+            "previous_env": { "$ref": "#/$defs/env_name" }
+          }
+        },
+        "oauth_resource": {
+          "description": "RFC 9728 metadata for Runner as an OAuth protected resource. The external authorization server issues tokens; Runner only verifies them.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["resource", "authorization_servers"],
+          "properties": {
+            "resource": { "type": "string", "pattern": "^https://" },
+            "authorization_servers": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 8,
+              "uniqueItems": true,
+              "items": { "type": "string", "pattern": "^https://" }
+            },
+            "scopes_supported": { "type": "array", "minItems": 1, "maxItems": 64, "uniqueItems": true, "items": { "$ref": "#/$defs/oauth_scope" } },
+            "required_scopes": { "type": "array", "minItems": 1, "maxItems": 64, "uniqueItems": true, "items": { "$ref": "#/$defs/oauth_scope" } },
+            "resource_name": { "type": "string", "minLength": 1, "maxLength": 128 },
+            "resource_documentation": { "type": "string", "pattern": "^https://" }
+          }
+        },
+        "allowed_origins": {
+          "description": "Exact browser origins accepted on HTTP MCP requests. Native clients may omit Origin. Wildcards are forbidden.",
+          "type": "array",
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^https?://[^/*]+(?::[0-9]+)?$" }
+        },
+        "allowed_hosts": {
+          "description": "Exact HTTP Host authorities accepted by the direct listener or trusted proxy. Forwarded host headers are never authority.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^(?:\\[[0-9A-Fa-f:.]+\\]|[A-Za-z0-9.-]+)(?::[0-9]{1,5})?$" }
+        },
+        "limits": {
+          "description": "Bounded HTTP request, header, connection, and session resource limits.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "max_request_bytes": { "type": "integer", "minimum": 1024, "maximum": 16777216 },
+            "max_header_bytes": { "type": "integer", "minimum": 4096, "maximum": 65536 },
+            "max_sessions": { "type": "integer", "minimum": 1, "maximum": 100000 },
+            "session_idle_timeout_seconds": { "type": "integer", "minimum": 10, "maximum": 86400 },
+            "request_timeout_ms": { "type": "integer", "minimum": 1000, "maximum": 300000 },
+            "headers_timeout_ms": { "type": "integer", "minimum": 1000, "maximum": 120000 },
+            "keep_alive_timeout_ms": { "type": "integer", "minimum": 1000, "maximum": 120000 },
+            "max_connections": { "type": "integer", "minimum": 1, "maximum": 100000 }
+          }
+        }
+      }
+    },
     "cloud": {
       "type": "object",
       "additionalProperties": false,
@@ -347,6 +421,12 @@
       "type": "string",
       "pattern": "^[A-Z_][A-Z0-9_]*$"
     },
+    "oauth_scope": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[!#-\\[\\]-~]+$"
+    },
     "identifier": {
       "type": "string",
       "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"