toolroll 0.9.49 → 0.9.50

package/dist/server/remote-hooks.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The remote domain's public roads (moved from serve.ts unchanged): the liveness probe and the webhooks a public
+ * relay may expose. Each is declared in the route table's edge stage and answers before the console's sign-in.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Store } from "../store.js";
+/** What the hooks read from the server: its store, clock and the two configuration paths. */
+export interface RemoteHookContext {
+    readonly store: Store;
+    readonly clock: () => Date;
+    readonly options: {
+        readonly configDir?: string | undefined;
+        readonly telegramTokenFile?: string | undefined;
+    };
+}
+/** Flow webhooks (v82): the one road a public relay may expose. The secret
+ * address proves nothing about the sender on its own for GitHub and Linear:
+ * their signatures are checked too. Nothing runs here; cards wait for a pass. */
+/**
+ * v98: Telegram pushes this bot's updates here. Only a request carrying our
+ * secret header is Telegram's; each update is kept for the bridge (which
+ * applies it through the same door as a polled one), and answered at once so
+ * Telegram doesn't send it again. An update already kept or applied is fine.
+ */
+export declare function telegramHook(ctx: RemoteHookContext, request: IncomingMessage, response: ServerResponse): Promise<void>;
+export declare function flowHook(ctx: RemoteHookContext, request: IncomingMessage, response: ServerResponse, url: URL): Promise<void>;
+/** A shared button as a public form (v84): its questions, and one card per submission. No sign-in, no session, nothing about the flow shown. */
+export declare function flowForm(ctx: RemoteHookContext, request: IncomingMessage, response: ServerResponse, url: URL): Promise<void>;
+export declare function healthz(store: Store, response: ServerResponse, head: boolean): void;

package/dist/server/remote-hooks.js

