@invisible-labs/sdk 0.6.0-devnet.1

package/dist/storage.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `@invisible-labs/sdk/storage` - storage adapters (spec section 7).
+ *
+ * The SDK persists recoverable secrets (Recovery Code, LP Position Code, LP
+ * Refill Key, withdrawal secret) only through a {@link StorageAdapter}. The
+ * `memory`, `browser`, and `extension` adapters are real. Browser and
+ * extension adapters persist the bytes provided by the caller; callers that need
+ * encrypted-at-rest storage can wrap/encrypt bytes before calling `put`.
+ */
+/**
+ * A namespaced key/value store for the SDK's recoverable secrets. Values are
+ * raw bytes. Callers may store plaintext bytes, pre-wrapped bytes, or encrypted
+ * bytes depending on their host product's storage model.
+ */
+interface StorageAdapter {
+    /** Which backing the adapter uses. */
+    readonly kind: "browser" | "extension" | "server-hkdf" | "server-custom" | "memory";
+    put(namespace: string, key: string, value: Uint8Array): Promise<void>;
+    get(namespace: string, key: string): Promise<Uint8Array | null>;
+    list(namespace: string): Promise<string[]>;
+    remove(namespace: string, key: string): Promise<void>;
+    /** `server-hkdf` only: derive a secret from a stable domain context. */
+    derive?(namespace: string, context: string): Promise<Uint8Array>;
+}
+interface BrowserStorageOptions {
+    /** Override for tests or custom host environments. Defaults to `globalThis.localStorage`. */
+    readonly storage?: StorageLike;
+}
+interface ExtensionStorageOptions {
+    /** Override for tests or custom extension hosts. Defaults to chrome/browser storage local. */
+    readonly storage?: ExtensionStorageArea;
+    /** Override for tests or custom extension hosts. Defaults to chrome/browser runtime. */
+    readonly runtime?: ExtensionRuntimeLike;
+    /**
+     * Chrome exposes storage.local to content scripts by default. Keep the default
+     * trusted-context restriction when the host API supports it.
+     */
+    readonly restrictAccessToTrustedContexts?: boolean;
+}
+interface StorageLike {
+    readonly length: number;
+    key(index: number): string | null;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+interface ExtensionStorageArea {
+    get(keys?: string | string[] | Record<string, unknown> | null, callback?: (items: Record<string, unknown>) => void): Promise<Record<string, unknown>> | void;
+    set(items: Record<string, string>, callback?: () => void): Promise<void> | void;
+    remove(keys: string | string[], callback?: () => void): Promise<void> | void;
+    setAccessLevel?(details: {
+        accessLevel: string;
+    }, callback?: () => void): Promise<void> | void;
+}
+interface ExtensionRuntimeLike {
+    readonly lastError?: {
+        readonly message?: string;
+    } | null;
+}
+/**
+ * In-memory adapter. Fully functional, unencrypted, non-persistent - intended
+ * for tests and ephemeral flows, never for real secrets at rest.
+ */
+declare function inMemoryStorage(): StorageAdapter;
+/**
+ * Browser `localStorage` adapter. Values are stored as base64url-encoded bytes.
+ * Encrypt or wrap the bytes before `put` if your product requires encrypted
+ * local persistence.
+ *
+ * @throws StorageError `STORAGE_NOT_AVAILABLE` if `localStorage` is unavailable.
+ */
+declare function browserStorage(options?: BrowserStorageOptions): StorageAdapter;
+/**
+ * Browser-extension (`chrome.storage.local` / `browser.storage.local`) adapter.
+ * Values are stored as base64url-encoded bytes. Encrypt or wrap the bytes before
+ * `put` if your product requires encrypted local persistence.
+ *
+ * @throws StorageError `STORAGE_NOT_AVAILABLE` if extension storage is unavailable.
+ */
+declare function extensionStorage(options?: ExtensionStorageOptions): StorageAdapter;
+
+export { type BrowserStorageOptions, type ExtensionStorageOptions, type StorageAdapter, browserStorage, extensionStorage, inMemoryStorage };

package/dist/storage.js

@@ -0,0 +1,246 @@
+import { StorageError } from './chunk-OHIM2YWU.js';
+import './chunk-VR6T6OJS.js';
+
+// src/storage/index.ts
+var STORAGE_KEY_PREFIX = "invisible:sdk:storage:v1:";
+var STORAGE_KEY_SEPARATOR = ":";
+var BASE64URL_PAD = "=";
+var BASE64URL_PLUS = "+";
+var BASE64URL_SLASH = "/";
+var BASE64URL_MINUS = "-";
+var BASE64URL_UNDERSCORE = "_";
+var BYTE_STRING_CHUNK_SIZE = 32768;
+var EXTENSION_TRUSTED_CONTEXTS_ACCESS_LEVEL = "TRUSTED_CONTEXTS";
+function inMemoryStorage() {
+  const namespaces = /* @__PURE__ */ new Map();
+  const bucket = (namespace) => {
+    let inner = namespaces.get(namespace);
+    if (!inner) {
+      inner = /* @__PURE__ */ new Map();
+      namespaces.set(namespace, inner);
+    }
+    return inner;
+  };
+  return {
+    kind: "memory",
+    async put(namespace, key, value) {
+      bucket(namespace).set(key, value);
+    },
+    async get(namespace, key) {
+      return namespaces.get(namespace)?.get(key) ?? null;
+    },
+    async list(namespace) {
+      return [...namespaces.get(namespace)?.keys() ?? []];
+    },
+    async remove(namespace, key) {
+      namespaces.get(namespace)?.delete(key);
+    }
+  };
+}
+function browserStorage(options = {}) {
+  const storage = options.storage ?? defaultBrowserStorage();
+  if (!storage) throw new StorageError("STORAGE_NOT_AVAILABLE", "localStorage is unavailable");
+  return {
+    kind: "browser",
+    async put(namespace, key, value) {
+      try {
+        storage.setItem(storageKey(namespace, key), bytesToBase64Url(value));
+      } catch (cause) {
+        throw browserOperationError(cause);
+      }
+    },
+    async get(namespace, key) {
+      try {
+        const value = storage.getItem(storageKey(namespace, key));
+        return value === null ? null : base64UrlToBytes(value);
+      } catch (cause) {
+        throw browserOperationError(cause);
+      }
+    },
+    async list(namespace) {
+      try {
+        const prefix = storageKeyPrefix(namespace);
+        const keys = [];
+        for (let index = 0; index < storage.length; index += 1) {
+          const storedKey = storage.key(index);
+          if (storedKey?.startsWith(prefix)) {
+            keys.push(decodeStorageSegment(storedKey.slice(prefix.length)));
+          }
+        }
+        return keys;
+      } catch (cause) {
+        throw browserOperationError(cause);
+      }
+    },
+    async remove(namespace, key) {
+      try {
+        storage.removeItem(storageKey(namespace, key));
+      } catch (cause) {
+        throw browserOperationError(cause);
+      }
+    }
+  };
+}
+function extensionStorage(options = {}) {
+  const storage = options.storage ?? defaultExtensionStorage();
+  if (!storage) {
+    throw new StorageError("STORAGE_NOT_AVAILABLE", "extension local storage is unavailable");
+  }
+  const runtime = options.runtime ?? defaultExtensionRuntime();
+  const trustedAccess = options.restrictAccessToTrustedContexts === false ? Promise.resolve() : extensionSetAccessLevel(storage, runtime);
+  return {
+    kind: "extension",
+    async put(namespace, key, value) {
+      await trustedAccess;
+      await extensionSet(storage, runtime, {
+        [storageKey(namespace, key)]: bytesToBase64Url(value)
+      });
+    },
+    async get(namespace, key) {
+      await trustedAccess;
+      const storedKey = storageKey(namespace, key);
+      const values = await extensionGet(storage, runtime, storedKey);
+      const value = values[storedKey];
+      return typeof value === "string" ? base64UrlToBytes(value) : null;
+    },
+    async list(namespace) {
+      await trustedAccess;
+      const prefix = storageKeyPrefix(namespace);
+      const values = await extensionGet(storage, runtime, null);
+      return Object.keys(values).filter((key) => key.startsWith(prefix)).map((key) => decodeStorageSegment(key.slice(prefix.length)));
+    },
+    async remove(namespace, key) {
+      await trustedAccess;
+      await extensionRemove(storage, runtime, storageKey(namespace, key));
+    }
+  };
+}
+function storageKey(namespace, key) {
+  return `${storageKeyPrefix(namespace)}${encodeStorageSegment(key)}`;
+}
+function storageKeyPrefix(namespace) {
+  return `${STORAGE_KEY_PREFIX}${encodeStorageSegment(namespace)}${STORAGE_KEY_SEPARATOR}`;
+}
+function encodeStorageSegment(value) {
+  return encodeURIComponent(value);
+}
+function decodeStorageSegment(value) {
+  return decodeURIComponent(value);
+}
+function bytesToBase64Url(value) {
+  let binary = "";
+  for (let index = 0; index < value.length; index += BYTE_STRING_CHUNK_SIZE) {
+    binary += String.fromCharCode(...value.slice(index, index + BYTE_STRING_CHUNK_SIZE));
+  }
+  return btoa(binary).split(BASE64URL_PLUS).join(BASE64URL_MINUS).split(BASE64URL_SLASH).join(BASE64URL_UNDERSCORE).split(BASE64URL_PAD).join("");
+}
+function base64UrlToBytes(value) {
+  try {
+    const base64 = value.split(BASE64URL_MINUS).join(BASE64URL_PLUS).split(BASE64URL_UNDERSCORE).join(BASE64URL_SLASH).padEnd(Math.ceil(value.length / 4) * 4, BASE64URL_PAD);
+    return Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
+  } catch (cause) {
+    throw new StorageError("STORAGE_DECRYPT_FAILED", "stored value is not valid base64url", {
+      cause
+    });
+  }
+}
+function defaultBrowserStorage() {
+  try {
+    return globalThis.localStorage;
+  } catch (cause) {
+    throw new StorageError("STORAGE_NOT_AVAILABLE", "localStorage is unavailable", { cause });
+  }
+}
+function browserOperationError(cause) {
+  if (cause instanceof StorageError) return cause;
+  return new StorageError(
+    "STORAGE_NOT_AVAILABLE",
+    storageErrorMessage(cause) ?? "localStorage operation failed",
+    { cause }
+  );
+}
+function defaultExtensionStorage() {
+  const global = globalThis;
+  return global.chrome?.storage?.local ?? global.browser?.storage?.local;
+}
+function defaultExtensionRuntime() {
+  const global = globalThis;
+  return global.chrome?.runtime ?? global.browser?.runtime;
+}
+function extensionGet(storage, runtime, keys) {
+  return new Promise((resolve, reject) => {
+    const maybePromise = storage.get(keys, (items) => {
+      const error = extensionLastError(runtime);
+      if (error) reject(extensionOperationError(error));
+      else resolve(items);
+    });
+    if (isPromise(maybePromise)) {
+      maybePromise.then(resolve, (cause) => reject(extensionOperationError(cause)));
+    }
+  });
+}
+function extensionSet(storage, runtime, items) {
+  return new Promise((resolve, reject) => {
+    const maybePromise = storage.set(items, () => {
+      const error = extensionLastError(runtime);
+      if (error) reject(extensionOperationError(error));
+      else resolve();
+    });
+    if (isPromise(maybePromise))
+      maybePromise.then(resolve, (cause) => reject(extensionOperationError(cause)));
+  });
+}
+function extensionRemove(storage, runtime, key) {
+  return new Promise((resolve, reject) => {
+    const maybePromise = storage.remove(key, () => {
+      const error = extensionLastError(runtime);
+      if (error) reject(extensionOperationError(error));
+      else resolve();
+    });
+    if (isPromise(maybePromise))
+      maybePromise.then(resolve, (cause) => reject(extensionOperationError(cause)));
+  });
+}
+function extensionSetAccessLevel(storage, runtime) {
+  const setAccessLevel = storage.setAccessLevel;
+  if (!setAccessLevel) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const maybePromise = setAccessLevel.call(
+      storage,
+      { accessLevel: EXTENSION_TRUSTED_CONTEXTS_ACCESS_LEVEL },
+      () => {
+        const error = extensionLastError(runtime);
+        if (error) reject(extensionOperationError(error));
+        else resolve();
+      }
+    );
+    if (isPromise(maybePromise))
+      maybePromise.then(resolve, (cause) => reject(extensionOperationError(cause)));
+  });
+}
+function extensionLastError(runtime) {
+  return runtime?.lastError ?? null;
+}
+function extensionOperationError(error) {
+  if (error instanceof StorageError) return error;
+  return new StorageError(
+    "STORAGE_NOT_AVAILABLE",
+    storageErrorMessage(error) ?? "extension storage operation failed",
+    { cause: error }
+  );
+}
+function storageErrorMessage(error) {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "object" && error !== null && "message" in error) {
+    const message = error.message;
+    if (typeof message === "string") return message;
+  }
+  return void 0;
+}
+function isPromise(value) {
+  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+
+export { browserStorage, extensionStorage, inMemoryStorage };
+//# sourceMappingURL=storage.js.map
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/storage/index.ts"],"names":[],"mappings":"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","file":"storage.js","sourcesContent":["/**\n * `@invisible-labs/sdk/storage` - storage adapters (spec section 7).\n *\n * The SDK persists recoverable secrets (Recovery Code, LP Position Code, LP\n * Refill Key, withdrawal secret) only through a {@link StorageAdapter}. The\n * `memory`, `browser`, and `extension` adapters are real. Browser and\n * extension adapters persist the bytes provided by the caller; callers that need\n * encrypted-at-rest storage can wrap/encrypt bytes before calling `put`.\n */\n\nimport { StorageError } from \"../core/errors.js\";\n\nconst STORAGE_KEY_PREFIX = \"invisible:sdk:storage:v1:\";\nconst STORAGE_KEY_SEPARATOR = \":\";\nconst BASE64URL_PAD = \"=\";\nconst BASE64URL_PLUS = \"+\";\nconst BASE64URL_SLASH = \"/\";\nconst BASE64URL_MINUS = \"-\";\nconst BASE64URL_UNDERSCORE = \"_\";\nconst BYTE_STRING_CHUNK_SIZE = 0x8000;\nconst EXTENSION_TRUSTED_CONTEXTS_ACCESS_LEVEL = \"TRUSTED_CONTEXTS\";\n\n/**\n * A namespaced key/value store for the SDK's recoverable secrets. Values are\n * raw bytes. Callers may store plaintext bytes, pre-wrapped bytes, or encrypted\n * bytes depending on their host product's storage model.\n */\nexport interface StorageAdapter {\n  /** Which backing the adapter uses. */\n  readonly kind: \"browser\" | \"extension\" | \"server-hkdf\" | \"server-custom\" | \"memory\";\n  put(namespace: string, key: string, value: Uint8Array): Promise<void>;\n  get(namespace: string, key: string): Promise<Uint8Array | null>;\n  list(namespace: string): Promise<string[]>;\n  remove(namespace: string, key: string): Promise<void>;\n  /** `server-hkdf` only: derive a secret from a stable domain context. */\n  derive?(namespace: string, context: string): Promise<Uint8Array>;\n}\n\nexport interface BrowserStorageOptions {\n  /** Override for tests or custom host environments. Defaults to `globalThis.localStorage`. */\n  readonly storage?: StorageLike;\n}\n\nexport interface ExtensionStorageOptions {\n  /** Override for tests or custom extension hosts. Defaults to chrome/browser storage local. */\n  readonly storage?: ExtensionStorageArea;\n  /** Override for tests or custom extension hosts. Defaults to chrome/browser runtime. */\n  readonly runtime?: ExtensionRuntimeLike;\n  /**\n   * Chrome exposes storage.local to content scripts by default. Keep the default\n   * trusted-context restriction when the host API supports it.\n   */\n  readonly restrictAccessToTrustedContexts?: boolean;\n}\n\ninterface StorageLike {\n  readonly length: number;\n  key(index: number): string | null;\n  getItem(key: string): string | null;\n  setItem(key: string, value: string): void;\n  removeItem(key: string): void;\n}\n\ninterface ExtensionStorageArea {\n  get(\n    keys?: string | string[] | Record<string, unknown> | null,\n    callback?: (items: Record<string, unknown>) => void,\n  ): Promise<Record<string, unknown>> | void;\n  set(items: Record<string, string>, callback?: () => void): Promise<void> | void;\n  remove(keys: string | string[], callback?: () => void): Promise<void> | void;\n  setAccessLevel?(details: { accessLevel: string }, callback?: () => void): Promise<void> | void;\n}\n\ninterface ExtensionRuntimeLike {\n  readonly lastError?: { readonly message?: string } | null;\n}\n\n/**\n * In-memory adapter. Fully functional, unencrypted, non-persistent - intended\n * for tests and ephemeral flows, never for real secrets at rest.\n */\nexport function inMemoryStorage(): StorageAdapter {\n  // Each namespace is a separate inner map rather than a flattened composite\n  // key, so a namespace or key containing any character (including a separator)\n  // can never collide across namespaces.\n  const namespaces = new Map<string, Map<string, Uint8Array>>();\n  const bucket = (namespace: string) => {\n    let inner = namespaces.get(namespace);\n    if (!inner) {\n      inner = new Map<string, Uint8Array>();\n      namespaces.set(namespace, inner);\n    }\n    return inner;\n  };\n  return {\n    kind: \"memory\",\n    async put(namespace, key, value) {\n      bucket(namespace).set(key, value);\n    },\n    async get(namespace, key) {\n      return namespaces.get(namespace)?.get(key) ?? null;\n    },\n    async list(namespace) {\n      return [...(namespaces.get(namespace)?.keys() ?? [])];\n    },\n    async remove(namespace, key) {\n      namespaces.get(namespace)?.delete(key);\n    },\n  };\n}\n\n/**\n * Browser `localStorage` adapter. Values are stored as base64url-encoded bytes.\n * Encrypt or wrap the bytes before `put` if your product requires encrypted\n * local persistence.\n *\n * @throws StorageError `STORAGE_NOT_AVAILABLE` if `localStorage` is unavailable.\n */\nexport function browserStorage(options: BrowserStorageOptions = {}): StorageAdapter {\n  const storage = options.storage ?? defaultBrowserStorage();\n  if (!storage) throw new StorageError(\"STORAGE_NOT_AVAILABLE\", \"localStorage is unavailable\");\n  return {\n    kind: \"browser\",\n    async put(namespace, key, value) {\n      try {\n        storage.setItem(storageKey(namespace, key), bytesToBase64Url(value));\n      } catch (cause) {\n        throw browserOperationError(cause);\n      }\n    },\n    async get(namespace, key) {\n      try {\n        const value = storage.getItem(storageKey(namespace, key));\n        return value === null ? null : base64UrlToBytes(value);\n      } catch (cause) {\n        throw browserOperationError(cause);\n      }\n    },\n    async list(namespace) {\n      try {\n        const prefix = storageKeyPrefix(namespace);\n        const keys: string[] = [];\n        for (let index = 0; index < storage.length; index += 1) {\n          const storedKey = storage.key(index);\n          if (storedKey?.startsWith(prefix)) {\n            keys.push(decodeStorageSegment(storedKey.slice(prefix.length)));\n          }\n        }\n        return keys;\n      } catch (cause) {\n        throw browserOperationError(cause);\n      }\n    },\n    async remove(namespace, key) {\n      try {\n        storage.removeItem(storageKey(namespace, key));\n      } catch (cause) {\n        throw browserOperationError(cause);\n      }\n    },\n  };\n}\n\n/**\n * Browser-extension (`chrome.storage.local` / `browser.storage.local`) adapter.\n * Values are stored as base64url-encoded bytes. Encrypt or wrap the bytes before\n * `put` if your product requires encrypted local persistence.\n *\n * @throws StorageError `STORAGE_NOT_AVAILABLE` if extension storage is unavailable.\n */\nexport function extensionStorage(options: ExtensionStorageOptions = {}): StorageAdapter {\n  const storage = options.storage ?? defaultExtensionStorage();\n  if (!storage) {\n    throw new StorageError(\"STORAGE_NOT_AVAILABLE\", \"extension local storage is unavailable\");\n  }\n  const runtime = options.runtime ?? defaultExtensionRuntime();\n  const trustedAccess =\n    options.restrictAccessToTrustedContexts === false\n      ? Promise.resolve()\n      : extensionSetAccessLevel(storage, runtime);\n  return {\n    kind: \"extension\",\n    async put(namespace, key, value) {\n      await trustedAccess;\n      await extensionSet(storage, runtime, {\n        [storageKey(namespace, key)]: bytesToBase64Url(value),\n      });\n    },\n    async get(namespace, key) {\n      await trustedAccess;\n      const storedKey = storageKey(namespace, key);\n      const values = await extensionGet(storage, runtime, storedKey);\n      const value = values[storedKey];\n      return typeof value === \"string\" ? base64UrlToBytes(value) : null;\n    },\n    async list(namespace) {\n      await trustedAccess;\n      const prefix = storageKeyPrefix(namespace);\n      const values = await extensionGet(storage, runtime, null);\n      return Object.keys(values)\n        .filter((key) => key.startsWith(prefix))\n        .map((key) => decodeStorageSegment(key.slice(prefix.length)));\n    },\n    async remove(namespace, key) {\n      await trustedAccess;\n      await extensionRemove(storage, runtime, storageKey(namespace, key));\n    },\n  };\n}\n\nfunction storageKey(namespace: string, key: string): string {\n  return `${storageKeyPrefix(namespace)}${encodeStorageSegment(key)}`;\n}\n\nfunction storageKeyPrefix(namespace: string): string {\n  return `${STORAGE_KEY_PREFIX}${encodeStorageSegment(namespace)}${STORAGE_KEY_SEPARATOR}`;\n}\n\nfunction encodeStorageSegment(value: string): string {\n  return encodeURIComponent(value);\n}\n\nfunction decodeStorageSegment(value: string): string {\n  return decodeURIComponent(value);\n}\n\nfunction bytesToBase64Url(value: Uint8Array): string {\n  let binary = \"\";\n  for (let index = 0; index < value.length; index += BYTE_STRING_CHUNK_SIZE) {\n    binary += String.fromCharCode(...value.slice(index, index + BYTE_STRING_CHUNK_SIZE));\n  }\n  return btoa(binary)\n    .split(BASE64URL_PLUS)\n    .join(BASE64URL_MINUS)\n    .split(BASE64URL_SLASH)\n    .join(BASE64URL_UNDERSCORE)\n    .split(BASE64URL_PAD)\n    .join(\"\");\n}\n\nfunction base64UrlToBytes(value: string): Uint8Array {\n  try {\n    const base64 = value\n      .split(BASE64URL_MINUS)\n      .join(BASE64URL_PLUS)\n      .split(BASE64URL_UNDERSCORE)\n      .join(BASE64URL_SLASH)\n      .padEnd(Math.ceil(value.length / 4) * 4, BASE64URL_PAD);\n    return Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));\n  } catch (cause) {\n    throw new StorageError(\"STORAGE_DECRYPT_FAILED\", \"stored value is not valid base64url\", {\n      cause,\n    });\n  }\n}\n\nfunction defaultBrowserStorage(): StorageLike | undefined {\n  try {\n    return globalThis.localStorage;\n  } catch (cause) {\n    throw new StorageError(\"STORAGE_NOT_AVAILABLE\", \"localStorage is unavailable\", { cause });\n  }\n}\n\nfunction browserOperationError(cause: unknown): StorageError {\n  if (cause instanceof StorageError) return cause;\n  return new StorageError(\n    \"STORAGE_NOT_AVAILABLE\",\n    storageErrorMessage(cause) ?? \"localStorage operation failed\",\n    { cause },\n  );\n}\n\nfunction defaultExtensionStorage(): ExtensionStorageArea | undefined {\n  const global = globalThis as {\n    chrome?: { storage?: { local?: ExtensionStorageArea } };\n    browser?: { storage?: { local?: ExtensionStorageArea } };\n  };\n  return global.chrome?.storage?.local ?? global.browser?.storage?.local;\n}\n\nfunction defaultExtensionRuntime(): ExtensionRuntimeLike | undefined {\n  const global = globalThis as {\n    chrome?: { runtime?: ExtensionRuntimeLike };\n    browser?: { runtime?: ExtensionRuntimeLike };\n  };\n  return global.chrome?.runtime ?? global.browser?.runtime;\n}\n\nfunction extensionGet(\n  storage: ExtensionStorageArea,\n  runtime: ExtensionRuntimeLike | undefined,\n  keys: string | string[] | Record<string, unknown> | null,\n): Promise<Record<string, unknown>> {\n  return new Promise((resolve, reject) => {\n    const maybePromise = storage.get(keys, (items) => {\n      const error = extensionLastError(runtime);\n      if (error) reject(extensionOperationError(error));\n      else resolve(items);\n    });\n    if (isPromise<Record<string, unknown>>(maybePromise)) {\n      maybePromise.then(resolve, (cause) => reject(extensionOperationError(cause)));\n    }\n  });\n}\n\nfunction extensionSet(\n  storage: ExtensionStorageArea,\n  runtime: ExtensionRuntimeLike | undefined,\n  items: Record<string, string>,\n): Promise<void> {\n  return new Promise((resolve, reject) => {\n    const maybePromise = storage.set(items, () => {\n      const error = extensionLastError(runtime);\n      if (error) reject(extensionOperationError(error));\n      else resolve();\n    });\n    if (isPromise<void>(maybePromise))\n      maybePromise.then(resolve, (cause) => reject(extensionOperationError(cause)));\n  });\n}\n\nfunction extensionRemove(\n  storage: ExtensionStorageArea,\n  runtime: ExtensionRuntimeLike | undefined,\n  key: string,\n): Promise<void> {\n  return new Promise((resolve, reject) => {\n    const maybePromise = storage.remove(key, () => {\n      const error = extensionLastError(runtime);\n      if (error) reject(extensionOperationError(error));\n      else resolve();\n    });\n    if (isPromise<void>(maybePromise))\n      maybePromise.then(resolve, (cause) => reject(extensionOperationError(cause)));\n  });\n}\n\nfunction extensionSetAccessLevel(\n  storage: ExtensionStorageArea,\n  runtime: ExtensionRuntimeLike | undefined,\n): Promise<void> {\n  const setAccessLevel = storage.setAccessLevel;\n  if (!setAccessLevel) return Promise.resolve();\n  return new Promise((resolve, reject) => {\n    const maybePromise = setAccessLevel.call(\n      storage,\n      { accessLevel: EXTENSION_TRUSTED_CONTEXTS_ACCESS_LEVEL },\n      () => {\n        const error = extensionLastError(runtime);\n        if (error) reject(extensionOperationError(error));\n        else resolve();\n      },\n    );\n    if (isPromise<void>(maybePromise))\n      maybePromise.then(resolve, (cause) => reject(extensionOperationError(cause)));\n  });\n}\n\nfunction extensionLastError(\n  runtime: ExtensionRuntimeLike | undefined,\n): { readonly message?: string } | null {\n  return runtime?.lastError ?? null;\n}\n\nfunction extensionOperationError(error: unknown): StorageError {\n  if (error instanceof StorageError) return error;\n  return new StorageError(\n    \"STORAGE_NOT_AVAILABLE\",\n    storageErrorMessage(error) ?? \"extension storage operation failed\",\n    { cause: error },\n  );\n}\n\nfunction storageErrorMessage(error: unknown): string | undefined {\n  if (error instanceof Error) return error.message;\n  if (typeof error === \"object\" && error !== null && \"message\" in error) {\n    const message = (error as { message?: unknown }).message;\n    if (typeof message === \"string\") return message;\n  }\n  return undefined;\n}\n\nfunction isPromise<T>(value: unknown): value is Promise<T> {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"then\" in value &&\n    typeof (value as { then: unknown }).then === \"function\"\n  );\n}\n"]}

