shraga 0.1.112 → 0.1.114

package/src/client/components/owner/OwnerConsole.tsx

@@ -0,0 +1,87 @@
+import { useCallback, useEffect, useState, type ReactNode } from 'react';
+import { RefreshCw, ShieldCheck } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from '@/components/ui/dialog';
+import { cn } from '@/lib/utils';
+import { ApiKeysTab } from './ApiKeysTab';
+import { AuditTab } from './AuditTab';
+import { BindingsTab } from './BindingsTab';
+import { BlocklistTab } from './BlocklistTab';
+import { PrincipalsTab } from './PrincipalsTab';
+import { RolesTab } from './RolesTab';
+import { ErrorBox, type OwnerCall, type Policy, type PolicyDoc } from './shared';
+
+const TABS = [['roles', 'Roles & Profiles'], ['bindings', 'Bindings'], ['principals', 'Principals'], ['keys', 'API keys'], ['blocks', 'Blocklist'], ['audit', 'Audit']] as const;
+type Tab = (typeof TABS)[number][0];
+const TAB_KEY = 'owner-console-tab';
+
+function storedTab(): Tab {
+  try {
+    const t = localStorage.getItem(TAB_KEY);
+    return TABS.some(([id]) => id === t) ? (t as Tab) : 'roles';
+  } catch { return 'roles'; }
+}
+
+/** Owner-only security console. Every write goes through `/api/owner/*` (validated + audited server-side). */
+export function OwnerConsole({ call, onOpenSession, trigger }: { call: OwnerCall; onOpenSession: (sessionId: string) => void | Promise<void>; trigger: ReactNode }) {
+  const [open, setOpen] = useState(false);
+  const [tab, setTab] = useState<Tab>(storedTab);
+  const [doc, setDoc] = useState<PolicyDoc | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+
+  const loadPolicy = useCallback(async () => {
+    try { setDoc(await call<PolicyDoc>('/policy')); setLoadError(null); } catch (e: any) { setLoadError(e?.message ?? String(e)); }
+  }, [call]);
+  useEffect(() => { if (open) loadPolicy(); }, [open, loadPolicy]);
+
+  const savePolicy = async (policy: Policy, version: string) => {
+    await call('/policy', 'PUT', { policy, version });
+    await loadPolicy();
+  };
+  /** Unsaved Roles/Bindings edits live in the mounted tab — leaving it discards them, so ask first. */
+  const [dirty, setDirty] = useState(false);
+  const leaveOk = () => !dirty || confirm('You have unsaved policy edits. Discard them?');
+  const selectTab = (t: Tab) => {
+    if (t === tab || !leaveOk()) return;
+    setTab(t);
+    try { localStorage.setItem(TAB_KEY, t); } catch (e) { console.warn('[owner] could not persist tab', e); }
+  };
+  const roles = doc ? Object.keys(doc.policy.roles).filter((r) => r !== 'owner') : [];
+
+  return (
+    <Dialog open={open} onOpenChange={(o) => { if (o || leaveOk()) setOpen(o); }}>
+      <DialogTrigger asChild>{trigger}</DialogTrigger>
+      <DialogContent className="max-w-[95vw] sm:max-w-5xl h-[85dvh] flex flex-col gap-0 p-0">
+        <DialogHeader className="px-4 pt-4 pb-2 border-b shrink-0">
+          <DialogTitle className="flex items-center gap-2">
+            <ShieldCheck className="w-4 h-4" /> Owner Console
+            <Button variant="ghost" size="icon" className="h-6 w-6 ml-1" title="Reload policy" onClick={loadPolicy}><RefreshCw className="w-3.5 h-3.5" /></Button>
+          </DialogTitle>
+          <div className="flex gap-1 overflow-x-auto pt-2" role="tablist">
+            {TABS.map(([id, label]) => (
+              <button key={id} role="tab" aria-selected={tab === id} onClick={() => selectTab(id)}
+                className={cn('text-xs px-2.5 py-1 rounded-md whitespace-nowrap transition-colors', tab === id ? 'bg-accent text-foreground font-medium' : 'text-muted-foreground hover:text-foreground')}>
+                {label}
+              </button>
+            ))}
+          </div>
+        </DialogHeader>
+        <div className="flex-1 overflow-y-auto p-3 space-y-3">
+          <ErrorBox error={loadError} />
+          {doc && !doc.valid && (
+            <p className="text-xs text-destructive border border-destructive/40 rounded-md p-2">
+              The policy file is invalid — the server is failing closed (owners only). Saving a valid policy restores it.
+            </p>
+          )}
+          {(tab === 'roles' || tab === 'bindings') && !doc && !loadError && <p className="text-sm text-muted-foreground text-center py-8">Loading…</p>}
+          {tab === 'roles' && doc && <RolesTab doc={doc} save={savePolicy} onDirty={setDirty} />}
+          {tab === 'bindings' && doc && <BindingsTab doc={doc} save={savePolicy} call={call} onDirty={setDirty} />}
+          {tab === 'principals' && <PrincipalsTab call={call} onPolicyChange={loadPolicy} ownerIds={doc?.ownerIds ?? []} />}
+          {tab === 'keys' && <ApiKeysTab call={call} roles={roles} />}
+          {tab === 'blocks' && <BlocklistTab call={call} onPolicyChange={loadPolicy} />}
+          {tab === 'audit' && <AuditTab call={call} onPolicyChange={loadPolicy} ownerIds={doc?.ownerIds ?? []} onOpenSession={async (id) => { await onOpenSession(id); setOpen(false); }} />}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/client/components/owner/PrincipalsTab.tsx

@@ -0,0 +1,55 @@
+import { useCallback, useEffect, useState } from 'react';
+import { Ban, KeyRound, RefreshCw } from 'lucide-react';
+import { ErrorBox, fmtTs, iconBtn, principalActions, selectCls, tdCls, thCls, useAction, type OwnerCall } from './shared';
+
+interface Row { id: string; kind: string; lastRole?: string; lastSeen: string; turns: number; denies: number }
+
+export function PrincipalsTab({ call, onPolicyChange, ownerIds }: { call: OwnerCall; onPolicyChange: () => Promise<void>; ownerIds: string[] }) {
+  const [days, setDays] = useState(7);
+  const [data, setData] = useState<{ principals: Row[]; truncated: boolean } | null>(null);
+  const { busy, error, run } = useAction();
+  const actions = principalActions(call, onPolicyChange, ownerIds);
+  const load = useCallback(() => run('load', async () => setData(await call(`/principals?days=${days}`))), [call, days]); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => { load(); }, [load]);
+
+  return (
+    <div className="space-y-2">
+      <div className="flex items-center gap-2">
+        <span className="text-xs text-muted-foreground">Seen in the audit, last</span>
+        <select className={selectCls} value={days} onChange={(e) => setDays(Number(e.target.value))}>
+          {[1, 7, 30, 90].map((d) => <option key={d} value={d}>{d} day{d > 1 ? 's' : ''}</option>)}
+        </select>
+        <button className={iconBtn} title="Refresh" onClick={load}><RefreshCw className={`w-3.5 h-3.5 ${busy === 'load' ? 'animate-spin' : ''}`} /></button>
+        {data?.truncated && <span className="text-[10px] text-amber-500">scan capped — older activity omitted</span>}
+      </div>
+      <ErrorBox error={error} />
+      <div className="border rounded-lg overflow-x-auto">
+        <table className="w-full text-xs">
+          <thead className="bg-muted/40"><tr>
+            <th className={thCls}>Principal</th><th className={thCls}>Kind</th><th className={thCls}>Last role</th>
+            <th className={thCls}>Last seen</th><th className={thCls}>Turns</th><th className={thCls} title="Includes shadow (would-deny) verdicts">Denies</th><th className={thCls} />
+          </tr></thead>
+          <tbody className="divide-y">
+            {data?.principals.map((p) => (
+              <tr key={p.id}>
+                <td className={`${tdCls} font-mono break-all`}>{p.id}</td>
+                <td className={tdCls}>{p.kind}</td>
+                <td className={tdCls}>{p.lastRole ?? '—'}</td>
+                <td className={`${tdCls} whitespace-nowrap`}>{fmtTs(p.lastSeen)}</td>
+                <td className={tdCls}>{p.turns}</td>
+                <td className={`${tdCls} ${p.denies ? 'text-destructive' : ''}`}>{p.denies}</td>
+                <td className={`${tdCls} whitespace-nowrap text-right`}>
+                  {actions.canRevoke(p.id) && (
+                    <button className={`${iconBtn} mr-2`} title="Revoke tokens" disabled={!!busy} onClick={() => run(`rv-${p.id}`, () => actions.revoke(p.id))}><KeyRound className="w-3.5 h-3.5" /></button>
+                  )}
+                  {actions.canBlock(p.id) &&<button className={`${iconBtn} hover:text-destructive`} title="Block" disabled={!!busy} onClick={() => run(`bl-${p.id}`, () => actions.block(p.id))}><Ban className="w-3.5 h-3.5" /></button>}
+                </td>
+              </tr>
+            ))}
+            {data && !data.principals.length && <tr><td colSpan={7} className="text-center text-muted-foreground py-6">No principals in this window.</td></tr>}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+}

package/src/client/components/owner/RolesTab.tsx

@@ -0,0 +1,132 @@
+import { useEffect, useState } from 'react';
+import { Check, Loader2, Plus, Trash2, Undo2 } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { CsvInput, ErrorBox, iconBtn, inputCls, selectCls, useAction, type Policy, type PolicyDoc, type Profile, type SavePolicy } from './shared';
+
+/** The part of the policy a PUT writes (blocklist/tokensValidAfter have their own routes; the server keeps them). */
+const editable = (p: Policy) => { const { blocklist: _b, tokensValidAfter: _t, ...rest } = p; return JSON.stringify(rest); };
+
+/** A whole-document policy draft: edit locally, Save = PUT with the version the draft started from (server validates;
+ *  errors stay on screen). A refresh never wipes edits: a clean draft follows it; a dirty one adopts the new version only
+ *  when the editable part is unchanged (a block/revoke meanwhile) — otherwise Save still 409s instead of overwriting. */
+export function usePolicyDraft(doc: PolicyDoc, save: SavePolicy, onDirty?: (dirty: boolean) => void) {
+  const [base, setBase] = useState(doc);
+  const [draft, setDraft] = useState<Policy>(() => structuredClone(doc.policy));
+  const dirty = editable(draft) !== editable(base.policy);
+  useEffect(() => {
+    if (!dirty || editable(doc.policy) === editable(draft)) { setBase(doc); setDraft(structuredClone(doc.policy)); }
+    else if (editable(doc.policy) === editable(base.policy)) setBase(doc);
+  }, [doc]); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => { onDirty?.(dirty); }, [dirty, onDirty]);
+  useEffect(() => () => onDirty?.(false), [onDirty]);
+  const action = useAction();
+  const saveBar = (
+    <div className="flex items-center gap-2 sticky -bottom-3 z-10 -mx-3 -mb-3 px-3 pt-2 pb-3 bg-background border-t">
+      <Button size="sm" className="h-7 text-xs" disabled={!dirty || !!action.busy} onClick={() => action.run('save', () => save(draft, base.version))}>
+        {action.busy ? <Loader2 className="w-3 h-3 mr-1 animate-spin" /> : <Check className="w-3 h-3 mr-1" />} Save policy
+      </Button>
+      <Button size="sm" variant="ghost" className="h-7 text-xs" disabled={!dirty} onClick={() => { setBase(doc); setDraft(structuredClone(doc.policy)); }}>
+        <Undo2 className="w-3 h-3 mr-1" /> Discard
+      </Button>
+      {dirty && <span className="text-[10px] text-amber-500">unsaved changes</span>}
+    </div>
+  );
+  return { draft, setDraft, error: action.error, saveBar };
+}
+
+export function RolesTab({ doc, save, onDirty }: { doc: PolicyDoc; save: SavePolicy; onDirty: (dirty: boolean) => void }) {
+  const { draft, setDraft, error, saveBar } = usePolicyDraft(doc, save, onDirty);
+  const [newRole, setNewRole] = useState('');
+  const [newProfile, setNewProfile] = useState('');
+  const profileNames = Object.keys(draft.profiles);
+
+  const setRole = (name: string, patch: Partial<Policy['roles'][string]>) =>
+    setDraft((d) => ({ ...d, roles: { ...d.roles, [name]: { ...d.roles[name], ...patch } } }));
+  const setProfile = (name: string, patch: Partial<Profile>) =>
+    setDraft((d) => ({ ...d, profiles: { ...d.profiles, [name]: { ...d.profiles[name], ...patch } } }));
+  const without = <T,>(o: Record<string, T>, k: string) => Object.fromEntries(Object.entries(o).filter(([n]) => n !== k));
+
+  return (
+    <div className="space-y-4">
+      <ErrorBox error={error} />
+      <section className="space-y-2">
+        <h3 className="text-xs font-medium text-muted-foreground uppercase tracking-wide">Roles</h3>
+        <p className="text-[11px] text-muted-foreground">Owners come only from the OWNERS env; this row only picks their rank and profile.</p>
+        <div className="border rounded-lg divide-y">
+          {Object.entries(draft.roles).sort((a, b) => b[1].rank - a[1].rank).map(([name, r]) => (
+            <div key={name} className="flex items-center gap-2 p-2">
+              <span className="text-sm font-medium w-28 truncate">{name}</span>
+              <label className="text-[10px] text-muted-foreground">rank</label>
+              <Input type="number" className={`${inputCls} w-20`} value={Number.isFinite(r.rank) ? r.rank : ''} onChange={(e) => setRole(name, { rank: e.target.value === '' ? NaN : Number(e.target.value) })} />
+              <label className="text-[10px] text-muted-foreground">profile</label>
+              <select className={selectCls} value={r.profile} onChange={(e) => setRole(name, { profile: e.target.value })}>
+                {!profileNames.includes(r.profile) && <option value={r.profile}>{r.profile} (missing)</option>}
+                {profileNames.map((p) => <option key={p} value={p}>{p}</option>)}
+              </select>
+              <div className="flex-1" />
+              {name !== 'owner' && (
+                <button className={`${iconBtn} hover:text-destructive`} title="Remove role" onClick={() => setDraft((d) => ({ ...d, roles: without(d.roles, name) }))}>
+                  <Trash2 className="w-3.5 h-3.5" />
+                </button>
+              )}
+            </div>
+          ))}
+        </div>
+        <div className="flex items-center gap-2">
+          <Input className={`${inputCls} w-40`} placeholder="new role name" value={newRole} onChange={(e) => setNewRole(e.target.value.trim())} />
+          <Button size="sm" variant="outline" className="h-7 text-xs" disabled={!newRole || newRole in draft.roles}
+            onClick={() => { setDraft((d) => ({ ...d, roles: { ...d.roles, [newRole]: { rank: 10, profile: profileNames.includes('none') ? 'none' : profileNames[0] } } })); setNewRole(''); }}>
+            <Plus className="w-3 h-3 mr-1" /> Add role
+          </Button>
+          <div className="flex-1" />
+          <label className="text-[10px] text-muted-foreground">default role</label>
+          <select className={selectCls} value={draft.default} onChange={(e) => setDraft((d) => ({ ...d, default: e.target.value }))}>
+            {Object.keys(draft.roles).filter((n) => n !== 'owner').map((n) => <option key={n} value={n}>{n}</option>)}
+          </select>
+        </div>
+      </section>
+
+      <section className="space-y-2">
+        <h3 className="text-xs font-medium text-muted-foreground uppercase tracking-wide">Profiles</h3>
+        {Object.entries(draft.profiles).map(([name, p]) => (
+          <div key={name} className="border rounded-lg p-3 space-y-2">
+            <div className="flex items-center gap-2">
+              <span className="text-sm font-medium">{name}</span>
+              <div className="flex-1" />
+              <button className={`${iconBtn} hover:text-destructive`} title="Remove profile" onClick={() => setDraft((d) => ({ ...d, profiles: without(d.profiles, name) }))}>
+                <Trash2 className="w-3.5 h-3.5" />
+              </button>
+            </div>
+            <div className="grid grid-cols-[4.5rem_1fr] gap-x-2 gap-y-1.5 items-center">
+              {(['tools', 'mcps', 'env'] as const).map((f) => (
+                <FieldRow key={f} label={f}><CsvInput value={p[f]} onChange={(v) => setProfile(name, { [f]: v })} placeholder='comma-separated, "*" = all' /></FieldRow>
+              ))}
+              <FieldRow label="rate"><Input className={`${inputCls} w-28`} value={p.rate} placeholder="120/h" onChange={(e) => setProfile(name, { rate: e.target.value.trim() })} /></FieldRow>
+              <FieldRow label="readScope">
+                <select className={`${selectCls} w-28`} value={p.readScope} onChange={(e) => setProfile(name, { readScope: e.target.value as Profile['readScope'] })}>
+                  {['all', 'own', 'none'].map((s) => <option key={s} value={s}>{s}</option>)}
+                </select>
+              </FieldRow>
+              <FieldRow label="outbound">
+                <input type="checkbox" className="h-4 w-4 justify-self-start" checked={p.outbound} onChange={(e) => setProfile(name, { outbound: e.target.checked })} />
+              </FieldRow>
+            </div>
+          </div>
+        ))}
+        <div className="flex items-center gap-2">
+          <Input className={`${inputCls} w-40`} placeholder="new profile name" value={newProfile} onChange={(e) => setNewProfile(e.target.value.trim())} />
+          <Button size="sm" variant="outline" className="h-7 text-xs" disabled={!newProfile || newProfile in draft.profiles}
+            onClick={() => { setDraft((d) => ({ ...d, profiles: { ...d.profiles, [newProfile]: { tools: [], mcps: [], env: [], outbound: false, readScope: 'none', rate: '0' } } })); setNewProfile(''); }}>
+            <Plus className="w-3 h-3 mr-1" /> Add profile
+          </Button>
+        </div>
+      </section>
+      {saveBar}
+    </div>
+  );
+}
+
+function FieldRow({ label, children }: { label: string; children: React.ReactNode }) {
+  return (<><label className="text-[11px] text-muted-foreground">{label}</label>{children}</>);
+}

package/src/client/components/owner/shared.tsx

@@ -0,0 +1,84 @@
+import { useEffect, useState } from 'react';
+import { Input } from '@/components/ui/input';
+import type { OwnerCall } from '@/hooks/useOwner';
+
+export type { OwnerCall };
+export interface Profile { tools: string[]; mcps: string[]; env: string[]; outbound: boolean; readScope: 'all' | 'own' | 'none'; rate: string }
+export interface Match { kind?: string; id?: string; emailIn?: string[]; domain?: string; verified?: boolean; [k: string]: unknown }
+export interface Policy {
+  roles: Record<string, { rank: number; profile: string }>;
+  profiles: Record<string, Profile>;
+  bindings: { match: Match; role: string }[];
+  default: string;
+  blocklist: { match: Match; until: number | null; reason?: string }[];
+  tokensValidAfter: Record<string, number>;
+}
+export interface PolicyDoc { policy: Policy; version: string; valid: boolean; ownerIds?: string[] }
+/** PUT the whole policy, guarded by the version the edit started from. */
+export type SavePolicy = (policy: Policy, version: string) => Promise<void>;
+
+export const KINDS = ['user', 'email', 'slack', 'apikey', 'internal', 'anonymous'];
+export const selectCls = 'h-7 rounded-md border border-input bg-background px-2 text-xs';
+export const inputCls = 'h-7 text-xs';
+export const thCls = 'text-left font-medium text-muted-foreground px-2 py-1 whitespace-nowrap';
+export const tdCls = 'px-2 py-1 align-top';
+export const iconBtn = 'text-muted-foreground hover:text-foreground disabled:opacity-40 transition-colors';
+
+export const fmtTs = (v: string | number) => new Date(v).toLocaleString(undefined, { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' });
+export const matchLabel = (m: Match) => Object.entries(m).map(([k, v]) => `${k}=${Array.isArray(v) ? v.join('|') : String(v)}`).join(' ');
+
+/** One action at a time, with its error kept visible (useOwner's call already logged it). */
+export function useAction() {
+  const [busy, setBusy] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const run = async (key: string, fn: () => Promise<void>) => {
+    if (busy) return;
+    setBusy(key);
+    setError(null);
+    try { await fn(); } catch (e: any) { setError(e?.message ?? String(e)); } finally { setBusy(null); }
+  };
+  return { busy, error, run };
+}
+
+/** Server error; a policy validation error ("Invalid policy: a; b") renders as a list. */
+export function ErrorBox({ error }: { error: string | null }) {
+  if (!error) return null;
+  const m = /^Invalid policy: (.*)$/s.exec(error);
+  return (
+    <div className="text-xs text-destructive border border-destructive/40 rounded-md p-2">
+      {m ? (<><p className="font-medium">Invalid policy — not saved:</p><ul className="list-disc pl-4">{m[1].split('; ').map((e, i) => <li key={i}>{e}</li>)}</ul></>) : error}
+    </div>
+  );
+}
+
+/** Comma-separated list input; commits on blur so typing "a, " isn't normalized away mid-edit. */
+export function CsvInput({ value, onChange, placeholder }: { value: string[] | undefined; onChange: (v: string[]) => void; placeholder?: string }) {
+  const joined = (value ?? []).join(', ');
+  const [text, setText] = useState(joined);
+  useEffect(() => setText(joined), [joined]);
+  return (
+    <Input className={inputCls} value={text} placeholder={placeholder} onChange={(e) => setText(e.target.value)}
+      onBlur={() => onChange(text.split(',').map((s) => s.trim()).filter(Boolean))} />
+  );
+}
+
+/** Row actions shared by Principals and Audit. Only `user:`/`internal:` principals carry revocable tokens. Both actions
+ *  change the policy document, so `onPolicyChange` refreshes its version (else the next Save would 409). */
+export function principalActions(call: OwnerCall, onPolicyChange: () => Promise<void>, ownerIds: string[] = []) {
+  return {
+    canRevoke: (id: string) => /^(user|internal):/.test(id) && id !== 'internal:agent-internal',
+    /** UI hint only (ownerIds from GET /policy) — the server refuses a block that matches an owner. */
+    canBlock: (id: string) => !ownerIds.includes(id),
+    revoke: async (id: string) => {
+      if (!confirm(`Revoke every token issued to ${id}? They must sign in again.`)) return;
+      await call('/tokens/revoke', 'POST', { principalId: id });
+      await onPolicyChange();
+    },
+    block: async (id: string) => {
+      const reason = prompt(`Block ${id}? Reason (optional):`);
+      if (reason === null) return;
+      await call('/blocks', 'POST', { match: { id }, until: null, reason });
+      await onPolicyChange();
+    },
+  };
+}

package/src/client/hooks/useAuth.ts

@@ -1,5 +1,9 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { onAuth, signOutUser, hasFirebase } from '@/lib/firebase';
+import { reportApiFailure, reportApiResponse } from '@/lib/backendHealth';
+import { logger } from '@/lib/debug';
+
+const log = logger.forComponent('useAuth');
 
 export interface AuthUser {
   uid: string;
@@ -47,13 +51,18 @@ export function useAuth(): AuthState {
       let m: 'local' | 'firebase' = hasFirebase ? 'firebase' : 'local';
       try {
         const r = await fetch('/api/auth/mode');
+        // The ONLY unauthenticated request the app makes, so it is the one chance to detect a hijacked
+        // backend BEFORE login. Without this a port-hijack just renders the login page forever with no
+        // explanation — the sign-in never succeeds and nothing on screen says why.
+        reportApiResponse('/api/auth/mode', r);
         if (r.ok) {
           const d = await r.json();
           m = d.provider === 'firebase' ? 'firebase' : 'local';
           setNeedsSetup(!!d.needsSetup);
         }
-      } catch {
-        /* fall back to firebase-presence heuristic */
+      } catch (err) {
+        reportApiFailure('/api/auth/mode', err);
+        log.warn('auth-mode probe failed — falling back to the firebase-presence heuristic', err);
       }
       setMode(m);
 

package/src/client/hooks/useIsOwner.ts

@@ -0,0 +1,24 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Whether the signed-in caller is an owner — `isOwner` on `GET /api/config` (derived server-side, never persisted).
+ * `undefined` until known. A UI hint only: the server enforces owner-only mutations regardless.
+ */
+export function useIsOwner(getToken: () => Promise<string | null>, enabled = true): boolean | undefined {
+  const [isOwner, setIsOwner] = useState<boolean>();
+
+  useEffect(() => {
+    if (!enabled) return;
+    let alive = true;
+    getToken().then((token) => {
+      if (!token || !alive) return;
+      fetch('/api/config', { headers: { Authorization: `Bearer ${token}` } })
+        .then((r) => { if (!r.ok) throw new Error(`HTTP ${r.status}`); return r.json(); })
+        .then((c: { isOwner?: boolean }) => { if (alive) setIsOwner(!!c.isOwner); })
+        .catch((e) => console.warn('[isOwner] load failed', e));
+    });
+    return () => { alive = false; };
+  }, [enabled, getToken]);
+
+  return isOwner;
+}

package/src/client/hooks/useModules.ts

@@ -42,7 +42,11 @@ export function useModules(getToken: () => Promise<string | null>, enabled: bool
     setLoading(true);
     setError(null);
     try {
-      const data = await api<{ installed: InstalledModule[]; available: AvailableModule[] }>('/api/modules', getToken);
+      const data = await api<{ installed: InstalledModule[]; available: AvailableModule[] }>('/api/modules', getToken, {
+        // A 404 here is the documented "server predates /api/modules" probe below — a handled outcome,
+        // not a backend fault, so it must not raise the health banner.
+        expect: [404],
+      });
       setInstalled(data.installed ?? []);
       setAvailable(data.available ?? []);
       setUnsupported(false);

package/src/client/hooks/useOwner.ts

@@ -0,0 +1,20 @@
+import { useCallback } from 'react';
+import { api } from '@/lib/api';
+import { useIsOwner } from './useIsOwner';
+
+/** `/api/owner/*` caller: throws the server's `error` (validation text included), logged before it reaches the UI. */
+export type OwnerCall = <T = any>(path: string, method?: string, body?: unknown) => Promise<T>;
+
+/** Owner Console access: `isOwner` (UI hint — the server enforces) + an authenticated caller for `/api/owner/*`. */
+export function useOwner(getToken: () => Promise<string | null>) {
+  const isOwner = useIsOwner(getToken);
+  const call = useCallback<OwnerCall>(async (path, method = 'GET', body) => {
+    try {
+      return await api(`/api/owner${path}`, getToken, { method, ...(body !== undefined ? { body: JSON.stringify(body) } : {}) });
+    } catch (e: any) {
+      console.warn(`[owner] ${method} ${path} failed: ${e?.message ?? e}`);
+      throw e;
+    }
+  }, [getToken]);
+  return { isOwner, call };
+}

package/src/client/lib/api.ts

@@ -1,13 +1,29 @@
-/** Minimal authenticated JSON fetch helper. Throws `Error("<status> <statusText>")` or the server's `error` field. */
-export async function api<T>(path: string, getToken: () => Promise<string | null>, init?: RequestInit): Promise<T> {
+import { reportApiFailure, reportApiResponse } from '@/lib/backendHealth';
+
+/** Minimal authenticated JSON fetch helper. Throws `Error("<status> <statusText>")` or the server's `error` field, with `status` set. */
+export async function api<T>(
+  path: string,
+  getToken: () => Promise<string | null>,
+  /** `expect`: statuses this call site handles as normal — see `apiFetch`. Still throws; it only keeps
+   *  the backend-health banner from flagging a by-design non-2xx. */
+  init?: RequestInit & { expect?: readonly number[] },
+): Promise<T> {
   const token = await getToken();
-  const res = await fetch(path, {
-    ...init,
-    headers: { Authorization: `Bearer ${token ?? ''}`, 'Content-Type': 'application/json', ...init?.headers },
-  });
+  let res: Response;
+  try {
+    res = await fetch(path, {
+      ...init,
+      headers: { Authorization: `Bearer ${token ?? ''}`, 'Content-Type': 'application/json', ...init?.headers },
+    });
+  } catch (err) {
+    // Single choke point: every caller of api() gets backend-fault surfacing with no call-site change.
+    reportApiFailure(path, err);
+    throw err;
+  }
+  reportApiResponse(path, res, init?.expect);
   if (!res.ok) {
     const body = await res.json().catch(() => ({}));
-    throw new Error(body.error || `${res.status} ${res.statusText}`);
+    throw Object.assign(new Error(body.error || `${res.status} ${res.statusText}`), { status: res.status });
   }
   return res.json();
 }