@reddb-io/ui 0.1.1

package/src/lib/reddb/local-url-provider.ts

@@ -0,0 +1,245 @@
+// LocalUrlProvider — the OSS implementation of ConnectionProvider. Wraps
+// a list of well-known presets and a recent-history backing store. The
+// browser usage backs history with localStorage; tests inject an
+// in-memory store via the options bag.
+
+import { RedClient, type RedClientOptions } from "./client";
+import {
+  NotConnectedError,
+  UnknownConnectionError,
+  UnreachableConnectionError,
+  type ActiveConnection,
+  type Connection,
+  type ConnectionProvider,
+  type Identity,
+} from "./connection-provider";
+import { BROWSER_TRANSPORTS } from "./transports";
+import type { Transport } from "./types";
+import { hasBootEndpoint, hasBootRoute, type BootParams } from "./boot-params";
+
+export interface HistoryEntry {
+  url: string;
+  label: string;
+  last_used: number;
+  rtt_ms?: number;
+}
+
+export interface HistoryStore {
+  load(): HistoryEntry[];
+  save(entries: HistoryEntry[]): void;
+}
+
+export interface LocalUrlProviderOptions {
+  /** Built-in connections, surfaced first in `list()`. */
+  presets?: Connection[];
+  /** Backing store for the recent-URL history. Defaults to in-memory. */
+  history?: HistoryStore;
+  /** Hook for tests / Tauri to swap the HTTP client implementation. */
+  clientFactory?: (url: string, opts?: RedClientOptions) => RedClient;
+  /** Max history entries retained. */
+  historyMax?: number;
+  /**
+   * Wire transports this Surface can reach (#34, ADR-0003). Defaults to the
+   * browser-reachable set (http/https + coerced red://); a Tauri Surface passes
+   * the desktop set so native unix/embedded connections are offered.
+   */
+  transports?: Transport[];
+  /**
+   * Non-secret boot config seeded by the Surface (#36, ADR-0005) — endpoint +
+   * initial view from the app URL. Surfaced via `bootParams()` so the Core can
+   * auto-connect without the Connect flow. Tokens must never be placed here.
+   */
+  bootParams?: BootParams;
+}
+
+export interface HandoffTokenConsumer {
+  useHandoffToken(url: string, token: string): void;
+}
+
+const HISTORY_MAX_DEFAULT = 8;
+
+function inMemoryStore(): HistoryStore {
+  let entries: HistoryEntry[] = [];
+  return {
+    load: () => entries.slice(),
+    save: (next) => {
+      entries = next.slice();
+    },
+  };
+}
+
+export function localStorageHistory(key: string): HistoryStore {
+  return {
+    load() {
+      if (typeof localStorage === "undefined") return [];
+      try {
+        const raw = localStorage.getItem(key);
+        if (!raw) return [];
+        const parsed = JSON.parse(raw) as HistoryEntry[];
+        return Array.isArray(parsed) ? parsed : [];
+      } catch {
+        return [];
+      }
+    },
+    save(entries) {
+      if (typeof localStorage === "undefined") return;
+      try {
+        localStorage.setItem(key, JSON.stringify(entries));
+      } catch {
+        /* quota or disabled — drop silently */
+      }
+    },
+  };
+}
+
+export class LocalUrlProvider implements ConnectionProvider {
+  private readonly presets: Connection[];
+  private readonly history: HistoryStore;
+  private readonly clientFactory: (
+    url: string,
+    opts?: RedClientOptions
+  ) => RedClient;
+  private readonly historyMax: number;
+  private readonly supportedTransports: Transport[];
+  private readonly boot: BootParams | null;
+  private readonly handoffTokens = new Map<string, string>();
+  private active: ActiveConnection | null = null;
+
+  constructor(opts: LocalUrlProviderOptions = {}) {
+    this.presets = opts.presets?.slice() ?? [];
+    this.history = opts.history ?? inMemoryStore();
+    this.historyMax = opts.historyMax ?? HISTORY_MAX_DEFAULT;
+    this.clientFactory =
+      opts.clientFactory ??
+      ((url, clientOpts) => new RedClient(url, clientOpts));
+    this.supportedTransports = opts.transports?.slice() ?? [
+      ...BROWSER_TRANSPORTS,
+    ];
+    this.boot =
+      opts.bootParams &&
+      (hasBootEndpoint(opts.bootParams) || hasBootRoute(opts.bootParams))
+        ? { ...opts.bootParams }
+        : null;
+  }
+
+  transports(): Transport[] {
+    return this.supportedTransports.slice();
+  }
+
+  bootParams(): BootParams | null {
+    return this.boot ? { ...this.boot } : null;
+  }
+
+  useHandoffToken(url: string, token: string): void {
+    const clean = token.trim();
+    if (!clean) return;
+    this.handoffTokens.set(this.handoffKey(url), clean);
+  }
+
+  async list(): Promise<Connection[]> {
+    const seen = new Set<string>();
+    const out: Connection[] = [];
+    for (const p of this.presets) {
+      if (seen.has(p.url)) continue;
+      seen.add(p.url);
+      out.push(p);
+    }
+    for (const h of this.history.load()) {
+      if (seen.has(h.url)) continue;
+      seen.add(h.url);
+      out.push({ id: h.url, label: h.label, url: h.url, role: "primary" });
+    }
+    return out;
+  }
+
+  /**
+   * Connect by id. The id matches a preset id, a history URL, or a raw URL
+   * the caller wants to attempt ad-hoc — that last case is what makes this
+   * a *URL* provider rather than a registry. Unknown raw strings that
+   * don't look like URLs throw UnknownConnectionError.
+   */
+  async connect(id: string): Promise<ActiveConnection> {
+    const target = this.resolve(id);
+    if (!target) throw new UnknownConnectionError(id);
+
+    const token = this.consumeHandoffToken(target.url);
+    const client = this.clientFactory(
+      target.url,
+      token ? { headers: { Authorization: `Bearer ${token}` } } : undefined
+    );
+    const ping = await client.ping();
+    if (!ping.ok) throw new UnreachableConnectionError(target.id, ping.error);
+
+    const active: ActiveConnection = {
+      connection: target,
+      client,
+      rtt_ms: ping.rtt_ms,
+    };
+    this.active = active;
+    this.record(target, ping.rtt_ms);
+    return active;
+  }
+
+  async whoami(): Promise<Identity> {
+    if (!this.active) throw new NotConnectedError();
+    const w = await this.active.client.whoami();
+    return {
+      authenticated: w.authenticated,
+      username: w.username,
+      role: w.role,
+    };
+  }
+
+  /** Test/UI helper: remove a URL from history. Not part of the contract. */
+  forget(url: string): void {
+    const next = this.history.load().filter((e) => e.url !== url);
+    this.history.save(next);
+  }
+
+  private resolve(id: string): Connection | null {
+    const preset = this.presets.find((p) => p.id === id);
+    if (preset) return preset;
+
+    const hit = this.history.load().find((e) => e.url === id);
+    if (hit)
+      return { id: hit.url, label: hit.label, url: hit.url, role: "primary" };
+
+    if (/^[a-z+]+:\/\//i.test(id)) {
+      let host = id;
+      try {
+        host = new URL(id).host || id;
+      } catch {
+        /* fall through */
+      }
+      return {
+        id,
+        label: host,
+        url: id,
+        role: "primary",
+        description: "Ad-hoc URL.",
+      };
+    }
+
+    return null;
+  }
+
+  private handoffKey(url: string): string {
+    return url.replace(/\/$/, "");
+  }
+
+  private consumeHandoffToken(url: string): string | null {
+    const key = this.handoffKey(url);
+    const token = this.handoffTokens.get(key) ?? null;
+    this.handoffTokens.delete(key);
+    return token;
+  }
+
+  private record(c: Connection, rtt_ms: number): void {
+    const existing = this.history.load().filter((e) => e.url !== c.url);
+    const next: HistoryEntry[] = [
+      { url: c.url, label: c.label, last_used: Date.now(), rtt_ms },
+      ...existing,
+    ].slice(0, this.historyMax);
+    this.history.save(next);
+  }
+}

