@solidus-network/auth 0.6.1 → 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@solidus-network/auth",
-  "version": "0.6.1",
-  "description": "DID-based authentication for the Solidus Network protocol — Ed25519 challenge / W3C Verifiable Presentation verification primitives.",
+  "version": "0.6.2",
+  "description": "DID-based authentication and DID-less BBS+ selective-disclosure verification for the Solidus Network protocol — Ed25519 challenge/response, unlinkable presentation envelopes, and the relying-party issuer-key resolver.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -9,22 +9,54 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./envelope": {
+      "import": "./dist/envelope.js",
+      "types": "./dist/envelope.d.ts"
+    },
+    "./pairwise": {
+      "import": "./dist/pairwise.js",
+      "types": "./dist/pairwise.d.ts"
     }
   },
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "demo",
+    "README.md",
+    "LICENSE"
+  ],
   "dependencies": {
+    "@solidus-network/types": "0.6.2",
+    "@solidus-network/bbs": "0.6.2",
     "@noble/ed25519": "^2.1.0",
-    "@noble/hashes": "^1.5.0"
+    "@noble/hashes": "^1.5.0",
+    "bs58": "^6.0.0"
   },
-  "keywords": ["solidus", "did", "authentication", "decentralized-identity", "ed25519", "verifiable-presentation", "challenge-response"],
+  "keywords": [
+    "solidus",
+    "did",
+    "authentication",
+    "decentralized-identity",
+    "ed25519",
+    "challenge-response",
+    "signature",
+    "bbs",
+    "selective-disclosure",
+    "unlinkability",
+    "verifiable-presentation"
+  ],
   "author": "Solidus Network (https://solidus.network)",
   "license": "Apache-2.0",
   "homepage": "https://solidus.network",
-  "bugs": { "url": "https://github.com/solidusnetwork/sdk/issues" },
+  "bugs": {
+    "url": "https://github.com/solidusnetwork/sdk/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/solidusnetwork/sdk.git",
     "directory": "auth"
   },
-  "publishConfig": { "access": "public" }
+  "publishConfig": {
+    "access": "public"
+  }
 }