Skip to content

feat: add endorsement endpoints and deprecate /api/content/verify#1

Merged
jt55401 merged 2 commits into
mainfrom
feat/endorsements-and-deprecate-verify
May 13, 2026
Merged

feat: add endorsement endpoints and deprecate /api/content/verify#1
jt55401 merged 2 commits into
mainfrom
feat/endorsements-and-deprecate-verify

Conversation

@jt55401
Copy link
Copy Markdown
Contributor

@jt55401 jt55401 commented Apr 29, 2026

Summary

  • Implements spec §2.5 endorsement storage and serving (POST/GET/DELETE /api/endorsements).
  • Marks POST /api/content/verify deprecated per spec §3.1 — cryptographic verification is a local operation in clients; the trust directory's job is to store and serve signed artifacts, not act as an oracle.
  • Existing sign/verify behavior unchanged; only metadata signaling that verify is no longer canonical.

Endorsement endpoints

  • POST /api/endorsements — stores a signed endorsement blob, optionally re-verifying server-side as a sanity check (clients MUST NOT rely on this; verification is local per spec).
  • GET /api/endorsements?content-hash=... — returns stored blobs verbatim for clients to verify locally.
  • DELETE /api/endorsements/:id — MVP-gated on the existing API key; TODO for keyid-match auth.
  • Endorsement model with unique compound index on {contentHash, endorser}.

Deprecation signaling

  • Deprecation: true and Link: <https://htmltrust.dev/spec#section-3-1>; rel="deprecation" headers.
  • deprecated: true in openapi.yaml.
  • README documents the deprecation and points to local verification.

Test plan

  • npm install clean, 0 vulnerabilities
  • node src/server.js boots cleanly with new routes mounted
  • openapi.yaml parses; new paths/schemas/tag and the deprecated flag verify in the parsed structure
  • Smoke tests against a running Mongo (no test framework configured in this repo):
    curl 'http://localhost:3000/api/endorsements?content-hash=sha256:abc'
    curl -X POST http://localhost:3000/api/endorsements \
      -H 'Content-Type: application/json' -H "X-API-KEY: $GENERAL_API_KEY" \
      -d '{"endorser":"did:web:publisher.org","contentHash":"sha256:abc","signature":"BASE64SIG","timestamp":"2025-05-01T00:00:00Z"}'
    curl -i -X POST http://localhost:3000/api/content/verify -H 'Content-Type: application/json' -d '{}'  # expect Deprecation: true

🤖 Generated with Claude Code

jt55401 and others added 2 commits April 10, 2026 22:36
Explicitly positions this Node.js reference as one of three federated
reference directory implementations, each with a distinct curatorial
personality:

- Node (this) -- permissive community baseline, full-featured, neutral
- Python -- curated journalism with admin approval + punitive scoring
- Rust -- rapid-flag public-safety with time-decay + researcher whitelist

All three conform to the same OpenAPI spec, demonstrating that
federation is real: clients subscribe to one or more directories and
weight the returned scores per their own trust policy.
Implements spec §2.5 endorsement storage and serving, and aligns the
trust server's role with spec §3.1 by deprecating the server-side
verification endpoint. Cryptographic verification is a local operation
in clients; the trust directory's job is to store and serve signed
artifacts (signatures, endorsements, reports), not to act as an oracle.

Endorsements (spec §2.5):
- POST /api/endorsements stores a signed endorsement blob, optionally
  re-verifying server-side as a sanity check (clients MUST NOT rely on
  this; verification is local per spec)
- GET /api/endorsements?content-hash=... returns stored blobs verbatim
  for clients to verify locally
- DELETE /api/endorsements/:id (MVP-gated; TODO for keyid-match auth)
- Endorsement model with unique compound index on {contentHash, endorser}

Deprecation of /api/content/verify:
- Sets Deprecation: true and Link rel="deprecation" headers on response
- deprecated: true in OpenAPI spec
- README documents the deprecation and points to local verification

Behavior of existing sign and verify endpoints is unchanged; only the
metadata signaling that verify is no longer canonical.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@jt55401 jt55401 merged commit a39ec57 into main May 13, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant