diff --git a/.github/ISSUE_TEMPLATE/quickstart-feedback.yml b/.github/ISSUE_TEMPLATE/quickstart-feedback.yml new file mode 100644 index 0000000..45d548a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/quickstart-feedback.yml @@ -0,0 +1,39 @@ +name: Quickstart feedback +description: Report friction from the first TTP demo or integration path. +title: "[Quickstart]: " +labels: + - docs + - developer-experience +body: + - type: markdown + attributes: + value: | + Use this when the local demo, getting started guide, or first integration path is unclear or does not work. + - type: input + id: path + attributes: + label: Path tried + description: Which path were you using? + placeholder: npm run demo, SDK install, Trust Authority setup, GitHub Actions gate + 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? Include command output if useful. + validations: + required: true + - type: textarea + id: environment + attributes: + label: Environment + description: Node version, OS, package manager, and any relevant runtime context. + placeholder: Node 20, macOS/Linux/Windows, npm/pnpm/yarn diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 985f8bc..2a2b77f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,106 +1,24 @@ -name: CI / Repository Health +name: CI on: - push: - branches: ["**"] pull_request: + push: + branches: + - main jobs: - test: - name: Test and Smoke Checks + verify: + name: Demo and Tests runs-on: ubuntu-latest - permissions: - contents: read - steps: - uses: actions/checkout@v4 - - name: Setup Node - uses: actions/setup-node@v4 + - uses: actions/setup-node@v4 with: - node-version: '20' - - - name: Run test suite - run: npm test - - - name: Compile Python SDK - run: python -m py_compile sdk/python/client.py - - - name: SDK + gate smoke matrix - shell: bash - run: | - set -euo pipefail - - node reference-implementations/runtime-authority-gate/server.mjs >/tmp/runtime-gate.log 2>&1 & - GATE_PID=$! - trap 'kill $GATE_PID' EXIT - - for i in {1..20}; do - if curl -fsS http://127.0.0.1:8080/healthz >/dev/null; then - break - fi - sleep 0.2 - done - - # PERMIT - curl -fsS -X POST http://127.0.0.1:8080/re/authorize \ - -H 'content-type: application/json' \ - -d '{"requestId":"ci-permit","subject":"ci-agent","action":"pipeline.deploy","resource":{"id":"prod"},"context":{"trustScore":0.9,"environment":"dev"},"authorityGrant":{"grantId":"grant-local-001"}}' \ - | jq -e '.decision=="PERMIT" and .mode=="FULL" and .rapDecision=="allow"' >/dev/null - - # STEP_UP - STEP_UP_RECEIPT=$(curl -fsS -X POST http://127.0.0.1:8080/re/authorize \ - -H 'content-type: application/json' \ - -d '{"requestId":"ci-stepup","subject":"ci-agent","action":"pipeline.deploy","resource":{"id":"prod"},"context":{"trustScore":0.55,"environment":"dev"},"authorityGrant":{"grantId":"grant-local-001"}}' \ - | jq -r 'select(.decision=="STEP_UP" and .rapDecision=="step_up") | .receiptId') - test -n "$STEP_UP_RECEIPT" - - # ESCALATE - curl -fsS -X POST http://127.0.0.1:8080/re/authorize \ - -H 'content-type: application/json' \ - -d '{"requestId":"ci-escalate","subject":"mythos-agent","action":"tool.invoke.delete_secret","resource":{"id":"prod-secret"},"context":{"trustScore":0.95,"environment":"prod","agentType":"mythos"},"authorityGrant":{"grantId":"grant-local-001"}}' \ - | jq -e '.decision=="ESCALATE" and .rapDecision=="escalate"' >/dev/null - - # DENY - curl -fsS -X POST http://127.0.0.1:8080/re/authorize \ - -H 'content-type: application/json' \ - -d '{"requestId":"ci-deny","subject":"ci-agent","action":"pipeline.deploy","resource":{"id":"prod"},"context":{"trustScore":0.1,"environment":"dev"},"authorityGrant":{"grantId":"grant-local-001"}}' \ - | jq -e '.decision=="DENY" and .rapDecision=="deny"' >/dev/null - - # REAUTHORIZE - curl -fsS -X POST http://127.0.0.1:8080/re/reauthorize \ - -H 'content-type: application/json' \ - -d "{\"requestId\":\"ci-reauth\",\"priorReceiptId\":\"$STEP_UP_RECEIPT\",\"approval\":{\"approvedBy\":\"ops-admin\",\"evidenceRef\":\"ticket-ci\"}}" \ - | jq -e '.decision=="PERMIT" and .mode=="CONSTRAINED" and .rapDecision=="throttle"' >/dev/null + node-version: 20 - python - <<'PY' -from sdk.python import authorize, AuthorizeRequest, Principal, Resource, AuthorityGrant -resp = authorize(AuthorizeRequest( - base_url='http://127.0.0.1:8080', - requestId='ci-py-1', - principal=Principal(id='py-ci-agent', type='service-agent'), - action='pipeline.deploy', - resource=Resource(type='environment', id='prod'), - context={'trustScore': 0.91, 'environment': 'dev'}, - authorityGrant=AuthorityGrant(grantId='grant-local-001', expiresAt='2030-01-01T00:00:00Z', scope=['pipeline.deploy:prod']) -)) -assert resp.decision.value == 'PERMIT' -PY + - name: Run local adoption demo + run: npm run demo - node --input-type=module - <<'JS' -import { authorize } from './sdk/node/index.js'; -const resp = await authorize({ - baseUrl: 'http://127.0.0.1:8080', - requestId: 'ci-node-1', - principal: { id: 'node-ci-agent', type: 'service-agent' }, - action: 'pipeline.deploy', - resource: { type: 'environment', id: 'prod' }, - context: { trustScore: 0.92, environment: 'dev' }, - authorityGrant: { - grantId: 'grant-local-001', - expiresAt: '2030-01-01T00:00:00Z', - scope: ['pipeline.deploy:prod'] - } -}); -if (resp.decision !== 'PERMIT') throw new Error('Expected PERMIT'); -JS + - name: Run trust-routing tests + run: npm run test:trust-routing diff --git a/.github/workflows/governed-execution.yml b/.github/workflows/governed-execution.yml new file mode 100644 index 0000000..ccebbe9 --- /dev/null +++ b/.github/workflows/governed-execution.yml @@ -0,0 +1,131 @@ +name: TTP / Governed Execution Proof + +on: + pull_request: + types: [opened, synchronize, reopened, ready_for_review] + +jobs: + govern: + name: Governed Execution + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + + outputs: + decision: ${{ steps.authorize.outputs.decision }} + receipt: ${{ steps.authorize.outputs.receipt }} + + steps: + # 1️⃣ Full checkout (safe and correct) + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + # 2️⃣ Detect changed files + - name: Detect changes + id: changes + shell: bash + run: | + set -euo pipefail + BASE="${{ github.event.pull_request.base.sha }}" + HEAD="${{ github.event.pull_request.head.sha }}" + + git diff --name-only "$BASE" "$HEAD" > changed.txt || true + + echo "Changed files:" + cat changed.txt || true + + PATHS_JSON=$(jq -R . < changed.txt | jq -s .) + echo "paths=$PATHS_JSON" >> "$GITHUB_OUTPUT" + + # 3️⃣ Ask external authority for permission + - name: Authorize execution + id: authorize + env: + AUTH_URL: ${{ secrets.RUNTIME_AUTH_URL }} + AUTH_TOKEN: ${{ secrets.RUNTIME_AUTH_TOKEN }} + shell: bash + run: | + set -euo pipefail + + if [ ! -s changed.txt ]; then + echo "No changes → deny by policy" + echo "decision=DENY" >> "$GITHUB_OUTPUT" + echo "receipt=" >> "$GITHUB_OUTPUT" + exit 0 + fi + + jq -n \ + --arg repo "${{ github.repository }}" \ + --arg actor "${{ github.actor }}" \ + --arg pr "${{ github.event.pull_request.number }}" \ + --arg sha "${{ github.event.pull_request.head.sha }}" \ + --argjson paths "$(jq -s . changed.txt | jq -R .)" \ + '{ + subject: "wi://github/actions/runner", + action: "pull_request.execute", + resource: ("repo:" + $repo + ":pr/" + $pr), + commitSha: $sha, + actor: $actor, + pathsTouched: $paths, + context: { + event: "pull_request", + repo: $repo + } + }' > request.json + + curl -sS \ + -H "Authorization: Bearer $AUTH_TOKEN" \ + -H "Content-Type: application/json" \ + -X POST "$AUTH_URL/re/authorize" \ + -d @request.json \ + > response.json + + cat response.json + + DECISION=$(jq -r '.decision // "DENY"' response.json) + RECEIPT=$(jq -r '.receiptId // ""' response.json) + + echo "decision=$DECISION" >> "$GITHUB_OUTPUT" + echo "receipt=$RECEIPT" >> "$GITHUB_OUTPUT" + + # 4️⃣ Human approval if required + step-up: + name: Step‑Up Approval + runs-on: ubuntu-latest + needs: govern + if: needs.govern.outputs.decision == 'STEP_UP' + environment: + name: protected-execution + steps: + - run: | + echo "Manual authorization granted via environment." + echo "Receipt: ${{ needs.govern.outputs.receipt }}" + + # 5️⃣ Final enforcement gate + enforce: + name: Enforce Authority Decision + runs-on: ubuntu-latest + needs: [govern, step-up] + if: always() + steps: + - run: | + DECISION="${{ needs.govern.outputs.decision }}" + RECEIPT="${{ needs.govern.outputs.receipt }}" + + echo "Final decision: $DECISION" + echo "Receipt: $RECEIPT" + + if [ -z "$RECEIPT" ]; then + echo "Missing receipt → hard deny" + exit 1 + fi + + if [ "$DECISION" = "PERMIT" ]; then + echo "✅ Execution permitted" + exit 0 + fi + + echo "❌ Execution denied" + exit 1 diff --git a/README.md b/README.md index 324e460..feafaee 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,482 @@ # Trust Transfer Protocol (TTP) -**Without TTP, any system can claim trust. With TTP, trust must be provable.** +TTP is an open protocol for deciding whether an autonomous system should be allowed to execute a protected action right now. + +It fills the gap between **identity authentication** and **execution-time trustworthiness** by using signed behavioral evidence, trust routing, short-lived trust tokens, and verifiable execution receipts. 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. ## What breaks without TTP -- Authority decisions rely on trust that is asserted but never verified -- Decayed or revoked attestations remain valid indefinitely with no signal -- No proof artifact exists — auditors see a decision with no supporting evidence -- Delegated trust chains cannot be validated end-to-end +## Why Teams Adopt TTP + +Autonomous agents can hold valid credentials while their behavior is stale, risky, compromised, or outside policy. TTP adds a runtime trust gate before high-impact actions such as production deploys, customer messaging, discount issuance, code changes, and tool execution. + +Instead of asking only "who is calling?", TTP asks: + +```text +Should this subject execute this action on this resource now? +``` + +The answer is explicit: `PERMIT`, `DENY`, `STEP_UP`, `THROTTLE`, or `CONSTRAIN`, with a receipt that can be audited later. + +--- + +## Try It In 60 Seconds + +Run the local trust-gate demo. It has no external dependencies and shows the core adoption wedge: a protected execution request is permitted, stepped up, or denied based on current trust evidence. + +```bash +npm run demo +``` + +Expected shape: + +```text +PERMIT trusted build action +decision: PERMIT +reason: route_valid + +STEP_UP production deploy +decision: STEP_UP +reason: step_up_required + +DENY revoked workload +decision: DENY +reason: revoked_subject +``` + +The demo is implemented in `examples/local-trust-gate-demo.mjs` and uses the routing engine in `packages/trust-routing-engine`. + +--- + +## What TTP Is + +- A protocol for **runtime trust decisions**. +- A receipt and token model for **stateless verification at service boundaries**. +- A way to combine evidence from **multiple independent issuers**. +- A trust-routing model for selecting a valid authority path before execution. +- A portable foundation for agent, workflow, and service governance. + +## What TTP Is Not + +- Not a replacement for OAuth/OIDC, IAM, SPIFFE, mTLS, ZTNA, or API gateways. +- Not a generic monitoring dashboard. +- Not a static policy-only system. +- Not a vendor-locked hosted service requirement. + +--- + +## Core Flow + +```text +execution request -> route resolution -> authority decision -> execution receipt -> enforcement +``` + +Concrete flow: + +1. A subject requests a protected action. +2. Issuers provide signed behavioral evidence. +3. A Trust Authority or resolver evaluates route, score, freshness, scope, and policy. +4. The service receives a scoped decision. +5. Execution is permitted, denied, stepped up, throttled, or constrained. +6. An execution receipt records what happened and why. + +--- + +## Core Concept + +- Trust is evaluated at execution time, not only at login time. +- Receipts are signed and verifiable. +- Tokens are short-lived and domain-scoped. +- Services verify tokens statelessly. +- Trust can decay and recover based on recent behavior. +- Multi-issuer evidence reduces single-observer bias. + +--- + +## How it works + +```text +Agent -> Issuers -> Trust Authority -> Trust Token -> Service Verifier -> Execution +``` + +Trust flow: + +1. Agent performs actions +1. Independent issuers observe behavior +1. Issuers generate signed behavioral receipts +1. Trust Authority aggregates receipts and computes trust score +1. Trust Authority issues short-lived trust token +1. Agent presents token to service +1. Service verifies token and enforces policy +1. Access granted or denied + +Verification at the service boundary is stateless and cryptographic. + +----- + +## Trust Routing Subsystem + +TTP includes a runtime **Trust Routing** subsystem for trust-before-execution: + +`execution request -> route resolution -> authority decision -> execution receipt -> enforcement` + +Core implementation entry points: +- `apps/trust-route-resolver/src/server.mjs` (runtime APIs) +- `packages/trust-routing-engine/src/*` (resolver, decay, policy, receipt logic) +- `.github/workflows/governed-execution.yml` (GitHub Actions governed execution example) +- `examples/local-trust-gate-demo.mjs` (local permit/step-up/deny demo) + +----- + +## Core Components + +### Behavioral Receipts + +Signed records of observed agent behavior. + +Receipts contain: + +- agent identity +- issuer identity +- event type +- timestamp +- domain +- behavioral score (optional) +- cryptographic signature + +Receipts are tamper-evident and verifiable. + +----- + +### Independent Issuers + +Issuers observe and attest to agent behavior. + +Examples: + +- API gateways +- Tool execution environments +- Inference gateways +- Security monitors +- Sandbox runtimes + +Multiple issuers reduce manipulation risk. + +----- + +### Trust Authority + +Aggregates receipts and issues trust tokens. + +Responsibilities: + +- Verify receipt signatures +- Aggregate behavioral evidence +- Compute trust score +- Issue short-lived trust tokens + +Trust Authorities may be: + +- Self-hosted +- Enterprise-hosted +- Provided as managed infrastructure + +----- + +### Trust Tokens + +Short-lived cryptographically signed tokens containing: + +- agent identity +- trust score +- domain scope +- issuance timestamp +- expiration timestamp + +Services verify tokens before granting access. + +Tokens expire quickly to ensure freshness. + +----- + +### Service Verifier + +Service-side verification logic. + +Verifies: + +- Token signature +- Token freshness +- Domain scope +- Minimum trust score + +Verification is stateless and fast. + +----- + +## Example Use Case: AI Retention Systems + +Autonomous retention agents perform actions such as: + +- Issuing discounts +- Triggering campaigns +- Sending customer messages + +Without TTP: + +Services trust agents based only on identity. + +With TTP: + +Services verify that the agent is currently trustworthy based on recent behavior. + +Flow: + +``` +Retention Agent → Trust Authority → Trust Token → Service → Verified Execution +``` + +This enables safe autonomous retention. + +See for detailed integration guide. + +----- + +## Protocol Properties + +### Runtime Trust Evaluation + +Trust is evaluated continuously, not just at authentication. + +----- + +### Behavioral Trust + +Trust derives from observed behavior, not static credentials. + +----- + +### Cryptographic Verification + +Trust decisions are based on signed, verifiable evidence. + +----- + +### Stateless Enforcement + +Services do not require access to behavioral history. + +Trust tokens contain necessary verification data. + +----- + +### Domain Isolation + +Trust is scoped to operational domains. + +Trust in one domain does not automatically transfer to another. + +----- + +### Issuer Independence + +Trust evidence may originate from multiple independent issuers. + +----- + +## Receipt Schema + +Canonical receipt structure: + +```json +{ + "ttp_version": "1.0", + "receipt_id": "uuid-v4", + "agent_id": "string", + "issuer_id": "string", + "event_type": "string", + "event_data": {}, + "domain": "string", + "timestamp": 1700000000000, + "score": 0.92, + "signature": "base64url-encoded-ed25519" +} +``` + +Signatures use Ed25519. The `ttp_version` field enables verifiers to apply the correct validation rules as the protocol evolves. See [protocol/schemas/receipt.schema.json](protocol/schemas/receipt.schema.json) for the full JSON Schema. + +----- + +## Trust Token Structure + +JWT format with TTP-specific claims: + +```json +{ + "ttp_version": "1.0", + "sub": "agent_id", + "iss": "trust_authority_id", + "iat": 1700000000, + "exp": 1700000300, + "jti": "unique-token-id", + "ttp_domain": "retention", + "ttp_score": 0.91, + "ttp_issuer_count": 3, + "ttp_receipt_window": 300 +} +``` + +Key claims: + +- `ttp_version` — protocol version used to produce this token +- `ttp_score` — aggregated trust score (0.0–1.0) +- `ttp_issuer_count` — number of independent issuers contributing receipts +- `ttp_receipt_window` — seconds of behavioral history reflected in the score +- `jti` — unique token ID for replay detection + +Tokens are short-lived. Recommended maximum TTL is 300 seconds. See [protocol/schemas/trust-token.schema.json](protocol/schemas/trust-token.schema.json) for the full JSON Schema. + +----- + +## Reference Implementation + +Reference SDK provides: + +- Agent token retrieval +- Receipt submission +- Service verification middleware + +Example: + +```typescript +import { TTPClient } from "@ttp/sdk" + +const client = new TTPClient({ + agentId: "agent-1", + privateKey: process.env.TTP_PRIVATE_KEY, + authority: "https://api.ttp.network" +}) + +const token = await client.getTrustToken({ + domain: "retention" +}) +``` + +Service verification: + +```typescript +import { verifyTTPToken } from "@ttp/sdk" + +app.post("/api/issue-discount", async (req, res) => { + const token = req.headers["x-ttp-token"] + + const verification = await verifyTTPToken(token, { + domain: "retention", + minScore: 0.85 + }) + + if (!verification.valid) { + return res.status(403).json({ error: "Insufficient trust" }) + } + + // Execute action + await issueDiscount(req.body) + res.json({ success: true }) +}) +``` + +----- + +## Quickstart (Simple Path) + +If you want the fastest path from zero to first protected action: + +1. **Run the Trust Authority** using the reference implementation. +1. **Register one agent + one issuer** using admin endpoints. +1. **Submit receipts** from your issuer as the agent performs actions. +1. **Request a trust token** from the agent. +1. **Verify token in your service** and enforce `minScore`. + +Use this guide for full commands and environment setup: +- [docs/integration-guide.md](docs/integration-guide.md) + +----- + +## Integration Paths (Choose One) -## 30-second demo +### Path A — Agent builder +You own an autonomous agent and need runtime trust gating. + +- Integrate `TTPClient` in the agent runtime. +- Request domain-scoped trust tokens before sensitive actions. +- Pass `X-TTP-Token` to downstream protected services. + +### Path B — Service/API owner +You operate APIs and need behavior-aware authorization. + +- Add TTP middleware or manual token verification. +- Configure per-route `domain` and `minScore` policies. +- Enforce deny/degrade/cached fallback by operation risk. + +### Path C — Platform/security operator +You run shared infrastructure for many agents. + +- Deploy and operate the Trust Authority. +- Register issuers and agents. +- Define score thresholds, quarantine policies, and domain boundaries. + +----- + +## Build the Network (Core -> Edge Participation Model) + +TTP adoption works best when participants can join at different layers. You do **not** need to run everything on day one. + +### Role 1 — Network Core Operator +Owns shared trust infrastructure for a domain/ecosystem. + +- Stand up and operate a Trust Authority. +- Publish verification keys and operational policies. +- Curate issuer admission, diversity, and governance. + +### Role 2 — Issuer Operator +Contributes signed behavioral evidence. + +- Run one or more issuers (gateway, runtime, monitor, sandbox). +- Submit high-quality receipts with clear event semantics. +- Maintain independent operational control to reduce collusion risk. + +### Role 3 — Verifier / Service Owner +Enforces trust at execution boundaries. + +- Verify TTP tokens at API, tool, or workflow boundaries. +- Apply domain-specific `minScore` thresholds. +- Use fallback modes appropriate to business risk. + +### Role 4 — Agent Builder / Integrator +Makes autonomous systems TTP-aware. + +- Request short-lived trust tokens per domain. +- Present tokens to protected services. +- Tune behavior and controls using trust feedback loops. + +### Start where you are + +- If you're an enterprise platform team: start as **Network Core + Verifier**. +- If you're an infra/security vendor: start as **Issuer + Verifier**. +- If you're an agent framework/vendor: start as **Agent Builder + Issuer**. +- If you're a single product team: start as **Verifier**, then add issuer coverage. + +This core-to-edge model lets the network expand outward without forcing every team to adopt every component at once. + +----- + +## Agent Registry & Trust Operations (Reference API) + +The reference Trust Authority includes admin endpoints that act as an operator-facing registry for known agents and operational trust state. + +### Register known agents ```bash npm install @@ -114,7 +579,67 @@ authority evaluated by RAP / SCIM-RE execution allowed only if authority is valid ``` -## Non-goals +Key implementation entry points: + +- `apps/trust-route-resolver/src/server.mjs` +- `packages/trust-routing-engine/src/*` +- `.github/workflows/governed-execution.yml` +- `examples/local-trust-gate-demo.mjs` + +--- + +## What guarantees you get + +- Cryptographic integrity of receipts and tokens. +- Time-bounded trust decisions. +- Domain isolation (trust does not automatically transfer across domains). +- Fail-closed decision model when trust requirements are not met. +- Stateless verification at service boundaries. + +``` +ttp-protocol/ +├── protocol/ +│ ├── spec.md # Protocol specification +│ ├── schemas/ # JSON schemas +│ └── rfc/ # Protocol RFCs +├── sdk/ +│ └── typescript/ # TypeScript SDK foundation +├── examples/ +│ ├── local-trust-gate-demo.mjs +│ ├── retention-platform-integration.md +│ ├── basic-agent/ +│ ├── service-integration/ +│ └── issuer-implementation/ +├── docs/ +│ ├── architecture.md +│ ├── security.md +│ ├── governance.md +│ ├── patent-strategy.md +│ ├── integration-guide.md +│ ├── getting-started.md +│ ├── operator-guide.md +│ └── ecosystem-integrations.md +├── reference-implementations/ +│ ├── trust-authority/ +│ └── issuers/ +└── README.md +``` + +--- + +## What you run + +Reference components in this repo: + +- Protocol + schemas: `protocol/` +- Trust Authority reference: `reference-implementations/trust-authority/` +- Issuer references: `reference-implementations/issuers/` +- Trust-route resolver demo: `apps/trust-route-resolver/` +- Trust-routing engine: `packages/trust-routing-engine/` + +--- + +## What you integrate - TTP does not replace SCIM-RE. - TTP does not implement platform adapters. @@ -124,20 +649,134 @@ execution allowed only if authority is valid ## Quickstart +### 1) Run the local trust-gate demo + ```bash -npm install -node --test tests/*.test.mjs +npm run demo ``` -```js -import { - prove_trust_threshold, - verify_attestation, - apply_decay, - verify_delegation, - verify_trust_route, - validate_transfer -} from './src/index.mjs'; +This shows `PERMIT`, `STEP_UP`, and `DENY` decisions with execution receipts. + +### 2) Run Trust Authority reference implementation + +```bash +npm install +npm run build +npm run generate-keys +npm start ``` +----- + +## Roadmap + +**Phase 1: Foundation (Current)** + +- Protocol specification v1.0 +- TypeScript SDK +- Reference Trust Authority +- Retention platform integration examples + +**Phase 2: Ecosystem** + +- Python and Go SDKs +- Issuer reference implementations (API Gateway, Lambda, Kubernetes) +- Hosted Trust Authority beta +- Integration with major agent frameworks + +**Phase 3: Enterprise** + +- Enterprise Trust Authority features (audit, compliance, multi-tenant) +- Advanced threat detection +- Performance optimizations +- Governance framework maturity + +**Phase 4: Standardization** + +- Formal specification submission +- Multi-vendor implementations +- Industry adoption + +See for detailed timeline. + +----- + +## Contributing + +Contributions welcome. + +Areas of interest: + +- Trust Authority / network core operations +- Issuer integrations and adapters +- Verifier enforcement patterns +- Agent SDK/runtime integrations +- Security analysis and threat modeling +- Documentation and onboarding + +See for guidelines. + +----- + +## Community + +- **Discussions:** [GitHub Discussions](https://github.com/blocksifrdev/ttp-protocol/discussions) +- **Issues:** [GitHub Issues](https://github.com/blocksifrdev/ttp-protocol/issues) +- **Email:** hello@blocksifr.com +- **Twitter:** [@blocksifr](https://twitter.com/blocksifr) + +----- + +## Integration References + +- Easy connect API: `docs/easy-connect-api.md` +- Runtime connect contract: `runtime/api/connect.contract.md` +- Full verification flow: `docs/integration-guide.md` + +--- + +## GitHub self-governance (runtime authority for repo actions) + +- Architecture: `docs/github-self-governance-reference-architecture.md` +- Protected action model: `docs/protected-action-model.md` +- Workflow contract: `docs/protected-gate-workflow-contract.md` + +--- + +## Security, governance, and release readiness + +- Security model: `docs/security.md` +- Security policy: `SECURITY.md` +- Contributing: `CONTRIBUTING.md` +- Public readiness checklist: `docs/public-readiness.md` +- Open-source boundary: `docs/open-source-boundary.md` +- Repo access control: `docs/repo-access-control.md` + +--- + +## Related systems (complementary) + +- OAuth/OIDC, IAM: identity and static authorization. +- SPIFFE/SPIRE, mTLS: workload identity/channel security. +- ZTNA: network access posture. +- API gateways/service mesh: traffic and connectivity controls. + +TTP adds execution-time behavioral trust decisions on top of these layers. + +--- + +## Project status + +- Spec: `v1.0` (active development) +- TypeScript SDK: present +- Python/Go SDKs: planned + +See `docs/roadmap.md`. + +--- + +## License + +Apache License 2.0. See `LICENSE`. + See `spec/`, `profiles/`, and `examples/` for normative docs, profile mappings, and test vectors. diff --git a/docs/getting-started.md b/docs/getting-started.md index 4fa1608..2adc80e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -2,31 +2,58 @@ This guide gives a fast path from zero to first protected action, then helps teams choose the right adoption path. -## Quickstart (Simple Path) +## Quickstart: First Trust Gate -1. Run the Trust Authority using the reference implementation. -2. Register one agent and one issuer via admin endpoints. -3. Submit receipts from the issuer as agent actions occur. -4. Request a trust token from the agent. -5. Verify the token in your service and enforce `minScore`. +Run the dependency-free local demo: -Use full commands and setup details in [integration-guide.md](integration-guide.md). +```bash +npm run demo +``` + +The demo shows the core TTP control loop: + +1. A trusted build action receives `PERMIT`. +2. A production deploy receives `STEP_UP`. +3. A revoked workload receives `DENY`. +4. Each decision produces an execution receipt with a chain hash. + +This is the fastest way to see the platform intent: TTP is a runtime trust gate for protected actions, not a replacement for identity, CI, API gateways, or policy engines. + +## Next: Wire A Real Boundary + +After the demo, choose one protected action in your system: + +- a production deploy +- a privileged tool call +- a customer-impacting agent action +- a write operation against sensitive data +- a high-risk workflow step + +Then add TTP at that boundary: + +1. Define the subject, action, resource, and parameter hash. +2. Attach at least one issuer that can observe recent behavior. +3. Resolve the trust route before execution. +4. Enforce `PERMIT`, `DENY`, `STEP_UP`, `THROTTLE`, or `CONSTRAIN`. +5. Store the execution receipt for audit and incident review. + +Use full setup details in [integration-guide.md](integration-guide.md). --- ## Integration Paths (Choose One) -### Path A — Agent Builder +### Path A - Agent Builder - Integrate `TTPClient` in agent runtime. - Request short-lived, domain-scoped trust tokens. - Pass `X-TTP-Token` to protected downstream services. -### Path B — Service/API Owner +### Path B - Service/API Owner - Add TTP middleware or manual verification. - Configure per-route `domain` and `minScore`. - Choose risk-appropriate fallback strategy. -### Path C — Platform/Security Operator +### Path C - Platform/Security Operator - Operate Trust Authority and issuer registry. - Register agents and issuers. - Manage trust thresholds, domain boundaries, and quarantine policy. @@ -37,10 +64,10 @@ Use full commands and setup details in [integration-guide.md](integration-guide. Teams can adopt incrementally: -1. **Network Core Operator** — runs Trust Authority and governance. -2. **Issuer Operator** — submits signed behavioral evidence. -3. **Verifier / Service Owner** — enforces trust at action boundaries. -4. **Agent Builder** — makes agents token-aware. +1. **Network Core Operator** - runs Trust Authority and governance. +2. **Issuer Operator** - submits signed behavioral evidence. +3. **Verifier / Service Owner** - enforces trust at action boundaries. +4. **Agent Builder** - makes agents token-aware. Suggested starts: - Enterprise platform teams: Core + Verifier diff --git a/docs/integration-guide.md b/docs/integration-guide.md index abf0255..57af6c4 100644 --- a/docs/integration-guide.md +++ b/docs/integration-guide.md @@ -8,7 +8,7 @@ This guide walks through integrating TTP into your services and agent infrastruc - A running Trust Authority (self-hosted or managed). See [reference-implementations/trust-authority](../reference-implementations/trust-authority/). - At least one registered issuer observing your agent. -- The Trust Authority's public key (available at `GET /authority/.well-known/ttp-keys`). +- The Trust Authority's public key (available at `GET /.well-known/ttp-keys`). --- @@ -16,10 +16,15 @@ This guide walks through integrating TTP into your services and agent infrastruc ### Step 1 — Install the SDK +The TypeScript SDK lives in this repository under `sdk/typescript`. The intended package name is `@ttp/sdk`, but it is not yet published to npm. Until publication, treat this section as the stable integration shape and use the local demo for a runnable first pass. + ```bash +# Once published: npm install @ttp/sdk ``` +The examples below use the intended stable import path. + ### Step 2 — Initialize the Client ```typescript @@ -249,30 +254,38 @@ function scoreRequest(req: express.Request, res: express.Response, latencyMs: nu } ``` -See [reference-implementations/issuers](../reference-implementations/issuers/) for a full production-ready issuer. +See [reference-implementations/issuers](../reference-implementations/issuers/) for a fuller issuer example. --- ## Part 4: Trust Authority Setup -### Self-Hosted (Docker) +### Self-Hosted Reference Authority ```bash -# Clone the reference implementation -git clone https://github.com/blocksifr/ttp-protocol +# Clone the repository +git clone https://github.com/blocksifrdev/ttp-protocol cd ttp-protocol/reference-implementations/trust-authority +# Install and build +npm install +npm run build + # Generate keypair npm run generate-keys # Output: authority.public.pem, authority.private.pem (guard the private key) # Configure cp .env.example .env -# Edit .env: set DATABASE_URL, REDIS_URL, KEY_PATH, etc. +# Edit .env for local keys, admin credentials, and network settings. -# Start with Docker -docker-compose up -d +# Start the reference authority +npm start +``` + +In a separate shell, register an issuer and agent: +```bash # Register an issuer curl -X POST http://localhost:3000/v1/admin/issuers \ -H "Authorization: Bearer $ADMIN_KEY" \ diff --git a/docs/public-readiness.md b/docs/public-readiness.md index 455e4ed..13ce3a2 100644 --- a/docs/public-readiness.md +++ b/docs/public-readiness.md @@ -4,14 +4,19 @@ This checklist is used to decide whether TTP is ready for a public launch. ## Current Assessment -**Status:** Almost ready, with a short pre-launch hardening list. +**Status:** Adoption-ready for early technical evaluators; not yet ready for a broad public launch. + +The repo now has a dependency-free local demo that shows the central value proposition: a protected action can be permitted, stepped up, or denied with an execution receipt. The remaining launch gates are mostly packaging, CI, and production-readiness polish. ## Release Gates ### 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. +- [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. ### 2) Documentation Quality @@ -19,7 +24,9 @@ This checklist is used to decide whether TTP is ready for a public launch. - [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] 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 @@ -32,12 +39,13 @@ 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. +- [x] Dependency-free resolver/routing demo exists for first evaluation. - [ ] Add persistent-storage guidance for production-like deployments in a dedicated operator runbook section. ### 5) Repo Hygiene - [x] Core docs references resolve (roadmap, guides, contributing). -- [ ] Add CI badge/status in README once workflow is live. +- [ ] Add CI badge/status in README once workflow is live and passing. - [x] CODEOWNERS exists for protocol/security/runtime critical paths. ### 6) Open-Source Boundary Integrity @@ -48,10 +56,11 @@ This checklist is used to decide whether TTP is ready for a public launch. ## Recommended Pre-Public Action Plan (Fast) -1. Add CI workflow (build + test + markdown/link checks). -2. Enforce branch protection + required checks in repository settings. -3. Add one smoke-test script for core Trust Authority endpoints. -4. Cut a tagged pre-release (`v1.0.0-rc1`) with changelog. -5. Run open-source boundary audit against `docs/open-source-boundary.md`. +1. Publish or explicitly reserve the SDK package name used in docs. +2. Extend CI to build SDK/reference packages and run markdown/link checks. +3. Enforce branch protection + required checks in repository settings. +4. Add one smoke-test script for core Trust Authority endpoints. +5. Cut a tagged pre-release (`v1.0.0-rc1`) with changelog. +6. Run open-source boundary audit against `docs/open-source-boundary.md`. -If those are done, the repo is in strong shape for public launch. +If those are done, the repo is in strong shape for a broader public launch. diff --git a/examples/basic-agent/index.ts b/examples/basic-agent/index.ts index 2a4e591..d8652f3 100644 --- a/examples/basic-agent/index.ts +++ b/examples/basic-agent/index.ts @@ -5,20 +5,20 @@ * * To run this example: * 1. Start the Trust Authority: cd reference-implementations/trust-authority && npm run dev - * 2. Install dependencies: npm install @ttp/sdk + * 2. Install dependencies from this repo until the SDK is published: npm install ./sdk/typescript * 3. Run: ts-node examples/basic-agent/index.ts */ import { TTPClient, TTPUnavailableError } from "@ttp/sdk" -// ─── Configuration ──────────────────────────────────────────────────────────── +// Configuration const AUTHORITY_URL = process.env.TTP_AUTHORITY_URL ?? "http://localhost:3000" const AGENT_ID = process.env.TTP_AGENT_ID ?? "agent-dev-001" const AGENT_API_KEY = process.env.TTP_API_KEY ?? "dev-agent-key" const SERVICE_URL = process.env.SERVICE_URL ?? "http://localhost:4000" -// ─── Initialize TTP Client ──────────────────────────────────────────────────── +// Initialize TTP Client const ttp = new TTPClient({ agentId: AGENT_ID, @@ -26,7 +26,7 @@ const ttp = new TTPClient({ authorityUrl: AUTHORITY_URL }) -// ─── Agent Logic ────────────────────────────────────────────────────────────── +// Agent Logic async function run() { console.log(`[Agent] Starting — ID: ${AGENT_ID}`) diff --git a/examples/local-trust-gate-demo.mjs b/examples/local-trust-gate-demo.mjs new file mode 100644 index 0000000..03308cb --- /dev/null +++ b/examples/local-trust-gate-demo.mjs @@ -0,0 +1,117 @@ +import { + computeBindingHash, + createExecutionReceipt, + resolveTrustRoute +} from '../packages/trust-routing-engine/src/index.js' + +const timestamp = new Date().toISOString() + +function executionRequest(overrides = {}) { + const base = { + subject: 'agent://retention-worker', + action: 'deploy.production', + resource: 'github:blocksifrdev/ttp-protocol/actions/deploy', + context: { + environment: 'production' + }, + attestationRef: 'att://gateway/recent-behavior', + requestedBy: 'github-actions', + paramsHash: 'sha256:deploy-plan-42', + timestamp, + delegationHopCount: 0, + ...overrides + } + + return { + ...base, + bindingHash: computeBindingHash({ + subject: base.subject, + action: base.action, + resource: base.resource, + paramsHash: base.paramsHash, + timestampBucket: base.timestamp.slice(0, 16) + }) + } +} + +function routeCandidate(overrides = {}) { + return { + issuerType: 'behavioral', + issuerId: 'issuer://ci-runtime', + proofRef: 'proof://ci-runtime/last-5m', + trustScore: 0.94, + lastVerifiedAt: new Date(Date.now() - 30_000).toISOString(), + freshnessSeconds: 120, + revoked: false, + delegationAllowed: true, + maxHops: 2, + currentHopCount: 0, + grantId: 'grant://production-deploy', + minTrustScore: 0.72, + requiresStepUp: false, + action: 'deploy.production', + environmentConstraints: { + environment: 'production' + }, + ...overrides + } +} + +const scenarios = [ + { + name: 'PERMIT trusted build action', + request: executionRequest({ + action: 'build.run', + resource: 'github:blocksifrdev/ttp-protocol/actions/build' + }), + candidates: [ + routeCandidate({ + action: 'build.run', + grantId: 'grant://ci-build', + requiresStepUp: false + }) + ] + }, + { + name: 'STEP_UP production deploy', + request: executionRequest(), + candidates: [ + routeCandidate({ + requiresStepUp: true + }) + ] + }, + { + name: 'DENY revoked workload', + request: executionRequest({ + subject: 'agent://compromised-worker' + }), + candidates: [ + routeCandidate({ + revoked: true + }) + ] + } +] + +let priorReceiptHash = '' + +for (const scenario of scenarios) { + const decision = resolveTrustRoute({ + request: scenario.request, + candidates: scenario.candidates + }) + const receipt = createExecutionReceipt({ + request: scenario.request, + decision, + priorReceiptHash + }) + priorReceiptHash = receipt.chainHash + + console.log(`\n${scenario.name}`) + console.log(`decision: ${decision.decision}`) + console.log(`reason: ${decision.reasonCodes.join(', ')}`) + console.log(`trust: ${decision.trustScoreAtDecision.toFixed(3)} (${decision.trustZone})`) + console.log(`receipt: ${receipt.receiptId}`) + console.log(`chain: ${receipt.chainHash.slice(0, 16)}...`) +} diff --git a/package.json b/package.json index 7e24b72..45b52ff 100644 --- a/package.json +++ b/package.json @@ -20,16 +20,7 @@ "./errors": "./src/errors.mjs" }, "scripts": { - "test": "npm run test:ttp && npm run test:contracts && npm run test:trust-routing && npm run test:runtime-authority-gate", - "test:ttp": "node --test tests/*.test.mjs", - "test:contracts": "node tools/validate-contracts.mjs", - "test:trust-routing": "node --test packages/trust-routing-engine/tests/*.test.mjs", - "test:runtime-authority-gate": "node --test reference-implementations/runtime-authority-gate/*.test.mjs", - "lint": "node --check src/*.mjs" - }, - "repository": { - "type": "git", - "url": "https://github.com/blocksifrdev/ttp-protocol.git" - }, - "keywords": ["trust", "governance", "agentic", "execution", "protocol", "attestation", "decay"] + "demo": "node examples/local-trust-gate-demo.mjs", + "test:trust-routing": "node --test packages/trust-routing-engine/tests/*.test.mjs" + } }