@celestea/studio 2.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mcd0LUO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/app.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Hono application factory — P4.
+ *
+ * Wiring order is contract order:
+ *   1. compose the studio context (store plugins + bus + injected runtime);
+ *   2. register all 39 contract endpoints and assert full coverage;
+ *   3. `/api/*` fallback = 404 JSON (an unknown API path must NEVER fall
+ *      through to the static/SPA handler);
+ *   4. static files + SPA fallback from the read-only Vite build.
+ *
+ * The engine is injected: `opts.runtime` is a `RuntimeAdapter` (or a factory
+ * over the composed stores, which is what the REAL adapter needs to resolve
+ * session directories AND the provider target). With nothing injected the app
+ * mounts the real runtime (`runtime/`) wired to the real LLM, so the default
+ * deployment is the engine over a live provider, not a fake; the P4 fake stays
+ * available to tests through `harness.test-util.ts`.
+ *
+ * W743 (W732 A1): the engine assembly itself lives in `createStudioEngine()`
+ * below — the ONE factory — and `defaultRuntime()` is just the production
+ * binding of its injected values. The real-engine test harness
+ * (`runtime/test-util.ts`) calls the same function, so "the tests run the real
+ * engine" now also means "the tests run the real grants boundary and the real
+ * usage ledger".
+ */
+import { Hono } from "hono";
+import type { Llm } from "@celestea/core";
+import { type Profile } from "@celestea/runtime";
+import { type RegisteredRoute } from "./routes.js";
+import { type StudioConfig } from "./config.js";
+import { type EngineFactory, type StudioServices } from "./plugins.js";
+import type { EngineProfile, RuntimeAdapter } from "./runtime-adapter.js";
+import type { StoreServices } from "./plugins.js";
+import type { DisclosureOptions } from "./runtime/engine-plugins.js";
+export interface StudioAppOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    config?: StudioConfig;
+    /** Engine seam (or a factory over the stores); defaults to the REAL runtime. */
+    runtime?: RuntimeAdapter | EngineFactory;
+    /** Deterministic clock for session dir suffixes / trash stamps. */
+    now?: () => number;
+}
+export interface StudioApp {
+    app: Hono;
+    routes: RegisteredRoute[];
+    services: StudioServices;
+    /** Contract ids bound by handlers (39 on success). */
+    endpointIds: string[];
+}
+/**
+ * Everything ONE engine build needs, resolved from the composed stores.
+ *
+ * W743 (closes W732 A1): this is the SINGLE engine assembly. The production app
+ * and the real-engine test harness both call it, so the two can no longer drift
+ * apart — the only thing a caller injects is PATHS, ENV and the LLM/profile
+ * seam; grants, the usage ledger, the worker receipt dir, session resolution and
+ * the three per-session profile hooks are assembled here exactly once.
+ *
+ * Note on placement: the factory cannot live in `packages/runtime` because it
+ * builds the HOST's adapter (`real-runtime-adapter.ts`, an L3 module) and needs
+ * the composed stores — `packages/*` must never depend on `apps/*`
+ * (ARCHITECTURE.md §1, K1/K2). It therefore stays in the L3 composition root and
+ * every other assembly (tests included) reuses THIS function.
+ *
+ * The dependency is a FUNCTION of `stores` because the engine factory runs
+ * INSIDE `composeStudio`: the test harness only learns its throwaway data dir
+ * once the workspace it registered is mounted.
+ */
+export interface StudioEngineInput {
+    /** The data file the host ACTUALLY composed (`<data dir>/workspaces.json`). */
+    workspacesFile: string;
+    /** Process environment (provider keys, tool roots, resource caps, grants). */
+    env: NodeJS.ProcessEnv;
+    /** Startup engine profile. */
+    profile: EngineProfile;
+    /** Provider row the profile came from, recorded as the ledger's `provider`. */
+    providerLabel: string | null;
+    /** Late-bound host services (per-session prompt assembly; see [HostRef]). */
+    host: HostRef;
+    /**
+     * W806 (P0): explicit dynamic-disclosure activation for the composed
+     * sessions. Absent = the static mode baseline (the default face).
+     */
+    disclosure?: DisclosureOptions;
+    /**
+     * LLM seam override. Absent = the live provider assembled from the profile
+     * (production); the real-engine tests inject the deterministic OFFLINE engine.
+     */
+    llm?: (profile: Profile) => Llm;
+}
+/** Resolves the injected values of one engine build from the composed stores. */
+export type StudioEngineDeps = (stores: StoreServices) => StudioEngineInput;
+/**
+ * The ONE engine factory. The factory form is what makes the production path
+ * possible — providers.json is composed before the engine, so the startup
+ * profile is resolved from the operator's provider registry — and it is also
+ * what the test harness reuses. Worker receipts land under
+ * `<data dir>/worker-results`.
+ */
+export declare function createStudioEngine(deps: StudioEngineDeps): EngineFactory;
+/**
+ * W729: the host services exist only AFTER `composeStudio` ran, but the engine
+ * factory runs INSIDE it (the adapter is built while the stores are mounted).
+ * The per-session prompt hook is therefore late-bound through this ref; it is
+ * only ever called while composing a NAMED session, which happens on the first
+ * turn / activate — long after startup filled the ref in.
+ */
+export interface HostRef {
+    services: StudioServices | null;
+}
+export declare function createStudioApp(opts?: StudioAppOptions): StudioApp;

