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 3b386bb..604ba3d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,7 +15,28 @@ jobs: - uses: actions/setup-node@v4 with: - node-version: 20 + node-version: '20' + + - 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 + + - name: SDK + gate smoke matrix + shell: bash + run: | + set -euo pipefail - name: Show CLI version run: npm run ttp -- version diff --git a/README.md b/README.md index 0733d1e..7320f1c 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,21 @@ -# Trust Transfer Protocol +
+ 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. [![Protocol](https://img.shields.io/badge/protocol-draft-2f6fed)](SPECIFICATION.md) [![Reference Implementation](https://img.shields.io/badge/reference%20implementation-active%20development-f59e0b)](MVP.md) @@ -7,7 +24,40 @@ [![Production Use](https://img.shields.io/badge/production%20use-not%20recommended-b91c1c)](SECURITY.md) [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE) -TTP is an open protocol and declarative language for expressing verifiable trust, authority context, delegation, and decay before autonomous systems execute. +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.
It is designed for AI agents, non-human identities, automation pipelines, service accounts, APIs, and cross-system workflows where static access is not enough. @@ -156,93 +206,15 @@ Expected JSON shape: } ``` ---- - -## BlockSiFr Stack Boundary - -TTP is the protocol foundation beneath the BlockSiFr stack. It should remain narrow and portable. - -| Layer | Responsibility | -| --- | --- | -| TTP | Trust expression, delegation, decay, proof semantics, authority context grammar. | -| SCIM-RE | Runtime execution resource model: `WorkloadIdentity`, `AuthorityGrant`, `Attestation`, `ExecutionRequest`, `ExecutionReceipt`. | -| RAP | Runtime Authority Protocol decision exchange: `PERMIT`, `STEP_UP`, `DENY`, `THROTTLE`, `ESCALATE`, `CONSTRAIN`. | -| Execution Exchange | Enforcement gateway, route, and runtime integration layer. | -| FrontDesk | Operator/customer UI, AI workforce command center, business approval, and evidence surface. | -| VerifiedTrust | Enterprise NHI posture, policy, lifecycle governance, and compliance control plane. | - -See [`docs/ttp-vs-rap-vs-scim-re.md`](docs/ttp-vs-rap-vs-scim-re.md). - ---- - -## Current Implementation Status - -| Area | Status | -| --- | --- | -| Protocol specification | Draft complete, still open for review | -| `.ttp` examples | Initial examples added | -| Parser | MVP parser scaffold | -| AST | Initial object model | -| Trust decay evaluator | Linear decay implemented for MVP examples | -| Proof engine | Cleartext-dev threshold evaluation | -| ZKP support | Future/advanced backend, not required for MVP | -| Runtime enforcement | Out of scope for TTP core; belongs in RAP/Execution Exchange integrations | - ---- - -## MVP Scope - -The MVP focuses on a buildable, testable protocol kernel: - -- Parse `.ttp` files. -- Validate required `subject`, `trust`, `proof`, and `authority_context` blocks. -- Build an AST-like object model. -- Evaluate static trust score. -- Evaluate linear trust decay over time. -- Evaluate threshold conditions. -- Emit JSON evaluation results. -- Support `cleartext-dev` proof mode. - -See [`MVP.md`](MVP.md). - ---- - -## Roadmap - -| Phase | Focus | -| --- | --- | -| Phase 0 | Protocol cleanup, examples, threat model, stack boundaries | -| Phase 1 | MVP parser/evaluator, AST, decay evaluator, JSON output | -| Phase 2 | RAP request mapping, SCIM-RE resource mapping, SDK | -| Phase 3 | Signed claims, issuer registry, replay protection, ZKP backend prototype | -| Phase 4 | VSCode extension, formatter, conformance tests, reference gateway integration | - -See [`ROADMAP.md`](ROADMAP.md). - ---- - -## Security Model - -TTP assumes trust is scoped, temporary, issuer-bound, and evaluated at execution time. Trust claims must expire. Proof freshness matters. Issuers must be validated. Runtime enforcement must fail closed when trust context cannot be evaluated. - -TTP alone does not enforce execution. Enforcement happens through RAP, Execution Exchange, FrontDesk-integrated gateways, or equivalent runtime controls. - -Read: - -- [`THREAT_MODEL.md`](THREAT_MODEL.md) -- [`SECURITY.md`](SECURITY.md) -- [`docs/protocol-security-model.md`](docs/protocol-security-model.md) - ---- - -## Contributing - -Contributions are welcome when they improve protocol clarity, implementation correctness, examples, tests, security review, or interoperability. - -Start with [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`GOVERNANCE.md`](GOVERNANCE.md). - ---- +## Examples Gallery -## License +| 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` | -TTP is licensed under the [Apache License 2.0](LICENSE). +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 13ce3a2..c75528d 100644 --- a/docs/public-readiness.md +++ b/docs/public-readiness.md @@ -13,20 +13,15 @@ The repo now has a dependency-free local demo that shows the central value propo ### 1) Build & Test Reliability - [x] Trust Authority TypeScript build compiles in local reference environment. -- [x] Local trust-routing demo runs with `npm run demo`. -- [x] Trust-routing engine tests run with `npm run test:trust-routing`. -- [x] Automated CI workflow for demo/test checks on every PR. -- [ ] Extend CI to build SDK/reference packages and run docs/link checks. -- [ ] 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. -- [x] README leads with a concrete runtime trust gate and local demo. - [x] Add a concise "public quickstart" issue template for first-time contributors. -- [ ] Publish SDK/package installation path or keep all public docs on local/Git installs. ### 3) Security & Governance Baseline @@ -39,8 +34,7 @@ The repo now has a dependency-free local demo that shows the central value propo - [x] Agent registry listing endpoint exists (`GET /v1/admin/agents`). - [x] Quarantine/block workflows documented and implemented. -- [x] Dependency-free resolver/routing demo exists for first evaluation. -- [ ] 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 a8a95ab..73232a0 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,