Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
* @chrismaz11
/apps/api/src/ @chrismaz11
/circuits/ @chrismaz11
/packages/core/ @chrismaz11
37 changes: 20 additions & 17 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,18 @@ on:
branches:
- master

permissions:
contents: read

jobs:
lint:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v6
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

- name: Setup Node.js
uses: actions/setup-node@v6
uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
with:
node-version: '20'
cache: npm
Expand All @@ -31,10 +34,10 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v6
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

- name: Setup Node.js
uses: actions/setup-node@v6
uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
with:
node-version: '20'
cache: npm
Expand All @@ -54,10 +57,10 @@ jobs:
POLYGON_RPC_URL: ${{ secrets.POLYGON_RPC_URL }}
steps:
- name: Checkout
uses: actions/checkout@v6
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

- name: Setup Node.js
uses: actions/setup-node@v6
uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
with:
node-version: '20'
cache: npm
Expand All @@ -72,10 +75,10 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v6
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

- name: Setup Node.js
uses: actions/setup-node@v6
uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
with:
node-version: '20'
cache: npm
Expand Down Expand Up @@ -106,10 +109,10 @@ jobs:
DATABASE_URL: postgresql://postgres@127.0.0.1:5432/trustsignal_signed_receipt_smoke?sslmode=disable
steps:
- name: Checkout
uses: actions/checkout@v6
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

- name: Setup Node.js
uses: actions/setup-node@v6
uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
with:
node-version: '20'
cache: npm
Expand All @@ -127,10 +130,10 @@ jobs:
working-directory: circuits/non_mem_gadget
steps:
- name: Checkout
uses: actions/checkout@v6
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

- name: Setup Rust
uses: dtolnay/rust-toolchain@stable
uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable

- name: Build Halo2 verifier
run: cargo build --release
Expand All @@ -142,7 +145,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v6
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

- name: Install gitleaks
run: |
Expand All @@ -158,10 +161,10 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v6
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

- name: Setup Node.js
uses: actions/setup-node@v6
uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
with:
node-version: '20'
cache: npm
Expand All @@ -178,10 +181,10 @@ jobs:
contents: read
steps:
- name: Checkout
uses: actions/checkout@v6
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

- name: Setup Node.js
uses: actions/setup-node@v6
uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
with:
node-version: 22
Copy link

Copilot AI Mar 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This workflow sets node-version: 22 for the verify-artifact-action job, but the repo root package.json declares Node 20.x and the action itself declares >=20. Using 22 here can mask compatibility issues and adds avoidable drift—please align this job to Node 20 (or update the repo engines if 22 is now required).

Suggested change
node-version: 22
node-version: '20'

Copilot uses AI. Check for mistakes.

Expand Down
26 changes: 26 additions & 0 deletions .github/workflows/dependency-review.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
name: Dependency diff review

on:
pull_request:
branches:
- master
- work

# Restrict to the minimum permissions needed for checkout and dependency review.
permissions:
contents: read

jobs:
dependency-review:
name: Dependency diff review
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
persist-credentials: false

- name: Dependency diff review
uses: actions/dependency-review-action@da24556b548a50705dd671f47852072ea4c105d9 # v4.7.1
with:
fail-on-severity: high
46 changes: 46 additions & 0 deletions .github/workflows/trivy.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
name: Trivy repository scan

on:
push:
branches:
- master
- work
pull_request:
branches:
- master
- work

# Restrict to minimum required permissions.
# security-events: write is required only for SARIF upload to code scanning.
permissions:
contents: read
security-events: write

Comment on lines +13 to +18
Copy link

Copilot AI Mar 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

security-events: write is granted at the workflow level, so the third-party aquasecurity/trivy-action step receives an elevated GITHUB_TOKEN. To follow least-privilege (and match the PR description), split this into two jobs: the scan job with only contents: read that uploads the SARIF as an artifact, and a separate upload job with security-events: write that only runs the upload-sarif action (and is skipped on forks).

Copilot uses AI. Check for mistakes.
jobs:
trivy:
name: Trivy filesystem scan
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
persist-credentials: false

- name: Run Trivy filesystem scan
uses: aquasecurity/trivy-action@6e7b7d1fd3e4fef0c5fa8cce1229c54b2c9bd0d8 # v0.30.0
with:
scan-type: fs
scan-ref: "."
severity: HIGH,CRITICAL
ignore-unfixed: true
format: sarif
output: trivy-results.sarif

- name: Upload Trivy SARIF to code scanning
# Skip on forked PRs — GitHub does not grant security-events: write to
# untrusted fork tokens, so SARIF upload would fail with a permissions error.
if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
uses: github/codeql-action/upload-sarif@ff0a06e83cb2de871e5a09832bc6a81e7276941f # v3.28.18
with:
sarif_file: trivy-results.sarif
category: trivy
34 changes: 34 additions & 0 deletions .github/workflows/zizmor.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
name: zizmor advisory audit

on:
pull_request:
paths:
- ".github/workflows/**"

# Restrict to minimum required permissions.
permissions:
contents: read

jobs:
zizmor:
name: zizmor workflow audit
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
persist-credentials: false

- name: Install zizmor
run: pip install zizmor==1.5.0

- name: Run zizmor workflow audit
# Advisory mode — findings are reported but do not fail the job.
# Maintainers should review and address findings before merging workflow changes.
run: |
EXIT_CODE=0
zizmor --format plain .github/workflows/ || EXIT_CODE=$?
if [ $EXIT_CODE -ne 0 ]; then
echo "::warning::zizmor found workflow security findings (advisory). Review the output above before merging."
fi
exit 0
Comment on lines +28 to +34
Copy link

