@metamask-previews/kyc-controller 0.0.0-preview-823dcff → 0.0.0-preview-e57e5c3dc

package/dist/ukyc/localUserSecret.mjs

@@ -0,0 +1,92 @@
+import { base64ToBytes, bytesToBase64 } from "@metamask/utils";
+import { randomBytes } from "@noble/hashes/utils";
+import { UKYC_LOCAL_USER_SECRET_PATH, UKYC_LOCAL_USER_SECRET_SIZE_BYTES } from "./constants.mjs";
+/**
+ * In-flight `getOrCreateLocalUserSecret` calls, keyed by entropy source.
+ * Deduplicates concurrent enrollments in a single client session so we never
+ * generate and persist two competing `local_user_secret`s for the same source.
+ */
+const inFlightCreations = new Map();
+/**
+ * Loads the persisted `local_user_secret` from Encrypted User Storage, if one
+ * exists.
+ *
+ * @param store - The Encrypted User Storage adapter.
+ * @param entropySourceId - Optional HD keyring entropy source id, used to scope
+ * the secret to a specific SRP in multi-SRP wallets. Defaults to the primary SRP.
+ * @returns The decoded `local_user_secret` bytes, or `null` if none has been
+ * enrolled.
+ */
+export async function loadLocalUserSecret(store, entropySourceId) {
+    const stored = await store.get(UKYC_LOCAL_USER_SECRET_PATH, entropySourceId);
+    if (!stored) {
+        return null;
+    }
+    const localUserSecret = base64ToBytes(stored);
+    if (localUserSecret.length !== UKYC_LOCAL_USER_SECRET_SIZE_BYTES) {
+        throw new Error(`UKYC: stored local_user_secret has unexpected length ${localUserSecret.length}, expected ${UKYC_LOCAL_USER_SECRET_SIZE_BYTES}.`);
+    }
+    return localUserSecret;
+}
+/**
+ * Persists a freshly generated `local_user_secret` to Encrypted User Storage.
+ *
+ * @param store - The Encrypted User Storage adapter.
+ * @param localUserSecret - The `local_user_secret` bytes to persist.
+ * @param entropySourceId - Optional HD keyring entropy source id.
+ */
+async function persistLocalUserSecret(store, localUserSecret, entropySourceId) {
+    await store.set(UKYC_LOCAL_USER_SECRET_PATH, bytesToBase64(localUserSecret), entropySourceId);
+}
+/**
+ * Creates the UKYC `local_user_secret` if it does not already exist, otherwise
+ * loads the existing one. This is the single entry point used on UKYC
+ * enrollment.
+ *
+ * The operation is idempotent and safe against concurrent callers in the same
+ * session: repeated or parallel calls resolve to the same `local_user_secret`
+ * and never generate more than one secret for a given entropy source.
+ *
+ * @param store - The Encrypted User Storage adapter.
+ * @param entropySourceId - Optional HD keyring entropy source id, used to scope
+ * the secret to a specific SRP in multi-SRP wallets. Defaults to the primary SRP.
+ * @returns The `local_user_secret` bytes (existing or newly created).
+ */
+export async function getOrCreateLocalUserSecret(store, entropySourceId) {
+    const cacheKey = entropySourceId ?? '';
+    const pending = inFlightCreations.get(cacheKey);
+    if (pending) {
+        return pending;
+    }
+    const creation = (async () => {
+        const existing = await loadLocalUserSecret(store, entropySourceId);
+        if (existing) {
+            return existing;
+        }
+        const localUserSecret = randomBytes(UKYC_LOCAL_USER_SECRET_SIZE_BYTES);
+        await persistLocalUserSecret(store, localUserSecret, entropySourceId);
+        // Re-read after persisting so that all callers converge on whatever value
+        // actually landed in storage (defends against a competing write that may
+        // have won the race, e.g. from another device syncing the same feature).
+        return ((await loadLocalUserSecret(store, entropySourceId)) ?? localUserSecret);
+    })();
+    inFlightCreations.set(cacheKey, creation);
+    try {
+        return await creation;
+    }
+    finally {
+        inFlightCreations.delete(cacheKey);
+    }
+}
+/**
+ * Whether a `local_user_secret` has already been enrolled for the given entropy
+ * source.
+ *
+ * @param store - The Encrypted User Storage adapter.
+ * @param entropySourceId - Optional HD keyring entropy source id.
+ * @returns `true` if a `local_user_secret` exists in Encrypted User Storage.
+ */
+export async function hasLocalUserSecret(store, entropySourceId) {
+    return (await loadLocalUserSecret(store, entropySourceId)) !== null;
+}
+//# sourceMappingURL=localUserSecret.mjs.map

