@metalabel/dfos-client 0.30.0 → 0.31.0

package/README.md

@@ -6,8 +6,6 @@ If verification logic appears in this package, that is the bug: every proof come
 
 ## Install
 
-> **Not yet published — pre-release.** This package is `private` until it ships with a stamped release; until then it is consumable only inside this workspace.
-
 ```bash
 npm install @metalabel/dfos-client @metalabel/dfos-protocol @metalabel/dfos-web-relay
 ```
@@ -78,10 +76,30 @@ import { indexedDbStore, memoryStore } from '@metalabel/dfos-client/store';
 ### `@metalabel/dfos-client/siwd`
 
 ```typescript
-import { createSiwdChallenge, siwdSigningInput, verifySiwd } from '@metalabel/dfos-client/siwd';
+import {
+  createSiwdLoginRequest,
+  readSiwdCallback,
+  siwdSigningInput,
+  verifySiwd,
+} from '@metalabel/dfos-client/siwd';
+```
+
+Sign In With DFOS. The three verbs above are the relying-party login kit, in the order a login uses them: `createSiwdLoginRequest` mints the challenge and builds the `/authorize` URL to redirect to, `readSiwdCallback` parses what comes back, and `verifySiwd` verifies it — mint → redirect, read → verify. The `expect` object `createSiwdLoginRequest` returns (nonce, domain, and the DID when the challenge is bound to one) is what `verifySiwd` checks against, so the relying party MUST persist it across the redirect: a verifier that takes its expectation from the callback has implemented the check and none of the protection. See [`examples/siwd-demo`](../../examples/siwd-demo) for the reference consumer.
+
+In production, spend the nonce instead of comparing it:
+
+```typescript
+await verifySiwd(client, jws, {
+  domain,
+  consumeNonce: async (nonce) => (await store.getdel(nonce)) !== null,
+});
 ```
 
-Sign In With DFOS. `siwdSigningInput(challenge)` is the pure byte contract both the signer and the verifier share (see [SIWD.md](../../specs/SIWD.md)); `verifySiwd` is a no-throw verifier that accepts only a current `authKeys` entry of a non-deleted identity.
+`consumeNonce` replaces `expect.nonce` (supply exactly one) and returns true iff **this** verifier minted the nonce and it was unspent — membership in verifier-minted state is what satisfies the spec's rule that the verifier MUST have minted the nonce it checks, and deleting it in the same operation is what makes it single-use. The atomicity is the caller's: a get-then-delete lets two concurrent replays both win, where a Redis `GETDEL` or a `DELETE … RETURNING` does not. It is called at most once, and only after every other check has passed, so an invalid presentation can never burn a nonce the user is still holding.
+
+`createSiwdLoginRequest` throws rather than returning an error on the two things that are RP misconfiguration: an `authorizeUrl` or `redirectUri` that is not an absolute URL, and any scope other than `identity` over a loopback redirect (a local port holds no `client_did` for a credential to be issued to — see [SIWD.md](../../specs/SIWD.md)).
+
+`siwdSigningInput(challenge)` is the pure byte contract both the signer and the verifier share (see [SIWD.md](../../specs/SIWD.md)); `createSiwdChallenge` mints a challenge on its own for a caller building its own redirect; `verifySiwd` is a no-throw verifier that accepts only a current `authKeys` entry of a non-deleted identity.
 
 ## License
 

package/dist/siwd.d.ts