package/src/lib/reddb/secure-store.ts

@@ -0,0 +1,41 @@
+/**
+ * EncryptedStore — deep module for credential-grade key/value storage.
+ *
+ * Two implementations are shipped:
+ *
+ *  - WebEncryptedStore: derives an AES-GCM key from a session-scoped
+ *    master password (PBKDF2/SHA-256, 200k iterations) and writes
+ *    {ciphertext, nonce, salt} to localStorage.
+ *
+ *  - TauriEncryptedStore: defers to the OS keychain (Keychain on
+ *    macOS, Credential Manager on Windows, libsecret on Linux) via
+ *    a tiny set of `invoke` commands implemented in Rust.
+ *
+ * Both implementations share the same surface, the same error vocabulary,
+ * and the same tamper-detection guarantees.
+ */
+
+export interface EncryptedStore {
+  put(key: string, value: string): Promise<void>
+  get(key: string): Promise<string | null>
+  delete(key: string): Promise<void>
+}
+
+export class SecureStoreError extends Error {
+  readonly code: SecureStoreErrorCode
+  constructor(code: SecureStoreErrorCode, message: string) {
+    super(message)
+    this.name = 'SecureStoreError'
+    this.code = code
+  }
+}
+
+export type SecureStoreErrorCode =
+  /** Decryption of stored ciphertext failed — wrong key or tampered payload. */
+  | 'DECRYPT_FAILED'
+  /** Stored envelope is missing required fields or is structurally invalid. */
+  | 'CORRUPT_ENVELOPE'
+  /** Backing store (localStorage, keychain) refused the operation. */
+  | 'BACKEND_FAILURE'
+  /** Store accessed before unlock/key derivation. */
+  | 'LOCKED'

