diff --git a/README.md b/README.md index 758f2ea..e1eccee 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Website: https://trustsignal.dev -TrustSignal is evidence integrity infrastructure for existing workflows. It acts as an integrity layer that returns signed verification receipts, verification signals, verifiable provenance metadata, and later verification capability without replacing the upstream system of record. +TrustSignal is evidence-integrity infrastructure that operates as an integrity layer for existing workflows. It issues **signed verification receipts**, verification signals, and verifiable provenance metadata — enabling **later verification** and auditability without replacing the upstream system of record. TrustSignal’s public integration boundary intentionally avoids exposing signing internals or proof internals and focuses on returning durable verification artifacts that integrators can store alongside their own evidence. ## Problem diff --git a/docs/public-private-boundary.md b/docs/public-private-boundary.md index 0e190eb..8ea9bbc 100644 --- a/docs/public-private-boundary.md +++ b/docs/public-private-boundary.md @@ -1,34 +1,22 @@ # Public / Private Boundary -This repository is currently a single codebase, but it is being organized so a -future split into: +This codebase is organized to make it straightforward to operate a **public integration layer** and a **private verification engine** with a narrow engine interface. -- a public integration-layer repository -- a private verification-engine repository or service +## Public integration layer +The public integration layer contains API, SDK, public docs, and public route/middleware code. It is responsible for: +- Authentication and authorization +- Request validation and tenant scoping +- Rate limiting and exposure controls +- Response shaping and partner-facing contracts -is straightforward. +Public code must not import or orchestrate engine-private helpers or signing internals. -## Public-Oriented Surfaces +## Private verification engine +The private verification engine owns proof orchestration, signing internals, revocation/anchoring workflows, ZKP/circuits, and compliance evaluation. Engine code is intentionally internal; integrators should depend on the API contract and receipt model rather than internal implementation details. -These directories are intended to remain part of the public integration layer: - -- `api/` -- `sdk/` -- `docs/` -- `security/` -- `apps/web/` -- `apps/watcher/` -- `packages/public-contracts/` -- public-facing route, middleware, and response-mapping code in `apps/api/src/` - -Public code should own: - -- authentication and authorization -- request validation -- tenant scoping -- rate limiting -- idempotency and request lifecycle concerns -- response shaping and partner-facing contracts +## Guardrails +- Route handlers must call the narrow engine interface and must not import engine internals directly. +- Public gateway code uses import restrictions and checks (e.g., `npm run check:api-boundary`) to prevent accidental leakage of private engine code. ## Private Engine Candidates diff --git a/docs/security-summary.md b/docs/security-summary.md index a45965c..eeb6447 100644 --- a/docs/security-summary.md +++ b/docs/security-summary.md @@ -1,18 +1,15 @@ # TrustSignal Public Security Summary -> TrustSignal is evidence integrity infrastructure for signed verification receipts and later verification. +TrustSignal provides a public-safe security posture at the integration boundary: scoped API authentication, request validation and rate-limiting at the API gateway, server-side persistence of artifact receipts, fail-closed production defaults, and a claims boundary that avoids exposing signing internals or proof internals. -Short description: -This public-safe security summary explains the TrustSignal integration boundary, security posture, and claims boundary without exposing non-public implementation details. - -Audience: -- partner security reviewers -- evaluators -- developers +## Audience +- Partner security reviewers +- Evaluators +- Developers ## Problem / Context -Partners and evaluators need a public-safe security summary that explains the attack surface without exposing internal implementation details. In high-stakes workflows, evidence can be challenged after collection through tampered evidence, provenance loss, artifact substitution, or stale records that are no longer independently verifiable. +Partners and evaluators need a public-safe security summary that explains the attack surface and the integration-facing guarantees without exposing non-public implementation details. ## Integrity Model