@tearleads/client-sdk 0.0.0-stage → 0.1.11

package/client/localKeyring/service.js

@@ -0,0 +1,116 @@
+import { assertLocalKeyringManifest } from "./manifest.js";
+import { randomBytes } from "./primitives.js";
+import { LOCAL_ROOT_KEY_BYTES } from "./rootKey.js";
+import { localKeyringScopeKey, localSecretContext, normalizeLocalKeyringScope, } from "./scope.js";
+import { createLocalKeyringSession, isDisposedLocalKeyringSession, } from "./session.js";
+import { LOCAL_KEYRING_MANIFEST_FORMAT, } from "./types.js";
+class LocalKeyringService {
+    options;
+    sessionOperationsByScopeKey = new Map();
+    closed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        // The cache is non-owning: callers may still be using returned sessions,
+        // including sessions produced by operations that are currently in flight.
+        this.sessionOperationsByScopeKey.clear();
+        try {
+            this.options.manifestStore.close?.();
+        }
+        finally {
+            this.options.keystore.close?.();
+        }
+    }
+    async deleteSession(scope) {
+        this.assertOpen();
+        const scopeKey = localKeyringScopeKey(scope);
+        const currentOperation = this.sessionOperationsByScopeKey.get(scopeKey);
+        this.sessionOperationsByScopeKey.delete(scopeKey);
+        const currentSession = await currentOperation?.catch(() => null);
+        currentSession?.dispose();
+        await this.options.manifestStore.deleteManifest(scope);
+        await this.options.keystore.deleteWrappingKey(scope);
+    }
+    async getOrCreateSession(scope) {
+        this.assertOpen();
+        const scopeKey = localKeyringScopeKey(scope);
+        const currentOperation = this.sessionOperationsByScopeKey.get(scopeKey);
+        if (currentOperation) {
+            const session = await currentOperation;
+            if (!isDisposedLocalKeyringSession(session)) {
+                return session;
+            }
+            if (this.sessionOperationsByScopeKey.get(scopeKey) === currentOperation) {
+                this.sessionOperationsByScopeKey.delete(scopeKey);
+            }
+            return this.getOrCreateSession(scope);
+        }
+        const operation = this.loadOrCreateSession(scope);
+        this.sessionOperationsByScopeKey.set(scopeKey, operation);
+        try {
+            return await operation;
+        }
+        catch (error) {
+            if (this.sessionOperationsByScopeKey.get(scopeKey) === operation) {
+                this.sessionOperationsByScopeKey.delete(scopeKey);
+            }
+            throw error;
+        }
+    }
+    async loadSession(scope) {
+        this.assertOpen();
+        const manifest = await this.options.manifestStore.loadManifest(scope);
+        if (!manifest) {
+            return null;
+        }
+        return this.openSession(manifest);
+    }
+    async loadOrCreateSession(scope) {
+        return ((await this.loadSession(scope)) ??
+            this.createSession(normalizeLocalKeyringScope(scope)));
+    }
+    async createSession(scope) {
+        const rootKey = randomBytes(LOCAL_ROOT_KEY_BYTES);
+        const handle = await this.options.keystore.getOrCreateWrappingKey(scope);
+        const now = this.options.now().toISOString();
+        const manifest = {
+            createdAt: now,
+            format: LOCAL_KEYRING_MANIFEST_FORMAT,
+            rootKeyEnvelope: await this.options.keystore.wrapSecret({
+                context: localSecretContext(scope, "account-root"),
+                handle,
+                plaintext: rootKey,
+            }),
+            scope,
+            updatedAt: now,
+            version: 1,
+        };
+        await this.options.manifestStore.saveManifest(manifest);
+        return createLocalKeyringSession({ manifest, rootKey });
+    }
+    async openSession(manifest) {
+        assertLocalKeyringManifest(manifest);
+        const rootKey = await this.options.keystore.unwrapSecret({
+            context: localSecretContext(manifest.scope, "account-root"),
+            envelope: manifest.rootKeyEnvelope,
+        });
+        return createLocalKeyringSession({ manifest, rootKey });
+    }
+    assertOpen() {
+        if (this.closed) {
+            throw new Error("Local keyring is closed.");
+        }
+    }
+}
+export function createLocalKeyring(options) {
+    return new LocalKeyringService({
+        ...options,
+        now: options.now ?? (() => new Date()),
+    });
+}
+//# sourceMappingURL=service.js.map

