TrustSignal-dev · chrismaz11 · Mar 12, 2026 · Mar 12, 2026 · Mar 12, 2026 · Mar 12, 2026
diff --git a/.env.example b/.env.example
@@ -5,11 +5,14 @@ ISSUER_PUBLIC_JWK_JSON='{"kty":"EC","crv":"P-256","x":"<x>","y":"<y>"}'
 DB_PATH=attestations.sqlite
 DATABASE_URL="file:./prisma/dev.db"
 # Supabase aliases for apps/api Postgres (optional)
+SUPABASE_URL=https://<project-ref>.supabase.co
+SUPABASE_SERVICE_ROLE_KEY=replace-with-server-only-service-role-key
 SUPABASE_DB_URL=postgresql://postgres.<project-ref>:[password]@aws-0-<region>.pooler.supabase.com:6543/postgres?sslmode=require
 SUPABASE_POOLER_URL=postgresql://postgres.<project-ref>:[password]@aws-0-<region>.pooler.supabase.com:6543/postgres?sslmode=require
 SUPABASE_DIRECT_URL=postgresql://postgres:[password]@db.<project-ref>.supabase.co:5432/postgres?sslmode=require
 # Optional helper if using Supabase CLI pooler URL discovery from `supabase/.temp/pooler-url`.
 SUPABASE_DB_PASSWORD=replace-with-supabase-db-password
+SUPABASE_SECRET_KEY=replace-with-server-only-secret-key
 PORT=3000
 
 # apps/api security controls

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -1,19 +1,53 @@
 version: 2
+
 updates:
   - package-ecosystem: "npm"
     directory: "/"
     schedule:
       interval: "weekly"
+      day: "monday"
+      time: "05:00"
+      timezone: "America/Chicago"
     open-pull-requests-limit: 5
+    groups:
+      npm-production:
+        dependency-type: "production"
+      npm-development:
+        dependency-type: "development"
     labels:
       - "dependencies"
       - "security"
+    commit-message:
+      prefix: "deps"
 
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
       interval: "weekly"
+      day: "monday"
+      time: "05:30"
+      timezone: "America/Chicago"
     open-pull-requests-limit: 5
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+    labels:
+      - "dependencies"
+      - "security"
+    commit-message:
+      prefix: "deps"
+
+  - package-ecosystem: "cargo"
+    directory: "/circuits/non_mem_gadget"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+      timezone: "America/Chicago"
+    open-pull-requests-limit: 3
     labels:
       - "dependencies"
       - "security"
+    commit-message:
+      prefix: "deps"
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,14 +1,33 @@
 ## Summary
 
-- Describe the change
+- Describe the change and why it is needed.
 
-## AI Disclosure
+## Change Type
 
-- [ ] AI-assisted changes are included in this PR
+- [ ] Runtime or API behavior
+- [ ] Security or repo governance
+- [ ] Workflow or CI configuration
+- [ ] Documentation or claims boundary only
+- [ ] Dependency update
 
-## Review Checklist
+## Security Review
 
-- [ ] Human review requested
-- [ ] Tests added or updated where appropriate
+- [ ] Security impact is described
 - [ ] No secrets, tokens, cookies, or raw PII were added to code, logs, fixtures, or docs