package/dist/app.js

@@ -0,0 +1,219 @@
+/**
+ * Hono application factory — P4.
+ *
+ * Wiring order is contract order:
+ *   1. compose the studio context (store plugins + bus + injected runtime);
+ *   2. register all 39 contract endpoints and assert full coverage;
+ *   3. `/api/*` fallback = 404 JSON (an unknown API path must NEVER fall
+ *      through to the static/SPA handler);
+ *   4. static files + SPA fallback from the read-only Vite build.
+ *
+ * The engine is injected: `opts.runtime` is a `RuntimeAdapter` (or a factory
+ * over the composed stores, which is what the REAL adapter needs to resolve
+ * session directories AND the provider target). With nothing injected the app
+ * mounts the real runtime (`runtime/`) wired to the real LLM, so the default
+ * deployment is the engine over a live provider, not a fake; the P4 fake stays
+ * available to tests through `harness.test-util.ts`.
+ *
+ * W743 (W732 A1): the engine assembly itself lives in `createStudioEngine()`
+ * below — the ONE factory — and `defaultRuntime()` is just the production
+ * binding of its injected values. The real-engine test harness
+ * (`runtime/test-util.ts`) calls the same function, so "the tests run the real
+ * engine" now also means "the tests run the real grants boundary and the real
+ * usage ledger".
+ */
+import { Hono } from "hono";
+import { dirname, join } from "node:path";
+import { createUsageLedgerFile } from "@celestea/runtime";
+import { API_ENDPOINT_COUNT, routeTable } from "./routes.js";
+import { loadStudioConfig } from "./config.js";
+import { apiTokenMiddleware, registerTokenBootstrap } from "./auth/api-token.js";
+import { composeStudio } from "./plugins.js";
+import { registerHandlers } from "./handlers/index.js";
+import { assembleSystemPromptFor } from "./handlers/config-shape.js";
+import { registerStatic } from "./static.js";
+import { DEFAULT_SESSION_MODE } from "./store/mode.js";
+import { sessionWorkspaceOf } from "./store/sessions.js";
+import { readSessionMeta } from "./store/session-meta.js";
+import { createSessionGrants } from "./runtime/session-grants.js";
+import { grantsEnv } from "./store/grants-service.js";
+import { createRealRuntimeAdapter, startupEngineProfile } from "./runtime/index.js";
+import { recoverActiveSessionOnBoot } from "./runtime/boot-recovery.js";
+import { RecoveryAuditWriter } from "./runtime/recovery-audit.js";
+import { observeWorkerTableOnBoot } from "./runtime/worker-recovery.js";
+import { workerTablePath } from "./runtime/worker-table.js";
+/**
+ * The ONE engine factory. The factory form is what makes the production path
+ * possible — providers.json is composed before the engine, so the startup
+ * profile is resolved from the operator's provider registry — and it is also
+ * what the test harness reuses. Worker receipts land under
+ * `<data dir>/worker-results`.
+ */
+export function createStudioEngine(deps) {
+    return (stores) => {
+        const input = deps(stores);
+        const dataDir = dirname(input.workspacesFile);
+        const resultsDir = join(dataDir, "worker-results");
+        return createRealRuntimeAdapter({
+            // E §2.3 P0 ①: the studio's OWN table — never the DSH fleet's (R2-1/B6).
+            workerRegistryPath: workerTablePath({ env: input.env, dataDir }),
+            // W787 (§5.2③): the audit channel of a degraded session log. The BOOT
+            // observer builds its own writer on the same append-only file (the two
+            // lines are written at different moments and never interleave a record).
+            recoveryAudit: new RecoveryAuditWriter({ dataDir, env: input.env }),
+            profile: input.profile,
+            env: input.env,
+            resultsDir,
+            // W516: every instance reads its session's grants at compose time. The env
+            // is pinned to the workspaces file the host ACTUALLY composed, so the
+            // fail-closed root rules resolve the same data dir (grants-service.ts).
+            grants: createSessionGrants({ dataDir, env: grantsEnv(input.env, input.workspacesFile) }),
+            // W728 §3 P0: ONE append-only usage ledger per process (`<data dir>`),
+            // shared by every session instance; `CELESTEA_USAGE_LEDGER=off` disables.
+            ledgerFile: createUsageLedgerFile({ dataDir, env: input.env }),
+            // E §4 P1 (W785): `fallbacks.json` + `fallbacks-audit.jsonl` live next to
+            // the ledger, so the fallback wiring needs the same data dir.
+            dataDir,
+            providerLabel: input.providerLabel,
+            ...(input.disclosure === undefined ? {} : { disclosure: input.disclosure }),
+            ...(input.llm === undefined ? {} : { llm: input.llm }),
+            resolveSession: (id) => {
+                const resolved = stores.sessions.resolve(id);
+                // W768: the workspace travels with the session target, so the tools'
+                // cwd/root and the prompt's `{{workspace}}` come from THIS resolution.
+                return resolved.ok
+                    ? { sessionId: id, dir: resolved.value.dir, workspace: sessionWorkspaceOf(resolved.value) }
+                    : null;
+            },
+            // W513: the session-level model override is applied to that session's own
+            // instance (it no longer rewrites a global engine profile).
+            sessionModel: (id) => sessionMetaAt(stores, id)?.model ?? null,
+            // W729 (§5.1 #4, R3): the session's mode is fixed at creation and the
+            // PROMPT assembly is therefore per instance, not per process. Both hooks
+            // read `session.json` of the session being composed, so a standard and an
+            // execution session in the same process get their own system prompt.
+            sessionMode: (id) => sessionMetaAt(stores, id)?.mode ?? null,
+            sessionSystemPrompt: (id) => sessionPromptAt(input.host, id),
+            // W804: the OPTIMISTIC per-model modality gate. null = the model is not
+            // configured anywhere => allow image input (the section 7.6 downgrade is
+            // the fallback for a wrong guess); a configured row without "image" is the
+            // only thing that disables the read_image gate.
+            modelInputModalities: (modelId) => {
+                for (const provider of stores.providers.rows()) {
+                    const model = provider.models.find((m) => m.id === modelId);
+                    if (model !== undefined)
+                        return model.input_modalities ?? null;
+                }
+                return null;
+            },
+        });
+    };
+}
+/** The production engine: [createStudioEngine] over the REAL provider registry. */
+function defaultRuntime(config, env, host) {
+    return createStudioEngine((stores) => {
+        const startup = startupEngineProfile(stores.providers, env, config.apiKeyEnv);
+        return {
+            workspacesFile: config.paths.workspacesFile,
+            env,
+            profile: startup.profile,
+            providerLabel: startup.target.provider_id,
+            host,
+        };
+    });
+}
+/** `session.json` of one session (null when the id does not resolve). */
+function sessionMetaAt(stores, id) {
+    const resolved = stores.sessions.resolve(id);
+    return resolved.ok ? readSessionMeta(resolved.value.dir) : null;
+}
+/**
+ * W729/K8: every named session's prompt is assembled for THAT session. A session
+ * without `session.json.mode` gets the DEFAULT (standard) mode's text — the
+ * pre-W729 behaviour for the mode dimension — and its **own** identity variables.
+ *
+ * W768 (amends K8's "keeps the primed base prompt"): the primed base prompt was
+ * assembled ONCE at startup against whichever session was active then, so every
+ * other session received a prompt naming a workspace it is not in. With the
+ * tools now running in the session's own workspace, inheriting another session's
+ * prompt is precisely the "prompt says A, `pwd` says B" bug — so the assembly is
+ * per session for ALL sessions, and the mode gate no longer decides it.
+ */
+function sessionPromptAt(host, id) {
+    if (host.services === null)
+        return null;
+    return assembleSystemPromptFor(host.services, id);
+}
+/** Every contract endpoint must be bound exactly once, or startup fails. */
+function assertCoverage(routes, ids) {
+    const bound = new Set(ids);
+    const missing = routes.filter((r) => !bound.has(r.id)).map((r) => r.id);
+    if (missing.length > 0)
+        throw new Error(`unbound contract endpoints: ${missing.join(", ")}`);
+    if (ids.length !== API_ENDPOINT_COUNT) {
+        throw new Error(`expected ${API_ENDPOINT_COUNT} contract endpoints, got ${ids.length}`);
+    }
+}
+/**
+ * Hand the engine the BASE system prompt the HOST assembles (prompt registry +
+ * settings override). The retired backend did this inside `build_gen`; here the engine is
+ * primed once at startup and the next composed generation picks it up.
+ *
+ * W729: this primes the DEFAULT (detached) generation only. A named session's
+ * prompt is assembled per instance through the composer's `sessionSystemPrompt`
+ * hook, so priming can never leak one session's mode into another's instance.
+ */
+function primeEnginePrompt(services, env) {
+    // The BASE (detached) generation is always the DEFAULT mode, whatever mode the
+    // session left active in workspaces.json happens to declare.
+    //
+    // W782: `env` is threaded through so the primed prompt states the unit name
+    // this process's own environment declares, not a compile-time guess.
+    services.runtime.primeSystemPrompt?.(assembleSystemPromptFor(services, null, DEFAULT_SESSION_MODE, env));
+}
+export function createStudioApp(opts = {}) {
+    const env = opts.env ?? process.env;
+    const config = opts.config ?? loadStudioConfig({ cwd: opts.cwd, env });
+    // Filled in right after composition; the engine reads it lazily (see HostRef).
+    const host = { services: null };
+    const runtime = opts.runtime ?? defaultRuntime(config, env, host);
+    const services = composeStudio({ config, runtime, env, now: opts.now });
+    host.services = services;
+    const table = routeTable();
+    const app = new Hono();
+    // H-security: a configured token gates every /api/* request except
+    // /api/health. No token = the historical nginx-delegated path, unchanged
+    // (the listener is loopback; a non-loopback bind is refused in server.ts).
+    if (config.authToken !== null) {
+        app.use("/api/*", apiTokenMiddleware(config.authToken));
+        // The browser never sends an Authorization header; this one-shot bootstrap
+        // sets the HttpOnly cookie the middleware also accepts. Registered BEFORE
+        // registerStatic's catch-all.
+        registerTokenBootstrap(app, config.authToken);
+    }
+    primeEnginePrompt(services, env);
+    // W787 (§5.2③): the ONE boot audit channel — the checkpoint repair and the
+    // worker-table observation both report into `<data dir>/recovery-audit.jsonl`.
+    const bootAudit = new RecoveryAuditWriter({ dataDir: dirname(config.paths.workspacesFile), env });
+    // E §1.3 P0 ③: close the turn the previous process died inside — BEFORE any
+    // instance of the active session is composed, because composing one replays the
+    // log and takes its turn counter from it. A clean log, a missing checkpoint or
+    // an unresolvable active session are all no-ops (fail-safe).
+    recoverActiveSessionOnBoot({ workspaces: services.workspaces, sessions: services.sessions, audit: bootAudit });
+    // E §2.3 P0 ③: OBSERVE the persisted worker table (dead owner / missing host
+    // session) and record it. Never re-dispatch: that is P2, behind an explicit
+    // switch, and it needs the tool side-effect table first (§5.1).
+    const dataDir = dirname(config.paths.workspacesFile);
+    observeWorkerTableOnBoot({
+        path: workerTablePath({ env, dataDir }),
+        knownHost: (sid) => services.sessions.resolve(sid).ok,
+        resultsDir: join(dataDir, "worker-results"),
+        audit: bootAudit,
+    });
+    const endpointIds = registerHandlers(app, services, table);
+    assertCoverage(table.routes, endpointIds);
+    // Unknown API paths are 404 JSON, never the SPA (frozen static contract).
+    app.all("/api/*", (c) => c.json({ error: "not found" }, 404));
+    registerStatic(app, config.paths.staticRoot);
+    return { app, routes: table.routes, services, endpointIds };
+}

