@ixo/credentials-kit 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,470 @@
-# Temporary Holding Version
+# @ixo/credentials-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The shared library of IXO Credentials: SD-JWT VC (`dc+sd-jwt`, Ed25519: signs with JWS `alg`
+`EdDSA`, accepts `EdDSA` and `Ed25519`), OpenID4VCI 1.0 (pre-authorized code flow), OpenID4VP 1.0
+(signed request objects, DCQL subset, encrypted `direct_post.jwt` responses with `A128GCM` or
+`A256GCM`, error responses, `openid4vp://` wallet links), IETF Token Status List, `did:ixo` /
+`did:web` resolution and the signed webhook between the Credentials worker and the Hub. The
+normative profile is `docs/profile.md` (SPEC §3, §13.3).
+
+- ESM only, TypeScript types included, `sideEffects: false`.
+- Runs unchanged in Cloudflare workerd, Node 22+ and browsers: WebCrypto, `CompressionStream`,
+  `fetch`; no Node built-ins. Runtime dependencies: `@noble/curves`, `@noble/hashes`.
+- Everything that reaches the network takes `fetch` (and optionally a cache) as an argument,
+  never follows redirects and always times out. A Cloudflare KV binding works as a cache as is.
+- Every `now` option is milliseconds since the epoch (`Date.now()`, the clock you read; a value
+  that looks like seconds throws `TypeError`); every timestamp the kit returns or puts in an API
+  shape (`expiresAt`, `created_at`, JWT claims) is unix seconds.
+- Outbound URLs and did:web hosts must be https on a public host (`isFetchableUrl`, exported
+  from `/did`). Loopback, private, link-local, CGNAT, unique-local and multicast IP literals
+  (also inside 6to4, NAT64, Teredo, IPv4-mapped and IPv4-translated IPv6), single-label names
+  (`intranet`) and `localhost`, `*.localhost`, `*.local`, `*.internal`, `*.lan`, `*.home.arpa`,
+  `*.home`, `*.corp`, `*.intranet`, `*.private`, `*.localdomain` are refused unless you pass
+  `allowLocal: true` (local development only; `http://localhost` needs `allowHttp: true` as
+  well). Names are not resolved: DNS rebinding to a private address still needs the runtime's
+  egress policy (Cloudflare Workers cannot reach private networks; a Node or browser wallet
+  should add its own).
+
+| Subpath                        | What                                                                        |
+| ------------------------------ | --------------------------------------------------------------------------- |
+| `@ixo/credentials-kit/jose`    | Ed25519 compact JWS, Ed25519 key helpers, `Signer`                          |
+| `@ixo/credentials-kit/did`     | DID documents, `did:ixo` (Blocksync) and `did:web` resolvers, key selection |
+| `@ixo/credentials-kit/sdjwt`   | SD-JWT parse / serialize / select, `sd_hash`, the Vault record and its CID  |
+| `@ixo/credentials-kit/status`  | Token Status List: bits, tokens, verification                               |
+| `@ixo/credentials-kit/verify`  | `verifyPresentation` (verifier), `verifyIssuedCredential` (wallet)          |
+| `@ixo/credentials-kit/oid4vci` | issuer metadata, offers, proof JWTs, `redeemOffer` (wallet, checks result)  |
+| `@ixo/credentials-kit/oid4vp`  | request objects, DCQL subset, presentations, responses, errors, links       |
+| `@ixo/credentials-kit/webhook` | `x-ixo-signature` sign / verify                                             |
+| `@ixo/credentials-kit/profile` | constants (UCAN resource, abilities, media types, events) and shared types  |
+| `@ixo/credentials-kit/display` | card look: validate an issuer's `display`, WCAG contrast, the neutral card  |
+| `@ixo/credentials-kit/holder`  | the person's block list at the Credentials worker (`credentials/hold`)      |
+
+The root export re-exports all of them.
+
+## Keys and resolvers (every role)
+
+```ts
+import {
+  ed25519SeedFromMnemonic,
+  signerFromEd25519Seed,
+  base58btc,
+} from '@ixo/credentials-kit/jose';
+import {
+  composeResolvers,
+  createIxoResolver,
+  createWebResolver,
+} from '@ixo/credentials-kit/did';
+
+const seed = ed25519SeedFromMnemonic(env.ISSUER_ED25519_MNEMONIC); // IXO service convention
+const probe = signerFromEd25519Seed(seed, 'tmp');
+const signer = signerFromEd25519Seed(
+  seed,
+  `${env.ISSUER_DID}#${base58btc.encode(probe.publicKey)}`
+);
+
+const resolver = composeResolvers(
+  createIxoResolver({
+    blocksyncUrl: env.BLOCKSYNC_GRAPHQL_URL,
+    fetch,
+    cache: env.CACHE_KV,
+  }),
+  // Local development only: http on localhost AND local hosts. Production passes neither.
+  createWebResolver({ fetch, allowHttp: isLocal, allowLocal: isLocal })
+);
+```
+
+A resolver returns `null` for a DID that does not exist and throws `ResolverUnavailable` when its
+source cannot be read: answer 503, never "no".
+
+did:web follows the [did:web method spec](https://w3c-ccg.github.io/did-method-web/) (`didWebUrl`,
+used by the web resolver): `did:web:<host>` → `https://<host>/.well-known/did.json`,
+`did:web:<host>:<a>:<b>` → `https://<host>/a/b/did.json`, a port percent-encoded
+(`did:web:example.com%3A3000:user:alice` → `https://example.com:3000/user/alice/did.json`). Any
+host works (a subdomain is fine) and any path; the document's `id` must equal the DID. Plain http
+only for `localhost` and only with `allowHttp` + `allowLocal` (local development).
+
+did:web is accepted only in canonical form (`parseDidWeb`), so one DID has one spelling: a
+lower-case host, no trailing dot, no percent-encoding in the host except `%3A` before a port, never
+`%3A443` (the port `https` already implies) or a port with a leading zero, no lower-case `%3a`, an
+IDN in punycode, no IP address (the spec: "MUST NOT include IP addresses"), and path segments made
+of DID characters (letters, digits, `.`, `-`, `_`, percent-encoding; never an encoded `/`, `\`,
+`.` or `..`). In a path segment, percent-encoding uses upper-case hex only and never encodes an
+unreserved character (`%61lice` is `alice`, so it is refused; a `~` cannot be written), and a
+`.well-known` segment is refused (it would read the bare host's document). Any other spelling gets
+`null` from `parseDidWeb` and `didWebUrl` (and so resolves to `null`). `parseDidWeb(did)` returns `{ host, port?, authority, path }`.
+
+## Issuer
+
+```ts
+import {
+  createStatusListToken,
+  newStatusBits,
+  setStatusBit,
+} from '@ixo/credentials-kit/status';
+import {
+  buildIssuerMetadata,
+  buildAuthorizationServerMetadata,
+  buildCredentialOffer,
+  verifyProofJwt,
+} from '@ixo/credentials-kit/oid4vci';
+
+// Status list, published to the Credentials worker (PUT /status/{issuerDid}/{listId}).
+const bits = newStatusBits(16_384);
+setStatusBit(bits, revokedIndex);
+const token = await createStatusListToken({
+  bits,
+  uri: `${CREDENTIALS_URL}/status/${ISSUER_DID}/${listId}`,
+  iss: ISSUER_DID,
+  signer,
+  ttl: 300,
+  exp: nowS + 86_400,
+});
+
+// OpenID4VCI: serve both metadata documents (the token endpoint is in the OAuth server
+// metadata), serve the offer at your credential_offer_uri (a fresh code per GET), check the proof.
+const metadata = buildIssuerMetadata({
+  credentialIssuer: 'https://host/identity',
+  configurations: { IdentityLevel1: { vct } },
+});
+const asMetadata = buildAuthorizationServerMetadata({
+  issuer: 'https://host/identity',
+});
+const offer = buildCredentialOffer({
+  credentialIssuer: 'https://host/identity',
+  configurationIds: ['IdentityLevel1'],
+  preAuthorizedCode,
+});
+const proof = await verifyProofJwt(body.proofs.jwt[0], {
+  audience: 'https://host/identity',
+  nonce: checkMyNonce,
+  resolver,
+});
+if (
+  proof.did !== verification.subjectDid
+) /* 400 invalid_proof: subject binding */ ;
+// mint with cnf = { jwk: proof.jwk }
+```
+
+`verifyProofJwt` throws `Oid4vciError` whose `code` is the spec's error (`invalid_proof` /
+`invalid_nonce`), ready for the error response. It checks the signature before it calls your
+`nonce` callback, so a single-use nonce store is only consulted for a proof the holder signed.
+
+## Verifier
+
+```ts
+import {
+  createAuthorizationRequest,
+  decodeOwnAuthorizationRequest,
+  generateResponseKeyPair,
+  parseAuthorizationResponse,
+  verifyAuthorizationResponse,
+} from '@ixo/credentials-kit/oid4vp';
+import { createMemoryCache } from '@ixo/credentials-kit/did';
+
+const { publicJwk, privateJwk } = await generateResponseKeyPair(); // keep privateJwk with the request
+const request = await createAuthorizationRequest({
+  signer,
+  clientDid: MY_DID,
+  responseUri: `https://me/response/${id}`,
+  nonce: randomNonce,
+  state: id,
+  exp: nowS + 900,
+  responseEncryptionJwk: publicJwk,
+  dcql: {
+    credentials: [
+      {
+        id: 'age',
+        format: 'dc+sd-jwt',
+        meta: { vct_values: [VCT] },
+        claims: [
+          { path: ['age_over_18'], values: [true] },
+          { path: ['iss'], values: TRUSTED_ISSUERS },
+        ],
+      },
+    ],
+  },
+});
+// … deposit at the Credentials worker; later, at the response URI:
+const { vpToken, state } = await parseAuthorizationResponse(await req.text(), {
+  decryptionKey: privateJwk,
+  request: decodeOwnAuthorizationRequest(request), // makes the key mandatory
+});
+const { ok, results, holderAuthenticated } = await verifyAuthorizationResponse({
+  vpToken,
+  request,
+  state, // required when the request has one
+  policyFor: () => ({
+    issuers: TRUSTED_ISSUERS,
+    vcts: [VCT],
+    expectedSubject: subjectDid,
+  }),
+  deps: { resolver, fetch, statusCache: env.CACHE_KV },
+});
+if (!holderAuthenticated) {
+  // Could have come from anyone holding the (public) request object: keep the request open.
+} else {
+  // The person answered for THIS nonce: record ok / the failure code, once.
+}
+```
+
+Anyone who can read a request object (its `request_uri` is public) can build a response that
+decrypts and carries the right `state`. Only `holderAuthenticated: true` (trusted issuer, valid
+signature, key binding for this request's nonce and audience, AND `expectedSubject` given and
+matched) proves the person you asked sent it; close your request only then
+(`examples/verifier` shows how). Without `expectedSubject`, `holderAuthenticated` is always
+`false`: anyone holding a credential from an accepted issuer could answer. `keyBindingValid`
+reports the weaker fact ("the holder of the presented credential signed for this nonce"); never
+close a request on it alone. A subject-less flow needs a different binding (OpenID4VP §14.2:
+a redirect URI with a response code tied to the browser session).
+
+`verifyPresentation` (in `/verify`) is the same check for one presentation outside OpenID4VP. When
+key binding is required (the default) it needs `audience` and `nonce` (a `TypeError` otherwise):
+pass the nonce you issued for this check, or a callback `nonce => boolean` that accepts each
+issued nonce once. There is no "accept any nonce". It returns `{ ok: false, code,
+holderAuthenticated, keyBindingValid }` for every refusal and throws `VerificationUnavailable` when the issuer's DID
+document or the status list cannot be read or verified (fail closed: answer 503). Status lists are
+fetched without following redirects (a deliberate rule; TSL §8.2 only RECOMMENDS following them).
+
+## Wallet
+
+```ts
+import { redeemOffer, sendNotification } from '@ixo/credentials-kit/oid4vci';
+import {
+  authorizationErrorFor,
+  createAuthorizationResponse,
+  createPresentation,
+  matchCredential,
+  parseWalletLink,
+  sendAuthorizationError,
+  verifyAuthorizationRequest,
+} from '@ixo/credentials-kit/oid4vp';
+import {
+  parseSdJwt,
+  credentialRecordFromSdJwt,
+  credentialCid,
+} from '@ixo/credentials-kit/sdjwt';
+
+// Issuance.
+// Offers travel by reference: fetched fresh on every call (single-use code), never cached.
+// redeemOffer checks what it receives (verifyIssuedCredential: the issuer's signature, iss, sub =
+// the holder, cnf = the holder's key, vct, validity, disclosures) and throws
+// Oid4vciError('invalid_credential') instead of returning a credential that does not check out.
+const out = await redeemOffer({
+  credentialOfferUri: offer.credential_offer_uri,
+  signer: userSigner, // kid = a DID URL of the holder; publicKey when it has one
+  resolver, // resolves the issuer (and the holder key when the signer has no publicKey)
+  // REQUIRED: the DID that deposited the offer. `false` accepts any issuer (unsafe: anyone can
+  // mint a credential with your vct; judge out.verified.issuer yourself).
+  expectedIssuer: offer.issuer,
+  fetch,
+});
+if (out.status === 'issued') {
+  const record = credentialRecordFromSdJwt(out.credential, {
+    holderDid: userDid,
+    issuerName,
+  });
+  await vault.store({ record, cid: credentialCid(record) });
+  if (out.notificationId && out.notificationEndpoint) {
+    await sendNotification({
+      notificationEndpoint: out.notificationEndpoint,
+      accessToken: out.accessToken,
+      notificationId: out.notificationId,
+      event: 'credential_accepted',
+      fetch,
+    });
+  }
+}
+
+// Presentation. A link from a non-Hub verifier: openid4vp://?client_id=…&request_uri=…
+// request_uri must pass isFetchableUrl (https, public host); local development passes
+// { allowHttp: true, allowLocal: true }.
+const link = parseWalletLink(scannedLink);
+// Your fetch: no redirects, a timeout, a size cap. Request objects from scanned links should
+// also be checked with requireExpiry: true below.
+const requestJwt = await fetchRequestObject(link.requestUri);
+let request;
+try {
+  request = await verifyAuthorizationRequest(requestJwt, {
+    resolver,
+    expectedClientId: link.clientId, // §5.10.1: must be identical
+    requireExpiry: true,
+  });
+} catch (e) {
+  // A verified request we cannot answer (credential_sets, claim_sets, …): tell the verifier.
+  const error = authorizationErrorFor(e);
+  if (error)
+    await sendAuthorizationError({ target: e.errorTarget, error, fetch });
+  throw e;
+}
+const query = request.dcql.credentials[0];
+const match = matchCredential(query, parseSdJwt(record.credential));
+if (match.ok) {
+  const vp = await createPresentation({
+    sdjwt: record.credential,
+    disclose: match.disclose,
+    signer: userSigner,
+    audience: request.clientId,
+    nonce: request.nonce,
+  });
+  const { url, body, contentType } = await createAuthorizationResponse({
+    request,
+    vpToken: { [query.id]: [vp] },
+  });
+  await fetch(url, {
+    method: 'POST',
+    headers: { 'content-type': contentType },
+    body,
+    redirect: 'manual',
+  });
+} else {
+  // After the person decided (OpenID4VP §15.9: never before, it would reveal what they hold).
+  await sendAuthorizationError({
+    target: request,
+    error: 'access_denied',
+    fetch,
+  });
+}
+```
+
+Verifiers build the link for other wallets with
+`buildWalletLink({ clientId, requestUri, scheme = 'openid4vp://' })`.
+
+### Blocking a sender (SPEC §16.1)
+
+A person can block any issuer or verifier at the Credentials worker (the gateway): its waiting
+offers and requests for the person are closed as declined, and its later deposits are refused
+(the sender gets 403 `blocked`, "This person is not accepting offers or requests from you.").
+One list for issuers and verifiers. A block is of exactly the DID named (every DID is its own
+sender: blocking `did:web:a.example.com` does not block `did:web:b.example.com` or
+`did:web:example.com:x`), and the list's `sender` is that DID. At most 500 per person. Each call needs a fresh single-use UCAN invocation as the person (`credentials/hold` on
+`ixo:credentials`, audience the worker's did:web) bound to that request: you mint it in
+`authorize`, the kit tells you the `{ method, path }` to bind.
+
+```ts
+import { createInvocation, serializeInvocation } from '@ixo/ucan';
+import {
+  blockSender,
+  listBlocks,
+  unblockSender,
+} from '@ixo/credentials-kit/holder';
+
+const service = {
+  serviceUrl: 'https://credentials.ixo.world',
+  fetch,
+  authorize: async binding =>
+    serializeInvocation(
+      await createInvocation({
+        issuer: personUcanSigner,
+        audience: workerDid, // from <serviceUrl>/.well-known/did.json
+        capability: { can: 'credentials/hold', with: 'ixo:credentials' },
+        expiration: Math.floor(Date.now() / 1000) + 120,
+        facts: [{ ...binding, nonce: crypto.randomUUID() }],
+      })
+    ),
+};
+const { closed } = await blockSender({ ...service, sender: issuerDid });
+const page = await listBlocks({ ...service, limit: 50 }); // { items, next_cursor }
+await unblockSender({ ...service, sender: issuerDid }); // { sender, removed }
+```
+
+A refusal throws `CredentialsServiceError` (`code` = the worker's error code, `status`,
+`reference`); a network failure, a timeout, a redirect or an answer whose body fails half way is
+`unreachable` (`status` null for all but a redirect). A `sender` that `senderKeyOf` refuses throws
+`TypeError` before anything is sent (such a block could never match).
+
+### Sender keys (SPEC §17.4)
+
+`@ixo/credentials-kit/sender` says who a sender is, the way the worker counts caps, blocks and
+catalog entries: every DID is its own sender, exactly as written.
+
+- `senderKeyOf(did)`: the DID itself when it is a did:ixo person (`did:ixo:ixo1…`, lower-case
+  bech32, `IXO_PERSON_DID`) or entity (`did:ixo:entity:` + 32 lower-case hex, `IXO_ENTITY_DID`),
+  or a did:web in canonical form (`parseDidWeb`). `did:web:example.com`, `did:web:a.example.com`
+  and `did:web:example.com:user:alice` are three senders. Null for any other did:ixo
+  (`did:ixo:IXO1…`, `did:ixo:anything`) or did:web spelling (refuse it), and for other methods.
+  The bech32 checksum is not verified (no bech32 decoder in the kit); a DID with a bad checksum
+  never resolves, so it never deposits anything.
+
+Wallets: show a sender by its DID (offers and requests carry `sender_key`, the sender's DID), and
+before storing a credential check `senderKeyOf(iss)` (the exact DID) against the person's blocks.
+
+### Card look (SPEC §15.1)
+
+Pure functions, no fetch. The look comes only from the issuer's catalog entry
+(`types[].display`, and `logo_uri` / `color` for its mark); an offer carries none (SPEC §16.1).
+Validate what the entry says, then draw the card (a neutral one from the DID when nothing is
+set). The image URLs are only validated: fetch them yourself under your own
+rules (png, jpeg or webp; never SVG). `parseCardUri` takes an image address only when it is https
+on the default port with no query string and no fragment (no credentials, a public host, at most
+512 characters): a per-person query string would turn the image into a tracking pixel, and an odd
+port would turn your image proxy into a fetch relay. `{ allowHttp: true, allowLocal: true }` (local
+development only) also takes http and any port on a loopback host, still without a query string
+or fragment.
+
+```ts
+import {
+  cardLook,
+  markLook,
+  parseCardDisplay,
+} from '@ixo/credentials-kit/display';
+
+const type = entry.types.find(t => t.vct === credentialVct);
+const display = parseCardDisplay(type?.display); // bad and unknown members dropped
+const look = cardLook({
+  display,
+  issuerDid: entry.did,
+  issuerName: entry.name,
+});
+// { background: '#0b6b7e', foreground: '#ffffff', monogram: 'IS', pattern: 3 }
+const mark = markLook({ color: entry.color, did: entry.did, name: entry.name });
+// { color: '#5b21b6', monogram: 'YR' }
+```
+
+## Choices to know about
+
+- Disclosures are processed per RFC 9901 §7.1, recursively (nested objects, array elements);
+  `_sd`, `_sd_alg` and `...` never reach `claims`; a repeated digest, an unreferenced disclosure,
+  or a claim named `__proto__` / `constructor` / `prototype` fails. `iss`, `nbf`, `exp`, `cnf`,
+  `vct`, `vct#integrity`, `aka_vcts` and `status` are never accepted from a disclosure
+  (SD-JWT VC §2.2.2.3); `sub` and `iat` may be disclosed. Every credential needs `exp` and a
+  `sub`.
+- DCQL: unknown members are ignored, duplicate claim queries dropped, `multiple: true` answered
+  with one presentation. `credential_sets`, `claim_sets`, `trusted_authorities`, multi-segment
+  paths and formats other than `dc+sd-jwt` are refused with `unsupported_request` (and
+  `error.feature`). Claim paths are exact: a one-segment path names the TOP-LEVEL claim only.
+  `matchCredential`, `selectDisclosures` and `createPresentation` never release a nested
+  disclosure that happens to carry the same name, and the Vault record
+  (`credentialRecordFromSdJwt`) keeps nested disclosures inside their parent's value. A requested
+  `sub` or `iat` is answered from the issuer-signed credential.
+- The Vault index slot (`stateKeyForVct`) is chosen by the FULL `vct`, exact match: known types
+  keep their slot (`identitylevel1`, `kycamllevel1`), any other `vct` gets `vct-<hash>`.
+- Request objects without `exp`, `iat` or `aud` are accepted by the wallet (the spec's examples
+  have none); each one that is present is enforced (lifetime at most 24 h, `aud` the static
+  `https://self-issued.me/v2`). The verifier side always writes all three.
+- Status values other than 0 are reported as `revoked`; an index outside the list is `no_status`.
+- Webhooks: a signature older than 5 minutes or more than 60 s in the future is refused. A
+  signed webhook still verifies again within that window: de-duplicate on the event `id`.
+
+## Errors
+
+Every error extends `CredentialsKitError` with a constant `code` (`JoseError`, `SdJwtError`,
+`StatusListError`, `Oid4vciError`, `Oid4vpError`, `ResolverUnavailable`,
+`VerificationUnavailable`). Messages are fixed sentences: they never contain credentials, keys or
+tokens, so they are safe to log. They are for logs, not for end users.
+
+## Development
+
+```sh
+pnpm --filter @ixo/credentials-kit build       # tsup → dist/ (ESM + .d.ts)
+pnpm --filter @ixo/credentials-kit type-check
+pnpm --filter @ixo/credentials-kit lint
+pnpm --filter @ixo/credentials-kit test        # vitest, Node
+```
+
+`test/self-interop.test.ts` mints a credential and a status list with Self's own issuer code when
+the ixo-self checkout is present (`UPDATE_SELF_FIXTURE=1` refreshes the committed fixture) and
+always checks the committed fixture.
+
+Install from npm: `pnpm add @ixo/credentials-kit` (or `npm install`). Inside this repo the worker
+and the examples use `workspace:*`. How a version is released: `packages/kit/RELEASING.md` in the
+repository.