workerdeck 0.0.0 → 0.6.0

package/build/index.d.mts

@@ -0,0 +1,286 @@
+import { Authenticator, WorkerServer, WorkerServerOptions } from "@workerdeck/server";
+import { IncomingMessage, ServerResponse } from "node:http";
+import { ProfileInfo } from "@workerdeck/protocol";
+
+//#region src/auth.d.ts
+/**
+ * Gateway auth for the turnkey CLI: one shared operator secret, two transports.
+ *
+ * Services present the secret itself on every request (`x-workerdeck-key`,
+ * or `Authorization: Bearer`). The dashboard cannot: the SPA is prebuilt to
+ * call `location.origin + '/v1'` with no headers, and a browser WebSocket
+ * handshake carries no custom headers at all. So browsers POST the secret once
+ * to `/auth/login`, get an HttpOnly cookie naming a server-side session, and
+ * the cookie rides same-origin REST and the WS upgrade automatically. That
+ * automatic ride is also the threat: the cookie is ambient authority, and the
+ * WS handshake is exempt from CORS, so cross-origin misuse is fenced off by an
+ * explicit Origin check here — not by the browser.
+ *
+ * This file guards the operator's own gateway and nothing else. It never sees
+ * an Anthropic credential — those are resolved by the SDK/CLI from the
+ * operator's environment (root CLAUDE.md, auth red lines).
+ */
+type CliAuthOptions = {
+  /**
+   * The shared operator secret. Unset disables auth entirely (the CLI then
+   * refuses to bind anything but loopback — enforced by the caller, not here).
+   * An empty or short value is a config accident, not a choice: anything under
+   * 12 characters throws rather than standing up a guessable gateway.
+   */
+  secret?: string;
+  /** Default 'workerdeck_session'. No `__Host-` prefix — it requires
+   * `Secure`, and plain-HTTP localhost is the primary deployment. */
+  cookieName?: string;
+  /**
+   * Browser session lifetime, default 7 days. Fixed, not sliding: the auth
+   * hooks only see the request, so a renewed cookie has nowhere to ride — and
+   * for a dashboard whose whole login is retyping one secret, a periodic
+   * re-login is cheaper than a refresh endpoint. Expiry (or a process restart —
+   * sessions are in-memory by design) simply lands the operator back on the
+   * login page.
+   */
+  ttlMs?: number;
+  /**
+   * Trust `x-forwarded-proto` / `x-forwarded-host` / `x-forwarded-for` from
+   * exactly one reverse proxy in front of this process; the *last* value of
+   * each is used (the one the proxy set, the only position a client cannot
+   * forge). Off by default: these are attacker-writable headers on a directly
+   * exposed port. Behind a TLS-terminating proxy this must be on, or the
+   * `Secure` cookie flag is skipped and the Origin check computes `http://`
+   * where the browser says `https://` and rejects the dashboard's own writes.
+   */
+  trustProxy?: boolean;
+  /**
+   * Origins accepted in addition to the request's own (scheme + Host). Needed
+   * when the proxy rewrites Host so the external origin no longer matches what
+   * this process sees. Entries must be full origins ('https://ops.example.com');
+   * invalid ones throw at startup rather than silently never matching.
+   */
+  allowedOrigins?: string[];
+  /** Login throttle tuning; defaults: 15 min window, 10 failures per IP, 100
+   * globally. Exposed mainly so tests need not wait out real windows. */
+  throttle?: {
+    windowMs?: number;
+    maxFailuresPerIp?: number;
+    maxFailuresGlobal?: number;
+  };
+};
+/** What `authenticate` hands the worker server as the request principal. */
+type CliPrincipal = {
+  /** Which transport authenticated the request; 'open' when auth is disabled. */via: 'header' | 'cookie' | 'open';
+  /** One secret, one trust level: whoever holds it is the operator, so the
+   * dashboard may manage provider profiles (still bounded by the server's
+   * `allowedConfigDirRoots`). */
+  canManageProfiles: true;
+};
+type CliAuth = {
+  enabled: boolean;
+  /** Hand straight to `createWorkerServer({ authenticate })` — it guards both
+   * REST and the WS upgrade, which is exactly why the Origin policy lives in it. */
+  authenticate: Authenticator;
+  /** Claims `/auth` and everything under it (login/logout/status); returns true
+   * when it consumed the request. The static host must call this first. */
+  handleAuthRequest(req: IncomingMessage, res: ServerResponse): boolean | Promise<boolean>;
+  /** Cookie-only check for the static host: login page or SPA? Gating the SPA
+   * shell is UX, not security — every byte of data sits behind `authenticate`. */
+  hasValidSession(req: IncomingMessage): boolean;
+  /** What the login page needs to render for this request. The endpoint path,
+   * field name, and the `?auth=` redirect params are all this module's wire
+   * format, so the page learns them here instead of hardcoding them. */
+  loginPage(req: IncomingMessage): {
+    action: string;
+    field: string;
+    error?: string;
+  };
+};
+declare function createCliAuth(options?: CliAuthOptions): CliAuth;
+//#endregion
+//#region src/config.d.ts
+/**
+ * What a `workerdeck.config.mjs` default-exports: the server options, plus
+ * the few instance-level settings that aren't the server's business. Keeping
+ * them in one object means a deployment is one file, not a file plus a
+ * memorised command line.
+ */
+type WorkerDeckConfig = WorkerServerOptions & {
+  port?: number;
+  host?: string; /** Built-in shared-secret auth. Ignored entirely if you supply `authenticate`. */
+  auth?: CliAuthOptions; /** Where parked sessions are persisted; null disables durable parking. */
+  stateDir?: string | null;
+  /**
+   * Host header values accepted when running *without* auth. Defaults to the
+   * loopback names; see `resolveInstanceConfig` for why this exists at all.
+   */
+  allowedHosts?: string[];
+  /**
+   * Bind hosts that may serve without auth. One declaration, two effects:
+   * binding a listed host waives the auth requirement (no key demanded, none
+   * generated), and while unauthenticated every entry is also accepted as a
+   * Host header, so the operator states the intent once. Entries name a host,
+   * never an endpoint — a port is rejected — and match the bind host literally
+   * and case-insensitively: nothing is inferred from DNS or the network, and
+   * `0.0.0.0` means the all-interfaces bind itself, not "any host". When auth
+   * is on this widens nothing.
+   */
+  insecureHosts?: string[]; /** Serve a dashboard build from here instead of the bundled one. */
+  webRoot?: string;
+};
+type CliFlags = {
+  config?: string;
+  port?: number;
+  host?: string;
+  authKey?: string;
+  profiles: ProfileInfo[];
+  cwdRoots: string[];
+  allowedOrigins: string[];
+  allowedHosts: string[];
+  insecureHosts: string[];
+  trustProxy?: boolean;
+  stateDir?: string;
+  parking?: boolean;
+  insecure?: boolean;
+  open?: boolean;
+  help?: boolean;
+  version?: boolean;
+};
+declare class ConfigError extends Error {}
+/**
+ * Hand-rolled rather than a dependency: the CLI's whole value is that `npx
+ * workerdeck` pulls down a small tree, and an arg parser is a hundred lines
+ * of it.
+ */
+declare function parseArgs(argv: string[]): CliFlags;
+type LoadedConfig = {
+  /** Absolute path of the file that was loaded, or null if there wasn't one. */path: string | null;
+  options: WorkerDeckConfig;
+};
+/**
+ * Explicit `--config` must exist — a typo that silently starts a default
+ * instance is worse than a failure. An implicit one is looked up in cwd only:
+ * walking parent directories would make what a given command does depend on
+ * where it was run from.
+ */
+declare function loadConfigFile(explicit?: string, cwd?: string): Promise<LoadedConfig>;
+declare function isLoopback(host: string): boolean;
+type ResolvedConfig = {
+  port: number;
+  host: string; /** Shared secret, or undefined for an unauthenticated instance. */
+  authKey?: string; /** Everything else the built-in auth takes (proxy trust, extra origins). */
+  auth: CliAuthOptions; /** Where parked sessions and other instance state live; null disables durable parking. */
+  stateDir: string | null;
+  configPath: string | null; /** True when the config file supplied its own `authenticate` — built-in auth stands down. */
+  hostAuthenticates: boolean;
+  /**
+   * Auth is required here but no key was supplied: `startInstance` must
+   * materialize one (stored under `stateDir`, ephemeral without one). This is a
+   * *promise* rather than a key because resolution is pure and synchronous while
+   * reading a key file is I/O — and the promise is load-bearing: `allowedHosts`
+   * is already null on the strength of it, so `startInstance` refuses to serve
+   * if materialization ever fails to arm the built-in auth.
+   */
+  generateAuthKey: boolean;
+  /**
+   * Host header values to accept, or null to accept any. Non-null only for an
+   * unauthenticated instance — see `resolveInstanceConfig`.
+   */
+  allowedHosts: Set<string> | null; /** Dashboard build to serve; resolved from the package when unset. */
+  webRoot?: string;
+  open: boolean;
+  options: WorkerServerOptions;
+};
+/**
+ * Durable parking is on by default because this is a long-lived instance: a
+ * turnkey tool that silently drops parked work on every restart is the wrong
+ * default. The store writes whole transcripts in plaintext, so it goes beside
+ * the config file (or under the home directory) rather than anywhere temporary,
+ * and one directory serves exactly one instance — the store is single-process
+ * by design, which the single-port model already implies.
+ */
+declare function defaultStateDir(configPath: string | null): string;
+/** Hostname out of a Host header, minus the port and any IPv6 brackets. */
+declare function hostnameOf(hostHeader: string): string;
+/** 127.0.0.0/8, ::1, and the names that mean them. */
+declare function isLoopbackHostname(hostname: string): boolean;
+declare function resolveInstanceConfig(flags: CliFlags, loaded: LoadedConfig, env?: NodeJS.ProcessEnv, cwd?: string): ResolvedConfig;
+//#endregion
+//#region src/instance.d.ts
+type Instance = {
+  server: WorkerServer;
+  url: string;
+  port: number; /** Resolves when the instance stops serving. */
+  closed: Promise<void>;
+  close: () => Promise<void>;
+};
+/**
+ * The dashboard comes from `@workerdeck/web`, which ships it prebuilt and
+ * exports the path to it. Depending on the package rather than vendoring a copy
+ * means one dashboard, versioned in lockstep with everything else.
+ *
+ * In a checkout that directory only exists once the app has been built — dev
+ * never builds — so the miss is worth a real message rather than a stack trace
+ * from the static host.
+ */
+declare function resolveWebRoot(): string;
+/**
+ * The Host-header gate for an unauthenticated instance. `allowedHosts` is null
+ * whenever auth is on, and then this is the identity function — with a
+ * credential in play a rebound origin holds no cookie and fails `authenticate`
+ * anyway. Loopback *names* are what's checked, not the socket: the attacker in
+ * this scenario controls DNS, so the connection genuinely arrives on 127.0.0.1;
+ * what they cannot control is the name the victim's browser writes into Host.
+ */
+declare function createHostGuard(allowedHosts: Set<string> | null): (req: IncomingMessage) => boolean;
+declare function startInstance(config: ResolvedConfig, options?: {
+  quiet?: boolean;
+}): Promise<Instance>;
+//#endregion
+//#region src/guard.d.ts
+declare function runGuard(argv: string[]): Promise<number>;
+//#endregion
+//#region src/auth-key.d.ts
+/**
+ * Materializes the key that `resolveInstanceConfig` promised via
+ * `generateAuthKey`: resolution is pure and synchronous, reading a key file is
+ * I/O, so the two halves meet here at startup. The contract is that this
+ * function returns a usable secret or throws — it never returns "no key",
+ * because the resolved config has already stood down the Host-header guard on
+ * the strength of the promise, and a silent miss would serve an open gateway
+ * that reports itself authenticated.
+ *
+ * The key persists under `stateDir` so a restart does not un-pair every client
+ * that stored it (the iOS app keeps it in its keychain). No `stateDir` means
+ * nothing durable to write, so the key is ephemeral per run — the banner says
+ * so. This is the gateway's own operator secret and nothing else: Anthropic
+ * credentials never pass through here (root CLAUDE.md, auth red lines).
+ */
+type MaterializedAuthKey = {
+  key: string; /** 'stored' reused the file, 'created' wrote a new one, 'ephemeral' had nowhere to write. */
+  source: 'stored' | 'created' | 'ephemeral'; /** Where the key lives, or null when ephemeral. */
+  path: string | null;
+};
+declare function materializeAuthKey(stateDir: string | null, options?: {
+  warn?: (message: string) => void;
+}): Promise<MaterializedAuthKey>;
+//#endregion
+//#region src/login-page.d.ts
+/**
+ * The login page is the CLI's, not the dashboard's. That split is deliberate:
+ * the SPA ships prebuilt and is also served straight from vite in dev, so making
+ * it aware of an auth scheme that only exists in the turnkey instance would
+ * couple two things that are otherwise independent. An unauthenticated document
+ * request gets this instead of index.html; nothing in the SPA changes.
+ *
+ * Self-contained by necessity — it renders before any bundled asset is worth
+ * fetching, and it must not depend on the app it is gating.
+ */
+type LoginPageOptions = {
+  /** Where the form POSTs. Comes from the auth module, not hardcoded here. */action: string; /** Form field name carrying the secret. */
+  field: string; /** Shown when a previous attempt failed. */
+  error?: string; /** Where to send the browser after a successful login. */
+  redirectTo?: string; /** Field name carrying the post-login redirect. */
+  redirectField?: string;
+};
+declare function renderLoginPage(options: LoginPageOptions): string;
+//#endregion
+export { type CliAuth, type CliAuthOptions, type CliFlags, type CliPrincipal, ConfigError, type Instance, type LoadedConfig, type LoginPageOptions, type MaterializedAuthKey, type ResolvedConfig, type WorkerDeckConfig, createCliAuth, createHostGuard, defaultStateDir, hostnameOf, isLoopback, isLoopbackHostname, loadConfigFile, materializeAuthKey, parseArgs, renderLoginPage, resolveInstanceConfig, resolveWebRoot, runGuard, startInstance };
+//# sourceMappingURL=index.d.mts.map

package/build/index.mjs

@@ -0,0 +1,3 @@
+import { n as runGuard } from "./guard-D3VN855w.mjs";
+import { a as ConfigError, c as isLoopback, d as parseArgs, f as resolveInstanceConfig, i as renderLoginPage, l as isLoopbackHostname, m as materializeAuthKey, n as resolveWebRoot, o as defaultStateDir, p as createCliAuth, r as startInstance, s as hostnameOf, t as createHostGuard, u as loadConfigFile } from "./instance-kupxU5UD.mjs";
+export { ConfigError, createCliAuth, createHostGuard, defaultStateDir, hostnameOf, isLoopback, isLoopbackHostname, loadConfigFile, materializeAuthKey, parseArgs, renderLoginPage, resolveInstanceConfig, resolveWebRoot, runGuard, startInstance };