@edspencer/paddock 0.0.1 → 0.56.0

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

@@ -0,0 +1,99 @@
+import type { ManagementApiConfig } from "./management-config.js";
+import type { ManagementPrincipal, ManagementDeniedError } from "./management-policy.js";
+/** Why a credential was refused. Shapes the challenge; never leaks the secret. */
+export type ManagementAuthFailure = 
+/** No credential presented at all. */
+"missing"
+/** An `Authorization` header we could not parse as a bearer token. */
+ | "malformed"
+/** Parsed fine, but matched no configured client (or failed instance binding). */
+ | "invalid";
+export type ManagementAuthResult = {
+    ok: true;
+    principal: ManagementPrincipal;
+} | {
+    ok: false;
+    failure: ManagementAuthFailure;
+};
+/**
+ * Compare two secrets without leaking their relationship through timing.
+ *
+ * `timingSafeEqual` requires equal-length buffers and throws otherwise — which
+ * would itself leak length. Hashing both sides to a fixed-width digest first
+ * makes the comparison length-independent as well as time-independent.
+ */
+export declare function constantTimeEqual(a: string, b: string): boolean;
+/**
+ * Extract a bearer token from an `Authorization` header value.
+ * Returns undefined when absent, and null when present but not a bearer token
+ * (so the caller can distinguish "missing" from "malformed").
+ */
+export declare function bearerToken(headerValue: string | string[] | undefined): string | null | undefined;
+/**
+ * Match a presented token against the configured clients.
+ *
+ * Scans EVERY client without early-exit so total work does not depend on which
+ * client matched (or on how far down the list a match sits). Instance binding is
+ * checked first: a token carrying an instance id that isn't ours is refused even
+ * if its secret would otherwise match, which is what makes a credential minted
+ * for another Paddock useless here.
+ */
+export declare function resolveTokenPrincipal(token: string, cfg: ManagementApiConfig): ManagementPrincipal | null;
+/**
+ * Authenticate a request's `Authorization` header against the configured
+ * clients. The caller decides the HTTP shape (see {@link challengeHeader}).
+ */
+export declare function authenticateManagementRequest(authorization: string | string[] | undefined, cfg: ManagementApiConfig): ManagementAuthResult;
+/**
+ * Build the `WWW-Authenticate` challenge for a refusal (RFC 6750 §3).
+ *
+ * `resourceMetadataUrl` is the RFC 9728 protected-resource-metadata location.
+ * M2 supplies it so an MCP client can discover how to obtain a token; M1 omits
+ * it (there is no OAuth path yet) and the header still forms a valid challenge.
+ */
+export declare function challengeHeader(failure: ManagementAuthFailure, resourceMetadataUrl?: string): string;
+/**
+ * The challenge for an authenticated caller whose SCOPE doesn't cover what it
+ * asked for (MCP spec revision 2025-11-25 / RFC 6750 §3.1).
+ *
+ * Deliberately distinct from the 401 above: the credential was valid, so
+ * re-authenticating changes nothing — the caller needs a WIDER GRANT. The
+ * transport pairs this with **403**, and the `scope` parameter names what was
+ * required, which is what lets a client ask for incremental consent instead of
+ * failing opaquely.
+ */
+export declare function insufficientScopeChallenge(requiredScope: string, resourceMetadataUrl?: string): string;
+/**
+ * The HTTP shape for a policy denial raised by the ops layer.
+ *
+ * Kept HERE, next to the other challenge builders, so that every transport maps
+ * a `ManagementDeniedError` the same way instead of inventing its own status.
+ * Both denial codes are scope problems, hence 403 rather than 401.
+ */
+export declare function denialResponse(error: ManagementDeniedError, resourceMetadataUrl?: string): {
+    status: 403;
+    challenge: string;
+    body: {
+        error: string;
+        code: string;
+        message: string;
+    };
+};
+/**
+ * The RFC 9728 protected-resource metadata URL to advertise in a challenge.
+ *
+ * Delegates to {@link metadataUrl} so there is ONE rule for when a document
+ * exists: advertising a `resource_metadata` URL that then 404s would send a
+ * client down a discovery path that cannot succeed.
+ */
+export declare function resourceMetadataUrl(cfg: ManagementApiConfig): string | undefined;
+/**
+ * Whether the external management API is configured at all (drives the 404).
+ *
+ * Requires BOTH a client and a canonical public URL: without the latter, M2's
+ * discovery document could not be served correctly, so the surface stays off
+ * rather than half-working. `resolveManagementApiConfig` already empties the
+ * client list when `publicUrl` is missing or bad; this is the belt to that
+ * braces.
+ */
+export declare function isManagementApiEnabled(cfg: ManagementApiConfig | undefined): boolean;

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

