@animalabs/connectome-host 0.3.1 → 0.3.7

package/web/src/observer-identity.ts

@@ -0,0 +1,110 @@
+/**
+ * Device observer identity (docs/observability.md §3, browser side).
+ *
+ * On first use the SPA generates a NON-EXTRACTABLE Ed25519 keypair via
+ * WebCrypto and persists the CryptoKey objects in IndexedDB — the private
+ * key never exists as bytes the page (or an XSS) could read. The public
+ * fingerprint (`ed25519:<base64url raw>`) is what a human shows to the
+ * agent/operator to be granted (`observers--grant`).
+ *
+ * Requires a secure context (https or localhost) — WebCrypto is absent on
+ * plain-http non-localhost origins. Callers get `null` and should offer
+ * password sign-in instead.
+ */
+
+const DB_NAME = 'fkm-observer';
+const STORE = 'keys';
+const KEY_ID = 'device-key';
+
+interface DeviceKey {
+  keyPair: CryptoKeyPair;
+  /** `ed25519:<base64url raw 32-byte public key>` */
+  id: string;
+}
+
+function b64url(buf: ArrayBuffer): string {
+  let s = '';
+  for (const b of new Uint8Array(buf)) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function idb(): Promise<IDBDatabase> {
+  return new Promise((resolvePromise, reject) => {
+    const req = indexedDB.open(DB_NAME, 1);
+    req.onupgradeneeded = () => req.result.createObjectStore(STORE);
+    req.onsuccess = () => resolvePromise(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+function idbGet<T>(db: IDBDatabase, key: string): Promise<T | undefined> {
+  return new Promise((resolvePromise, reject) => {
+    const tx = db.transaction(STORE, 'readonly').objectStore(STORE).get(key);
+    tx.onsuccess = () => resolvePromise(tx.result as T | undefined);
+    tx.onerror = () => reject(tx.error);
+  });
+}
+
+function idbPut(db: IDBDatabase, key: string, value: unknown): Promise<void> {
+  return new Promise((resolvePromise, reject) => {
+    const tx = db.transaction(STORE, 'readwrite').objectStore(STORE).put(value, key);
+    tx.onsuccess = () => resolvePromise();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+
+async function fingerprintOf(publicKey: CryptoKey): Promise<string> {
+  const raw = await crypto.subtle.exportKey('raw', publicKey);
+  return `ed25519:${b64url(raw)}`;
+}
+
+/** Ed25519 support probe — false on insecure contexts and old browsers. */
+export function observerCryptoAvailable(): boolean {
+  return typeof crypto !== 'undefined' && !!crypto.subtle && typeof indexedDB !== 'undefined';
+}
+
+/** Load (or create on first use) this device's observer key. Null when the
+ *  environment can't do WebCrypto Ed25519. */
+export async function ensureDeviceKey(): Promise<DeviceKey | null> {
+  if (!observerCryptoAvailable()) return null;
+  try {
+    const db = await idb();
+    const existing = await idbGet<CryptoKeyPair>(db, KEY_ID);
+    if (existing?.privateKey && existing.publicKey) {
+      return { keyPair: existing, id: await fingerprintOf(existing.publicKey) };
+    }
+    const keyPair = (await crypto.subtle.generateKey(
+      { name: 'Ed25519' } as AlgorithmIdentifier,
+      false, // non-extractable — the private key never leaves the browser
+      ['sign', 'verify'],
+    )) as CryptoKeyPair;
+    await idbPut(db, KEY_ID, keyPair);
+    return { keyPair, id: await fingerprintOf(keyPair.publicKey) };
+  } catch (err) {
+    console.warn('[observer] device key unavailable:', err);
+    return null;
+  }
+}
+
+/** Build the signed observer-hello identity envelope for `host` (the value
+ *  the server sent in observer-auth-required — its own Host header). */
+export async function buildHelloIdentity(host: string): Promise<{
+  scheme: 'ed25519'; id: string; proof: string; timestamp: string;
+} | null> {
+  const key = await ensureDeviceKey();
+  if (!key) return null;
+  const timestamp = new Date().toISOString();
+  const statement = `connectome-observer|v1|${host}|${timestamp}`;
+  const sig = await crypto.subtle.sign(
+    { name: 'Ed25519' } as AlgorithmIdentifier,
+    key.keyPair.privateKey,
+    new TextEncoder().encode(statement),
+  );
+  return { scheme: 'ed25519', id: key.id, proof: b64url(sig), timestamp };
+}
+
+/** Current device fingerprint for display (creates the key if absent). */
+export async function deviceFingerprint(): Promise<string | null> {
+  const key = await ensureDeviceKey();
+  return key?.id ?? null;
+}

package/web/src/wire.ts

@@ -11,11 +11,31 @@ import type {
   WebUiClientMessage,
   WebUiServerMessage,
 } from '@conhost/web/protocol';
+import { buildHelloIdentity } from './observer-identity.js';
 
 export type ConnectionStatus = 'connecting' | 'open' | 'reconnecting' | 'closed';
 
+/**
+ * Observer-auth state (docs/observability.md, browser side).
+ *   'none'        — basic-auth / open server; historical behavior
+ *   'authing'     — server demanded observer auth; hello sent
+ *   'observer'    — key-authenticated; `observer()` carries label + scopes
+ *   'denied'      — this device's key holds no grant on this agent
+ *   'unavailable' — WebCrypto absent (insecure context) — password only
+ */
+export type ObserverAuthState = 'none' | 'authing' | 'observer' | 'denied' | 'unavailable';
+
+export interface ObserverInfo {
+  label: string;
+  scopes: string[];
+}
+
 export interface WireClient {
   status: Accessor<ConnectionStatus>;
+  /** Observer-auth state for this connection. */
+  observerState: Accessor<ObserverAuthState>;
+  /** Grant info after a successful observer handshake. */
+  observer: Accessor<ObserverInfo | null>;
   /** Last received message, or null. Useful for reactive folds. */
   lastMessage: Accessor<WebUiServerMessage | null>;
   /** Subscribe to all incoming messages. Returns an unsubscribe fn. */
@@ -42,6 +62,8 @@ export function createWireClient(opts: WireOptions = {}): WireClient {
 
   const [status, setStatus] = createSignal<ConnectionStatus>('connecting');
   const [lastMessage, setLastMessage] = createSignal<WebUiServerMessage | null>(null);
+  const [observerState, setObserverState] = createSignal<ObserverAuthState>('none');
+  const [observer, setObserver] = createSignal<ObserverInfo | null>(null);
   const handlers = new Set<(m: WebUiServerMessage) => void>();
 
   let socket: WebSocket | null = null;
@@ -49,6 +71,21 @@ export function createWireClient(opts: WireOptions = {}): WireClient {
   let delay = initialDelay;
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
 
+  /** Server demanded observer auth → sign and reply with this device's key.
+   *  Failure paths surface via observerState so the UI can show the
+   *  fingerprint-grant screen or fall back to password sign-in. */
+  async function respondToAuthRequired(sock: WebSocket, host: string): Promise<void> {
+    setObserverState('authing');
+    const identity = await buildHelloIdentity(host);
+    if (!identity) {
+      setObserverState('unavailable');
+      return;
+    }
+    if (sock.readyState === WebSocket.OPEN) {
+      sock.send(JSON.stringify({ type: 'observer-hello', identity }));
+    }
+  }
+
   function connect(): void {
     if (stopped) return;
     setStatus(socket ? 'reconnecting' : 'connecting');
@@ -67,18 +104,38 @@ export function createWireClient(opts: WireOptions = {}): WireClient {
         console.warn('[wire] failed to parse message', event.data);
         return;
       }
+      // Observer handshake frames are handled here (the wire owns the
+      // socket); they also fan out to handlers for any UI that cares.
+      if (parsed.type === 'observer-auth-required' && socket) {
+        void respondToAuthRequired(socket, parsed.host);
+      } else if (parsed.type === 'observer-ack') {
+        setObserverState('observer');
+        setObserver({ label: parsed.label, scopes: parsed.scopes });
+        // Session cookie lets the SPA hit /debug/* and /healthz over HTTP.
+        document.cookie = `fkm_obs=${parsed.sessionToken}; path=/; SameSite=Lax; max-age=${12 * 3600}`;
+      }
       setLastMessage(parsed);
       for (const h of handlers) {
         try { h(parsed); } catch (err) { console.error('[wire] handler threw', err); }
       }
     });
 
-    socket.addEventListener('close', () => {
+    socket.addEventListener('close', (ev) => {
       socket = null;
       if (stopped) {
         setStatus('closed');
         return;
       }
+      if (ev.code === 4401) {
+        // Observer auth rejected — reconnect loops would spam the server;
+        // hold until the user acts (grant lands / password). The server also
+        // closes never-authenticated connections with 4401 on timeout, so
+        // don't overwrite 'unavailable' (no WebCrypto — a hello was never
+        // possible) with 'denied' (a key exists but holds no grant).
+        if (observerState() !== 'unavailable') setObserverState('denied');
+        setStatus('closed');
+        return;
+      }
       setStatus('reconnecting');
       reconnectTimer = setTimeout(connect, delay);
       delay = Math.min(delay * 2, maxDelay);
@@ -93,6 +150,8 @@ export function createWireClient(opts: WireOptions = {}): WireClient {
 
   return {
     status,
+    observerState,
+    observer,
     lastMessage,
     onMessage(handler) {
       handlers.add(handler);