@ibgib/web-gib 0.0.59 → 0.0.61

package/dist/util/device-helper.respec.mjs

@@ -0,0 +1,83 @@
+import { respecfully, iReckon, ifWe // DO NOT REMOVE ifWeMight or ifWe even if no longer used. We constantly change these when focusing tests
+ } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+const maam = `[${import.meta.url}]`, sir = maam;
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { generateDefaultDeviceTag } from './device-helper.mjs';
+await respecfully(sir, 'device-helper', async () => {
+    await ifWe(sir, 'generate clean tag for Desktop Windows Chrome', async () => {
+        const lc = `[generate clean tag for Desktop Windows Chrome]`;
+        try {
+            const tag = generateDefaultDeviceTag({
+                userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+                userAgentData: { platform: 'Windows', mobile: false },
+                randomSuffix: 'a1b2'
+            });
+            iReckon(sir, tag).asTo('tag value').isGonnaBe('chrome-win-a1b2');
+        }
+        catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    });
+    await ifWe(sir, 'generate clean tag for Mobile iOS Safari (iPhone)', async () => {
+        const lc = `[generate clean tag for Mobile iOS Safari (iPhone)]`;
+        try {
+            const tag = generateDefaultDeviceTag({
+                userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1',
+                userAgentData: { platform: 'iOS', mobile: true },
+                randomSuffix: '3c4d'
+            });
+            iReckon(sir, tag).asTo('tag value').isGonnaBe('mobile-safari-ios-3c4d');
+        }
+        catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    });
+    await ifWe(sir, 'generate clean tag for Android Chrome Phone', async () => {
+        const lc = `[generate clean tag for Android Chrome Phone]`;
+        try {
+            const tag = generateDefaultDeviceTag({
+                userAgent: 'Mozilla/5.0 (Linux; Android 13; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36',
+                userAgentData: { platform: 'Android', mobile: true },
+                randomSuffix: '9e8f'
+            });
+            iReckon(sir, tag).asTo('tag value').isGonnaBe('mobile-chrome-android-9e8f');
+        }
+        catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    });
+    await ifWe(sir, 'generate clean tag for iPad / Tablet', async () => {
+        const lc = `[generate clean tag for iPad / Tablet]`;
+        try {
+            const tag = generateDefaultDeviceTag({
+                userAgent: 'Mozilla/5.0 (iPad; CPU OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1',
+                maxTouchPoints: 5,
+                screenWidth: 1024,
+                randomSuffix: '7a8b'
+            });
+            iReckon(sir, tag).asTo('tag value').isGonnaBe('tablet-safari-ios-7a8b');
+        }
+        catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    });
+    await ifWe(sir, 'generate fallback tag with random 4-char suffix when no hints are present', async () => {
+        const lc = `[generate fallback tag with random 4-char suffix]`;
+        try {
+            const tag = generateDefaultDeviceTag({
+                userAgent: '',
+                randomSuffix: '1234'
+            });
+            iReckon(sir, tag).asTo('tag value').isGonnaBe('device-1234');
+        }
+        catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    });
+});
+//# sourceMappingURL=device-helper.respec.mjs.map

