workerdeck 0.0.0 → 0.7.0

package/build/index.d.mts

@@ -0,0 +1,453 @@
+import { Authenticator, WorkerServer, WorkerServerOptions } from "@workerdeck/server";
+import { KeyObject } from "node:crypto";
+import { IncomingMessage, ServerResponse } from "node:http";
+import { ProfileInfo, SessionNotification } from "@workerdeck/protocol";
+
+//#region src/apns/client.d.ts
+/**
+ * A minimal APNs provider client: an HTTP/2 POST carrying an ES256 JWT.
+ *
+ * Hand-rolled rather than a dependency, because that is the whole of the
+ * protocol and the published CLI's zero-runtime-dep posture is worth more than
+ * the eighty lines. Note `fetch`/undici will not do: it does not speak HTTP/2,
+ * and APNs accepts nothing else — hence `node:http2` directly.
+ *
+ * Token authentication, not certificates: one `.p8` serves every app in the team
+ * and both environments, and it does not expire. Certificates are per-app,
+ * per-environment, and expire annually.
+ */
+type ApnsEnvironment = 'development' | 'production';
+type ApnsConfig = {
+  /** Path to the `.p8`. A path, never the contents — a secret pasted into a
+   * config file is a secret in every backup of that file. */
+  keyFile: string; /** The 10-character Key ID shown beside the key in the developer portal. */
+  keyId: string; /** The 10-character Team ID from the top right of the portal. */
+  teamId: string; /** The APNs topic, which is the app's bundle id (`bi.atomic.workerdeck.ios`). */
+  topic: string;
+  /** Environment for a device that registered without naming one. Devices that
+   * do name one are always routed by their own answer — see the note on
+   * `ApnsEnvironment` below. */
+  production?: boolean;
+};
+type ApnsRequest = {
+  deviceToken: string;
+  environment: ApnsEnvironment;
+  payload: unknown; /** 10 for something a person is waiting on, 5 for everything else. */
+  priority?: 5 | 10; /** Unix seconds after which Apple stops trying. 0 means "one attempt". */
+  expiration?: number;
+  /** Later pushes with the same id replace an undelivered earlier one. Max 64
+   * bytes, so never pass a raw identifier of unbounded length. */
+  collapseId?: string;
+};
+type ApnsResult = {
+  ok: true;
+  apnsId?: string;
+} | {
+  ok: false;
+  status: number;
+  reason: string;
+  /** The token is dead: drop it from the registry rather than retrying it
+   * forever. The app re-registers on its next launch anyway. */
+  unregistered: boolean;
+};
+type ApnsClient = {
+  send(request: ApnsRequest): Promise<ApnsResult>;
+  close(): void;
+};
+/**
+ * Load and sanity-check the auth key. Done once at startup rather than at the
+ * first push, so a mistyped path is a launch error with a clear message instead
+ * of a notification that silently never arrives.
+ */
+declare function loadApnsKey(keyFile: string): Promise<KeyObject>;
+declare function createApnsClient(config: ApnsConfig, key: KeyObject,
+/** Test seam: point the two environments at a local HTTP/2 server. Nothing in
+ * production should pass this — the real endpoints are not configurable, and
+ * an operator who could redirect them could exfiltrate every push. */
+
+options?: {
+  hosts?: Record<ApnsEnvironment, string>;
+}): ApnsClient;
+//#endregion
+//#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;
+  /**
+   * Forward session notifications to Apple Push Notification service, for the
+   * iOS app. Absent turns the forwarder off entirely — including its
+   * `/apns/devices` route, so a gateway without this answers 404 there and the
+   * app quietly stops asking.
+   *
+   * Lives here rather than in `packages/server` on purpose: this is the only
+   * place in the project that holds a push credential, and the OSS gateway
+   * stays credential-free. `keyFile` is a path, never key contents.
+   */
+  apns?: ApnsConfig;
+};
+type CliFlags = {
+  config?: string;
+  port?: number;
+  host?: string;
+  authKey?: string;
+  profiles: ProfileInfo[];
+  cwdRoots: string[];
+  fsRoots: string[];
+  fsWrite?: boolean;
+  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;
+  /** APNs forwarder settings with `keyFile` made absolute, or undefined for an
+   * instance that does not push. */
+  apns?: ApnsConfig;
+  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
+//#region src/apns/devices.d.ts
+/**
+ * The device-token registry, and the route that fills it.
+ *
+ * This has to live *somewhere*, and the point of the webhooks-first decision is
+ * that it is not `packages/server`: the OSS gateway stays credential-free and
+ * knows nothing about APNs. So the turnkey CLI mounts its own route through the
+ * server's `fallback` hook — the same seam that serves the dashboard — and
+ * registration lands on the gateway's own origin, behind the auth key that
+ * already guards everything else.
+ *
+ * Storage is a JSON file under the state dir with the same 0600 posture as
+ * `auth-key`. Device tokens are not secrets in the way an auth key is, but they
+ * are a list of which phones belong to the operator, and there is no reason for
+ * every user on the machine to read it.
+ */
+type DeviceRecord = {
+  /** Hex APNs device token. */token: string;
+  environment: ApnsEnvironment;
+  /**
+   * Opaque to us: the client's own id for this gateway, echoed back in every
+   * payload. It is what lets an app configured with two gateways tell which one
+   * woke it — we store the string and never interpret it.
+   */
+  hostId?: string;
+  bundleId?: string;
+  platform?: string;
+  updatedAt: number;
+};
+type DeviceRegistry = {
+  list(): DeviceRecord[];
+  register(record: Omit<DeviceRecord, 'updatedAt'>): Promise<void>;
+  remove(token: string): Promise<void>;
+};
+/**
+ * `dir` null keeps the registry in memory: a restart then forgets every token,
+ * which is survivable because the app re-registers on launch, but it does mean
+ * an instance with no state dir goes quiet until each phone is next opened.
+ */
+declare function createDeviceRegistry(options: {
+  dir: string | null;
+  onError?: (error: unknown, context: {
+    op: string;
+    path: string;
+  }) => void;
+}): Promise<DeviceRegistry>;
+/**
+ * `POST /apns/devices` to register a token, `DELETE /apns/devices` to drop one.
+ * Returns true when it consumed the request.
+ *
+ * Deliberately outside `/v1`: this is the forwarder's own surface, not part of
+ * the protocol `packages/protocol` defines, and a client that finds a 404 here
+ * has simply reached a gateway running without push configured.
+ *
+ * DELETE exists so removing a gateway from the app can stop its pushes. Without
+ * it a forgotten server keeps buzzing a phone that no longer has any way to act
+ * on what it says.
+ */
+declare function createDeviceRoute(registry: DeviceRegistry, authenticate: (req: IncomingMessage) => unknown): (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+//#endregion
+//#region src/apns/forwarder.d.ts
+type ApnsForwarder = {
+  /** Hand to `createWorkerServer({ notifications: { onNotification } })`. */onNotification: (notification: SessionNotification) => void; /** Mount ahead of the static host; true when it consumed the request. */
+  handleRequest: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>; /** How many devices are registered, for the startup banner. */
+  deviceCount: () => number;
+  close: () => void;
+};
+/**
+ * Build the push for one notification.
+ *
+ * The payload carries routing and nothing else — `sessionId` to deep-link,
+ * `requestId` because a lock-screen Approve has nothing to POST to without it,
+ * and `hostId` so a client with two gateways knows which one this came from.
+ * Everything else the app fetches over REST the moment it opens; a transcript
+ * has no business in a 4 KB envelope.
+ */
+declare function buildPush(notification: SessionNotification, hostId: string | undefined): Omit<ApnsRequest, 'deviceToken' | 'environment'>;
+declare function createApnsForwarder(options: {
+  config: ApnsConfig; /** Where the device registry is persisted; null keeps it in memory. */
+  stateDir: string | null; /** Guards `/apns/devices` — the instance's own `authenticate`. */
+  authenticate: (req: IncomingMessage) => unknown;
+  warn?: (message: string) => void;
+}): Promise<ApnsForwarder>;
+//#endregion
+export { type ApnsClient, type ApnsConfig, type ApnsEnvironment, type ApnsForwarder, type ApnsRequest, type ApnsResult, type CliAuth, type CliAuthOptions, type CliFlags, type CliPrincipal, ConfigError, type DeviceRecord, type DeviceRegistry, type Instance, type LoadedConfig, type LoginPageOptions, type MaterializedAuthKey, type ResolvedConfig, type WorkerDeckConfig, buildPush, createApnsClient, createApnsForwarder, createCliAuth, createDeviceRegistry, createDeviceRoute, createHostGuard, defaultStateDir, hostnameOf, isLoopback, isLoopbackHostname, loadApnsKey, 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 { _ as createDeviceRegistry, a as ConfigError, b as loadApnsKey, c as isLoopback, d as parseArgs, f as resolveInstanceConfig, g as createApnsForwarder, h as buildPush, 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, v as createDeviceRoute, y as createApnsClient } from "./instance-DbIqlX-e.mjs";
+export { ConfigError, buildPush, createApnsClient, createApnsForwarder, createCliAuth, createDeviceRegistry, createDeviceRoute, createHostGuard, defaultStateDir, hostnameOf, isLoopback, isLoopbackHostname, loadApnsKey, loadConfigFile, materializeAuthKey, parseArgs, renderLoginPage, resolveInstanceConfig, resolveWebRoot, runGuard, startInstance };