package/client/localKeyring/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["service.ts"],"names":[],"mappings":"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","sourcesContent":["import { assertLocalKeyringManifest } from \"./manifest\";\nimport { randomBytes } from \"./primitives\";\nimport { LOCAL_ROOT_KEY_BYTES } from \"./rootKey\";\nimport {\n  localKeyringScopeKey,\n  localSecretContext,\n  normalizeLocalKeyringScope,\n} from \"./scope\";\nimport {\n  createLocalKeyringSession,\n  isDisposedLocalKeyringSession,\n} from \"./session\";\nimport {\n  LOCAL_KEYRING_MANIFEST_FORMAT,\n  type LocalKeyring,\n  type LocalKeyringManifest,\n  type LocalKeyringOptions,\n  type LocalKeyringScope,\n  type LocalKeyringSession,\n  type NormalizedLocalKeyringScope,\n} from \"./types\";\n\ntype LocalKeyringServiceOptions = Omit<LocalKeyringOptions, \"now\"> & {\n  readonly now: () => Date;\n};\n\nclass LocalKeyringService implements LocalKeyring {\n  private readonly sessionOperationsByScopeKey = new Map<\n    string,\n    Promise<LocalKeyringSession>\n  >();\n  private closed = false;\n\n  constructor(private readonly options: LocalKeyringServiceOptions) {}\n\n  close(): void {\n    if (this.closed) {\n      return;\n    }\n\n    this.closed = true;\n    // The cache is non-owning: callers may still be using returned sessions,\n    // including sessions produced by operations that are currently in flight.\n    this.sessionOperationsByScopeKey.clear();\n    try {\n      this.options.manifestStore.close?.();\n    } finally {\n      this.options.keystore.close?.();\n    }\n  }\n\n  async deleteSession(scope: LocalKeyringScope): Promise<void> {\n    this.assertOpen();\n    const scopeKey = localKeyringScopeKey(scope);\n    const currentOperation = this.sessionOperationsByScopeKey.get(scopeKey);\n    this.sessionOperationsByScopeKey.delete(scopeKey);\n    const currentSession = await currentOperation?.catch(() => null);\n    currentSession?.dispose();\n    await this.options.manifestStore.deleteManifest(scope);\n    await this.options.keystore.deleteWrappingKey(scope);\n  }\n\n  async getOrCreateSession(\n    scope: LocalKeyringScope,\n  ): Promise<LocalKeyringSession> {\n    this.assertOpen();\n    const scopeKey = localKeyringScopeKey(scope);\n    const currentOperation = this.sessionOperationsByScopeKey.get(scopeKey);\n    if (currentOperation) {\n      const session = await currentOperation;\n      if (!isDisposedLocalKeyringSession(session)) {\n        return session;\n      }\n\n      if (this.sessionOperationsByScopeKey.get(scopeKey) === currentOperation) {\n        this.sessionOperationsByScopeKey.delete(scopeKey);\n      }\n      return this.getOrCreateSession(scope);\n    }\n\n    const operation = this.loadOrCreateSession(scope);\n    this.sessionOperationsByScopeKey.set(scopeKey, operation);\n    try {\n      return await operation;\n    } catch (error) {\n      if (this.sessionOperationsByScopeKey.get(scopeKey) === operation) {\n        this.sessionOperationsByScopeKey.delete(scopeKey);\n      }\n      throw error;\n    }\n  }\n\n  async loadSession(\n    scope: LocalKeyringScope,\n  ): Promise<LocalKeyringSession | null> {\n    this.assertOpen();\n    const manifest = await this.options.manifestStore.loadManifest(scope);\n    if (!manifest) {\n      return null;\n    }\n\n    return this.openSession(manifest);\n  }\n\n  private async loadOrCreateSession(\n    scope: LocalKeyringScope,\n  ): Promise<LocalKeyringSession> {\n    return (\n      (await this.loadSession(scope)) ??\n      this.createSession(normalizeLocalKeyringScope(scope))\n    );\n  }\n\n  private async createSession(\n    scope: NormalizedLocalKeyringScope,\n  ): Promise<LocalKeyringSession> {\n    const rootKey = randomBytes(LOCAL_ROOT_KEY_BYTES);\n    const handle = await this.options.keystore.getOrCreateWrappingKey(scope);\n    const now = this.options.now().toISOString();\n    const manifest: LocalKeyringManifest = {\n      createdAt: now,\n      format: LOCAL_KEYRING_MANIFEST_FORMAT,\n      rootKeyEnvelope: await this.options.keystore.wrapSecret({\n        context: localSecretContext(scope, \"account-root\"),\n        handle,\n        plaintext: rootKey,\n      }),\n      scope,\n      updatedAt: now,\n      version: 1,\n    };\n    await this.options.manifestStore.saveManifest(manifest);\n    return createLocalKeyringSession({ manifest, rootKey });\n  }\n\n  private async openSession(\n    manifest: LocalKeyringManifest,\n  ): Promise<LocalKeyringSession> {\n    assertLocalKeyringManifest(manifest);\n    const rootKey = await this.options.keystore.unwrapSecret({\n      context: localSecretContext(manifest.scope, \"account-root\"),\n      envelope: manifest.rootKeyEnvelope,\n    });\n\n    return createLocalKeyringSession({ manifest, rootKey });\n  }\n\n  private assertOpen(): void {\n    if (this.closed) {\n      throw new Error(\"Local keyring is closed.\");\n    }\n  }\n}\n\nexport function createLocalKeyring(options: LocalKeyringOptions): LocalKeyring {\n  return new LocalKeyringService({\n    ...options,\n    now: options.now ?? (() => new Date()),\n  });\n}\n"]}

package/client/localKeyring/session.js

@@ -0,0 +1,76 @@
+import { bytesToBase64 } from "../../internal/encoding/index.js";
+import { copyBytes } from "./primitives.js";
+import { deriveLocalSecretKey } from "./rootKey.js";
+class LocalKeyringSessionImpl {
+    manifest;
+    rootKey;
+    blobStoreKey;
+    identityPersistenceKey;
+    scope;
+    sqliteKey;
+    disposed = false;
+    constructor(manifest, rootKey, derivedKeys) {
+        this.manifest = manifest;
+        this.rootKey = rootKey;
+        this.scope = manifest.scope;
+        this.blobStoreKey = derivedKeys.blobStoreKey;
+        this.identityPersistenceKey = derivedKeys.identityPersistenceKey;
+        this.sqliteKey = derivedKeys.sqliteKey;
+    }
+    static async create(input) {
+        const rootKey = copyBytes(input.rootKey);
+        const [sqliteKeyMaterial, blobStoreKey, identityPersistenceKey] = await Promise.all([
+            deriveLocalSecretKey({
+                purpose: "sqlite",
+                rootKey,
+                scope: input.manifest.scope,
+            }),
+            deriveLocalSecretKey({
+                purpose: "blob-store",
+                rootKey,
+                scope: input.manifest.scope,
+            }),
+            deriveLocalSecretKey({
+                purpose: "identity-persistence",
+                rootKey,
+                scope: input.manifest.scope,
+            }),
+        ]);
+        const sqliteKey = bytesToBase64(sqliteKeyMaterial);
+        sqliteKeyMaterial.fill(0);
+        return new LocalKeyringSessionImpl(input.manifest, rootKey, {
+            blobStoreKey,
+            identityPersistenceKey,
+            sqliteKey,
+        });
+    }
+    async deriveKey(purpose) {
+        if (this.disposed) {
+            throw new Error("Local keyring session has been disposed.");
+        }
+        return deriveLocalSecretKey({
+            purpose,
+            rootKey: this.rootKey,
+            scope: this.scope,
+        });
+    }
+    dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.rootKey.fill(0);
+        this.blobStoreKey.fill(0);
+        this.identityPersistenceKey.fill(0);
+        this.disposed = true;
+    }
+    isDisposed() {
+        return this.disposed;
+    }
+}
+export function createLocalKeyringSession(input) {
+    return LocalKeyringSessionImpl.create(input);
+}
+export function isDisposedLocalKeyringSession(session) {
+    return session instanceof LocalKeyringSessionImpl && session.isDisposed();
+}
+//# sourceMappingURL=session.js.map

package/client/localKeyring/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["session.ts"],"names":[],"mappings":"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","sourcesContent":["import { bytesToBase64 } from \"@tearleads/encoding\";\nimport { copyBytes } from \"./primitives\";\nimport { deriveLocalSecretKey } from \"./rootKey\";\nimport type {\n  LocalKeyPurpose,\n  LocalKeyringManifest,\n  LocalKeyringSession,\n  NormalizedLocalKeyringScope,\n} from \"./types\";\n\nclass LocalKeyringSessionImpl implements LocalKeyringSession {\n  readonly blobStoreKey: Uint8Array<ArrayBuffer>;\n  readonly identityPersistenceKey: Uint8Array<ArrayBuffer>;\n  readonly scope: NormalizedLocalKeyringScope;\n  readonly sqliteKey: string;\n\n  private disposed = false;\n\n  private constructor(\n    readonly manifest: LocalKeyringManifest,\n    private readonly rootKey: Uint8Array<ArrayBuffer>,\n    derivedKeys: {\n      readonly blobStoreKey: Uint8Array<ArrayBuffer>;\n      readonly identityPersistenceKey: Uint8Array<ArrayBuffer>;\n      readonly sqliteKey: string;\n    },\n  ) {\n    this.scope = manifest.scope;\n    this.blobStoreKey = derivedKeys.blobStoreKey;\n    this.identityPersistenceKey = derivedKeys.identityPersistenceKey;\n    this.sqliteKey = derivedKeys.sqliteKey;\n  }\n\n  static async create(input: {\n    readonly manifest: LocalKeyringManifest;\n    readonly rootKey: Uint8Array;\n  }): Promise<LocalKeyringSession> {\n    const rootKey = copyBytes(input.rootKey);\n    const [sqliteKeyMaterial, blobStoreKey, identityPersistenceKey] =\n      await Promise.all([\n        deriveLocalSecretKey({\n          purpose: \"sqlite\",\n          rootKey,\n          scope: input.manifest.scope,\n        }),\n        deriveLocalSecretKey({\n          purpose: \"blob-store\",\n          rootKey,\n          scope: input.manifest.scope,\n        }),\n        deriveLocalSecretKey({\n          purpose: \"identity-persistence\",\n          rootKey,\n          scope: input.manifest.scope,\n        }),\n      ]);\n\n    const sqliteKey = bytesToBase64(sqliteKeyMaterial);\n    sqliteKeyMaterial.fill(0);\n\n    return new LocalKeyringSessionImpl(input.manifest, rootKey, {\n      blobStoreKey,\n      identityPersistenceKey,\n      sqliteKey,\n    });\n  }\n\n  async deriveKey(purpose: LocalKeyPurpose): Promise<Uint8Array<ArrayBuffer>> {\n    if (this.disposed) {\n      throw new Error(\"Local keyring session has been disposed.\");\n    }\n\n    return deriveLocalSecretKey({\n      purpose,\n      rootKey: this.rootKey,\n      scope: this.scope,\n    });\n  }\n\n  dispose(): void {\n    if (this.disposed) {\n      return;\n    }\n\n    this.rootKey.fill(0);\n    this.blobStoreKey.fill(0);\n    this.identityPersistenceKey.fill(0);\n    this.disposed = true;\n  }\n\n  isDisposed(): boolean {\n    return this.disposed;\n  }\n}\n\nexport function createLocalKeyringSession(input: {\n  readonly manifest: LocalKeyringManifest;\n  readonly rootKey: Uint8Array;\n}): Promise<LocalKeyringSession> {\n  return LocalKeyringSessionImpl.create(input);\n}\n\nexport function isDisposedLocalKeyringSession(\n  session: LocalKeyringSession,\n): boolean {\n  return session instanceof LocalKeyringSessionImpl && session.isDisposed();\n}\n"]}

package/client/localKeyring/sqliteKey.d.ts

@@ -0,0 +1,2 @@
+export declare function decodeLocalKeyringSqliteKey(sqliteKey: string): Uint8Array<ArrayBuffer>;
+export declare function encodeLocalKeyringSqliteKey(sqliteKey: Uint8Array): string;

package/client/localKeyring/sqliteKey.js