package/src/lib/reddb/server-capabilities.ts

@@ -0,0 +1,71 @@
+// Server-version capability negotiation (#22). One UI build talks to many
+// reddb server versions: rather than assume every endpoint exists, the UI
+// resolves a capability map for the active connection and HIDES controls the
+// server can't honour (absent, not greyed — the permission-aware rule).
+//
+// Resolution prefers a STABLE server signal (`GET /capabilities`) over
+// inferring from 404s, and FAILS SAFE — any uncertainty resolves to "not
+// supported" so a newer UI never assumes a capability a server lacks.
+
+/** The feature flags the UI gates controls on. Extend as features are added. */
+export interface ServerCapabilities {
+  /** Version control (commits / diffs) — `/repo/commits`, `/collections/:n/vcs`. */
+  vcs: boolean
+  /** Cluster topology + status — `/cluster/status`. */
+  clusterStatus: boolean
+  /** Per-collection metadata route — `GET /collections/:name`. */
+  collectionMetadata: boolean
+  /** Server-sent change stream — `/changes/stream`. */
+  cdcStream: boolean
+}
+
+/** Fail-safe baseline: nothing is assumed present until proven. */
+export const EMPTY_SERVER_CAPABILITIES: ServerCapabilities = Object.freeze({
+  vcs: false,
+  clusterStatus: false,
+  collectionMetadata: false,
+  cdcStream: false,
+})
+
+/** Shape of the optional stable `/capabilities` signal. */
+export interface RawCapabilities {
+  ok?: boolean
+  /** Flat feature names, e.g. ["vcs","cluster_status"]. */
+  features?: string[]
+  /** Or an explicit flag map, e.g. { vcs: true }. */
+  capabilities?: Record<string, boolean>
+}
+
+// Server feature names → our capability keys. Several aliases per key so we
+// tolerate naming drift across server versions without a UI release.
+const FEATURE_ALIASES: Record<string, keyof ServerCapabilities> = {
+  vcs: 'vcs',
+  versioning: 'vcs',
+  version_control: 'vcs',
+  cluster: 'clusterStatus',
+  cluster_status: 'clusterStatus',
+  collection_metadata: 'collectionMetadata',
+  collections_metadata: 'collectionMetadata',
+  cdc: 'cdcStream',
+  changes_stream: 'cdcStream',
+  cdc_stream: 'cdcStream',
+}
+
+/**
+ * Build a capability map from the stable `/capabilities` signal. Unknown
+ * feature names are ignored (a server advertising features this UI version
+ * doesn't model is harmless); known ones flip their flag on. The explicit
+ * `capabilities` map, when present, takes precedence over the `features` list.
+ */
+export function capabilitiesFromSignal(raw: RawCapabilities): ServerCapabilities {
+  const out: ServerCapabilities = { ...EMPTY_SERVER_CAPABILITIES }
+  for (const name of raw.features ?? []) {
+    const key = FEATURE_ALIASES[name?.toLowerCase?.() ?? '']
+    if (key) out[key] = true
+  }
+  for (const [name, on] of Object.entries(raw.capabilities ?? {})) {
+    const key = FEATURE_ALIASES[name.toLowerCase()]
+    if (key) out[key] = on === true
+  }
+  return out
+}

package/src/lib/reddb/tauri-encrypted-store.ts

