stageflow 0.25.0 → 0.27.0

package/dist/runtime/workspaceBinding.d.ts

@@ -0,0 +1,20 @@
+import { type LoadOutcome } from "../config/loadOutcome.js";
+export type WorkspaceBinding = {
+    kind: "repository";
+    repository: string;
+    ref: string;
+} | {
+    kind: "checkout";
+    path: string;
+} | {
+    kind: "unbound";
+};
+export type WorkspaceBindingInput = {
+    repository?: string;
+    ref?: string;
+    checkout?: string;
+};
+export type ResolveWorkspaceBindingOptions = {
+    checkoutOverride?: string;
+};
+export declare function resolveWorkspaceBinding(task: WorkspaceBindingInput, options?: ResolveWorkspaceBindingOptions): LoadOutcome<WorkspaceBinding>;

package/dist/runtime/workspaceBinding.js

@@ -0,0 +1,60 @@
+import { loadFailure, loadSuccess } from "../config/loadOutcome.js";
+const OWNER_REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+function nonEmptyTrimmed(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function isGithubOwnerRepo(repository) {
+    return OWNER_REPO_RE.test(repository);
+}
+export function resolveWorkspaceBinding(task, options) {
+    const repository = nonEmptyTrimmed(task.repository);
+    const ref = nonEmptyTrimmed(task.ref);
+    const checkoutPath = nonEmptyTrimmed(options?.checkoutOverride ?? task.checkout);
+    const hasRepositoryField = repository !== undefined;
+    if (hasRepositoryField && checkoutPath !== undefined) {
+        return loadFailure([
+            {
+                code: "task.binding_conflict",
+                message: "Task cannot declare both repository and checkout (exactly one workspace binding)",
+                category: "task",
+            },
+        ]);
+    }
+    if (hasRepositoryField && ref === undefined) {
+        return loadFailure([
+            {
+                code: "task.repository_ref_required",
+                message: "Task repository requires a non-empty ref",
+                category: "task",
+            },
+        ]);
+    }
+    if (ref !== undefined && repository === undefined) {
+        return loadFailure([
+            {
+                code: "task.ref_without_repository",
+                message: "Task ref requires repository",
+                category: "task",
+            },
+        ]);
+    }
+    if (repository !== undefined && ref !== undefined) {
+        if (!isGithubOwnerRepo(repository)) {
+            return loadFailure([
+                {
+                    code: "task.repository_invalid",
+                    message: "Task repository must be a GitHub owner/repo (e.g. acme/api); hosts and URLs are not accepted",
+                    category: "task",
+                },
+            ]);
+        }
+        return loadSuccess({ kind: "repository", repository, ref });
+    }
+    if (checkoutPath !== undefined) {
+        return loadSuccess({ kind: "checkout", path: checkoutPath });
+    }
+    return loadSuccess({ kind: "unbound" });
+}

package/dist/server/allowedHosts.d.ts

@@ -0,0 +1,19 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export type AllowedHostEntry = {
+    hostname: string;
+    port?: string;
+};
+export type AllowedHosts = {
+    entries: AllowedHostEntry[];
+};
+export declare function hostnameFromHostHeader(hostHeader: string): string;
+export declare function portFromHostHeader(hostHeader: string): string | undefined;
+export declare function isLoopbackHostname(hostname: string): boolean;
+export declare function isLoopbackRemoteAddress(addr: string | undefined): boolean;
+/** Loopback peer plus Host (and Origin, when present) — trusted local plane for ensure. */
+export declare function isTrustedLocalHttpRequest(req: IncomingMessage): boolean;
+export declare function resolveAllowedHosts(env?: NodeJS.ProcessEnv): AllowedHosts;
+export declare function isHostAllowed(allowed: AllowedHosts, hostname: string, port?: string): boolean;
+export declare function assertAllowedHttpAccess(allowed: AllowedHosts, req: IncomingMessage, res: ServerResponse, options?: {
+    requireOrigin?: boolean;
+}): boolean;

package/dist/server/allowedHosts.js

@@ -0,0 +1,179 @@
+import { isIP } from "node:net";
+function writeForbidden(res, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(403, {
+        "Content-Type": "application/json; charset=utf-8",
+        "Content-Length": Buffer.byteLength(payload),
+    });
+    res.end(payload);
+}
+export function hostnameFromHostHeader(hostHeader) {
+    if (hostHeader.startsWith("[")) {
+        const end = hostHeader.indexOf("]");
+        return end === -1 ? hostHeader : hostHeader.slice(1, end);
+    }
+    const colon = hostHeader.lastIndexOf(":");
+    if (colon > 0 && /^\d+$/.test(hostHeader.slice(colon + 1))) {
+        return hostHeader.slice(0, colon);
+    }
+    return hostHeader;
+}
+export function portFromHostHeader(hostHeader) {
+    if (hostHeader.startsWith("[")) {
+        const end = hostHeader.indexOf("]");
+        if (end === -1)
+            return undefined;
+        const rest = hostHeader.slice(end + 1);
+        if (rest.startsWith(":") && /^\d+$/.test(rest.slice(1))) {
+            return rest.slice(1);
+        }
+        return undefined;
+    }
+    const colon = hostHeader.lastIndexOf(":");
+    if (colon > 0 && /^\d+$/.test(hostHeader.slice(colon + 1))) {
+        return hostHeader.slice(colon + 1);
+    }
+    return undefined;
+}
+export function isLoopbackHostname(hostname) {
+    const h = hostname.toLowerCase();
+    if (h === "localhost" || h === "::1")
+        return true;
+    if (isIP(h) === 4) {
+        const first = Number(h.split(".")[0]);
+        return first === 127;
+    }
+    return false;
+}
+export function isLoopbackRemoteAddress(addr) {
+    if (addr === undefined || addr.length === 0)
+        return false;
+    let normalized = addr;
+    if (normalized.toLowerCase().startsWith("::ffff:")) {
+        normalized = normalized.slice(7);
+    }
+    if (normalized === "::1")
+        return true;
+    if (isIP(normalized) === 4) {
+        const first = Number(normalized.split(".")[0]);
+        return first === 127;
+    }
+    return false;
+}
+/** Loopback peer plus Host (and Origin, when present) — trusted local plane for ensure. */
+export function isTrustedLocalHttpRequest(req) {
+    const hostHeader = req.headers.host;
+    if (typeof hostHeader !== "string" || hostHeader.length === 0)
+        return false;
+    if (!isLoopbackHostname(hostnameFromHostHeader(hostHeader)))
+        return false;
+    const origin = req.headers.origin;
+    if (typeof origin === "string" && origin.length > 0) {
+        try {
+            const originUrl = new URL(origin);
+            if (!isLoopbackHostname(originUrl.hostname))
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return isLoopbackRemoteAddress(req.socket?.remoteAddress);
+}
+export function resolveAllowedHosts(env = process.env) {
+    const raw = env.STAGEFLOW_ALLOWED_HOSTS;
+    const entries = [
+        { hostname: "localhost" },
+        { hostname: "127.0.0.1" },
+        { hostname: "::1" },
+    ];
+    if (raw === undefined || raw.trim() === "") {
+        return { entries };
+    }
+    for (const part of raw.split(",")) {
+        const token = part.trim();
+        if (token.length === 0)
+            continue;
+        if (token === "*") {
+            throw new Error("STAGEFLOW_ALLOWED_HOSTS must not contain '*'; list explicit hostnames instead.");
+        }
+        const parsed = parseAllowedHostEntry(token);
+        if (!entries.some((e) => e.hostname === parsed.hostname &&
+            (e.port ?? "") === (parsed.port ?? ""))) {
+            entries.push(parsed);
+        }
+    }
+    return { entries };
+}
+function parseAllowedHostEntry(token) {
+    if (token.startsWith("[")) {
+        const end = token.indexOf("]");
+        if (end === -1) {
+            throw new Error(`Invalid STAGEFLOW_ALLOWED_HOSTS entry: ${token}`);
+        }
+        const hostname = token.slice(1, end).toLowerCase();
+        const rest = token.slice(end + 1);
+        if (rest.length === 0)
+            return { hostname };
+        if (rest.startsWith(":") && /^\d+$/.test(rest.slice(1))) {
+            return { hostname, port: rest.slice(1) };
+        }
+        throw new Error(`Invalid STAGEFLOW_ALLOWED_HOSTS entry: ${token}`);
+    }
+    const colon = token.lastIndexOf(":");
+    if (colon > 0 && /^\d+$/.test(token.slice(colon + 1))) {
+        return {
+            hostname: token.slice(0, colon).toLowerCase(),
+            port: token.slice(colon + 1),
+        };
+    }
+    return { hostname: token.toLowerCase() };
+}
+export function isHostAllowed(allowed, hostname, port) {
+    const h = hostname.toLowerCase();
+    if (isLoopbackHostname(h))
+        return true;
+    for (const entry of allowed.entries) {
+        if (entry.hostname !== h)
+            continue;
+        if (entry.port === undefined)
+            return true;
+        if (port !== undefined && entry.port === port)
+            return true;
+    }
+    return false;
+}
+export function assertAllowedHttpAccess(allowed, req, res, options = {}) {
+    const hostHeader = req.headers.host;
+    if (typeof hostHeader !== "string" || hostHeader.length === 0) {
+        writeForbidden(res, { error: "Forbidden host" });
+        return false;
+    }
+    const hostname = hostnameFromHostHeader(hostHeader);
+    const port = portFromHostHeader(hostHeader);
+    if (!isHostAllowed(allowed, hostname, port)) {
+        writeForbidden(res, { error: "Forbidden host", host: hostname });
+        return false;
+    }
+    const origin = req.headers.origin;
+    if (typeof origin === "string" && origin.length > 0) {
+        try {
+            const originUrl = new URL(origin);
+            const originHost = originUrl.hostname;
+            const originPort = originUrl.port || undefined;
+            if (!isHostAllowed(allowed, originHost, originPort)) {
+                writeForbidden(res, { error: "Forbidden origin", host: originHost });
+                return false;
+            }
+        }
+        catch {
+            writeForbidden(res, { error: "Forbidden origin" });
+            return false;
+        }
+    }
+    else if (options.requireOrigin) {
+        writeForbidden(res, { error: "Origin required" });
+        return false;
+    }
+    return true;
+}

package/dist/server/bootstrap.d.ts

@@ -3,9 +3,13 @@ import type { AgentPort } from "../agent/port.js";
 import type { ProviderAuthContext } from "../agent/providerAuth.js";
 import { type RunStoreKind } from "../runstore/createStore.js";
 import type { RunStore } from "../runstore/port.js";
+import type { StoreFilesystemClassification } from "../runstore/storeFilesystem.js";
 import { RunManager } from "../runtime/runManager.js";
 import { type RunChangeBus } from "../runtime/runChangeBus.js";
 import { type McpHttpHandler } from "../mcp/server.js";
+import { type HostConfig } from "../config/hostConfig.js";
+import { bootProviderConfig } from "../agent/bootProviderConfig.js";
+export declare const DEFAULT_GC_INTERVAL_MS: number;
 export type StageflowHostOptions = {
     agent: AgentPort;
     cwd?: string;
@@ -17,6 +21,10 @@ export type StageflowHostOptions = {
     providerAuthContext?: ProviderAuthContext;
     mcpStateless?: boolean;
     runChangeBus?: RunChangeBus;
+    env?: NodeJS.ProcessEnv;
+    hostConfig?: HostConfig;
+    /** Skip HostConfig load (tests that inject store/manager pieces only). */
+    skipHostConfig?: boolean;
 };
 export type StageflowHostBootstrap = {
     a2a?: A2aHost;
@@ -24,11 +32,37 @@ export type StageflowHostBootstrap = {
     agentDir: string;
     rootDir: string;
     isGitProject: boolean;
-    store: RunStore;
-    manager: RunManager;
+    /** Absent when `serveBlocked` — store must not be opened after a failed restore. */
+    store?: RunStore;
+    /** Absent when `serveBlocked` — no RunManager lifecycle/resume. */
+    manager?: RunManager;
     runChangeBus: RunChangeBus;
     mcpStateless: boolean;
     providerAuthContext: ProviderAuthContext | undefined;
     mcpHandler: McpHttpHandler;
+    hostConfig?: HostConfig;
+    providerBoot?: Awaited<ReturnType<typeof bootProviderConfig>>;
+    /** Periodic retention GC handle when enabled; already `.unref()`'d. */
+    gcInterval?: NodeJS.Timeout;
+    stopGcInterval: () => void;
+    /** Filesystem classification for `$STAGEFLOW_HOME` (Slot 8). */
+    storeFilesystem?: StoreFilesystemClassification;
+    /**
+     * When set, Host must not serve API/MCP (restore.failed or failed boot apply).
+     * /livez still answers; /readyz fails.
+     */
+    serveBlocked?: {
+        code: string;
+        reason: string;
+    };
 };
+/** Parse `STAGEFLOW_GC_INTERVAL_MS`; default 1h; `0` disables. */
+export declare function gcIntervalMsFromEnv(env?: NodeJS.ProcessEnv): number;
+/**
+ * Start the unattended retention sweep. First fire is one interval after start
+ * (`setInterval` semantics). Returns undefined when intervalMs is 0.
+ */
+export declare function startPeriodicRunGc(manager: RunManager, intervalMs: number, options?: {
+    logError?: (message: string) => void;
+}): NodeJS.Timeout | undefined;
 export declare function bootstrapStageflowHost(options: StageflowHostOptions): Promise<StageflowHostBootstrap>;

package/dist/server/bootstrap.js

@@ -1,31 +1,205 @@
+import path from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { createA2aHost } from "../a2a/server.js";
+import { A2aStore } from "../a2a/store.js";
 import { createRunStoreWithConnection } from "../runstore/createStore.js";
 import { resolveA2aConfigPath } from "../a2a/configDiscovery.js";
+import { ensureGlobalHome } from "../project/globalHome.js";
 import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
 import { findProjectRoot } from "../project/findProjectRoot.js";
+import { warnDurableRootDiskIfNeeded } from "../runstore/diskUsage.js";
+import { assertStoreFilesystemSupported } from "../runstore/storeFilesystem.js";
+import { assertStoreQuickCheck, isSqliteCorruptError, maybeCheckpointResidualWal, rethrowAsStoreIntegrityFailed, } from "../runstore/sqlite/applyStorePragmas.js";
 import { RunManager } from "../runtime/runManager.js";
+import { PI_CODING_AGENT_DIR_ENV } from "../runtime/stageRoots.js";
 import { createRunChangeBus, getRunChangeBusFromWrappedStore, isRunStoreWrapped, wrapRunStoreWithChangeBus, } from "../runtime/runChangeBus.js";
 import { createMcpHttpHandler, resolveMcpStateless, } from "../mcp/server.js";
+import { loadHostConfig, } from "../config/hostConfig.js";
+import { bootProviderConfig } from "../agent/bootProviderConfig.js";
+import { applyPendingRestoreAtBoot, } from "../runstore/restore.js";
+import { assertTmpdirUsable } from "../runstore/assertTmpdir.js";
+import { logger as rootLogger } from "../logging/logger.js";
+export const DEFAULT_GC_INTERVAL_MS = 60 * 60 * 1000;
+function sqliteConnectionFromStore(store) {
+    const connection = store.connection;
+    if (connection !== undefined &&
+        connection !== null &&
+        typeof connection.prepare === "function") {
+        return connection;
+    }
+    return undefined;
+}
+/** Parse `STAGEFLOW_GC_INTERVAL_MS`; default 1h; `0` disables. */
+export function gcIntervalMsFromEnv(env = process.env) {
+    const raw = env.STAGEFLOW_GC_INTERVAL_MS;
+    if (raw === undefined || raw.trim() === "")
+        return DEFAULT_GC_INTERVAL_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return DEFAULT_GC_INTERVAL_MS;
+    return parsed;
+}
+/**
+ * Start the unattended retention sweep. First fire is one interval after start
+ * (`setInterval` semantics). Returns undefined when intervalMs is 0.
+ */
+export function startPeriodicRunGc(manager, intervalMs, options) {
+    if (intervalMs <= 0)
+        return undefined;
+    const logError = options?.logError ??
+        ((message) => {
+            console.error(message);
+        });
+    let inFlight = false;
+    return setInterval(() => {
+        if (inFlight)
+            return;
+        inFlight = true;
+        void manager
+            .gcRuns({ execute: true, channel: "periodic" })
+            .then((result) => {
+            if (!result.ok) {
+                logError(`periodic run GC failed: ${result.reason}`);
+            }
+        })
+            .catch((err) => {
+            logError(`periodic run GC failed: ${err instanceof Error ? err.message : String(err)}`);
+        })
+            .finally(() => {
+            inFlight = false;
+        });
+    }, intervalMs).unref();
+}
 export async function bootstrapStageflowHost(options) {
+    const env = options.env ?? process.env;
     const invocationCwd = options.cwd ?? process.cwd();
     const ctx = await resolveStageflowContext(invocationCwd);
     const cwd = ctx.invocationCwd;
+    ensureGlobalHome();
+    assertTmpdirUsable(env);
+    const hostConfig = options.hostConfig ??
+        (options.skipHostConfig
+            ? undefined
+            : loadHostConfig({
+                env,
+                homeDir: ctx.globalHome,
+                overrides: options.maxConcurrent !== undefined
+                    ? { maxConcurrentRuns: options.maxConcurrent }
+                    : undefined,
+            }));
+    for (const warning of hostConfig?.warnings ?? []) {
+        console.warn(`stageflow: ${warning}`);
+    }
+    const providerBoot = options.skipHostConfig
+        ? undefined
+        : await bootProviderConfig({
+            cwd: invocationCwd,
+            env,
+            requireProviders: hostConfig?.requireProviders,
+            authContext: options.providerAuthContext,
+        });
+    process.env[PI_CODING_AGENT_DIR_ENV] = path.join(ctx.globalHome, "agent");
     const agentDir = options.agentDir ?? getAgentDir();
     const rootDir = options.rootDir ?? ctx.projectRoot;
     const isGitProject = options.rootDir !== undefined
         ? findProjectRoot(rootDir) !== null
         : ctx.isGitProject;
+    const storeFilesystem = assertStoreFilesystemSupported(ctx.globalHome, {
+        env,
+        warn: (message) => console.warn(message),
+    });
+    const bootLog = rootLogger.child({ component: "bootstrap" });
+    let serveBlocked;
+    let restoreOutcome = { status: "none" };
+    if (!options.store) {
+        restoreOutcome = await applyPendingRestoreAtBoot(ctx.globalHome);
+        if (restoreOutcome.status === "blocked") {
+            serveBlocked = {
+                code: "restore_failed",
+                reason: restoreOutcome.reason,
+            };
+            bootLog.error("restore.blocked", `restore.failed: ${restoreOutcome.reason}`);
+        }
+        else if (restoreOutcome.status === "failed") {
+            serveBlocked = {
+                code: "restore_failed",
+                reason: restoreOutcome.reason,
+            };
+            bootLog.error("restore.apply_failed", `restore apply failed (attempts=${restoreOutcome.attempts}): ${restoreOutcome.reason}`);
+        }
+        else if (restoreOutcome.status === "applied") {
+            bootLog.info("restore.applied", `restore applied schema_version=${restoreOutcome.result.schema_version}`);
+        }
+    }
+    if (serveBlocked !== undefined) {
+        const runChangeBus = options.runChangeBus ?? createRunChangeBus();
+        const mcpStateless = resolveMcpStateless({
+            mcpStateless: options.mcpStateless,
+        });
+        return {
+            cwd,
+            agentDir,
+            rootDir,
+            isGitProject,
+            runChangeBus,
+            mcpStateless,
+            providerAuthContext: options.providerAuthContext,
+            mcpHandler: {
+                handle: async () => { },
+                close: async () => { },
+            },
+            stopGcInterval: () => { },
+            storeFilesystem,
+            serveBlocked,
+            ...(hostConfig !== undefined ? { hostConfig } : {}),
+            ...(providerBoot !== undefined ? { providerBoot } : {}),
+        };
+    }
     let rawStore;
     let sqliteConnection;
+    const storeRootDir = options.store
+        ? (options.rootDir ?? ctx.globalHome)
+        : ctx.globalHome;
     if (options.store) {
         rawStore = options.store;
+        sqliteConnection = sqliteConnectionFromStore(rawStore);
     }
     else {
-        const created = createRunStoreWithConnection({ rootDir: ctx.globalHome, kind: options.storeKind });
-        rawStore = created.store;
-        sqliteConnection = created.connection;
+        try {
+            const created = createRunStoreWithConnection({
+                rootDir: ctx.globalHome,
+                kind: options.storeKind,
+                openerMode: "migrate",
+            });
+            rawStore = created.store;
+            sqliteConnection = created.connection;
+        }
+        catch (err) {
+            if (isSqliteCorruptError(err)) {
+                rethrowAsStoreIntegrityFailed(err);
+            }
+            throw err;
+        }
+    }
+    if (sqliteConnection !== undefined) {
+        try {
+            assertStoreQuickCheck(sqliteConnection);
+        }
+        catch (err) {
+            if (isSqliteCorruptError(err)) {
+                rethrowAsStoreIntegrityFailed(err);
+            }
+            throw err;
+        }
+        maybeCheckpointResidualWal(storeRootDir, sqliteConnection, {
+            log: (event, fields) => {
+                bootLog.info(event, event, fields);
+            },
+        });
     }
+    const a2aStore = sqliteConnection !== undefined
+        ? new A2aStore(storeRootDir, sqliteConnection)
+        : undefined;
     const boundBus = isRunStoreWrapped(rawStore)
         ? getRunChangeBusFromWrappedStore(rawStore)
         : undefined;
@@ -42,12 +216,30 @@ export async function bootstrapStageflowHost(options) {
         projectRoot: rootDir,
         isGitProject,
         store,
-        maxConcurrent: options.maxConcurrent,
+        maxConcurrent: options.maxConcurrent ??
+            (hostConfig?.maxConcurrentRunsExplicit
+                ? hostConfig.maxConcurrentRuns
+                : undefined),
+        maxQueued: hostConfig?.maxQueued,
+        maxConcurrentPerProject: hostConfig?.maxConcurrentRunsPerProject,
+        callerQuotas: Object.fromEntries(Object.entries(hostConfig?.callers ?? {}).map(([id, cfg]) => [
+            id,
+            cfg.maxConcurrent,
+        ])),
         operatorCatalog: { cwd, agentDir },
+        a2aStore,
     });
     await manager.attachWaitingStages();
     await manager.reconcileOrphanedStages();
+    await manager.autoResumeInterruptedStages();
     await manager.resumeStalledSchedules();
+    await manager.reenqueuePersistedQueuedRuns();
+    await warnDurableRootDiskIfNeeded(ctx.globalHome, { env });
+    const gcInterval = startPeriodicRunGc(manager, gcIntervalMsFromEnv(env));
+    const stopGcInterval = () => {
+        if (gcInterval !== undefined)
+            clearInterval(gcInterval);
+    };
     const mcpStateless = resolveMcpStateless({
         mcpStateless: options.mcpStateless,
     });
@@ -55,12 +247,19 @@ export async function bootstrapStageflowHost(options) {
         manager,
         store,
         cwd,
+        agentDir,
         runChangeBus,
         providerAuthContext: options.providerAuthContext,
         projectRoot: rootDir,
     }, { mcpStateless });
     return {
-        a2a: await createA2aHost({ manager, runStore: store, rootDir, connection: sqliteConnection }, resolveA2aConfigPath(rootDir)),
+        a2a: await createA2aHost({
+            manager,
+            runStore: store,
+            rootDir: storeRootDir,
+            connection: sqliteConnection,
+            a2aStore,
+        }, resolveA2aConfigPath(rootDir)),
         cwd,
         agentDir,
         rootDir,
@@ -71,5 +270,10 @@ export async function bootstrapStageflowHost(options) {
         mcpStateless,
         providerAuthContext: options.providerAuthContext,
         mcpHandler,
+        ...(hostConfig !== undefined ? { hostConfig } : {}),
+        ...(providerBoot !== undefined ? { providerBoot } : {}),
+        ...(gcInterval !== undefined ? { gcInterval } : {}),
+        stopGcInterval,
+        storeFilesystem,
     };
 }

package/dist/server/controlToken.d.ts

@@ -0,0 +1,47 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export type ControlScope = "read" | "drive";
+export type BearerAuth = {
+    scope: ControlScope;
+    caller_id: string;
+};
+export type NamedDriveToken = {
+    caller_id: string;
+    digest: Buffer;
+};
+export type ControlTokens = {
+    driveDigest: Buffer | undefined;
+    readDigest: Buffer | undefined;
+    namedDrive: readonly NamedDriveToken[];
+};
+/** Parse named drive callers from STAGEFLOW_CONTROL_TOKEN_<NAME> / _FILE. */
+export declare function listNamedControlTokenEnvKeys(env?: NodeJS.ProcessEnv): Array<{
+    envKey: string;
+    caller_id: string;
+    isFile: boolean;
+}>;
+export declare function loadControlTokens(env?: NodeJS.ProcessEnv): ControlTokens;
+/** Plain bearer for CLI→host calls. Drive preferred; read only for GET/HEAD. */
+export declare function resolveClientBearerToken(method: string, env?: NodeJS.ProcessEnv): string | undefined;
+export declare function clientAuthorizationHeaders(method: string, env?: NodeJS.ProcessEnv): Record<string, string>;
+export declare function hasDriveToken(tokens: ControlTokens): boolean;
+export declare function hasAnyToken(tokens: ControlTokens): boolean;
+export declare function isLoopbackBind(bind: string): boolean;
+export declare function refuseBindMessage(bind: string): string;
+export declare function assertBindAllowed(bind: string, tokens: ControlTokens): void;
+export declare class BindRefusedError extends Error {
+    readonly exitCode = 1;
+    constructor(message: string);
+}
+export declare function requiredScopeFor(method: string, pathname: string): ControlScope | null;
+/**
+ * Digest once; timingSafeEqual against every loaded digest (no early-return oracle).
+ * Named control tokens are drive-only; READ stays the singular global token.
+ */
+export declare function authenticateBearer(tokens: ControlTokens, authorization: string | undefined): BearerAuth | undefined;
+export type EnforceBearerResult = {
+    ok: true;
+    auth: BearerAuth | undefined;
+} | {
+    ok: false;
+};
+export declare function enforceBearerAuth(tokens: ControlTokens, req: IncomingMessage, res: ServerResponse, required: ControlScope): EnforceBearerResult;