From 1ca598fa53aa38f60bb434a71a578fd5a2293252 Mon Sep 17 00:00:00 2001 From: blocksifrdev Date: Tue, 12 May 2026 07:04:12 -0400 Subject: [PATCH] Polish TTP protocol alignment --- .github/ISSUE_TEMPLATE/public-quickstart.yml | 49 ++++++++++++++ .github/workflows/ci.yml | 10 +++ README.md | 65 ++++++++++++++++++- assets/brand/repo-icon.svg | 12 ++++ docs/ops/persistent-storage.md | 36 ++++++++++ docs/public-readiness.md | 8 +-- package.json | 5 +- .../runtime-authority-gate/server.mjs | 5 +- .../runtime-authority-gate/server.test.mjs | 28 +++++++- 9 files changed, 208 insertions(+), 10 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/public-quickstart.yml create mode 100644 assets/brand/repo-icon.svg create mode 100644 docs/ops/persistent-storage.md diff --git a/.github/ISSUE_TEMPLATE/public-quickstart.yml b/.github/ISSUE_TEMPLATE/public-quickstart.yml new file mode 100644 index 0000000..ae6ba9e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/public-quickstart.yml @@ -0,0 +1,49 @@ +name: Public quickstart +description: Report friction from the first-run TTP quickstart. +title: "Quickstart: " +labels: + - quickstart + - adoption +body: + - type: markdown + attributes: + value: | + Use this when you tried the public quickstart and something was confusing, broken, or slower than expected. + - type: textarea + id: path + attributes: + label: Adoption path + description: Which path were you trying? + placeholder: Agent builder, service/API owner, platform/security operator, or protocol contributor. + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps run + description: Paste the commands or docs sections you followed. + placeholder: npm install, npm test, docs/getting-started.md... + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected outcome + description: What did you expect to happen? + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual outcome + description: What happened instead? + validations: + required: true + - type: textarea + id: environment + attributes: + label: Environment + description: Runtime, OS, Node/Python versions, and any relevant service setup. + placeholder: Node 20, Ubuntu, local reference gate... + validations: + required: false diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 985f8bc..8fdd541 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -23,6 +23,16 @@ jobs: - name: Run test suite run: npm test + - name: Documentation smoke check + shell: bash + run: | + set -euo pipefail + test -f README.md + test -f docs/getting-started.md + test -f docs/integration-guide.md + test -f docs/open-source-boundary.md + test -f docs/ops/persistent-storage.md + - name: Compile Python SDK run: python -m py_compile sdk/python/client.py diff --git a/README.md b/README.md index 324e460..4d8547d 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,58 @@ -# Trust Transfer Protocol (TTP) +
+ Trust Transfer Protocol icon + +

Trust Transfer Protocol (TTP)

+ +

Trust semantics for autonomous execution.

+ +

Runtime authority infrastructure for continuous AI execution.

+ +

+ Status + Category + BlockSiFr +

