@metalabel/dfos-client 0.29.0

package/dist/memory-CL1DM6Ud.d.ts

@@ -0,0 +1,5 @@
+import { S as Store } from './types-ByxTj1u-.js';
+
+declare const memoryStore: () => Store;
+
+export { memoryStore as m };

package/dist/siwd.d.ts

@@ -0,0 +1,130 @@
+import { Signer, VerifiedIdentity, VerifiedSignRequest } from '@metalabel/dfos-protocol/chain';
+import { a as Client, V as VerifyResult } from './types-ByxTj1u-.js';
+import '@metalabel/dfos-protocol/credentials';
+import '@metalabel/dfos-web-relay/peer-client';
+
+/**
+ * The normative JWS header `typ` for a signed SIWD challenge (SIWD.md). Signers
+ * MUST set it; `verifySiwd` rejects anything else — it is also what lets typ-
+ * routing dispatchers tell a SIWD proof apart from credentials and chain ops.
+ */
+declare const SIWD_JWS_TYP = "did:dfos:siwd";
+interface SiwdChallenge {
+    /** Origin domain of the requesting application. */
+    domain: string;
+    /** Unique replay-prevention value generated by the third party. */
+    nonce: string;
+    /** ISO 8601 timestamp of challenge creation. */
+    timestamp: string;
+    /** Human-readable description shown on the consent screen. */
+    statement?: string;
+    /** Binds the challenge to a specific DID. */
+    did?: string;
+}
+interface SiwdSession {
+    did: string;
+    domain: string;
+    nonce: string;
+    timestamp: string;
+    statement?: string;
+    /** The DID URL of the key that signed the challenge. */
+    kid: string;
+}
+/**
+ * The byte contract. Serializes a challenge to the canonical bytes that ARE the
+ * JWS payload and the base64url query-param body — a fixed key order
+ * (domain, nonce, timestamp, statement?, did?) so both halves agree exactly.
+ * PURE and clientless: import it in an edge minter and in a browser wallet alike.
+ */
+declare const siwdSigningInput: (challenge: SiwdChallenge) => Uint8Array;
+/**
+ * Parse exact SIWD challenge octets under the signer-side WYSIWYS contract.
+ * The input must be UTF-8 JSON, satisfy the closed challenge schema, and equal
+ * the canonical serialization byte for byte.
+ */
+declare const parseSiwdChallenge: (octets: Uint8Array) => SiwdChallenge;
+interface CreateChallengeInput {
+    domain: string;
+    statement?: string;
+    did?: string;
+    /** Provide a nonce, or one is generated. */
+    nonce?: string;
+    /** Provide a timestamp, or `now` is used. */
+    timestamp?: string;
+    /** Clock injection (unix ms) for the timestamp. Default `Date.now()`. */
+    now?: () => number;
+}
+/**
+ * Mint a challenge, clientless and edge-safe. Returns the challenge object, the
+ * base64url `encoded` form for the `/authorize?challenge=` query param, and the
+ * nonce for server-side replay storage. `encoded` is exactly
+ * base64url(siwdSigningInput(challenge)) — the same bytes the wallet signs.
+ */
+declare const createSiwdChallenge: (input: CreateChallengeInput) => {
+    challenge: SiwdChallenge;
+    encoded: string;
+    nonce: string;
+};
+/** Decode a base64url `challenge` query-param body back into a challenge object. */
+declare const decodeSiwdChallenge: (encoded: string) => SiwdChallenge;
+interface BuildSiwdSignRequestInput {
+    /** Requester DID that signs the courier envelope. */
+    did: string;
+    /** DID being asked to sign the SIWD artifact. */
+    subject: string;
+    challenge: SiwdChallenge;
+    /** Explicit composer policy; no implicit SIWD mailbox lifetime exists. */
+    acceptanceWindowSeconds: number;
+    expiresAt: string;
+    createdAt?: string;
+    signer: Signer;
+    keyId: string;
+}
+interface ValidateSiwdSignRequestOptions {
+    signerDid: string;
+    /** Must be the composer's stated acceptance policy for this request. */
+    acceptanceWindowSeconds: number;
+    resolveIdentity: (did: string) => Promise<VerifiedIdentity | undefined>;
+    /** Unix milliseconds; defaults to Date.now(). */
+    now?: number;
+}
+interface ValidatedSiwdSignRequest extends VerifiedSignRequest {
+    /** Strictly parsed canonical challenge used by the signer for rendering. */
+    challenge: SiwdChallenge;
+}
+/** Compose SIWD profile B using the generic sign-request envelope. */
+declare const buildSiwdSignRequest: (input: BuildSiwdSignRequestInput) => Promise<{
+    jwsToken: string;
+    requestCID: string;
+}>;
+/** Verify and strictly parse a SIWD profile-B request before rendering/signing. */
+declare const validateSiwdSignRequest: (jwsToken: string, options: ValidateSiwdSignRequestOptions) => Promise<ValidatedSiwdSignRequest>;
+interface SiwdExpectations {
+    /** The verifier's own origin — MUST match the challenge domain. */
+    domain: string;
+    /** The nonce this verifier issued for the session. */
+    nonce: string;
+    /** 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. */
+    timestamp?: string;
+    /** Reject challenges older than this many seconds. Default 300 (5 min). */
+    maxAgeSeconds?: number;
+    /**
+     * Accept an identity resolution whose tip could not be verified (cache-only
+     * or empty-delta-against-cache). Default FALSE: authentication never silently
+     * degrades — a rotated-out key must not verify against a stale cached state.
+     */
+    allowStale?: boolean;
+    /** Clock injection (unix ms). Default `Date.now()`. */
+    now?: () => number;
+}
+/**
+ * Verify a SIWD challenge JWS. No-throw. The signature is checked under the DFOS
+ * profile (via the protocol's `verifyJws`), against a CURRENT `authKeys` entry
+ * of a non-deleted identity resolved through the client. Nonce, timestamp
+ * window, and domain are validated against `expect`.
+ */
+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 };

package/dist/siwd.js

@@ -0,0 +1,260 @@
+// src/siwd.ts
+import {
+  buildSignRequest,
+  decodeMultikey,
+  SignRequestVerifyError,
+  verifySignRequest
+} from "@metalabel/dfos-protocol/chain";
+import {
+  assertJwsProfile,
+  base64urlDecode,
+  base64urlEncode,
+  decodeJwsUnsafe,
+  generateIdNoPrefix,
+  verifyJws
+} from "@metalabel/dfos-protocol/crypto";
+var SIWD_JWS_TYP = "did:dfos:siwd";
+var MAX_CLOCK_SKEW_SECONDS = 60;
+var SIWD_CHALLENGE_FIELDS = /* @__PURE__ */ new Set(["domain", "nonce", "timestamp", "statement", "did"]);
+var WHOLE_SECOND_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.000Z$/;
+var LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+var MAX_SIGN_REQUEST_WINDOW_SECONDS = 604800;
+var validateSiwdChallenge = (value) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("invalid SIWD challenge: expected a JSON object");
+  }
+  const raw = value;
+  for (const field of Object.keys(raw)) {
+    if (!SIWD_CHALLENGE_FIELDS.has(field)) {
+      throw new Error(`invalid SIWD challenge: unknown member ${field}`);
+    }
+  }
+  for (const field of ["domain", "nonce", "timestamp"]) {
+    if (typeof raw[field] !== "string" || raw[field].length === 0) {
+      throw new Error(`invalid SIWD challenge: ${field} must be a non-empty string`);
+    }
+  }
+  for (const field of ["statement", "did"]) {
+    if (raw[field] !== void 0 && typeof raw[field] !== "string") {
+      throw new Error(`invalid SIWD challenge: ${field} must be a string when present`);
+    }
+  }
+  const strings = [raw["domain"], raw["nonce"], raw["timestamp"], raw["statement"], raw["did"]];
+  if (strings.some((field) => typeof field === "string" && LONE_SURROGATE.test(field))) {
+    throw new Error("invalid SIWD challenge: string members must be well-formed Unicode");
+  }
+  const timestamp = raw["timestamp"];
+  const timestampMs = Date.parse(timestamp);
+  if (!WHOLE_SECOND_TIMESTAMP.test(timestamp) || Number.isNaN(timestampMs) || new Date(timestampMs).toISOString() !== timestamp) {
+    throw new Error("invalid SIWD challenge: timestamp must be ISO-8601 UTC whole-second .000Z");
+  }
+  return {
+    domain: raw["domain"],
+    nonce: raw["nonce"],
+    timestamp,
+    ...raw["statement"] !== void 0 ? { statement: raw["statement"] } : {},
+    ...raw["did"] !== void 0 ? { did: raw["did"] } : {}
+  };
+};
+var siwdSigningInput = (challenge) => {
+  const parsed = validateSiwdChallenge(challenge);
+  const canonical = {
+    domain: parsed.domain,
+    nonce: parsed.nonce,
+    timestamp: parsed.timestamp
+  };
+  if (parsed.statement !== void 0) canonical["statement"] = parsed.statement;
+  if (parsed.did !== void 0) canonical["did"] = parsed.did;
+  return new TextEncoder().encode(JSON.stringify(canonical));
+};
+var parseSiwdChallenge = (octets) => {
+  let source;
+  try {
+    source = new TextDecoder("utf-8", { fatal: true }).decode(octets);
+  } catch {
+    throw new Error("invalid SIWD challenge: payload is not valid UTF-8 JSON");
+  }
+  if (source.startsWith("\uFEFF")) {
+    throw new Error("invalid SIWD challenge: payload must not carry a UTF-8 BOM");
+  }
+  let raw;
+  try {
+    raw = JSON.parse(source);
+  } catch {
+    throw new Error("invalid SIWD challenge: payload is not valid JSON");
+  }
+  const challenge = validateSiwdChallenge(raw);
+  const canonical = siwdSigningInput(challenge);
+  if (canonical.length !== octets.length || !canonical.every((byte, index) => byte === octets[index])) {
+    throw new Error("invalid SIWD challenge: payload bytes are not canonical");
+  }
+  return challenge;
+};
+var createSiwdChallenge = (input) => {
+  const nonce = input.nonce ?? generateIdNoPrefix();
+  const timestampValue = input.timestamp ?? new Date(input.now ? input.now() : Date.now()).toISOString();
+  const timestampMs = Date.parse(timestampValue);
+  if (Number.isNaN(timestampMs)) {
+    throw new Error(`invalid SIWD challenge: unparseable timestamp: ${timestampValue}`);
+  }
+  const timestamp = new Date(Math.floor(timestampMs / 1e3) * 1e3).toISOString();
+  const challenge = {
+    domain: input.domain,
+    nonce,
+    timestamp,
+    ...input.statement !== void 0 ? { statement: input.statement } : {},
+    ...input.did !== void 0 ? { did: input.did } : {}
+  };
+  const encoded = base64urlEncode(siwdSigningInput(challenge));
+  return { challenge, encoded, nonce };
+};
+var decodeSiwdChallenge = (encoded) => parseSiwdChallenge(base64urlDecode(encoded));
+var assertSiwdAcceptanceWindow = (seconds) => {
+  if (!Number.isSafeInteger(seconds) || seconds <= 0) {
+    throw new Error("SIWD acceptanceWindowSeconds must be a positive integer");
+  }
+  if (seconds > MAX_SIGN_REQUEST_WINDOW_SECONDS) {
+    throw new Error("SIWD acceptanceWindowSeconds exceeds the sign-request 604800-second ceiling");
+  }
+};
+var assertSiwdOneClock = (challengeTimestamp, expiresAt, acceptanceWindowSeconds) => {
+  assertSiwdAcceptanceWindow(acceptanceWindowSeconds);
+  const challengeMs = Date.parse(challengeTimestamp);
+  const expiresMs = Date.parse(expiresAt);
+  if (Number.isNaN(expiresMs)) {
+    throw new Error(`invalid SIWD sign request: unparseable expiresAt: ${expiresAt}`);
+  }
+  const normalizedExpiresMs = Math.floor(expiresMs / 1e3) * 1e3;
+  if (normalizedExpiresMs > challengeMs + acceptanceWindowSeconds * 1e3) {
+    throw new Error("SIWD sign request expiresAt exceeds the challenge acceptance window");
+  }
+};
+var buildSiwdSignRequest = async (input) => {
+  const challenge = validateSiwdChallenge(input.challenge);
+  if (challenge.did !== void 0 && challenge.did !== input.subject) {
+    throw new Error("SIWD challenge did does not match sign request subject");
+  }
+  assertSiwdOneClock(challenge.timestamp, input.expiresAt, input.acceptanceWindowSeconds);
+  return buildSignRequest({
+    did: input.did,
+    subject: input.subject,
+    payloadTyp: SIWD_JWS_TYP,
+    payload: siwdSigningInput(challenge),
+    expiresAt: input.expiresAt,
+    ...input.createdAt !== void 0 ? { createdAt: input.createdAt } : {},
+    signer: input.signer,
+    keyId: input.keyId
+  });
+};
+var validateSiwdSignRequest = async (jwsToken, options) => {
+  assertSiwdAcceptanceWindow(options.acceptanceWindowSeconds);
+  const request = await verifySignRequest(jwsToken, {
+    resolveIdentity: options.resolveIdentity,
+    ...options.now !== void 0 ? { now: options.now } : {}
+  });
+  const invalid = (message) => new SignRequestVerifyError("invalid", message);
+  if (request.subject !== options.signerDid) {
+    throw invalid("SIWD sign request subject does not match signer DID");
+  }
+  if (request.payloadTyp !== SIWD_JWS_TYP) {
+    throw invalid(`invalid SIWD sign request payloadTyp: ${request.payloadTyp}`);
+  }
+  let challenge;
+  try {
+    challenge = parseSiwdChallenge(request.payloadBytes);
+    assertSiwdOneClock(challenge.timestamp, request.expiresAt, options.acceptanceWindowSeconds);
+  } catch (err) {
+    throw invalid(err instanceof Error ? err.message : "invalid SIWD sign request payload");
+  }
+  if (challenge.did !== void 0 && challenge.did !== options.signerDid) {
+    throw invalid("SIWD challenge did does not match signer DID");
+  }
+  return { ...request, challenge };
+};
+var fail = (error) => ({ ok: false, error });
+var verifySiwd = async (client, jws, expect) => {
+  try {
+    const decoded = decodeJwsUnsafe(jws);
+    if (!decoded) return fail("failed to decode JWS");
+    const rawHeader = decoded.header;
+    if (typeof rawHeader !== "object" || rawHeader === null || Array.isArray(rawHeader)) {
+      return fail("SIWD protected header must be an object");
+    }
+    assertJwsProfile(rawHeader, (message) => new Error(message));
+    if (decoded.header.typ !== SIWD_JWS_TYP) {
+      return fail(`invalid typ: expected ${SIWD_JWS_TYP}, got ${decoded.header.typ}`);
+    }
+    const kid = decoded.header.kid;
+    if (typeof kid !== "string") return fail("kid must be a DID URL");
+    const hashIdx = kid.indexOf("#");
+    if (hashIdx < 0) return fail("kid must be a DID URL");
+    const did = kid.substring(0, hashIdx);
+    const keyId = kid.substring(hashIdx + 1);
+    const payloadSegment = jws.split(".")[1];
+    if (payloadSegment === void 0) return fail("failed to decode JWS payload");
+    const payload = parseSiwdChallenge(base64urlDecode(payloadSegment));
+    if (payload.did !== void 0 && payload.did !== did) {
+      return fail("challenge did does not match signer");
+    }
+    if (expect.did !== void 0 && expect.did !== did) {
+      return fail("signer did does not match expected did");
+    }
+    const resolved = await client.identity(did);
+    const unverifiable = resolved.trust.unverifiable ?? [];
+    if (!expect.allowStale && (unverifiable.includes("tip") || resolved.provenance.fromCache)) {
+      return fail(
+        "identity resolution is stale (tip unverified) \u2014 refusing to authenticate against a cached identity state; pass allowStale: true to accept the risk"
+      );
+    }
+    const state = resolved.value;
+    if (state.isDeleted) return fail("identity is deleted");
+    const authKey = state.authKeys.find((k) => k.id === keyId);
+    if (!authKey) return fail("signing key is not a current authentication key");
+    const publicKey = decodeMultikey(authKey.publicKeyMultibase).keyBytes;
+    try {
+      verifyJws({ token: jws, publicKey });
+    } 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");
+    }
+    const maxAge = expect.maxAgeSeconds ?? 300;
+    const nowMs = expect.now ? expect.now() : Date.now();
+    const issuedMs = Date.parse(payload.timestamp);
+    if (Number.isNaN(issuedMs)) return fail("invalid timestamp");
+    if (nowMs - issuedMs > maxAge * 1e3) return fail("challenge expired");
+    if (issuedMs - nowMs > MAX_CLOCK_SKEW_SECONDS * 1e3) {
+      return fail("challenge timestamp is in the future");
+    }
+    const session = {
+      did,
+      domain: payload.domain,
+      nonce: payload.nonce,
+      timestamp: payload.timestamp,
+      kid,
+      ...payload.statement !== void 0 ? { statement: payload.statement } : {}
+    };
+    return {
+      ok: true,
+      value: session,
+      // surface the resolution's honest gaps either way (populated only on the
+      // allowStale path — the default path fails closed above)
+      ...unverifiable.length > 0 ? { unverifiable } : {}
+    };
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : "siwd verification failed");
+  }
+};
+export {
+  SIWD_JWS_TYP,
+  buildSiwdSignRequest,
+  createSiwdChallenge,
+  decodeSiwdChallenge,
+  parseSiwdChallenge,
+  siwdSigningInput,
+  validateSiwdSignRequest,
+  verifySiwd
+};

package/dist/store/index.d.ts

@@ -0,0 +1,14 @@
+export { m as memoryStore } from '../memory-CL1DM6Ud.js';
+import { S as Store } from '../types-ByxTj1u-.js';
+import '@metalabel/dfos-protocol/chain';
+import '@metalabel/dfos-protocol/credentials';
+import '@metalabel/dfos-web-relay/peer-client';
+
+/**
+ * A durable, browser-only cache backed by a single IndexedDB object store.
+ * `dbName` defaults to `dfos-client`; pass a distinct name to isolate caches
+ * (e.g. per relay set) since a relay switch is a new client.
+ */
+declare const indexedDbStore: (dbName?: string) => Store;
+
+export { Store, indexedDbStore };

package/dist/store/index.js

@@ -0,0 +1,49 @@
+import {
+  memoryStore
+} from "../chunk-63XCFYOE.js";
+
+// src/store/indexeddb.ts
+var STORE_NAME = "dfos-cache";
+var getFactory = () => {
+  const idb = globalThis.indexedDB;
+  if (!idb) throw new Error("indexedDbStore requires a browser IndexedDB environment");
+  return idb;
+};
+var promisify = (req) => new Promise((resolve, reject) => {
+  req.onsuccess = () => resolve(req.result);
+  req.onerror = () => reject(req.error ?? new Error("indexeddb request failed"));
+});
+var indexedDbStore = (dbName = "dfos-client") => {
+  let dbPromise;
+  const open = () => {
+    if (!dbPromise) {
+      dbPromise = new Promise((resolve, reject) => {
+        const req = getFactory().open(dbName, 1);
+        req.onupgradeneeded = () => {
+          const db = req.result;
+          if (!db.objectStoreNames.contains(STORE_NAME)) db.createObjectStore(STORE_NAME);
+        };
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error ?? new Error("failed to open indexeddb"));
+      });
+    }
+    return dbPromise;
+  };
+  return {
+    async get(key) {
+      const db = await open();
+      const store = db.transaction(STORE_NAME, "readonly").objectStore(STORE_NAME);
+      const value = await promisify(store.get(key));
+      return value ?? void 0;
+    },
+    async set(key, value) {
+      const db = await open();
+      const store = db.transaction(STORE_NAME, "readwrite").objectStore(STORE_NAME);
+      await promisify(store.put(value, key));
+    }
+  };
+};
+export {
+  indexedDbStore,
+  memoryStore
+};