@metalabel/dfos-client 0.29.1 → 0.30.0

package/dist/siwd.d.ts

@@ -67,6 +67,118 @@ 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.
+     *
+     * 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.
+     */
+    expect: Pick<SiwdExpectations, 'domain' | 'nonce' | 'did'>;
+    /** 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.
+ *
+ * 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.
+ */
+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;
@@ -127,4 +239,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,65 @@ 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 { 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 && !SIWD_LOOPBACK_HOSTS.has(bareHostname(redirect))) {
+    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");
@@ -252,8 +311,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.30.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.30.0",
+    "@metalabel/dfos-web-relay": "^0.30.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.30.0",
+    "@metalabel/dfos-web-relay": "0.30.0"
   },
   "scripts": {
     "build": "tsup",