@ibgib/web-gib 0.0.61 → 0.0.63

package/src/identity/passkey-helper.mts

@@ -0,0 +1,337 @@
+/**
+ * @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,
+    userVerification = 'preferred',
+    authenticatorAttachment,
+    hints = ['security-key', 'client-device', 'hybrid'],
+}: {
+    username: string;
+    displayName?: string;
+    rpName?: string;
+    rpId?: string;
+    salt?: string | Uint8Array;
+    userVerification?: UserVerificationRequirement;
+    authenticatorAttachment?: AuthenticatorAttachment;
+    hints?: ('security-key' | 'client-device' | 'hybrid')[];
+}): 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,
+                    ...(authenticatorAttachment ? { authenticatorAttachment } : {})
+                },
+                ...(hints && hints.length > 0 ? { hints } : {}),
+                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,
+    userVerification = 'preferred',
+    hints = ['security-key', 'client-device', 'hybrid'],
+}: {
+    salt: string | Uint8Array;
+    credentialId?: string;
+    transports?: AuthenticatorTransport[];
+    rpId?: string;
+    userVerification?: UserVerificationRequirement;
+    hints?: ('security-key' | 'client-device' | 'hybrid')[];
+}): 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 credentialIdBase64Url: string | undefined = undefined;
+        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 } : {})
+            }];
+            let binary = '';
+            for (let i = 0; i < rawBytes.byteLength; i++) {
+                binary += String.fromCharCode(rawBytes[i]);
+            }
+            credentialIdBase64Url = btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+        }
+
+        const prfExtension: any = {
+            eval: {
+                first: saltBuffer
+            }
+        };
+        if (credentialIdBase64Url) {
+            prfExtension.evalByCredential = {
+                [credentialIdBase64Url]: {
+                    first: saltBuffer
+                }
+            };
+        }
+
+        const assertion = await navigator.credentials.get({
+            publicKey: {
+                challenge,
+                ...(effectiveRpId ? { rpId: effectiveRpId } : {}),
+                allowCredentials,
+                userVerification,
+                ...(hints && hints.length > 0 ? { hints } : {}),
+                extensions: {
+                    prf: prfExtension
+                } 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:`, JSON.stringify(extResults), extResults);
+        
+        let prfResult: ArrayBuffer | undefined = extResults.prf?.results?.first;
+        if (!prfResult && credentialIdBase64Url && extResults.prf?.resultsByCredential?.[credentialIdBase64Url]?.first) {
+            prfResult = extResults.prf.resultsByCredential[credentialIdBase64Url].first;
+            console.log(`${lc} Extracted PRF result from resultsByCredential!`);
+        }
+
+        if (!prfResult) {
+            console.error(`${lc} Extension results did not contain PRF evaluation:`, JSON.stringify(extResults), 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 };
+}

package/src/identity/passkey.respec.mts

@@ -0,0 +1,194 @@
+import { respecfully, ifWe, ifWeMight, iReckon } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+import { getIbGibGlobalThis_IbGib } from '../helpers.mjs';
+import {
+    bufferToHex,
+    hexToUint8Array,
+    normalizeSaltTo32Bytes,
+    isPasskeyPrfSupported,
+    registerPasskeyCredential,
+    evaluatePasskeyPrf,
+    createPasskeyDeviceSyncDelegate
+} from './passkey-helper.mjs';
+import { getDeviceDelegateSecret } 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;
+        }
+    };
+}
+
+// Setup environment profile
+process.env.KEYSTONE_PROFILE_SOVEREIGN_SYNC = 'sync-profile.dev';
+
+class MockIbGibSpace {
+    store = new Map<string, any>();
+    ib: string = 'witness space mock-space mock_space_id user';
+
+    constructor(public name: string = "mock_space") { }
+
+    async put({ ibGib }: { ibGib: any }): Promise<void> {
+        const addr = `${ibGib.ib}^${ibGib.gib}`;
+        this.store.set(addr, JSON.parse(JSON.stringify(ibGib)));
+    }
+
+    async get({ addr }: { addr: string }): Promise<any | null> {
+        const data = this.store.get(addr);
+        return data ? JSON.parse(JSON.stringify(data)) : null;
+    }
+
+    async argy({ argData, ibGibs }: { argData: any; ibGibs?: any[] }): Promise<any> {
+        return {
+            ib: 'arg^gib',
+            gib: 'arg_gib',
+            data: argData,
+            ibGibs,
+        };
+    }
+
+    async witness(arg: any): Promise<any> {
+        return { data: { success: true } };
+    }
+}
+
+class MockMetaspaceService {
+    constructor(public space: MockIbGibSpace) { }
+
+    async getLocalUserSpace({ lock }: { lock?: boolean } = {}): Promise<MockIbGibSpace> {
+        return this.space;
+    }
+
+    async put(args: any): Promise<void> {
+        const target = args.space || this.space;
+        return target.put(args);
+    }
+
+    async registerNewIbGib({ ibGib }: { ibGib: any }): Promise<void> {
+        return this.put({ ibGib });
+    }
+
+    async get(args: { addr?: string; addrs?: string[]; space?: any }): Promise<{ success: boolean; ibGibs?: any[] }> {
+        const target = args.space || this.space;
+        if (args.addr) {
+            const x = await target.get({ addr: args.addr });
+            return { success: !!x, ibGibs: x ? [x] : [] };
+        }
+        return { success: true, ibGibs: [] };
+    }
+}
+
+const mockSpace = new MockIbGibSpace();
+const mockMetaspace = new MockMetaspaceService(mockSpace);
+
+await respecfully(sir, 'Passkey WebAuthn PRF Helper Service', async () => {
+
+    await ifWe(sir, 'bufferToHex and hexToUint8Array roundtrip correctly', async () => {
+        const originalBytes = new Uint8Array([0xde, 0xad, 0xbe, 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef]);
+        const hex = bufferToHex(originalBytes.buffer);
+        iReckon(sir, hex).willEqual('deadbeef0123456789abcdef');
+
+        const roundtripBytes = hexToUint8Array(hex);
+        iReckon(sir, roundtripBytes.length).willEqual(originalBytes.length);
+        for (let i = 0; i < originalBytes.length; i++) {
+            iReckon(sir, roundtripBytes[i]).willEqual(originalBytes[i]);
+        }
+    });
+
+    await ifWe(sir, 'normalizeSaltTo32Bytes normalizes various salt inputs to 32 bytes', async () => {
+        // 1. Hex string of 64 chars (32 bytes)
+        const hex64 = '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
+        const normHex = normalizeSaltTo32Bytes(hex64);
+        iReckon(sir, normHex.length).willEqual(32);
+        iReckon(sir, bufferToHex(normHex.buffer)).willEqual(hex64);
+
+        // 2. Text string
+        const textSalt = 'ibgib_passkey_salt_domain_123';
+        const normText = normalizeSaltTo32Bytes(textSalt);
+        iReckon(sir, normText.length).willEqual(32);
+
+        // 3. Uint8Array
+        const rawBytes = new Uint8Array(32);
+        rawBytes.fill(0x42);
+        const normRaw = normalizeSaltTo32Bytes(rawBytes);
+        iReckon(sir, normRaw.length).willEqual(32);
+        iReckon(sir, normRaw[0]).willEqual(0x42);
+    });
+
+    await ifWe(sir, 'isPasskeyPrfSupported evaluates capabilities cleanly', async () => {
+        // In Node environment without window
+        const supported = await isPasskeyPrfSupported();
+        iReckon(sir, typeof supported).willEqual('boolean');
+    });
+
+    await ifWe(sir, 'createPasskeyDeviceSyncDelegate creates standard passkey sync delegate', async () => {
+        const username = 'alice';
+        const primaryTjpAddr = 'keystone^alice_primary_tjp.addr';
+        const passkeySecret = 'deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef';
+
+        const { delegateKeystone, deviceTag, delegateSecret } = await createPasskeyDeviceSyncDelegate({
+            username,
+            primaryTjpAddr,
+            passkeySecret,
+            transports: ['internal'],
+            metaspace: mockMetaspace as any,
+            space: mockSpace as any,
+        });
+
+        iReckon(sir, delegateKeystone).asTo('delegateKeystone is generated').isGonnaBeTruthy();
+        iReckon(sir, deviceTag.startsWith('passkey-alice-')).asTo('deviceTag follows passkey naming format').isGonnaBeTrue();
+        iReckon(sir, delegateSecret).asTo('delegateSecret is derived').isGonnaBeTruthy();
+
+        // Verify stored in IndexedDB
+        const storedSecret = await getDeviceDelegateSecret({ primaryTjpAddr });
+        iReckon(sir, storedSecret).willEqual(delegateSecret);
+    });
+});

package/src/index.mts

@@ -20,6 +20,7 @@ export * from "./api/ibgib-api-bridge.mjs";
 export * from "./identity/keystone-sync-service.mjs";
 export * from "./identity/device-delegate-helper.mjs";
 export * from "./identity/sso-popup-helper.mjs";
+export * from "./identity/passkey-helper.mjs";
 
 // Identity UI components
 export * from "./ui/component/identity/index.mjs";

package/src/ui/component/identity/add-device/add-device.mts

@@ -615,6 +615,7 @@ export class AddDeviceComponentInstance
                 parentKeystone: primaryKeystone,
                 delegateKeystone,
                 masterSecret,
+                signingPoolId: 'manage',
                 allowedVerbs: [KEYSTONE_VERB_SYNC, KEYSTONE_VERB_CONNECT],
                 metaspace,
                 space,

package/src/ui/component/identity/keystone-creator/keystone-creator.css

@@ -199,4 +199,30 @@ h2 {
 input::placeholder {
     color: rgba(255, 255, 255, 0.35);
     opacity: 1;
+}
+
+.public-directory-notice {
+    padding: 0.75rem 1rem;
+    border-radius: 8px;
+    background: rgba(137, 180, 250, 0.08);
+    border: 1px solid rgba(137, 180, 250, 0.25);
+    display: flex;
+    gap: 0.6rem;
+    align-items: flex-start;
+    text-align: left;
+}
+
+.notice-icon {
+    font-size: 1.1rem;
+    line-height: 1.2;
+}
+
+.notice-body {
+    font-size: 0.82rem;
+    color: var(--clr-text, #cdd6f4);
+    line-height: 1.45;
+}
+
+.notice-body strong {
+    color: #89b4fa;
 }