@@ -0,0 +1,9 @@
+import { base64ToBytes, bytesToBase64 } from "../../internal/encoding/index.js";
+import { copyBytes } from "./primitives.js";
+export function decodeLocalKeyringSqliteKey(sqliteKey) {
+    return copyBytes(base64ToBytes(sqliteKey));
+}
+export function encodeLocalKeyringSqliteKey(sqliteKey) {
+    return bytesToBase64(sqliteKey);
+}
+//# sourceMappingURL=sqliteKey.js.map

package/client/localKeyring/sqliteKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqliteKey.js","sourceRoot":"","sources":["sqliteKey.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,MAAM,UAAU,2BAA2B,CACzC,SAAiB;IAEjB,OAAO,SAAS,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,SAAqB;IAC/D,OAAO,aAAa,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC","sourcesContent":["import { base64ToBytes, bytesToBase64 } from \"@tearleads/encoding\";\nimport { copyBytes } from \"./primitives\";\n\nexport function decodeLocalKeyringSqliteKey(\n  sqliteKey: string,\n): Uint8Array<ArrayBuffer> {\n  return copyBytes(base64ToBytes(sqliteKey));\n}\n\nexport function encodeLocalKeyringSqliteKey(sqliteKey: Uint8Array): string {\n  return bytesToBase64(sqliteKey);\n}\n"]}

package/client/localKeyring/types.d.ts

@@ -0,0 +1,106 @@
+export declare const LOCAL_KEYRING_MANIFEST_FORMAT = "tearleads.local-keyring.manifest";
+export declare const WRAPPED_LOCAL_SECRET_FORMAT = "tearleads.wrapped-local-secret";
+export type LocalKeyringManifestFormat = typeof LOCAL_KEYRING_MANIFEST_FORMAT;
+export type WrappedLocalSecretFormat = typeof WRAPPED_LOCAL_SECRET_FORMAT;
+export type LocalKeyPurpose = "account-root" | "sqlite" | "blob-store" | "identity-persistence" | (string & {});
+export interface LocalKeyringScope {
+    readonly accountId?: string | null | undefined;
+    readonly namespace: string;
+    readonly signingFingerprint?: string | null | undefined;
+}
+export interface NormalizedLocalKeyringScope {
+    readonly accountId: string | null;
+    readonly namespace: string;
+    readonly signingFingerprint: string | null;
+}
+export interface LocalSecretContext {
+    readonly purpose: LocalKeyPurpose;
+    readonly scope: NormalizedLocalKeyringScope;
+}
+export interface WrappingKeyHandle {
+    readonly keyId: string;
+    readonly provider: string;
+}
+export interface WrappedLocalSecretEnvelope {
+    readonly algorithm: string;
+    readonly ciphertext: string;
+    readonly context: LocalSecretContext;
+    readonly format: WrappedLocalSecretFormat;
+    readonly iv?: string | undefined;
+    readonly keyId: string;
+    readonly provider: string;
+    readonly version: 1;
+    readonly wrappedAt: string;
+}
+export interface WrapLocalSecretInput {
+    readonly context: LocalSecretContext;
+    readonly handle: WrappingKeyHandle;
+    readonly plaintext: Uint8Array;
+}
+export interface UnwrapLocalSecretInput {
+    readonly context: LocalSecretContext;
+    readonly envelope: WrappedLocalSecretEnvelope;
+}
+export interface WrappingKeyKeystore {
+    readonly provider: string;
+    close?(): void;
+    deleteWrappingKey(scope: LocalKeyringScope): Promise<void>;
+    getOrCreateWrappingKey(scope: LocalKeyringScope): Promise<WrappingKeyHandle>;
+    unwrapSecret(input: UnwrapLocalSecretInput): Promise<Uint8Array<ArrayBuffer>>;
+    wrapSecret(input: WrapLocalSecretInput): Promise<WrappedLocalSecretEnvelope>;
+}
+export interface LocalKeyringManifest {
+    readonly createdAt: string;
+    readonly format: LocalKeyringManifestFormat;
+    readonly rootKeyEnvelope: WrappedLocalSecretEnvelope;
+    readonly scope: NormalizedLocalKeyringScope;
+    readonly updatedAt: string;
+    readonly version: 1;
+}
+export interface LocalKeyringManifestStore {
+    close?(): void;
+    deleteManifest(scope: LocalKeyringScope): Promise<void>;
+    loadManifest(scope: LocalKeyringScope): Promise<LocalKeyringManifest | null>;
+    saveManifest(manifest: LocalKeyringManifest): Promise<void>;
+}
+export interface LocalKeyringSession {
+    readonly blobStoreKey: Uint8Array<ArrayBuffer>;
+    readonly identityPersistenceKey: Uint8Array<ArrayBuffer>;
+    readonly manifest: LocalKeyringManifest;
+    readonly scope: NormalizedLocalKeyringScope;
+    readonly sqliteKey: string;
+    deriveKey(purpose: LocalKeyPurpose): Promise<Uint8Array<ArrayBuffer>>;
+    dispose(): void;
+}
+export interface LocalKeyring {
+    /**
+     * Releases resources owned by the keyring service. Sessions already returned
+     * to callers remain valid until their holder calls `dispose()`.
+     */
+    close?(): void;
+    deleteSession(scope: LocalKeyringScope): Promise<void>;
+    getOrCreateSession(scope: LocalKeyringScope): Promise<LocalKeyringSession>;
+    loadSession(scope: LocalKeyringScope): Promise<LocalKeyringSession | null>;
+}
+export interface LocalKeyringOptions {
+    readonly keystore: WrappingKeyKeystore;
+    readonly manifestStore: LocalKeyringManifestStore;
+    readonly now?: (() => Date) | undefined;
+}
+export type LocalKeyringManifestStorage = Pick<Storage, "getItem" | "removeItem" | "setItem">;
+/**
+ * How the AES-GCM wrapping key is stored in IndexedDB.
+ *
+ * - `"crypto-key"` (default): persist the live, non-extractable {@link CryptoKey}
+ *   object via structured clone. The key material can never be read back out of
+ *   IndexedDB, only used — the strongest option, and what browsers support.
+ * - `"raw-bytes"`: persist the exported raw key bytes and re-import them on read.
+ *   The key is therefore extractable and readable by anything with IndexedDB
+ *   access, so this is strictly weaker. It exists for WKWebView-based shells
+ *   (Electrobun/Capacitor) where structured-cloning a CryptoKey requires writing
+ *   a "WebCrypto master key" to the macOS keychain — which fails with
+ *   `errSecInteractionNotAllowed` (-25308) in an unsigned app and throws
+ *   `DataCloneError`, taking down keyring init (and, on some WebKit builds,
+ *   crashing the WebContent process).
+ */
+export type WrappingKeyMaterialStorage = "crypto-key" | "raw-bytes";