@@ -0,0 +1,64 @@
+import { type EncryptedStore, SecureStoreError } from './secure-store'
+
+export type TauriInvoke = <T = unknown>(cmd: string, args?: Record<string, unknown>) => Promise<T>
+
+export interface TauriEncryptedStoreOptions {
+  /** Service name passed to the OS keychain. */
+  service?: string
+  /** Bound to the running Tauri runtime — pass `invoke` from `@tauri-apps/api/core`. */
+  invoke: TauriInvoke
+}
+
+/**
+ * Tauri-backed encrypted store. Defers entirely to the OS keychain via
+ * three commands implemented in Rust (see apps/desktop/src-tauri):
+ *
+ *   keychain_set    { service, key, value }   → void
+ *   keychain_get    { service, key }          → string | null
+ *   keychain_delete { service, key }          → void
+ *
+ * No master password prompt: trust is rooted in the OS user session.
+ */
+export class TauriEncryptedStore implements EncryptedStore {
+  private readonly invoke: TauriInvoke
+  private readonly service: string
+
+  constructor(opts: TauriEncryptedStoreOptions) {
+    if (!opts.invoke) {
+      throw new SecureStoreError('BACKEND_FAILURE', 'tauri invoke fn not provided')
+    }
+    this.invoke = opts.invoke
+    this.service = opts.service ?? 'io.reddb.red-ui'
+  }
+
+  async put(key: string, value: string): Promise<void> {
+    try {
+      await this.invoke<void>('keychain_set', { service: this.service, key, value })
+    } catch (e) {
+      throw new SecureStoreError('BACKEND_FAILURE', `keychain_set failed: ${stringifyError(e)}`)
+    }
+  }
+
+  async get(key: string): Promise<string | null> {
+    try {
+      const v = await this.invoke<string | null>('keychain_get', { service: this.service, key })
+      return v ?? null
+    } catch (e) {
+      throw new SecureStoreError('BACKEND_FAILURE', `keychain_get failed: ${stringifyError(e)}`)
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    try {
+      await this.invoke<void>('keychain_delete', { service: this.service, key })
+    } catch (e) {
+      throw new SecureStoreError('BACKEND_FAILURE', `keychain_delete failed: ${stringifyError(e)}`)
+    }
+  }
+}
+
+function stringifyError(e: unknown): string {
+  if (e instanceof Error) return e.message
+  if (typeof e === 'string') return e
+  try { return JSON.stringify(e) } catch { return String(e) }
+}

package/src/lib/reddb/transports.ts

@@ -0,0 +1,89 @@
+// Transport reachability (#34, ADR-0003). Which transports a connection can use
+// is bounded by what the *red-ui client* speaks — NOT by the browser, and NOT by
+// what the reddb server exposes. reddb itself offers many wire transports (HTTP
+// + SSE/NDJSON, RedWire on :5050, gRPC, Postgres-wire, and a WebSocket ingest
+// endpoint `WS /ws/ingest/{collection}` — see ../reddb/docs/api/). The red-ui
+// client, however, currently speaks only HTTP: RedClient is fetch-based (REST),
+// and live changes use SSE/REST polling over the same http(s) connection. So the
+// Connect UI offers http(s) only because that is the client's surface today — a
+// `ws`/`wss` (or `grpc`) transport belongs here only once the client actually
+// consumes reddb's WebSocket/gRPC endpoint, not before (that would be a phantom
+// option that fails when picked).
+//
+// `red://`/`reds://` are not distinct client transports either: normalizeUrl
+// rewrites them to `http(s)://host:5055` (the documented `red://localhost`
+// production tunnel — red-ui's HTTP convention, distinct from reddb's native
+// RedWire on :5050), so they classify as their coerced http(s) transport and are
+// reachable wherever http(s) is. Streaming rides over the http(s) connection, so
+// it needs no separate transport member. Only unix-socket / embedded-file
+// connections are reachable solely from a Tauri Surface, so those are the ones a
+// browser Surface hides. The Connect UI offers only the transports the active
+// provider declares reachable, so the user never picks one that fails. This
+// module is the pure scheme↔transport mapping + reachability sets; the provider
+// declares its set and the UI consults it.
+
+import type { Transport } from "./types";
+
+/**
+ * User-typed connection-string scheme → the wire transport it resolves to.
+ * `red`/`reds` (and their `red+tcp`/`red+wire`/`red+tls` aliases) are sugar for
+ * `http(s)://host:5055` via normalizeUrl, so they map to `http`/`https` — they
+ * carry no distinct wire transport in any Surface today. Native tcp/tls remains
+ * a possible future Desktop capability (ADR-0003) but is not materialized yet.
+ */
+const SCHEME_TRANSPORT: Record<string, Transport> = {
+  http: "http",
+  https: "https",
+  red: "http",
+  "red+tcp": "http",
+  "red+wire": "http",
+  reds: "https",
+  "red+tls": "https",
+  "red+http": "http",
+  "red+https": "https",
+  "red+unix": "unix",
+  file: "unix",
+  unix: "unix",
+};
+
+/**
+ * The transport a user-typed connection string would use. Defaults to `http`
+ * for a bare `host:port` (matching normalizeUrl, which prepends http://).
+ * Returns `null` for a scheme this client doesn't recognise at all.
+ */
+export function transportForUrl(input: string): Transport | null {
+  const raw = input.trim();
+  if (!raw) return null;
+  const m = raw.match(/^([a-z+]+):\/\//i);
+  if (!m) return "http"; // bare host:port → http (normalizeUrl prepends it)
+  return SCHEME_TRANSPORT[m[1].toLowerCase()] ?? null;
+}
+
+/**
+ * Browser-reachable transports: `http`/`https` only (ADR-0003). `red://`/`reds://`
+ * are still reachable here because they coerce to `http(s)://host:5055` and so
+ * classify as `http`/`https` — the documented `red://localhost` production
+ * tunnel keeps working — but the browser advertises no distinct red(s):// or
+ * file:// transport. Unix-socket / embedded-file connections are genuinely
+ * unreachable from a browser and are hidden.
+ */
+export const BROWSER_TRANSPORTS: readonly Transport[] = ["http", "https"];
+
+/** A Tauri Surface adds the native unix-socket / embedded-file transport. */
+export const DESKTOP_TRANSPORTS: readonly Transport[] = [
+  "http",
+  "https",
+  "unix",
+];
+
+/**
+ * Whether a user-typed URL's transport is reachable from a provider that
+ * declares `supported`. An unrecognised scheme is never reachable.
+ */
+export function isUrlReachable(
+  input: string,
+  supported: readonly Transport[]
+): boolean {
+  const t = transportForUrl(input);
+  return t !== null && supported.includes(t);
+}

package/src/lib/reddb/types.ts

@@ -0,0 +1,32 @@
+export type NodeRole = 'primary' | 'replica' | 'embedded'
+
+export type Transport = 'tcp' | 'tls' | 'unix' | 'http' | 'https'
+
+export interface ConnectionTarget {
+  transport: Transport
+  host: string
+  port?: number
+  path?: string
+  database?: string
+  username?: string
+  password?: string
+  role?: NodeRole
+  params: Record<string, string>
+}
+
+export interface NodeStats {
+  id: string
+  role: NodeRole
+  host: string
+  bytesUsed: number
+  bytesAvailable: number
+  keyCount: number
+  lagBytes?: number
+  uptimeSeconds: number
+}
+
+export interface Topology {
+  primary: NodeStats
+  replicas: NodeStats[]
+  observedAt: string
+}

package/src/lib/reddb/uri.ts

@@ -0,0 +1,54 @@
+import type { ConnectionTarget, NodeRole, Transport } from './types'
+
+const TRANSPORTS: Record<string, Transport> = {
+  red: 'tcp',
+  'red+tls': 'tls',
+  'red+unix': 'unix',
+  'red+http': 'http',
+  'red+https': 'https',
+}
+
+export function parseRedUri(uri: string): ConnectionTarget {
+  const match = uri.match(/^([a-z+]+):\/\/(.+)$/i)
+  if (!match) throw new Error(`Invalid red:// URI: ${uri}`)
+  const [, scheme, rest] = match
+
+  const transport = TRANSPORTS[scheme.toLowerCase()]
+  if (!transport) throw new Error(`Unsupported scheme: ${scheme}`)
+
+  if (transport === 'unix') {
+    const [path, query = ''] = rest.split('?')
+    return {
+      transport,
+      host: 'localhost',
+      path: decodeURIComponent(path),
+      params: parseQuery(query),
+    }
+  }
+
+  const url = new URL(`http://${rest}`)
+  const params = parseQuery(url.search.slice(1))
+  const role = params.role as NodeRole | undefined
+  const database = url.pathname.replace(/^\//, '') || undefined
+
+  return {
+    transport,
+    host: url.hostname,
+    port: url.port ? Number(url.port) : undefined,
+    database,
+    username: url.username ? decodeURIComponent(url.username) : undefined,
+    password: url.password ? decodeURIComponent(url.password) : undefined,
+    role,
+    params,
+  }
+}
+
+function parseQuery(qs: string): Record<string, string> {
+  const out: Record<string, string> = {}
+  if (!qs) return out
+  for (const pair of qs.split('&')) {
+    const [k, v = ''] = pair.split('=')
+    if (k) out[decodeURIComponent(k)] = decodeURIComponent(v)
+  }
+  return out
+}