@metalabel/dfos-client 0.29.1 → 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

@@ -67,6 +67,134 @@ declare const createSiwdChallenge: (input: CreateChallengeInput) => {
 };
 /** Decode a base64url `challenge` query-param body back into a challenge object. */
 declare const decodeSiwdChallenge: (encoded: string) => SiwdChallenge;
+interface SiwdLoginRequestInput {
+    /** The host's authorize endpoint, e.g. `https://app.example.com/authorize`. */
+    authorizeUrl: string;
+    /** The RP's own domain — bound into the signed challenge as a bare hostname. */
+    domain: string;
+    /** Exact redirect target; must match the RP's registered or served allowlist. */
+    redirectUri: string;
+    /** Requested scope. `identity` is the only scope implemented today. */
+    scope: string;
+    /** Consent-screen prose. A host MAY decline to render it; see specs/SIWD.md. */
+    statement?: string;
+    /**
+     * Bind the challenge to ONE identity — "sign in as this DID, or not at all".
+     * Threaded into the signed bytes AND into `expect`, because binding a
+     * challenge without verifying the binding proves nothing: a host that ignored
+     * it would return a signature from whoever was logged in, and an RP checking
+     * only the signature would accept it.
+     */
+    did?: string;
+    /** The RP's own DID. Omitted from the URL automatically for loopback redirects. */
+    clientDid?: string;
+    /** Supply a nonce minted elsewhere (e.g. by your backend); default: minted here. */
+    nonce?: string;
+}
+interface SiwdLoginRequest {
+    /** Navigate the browser here, or hand it to the user. */
+    url: string;
+    /**
+     * THE THING TO PERSIST ACROSS THE REDIRECT. One JSON-serializable object that
+     * satisfies `SiwdExpectations`, so the whole round trip is: store this before
+     * navigating, rehydrate it when the callback lands, and hand it straight to
+     * `verifySiwd(client, jws, saved)`. Nothing else has to survive the hop, and
+     * nothing has to be threaded to both ends by hand — which is the point, since
+     * 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. 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
+     * itself and has verified nothing — the replay guard binds only when the
+     * 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' | '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. */
+    timestamp: string;
+}
+/**
+ * Mint a challenge and build the `/authorize` URL to send the browser to — the
+ * OUTBOUND half of profile A. `readSiwdCallback` is the inbound half, and
+ * `verifySiwd` is what both compose around: mint → redirect, read → verify.
+ *
+ * The rule this function exists to own is the LOOPBACK OMISSION. Nothing can
+ * prove a client DID for an app on a local port — there is no domain serving a
+ * well-known and no registration to check — so a host REFUSES a `client_did`
+ * on a loopback redirect rather than displaying an identity it cannot stand
+ * behind. A CLI that passed its own DID would have the whole request rejected,
+ * 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`, 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;
+/**
+ * What came back on the redirect. `none` means this was a plain page load, not
+ * a callback at all — the common case on an RP's own landing page.
+ */
+type SiwdCallbackResult = {
+    kind: 'success';
+    jws: string;
+    did: string;
+} | {
+    kind: 'denied';
+    error: string;
+} | {
+    kind: 'none';
+};
+/**
+ * Read a profile-A callback — the INBOUND half of the pair. Pure parse: it
+ * decides only what kind of return this is, and hands `jws` to the caller for
+ * `verifySiwd`. NOTHING here is trusted; the `did` param is unauthenticated
+ * courier convenience, and the DID a caller should act on is the one
+ * `verifySiwd` returns from the signature.
+ *
+ * Takes an absolute URL string, a `URL`, or a bare `?…` query string (so
+ * `readSiwdCallback(location.search)` works, including when it is empty).
+ *
+ * SCRUB THE URL YOURSELF, IMMEDIATELY. A signed JWS is sitting in the query
+ * string, which means it is in the address bar, in `history`, in the referrer
+ * of anything the page loads next, and in any analytics that samples the
+ * location. This function cannot do the scrubbing for you — `history` is
+ * environment-owned and this package stays free of the DOM — so a browser RP
+ * should follow the read with a `history.replaceState` back to the bare path.
+ *
+ * A HALF-CALLBACK IS A FAILURE, NOT A NON-EVENT: `jws` without `did` (or the
+ * reverse) resolves to `denied` carrying a synthetic reason rather than `none`.
+ * Silently treating it as a plain page load would strand the user on a
+ * sign-in button with no explanation of why the last attempt vanished.
+ */
+declare const readSiwdCallback: (url: string | URL) => SiwdCallbackResult;
 interface BuildSiwdSignRequestInput {
     /** Requester DID that signs the courier envelope. */
     did: string;
@@ -102,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. */
@@ -127,4 +273,4 @@ interface SiwdExpectations {
  */
 declare const verifySiwd: (client: Client, jws: string, expect: SiwdExpectations) => Promise<VerifyResult<SiwdSession>>;
 
-export { type BuildSiwdSignRequestInput, type CreateChallengeInput, SIWD_JWS_TYP, type SiwdChallenge, type SiwdExpectations, type SiwdSession, type ValidateSiwdSignRequestOptions, type ValidatedSiwdSignRequest, buildSiwdSignRequest, createSiwdChallenge, decodeSiwdChallenge, parseSiwdChallenge, siwdSigningInput, validateSiwdSignRequest, verifySiwd };
+export { type BuildSiwdSignRequestInput, type CreateChallengeInput, SIWD_JWS_TYP, type SiwdCallbackResult, type SiwdChallenge, type SiwdExpectations, type SiwdLoginRequest, type SiwdLoginRequestInput, type SiwdSession, type ValidateSiwdSignRequestOptions, type ValidatedSiwdSignRequest, buildSiwdSignRequest, createSiwdChallenge, createSiwdLoginRequest, decodeSiwdChallenge, parseSiwdChallenge, readSiwdCallback, siwdSigningInput, validateSiwdSignRequest, verifySiwd };

package/dist/siwd.js

@@ -109,6 +109,69 @@ var createSiwdChallenge = (input) => {
   return { challenge, encoded, nonce };
 };
 var decodeSiwdChallenge = (encoded) => parseSiwdChallenge(base64urlDecode(encoded));
+var SIWD_LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1"]);
+var bareHostname = (url) => {
+  const host = url.hostname.toLowerCase();
+  return host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+};
+var parseUrlOrThrow = (value, field) => {
+  try {
+    return new URL(value);
+  } catch {
+    throw new Error(`invalid SIWD login request: ${field} must be an absolute URL`);
+  }
+};
+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 } : {},
+    ...input.did !== void 0 ? { did: input.did } : {},
+    ...input.nonce !== void 0 ? { nonce: input.nonce } : {}
+  });
+  const url = new URL(authorizeUrl);
+  url.searchParams.set("challenge", encoded);
+  url.searchParams.set("redirect_uri", input.redirectUri);
+  url.searchParams.set("scope", input.scope);
+  if (input.clientDid !== void 0 && !isLoopback) {
+    url.searchParams.set("client_did", input.clientDid);
+  }
+  return {
+    url: url.toString(),
+    expect: {
+      domain: input.domain,
+      nonce,
+      ...input.did !== void 0 ? { did: input.did } : {}
+    },
+    challenge: encoded,
+    timestamp: challenge.timestamp
+  };
+};
+var callbackParam = (params, key) => {
+  const value = params.get(key);
+  return value === null || value === "" ? void 0 : value;
+};
+var callbackParams = (url) => {
+  if (typeof url !== "string") return url.searchParams;
+  if (url === "" || url.startsWith("?")) return new URLSearchParams(url);
+  return parseUrlOrThrow(url, "url").searchParams;
+};
+var readSiwdCallback = (url) => {
+  const params = callbackParams(url);
+  const jws = callbackParam(params, "jws");
+  const did = callbackParam(params, "did");
+  const error = callbackParam(params, "error");
+  if (jws !== void 0 && did !== void 0) return { kind: "success", jws, did };
+  if (error !== void 0) return { kind: "denied", error };
+  if (jws !== void 0) return { kind: "denied", error: "malformed SIWD callback: missing did" };
+  if (did !== void 0) return { kind: "denied", error: "malformed SIWD callback: missing jws" };
+  return { kind: "none" };
+};
 var assertSiwdAcceptanceWindow = (seconds) => {
   if (!Number.isSafeInteger(seconds) || seconds <= 0) {
     throw new Error("SIWD acceptanceWindowSeconds must be a positive integer");
@@ -174,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;
@@ -216,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");
@@ -229,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,
@@ -252,8 +324,10 @@ export {
   SIWD_JWS_TYP,
   buildSiwdSignRequest,
   createSiwdChallenge,
+  createSiwdLoginRequest,
   decodeSiwdChallenge,
   parseSiwdChallenge,
+  readSiwdCallback,
   siwdSigningInput,
   validateSiwdSignRequest,
   verifySiwd

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalabel/dfos-client",
-  "version": "0.29.1",
+  "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.29.1",
-    "@metalabel/dfos-web-relay": "^0.29.1"
+    "@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.29.1",
-    "@metalabel/dfos-web-relay": "0.29.1"
+    "@metalabel/dfos-protocol": "0.31.0",
+    "@metalabel/dfos-web-relay": "0.31.0"
   },
   "scripts": {
     "build": "tsup",