@presence-auth/verifier-sdk

Presence verifier SDK for server-side proof verification.

This package is designed for the Stripe-like service side of Presence:

• the Presence app is managed and distributed by Presence
• partner services install the verifier SDK
• partner services verify signed Presence proofs on their own backend
• raw health data never enters the verifier contract

Install status

Current status:

• source is open in this repository under MIT
• the standalone npm package is prepared and dry-run verified
• the public production signing target is now frozen in ../../docs/spec/PRESENCE-SIGNING-MODEL.md
• the package metadata is now staged for public release (0.2.0, non-private, public publish config)
• actual npm publish is still a separate release action and has not been executed yet

Current source-open install path:

npm install /absolute/path/to/presence-auth/packages/presence-verifier

Target install command after publish:

npm install @presence-auth/verifier-sdk

If you just want to validate the package from source first:

npm --prefix packages/presence-verifier run verify:package

5-minute first success path

1. Install from the local package workspace

npm install /absolute/path/to/presence-auth/packages/presence-verifier

2. Load the packaged Ed25519 fixture

const {
  loadPresenceSandboxFixture,
} = require('@presence-auth/verifier-sdk/sandbox');

const fixture = await loadPresenceSandboxFixture('valid-verify-proof-ed25519');

3. Create a signature verifier

const {
  createEd25519SignatureVerifier,
} = require('@presence-auth/verifier-sdk');

const signatureVerifier = createEd25519SignatureVerifier({
  trustRootPublicKey: fixture.trustRootPublicKey,
});

4. Verify the proof

const {
  assertVerifiedPresenceResult,
  verifyPresence,
} = require('@presence-auth/verifier-sdk');

const result = await verifyPresence({
  proof: fixture.proof,
  expected: fixture.verifierInput.expected,
  signatureVerifier,
});

assertVerifiedPresenceResult(result);
console.log(result.reasonCode); // OK

5. Move to your real service flow

Replace these fixture-owned inputs:

• packaged fixture proof -> real proof sent from the Presence app flow
• fixture trust-root public key -> your production trust-root source
• optional in-memory replay guard -> durable Redis/DB replay protection

Keep these pieces unchanged:

• verifyPresence(...)
• the verifier result contract
• the privacy invariant that raw health data never reaches your service

Compatibility note:

• the legacy sandbox fixtures and createStoreBackedSignatureVerifier(...) remain available for compatibility testing only

Copy-paste starter files

The package includes starter templates under templates/:

• templates/minimal-express-server.cjs
• templates/minimal-express-server.ts
• templates/verify-request.example.json
• templates/env.verifier.example

Notes:

• verify-request.example.json now contains a production-shaped Ed25519 example that matches the packaged env template trust root
• both starter templates now use createEd25519SignatureVerifier(...) as the primary path
• createStoreBackedSignatureVerifier(...) remains a sandbox / compatibility helper only

Runtime integration checklist

A production verifier service should provide:

• canonical serviceId
• server-issued expected context for the pending request
• durable replay protection (Redis or DB)
• a pinned Presence trust-root public key source
• request/binding lookup owned by the service
• audit logging

Reference docs:

• ./INTEGRATORS_GUIDE.md
• source-repo docs under docs/spec/ for deeper integration notes

Package verification

npm run verify:package

This command:

• builds the package
• verifies the root import
• verifies the sandbox subpath import
• syntax-checks both packaged starter templates
• validates the packaged example request JSON
• runs the packaged quickstart example
• performs npm pack --dry-run

Upgrading

Planned upgrade contract:

• semver governs future public package releases
• user-facing package changes are recorded in CHANGELOG.md
• release/process rules live in ../../docs/spec/PRESENCE-VERIFIER-RELEASE-POLICY.md
• protocol freeze status lives in ../../docs/spec/PRESENCE-PROTOCOL-FREEZE.md

Before adopting a new version, re-run:

npm run verify:package
npm run compat:presence -- --report artifacts/presence-compat-report.json

Privacy invariant

The verifier package only operates on:

• proof envelope
• expected verifier context
• verifier result

It does not request, accept, or persist:

• raw BPM samples
• raw step history
• HealthKit exports
• reconstructable health timelines