@ibgib/web-gib 0.0.61 → 0.0.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibgib/web-gib",
-  "version": "0.0.61",
+  "version": "0.0.62",
   "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,7 +29,7 @@
   "license": "ISC",
   "dependencies": {
     "@google/genai": "^1.33.0",
-    "@ibgib/core-gib": "^0.1.75",
+    "@ibgib/core-gib": "^0.1.76",
     "@ibgib/encrypt-gib": "^0.3.1",
     "@ibgib/helper-gib": "^0.0.37",
     "@ibgib/ts-gib": "^0.5.34"

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.61';
+export const AUTO_GENERATED_VERSION = '0.0.62';

package/src/helpers.web.mts

@@ -424,6 +424,9 @@ export async function promptForText({
     }
 }
 
+import { evaluatePasskeyPrf, isPasskeyPrfSupported } from "./identity/passkey-helper.mjs";
+import { KeystonePasskeyEntry } from "@ibgib/core-gib/dist/keystone/keystone-types.mjs";
+
 /**
  * not implemented atow (12/2024). I think we'll have perhaps a modal dialog
  * with a known name and get at it that way.
@@ -431,9 +434,11 @@ export async function promptForText({
 export async function promptForSecret({
     msg,
     confirm,
+    passkeys,
 }: {
-    msg?: string,
-    confirm: boolean,
+    msg?: string;
+    confirm: boolean;
+    passkeys?: Record<string, KeystonePasskeyEntry>;
 }): Promise<string> {
     const lc = `[${promptForSecret.name}]`;
     try {
@@ -445,6 +450,19 @@ export async function promptForSecret({
         let attempts = 0;
         let maxAttempts = 5;
 
+        const prfSupported = await isPasskeyPrfSupported().catch(() => false);
+        const onPasskeyAuth = (prfSupported && passkeys && Object.keys(passkeys).length > 0)
+            ? async (passkeyEntry?: any) => {
+                if (!passkeyEntry) return undefined;
+                const { passkeySecret } = await evaluatePasskeyPrf({
+                    credentialId: passkeyEntry.credentialId,
+                    salt: passkeyEntry.salt,
+                    transports: passkeyEntry.transports,
+                });
+                return passkeySecret;
+            }
+            : undefined;
+
         do {
             attempts++;
             if (attempts >= maxAttempts) {
@@ -458,6 +476,8 @@ export async function promptForSecret({
                 showInput: true,
                 isPassword: true,
                 defaultValue: undefined,
+                passkeys,
+                onPasskeyAuth,
             });
             if (result === undefined) { throw new Error(`user cancelled (E: 91519d04378e84106f3df8eb36d99725)`); }
 

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

@@ -7,11 +7,14 @@
  * 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 { extractErrorMsg, getSaferSubstring } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { deriveDeviceDelegateSecret, deriveDelegateSecret, createSyncDelegateKeystone } from "@ibgib/core-gib/dist/keystone/delegate/delegate-helpers.mjs";
+import { generateDefaultDeviceTag } from "../util/device-helper.mjs";
 import { storageGet, storagePut, storageDelete } from "../storage/storage-helpers.web.mjs";
 import { getGlobalDbName, getGlobalStoreName } from "../helpers.web.mjs";
 
+export { generateDefaultDeviceTag };
+
 export const DEVICE_DELEGATE_SECRET_PREFIX = 'ibgib_device_delegate_secret_';
 
 /**
@@ -133,3 +136,133 @@ export async function clearDeviceDelegateSecret({
         throw error;
     }
 }
+
+/**
+ * Creates a Sovereign Password-based sync delegate for this device.
+ * Standardized format: `pwd-${safeUsername}-${defaultDeviceTag}`
+ */
+export async function createSovereignDeviceSyncDelegate({
+    username,
+    primaryTjpAddr,
+    masterSecret,
+    metaspace,
+    space,
+}: {
+    username: string;
+    primaryTjpAddr: string;
+    masterSecret: string;
+    metaspace?: any;
+    space?: any;
+}): Promise<{ delegateKeystone: any; deviceTag: string; delegateSecret: string }> {
+    const delegateSecret = await deriveDelegateSecret({ masterSecret });
+    await setDeviceDelegateSecret({ primaryTjpAddr, delegateSecret });
+
+    const safeUser = getSaferSubstring({ text: username, length: 8, keepLiterals: ['-'] }) || 'user';
+    const defaultDeviceTag = generateDefaultDeviceTag();
+    const deviceTag = `pwd-${safeUser}-${defaultDeviceTag}`;
+    const sovereignSyncProfileName = process.env.KEYSTONE_PROFILE_SOVEREIGN_SYNC;
+    if (!sovereignSyncProfileName || !sovereignSyncProfileName.trim()) {
+        throw new Error('KEYSTONE_PROFILE_SOVEREIGN_SYNC environment variable is missing.');
+    }
+
+    const delegateKeystone = await createSyncDelegateKeystone({
+        profileName: sovereignSyncProfileName.trim() as any,
+        username,
+        deviceTag,
+        primaryTjpAddr,
+        delegateSecret,
+        additionalFrameDetails: { client: 'space-gib-web' },
+        metaspace,
+        space,
+    });
+
+    return { delegateKeystone, deviceTag, delegateSecret };
+}
+
+/**
+ * Creates an OAuth2 Custodial sync delegate for this device.
+ * Standardized format: `oauth2-${providerId}-${defaultDeviceTag}`
+ */
+export async function createOAuth2DeviceSyncDelegate({
+    providerId,
+    username = 'user',
+    primaryTjpAddr,
+    custodianReqs,
+    metaspace,
+    space,
+}: {
+    providerId: string;
+    username?: string;
+    primaryTjpAddr: string;
+    custodianReqs?: any;
+    metaspace?: any;
+    space?: any;
+}): Promise<{ delegateKeystone: any; deviceTag: string; delegateSecret: string }> {
+    const delegateSecret = await getOrCreateDeviceDelegateSecret({ primaryTjpAddr });
+    const defaultDeviceTag = generateDefaultDeviceTag();
+    const deviceTag = `oauth2-${providerId}-${defaultDeviceTag}`;
+    const custodianSyncProfileName = process.env.KEYSTONE_PROFILE_CUSTODIAN_SYNC;
+    if (!custodianSyncProfileName || !custodianSyncProfileName.trim()) {
+        throw new Error('KEYSTONE_PROFILE_CUSTODIAN_SYNC environment variable is missing.');
+    }
+
+    const delegateKeystone = await createSyncDelegateKeystone({
+        profileName: custodianSyncProfileName.trim() as any,
+        username,
+        deviceTag,
+        primaryTjpAddr,
+        delegateSecret,
+        custodianReqs,
+        additionalFrameDetails: { client: 'space-gib-web' },
+        metaspace,
+        space,
+    });
+
+    return { delegateKeystone, deviceTag, delegateSecret };
+}
+
+/**
+ * Creates an Email Custodial sync delegate for this device.
+ * Standardized format: `email-${safeUser}@${safeDomain}-${defaultDeviceTag}`
+ */
+export async function createEmailDeviceSyncDelegate({
+    email,
+    primaryTjpAddr,
+    custodianReqs,
+    metaspace,
+    space,
+}: {
+    email: string;
+    primaryTjpAddr: string;
+    custodianReqs?: any;
+    metaspace?: any;
+    space?: any;
+}): Promise<{ delegateKeystone: any; deviceTag: string; delegateSecret: string }> {
+    const delegateSecret = await getOrCreateDeviceDelegateSecret({ primaryTjpAddr });
+    const defaultDeviceTag = generateDefaultDeviceTag();
+    const [emailUser = '', emailDomain = ''] = (email || '').split('@');
+    const safeUser = getSaferSubstring({ text: emailUser, length: 8, keepLiterals: ['-'] }) || 'user';
+    const domainPart = emailDomain.split('.')[0] || '';
+    const safeDomain = domainPart ? getSaferSubstring({ text: domainPart, length: 8, keepLiterals: ['-'] }) : '';
+    const emailTag = safeDomain ? `${safeUser}@${safeDomain}` : safeUser;
+    const deviceTag = `email-${emailTag}-${defaultDeviceTag}`;
+    const username = safeUser;
+    const custodianSyncProfileName = process.env.KEYSTONE_PROFILE_CUSTODIAN_SYNC;
+    if (!custodianSyncProfileName || !custodianSyncProfileName.trim()) {
+        throw new Error('KEYSTONE_PROFILE_CUSTODIAN_SYNC environment variable is missing.');
+    }
+
+    const delegateKeystone = await createSyncDelegateKeystone({
+        profileName: custodianSyncProfileName.trim() as any,
+        username,
+        deviceTag,
+        primaryTjpAddr,
+        delegateSecret,
+        custodianReqs,
+        additionalFrameDetails: { client: 'space-gib-web' },
+        metaspace,
+        space,
+    });
+
+    return { delegateKeystone, deviceTag, delegateSecret };
+}

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

@@ -1,4 +1,4 @@
-import { respecfully, ifWeMight, iReckon } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+import { respecfully, ifWe, ifWeMight, iReckon } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
 import { getIbGibGlobalThis_IbGib } from '../helpers.mjs';
 import {
     getDeviceDelegateSecretKey,
@@ -67,14 +67,14 @@ if (typeof globalThis.indexedDB === 'undefined') {
 
 await respecfully(sir, 'Device Delegate Storage & Secret Lifecycle', async () => {
 
-    await ifWeMight(sir, 'getDeviceDelegateSecretKey constructs deterministic storage key', async () => {
+    await ifWe(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 () => {
+    await ifWe(sir, 'setDeviceDelegateSecret and getDeviceDelegateSecret persist and retrieve secret', async () => {
         const primaryTjpAddr = 'keystone^bob_tjp_999';
         const secret = 'super-secret-512-token-abc';
 
@@ -84,7 +84,7 @@ await respecfully(sir, 'Device Delegate Storage & Secret Lifecycle', async () =>
         iReckon(sir, retrieved).willEqual(secret);
     });
 
-    await ifWeMight(sir, 'getOrCreateDeviceDelegateSecret generates high entropy token on first call and caches it', async () => {
+    await ifWe(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' });
@@ -94,7 +94,7 @@ await respecfully(sir, 'Device Delegate Storage & Secret Lifecycle', async () =>
         iReckon(sir, token1).willEqual(token2);
     });
 
-    await ifWeMight(sir, 'clearDeviceDelegateSecret removes stored secret', async () => {
+    await ifWe(sir, 'clearDeviceDelegateSecret removes stored secret', async () => {
         const primaryTjpAddr = 'keystone^david_tjp_777';
 
         await getOrCreateDeviceDelegateSecret({ primaryTjpAddr });
@@ -106,7 +106,7 @@ await respecfully(sir, 'Device Delegate Storage & Secret Lifecycle', async () =>
         iReckon(sir, afterClear).willEqual(undefined);
     });
 
-    await ifWeMight(sir, 'fails fast when global db or store name is uninitialized', async () => {
+    await ifWe(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;

package/src/identity/passkey-helper.mts

@@ -0,0 +1,304 @@
+/**
+ * @module identity/passkey-helper
+ *
+ * WebAuthn Level 3 PRF (Pseudo-Random Function) Passkey helper service.
+ * Derives deterministic 256-bit symmetric secrets from hardware biometrics
+ * (Touch ID, Windows Hello, Android Biometrics, YubiKey 5Ci) and creates
+ * passkey device sync delegates.
+ */
+
+import { extractErrorMsg, getSaferSubstring } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { deriveDelegateSecret, createSyncDelegateKeystone } from '@ibgib/core-gib/dist/keystone/delegate/delegate-helpers.mjs';
+import { AuthenticatorTransport, KeystonePasskeyEntry } from '@ibgib/core-gib/dist/keystone/keystone-types.mjs';
+import { generateDefaultDeviceTag, setDeviceDelegateSecret } from './device-delegate-helper.mjs';
+
+/**
+ * Checks if the browser and underlying platform authenticator support WebAuthn PRF.
+ */
+export async function isPasskeyPrfSupported(): Promise<boolean> {
+    try {
+        if (typeof window === 'undefined' || !window.PublicKeyCredential) {
+            return false;
+        }
+        if (typeof (window.PublicKeyCredential as any).getClientCapabilities === 'function') {
+            const caps = await (window.PublicKeyCredential as any).getClientCapabilities();
+            if (caps && caps['prf']) {
+                return true;
+            }
+        }
+        // Fallback: check if PublicKeyCredential exists and platform authenticator is available
+        if (typeof PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable === 'function') {
+            const isPlatformAvailable = await PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable();
+            return isPlatformAvailable;
+        }
+        return false;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Helper to convert an ArrayBuffer to a lowercase hex string.
+ */
+export function bufferToHex(buffer: ArrayBuffer | ArrayBufferLike): string {
+    return Array.from(new Uint8Array(buffer as ArrayBuffer))
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+
+/**
+ * Helper to convert a hex string to a Uint8Array.
+ */
+export function hexToUint8Array(hex: string): Uint8Array {
+    const cleanHex = hex.replace(/[^0-9a-fA-F]/g, '');
+    const bytes = new Uint8Array(Math.floor(cleanHex.length / 2));
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(cleanHex.substr(i * 2, 2), 16);
+    }
+    return bytes;
+}
+
+/**
+ * Helper to normalize a salt string or buffer into a 32-byte Uint8Array for PRF evaluation.
+ */
+export function normalizeSaltTo32Bytes(salt: string | Uint8Array): Uint8Array {
+    if (salt instanceof Uint8Array) {
+        if (salt.length === 32) return salt;
+        const result = new Uint8Array(32);
+        result.set(salt.subarray(0, 32));
+        return result;
+    }
+    // If hex string of length 64 (32 bytes)
+    if (/^[0-9a-fA-F]{64}$/.test(salt)) {
+        return hexToUint8Array(salt);
+    }
+    // Text string: encode and pad/slice to 32 bytes
+    const encoded = new TextEncoder().encode(salt);
+    const result = new Uint8Array(32);
+    result.set(encoded.subarray(0, 32));
+    return result;
+}
+
+/**
+ * Creates and registers a new WebAuthn resident passkey credential with PRF enabled.
+ */
+/**
+ * Creates and registers a new WebAuthn resident passkey credential with PRF enabled.
+ */
+export async function registerPasskeyCredential({
+    username,
+    displayName = username,
+    rpName = 'ibgib',
+    rpId,
+    salt,
+}: {
+    username: string;
+    displayName?: string;
+    rpName?: string;
+    rpId?: string;
+    salt?: string | Uint8Array;
+}): Promise<{
+    credentialId: string;
+    rawId: ArrayBuffer;
+    transports: AuthenticatorTransport[];
+    passkeySecret?: string;
+}> {
+    const lc = `[registerPasskeyCredential]`;
+    try {
+        if (typeof window === 'undefined' || !navigator.credentials?.create) {
+            throw new Error('WebAuthn is not supported in this browser environment.');
+        }
+
+        const effectiveRpId = rpId || (typeof window !== 'undefined' ? window.location.hostname : undefined);
+        const challenge = crypto.getRandomValues(new Uint8Array(32));
+        const userId = new TextEncoder().encode(username.slice(0, 64));
+
+        const saltBuffer = salt ? normalizeSaltTo32Bytes(salt) : undefined;
+        const prfExtension = saltBuffer
+            ? { eval: { first: saltBuffer } }
+            : {};
+
+        const credential = await navigator.credentials.create({
+            publicKey: {
+                challenge,
+                rp: {
+                    name: rpName,
+                    ...(effectiveRpId ? { id: effectiveRpId } : {})
+                },
+                user: {
+                    id: userId,
+                    name: username,
+                    displayName
+                },
+                pubKeyCredParams: [
+                    { alg: -7, type: 'public-key' },   // ES256 (ECDSA P-256)
+                    { alg: -257, type: 'public-key' }, // RS256 (RSA)
+                    { alg: -8, type: 'public-key' },   // Ed25519
+                ],
+                authenticatorSelection: {
+                    residentKey: 'required',
+                    userVerification: 'required'
+                },
+                extensions: {
+                    prf: prfExtension
+                } as any
+            }
+        }) as PublicKeyCredential;
+
+        if (!credential) {
+            throw new Error('Passkey creation was cancelled or failed.');
+        }
+
+        const credentialId = bufferToHex(credential.rawId);
+        const response: any = credential.response;
+        const transports: AuthenticatorTransport[] = (typeof response.getTransports === 'function')
+            ? response.getTransports()
+            : [];
+
+        const extResults: any = credential.getClientExtensionResults?.() || {};
+        console.log(`${lc} WebAuthn registration clientExtensionResults:`, extResults);
+
+        let passkeySecret: string | undefined;
+        if (extResults.prf?.results?.first) {
+            passkeySecret = bufferToHex(extResults.prf.results.first);
+            console.log(`${lc} Evaluated PRF directly during create!`);
+        }
+
+        return {
+            credentialId,
+            rawId: credential.rawId,
+            transports,
+            passkeySecret
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
+/**
+ * Evaluates the PRF extension on a passkey assertion to derive a deterministic 256-bit symmetric secret.
+ */
+export async function evaluatePasskeyPrf({
+    salt,
+    credentialId,
+    transports,
+    rpId,
+}: {
+    salt: string | Uint8Array;
+    credentialId?: string;
+    transports?: AuthenticatorTransport[];
+    rpId?: string;
+}): Promise<{
+    passkeySecret: string;
+    credentialId: string;
+}> {
+    const lc = `[evaluatePasskeyPrf]`;
+    try {
+        if (typeof window === 'undefined' || !navigator.credentials?.get) {
+            throw new Error('WebAuthn is not supported in this browser environment.');
+        }
+
+        const effectiveRpId = rpId || (typeof window !== 'undefined' ? window.location.hostname : undefined);
+        const challenge = crypto.getRandomValues(new Uint8Array(32));
+        const saltBuffer = normalizeSaltTo32Bytes(salt);
+
+        let allowCredentials: PublicKeyCredentialDescriptor[] | undefined = undefined;
+        if (credentialId) {
+            const rawBytes = hexToUint8Array(credentialId);
+            allowCredentials = [{
+                id: rawBytes.buffer as ArrayBuffer,
+                type: 'public-key' as const,
+                ...(transports && transports.length > 0 ? { transports } : {})
+            }];
+        }
+
+        const assertion = await navigator.credentials.get({
+            publicKey: {
+                challenge,
+                ...(effectiveRpId ? { rpId: effectiveRpId } : {}),
+                allowCredentials,
+                userVerification: 'required',
+                extensions: {
+                    prf: {
+                        eval: {
+                            first: saltBuffer
+                        }
+                    }
+                } as any
+            }
+        }) as PublicKeyCredential;
+
+        if (!assertion) {
+            throw new Error('Passkey authentication was cancelled or failed.');
+        }
+
+        const resolvedCredentialId = bufferToHex(assertion.rawId);
+        const extResults: any = assertion.getClientExtensionResults?.() || {};
+        console.log(`${lc} WebAuthn assertion clientExtensionResults:`, extResults);
+        const prfResult = extResults.prf?.results?.first;
+
+        if (!prfResult) {
+            console.error(`${lc} Extension results did not contain PRF evaluation:`, extResults);
+            throw new Error('Authenticator did not return a PRF evaluation. PRF extension may not be supported on this authenticator.');
+        }
+
+        const passkeySecret = bufferToHex(prfResult);
+
+        return {
+            passkeySecret,
+            credentialId: resolvedCredentialId
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
+/**
+ * Creates a Passkey sovereign sync delegate for this device.
+ * Standardized format: `passkey-${safeUsername}-${defaultDeviceTag}`
+ */
+export async function createPasskeyDeviceSyncDelegate({
+    username,
+    primaryTjpAddr,
+    passkeySecret,
+    transports,
+    metaspace,
+    space,
+}: {
+    username: string;
+    primaryTjpAddr: string;
+    passkeySecret: string;
+    transports?: AuthenticatorTransport[];
+    metaspace?: any;
+    space?: any;
+}): Promise<{ delegateKeystone: any; deviceTag: string; delegateSecret: string }> {
+    const delegateSecret = await deriveDelegateSecret({ masterSecret: passkeySecret });
+    await setDeviceDelegateSecret({ primaryTjpAddr, delegateSecret });
+
+    const safeUser = getSaferSubstring({ text: username, length: 8, keepLiterals: ['-'] }) || 'user';
+    const defaultDeviceTag = generateDefaultDeviceTag();
+    const deviceTag = `passkey-${safeUser}-${defaultDeviceTag}`;
+    const sovereignSyncProfileName = process.env.KEYSTONE_PROFILE_SOVEREIGN_SYNC;
+    if (!sovereignSyncProfileName || !sovereignSyncProfileName.trim()) {
+        throw new Error('KEYSTONE_PROFILE_SOVEREIGN_SYNC environment variable is missing.');
+    }
+
+    const delegateKeystone = await createSyncDelegateKeystone({
+        profileName: sovereignSyncProfileName.trim() as any,
+        username,
+        deviceTag,
+        primaryTjpAddr,
+        delegateSecret,
+        additionalFrameDetails: {
+            client: 'space-gib-web',
+            role: 'passkey-sync',
+            ...(transports && transports.length > 0 ? { transports } : {})
+        },
+        metaspace,
+        space,
+    });
+
+    return { delegateKeystone, deviceTag, delegateSecret };
+}