package/client/localKeyring/types.js

@@ -0,0 +1,3 @@
+export const LOCAL_KEYRING_MANIFEST_FORMAT = "tearleads.local-keyring.manifest";
+export const WRAPPED_LOCAL_SECRET_FORMAT = "tearleads.wrapped-local-secret";
+//# sourceMappingURL=types.js.map

package/client/localKeyring/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,6BAA6B,GAAG,kCAAkC,CAAC;AAChF,MAAM,CAAC,MAAM,2BAA2B,GAAG,gCAAgC,CAAC","sourcesContent":["export const LOCAL_KEYRING_MANIFEST_FORMAT = \"tearleads.local-keyring.manifest\";\nexport const WRAPPED_LOCAL_SECRET_FORMAT = \"tearleads.wrapped-local-secret\";\n\nexport type LocalKeyringManifestFormat = typeof LOCAL_KEYRING_MANIFEST_FORMAT;\nexport type WrappedLocalSecretFormat = typeof WRAPPED_LOCAL_SECRET_FORMAT;\n\nexport type LocalKeyPurpose =\n  | \"account-root\"\n  | \"sqlite\"\n  | \"blob-store\"\n  | \"identity-persistence\"\n  | (string & {});\n\nexport interface LocalKeyringScope {\n  readonly accountId?: string | null | undefined;\n  readonly namespace: string;\n  readonly signingFingerprint?: string | null | undefined;\n}\n\nexport interface NormalizedLocalKeyringScope {\n  readonly accountId: string | null;\n  readonly namespace: string;\n  readonly signingFingerprint: string | null;\n}\n\nexport interface LocalSecretContext {\n  readonly purpose: LocalKeyPurpose;\n  readonly scope: NormalizedLocalKeyringScope;\n}\n\nexport interface WrappingKeyHandle {\n  readonly keyId: string;\n  readonly provider: string;\n}\n\nexport interface WrappedLocalSecretEnvelope {\n  readonly algorithm: string;\n  readonly ciphertext: string;\n  readonly context: LocalSecretContext;\n  readonly format: WrappedLocalSecretFormat;\n  readonly iv?: string | undefined;\n  readonly keyId: string;\n  readonly provider: string;\n  readonly version: 1;\n  readonly wrappedAt: string;\n}\n\nexport interface WrapLocalSecretInput {\n  readonly context: LocalSecretContext;\n  readonly handle: WrappingKeyHandle;\n  readonly plaintext: Uint8Array;\n}\n\nexport interface UnwrapLocalSecretInput {\n  readonly context: LocalSecretContext;\n  readonly envelope: WrappedLocalSecretEnvelope;\n}\n\nexport interface WrappingKeyKeystore {\n  readonly provider: string;\n  close?(): void;\n  deleteWrappingKey(scope: LocalKeyringScope): Promise<void>;\n  getOrCreateWrappingKey(scope: LocalKeyringScope): Promise<WrappingKeyHandle>;\n  unwrapSecret(input: UnwrapLocalSecretInput): Promise<Uint8Array<ArrayBuffer>>;\n  wrapSecret(input: WrapLocalSecretInput): Promise<WrappedLocalSecretEnvelope>;\n}\n\nexport interface LocalKeyringManifest {\n  readonly createdAt: string;\n  readonly format: LocalKeyringManifestFormat;\n  readonly rootKeyEnvelope: WrappedLocalSecretEnvelope;\n  readonly scope: NormalizedLocalKeyringScope;\n  readonly updatedAt: string;\n  readonly version: 1;\n}\n\nexport interface LocalKeyringManifestStore {\n  close?(): void;\n  deleteManifest(scope: LocalKeyringScope): Promise<void>;\n  loadManifest(scope: LocalKeyringScope): Promise<LocalKeyringManifest | null>;\n  saveManifest(manifest: LocalKeyringManifest): Promise<void>;\n}\n\nexport interface LocalKeyringSession {\n  readonly blobStoreKey: Uint8Array<ArrayBuffer>;\n  readonly identityPersistenceKey: Uint8Array<ArrayBuffer>;\n  readonly manifest: LocalKeyringManifest;\n  readonly scope: NormalizedLocalKeyringScope;\n  readonly sqliteKey: string;\n  deriveKey(purpose: LocalKeyPurpose): Promise<Uint8Array<ArrayBuffer>>;\n  dispose(): void;\n}\n\nexport interface LocalKeyring {\n  /**\n   * Releases resources owned by the keyring service. Sessions already returned\n   * to callers remain valid until their holder calls `dispose()`.\n   */\n  close?(): void;\n  deleteSession(scope: LocalKeyringScope): Promise<void>;\n  getOrCreateSession(scope: LocalKeyringScope): Promise<LocalKeyringSession>;\n  loadSession(scope: LocalKeyringScope): Promise<LocalKeyringSession | null>;\n}\n\nexport interface LocalKeyringOptions {\n  readonly keystore: WrappingKeyKeystore;\n  readonly manifestStore: LocalKeyringManifestStore;\n  readonly now?: (() => Date) | undefined;\n}\n\nexport type LocalKeyringManifestStorage = Pick<\n  Storage,\n  \"getItem\" | \"removeItem\" | \"setItem\"\n>;\n\n/**\n * How the AES-GCM wrapping key is stored in IndexedDB.\n *\n * - `\"crypto-key\"` (default): persist the live, non-extractable {@link CryptoKey}\n *   object via structured clone. The key material can never be read back out of\n *   IndexedDB, only used — the strongest option, and what browsers support.\n * - `\"raw-bytes\"`: persist the exported raw key bytes and re-import them on read.\n *   The key is therefore extractable and readable by anything with IndexedDB\n *   access, so this is strictly weaker. It exists for WKWebView-based shells\n *   (Electrobun/Capacitor) where structured-cloning a CryptoKey requires writing\n *   a \"WebCrypto master key\" to the macOS keychain — which fails with\n *   `errSecInteractionNotAllowed` (-25308) in an unsigned app and throws\n *   `DataCloneError`, taking down keyring init (and, on some WebKit builds,\n *   crashing the WebContent process).\n */\nexport type WrappingKeyMaterialStorage = \"crypto-key\" | \"raw-bytes\";\n"]}