@@ -103,7 +103,10 @@ interface SiwdLoginRequest {
      * a `domain` or `did` that drifts between mint and verify is a check that
      * silently stops checking.
      *
-     * SINGLE USE: consume the nonce on the way back, pass or fail.
+     * SINGLE USE: consume the nonce on the way back, pass or fail. A backend
+     * holding its minted nonces in shared state should hand `verifySiwd` a
+     * `consumeNonce` instead of this object's `nonce`, so the consumption is
+     * atomic and is the last thing that happens before a session is granted.
      *
      * WHOEVER VERIFIES MUST HAVE MINTED. A verifier that accepts an expectation
      * supplied by the party presenting the JWS is comparing a value against
@@ -111,8 +114,14 @@ interface SiwdLoginRequest {
      * expectation comes from the verifier's own prior state (this object, held
      * server-side or in the session that began the sign-in) or from an
      * independent validation of it.
+     *
+     * `nonce` is REQUIRED here even though `SiwdExpectations` leaves it optional
+     * for the `consumeNonce` form: what this function mints into the challenge is
+     * always a string, and an RP persisting this object must get it back.
      */
-    expect: Pick<SiwdExpectations, 'domain' | 'nonce' | 'did'>;
+    expect: Pick<SiwdExpectations, 'domain' | 'did'> & {
+        nonce: string;
+    };
     /** base64url canonical challenge bytes, exactly as embedded in `url`. */
     challenge: string;
     /** ISO whole-second mint timestamp, exactly as embedded in the signed bytes. */
@@ -131,15 +140,22 @@ interface SiwdLoginRequest {
  * not downgraded, so the param is dropped here instead of being forwarded into
  * a guaranteed refusal.
  *
+ * The same judgment BOUNDS THE SCOPE. Every scope past `identity` returns a
+ * credential issued to a `client_did` — the one param a loopback request cannot
+ * carry — so specs/SIWD.md admits a loopback target for `scope=identity` only.
+ * Asking for more from a local port is not a downgrade the way `client_did` is;
+ * there is nothing to drop, so it throws.
+ *
  * It also owns the WIRE PARAM NAMES (`challenge`, `redirect_uri`, `scope`,
  * `client_did`) as their single source in this package. They are snake_case on
  * the wire and camelCase everywhere else, which is exactly the kind of seam
  * every hand-rolled RP re-implements and eventually gets wrong.
  *
  * PURE: no DOM, no storage, no navigation, no fetch — identical in a browser
- * and in Node. Throws on an unparseable `authorizeUrl` or `redirectUri`,
- * because those are mistakes in the RP's own configuration rather than runtime
- * conditions a result type would help a caller recover from.
+ * and in Node. Throws on an unparseable `authorizeUrl` or `redirectUri`, and on
+ * a non-`identity` scope over a loopback redirect, because those are mistakes
+ * in the RP's own configuration rather than runtime conditions a result type
+ * would help a caller recover from.
  */
 declare const createSiwdLoginRequest: (input: SiwdLoginRequestInput) => SiwdLoginRequest;
 /**
@@ -214,8 +230,26 @@ declare const validateSiwdSignRequest: (jwsToken: string, options: ValidateSiwdS
 interface SiwdExpectations {
     /** The verifier's own origin — MUST match the challenge domain. */
     domain: string;
-    /** The nonce this verifier issued for the session. */
-    nonce: string;
+    /**
+     * The nonce this verifier issued for the session. Supply EXACTLY ONE of
+     * `nonce` and `consumeNonce`.
+     */
+    nonce?: string;
+    /**
+     * Atomically consume the presented nonce against verifier-minted state — a
+     * Redis `GETDEL`, a `DELETE … RETURNING` row — returning true iff THIS
+     * verifier minted it and it was unspent. Membership in the verifier's own
+     * minted state is what proves the verifier minted it, which is the whole
+     * check; an equality test against a `nonce` fed in from the presented
+     * artifact is a value compared against itself. The ATOMICITY is yours: a
+     * get-then-delete lets two concurrent replays both win.
+     *
+     * Called AT MOST ONCE, and only after every other check has passed —
+     * signature, current-key resolution, did binding, domain, timestamp — so an
+     * otherwise-invalid presentation can never burn a live nonce, and the
+     * consumption is the last gate before the caller grants anything.
+     */
+    consumeNonce?: (nonce: string) => boolean | Promise<boolean>;
     /** If set, the challenge (and identity) MUST bind to this DID. */
     did?: string;
     /** If set, the signed challenge's timestamp MUST equal this exact value. */

package/dist/siwd.js

@@ -124,6 +124,10 @@ var parseUrlOrThrow = (value, field) => {
 var createSiwdLoginRequest = (input) => {
   const authorizeUrl = parseUrlOrThrow(input.authorizeUrl, "authorizeUrl");
   const redirect = parseUrlOrThrow(input.redirectUri, "redirectUri");
+  const isLoopback = SIWD_LOOPBACK_HOSTS.has(bareHostname(redirect));
+  if (isLoopback && input.scope !== "identity") {
+    throw new Error("invalid SIWD login request: loopback redirects support scope=identity only");
+  }
   const { challenge, encoded, nonce } = createSiwdChallenge({
     domain: input.domain,
     ...input.statement !== void 0 ? { statement: input.statement } : {},
@@ -134,7 +138,7 @@ var createSiwdLoginRequest = (input) => {
   url.searchParams.set("challenge", encoded);
   url.searchParams.set("redirect_uri", input.redirectUri);
   url.searchParams.set("scope", input.scope);
-  if (input.clientDid !== void 0 && !SIWD_LOOPBACK_HOSTS.has(bareHostname(redirect))) {
+  if (input.clientDid !== void 0 && !isLoopback) {
     url.searchParams.set("client_did", input.clientDid);
   }
   return {
@@ -233,6 +237,9 @@ var validateSiwdSignRequest = async (jwsToken, options) => {
 var fail = (error) => ({ ok: false, error });
 var verifySiwd = async (client, jws, expect) => {
   try {
+    if (expect.nonce === void 0 === (expect.consumeNonce === void 0)) {
+      return fail("provide exactly one of nonce or consumeNonce");
+    }
     const decoded = decodeJwsUnsafe(jws);
     if (!decoded) return fail("failed to decode JWS");
     const rawHeader = decoded.header;
@@ -275,7 +282,6 @@ var verifySiwd = async (client, jws, expect) => {
     } catch (err) {
       return fail(err instanceof Error ? err.message : "invalid signature");
     }
-    if (payload.nonce !== expect.nonce) return fail("nonce mismatch");
     if (payload.domain !== expect.domain) return fail("domain mismatch");
     if (expect.timestamp !== void 0 && payload.timestamp !== expect.timestamp) {
       return fail("timestamp does not match expected challenge timestamp");
@@ -288,6 +294,13 @@ var verifySiwd = async (client, jws, expect) => {
     if (issuedMs - nowMs > MAX_CLOCK_SKEW_SECONDS * 1e3) {
       return fail("challenge timestamp is in the future");
     }
+    if (expect.consumeNonce !== void 0) {
+      if (!await expect.consumeNonce(payload.nonce)) {
+        return fail("nonce already used or not recognized");
+      }
+    } else if (payload.nonce !== expect.nonce) {
+      return fail("nonce mismatch");
+    }
     const session = {
       did,
       domain: payload.domain,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalabel/dfos-client",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "type": "module",
   "description": "DFOS Client — read-only resolve + verify orchestration over untrusted relays. Fetch, resolve, verify-orchestration, cache; all crypto truth comes from @metalabel/dfos-protocol",
   "license": "MIT",
@@ -43,15 +43,15 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@metalabel/dfos-protocol": "^0.30.0",
-    "@metalabel/dfos-web-relay": "^0.30.0"
+    "@metalabel/dfos-protocol": "^0.31.0",
+    "@metalabel/dfos-web-relay": "^0.31.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.4",
     "tsup": "^8.5.1",
     "vitest": "^4.1.8",
-    "@metalabel/dfos-protocol": "0.30.0",
-    "@metalabel/dfos-web-relay": "0.30.0"
+    "@metalabel/dfos-protocol": "0.31.0",
+    "@metalabel/dfos-web-relay": "0.31.0"
   },
   "scripts": {
     "build": "tsup",