package/dist/ukyc/localUserSecret.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"localUserSecret.mjs","sourceRoot":"","sources":["../../src/ukyc/localUserSecret.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,wBAAwB;AAC/D,OAAO,EAAE,WAAW,EAAE,4BAA4B;AAElD,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EAClC,wBAAuB;AAiCxB;;;;GAIG;AACH,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAA+B,CAAC;AAEjE;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAA+B,EAC/B,eAAwB;IAExB,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,2BAA2B,EAAE,eAAe,CAAC,CAAC;IAE7E,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,eAAe,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAE9C,IAAI,eAAe,CAAC,MAAM,KAAK,iCAAiC,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CACb,wDAAwD,eAAe,CAAC,MAAM,cAAc,iCAAiC,GAAG,CACjI,CAAC;IACJ,CAAC;IAED,OAAO,eAAe,CAAC;AACzB,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,sBAAsB,CACnC,KAA+B,EAC/B,eAA2B,EAC3B,eAAwB;IAExB,MAAM,KAAK,CAAC,GAAG,CACb,2BAA2B,EAC3B,aAAa,CAAC,eAAe,CAAC,EAC9B,eAAe,CAChB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,KAA+B,EAC/B,eAAwB;IAExB,MAAM,QAAQ,GAAG,eAAe,IAAI,EAAE,CAAC;IAEvC,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAChD,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,KAAK,IAAyB,EAAE;QAChD,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC;QACnE,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,MAAM,eAAe,GAAG,WAAW,CAAC,iCAAiC,CAAC,CAAC;QACvE,MAAM,sBAAsB,CAAC,KAAK,EAAE,eAAe,EAAE,eAAe,CAAC,CAAC;QAEtE,0EAA0E;QAC1E,yEAAyE;QACzE,yEAAyE;QACzE,OAAO,CACL,CAAC,MAAM,mBAAmB,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,IAAI,eAAe,CACvE,CAAC;IACJ,CAAC,CAAC,EAAE,CAAC;IAEL,iBAAiB,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAE1C,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC;IACxB,CAAC;YAAS,CAAC;QACT,iBAAiB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrC,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAA+B,EAC/B,eAAwB;IAExB,OAAO,CAAC,MAAM,mBAAmB,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,KAAK,IAAI,CAAC;AACtE,CAAC","sourcesContent":["import { base64ToBytes, bytesToBase64 } from '@metamask/utils';\nimport { randomBytes } from '@noble/hashes/utils';\n\nimport {\n  UKYC_LOCAL_USER_SECRET_PATH,\n  UKYC_LOCAL_USER_SECRET_SIZE_BYTES,\n} from './constants.js';\n\n/**\n * Orchestrates creation and loading of the UKYC `local_user_secret`.\n *\n * The `local_user_secret` is the root secret for all UKYC client-derived\n * material. It is generated once, on first enrollment, and persisted to\n * MetaMask Encrypted User Storage. It is never transmitted off the device, not\n * even to the idOS Relay. Every subsequent value (`storage_id`,\n * `data_encryption_key`, `signing_key`, `relay_tunnel_key`) is derived from it\n * via HKDF — see `deriveClientMaterial`.\n *\n * This module is platform-agnostic: the Encrypted User Storage backing is\n * injected as a {@link UkycLocalUserSecretStore} so the controller (which owns\n * the messenger) supplies the concrete `UserStorageController` calls.\n */\n\n/**\n * The Encrypted User Storage operations this module needs. On MetaMask clients\n * these are backed by `UserStorageController:performGetStorage` /\n * `performSetStorage`.\n */\nexport type UkycLocalUserSecretStore = {\n  /**\n   * Reads the base64 string stored at `path`, or `null` if none exists.\n   */\n  get: (path: string, entropySourceId?: string) => Promise<string | null>;\n  /**\n   * Writes the base64 string `value` at `path`.\n   */\n  set: (path: string, value: string, entropySourceId?: string) => Promise<void>;\n};\n\n/**\n * In-flight `getOrCreateLocalUserSecret` calls, keyed by entropy source.\n * Deduplicates concurrent enrollments in a single client session so we never\n * generate and persist two competing `local_user_secret`s for the same source.\n */\nconst inFlightCreations = new Map<string, Promise<Uint8Array>>();\n\n/**\n * Loads the persisted `local_user_secret` from Encrypted User Storage, if one\n * exists.\n *\n * @param store - The Encrypted User Storage adapter.\n * @param entropySourceId - Optional HD keyring entropy source id, used to scope\n * the secret to a specific SRP in multi-SRP wallets. Defaults to the primary SRP.\n * @returns The decoded `local_user_secret` bytes, or `null` if none has been\n * enrolled.\n */\nexport async function loadLocalUserSecret(\n  store: UkycLocalUserSecretStore,\n  entropySourceId?: string,\n): Promise<Uint8Array | null> {\n  const stored = await store.get(UKYC_LOCAL_USER_SECRET_PATH, entropySourceId);\n\n  if (!stored) {\n    return null;\n  }\n\n  const localUserSecret = base64ToBytes(stored);\n\n  if (localUserSecret.length !== UKYC_LOCAL_USER_SECRET_SIZE_BYTES) {\n    throw new Error(\n      `UKYC: stored local_user_secret has unexpected length ${localUserSecret.length}, expected ${UKYC_LOCAL_USER_SECRET_SIZE_BYTES}.`,\n    );\n  }\n\n  return localUserSecret;\n}\n\n/**\n * Persists a freshly generated `local_user_secret` to Encrypted User Storage.\n *\n * @param store - The Encrypted User Storage adapter.\n * @param localUserSecret - The `local_user_secret` bytes to persist.\n * @param entropySourceId - Optional HD keyring entropy source id.\n */\nasync function persistLocalUserSecret(\n  store: UkycLocalUserSecretStore,\n  localUserSecret: Uint8Array,\n  entropySourceId?: string,\n): Promise<void> {\n  await store.set(\n    UKYC_LOCAL_USER_SECRET_PATH,\n    bytesToBase64(localUserSecret),\n    entropySourceId,\n  );\n}\n\n/**\n * Creates the UKYC `local_user_secret` if it does not already exist, otherwise\n * loads the existing one. This is the single entry point used on UKYC\n * enrollment.\n *\n * The operation is idempotent and safe against concurrent callers in the same\n * session: repeated or parallel calls resolve to the same `local_user_secret`\n * and never generate more than one secret for a given entropy source.\n *\n * @param store - The Encrypted User Storage adapter.\n * @param entropySourceId - Optional HD keyring entropy source id, used to scope\n * the secret to a specific SRP in multi-SRP wallets. Defaults to the primary SRP.\n * @returns The `local_user_secret` bytes (existing or newly created).\n */\nexport async function getOrCreateLocalUserSecret(\n  store: UkycLocalUserSecretStore,\n  entropySourceId?: string,\n): Promise<Uint8Array> {\n  const cacheKey = entropySourceId ?? '';\n\n  const pending = inFlightCreations.get(cacheKey);\n  if (pending) {\n    return pending;\n  }\n\n  const creation = (async (): Promise<Uint8Array> => {\n    const existing = await loadLocalUserSecret(store, entropySourceId);\n    if (existing) {\n      return existing;\n    }\n\n    const localUserSecret = randomBytes(UKYC_LOCAL_USER_SECRET_SIZE_BYTES);\n    await persistLocalUserSecret(store, localUserSecret, entropySourceId);\n\n    // Re-read after persisting so that all callers converge on whatever value\n    // actually landed in storage (defends against a competing write that may\n    // have won the race, e.g. from another device syncing the same feature).\n    return (\n      (await loadLocalUserSecret(store, entropySourceId)) ?? localUserSecret\n    );\n  })();\n\n  inFlightCreations.set(cacheKey, creation);\n\n  try {\n    return await creation;\n  } finally {\n    inFlightCreations.delete(cacheKey);\n  }\n}\n\n/**\n * Whether a `local_user_secret` has already been enrolled for the given entropy\n * source.\n *\n * @param store - The Encrypted User Storage adapter.\n * @param entropySourceId - Optional HD keyring entropy source id.\n * @returns `true` if a `local_user_secret` exists in Encrypted User Storage.\n */\nexport async function hasLocalUserSecret(\n  store: UkycLocalUserSecretStore,\n  entropySourceId?: string,\n): Promise<boolean> {\n  return (await loadLocalUserSecret(store, entropySourceId)) !== null;\n}\n"]}