package/client/logger.d.ts

@@ -0,0 +1,5 @@
+export interface Logger {
+    log?: ((message: string) => void) | undefined;
+    logError?: ((message: string | Error, cause?: unknown) => void) | undefined;
+}
+export declare function logErrorToConsole(message: string | Error, cause?: unknown): void;

package/client/logger.js

@@ -0,0 +1,8 @@
+export function logErrorToConsole(message, cause) {
+    if (cause === undefined) {
+        console.error(message);
+        return;
+    }
+    console.error(message, cause);
+}
+//# sourceMappingURL=logger.js.map

package/client/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["logger.ts"],"names":[],"mappings":"AAKA,MAAM,UAAU,iBAAiB,CAC/B,OAAuB,EACvB,KAAe;IAEf,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACvB,OAAO;IACT,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AAChC,CAAC","sourcesContent":["export interface Logger {\n  log?: ((message: string) => void) | undefined;\n  logError?: ((message: string | Error, cause?: unknown) => void) | undefined;\n}\n\nexport function logErrorToConsole(\n  message: string | Error,\n  cause?: unknown,\n): void {\n  if (cause === undefined) {\n    console.error(message);\n    return;\n  }\n\n  console.error(message, cause);\n}\n"]}

package/client/network.d.ts

@@ -0,0 +1,87 @@
+export type NetworkListener = (online: boolean) => void;
+export type NetworkMode = "automatic" | "online" | "offline";
+/**
+ * Platform-agnostic source of connectivity status. The default browser
+ * implementation reads `navigator.onLine` and the window `online`/`offline`
+ * events, which is accurate on real browsers. Native shells supply their own
+ * implementation backed by the OS connectivity API — most importantly the
+ * Capacitor Android WebView, where `navigator.onLine` is unreliable and often
+ * reports offline while the device is genuinely connected.
+ *
+ * The contract is deliberately small so a host adapter can satisfy it: a
+ * synchronous best-known read for seeding, plus a push subscription for
+ * changes. A source that can only read connectivity asynchronously returns an
+ * optimistic value from {@link getOnline} and corrects it through the first
+ * emission to a subscriber.
+ */
+export interface NetworkStatusSource {
+    /**
+     * Whether this source continuously governs device connectivity. Browser
+     * `online`/`offline` events and native OS-backed sources set this so the SDK
+     * treats them as the sole source of offline transitions: a backend request
+     * that fails to reach the server then means the backend is unreachable, not
+     * that the device went offline, and must not stop recovery retries (see
+     * {@link Network.reportReachability}). A successful backend request still
+     * proves connectivity and can correct a stale offline signal. Sources that
+     * omit this flag let both request outcomes act as connectivity hints, which is
+     * useful for headless hosts that have no independent connectivity signal.
+     */
+    readonly authoritative?: boolean;
+    /**
+     * Best-known connectivity, read synchronously so the SDK can seed its state
+     * without waiting on an async native round-trip.
+     */
+    getOnline(): boolean;
+    /**
+     * Subscribe to connectivity changes; returns an unsubscribe function. A
+     * source whose underlying read is asynchronous should emit the resolved
+     * value as soon as it is known so the seeded value is corrected promptly.
+     */
+    subscribe(listener: NetworkListener): () => void;
+    /** Release any platform resources (event handlers, native listeners). */
+    dispose?(): void;
+    /**
+     * Optional one-line diagnostic snapshot for the support log — how the source
+     * is reading connectivity (e.g. which native plugin, the raw status, the
+     * WebView's `navigator.onLine`). Purely informational; a source that has
+     * nothing platform-specific to report omits it.
+     */
+    diagnose?(): Promise<string>;
+}
+/**
+ * The default {@link NetworkStatusSource}: `navigator.onLine` for the seed and
+ * the window `online`/`offline` events for changes. Safe to construct in a
+ * non-DOM context (SSR, tests) — it reports online and never registers a
+ * listener when `window` is absent.
+ */
+export declare function createBrowserNetworkStatusSource(): NetworkStatusSource;
+export declare class Network {
+    private readonly listeners;
+    private detectedOnlineValue;
+    private modeValue;
+    private connectivityAuthoritativeValue;
+    constructor(online?: boolean);
+    get online(): boolean;
+    get detectedOnline(): boolean;
+    get mode(): NetworkMode;
+    setOnline(online: boolean): void;
+    setMode(mode: NetworkMode): void;
+    /**
+     * Declares whether an independent {@link NetworkStatusSource} is governing
+     * connectivity. When set, failed-request reachability signals
+     * ({@link reportReachability}) no longer touch `online`; successful requests
+     * may still repair a stale offline signal.
+     */
+    setConnectivityAuthoritative(authoritative: boolean): void;
+    /**
+     * Reports the outcome of a backend request as a connectivity hint. Without an
+     * authoritative source, it drives `online` exactly like a detected change.
+     * With an authoritative browser or OS source, a failed request means the
+     * backend is unreachable — not that the device lost its network — so a
+     * negative hint is ignored. A successful request is conclusive evidence of
+     * connectivity and can repair a stale source reading. Backend failures still
+     * surface downstream while connection retries remain live.
+     */
+    reportReachability(online: boolean): void;
+    subscribe: (listener: NetworkListener) => (() => void);
+}