@@ -0,0 +1,165 @@
+/**
+ * Management API authentication (issue #312 M1) — the config-token authenticator.
+ *
+ * Turns a presented credential into a {@link ManagementPrincipal}, or refuses.
+ * Transport-agnostic: it takes a header value and returns a verdict, so the
+ * `/mcp` route, a future REST surface (#465), and tests all share one path.
+ *
+ * ── This is INDEPENDENT of `PADDOCK_AUTH_MODE` and of any reverse proxy ─────
+ * The non-negotiable invariant on the ticket: Paddock authenticates the
+ * management surface ITSELF. It must be possible to run with no proxy at all —
+ * even `auth.mode: none` — and still have a correctly authenticated `/mcp`. A
+ * proxy is an operator's choice, never a prerequisite. Consequently `/mcp` is
+ * exempted from the browser auth hook (auth.ts) and gated by THIS instead; the
+ * exemption is safe only because this runs in its place.
+ *
+ * ── Why 401 + WWW-Authenticate, never a 302 ────────────────────────────────
+ * An SSO proxy answers an unauthenticated request with an HTML login redirect.
+ * That breaks MCP clients outright: they cannot follow it, and OAuth discovery
+ * (M2) depends on reading a real `401` + `WWW-Authenticate` challenge. So this
+ * module owns the challenge header and always fails with a status an MCP client
+ * can act on.
+ */
+import { createHash, timingSafeEqual } from "node:crypto";
+import { tokenInstanceId } from "./management-config.js";
+import { metadataUrl } from "./management-metadata.js";
+/**
+ * Compare two secrets without leaking their relationship through timing.
+ *
+ * `timingSafeEqual` requires equal-length buffers and throws otherwise — which
+ * would itself leak length. Hashing both sides to a fixed-width digest first
+ * makes the comparison length-independent as well as time-independent.
+ */
+export function constantTimeEqual(a, b) {
+    const ha = createHash("sha256").update(a, "utf8").digest();
+    const hb = createHash("sha256").update(b, "utf8").digest();
+    return timingSafeEqual(ha, hb);
+}
+/**
+ * Extract a bearer token from an `Authorization` header value.
+ * Returns undefined when absent, and null when present but not a bearer token
+ * (so the caller can distinguish "missing" from "malformed").
+ */
+export function bearerToken(headerValue) {
+    const raw = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+    if (raw === undefined || raw.trim().length === 0)
+        return undefined;
+    const m = /^Bearer[ \t]+(.+)$/i.exec(raw.trim());
+    if (!m)
+        return null;
+    const token = m[1].trim();
+    return token.length > 0 ? token : null;
+}
+/**
+ * Match a presented token against the configured clients.
+ *
+ * Scans EVERY client without early-exit so total work does not depend on which
+ * client matched (or on how far down the list a match sits). Instance binding is
+ * checked first: a token carrying an instance id that isn't ours is refused even
+ * if its secret would otherwise match, which is what makes a credential minted
+ * for another Paddock useless here.
+ */
+export function resolveTokenPrincipal(token, cfg) {
+    const embedded = tokenInstanceId(token);
+    // A prefixed token names its instance; enforce it when we know our own.
+    if (embedded !== undefined && cfg.instanceId !== undefined && embedded !== cfg.instanceId) {
+        return null;
+    }
+    let matched = null;
+    for (const client of cfg.clients) {
+        if (constantTimeEqual(token, client.token))
+            matched = client;
+    }
+    if (!matched)
+        return null;
+    return { clientId: matched.clientId, kind: "token", scope: matched.scope };
+}
+/**
+ * Authenticate a request's `Authorization` header against the configured
+ * clients. The caller decides the HTTP shape (see {@link challengeHeader}).
+ */
+export function authenticateManagementRequest(authorization, cfg) {
+    const token = bearerToken(authorization);
+    if (token === undefined)
+        return { ok: false, failure: "missing" };
+    if (token === null)
+        return { ok: false, failure: "malformed" };
+    const principal = resolveTokenPrincipal(token, cfg);
+    if (!principal)
+        return { ok: false, failure: "invalid" };
+    return { ok: true, principal };
+}
+/**
+ * Build the `WWW-Authenticate` challenge for a refusal (RFC 6750 §3).
+ *
+ * `resourceMetadataUrl` is the RFC 9728 protected-resource-metadata location.
+ * M2 supplies it so an MCP client can discover how to obtain a token; M1 omits
+ * it (there is no OAuth path yet) and the header still forms a valid challenge.
+ */
+export function challengeHeader(failure, resourceMetadataUrl) {
+    const params = ['realm="paddock"'];
+    if (failure !== "missing") {
+        params.push('error="invalid_token"');
+        params.push(`error_description="${failure === "malformed" ? "malformed Authorization header" : "the access token is invalid"}"`);
+    }
+    if (resourceMetadataUrl)
+        params.push(`resource_metadata="${resourceMetadataUrl}"`);
+    return `Bearer ${params.join(", ")}`;
+}
+/**
+ * The challenge for an authenticated caller whose SCOPE doesn't cover what it
+ * asked for (MCP spec revision 2025-11-25 / RFC 6750 §3.1).
+ *
+ * Deliberately distinct from the 401 above: the credential was valid, so
+ * re-authenticating changes nothing — the caller needs a WIDER GRANT. The
+ * transport pairs this with **403**, and the `scope` parameter names what was
+ * required, which is what lets a client ask for incremental consent instead of
+ * failing opaquely.
+ */
+export function insufficientScopeChallenge(requiredScope, resourceMetadataUrl) {
+    const params = [
+        'realm="paddock"',
+        'error="insufficient_scope"',
+        `error_description="the authenticated client's scope does not permit this operation"`,
+        `scope="${requiredScope}"`,
+    ];
+    if (resourceMetadataUrl)
+        params.push(`resource_metadata="${resourceMetadataUrl}"`);
+    return `Bearer ${params.join(", ")}`;
+}
+/**
+ * The HTTP shape for a policy denial raised by the ops layer.
+ *
+ * Kept HERE, next to the other challenge builders, so that every transport maps
+ * a `ManagementDeniedError` the same way instead of inventing its own status.
+ * Both denial codes are scope problems, hence 403 rather than 401.
+ */
+export function denialResponse(error, resourceMetadataUrl) {
+    return {
+        status: 403,
+        challenge: insufficientScopeChallenge(error.code === "project_denied" ? `project:${error.projectSlug}` : error.operation, resourceMetadataUrl),
+        body: { error: "forbidden", code: error.code, message: error.message },
+    };
+}
+/**
+ * The RFC 9728 protected-resource metadata URL to advertise in a challenge.
+ *
+ * Delegates to {@link metadataUrl} so there is ONE rule for when a document
+ * exists: advertising a `resource_metadata` URL that then 404s would send a
+ * client down a discovery path that cannot succeed.
+ */
+export function resourceMetadataUrl(cfg) {
+    return metadataUrl(cfg);
+}
+/**
+ * Whether the external management API is configured at all (drives the 404).
+ *
+ * Requires BOTH a client and a canonical public URL: without the latter, M2's
+ * discovery document could not be served correctly, so the surface stays off
+ * rather than half-working. `resolveManagementApiConfig` already empties the
+ * client list when `publicUrl` is missing or bad; this is the belt to that
+ * braces.
+ */
+export function isManagementApiEnabled(cfg) {
+    return (cfg?.clients.length ?? 0) > 0 && Boolean(cfg?.publicUrl);
+}

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