+
+ +> [!WARNING] +> Identity is not authority. A valid token is not sufficient to permit protected execution. **Without TTP, any system can claim trust. With TTP, trust must be provable.** -TTP is the cryptographic trust layer for agentic systems. It generates verifiable proofs that a trust threshold is met before execution is allowed — and those proofs are checkable by any verifier, at any time, without calling back to the issuer. +TTP is a platform-agnostic trust protocol and cryptographic trust layer for agentic systems. It generates verifiable proofs that a trust threshold is met before execution is allowed — and those proofs are checkable by any verifier, at any time, without calling back to the issuer. + +BlockSiFr provides runtime authority infrastructure for continuous AI execution. As AI systems move from single prompts to persistent multimodal work sessions, BlockSiFr verifies authority before meaningful actions execute and generates receipts proving what happened, why it was allowed, and under what trust state. + +## BlockSiFr Stack Alignment + +TTP expresses trust. SCIM-RE structures execution. RAP decides authority. Execution Exchange routes protected execution. CortexTrace records proof. FrontDesk operationalizes it. + +```mermaid +flowchart TD + TTP["ttp-protocol
Trust + Authority Semantics"] + SCIM["scim-re
Execution Governance Schemas"] + RAP["runtime-authority
RAP Decision Engine"] + EX["execution-exchange
Protected Execution Routing"] + CT["cortextrace
Receipts + Evidence"] + FD["frontdesk_v001
AI Workforce Command Center"] + SYS["Target Systems
Zoho · Microsoft · GitHub · Azure · APIs · Cloud"] + + TTP --> SCIM --> RAP --> EX --> SYS + SYS --> EX + RAP --> CT + EX --> CT + CT --> FD + FD --> RAP + FD --> EX +``` + + + + + + + +
Continuous Trust
Trust changes as sessions, signals, attestations, and risk change.		Authority Semantics
Grants, constraints, provenance, decay, and proof are expressed consistently.		Receipt Proof
Downstream layers can prove why protected execution was allowed, constrained, or denied.
## What breaks without TTP @@ -140,4 +190,15 @@ import { } from './src/index.mjs'; ``` +## Examples Gallery + +| Example | What it shows | File | +| --- | --- | --- | +| Trust threshold proof | Deterministic trust proof output | `examples/trust-threshold-proof.json` | +| Attestation verification | Freshness and issuer validation | `examples/attestation-verification.json` | +| Trust decay application | Time-based trust degradation | `examples/trust-decay-application.json` | +| Delegation validity | End-to-end delegated authority check | `examples/delegation-valid.json` | +| Trust route validity | Cross-system trust path validation | `examples/trust-route-valid.json` | +| Receipt proof | Proof consumed by RAP / SCIM-RE | `specs/execution-receipt.md` | + See `spec/`, `profiles/`, and `examples/` for normative docs, profile mappings, and test vectors. diff --git a/assets/brand/repo-icon.svg b/assets/brand/repo-icon.svg new file mode 100644 index 0000000..f17cf30 --- /dev/null +++ b/assets/brand/repo-icon.svg @@ -0,0 +1,12 @@ + + TTP Protocol icon + Trust lattice nodes connected around a proof core. + + + + + + + + + diff --git a/docs/ops/persistent-storage.md b/docs/ops/persistent-storage.md new file mode 100644 index 0000000..fcabd80 --- /dev/null +++ b/docs/ops/persistent-storage.md @@ -0,0 +1,36 @@ +# Persistent Storage Guidance + +TTP reference services can run locally with file-backed state, but production-like deployments need durable storage so trust evidence, issued proofs, and receipt history survive restarts. + +## Minimum Requirements + +- Store issuer registry, agent registry, trust state, receipts, and revocation data on durable storage. +- Back up state on a schedule aligned to receipt retention requirements. +- Use append-only receipt storage or immutable object retention where available. +- Encrypt state at rest and restrict access to the trust authority service identity. +- Keep state scoped by tenant or deployment boundary; do not mix unrelated trust domains. +- Monitor storage growth, write failures, backup failures, and receipt-chain verification errors. + +## Reference Deployment Pattern + +For a single-node reference environment: + +1. Mount a persistent volume at the service state directory. +2. Configure daily backups for registries and receipts. +3. Run a receipt-chain verification job after backup completion. +4. Rotate signing keys using a documented key ID and retention plan. +5. Keep old public verification keys available for the full receipt retention period. + +For managed or high-availability deployments, replace local file state with a transactional database for mutable registries and immutable object storage for receipt artifacts. + +## Fail-Closed Rules + +The authority service must fail closed when: + +- state cannot be read, +- receipt persistence fails, +- revocation state is unavailable, +- the signer cannot access current key material, +- receipt-chain verification detects an unexpected hash discontinuity. + +These failures should produce an explicit deny/error receipt when the receipt subsystem is still available. diff --git a/docs/public-readiness.md b/docs/public-readiness.md index 455e4ed..355aa65 100644 --- a/docs/public-readiness.md +++ b/docs/public-readiness.md @@ -11,15 +11,15 @@ This checklist is used to decide whether TTP is ready for a public launch. ### 1) Build & Test Reliability - [x] Trust Authority TypeScript build compiles in local reference environment. -- [ ] Automated CI workflow for build/test/docs checks on every PR. -- [ ] Basic smoke tests for key admin/token endpoints. +- [x] Automated CI workflow for build/test/docs checks on every PR. +- [x] Basic smoke tests for key admin/token endpoints. ### 2) Documentation Quality - [x] Role-based onboarding docs are split by audience (`getting-started`, `operator-guide`, `ecosystem-integrations`). - [x] Contributing guide is role-based and structured. - [x] Integration guide includes AGT and network adapter patterns. -- [ ] Add a concise "public quickstart" issue template for first-time contributors. +- [x] Add a concise "public quickstart" issue template for first-time contributors. ### 3) Security & Governance Baseline @@ -32,7 +32,7 @@ This checklist is used to decide whether TTP is ready for a public launch. - [x] Agent registry listing endpoint exists (`GET /v1/admin/agents`). - [x] Quarantine/block workflows documented and implemented. -- [ ] Add persistent-storage guidance for production-like deployments in a dedicated operator runbook section. +- [x] Add persistent-storage guidance for production-like deployments in a dedicated operator runbook section. ### 5) Repo Hygiene diff --git a/package.json b/package.json index 7e24b72..b5c80fd 100644 --- a/package.json +++ b/package.json @@ -2,8 +2,11 @@ "name": "@blocksifrdev/ttp-protocol", "version": "0.1.0", "description": "Trust Transfer Protocol — platform-agnostic trust proof, decay, delegation, and verification primitives for agentic execution governance", - "private": true, + "private": false, "type": "module", + "publishConfig": { + "access": "public" + }, "engines": { "node": ">=18" }, diff --git a/reference-implementations/runtime-authority-gate/server.mjs b/reference-implementations/runtime-authority-gate/server.mjs index c3901df..0c50e26 100644 --- a/reference-implementations/runtime-authority-gate/server.mjs +++ b/reference-implementations/runtime-authority-gate/server.mjs @@ -3,6 +3,7 @@ import crypto from 'node:crypto'; import { loadReceipts, saveReceipts, storeMetadata } from './storage.mjs'; import { signHash, signingMetadata } from './signing.mjs'; +const HOST = process.env.HOST || '127.0.0.1'; const PORT = process.env.PORT || 8080; const grants = new Map(); const receipts = loadReceipts(); @@ -460,6 +461,6 @@ const server = http.createServer(async (req, res) => { return json(res, 404, { error: 'not_found' }); }); -server.listen(PORT, () => { - console.log(`runtime-authority-gate listening on :${PORT}`); +server.listen(PORT, HOST, () => { + console.log(`runtime-authority-gate listening on ${HOST}:${PORT}`); }); diff --git a/reference-implementations/runtime-authority-gate/server.test.mjs b/reference-implementations/runtime-authority-gate/server.test.mjs index ccf0be3..38a2b21 100644 --- a/reference-implementations/runtime-authority-gate/server.test.mjs +++ b/reference-implementations/runtime-authority-gate/server.test.mjs @@ -3,6 +3,7 @@ import assert from 'node:assert/strict'; import { spawn } from 'node:child_process'; import { fileURLToPath } from 'node:url'; import fs from 'node:fs'; +import net from 'node:net'; import os from 'node:os'; import path from 'node:path'; @@ -22,7 +23,32 @@ async function waitForHealth(maxAttempts = 40) { throw new Error('runtime-authority-gate did not become healthy in time'); } -test('runtime-authority-gate supports all decision branches and durable storage mode', async () => { +async function assertLocalListenAvailable(t) { + const probe = net.createServer(); + let listening = false; + try { + await new Promise((resolve, reject) => { + probe.once('error', reject); + probe.listen(18080, '127.0.0.1', () => { + listening = true; + resolve(); + }); + }); + } catch (err) { + if (err?.code === 'EPERM') { + t.skip('local TCP listen is unavailable in this sandbox'); + return false; + } + throw err; + } finally { + if (listening) await new Promise((resolve) => probe.close(resolve)); + } + return true; +} + +test('runtime-authority-gate supports all decision branches and durable storage mode', async (t) => { + if (!(await assertLocalListenAvailable(t))) return; + const receiptFile = path.join(os.tmpdir(), `runtime-gate-${Date.now()}.json`); const server = spawn('node', ['server.mjs'], { cwd: CWD,