@corbet-labs/ccht 0.2.0 → 0.2.3

package/source/src/transport.rs

@@ -0,0 +1,330 @@
+//! Transport abstraction for ACP-style JSON-RPC.
+//!
+//! The same event contract can travel over a native stdio pipe or over a
+//! socket used by a Wasm bridge. This module only describes and validates
+//! endpoints; it never connects, spawns processes, or performs network I/O.
+//!
+//! Validation is offline and never echoes addresses or credentials: error
+//! messages use fixed text so secrets cannot leak through [`TransportError`].
+
+/// How an ACP-style endpoint is reached.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TransportKind {
+    /// A child process speaking JSON-RPC over stdin and stdout.
+    Stdio,
+    /// A socket endpoint (`ws`/`wss`/`http`/`https`) used by a bridge.
+    Socket,
+}
+
+/// A validated endpoint description for ACP-style JSON-RPC.
+///
+/// Implementors must be sendable across threads; validation is offline only
+/// and performs no connecting or process spawning.
+pub trait Transport: Send {
+    /// Which mechanism this endpoint uses.
+    fn kind(&self) -> TransportKind;
+    /// Non-sensitive hint for logs or UI, without credentials.
+    fn address_hint(&self) -> Option<String>;
+    /// Check endpoint shape without connecting or spawning.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TransportError`] when the endpoint shape is invalid.
+    fn validate(&self) -> Result<(), TransportError>;
+}
+
+/// Transport validation failure without sensitive data.
+///
+/// Messages are fixed strings; they never echo programs, URLs, or tokens.
+#[derive(Debug, Clone, thiserror::Error, PartialEq, Eq)]
+pub enum TransportError {
+    /// The endpoint address shape is invalid.
+    #[error("invalid transport address: {0}")]
+    InvalidAddress(&'static str),
+    /// This transport kind is not supported in the current context.
+    #[error("unsupported transport: {0}")]
+    Unsupported(&'static str),
+    /// The transport is already closed.
+    #[error("transport is closed")]
+    Closed,
+}
+
+/// Stdio endpoint: an explicit program plus arguments.
+///
+/// No shell parsing is involved; the program must be non-empty.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct StdioTransport {
+    /// Explicit executable path or name; never a shell string.
+    pub program: String,
+    /// Arguments passed directly to the executable.
+    pub args: Vec<String>,
+}
+
+impl StdioTransport {
+    /// Create a stdio endpoint with an explicit program and arguments.
+    pub fn new(program: impl Into<String>, args: Vec<String>) -> Self {
+        Self {
+            program: program.into(),
+            args,
+        }
+    }
+}
+
+impl Transport for StdioTransport {
+    /// Report [`TransportKind::Stdio`].
+    fn kind(&self) -> TransportKind {
+        TransportKind::Stdio
+    }
+
+    /// The program name when non-empty, without arguments.
+    fn address_hint(&self) -> Option<String> {
+        let program = self.program.trim();
+        if program.is_empty() {
+            None
+        } else {
+            Some(program.to_owned())
+        }
+    }
+
+    /// Require a non-empty program; arguments need no validation.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TransportError::InvalidAddress`] when the program is empty.
+    fn validate(&self) -> Result<(), TransportError> {
+        if self.program.trim().is_empty() {
+            return Err(TransportError::InvalidAddress(
+                "stdio program must not be empty",
+            ));
+        }
+        Ok(())
+    }
+}
+
+/// Socket endpoint: a URL string validated offline, never dialed.
+///
+/// Accepted schemes are `ws`, `wss`, `http`, and `https` with a non-empty
+/// host. Validation checks shape only and never connects.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SocketTransport {
+    /// Endpoint URL; validated for shape only, never connected.
+    pub url: String,
+}
+
+impl SocketTransport {
+    /// Create a socket endpoint; call [`Transport::validate`] to check shape.
+    pub fn new(url: impl Into<String>) -> Self {
+        Self { url: url.into() }
+    }
+}
+
+impl Transport for SocketTransport {
+    /// Report [`TransportKind::Socket`].
+    fn kind(&self) -> TransportKind {
+        TransportKind::Socket
+    }
+
+    /// The URL when non-empty; callers must redact userinfo before display
+    /// when the URL may carry credentials.
+    fn address_hint(&self) -> Option<String> {
+        if self.url.trim().is_empty() {
+            None
+        } else {
+            Some(self.url.clone())
+        }
+    }
+
+    /// Validate scheme and host presence without connecting.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TransportError::InvalidAddress`] when the scheme is not
+    /// `ws`/`wss`/`http`/`https` or when no host is present.
+    fn validate(&self) -> Result<(), TransportError> {
+        validate_socket_url(&self.url)
+    }
+}
+
+/// Check socket URL shape without connecting or echoing the URL in errors.
+fn validate_socket_url(url: &str) -> Result<(), TransportError> {
+    if url.trim().is_empty() {
+        return Err(TransportError::InvalidAddress(
+            "socket url must not be empty",
+        ));
+    }
+    if url != url.trim() || url.chars().any(char::is_whitespace) {
+        return Err(TransportError::InvalidAddress(
+            "socket url must not contain whitespace",
+        ));
+    }
+    let Some((scheme, rest)) = url.split_once("://") else {
+        return Err(TransportError::InvalidAddress(
+            "socket url must include a scheme",
+        ));
+    };
+    match scheme.to_ascii_lowercase().as_str() {
+        "ws" | "wss" | "http" | "https" => {}
+        _ => {
+            return Err(TransportError::InvalidAddress(
+                "socket url scheme must be ws, wss, http, or https",
+            ));
+        }
+    }
+    if rest.is_empty() {
+        return Err(TransportError::InvalidAddress(
+            "socket url must include a host",
+        ));
+    }
+    let authority = rest.split(['/', '?', '#']).next().unwrap_or("");
+    if authority.is_empty() {
+        return Err(TransportError::InvalidAddress(
+            "socket url must include a host",
+        ));
+    }
+    let host_port = authority.rsplit('@').next().unwrap_or("");
+    let host = if let Some(bracketed) = host_port.strip_prefix('[') {
+        let Some(end) = bracketed.find(']') else {
+            return Err(TransportError::InvalidAddress(
+                "socket url must include a host",
+            ));
+        };
+        &bracketed[..end]
+    } else {
+        host_port.split(':').next().unwrap_or("")
+    };
+    if host.is_empty() {
+        return Err(TransportError::InvalidAddress(
+            "socket url must include a host",
+        ));
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn assert_send<T: Send>() {}
+
+    #[test]
+    fn transports_are_send() {
+        assert_send::<StdioTransport>();
+        assert_send::<SocketTransport>();
+        assert_send::<TransportKind>();
+        assert_send::<TransportError>();
+    }
+
+    #[test]
+    fn stdio_accepts_explicit_program() {
+        let transport = StdioTransport::new("agent", vec!["--flag".into()]);
+        assert_eq!(transport.kind(), TransportKind::Stdio);
+        assert_eq!(transport.address_hint().as_deref(), Some("agent"));
+        transport.validate().unwrap();
+    }
+
+    #[test]
+    fn stdio_rejects_empty_program() {
+        for program in ["", "   ", "\t\n"] {
+            let transport = StdioTransport::new(program, Vec::new());
+            assert_eq!(transport.address_hint(), None);
+            assert_eq!(
+                transport.validate().unwrap_err(),
+                TransportError::InvalidAddress("stdio program must not be empty")
+            );
+        }
+    }
+
+    #[test]
+    fn socket_accepts_supported_schemes_with_host() {
+        for url in [
+            "ws://bridge.local/session",
+            "wss://bridge.example.com:443/session",
+            "http://localhost:8080/bridge",
+            "https://example.com",
+            "ws://127.0.0.1:9000",
+            "wss://[::1]:9000/session",
+            "https://example.com/path?query=1#fragment",
+        ] {
+            let transport = SocketTransport::new(url);
+            assert_eq!(transport.kind(), TransportKind::Socket);
+            assert_eq!(transport.address_hint().as_deref(), Some(url));
+            transport.validate().unwrap();
+        }
+    }
+
+    #[test]
+    fn socket_scheme_match_is_case_insensitive() {
+        SocketTransport::new("WSS://bridge.example.com/session")
+            .validate()
+            .unwrap();
+    }
+
+    #[test]
+    fn socket_rejects_missing_or_unsupported_address() {
+        for url in [
+            "",
+            "   ",
+            "bridge.example.com/session",
+            "ftp://bridge.example.com/session",
+            "file:///tmp/socket",
+            "ws://",
+            "wss://",
+            "https://",
+            "ws:///path-only",
+            "https:///path-only",
+            "ws://?query-only",
+            "ws://#fragment-only",
+            "ws://:8080/no-host",
+            "ws://bridge.example.com:8080/pa th",
+            " ws://bridge.example.com",
+            "ws://bridge.example.com ",
+        ] {
+            let transport = SocketTransport::new(url);
+            assert!(
+                transport.validate().is_err(),
+                "expected rejection for {url:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn error_messages_never_echo_addresses() {
+        let secret = "super-secret-token-9f8e7d6c";
+        let transport = SocketTransport::new(format!("ftp://bridge.example.com/{secret}"));
+        let error = transport.validate().unwrap_err();
+        assert_eq!(
+            error,
+            TransportError::InvalidAddress("socket url scheme must be ws, wss, http, or https")
+        );
+        let rendered = format!("{error} {error:?}");
+        assert!(!rendered.contains(secret));
+        assert!(!rendered.contains("ftp://"));
+
+        let stdio_error = StdioTransport::new("", Vec::new()).validate().unwrap_err();
+        assert!(!format!("{stdio_error}").contains(secret));
+    }
+
+    #[test]
+    fn closed_and_unsupported_variants_stay_static() {
+        let closed = TransportError::Closed;
+        let unsupported = TransportError::Unsupported("socket bridge");
+        assert_eq!(format!("{closed}"), "transport is closed");
+        assert_eq!(
+            format!("{unsupported}"),
+            "unsupported transport: socket bridge"
+        );
+    }
+
+    #[test]
+    fn socket_hint_is_none_for_blank_address() {
+        for url in ["", "   ", "\t\n"] {
+            assert_eq!(SocketTransport::new(url).address_hint(), None);
+        }
+    }
+
+    #[test]
+    fn stdio_hint_trims_program_name() {
+        let transport = StdioTransport::new("  agent  ", Vec::new());
+        assert_eq!(transport.address_hint().as_deref(), Some("agent"));
+    }
+}

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>;
+}

package/src/components/AccountConnection.svelte

@@ -0,0 +1,201 @@
+<!-- Product-neutral account connector. The application backend owns all effects
+  (starting device flows, polling logins, storing keys, signing out); this
+  component only renders state and forwards user intent through app-supplied
+  async callbacks. It never spawns agents, polls, or touches credentials. -->
+<script lang="ts">
+  import {
+    authAccount,
+    isAuthenticated,
+    validateChallenge,
+    type AuthState,
+    type Challenge
+  } from '../auth.js';
+
+  interface AccountRef {
+    id: string;
+    label: string;
+    kind: 'chatgpt' | 'opencode_go' | (string & {});
+  }
+
+  let {
+    account,
+    state: authState = 'unknown' as AuthState,
+    busy = false,
+    challenge = null as Challenge | null,
+    onStart,
+    onCancel,
+    onKeySubmit,
+    onDisconnect
+  }: {
+    account: AccountRef;
+    state: AuthState;
+    busy: boolean;
+    challenge?: Challenge | null;
+    onStart: () => void | Promise<void>;
+    onCancel: () => void | Promise<void>;
+    onKeySubmit: (key: string) => void | Promise<void>;
+    onDisconnect?: () => void | Promise<void>;
+  } = $props();
+
+  let key = $state('');
+  let copyError = $state('');
+
+  // Renamed locally: a binding called `state` would shadow the `$state` rune analysis.
+  const authenticated: boolean = $derived(isAuthenticated(authState));
+  const accountName: string | null = $derived(authAccount(authState));
+  const validChallenge: Challenge | null = $derived(
+    challenge != null && validateChallenge(challenge) ? challenge : null
+  );
+  const isDeviceCodeAccount: boolean = $derived(account.kind === 'chatgpt');
+  const isKeyAccount: boolean = $derived(account.kind === 'opencode_go');
+  const keyInputId: string = $derived(`ccht-key-${account.id.replace(/[^a-zA-Z0-9_-]/g, '-')}`);
+  const canSubmitKey: boolean = $derived(key.trim().length >= 8 && !busy);
+
+  // Callbacks run application effects; the app surfaces their failures
+  // through its own operation state, so a rejection here stays silent.
+  function invoke(action: () => void | Promise<void>): void {
+    try {
+      const result = action();
+      if (result instanceof Promise) {
+        result.catch(() => {});
+      }
+    } catch {
+      // Handled by the application through its own operation state.
+    }
+  }
+
+  function submitKey(event: SubmitEvent): void {
+    event.preventDefault();
+    const value = key.trim();
+    // Clear immediately so the secret never lingers in component state.
+    key = '';
+    if (value.length < 8) {
+      return;
+    }
+    invoke(() => onKeySubmit(value));
+  }
+
+  async function copyAndContinue(): Promise<void> {
+    if (!validChallenge) {
+      return;
+    }
+    // Open during the click so browsers do not block the sign-in window after copying.
+    if (typeof window !== 'undefined') {
+      window.open(validChallenge.verification_url, '_blank', 'noopener,noreferrer');
+    }
+    try {
+      await navigator.clipboard.writeText(validChallenge.user_code);
+      copyError = '';
+    } catch {
+      copyError = 'Could not copy automatically. Copy the code above into the sign-in page.';
+    }
+  }
+</script>
+
+<section class="ccht-account" aria-label={`${account.label} connection`}>
+  {#if authenticated}
+    <p class="ccht-status" role="status">Connected{#if accountName} · {accountName}{/if}</p>
+    <button
+      type="button"
+      class="ccht-button ccht-disconnect"
+      disabled={busy}
+      onclick={() => invoke(onDisconnect ?? onCancel)}
+    >
+      Disconnect
+    </button>
+  {:else if authState === 'unknown'}
+    <p class="ccht-status" role="status">Checking {account.label} connection status…</p>
+    {#if busy}
+      <button type="button" class="ccht-button ccht-cancel" onclick={() => invoke(onCancel)}>
+        Cancel
+      </button>
+    {/if}
+  {:else if isDeviceCodeAccount}
+    {#if validChallenge}
+      <div class="ccht-challenge" aria-live="polite">
+        <p class="ccht-hint">Enter this code on the {account.label} sign-in page:</p>
+        <code class="ccht-code">{validChallenge.user_code}</code>
+        <button type="button" class="ccht-button" disabled={busy} onclick={() => void copyAndContinue()}>
+          Copy code and continue
+        </button>
+        <p>
+          <a
+            class="ccht-link"
+            href={validChallenge.verification_url}
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            Continue to {account.label}
+          </a>
+        </p>
+        {#if copyError}<p class="ccht-error" role="alert">{copyError}</p>{/if}
+      </div>
+    {:else if busy}
+      <p class="ccht-status" role="status">Starting account connection…</p>
+    {:else}
+      <p class="ccht-hint">Sign in with your {account.label} account.</p>
+      <button type="button" class="ccht-button" onclick={() => invoke(onStart)}>
+        Sign in to {account.label}
+      </button>
+    {/if}
+    {#if busy}
+      <button type="button" class="ccht-button ccht-cancel" onclick={() => invoke(onCancel)}>
+        Cancel
+      </button>
+    {/if}
+  {:else if isKeyAccount}
+    <form class="ccht-keyform" onsubmit={submitKey}>
+      <label class="ccht-label" for={keyInputId}>
+        {account.label} account key
+        <input
+          id={keyInputId}
+          class="ccht-input"
+          type="password"
+          autocomplete="off"
+          spellcheck="false"
+          maxlength="4096"
+          bind:value={key}
+          disabled={busy}
+        />
+      </label>
+      <button type="submit" class="ccht-button" disabled={!canSubmitKey}>
+        Connect {account.label}
+      </button>
+    </form>
+    {#if busy}
+      <button type="button" class="ccht-button ccht-cancel" onclick={() => invoke(onCancel)}>
+        Cancel
+      </button>
+    {/if}
+  {:else}
+    <p class="ccht-status" role="status">Not connected</p>
+    <p class="ccht-hint">Sign in with your {account.label} account.</p>
+    <button type="button" class="ccht-button" disabled={busy} onclick={() => invoke(onStart)}>
+      Sign in to {account.label}
+    </button>
+    {#if busy}
+      <button type="button" class="ccht-button ccht-cancel" onclick={() => invoke(onCancel)}>
+        Cancel
+      </button>
+    {/if}
+  {/if}
+</section>
+
+<style>
+  .ccht-account {
+    color: var(--ccht-fg, inherit);
+  }
+  .ccht-status,
+  .ccht-hint {
+    color: var(--ccht-muted, inherit);
+  }
+  .ccht-error {
+    color: var(--ccht-error, #b91c1c);
+  }
+  .ccht-code {
+    background-color: var(--ccht-code-bg, transparent);
+  }
+  .ccht-link {
+    color: var(--ccht-accent, inherit);
+  }
+</style>