@backbay/glia 0.2.0-alpha.1

package/dist/speakeasy/doorman/DoormanStateMachine.js

@@ -0,0 +1,393 @@
+/**
+ * DoormanStateMachine - State machine for speakeasy doorman interaction
+ *
+ * States: IDLE → CHALLENGED → VERIFYING → ADMITTED → COOLDOWN/LOCKED
+ *
+ * Mirrors the HSM pattern from kernel/src/cyntra/core/topology/hsm_engine.py
+ * but implemented as a Zustand store for React integration.
+ */
+import { create } from 'zustand';
+import { subscribeWithSelector } from 'zustand/middleware';
+import { DEFAULT_DOORMAN_CONFIG, } from '../types.js';
+const createTransitions = (config) => [
+    // IDLE → CHALLENGED: Public knock detected
+    {
+        from: 'IDLE',
+        to: 'CHALLENGED',
+        event: 'KNOCK_DETECTED',
+        action: (ctx, event) => {
+            const timestamp = event.timestamp || Date.now();
+            return {
+                challenge: {
+                    nonce: generateNonce(),
+                    salt: generateSalt(),
+                    issuedAt: timestamp,
+                    expiresAt: timestamp + config.challengeWindowMs,
+                },
+            };
+        },
+    },
+    // CHALLENGED → VERIFYING: Gesture complete
+    {
+        from: 'CHALLENGED',
+        to: 'VERIFYING',
+        event: 'GESTURE_COMPLETE',
+        guard: (ctx) => {
+            // Check challenge not expired
+            if (!ctx.challenge)
+                return false;
+            return Date.now() < ctx.challenge.expiresAt;
+        },
+    },
+    // CHALLENGED → IDLE: Challenge timeout
+    {
+        from: 'CHALLENGED',
+        to: 'IDLE',
+        event: 'CHALLENGE_TIMEOUT',
+        action: () => ({ challenge: null }),
+    },
+    // CHALLENGED → IDLE: User cancels
+    {
+        from: 'CHALLENGED',
+        to: 'IDLE',
+        event: 'EXIT_REQUESTED',
+        action: () => ({ challenge: null }),
+    },
+    // VERIFYING → IDLE: User cancels
+    {
+        from: 'VERIFYING',
+        to: 'IDLE',
+        event: 'EXIT_REQUESTED',
+        action: () => ({ challenge: null }),
+    },
+    // VERIFYING → ADMITTED: Verification success
+    {
+        from: 'VERIFYING',
+        to: 'ADMITTED',
+        event: 'VERIFICATION_SUCCESS',
+        action: (ctx, event) => {
+            const e = event;
+            return {
+                capability: e.capability,
+                challenge: null,
+                consecutiveFailures: 0,
+                admissionEndsAt: Date.now() + config.admissionTtlMs,
+            };
+        },
+    },
+    // VERIFYING → COOLDOWN: Verification failure (under threshold)
+    {
+        from: 'VERIFYING',
+        to: 'COOLDOWN',
+        event: 'VERIFICATION_FAILURE',
+        guard: (ctx) => ctx.consecutiveFailures + 1 < config.maxConsecutiveFailures,
+        action: (ctx) => {
+            const failures = ctx.consecutiveFailures + 1;
+            const cooldownMs = config.cooldownBaseMs * Math.pow(2, failures - 1);
+            return {
+                consecutiveFailures: failures,
+                cooldownEndsAt: Date.now() + cooldownMs,
+                challenge: null,
+            };
+        },
+    },
+    // VERIFYING → LOCKED: Verification failure (at threshold)
+    {
+        from: 'VERIFYING',
+        to: 'LOCKED',
+        event: 'VERIFICATION_FAILURE',
+        guard: (ctx) => ctx.consecutiveFailures + 1 >= config.maxConsecutiveFailures,
+        action: () => ({
+            consecutiveFailures: config.maxConsecutiveFailures,
+            lockEndsAt: Date.now() + config.lockDurationMs,
+            challenge: null,
+        }),
+    },
+    // COOLDOWN → IDLE: Cooldown elapsed
+    {
+        from: 'COOLDOWN',
+        to: 'IDLE',
+        event: 'COOLDOWN_ELAPSED',
+        action: () => ({ cooldownEndsAt: null }),
+    },
+    // LOCKED → IDLE: Lock expired
+    {
+        from: 'LOCKED',
+        to: 'IDLE',
+        event: 'LOCK_EXPIRED',
+        action: () => ({
+            lockEndsAt: null,
+            consecutiveFailures: 0,
+        }),
+    },
+    // ADMITTED → IDLE: Exit requested
+    {
+        from: 'ADMITTED',
+        to: 'IDLE',
+        event: 'EXIT_REQUESTED',
+        action: () => ({
+            capability: null,
+            admissionEndsAt: null,
+        }),
+    },
+    // ADMITTED → IDLE: Admission timeout
+    {
+        from: 'ADMITTED',
+        to: 'IDLE',
+        event: 'ADMISSION_TIMEOUT',
+        action: () => ({
+            capability: null,
+            admissionEndsAt: null,
+        }),
+    },
+    // DECOY → IDLE: Exit requested
+    {
+        from: 'DECOY',
+        to: 'IDLE',
+        event: 'EXIT_REQUESTED',
+        action: () => ({
+            capability: null,
+            admissionEndsAt: null,
+        }),
+    },
+    // DECOY → IDLE: Timeout
+    {
+        from: 'DECOY',
+        to: 'IDLE',
+        event: 'ADMISSION_TIMEOUT',
+        action: () => ({
+            capability: null,
+            admissionEndsAt: null,
+        }),
+    },
+    // Panic gesture handling (if enabled)
+    // Note: PANIC_GESTURE can be dispatched from both CHALLENGED and VERIFYING states
+    ...(config.panicGestureEnabled
+        ? [
+            // From CHALLENGED state
+            {
+                from: 'CHALLENGED',
+                to: 'DECOY',
+                event: 'PANIC_GESTURE',
+                guard: (_ctx, event) => {
+                    const e = event;
+                    return e.decoyMode === true;
+                },
+                action: () => ({
+                    admissionEndsAt: Date.now() + config.decoyTtlMs,
+                    challenge: null,
+                    capability: null,
+                }),
+            },
+            {
+                from: 'CHALLENGED',
+                to: 'LOCKED',
+                event: 'PANIC_GESTURE',
+                guard: (_ctx, event) => {
+                    const e = event;
+                    return e.decoyMode === false;
+                },
+                action: () => ({
+                    lockEndsAt: Date.now() + config.lockDurationMs * config.panicLockMultiplier,
+                    challenge: null,
+                    capability: null,
+                }),
+            },
+            // From VERIFYING state (panic detected after claiming verification lock)
+            {
+                from: 'VERIFYING',
+                to: 'DECOY',
+                event: 'PANIC_GESTURE',
+                guard: (_ctx, event) => {
+                    const e = event;
+                    return e.decoyMode === true;
+                },
+                action: () => ({
+                    admissionEndsAt: Date.now() + config.decoyTtlMs,
+                    challenge: null,
+                    capability: null,
+                }),
+            },
+            {
+                from: 'VERIFYING',
+                to: 'LOCKED',
+                event: 'PANIC_GESTURE',
+                guard: (_ctx, event) => {
+                    const e = event;
+                    return e.decoyMode === false;
+                },
+                action: () => ({
+                    lockEndsAt: Date.now() + config.lockDurationMs * config.panicLockMultiplier,
+                    challenge: null,
+                    capability: null,
+                }),
+            },
+        ]
+        : []),
+];
+// ============================================================================
+// Utility Functions
+// ============================================================================
+function randomHex(byteLength) {
+    if (typeof globalThis.crypto === 'undefined' ||
+        typeof globalThis.crypto.getRandomValues !== 'function') {
+        throw new Error('[Doorman] crypto.getRandomValues is required');
+    }
+    const bytes = new Uint8Array(byteLength);
+    globalThis.crypto.getRandomValues(bytes);
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+function generateNonce() {
+    return randomHex(32);
+}
+function generateSalt() {
+    return randomHex(16);
+}
+const INITIAL_CONTEXT = {
+    state: 'IDLE',
+    challenge: null,
+    consecutiveFailures: 0,
+    cooldownEndsAt: null,
+    lockEndsAt: null,
+    admissionEndsAt: null,
+    capability: null,
+};
+export const useDoormanStore = create()(subscribeWithSelector((set, get) => ({
+    ...INITIAL_CONTEXT,
+    config: DEFAULT_DOORMAN_CONFIG,
+    transitions: createTransitions(DEFAULT_DOORMAN_CONFIG),
+    dispatch: (event) => {
+        const { state, transitions, ...context } = get();
+        const currentContext = { state, ...context };
+        // Find matching transition
+        const transition = transitions.find((t) => {
+            if (t.from !== state)
+                return false;
+            if (t.event !== event.type)
+                return false;
+            if (t.guard && !t.guard(currentContext, event))
+                return false;
+            return true;
+        });
+        if (!transition) {
+            console.warn(`[Doorman] No valid transition from ${state} on event ${event.type}`);
+            return;
+        }
+        // Execute action and update state
+        const updates = transition.action?.(currentContext, event) || {};
+        set({
+            state: transition.to,
+            ...updates,
+        });
+    },
+    reset: () => {
+        set(INITIAL_CONTEXT);
+    },
+    setConfig: (partialConfig) => {
+        const newConfig = { ...get().config, ...partialConfig };
+        set({
+            config: newConfig,
+            transitions: createTransitions(newConfig),
+        });
+    },
+    isAdmitted: () => get().state === 'ADMITTED',
+    timeRemaining: () => {
+        const { state, challenge, cooldownEndsAt, lockEndsAt, admissionEndsAt } = get();
+        const now = Date.now();
+        switch (state) {
+            case 'CHALLENGED':
+                return challenge ? Math.max(0, challenge.expiresAt - now) : null;
+            case 'COOLDOWN':
+                return cooldownEndsAt ? Math.max(0, cooldownEndsAt - now) : null;
+            case 'LOCKED':
+                return lockEndsAt ? Math.max(0, lockEndsAt - now) : null;
+            case 'ADMITTED':
+            case 'DECOY':
+                return admissionEndsAt ? Math.max(0, admissionEndsAt - now) : null;
+            default:
+                return null;
+        }
+    },
+})));
+// ============================================================================
+// Timeout Management
+// ============================================================================
+let challengeTimeoutId = null;
+let cooldownTimeoutId = null;
+let lockTimeoutId = null;
+let admissionTimeoutId = null;
+/**
+ * Start automatic timeout handling based on state changes
+ */
+export function startDoormanTimeouts() {
+    const unsubscribe = useDoormanStore.subscribe((state) => state.state, (doormanState, prevState) => {
+        const store = useDoormanStore.getState();
+        // Clear all timeouts on state change
+        if (challengeTimeoutId)
+            clearTimeout(challengeTimeoutId);
+        if (cooldownTimeoutId)
+            clearTimeout(cooldownTimeoutId);
+        if (lockTimeoutId)
+            clearTimeout(lockTimeoutId);
+        if (admissionTimeoutId)
+            clearTimeout(admissionTimeoutId);
+        // Set new timeout based on current state
+        switch (doormanState) {
+            case 'CHALLENGED':
+                if (store.challenge) {
+                    const remaining = store.challenge.expiresAt - Date.now();
+                    if (remaining > 0) {
+                        challengeTimeoutId = setTimeout(() => {
+                            store.dispatch({ type: 'CHALLENGE_TIMEOUT' });
+                        }, remaining);
+                    }
+                }
+                break;
+            case 'COOLDOWN':
+                if (store.cooldownEndsAt) {
+                    const remaining = store.cooldownEndsAt - Date.now();
+                    if (remaining > 0) {
+                        cooldownTimeoutId = setTimeout(() => {
+                            store.dispatch({ type: 'COOLDOWN_ELAPSED' });
+                        }, remaining);
+                    }
+                }
+                break;
+            case 'LOCKED':
+                if (store.lockEndsAt) {
+                    const remaining = store.lockEndsAt - Date.now();
+                    if (remaining > 0) {
+                        lockTimeoutId = setTimeout(() => {
+                            store.dispatch({ type: 'LOCK_EXPIRED' });
+                        }, remaining);
+                    }
+                }
+                break;
+            case 'ADMITTED':
+            case 'DECOY':
+                if (store.admissionEndsAt) {
+                    const remaining = store.admissionEndsAt - Date.now();
+                    if (remaining > 0) {
+                        admissionTimeoutId = setTimeout(() => {
+                            store.dispatch({ type: 'ADMISSION_TIMEOUT' });
+                        }, remaining);
+                    }
+                }
+                break;
+        }
+    });
+    return () => {
+        unsubscribe();
+        if (challengeTimeoutId)
+            clearTimeout(challengeTimeoutId);
+        if (cooldownTimeoutId)
+            clearTimeout(cooldownTimeoutId);
+        if (lockTimeoutId)
+            clearTimeout(lockTimeoutId);
+        if (admissionTimeoutId)
+            clearTimeout(admissionTimeoutId);
+    };
+}
+export default useDoormanStore;

package/dist/speakeasy/doorman/panic.d.ts

@@ -0,0 +1,10 @@
+import type { GestureSequence } from '../types.js';
+export interface PanicGesturePattern {
+    tapCount: number;
+    tapRegion: 'center' | 'edge' | 'any';
+    holdMinDurationMs: number;
+    holdRegion: 'center' | 'edge' | 'any';
+}
+export declare const DEFAULT_PANIC_GESTURE_PATTERN: PanicGesturePattern;
+export declare function isPanicGesture(sequence: GestureSequence, pattern?: PanicGesturePattern): boolean;
+//# sourceMappingURL=panic.d.ts.map

package/dist/speakeasy/doorman/panic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panic.d.ts","sourceRoot":"","sources":["../../../src/speakeasy/doorman/panic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAe,MAAM,aAAa,CAAC;AAEhE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;IACrC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;CACvC;AAED,eAAO,MAAM,6BAA6B,EAAE,mBAK3C,CAAC;AAMF,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,eAAe,EACzB,OAAO,GAAE,mBAAmD,GAC3D,OAAO,CAyBT"}

package/dist/speakeasy/doorman/panic.js

@@ -0,0 +1,28 @@
+export const DEFAULT_PANIC_GESTURE_PATTERN = {
+    tapCount: 5,
+    tapRegion: 'center',
+    holdMinDurationMs: 2_500,
+    holdRegion: 'edge',
+};
+function isRegionMatch(region, expected) {
+    return expected === 'any' ? true : region === expected;
+}
+export function isPanicGesture(sequence, pattern = DEFAULT_PANIC_GESTURE_PATTERN) {
+    // Use filter to check ALL tap/hold pairs, not just the first match
+    const allTaps = sequence.steps.filter((s) => s.type === 'tap');
+    const allHolds = sequence.steps.filter((s) => s.type === 'hold');
+    // Check all combinations of taps and holds for panic pattern
+    for (const tap of allTaps) {
+        if (tap.count < pattern.tapCount)
+            continue;
+        if (!isRegionMatch(tap.region, pattern.tapRegion))
+            continue;
+        for (const hold of allHolds) {
+            if (hold.durationMs >= pattern.holdMinDurationMs &&
+                isRegionMatch(hold.region, pattern.holdRegion)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}

package/dist/speakeasy/hooks/useGestureRecognizer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * useGestureRecognizer - Hook for capturing speakeasy gesture sequences
+ *
+ * Recognizes:
+ * - Tap sequences (single, double, triple+)
+ * - Hold gestures (with configurable threshold)
+ * - Radial drags (angle calculation, notch detection)
+ * - Flicks (direction + velocity)
+ *
+ * Outputs a GestureSequence with timing data for verification.
+ */
+import { type GestureRecognizerConfig, type GestureRecognizerState, type GestureSequence, type GestureStep } from '../types.js';
+interface UseGestureRecognizerOptions {
+    /** Configuration overrides */
+    config?: Partial<GestureRecognizerConfig>;
+    /** Center point of the orb (for radial calculations) */
+    centerRef: React.RefObject<HTMLElement | null>;
+    /** Called when a complete gesture sequence is detected */
+    onGestureComplete?: (sequence: GestureSequence) => void;
+    /** Called when gesture recognition starts */
+    onGestureStart?: () => void;
+    /** Called on each gesture step */
+    onGestureStep?: (step: GestureStep) => void;
+}
+interface UseGestureRecognizerReturn {
+    /** Current recognizer state */
+    state: GestureRecognizerState;
+    /** Accumulated steps */
+    steps: GestureStep[];
+    /** Whether actively capturing */
+    isCapturing: boolean;
+    /** Bind these to your target element */
+    handlers: {
+        onPointerDown: (e: React.PointerEvent) => void;
+        onPointerMove: (e: React.PointerEvent) => void;
+        onPointerUp: (e: React.PointerEvent) => void;
+        onPointerCancel: (e: React.PointerEvent) => void;
+    };
+    /** Start capturing a new gesture sequence */
+    startCapture: () => void;
+    /** End capture and get the sequence */
+    endCapture: () => Promise<GestureSequence | null>;
+    /** Reset without emitting */
+    reset: () => void;
+}
+export declare function useGestureRecognizer(options: UseGestureRecognizerOptions): UseGestureRecognizerReturn;
+export default useGestureRecognizer;
+//# sourceMappingURL=useGestureRecognizer.d.ts.map

package/dist/speakeasy/hooks/useGestureRecognizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useGestureRecognizer.d.ts","sourceRoot":"","sources":["../../../src/speakeasy/hooks/useGestureRecognizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,WAAW,EAEjB,MAAM,aAAa,CAAC;AAErB,UAAU,2BAA2B;IACnC,8BAA8B;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC1C,wDAAwD;IACxD,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC/C,0DAA0D;IAC1D,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,IAAI,CAAC;IACxD,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B,kCAAkC;IAClC,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;CAC7C;AAED,UAAU,0BAA0B;IAClC,+BAA+B;IAC/B,KAAK,EAAE,sBAAsB,CAAC;IAC9B,wBAAwB;IACxB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,iCAAiC;IACjC,WAAW,EAAE,OAAO,CAAC;IACrB,wCAAwC;IACxC,QAAQ,EAAE;QACR,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;QAC/C,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;QAC/C,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;QAC7C,eAAe,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;KAClD,CAAC;IACF,6CAA6C;IAC7C,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,uCAAuC;IACvC,UAAU,EAAE,MAAM,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IAClD,6BAA6B;IAC7B,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAwCD,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,2BAA2B,GACnC,0BAA0B,CAgU5B;AAED,eAAe,oBAAoB,CAAC"}