@pellux/goodvibes-tui 0.24.1 → 0.26.0

package/src/daemon/handlers/remote/peer-registry.ts

@@ -0,0 +1,357 @@
+import { HandlerSqliteStore } from '../sqlite-store.ts';
+import {
+  isSecretReferenceValue,
+  isMalformedGoodVibesSecretReferenceValue,
+} from '../../../config/secret-config.ts';
+
+// ---------------------------------------------------------------------------
+// Backend vocabulary + per-backend config shapes
+// ---------------------------------------------------------------------------
+
+export type BackendKind = 'docker' | 'ssh' | 'cloud-terminal' | 'local-process';
+
+export type CloudProvider = 'gcp' | 'aws' | 'azure';
+
+export interface DockerBackendConfig {
+  containerName: string;
+  /**
+   * Optional Docker host. When it points at a remote daemon over TLS this MUST
+   * be a goodvibes://secrets/ reference (never a raw URL with embedded creds).
+   * A bare local socket path (unix://...) or tcp host without credentials is
+   * also accepted.
+   */
+  dockerHost?: string;
+}
+
+export interface SshBackendConfig {
+  sshHost: string;
+  sshPort?: number;
+  sshUser: string;
+  /** goodvibes://secrets/ reference to the private key — never the raw key. */
+  identityRef: string;
+}
+
+export interface CloudTerminalBackendConfig {
+  provider: CloudProvider;
+  projectId?: string;
+  /** goodvibes://secrets/ reference to the provider credential. */
+  credentialRef: string;
+  /** Optional zone/region/location passed to the provider CLI. */
+  location?: string;
+  /** For gcp: the Cloud Shell / VM instance to target. */
+  instance?: string;
+}
+
+export interface LocalProcessBackendConfig {
+  /** Optional working directory for spawned processes. */
+  cwd?: string;
+  /** Optional allowlist of executables; when set, only these may be invoked. */
+  allowedCommands?: string[];
+}
+
+export type BackendConfig =
+  | ({ kind: 'docker' } & DockerBackendConfig)
+  | ({ kind: 'ssh' } & SshBackendConfig)
+  | ({ kind: 'cloud-terminal' } & CloudTerminalBackendConfig)
+  | ({ kind: 'local-process' } & LocalProcessBackendConfig);
+
+export interface PeerRecord {
+  peerId: string;
+  displayName: string;
+  backendKind: BackendKind;
+  backendConfig: BackendConfig;
+}
+
+export interface PeerRegistrationInput {
+  peerId: string;
+  displayName: string;
+  backendKind: BackendKind;
+  // Raw, untrusted config from the operator method body. Normalized + validated.
+  backendConfig: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Validation helpers — backendConfig must hold ONLY secret refs for any
+// credential-bearing field. Raw secrets are rejected outright.
+// ---------------------------------------------------------------------------
+
+class PeerRegistryValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'PeerRegistryValidationError';
+  }
+}
+
+function requireString(value: unknown, field: string): string {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new PeerRegistryValidationError(`Field '${field}' is required and must be a non-empty string.`);
+  }
+  return value.trim();
+}
+
+function optionalString(value: unknown, field: string): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'string') {
+    throw new PeerRegistryValidationError(`Field '${field}' must be a string when provided.`);
+  }
+  const trimmed = value.trim();
+  return trimmed.length === 0 ? undefined : trimmed;
+}
+
+function requireSecretRef(value: unknown, field: string): string {
+  const ref = requireString(value, field);
+  if (!isSecretReferenceValue(ref)) {
+    throw new PeerRegistryValidationError(
+      `Field '${field}' must be a goodvibes://secrets/ reference, not a raw credential.`,
+    );
+  }
+  return ref;
+}
+
+function assertDockerHostSafe(value: string | undefined, field: string): void {
+  // A dockerHost is accepted in exactly two shapes, mirroring how docker.ts
+  // resolves it (docker.ts: `startsWith('goodvibes://') ? resolveRef(...) : raw`):
+  //   1. A goodvibes://secrets/ reference — resolved from the credential store.
+  //   2. A credential-free local/plain address (unix:// socket, or a bare
+  //      tcp/host with no embedded userinfo) — used verbatim.
+  // Enforcement here must match that resolution so no credential-bearing or
+  // unresolvable value slips through to docker.ts.
+  if (value === undefined) return;
+
+  // A valid secret ref is always allowed: docker.ts resolves it from the store.
+  if (isSecretReferenceValue(value)) return;
+
+  // A `goodvibes://` value that is NOT a well-formed secret ref would be handed
+  // to credentials.resolveRef() and fail opaquely (REMOTE_BACKEND_CREDENTIAL_MISSING)
+  // — or, worse, a near-miss could be treated as a literal host. Reject it at
+  // registration so the misconfiguration surfaces immediately.
+  if (isMalformedGoodVibesSecretReferenceValue(value)) {
+    throw new PeerRegistryValidationError(
+      `Field '${field}' looks like a goodvibes:// reference but is malformed; use a valid goodvibes://secrets/ reference.`,
+    );
+  }
+
+  // Embedded userinfo credentials (e.g. tcp://user:pass@host) must never be
+  // stored raw — docker.ts would pass them verbatim as DOCKER_HOST.
+  if (value.includes('@')) {
+    throw new PeerRegistryValidationError(
+      `Field '${field}' appears to embed credentials; pass a goodvibes://secrets/ reference instead.`,
+    );
+  }
+
+  // A remote daemon reached over TLS carries its credentials out-of-band and
+  // MUST be referenced through the credential store, never pinned as a raw
+  // host string the daemon would use unauthenticated. docker.ts only treats a
+  // goodvibes:// value as a secret, so a raw `https://`/`tcp+tls://` endpoint
+  // here would bypass credential resolution entirely.
+  const lowered = value.toLowerCase();
+  if (lowered.startsWith('https://') || lowered.startsWith('tcp+tls://')) {
+    throw new PeerRegistryValidationError(
+      `Field '${field}' points at a TLS Docker daemon; pass a goodvibes://secrets/ reference instead of a raw URL.`,
+    );
+  }
+}
+
+/** Normalize + validate raw backendConfig into a typed, ref-only BackendConfig. */
+export function normalizeBackendConfig(
+  backendKind: BackendKind,
+  raw: Record<string, unknown>,
+): BackendConfig {
+  switch (backendKind) {
+    case 'docker': {
+      const dockerHost = optionalString(raw.dockerHost, 'dockerHost');
+      assertDockerHostSafe(dockerHost, 'dockerHost');
+      return {
+        kind: 'docker',
+        containerName: requireString(raw.containerName, 'containerName'),
+        ...(dockerHost !== undefined ? { dockerHost } : {}),
+      };
+    }
+    case 'ssh': {
+      const portValue = raw.sshPort;
+      let sshPort: number | undefined;
+      if (portValue !== undefined && portValue !== null) {
+        const parsed = typeof portValue === 'number' ? portValue : Number(portValue);
+        if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+          throw new PeerRegistryValidationError("Field 'sshPort' must be an integer between 1 and 65535.");
+        }
+        sshPort = parsed;
+      }
+      return {
+        kind: 'ssh',
+        sshHost: requireString(raw.sshHost, 'sshHost'),
+        sshUser: requireString(raw.sshUser, 'sshUser'),
+        identityRef: requireSecretRef(raw.identityRef, 'identityRef'),
+        ...(sshPort !== undefined ? { sshPort } : {}),
+      };
+    }
+    case 'cloud-terminal': {
+      const provider = requireString(raw.provider, 'provider');
+      if (provider !== 'gcp' && provider !== 'aws' && provider !== 'azure') {
+        throw new PeerRegistryValidationError("Field 'provider' must be one of 'gcp' | 'aws' | 'azure'.");
+      }
+      const projectId = optionalString(raw.projectId, 'projectId');
+      const location = optionalString(raw.location, 'location');
+      const instance = optionalString(raw.instance, 'instance');
+      return {
+        kind: 'cloud-terminal',
+        provider,
+        credentialRef: requireSecretRef(raw.credentialRef, 'credentialRef'),
+        ...(projectId !== undefined ? { projectId } : {}),
+        ...(location !== undefined ? { location } : {}),
+        ...(instance !== undefined ? { instance } : {}),
+      };
+    }
+    case 'local-process': {
+      const cwd = optionalString(raw.cwd, 'cwd');
+      let allowedCommands: string[] | undefined;
+      if (raw.allowedCommands !== undefined && raw.allowedCommands !== null) {
+        if (!Array.isArray(raw.allowedCommands)) {
+          throw new PeerRegistryValidationError("Field 'allowedCommands' must be an array of strings.");
+        }
+        const list = raw.allowedCommands
+          .map((entry) => (typeof entry === 'string' ? entry.trim() : ''))
+          .filter((entry) => entry.length > 0);
+        allowedCommands = list;
+      }
+      return {
+        kind: 'local-process',
+        ...(cwd !== undefined ? { cwd } : {}),
+        ...(allowedCommands !== undefined ? { allowedCommands } : {}),
+      };
+    }
+    default:
+      throw new PeerRegistryValidationError(`Unknown backendKind: ${String(backendKind)}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Peer registry — persisted via HandlerSqliteStore (peer-registry.sqlite)
+// ---------------------------------------------------------------------------
+
+const PEER_REGISTRY_FILE = 'peer-registry.sqlite';
+
+const SCHEMA = [
+  `CREATE TABLE IF NOT EXISTS peers (
+     peerId TEXT PRIMARY KEY,
+     displayName TEXT NOT NULL,
+     backendKind TEXT NOT NULL,
+     backendConfig TEXT NOT NULL
+   )`,
+];
+
+interface PeerRow {
+  peerId: string;
+  displayName: string;
+  backendKind: string;
+  backendConfig: string;
+}
+
+const VALID_BACKEND_KINDS: ReadonlySet<BackendKind> = new Set([
+  'docker',
+  'ssh',
+  'cloud-terminal',
+  'local-process',
+]);
+
+function rowToRecord(row: PeerRow): PeerRecord {
+  const backendKind = row.backendKind as BackendKind;
+  const parsed = JSON.parse(row.backendConfig) as BackendConfig;
+  return {
+    peerId: row.peerId,
+    displayName: row.displayName,
+    backendKind,
+    backendConfig: parsed,
+  };
+}
+
+export class PeerRegistry {
+  private readonly store: HandlerSqliteStore;
+  private initialized = false;
+
+  constructor(workingDirectory: string) {
+    this.store = new HandlerSqliteStore({
+      workingDirectory,
+      fileName: PEER_REGISTRY_FILE,
+      schema: SCHEMA,
+    });
+  }
+
+  get dbPath(): string {
+    return this.store.dbPath;
+  }
+
+  async init(): Promise<void> {
+    if (this.initialized) return;
+    await this.store.init();
+    this.initialized = true;
+  }
+
+  private requireInit(): void {
+    if (!this.initialized) {
+      throw new Error('PeerRegistry not initialized: call init() first.');
+    }
+  }
+
+  /** Register (upsert) a peer. Validates + normalizes backendConfig to refs-only. */
+  async register(input: PeerRegistrationInput): Promise<PeerRecord> {
+    this.requireInit();
+    const peerId = requireString(input.peerId, 'peerId');
+    const displayName = requireString(input.displayName, 'displayName');
+    if (!VALID_BACKEND_KINDS.has(input.backendKind)) {
+      throw new PeerRegistryValidationError(`Unknown backendKind: ${String(input.backendKind)}`);
+    }
+    const backendConfig = normalizeBackendConfig(input.backendKind, input.backendConfig ?? {});
+    const serialized = JSON.stringify(backendConfig);
+    this.store.run(
+      `INSERT INTO peers (peerId, displayName, backendKind, backendConfig)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(peerId) DO UPDATE SET
+         displayName = excluded.displayName,
+         backendKind = excluded.backendKind,
+         backendConfig = excluded.backendConfig`,
+      [peerId, displayName, input.backendKind, serialized],
+    );
+    await this.store.save();
+    return { peerId, displayName, backendKind: input.backendKind, backendConfig };
+  }
+
+  /** Look up a peer by id. Returns null when not registered. */
+  get(peerId: string): PeerRecord | null {
+    this.requireInit();
+    const row = this.store.get<PeerRow>(
+      'SELECT peerId, displayName, backendKind, backendConfig FROM peers WHERE peerId = ?',
+      [peerId],
+    );
+    return row ? rowToRecord(row) : null;
+  }
+
+  /** List all registered peers (config included; contains only secret refs). */
+  list(): PeerRecord[] {
+    this.requireInit();
+    const rows = this.store.all<PeerRow>(
+      'SELECT peerId, displayName, backendKind, backendConfig FROM peers ORDER BY peerId ASC',
+    );
+    return rows.map(rowToRecord);
+  }
+
+  /** Remove a peer. Returns true when a row was deleted. */
+  async remove(peerId: string): Promise<boolean> {
+    this.requireInit();
+    const existed = this.get(peerId) !== null;
+    if (existed) {
+      this.store.run('DELETE FROM peers WHERE peerId = ?', [peerId]);
+      await this.store.save();
+    }
+    return existed;
+  }
+
+  close(): void {
+    if (this.initialized) {
+      this.store.close();
+      this.initialized = false;
+    }
+  }
+}
+
+export { PeerRegistryValidationError };

package/src/daemon/handlers/remote/service.ts

@@ -0,0 +1,191 @@
+/**
+ * Host implementation of the daemon-sdk `DistributedRuntimeRouteService` (17
+ * methods). The SDK ships NO docker/ssh/cloud backend, so the host owns it:
+ *
+ *  - `invokePeer` executes against the host's own remote backends through the
+ *    `RemoteDispatcher` (docker / ssh / cloud-terminal / local-process). This is
+ *    the only method that performs real command execution.
+ *  - The 16 peer / pairing / work-queue methods are backed by the SDK's
+ *    `DistributedRuntimeManager` (constructed by the surface), which owns peer
+ *    records, pairing challenges, token rotation, and the work queue.
+ *
+ * The SDK injects this instance into `DaemonRemoteRouteContext.distributedRuntime`
+ * so the published `remote.peers.*` HTTP routes dispatch to it. No catalog
+ * descriptor or schema is authored here.
+ */
+import { operations } from '@pellux/goodvibes-sdk/platform/runtime';
+import type {
+  DistributedRuntimeRouteService,
+  RemotePeerAuth,
+} from '../contracts.ts';
+import { RemoteDispatcher } from './dispatcher.ts';
+import type { DispatchPayload } from './backends/index.ts';
+
+type DistributedRuntimeManager = operations.DistributedRuntimeManager;
+type DistributedPeerAuth = operations.DistributedPeerAuth;
+
+/** Coerce an injected `RemotePeerAuth` (typed `unknown` by the SDK) to the manager's auth shape. */
+function asPeerAuth(auth: RemotePeerAuth): DistributedPeerAuth {
+  return auth as DistributedPeerAuth;
+}
+
+/** Narrow an arbitrary route-supplied input bag to a typed manager input. */
+function asInput<T>(input: Record<string, unknown>): T {
+  return input as unknown as T;
+}
+
+function readString(input: Record<string, unknown>, key: string): string {
+  const value = input[key];
+  return typeof value === 'string' ? value : '';
+}
+
+function readPrincipal(input: Record<string, unknown>): string {
+  const actor = input.actor ?? input.principalId ?? input.queuedBy;
+  return typeof actor === 'string' && actor.length > 0 ? actor : 'remote';
+}
+
+function readPayload(input: Record<string, unknown>): DispatchPayload | undefined {
+  const payload = input.payload;
+  if (payload && typeof payload === 'object') {
+    return payload as DispatchPayload;
+  }
+  return undefined;
+}
+
+export class HostDistributedRuntime implements DistributedRuntimeRouteService {
+  private readonly manager: DistributedRuntimeManager;
+  private readonly dispatcher: RemoteDispatcher;
+
+  constructor(manager: DistributedRuntimeManager, dispatcher: RemoteDispatcher) {
+    this.manager = manager;
+    this.dispatcher = dispatcher;
+  }
+
+  // --- Pairing -------------------------------------------------------------
+
+  listPairRequests(): unknown {
+    return this.manager.listPairRequests();
+  }
+
+  requestPairing(input: Record<string, unknown>): Promise<unknown> {
+    return this.manager.requestPairing(
+      asInput<Parameters<DistributedRuntimeManager['requestPairing']>[0]>(input),
+    );
+  }
+
+  approvePairRequest(requestId: string, input: Record<string, unknown>): Promise<unknown | null> {
+    return this.manager.approvePairRequest(
+      requestId,
+      asInput<Parameters<DistributedRuntimeManager['approvePairRequest']>[1]>(input),
+    );
+  }
+
+  rejectPairRequest(requestId: string, input: Record<string, unknown>): Promise<unknown | null> {
+    return this.manager.rejectPairRequest(
+      requestId,
+      asInput<Parameters<DistributedRuntimeManager['rejectPairRequest']>[1]>(input),
+    );
+  }
+
+  verifyPairRequest(
+    requestId: string,
+    challenge: string,
+    input: Record<string, unknown>,
+  ): Promise<unknown | null> {
+    return this.manager.verifyPairRequest(
+      requestId,
+      challenge,
+      asInput<Parameters<DistributedRuntimeManager['verifyPairRequest']>[2]>(input),
+    );
+  }
+
+  // --- Peer management -----------------------------------------------------
+
+  listPeers(): unknown {
+    return this.manager.listPeers();
+  }
+
+  rotatePeerToken(peerId: string, input: Record<string, unknown>): Promise<unknown | null> {
+    return this.manager.rotatePeerToken(
+      peerId,
+      asInput<Parameters<DistributedRuntimeManager['rotatePeerToken']>[1]>(input),
+    );
+  }
+
+  revokePeerToken(peerId: string, input: Record<string, unknown>): Promise<unknown | null> {
+    return this.manager.revokePeerToken(
+      peerId,
+      asInput<Parameters<DistributedRuntimeManager['revokePeerToken']>[1]>(input),
+    );
+  }
+
+  disconnectPeer(peerId: string, input: Record<string, unknown>): Promise<unknown | null> {
+    return this.manager.disconnectPeer(
+      peerId,
+      asInput<Parameters<DistributedRuntimeManager['disconnectPeer']>[1]>(input),
+    );
+  }
+
+  getNodeHostContract(): unknown {
+    return this.manager.getNodeHostContract();
+  }
+
+  // --- Peer-authenticated heartbeat + work claim ---------------------------
+
+  heartbeatPeer(auth: RemotePeerAuth, input: Record<string, unknown>): Promise<unknown> {
+    return this.manager.heartbeatPeer(
+      asPeerAuth(auth),
+      asInput<Parameters<DistributedRuntimeManager['heartbeatPeer']>[1]>(input),
+    );
+  }
+
+  claimWork(auth: RemotePeerAuth, input: Record<string, unknown>): Promise<unknown> {
+    return this.manager.claimWork(
+      asPeerAuth(auth),
+      asInput<Parameters<DistributedRuntimeManager['claimWork']>[1]>(input),
+    );
+  }
+
+  completeWork(
+    auth: RemotePeerAuth,
+    workId: string,
+    input: Record<string, unknown>,
+  ): Promise<unknown | null> {
+    return this.manager.completeWork(
+      asPeerAuth(auth),
+      workId,
+      asInput<Parameters<DistributedRuntimeManager['completeWork']>[2]>(input),
+    );
+  }
+
+  // --- Work queue ----------------------------------------------------------
+
+  listWork(): unknown {
+    return this.manager.listWork();
+  }
+
+  cancelWork(workId: string, input: Record<string, unknown>): Promise<unknown | null> {
+    return this.manager.cancelWork(
+      workId,
+      asInput<Parameters<DistributedRuntimeManager['cancelWork']>[1]>(input),
+    );
+  }
+
+  // --- Command execution (host-owned backends) -----------------------------
+
+  /**
+   * Execute a command on a registered peer through the host backends. Unlike the
+   * manager's enqueue-only `invokePeer`, this performs real docker/ssh/cloud/
+   * local-process execution and returns a receipt with a full-stdout digest.
+   */
+  async invokePeer(input: Record<string, unknown>): Promise<unknown> {
+    const payload = readPayload(input);
+    return this.dispatcher.dispatch({
+      peerId: readString(input, 'peerId'),
+      command: readString(input, 'command'),
+      principalId: readPrincipal(input),
+      async: input.async === true,
+      ...(payload !== undefined ? { payload } : {}),
+    });
+  }
+}

package/src/daemon/handlers/routing/inbox-bridge.ts

@@ -0,0 +1,71 @@
+// ---------------------------------------------------------------------------
+// Inbox <-> Routing resolver bridge.
+//
+// The inbox provider adapters expose a best-effort route-resolution seam: given
+// an inbound item's `{ provider, fromDigest, kind, routeId? }` they ask "which
+// daemon route binding handles this item?" and stamp the answer onto
+// `item.routeId` when one resolves. The routing control plane owns the
+// channel<->profile bindings and exposes a `RoutingResolver` whose
+// `getProfileForChannel(surfaceKind, routeId?)` applies the canonical
+// resolution order:
+//
+//   1. exact     — surfaceKind AND routeId both match
+//   2. surface   — surfaceKind matches, route has no routeId
+//   3. wildcard  — a route with surfaceKind === 'any' (no routeId)
+//
+// This module bridges the two shapes. The bridge maps an inbound item's
+// `provider` to the routing `surfaceKind` and forwards an optional `routeId`
+// refinement; `fromDigest`/`kind` are NOT used as routing keys (the routing
+// store is keyed by surfaceKind + optional routeId only, never by sender digest
+// or message kind — see RoutingChannelRoute). When no binding matches the
+// resolver returns null and the bridge yields `undefined`, so the adapter falls
+// back to leaving the item unrouted (offline/default behaviour intact). The
+// bridge NEVER throws: the underlying resolver is a pure in-memory lookup.
+//
+// The inbox surface is a separate follow-up module, so this bridge declares the
+// minimal `RouteResolver` seam locally rather than importing a sibling that the
+// routing slice does not own — keeping the routing handler layer free of any
+// cross-surface import edge.
+// ---------------------------------------------------------------------------
+
+import type { RoutingResolver } from './routing-resolver.ts';
+
+/**
+ * Fields the bridge consults on an inbound item. `provider` maps to the routing
+ * `surfaceKind`; an optional `routeId` (e.g. a Slack channel id or email
+ * mailbox tag) enables exact (surfaceKind+routeId) matches. Additional inbound
+ * fields are ignored for routing purposes.
+ */
+export interface RouteResolverInput {
+  readonly provider?: unknown;
+  readonly routeId?: unknown;
+  readonly [key: string]: unknown;
+}
+
+/**
+ * Best-effort seam the inbox provider adapters invoke per inbound item. Returns
+ * the resolved profile-route binding id, or `undefined` when nothing matches.
+ */
+export type RouteResolver = (input: RouteResolverInput) => string | undefined;
+
+/**
+ * Build a {@link RouteResolver} backed by the routing surface's
+ * {@link RoutingResolver}. Maps `provider -> surfaceKind` and forwards an
+ * optional `routeId` refinement, then applies the canonical
+ * exact > surface-only > wildcard resolution order via `getProfileForChannel`.
+ * Returns the resolved profileId (the daemon route binding) or `undefined` when
+ * nothing matches.
+ */
+export function createInboxRouteResolver(resolver: RoutingResolver): RouteResolver {
+  return (input: RouteResolverInput): string | undefined => {
+    const surfaceKind = typeof input.provider === 'string' ? input.provider : '';
+    if (surfaceKind.length === 0) return undefined;
+    const routeId = typeof input.routeId === 'string' && input.routeId.length > 0
+      ? input.routeId
+      : undefined;
+    // getProfileForChannel applies exact (surfaceKind+routeId) > surface-only >
+    // wildcard ('any') and returns null when no assignment matches.
+    const profileId = resolver.getProfileForChannel(surfaceKind, routeId);
+    return profileId ?? undefined;
+  };
+}