package/dist/ukyc/storageAccessToken.cjs

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeStorageAccessTokenForHeader = exports.signStorageAccessToken = exports.canonicalizeJson = void 0;
+const utils_1 = require("@metamask/utils");
+const ed25519_1 = require("@noble/curves/ed25519");
+const constants_js_1 = require("./constants.cjs");
+const encoding_js_1 = require("../encoding.cjs");
+/**
+ * Serializes a JSON value to RFC 8785 (JCS) canonical form.
+ *
+ * Scope note: this implementation covers the JSON shapes used by UKYC storage
+ * payloads — objects, arrays, strings, integers, booleans, and null. Object
+ * members are sorted by their UTF-16 code units (matching JS default string
+ * ordering, which is what JCS requires) and `undefined` members are dropped.
+ * Non-finite and non-integer numbers are rejected, since the payloads never
+ * contain them and correct JCS number formatting for the general case is
+ * intentionally out of scope here.
+ *
+ * @param value - The value to canonicalize.
+ * @returns The canonical JSON string.
+ */
+function canonicalizeJson(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (typeof value === 'boolean') {
+        return value ? 'true' : 'false';
+    }
+    if (typeof value === 'number') {
+        if (!Number.isInteger(value)) {
+            throw new Error('UKYC: cannot canonicalize a non-integer number for JCS.');
+        }
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'string') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalizeJson(item)).join(',')}]`;
+    }
+    const entries = Object.keys(value)
+        .sort()
+        .reduce((acc, key) => {
+        const child = value[key];
+        if (child !== undefined) {
+            acc.push(`${JSON.stringify(key)}:${canonicalizeJson(child)}`);
+        }
+        return acc;
+    }, []);
+    return `{${entries.join(',')}}`;
+}
+exports.canonicalizeJson = canonicalizeJson;
+/**
+ * Formats a date as RFC 3339 UTC with whole-second precision (e.g.
+ * `2026-07-07T00:00:00Z`). `Date.prototype.toISOString` always emits
+ * milliseconds (`...:00.000Z`); the `storage_access_token` wire format omits
+ * fractional seconds, so the sub-second component is truncated (not rounded).
+ *
+ * @param date - The date to format.
+ * @returns The RFC 3339 timestamp without fractional seconds.
+ */
+function toRfc3339Seconds(date) {
+    return `${date.toISOString().slice(0, 19)}Z`;
+}
+/**
+ * Builds and signs a `storage_access_token`.
+ *
+ * @param params - See {@link SignStorageAccessTokenParams}.
+ * @returns The signed token envelope.
+ */
+function signStorageAccessToken(params) {
+    const { material, operations, presenter = 'client', sessionId, issuedAt = new Date(), expiresAt, } = params;
+    assertValidOperations(operations);
+    if (expiresAt.getTime() <= issuedAt.getTime()) {
+        throw new Error('UKYC: storage_access_token expires_at must be after issued_at.');
+    }
+    const isDelete = operations.includes('delete');
+    if (presenter === 'idos-relay' && isDelete) {
+        throw new Error('UKYC: a delete-scoped storage_access_token cannot be delegated to the Relay.');
+    }
+    if (presenter === 'idos-relay' && !sessionId) {
+        throw new Error('UKYC: a Relay-presented storage_access_token requires a session_id.');
+    }
+    const payload = {
+        version: constants_js_1.UKYC_STORAGE_ACCESS_TOKEN_VERSION,
+        aud: [...constants_js_1.UKYC_STORAGE_ACCESS_TOKEN_AUDIENCES],
+        storage_id: (0, encoding_js_1.toBase64Url)(material.storageId),
+        signing_public_key: (0, encoding_js_1.toBase64Url)(material.signingPublicKey),
+        operations,
+        presenter,
+        issued_at: toRfc3339Seconds(issuedAt),
+        expires_at: toRfc3339Seconds(expiresAt),
+    };
+    // Only bind session_id for Relay-presented tokens; omit the key entirely for
+    // client-presented tokens so it does not appear in the canonicalized payload.
+    if (presenter === 'idos-relay') {
+        payload.session_id = sessionId;
+    }
+    const message = (0, utils_1.stringToBytes)(canonicalizeJson(payload));
+    const signature = ed25519_1.ed25519.sign(message, material.signingKey);
+    return {
+        payload,
+        signature: (0, encoding_js_1.toBase64Url)(signature),
+    };
+}
+exports.signStorageAccessToken = signStorageAccessToken;
+/**
+ * Serializes a signed token to a compact string suitable for header transport
+ * (`Authorization: AccessToken <token>`, see `UKYC_CAPABILITY_AUTH_SCHEME`). The
+ * complete envelope is base64url-encoded; the private `signing_key` is never
+ * included.
+ *
+ * @param token - The signed token envelope.
+ * @returns The base64url-encoded envelope string.
+ */
+function encodeStorageAccessTokenForHeader(token) {
+    return (0, encoding_js_1.toBase64Url)((0, utils_1.stringToBytes)(JSON.stringify(token)));
+}
+exports.encodeStorageAccessTokenForHeader = encodeStorageAccessTokenForHeader;
+/**
+ * Validates that an operations list is one storage understands: a non-empty set
+ * of `read`/`write`, or exactly `['delete']`. `delete` is never combined with
+ * other operations.
+ *
+ * @param operations - The requested operations.
+ */
+function assertValidOperations(operations) {
+    if (operations.length === 0) {
+        throw new Error('UKYC: storage_access_token requires at least one operation.');
+    }
+    const unique = new Set(operations);
+    if (unique.size !== operations.length) {
+        throw new Error('UKYC: storage_access_token operations must be unique.');
+    }
+    if (unique.has('delete') && operations.length > 1) {
+        throw new Error('UKYC: a delete-scoped storage_access_token must contain only "delete".');
+    }
+}
+//# sourceMappingURL=storageAccessToken.cjs.map

package/dist/ukyc/storageAccessToken.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageAccessToken.cjs","sourceRoot":"","sources":["../../src/ukyc/storageAccessToken.ts"],"names":[],"mappings":"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","sourcesContent":["import { stringToBytes } from '@metamask/utils';\nimport { ed25519 } from '@noble/curves/ed25519';\n\nimport {\n  UKYC_STORAGE_ACCESS_TOKEN_AUDIENCES,\n  UKYC_STORAGE_ACCESS_TOKEN_VERSION,\n} from './constants.js';\nimport type { UkycClientMaterial } from './deriveClientMaterial.js';\nimport { toBase64Url } from '../encoding.js';\n\n/**\n * Mints `storage_access_token` capabilities — the client-signed, scoped,\n * session-bound proofs that authorize UKYC storage operations. See the\n * architecture doc, section \"Storage Authentication\".\n *\n * The token is Ed25519 over RFC 8785 (JCS) canonical JSON of the payload. Only\n * the client holds the private `signing_key`, so only the client can mint a\n * token; a `read`/`write`-scoped token may then be handed to the Relay to\n * present, but `delete` is never delegated.\n */\n\n/**\n * Storage operations a `storage_access_token` can authorize.\n */\nexport type UkycStorageOperation = 'read' | 'write' | 'delete';\n\n/**\n * Who presents the token to UKYC storage. The Relay may only present\n * `read`/`write` tokens; `delete` is always client-presented.\n */\nexport type UkycTokenPresenter = 'client' | 'idos-relay';\n\n/**\n * The signed `storage_access_token` payload. Field names are snake_case because\n * they are canonicalized and hashed exactly as they appear on the wire.\n */\nexport type UkycStorageAccessTokenPayload = {\n  version: number;\n  /** Every verifier that may accept the token, e.g. UKYC Storage and idOS Kwil. */\n  aud: string[];\n  // Wire-shape fields are snake_case; they are canonicalized and signed exactly\n  // as they appear on the wire.\n  /* eslint-disable @typescript-eslint/naming-convention */\n  storage_id: string;\n  signing_public_key: string;\n  operations: UkycStorageOperation[];\n  presenter: UkycTokenPresenter;\n  /** UKYC session id. Required (and only present) when presenter is `idos-relay`. */\n  session_id?: string;\n  issued_at: string;\n  expires_at: string;\n  /* eslint-enable @typescript-eslint/naming-convention */\n};\n\n/**\n * The on-the-wire envelope: the payload plus its detached Ed25519 signature\n * (base64url) over the JCS canonicalization of the payload.\n */\nexport type UkycStorageAccessToken = {\n  payload: UkycStorageAccessTokenPayload;\n  signature: string;\n};\n\n/**\n * Inputs for minting a `storage_access_token`.\n */\nexport type SignStorageAccessTokenParams = {\n  /** Client material derived from `local_user_secret`. */\n  material: UkycClientMaterial;\n  /** Operations the token authorizes. `delete` must be the sole operation. */\n  operations: UkycStorageOperation[];\n  /** Who will present the token. Defaults to `client`. */\n  presenter?: UkycTokenPresenter;\n  /** UKYC session id. Required when presenter is `idos-relay`. */\n  sessionId?: string;\n  /** Token issue time. Defaults to now. */\n  issuedAt?: Date;\n  /** Token expiry. Must be strictly after `issuedAt`. */\n  expiresAt: Date;\n};\n\ntype JsonValue =\n  | null\n  | boolean\n  | number\n  | string\n  | JsonValue[]\n  | { [key: string]: JsonValue | undefined };\n\n/**\n * Serializes a JSON value to RFC 8785 (JCS) canonical form.\n *\n * Scope note: this implementation covers the JSON shapes used by UKYC storage\n * payloads — objects, arrays, strings, integers, booleans, and null. Object\n * members are sorted by their UTF-16 code units (matching JS default string\n * ordering, which is what JCS requires) and `undefined` members are dropped.\n * Non-finite and non-integer numbers are rejected, since the payloads never\n * contain them and correct JCS number formatting for the general case is\n * intentionally out of scope here.\n *\n * @param value - The value to canonicalize.\n * @returns The canonical JSON string.\n */\nexport function canonicalizeJson(value: JsonValue): string {\n  if (value === null) {\n    return 'null';\n  }\n\n  if (typeof value === 'boolean') {\n    return value ? 'true' : 'false';\n  }\n\n  if (typeof value === 'number') {\n    if (!Number.isInteger(value)) {\n      throw new Error(\n        'UKYC: cannot canonicalize a non-integer number for JCS.',\n      );\n    }\n    return JSON.stringify(value);\n  }\n\n  if (typeof value === 'string') {\n    return JSON.stringify(value);\n  }\n\n  if (Array.isArray(value)) {\n    return `[${value.map((item) => canonicalizeJson(item)).join(',')}]`;\n  }\n\n  const entries = Object.keys(value)\n    .sort()\n    .reduce<string[]>((acc, key) => {\n      const child = value[key];\n      if (child !== undefined) {\n        acc.push(`${JSON.stringify(key)}:${canonicalizeJson(child)}`);\n      }\n      return acc;\n    }, []);\n\n  return `{${entries.join(',')}}`;\n}\n\n/**\n * Formats a date as RFC 3339 UTC with whole-second precision (e.g.\n * `2026-07-07T00:00:00Z`). `Date.prototype.toISOString` always emits\n * milliseconds (`...:00.000Z`); the `storage_access_token` wire format omits\n * fractional seconds, so the sub-second component is truncated (not rounded).\n *\n * @param date - The date to format.\n * @returns The RFC 3339 timestamp without fractional seconds.\n */\nfunction toRfc3339Seconds(date: Date): string {\n  return `${date.toISOString().slice(0, 19)}Z`;\n}\n\n/**\n * Builds and signs a `storage_access_token`.\n *\n * @param params - See {@link SignStorageAccessTokenParams}.\n * @returns The signed token envelope.\n */\nexport function signStorageAccessToken(\n  params: SignStorageAccessTokenParams,\n): UkycStorageAccessToken {\n  const {\n    material,\n    operations,\n    presenter = 'client',\n    sessionId,\n    issuedAt = new Date(),\n    expiresAt,\n  } = params;\n\n  assertValidOperations(operations);\n\n  if (expiresAt.getTime() <= issuedAt.getTime()) {\n    throw new Error(\n      'UKYC: storage_access_token expires_at must be after issued_at.',\n    );\n  }\n\n  const isDelete = operations.includes('delete');\n\n  if (presenter === 'idos-relay' && isDelete) {\n    throw new Error(\n      'UKYC: a delete-scoped storage_access_token cannot be delegated to the Relay.',\n    );\n  }\n\n  if (presenter === 'idos-relay' && !sessionId) {\n    throw new Error(\n      'UKYC: a Relay-presented storage_access_token requires a session_id.',\n    );\n  }\n\n  const payload: UkycStorageAccessTokenPayload = {\n    version: UKYC_STORAGE_ACCESS_TOKEN_VERSION,\n    aud: [...UKYC_STORAGE_ACCESS_TOKEN_AUDIENCES],\n    storage_id: toBase64Url(material.storageId),\n    signing_public_key: toBase64Url(material.signingPublicKey),\n    operations,\n    presenter,\n    issued_at: toRfc3339Seconds(issuedAt),\n    expires_at: toRfc3339Seconds(expiresAt),\n  };\n\n  // Only bind session_id for Relay-presented tokens; omit the key entirely for\n  // client-presented tokens so it does not appear in the canonicalized payload.\n  if (presenter === 'idos-relay') {\n    payload.session_id = sessionId;\n  }\n\n  const message = stringToBytes(canonicalizeJson(payload));\n  const signature = ed25519.sign(message, material.signingKey);\n\n  return {\n    payload,\n    signature: toBase64Url(signature),\n  };\n}\n\n/**\n * Serializes a signed token to a compact string suitable for header transport\n * (`Authorization: AccessToken <token>`, see `UKYC_CAPABILITY_AUTH_SCHEME`). The\n * complete envelope is base64url-encoded; the private `signing_key` is never\n * included.\n *\n * @param token - The signed token envelope.\n * @returns The base64url-encoded envelope string.\n */\nexport function encodeStorageAccessTokenForHeader(\n  token: UkycStorageAccessToken,\n): string {\n  return toBase64Url(stringToBytes(JSON.stringify(token)));\n}\n\n/**\n * Validates that an operations list is one storage understands: a non-empty set\n * of `read`/`write`, or exactly `['delete']`. `delete` is never combined with\n * other operations.\n *\n * @param operations - The requested operations.\n */\nfunction assertValidOperations(operations: UkycStorageOperation[]): void {\n  if (operations.length === 0) {\n    throw new Error(\n      'UKYC: storage_access_token requires at least one operation.',\n    );\n  }\n\n  const unique = new Set(operations);\n\n  if (unique.size !== operations.length) {\n    throw new Error('UKYC: storage_access_token operations must be unique.');\n  }\n\n  if (unique.has('delete') && operations.length > 1) {\n    throw new Error(\n      'UKYC: a delete-scoped storage_access_token must contain only \"delete\".',\n    );\n  }\n}\n"]}

package/dist/ukyc/storageAccessToken.d.cts

@@ -0,0 +1,99 @@
+import type { UkycClientMaterial } from "./deriveClientMaterial.cjs";
+/**
+ * Mints `storage_access_token` capabilities — the client-signed, scoped,
+ * session-bound proofs that authorize UKYC storage operations. See the
+ * architecture doc, section "Storage Authentication".
+ *
+ * The token is Ed25519 over RFC 8785 (JCS) canonical JSON of the payload. Only
+ * the client holds the private `signing_key`, so only the client can mint a
+ * token; a `read`/`write`-scoped token may then be handed to the Relay to
+ * present, but `delete` is never delegated.
+ */
+/**
+ * Storage operations a `storage_access_token` can authorize.
+ */
+export type UkycStorageOperation = 'read' | 'write' | 'delete';
+/**
+ * Who presents the token to UKYC storage. The Relay may only present
+ * `read`/`write` tokens; `delete` is always client-presented.
+ */
+export type UkycTokenPresenter = 'client' | 'idos-relay';
+/**
+ * The signed `storage_access_token` payload. Field names are snake_case because
+ * they are canonicalized and hashed exactly as they appear on the wire.
+ */
+export type UkycStorageAccessTokenPayload = {
+    version: number;
+    /** Every verifier that may accept the token, e.g. UKYC Storage and idOS Kwil. */
+    aud: string[];
+    storage_id: string;
+    signing_public_key: string;
+    operations: UkycStorageOperation[];
+    presenter: UkycTokenPresenter;
+    /** UKYC session id. Required (and only present) when presenter is `idos-relay`. */
+    session_id?: string;
+    issued_at: string;
+    expires_at: string;
+};
+/**
+ * The on-the-wire envelope: the payload plus its detached Ed25519 signature
+ * (base64url) over the JCS canonicalization of the payload.
+ */
+export type UkycStorageAccessToken = {
+    payload: UkycStorageAccessTokenPayload;
+    signature: string;
+};
+/**
+ * Inputs for minting a `storage_access_token`.
+ */
+export type SignStorageAccessTokenParams = {
+    /** Client material derived from `local_user_secret`. */
+    material: UkycClientMaterial;
+    /** Operations the token authorizes. `delete` must be the sole operation. */
+    operations: UkycStorageOperation[];
+    /** Who will present the token. Defaults to `client`. */
+    presenter?: UkycTokenPresenter;
+    /** UKYC session id. Required when presenter is `idos-relay`. */
+    sessionId?: string;
+    /** Token issue time. Defaults to now. */
+    issuedAt?: Date;
+    /** Token expiry. Must be strictly after `issuedAt`. */
+    expiresAt: Date;
+};
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue | undefined;
+};
+/**
+ * Serializes a JSON value to RFC 8785 (JCS) canonical form.
+ *
+ * Scope note: this implementation covers the JSON shapes used by UKYC storage
+ * payloads — objects, arrays, strings, integers, booleans, and null. Object
+ * members are sorted by their UTF-16 code units (matching JS default string
+ * ordering, which is what JCS requires) and `undefined` members are dropped.
+ * Non-finite and non-integer numbers are rejected, since the payloads never
+ * contain them and correct JCS number formatting for the general case is
+ * intentionally out of scope here.
+ *
+ * @param value - The value to canonicalize.
+ * @returns The canonical JSON string.
+ */
+export declare function canonicalizeJson(value: JsonValue): string;
+/**
+ * Builds and signs a `storage_access_token`.
+ *
+ * @param params - See {@link SignStorageAccessTokenParams}.
+ * @returns The signed token envelope.
+ */
+export declare function signStorageAccessToken(params: SignStorageAccessTokenParams): UkycStorageAccessToken;
+/**
+ * Serializes a signed token to a compact string suitable for header transport
+ * (`Authorization: AccessToken <token>`, see `UKYC_CAPABILITY_AUTH_SCHEME`). The
+ * complete envelope is base64url-encoded; the private `signing_key` is never
+ * included.
+ *
+ * @param token - The signed token envelope.
+ * @returns The base64url-encoded envelope string.
+ */
+export declare function encodeStorageAccessTokenForHeader(token: UkycStorageAccessToken): string;
+export {};
+//# sourceMappingURL=storageAccessToken.d.cts.map

package/dist/ukyc/storageAccessToken.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageAccessToken.d.cts","sourceRoot":"","sources":["../../src/ukyc/storageAccessToken.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,kBAAkB,EAAE,mCAAkC;AAGpE;;;;;;;;;GASG;AAEH;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE/D;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,YAAY,CAAC;AAEzD;;;GAGG;AACH,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,GAAG,EAAE,MAAM,EAAE,CAAC;IAId,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,oBAAoB,EAAE,CAAC;IACnC,SAAS,EAAE,kBAAkB,CAAC;IAC9B,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CAEpB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,6BAA6B,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC,wDAAwD;IACxD,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,4EAA4E;IAC5E,UAAU,EAAE,oBAAoB,EAAE,CAAC;IACnC,wDAAwD;IACxD,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,uDAAuD;IACvD,SAAS,EAAE,IAAI,CAAC;CACjB,CAAC;AAEF,KAAK,SAAS,GACV,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAA;CAAE,CAAC;AAE7C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAqCzD;AAeD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,4BAA4B,GACnC,sBAAsB,CAwDxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,sBAAsB,GAC5B,MAAM,CAER"}

package/dist/ukyc/storageAccessToken.d.mts

@@ -0,0 +1,99 @@
+import type { UkycClientMaterial } from "./deriveClientMaterial.mjs";
+/**
+ * Mints `storage_access_token` capabilities — the client-signed, scoped,
+ * session-bound proofs that authorize UKYC storage operations. See the
+ * architecture doc, section "Storage Authentication".
+ *
+ * The token is Ed25519 over RFC 8785 (JCS) canonical JSON of the payload. Only
+ * the client holds the private `signing_key`, so only the client can mint a
+ * token; a `read`/`write`-scoped token may then be handed to the Relay to
+ * present, but `delete` is never delegated.
+ */
+/**
+ * Storage operations a `storage_access_token` can authorize.
+ */
+export type UkycStorageOperation = 'read' | 'write' | 'delete';
+/**
+ * Who presents the token to UKYC storage. The Relay may only present
+ * `read`/`write` tokens; `delete` is always client-presented.
+ */
+export type UkycTokenPresenter = 'client' | 'idos-relay';
+/**
+ * The signed `storage_access_token` payload. Field names are snake_case because
+ * they are canonicalized and hashed exactly as they appear on the wire.
+ */
+export type UkycStorageAccessTokenPayload = {
+    version: number;
+    /** Every verifier that may accept the token, e.g. UKYC Storage and idOS Kwil. */
+    aud: string[];
+    storage_id: string;
+    signing_public_key: string;
+    operations: UkycStorageOperation[];
+    presenter: UkycTokenPresenter;
+    /** UKYC session id. Required (and only present) when presenter is `idos-relay`. */
+    session_id?: string;
+    issued_at: string;
+    expires_at: string;
+};
+/**
+ * The on-the-wire envelope: the payload plus its detached Ed25519 signature
+ * (base64url) over the JCS canonicalization of the payload.
+ */
+export type UkycStorageAccessToken = {
+    payload: UkycStorageAccessTokenPayload;
+    signature: string;
+};
+/**
+ * Inputs for minting a `storage_access_token`.
+ */
+export type SignStorageAccessTokenParams = {
+    /** Client material derived from `local_user_secret`. */
+    material: UkycClientMaterial;
+    /** Operations the token authorizes. `delete` must be the sole operation. */
+    operations: UkycStorageOperation[];
+    /** Who will present the token. Defaults to `client`. */
+    presenter?: UkycTokenPresenter;
+    /** UKYC session id. Required when presenter is `idos-relay`. */
+    sessionId?: string;
+    /** Token issue time. Defaults to now. */
+    issuedAt?: Date;
+    /** Token expiry. Must be strictly after `issuedAt`. */
+    expiresAt: Date;
+};
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue | undefined;
+};
+/**
+ * Serializes a JSON value to RFC 8785 (JCS) canonical form.
+ *
+ * Scope note: this implementation covers the JSON shapes used by UKYC storage
+ * payloads — objects, arrays, strings, integers, booleans, and null. Object
+ * members are sorted by their UTF-16 code units (matching JS default string
+ * ordering, which is what JCS requires) and `undefined` members are dropped.
+ * Non-finite and non-integer numbers are rejected, since the payloads never
+ * contain them and correct JCS number formatting for the general case is
+ * intentionally out of scope here.
+ *
+ * @param value - The value to canonicalize.
+ * @returns The canonical JSON string.
+ */
+export declare function canonicalizeJson(value: JsonValue): string;
+/**
+ * Builds and signs a `storage_access_token`.
+ *
+ * @param params - See {@link SignStorageAccessTokenParams}.
+ * @returns The signed token envelope.
+ */
+export declare function signStorageAccessToken(params: SignStorageAccessTokenParams): UkycStorageAccessToken;
+/**
+ * Serializes a signed token to a compact string suitable for header transport
+ * (`Authorization: AccessToken <token>`, see `UKYC_CAPABILITY_AUTH_SCHEME`). The
+ * complete envelope is base64url-encoded; the private `signing_key` is never
+ * included.
+ *
+ * @param token - The signed token envelope.
+ * @returns The base64url-encoded envelope string.
+ */
+export declare function encodeStorageAccessTokenForHeader(token: UkycStorageAccessToken): string;
+export {};
+//# sourceMappingURL=storageAccessToken.d.mts.map

package/dist/ukyc/storageAccessToken.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageAccessToken.d.mts","sourceRoot":"","sources":["../../src/ukyc/storageAccessToken.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,kBAAkB,EAAE,mCAAkC;AAGpE;;;;;;;;;GASG;AAEH;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE/D;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,YAAY,CAAC;AAEzD;;;GAGG;AACH,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,GAAG,EAAE,MAAM,EAAE,CAAC;IAId,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,oBAAoB,EAAE,CAAC;IACnC,SAAS,EAAE,kBAAkB,CAAC;IAC9B,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CAEpB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,6BAA6B,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC,wDAAwD;IACxD,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,4EAA4E;IAC5E,UAAU,EAAE,oBAAoB,EAAE,CAAC;IACnC,wDAAwD;IACxD,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,uDAAuD;IACvD,SAAS,EAAE,IAAI,CAAC;CACjB,CAAC;AAEF,KAAK,SAAS,GACV,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAA;CAAE,CAAC;AAE7C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAqCzD;AAeD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,4BAA4B,GACnC,sBAAsB,CAwDxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,sBAAsB,GAC5B,MAAM,CAER"}

package/dist/ukyc/storageAccessToken.mjs

@@ -0,0 +1,133 @@
+import { stringToBytes } from "@metamask/utils";
+import { ed25519 } from "@noble/curves/ed25519";
+import { UKYC_STORAGE_ACCESS_TOKEN_AUDIENCES, UKYC_STORAGE_ACCESS_TOKEN_VERSION } from "./constants.mjs";
+import { toBase64Url } from "../encoding.mjs";
+/**
+ * Serializes a JSON value to RFC 8785 (JCS) canonical form.
+ *
+ * Scope note: this implementation covers the JSON shapes used by UKYC storage
+ * payloads — objects, arrays, strings, integers, booleans, and null. Object
+ * members are sorted by their UTF-16 code units (matching JS default string
+ * ordering, which is what JCS requires) and `undefined` members are dropped.
+ * Non-finite and non-integer numbers are rejected, since the payloads never
+ * contain them and correct JCS number formatting for the general case is
+ * intentionally out of scope here.
+ *
+ * @param value - The value to canonicalize.
+ * @returns The canonical JSON string.
+ */
+export function canonicalizeJson(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (typeof value === 'boolean') {
+        return value ? 'true' : 'false';
+    }
+    if (typeof value === 'number') {
+        if (!Number.isInteger(value)) {
+            throw new Error('UKYC: cannot canonicalize a non-integer number for JCS.');
+        }
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'string') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalizeJson(item)).join(',')}]`;
+    }
+    const entries = Object.keys(value)
+        .sort()
+        .reduce((acc, key) => {
+        const child = value[key];
+        if (child !== undefined) {
+            acc.push(`${JSON.stringify(key)}:${canonicalizeJson(child)}`);
+        }
+        return acc;
+    }, []);
+    return `{${entries.join(',')}}`;
+}
+/**
+ * Formats a date as RFC 3339 UTC with whole-second precision (e.g.
+ * `2026-07-07T00:00:00Z`). `Date.prototype.toISOString` always emits
+ * milliseconds (`...:00.000Z`); the `storage_access_token` wire format omits
+ * fractional seconds, so the sub-second component is truncated (not rounded).
+ *
+ * @param date - The date to format.
+ * @returns The RFC 3339 timestamp without fractional seconds.
+ */
+function toRfc3339Seconds(date) {
+    return `${date.toISOString().slice(0, 19)}Z`;
+}
+/**
+ * Builds and signs a `storage_access_token`.
+ *
+ * @param params - See {@link SignStorageAccessTokenParams}.
+ * @returns The signed token envelope.
+ */
+export function signStorageAccessToken(params) {
+    const { material, operations, presenter = 'client', sessionId, issuedAt = new Date(), expiresAt, } = params;
+    assertValidOperations(operations);
+    if (expiresAt.getTime() <= issuedAt.getTime()) {
+        throw new Error('UKYC: storage_access_token expires_at must be after issued_at.');
+    }
+    const isDelete = operations.includes('delete');
+    if (presenter === 'idos-relay' && isDelete) {
+        throw new Error('UKYC: a delete-scoped storage_access_token cannot be delegated to the Relay.');
+    }
+    if (presenter === 'idos-relay' && !sessionId) {
+        throw new Error('UKYC: a Relay-presented storage_access_token requires a session_id.');
+    }
+    const payload = {
+        version: UKYC_STORAGE_ACCESS_TOKEN_VERSION,
+        aud: [...UKYC_STORAGE_ACCESS_TOKEN_AUDIENCES],
+        storage_id: toBase64Url(material.storageId),
+        signing_public_key: toBase64Url(material.signingPublicKey),
+        operations,
+        presenter,
+        issued_at: toRfc3339Seconds(issuedAt),
+        expires_at: toRfc3339Seconds(expiresAt),
+    };
+    // Only bind session_id for Relay-presented tokens; omit the key entirely for
+    // client-presented tokens so it does not appear in the canonicalized payload.
+    if (presenter === 'idos-relay') {
+        payload.session_id = sessionId;
+    }
+    const message = stringToBytes(canonicalizeJson(payload));
+    const signature = ed25519.sign(message, material.signingKey);
+    return {
+        payload,
+        signature: toBase64Url(signature),
+    };
+}
+/**
+ * Serializes a signed token to a compact string suitable for header transport
+ * (`Authorization: AccessToken <token>`, see `UKYC_CAPABILITY_AUTH_SCHEME`). The
+ * complete envelope is base64url-encoded; the private `signing_key` is never
+ * included.
+ *
+ * @param token - The signed token envelope.
+ * @returns The base64url-encoded envelope string.
+ */
+export function encodeStorageAccessTokenForHeader(token) {
+    return toBase64Url(stringToBytes(JSON.stringify(token)));
+}
+/**
+ * Validates that an operations list is one storage understands: a non-empty set
+ * of `read`/`write`, or exactly `['delete']`. `delete` is never combined with
+ * other operations.
+ *
+ * @param operations - The requested operations.
+ */
+function assertValidOperations(operations) {
+    if (operations.length === 0) {
+        throw new Error('UKYC: storage_access_token requires at least one operation.');
+    }
+    const unique = new Set(operations);
+    if (unique.size !== operations.length) {
+        throw new Error('UKYC: storage_access_token operations must be unique.');
+    }
+    if (unique.has('delete') && operations.length > 1) {
+        throw new Error('UKYC: a delete-scoped storage_access_token must contain only "delete".');
+    }
+}
+//# sourceMappingURL=storageAccessToken.mjs.map