Copilot AI Mar 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The zizmor step unconditionally exit 0, so the job will pass even if zizmor fails to run (e.g., install issues, runtime crash, bad args). If the intent is “advisory findings don’t fail, but genuine execution failures do”, prefer continue-on-error: true on the zizmor step (or handle specific exit codes for findings vs errors) rather than always exiting successfully.

Suggested change
run: |
EXIT_CODE=0
zizmor --format plain .github/workflows/ || EXIT_CODE=$?
if [ $EXIT_CODE -ne 0 ]; then
echo "::warning::zizmor found workflow security findings (advisory). Review the output above before merging."
fi
exit 0
continue-on-error: true
run: zizmor --format plain .github/workflows/

Copilot uses AI. Check for mistakes.
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,8 @@ packages/core/registry/registry.private.jwk
.vercel
circuits/non_mem_gadget/target/
ml/.venv/
**/__pycache__/
**/*.py[cod]
ml/zkml/deed_cnn.pk
tmp/

Expand Down
44 changes: 22 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,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.

Expand Down Expand Up @@ -47,17 +47,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:

Expand Down Expand Up @@ -191,12 +191,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.

Expand All @@ -211,7 +211,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

Expand All @@ -225,7 +225,7 @@ TrustSignal does not provide:

## Current Repository Context

DeedShield is the current application surface in this repository. The broader product framing remains TrustSignal as evidence integrity infrastructure and an integrity layer for existing workflows.
TrustSignal is the canonical product and application surface in this repository. The current wedge remains property-record verification, with the platform framed as evidence integrity infrastructure for existing workflows.

## Newbie Difficulty Rating

Expand Down Expand Up @@ -261,10 +261,10 @@ npm run build

## 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)
- [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)
6 changes: 3 additions & 3 deletions SECURITY_CHECKLIST.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Deed Shield — Security & Production Readiness Checklist
# TrustSignal — Security & Production Readiness Checklist

> This document tracks the security posture of the Deed Shield API.
> This document tracks the security posture of the TrustSignal API.
> Each item is either ✅ (verified in-repo), 🔒 (enforced by code), or 📋 (requires infra/ops verification).

---
Expand Down Expand Up @@ -45,7 +45,7 @@

| # | Requirement | Status | Evidence |
| --- | ------------------------------------------ | ------ | -------------------------------------------------------- |
| 4.1 | Keccak-256 for document hashing | ✅ | `keccak256Buffer` from `@deed-shield/core`. |
| 4.1 | Keccak-256 for document hashing | ✅ | `keccak256Buffer` from `@trustsignal/core`. |
| 4.2 | Receipt hash verification | ✅ | `POST /receipt/:id/verify` recomputes hash. |
| 4.3 | JWT receipts have expiration | ✅ | Enforced in core receipt builder. |
| 4.4 | Private keys never in code or config files | ✅ | Only via `PRIVATE_KEY` env var, never imported directly. |
Expand Down
10 changes: 5 additions & 5 deletions USER_MANUAL.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# DeedShield User Manual
# TrustSignal User Manual

**Version:** 2.0 (Risk & Compliance Enhanced)
**Date:** February 2026

## 1. Overview
DeedShield is an automated document verification platform designed to prevent real estate title fraud. It protects homeowners and county clerks by ensuring:
TrustSignal is an automated document verification platform designed to prevent real estate title fraud. It protects homeowners and county clerks by ensuring:
1. **Recording Integrity**: Documents meet strict Cook County formatting and content rules.
2. **Fraud Detection**: An AI Risk Engine analyzes documents for signs of forgery or tampering.
3. **Immutable Proof**: Every validation is "anchored" on a public blockchain (EVM), creating a permanent, tamper-proof audit trail.
Expand All @@ -20,7 +20,7 @@ DeedShield is an automated document verification platform designed to prevent re
* *Note: Only PDF files are supported for full verification.*

### Step 2: Automated Extraction & Review
Once uploaded, DeedShield automatically:
Once uploaded, TrustSignal automatically:
* **Removes Watermarks**: Strips "DO NOT COPY" or "UNOFFICIAL" stamps to read the text.
* **Extracts Metadata**: Finds the **Parcel ID (PIN)** and **Grantor Name**.
* **Computes Hash**: Generates a unique `SHA-256` digital fingerprint of your file.
Expand All @@ -36,7 +36,7 @@ The system pre-fills the verification form with your document's data.
3. Click **"Verify Bundle"**.

### Step 4: Results & Receipt
DeedShield runs a comprehensive audit and produces a **Verification Receipt**.
TrustSignal runs a comprehensive audit and produces a **Verification Receipt**.
* **Decision**:
* `ALLOW`: Safe to record.
* `FLAG`: Minor issues found (e.g., low visual quality, warnings).
Expand All @@ -63,7 +63,7 @@ The **Document Fraud Risk Engine** assigns a probability score (0.0 - 1.0) based

### C. Anchoring
* **"Anchored" Status**: The digital fingerprint (hash) of your receipt has been written to the Ethereum blockchain.
* **Proof**: This proves *exactly* what the document looked like and what the verification result was at that specific moment in time. Even DeedShield cannot alter this record later.
* **Proof**: This proves *exactly* what the document looked like and what the verification result was at that specific moment in time. Even TrustSignal cannot alter this record later.

---

Expand Down
Loading
Loading