feat(idos): Gov ID branch — sessions wiring, consumer SDK, kyc-token, credentials endpoint

[calebtuttle]

Adds the id-server side of the idOS Gov ID flow. Pairs with frontend PR holonym-foundation/human-id#196.

What lands

• U1 — sessions (ea79634)

  • Add "idos" to the four idvProvider validation lists in src/services/sessions/endpoints.ts (POST /sessions/v3 paths and setIdvProvider).
  • Add an idos branch to handleIdvSessionCreation that persists the session row with no external SDK call. idOS has no applicant / token / webhook lifecycle.

• U2 — consumer SDK wrapper (56c7f1e)

  • src/services/idos/consumer.ts: lazily-initialized idOSConsumer with a narrow public surface (listGrants, decryptCredential, getSharedCredential).
  • Reads IDOS_SIGNER (128-char hex nacl secret key) and IDOS_RECIPIENT_ENCRYPTION_PRIVATE_KEY on first use; throws clear errors on missing/malformed env vars. Optional IDOS_NODE_URL and IDOS_CHAIN_ID overrides.
  • package.json: add @idos-network/consumer ^1.1.0 and tweetnacl ^1.0.3.
  • Bun-test coverage of env validation, init memoization, and node/chain forwarding.

• U9 — POST /idos/kyc-token (6c3f5dc)

  • ES512-signed Fractal KYC JWT for the verify page to embed in the Kraken iframe URL.
  • Body validation (0x-prefixed 20-byte walletAddress, bounded externalUserId), per-env rate limit, sandbox env-var fallback (IDOS_JWT_PRIVATE_KEY_SANDBOX, IDOS_FRACTAL_CLIENT_ID_SANDBOX).
  • No expiresIn per the parent plan U9 (Fractal expects tokens without expiration). Single seam if that ever changes.
  • Mounted at /idos/kyc-token and /sandbox/idos/kyc-token.

• U3 + U4 — GET /idos/credentials/v3/:_id/:nullifier (4686c2f)

  • services/idos/credentials/utils.ts: extractCreds(vc) maps a decrypted VerifiableCredential<VerifiableCredentialSubject> into the Onfido-compatible { rawCreds, derivedCreds, fieldsInLeaf } shape. Hash composition is byte-identical to Onfido's extractCreds for equivalent inputs — enforced by parity tests against the Onfido extractor.
  • services/idos/credentials/v3.ts: mirrors services/onfido/credentials/v3.ts structurally — nullifier validation, ObjectId parse, session lookup, VERIFICATION_FAILED guard, 5-day nullifier replay path, sybil-resistance UUID + UserVerifications insert, issuev2KYC, ISSUED status. New: reads dataId + userAddress from the query string, filters the consumer's grant list by data_id, and trust-checks the on-chain credential's issuer_auth_public_key against the configured allow-list before any field hashing.
  • services/idos/issuers.ts: env-driven trust list (IDOS_ALLOWED_ISSUERS_JSON or IDOS_ALLOWED_ISSUER + IDOS_ALLOWED_ISSUER_PUBLIC_KEY).
  • schemas.ts + types.ts: extend NullifierAndCreds.idvSessionIds with idos.dataId (sandbox mirrored).

Plan

Implements U1, U2, U3, U4, U9 from the parent plan in the human-id repo: docs/plans/2026-04-30-003-feat-idos-as-onfido-alternative-in-gov-id-flow-plan.md (also visible on the linked frontend PR).

Env vars introduced

Var	Purpose
IDOS_SIGNER	hex-encoded nacl.sign secret key (128 hex chars) for the consumer's grant signer
IDOS_RECIPIENT_ENCRYPTION_PRIVATE_KEY	consumer-side encryption private key
IDOS_NODE_URL (optional)	Kwil node URL override
IDOS_CHAIN_ID (optional)	Kwil chain id override
IDOS_JWT_PRIVATE_KEY	PEM-encoded ES512 private key Fractal trusts
IDOS_FRACTAL_CLIENT_ID	Fractal-issued client id (UUID)
IDOS_JWT_PRIVATE_KEY_SANDBOX (optional)	sandbox override; falls back to prod
IDOS_FRACTAL_CLIENT_ID_SANDBOX (optional)	sandbox override; falls back to prod
IDOS_ALLOWED_ISSUERS_JSON or IDOS_ALLOWED_ISSUER + IDOS_ALLOWED_ISSUER_PUBLIC_KEY	issuer trust list

.env.example was not updated in this branch (permission-blocked when authored). Copy these into the deploy env-var contract before Slice U / staging smoke.

Test plan

• bun install completes (adds @idos-network/consumer + tweetnacl)
• bun test src/services/idos/consumer.test.ts — env validation + init memoization
• bun test src/services/idos/kyc-token.test.ts — ES512 payload shape, sandbox env fallback, validation 400s
• bun test src/services/idos/credentials/utils.test.ts — Onfido parity for nameHash / streetHash / addressHash / nameDobCitySubdivisionZipStreetExpireHash
• bun --watch src/server.ts boots without idOS env vars set (lazy-init contract)
• Hit POST /idos/kyc-token with a valid walletAddress and verify the returned JWT decodes to the expected payload (against IDOS_FRACTAL_CLIENT_ID + ES512 alg)
• End-to-end smoke: frontend verify page (PR #196) → grant → GET /idos/credentials/v3/:sid/:nullifier returns issuance response equivalent to the Onfido path for the same logical input

Notes

• This branch was force-recovered from a deleted worktree's submodule clone. The sequence of commits is identical in scope to the original (lost) work; only the SHAs are new.

🤖 Generated with Claude Code