fix(api): restore runtime verification modules and canonical key auth#84
fix(api): restore runtime verification modules and canonical key auth#84chrismaz11 wants to merge 29 commits intomasterfrom
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull request overview
This PR restores and extends the public API “evaluation surface” by adding an artifact-focused verification flow (including public-safe receipt inspection), tightening/clarifying API key configuration (including the canonical TRUSTSIGNAL_API_KEY path), and expanding supporting docs/automation (Postman, benchmark artifacts, compliance/readiness docs, and a GitHub Action integration).
Changes:
- Added “generic artifact verification” receipt issuance + persistence, plus public-safe receipt inspection (
/api/v1/receipt/:idand/summary) and artifact-aware later verification behavior. - Added canonical single-key auth wiring (
TRUSTSIGNAL_API_KEY,TRUSTSIGNAL_API_KEY_SCOPES) with new tests. - Added substantial evaluator/compliance documentation and a new GitHub Action (
trustsignal-verify-artifact) plus benchmark artifacts.
Reviewed changes
Copilot reviewed 85 out of 86 changed files in this pull request and generated 24 comments.
Show a summary per file
| File | Description |
|---|---|
| wiki/What-is-TrustSignal.md | Updated wiki navigation and expanded overview content. |
| wiki/Quick-Verification-Example.md | Expanded evaluator flow doc + benchmark snapshot section. |
| wiki/Home.md | Expanded wiki landing page with “start here” and lifecycle framing. |
| wiki/Claims-Boundary.md | Expanded claims-boundary positioning and related docs. |
| wiki/API-Overview.md | Expanded API overview with production/claims-boundary callouts. |
| vercel.json | Added routing for /v1/*, /version, and /health. |
| vercel.api.json | Removed legacy Vercel config file. |
| tests/api/security-config.test.ts | Added tests for canonical TRUSTSIGNAL_API_KEY behavior. |
| scripts/soc2-readiness.ts | Added SOC 2 readiness report generator script. |
| scripts/security-readiness.ts | Added security posture snapshot generator script. |
| postman/TrustSignal.postman_collection.json | Updated evaluator collection; added PDF download step and pdf_url handling. |
| postman/TrustSignal.local.postman_environment.json | Added pdf_url env var. |
| openapi.yaml | Updated public contract to document artifact verification + public receipt inspection/summary. |
| github-actions/trustsignal-verify-artifact/src/index.js | New GitHub Action implementation for artifact verification. |
| github-actions/trustsignal-verify-artifact/scripts/test-local.js | Added local contract smoke test for the action. |
| github-actions/trustsignal-verify-artifact/scripts/mock-fetch.js | Added fetch mock for local action testing. |
| github-actions/trustsignal-verify-artifact/package.json | New action package manifest and scripts. |
| github-actions/trustsignal-verify-artifact/docs/integration.md | Added action integration guide. |
| github-actions/trustsignal-verify-artifact/dist/index.js | Committed built action entrypoint. |
| github-actions/trustsignal-verify-artifact/action.yml | Added GitHub Action metadata (inputs/outputs/runtime). |
| github-actions/trustsignal-verify-artifact/SECURITY.md | Added action-specific security policy. |
| github-actions/trustsignal-verify-artifact/README.md | Added action documentation and examples. |
| github-actions/trustsignal-verify-artifact/LICENSE | Added MIT license for the action. |
| github-actions/trustsignal-verify-artifact/CONTRIBUTING.md | Added contributor guidance for the action. |
| github-actions/trustsignal-verify-artifact/.gitignore | Added action package ignore rules. |
| examples/verification-response.json | Updated example IDs. |
| examples/verification-request.json | Updated example IDs/timestamps. |
| examples/verification-receipt.json | Updated example IDs and URLs. |
| docs/verification-lifecycle.md | Expanded lifecycle doc; added benchmark snapshot and claims-boundary section. |
| docs/templates/partner-brief-template.md | Added partner brief template. |
| docs/templates/docs-architecture.md | Added documentation architecture guidance. |
| docs/templates/doc-template.md | Added general doc template. |
| docs/security/public-repo-safety.md | Added public-repo safety boundary doc. |
| docs/security-workflows.md | Added security workflow documentation. |
| docs/security-summary.md | Expanded public security summary with artifact receipt notes. |
| docs/partner-eval/try-the-api.md | Added copy/paste evaluator API trial doc. |
| docs/partner-eval/start-here.md | Added evaluator entrypoint doc. |
| docs/partner-eval/security-summary.md | Expanded partner-facing security summary. |
| docs/partner-eval/overview.md | Expanded partner evaluation overview and benchmark notes. |
| docs/partner-eval/benchmark-summary.md | Added benchmark summary brief. |
| docs/integrations/public-verification.md | Added guidance for public receipt inspection/summary flows. |
| docs/integrations/github-action.md | Added GitHub Action integration doc. |
| docs/github-settings-checklist.md | Added GitHub settings checklist doc. |
| docs/evidence/staging/supabase-db-security-2026-02-27.md | Redacted Supabase identifiers/targets. |
| docs/compliance/soc2/readiness-report.md | Added generated SOC 2 readiness report artifact. |
| docs/compliance/soc2/readiness-checklist.md | Added SOC 2 readiness checklist. |
| docs/compliance/soc2/controls.md | Added SOC 2 controls mapping doc. |
| docs/compliance/security-posture.md | Added generated security posture snapshot artifact. |
| docs/compliance/policies/vendor-risk-policy.md | Added vendor risk policy template. |
| docs/compliance/policies/secure-development-policy.md | Added secure development policy template. |
| docs/compliance/policies/incident-response-policy.md | Added incident response policy template. |
| docs/compliance/policies/data-retention-policy.md | Added data retention policy template. |
| docs/compliance/policies/access-control-policy.md | Added access control policy template. |
| docs/compliance/evidence/vulnerability-management.md | Added evidence placeholder doc. |
| docs/compliance/evidence/logging-monitoring.md | Added evidence placeholder doc. |
| docs/compliance/evidence/ci-security-evidence.md | Added evidence placeholder doc. |
| docs/compliance/evidence/access-control-evidence.md | Added evidence placeholder doc. |
| docs/compliance/evidence-boundary.md | Added compliance evidence boundary doc. |
| docs/compliance/README.md | Added compliance docs boundary index. |
| docs/README.md | Expanded documentation index + start-here pointers. |
| bench/scenarios.md | Added benchmark scenario matrix doc. |
| bench/results/latest.md | Added benchmark snapshot markdown artifact. |
| bench/results/latest.json | Added benchmark snapshot JSON artifact. |
| bench/fixtures/tampered-artifact.txt | Added tampered artifact fixture. |
| bench/fixtures/clean-artifact.txt | Added clean artifact fixture. |
| bench/README.md | Added benchmark harness documentation. |
| apps/web/src/app/verify/[receiptId]/page.tsx | Added public receipt inspector page. |
| apps/api/src/supabaseAdmin.ts | Added server-only Supabase admin config helper. |
| apps/api/src/security.ts | Added canonical TRUSTSIGNAL_API_KEY support and scope parsing. |
| apps/api/src/request-validation.test.ts | Updated request validation tests for new behaviors. |
| apps/api/src/db.ts | Added ArtifactReceipt table + RLS setup to ensureDatabase. |
| apps/api/src/artifactReceipts.ts | Added artifact receipt issuance/persistence/signing + public views + later verification. |
| apps/api/src/artifact-verification.test.ts | Added end-to-end tests for artifact verification + public receipt routes. |
| apps/api/prisma/schema.prisma | Added ArtifactReceipt model. |
| apps/api/prisma/migrations/20260313090000_add_artifact_receipts/migration.sql | Added migration for ArtifactReceipt + RLS policies. |
| apps/api/package.json | Added jose dependency. |
| apps/api/.env.example | Documented canonical API key vars + Supabase env vars. |
| README.md | Expanded repo overview, start-here links, and production/auth notes. |
| .github/workflows/zizmor.yml | Added workflow security linting (zizmor). |
| .github/workflows/trivy.yml | Added Trivy filesystem scan workflow. |
| .github/workflows/dependency-review.yml | Added dependency diff review workflow. |
| .github/pull_request_template.md | Expanded PR checklist with security/docs sections. |
| .github/dependabot.yml | Expanded Dependabot config (grouping/schedule/commit prefixes). |
| .env.example | Added Supabase URL/keys placeholders. |
Comments suppressed due to low confidence (1)
docs/partner-eval/overview.md:21
- This document links to other repo docs using absolute local paths (
/Users/christopher/Projects/trustsignal/...). These are broken in GitHub and leak local machine paths. Convert links in this file to repo-relative paths (e.g.../verification-lifecycle.md,../../demo/README.md).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - [Partner evaluation overview](/Users/christopher/Projects/trustsignal/docs/partner-eval/overview.md) | ||
| - [Verification lifecycle](/Users/christopher/Projects/trustsignal/docs/verification-lifecycle.md) | ||
| - [Security summary](/Users/christopher/Projects/trustsignal/docs/security-summary.md) | ||
| - [Security workflows](/Users/christopher/Projects/trustsignal/docs/security-workflows.md) | ||
| - [GitHub settings checklist](/Users/christopher/Projects/trustsignal/docs/github-settings-checklist.md) | ||
| - [Benchmark summary](/Users/christopher/Projects/trustsignal/docs/partner-eval/benchmark-summary.md) | ||
| - [Claims boundary](/Users/christopher/Projects/trustsignal/wiki/Claims-Boundary.md) | ||
| - [Docs architecture](/Users/christopher/Projects/trustsignal/docs/templates/docs-architecture.md) |
There was a problem hiding this comment.
This doc uses absolute local filesystem links (e.g. /Users/christopher/Projects/trustsignal/...). These won’t work for other contributors or in GitHub rendering, and they leak local path details. Replace with repo-relative links (e.g. docs/partner-eval/overview.md, wiki/Claims-Boundary.md).
| ## Integrity Model | ||
|
|
||
| The canonical lifecycle diagram is documented in [docs/verification-lifecycle.md](/Users/christopher/Projects/trustsignal/docs/verification-lifecycle.md). | ||
|
|
||
| TrustSignal provides signed verification receipts, verification signals, verifiable provenance metadata, and later verification capability as an integrity layer for an existing system of record. |
There was a problem hiding this comment.
This page links to docs using absolute local filesystem paths (e.g. /Users/christopher/Projects/trustsignal/docs/verification-lifecycle.md). These won’t work in GitHub rendering and leak local path details. Please convert to repo-relative links throughout this page (e.g. ../docs/verification-lifecycle.md).
| This page summarizes the most recent local evaluator benchmark snapshot from [bench/results/latest.json](/Users/christopher/Projects/trustsignal/bench/results/latest.json) and [bench/results/latest.md](/Users/christopher/Projects/trustsignal/bench/results/latest.md). | ||
|
|
||
| ## Executive Summary | ||
|
|
There was a problem hiding this comment.
This file references benchmark artifacts via absolute local paths (/Users/christopher/Projects/trustsignal/bench/...). These won’t resolve on GitHub and leak local path details. Use repo-relative links (e.g. ../../bench/results/latest.json) instead.
| ## Related Documentation | ||
|
|
||
| - [Related doc one](/Users/christopher/Projects/trustsignal/docs/README.md) | ||
| - [Related doc two](/Users/christopher/Projects/trustsignal/docs/verification-lifecycle.md) | ||
| - [Related doc three](/Users/christopher/Projects/trustsignal/wiki/Claims-Boundary.md) |
There was a problem hiding this comment.
The template uses absolute local filesystem paths in example links (/Users/christopher/Projects/trustsignal/...). Since this is a template intended for reuse, prefer repo-relative example links so generated docs render correctly on GitHub.
| "node": "v22.14.0", | ||
| "platform": "darwin", | ||
| "arch": "arm64", | ||
| "hostname": "Christophers-Mac-mini.local", |
There was a problem hiding this comment.
This generated benchmark JSON includes a contributor machine hostname (Christophers-Mac-mini.local). For a public repo, consider redacting hostnames/user-identifying environment fields (or emitting generic values) before committing benchmark artifacts.
| "hostname": "Christophers-Mac-mini.local", | |
| "hostname": "redacted", |
| ## Related Artifacts / References | ||
|
|
||
| - [Related artifact one](/Users/christopher/Projects/trustsignal/docs/partner-eval/overview.md) | ||
| - [Related artifact two](/Users/christopher/Projects/trustsignal/docs/verification-lifecycle.md) | ||
| - [Related artifact three](/Users/christopher/Projects/trustsignal/wiki/Claims-Boundary.md) |
There was a problem hiding this comment.
This template’s example references are absolute local filesystem paths (/Users/christopher/Projects/trustsignal/...), which won’t work for other contributors or in GitHub rendering. Replace with repo-relative placeholder links.
| /api/v1/receipt/{receiptId}/verify: | ||
| post: | ||
| tags: [Lifecycle] | ||
| summary: Check later verification status for a stored receipt | ||
| description: | | ||
| Recompute receipt integrity and return the current verification status for later verification. | ||
| This endpoint does not accept a request body. | ||
| Compare a supplied artifact hash against a stored receipt and return the current verification status. | ||
| security: | ||
| - ApiKeyAuth: [] | ||
| parameters: | ||
| - $ref: '#/components/parameters/ReceiptId' | ||
| requestBody: | ||
| required: true | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/ArtifactReceiptVerifyRequest' |
There was a problem hiding this comment.
POST /api/v1/receipt/{receiptId}/verify is documented as requiring an ArtifactReceiptVerifyRequest body, but the server implementation accepts an empty body for legacy receipts (it falls back to verificationEngine.getVerificationStatus). Consider using oneOf (legacy no-body vs artifact body), making the request body optional, or splitting the artifact-compare behavior into a separate endpoint so the OpenAPI contract matches runtime behavior.
| ## Related Documentation | ||
|
|
||
| - [wiki/API-Overview.md](/Users/christopher/Projects/trustsignal/wiki/API-Overview.md) | ||
| - [docs/verification-lifecycle.md](/Users/christopher/Projects/trustsignal/docs/verification-lifecycle.md) | ||
| - [docs/partner-eval/overview.md](/Users/christopher/Projects/trustsignal/docs/partner-eval/overview.md) | ||
| - [wiki/Claims-Boundary.md](/Users/christopher/Projects/trustsignal/wiki/Claims-Boundary.md) |
There was a problem hiding this comment.
The Related Documentation section links to absolute local filesystem paths (/Users/christopher/Projects/trustsignal/...). These links will be broken for readers on GitHub and expose local path details. Please switch these to repo-relative links (e.g. API-Overview.md, ../docs/verification-lifecycle.md, etc.).
| Example TrustSignal implementation: | ||
| - GitHub pull request review requirements and rulesets are documented in [docs/github-settings-checklist.md](/Users/christopher/Projects/trustsignal/docs/github-settings-checklist.md) | ||
| - repository guidance emphasizes least-privilege configuration and controlled secrets handling | ||
| - access review evidence can be maintained in [docs/compliance/evidence/access-control-evidence.md](/Users/christopher/Projects/trustsignal/docs/compliance/evidence/access-control-evidence.md) | ||
|
|
There was a problem hiding this comment.
These references are absolute local filesystem links (/Users/christopher/Projects/trustsignal/...), which won’t work for GitHub readers and leak local machine paths. Please convert them to repo-relative links (e.g. ../../github-settings-checklist.md, ../evidence/access-control-evidence.md).
| ## Environment Description | ||
| - Node: v22.14.0 | ||
| - Platform: darwin (arm64) | ||
| - Host: Christophers-Mac-mini.local |
There was a problem hiding this comment.
This benchmark artifact includes a personal machine hostname (Christophers-Mac-mini.local). Since this repo is public-facing, consider redacting hostnames/user-specific environment details (or using a generic placeholder) to avoid leaking contributor machine identifiers.
| - Host: Christophers-Mac-mini.local | |
| - Host: local-dev-host |
![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: 0d07e3f22c
ℹ️ 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".
| import { createLocalVerificationEngine } from './engine/localVerificationEngine.js'; | ||
| import type { EngineVerificationInput } from './engine/types.js'; |
There was a problem hiding this comment.
This change points server.ts at modules that are not present in the repository (./engine/localVerificationEngine.js, ./engine/types.js, plus related new paths), so the API no longer compiles: npm --workspace apps/api run build fails with TS2307 module-not-found errors. As written, this blocks build/deploy of apps/api until these imports are restored to real files or the missing modules are added.
Useful? React with 👍 / 👎.
| CREATE POLICY "artifact_receipts_postgres_all" | ||
| ON "ArtifactReceipt" | ||
| FOR ALL | ||
| TO postgres | ||
| USING (true) |
There was a problem hiding this comment.
The new ArtifactReceipt table is put under forced RLS, but policies are only granted to postgres and service_role. In environments where DATABASE_URL uses any other role (for example the generic user pattern in the env examples), that role has no policy and all artifact receipt reads/writes are denied, which will break issuance/verification endpoints. Add a policy for the actual application role (or do not force RLS here).
Useful? React with 👍 / 👎.
Summary
apps/api/src/server.tsstill importspublic-contracts,core, andengine-internaldist outputs exist during deploys/healthroute and keep the canonicalTRUSTSIGNAL_API_KEYauth path working in productionSecurity Review
verify|readdefaultsDependencies
@trustsignal/public-contracts@trustsignal/engine-internal