package/dist/auth/api-token.d.ts

@@ -0,0 +1,76 @@
+/**
+ * H-security — the minimal self-contained API token (fail-closed).
+ *
+ * Why this exists: `handlers/auth.ts` delegates the browser gate to nginx
+ * (`auth_request` -> `/auth/check`), and the backend is deliberately reachable
+ * from localhost with no cookie. That is safe ONLY while the listener is on the
+ * loopback. The CLI's `--bind` can move it to `0.0.0.0`, where the SAME backend
+ * exposes `POST /api/exec` (arbitrary shell as this user), `GET /api/fs/list`
+ * (any directory) and every agent endpoint to anyone who can reach the port.
+ *
+ * Rules, all "never silently allow":
+ *   1. a NON-loopback bind is REFUSED unless a token is configured;
+ *   2. when a token IS configured, every `/api/*` request except `/api/health`
+ *      must present it — as `Authorization: Bearer`, `x-celestea-token`, or the
+ *      cookie `GET /auth/token?token=…` sets — else 401.
+ *
+ * The browser problem (why the cookie exists): a browser never sends an
+ * `Authorization` header, so a token-only gate leaves the UI unusable (every
+ * fetch 401). `/auth/token` is the standard one-shot bootstrap: a correct token
+ * sets an HttpOnly cookie and 302s to `/`; the middleware then accepts the
+ * cookie. The cookie value is an HMAC of the token, never the plaintext token,
+ * so the raw secret is not stored client-side.
+ *
+ * The loopback path is untouched (no token -> no middleware, no bootstrap), so
+ * the existing nginx deployment and every existing test keep working.
+ */
+import type { Hono, MiddlewareHandler } from "hono";
+/** Env var carrying the token (the `--token` flag overrides it). */
+export declare const ENV_AUTH_TOKEN = "CELESTEA_AUTH_TOKEN";
+/** The token header (in addition to `Authorization: Bearer <token>`). */
+export declare const AUTH_TOKEN_HEADER = "x-celestea-token";
+/** The one API path that stays public (liveness probes, the UI's boot check). */
+export declare const AUTH_EXEMPT_PATH = "/api/health";
+/** The browser bootstrap path (NOT under /api, so the token gate never blocks it). */
+export declare const AUTH_TOKEN_PATH = "/auth/token";
+/** The HttpOnly cookie the bootstrap sets; distinct from the login cookie. */
+export declare const AUTH_TOKEN_COOKIE = "celestea_api_token";
+/** 30 days, the same lifetime the login cookie uses. */
+export declare const AUTH_TOKEN_COOKIE_MAX_AGE: number;
+/** true only for an address that cannot be reached from another host. */
+export declare function isLoopbackBind(bind: string): boolean;
+/** The configured token, or null when unset/blank. */
+export declare function readAuthToken(env?: NodeJS.ProcessEnv): string | null;
+/** The token a request presents, from either accepted header (or null). */
+export declare function presentedToken(authHeader: string | undefined, tokenHeader: string | undefined): string | null;
+/** Constant-time string comparison (a length mismatch is a plain false). */
+export declare function tokensMatch(presented: string, expected: string): boolean;
+/**
+ * The cookie value for a token. An HMAC keyed by the token, so the cookie the
+ * browser stores is NOT the raw secret (a leaked cookie does not reveal the
+ * token, and the token never appears in a page or a cookie jar verbatim).
+ */
+export declare function tokenCookieValue(token: string): string;
+/** true when the presented cookie value is this token's cookie value. */
+export declare function cookieMatches(presented: string | null | undefined, token: string): boolean;
+/** The refusal when a non-loopback bind has no token. */
+export declare class InsecureBindError extends Error {
+    readonly name = "InsecureBindError";
+    constructor(bind: string);
+}
+/** Refuse a non-loopback bind that has no token (throws [InsecureBindError]). */
+export declare function assertBindIsSafe(bind: string, token: string | null): void;
+/**
+ * The token middleware: every `/api/*` request except `/api/health` must
+ * present the token as a header OR the bootstrap cookie, else 401. `/auth/*`
+ * and the static UI are not under `/api/*` and stay reachable.
+ */
+export declare function apiTokenMiddleware(token: string): MiddlewareHandler;
+/** The `Set-Cookie` value: HttpOnly + SameSite=Strict + Path=/ (+Secure over TLS). */
+export declare function apiTokenCookie(token: string, secure: boolean): string;
+/**
+ * `GET /auth/token?token=<secret>`: correct -> set the cookie and 302 to `/`;
+ * wrong/missing -> 401 with NO cookie. Not a contract endpoint (a security-layer
+ * route, registered outside the frozen route table).
+ */
+export declare function registerTokenBootstrap(app: Hono, token: string): void;

