@droponair/sdk-js 0.24.3 → 0.25.1

package/dist/crypto/crypto-service.js

@@ -1,35 +1,50 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CryptoService = void 0;
-const tweetnacl_1 = __importDefault(require("tweetnacl"));
 const bytes_1 = require("../core/bytes");
+const nacl_identity_provider_1 = require("./nacl-identity-provider");
 const payload_format_1 = require("./payload-format");
-const STORAGE_PRIVATE = 'droponair.identity.privateKey.v1';
-const STORAGE_PUBLIC = 'droponair.identity.publicKey.v1';
 function asBufferSource(data) {
     return new Uint8Array(data);
 }
+/**
+ * HKDF inputs, unchanged from the original implementation and deliberately
+ * defined once. Both are part of the wire format: two participants must derive
+ * the same key from the same shared secret, so these strings and the user-id
+ * ordering cannot vary by provider, platform or SDK version without breaking
+ * every conversation that spans the change.
+ */
+function hkdfSalt() {
+    return (0, bytes_1.utf8Encode)('droponair-e2ee-hkdf-salt-v1');
+}
+function hkdfInfo(localUserId, peerUserId) {
+    const ordering = [localUserId, peerUserId].sort().join(':');
+    return (0, bytes_1.utf8Encode)(`droponair-e2ee-v1:${ordering}`);
+}
+function isIdentityProvider(value) {
+    return typeof value.deriveMessageKey === 'function';
+}
 class CryptoService {
-    constructor(storage, sessionManager) {
-        this.storage = storage;
+    /**
+     * Accepts either an identity provider or, for compatibility, the storage
+     * adapter it used to take. Passing storage keeps the previous behaviour
+     * exactly, by wrapping it in the tweetnacl provider.
+     */
+    constructor(storageOrIdentity, sessionManager) {
         this.sessionManager = sessionManager;
+        this.identity = isIdentityProvider(storageOrIdentity)
+            ? storageOrIdentity
+            : new nacl_identity_provider_1.NaclIdentityProvider(storageOrIdentity);
+    }
+    /** How the identity private key is held. See {@link KeyCustody}. */
+    get keyCustody() {
+        return this.identity.keyCustody;
     }
     async generateIdentity() {
-        const keyPair = tweetnacl_1.default.box.keyPair();
-        await this.storage.set(STORAGE_PRIVATE, (0, bytes_1.toBase64)(keyPair.secretKey));
-        await this.storage.set(STORAGE_PUBLIC, (0, bytes_1.toBase64)(keyPair.publicKey));
-        return { publicKey: (0, bytes_1.toBase64)(keyPair.publicKey) };
+        return { publicKey: await this.identity.getPublicKey() };
     }
     async getOrCreateIdentity() {
-        const existingPublic = await this.storage.get(STORAGE_PUBLIC);
-        const existingPrivate = await this.storage.get(STORAGE_PRIVATE);
-        if (existingPublic && existingPrivate) {
-            return { publicKey: existingPublic };
-        }
-        return this.generateIdentity();
+        return { publicKey: await this.identity.getPublicKey() };
     }
     async deriveSharedSecret(peerUserId, peerPublicKeyBase64, localUserId) {
         // Cache by public key (not userId) to support multi-device, same user may have
@@ -39,17 +54,14 @@ class CryptoService {
         if (cached) {
             return cached;
         }
-        const privateBase64 = await this.storage.get(STORAGE_PRIVATE);
-        if (!privateBase64) {
-            throw new Error('Local identity keypair is missing');
-        }
-        const privateKey = (0, bytes_1.fromBase64)(privateBase64);
-        const peerPublicKey = (0, bytes_1.fromBase64)(peerPublicKeyBase64);
-        if (peerPublicKey.length !== 32 || privateKey.length !== 32) {
-            throw new Error('Invalid X25519 key length');
-        }
-        const sharedSecret = tweetnacl_1.default.scalarMult(privateKey, peerPublicKey);
-        const symmetricKey = await this.deriveAesKey(sharedSecret, localUserId, peerUserId);
+        // salt and info are part of the wire format, so they are computed here and
+        // handed to the provider rather than left to it. A provider that invented
+        // its own would derive keys nobody else could reproduce.
+        const symmetricKey = await this.identity.deriveMessageKey({
+            peerPublicKey: peerPublicKeyBase64,
+            salt: hkdfSalt(),
+            info: hkdfInfo(localUserId, peerUserId)
+        });
         this.sessionManager.set(cacheKey, symmetricKey);
         return symmetricKey;
     }
@@ -78,21 +90,6 @@ class CryptoService {
         }, symmetricKey, asBufferSource(unpacked.ciphertext));
         return (0, bytes_1.utf8Decode)(new Uint8Array(plainBuffer));
     }
-    async deriveAesKey(sharedSecret, localUserId, peerUserId) {
-        const ordering = [localUserId, peerUserId].sort().join(':');
-        const info = (0, bytes_1.utf8Encode)(`droponair-e2ee-v1:${ordering}`);
-        const salt = (0, bytes_1.utf8Encode)('droponair-e2ee-hkdf-salt-v1');
-        const ikm = await crypto.subtle.importKey('raw', asBufferSource(sharedSecret), 'HKDF', false, ['deriveKey']);
-        return crypto.subtle.deriveKey({
-            name: 'HKDF',
-            hash: 'SHA-256',
-            salt: asBufferSource(salt),
-            info: asBufferSource(info)
-        }, ikm, {
-            name: 'AES-GCM',
-            length: 256
-        }, false, ['encrypt', 'decrypt']);
-    }
     buildAad(context) {
         return (0, bytes_1.utf8Encode)(`${context.messageId}|${context.senderId}|${context.recipientId}|${context.timestamp}`);
     }

package/dist/crypto/nacl-identity-provider.d.ts

@@ -0,0 +1,25 @@
+import { KeyCustody, KeyStorageAdapter, SecureIdentityProvider } from '../core/types';
+/**
+ * The original identity path, unchanged in behaviour and kept as the default.
+ *
+ * tweetnacl needs the private key as bytes, so this reports `software` custody:
+ * whatever the configured {@link KeyStorageAdapter} does, the key is reachable
+ * from script at derive time. That is not a flaw in this class, it is what using
+ * tweetnacl means, and saying so plainly is the point of `keyCustody`.
+ *
+ * It stays the default because every existing consumer already has keys in this
+ * format, and silently moving them would change which messages they can read.
+ * Opting into {@link WebCryptoIdentityProvider} is a decision an application
+ * makes, not one the SDK makes for it.
+ */
+export declare class NaclIdentityProvider implements SecureIdentityProvider {
+    private readonly storage;
+    readonly keyCustody: KeyCustody;
+    constructor(storage: KeyStorageAdapter);
+    getPublicKey(): Promise<string>;
+    deriveMessageKey(params: {
+        peerPublicKey: string;
+        salt: Uint8Array;
+        info: Uint8Array;
+    }): Promise<CryptoKey>;
+}

package/dist/crypto/nacl-identity-provider.js

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NaclIdentityProvider = void 0;
+const tweetnacl_1 = __importDefault(require("tweetnacl"));
+const bytes_1 = require("../core/bytes");
+const STORAGE_PRIVATE = 'droponair.identity.privateKey.v1';
+const STORAGE_PUBLIC = 'droponair.identity.publicKey.v1';
+/**
+ * The original identity path, unchanged in behaviour and kept as the default.
+ *
+ * tweetnacl needs the private key as bytes, so this reports `software` custody:
+ * whatever the configured {@link KeyStorageAdapter} does, the key is reachable
+ * from script at derive time. That is not a flaw in this class, it is what using
+ * tweetnacl means, and saying so plainly is the point of `keyCustody`.
+ *
+ * It stays the default because every existing consumer already has keys in this
+ * format, and silently moving them would change which messages they can read.
+ * Opting into {@link WebCryptoIdentityProvider} is a decision an application
+ * makes, not one the SDK makes for it.
+ */
+class NaclIdentityProvider {
+    constructor(storage) {
+        this.storage = storage;
+        this.keyCustody = 'software';
+    }
+    async getPublicKey() {
+        const existingPublic = await this.storage.get(STORAGE_PUBLIC);
+        const existingPrivate = await this.storage.get(STORAGE_PRIVATE);
+        if (existingPublic && existingPrivate) {
+            return existingPublic;
+        }
+        const keyPair = tweetnacl_1.default.box.keyPair();
+        await this.storage.set(STORAGE_PRIVATE, (0, bytes_1.toBase64)(keyPair.secretKey));
+        await this.storage.set(STORAGE_PUBLIC, (0, bytes_1.toBase64)(keyPair.publicKey));
+        return (0, bytes_1.toBase64)(keyPair.publicKey);
+    }
+    async deriveMessageKey(params) {
+        const privateBase64 = await this.storage.get(STORAGE_PRIVATE);
+        if (!privateBase64) {
+            throw new Error('Local identity keypair is missing');
+        }
+        const privateKey = (0, bytes_1.fromBase64)(privateBase64);
+        const peerPublicKey = (0, bytes_1.fromBase64)(params.peerPublicKey);
+        if (peerPublicKey.length !== 32 || privateKey.length !== 32) {
+            throw new Error('Invalid X25519 key length');
+        }
+        const sharedSecret = tweetnacl_1.default.scalarMult(privateKey, peerPublicKey);
+        const ikm = await crypto.subtle.importKey('raw', new Uint8Array(sharedSecret), 'HKDF', false, ['deriveKey']);
+        return crypto.subtle.deriveKey({
+            name: 'HKDF',
+            hash: 'SHA-256',
+            salt: params.salt,
+            info: params.info
+        }, ikm, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+    }
+}
+exports.NaclIdentityProvider = NaclIdentityProvider;

package/dist/crypto/webcrypto-identity-provider.d.ts

@@ -0,0 +1,116 @@
+import { KeyCustody, KeyStorageAdapter, SecureIdentityProvider } from '../core/types';
+interface StoredIdentity {
+    privateKey: CryptoKey;
+    publicKeyBase64: string;
+}
+/**
+ * Identity provider backed by a non-extractable WebCrypto X25519 key.
+ *
+ * The private key is generated with `extractable: false` and stored in IndexedDB
+ * as a CryptoKey rather than as bytes. CryptoKey is structured-cloneable, so it
+ * survives the round trip, and `crypto.subtle.exportKey` refuses on the way out.
+ * Script on the origin can therefore ask this key to derive, but cannot copy it.
+ *
+ * This is the same curve tweetnacl's `box` uses, and `deriveBits` computes the
+ * same X25519 shared secret, so a message encrypted through this provider is
+ * indistinguishable on the wire from one encrypted through the legacy path. That
+ * property is what makes adoption safe, and it is asserted by tests rather than
+ * assumed.
+ *
+ * Availability is not universal. Call {@link isSupported} before choosing this;
+ * the SDK does, and falls back rather than throwing at send time.
+ */
+/**
+ * Where the identity record is kept between sessions.
+ *
+ * Extracted so persistence is not welded to IndexedDB. It lets the equivalence
+ * tests run somewhere without IndexedDB, which is the only way to verify wire
+ * compatibility outside a browser, and it lets a consumer persist the record
+ * somewhere of their own choosing.
+ *
+ * Whatever implements it must preserve the CryptoKey as an object. Serialising
+ * the record to JSON destroys the key silently and leaves a record that looks
+ * present and is unusable.
+ */
+export interface IdentityRecordStore {
+    read(): Promise<StoredIdentity | null>;
+    write(record: StoredIdentity): Promise<void>;
+}
+/** Keeps the identity for the lifetime of the process only. Used by tests. */
+export declare class MemoryIdentityRecordStore implements IdentityRecordStore {
+    private record;
+    read(): Promise<StoredIdentity | null>;
+    write(record: StoredIdentity): Promise<void>;
+}
+/**
+ * Wrap a raw 32 byte X25519 scalar so WebCrypto will import it.
+ *
+ * This is what makes migration possible at all: an existing tweetnacl identity is
+ * 32 raw bytes, and without this there is no way to hand it to WebCrypto, which
+ * would mean every existing user had to be re-keyed and would lose the ability to
+ * read their own history.
+ */
+export declare function rawX25519ToPkcs8(raw: Uint8Array): Uint8Array;
+export declare class WebCryptoIdentityProvider implements SecureIdentityProvider {
+    readonly keyCustody: KeyCustody;
+    private cached;
+    private readonly store;
+    constructor(store?: IdentityRecordStore);
+    /**
+     * Whether this environment can actually do non-extractable X25519.
+     *
+     * Probes by generating a throwaway key rather than sniffing user agents,
+     * because support has arrived at different times in different engines and a
+     * feature test is the only answer that stays true.
+     */
+    static isSupported(): Promise<boolean>;
+    /**
+     * Whether an X25519 key actually survives being stored and read back here.
+     *
+     * Separate from {@link isSupported} because the two are genuinely different
+     * questions and one engine answers them differently. **WebKit can generate and
+     * derive with a non-extractable X25519 key, and then loses it through
+     * structured clone**: the IndexedDB write reports success, and after a reload
+     * the record is simply absent. Measured 2026-08-15; AES-GCM, ECDH P-256 and
+     * ECDSA P-256 all survive there, X25519 alone does not.
+     *
+     * That failure is silent, which is what makes it dangerous. An identity that
+     * regenerates every load means every previous conversation becomes
+     * undecryptable, with no error raised anywhere to explain it, so this must be
+     * checked rather than assumed.
+     *
+     * Costs one write and one read of a throwaway key, so call it once at startup
+     * rather than per message.
+     */
+    static canPersist(store: IdentityRecordStore): Promise<boolean>;
+    /**
+     * Adopt an existing tweetnacl identity, so a user keeps their conversations.
+     *
+     * The scalar is imported as a non-extractable key and the raw copy is then
+     * removed from the {@link KeyStorageAdapter}, which is the whole point: after
+     * this, the same identity exists but script can no longer read it.
+     *
+     * Ordering matters and is deliberate. The import and the write happen first,
+     * and only a successful write is followed by deleting the raw copy. Interrupted
+     * at any point, the user still has a usable identity somewhere: either the old
+     * raw key, or the new protected one, never neither.
+     *
+     * Returns false when there is nothing to migrate, so a caller can run it
+     * unconditionally on startup.
+     */
+    migrateFromKeyStorage(storage: KeyStorageAdapter): Promise<boolean>;
+    getPublicKey(): Promise<string>;
+    deriveMessageKey(params: {
+        peerPublicKey: string;
+        salt: Uint8Array;
+        info: Uint8Array;
+    }): Promise<CryptoKey>;
+    private getOrCreate;
+}
+/** The default: an IndexedDB object store, which preserves CryptoKey objects. */
+export declare class IndexedDbIdentityRecordStore implements IdentityRecordStore {
+    private openDb;
+    read(): Promise<StoredIdentity | null>;
+    write(record: StoredIdentity): Promise<void>;
+}
+export {};

package/dist/crypto/webcrypto-identity-provider.js

@@ -0,0 +1,265 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IndexedDbIdentityRecordStore = exports.WebCryptoIdentityProvider = exports.MemoryIdentityRecordStore = void 0;
+exports.rawX25519ToPkcs8 = rawX25519ToPkcs8;
+const bytes_1 = require("../core/bytes");
+/**
+ * A database of its own, not a second store inside `droponair_sdk`.
+ *
+ * IndexedDbKeyStorage already owns `droponair_sdk` at version 1 with a
+ * `secure_keys` store. Adding another store to the same name and version means
+ * whichever opens second finds no upgrade needed, its store is never created,
+ * and every read fails. Both are used together in a real application, so this
+ * was not hypothetical: it made the identity vanish across a reload under WebKit
+ * while appearing to work in Chromium, purely on open ordering.
+ *
+ * Coordinating versions between two independent components is the other way to
+ * solve it and a worse one, because it couples their release cycles forever.
+ */
+const DB_NAME = 'droponair_identity';
+const STORE_NAME = 'identity_v2';
+const DB_VERSION = 1;
+const RECORD_KEY = 'x25519';
+/** Where the tweetnacl path keeps its identity. Must match NaclIdentityProvider. */
+const LEGACY_STORAGE_PRIVATE = 'droponair.identity.privateKey.v1';
+const LEGACY_STORAGE_PUBLIC = 'droponair.identity.publicKey.v1';
+/** Keeps the identity for the lifetime of the process only. Used by tests. */
+class MemoryIdentityRecordStore {
+    constructor() {
+        this.record = null;
+    }
+    async read() {
+        return this.record;
+    }
+    async write(record) {
+        this.record = record;
+    }
+}
+exports.MemoryIdentityRecordStore = MemoryIdentityRecordStore;
+/**
+ * DER prefix for a PKCS#8 X25519 private key, per RFC 8410.
+ *
+ * WebCrypto will not import a bare 32 byte scalar, but it will import PKCS#8,
+ * and for X25519 the encoding is fixed: everything before the key is constant,
+ * so the wrapper is a concatenation rather than a DER encoder.
+ *
+ *   30 2e             SEQUENCE, 46 bytes
+ *   02 01 00          INTEGER 0, the version
+ *   30 05             SEQUENCE, 5 bytes
+ *   06 03 2b 65 6e    OID 1.3.101.110, X25519
+ *   04 22             OCTET STRING, 34 bytes
+ *   04 20             OCTET STRING, 32 bytes, the scalar follows
+ */
+const PKCS8_X25519_PREFIX = new Uint8Array([
+    0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e, 0x04, 0x22, 0x04, 0x20
+]);
+/**
+ * Wrap a raw 32 byte X25519 scalar so WebCrypto will import it.
+ *
+ * This is what makes migration possible at all: an existing tweetnacl identity is
+ * 32 raw bytes, and without this there is no way to hand it to WebCrypto, which
+ * would mean every existing user had to be re-keyed and would lose the ability to
+ * read their own history.
+ */
+function rawX25519ToPkcs8(raw) {
+    if (raw.length !== 32) {
+        throw new Error('Invalid X25519 key length');
+    }
+    const out = new Uint8Array(PKCS8_X25519_PREFIX.length + 32);
+    out.set(PKCS8_X25519_PREFIX, 0);
+    out.set(raw, PKCS8_X25519_PREFIX.length);
+    return out;
+}
+class WebCryptoIdentityProvider {
+    constructor(store) {
+        this.keyCustody = 'non-extractable';
+        this.cached = null;
+        this.store = store ?? new IndexedDbIdentityRecordStore();
+    }
+    /**
+     * Whether this environment can actually do non-extractable X25519.
+     *
+     * Probes by generating a throwaway key rather than sniffing user agents,
+     * because support has arrived at different times in different engines and a
+     * feature test is the only answer that stays true.
+     */
+    static async isSupported() {
+        try {
+            // Deliberately does not require IndexedDB. Persistence is pluggable, and
+            // conflating the two meant this reported "unsupported" in any environment
+            // without IndexedDB even where X25519 worked perfectly, which is exactly
+            // what hid the equivalence test from ever running.
+            if (typeof crypto === 'undefined' || !crypto.subtle)
+                return false;
+            const pair = (await crypto.subtle.generateKey({ name: 'X25519' }, false, [
+                'deriveBits'
+            ]));
+            await crypto.subtle.deriveBits({ name: 'X25519', public: pair.publicKey }, pair.privateKey, 256);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Whether an X25519 key actually survives being stored and read back here.
+     *
+     * Separate from {@link isSupported} because the two are genuinely different
+     * questions and one engine answers them differently. **WebKit can generate and
+     * derive with a non-extractable X25519 key, and then loses it through
+     * structured clone**: the IndexedDB write reports success, and after a reload
+     * the record is simply absent. Measured 2026-08-15; AES-GCM, ECDH P-256 and
+     * ECDSA P-256 all survive there, X25519 alone does not.
+     *
+     * That failure is silent, which is what makes it dangerous. An identity that
+     * regenerates every load means every previous conversation becomes
+     * undecryptable, with no error raised anywhere to explain it, so this must be
+     * checked rather than assumed.
+     *
+     * Costs one write and one read of a throwaway key, so call it once at startup
+     * rather than per message.
+     */
+    static async canPersist(store) {
+        try {
+            const pair = (await crypto.subtle.generateKey({ name: 'X25519' }, false, [
+                'deriveBits'
+            ]));
+            const rawPublic = await crypto.subtle.exportKey('raw', pair.publicKey);
+            const probe = {
+                privateKey: pair.privateKey,
+                publicKeyBase64: (0, bytes_1.toBase64)(new Uint8Array(rawPublic))
+            };
+            await store.write(probe);
+            const back = await store.read();
+            // The write above will have overwritten any real identity, so a caller must
+            // only use a store dedicated to probing. The SDK does exactly that.
+            return !!back?.privateKey;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Adopt an existing tweetnacl identity, so a user keeps their conversations.
+     *
+     * The scalar is imported as a non-extractable key and the raw copy is then
+     * removed from the {@link KeyStorageAdapter}, which is the whole point: after
+     * this, the same identity exists but script can no longer read it.
+     *
+     * Ordering matters and is deliberate. The import and the write happen first,
+     * and only a successful write is followed by deleting the raw copy. Interrupted
+     * at any point, the user still has a usable identity somewhere: either the old
+     * raw key, or the new protected one, never neither.
+     *
+     * Returns false when there is nothing to migrate, so a caller can run it
+     * unconditionally on startup.
+     */
+    async migrateFromKeyStorage(storage) {
+        const privateBase64 = await storage.get(LEGACY_STORAGE_PRIVATE);
+        const publicBase64 = await storage.get(LEGACY_STORAGE_PUBLIC);
+        if (!privateBase64 || !publicBase64) {
+            return false;
+        }
+        const raw = (0, bytes_1.fromBase64)(privateBase64);
+        const privateKey = await crypto.subtle.importKey('pkcs8', rawX25519ToPkcs8(raw), { name: 'X25519' }, 
+        // Non-extractable from this moment on. The bytes still exist in the
+        // adapter until the delete below, which is why that delete is not optional.
+        false, ['deriveBits']);
+        const record = { privateKey, publicKeyBase64: publicBase64 };
+        await this.store.write(record);
+        this.cached = record;
+        await storage.remove(LEGACY_STORAGE_PRIVATE);
+        return true;
+    }
+    async getPublicKey() {
+        const identity = await this.getOrCreate();
+        return identity.publicKeyBase64;
+    }
+    async deriveMessageKey(params) {
+        const identity = await this.getOrCreate();
+        const peerRaw = (0, bytes_1.fromBase64)(params.peerPublicKey);
+        if (peerRaw.length !== 32) {
+            throw new Error('Invalid X25519 key length');
+        }
+        const peerKey = await crypto.subtle.importKey('raw', peerRaw, { name: 'X25519' }, false, []);
+        // deriveBits, not deriveKey: HKDF needs the shared secret as key material,
+        // and this is the only point where it exists. It is never returned to a
+        // caller and never stored.
+        const sharedSecret = await crypto.subtle.deriveBits({ name: 'X25519', public: peerKey }, identity.privateKey, 256);
+        const ikm = await crypto.subtle.importKey('raw', sharedSecret, 'HKDF', false, ['deriveKey']);
+        return crypto.subtle.deriveKey({
+            name: 'HKDF',
+            hash: 'SHA-256',
+            salt: params.salt,
+            info: params.info
+        }, ikm, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+    }
+    async getOrCreate() {
+        if (this.cached)
+            return this.cached;
+        const existing = await this.store.read();
+        if (existing) {
+            this.cached = existing;
+            return existing;
+        }
+        const pair = (await crypto.subtle.generateKey({ name: 'X25519' }, false, [
+            'deriveBits'
+        ]));
+        // The public half is exported once and kept as base64, because it is
+        // published to peers anyway. Only the private half is protected.
+        const rawPublic = await crypto.subtle.exportKey('raw', pair.publicKey);
+        const record = {
+            privateKey: pair.privateKey,
+            publicKeyBase64: (0, bytes_1.toBase64)(new Uint8Array(rawPublic))
+        };
+        await this.store.write(record);
+        this.cached = record;
+        return record;
+    }
+}
+exports.WebCryptoIdentityProvider = WebCryptoIdentityProvider;
+/** The default: an IndexedDB object store, which preserves CryptoKey objects. */
+class IndexedDbIdentityRecordStore {
+    async openDb() {
+        return new Promise((resolve, reject) => {
+            const request = indexedDB.open(DB_NAME, DB_VERSION);
+            request.onupgradeneeded = () => {
+                const db = request.result;
+                if (!db.objectStoreNames.contains(STORE_NAME)) {
+                    db.createObjectStore(STORE_NAME);
+                }
+            };
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async read() {
+        const db = await this.openDb();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(STORE_NAME, 'readonly');
+            const request = tx.objectStore(STORE_NAME).get(RECORD_KEY);
+            request.onsuccess = () => {
+                const value = request.result;
+                // A record written by an older or broken build could be missing the
+                // CryptoKey. Treating that as absent regenerates rather than throwing on
+                // every send.
+                if (!value || !value.privateKey || !value.publicKeyBase64) {
+                    resolve(null);
+                    return;
+                }
+                resolve(value);
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async write(record) {
+        const db = await this.openDb();
+        await new Promise((resolve, reject) => {
+            const tx = db.transaction(STORE_NAME, 'readwrite');
+            tx.objectStore(STORE_NAME).put(record, RECORD_KEY);
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+}
+exports.IndexedDbIdentityRecordStore = IndexedDbIdentityRecordStore;

package/dist/index.d.ts

@@ -1,11 +1,40 @@
+import { IdentityRecordStore, WebCryptoIdentityProvider } from './crypto/webcrypto-identity-provider';
 import { InitializeOptions, DropOnAirClient } from './core/types';
 export { SDK_VERSION, PROTOCOL_VERSION, PAYLOAD_FORMAT_VERSION } from './version';
+/**
+ * An identity whose private key script cannot read, or `null` where the platform
+ * cannot provide one.
+ *
+ * Returns `null` rather than throwing, and rather than quietly handing back a
+ * weaker implementation, because those are the two ways a caller ends up
+ * believing it has a guarantee it does not have. A `null` here means: this engine
+ * cannot do it, carry on with the ordinary path and know that you did.
+ *
+ * Two separate conditions are checked, and both matter. `isSupported` asks
+ * whether the primitive exists. `canPersist` asks whether a key survives being
+ * stored and read back, which WebKit fails for X25519 while reporting the write
+ * as successful. An identity that silently regenerates every load makes every
+ * previous conversation undecryptable, with nothing raised to explain it, so the
+ * check is worth its round trip.
+ *
+ * Migration is the caller's to trigger, via `migrateFromKeyStorage`, because it
+ * removes the raw key and that is not a decision to take on someone's behalf.
+ */
+export declare function createSecureIdentity(store?: IdentityRecordStore): Promise<WebCryptoIdentityProvider | null>;
 export declare function initialize(options: InitializeOptions): Promise<DropOnAirClient>;
 export type { InitializeOptions, DropOnAirClient, DropOnAirEvent, MessageCallback, EventCallback, DecryptedMessage, KeyStorageAdapter, CallEvent, CallEventType, CallEventCallback, TurnCredentials, BroadcastMessage, BroadcastCallback, GroupInfo, GroupMemberInfo, DecryptedGroupMessage, GroupMessageCallback, GroupCallEvent, GroupCallEventType, GroupCallEventCallback, Room, RoomPolicy, CreateRoomOptions, UpdateRoomOptions, SfuToken, SfuRecording, MessageEditEvent, MessageEditCallback, MessageDeleteEvent, MessageDeleteCallback, DeviceInfo, ReadReceiptEvent, ReadReceiptCallback, NotificationClearEvent, NotificationClearCallback, DraftSyncEvent, DraftSyncCallback, } from './core/types';
 export type { AttachmentEncryptionType, AttachmentConversationType, AttachmentRef, DeviceWrappedKey, CreateUploadSessionOptions, UploadSession, PrepareAttachmentOptions, DownloadedAttachment, } from './attachment/attachment-types';
 export { SseTransport, type SseTransportOptions, type SseFrameHandler, type SseStateHandler, } from './transport/sse-transport';
 export { WebTransportTransport, type WebTransportTransportOptions, type WTFrameHandler, type WTStateHandler, } from './transport/webtransport-transport';
 export { selectTransport, type TransportLane, type SelectTransportOptions, } from './transport/auto-select';
+/**
+ * Identity providers, for a private key that script cannot read.
+ *
+ * Exported so a consumer can construct one deliberately, supply its own record
+ * store, or implement {@link SecureIdentityProvider} against custody of its own.
+ * The platform offers the capability; it does not impose an implementation.
+ */
+export { WebCryptoIdentityProvider, IndexedDbIdentityRecordStore, MemoryIdentityRecordStore, type IdentityRecordStore, } from './crypto/webcrypto-identity-provider';
 declare const _default: {
     initialize: typeof initialize;
 };