package/dist/util/device-helper.respec.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-helper.respec.mjs","sourceRoot":"","sources":["../../src/util/device-helper.respec.mts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibgib/web-gib",
-  "version": "0.0.59",
+  "version": "0.0.61",
   "description": "Framework for creating agentic ibGib web apps. Contains plumbing for ibgib components, agentic framework (currently only Gemini implemented), web-based IndexedDB storage substrate, and more.",
   "funding": {
     "type": "individual",
@@ -29,10 +29,10 @@
   "license": "ISC",
   "dependencies": {
     "@google/genai": "^1.33.0",
-    "@ibgib/core-gib": "^0.1.73",
+    "@ibgib/core-gib": "^0.1.75",
     "@ibgib/encrypt-gib": "^0.3.1",
     "@ibgib/helper-gib": "^0.0.37",
-    "@ibgib/ts-gib": "^0.5.33"
+    "@ibgib/ts-gib": "^0.5.34"
   },
   "engines": {
     "node": ">=19.0.0"

package/src/AUTO-GENERATED-version.mts

@@ -11,4 +11,4 @@
 /**
  * this is the version of this package, auto-updated in the build process
  */
-export const AUTO_GENERATED_VERSION = '0.0.59';
+export const AUTO_GENERATED_VERSION = '0.0.61';

package/src/helpers.mts

@@ -716,6 +716,7 @@ export function getIbGibGlobalThis_IbGib(): IbGibGlobalThisInfo {
         if (!result) {
             console.log(`${lc} initializing globalThis.${GLOBAL_THIS_IBGIB_KEY}... (I: 9d9ff1813448d9a1b82b0e5790a74825)`);
             result = {};
+            globalThis[GLOBAL_THIS_IBGIB_KEY] = result;
         }
 
         return result;

package/src/identity/custodian-delegate-helper.mts.bak

@@ -0,0 +1,7 @@
+/**
+ * @module identity/custodian-delegate-helper
+ *
+ * Re-exports from {@link ./device-delegate-helper.mjs} for backward compatibility.
+ */
+
+export * from './device-delegate-helper.mjs';

package/src/identity/device-delegate-helper.mts

@@ -0,0 +1,135 @@
+/**
+ * @module identity/device-delegate-helper
+ *
+ * Client-side helper functions for deriving, retrieving, persisting, and clearing local
+ * cryptographic device delegate signing tokens ($S_D$) in IndexedDB.
+ *
+ * Applicable symmetrically to Sovereign, Custodial, and Hybrid identities.
+ */
+
+import { extractErrorMsg } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { deriveDeviceDelegateSecret } from "@ibgib/core-gib/dist/keystone/delegate/delegate-helpers.mjs";
+import { storageGet, storagePut, storageDelete } from "../storage/storage-helpers.web.mjs";
+import { getGlobalDbName, getGlobalStoreName } from "../helpers.web.mjs";
+
+export const DEVICE_DELEGATE_SECRET_PREFIX = 'ibgib_device_delegate_secret_';
+
+/**
+ * Builds the IndexedDB storage key for a device delegate secret given its primary identity TJP address.
+ */
+export function getDeviceDelegateSecretKey({ primaryTjpAddr }: { primaryTjpAddr: string }): string {
+    if (!primaryTjpAddr) {
+        throw new Error('primaryTjpAddr is required to get device delegate secret key (E: 1a2b3c4d5e6f7890123456789a000101)');
+    }
+    return `${DEVICE_DELEGATE_SECRET_PREFIX}${primaryTjpAddr}`;
+}
+
+/**
+ * Retrieves the stored device delegate secret for the given primary identity from IndexedDB, if present.
+ */
+export async function getDeviceDelegateSecret({
+    primaryTjpAddr,
+}: {
+    primaryTjpAddr: string;
+}): Promise<string | undefined> {
+    const lc = `[${getDeviceDelegateSecret.name}]`;
+    try {
+        if (!primaryTjpAddr) {
+            throw new Error('primaryTjpAddr is required to get device delegate secret (E: 2a2b3c4d5e6f7890123456789a000102)');
+        }
+
+        const dbName = getGlobalDbName();
+        const storeName = getGlobalStoreName();
+        const key = getDeviceDelegateSecretKey({ primaryTjpAddr });
+
+        return await storageGet({ dbName, storeName, key });
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
+/**
+ * Persists a device delegate secret for the given primary identity into IndexedDB.
+ */
+export async function setDeviceDelegateSecret({
+    primaryTjpAddr,
+    delegateSecret,
+}: {
+    primaryTjpAddr: string;
+    delegateSecret: string;
+}): Promise<void> {
+    const lc = `[${setDeviceDelegateSecret.name}]`;
+    try {
+        if (!primaryTjpAddr) {
+            throw new Error('primaryTjpAddr is required to set device delegate secret (E: 3a2b3c4d5e6f7890123456789a000103)');
+        }
+        if (!delegateSecret) {
+            throw new Error('delegateSecret is required to set device delegate secret (E: 4a2b3c4d5e6f7890123456789a000104)');
+        }
+
+        const dbName = getGlobalDbName();
+        const storeName = getGlobalStoreName();
+        const key = getDeviceDelegateSecretKey({ primaryTjpAddr });
+
+        await storagePut({ dbName, storeName, key, value: delegateSecret });
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
+/**
+ * Retrieves an existing device delegate secret from IndexedDB, or generates a high-entropy 512-bit
+ * secret, persists it, and returns it.
+ */
+export async function getOrCreateDeviceDelegateSecret({
+    primaryTjpAddr,
+    deviceTag,
+}: {
+    primaryTjpAddr: string;
+    deviceTag?: string;
+}): Promise<string> {
+    const lc = `[${getOrCreateDeviceDelegateSecret.name}]`;
+    try {
+        if (!primaryTjpAddr) {
+            throw new Error('primaryTjpAddr is required to get or create device delegate secret (E: 5a2b3c4d5e6f7890123456789a000105)');
+        }
+
+        const existingSecret = await getDeviceDelegateSecret({ primaryTjpAddr });
+        if (existingSecret) {
+            return existingSecret;
+        }
+
+        const newSecret = await deriveDeviceDelegateSecret({ primaryTjpAddr, deviceTag });
+        await setDeviceDelegateSecret({ primaryTjpAddr, delegateSecret: newSecret });
+
+        return newSecret;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
+/**
+ * Removes the stored local device delegate secret from IndexedDB.
+ */
+export async function clearDeviceDelegateSecret({
+    primaryTjpAddr,
+}: {
+    primaryTjpAddr: string;
+}): Promise<void> {
+    const lc = `[${clearDeviceDelegateSecret.name}]`;
+    try {
+        if (!primaryTjpAddr) { return; }
+
+        const dbName = getGlobalDbName();
+        const storeName = getGlobalStoreName();
+        const key = getDeviceDelegateSecretKey({ primaryTjpAddr });
+
+        await storageDelete({ dbName, storeName, key });
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}

package/src/identity/device-delegate.respec.mts

@@ -0,0 +1,125 @@
+import { respecfully, ifWeMight, iReckon } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+import { getIbGibGlobalThis_IbGib } from '../helpers.mjs';
+import {
+    getDeviceDelegateSecretKey,
+    getDeviceDelegateSecret,
+    setDeviceDelegateSecret,
+    getOrCreateDeviceDelegateSecret,
+    clearDeviceDelegateSecret,
+    DEVICE_DELEGATE_SECRET_PREFIX
+} from './device-delegate-helper.mjs';
+
+const sir = `[${import.meta.url}]`;
+
+// Initialize global db & store names for tests
+const globalThisIbGib = getIbGibGlobalThis_IbGib();
+globalThisIbGib.dbName_hack = 'space_gib_db';
+globalThisIbGib.storeName_hack = 'space_gib_store';
+
+// Mock storage substrate for Node test environment
+const inMemoryStore = new Map<string, string>();
+
+if (typeof globalThis.indexedDB === 'undefined') {
+    (globalThis as any).indexedDB = {
+        open: (dbName: string) => {
+            const req: any = {};
+            setTimeout(() => {
+                const db = {
+                    objectStoreNames: { contains: () => true },
+                    transaction: (storeName: string) => ({
+                        objectStore: (sName: string) => ({
+                            get: (key: string) => {
+                                const getReq: any = {};
+                                setTimeout(() => {
+                                    const val = inMemoryStore.get(key);
+                                    getReq.result = val !== undefined ? { value: val } : undefined;
+                                    if (getReq.onsuccess) getReq.onsuccess({ target: getReq });
+                                }, 0);
+                                return getReq;
+                            },
+                            put: (datum: any) => {
+                                const putReq: any = {};
+                                setTimeout(() => {
+                                    inMemoryStore.set(datum.key, datum.value);
+                                    if (putReq.onsuccess) putReq.onsuccess({ target: putReq });
+                                }, 0);
+                                return putReq;
+                            },
+                            delete: (key: string) => {
+                                const delReq: any = {};
+                                setTimeout(() => {
+                                    inMemoryStore.delete(key);
+                                    if (delReq.onsuccess) delReq.onsuccess({ target: delReq });
+                                }, 0);
+                                return delReq;
+                            }
+                        })
+                    }),
+                    close: () => {}
+                };
+                req.result = db;
+                if (req.onsuccess) req.onsuccess({ target: req });
+            }, 0);
+            return req;
+        }
+    };
+}
+
+await respecfully(sir, 'Device Delegate Storage & Secret Lifecycle', async () => {
+
+    await ifWeMight(sir, 'getDeviceDelegateSecretKey constructs deterministic storage key', async () => {
+        const primaryTjpAddr = 'keystone^alice_tjp_12345';
+        const key = getDeviceDelegateSecretKey({ primaryTjpAddr });
+
+        iReckon(sir, key).willEqual(`${DEVICE_DELEGATE_SECRET_PREFIX}${primaryTjpAddr}`);
+    });
+
+    await ifWeMight(sir, 'setDeviceDelegateSecret and getDeviceDelegateSecret persist and retrieve secret', async () => {
+        const primaryTjpAddr = 'keystone^bob_tjp_999';
+        const secret = 'super-secret-512-token-abc';
+
+        await setDeviceDelegateSecret({ primaryTjpAddr, delegateSecret: secret });
+        const retrieved = await getDeviceDelegateSecret({ primaryTjpAddr });
+
+        iReckon(sir, retrieved).willEqual(secret);
+    });
+
+    await ifWeMight(sir, 'getOrCreateDeviceDelegateSecret generates high entropy token on first call and caches it', async () => {
+        const primaryTjpAddr = 'keystone^charlie_tjp_888';
+
+        const token1 = await getOrCreateDeviceDelegateSecret({ primaryTjpAddr, deviceTag: 'laptop' });
+        iReckon(sir, typeof token1 === 'string' && token1.length === 128).willEqual(true);
+
+        const token2 = await getOrCreateDeviceDelegateSecret({ primaryTjpAddr, deviceTag: 'laptop' });
+        iReckon(sir, token1).willEqual(token2);
+    });
+
+    await ifWeMight(sir, 'clearDeviceDelegateSecret removes stored secret', async () => {
+        const primaryTjpAddr = 'keystone^david_tjp_777';
+
+        await getOrCreateDeviceDelegateSecret({ primaryTjpAddr });
+        const beforeClear = await getDeviceDelegateSecret({ primaryTjpAddr });
+        iReckon(sir, !!beforeClear).willEqual(true);
+
+        await clearDeviceDelegateSecret({ primaryTjpAddr });
+        const afterClear = await getDeviceDelegateSecret({ primaryTjpAddr });
+        iReckon(sir, afterClear).willEqual(undefined);
+    });
+
+    await ifWeMight(sir, 'fails fast when global db or store name is uninitialized', async () => {
+        const primaryTjpAddr = 'keystone^failfast_tjp_000';
+        const savedDb = globalThisIbGib.dbName_hack;
+        globalThisIbGib.dbName_hack = undefined as any;
+
+        let threw = false;
+        try {
+            await getDeviceDelegateSecret({ primaryTjpAddr });
+        } catch (error) {
+            threw = true;
+        } finally {
+            globalThisIbGib.dbName_hack = savedDb;
+        }
+
+        iReckon(sir, threw).willEqual(true);
+    });
+});

package/src/identity/identity-constants.mts

@@ -65,8 +65,8 @@ export const IDENTITY_POOL_ID_APP_EPOCH = 'identity-app-epoch';
 
 // ===========================================================================
 // KDF SALTS
-// Used to derive tier-specific MasterSecrets from a root passphrase.
-// Different salt per tier ensures independent secrets even with same passphrase.
+// Used to derive tier-specific MasterSecrets from a root password.
+// Different salt per tier ensures independent secrets even with same password.
 // ===========================================================================
 
 export const IDENTITY_KDF_SALT_META = 'ibgib-identity-meta-v1';

package/src/identity/identity-types.mts

@@ -221,17 +221,17 @@ export interface IIdentityService {
 // ===========================================================================
 
 /**
- * Inputs for deriving a tier-specific MasterSecret from a root passphrase.
+ * Inputs for deriving a tier-specific MasterSecret from a root password.
  *
  * Each tier uses a different salt to ensure independent MasterSecrets
- * even when the same passphrase is used for all tiers.
+ * even when the same password is used for all tiers.
  *
  * @see docs/identity/KEYSTONES.md for per-tier salt conventions
  * @see identity-helpers.mts for derivation functions
  */
 export interface MasterSecretDerivationContext {
-    /** The root passphrase (sovereign path) or server secret (custodial path). */
-    passphrase: string;
+    /** The root password (sovereign path) or server secret (custodial path). */
+    password: string;
 
     /**
      * Tier-specific salt (e.g., `IDENTITY_KDF_SALT_META`, `IDENTITY_KDF_SALT_LOCAL`).

package/src/identity/keystone-sync-service.mts

@@ -9,12 +9,15 @@ import { extractErrorMsg } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs
 import { getIbAndGib, getIbGibAddr } from "@ibgib/ts-gib/dist/helper.mjs";
 import { getGibInfo } from "@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs";
 import { KeystoneIbGib_V1 } from "@ibgib/core-gib/dist/keystone/keystone-types.mjs";
+import { KeystoneService_V1 } from "@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs";
 import { getTimelinesGroupedByTjp, getTjpAddr, toDto } from "@ibgib/core-gib/dist/common/other/ibgib-helper.mjs";
 import { updateSpecialIndex } from "@ibgib/core-gib/dist/timeline/timeline-api.mjs";
+import { isDelegateExpired } from "@ibgib/core-gib/dist/keystone/delegate/delegate-helpers.mjs";
 import { getApiBridge } from "../api/ibgib-api-bridge.mjs";
 import { getGlobalMetaspace_waitIfNeeded } from "../helpers.mjs";
-import { EVENT_IBGIB_IDENTITY_UPDATE_AVAILABLE } from "../ui/ui-constants.mjs";
-import { EventIbGibIdentityUpdateAvailableDetail } from "../ui/ui-types.mjs";
+import { getDeviceDelegateSecret } from "./device-delegate-helper.mjs";
+import { EVENT_IBGIB_IDENTITY_UPDATE_AVAILABLE, EVENT_IBGIB_IDENTITY_RENEWAL_REQUIRED } from "../ui/ui-constants.mjs";
+import { EventIbGibIdentityUpdateAvailableDetail, EventIbGibIdentityRenewalRequiredDetail } from "../ui/ui-types.mjs";
 
 export interface KeystoneUpdateCheckResult {
     hasUpdate: boolean;
@@ -37,6 +40,96 @@ export class KeystoneSyncService {
         }
     }
 
+    private dispatchRenewalRequiredEvent(detail: EventIbGibIdentityRenewalRequiredDetail): void {
+        if (typeof window !== 'undefined') {
+            window.dispatchEvent(new CustomEvent(EVENT_IBGIB_IDENTITY_RENEWAL_REQUIRED, {
+                detail,
+                bubbles: true,
+                composed: true,
+            }));
+        }
+    }
+
+    /**
+     * Retrieves the stored device delegate secret ($S_D$) for an active primary identity from IndexedDB.
+     */
+    public async getDeviceDelegateSecret({
+        primaryTjpAddr
+    }: {
+        primaryTjpAddr: string;
+    }): Promise<string | undefined> {
+        return getDeviceDelegateSecret({ primaryTjpAddr });
+    }
+
+    /**
+     * Checks if the active identity has a valid, unexpired sync delegate on this device.
+     */
+    public async checkDelegateStatus({
+        activePrimaryAddr,
+        metaspace,
+        space
+    }: {
+        activePrimaryAddr: string;
+        metaspace?: any;
+        space?: any;
+    }): Promise<{ isValid: boolean; reason?: 'expired' | 'missing_secret' }> {
+        const lc = `${this.lc}[${this.checkDelegateStatus.name}]`;
+        try {
+            if (!metaspace) metaspace = await getGlobalMetaspace_waitIfNeeded();
+            if (!metaspace) {
+                throw new Error(`${lc} (UNEXPECTED) metaspace falsy? (E: a1b2c3d4e5f60718293a4b5c6d7e8f90)`);
+            }
+            if (!space) space = await metaspace.getLocalUserSpace({ lock: false });
+            if (!space) {
+                throw new Error(`${lc} (UNEXPECTED) space falsy? (E: b2c3d4e5f60718293a4b5c6d7e8f90a1)`);
+            }
+
+            const info = getGibInfo({ ibGibAddr: activePrimaryAddr });
+            const { ib } = getIbAndGib({ ibGibAddr: activePrimaryAddr });
+            const primaryTjpAddr = info.tjpGib ? `${ib}^${info.tjpGib}` : activePrimaryAddr;
+
+            // 1. Check if local secret exists in IndexedDB
+            const secret = await getDeviceDelegateSecret({ primaryTjpAddr });
+            if (!secret) {
+                this.dispatchRenewalRequiredEvent({
+                    activePrimaryAddr,
+                    primaryTjpAddr,
+                    reason: 'missing_secret'
+                });
+                return { isValid: false, reason: 'missing_secret' };
+            }
+
+            // 2. Check if primary keystone has registered delegates and if any are expired
+            const keystoneService = new KeystoneService_V1();
+            const keystone = await keystoneService.getLatestKeystone({
+                addr: activePrimaryAddr,
+                metaspace,
+                space
+            });
+            if (!keystone) {
+                throw new Error(`${lc} (UNEXPECTED) latest primary keystone not found for addr: ${activePrimaryAddr} (E: c3d4e5f60718293a4b5c6d7e8f90a1b2)`);
+            }
+
+            if (keystone?.data?.delegates) {
+                const delegates = Object.values(keystone.data.delegates);
+                const isAnyExpired = delegates.some(d => isDelegateExpired({ delegateInfo: d }));
+                if (isAnyExpired) {
+                    this.dispatchRenewalRequiredEvent({
+                        activePrimaryAddr,
+                        primaryTjpAddr,
+                        reason: 'expired'
+                    });
+                    return { isValid: false, reason: 'expired' };
+                }
+            }
+
+            return { isValid: true };
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            return { isValid: false };
+        }
+    }
+
     /**
      * Checks if a server update exists for the given active primary keystone address.
      */

package/src/index.mts

@@ -18,8 +18,7 @@ export * from "./api/ibgib-api-bridge.mjs";
 
 // Identity & Sync services
 export * from "./identity/keystone-sync-service.mjs";
-export * from "./identity/custodian-delegate-helper.mjs";
-// export * from "./identity/sso-callback-helper.mjs";
+export * from "./identity/device-delegate-helper.mjs";
 export * from "./identity/sso-popup-helper.mjs";
 
 // Identity UI components

package/src/storage/storage-helpers.web.mts

@@ -726,3 +726,50 @@ export async function storageReaddir({
         }
     }
 }
+
+/**
+ * Deletes a single key from indexeddb storage.
+ */
+export async function storageDelete({
+    dbName,
+    storeName,
+    key,
+    logalot = false,
+}: {
+    dbName: string;
+    storeName: string;
+    key: string;
+    logalot?: boolean;
+}): Promise<void> {
+    const lc = `[${storageDelete.name}]`;
+    let db: IDBDatabase | undefined = undefined;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d)`); }
+        await new Promise<void>((resolve, reject) => {
+            const openDBRequest = indexedDB.open(dbName);
+            openDBRequest.onerror = () => {
+                reject(openDBRequest.error);
+            };
+            openDBRequest.onsuccess = () => {
+                db = openDBRequest.result;
+                const transaction = db.transaction(storeName, "readwrite");
+                const objectStore = transaction.objectStore(storeName);
+                const deleteRequest = objectStore.delete(key);
+                deleteRequest.onerror = () => {
+                    reject(deleteRequest.error);
+                };
+                deleteRequest.onsuccess = () => {
+                    resolve();
+                };
+            };
+        });
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (db) {
+            (db as any).close();
+        }
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}