package/client/network.js

@@ -0,0 +1,105 @@
+import { createListenerSet } from "./listenerSet.js";
+function defaultOnline() {
+    return typeof navigator === "object" && typeof navigator.onLine === "boolean"
+        ? navigator.onLine
+        : true;
+}
+/**
+ * The default {@link NetworkStatusSource}: `navigator.onLine` for the seed and
+ * the window `online`/`offline` events for changes. Safe to construct in a
+ * non-DOM context (SSR, tests) — it reports online and never registers a
+ * listener when `window` is absent.
+ */
+export function createBrowserNetworkStatusSource() {
+    return {
+        // Keep backend failures distinct from device connectivity. If a failed
+        // request flipped this source offline while the browser remained connected,
+        // no later `online` event would fire and the WebSocket retry loop would stay
+        // disabled after the backend recovered.
+        authoritative: true,
+        getOnline: defaultOnline,
+        subscribe(listener) {
+            if (typeof window === "undefined") {
+                return () => { };
+            }
+            const goOnline = () => listener(true);
+            const goOffline = () => listener(false);
+            window.addEventListener("online", goOnline);
+            window.addEventListener("offline", goOffline);
+            return () => {
+                window.removeEventListener("online", goOnline);
+                window.removeEventListener("offline", goOffline);
+            };
+        },
+    };
+}
+function resolveOnline(mode, detectedOnline) {
+    if (mode === "online") {
+        return true;
+    }
+    if (mode === "offline") {
+        return false;
+    }
+    return detectedOnline;
+}
+export class Network {
+    listeners = createListenerSet();
+    detectedOnlineValue;
+    modeValue = "automatic";
+    connectivityAuthoritativeValue = false;
+    constructor(online = defaultOnline()) {
+        this.detectedOnlineValue = online;
+    }
+    get online() {
+        return resolveOnline(this.modeValue, this.detectedOnlineValue);
+    }
+    get detectedOnline() {
+        return this.detectedOnlineValue;
+    }
+    get mode() {
+        return this.modeValue;
+    }
+    setOnline(online) {
+        const previousOnline = this.online;
+        if (this.detectedOnlineValue === online) {
+            return;
+        }
+        this.detectedOnlineValue = online;
+        if (this.online !== previousOnline) {
+            this.listeners.notify(this.online);
+        }
+    }
+    setMode(mode) {
+        if (this.modeValue === mode) {
+            return;
+        }
+        this.modeValue = mode;
+        this.listeners.notify(this.online);
+    }
+    /**
+     * Declares whether an independent {@link NetworkStatusSource} is governing
+     * connectivity. When set, failed-request reachability signals
+     * ({@link reportReachability}) no longer touch `online`; successful requests
+     * may still repair a stale offline signal.
+     */
+    setConnectivityAuthoritative(authoritative) {
+        this.connectivityAuthoritativeValue = authoritative;
+    }
+    /**
+     * Reports the outcome of a backend request as a connectivity hint. Without an
+     * authoritative source, it drives `online` exactly like a detected change.
+     * With an authoritative browser or OS source, a failed request means the
+     * backend is unreachable — not that the device lost its network — so a
+     * negative hint is ignored. A successful request is conclusive evidence of
+     * connectivity and can repair a stale source reading. Backend failures still
+     * surface downstream while connection retries remain live.
+     */
+    reportReachability(online) {
+        if (this.connectivityAuthoritativeValue && !online) {
+            return;
+        }
+        this.setOnline(online);
+    }
+    subscribe = (listener) => this.listeners.subscribe(listener);
+}
+//# sourceMappingURL=network.js.map