@@ -0,0 +1,164 @@
+/**
+ * `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 { type ManagementScope } from "./management-policy.js";
+import { type TrustedProxies } 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 declare 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 declare const MIN_TOKEN_LENGTH = 24;
+/** One resolved external client: an identity, a credential, and a scope. */
+export interface ManagementClient {
+    /** The `managementApi.clients` map key — the stable, loggable identity. */
+    clientId: string;
+    /** The resolved secret. NEVER logged, never echoed in an API response. */
+    token: string;
+    scope: ManagementScope;
+}
+/** The resolved management-API config. */
+export interface ManagementApiConfig {
+    /**
+     * Resolved external clients. EMPTY means the external management API is off
+     * entirely and `/mcp` must 404 (fail closed) — see routes/mcp.ts.
+     */
+    clients: ManagementClient[];
+    /**
+     * This instance's identifier, used to bind prefixed tokens to it. Absent ⇒
+     * binding is not enforced (an unprefixed-token deployment still works).
+     */
+    instanceId?: string;
+    /**
+     * The canonical PUBLIC origin clients reach this instance at, with no trailing
+     * slash (e.g. `https://paddock.example.com`).
+     *
+     * Required whenever clients are configured, because RFC 9728 §3.3 makes the
+     * `resource` value in the protected-resource metadata document a byte-for-byte
+     * match against the URL the client used — a mismatch means the client MUST
+     * discard the document. It cannot be derived from `Host`: behind a
+     * TLS-terminating proxy the scheme is wrong, and the header is
+     * attacker-controlled. So the operator states it once, here.
+     */
+    publicUrl?: string;
+    /**
+     * Issuer URLs of the OAuth authorization servers that may issue tokens for
+     * this resource, advertised in the RFC 9728 discovery document.
+     *
+     * Optional and empty by default: with only config tokens configured there IS
+     * no authorization server, and advertising one would send clients into an
+     * OAuth flow that cannot complete. Populated when the OAuth authenticator is
+     * configured.
+     */
+    authorizationServers?: string[];
+    /**
+     * Peers whose `X-Forwarded-Proto` the `/mcp` plaintext guard believes (#474).
+     * Absent ⇒ the compatibility default (loopback + private address space); see
+     * trusted-proxy.ts for what that default does and does not prove.
+     */
+    trustedProxies?: TrustedProxies;
+}
+/** On-disk shape of the `managementApi` block. Every field optional. */
+export interface ManagementApiConfigFile {
+    instanceId?: string;
+    publicUrl?: string;
+    authorizationServers?: string[] | string;
+    /** IPs / CIDRs / presets — see {@link parseTrustedProxies}. */
+    trustedProxies?: string[] | string;
+    clients?: Record<string, ManagementClientConfigFile | null | undefined>;
+}
+/**
+ * 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 declare function validatePublicUrl(raw: string): {
+    url: string;
+} | {
+    error: string;
+};
+export interface ManagementClientConfigFile {
+    auth?: {
+        type?: string;
+        /** `env:VAR_NAME` — the ONLY supported form. An inline value is an error. */
+        ref?: string;
+        /** Present only in a MISCONFIGURED file; its presence is a hard error. */
+        token?: string;
+        secret?: string;
+    };
+    scope?: {
+        projects?: string[] | string;
+        allow?: string[] | string;
+        deny?: string[] | string;
+        denyProjects?: string[] | string;
+        maxSpawnDepth?: number | string;
+    };
+}
+/** Outcome of resolving the block: the clients plus everything worth telling the operator. */
+export interface ManagementConfigResolution {
+    config: ManagementApiConfig;
+    /** Fatal-to-that-client misconfigurations (logged at error level). */
+    errors: string[];
+    /** Non-fatal advice + dropped-client notices (logged at warn level). */
+    warnings: string[];
+}
+/**
+ * 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 declare function tokenInstanceId(token: string): string | undefined;
+/**
+ * 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 declare function resolveClientScope(file: ManagementClientConfigFile["scope"]): ManagementScope;
+/**
+ * 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 declare function resolveManagementApiConfig(file: ManagementApiConfigFile | undefined, env: Record<string, string | undefined>): ManagementConfigResolution;