@@ -0,0 +1,130 @@
+import { adapterPolicy } from "./route-policy.js";
+import { flowFormPage, FORM_PATH, HOOK_PATH, receiveFlowForm, receiveFlowHook } from "../flow-triggers.js";
+import { keepPushedUpdate, loadBotToken, pushedByTelegram, telegramHookSecret } from "../telegram.js";
+/** Flow webhooks (v82): the one road a public relay may expose. The secret
+ * address proves nothing about the sender on its own for GitHub and Linear:
+ * their signatures are checked too. Nothing runs here; cards wait for a pass. */
+/**
+ * v98: Telegram pushes this bot's updates here. Only a request carrying our
+ * secret header is Telegram's; each update is kept for the bridge (which
+ * applies it through the same door as a polled one), and answered at once so
+ * Telegram doesn't send it again. An update already kept or applied is fine.
+ */
+export async function telegramHook(ctx, request, response) {
+    const { store, options, clock } = ctx;
+    const reply = (status) => { response.writeHead(status, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" }); response.end(status === 200 ? "ok" : "no"); request.resume(); };
+    const source = options.configDir === undefined || options.telegramTokenFile === undefined ? null : loadBotToken(process.env, options.telegramTokenFile);
+    if (source === null || options.configDir === undefined)
+        return reply(404);
+    if (request.method !== "POST")
+        return reply(405);
+    if (!pushedByTelegram(request.headers["x-telegram-bot-api-secret-token"], telegramHookSecret(options.configDir)))
+        return reply(401);
+    if (!adapterPolicy({ caller: "service", capability: "none" }).ok)
+        return reply(403);
+    if (Number(request.headers["content-length"] ?? 0) > 1_000_000)
+        return reply(413);
+    const chunks = [];
+    try {
+        await new Promise((resolve, reject) => {
+            let size = 0;
+            request.on("data", (chunk) => { size += chunk.length; if (size > 1_000_000)
+                reject(new Error("too-large"));
+            else
+                chunks.push(chunk); });
+            request.on("end", resolve);
+            request.on("error", reject);
+        });
+    }
+    catch {
+        return reply(413);
+    }
+    try {
+        return reply(keepPushedUpdate(store, source.botId, Buffer.concat(chunks), clock()).ok ? 200 : 400);
+    }
+    catch {
+        return reply(500);
+    }
+}
+export async function flowHook(ctx, request, response, url) {
+    const { store, options, clock } = ctx;
+    const reply = (status, said) => { response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" }); response.end(JSON.stringify({ said })); request.resume(); };
+    if (url.pathname.startsWith(FORM_PATH))
+        return flowForm(ctx, request, response, url);
+    if (options.configDir === undefined || !url.pathname.startsWith(HOOK_PATH))
+        return reply(404, "No such address.");
+    if (request.method !== "POST")
+        return reply(405, "Send a POST.");
+    if (Number(request.headers["content-length"] ?? 0) > 1_000_000)
+        return reply(413, "Too large.");
+    const chunks = [];
+    try {
+        await new Promise((resolve, reject) => {
+            let size = 0;
+            request.on("data", (chunk) => { size += chunk.length; if (size > 1_000_000)
+                reject(new Error("too-large"));
+            else
+                chunks.push(chunk); });
+            request.on("end", resolve);
+            request.on("error", reject);
+        });
+    }
+    catch (error) {
+        return reply(error instanceof Error && error.message === "too-large" ? 413 : 400, "Couldn't read that.");
+    }
+    try {
+        const answer = receiveFlowHook(store, url.pathname.slice(HOOK_PATH.length), { headers: request.headers, body: Buffer.concat(chunks) }, options.configDir, clock());
+        return reply(answer.status, answer.said);
+    }
+    catch {
+        return reply(500, "Not saved.");
+    }
+}
+/** A shared button as a public form (v84): its questions, and one card per submission. No sign-in, no session, nothing about the flow shown. */
+export async function flowForm(ctx, request, response, url) {
+    const { store, clock } = ctx;
+    const page = (answer) => {
+        response.writeHead(answer.status, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", "referrer-policy": "no-referrer", "x-content-type-options": "nosniff",
+            "x-frame-options": "DENY", "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'" });
+        response.end(request.method === "HEAD" ? undefined : answer.html);
+        request.resume();
+    };
+    const token = url.pathname.slice(FORM_PATH.length);
+    if (request.method === "GET" || request.method === "HEAD")
+        return page(flowFormPage(store, token, clock()));
+    if (request.method !== "POST")
+        return page({ status: 405, html: "" });
+    if (Number(request.headers["content-length"] ?? 0) > 65_536)
+        return page({ status: 413, html: "" });
+    let raw = "";
+    try {
+        await new Promise((resolve, reject) => {
+            request.setEncoding("utf8");
+            request.on("data", (chunk) => { raw += chunk; if (raw.length > 65_536)
+                reject(new Error("too-large")); });
+            request.on("end", resolve);
+            request.on("error", reject);
+        });
+    }
+    catch {
+        return page({ status: 413, html: "" });
+    }
+    try {
+        return page(receiveFlowForm(store, token, new URLSearchParams(raw), clock()));
+    }
+    catch {
+        return page({ status: 500, html: "" });
+    }
+}
+export function healthz(store, response, head) {
+    let healthy = true;
+    try {
+        store.handle.prepare("SELECT 1 FROM schema_version").get();
+    }
+    catch {
+        healthy = false;
+    }
+    const body = JSON.stringify({ status: healthy ? "ok" : "unavailable" });
+    response.writeHead(healthy ? 200 : 503, { "content-type": "application/json", "cache-control": "no-store", "x-content-type-options": "nosniff" });
+    response.end(head ? undefined : body);
+}

package/dist/server/remote.d.ts

@@ -0,0 +1,59 @@
+import type { Registration } from './handler-registry.js';
+/** tasks handlers, moved without changing their route bodies. */
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { CodingWorkspace } from '../coding-workspace.js';
+import { type Principal } from "../operate-remote.js";
+import { RequestBudget, SourceAdmission, type Admission } from "../request-budget.js";
+import { type Store } from "../store.js";
+import type { TeamResponse } from '../team-contract.js';
+import type { EdgeContext } from './handler-context.js';
+import { type RemoteHookContext } from "./remote-hooks.js";
+import { type ServeOptions, type Who } from "./shared.js";
+export interface RemoteRuntime {
+    identify: (request: IncomingMessage, touch?: boolean, limited?: boolean, refusedToken?: {
+        principal?: Principal;
+    }) => Who | null;
+    store: Store;
+    admitPasswordSource: (request: IncomingMessage) => Admission;
+    admitBearer: (request: IncomingMessage, actor: {
+        name: string;
+        principal?: Principal;
+    }) => Admission;
+    allowedHost: (host: string | undefined) => boolean;
+    team: {
+        execute: import("../team-contract.js").TeamExecute;
+        start: () => void;
+        close: () => Promise<void>;
+        pass: () => Promise<void>;
+        cursor: (actor: import("../team-contract.js").TeamActor, conversationId?: string) => number | null;
+        domain: import("../team-leads.js").TeamLeads;
+    };
+    teamBrowserReply: (reply: TeamResponse, actor: {
+        name: string;
+        generation: number;
+    }, csrf: string) => TeamResponse;
+    teamStreams: Set<ServerResponse<IncomingMessage>>;
+    requestBudget: RequestBudget;
+    options: ServeOptions;
+    coding: CodingWorkspace | null;
+    codingProjects: () => string[];
+    liveCeiling: () => {
+        repos: string[];
+        roots: readonly string[];
+    };
+    clock: () => Date;
+    evidenceRoot: string;
+    consoleOrigin: (host: string | undefined) => string | null;
+    managedRepos: () => string[];
+    joinSourceOf: (request: IncomingMessage) => string;
+    ssoSettings: () => import("../oidc.js").OidcSettings | null;
+    SSO_FRESH_MS: number;
+    oauthTokenBudget: SourceAdmission;
+    hookContext: RemoteHookContext;
+    teamsSourceBudget: SourceAdmission;
+    teamsTenantBudget: SourceAdmission;
+}
+export declare function createRemoteHandlers(runtime: RemoteRuntime): {
+    registrations: Registration[];
+    edge: (ctx: EdgeContext) => Promise<void>;
+};

package/dist/server/remote.js

@@ -0,0 +1,185 @@
+/** tasks handlers, moved without changing their route bodies. */
+import {} from "node:http";
+import { handleCliHttp } from '../cli-http.js';
+import { CodingWorkspace } from '../coding-workspace.js';
+import { createMcpHttp } from "../mcp-http.js";
+import { createOAuthHttp, resourceMetadataUrl } from "../mcp-oauth.js";
+import { reproveRemote } from "../operate-remote.js";
+import { rowVisible } from "../project.js";
+import { RequestBudget, SourceAdmission } from "../request-budget.js";
+import { authenticateAccount } from "../scope.js";
+import { createSessionEndpoint } from '../session-server.js';
+import {} from "../store.js";
+import { handleTeamHttp } from '../team-http.js';
+import { handleTeamsHttp } from "../teams.js";
+import { flowHook, telegramHook } from "./remote-hooks.js";
+import { respond } from "./shared.js";
+export function createRemoteHandlers(runtime) {
+    const { identify, store, admitPasswordSource, admitBearer, allowedHost, team, teamBrowserReply, teamStreams, requestBudget, options, coding, codingProjects, liveCeiling, clock, evidenceRoot, consoleOrigin, managedRepos, joinSourceOf, ssoSettings, SSO_FRESH_MS, oauthTokenBudget, hookContext, teamsSourceBudget, teamsTenantBudget } = runtime;
+    /**
+     * The full principal a live `so_` API token stands for: its person and their generation, the token's own read/act
+     * scope, its project limit narrowed by the person's current access, and its id. Every route that accepts an API token
+     * builds its identity here and carries it whole, so no route can drop the token's narrower scope or projects.
+     */
+    const tokenPrincipalOf = (request) => {
+        const who = identify(request, false, true);
+        return who?.via === "bearer" ? who.principal ?? null : null;
+    };
+    const presentsToken = (request) => /^Bearer so_\S+$/.test(request.headers.authorization ?? "");
+    const teamEndpoint = (request, response) => handleTeamHttp(request, response, {
+        authenticate: request => {
+            if (presentsToken(request)) {
+                const principal = tokenPrincipalOf(request);
+                return principal === null ? null : { name: principal.account, generation: principal.generation, principal };
+            }
+            const who = identify(request, request.method === 'POST');
+            const account = who === null ? null : store.accountOf(who.name);
+            return who && account && account.revokedAt === null ? { name: who.name, generation: account.generation, role: account.role } : null;
+        },
+        admit: admitPasswordSource,
+        admitAuthenticated: admitBearer,
+        revalidate: (request, actor) => {
+            const account = store.accountOf(actor.name);
+            if (!account || account.revokedAt !== null || account.generation !== actor.generation)
+                return false;
+            // An API token is re-proved against the store every time: unrevoked, unexpired, inside its project limit.
+            if (actor.principal !== undefined) {
+                const live = reproveRemote(store, actor.principal, new Date());
+                if (!live.ok)
+                    return false;
+                // The post-body mutation check must see a scope lowered since authentication, too.
+                actor.principal = { ...actor.principal, scope: live.scope };
+                return true;
+            }
+            // A password bearer was proved when this connection opened. Cookie expiry/revocation
+            // is rechecked without allowing a passive stream to extend its lifetime.
+            if (request.headers.authorization)
+                return true;
+            const who = identify(request, false);
+            return who?.name === actor.name && who.via === 'cookie' && who.session.generation === actor.generation;
+        },
+        authorizeMutation: (request, actor) => {
+            if (actor.principal !== undefined)
+                return request.headers.origin === undefined;
+            const who = identify(request, false);
+            if (!who || who.name !== actor.name)
+                return false;
+            if (who.via === 'bearer')
+                return request.headers.origin === undefined;
+            const origin = request.headers.origin, referer = request.headers.referer;
+            const named = typeof origin === 'string' && origin !== 'null' ? origin : typeof referer === 'string' ? referer : null;
+            if (named !== null && !allowedHost(named.replace(/^https?:\/\//, '').split('/')[0]))
+                return false;
+            return request.headers['x-csrf-token'] === who.session.csrf;
+        },
+        execute: async (actor, input) => {
+            const reply = await team.execute(actor, input);
+            if (actor.principal !== undefined)
+                return reply;
+            const who = identify(request, false);
+            return who?.via === 'cookie' ? teamBrowserReply(reply, actor, who.session.csrf) : reply;
+        }, cursor: team.cursor, streams: teamStreams,
+    });
+    // Remote CLI: one live API token names the person; the shared command boundary decides everything else.
+    const cliEndpoint = (request, response) => handleCliHttp(request, response, {
+        admit: principal => requestBudget.admit(principal.tokenId, "api"),
+        authenticate: tokenPrincipalOf,
+        run: async () => options.cliRunner ?? (await import("../operate.js")).runOperateAs ?? null,
+        modeOf: options.cliModeOf,
+        store,
+    });
+    const sessionEndpoint = createSessionEndpoint({ store, workspace: coding, projects: codingProjects, projectAllowed: repo => rowVisible(liveCeiling(), repo),
+        admit: admitPasswordSource, admitAuthenticated: admitBearer });
+    const mcpHttp = createMcpHttp({ store, clock, evidenceRoot, ...(options.requestBudgetClock === undefined ? {} : { requestBudgetClock: options.requestBudgetClock }), signedIn: request => identify(request, true, true) !== null, admit: person => requestBudget.admit(person.principal.tokenId, "mcp"),
+        resourceMetadata: request => { const origin = consoleOrigin(request.headers.host); return origin === null ? null : resourceMetadataUrl(origin); },
+        enrolled: () => [...new Set([...managedRepos(), ...store.listProjects().map(project => project.path)])], ...(options.runOperateAs === undefined ? {} : { runAs: options.runOperateAs }) });
+    // MCP sign-in: the console's own sign-in and step-up, a same-site consent form, and the person's current projects.
+    const oauthHttp = createOAuthHttp({ store, clock,
+        originOf: request => consoleOrigin(request.headers.host),
+        requesterKey: joinSourceOf,
+        session: request => {
+            const who = identify(request, false);
+            if (who === null || who.via !== "cookie")
+                return null;
+            return { name: who.name, role: who.role, csrf: who.session.csrf,
+                sso: who.session.sso === undefined ? null : { label: ssoSettings()?.label ?? "your identity provider", fresh: Date.now() - who.session.sso.at < SSO_FRESH_MS } };
+        },
+        sameSite: request => {
+            const origin = request.headers.origin, referer = request.headers.referer;
+            const named = typeof origin === "string" && origin !== "null" ? origin : typeof referer === "string" ? referer : null;
+            return named !== null && allowedHost(named.replace(/^https?:\/\//, "").split("/")[0]);
+        },
+        // The step-up for a credential: the person's password, or (empty) a fresh identity-provider check. What they may
+        // grant (their role, their projects) is checked beside it.
+        confirm: (session, typed) => typed === "" ? session.sso?.fresh === true : authenticateAccount(store, session.name, typed).ok,
+        projectsFor: account => store.knownRepos().filter(repo => store.accountCanAccess(account, repo)).sort(),
+        admitToken: request => oauthTokenBudget.admit(joinSourceOf(request)),
+    });
+    async function edge(ctx) {
+        const { request, response, url, route } = ctx;
+        switch (route.id) {
+            case 'edge.telegram-hook': return telegramHook(hookContext, request, response);
+            case 'edge.flow-hook':
+            case 'edge.flow-form':
+            case 'edge.flow-form-send': return flowHook(hookContext, request, response, url);
+            case 'edge.mcp': return mcpHttp(request, response);
+            case 'edge.oauth-discovery':
+            case 'edge.oauth-register':
+            case 'edge.oauth-token':
+            case 'edge.oauth-authorize':
+            case 'edge.oauth-consent':
+                await oauthHttp(request, response, url);
+                return;
+            case 'edge.sessions-list':
+            case 'edge.sessions-show':
+            case 'edge.sessions-changes':
+            case 'edge.sessions-start':
+            case 'edge.sessions-send':
+            case 'edge.sessions-stop':
+            case 'edge.sessions-resume':
+            case 'edge.sessions-recover':
+                await sessionEndpoint(request, response);
+                return;
+            case 'edge.team-read':
+            case 'edge.team-send':
+            case 'edge.team-events':
+                await teamEndpoint(request, response);
+                return;
+            case 'edge.cli':
+                await cliEndpoint(request, response);
+                return;
+            case 'edge.teams':
+                if (options.configDir !== undefined && await handleTeamsHttp(request, response, { store, dir: options.configDir, ...(options.teamsFetcher ? { fetcher: options.teamsFetcher } : {}), clock,
+                    admitSource: request => teamsSourceBudget.admit(joinSourceOf(request)), admitTenant: tenant => teamsTenantBudget.admit(tenant) }))
+                    return;
+                return respond(response, 404, 'text/plain; charset=utf-8', 'No such address.');
+        }
+        throw new Error('Unregistered remote route');
+    }
+    const registrations = [
+        { id: "edge.telegram-hook", domain: "remote", stage: "edge", method: "POST", handle: edge },
+        { id: "edge.flow-form", domain: "remote", stage: "edge", method: "GET,HEAD", handle: edge },
+        { id: "edge.flow-form-send", domain: "remote", stage: "edge", method: "POST", handle: edge },
+        { id: "edge.flow-hook", domain: "remote", stage: "edge", method: "POST", handle: edge },
+        { id: "edge.mcp", domain: "remote", stage: "edge", method: "POST", handle: edge },
+        { id: "edge.oauth-discovery", domain: "remote", stage: "edge", method: "GET,HEAD", handle: edge },
+        { id: "edge.oauth-register", domain: "remote", stage: "edge", method: "POST", handle: edge },
+        { id: "edge.oauth-token", domain: "remote", stage: "edge", method: "POST", handle: edge },
+        { id: "edge.oauth-authorize", domain: "remote", stage: "edge", method: "GET,HEAD", handle: edge },
+        { id: "edge.oauth-consent", domain: "remote", stage: "edge", method: "POST", handle: edge },
+        { id: "edge.sessions-list", domain: "remote", stage: "edge", method: "POST", handle: edge },
+        { id: "edge.sessions-show", domain: "remote", stage: "edge", method: "POST", handle: edge },
+        { id: "edge.sessions-changes", domain: "remote", stage: "edge", method: "POST", handle: edge },
+        { id: "edge.sessions-start", domain: "remote", stage: "edge", method: "POST", handle: edge },
+        { id: "edge.sessions-send", domain: "remote", stage: "edge", method: "POST", handle: edge },
+        { id: "edge.sessions-stop", domain: "remote", stage: "edge", method: "POST", handle: edge },
+        { id: "edge.sessions-resume", domain: "remote", stage: "edge", method: "POST", handle: edge },
+        { id: "edge.sessions-recover", domain: "remote", stage: "edge", method: "POST", handle: edge },
+        { id: "edge.team-read", domain: "remote", stage: "edge", method: "GET", handle: edge },
+        { id: "edge.team-send", domain: "remote", stage: "edge", method: "POST", handle: edge },
+        { id: "edge.team-events", domain: "remote", stage: "edge", method: "GET", handle: edge },
+        { id: "edge.cli", domain: "remote", stage: "edge", method: "POST", handle: edge },
+        { id: "edge.teams", domain: "remote", stage: "edge", method: "POST", handle: edge },
+    ];
+    return { registrations, edge };
+}

package/dist/server/route-policy.d.ts

@@ -0,0 +1,18 @@
+import type { Caller, ProjectResolver, RouteDeclaration, RouteScope } from './route-table.js';
+export interface RoutePrincipal {
+    caller: Caller;
+    capability: 'none' | 'read' | 'act';
+    viewer?: boolean;
+    token?: boolean;
+}
+export type PolicyResult = {
+    ok: true;
+} | {
+    ok: false;
+    status: 403;
+    reason: 'caller' | 'scope' | 'project';
+};
+/** The row supplies the minimum capability and the project resolver. Passwords/nonces are re-proved by the handler. */
+export declare function evaluateRoutePolicy(route: RouteDeclaration, principal: RoutePrincipal, resolve: (source: ProjectResolver) => boolean, operationScope?: RouteScope): PolicyResult;
+export declare function withEdgePolicy<T>(route: RouteDeclaration, run: () => T): T;
+export declare function adapterPolicy(principal: RoutePrincipal, scope?: RouteScope, resolve?: (source: ProjectResolver) => boolean): PolicyResult;

package/dist/server/route-policy.js

@@ -0,0 +1,30 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** The row supplies the minimum capability and the project resolver. Passwords/nonces are re-proved by the handler. */
+export function evaluateRoutePolicy(route, principal, resolve, operationScope) {
+    if (!route.callers.includes(principal.caller))
+        return { ok: false, status: 403, reason: 'caller' };
+    const required = route.scope === 'step-up' || operationScope === 'step-up' ? 'step-up'
+        : route.scope === 'act' || operationScope === 'act' ? 'act' : route.scope === 'read' || operationScope === 'read' ? 'read' : 'none';
+    if (required === 'step-up' && principal.caller !== 'cookie')
+        return { ok: false, status: 403, reason: 'caller' };
+    const needsAct = required === 'act' || required === 'step-up';
+    const viewerPreference = principal.caller === 'cookie' && route.viewer && principal.viewer === true && principal.token !== true;
+    if ((needsAct && principal.capability !== 'act' && !viewerPreference) || (required === 'read' && principal.capability === 'none'))
+        return { ok: false, status: 403, reason: 'scope' };
+    if (!resolve(route.project))
+        return { ok: false, status: 403, reason: 'project' };
+    return { ok: true };
+}
+/** The dispatcher matches once; protocol authentication then checks the same row before operation dispatch. */
+const edgePolicy = new AsyncLocalStorage();
+export function withEdgePolicy(route, run) { return edgePolicy.run({ route }, run); }
+export function adapterPolicy(principal, scope, resolve = source => source === 'none' || source === 'adapter') {
+    const context = edgePolicy.getStore();
+    // Standalone protocol adapters retain their own authoritative admission checks.
+    if (context === undefined)
+        return { ok: true };
+    const checked = evaluateRoutePolicy(context.route, { ...principal, caller: context.caller ?? principal.caller }, resolve, scope);
+    if (checked.ok && context.caller === undefined)
+        context.caller = principal.caller;
+    return checked;
+}

package/dist/server/route-table.d.ts

@@ -0,0 +1,74 @@
+/**
+ * THE ROUTE TABLE: every address this server answers, in one ordered list.
+ *
+ * Each row declares its method, its exact pattern, which callers may reach it,
+ * the scope it needs, how its project is found, and what a project-limited
+ * account may do there. The server matches a request against this table before
+ * any handler runs; a request no row declares is refused (fail closed). The
+ * scattered allowlists that used to repeat these facts by hand (the limited
+ * account's read/write sets, the viewer's POST set, the selected-project
+ * exceptions) are projections of this table.
+ *
+ * Handlers still re-prove what can change after admission: passwords, nonces,
+ * webhook signatures, object membership, stale sessions and revoked tokens.
+ */
+/** Who presents the request. `service` is a verified external sender (a signed webhook, an OAuth return carrying its one-time state). */
+export type Caller = "anonymous" | "service" | "cookie" | "bearer" | "oauth" | "coordinator" | "lead";
+/** What the caller must hold: nothing, read, act (an approver or an `act` token), or a fresh password/provider check on top. */
+export type RouteScope = "none" | "read" | "act" | "step-up";
+/** Where the request's project comes from. */
+export type ProjectResolver = "none" | "session" | "form" | "form-path" | "task" | "run" | "decision" | "incident" | "routine" | "flow" | "proposal" | "conversation" | "coding" | "adapter";
+/**
+ * What a project-limited account may do here:
+ * - `deny`: instance access only.
+ * - `collection`: a listing within a concrete visible project.
+ * - `unscoped`: allowed without a concrete project (the handler filters to the account's projects).
+ * - `resource`: the named object's project must be visible, and so must the request's project.
+ * - `self`: the caller's own settings or saved objects; the handler proves ownership and each project named.
+ * - `proposal`: a chat proposal: the saved owner/room and project must be visible.
+ * - `conversation`: a shared room's own audience admission, else instance access.
+ */
+export type LimitedAccess = "deny" | "collection" | "unscoped" | "resource" | "self" | "proposal" | "conversation";
+export type Domain = "tasks" | "flows" | "chat" | "settings" | "people" | "remote" | "pages";
+/** `edge`: answered before the console's sign-in (its own protocol proves the caller). `console`: after identify(). */
+export type Stage = "edge" | "console";
+export type RouteMethod = "GET" | "POST" | "GET,HEAD";
+export interface RouteDeclaration {
+    readonly id: string;
+    readonly domain: Domain;
+    readonly stage: Stage;
+    readonly method: RouteMethod;
+    /** An anchored regular expression source matched against the decoded-free pathname. */
+    readonly pattern: string;
+    readonly callers: readonly Caller[];
+    readonly scope: RouteScope;
+    readonly project: ProjectResolver;
+    readonly limited: LimitedAccess;
+    /** A cookie session with no open project is sent to the project opener first (console GET only). */
+    readonly needsProject: boolean;
+    /** A viewer (watch-only) account may POST here. */
+    readonly viewer: boolean;
+    /** Signed hooks and health are the only roads exposed before Host validation. */
+    readonly host: "before" | "after";
+    /** Protocol authentication stays in its adapter, before its operation handler. */
+    readonly proof: "console" | "public" | "adapter";
+    /** A concrete path this row must win, for the precedence test. */
+    readonly sample: string;
+    /** The exact answer to a caller the row does not admit, when the route has its own protocol (else a plain 403). */
+    readonly scopeRefusal?: string;
+    readonly callerRefusal?: {
+        readonly status: number;
+        readonly type: string;
+        readonly body: string;
+    };
+}
+/** The sole route table, in match order. */
+export declare const ROUTES: readonly RouteDeclaration[];
+/** The first row that declares this method and path, or null: an undeclared request never reaches a handler. */
+export declare function matchRoute(method: string, pathname: string, stage?: Stage): RouteDeclaration | null;
+/** True when some row declares this path for another method (a wrong-method request). */
+export declare function declaredForAnotherMethod(method: string, pathname: string, stage?: Stage): boolean;
+/** Refuses a malformed table at startup: duplicate ids, duplicate method+pattern rows, or a row shadowed by an earlier one for its own sample. */
+export declare function assertRouteTable(routes?: readonly RouteDeclaration[]): void;
+/** The effective policy of every row, as plain data — what the snapshot test compares. */
+export declare const routePolicySnapshot: () => Array<Omit<RouteDeclaration, "sample">>;