@corbet-labs/ccht 0.1.0 → 0.2.2

package/README.md

@@ -1,185 +1,216 @@
-# ccht
+# @corbet-labs/ccht
 
-Reusable conversations for Rust applications, terminals and web frontends.
-**ccht** keeps the conversation model in Rust and compiles
-that same model to Wasm. Native hosts connect to installed agents using the
-[official ACP Rust SDK](https://github.com/agentclientprotocol/rust-sdk).
+Reusable conversations for your applications, powered by the shared Rust/Wasm model.
 
-```text
-Web UI ── @corbet-labs/ccht (Wasm) ── application transport/storage
-                                              │
-TUI / native UI ── ccht::Conversation ── ccht::native ── upstream ACP agent
+The root entry (`createConversation`) owns the conversation state machine. The
+`./auth` entry adds typed auth/challenge models mirroring `ccht::auth`, the
+`./dock` entry adds framework-free dock state, and
+`./components/AccountConnection.svelte` adds the first shared Svelte 5 account
+connector alongside the generic `./components/Dock.svelte` edge rail. All
+entries are product-neutral: no product names, prompts, or
+pricing appear in this package.
+
+```js
+import { createConversation } from '@corbet-labs/ccht';
+import { isAuthenticated, validateChallenge } from '@corbet-labs/ccht/auth';
+import { createDockManager, validateDockId } from '@corbet-labs/ccht/dock';
+import AccountConnection from '@corbet-labs/ccht/components/AccountConnection.svelte';
+import Dock from '@corbet-labs/ccht/components/Dock.svelte';
 ```
 
-The library owns structured conversation events, ordered replay, native sessions,
-streaming, cancellation and permission requests. Your application owns its UI,
-instructions, context, tools, user authorization, storage and HTTP/WebSocket/SSE
-transport. No Corbet-specific prompts or database are required.
+The Svelte component ships as source and needs `svelte` `^5` (a peer
+dependency). It has no other dependencies and imports no CSS framework.
 
-Agent reasoning, tools, authentication and protocol translation remain upstream.
-ccht does not implement an agent loop, read provider credentials, install agents,
-call paid model HTTP APIs or select an API-key fallback.
+## What is shared vs what the app owns
 
-## Rust
+Shared (this package):
 
-```toml
-[dependencies]
-ccht = "0.1"
-tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
-```
+- Conversation state and ordered event replay (Wasm `ConversationModel`).
+- Auth/challenge types and validators (`AuthState`, `Challenge`,
+  `CredentialsProvider`).
+- Presentational account connector markup with stable styling hooks.
 
-`native` is the default feature. For the portable model alone:
+Owned by the embedding application:
 
-```toml
-ccht = { version = "0.1", default-features = false }
-```
+- Transport: delivering `WireEvent`s (HTTP/WebSocket/SSE), serving the Wasm
+  bytes, and polling login operations until they complete.
+- Effects: spawning agents, starting or cancelling logins, signing out. These
+  never run in browser library code; the component drives them through
+  app-supplied async callbacks and the app backend does the work.
+- Storage: where credentials persist (OS keychain natively, origin-scoped
+  browser storage on the web). The library defines the interface only.
+- Product copy: account labels, help text, links, and error wording beyond the
+  component's generic strings.
 
-```rust
-use ccht::{Conversation, Event, WireEvent, acp};
-
-let mut conversation = Conversation::new("workspace/creator");
-conversation.apply(WireEvent::new(
-    "workspace/creator", "turn-1", 1,
-    Event::Update {
-        update: acp::SessionUpdate::AgentMessageChunk(
-            acp::ContentChunk::new("Hello".into()),
-        ),
-    },
-)).unwrap();
-assert_eq!(conversation.turns()[0].text, "Hello");
-```
+Rule: browser code in this package never spawns agents, performs network I/O,
+or holds ambient authority. Service keys are explicit strings passed by the
+app, and secrets are opaque bytes that are never logged.
 
-[examples/native.rs](source/examples/native.rs) shows streaming from an explicitly
-supplied installed ACP executable. It requires native agent authentication already
-configured by the operator. Use `codex-acp`, `claude-agent-acp`, or `opencode acp`
-as separate, reviewed runtime installations. Generic ACP executables also work.
-No agent/runtime is bundled in the crate or browser package.
-
-`NativeClient::connect` initializes the protocol. Create a session with its working
-directory, explicit model (if desired) and application MCP servers. Take the event
-receiver before prompting and consume it concurrently with the prompt future.
-A session accepts one active prompt; another returns `Busy`. Different sessions
-have separate streams and permission identities. History load/resume and model
-selection require the agent's advertised capabilities; unsupported requests fail.
-
-Permissions default to denial. Applications that opt into asking must render the
-request, check their authority and respond with one of the advertised choices.
-A permission callback is not a sandbox: agent-owned tools may have separate runtime
-policy. Configure filesystem/network confinement in the host for your use case.
-ccht advertises no client filesystem or terminal capabilities.
-
-Cancellation asks the upstream agent to stop. If it does not stop within the
-configured shutdown timeout, ccht closes the SDK connection, affecting **all**
-sessions on that connection. Dropping an active prompt also closes its connection.
-Use one connection per independent workload when cancellation must be isolated.
-Bounded event channels fail explicitly on an unresponsive consumer.
-
-`AgentCommand::with_working_directory` sets the actual agent startup directory
-using installed Linux/macOS `env` launchers. Windows currently reports this helper
-as unsupported because the SDK launch configuration lacks a startup-directory
-field. Session cwd alone does not constrain files read during agent startup.
-Linux is covered by process-level tests; macOS support is source-reviewed.
-
-ACP enables `serde_json`'s `preserve_order` feature through Cargo feature
-unification. Applications that hash or sign JSON must explicitly canonicalize
-object keys; depending on a `Value` map's incidental iteration order is unsafe.
-
-## Browser
-
-```sh
-npm install @corbet-labs/ccht
-```
+## Auth entry (`@corbet-labs/ccht/auth`)
 
-```js
-import { createConversation } from '@corbet-labs/ccht';
-// Vite example: emit the Wasm as a separately replaceable asset.
-import wasmUrl from '@corbet-labs/ccht/ccht_bg.wasm?url';
-
-const conversation = await createConversation('workspace/creator', { wasm: wasmUrl });
-// After your authenticated application transport delivers a ccht WireEvent:
-const snapshot = conversation.applyEvent(event);
-render(snapshot.turns);
-// When the view is destroyed:
-conversation.free();
-```
+Plain types and functions, no DOM access.
 
-Without an explicit `wasm` option, initialization loads `wasm/ccht_bg.wasm`
-relative to the generated module. A browser cannot launch native processes: its
-application server or desktop host runs `ccht::native`. The package makes no
-network connection apart from loading its Wasm module. The host decides which
-backend is available and how users authenticate to the application.
-
-## Event and persistence contract
-
-`WireEvent` version 1 contains `conversation_id`, `request_id`, a per-request
-`sequence` starting at 1, and `event`. Retain the original structured ACP updates:
-text, non-text content, tool calls, thought chunks, plans, permissions and errors
-are distinct. The model returns a serializable snapshot for your renderer.
-
-Assign identities and sequences on a trusted application host. Never let a browser
-select another user's conversation without server-side authorization. Sequence
-numbers are **not** SSE cursors or database row IDs. The app stores its own event
-log and replays each request in order. Already-applied sequences are ignored;
-gaps, a different conversation, malformed events and new events after completion
-fail without mutating state. Delivery identity must not be reused for another turn.
-
-A model holds at most 256 turns, 8 MiB per turn and 1 MiB per event. Applications
-should page long histories into separate models and limit streamed inputs before
-parsing them. Durable transcript storage and reconnection are application concerns;
-a serialized snapshot is a render result, not a native-agent session checkpoint.
-
-Namer is the first integration: Creator/Critic have independent conversation
-scopes, durable application events, authenticated SSE and cancellation. Its queue
-uses a fresh native session per turn with bounded role history supplied by Namer.
-CareerVector's TUI reuses the native session API while keeping CV tools, prompts
-and revision checks in its own code. Explicit local inference can emit the same
-`WireEvent` contract through an application-owned backend.
-
-## Building the Wasm package
-
-Use Rust with `wasm32-unknown-unknown` installed. The checked-in generator uses the
-same exact `wasm-bindgen` version as the Rust crate; no global Wasm CLI is required.
-
-```sh
-cargo build --locked --release --no-default-features --features web --target wasm32-unknown-unknown
-cargo run --locked --release -p ccht-wasm-bundle -- target/wasm32-unknown-unknown/release/ccht.wasm web/wasm
-```
+`AuthState` mirrors the Rust `snake_case` JSON byte-for-byte:
+
+| Rust | JSON | TypeScript |
+| --- | --- | --- |
+| `Unknown` | `"unknown"` | `'unknown'` |
+| `Unauthenticated` | `"unauthenticated"` | `'unauthenticated'` |
+| `Authenticated { account }` | `{"authenticated": {"account": "…"}}` | `{ authenticated: { account?: string \| null } }` |
 
-Published browser archives include the corresponding Rust source and generator
-under `source/`, original notices, and the full locked dependency sources in
-`source/dependencies.tar.gz`. Cargo's vendor checksums are preserved inside that
-archive. To rebuild from the distributed package, extract it inside `source/`:
+Helpers: `isAuthenticated(state)` mirrors `AuthState::authenticated`,
+`authAccount(state)` returns the display-only label (or null), and
+`parseAuthState(value)` / `isAuthState(value)` validate decoded JSON. The
+label is provenance for the UI, never an authentication proof.
 
-```sh
-cd source
-tar -xzf dependencies.tar.gz
-cargo build --locked --offline --release --no-default-features --features web --target wasm32-unknown-unknown
-cargo run --locked --offline --release -p ccht-wasm-bundle -- target/wasm32-unknown-unknown/release/ccht.wasm ../wasm
+`Challenge` is `{ verification_url, user_code }`. The backend issues it, pins
+any provider-specific endpoint, and polls for completion; the browser only
+renders a validated challenge. `validateChallenge(value)` accepts an `https:`
+URL with a host (no embedded credentials) and a non-empty code of up to 64
+ASCII alphanumeric or `-` characters. It never throws, so callers can gate
+rendering on it. The component validates internally and renders waiting text
+for a missing or malformed challenge instead of an unvalidated link.
+
+`CredentialsProvider` mirrors the Rust trait with JS method names:
+
+```ts
+interface CredentialsProvider {
+  readCredentials(service: string): Promise<Credential | null>;
+  writeCredentials(service: string, credential: Credential): Promise<void>;
+  deleteCredentials(service: string): Promise<void>;
+}
 ```
 
-The supplied `.cargo/config.toml` uses only those vendored sources. The installed
-Rust toolchain must include the Wasm target and linker. CI rebuilds this kit with
-an empty Cargo cache and tests the replacement module through the same npm API.
-Keep that exported interface compatible when replacing the library.
-
-CI verifies the portable Rust model, actual Wasm compilation and packaged Node
-consumer, native protocol/process fixtures, dependency notices and an independent
-Rust crate consumer. Native fixtures do not call a model or access an account.
-Live runtime support must additionally be checked against the installed agent,
-its advertised capabilities, login state and execution policy.
-
-## License
-
-ccht is **LGPL-3.0-only**. See [LICENSE.md](LICENSE.md) and
-[THIRD-PARTY.md](THIRD-PARTY.md). Applications may use different licenses while
-preserving the LGPL library rights. Distributing a combined Rust binary requires
-a compliant relinking route; making source available somewhere is not by itself
-sufficient. Keep the browser's Wasm replaceable and provide its corresponding
-source and notices. Review the complete license for your distribution method.
-
-ACP and an account's subscription do not guarantee a billing mode. The operator
-must configure the native agent/account and disable unwanted paid usage. Known
-ambient API-key variables are cleared at launch and explicit API-key overrides
-are rejected, but ccht cannot attest saved agent credentials or account billing
-settings. Native runtimes and hosted services retain their own terms; a library
-license does not authorize pooling subscriptions or product-specific login flows.
+`Credential` is `{ account: string; secret: Uint8Array }`. Encode at the app
+boundary (`TextEncoder`/base64) when the store needs text. Service keys are
+app-defined (for example `assistant-login:<provider>`); deleting a missing
+entry succeeds, and a rejected promise signals store failure. There is no
+environment-variable override on the web: the store alone decides, matching
+the documented `ApiKeyState` behavior on Wasm.
+
+## Component (`AccountConnection.svelte`)
+
+Svelte 5 runes. Props:
+
+| Prop | Type | Meaning |
+| --- | --- | --- |
+| `account` | `{ id: string; label: string; kind: 'chatgpt' \| 'opencode_go' \| string }` | Product-neutral identity. Known kinds select the ceremony; unknown kinds fall back to a generic sign-in button. |
+| `state` | `AuthState` | Observed login state (defaults to `'unknown'`). |
+| `busy` | `boolean` | An app-owned operation is in flight; actions disable, cancel shows. |
+| `challenge` | `Challenge \| null` (optional) | Device-code challenge supplied by the app after `onStart` starts polling. |
+| `onStart` | `() => void \| Promise<void>` | Begin the login ceremony (for example start a device flow). |
+| `onCancel` | `() => void \| Promise<void>` | Abort the in-flight operation; also backs Disconnect when `onDisconnect` is omitted. |
+| `onKeySubmit` | `(key: string) => void \| Promise<void>` | Persist a trimmed account key (minimum 8 characters). |
+| `onDisconnect` | optional | Sign out when authenticated. Falls back to `onCancel`, which can branch on app state. |
+
+Rendering:
+
+- Unauthenticated `chatgpt`: sign-in button, then waiting text while `busy`,
+  then the device-code view (code, copy button, sign-in link) once a valid
+  `challenge` arrives. The copy button opens the link during the click (so
+  popup blockers do not trigger) and falls back to a manual-copy message when
+  the clipboard API is unavailable.
+- Unauthenticated `opencode_go`: password key form that clears on submit.
+- Authenticated: connection status with the account label (when known) and a
+  Disconnect button.
+- `unknown` state: neutral checking text with no ceremony buttons.
+
+Callbacks are fire-and-forget from the component's view: the app must handle
+its own failures and surface them through its own operation state, which it
+renders outside the component. Callback rejections are therefore ignored here
+by design.
+
+Accessibility: semantic `section`/`form`/`label`/`button` elements, an
+`aria-label` naming the account connection, `role="status"` for status lines,
+an `aria-live="polite"` region announcing challenge arrival, and
+`role="alert"` for the clipboard fallback. The key input is labelled,
+password-masked, and non-persistent.
+
+## Dock entry (`@corbet-labs/ccht/dock`) and component (`Dock.svelte`)
+
+Framework-free dock state plus a generic Svelte 5 edge rail. `DockKind`
+(`'chat' | 'config' | 'custom'`) classifies a dock and `Placement`
+(`'left' | 'right' | 'bottom' | 'inline'`) places it. The state module is
+plain TypeScript with no DOM access.
+
+`validateDockId(id)` returns an error message or null (never throws). Rules:
+a non-empty string of at most 64 ASCII `[a-z0-9-_]` characters.
+
+`createDockManager()` returns an independent manager:
+
+| Method | Meaning |
+| --- | --- |
+| `register(id, kind, placement)` | Register a closed dock. Throws the validation message for a malformed id, `DuplicateDock: <id>` for a repeat. |
+| `open(id)` / `close(id)` | Mark a dock open or closed. Unknown ids throw `UnknownDock: <id>`. |
+| `openWithFocus(id, token)` | Open a dock and stage an opaque focus token (non-empty string) for the app to consume. |
+| `toggle(id)` | Flip a dock's open state and return the new state. |
+| `isOpen(id)` | Whether a dock is open. |
+| `placement(id)` / `setPlacement(id, placement)` | Read or move a dock's placement. Invalid placements throw `invalid dock placement`. |
+| `openDocks()` | Ids of open docks, in registration order. |
+| `takeFocusToken()` | Take the staged focus token once, clearing it; null when none is staged. |
+| `closeAll()` | Mark every dock closed. |
+| `serialize()` | Persist `[{id, kind, placement, open}]` as JSON, in registration order. The focus token is never persisted. |
+| `restore(json)` | Replace all state from `serialize` output. Every entry is validated first, so a malformed snapshot (thrown as `invalid dock snapshot: …`) leaves current state untouched, and any staged focus token is cleared. |
+
+`Dock.svelte` renders one named dock as an edge rail for the `left` and
+`right` placements. Svelte 5 runes. Props:
+
+| Prop | Type | Meaning |
+| --- | --- | --- |
+| `side` | `'left' \| 'right'` | Which window edge the rail pins to. |
+| `title` | `string` | Panel heading and dialog label. |
+| `open` | `boolean` | App-owned visibility state. |
+| `onClose` | `() => void` | Close intent (tab is hidden while open; Esc key also closes). |
+| `onOpen` | `() => void` | Open intent from the edge tab button. |
+| `tabLabel` | `string` | Short tab caption. |
+| `tabSummary` | `string` (optional, defaults to `''`) | Detail shown in the tab button and panel head. |
+| `closeLabel` | optional `string` | Close button label (defaults to `Close {title}`). |
+| `panelId` | `string` | Panel element id, referenced by the tab's `aria-controls`. |
+| `children` | `Snippet` | Panel body content. |
+
+Rendering:
+
+- Closed: a fixed edge tab button (`aria-expanded="false"`,
+  `aria-controls={panelId}`, labelled `Open {title}: {tabSummary}` or
+  `Open {title}`). The panel stays mounted but hidden and inert.
+- Open: a `role="dialog"` panel with a head (`h2` title, summary paragraph,
+  Close button) and a body rendering `children`.
+- Opening moves focus to the first visible, enabled control in the panel
+  (or the panel itself); closing returns focus to the tab or the previously
+  focused element. Esc closes.
+- The `bottom` and `inline` placements are state-only: they persist and
+  restore through the manager but have no rail chrome here. Custom hosts
+  (for example a ratatui overlay or an inline sheet) render them.
+
+Stable classes: `ccht-dock-tab`, `ccht-dock-tab-text`, `ccht-dock-panel`,
+`ccht-dock-head`, `ccht-dock-title`, `ccht-dock-close`, `ccht-dock-body`.
+The tab and panel carry `data-side` (`left` / `right`) and the panel carries
+`data-open` (`true` / `false`).
+
+CSS variables (with fallbacks when unset): `--ccht-fg`, `--ccht-muted`,
+`--ccht-accent`, `--ccht-border`, `--ccht-panel-bg`, `--ccht-tab-bg`,
+`--ccht-tab-bg-hover`, `--ccht-fg-bright`.
+
+Rule: the app owns dock effects. The manager never persists, the component
+never fetches, spawns, or stores; visibility, persistence, and focus targets
+beyond the panel run through app callbacks and app-held state.
+
+## Styling hooks
+
+Unstyled-but-hooked markup: layout comes from the app, colors resolve through
+CSS custom properties with plain fallbacks. Stable classes:
+
+`ccht-account`, `ccht-status`, `ccht-hint`, `ccht-error`, `ccht-challenge`,
+`ccht-code`, `ccht-button`, `ccht-cancel`, `ccht-disconnect`, `ccht-link`,
+`ccht-keyform`, `ccht-label`, `ccht-input`.
+
+CSS variables (with fallbacks when unset): `--ccht-fg`, `--ccht-muted`,
+`--ccht-error`, `--ccht-accent`, `--ccht-code-bg`. Example:
+
+```css
+:root {
+  --ccht-muted: #a5b5cb;
+  --ccht-error: #fda4af;
+  --ccht-accent: #7bb8ff;
+}
+```

package/index.d.ts

@@ -35,13 +35,28 @@ export interface TurnState {
   stop_reason: string | null;
   error: { code: string; message: string } | null;
 }
-export interface ConversationSnapshot { conversation_id: string; turns: TurnState[] }
+export interface ConfigChoice { value: string; name: string; description?: string }
+export interface ConfigGroup { group: string; name: string; options: ConfigChoice[] }
+export type SessionConfigOption = {
+  id: string; name: string; description?: string; category?: string;
+} & ({ type: 'select'; currentValue: string; options: ConfigChoice[] | ConfigGroup[] }
+  | { type: 'boolean'; currentValue: boolean });
+export interface SessionConfiguration {
+  options: SessionConfigOption[];
+  modes: null | { currentModeId: string; availableModes: Array<{id: string; name: string; description?: string}> };
+}
+export interface ConversationSnapshot { conversation_id: string; turns: TurnState[]; configuration: SessionConfiguration }
 export interface Conversation {
   applyEvent(event: WireEvent | string): ConversationSnapshot;
   snapshot(): ConversationSnapshot;
   free(): void;
 }
-/** Transport/authentication and persistence belong to the embedding application. */
+/** Transport/authentication and persistence belong to the embedding application.
+ *
+ * Only the first call's `wasm` option initializes the shared module; later
+ * calls reuse it. `applyEvent` returns the fresh snapshot and throws on
+ * invalid, out-of-scope, gapped, terminal, or freed input. `free` is idempotent.
+ */
 export function createConversation(conversationId: string, options?: {
   wasm?: URL | string | Request | Response | BufferSource | WebAssembly.Module;
 }): Promise<Conversation>;

package/index.js

@@ -3,7 +3,14 @@ import initialize, { ConversationModel } from './wasm/ccht.js';
 
 let initialization;
 
-/** Initialize the shared Rust/Wasm model. Supply an explicit Wasm URL when bundling. */
+/** Initialize the shared Rust/Wasm model. Supply an explicit Wasm URL when bundling.
+ *
+ * Only the first call's `wasm` option initializes the shared module; later
+ * calls reuse it. The returned `applyEvent` applies one ordered event and
+ * returns the fresh snapshot (the underlying Rust boolean for "changed" is
+ * not exposed); it throws on invalid JSON, scope, gap, terminal, or freed
+ * state. `snapshot` returns the parsed render state and `free` is idempotent.
+ */
 export async function createConversation(conversationId, options = {}) {
   if (!initialization) {
     initialization = initialize(options.wasm === undefined ? undefined : { module_or_path: options.wasm })

package/package.json

@@ -1,36 +1,22 @@
 {
   "name": "@corbet-labs/ccht",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "description": "Reusable conversations for your applications, powered by the shared Rust/Wasm model",
-  "license": "LGPL-3.0-only",
+  "license": "LGPL-3.0-only WITH LGPL-3.0-linking-exception",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
   "exports": {
-    ".": {
-      "types": "./index.d.ts",
-      "import": "./index.js"
-    },
+    ".": { "types": "./index.d.ts", "import": "./index.js" },
+    "./auth": { "types": "./src/auth.ts", "import": "./src/auth.ts" },
+    "./dock": { "types": "./src/dock.ts", "import": "./src/dock.ts" },
+    "./components/AccountConnection.svelte": "./src/components/AccountConnection.svelte",
+    "./components/Dock.svelte": "./src/components/Dock.svelte",
     "./ccht_bg.wasm": "./wasm/ccht_bg.wasm"
   },
-  "files": [
-    "index.js",
-    "index.d.ts",
-    "wasm/",
-    "source/",
-    "LICENSE",
-    "LICENSE.md",
-    "LICENSES/",
-    "README.md",
-    "THIRD-PARTY.md"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/corbet-labs/ccht.git"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "sideEffects": false,
-  "gitHead": "340b9c2d41c77c2c1448666ddad8cd28307517bd"
+  "files": ["index.js", "index.d.ts", "src/", "wasm/", "source/", "LICENSE", "LICENSE.md", "LICENSES/", "README.md", "THIRD-PARTY.md"],
+  "repository": { "type": "git", "url": "git+https://github.com/corbet-labs/ccht.git" },
+  "publishConfig": { "access": "public" },
+  "peerDependencies": { "svelte": "^5" },
+  "sideEffects": false
 }

package/src/auth.ts

@@ -0,0 +1,149 @@
+/** Typed mirrors of the Rust auth surface (`ccht::auth`) for web consumers.
+ *
+ * The conversation model stays in Rust/Wasm; these types only describe *who*
+ * may act. Transport, login ceremonies, credential storage, polling and
+ * product copy belong to the embedding application. Nothing here touches the
+ * DOM, performs network I/O, or spawns processes: effects run in the
+ * application backend and reach the browser through app-supplied async
+ * callbacks and explicit service keys.
+ */
+
+/** Login state of one provider, mirroring `ccht::auth::AuthState`.
+ *
+ * The shape round-trips the Rust `snake_case` JSON byte-for-byte, so a state
+ * serialized by Rust deserializes here and vice versa:
+ * - `Unknown` becomes the string `"unknown"`.
+ * - `Unauthenticated` becomes the string `"unauthenticated"`.
+ * - `Authenticated { account }` becomes `{"authenticated": {"account": ...}}`,
+ *   where `account` is a display-only label (string), `null`, or absent.
+ *   The label is provenance for the UI and never an authentication proof.
+ */
+export type AuthState = 'unknown' | 'unauthenticated' | { authenticated: { account?: string | null } };
+
+/** Whether routine work may proceed without prompting for login first. Mirrors `AuthState::authenticated`. */
+export function isAuthenticated(state: AuthState): boolean {
+  return typeof state === 'object' && state !== null && 'authenticated' in state;
+}
+
+/** Display-only account label (username, email, or subscription name), or null when absent. Never a secret. */
+export function authAccount(state: AuthState): string | null {
+  if (typeof state === 'object' && state !== null && 'authenticated' in state) {
+    return state.authenticated.account ?? null;
+  }
+  return null;
+}
+
+/** Whether a decoded JSON value has the exact Rust `AuthState` shape. Unknown fields inside the inner object are ignored, matching serde's default. */
+export function isAuthState(value: unknown): value is AuthState {
+  try {
+    parseAuthState(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Validate a decoded JSON value as the Rust `AuthState` shape. Throws a `TypeError` when the shape differs. */
+export function parseAuthState(value: unknown): AuthState {
+  if (value === 'unknown' || value === 'unauthenticated') {
+    return value;
+  }
+  if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    const keys = Object.keys(value);
+    if (keys.length === 1 && keys[0] === 'authenticated') {
+      const inner = (value as { authenticated: unknown }).authenticated;
+      if (typeof inner === 'object' && inner !== null && !Array.isArray(inner)) {
+        const account = (inner as { account?: unknown }).account;
+        if (account === undefined) {
+          return { authenticated: {} };
+        }
+        if (account === null || typeof account === 'string') {
+          return { authenticated: { account } };
+        }
+      }
+    }
+  }
+  throw new TypeError('invalid AuthState');
+}
+
+/** Device-code challenge as exchanged during a provider login ceremony.
+ *
+ * Field names stay `snake_case` to match the wire format applications pass
+ * between their backend and the browser. The backend remains authoritative:
+ * it issues the challenge, pins any provider-specific endpoint, and polls
+ * for completion. The browser only displays a validated challenge and never
+ * invents one.
+ */
+export interface Challenge {
+  verification_url: string;
+  user_code: string;
+}
+
+const CHALLENGE_CODE_PATTERN = /^[A-Za-z0-9-]+$/;
+const CHALLENGE_CODE_MAX_LENGTH = 64;
+
+/** Whether a value is a renderable device-code challenge.
+ *
+ * Accepts any `https:` URL with a host (applications may narrow this
+ * further, for example by pinning the provider's device endpoint) and a
+ * non-empty code of up to 64 ASCII alphanumeric or `-` characters. URLs with
+ * embedded credentials are rejected. Never throws; validate before rendering
+ * a challenge as a link or code.
+ */
+export function validateChallenge(value: unknown): value is Challenge {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const { verification_url, user_code } = value as Record<string, unknown>;
+  if (typeof verification_url !== 'string' || typeof user_code !== 'string') {
+    return false;
+  }
+  if (user_code.length < 1 || user_code.length > CHALLENGE_CODE_MAX_LENGTH) {
+    return false;
+  }
+  if (!CHALLENGE_CODE_PATTERN.test(user_code)) {
+    return false;
+  }
+  let url: URL;
+  try {
+    url = new URL(verification_url);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== 'https:' || url.hostname === '') {
+    return false;
+  }
+  if (url.username !== '' || url.password !== '') {
+    return false;
+  }
+  return true;
+}
+
+/** Opaque credential, mirroring `ccht::auth::Credential`.
+ *
+ * Stores treat both fields as opaque. `account` is display-only; `secret`
+ * holds the raw secret bytes. Encode at the application boundary (for
+ * example with `TextEncoder` or base64) when the backing store needs text,
+ * and never write secrets to logs, errors, or fixtures.
+ */
+export interface Credential {
+  account: string;
+  secret: Uint8Array;
+}
+
+/** Application-supplied credential persistence, mirroring `ccht::auth::CredentialsProvider`.
+ *
+ * One method triple per service key. Service keys are application-defined
+ * opaque strings (never ambient authority); native applications back this
+ * with the OS keychain and web applications with origin-scoped browser
+ * storage. Removing a missing entry succeeds. Implementations reject the
+ * promise when the backing store fails.
+ */
+export interface CredentialsProvider {
+  /** Read stored credentials, if any, for a service key. */
+  readCredentials(service: string): Promise<Credential | null>;
+  /** Persist credentials for a service key, replacing any previous entry. */
+  writeCredentials(service: string, credential: Credential): Promise<void>;
+  /** Remove stored credentials for a service key. Missing entries are not an error. */
+  deleteCredentials(service: string): Promise<void>;
+}