create-safest-tools 0.2.0

package/template/console/settings/SettingsWorkspace.tsx

@@ -0,0 +1,155 @@
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+import { PageHeader } from "../components/PageHeader";
+import { errorMessage, requestJson } from "../lib/http";
+import { getShellSnapshot, subscribeToShell } from "../shell/store";
+import type { WorkspaceBrand } from "../shell/types";
+import { BrandEditor } from "./BrandEditor";
+import { dispatchSetupUpdated, openChannelDialog, settingsEvents } from "./events";
+import type {
+  ApplicationIntegration,
+  BrandResponse,
+  InstallationDetails,
+  InstallationResponse,
+  IntegrationsResponse,
+  ReportingChannel,
+  ReportingChannelsResponse,
+  SetupResponse,
+  SetupStatus,
+} from "./types";
+
+const featureNames: Record<string, string> = {
+  database: "Database",
+  email: "Email delivery",
+  queues: "Queues",
+  r2: "Private evidence storage",
+  storage: "Private evidence storage",
+  turnstile: "Human verification",
+  workflows: "Workflows",
+};
+
+function featureName(value: string): string {
+  return featureNames[value] ?? value.replaceAll("_", " ").replace(/^./u, (letter) => letter.toUpperCase());
+}
+
+function installationFacts(installation: InstallationDetails): Array<[string, string]> {
+  return [
+    ["Workspace", installation.displayName || "Safety workspace"],
+    ["Default language", installation.defaultLocale || "en"],
+    ["Time zone", installation.timezone || "UTC"],
+    ["Anonymous reporting", installation.anonymousReportingEnabled ? "Enabled" : "Disabled"],
+  ];
+}
+
+function SettingsLoading() {
+  return <div className="settings-card-loading" aria-label="Loading settings" role="status"><div className="skeleton-block" /></div>;
+}
+
+function ChannelRow({ channel }: { channel: ReportingChannel }) {
+  const active = channel.enabled !== false;
+  return <article className="integration-row"><span className={`setup-state${active ? "" : " warning"}`}>{active ? "✓" : "!"}</span><div><strong>{channel.name || "Hosted report form"}</strong><small>{channel.url}</small></div><div className="integration-actions"><span className={`badge${active ? "" : " urgent"}`}>{active ? "Hosted" : "Needs setup"}</span><a className="text-button" href={channel.url} target="_blank" rel="noopener">Open</a></div></article>;
+}
+
+function IntegrationRow({ integration }: { integration: ApplicationIntegration }) {
+  const active = integration.enabled !== false;
+  const contextual = integration.channelMode === "contextual";
+  const ready = active && (!contextual || integration.activeKeyCount > 0);
+  const detail = integration.allowedOrigins.length ? integration.allowedOrigins.join(", ") : "No website origin";
+  const status = !active ? "Disabled" : contextual ? integration.activeKeyCount > 0 ? "Signed-in" : "Needs key" : "Anonymous";
+  return <article className="integration-row"><span className={`setup-state${ready ? "" : " warning"}`}>{ready ? "✓" : "!"}</span><div><strong>{integration.name || integration.id}</strong><small>{detail}</small></div><span className={`badge${ready ? "" : " urgent"}`}>{status}</span></article>;
+}
+
+export function SettingsWorkspace() {
+  const shell = useSyncExternalStore(subscribeToShell, getShellSnapshot, getShellSnapshot);
+  const canManageInstallation = shell.session?.permissions.manageInstallation === true;
+  const canManageConfiguration = shell.session?.permissions.manageConfiguration === true;
+  const canManageIntegrations = shell.session?.permissions.manageIntegrations === true;
+  const [setup, setSetup] = useState<SetupStatus | null>(null);
+  const [installation, setInstallation] = useState<InstallationDetails | null>(null);
+  const [brand, setBrand] = useState<WorkspaceBrand | null>(null);
+  const [integrations, setIntegrations] = useState<ApplicationIntegration[]>([]);
+  const [channels, setChannels] = useState<ReportingChannel[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [verifying, setVerifying] = useState("");
+  const [error, setError] = useState("");
+
+  const loadChannels = useCallback(async (): Promise<void> => {
+    if (!canManageIntegrations) { setIntegrations([]); setChannels([]); return; }
+    const [integrationResponse, channelResponse] = await Promise.all([
+      requestJson<IntegrationsResponse>("/v1/admin/integrations"),
+      requestJson<ReportingChannelsResponse>("/v1/admin/reporting-channels"),
+    ]);
+    setIntegrations(Array.isArray(integrationResponse.integrations) ? integrationResponse.integrations : []);
+    setChannels(Array.isArray(channelResponse.channels) ? channelResponse.channels : []);
+  }, [canManageIntegrations]);
+
+  const load = useCallback(async (): Promise<void> => {
+    if (!shell.session) return;
+    setLoading(true);
+    setError("");
+    try {
+      const tasks: Promise<void>[] = [];
+      if (canManageInstallation) tasks.push(Promise.all([
+        requestJson<SetupResponse>("/v1/admin/setup"),
+        requestJson<InstallationResponse>("/v1/admin/installation"),
+      ]).then(([setupResponse, installationResponse]) => {
+        setSetup(setupResponse.setup);
+        setInstallation(installationResponse.installation);
+        dispatchSetupUpdated(setupResponse.setup);
+      }));
+      if (canManageConfiguration) tasks.push(requestJson<BrandResponse>("/v1/admin/brand").then((response) => setBrand(response.brand)));
+      if (canManageIntegrations) tasks.push(loadChannels());
+      await Promise.all(tasks);
+    } catch (cause) {
+      setError(errorMessage(cause, "Workspace settings could not be loaded."));
+    } finally {
+      setLoading(false);
+    }
+  }, [shell.session?.actor.id, canManageInstallation, canManageConfiguration, canManageIntegrations, loadChannels]);
+
+  useEffect(() => { void load(); }, [load]);
+  useEffect(() => {
+    const reloadChannels = (): void => { void loadChannels().catch((cause) => setError(errorMessage(cause, "Reporting channels could not be refreshed."))); };
+    window.addEventListener(settingsEvents.channelsChanged, reloadChannels);
+    return () => window.removeEventListener(settingsEvents.channelsChanged, reloadChannels);
+  }, [loadChannels]);
+
+  const verify = async (featureKey: string): Promise<void> => {
+    setVerifying(featureKey);
+    setError("");
+    try {
+      await requestJson(`/v1/admin/setup/${encodeURIComponent(featureKey)}/verify`, { method: "POST" });
+      const response = await requestJson<SetupResponse>("/v1/admin/setup");
+      setSetup(response.setup);
+      dispatchSetupUpdated(response.setup);
+    } catch (cause) {
+      setError(errorMessage(cause, "The setup item could not be verified."));
+    } finally {
+      setVerifying("");
+    }
+  };
+
+  const optional = new Set(setup?.optional ?? []);
+  const requiredRemaining = setup?.features.filter((feature) => feature.state !== "ready" && !optional.has(feature.featureKey)).length ?? 0;
+  const noAccess = !canManageInstallation && !canManageConfiguration && !canManageIntegrations;
+
+  return (
+    <div className="page-stack settings-react-workspace" data-react-slice="settings-workspace">
+      <PageHeader titleId="settings-title" title="Settings" description="Update branding, reporting channels, and deployment checks.">
+        {!noAccess ? <div className="surface-buttons"><button className="secondary" type="button" disabled={loading} onClick={() => void load()}>{loading ? "Refreshing…" : "Refresh"}</button></div> : null}
+      </PageHeader>
+      {noAccess ? <section className="surface settings-no-access"><div className="empty-product"><h2>Settings unavailable</h2><p>Your role does not include workspace settings access.</p></div></section> : <div className="settings-grid">
+        {canManageInstallation ? <>
+          <section className="surface settings-card" aria-labelledby="setup-checklist-title"><div className="surface-head"><h2 id="setup-checklist-title">Setup checklist</h2><span className={`badge${requiredRemaining ? " urgent" : ""}`}>{loading && !setup ? "Checking" : requiredRemaining ? `${requiredRemaining} required` : "Ready"}</span></div>{loading && !setup ? <SettingsLoading /> : <div className="setup-list">{setup?.features.length ? setup.features.map((feature) => {
+            const ready = feature.state === "ready";
+            const isOptional = optional.has(feature.featureKey);
+            return <article className="setup-row" key={feature.featureKey}><span className={`setup-state${ready ? "" : " warning"}`}>{ready ? "✓" : "!"}</span><div><strong>{featureName(feature.featureKey)}</strong><small>{feature.message || feature.detail || (ready ? "Verified in this deployment" : isOptional ? "Optional setup" : "Verification required")}</small></div>{ready ? <span className="badge">Ready</span> : <button className="secondary compact-button" type="button" disabled={Boolean(verifying)} onClick={() => void verify(feature.featureKey)}>{verifying === feature.featureKey ? "Checking…" : isOptional ? "Check optional" : "Verify"}</button>}</article>;
+          }) : <div className="settings-empty-row"><strong>No setup items</strong><small>There is nothing to verify for this deployment.</small></div>}</div>}</section>
+          <section className="surface settings-card" aria-labelledby="workspace-details-title"><div className="surface-head"><h2 id="workspace-details-title">Workspace details</h2></div>{loading && !installation ? <SettingsLoading /> : installation ? <dl className="settings-facts">{installationFacts(installation).map(([label, value]) => <span className="settings-fact" key={label}><dt>{label}</dt><dd>{value}</dd></span>)}</dl> : <div className="settings-empty-row">Workspace details are unavailable.</div>}</section>
+        </> : null}
+        {canManageConfiguration ? <BrandEditor brand={brand} displayName={installation?.displayName ?? "Safest Resolve"} loading={loading && !brand} onSaved={setBrand} /> : null}
+        {canManageIntegrations ? <section className="surface settings-card settings-wide" aria-labelledby="reporting-channels-title"><div className="surface-head"><div><h2 id="reporting-channels-title">Reporting channels</h2><p>Choose where people open the form and what context can be trusted.</p></div><button className="primary" type="button" onClick={openChannelDialog}>Add channel</button></div>{loading && !channels.length && !integrations.length ? <SettingsLoading /> : <div className="integration-list">{channels.map((channel) => <ChannelRow channel={channel} key={channel.id} />)}{integrations.map((integration) => <IntegrationRow integration={integration} key={integration.id} />)}{!channels.length && !integrations.length ? <div className="settings-empty-row"><strong>No reporting channels yet</strong><small>Add a hosted form or connect the widget to your application.</small></div> : null}</div>}</section> : null}
+      </div>}
+      <p className="error surface-error" role="alert">{error}</p>
+    </div>
+  );
+}

package/template/console/settings/events.ts

@@ -0,0 +1,19 @@
+import type { SetupStatus } from "./types";
+
+export const settingsEvents = {
+  openChannel: "safest:settings:open-channel",
+  channelsChanged: "safest:settings:channels-changed",
+  setupUpdated: "safest:settings:setup-updated",
+} as const;
+
+export function openChannelDialog(): void {
+  window.dispatchEvent(new Event(settingsEvents.openChannel));
+}
+
+export function dispatchChannelsChanged(): void {
+  window.dispatchEvent(new Event(settingsEvents.channelsChanged));
+}
+
+export function dispatchSetupUpdated(setup: SetupStatus): void {
+  window.dispatchEvent(new CustomEvent(settingsEvents.setupUpdated, { detail: { setup } }));
+}

package/template/console/settings/handoff.ts

@@ -0,0 +1,22 @@
+import type { ContextSchema, WidgetChannelResponse } from "./types";
+
+export function widgetHandoff(
+  result: WidgetChannelResponse,
+  origin: string,
+  formVersion: string,
+  mode: "contextual" | "anonymous",
+  contextSchema: ContextSchema,
+): string {
+  const serviceBase = result.publicBaseUrl || window.location.origin;
+  const tag = `<script src="${serviceBase}/widget.js" defer></script>\n<safest-report\n  api-base="${serviceBase}"\n  integration-id="${result.integrationId}"\n  form-version="${formVersion}"${mode === "contextual" ? '\n  context-endpoint="/api/safest/report-context"' : ""}\n  target-type="<object type>"\n  target-reference="<object id>">\n</safest-report>`;
+
+  if (mode === "anonymous") {
+    return `Safest Resolve anonymous widget\n\nThis channel has no API key and does not identify the reporter. Values in target-type and target-reference are reporter-provided hints, not verified facts.\n\nAdd this component:\n${tag}\n\nContent Security Policy\nAllow ${serviceBase} in script-src, style-src, and frame-src. The human check runs inside the isolated Resolve frame.`;
+  }
+
+  const registered = contextSchema.fields.length
+    ? contextSchema.fields.map((field) => `  "${field.key}": <${field.type}>`).join(",\n")
+    : "  // no extra trusted fields registered";
+
+  return `Safest Resolve signed-in widget\n\n1. Store the one-time backend key in your secret manager. Never put it in HTML, JavaScript, logs, or a URL.\n\n2. Add this component:\n${tag}\n\nThe component automatically asks /api/safest/report-context for a short-lived opaque token. Your endpoint must authenticate the current session and verify that the user may report the requested object. Do not trust a user ID or object ownership sent by the browser.\n\n3. From that backend endpoint, POST ${serviceBase}/v1/context-tokens with:\nAuthorization: Bearer <BACKEND KEY>\nX-Safest-Integration-Id: ${result.integrationId}\nContent-Type: application/json\n\n{\n  "origin": "${origin}",\n  "form_version": "${formVersion}",\n  "reporter": { "reference": "<ID from authenticated server session>" },\n  "target": { "type": "<verified object type>", "reference": "<verified object id>" },\n  "trusted_facts": {\n${registered}\n  }\n}\n\nReturn only Resolve's context_token and expires_at to the component. Trusted facts stay in Resolve; the token itself contains only random identifiers.\n\nContent Security Policy\nAllow ${serviceBase} in script-src, style-src, and frame-src. The human check runs inside the isolated Resolve frame.`;
+}

package/template/console/settings/types.ts

@@ -0,0 +1,93 @@
+import type { WorkspaceBrand } from "../shell/types";
+
+export type ChannelMode = "hosted" | "contextual" | "anonymous";
+export type ContextFieldType = "string" | "number" | "boolean";
+export type ContextFieldSensitivity = "standard" | "sensitive";
+
+export interface SetupFeature {
+  featureKey: string;
+  state: string;
+  message?: string;
+  detail?: string;
+  errorCode?: string | null;
+}
+
+export interface SetupStatus {
+  ready: boolean;
+  features: SetupFeature[];
+  optional: string[];
+}
+
+export interface InstallationDetails {
+  id: string;
+  displayName: string;
+  defaultLocale: string;
+  timezone: string;
+  anonymousReportingEnabled: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ReportingChannel {
+  id: string;
+  mode: "hosted";
+  name: string;
+  formVersionId: string;
+  url: string;
+  enabled: boolean;
+  status: string;
+}
+
+export interface ApplicationIntegration {
+  id: string;
+  name: string;
+  allowedOrigins: string[];
+  scopes: string[];
+  channelMode: "contextual" | "anonymous";
+  formVersionId: string | null;
+  enabled: boolean;
+  activeKeyCount: number;
+}
+
+export interface PublishedForm {
+  id: string;
+  formKey: string;
+  version: number;
+  title: string;
+  description: string;
+  publishedAt: string;
+}
+
+export interface ContextField {
+  id: string;
+  key: string;
+  label: string;
+  type: ContextFieldType;
+  sensitivity: ContextFieldSensitivity;
+  required: boolean;
+  rule_eligible: boolean;
+}
+
+export interface ContextSchema {
+  version: 1;
+  allow_unknown: false;
+  fields: Omit<ContextField, "id">[];
+}
+
+export interface SetupResponse { setup: SetupStatus }
+export interface InstallationResponse { installation: InstallationDetails }
+export interface BrandResponse { brand: WorkspaceBrand }
+export interface IntegrationsResponse { integrations: ApplicationIntegration[] }
+export interface ReportingChannelsResponse { channels: ReportingChannel[] }
+export interface PublishedFormsResponse { forms: PublishedForm[] }
+
+export interface HostedChannelResponse {
+  channel: { mode: "hosted"; formVersionId: string; url: string };
+}
+
+export interface WidgetChannelResponse {
+  integrationId: string;
+  keyId: string | null;
+  apiKey: string | null;
+  publicBaseUrl: string;
+}

package/template/console/shell/WorkspaceShell.tsx

@@ -0,0 +1,160 @@
+import { Fragment, useEffect, useMemo, useState, useSyncExternalStore, type MouseEvent } from "react";
+import { createPortal } from "react-dom";
+import { AnalystIdentity } from "../components/AnalystIdentity";
+import { dispatchNavigation, dispatchSignOut } from "./events";
+import { visibleNavigationGroups } from "./navigation";
+import { getShellSnapshot, subscribeToShell } from "./store";
+import type { ConsoleAnalystProfile, ConsoleSession, CustomerBrand, WorkspaceView } from "./types";
+
+const fallbackBrand: CustomerBrand = {
+  organization_name: "Safest Resolve",
+  logo_url: "",
+  logo_alt: "",
+};
+
+const roleLabels: Record<string, string> = {
+  reviewer: "Analyst",
+  appeal_reviewer: "Appeal analyst",
+  administrator: "Administrator",
+  owner: "Infrastructure owner",
+  auditor: "Auditor",
+};
+
+function initials(value: string): string {
+  return value.split(/\s+/u).slice(0, 2).map((part) => part[0] ?? "").join("").toUpperCase() || "SR";
+}
+
+function useCustomerBrand(): CustomerBrand {
+  const [brand, setBrand] = useState<CustomerBrand>(() => window.SafestBrand?.defaults ?? fallbackBrand);
+
+  useEffect(() => {
+    const receiveBrand = (event: Event): void => {
+      if (!(event instanceof CustomEvent) || !event.detail?.brand) return;
+      setBrand((current) => ({ ...current, ...(event.detail.brand as CustomerBrand) }));
+    };
+    window.addEventListener("safest-brand-applied", receiveBrand);
+    return () => window.removeEventListener("safest-brand-applied", receiveBrand);
+  }, []);
+
+  return brand;
+}
+
+function BrandLogo({ brand, size }: { brand: CustomerBrand; size: "brand" | "workspace" }) {
+  const isDefaultBrand = brand.organization_name.trim().toLowerCase() === "safest resolve";
+  const logoUrl = brand.logo_url || (isDefaultBrand ? "/brand-icon.svg" : "");
+  const alt = brand.logo_alt || (isDefaultBrand ? "Safest Resolve logo" : `${brand.organization_name} logo`);
+  if (logoUrl) {
+    return <img className={size === "workspace" ? "workspace-logo" : undefined} src={logoUrl} alt={alt} width={size === "workspace" ? 30 : 34} height={size === "workspace" ? 30 : 34} />;
+  }
+  return <span className={size === "workspace" ? "workspace-mark" : "customer-brand-fallback"} aria-hidden="true">{initials(brand.organization_name)}</span>;
+}
+
+function analystProfile(session: ConsoleSession): ConsoleAnalystProfile {
+  return session.profile ?? {
+    actorId: session.actor.id,
+    displayName: session.displayName,
+    email: session.email ?? null,
+    avatarUrl: session.avatarUrl ?? null,
+    avatarColor: "#315d4d",
+    roles: session.roles,
+  };
+}
+
+function accessLabel(session: ConsoleSession): string {
+  return session.roles.map((role) => roleLabels[role] ?? role.replaceAll("_", " ")).join(", ") || "Team member";
+}
+
+function Navigation({ session, currentView, reportCount, open, onClose }: {
+  session: ConsoleSession;
+  currentView: WorkspaceView;
+  reportCount: number;
+  open: boolean;
+  onClose: () => void;
+}) {
+  const groups = useMemo(() => visibleNavigationGroups(session), [session]);
+  const navigate = (event: MouseEvent<HTMLAnchorElement>, view: WorkspaceView): void => {
+    event.preventDefault();
+    dispatchNavigation(view);
+    onClose();
+  };
+  return (
+    <>
+      <aside id="workspace-navigation" className={`sidebar${open ? " open" : ""}`} aria-label="Workspace navigation">
+        <nav>
+          {groups.map((group) => (
+            <Fragment key={group.label}>
+              <small>{group.label}</small>
+              {group.items.map((item) => (
+                <a className={item.view === currentView ? "active" : undefined} data-nav={item.view} href={`#${item.view}`} key={item.view} aria-current={item.view === currentView ? "page" : undefined} onClick={(event) => navigate(event, item.view)}>
+                  <svg aria-hidden="true"><use href={`#${item.icon}`} /></svg>
+                  <span>{item.label}</span>
+                  {item.count === "reports" ? <b id="nav-report-count" className="nav-count">{reportCount}</b> : null}
+                </a>
+              ))}
+            </Fragment>
+          ))}
+        </nav>
+        <div className="principle">
+          <span className="principle-dot" aria-hidden="true" />
+          <div><strong>Customer-owned records</strong><p>Reports and decisions stay in this deployment.</p></div>
+        </div>
+      </aside>
+      <button className="nav-scrim" type="button" aria-label="Close navigation" hidden={!open} onClick={onClose} />
+    </>
+  );
+}
+
+export function WorkspaceShell({ navigationTarget }: { navigationTarget: HTMLElement }) {
+  const snapshot = useSyncExternalStore(subscribeToShell, getShellSnapshot, getShellSnapshot);
+  const [navigationOpen, setNavigationOpen] = useState(false);
+  const brand = useCustomerBrand();
+  const session = snapshot.session;
+
+  useEffect(() => setNavigationOpen(false), [snapshot.currentView, session]);
+  useEffect(() => {
+    document.body.classList.toggle("mobile-navigation-open", navigationOpen && Boolean(session));
+    return () => document.body.classList.remove("mobile-navigation-open");
+  }, [navigationOpen, session]);
+  useEffect(() => {
+    const closeOnWideViewport = (): void => {
+      if (window.innerWidth > 760) setNavigationOpen(false);
+    };
+    const closeOnEscape = (event: KeyboardEvent): void => {
+      if (event.key === "Escape") setNavigationOpen(false);
+    };
+    window.addEventListener("resize", closeOnWideViewport);
+    window.addEventListener("keydown", closeOnEscape);
+    return () => {
+      window.removeEventListener("resize", closeOnWideViewport);
+      window.removeEventListener("keydown", closeOnEscape);
+    };
+  }, []);
+
+  const canUseAssistant = session?.permissions.useAssistant === true;
+  return (
+    <>
+      <header className="topbar" data-react-slice="workspace-shell">
+        <button className="nav-toggle" type="button" aria-label={navigationOpen ? "Close navigation" : "Open navigation"} aria-controls="workspace-navigation" aria-expanded={navigationOpen} hidden={!session} onClick={() => setNavigationOpen((open) => !open)}>
+          <svg aria-hidden="true"><use href="#i-menu" /></svg>
+        </button>
+        <a className="brand" href="/" aria-label="Workspace home">
+          <BrandLogo brand={brand} size="brand" />
+          <span><strong>{brand.organization_name}</strong><small>Reports and workflows</small></span>
+        </a>
+        <div className="top-workspace" aria-label="Current workspace" hidden={!session}>
+          <BrandLogo brand={brand} size="workspace" />
+          <span><strong>{brand.organization_name}</strong><small>Reports and workflows</small></span>
+        </div>
+        <button className="global-command" type="button" hidden={!session || !canUseAssistant} onClick={() => dispatchNavigation("assistant")}>
+          <svg aria-hidden="true"><use href="#i-search" /></svg><span>Search or ask Safest</span><kbd>⌘ K</kbd>
+        </button>
+        <div className="top-actions">
+          <span className={`health ${snapshot.health.status === "checking" ? "" : snapshot.health.status}`.trim()}><i aria-hidden="true" /><span>{snapshot.health.label}</span></span>
+          {session ? <div className="current-analyst"><AnalystIdentity analyst={analystProfile(session)} detail={accessLabel(session)} /></div> : null}
+          {session ? <button className="sign-out-button" type="button" onClick={dispatchSignOut}>Sign out</button> : null}
+        </div>
+      </header>
+      {session ? createPortal(<Navigation session={session} currentView={snapshot.currentView} reportCount={snapshot.reportCount} open={navigationOpen} onClose={() => setNavigationOpen(false)} />, navigationTarget) : null}
+    </>
+  );
+}

package/template/console/shell/controller.ts

@@ -0,0 +1,182 @@
+import { authEvents } from "../auth/events";
+import { errorMessage, hasSessionCredentials, requestJson } from "../lib/http";
+import { shellEvents } from "./events";
+import { visibleNavigationGroups } from "./navigation";
+import { getShellSnapshot, setShellSnapshot } from "./store";
+import type { ConsoleSession, CustomerBrand, ShellHealthStatus, WorkspaceView } from "./types";
+
+interface SessionResponse {
+  session: ConsoleSession;
+  configuration?: {
+    allowed_action_codes?: string[];
+    action_delivery_enabled?: boolean;
+  } | null;
+}
+
+const viewTitles: Partial<Record<WorkspaceView, string>> = {
+  command: "Command centre",
+  queues: "Queues and policies",
+  assistant: "Ask Safest",
+  "ai-quality": "AI quality",
+  analytics: "Reports and outcomes",
+  settings: "Settings",
+};
+
+let brand: CustomerBrand = { organization_name: "Safest Resolve", logo_url: "", logo_alt: "" };
+let expired = false;
+let started = false;
+
+function element(id: "login" | "workspace"): HTMLElement | null {
+  return document.querySelector<HTMLElement>(`#${id}`);
+}
+
+function readable(value: string): string {
+  const copy = value.replaceAll("_", " ");
+  if (!copy) return "";
+  const sentence = `${copy.charAt(0).toUpperCase()}${copy.slice(1)}`;
+  const acronyms: Record<string, string> = { ai: "AI", api: "API", csv: "CSV", d1: "D1", http: "HTTP", https: "HTTPS", id: "ID", json: "JSON", r2: "R2", sla: "SLA", url: "URL" };
+  return sentence.replace(/\b(ai|api|csv|d1|http|https|id|json|r2|sla|url)\b/giu, (match) => acronyms[match.toLowerCase()] ?? match);
+}
+
+function setWorkspaceMode(authenticated: boolean): void {
+  document.body.classList.toggle("workspace-mode", authenticated);
+  document.body.classList.toggle("login-mode", !authenticated);
+  document.body.classList.remove("mobile-navigation-open", "report-open");
+  window.scrollTo({ top: 0, left: 0, behavior: "auto" });
+}
+
+function showWorkspace(authenticated: boolean): void {
+  const login = element("login");
+  const workspace = element("workspace");
+  if (login) login.hidden = authenticated;
+  if (workspace) workspace.hidden = !authenticated;
+  setWorkspaceMode(authenticated);
+  if (!authenticated) setDocumentTitle("command");
+}
+
+function allowedViews(session: ConsoleSession): Set<WorkspaceView> {
+  return new Set(visibleNavigationGroups(session).flatMap((group) => group.items.map((item) => item.view)));
+}
+
+function setDocumentTitle(view: WorkspaceView): void {
+  const suffix = getShellSnapshot().session ? viewTitles[view] || readable(view) : "Reports and workflows";
+  document.title = `${brand.organization_name || "Safest Resolve"} — ${suffix}`;
+}
+
+function setView(requested: string): void {
+  const snapshot = getShellSnapshot();
+  const session = snapshot.session;
+  if (!session) return;
+  const available = [...document.querySelectorAll<HTMLElement>("[data-view]")];
+  const allowed = allowedViews(session);
+  const requestedView = requested as WorkspaceView;
+  const selected: WorkspaceView = allowed.has(requestedView) && available.some((section) => section.dataset.view === requestedView)
+    ? requestedView
+    : "command";
+  for (const section of available) section.hidden = section.dataset.view !== selected;
+  if (window.location.hash !== `#${selected}`) history.replaceState(null, "", `#${selected}`);
+  setShellSnapshot((current) => ({ ...current, currentView: selected }));
+  setDocumentTitle(selected);
+}
+
+function expireWorkspaceSession(message = ""): void {
+  if (expired && !getShellSnapshot().session) return;
+  expired = true;
+  setShellSnapshot((snapshot) => ({ ...snapshot, session: null, configuration: null, currentView: "command", reportCount: 0 }));
+  showWorkspace(false);
+  if (message) window.dispatchEvent(new CustomEvent(authEvents.error, { detail: { message } }));
+  else window.dispatchEvent(new Event(authEvents.focusEmail));
+}
+
+async function openWorkspace(destination?: WorkspaceView, silent = false): Promise<void> {
+  try {
+    const response = await requestJson<SessionResponse>("/v1/admin/session");
+    expired = false;
+    setShellSnapshot((snapshot) => ({
+      ...snapshot,
+      session: response.session,
+      configuration: response.configuration ?? null,
+      reportCount: 0,
+    }));
+    showWorkspace(true);
+    const hashView = window.location.hash.slice(1);
+    setView(destination || (hashView && hashView !== "invite" ? hashView : "command"));
+  } catch (cause) {
+    expireWorkspaceSession(silent ? "" : errorMessage(cause, "Authentication failed."));
+  }
+}
+
+async function checkHealth(): Promise<void> {
+  let status: ShellHealthStatus = "ready";
+  let label = "Durable storage ready";
+  try {
+    await requestJson("/health");
+  } catch {
+    status = "failed";
+    label = "Storage unavailable";
+  }
+  setShellSnapshot((snapshot) => ({ ...snapshot, health: { status, label } }));
+}
+
+async function signOut(): Promise<void> {
+  try { await requestJson("/v1/auth/logout", { method: "POST" }); } catch { /* Local state is still cleared. */ }
+  expired = false;
+  sessionStorage.setItem("safest-reports-force-login", "true");
+  setShellSnapshot((snapshot) => ({ ...snapshot, session: null, configuration: null, currentView: "command", reportCount: 0 }));
+  showWorkspace(false);
+  window.dispatchEvent(new Event(authEvents.focusEmail));
+}
+
+async function initialize(): Promise<void> {
+  try {
+    brand = await window.SafestBrand?.loadBrand("/v1/brand", { title: "Reports and workflows" }) || brand;
+  } catch {
+    brand = window.SafestBrand?.defaults || brand;
+  }
+  await checkHealth();
+  const parameters = new URLSearchParams(window.location.hash.slice(1));
+  if (parameters.has("invite") || parameters.has("reset")) return;
+  if (sessionStorage.getItem("safest-reports-force-login") !== "true") {
+    await openWorkspace(undefined, !hasSessionCredentials());
+  } else {
+    showWorkspace(false);
+    window.dispatchEvent(new Event(authEvents.focusEmail));
+  }
+}
+
+export function startShellController(): void {
+  if (started) return;
+  started = true;
+  window.addEventListener("safest-brand-applied", (event) => {
+    if (!(event instanceof CustomEvent) || !event.detail?.brand) return;
+    brand = { ...brand, ...(event.detail.brand as CustomerBrand) };
+    setDocumentTitle(getShellSnapshot().currentView);
+  });
+  window.addEventListener(authEvents.authenticated, (event) => {
+    const destination = event instanceof CustomEvent && event.detail?.destination === "profile" ? "profile" : undefined;
+    void openWorkspace(destination);
+  });
+  window.addEventListener("safest:auth:expired", (event) => {
+    const message = event instanceof CustomEvent && typeof event.detail?.message === "string"
+      ? event.detail.message
+      : "Your session expired. Sign in again.";
+    expireWorkspaceSession(message);
+  });
+  window.addEventListener(shellEvents.signOut, () => { void signOut(); });
+  window.addEventListener(shellEvents.navigate, (event) => {
+    const view = event instanceof CustomEvent && typeof event.detail?.view === "string" ? event.detail.view : "command";
+    setView(view);
+    if (view === "assistant") window.dispatchEvent(new Event("safest:assistant:focus"));
+  });
+  window.addEventListener("keydown", (event) => {
+    if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k" && getShellSnapshot().session?.permissions.useAssistant) {
+      event.preventDefault();
+      setView("assistant");
+      window.dispatchEvent(new Event("safest:assistant:focus"));
+    }
+  });
+  window.addEventListener("hashchange", () => {
+    if (getShellSnapshot().session && !window.location.hash.startsWith("#invite=")) setView(window.location.hash.slice(1) || "reports");
+  });
+  void initialize();
+}

package/template/console/shell/events.ts

@@ -0,0 +1,25 @@
+import type { ShellSnapshot, WorkspaceView } from "./types";
+
+export const shellEvents = {
+  state: "safest:shell:state",
+  navigate: "safest:shell:navigate",
+  signOut: "safest:shell:sign-out",
+} as const;
+
+export function dispatchNavigation(view: WorkspaceView): void {
+  window.dispatchEvent(new CustomEvent(shellEvents.navigate, { detail: { view } }));
+}
+
+export function dispatchSignOut(): void {
+  window.dispatchEvent(new Event(shellEvents.signOut));
+}
+
+export function isShellSnapshot(value: unknown): value is ShellSnapshot {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Partial<ShellSnapshot>;
+  return (candidate.session === null || typeof candidate.session === "object")
+    && typeof candidate.currentView === "string"
+    && typeof candidate.reportCount === "number"
+    && typeof candidate.health?.status === "string"
+    && typeof candidate.health?.label === "string";
+}