chore(docs): standardize canonical messaging and claims boundary#86
chore(docs): standardize canonical messaging and claims boundary#86chrismaz11 wants to merge 1 commit intomasterfrom
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
chrismaz11
force-pushed
the
docs/standardize-messaging
branch
from
34c448b to
6c0f9bf
Compare
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 34c448be82
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
README.md
Outdated
| curl -X POST "http://localhost:3001/api/v1/verify" \ | ||
| -H "Content-Type: application/json" \ | ||
| -H "x-api-key: $TRUSTSIGNAL_API_KEY" \ | ||
| -H "Authorization: Bearer $TRUSTSIGNAL_ACCESS_TOKEN" \ |
There was a problem hiding this comment.
The updated quickstart now sends Authorization: Bearer $TRUSTSIGNAL_ACCESS_TOKEN, but the /api/v1/* routes still enforce x-api-key auth via requireApiKeyScope (see apps/api/src/security.ts), including POST /api/v1/verify and receipt routes in apps/api/src/server.ts. Following this README command will return 401 Unauthorized: missing x-api-key, so the primary evaluation flow is currently broken for readers.
Useful? React with 👍 / 👎.
README.md
Outdated
|
|
||
| The current partner-facing lifecycle in this repository is: | ||
|
|
||
| - `POST /api/v1/clients` |
There was a problem hiding this comment.
This section now describes POST /api/v1/clients (and subsequent auth/token endpoints) as part of the current partner-facing lifecycle, but those handlers are not registered in apps/api/src/server.ts where /api/v1 routes are defined. Publishing non-existent routes as current behavior sends integrators to 404s and makes the onboarding contract inaccurate.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Normalize public-facing messaging around TrustSignal’s integration boundary, security posture, and public/private claims boundary across top-level docs.
Changes:
- Updates
README.mdproduct statement and expands the documented “partner-facing lifecycle” and auth guidance. - Rewrites the intro + audience framing in
docs/security-summary.md. - Reframes
docs/public-private-boundary.mdto describe a public integration layer vs private verification engine and adds guardrails language.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/security-summary.md | Updates the public-safe posture/claims-boundary introduction and audience section. |
| docs/public-private-boundary.md | Rewords the public/private split narrative and adds guardrails wording about boundary enforcement. |
| README.md | Updates canonical product messaging and significantly expands API/auth flow documentation and examples. |
Comments suppressed due to low confidence (5)
README.md:150
- This section references
TRUSTSIGNAL_REPLAY_REDIS_URL, assertion replay protection, and a fallback "database nonce table", but there is no corresponding configuration/implementation in the repo. If this is planned future behavior, it should be marked as such and moved out of the main quickstart flow; otherwise it should be removed to avoid implying security properties the current implementation doesn’t provide.
- TrustSignal can fit behind an existing workflow without replacing the system of record
- the API returns signed verification receipts and verification signals in one flow
- later verification is explicit and separate from initial receipt issuance
README.md:220
- This bullet switches production requirements from API keys/JWT to "machine-client registration" and "access-token signing", but the current API implementation and OpenAPI specs use scoped
x-api-keyauth and do not expose any client-registration/token-minting flows. To keep the README accurate, either revert this to the actual auth mechanism or land the corresponding API/auth work in the same release.
TrustSignal does not provide:
- legal determinations
README.md:246
- The README now claims browser Authorization Code + PKCE is implemented and lists it as a public-facing security property, but there are no
/api/v1/auth/*or/api/v1/oauth/*routes in the API server and no such paths in the OpenAPI specs. This should be removed or clearly marked as future/planned so the repo doesn't overstate its current security posture.
### Recommended Starting Points by Background
- **Evaluator / non-engineer** — Run `npm run demo` and read [docs/partner-eval/start-here.md](docs/partner-eval/start-here.md)
README.md:87
- README now documents client registration, OAuth, token, and introspection endpoints (e.g.,
/api/v1/clients,/api/v1/token,/api/v1/introspect,/api/v1/auth/*,/api/v1/oauth/authorize*), but these routes are not present inapps/api/src/server.tsand they are not defined in the OpenAPI specs (openapi.yaml/apps/api/openapi.json). As written, this will mislead integrators; either remove these endpoints from the lifecycle list or land the corresponding API/OpenAPI changes first.
- `POST /api/v1/verify`
- `GET /api/v1/receipt/:receiptId`
- `GET /api/v1/receipt/:receiptId/pdf`
- `POST /api/v1/receipt/:receiptId/verify`
- `POST /api/v1/receipt/:receiptId/revoke`
- `POST /api/v1/anchor/:receiptId`
- `GET /api/v1/receipts`
## What You Will See
The evaluator path is designed to show the core value before full production integration work:
- artifact intake through the public API
README.md:176
- The curl examples were updated to use
Authorization: Bearer $TRUSTSIGNAL_ACCESS_TOKEN, but the API currently authenticates viax-api-key(seerequireApiKeyScope(...)inapps/api/src/security.tsand all/api/v1/*routes inapps/api/src/server.ts). Unless bearer-token auth is implemented for these routes, the README examples should continue to usex-api-key(or the code/OpenAPI must be updated to accept bearer tokens).
## Integration Boundary Notes
The local evaluator path is intentionally constrained. Local development defaults are a deliberate evaluator and development path, and they fail closed where production trust assumptions are not satisfied.
Authentication is `x-api-key` with scoped access. Revocation additionally requires issuer authorization headers: `x-issuer-id`, `x-signature-timestamp`, and `x-issuer-signature`.
The repository also still includes a legacy JWT-authenticated `/v1/*` surface used by the current JavaScript SDK:
- `POST /v1/verify-bundle`
- `GET /v1/status/:bundleId`
- `POST /v1/revoke`
## Production Deployment Requirements
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - 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. |
There was a problem hiding this comment.
The doc claims a npm run check:api-boundary guardrail, but there is no check:api-boundary script anywhere in the repo (root package.json and apps/* package.json files). This makes the stated enforcement mechanism misleading; either add the script (and document where it runs) or remove/replace the reference with the actual enforced check(s).
| ## 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. |
There was a problem hiding this comment.
This adds a second "## Guardrails" section near the top of the document, but the file already has an existing "## Guardrails" section later. The duplicate headings make the structure ambiguous; consider merging these guardrails into a single section or renaming one of the headings so there is a single source of truth.
Summary:
Normalize public-facing messaging and the claims boundary.
Changes:
Verification:
npm run check:api-boundaryat repo root is not defined in package.json; see notes below.Notes for reviewers: