@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/management-config.js

@@ -0,0 +1,286 @@
+/**
+ * `managementApi.clients` config resolution (issue #312 M1).
+ *
+ * Turns the optional `managementApi` block of `paddock.config.yaml` into the
+ * resolved list of external clients the token authenticator will accept, each
+ * carrying its {@link ManagementScope}. Pure over an injected environment map so
+ * the whole validation matrix is unit-testable without touching `process.env`.
+ *
+ * ── Why token material is REFERENCED, never inlined ─────────────────────────
+ * `paddock.config.yaml` is git-tracked (and editable from the instance Settings
+ * screen, #385). A secret written there leaks into history the moment it is
+ * committed, and no later edit removes it. So a client's credential is given as
+ * an env REFERENCE (`ref: env:PADDOCK_MCP_TOKEN_MY_LAPTOP`) and an inline value
+ * is a hard config error — not a warning — because accepting one silently would
+ * teach operators the unsafe habit.
+ *
+ * ── Failure posture ─────────────────────────────────────────────────────────
+ * Two different kinds of problem, handled differently on purpose:
+ *   - **Malformed config** (inline secret, unknown auth type, bad scope shape)
+ *     is an ERROR. The operator wrote something meaningless; surface it.
+ *   - **An unresolvable reference** (env var unset/blank/too short) DROPS THAT
+ *     CLIENT with a loud warning, leaving other clients working. Dropping is the
+ *     fail-closed direction: the credential simply doesn't exist, so nothing can
+ *     authenticate as that client. If every client drops, `/mcp` reverts to its
+ *     unconfigured 404 — the endpoint ceases to exist rather than opening up.
+ */
+import { DEFAULT_READ_ONLY_SCOPE, grantsCodeExecution, } from "./management-policy.js";
+import { parseTrustedProxies } from "./trusted-proxy.js";
+/**
+ * Recommended token prefix. A prefixed token additionally carries the INSTANCE
+ * it was minted for (`pdk_<instanceId>_<secret>`), which is what makes a
+ * credential for instance A meaningless at instance B — see
+ * {@link tokenInstanceId}. Also gives secret scanners something to match on.
+ */
+export const TOKEN_PREFIX = "pdk_";
+/**
+ * Minimum accepted token length. Not a strength guarantee — just a floor that
+ * rejects obvious placeholders ("changeme", "test") before they can ever
+ * authenticate a turn-spawning client.
+ */
+export const MIN_TOKEN_LENGTH = 24;
+/**
+ * Validate the canonical public URL. Returns the normalised origin (no trailing
+ * slash) or an error string.
+ *
+ * Rejects plaintext for anything but loopback: `/mcp` carries bearer tokens, so
+ * advertising an `http://` origin to the world would publish a URL on which the
+ * credential is readable in transit. This is the config-time half of the epic's
+ * "refuse to serve `/mcp` over plaintext" rule (routes/mcp.ts enforces the
+ * per-request half).
+ */
+export function validatePublicUrl(raw) {
+    let parsed;
+    try {
+        parsed = new URL(raw.trim());
+    }
+    catch {
+        return { error: `must be an absolute URL (got "${raw}")` };
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        return { error: `must be an http(s) URL (got "${parsed.protocol}")` };
+    }
+    const host = parsed.hostname;
+    const isLoopback = host === "localhost" || host === "127.0.0.1" || host === "::1";
+    if (parsed.protocol === "http:" && !isLoopback) {
+        return {
+            error: `must be https for a non-loopback host (got "${raw}") — the management API carries ` +
+                `bearer tokens, so a plaintext public URL would expose them in transit`,
+        };
+    }
+    if (parsed.search || parsed.hash)
+        return { error: "must not carry a query string or fragment" };
+    // Normalise to an origin + optional path, dropping any trailing slash so the
+    // RFC 9728 byte-comparison has one canonical form to work from.
+    const path = parsed.pathname.replace(/\/+$/, "");
+    return { url: `${parsed.origin}${path}` };
+}
+/** Normalize a YAML list field that may be a real array or a delimited string. */
+function toList(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (Array.isArray(raw)) {
+        return raw.map((v) => String(v).trim()).filter((v) => v.length > 0);
+    }
+    const s = String(raw).trim();
+    if (s.length === 0)
+        return [];
+    return s
+        .split(/[\n,]/)
+        .map((v) => v.trim())
+        .filter((v) => v.length > 0);
+}
+function toOptionalInt(raw) {
+    if (raw === undefined || raw === null || raw === "")
+        return undefined;
+    const n = typeof raw === "number" ? raw : Number.parseInt(String(raw).trim(), 10);
+    if (!Number.isFinite(n) || n < 0)
+        return undefined;
+    return Math.floor(n);
+}
+/**
+ * The instance id embedded in a prefixed token (`pdk_<instanceId>_<secret>`), or
+ * undefined for a token that carries none.
+ *
+ * This is the audience-binding hook the ticket asks for on day one: the
+ * authenticator refuses a prefixed token whose embedded instance doesn't match
+ * this instance, so copying a credential to a second Paddock does not make it
+ * work there — even though the secret bytes are identical.
+ */
+export function tokenInstanceId(token) {
+    if (!token.startsWith(TOKEN_PREFIX))
+        return undefined;
+    const rest = token.slice(TOKEN_PREFIX.length);
+    const sep = rest.indexOf("_");
+    if (sep <= 0)
+        return undefined;
+    return rest.slice(0, sep);
+}
+/**
+ * Resolve one client's scope, defaulting to READ-ONLY when the operator gave
+ * none. The default is the security posture of the whole feature: a client
+ * added without thinking about scope gets the risk class that cannot execute
+ * code (see the RCE framing in management-policy.ts).
+ */
+export function resolveClientScope(file) {
+    if (!file)
+        return { ...DEFAULT_READ_ONLY_SCOPE };
+    const projects = toList(file.projects) ?? [...DEFAULT_READ_ONLY_SCOPE.projects];
+    const allow = toList(file.allow) ?? [...DEFAULT_READ_ONLY_SCOPE.allow];
+    const deny = toList(file.deny) ?? [];
+    const denyProjects = toList(file.denyProjects);
+    const maxSpawnDepth = toOptionalInt(file.maxSpawnDepth);
+    return {
+        projects,
+        allow,
+        deny,
+        ...(denyProjects && denyProjects.length > 0 ? { denyProjects } : {}),
+        ...(maxSpawnDepth !== undefined ? { maxSpawnDepth } : {}),
+    };
+}
+/**
+ * Resolve the `managementApi` block against `env`.
+ *
+ * Never throws: a bad client is reported and dropped so one typo can't take the
+ * whole instance down (the browser UI and keepers are unaffected by management-
+ * API config). The caller logs `errors`/`warnings` at boot.
+ */
+export function resolveManagementApiConfig(file, env) {
+    const errors = [];
+    const warnings = [];
+    const clients = [];
+    const instanceId = file?.instanceId?.trim() || undefined;
+    const entries = Object.entries(file?.clients ?? {});
+    // Which peers may tell us "this arrived over https" (#474). Env wins over the
+    // file, matching every other setting's precedence; saying nothing yields the
+    // compatibility default rather than a strict list, so an existing deployment
+    // behind a TLS-terminating sidecar keeps working across the upgrade.
+    const trustedProxiesRaw = env.PADDOCK_MANAGEMENT_TRUSTED_PROXIES ?? file?.trustedProxies;
+    const parsedProxies = parseTrustedProxies(trustedProxiesRaw);
+    errors.push(...parsedProxies.errors);
+    warnings.push(...parsedProxies.warnings);
+    const trustedProxies = parsedProxies.trusted;
+    // Resolve the canonical public URL up front: it gates the whole surface, so a
+    // bad or missing value must fail the feature closed rather than half-enable it.
+    let publicUrl;
+    const rawPublicUrl = file?.publicUrl?.trim();
+    if (rawPublicUrl) {
+        const checked = validatePublicUrl(rawPublicUrl);
+        if ("error" in checked) {
+            errors.push(`managementApi.publicUrl: ${checked.error} — the management API is disabled`);
+            return {
+                config: {
+                    clients: [],
+                    ...(instanceId ? { instanceId } : {}),
+                    trustedProxies,
+                },
+                errors,
+                warnings,
+            };
+        }
+        publicUrl = checked.url;
+    }
+    else if (entries.length > 0) {
+        // Required whenever clients exist. Enforced in M1 (before any client can be
+        // configured) so that turning on M2's discovery is a no-op for the operator
+        // rather than a breaking config change.
+        errors.push("managementApi.publicUrl: required when managementApi.clients is set (the canonical " +
+            "public origin clients reach this instance at, e.g. https://paddock.example.com) — " +
+            "the management API is disabled");
+        return {
+            config: {
+                clients: [],
+                ...(instanceId ? { instanceId } : {}),
+                trustedProxies,
+            },
+            errors,
+            warnings,
+        };
+    }
+    for (const [rawId, raw] of entries) {
+        const clientId = rawId.trim();
+        if (clientId.length === 0) {
+            errors.push("managementApi.clients: a client key is empty — skipped");
+            continue;
+        }
+        const where = `managementApi.clients.${clientId}`;
+        if (!raw || typeof raw !== "object") {
+            errors.push(`${where}: not a mapping — skipped`);
+            continue;
+        }
+        const auth = raw.auth ?? {};
+        // Hard error: a secret written INTO the git-tracked config file.
+        if (auth.token !== undefined || auth.secret !== undefined) {
+            errors.push(`${where}.auth: inline token material is not allowed (the config file is ` +
+                `git-tracked). Use \`ref: env:VAR_NAME\` and set the value in the environment — skipped`);
+            continue;
+        }
+        const type = (auth.type ?? "token").trim();
+        if (type !== "token") {
+            errors.push(`${where}.auth.type: unsupported type "${type}" (M1 supports "token") — skipped`);
+            continue;
+        }
+        const ref = auth.ref?.trim();
+        if (!ref) {
+            errors.push(`${where}.auth.ref: required (e.g. \`env:PADDOCK_MCP_TOKEN_${clientId
+                .toUpperCase()
+                .replace(/[^A-Z0-9]/g, "_")}\`) — skipped`);
+            continue;
+        }
+        if (!ref.startsWith("env:")) {
+            errors.push(`${where}.auth.ref: must be an \`env:VAR_NAME\` reference (got "${ref}") — skipped`);
+            continue;
+        }
+        const varName = ref.slice("env:".length).trim();
+        if (varName.length === 0) {
+            errors.push(`${where}.auth.ref: names no environment variable — skipped`);
+            continue;
+        }
+        const token = env[varName]?.trim();
+        if (!token) {
+            // Fail-closed drop, not a boot failure: the credential doesn't exist, so
+            // nothing can authenticate as this client.
+            warnings.push(`${where}: environment variable ${varName} is unset or empty — client disabled`);
+            continue;
+        }
+        if (token.length < MIN_TOKEN_LENGTH) {
+            warnings.push(`${where}: token from ${varName} is shorter than ${MIN_TOKEN_LENGTH} characters — client disabled`);
+            continue;
+        }
+        // Instance binding advice (enforcement happens in the authenticator).
+        const embedded = tokenInstanceId(token);
+        if (embedded === undefined) {
+            warnings.push(`${where}: token from ${varName} has no \`${TOKEN_PREFIX}<instanceId>_\` prefix, so it is ` +
+                `NOT bound to this instance — the same value would authenticate at any Paddock that ` +
+                `configures it. Prefer a prefixed token.`);
+        }
+        else if (instanceId && embedded !== instanceId) {
+            warnings.push(`${where}: token from ${varName} is bound to instance "${embedded}" but this instance is ` +
+                `"${instanceId}" — it will be REJECTED at authentication. Check which instance minted it.`);
+        }
+        else if (!instanceId) {
+            warnings.push(`${where}: token from ${varName} is bound to instance "${embedded}" but ` +
+                `managementApi.instanceId is not set, so the binding cannot be enforced.`);
+        }
+        const scope = resolveClientScope(raw.scope);
+        if (grantsCodeExecution(scope)) {
+            // Deliberately loud: this grant is code execution on the host.
+            warnings.push(`${where}: scope grants code-execution operations — this client can run code on this host ` +
+                `(a spawned keeper has a shell; create_project clones a caller-supplied URL). Ensure its ` +
+                `token is treated as a production secret.`);
+        }
+        clients.push({ clientId, token, scope });
+    }
+    const authorizationServers = toList(file?.authorizationServers) ?? [];
+    return {
+        config: {
+            clients,
+            ...(instanceId ? { instanceId } : {}),
+            ...(publicUrl ? { publicUrl } : {}),
+            ...(authorizationServers.length > 0 ? { authorizationServers } : {}),
+            trustedProxies,
+        },
+        errors,
+        warnings,
+    };
+}

package/packages/server/dist/management-mcp-server.d.ts

@@ -0,0 +1,20 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { InjectedMcpServerDef } from "@herdctl/core";
+import { type ManagementPrincipal } from "./management-policy.js";
+/** Server identity advertised in the MCP `initialize` handshake. */
+export declare const MANAGEMENT_MCP_SERVER_NAME = "paddock";
+/**
+ * Package version, advertised to the client so it can report which Paddock it
+ * is talking to. Resolved at runtime (dist/management-mcp-server.js →
+ * ../package.json), the same way app.ts resolves it for the OpenAPI document,
+ * so it tracks releases without a build step.
+ */
+export declare const MANAGEMENT_MCP_SERVER_VERSION: string;
+/**
+ * Build an MCP server exposing `def`'s tools to `principal`.
+ *
+ * One server instance per request (the transport is stateless), so nothing here
+ * is shared across callers and a principal's tool visibility can never leak into
+ * another's session.
+ */
+export declare function buildManagementMcpServer(def: InjectedMcpServerDef, principal: ManagementPrincipal): Server;

package/packages/server/dist/management-mcp-server.js

@@ -0,0 +1,95 @@
+/**
+ * The MCP server for external Management API callers (issue #312 M2).
+ *
+ * Adapts the SAME tool definitions the in-process keeper gets — an
+ * {@link InjectedMcpServerDef} produced by `selfMcpServerDefForOps` — onto the
+ * official MCP SDK, so an external client sees exactly the toolset a keeper
+ * sees, minus whatever its scope hides. Nothing is redefined here: if a tool is
+ * added to the self-MCP, it appears over `/mcp` with no further work, which is
+ * the "upgrade the server, every client's toolset upgrades" property the epic
+ * calls out.
+ *
+ * ── Why the LOW-LEVEL `Server`, not `McpServer` ────────────────────────────
+ * The high-level `McpServer.registerTool` wants Zod schemas and converts them to
+ * JSON Schema for the wire. Our tools already carry hand-written JSON Schema
+ * (shared with herdctl's injected-MCP bridge), so going through Zod would mean
+ * translating JSON Schema → Zod → JSON Schema and hoping the round trip is
+ * faithful. Implementing `tools/list` + `tools/call` directly passes our schemas
+ * through verbatim and keeps ONE source of truth for the tool surface.
+ */
+import { createRequire } from "node:module";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { ManagementDeniedError } from "./management-policy.js";
+/** Server identity advertised in the MCP `initialize` handshake. */
+export const MANAGEMENT_MCP_SERVER_NAME = "paddock";
+/**
+ * Package version, advertised to the client so it can report which Paddock it
+ * is talking to. Resolved at runtime (dist/management-mcp-server.js →
+ * ../package.json), the same way app.ts resolves it for the OpenAPI document,
+ * so it tracks releases without a build step.
+ */
+export const MANAGEMENT_MCP_SERVER_VERSION = (() => {
+    try {
+        const require = createRequire(import.meta.url);
+        return require("../package.json").version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
+/**
+ * Build an MCP server exposing `def`'s tools to `principal`.
+ *
+ * One server instance per request (the transport is stateless), so nothing here
+ * is shared across callers and a principal's tool visibility can never leak into
+ * another's session.
+ */
+export function buildManagementMcpServer(def, principal) {
+    const server = new Server({ name: MANAGEMENT_MCP_SERVER_NAME, version: MANAGEMENT_MCP_SERVER_VERSION }, { capabilities: { tools: {} } });
+    const byName = new Map(def.tools.map((t) => [t.name, t]));
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: def.tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            // Passed through verbatim — see the module header.
+            inputSchema: t.inputSchema,
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const tool = byName.get(request.params.name);
+        // A tool hidden by scope is simply absent from the map, so an external caller
+        // guessing a name it wasn't offered gets the same answer as for a typo.
+        if (!tool) {
+            return {
+                content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],
+                isError: true,
+            };
+        }
+        try {
+            const result = await tool.handler((request.params.arguments ?? {}));
+            return result;
+        }
+        catch (error) {
+            // A policy denial is a normal, expected outcome for a scoped caller — it
+            // must reach the model as a readable tool error rather than blowing up the
+            // JSON-RPC layer. (The HTTP 403 + `insufficient_scope` challenge is the
+            // right shape for a REQUEST-level refusal; a denial DURING a tool call is
+            // already past that point, so it is reported in-band.)
+            if (error instanceof ManagementDeniedError) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${error.message} (client "${principal.clientId}"; operation "${error.operation}")`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+        }
+    });
+    return server;
+}

package/packages/server/dist/management-metadata.d.ts

@@ -0,0 +1,67 @@
+/**
+ * RFC 9728 protected-resource metadata (issue #312 M2).
+ *
+ * The document an MCP client fetches to learn HOW to authenticate against
+ * `/mcp`. Paddock publishes this itself: it is the resource server's job, and
+ * IdPs do not emit it.
+ *
+ * ── Two things here are easy to get wrong ──────────────────────────────────
+ *
+ * 1. **`resource` must byte-match the URL the client used** (RFC 9728 §3.3) —
+ *    a mismatch means the client MUST discard the document. So it is built from
+ *    the operator-configured `publicUrl`, never from `req.headers.host`: behind
+ *    a TLS-terminating proxy the scheme would be wrong, and the header is
+ *    attacker-controlled anyway.
+ *
+ * 2. **The URL is path-INSERTED, not path-appended.** For a resource at
+ *    `https://host/mcp` the metadata lives at
+ *    `https://host/.well-known/oauth-protected-resource/mcp` — the well-known
+ *    segment goes between the host and the resource path. A verified trace of a
+ *    real Claude Code session showed it requests ONLY that form and never the
+ *    bare root, so serving the root alone leaves discovery silently broken. We
+ *    serve both and rely on the path-inserted one.
+ */
+import type { ManagementApiConfig } from "./management-config.js";
+/** The well-known prefix, per RFC 9728. */
+export declare const PROTECTED_RESOURCE_METADATA_PREFIX = "/.well-known/oauth-protected-resource";
+/** The MCP resource path this instance serves. */
+export declare const MCP_RESOURCE_PATH = "/mcp";
+/** The RFC 9728 document. `authorization_servers` is optional in the RFC but MANDATORY per MCP. */
+export interface ProtectedResourceMetadata {
+    resource: string;
+    authorization_servers?: string[];
+    scopes_supported: string[];
+    bearer_methods_supported: string[];
+    resource_name: string;
+    resource_documentation?: string;
+}
+/** The canonical resource identifier — what a client must byte-match. */
+export declare function resourceIdentifier(cfg: ManagementApiConfig): string | undefined;
+/**
+ * The absolute, path-inserted metadata URL (what clients actually request), or
+ * undefined when no document will be served — pointing a client at a URL that
+ * 404s is worse than omitting the pointer, since `resource_metadata` is a
+ * promise that discovery will work.
+ */
+export declare function metadataUrl(cfg: ManagementApiConfig): string | undefined;
+/**
+ * Build the metadata document, or undefined when it cannot be built COMPLETELY.
+ *
+ * Requires an authorization server. RFC 9728 makes `authorization_servers`
+ * optional, but the MCP spec makes it mandatory ("MUST include the
+ * `authorization_servers` field containing at least one authorization server"),
+ * and a token-only deployment has none — so rather than publish a document the
+ * governing spec calls invalid, we publish nothing.
+ *
+ * This is not theoretical. A discovery trace of a real Claude Code session
+ * against an earlier build that served the document WITHOUT
+ * `authorization_servers` showed the client fetch it, find no authorization
+ * server, and then go hunting: `/.well-known/oauth-authorization-server`, then
+ * `/.well-known/openid-configuration`, both 404. Publishing nothing produces the
+ * same end state (an OAuth-only client cannot connect without OAuth configured)
+ * without the misleading intermediate step.
+ *
+ * Nothing is lost for the supported path: a client holding a static bearer token
+ * never performs discovery at all.
+ */
+export declare function buildProtectedResourceMetadata(cfg: ManagementApiConfig): ProtectedResourceMetadata | undefined;

package/packages/server/dist/management-metadata.js

@@ -0,0 +1,56 @@
+import { OAUTH_SCOPES_SUPPORTED } from "./management-policy.js";
+/** The well-known prefix, per RFC 9728. */
+export const PROTECTED_RESOURCE_METADATA_PREFIX = "/.well-known/oauth-protected-resource";
+/** The MCP resource path this instance serves. */
+export const MCP_RESOURCE_PATH = "/mcp";
+/** The canonical resource identifier — what a client must byte-match. */
+export function resourceIdentifier(cfg) {
+    return cfg.publicUrl ? `${cfg.publicUrl}${MCP_RESOURCE_PATH}` : undefined;
+}
+/**
+ * The absolute, path-inserted metadata URL (what clients actually request), or
+ * undefined when no document will be served — pointing a client at a URL that
+ * 404s is worse than omitting the pointer, since `resource_metadata` is a
+ * promise that discovery will work.
+ */
+export function metadataUrl(cfg) {
+    if (!cfg.publicUrl)
+        return undefined;
+    if (!cfg.authorizationServers || cfg.authorizationServers.length === 0)
+        return undefined;
+    return `${cfg.publicUrl}${PROTECTED_RESOURCE_METADATA_PREFIX}${MCP_RESOURCE_PATH}`;
+}
+/**
+ * Build the metadata document, or undefined when it cannot be built COMPLETELY.
+ *
+ * Requires an authorization server. RFC 9728 makes `authorization_servers`
+ * optional, but the MCP spec makes it mandatory ("MUST include the
+ * `authorization_servers` field containing at least one authorization server"),
+ * and a token-only deployment has none — so rather than publish a document the
+ * governing spec calls invalid, we publish nothing.
+ *
+ * This is not theoretical. A discovery trace of a real Claude Code session
+ * against an earlier build that served the document WITHOUT
+ * `authorization_servers` showed the client fetch it, find no authorization
+ * server, and then go hunting: `/.well-known/oauth-authorization-server`, then
+ * `/.well-known/openid-configuration`, both 404. Publishing nothing produces the
+ * same end state (an OAuth-only client cannot connect without OAuth configured)
+ * without the misleading intermediate step.
+ *
+ * Nothing is lost for the supported path: a client holding a static bearer token
+ * never performs discovery at all.
+ */
+export function buildProtectedResourceMetadata(cfg) {
+    const resource = resourceIdentifier(cfg);
+    if (!resource)
+        return undefined;
+    if (!cfg.authorizationServers || cfg.authorizationServers.length === 0)
+        return undefined;
+    return {
+        resource,
+        authorization_servers: [...cfg.authorizationServers],
+        scopes_supported: [...OAUTH_SCOPES_SUPPORTED],
+        bearer_methods_supported: ["header"],
+        resource_name: "Paddock Management API",
+    };
+}

package/packages/server/dist/management-ops.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The transport-agnostic Management API ops layer (issue #312 M1).
+ *
+ * This is the single place every management operation is implemented, and the
+ * single place policy is enforced. Two exports carry that:
+ *
+ *   - {@link buildManagementOps} — constructs the operation callbacks (the
+ *     `SelfMcpContext` read bag + `SelfMcpWriteContext` write bag) over the
+ *     shared {@link ChatHandlerContext}. Extracted from `ws-self-mcp.ts`, which
+ *     previously built the ops AND assembled the MCP server def in one function.
+ *     Splitting them is what lets a NON-MCP caller (HTTP now, REST parity in
+ *     #465) reach the same operations.
+ *   - {@link enforceManagementPolicy} — wraps a built ops bag with a
+ *     {@link ManagementPrincipal}, so every call is scope-checked centrally.
+ *
+ * ── Why enforcement is HERE and not in the transport ────────────────────────
+ * The load-bearing decision on #312. If the MCP handler enforced scope, the REST
+ * endpoints of #465 would have to reimplement it, and the two would drift — a
+ * drift whose failure mode is an unchecked write path, i.e. code execution. By
+ * enforcing on the ops themselves, any transport that obtains a principal
+ * inherits the identical checks for free, and a new transport cannot forget.
+ *
+ * ── The in-process keeper path is unchanged ─────────────────────────────────
+ * A keeper is bounded by DEPTH (`maxSpawnDepth`, #278), not by auth+scope: it is
+ * not a distinct identity. It therefore runs under {@link INTERNAL_PRINCIPAL},
+ * whose full scope makes every check below short-circuit to allow. This module
+ * is a pure refactor for keepers — no behaviour change.
+ *
+ * ── Enumerate vs. address ───────────────────────────────────────────────────
+ * A scoped principal listing projects/chats gets a FILTERED view rather than a
+ * denial: "show me what I can see" is a reasonable request, and erroring would
+ * make a narrowly-scoped client useless. Operations that NAME a target are
+ * asserted instead, so an out-of-scope slug is refused loudly.
+ *
+ * ── The root workspace is an ADDRESS, not an absence (#560) ──────────────────
+ * A workspace key is a path relative to `projectsRoot`, so the ROOT's key is the
+ * empty string. Every read here therefore branches on `!== undefined`, never on
+ * truthiness — `if (!projectSlug)` silently retargets a root request at "all
+ * projects", which is exactly the bug #560 reported.
+ */
+import type { ChatHandlerContext } from "./ws-context.js";
+import type { SelfMcpContext, SelfMcpWriteContext } from "./self-mcp.js";
+import { type RunProvenance } from "./run-provenance.js";
+import { type ManagementPrincipal } from "./management-policy.js";
+/**
+ * Frame an agent-initiated FORK kickoff (issue #214 Phase 2). A fork inherits the
+ * parent's transcript as context — and when the parent is the *live* chat doing
+ * the forking, that snapshot is taken mid-turn, so the child would otherwise
+ * inherit the parent's "I am still mid-task" identity and reject the seeded
+ * instruction (observed in QA). This preamble tells the child the history above
+ * is inherited background and that its job now is the given directive — which is
+ * exactly the fan-out contract ("fork this chat N times, one work-item each").
+ */
+export declare function forkKickoffPrompt(directive: string): string;
+/** The built ops. `write` is absent when the caller isn't granted write access. */
+export interface ManagementOps {
+    read: SelfMcpContext;
+    write?: SelfMcpWriteContext;
+}
+export interface ManagementOpsParams {
+    currentProjectSlug: string;
+    currentSessionId: () => string | null;
+    parentProvenance: RunProvenance;
+    includeWrite: boolean;
+    includeTriggers: boolean;
+    /**
+     * Whether to expose `create_project` (#467). Its OWN gate, separate from the
+     * other write tools, because it creates INSTANCE-level state and clones
+     * caller-supplied git URLs.
+     */
+    includeProjects: boolean;
+    /**
+     * Optional ceiling on the spawn depth granted to turns these ops start
+     * (a scoped external principal's `scope.maxSpawnDepth`). Applied as a MINIMUM
+     * against the target project's resolved bound, so a scope can only ever
+     * NARROW what the project would allow, never widen it.
+     */
+    spawnDepthCap?: number;
+}
+/**
+ * Build the management operations bound to one caller's context.
+ *
+ * `parentProvenance` is the provenance of the chat these ops run IN — so any
+ * child they spawn is `childOf(parentProvenance)` (origin `spawned`, depth+1).
+ * The human path passes a human root (depth 0 → children depth 1); the spawned
+ * path passes the current turn's own `{ origin, depth }`, so the `maxSpawnDepth`
+ * bound descends and the tree can't run away.
+ */
+export declare function buildManagementOps(ctx: ChatHandlerContext, params: ManagementOpsParams): ManagementOps;
+/**
+ * Wrap built ops so every call is checked against `principal`.
+ *
+ * Returns the ops UNCHANGED for the internal principal — the keeper path must be
+ * byte-for-byte identical to its pre-#312 behaviour, and skipping the wrapper
+ * entirely is the most honest way to guarantee that.
+ *
+ * The write bag is dropped wholesale when the principal is granted no write
+ * operation, so a read-only client's write tools are ABSENT rather than
+ * present-and-refusing — matching how the existing capability gates behave.
+ */
+export declare function enforceManagementPolicy(ops: ManagementOps, principal: ManagementPrincipal): ManagementOps;
+/**
+ * A predicate selecting which MCP tools a principal should even SEE.
+ *
+ * Tool-list filtering is presentation, not enforcement — the ops wrapper above
+ * is what actually refuses a call. But hiding out-of-scope tools means a client
+ * never offers its model a verb it cannot use, which avoids a whole class of
+ * confusing "the tool exists but always errors" behaviour.
+ */
+export declare function managementToolFilter(principal: ManagementPrincipal): (toolName: string) => boolean;