package/dist/types-ZhV7TIQY.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Transport abstraction.
+ *
+ * A `Transport` is the raw, ordered byte channel between the client and one
+ * coordinator process. It knows how to open, carry frames, and close - nothing
+ * about Noise or attestation, which are session-level concerns layered on top.
+ * This separation lets the same session logic run over a real WebSocket in
+ * production and over an in-memory channel in tests.
+ */
+/** Lifecycle of a transport connection. */
+type ConnectionState = "idle" | "connecting" | "open" | "closing" | "closed";
+/** Unsubscribe a previously-registered listener. */
+type Unsubscribe = () => void;
+/**
+ * The byte channel a session runs over. Implementations are created by a
+ * factory (`inMemoryTransport`, `noiseWebSocketTransport`); consumers never
+ * construct one directly.
+ */
+interface Transport {
+    /**
+     * Open the channel. Resolves once the underlying connection is established
+     * (for the WebSocket transport, once the socket is open). Rejects with a
+     * `TransportError` on failure or abort.
+     *
+     * @param signal optional `AbortSignal`; aborting mid-connect closes the
+     *   socket and rejects.
+     */
+    connect(signal?: AbortSignal): Promise<void>;
+    /** The current lifecycle state. */
+    state(): ConnectionState;
+    /** Subscribe to state transitions. Returns an unsubscribe function. */
+    onStateChange(listener: (state: ConnectionState) => void): Unsubscribe;
+    /** Subscribe to inbound frames. Returns an unsubscribe function. */
+    onMessage(listener: (frame: Uint8Array) => void): Unsubscribe;
+    /**
+     * Send one frame. Frame construction (Noise encryption, length framing) is
+     * not implemented in the skeleton, so this throws `NotImplementedError`.
+     */
+    send(frame: Uint8Array): void;
+    /** Close the channel. Idempotent. */
+    close(): void;
+}
+/**
+ * Minimal browser-`WebSocket`-shaped surface the WebSocket transport depends on.
+ * Node 22's global `WebSocket` and the `ws` package's client both satisfy it,
+ * so tests can inject a stub without a real network.
+ */
+interface WebSocketLike {
+    binaryType: string;
+    readonly readyState: number;
+    send(data: ArrayBufferView | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((event: unknown) => void) | null;
+    onclose: ((event: unknown) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+}
+/** Constructs a {@link WebSocketLike} for a URL. Injected for testability. */
+type WebSocketFactory = (url: string) => WebSocketLike;
+/** Options for {@link noiseWebSocketTransport}. */
+interface NoiseWebSocketTransportOptions {
+    /** The coordinator URL, e.g. `wss://<host>/ws-noise`. */
+    readonly wsUrl: string;
+    /**
+     * WebSocket constructor. Defaults to the platform global `WebSocket`
+     * (present in browsers and Node 22+). Inject a stub or the `ws` client in
+     * environments without one.
+     */
+    readonly webSocketFactory?: WebSocketFactory;
+    /** Milliseconds to wait for the socket to open before failing. Default 30000. */
+    readonly connectTimeoutMs?: number;
+}
+
+export type { ConnectionState as C, NoiseWebSocketTransportOptions as N, Transport as T, Unsubscribe as U, WebSocketFactory as W, WebSocketLike as a };

package/dist/types.generated-CHGSbmLp.d.ts

@@ -0,0 +1,67 @@
+type CoordinatorEndpoint = {
+    readonly wsUrl: string;
+    readonly expectedHostname: string;
+    readonly releasePin: CoordinatorReleasePin;
+    readonly requiredMode: "prod" | "dev" | "auto";
+    readonly allowLocalAttestation?: boolean;
+    readonly roleHint?: "leader" | "watcher";
+    readonly weight?: number;
+};
+type CoordinatorReleasePin = {
+    readonly mrtd: string;
+    readonly binaryHash?: string;
+    readonly intelRootFingerprint?: string;
+    readonly allowMissingDcapCollateral?: boolean;
+    readonly azureMaa?: AzureMaaPin;
+};
+type AzureMaaPin = {
+    readonly issuer: string;
+    readonly jwksUrl: string;
+    readonly policyHash: string;
+};
+type CoordinatorPoolConfig = {
+    readonly endpoints: readonly CoordinatorEndpoint[];
+    readonly reattestEveryMs?: number;
+    readonly failoverDebounceMs?: number;
+    readonly maxReconnectAttempts?: number;
+    readonly noiseTransportTimeoutMs?: number;
+    readonly preferLeader?: boolean;
+    readonly allowedRoles?: readonly ("leader" | "watcher")[];
+};
+type LpPositionView = {
+    readonly id: string;
+    readonly status: "dkg_pending" | "active" | "withdrawing" | "closed";
+    readonly targetShardCount: number;
+    readonly authPublicKey: string;
+    readonly refillPublicKey: string;
+    readonly withdrawalCommitment: string;
+    readonly committedLamports: number;
+    readonly earnedLamports: number;
+    readonly refillThreshold: number;
+    readonly shards: readonly {
+        readonly [key: string]: unknown;
+    }[];
+    readonly createdAt: number;
+};
+type PayoutDestination = {
+    readonly address: string;
+    readonly sharePercent: number;
+    readonly minDelayMs?: number;
+    readonly maxDelayMs?: number;
+    readonly minLamports?: number;
+};
+type PayoutPolicy = {
+    readonly destinations: readonly PayoutDestination[];
+    readonly totalDeadlineMs?: number;
+    readonly batchExclusionId?: string;
+};
+type StorageEnvelope = {
+    readonly namespace: string;
+    readonly key: string;
+    readonly alg: "AES-GCM" | "none";
+    readonly ciphertext: string;
+    readonly iv?: string;
+    readonly createdAtMs: number;
+};
+
+export type { AzureMaaPin as A, CoordinatorEndpoint as C, LpPositionView as L, PayoutPolicy as P, StorageEnvelope as S, CoordinatorPoolConfig as a, CoordinatorReleasePin as b, PayoutDestination as c };