package/dist/auth/api-token.js

@@ -0,0 +1,172 @@
+/**
+ * H-security — the minimal self-contained API token (fail-closed).
+ *
+ * Why this exists: `handlers/auth.ts` delegates the browser gate to nginx
+ * (`auth_request` -> `/auth/check`), and the backend is deliberately reachable
+ * from localhost with no cookie. That is safe ONLY while the listener is on the
+ * loopback. The CLI's `--bind` can move it to `0.0.0.0`, where the SAME backend
+ * exposes `POST /api/exec` (arbitrary shell as this user), `GET /api/fs/list`
+ * (any directory) and every agent endpoint to anyone who can reach the port.
+ *
+ * Rules, all "never silently allow":
+ *   1. a NON-loopback bind is REFUSED unless a token is configured;
+ *   2. when a token IS configured, every `/api/*` request except `/api/health`
+ *      must present it — as `Authorization: Bearer`, `x-celestea-token`, or the
+ *      cookie `GET /auth/token?token=…` sets — else 401.
+ *
+ * The browser problem (why the cookie exists): a browser never sends an
+ * `Authorization` header, so a token-only gate leaves the UI unusable (every
+ * fetch 401). `/auth/token` is the standard one-shot bootstrap: a correct token
+ * sets an HttpOnly cookie and 302s to `/`; the middleware then accepts the
+ * cookie. The cookie value is an HMAC of the token, never the plaintext token,
+ * so the raw secret is not stored client-side.
+ *
+ * The loopback path is untouched (no token -> no middleware, no bootstrap), so
+ * the existing nginx deployment and every existing test keep working.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { cookieValue } from "./token.js";
+/** Env var carrying the token (the `--token` flag overrides it). */
+export const ENV_AUTH_TOKEN = "CELESTEA_AUTH_TOKEN";
+/** The token header (in addition to `Authorization: Bearer <token>`). */
+export const AUTH_TOKEN_HEADER = "x-celestea-token";
+/** The one API path that stays public (liveness probes, the UI's boot check). */
+export const AUTH_EXEMPT_PATH = "/api/health";
+/** The browser bootstrap path (NOT under /api, so the token gate never blocks it). */
+export const AUTH_TOKEN_PATH = "/auth/token";
+/** The HttpOnly cookie the bootstrap sets; distinct from the login cookie. */
+export const AUTH_TOKEN_COOKIE = "celestea_api_token";
+/** 30 days, the same lifetime the login cookie uses. */
+export const AUTH_TOKEN_COOKIE_MAX_AGE = 30 * 24 * 60 * 60;
+/** The host part of a `host` or `host:port` bind string (IPv6 aware). */
+function hostOf(bind) {
+    const raw = bind.trim().toLowerCase();
+    if (raw.startsWith("[")) {
+        const end = raw.indexOf("]");
+        return end === -1 ? raw : raw.slice(1, end);
+    }
+    const first = raw.indexOf(":");
+    // Exactly one colon = "host:port"; two or more = a bare IPv6 literal.
+    if (first !== -1 && raw.indexOf(":", first + 1) === -1)
+        return raw.slice(0, first);
+    return raw;
+}
+/** true only for an address that cannot be reached from another host. */
+export function isLoopbackBind(bind) {
+    const host = hostOf(bind);
+    if (host === "localhost" || host === "::1" || host === "127.0.0.1")
+        return true;
+    if (host.startsWith("127."))
+        return true;
+    // IPv4-mapped IPv6 loopback (::ffff:127.0.0.1).
+    if (host.startsWith("::ffff:127."))
+        return true;
+    return false;
+}
+/** The configured token, or null when unset/blank. */
+export function readAuthToken(env = process.env) {
+    const raw = env[ENV_AUTH_TOKEN];
+    if (typeof raw !== "string")
+        return null;
+    const trimmed = raw.trim();
+    return trimmed === "" ? null : trimmed;
+}
+/** The token a request presents, from either accepted header (or null). */
+export function presentedToken(authHeader, tokenHeader) {
+    if (typeof tokenHeader === "string" && tokenHeader.trim() !== "")
+        return tokenHeader.trim();
+    if (typeof authHeader === "string") {
+        const match = /^Bearer\s+(.+)$/i.exec(authHeader.trim());
+        const value = match?.[1];
+        if (value !== undefined && value.trim() !== "")
+            return value.trim();
+    }
+    return null;
+}
+/** Constant-time string comparison (a length mismatch is a plain false). */
+export function tokensMatch(presented, expected) {
+    const a = Buffer.from(presented, "utf8");
+    const b = Buffer.from(expected, "utf8");
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+/**
+ * The cookie value for a token. An HMAC keyed by the token, so the cookie the
+ * browser stores is NOT the raw secret (a leaked cookie does not reveal the
+ * token, and the token never appears in a page or a cookie jar verbatim).
+ */
+export function tokenCookieValue(token) {
+    return createHmac("sha256", token).update("celestea-api-token-v1").digest("hex");
+}
+/** true when the presented cookie value is this token's cookie value. */
+export function cookieMatches(presented, token) {
+    if (typeof presented !== "string" || presented === "")
+        return false;
+    return tokensMatch(presented, tokenCookieValue(token));
+}
+/** The refusal when a non-loopback bind has no token. */
+export class InsecureBindError extends Error {
+    name = "InsecureBindError";
+    constructor(bind) {
+        super(`refusing to bind ${bind} without authentication: that would expose ` +
+            `POST /api/exec (arbitrary shell as this user), GET /api/fs/list (any directory) ` +
+            `and every agent endpoint to anyone who can reach the port.\n` +
+            `  Fix it one of two ways:\n` +
+            `    1. keep it local: --bind 127.0.0.1 (the default), or\n` +
+            `    2. set a token: --token <secret> (or ${ENV_AUTH_TOKEN}=<secret>) and send it as ` +
+            `'Authorization: Bearer <secret>' (or '${AUTH_TOKEN_HEADER}: <secret>') on every /api/* request.\n` +
+            `  For a browser, visit /auth/token?token=<secret> once to set the session cookie.\n` +
+            `  For the nginx login gate, put nginx in front and bind 127.0.0.1.`);
+    }
+}
+/** Refuse a non-loopback bind that has no token (throws [InsecureBindError]). */
+export function assertBindIsSafe(bind, token) {
+    if (isLoopbackBind(bind) || token !== null)
+        return;
+    throw new InsecureBindError(bind);
+}
+/**
+ * The token middleware: every `/api/*` request except `/api/health` must
+ * present the token as a header OR the bootstrap cookie, else 401. `/auth/*`
+ * and the static UI are not under `/api/*` and stay reachable.
+ */
+export function apiTokenMiddleware(token) {
+    return async (c, next) => {
+        if (c.req.path === AUTH_EXEMPT_PATH)
+            return next();
+        const presented = presentedToken(c.req.header("authorization"), c.req.header(AUTH_TOKEN_HEADER));
+        if (presented !== null && tokensMatch(presented, token))
+            return next();
+        if (cookieMatches(cookieValue(c.req.header("cookie"), AUTH_TOKEN_COOKIE), token))
+            return next();
+        return c.json({ ok: false, error: "unauthorized" }, 401);
+    };
+}
+/** The `Set-Cookie` value: HttpOnly + SameSite=Strict + Path=/ (+Secure over TLS). */
+export function apiTokenCookie(token, secure) {
+    const attrs = [`${AUTH_TOKEN_COOKIE}=${tokenCookieValue(token)}`, "Path=/", `Max-Age=${AUTH_TOKEN_COOKIE_MAX_AGE}`, "HttpOnly", "SameSite=Strict"];
+    if (secure)
+        attrs.push("Secure");
+    return attrs.join("; ");
+}
+/** `Secure` is set only when the request really arrived over TLS (nginx). */
+function isSecureRequest(c) {
+    const first = (c.req.header("x-forwarded-proto") ?? "").toLowerCase().split(",")[0];
+    return first !== undefined && first.trim() === "https";
+}
+/**
+ * `GET /auth/token?token=<secret>`: correct -> set the cookie and 302 to `/`;
+ * wrong/missing -> 401 with NO cookie. Not a contract endpoint (a security-layer
+ * route, registered outside the frozen route table).
+ */
+export function registerTokenBootstrap(app, token) {
+    app.get(AUTH_TOKEN_PATH, (c) => {
+        const presented = c.req.query("token");
+        if (presented === undefined || !tokensMatch(presented, token)) {
+            return c.json({ ok: false, error: "unauthorized" }, 401);
+        }
+        c.header("set-cookie", apiTokenCookie(token, isSecureRequest(c)));
+        return c.redirect("/", 302);
+    });
+}

package/dist/auth/htpasswd.d.ts

@@ -0,0 +1,22 @@
+/**
+ * W767 — password verification against Studio's OWN password file.
+ *
+ * `htpasswd -vbi` is used deliberately: `-b` takes the password on **stdin**
+ * (never in argv, so it cannot show up in `ps`/audit logs), `-v` verifies, `-i`
+ * reads stdin. The file is read-only input — Studio never writes it, and it is
+ * the only credential source this module knows about.
+ *
+ * The username is restricted to a conservative charset: it travels in argv, and
+ * a leading `-` or a newline must never be able to steer the helper.
+ */
+/** The verifier binary (net/httpd-tools `htpasswd`). */
+export declare const HTPASSWD_BIN = "htpasswd";
+/** Accepted username shape (argv-safe, 1..64 chars). */
+export declare const HTPASSWD_USER_RE: RegExp;
+/**
+ * `ok` = the password verified; `denied` = wrong password or unknown user (the
+ * two are deliberately indistinguishable); `error` = the helper or the file is
+ * unusable (an operator problem, never reported as a wrong password).
+ */
+export type PasswordVerdict = "ok" | "denied" | "error";
+export declare function verifyPassword(file: string, user: string, password: string): PasswordVerdict;