package/dist/ukyc/storageAccessToken.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageAccessToken.mjs","sourceRoot":"","sources":["../../src/ukyc/storageAccessToken.ts"],"names":[],"mappings":"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","sourcesContent":["import { stringToBytes } from '@metamask/utils';\nimport { ed25519 } from '@noble/curves/ed25519';\n\nimport {\n  UKYC_STORAGE_ACCESS_TOKEN_AUDIENCES,\n  UKYC_STORAGE_ACCESS_TOKEN_VERSION,\n} from './constants.js';\nimport type { UkycClientMaterial } from './deriveClientMaterial.js';\nimport { toBase64Url } from '../encoding.js';\n\n/**\n * Mints `storage_access_token` capabilities — the client-signed, scoped,\n * session-bound proofs that authorize UKYC storage operations. See the\n * architecture doc, section \"Storage Authentication\".\n *\n * The token is Ed25519 over RFC 8785 (JCS) canonical JSON of the payload. Only\n * the client holds the private `signing_key`, so only the client can mint a\n * token; a `read`/`write`-scoped token may then be handed to the Relay to\n * present, but `delete` is never delegated.\n */\n\n/**\n * Storage operations a `storage_access_token` can authorize.\n */\nexport type UkycStorageOperation = 'read' | 'write' | 'delete';\n\n/**\n * Who presents the token to UKYC storage. The Relay may only present\n * `read`/`write` tokens; `delete` is always client-presented.\n */\nexport type UkycTokenPresenter = 'client' | 'idos-relay';\n\n/**\n * The signed `storage_access_token` payload. Field names are snake_case because\n * they are canonicalized and hashed exactly as they appear on the wire.\n */\nexport type UkycStorageAccessTokenPayload = {\n  version: number;\n  /** Every verifier that may accept the token, e.g. UKYC Storage and idOS Kwil. */\n  aud: string[];\n  // Wire-shape fields are snake_case; they are canonicalized and signed exactly\n  // as they appear on the wire.\n  /* eslint-disable @typescript-eslint/naming-convention */\n  storage_id: string;\n  signing_public_key: string;\n  operations: UkycStorageOperation[];\n  presenter: UkycTokenPresenter;\n  /** UKYC session id. Required (and only present) when presenter is `idos-relay`. */\n  session_id?: string;\n  issued_at: string;\n  expires_at: string;\n  /* eslint-enable @typescript-eslint/naming-convention */\n};\n\n/**\n * The on-the-wire envelope: the payload plus its detached Ed25519 signature\n * (base64url) over the JCS canonicalization of the payload.\n */\nexport type UkycStorageAccessToken = {\n  payload: UkycStorageAccessTokenPayload;\n  signature: string;\n};\n\n/**\n * Inputs for minting a `storage_access_token`.\n */\nexport type SignStorageAccessTokenParams = {\n  /** Client material derived from `local_user_secret`. */\n  material: UkycClientMaterial;\n  /** Operations the token authorizes. `delete` must be the sole operation. */\n  operations: UkycStorageOperation[];\n  /** Who will present the token. Defaults to `client`. */\n  presenter?: UkycTokenPresenter;\n  /** UKYC session id. Required when presenter is `idos-relay`. */\n  sessionId?: string;\n  /** Token issue time. Defaults to now. */\n  issuedAt?: Date;\n  /** Token expiry. Must be strictly after `issuedAt`. */\n  expiresAt: Date;\n};\n\ntype JsonValue =\n  | null\n  | boolean\n  | number\n  | string\n  | JsonValue[]\n  | { [key: string]: JsonValue | undefined };\n\n/**\n * Serializes a JSON value to RFC 8785 (JCS) canonical form.\n *\n * Scope note: this implementation covers the JSON shapes used by UKYC storage\n * payloads — objects, arrays, strings, integers, booleans, and null. Object\n * members are sorted by their UTF-16 code units (matching JS default string\n * ordering, which is what JCS requires) and `undefined` members are dropped.\n * Non-finite and non-integer numbers are rejected, since the payloads never\n * contain them and correct JCS number formatting for the general case is\n * intentionally out of scope here.\n *\n * @param value - The value to canonicalize.\n * @returns The canonical JSON string.\n */\nexport function canonicalizeJson(value: JsonValue): string {\n  if (value === null) {\n    return 'null';\n  }\n\n  if (typeof value === 'boolean') {\n    return value ? 'true' : 'false';\n  }\n\n  if (typeof value === 'number') {\n    if (!Number.isInteger(value)) {\n      throw new Error(\n        'UKYC: cannot canonicalize a non-integer number for JCS.',\n      );\n    }\n    return JSON.stringify(value);\n  }\n\n  if (typeof value === 'string') {\n    return JSON.stringify(value);\n  }\n\n  if (Array.isArray(value)) {\n    return `[${value.map((item) => canonicalizeJson(item)).join(',')}]`;\n  }\n\n  const entries = Object.keys(value)\n    .sort()\n    .reduce<string[]>((acc, key) => {\n      const child = value[key];\n      if (child !== undefined) {\n        acc.push(`${JSON.stringify(key)}:${canonicalizeJson(child)}`);\n      }\n      return acc;\n    }, []);\n\n  return `{${entries.join(',')}}`;\n}\n\n/**\n * Formats a date as RFC 3339 UTC with whole-second precision (e.g.\n * `2026-07-07T00:00:00Z`). `Date.prototype.toISOString` always emits\n * milliseconds (`...:00.000Z`); the `storage_access_token` wire format omits\n * fractional seconds, so the sub-second component is truncated (not rounded).\n *\n * @param date - The date to format.\n * @returns The RFC 3339 timestamp without fractional seconds.\n */\nfunction toRfc3339Seconds(date: Date): string {\n  return `${date.toISOString().slice(0, 19)}Z`;\n}\n\n/**\n * Builds and signs a `storage_access_token`.\n *\n * @param params - See {@link SignStorageAccessTokenParams}.\n * @returns The signed token envelope.\n */\nexport function signStorageAccessToken(\n  params: SignStorageAccessTokenParams,\n): UkycStorageAccessToken {\n  const {\n    material,\n    operations,\n    presenter = 'client',\n    sessionId,\n    issuedAt = new Date(),\n    expiresAt,\n  } = params;\n\n  assertValidOperations(operations);\n\n  if (expiresAt.getTime() <= issuedAt.getTime()) {\n    throw new Error(\n      'UKYC: storage_access_token expires_at must be after issued_at.',\n    );\n  }\n\n  const isDelete = operations.includes('delete');\n\n  if (presenter === 'idos-relay' && isDelete) {\n    throw new Error(\n      'UKYC: a delete-scoped storage_access_token cannot be delegated to the Relay.',\n    );\n  }\n\n  if (presenter === 'idos-relay' && !sessionId) {\n    throw new Error(\n      'UKYC: a Relay-presented storage_access_token requires a session_id.',\n    );\n  }\n\n  const payload: UkycStorageAccessTokenPayload = {\n    version: UKYC_STORAGE_ACCESS_TOKEN_VERSION,\n    aud: [...UKYC_STORAGE_ACCESS_TOKEN_AUDIENCES],\n    storage_id: toBase64Url(material.storageId),\n    signing_public_key: toBase64Url(material.signingPublicKey),\n    operations,\n    presenter,\n    issued_at: toRfc3339Seconds(issuedAt),\n    expires_at: toRfc3339Seconds(expiresAt),\n  };\n\n  // Only bind session_id for Relay-presented tokens; omit the key entirely for\n  // client-presented tokens so it does not appear in the canonicalized payload.\n  if (presenter === 'idos-relay') {\n    payload.session_id = sessionId;\n  }\n\n  const message = stringToBytes(canonicalizeJson(payload));\n  const signature = ed25519.sign(message, material.signingKey);\n\n  return {\n    payload,\n    signature: toBase64Url(signature),\n  };\n}\n\n/**\n * Serializes a signed token to a compact string suitable for header transport\n * (`Authorization: AccessToken <token>`, see `UKYC_CAPABILITY_AUTH_SCHEME`). The\n * complete envelope is base64url-encoded; the private `signing_key` is never\n * included.\n *\n * @param token - The signed token envelope.\n * @returns The base64url-encoded envelope string.\n */\nexport function encodeStorageAccessTokenForHeader(\n  token: UkycStorageAccessToken,\n): string {\n  return toBase64Url(stringToBytes(JSON.stringify(token)));\n}\n\n/**\n * Validates that an operations list is one storage understands: a non-empty set\n * of `read`/`write`, or exactly `['delete']`. `delete` is never combined with\n * other operations.\n *\n * @param operations - The requested operations.\n */\nfunction assertValidOperations(operations: UkycStorageOperation[]): void {\n  if (operations.length === 0) {\n    throw new Error(\n      'UKYC: storage_access_token requires at least one operation.',\n    );\n  }\n\n  const unique = new Set(operations);\n\n  if (unique.size !== operations.length) {\n    throw new Error('UKYC: storage_access_token operations must be unique.');\n  }\n\n  if (unique.has('delete') && operations.length > 1) {\n    throw new Error(\n      'UKYC: a delete-scoped storage_access_token must contain only \"delete\".',\n    );\n  }\n}\n"]}