package/client/network.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.js","sourceRoot":"","sources":["network.ts"],"names":[],"mappings":"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","sourcesContent":["import { createListenerSet } from \"./listenerSet\";\nexport type NetworkListener = (online: boolean) => void;\nexport type NetworkMode = \"automatic\" | \"online\" | \"offline\";\n\nfunction defaultOnline(): boolean {\n  return typeof navigator === \"object\" && typeof navigator.onLine === \"boolean\"\n    ? navigator.onLine\n    : true;\n}\n\n/**\n * Platform-agnostic source of connectivity status. The default browser\n * implementation reads `navigator.onLine` and the window `online`/`offline`\n * events, which is accurate on real browsers. Native shells supply their own\n * implementation backed by the OS connectivity API — most importantly the\n * Capacitor Android WebView, where `navigator.onLine` is unreliable and often\n * reports offline while the device is genuinely connected.\n *\n * The contract is deliberately small so a host adapter can satisfy it: a\n * synchronous best-known read for seeding, plus a push subscription for\n * changes. A source that can only read connectivity asynchronously returns an\n * optimistic value from {@link getOnline} and corrects it through the first\n * emission to a subscriber.\n */\nexport interface NetworkStatusSource {\n  /**\n   * Whether this source continuously governs device connectivity. Browser\n   * `online`/`offline` events and native OS-backed sources set this so the SDK\n   * treats them as the sole source of offline transitions: a backend request\n   * that fails to reach the server then means the backend is unreachable, not\n   * that the device went offline, and must not stop recovery retries (see\n   * {@link Network.reportReachability}). A successful backend request still\n   * proves connectivity and can correct a stale offline signal. Sources that\n   * omit this flag let both request outcomes act as connectivity hints, which is\n   * useful for headless hosts that have no independent connectivity signal.\n   */\n  readonly authoritative?: boolean;\n  /**\n   * Best-known connectivity, read synchronously so the SDK can seed its state\n   * without waiting on an async native round-trip.\n   */\n  getOnline(): boolean;\n  /**\n   * Subscribe to connectivity changes; returns an unsubscribe function. A\n   * source whose underlying read is asynchronous should emit the resolved\n   * value as soon as it is known so the seeded value is corrected promptly.\n   */\n  subscribe(listener: NetworkListener): () => void;\n  /** Release any platform resources (event handlers, native listeners). */\n  dispose?(): void;\n  /**\n   * Optional one-line diagnostic snapshot for the support log — how the source\n   * is reading connectivity (e.g. which native plugin, the raw status, the\n   * WebView's `navigator.onLine`). Purely informational; a source that has\n   * nothing platform-specific to report omits it.\n   */\n  diagnose?(): Promise<string>;\n}\n\n/**\n * The default {@link NetworkStatusSource}: `navigator.onLine` for the seed and\n * the window `online`/`offline` events for changes. Safe to construct in a\n * non-DOM context (SSR, tests) — it reports online and never registers a\n * listener when `window` is absent.\n */\nexport function createBrowserNetworkStatusSource(): NetworkStatusSource {\n  return {\n    // Keep backend failures distinct from device connectivity. If a failed\n    // request flipped this source offline while the browser remained connected,\n    // no later `online` event would fire and the WebSocket retry loop would stay\n    // disabled after the backend recovered.\n    authoritative: true,\n    getOnline: defaultOnline,\n    subscribe(listener: NetworkListener): () => void {\n      if (typeof window === \"undefined\") {\n        return () => {};\n      }\n      const goOnline = () => listener(true);\n      const goOffline = () => listener(false);\n      window.addEventListener(\"online\", goOnline);\n      window.addEventListener(\"offline\", goOffline);\n      return () => {\n        window.removeEventListener(\"online\", goOnline);\n        window.removeEventListener(\"offline\", goOffline);\n      };\n    },\n  };\n}\n\nfunction resolveOnline(mode: NetworkMode, detectedOnline: boolean): boolean {\n  if (mode === \"online\") {\n    return true;\n  }\n\n  if (mode === \"offline\") {\n    return false;\n  }\n\n  return detectedOnline;\n}\n\nexport class Network {\n  private readonly listeners = createListenerSet<[boolean]>();\n  private detectedOnlineValue: boolean;\n  private modeValue: NetworkMode = \"automatic\";\n  private connectivityAuthoritativeValue = false;\n\n  constructor(online: boolean = defaultOnline()) {\n    this.detectedOnlineValue = online;\n  }\n\n  get online(): boolean {\n    return resolveOnline(this.modeValue, this.detectedOnlineValue);\n  }\n\n  get detectedOnline(): boolean {\n    return this.detectedOnlineValue;\n  }\n\n  get mode(): NetworkMode {\n    return this.modeValue;\n  }\n\n  setOnline(online: boolean): void {\n    const previousOnline = this.online;\n    if (this.detectedOnlineValue === online) {\n      return;\n    }\n\n    this.detectedOnlineValue = online;\n    if (this.online !== previousOnline) {\n      this.listeners.notify(this.online);\n    }\n  }\n\n  setMode(mode: NetworkMode): void {\n    if (this.modeValue === mode) {\n      return;\n    }\n\n    this.modeValue = mode;\n    this.listeners.notify(this.online);\n  }\n\n  /**\n   * Declares whether an independent {@link NetworkStatusSource} is governing\n   * connectivity. When set, failed-request reachability signals\n   * ({@link reportReachability}) no longer touch `online`; successful requests\n   * may still repair a stale offline signal.\n   */\n  setConnectivityAuthoritative(authoritative: boolean): void {\n    this.connectivityAuthoritativeValue = authoritative;\n  }\n\n  /**\n   * Reports the outcome of a backend request as a connectivity hint. Without an\n   * authoritative source, it drives `online` exactly like a detected change.\n   * With an authoritative browser or OS source, a failed request means the\n   * backend is unreachable — not that the device lost its network — so a\n   * negative hint is ignored. A successful request is conclusive evidence of\n   * connectivity and can repair a stale source reading. Backend failures still\n   * surface downstream while connection retries remain live.\n   */\n  reportReachability(online: boolean): void {\n    if (this.connectivityAuthoritativeValue && !online) {\n      return;\n    }\n\n    this.setOnline(online);\n  }\n\n  subscribe = (listener: NetworkListener): (() => void) =>\n    this.listeners.subscribe(listener);\n}\n"]}