-- [ ] Security impact and remaining risks are described
+- [ ] New permissions, auth assumptions, or trust-boundary changes are called out
+- [ ] Dependency changes were reviewed for risk
+
+## Claims Boundary And Docs
+
+- [ ] Public-facing claims or evaluator docs were updated if needed
+- [ ] No unsupported claims were introduced
+
+## Validation
+
+- [ ] Human review requested
+- [ ] Tests or validation commands were run where appropriate
+- [ ] Workflow changes were reviewed for least privilege and pinned actions
+
+## AI Disclosure
+
+- [ ] AI-assisted changes are included in this PR
diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml
@@ -0,0 +1,17 @@
+name: Security / Dependency Review
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    name: Dependency diff review
+    runs-on: ubuntu-latest
+    steps:
+      - name: Dependency review
+        uses: actions/dependency-review-action@v4 # GitHub-maintained action pinned to supported major; Dependabot tracks updates.
+        with:
+          fail-on-severity: high
diff --git a/.github/workflows/trivy.yml b/.github/workflows/trivy.yml
@@ -0,0 +1,54 @@
+name: Security / Trivy Filesystem Scan
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  trivy-fs:
+    name: Trivy repository scan
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v4.1.7
+        with:
+          persist-credentials: false
+
+      - name: Run Trivy filesystem scan
+        uses: aquasecurity/trivy-action@0.34.0
+        with:
+          scan-type: fs
+          scan-ref: .
+          scanners: vuln
+          vuln-type: os,library
+          severity: HIGH,CRITICAL
+          ignore-unfixed: true
+          hide-progress: true
+          format: sarif
+          output: trivy-results.sarif
+          limit-severities-for-sarif: true
+          exit-code: "0"
+          skip-dirs: node_modules,.next,dist,coverage,.git
+
+      - name: Upload Trivy SARIF
+        if: always() && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false)
+        uses: github/codeql-action/upload-sarif@v4 # GitHub-maintained action pinned to supported major; Dependabot tracks updates.
+        with:
+          sarif_file: trivy-results.sarif
+
+      - name: Summarize Trivy mode
+        if: always()
+        run: |
+          {
+            echo "## Trivy filesystem scan"
+            echo ""
+            echo "- Mode: advisory"
+            echo "- Scope: filesystem vulnerability scan with HIGH/CRITICAL severity only"
+            echo "- Notes: ignores unfixed issues and uploads SARIF for review in Security/code scanning when token permissions allow it"
+          } >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/zizmor.yml b/.github/workflows/zizmor.yml
@@ -0,0 +1,42 @@
+name: Security / zizmor Workflow Audit
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/**"
+  push:
+    paths:
+      - ".github/workflows/**"
+
+permissions: {}
+
+jobs:
+  zizmor:
+    name: zizmor advisory audit
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v4.1.7
+        with:
+          persist-credentials: false
+
+      - name: Run zizmor
+        continue-on-error: true
+        uses: zizmorcore/zizmor-action@e639db99335bc9038abc0e066dfcd72e23d26fb4 # v0.3.0
+        with:
+          advanced-security: false
+          annotations: true
+
+      - name: Summarize zizmor mode
+        if: always()
+        run: |
+          {
+            echo "## zizmor workflow audit"
+            echo ""
+            echo "- Mode: advisory"
+            echo "- Scope: GitHub Actions workflow security linting"
+            echo "- Notes: findings are annotated in the run and should be reviewed before merging workflow changes"
+          } >> "$GITHUB_STEP_SUMMARY"
diff --git a/README.md b/README.md
@@ -10,6 +10,24 @@ 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.
 
+Short description:
+This repository is the main TrustSignal documentation and implementation surface for public evaluation, existing workflow integration, and signed verification receipts with later verification.
+
+Audience:
+- evaluators
+- developers
+- partner reviewers
+
+## Start Here
+
+- [Documentation index](docs/README.md)
+- [Partner evaluation overview](docs/partner-eval/overview.md)
+- [Verification lifecycle](docs/verification-lifecycle.md)
+- [Security workflows](docs/security-workflows.md)
+- [GitHub settings checklist](docs/github-settings-checklist.md)
+- [API overview](wiki/API-Overview.md)
+- [Claims boundary](wiki/Claims-Boundary.md)
+
 ## Problem
 
 High-stakes document and evidence workflows create an attack surface after collection, not just at intake. Once an artifact has been uploaded, reviewed, or approved, downstream teams still face risks such as tampered evidence, provenance loss, artifact substitution, and stale evidence that can no longer be verified later.
@@ -18,7 +36,7 @@ Those risks matter in audit, compliance, partner-review, and trust-sensitive wor
 
 ## Verification Lifecycle
 
-The canonical lifecycle diagram and trust-boundary view are documented in [docs/verification-lifecycle.md](/Users/christopher/Projects/trustsignal/docs/verification-lifecycle.md).
+The canonical lifecycle diagram and trust-boundary view are documented in [docs/verification-lifecycle.md](docs/verification-lifecycle.md).
 
 TrustSignal accepts a verification request, returns verification signals, issues a signed verification receipt, and supports later verification against stored receipt state so downstream teams can detect artifact tampering, evidence provenance loss, or stale records during audit review.
 
@@ -27,7 +45,6 @@ TrustSignal accepts a verification request, returns verification signals, issues
 The fastest evaluator path is the local 5-minute developer trial:
 
 TrustSignal provides:
-
 - signed verification receipts
 - verification signals
 - verifiable provenance metadata
@@ -47,17 +64,17 @@ It shows the full lifecycle in one run:
 4. later verification
 5. tampered artifact mismatch detection
 
-See [demo/README.md](/Users/christopher/Projects/trustsignal/demo/README.md).
+See [demo/README.md](demo/README.md).
 
 ## Integration Model
 
 Start here if you are evaluating the public verification lifecycle:
 
-- [Evaluator quickstart](/Users/christopher/Projects/trustsignal/docs/partner-eval/quickstart.md)
-- [API playground](/Users/christopher/Projects/trustsignal/docs/partner-eval/api-playground.md)
-- [OpenAPI contract](/Users/christopher/Projects/trustsignal/openapi.yaml)
-- [Postman collection](/Users/christopher/Projects/trustsignal/postman/TrustSignal.postman_collection.json)
-- [Postman local environment](/Users/christopher/Projects/trustsignal/postman/TrustSignal.local.postman_environment.json)
+- [Evaluator quickstart](docs/partner-eval/quickstart.md)
+- [API playground](docs/partner-eval/api-playground.md)
+- [OpenAPI contract](openapi.yaml)
+- [Postman collection](postman/TrustSignal.postman_collection.json)
+- [Postman local environment](postman/TrustSignal.local.postman_environment.json)
 
 Golden path:
 
@@ -90,6 +107,11 @@ The evaluator path is designed to show the core value before full production int
 - later verification against the stored receipt state
 - visible handling for tampered evidence or stale evidence through the later verification lifecycle
 
+## Production Considerations
+
+> [!IMPORTANT]
+> Production considerations: local evaluator paths are deliberate evaluation paths. They do not replace deployment-specific authentication, signing configuration, infrastructure controls, or operational review.
+
 ## Local API Development Setup
 
 Prerequisites:
@@ -161,6 +183,17 @@ TrustSignal is designed to sit behind an existing workflow such as:
 
 The upstream platform remains the system of record. TrustSignal adds an integrity layer at the boundary and returns technical verification artifacts that the upstream workflow can store and use later.
 
+## Security And Claims Boundary
+
+> [!NOTE]
+> Claims boundary: this repository documents the public integration and evaluation surface only. It does not expose proof internals, circuit identifiers, model outputs, signing infrastructure specifics, or internal service topology.
+
+## Compliance and Security Readiness
+
+TrustSignal includes a repository-level SOC 2 readiness framework for assessing security posture, documentation maturity, governance evidence, and mock-audit gaps. It is intended to support internal review and partner diligence preparation. It does not claim SOC 2 certification.
+
+- [SOC 2 readiness report](docs/compliance/soc2/readiness-report.md)
+
 ## 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.
@@ -191,12 +224,12 @@ Fail-closed defaults are part of the security posture. They are meant to prevent
 
 The public evaluation artifacts in this repo are:
 
-- [openapi.yaml](/Users/christopher/Projects/trustsignal/openapi.yaml)
-- [verification-request.json](/Users/christopher/Projects/trustsignal/examples/verification-request.json)
-- [verification-response.json](/Users/christopher/Projects/trustsignal/examples/verification-response.json)
-- [verification-receipt.json](/Users/christopher/Projects/trustsignal/examples/verification-receipt.json)
-- [verification-status.json](/Users/christopher/Projects/trustsignal/examples/verification-status.json)
-- [partner evaluation kit](/Users/christopher/Projects/trustsignal/docs/partner-eval/overview.md)
+- [openapi.yaml](openapi.yaml)
+- [verification-request.json](examples/verification-request.json)
+- [verification-response.json](examples/verification-response.json)
+- [verification-receipt.json](examples/verification-receipt.json)
+- [verification-status.json](examples/verification-status.json)
+- [partner evaluation kit](docs/partner-eval/overview.md)
 
 These artifacts document the public verification lifecycle only. They intentionally avoid proof internals, model outputs, circuit identifiers, signing infrastructure specifics, and internal service topology.
 
@@ -211,7 +244,7 @@ Public-facing security properties for this repository are:
 - explicit lifecycle boundaries for read, revoke, and provenance-state operations
 - fail-closed defaults where production trust assumptions are not satisfied
 
-See [docs/security-summary.md](/Users/christopher/Projects/trustsignal/docs/security-summary.md), [SECURITY_CHECKLIST.md](/Users/christopher/Projects/trustsignal/SECURITY_CHECKLIST.md), and [docs/SECURITY.md](/Users/christopher/Projects/trustsignal/docs/SECURITY.md) for the current public-safe security summary and repository guardrails.
+See [docs/security-summary.md](docs/security-summary.md), [SECURITY_CHECKLIST.md](SECURITY_CHECKLIST.md), and [docs/SECURITY.md](docs/SECURITY.md) for the current public-safe security summary and repository guardrails.
 
 ## What TrustSignal Does Not Claim
 
@@ -237,12 +270,27 @@ npm run typecheck
 npm run build
 ```
 
+## Current Evaluator Metrics
+
+Recent local benchmark snapshot from [bench/results/latest.md](bench/results/latest.md). A partner-facing interpretation is available in [docs/partner-eval/benchmark-summary.md](docs/partner-eval/benchmark-summary.md).
+
+- clean verification request latency: mean `5.24 ms`, median `4.11 ms`, p95 `21.65 ms`
+- signed receipt generation latency: mean `0.34 ms`, median `0.32 ms`, p95 `0.63 ms`
+- receipt lookup latency: mean `0.57 ms`, median `0.56 ms`, p95 `0.63 ms`
+- later verification latency: mean `0.77 ms`, median `0.71 ms`, p95 `1.08 ms`
+- tampered artifact detection latency: mean `7.76 ms`, median `5.13 ms`, p95 `42.82 ms`
+- repeated-run stability for the same artifact payload: mean `3.24 ms`, median `3.16 ms`, p95 `3.69 ms`
+
+This is a recent local evaluator run against the current `/api/v1/*` lifecycle with a temporary local PostgreSQL instance. It is a benchmark snapshot for evaluation and regression tracking, not a production guarantee or SLA.
+
 ## Documentation Map
 
-- [docs/partner-eval/overview.md](/Users/christopher/Projects/trustsignal/docs/partner-eval/overview.md)
-- [docs/partner-eval/quickstart.md](/Users/christopher/Projects/trustsignal/docs/partner-eval/quickstart.md)
-- [docs/partner-eval/api-playground.md](/Users/christopher/Projects/trustsignal/docs/partner-eval/api-playground.md)
-- [wiki/What-is-TrustSignal.md](/Users/christopher/Projects/trustsignal/wiki/What-is-TrustSignal.md)
-- [wiki/API-Overview.md](/Users/christopher/Projects/trustsignal/wiki/API-Overview.md)
-- [wiki/Claims-Boundary.md](/Users/christopher/Projects/trustsignal/wiki/Claims-Boundary.md)
-- [wiki/Verification-Receipts.md](/Users/christopher/Projects/trustsignal/wiki/Verification-Receipts.md)
+- [docs/partner-eval/overview.md](docs/partner-eval/overview.md)
+- [docs/partner-eval/quickstart.md](docs/partner-eval/quickstart.md)
+- [docs/partner-eval/api-playground.md](docs/partner-eval/api-playground.md)
+- [docs/templates/docs-architecture.md](docs/templates/docs-architecture.md)
+- [docs/templates/doc-template.md](docs/templates/doc-template.md)
+- [wiki/What-is-TrustSignal.md](wiki/What-is-TrustSignal.md)
+- [wiki/API-Overview.md](wiki/API-Overview.md)
+- [wiki/Claims-Boundary.md](wiki/Claims-Boundary.md)
+- [wiki/Verification-Receipts.md](wiki/Verification-Receipts.md)
diff --git a/apps/api/.env.example b/apps/api/.env.example
@@ -42,11 +42,14 @@ RATE_LIMIT_API_KEY_MAX=120
 # Database (must enforce TLS; include sslmode=require)
 DATABASE_URL=postgresql://user:password@host:5432/deedshield?sslmode=require
 # Supabase aliases (optional if you prefer naming by provider)
+SUPABASE_URL=https://<project-ref>.supabase.co
+SUPABASE_SERVICE_ROLE_KEY=replace-with-server-only-service-role-key
 SUPABASE_DB_URL=postgresql://postgres.<project-ref>:[password]@aws-0-<region>.pooler.supabase.com:6543/postgres?sslmode=require
 SUPABASE_POOLER_URL=postgresql://postgres.<project-ref>:[password]@aws-0-<region>.pooler.supabase.com:6543/postgres?sslmode=require
 SUPABASE_DIRECT_URL=postgresql://postgres:[password]@db.<project-ref>.supabase.co:5432/postgres?sslmode=require
 # Optional helper if using Supabase CLI pooler URL discovery from `supabase/.temp/pooler-url`.
 SUPABASE_DB_PASSWORD=replace-with-supabase-db-password
+SUPABASE_SECRET_KEY=replace-with-server-only-secret-key
 
 # Blockchain Configuration (Sepolia or Local)
 ANCHOR_REGISTRY_ADDRESS=0x...