@solidus-network/auth 0.6.0 → 0.6.2

package/README.md

@@ -1,8 +1,11 @@
 # @solidus-network/auth
 
-DID-based authentication primitives for the [Solidus Network](https://solidus.network) protocol.
+DID-based authentication and DID-less BBS+ selective-disclosure verification for the [Solidus Network](https://solidus.network) protocol.
 
-Ed25519 challenge / signature / verification, designed to drop into any Node.js or edge backend that needs to authenticate a holder of a DID without operating its own user database.
+Two independent surfaces, one package:
+
+- **DID-bound auth** — Ed25519 challenge / signature / verification, for backends that authenticate the holder of a known DID without operating a user database.
+- **DID-less presentations** — the relying-party surface for Solidus's unlinkable credential presentations: verify "a valid KYC credential from this issuer, disclosing exactly these claims" without ever learning who presented it.
 
 ## Install
 
@@ -12,39 +15,146 @@ npm install @solidus-network/auth
 pnpm add @solidus-network/auth
 ```
 
-## Quick start
+## Quick start — DID-bound challenge
+
+```ts
+import { createChallenge, verifyPresentation } from '@solidus-network/auth'
+
+// Server: issue a challenge for a known DID (TTL in seconds, default 300)
+const challenge = createChallenge('did:solidus:testnet:abc123', 300)
+
+// Client answers with a W3C Verifiable Presentation whose proof signs
+// the challenge nonce; the server verifies:
+const result = await verifyPresentation(challenge, presentation, getPublicKey)
+
+if (result.valid) {
+  // authenticated — result.checks itemizes expiry/holder/nonce/signature
+}
+```
+
+## DID-less selective-disclosure presentations (BBS+)
+
+The verifier surface for Solidus's **unlinkable** presentations: a wallet
+proves it holds a valid KYC credential from a trusted issuer and disclosed
+exactly the claims you asked for — without revealing the holder's DID, a
+credential ID, or anything two relying parties could later compare to
+discover they served the same person.
+
+### How it works
+
+- The issuer signs an 8-message KYC vector with BBS+ under a **header that
+  is constant per (issuer, credential-type, epoch)** — no per-credential
+  entropy, so the header places a holder in a cohort, never identifies one.
+- The issuer publishes its per-epoch public keys at
+  `https://verify.solidus.network/.well-known/solidus-bbs-issuer.json`.
+  Credentials live as long as their epoch (+ a grace window); revocation is
+  bounded-lifetime — a lapsed epoch's key disappears from the document and
+  every verifier fails closed.
+- The wallet answers a verifier's challenge with a **randomized proof**
+  bound to that verifier's domain + nonce. Replaying it under any other
+  challenge fails cryptographically.
+- The envelope (`BbsSelectiveDisclosurePresentation`) has **no `holder`
+  field by construction**, and the verifier rejects any envelope that
+  discloses `subject_did`, `verification_id`, or `document_hash` even when
+  the proof itself is valid.
+
+### Verifier quickstart (a complete relying party)
 
 ```ts
-import { generateChallenge, verifyChallenge } from '@solidus-network/auth'
+import {
+  createBbsChallenge,
+  verifyBbsPresentation,
+  createIssuerKeyResolver,
+  parseBbsPresentation,
+  decodeDisclosedKycFields,
+} from '@solidus-network/auth'
 
-// Server: issue a challenge
-const challenge = generateChallenge({
-  did: 'did:solidus:testnet:abc123',
-  domain: 'app.example.com',
-  ttlMs: 5 * 60_000,
+// 1. Issue a DID-less challenge (store it; enforce single use).
+const challenge = createBbsChallenge({
+  domain: 'your-app.example.com',      // your authenticated origin
+  credentialType: 'kyc',
+  requiredIndices: [4, 5],             // kyc_level, country
 })
 
-// Client signs `challenge.nonce` with the DID's signing key, returns the signature
+// 2. The wallet answers with a serialized envelope.
+const presentation = parseBbsPresentation(envelopeJson)
 
-// Server: verify
-const result = await verifyChallenge({
-  challenge,
-  signature,
-  publicKey,
+// 3. Verify — stateless, against the issuer's published epoch keys.
+const resolveIssuerKey = createIssuerKeyResolver({
+  issuerBaseUrl: 'https://verify.solidus.network',
+})
+const result = await verifyBbsPresentation(challenge, presentation, {
+  issuerDid: 'did:solidus:testnet:2FDp7gH5qyb66jjsXAbFQYwLygqQ',
+  resolveIssuerKey,
+  used: false,                          // your storage-side single-use flag
 })
 
-if (result.ok) {
-  // authenticated
+if (result.valid) {
+  const fields = decodeDisclosedKycFields(presentation.disclosed)
+  // e.g. { issuer_did: '…', kyc_level: '2', country: 'TR' } — and nothing else
 }
 ```
 
+The resolver is fail-closed: an unknown or lapsed epoch, an unreachable
+issuer, or a malformed key document all resolve to `null` and the
+presentation is rejected — never accepted on error.
+
+### Verify the unlinkability claim yourself
+
+Don't take our word for it — the demonstration ships in this package and
+runs in under a minute:
+
+```sh
+node node_modules/@solidus-network/auth/demo/unlinkability-demo.mjs
+```
+
+It issues one credential, presents it to two relying parties, verifies
+both presentations, then pools everything both RPs received and shows the
+complete correlation surface: cohort-level constants and the disclosed
+claims — no per-holder value in common, randomized proofs sharing no
+bytes, and cross-challenge replay failing.
+
+### Re-recognition (pairwise DIDs)
+
+When a returning user *wants* to be recognized by one relying party, the
+wallet can attach a **pairwise DID** — deterministically derived from the
+holder's seed *and that verifier's identity*, so the same user shows a
+different, uncorrelatable pairwise DID to every other verifier. See
+`buildPairwiseAttachment` / `buildPairwiseDid`. Two caveats, stated
+plainly: the wallet must derive against the verifier's *authenticated*
+origin (never an ID copied blindly from the challenge), and the pairwise
+signature sits *beside* the credential proof rather than being
+cryptographically bound to the same seed — assurance is "a returning
+controller of this key who also holds a valid credential", which is right
+for convenience and analytics, not for access-control-grade identity.
+
+### What this does and does not protect
+
+**Protected (cryptographic presentation layer):** two relying parties —
+or the same one twice — cannot link presentations by anything in the
+envelopes: no subject DID, no credential ID, no document hash, randomized
+proofs, cohort-constant headers, challenge-bound replay protection.
+
+**NOT protected (out of scope — be honest with your users):** network-level
+correlation (IP address, timing, TLS/device fingerprints, cookies), and
+relying parties pooling out-of-band data they each collected themselves
+(email, phone, payment details). If your application hands every RP the
+user's email address, unlinkable credentials will not make them unlinkable.
+
+**Status:** the underlying `@solidus-network/bbs` implementation is
+**testnet-grade and audit-pending** (external audit via NLnet NGI Zero,
+H2 2026 target). `did:solidus` is submitted to the W3C DID method registry
+and under review. This runs on the Solidus testnet — do not represent it
+as audited or production-assured until those complete.
+
 ## Features
 
 - Ed25519 signature verification via [@noble/ed25519](https://www.npmjs.com/package/@noble/ed25519)
 - BLAKE3 hashing for challenge digests via [@noble/hashes](https://www.npmjs.com/package/@noble/hashes)
 - Time-bounded challenges with TTL enforcement
 - Domain-bound challenges (prevents replay across origins)
-- Zero runtime dependencies on a database or framework
+- DID-less BBS+ selective-disclosure verification with fail-closed epoch-key resolution
+- A runnable unlinkability demonstration (`demo/unlinkability-demo.mjs`)
 
 ## License
 

package/demo/unlinkability-demo.mjs

@@ -0,0 +1,159 @@
+// Solidus unlinkability demonstration — runnable by anyone, from npm alone.
+//
+//   npm i @solidus-network/auth @solidus-network/bbs
+//   node node_modules/@solidus-network/auth/demo/unlinkability-demo.mjs
+//
+// You play every role: issuer, holder, and two relying parties who later
+// collude. The issuer keypair is generated locally; the FORMAT — header v2,
+// the 8-message KYC vector, the envelope, the presentation-header binding —
+// is exactly what verify.solidus.network issues in production (Part 1
+// fetches its live epoch-key document so you can see that for yourself).
+// Production differs only in whose secret key signs, never in what a
+// relying party receives — so the correlation analysis below transfers.
+//
+// HONESTY BOUNDARY (read before quoting this): this demonstrates
+// unlinkability at the cryptographic presentation layer ONLY. It does NOT
+// defend against network-level correlation (IP address, timing, device
+// fingerprint, cookies) or relying parties pooling out-of-band data they
+// collected themselves (email, phone number). @solidus-network/bbs is
+// testnet-grade; external audit pending (NLnet NGI Zero, H2 2026 target).
+
+import {
+  createBbsChallenge,
+  verifyBbsPresentation,
+  buildBbsPresentation,
+  createIssuerKeyResolver,
+  KYC_MESSAGE_FIELDS,
+} from '@solidus-network/auth'
+import {
+  BbsSecretKey,
+  buildV2Header,
+  derivePresentationHeader,
+  utf8,
+} from '@solidus-network/bbs'
+
+const hex = (b) => Buffer.from(b).toString('hex')
+const line = (s = '') => console.log(s)
+
+// ---------------------------------------------------------------------------
+// PART 1 — the production issuer publishes epoch keys at a public URL.
+// Anyone can resolve them; unknown or lapsed epochs fail closed to null.
+// ---------------------------------------------------------------------------
+line('== PART 1: production issuer key document (public URL) ==')
+const PROD = 'https://verify.solidus.network'
+try {
+  const doc = await (await fetch(`${PROD}/.well-known/solidus-bbs-issuer.json`)).json()
+  line(`issuer_did:    ${doc.issuer_did}`)
+  line(`current epoch: ${doc.current.epoch} (notAfter ${doc.current.notAfter})`)
+  const resolve = createIssuerKeyResolver({ issuerBaseUrl: PROD })
+  const key = await resolve(doc.current.epoch)
+  line(`resolver → epoch ${doc.current.epoch}: ${key ? key.slice(0, 32) + '… (96-byte BLS12-381 G2 key)' : 'null'}`)
+  const lapsed = await resolve(9999)
+  line(`resolver → epoch 9999 (unknown): ${lapsed === null ? 'null (fail-closed)' : 'UNEXPECTED KEY'}`)
+} catch {
+  line('(offline — skipping the live fetch; the local demonstration below is unaffected)')
+}
+
+// ---------------------------------------------------------------------------
+// PART 2 — one credential, two relying parties.
+// ---------------------------------------------------------------------------
+line()
+line('== PART 2: one credential, presented to two relying parties ==')
+const issuerDid = 'did:solidus:testnet:demo-issuer'
+const credentialType = 'kyc'
+const epoch = 2
+const sk = await BbsSecretKey.generate()
+const pk = await sk.publicKey()
+const header = buildV2Header(issuerDid, credentialType, epoch)
+
+// The production message vector (order frozen). Demo values only — no PII.
+const messages = [
+  utf8('did:solidus:testnet:demoHolderSubjectDid0000'), // 0 subject_did     — ALWAYS hidden
+  utf8(issuerDid),                                      // 1 issuer_did
+  utf8('vrf_demo_0001'),                                // 2 verification_id — ALWAYS hidden
+  utf8('2026-07-01T09:30:00Z'),                         // 3 verified_at
+  utf8('2'),                                            // 4 kyc_level
+  utf8('TR'),                                           // 5 country
+  utf8('passport'),                                     // 6 document_type
+  utf8('deadbeefdeadbeefdeadbeefdeadbeef'),             // 7 document_hash   — ALWAYS hidden
+]
+const sig = await sk.sign(header, messages)
+line(`issued: 1 credential, 8 messages, header v2 = "${Buffer.from(header).toString()}"`)
+line('(header v2 is issuer/type/epoch-constant — identical for every holder in the cohort)')
+
+const resolveLocal = async (e) => (e === epoch ? pk.toHex() : null)
+const rpA = createBbsChallenge({ domain: 'rp-a.example.com', credentialType, requiredIndices: [4, 5] })
+const rpB = createBbsChallenge({ domain: 'rp-b.example.com', credentialType, requiredIndices: [4] })
+
+async function present(challenge) {
+  const ph = derivePresentationHeader(challenge.domain, Buffer.from(challenge.nonce, 'hex'))
+  const disclosedIndices = [1, ...challenge.requiredIndices].sort((x, y) => x - y)
+  const proof = await sig.createProof({ pk, header, presentationHeader: ph, messages, disclosedIndices })
+  return buildBbsPresentation({
+    challengeId: challenge.id,
+    epoch,
+    proofHex: proof.toHex(),
+    totalMessageCount: messages.length,
+    disclosed: disclosedIndices.map((i) => ({ index: i, message: hex(messages[i]) })),
+  })
+}
+const presA = await present(rpA)
+const presB = await present(rpB)
+
+const opts = () => ({ issuerDid, resolveIssuerKey: resolveLocal, used: false, network: 'testnet' })
+const resA = await verifyBbsPresentation(rpA, presA, opts())
+const resB = await verifyBbsPresentation(rpB, presB, opts())
+line(`RP A verify: valid=${resA.valid}`)
+line(`RP B verify: valid=${resB.valid}`)
+if (!resA.valid || !resB.valid) throw new Error('verification failed — demo aborted')
+
+const replay = await verifyBbsPresentation(rpB, { ...presA, challengeId: rpB.id }, opts())
+line(`RP B replaying A's proof under its own challenge: valid=${replay.valid} (must be false)`)
+
+// ---------------------------------------------------------------------------
+// PART 3 — the collusion attempt: both RPs pool everything they received.
+// ---------------------------------------------------------------------------
+line()
+line('== PART 3: RP A + RP B collude — the complete correlation surface ==')
+const jsonA = JSON.stringify(presA)
+const jsonB = JSON.stringify(presB)
+
+for (const [name, needle] of [
+  ['subject DID', 'demoHolderSubjectDid0000'],
+  ['verification_id', hex(utf8('vrf_demo_0001'))],
+  ['document_hash', hex(utf8('deadbeefdeadbeefdeadbeefdeadbeef'))],
+]) {
+  const found = jsonA.includes(needle) || jsonB.includes(needle)
+  line(`per-holder ${name} present in either envelope: ${found ? 'YES — LINKABLE (FAIL)' : 'no'}`)
+  if (found) throw new Error('linkable identifier leaked')
+}
+
+const a = Buffer.from(presA.proof, 'hex')
+const b = Buffer.from(presB.proof, 'hex')
+let equalBytes = 0
+for (let i = 0; i < Math.min(a.length, b.length); i++) if (a[i] === b[i]) equalBytes++
+line(`proof bytes equal at the same offset: ${equalBytes}/${Math.min(a.length, b.length)} (random baseline ≈ ${(Math.min(a.length, b.length) / 256).toFixed(1)})`)
+
+const presA2 = await present(rpA)
+line(`regenerated proof for the SAME challenge identical to the first: ${presA2.proof === presA.proof ? 'YES (FAIL)' : 'no (randomized)'}`)
+
+line('fields present in BOTH envelopes:')
+for (const [k, v] of Object.entries(presA)) {
+  if (JSON.stringify(v) === JSON.stringify(presB[k])) line(`    ${k} = ${JSON.stringify(v)}  ← cohort-constant, shared by every holder of this (issuer, type, epoch)`)
+}
+const inA = Object.fromEntries(presA.disclosed.map((d) => [d.index, d.message]))
+for (const d of presB.disclosed) {
+  if (inA[d.index]) line(`    disclosed[${d.index}] (${KYC_MESSAGE_FIELDS[d.index]}) = "${Buffer.from(d.message, 'hex')}"  ← disclosed by policy to both; a cohort value, not a per-user handle`)
+}
+
+line()
+line('RESULT: both presentations verified; the pooled correlation surface contains only')
+line('cohort-level constants and the claims each RP itself requested. No per-holder')
+line('value appears in both envelopes.')
+line()
+line('HONESTY BOUNDARY — read before quoting this result:')
+line('  This demonstrates unlinkability at the cryptographic PRESENTATION LAYER only.')
+line('  It does NOT defend against network-level correlation (IP address, timing,')
+line('  device fingerprints, cookies) or relying parties pooling out-of-band data')
+line('  they collected themselves (email, phone). @solidus-network/bbs is testnet-grade;')
+line('  external audit pending (NLnet NGI Zero, H2 2026 target).')

package/dist/challenge.d.ts

@@ -17,4 +17,39 @@ export interface Challenge {
  * @param ttlSeconds - How long the challenge is valid (default: 300 = 5 minutes)
  */
 export declare function createChallenge(did: string, ttlSeconds?: number): Challenge;
+export interface BbsChallenge {
+    /** UUID, for idempotency and storage. */
+    id: string;
+    /**
+     * The verifier's AUTHENTICATED origin (e.g. its TLS hostname). Folded
+     * into the presentation header, so a proof made for this verifier
+     * fails at every other one.
+     */
+    domain: string;
+    /** The credential type this challenge accepts (pins the header cohort). */
+    credentialType: string;
+    /** Message indices the presenter must disclose. */
+    requiredIndices: number[];
+    /** 32-byte random hex — folded into the presentation header. */
+    nonce: string;
+    /** ISO 8601 */
+    issuedAt: string;
+    /** ISO 8601 */
+    expiresAt: string;
+}
+/**
+ * Create a DID-less selective-disclosure challenge. Carries no DID by
+ * construction — the verifier learns only what the disclosed indices say.
+ *
+ * The CALLER stores the challenge and must enforce single-use (mark it
+ * used once a presentation verifies) — the cryptographic ph binding kills
+ * cross-challenge replay, storage-side bookkeeping kills same-challenge
+ * re-submission.
+ */
+export declare function createBbsChallenge(opts: {
+    domain: string;
+    credentialType: string;
+    requiredIndices: number[];
+    ttlSeconds?: number;
+}): BbsChallenge;
 //# sourceMappingURL=challenge.d.ts.map

package/dist/challenge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"challenge.d.ts","sourceRoot":"","sources":["../src/challenge.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,SAAS;IACxB,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAA;IACV,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAA;IACX,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAA;IACb,eAAe;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,eAAe;IACf,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,SAAM,GAAG,SAAS,CAUxE"}
+{"version":3,"file":"challenge.d.ts","sourceRoot":"","sources":["../src/challenge.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,SAAS;IACxB,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAA;IACV,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAA;IACX,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAA;IACb,eAAe;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,eAAe;IACf,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,SAAM,GAAG,SAAS,CAUxE;AASD,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAA;IACV;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,2EAA2E;IAC3E,cAAc,EAAE,MAAM,CAAA;IACtB,mDAAmD;IACnD,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAA;IACb,eAAe;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,eAAe;IACf,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,MAAM,EAAE,MAAM,CAAA;IACd,cAAc,EAAE,MAAM,CAAA;IACtB,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,GAAG,YAAY,CA0Bf"}

package/dist/challenge.js

@@ -16,4 +16,43 @@ export function createChallenge(did, ttlSeconds = 300) {
         expiresAt: expiresAt.toISOString(),
     };
 }
+// ---------------------------------------------------------------------------
+// DID-less BBS challenge (privacy rebuild §5.3) — additive beside the
+// DID-bound challenge above; never a replacement.
+// ---------------------------------------------------------------------------
+import { ALWAYS_HIDDEN_KYC_INDICES } from './envelope.js';
+/**
+ * Create a DID-less selective-disclosure challenge. Carries no DID by
+ * construction — the verifier learns only what the disclosed indices say.
+ *
+ * The CALLER stores the challenge and must enforce single-use (mark it
+ * used once a presentation verifies) — the cryptographic ph binding kills
+ * cross-challenge replay, storage-side bookkeeping kills same-challenge
+ * re-submission.
+ */
+export function createBbsChallenge(opts) {
+    if (!opts.domain)
+        throw new Error('domain must be non-empty');
+    if (!opts.credentialType)
+        throw new Error('credentialType must be non-empty');
+    const forbidden = opts.requiredIndices.filter((i) => ALWAYS_HIDDEN_KYC_INDICES.includes(i));
+    if (forbidden.length > 0) {
+        throw new Error(`requiredIndices ${forbidden.join(',')} are always-hidden fields ` +
+            `(subject_did/verification_id/document_hash) and can never be requested`);
+    }
+    if (opts.requiredIndices.some((i) => !Number.isInteger(i) || i < 0)) {
+        throw new Error('requiredIndices must be non-negative integers');
+    }
+    const now = new Date();
+    const ttl = opts.ttlSeconds ?? 300;
+    return {
+        id: randomUUID(),
+        domain: opts.domain,
+        credentialType: opts.credentialType,
+        requiredIndices: [...opts.requiredIndices],
+        nonce: randomBytes(32).toString('hex'),
+        issuedAt: now.toISOString(),
+        expiresAt: new Date(now.getTime() + ttl * 1_000).toISOString(),
+    };
+}
 //# sourceMappingURL=challenge.js.map

package/dist/challenge.js.map

@@ -1 +1 @@
-{"version":3,"file":"challenge.js","sourceRoot":"","sources":["../src/challenge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAerD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,UAAU,GAAG,GAAG;IAC3D,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAA;IACtB,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,UAAU,GAAG,KAAK,CAAC,CAAA;IAC9D,OAAO;QACL,EAAE,EAAE,UAAU,EAAE;QAChB,GAAG;QACH,KAAK,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;QACtC,QAAQ,EAAE,GAAG,CAAC,WAAW,EAAE;QAC3B,SAAS,EAAE,SAAS,CAAC,WAAW,EAAE;KACnC,CAAA;AACH,CAAC"}
+{"version":3,"file":"challenge.js","sourceRoot":"","sources":["../src/challenge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAerD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,UAAU,GAAG,GAAG;IAC3D,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAA;IACtB,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,UAAU,GAAG,KAAK,CAAC,CAAA;IAC9D,OAAO;QACL,EAAE,EAAE,UAAU,EAAE;QAChB,GAAG;QACH,KAAK,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;QACtC,QAAQ,EAAE,GAAG,CAAC,WAAW,EAAE;QAC3B,SAAS,EAAE,SAAS,CAAC,WAAW,EAAE;KACnC,CAAA;AACH,CAAC;AAED,8EAA8E;AAC9E,sEAAsE;AACtE,kDAAkD;AAClD,8EAA8E;AAE9E,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAA;AAuBzD;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAKlC;IACC,IAAI,CAAC,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAA;IAC7D,IAAI,CAAC,IAAI,CAAC,cAAc;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAA;IAC7E,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CACjD,yBAA+C,CAAC,QAAQ,CAAC,CAAC,CAAC,CAC7D,CAAA;IACD,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,mBAAmB,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,4BAA4B;YAChE,wEAAwE,CAC3E,CAAA;IACH,CAAC;IACD,IAAI,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAA;IAClE,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAA;IACtB,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,IAAI,GAAG,CAAA;IAClC,OAAO;QACL,EAAE,EAAE,UAAU,EAAE;QAChB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,eAAe,EAAE,CAAC,GAAG,IAAI,CAAC,eAAe,CAAC;QAC1C,KAAK,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;QACtC,QAAQ,EAAE,GAAG,CAAC,WAAW,EAAE;QAC3B,SAAS,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,GAAG,GAAG,KAAK,CAAC,CAAC,WAAW,EAAE;KAC/D,CAAA;AACH,CAAC"}

package/dist/envelope.d.ts

@@ -0,0 +1,72 @@
+/**
+ * DID-less selective-disclosure presentation envelope (privacy rebuild §5.3).
+ *
+ * A `BbsSelectiveDisclosurePresentation` is what a wallet sends a relying
+ * party: a randomized BBS+ proof over the issuer-signed credential,
+ * disclosing exactly the requested message indices. By construction it has
+ * NO `holder` field, no subject DID, no per-credential identifier — the
+ * only things a verifier learns are "a valid credential from this issuer's
+ * (type, epoch) cohort" plus the disclosed claim values.
+ *
+ * DELIBERATE OMISSION vs the design sketch: the envelope does NOT carry
+ * the BBS header. The verifier RECONSTRUCTS the header from its own
+ * trusted (issuerDid, credentialType, epoch) — a header taken from the
+ * envelope would let a credential of a different cohort (e.g. a lower KYC
+ * level) satisfy a check whose policy expects another, and invites
+ * third-party RP implementations to skip policy binding entirely.
+ *
+ * Browser-safe: the wallet builds envelopes client-side — no node imports.
+ */
+/** Canonical KYC message order (frozen — mirrors verify's `buildKycMessageVector`). */
+export declare const KYC_MESSAGE_FIELDS: readonly ["subject_did", "issuer_did", "verification_id", "verified_at", "kyc_level", "country", "document_type", "document_hash"];
+/**
+ * Indices that must NEVER be disclosed (§5.2 disposition): the subject
+ * DID (the T2 handle), the per-credential verification id (the old
+ * header leak), and the per-document hash. Verifiers reject envelopes
+ * disclosing any of these even when the proof is cryptographically valid.
+ */
+export declare const ALWAYS_HIDDEN_KYC_INDICES: readonly [0, 2, 7];
+export declare const BBS_PRESENTATION_TYPE = "BbsSelectiveDisclosurePresentation";
+export interface DisclosedMessage {
+    /** Zero-based index in the original signed vector. */
+    index: number;
+    /** Hex-encoded message bytes. */
+    message: string;
+}
+export interface BbsSelectiveDisclosurePresentation {
+    type: typeof BBS_PRESENTATION_TYPE;
+    /** Credential-format version marker. */
+    v: 'bbs-v2';
+    /** The challenge this presentation answers. */
+    challengeId: string;
+    /** Issuer key-rotation epoch (cohort label — selects the pubkey). */
+    epoch: number;
+    /** Hex-encoded randomized BBS+ proof. */
+    proof: string;
+    totalMessageCount: number;
+    disclosed: DisclosedMessage[];
+    /** Re-recognition (mechanism B) only — §5.4. Null in one-shot mode. */
+    pairwiseDid: string | null;
+    /** VP signed by the pairwise key — §5.4. Null in one-shot mode. */
+    pairwiseProof: Record<string, unknown> | null;
+}
+export interface BuildBbsPresentationInput {
+    challengeId: string;
+    epoch: number;
+    proofHex: string;
+    totalMessageCount: number;
+    disclosed: DisclosedMessage[];
+    pairwiseDid?: string | null;
+    pairwiseProof?: Record<string, unknown> | null;
+}
+/** Build (and validate) a presentation envelope — wallet side. */
+export declare function buildBbsPresentation(input: BuildBbsPresentationInput): BbsSelectiveDisclosurePresentation;
+/** Parse + strictly validate a serialized envelope — verifier side. */
+export declare function parseBbsPresentation(json: string): BbsSelectiveDisclosurePresentation;
+/**
+ * Decode disclosed messages to named KYC fields (utf8). Only disclosed
+ * indices appear; always-hidden fields can never appear in a valid
+ * envelope (the verifier rejects them).
+ */
+export declare function decodeDisclosedKycFields(disclosed: DisclosedMessage[]): Partial<Record<(typeof KYC_MESSAGE_FIELDS)[number], string>>;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,uFAAuF;AACvF,eAAO,MAAM,kBAAkB,oIASrB,CAAA;AAEV;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,oBAAqB,CAAA;AAE3D,eAAO,MAAM,qBAAqB,uCAAuC,CAAA;AAEzE,MAAM,WAAW,gBAAgB;IAC/B,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAA;IACb,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,kCAAkC;IACjD,IAAI,EAAE,OAAO,qBAAqB,CAAA;IAClC,wCAAwC;IACxC,CAAC,EAAE,QAAQ,CAAA;IACX,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAA;IACnB,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAA;IACb,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAA;IACb,iBAAiB,EAAE,MAAM,CAAA;IACzB,SAAS,EAAE,gBAAgB,EAAE,CAAA;IAC7B,uEAAuE;IACvE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAC9C;AAQD,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,iBAAiB,EAAE,MAAM,CAAA;IACzB,SAAS,EAAE,gBAAgB,EAAE,CAAA;IAC7B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAC/C;AAED,kEAAkE;AAClE,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,yBAAyB,GAC/B,kCAAkC,CAcpC;AAED,uEAAuE;AACvE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,kCAAkC,CAwBrF;AAmDD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,gBAAgB,EAAE,GAC5B,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAa9D"}

package/dist/envelope.js

@@ -0,0 +1,153 @@
+/**
+ * DID-less selective-disclosure presentation envelope (privacy rebuild §5.3).
+ *
+ * A `BbsSelectiveDisclosurePresentation` is what a wallet sends a relying
+ * party: a randomized BBS+ proof over the issuer-signed credential,
+ * disclosing exactly the requested message indices. By construction it has
+ * NO `holder` field, no subject DID, no per-credential identifier — the
+ * only things a verifier learns are "a valid credential from this issuer's
+ * (type, epoch) cohort" plus the disclosed claim values.
+ *
+ * DELIBERATE OMISSION vs the design sketch: the envelope does NOT carry
+ * the BBS header. The verifier RECONSTRUCTS the header from its own
+ * trusted (issuerDid, credentialType, epoch) — a header taken from the
+ * envelope would let a credential of a different cohort (e.g. a lower KYC
+ * level) satisfy a check whose policy expects another, and invites
+ * third-party RP implementations to skip policy binding entirely.
+ *
+ * Browser-safe: the wallet builds envelopes client-side — no node imports.
+ */
+/** Canonical KYC message order (frozen — mirrors verify's `buildKycMessageVector`). */
+export const KYC_MESSAGE_FIELDS = [
+    'subject_did',
+    'issuer_did',
+    'verification_id',
+    'verified_at',
+    'kyc_level',
+    'country',
+    'document_type',
+    'document_hash',
+];
+/**
+ * Indices that must NEVER be disclosed (§5.2 disposition): the subject
+ * DID (the T2 handle), the per-credential verification id (the old
+ * header leak), and the per-document hash. Verifiers reject envelopes
+ * disclosing any of these even when the proof is cryptographically valid.
+ */
+export const ALWAYS_HIDDEN_KYC_INDICES = [0, 2, 7];
+export const BBS_PRESENTATION_TYPE = 'BbsSelectiveDisclosurePresentation';
+const HEX_RE = /^[0-9a-f]*$/i;
+function isHex(s) {
+    return HEX_RE.test(s) && s.length % 2 === 0;
+}
+/** Build (and validate) a presentation envelope — wallet side. */
+export function buildBbsPresentation(input) {
+    const envelope = {
+        type: BBS_PRESENTATION_TYPE,
+        v: 'bbs-v2',
+        challengeId: input.challengeId,
+        epoch: input.epoch,
+        proof: input.proofHex,
+        totalMessageCount: input.totalMessageCount,
+        disclosed: input.disclosed.map((d) => ({ index: d.index, message: d.message })),
+        pairwiseDid: input.pairwiseDid ?? null,
+        pairwiseProof: input.pairwiseProof ?? null,
+    };
+    assertEnvelopeShape(envelope);
+    return envelope;
+}
+/** Parse + strictly validate a serialized envelope — verifier side. */
+export function parseBbsPresentation(json) {
+    let raw;
+    try {
+        raw = JSON.parse(json);
+    }
+    catch {
+        throw new Error('presentation is not valid JSON');
+    }
+    if (typeof raw !== 'object' || raw === null) {
+        throw new Error('presentation must be a JSON object');
+    }
+    const e = raw;
+    const envelope = {
+        type: e['type'],
+        v: e['v'],
+        challengeId: e['challengeId'],
+        epoch: e['epoch'],
+        proof: e['proof'],
+        totalMessageCount: e['totalMessageCount'],
+        disclosed: e['disclosed'],
+        pairwiseDid: (e['pairwiseDid'] ?? null),
+        pairwiseProof: (e['pairwiseProof'] ?? null),
+    };
+    assertEnvelopeShape(envelope);
+    return envelope;
+}
+function assertEnvelopeShape(e) {
+    if (e.type !== BBS_PRESENTATION_TYPE) {
+        throw new Error(`presentation type must be ${BBS_PRESENTATION_TYPE}`);
+    }
+    if (e.v !== 'bbs-v2')
+        throw new Error('unsupported presentation version');
+    if (typeof e.challengeId !== 'string' || e.challengeId.length === 0) {
+        throw new Error('challengeId must be a non-empty string');
+    }
+    if (!Number.isInteger(e.epoch) || e.epoch < 0) {
+        throw new Error('epoch must be a non-negative integer');
+    }
+    if (typeof e.proof !== 'string' || e.proof.length === 0 || !isHex(e.proof)) {
+        throw new Error('proof must be non-empty hex');
+    }
+    if (!Number.isInteger(e.totalMessageCount) ||
+        e.totalMessageCount < 1 ||
+        e.totalMessageCount > 64) {
+        throw new Error('totalMessageCount out of range');
+    }
+    if (!Array.isArray(e.disclosed))
+        throw new Error('disclosed must be an array');
+    const seen = new Set();
+    for (const d of e.disclosed) {
+        if (typeof d !== 'object' ||
+            d === null ||
+            !Number.isInteger(d.index) ||
+            d.index < 0 ||
+            d.index >= e.totalMessageCount ||
+            typeof d.message !== 'string' ||
+            !isHex(d.message)) {
+            throw new Error('disclosed entries must be {index within range, hex message}');
+        }
+        if (seen.has(d.index))
+            throw new Error(`duplicate disclosed index ${d.index}`);
+        seen.add(d.index);
+    }
+    if (e.pairwiseDid !== null && (typeof e.pairwiseDid !== 'string' || e.pairwiseDid.length === 0)) {
+        throw new Error('pairwiseDid must be null or a non-empty string');
+    }
+    if (e.pairwiseProof !== null && (typeof e.pairwiseProof !== 'object' || Array.isArray(e.pairwiseProof))) {
+        throw new Error('pairwiseProof must be null or an object');
+    }
+    if ((e.pairwiseDid === null) !== (e.pairwiseProof === null)) {
+        throw new Error('pairwiseDid and pairwiseProof must be provided together');
+    }
+}
+/**
+ * Decode disclosed messages to named KYC fields (utf8). Only disclosed
+ * indices appear; always-hidden fields can never appear in a valid
+ * envelope (the verifier rejects them).
+ */
+export function decodeDisclosedKycFields(disclosed) {
+    const out = {};
+    const decoder = new TextDecoder();
+    for (const d of disclosed) {
+        const field = KYC_MESSAGE_FIELDS[d.index];
+        if (!field)
+            continue;
+        const bytes = new Uint8Array(d.message.length / 2);
+        for (let i = 0; i < bytes.length; i++) {
+            bytes[i] = parseInt(d.message.slice(i * 2, i * 2 + 2), 16);
+        }
+        out[field] = decoder.decode(bytes);
+    }
+    return out;
+}
+//# sourceMappingURL=envelope.js.map