@wardby/cli 0.1.0

package/dist/observability/metrics-server.js

@@ -0,0 +1,47 @@
+import { createServer } from "node:http";
+/** Serve the Prometheus exposition endpoint on an explicitly private listener. */
+export async function startMetricsServer(registry, config) {
+    const server = createServer({ maxHeaderSize: 8 * 1024, requireHostHeader: false }, (request, response) => {
+        void (async () => {
+            if (request.method === "GET" && request.url === "/healthz") {
+                response
+                    .writeHead(200, { "cache-control": "no-store", "content-type": "text/plain; charset=utf-8" })
+                    .end("ok\n");
+                return;
+            }
+            if (request.method === "GET" && request.url === "/metrics") {
+                response
+                    .writeHead(200, { "cache-control": "no-store", "content-type": registry.contentType })
+                    .end(await registry.metrics());
+                return;
+            }
+            response
+                .writeHead(404, { "cache-control": "no-store", "content-type": "text/plain; charset=utf-8" })
+                .end("not found\n");
+        })().catch(() => {
+            if (!response.headersSent) {
+                response
+                    .writeHead(500, { "cache-control": "no-store", "content-type": "text/plain; charset=utf-8" })
+                    .end("internal error\n");
+            }
+            else if (!response.destroyed) {
+                response.destroy();
+            }
+        });
+    });
+    server.requestTimeout = 10_000;
+    server.headersTimeout = 10_000;
+    server.keepAliveTimeout = 5_000;
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(config.port, config.host, resolve);
+    });
+    const address = server.address();
+    return {
+        port: typeof address === "object" && address ? address.port : config.port,
+        close: () => new Promise((resolve, reject) => {
+            server.close((error) => (error ? reject(error) : resolve()));
+            server.closeIdleConnections();
+        }),
+    };
+}

package/dist/observability/metrics.d.ts

@@ -0,0 +1,36 @@
+import { Registry } from "@prometheus-io/client";
+import type { CodingLifecycleEvent, CodingRunObserver } from "../coding/observability.js";
+import type { ProxyAuditEvent } from "../providers/coding-proxy/types.js";
+type ProxyProtocolLabel = "openai-responses" | "anthropic-messages" | "other";
+export interface ProxyHttpMetricEvent {
+    protocol: ProxyProtocolLabel;
+    status: number;
+    durationMs: number;
+}
+/**
+ * Prometheus adapter for the metadata-only lifecycle and proxy audit signals.
+ * Labels are deliberately finite enums: run IDs, request IDs, models, reasons,
+ * credentials, and untrusted input never enter the metrics registry.
+ */
+export declare class WardbyMetrics implements CodingRunObserver {
+    readonly registry: Registry;
+    private readonly lifecycleEvents;
+    private readonly terminalRuns;
+    private readonly activeJobs;
+    private readonly cleanupFailures;
+    private readonly budgetReserved;
+    private readonly budgetActual;
+    private readonly runDuration;
+    private readonly proxyAuditEvents;
+    private readonly proxyRequests;
+    private readonly proxyRequestDuration;
+    private readonly proxyBudgetReserved;
+    private readonly proxyCost;
+    private readonly proxyTokens;
+    private activeJobCount;
+    constructor(registry?: Registry<import("@prometheus-io/client").RegistryContentType>);
+    emit(event: CodingLifecycleEvent): void;
+    observeProxyAudit: (event: ProxyAuditEvent) => void;
+    observeProxyRequest(event: ProxyHttpMetricEvent): void;
+}
+export {};

package/dist/observability/metrics.js

@@ -0,0 +1,158 @@
+import { Counter, Gauge, Histogram, Registry, collectDefaultMetrics } from "@prometheus-io/client";
+function statusClass(status) {
+    if (status >= 100 && status < 200)
+        return "1xx";
+    if (status >= 200 && status < 300)
+        return "2xx";
+    if (status >= 300 && status < 400)
+        return "3xx";
+    if (status >= 400 && status < 500)
+        return "4xx";
+    if (status >= 500 && status < 600)
+        return "5xx";
+    return "other";
+}
+/**
+ * Prometheus adapter for the metadata-only lifecycle and proxy audit signals.
+ * Labels are deliberately finite enums: run IDs, request IDs, models, reasons,
+ * credentials, and untrusted input never enter the metrics registry.
+ */
+export class WardbyMetrics {
+    registry;
+    lifecycleEvents;
+    terminalRuns;
+    activeJobs;
+    cleanupFailures;
+    budgetReserved;
+    budgetActual;
+    runDuration;
+    proxyAuditEvents;
+    proxyRequests;
+    proxyRequestDuration;
+    proxyBudgetReserved;
+    proxyCost;
+    proxyTokens;
+    activeJobCount = 0;
+    constructor(registry = new Registry()) {
+        this.registry = registry;
+        collectDefaultMetrics({ register: registry, prefix: "wardby_nodejs_" });
+        this.lifecycleEvents = new Counter({
+            name: "wardby_coding_lifecycle_events_total",
+            help: "Coding lifecycle events by finite stage.",
+            labelNames: ["stage"],
+            registers: [registry],
+        });
+        this.terminalRuns = new Counter({
+            name: "wardby_coding_runs_terminal_total",
+            help: "Completed coding runs by terminal outcome.",
+            labelNames: ["outcome"],
+            registers: [registry],
+        });
+        this.activeJobs = new Gauge({
+            name: "wardby_coding_active_jobs",
+            help: "Coding jobs launched by this process that have not completed cleanup.",
+            registers: [registry],
+        });
+        this.cleanupFailures = new Counter({
+            name: "wardby_coding_cleanup_failures_total",
+            help: "Coding cleanup attempts that failed.",
+            registers: [registry],
+        });
+        this.budgetReserved = new Counter({
+            name: "wardby_coding_budget_reserved_usd_total",
+            help: "USD budget reserved for coding runs.",
+            registers: [registry],
+        });
+        this.budgetActual = new Counter({
+            name: "wardby_coding_budget_actual_usd_total",
+            help: "USD budget charged for coding runs.",
+            registers: [registry],
+        });
+        this.runDuration = new Histogram({
+            name: "wardby_coding_run_duration_seconds",
+            help: "Observed coding run duration in seconds.",
+            buckets: [1, 10, 30, 60, 300, 900, 1800, 3600],
+            registers: [registry],
+        });
+        this.proxyAuditEvents = new Counter({
+            name: "wardby_proxy_audit_events_total",
+            help: "Trusted coding proxy audit events by finite event type.",
+            labelNames: ["event"],
+            registers: [registry],
+        });
+        this.proxyRequests = new Counter({
+            name: "wardby_proxy_http_requests_total",
+            help: "Coding proxy HTTP requests by protocol and status class.",
+            labelNames: ["protocol", "status_class"],
+            registers: [registry],
+        });
+        this.proxyRequestDuration = new Histogram({
+            name: "wardby_proxy_http_request_duration_seconds",
+            help: "Coding proxy HTTP request duration by protocol and status class.",
+            labelNames: ["protocol", "status_class"],
+            buckets: [0.01, 0.05, 0.1, 0.5, 1, 5, 15, 60, 300],
+            registers: [registry],
+        });
+        this.proxyBudgetReserved = new Counter({
+            name: "wardby_proxy_budget_reserved_usd_total",
+            help: "USD budget reserved by trusted coding proxy requests.",
+            registers: [registry],
+        });
+        this.proxyCost = new Counter({
+            name: "wardby_proxy_cost_usd_total",
+            help: "USD cost reported by completed upstream proxy responses.",
+            registers: [registry],
+        });
+        this.proxyTokens = new Counter({
+            name: "wardby_proxy_tokens_total",
+            help: "Token usage reported by completed upstream proxy responses by token kind.",
+            labelNames: ["kind"],
+            registers: [registry],
+        });
+    }
+    emit(event) {
+        this.lifecycleEvents.inc({ stage: event.stage });
+        if (event.stage === "launched") {
+            this.activeJobCount += 1;
+            this.activeJobs.set(this.activeJobCount);
+        }
+        if (event.stage === "cleanup") {
+            this.activeJobCount = Math.max(0, this.activeJobCount - 1);
+            this.activeJobs.set(this.activeJobCount);
+            if (event.cleanupSucceeded === false)
+                this.cleanupFailures.inc();
+        }
+        if (event.stage === "terminal" && event.outcome)
+            this.terminalRuns.inc({ outcome: event.outcome });
+        if (event.budgetReservedUsd !== undefined)
+            this.budgetReserved.inc(event.budgetReservedUsd);
+        if (event.budgetActualUsd !== undefined)
+            this.budgetActual.inc(event.budgetActualUsd);
+        if (event.durationMs !== undefined)
+            this.runDuration.observe(event.durationMs / 1_000);
+    }
+    observeProxyAudit = (event) => {
+        this.proxyAuditEvents.inc({ event: event.type });
+        if (event.reservationUsd !== undefined)
+            this.proxyBudgetReserved.inc(event.reservationUsd);
+        if (event.type !== "response.completed")
+            return;
+        if (event.costUsd !== undefined)
+            this.proxyCost.inc(event.costUsd);
+        if (event.inputTokens !== undefined)
+            this.proxyTokens.inc({ kind: "input" }, event.inputTokens);
+        if (event.outputTokens !== undefined)
+            this.proxyTokens.inc({ kind: "output" }, event.outputTokens);
+        if (event.cachedInputTokens !== undefined)
+            this.proxyTokens.inc({ kind: "cached_input" }, event.cachedInputTokens);
+        if (event.cacheWriteTokens !== undefined)
+            this.proxyTokens.inc({ kind: "cache_write" }, event.cacheWriteTokens);
+        if (event.reasoningTokens !== undefined)
+            this.proxyTokens.inc({ kind: "reasoning" }, event.reasoningTokens);
+    };
+    observeProxyRequest(event) {
+        const labels = { protocol: event.protocol, status_class: statusClass(event.status) };
+        this.proxyRequests.inc(labels);
+        this.proxyRequestDuration.observe(labels, event.durationMs / 1_000);
+    }
+}

package/dist/providers/auth/authorization-server.d.ts

@@ -0,0 +1,41 @@
+export interface SelfHostedAuthConfig {
+    canonicalUri: string;
+    signingKey: string;
+    credentialHashKey: string;
+    maxClients?: number;
+}
+export interface RegisterClientParams {
+    redirectUris: string[];
+    clientName?: string;
+    grantTypes?: string[];
+    tokenEndpointAuthMethod?: string;
+}
+export interface AuthorizeParams {
+    clientId: string;
+    redirectUri: string;
+    codeChallenge: string;
+    codeChallengeMethod: string;
+    scope: string;
+    resource: string;
+    state?: string;
+}
+export type TokenParams = {
+    grantType: "authorization_code";
+    code: string;
+    codeVerifier: string;
+    redirectUri: string;
+    clientId: string;
+    resource?: string;
+} | {
+    grantType: "refresh_token";
+    refreshToken: string;
+    clientId: string;
+    resource?: string;
+};
+export interface TokenResult {
+    accessToken: string;
+    tokenType: "Bearer";
+    expiresIn: number;
+    refreshToken: string;
+    scope: string;
+}

package/dist/providers/auth/authorization-server.js

@@ -0,0 +1 @@
+export {};

package/dist/providers/auth/delegating.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Resource-server-only AuthProvider: wardby never issues tokens itself, an
+ * external OIDC/OAuth IdP is the authorization server. verifyBearer is the
+ * whole job — validate a caller-supplied access token (signature via JWKS,
+ * audience, expiry, issuer) and map its claims to a VerifiedToken (subject
+ * + per-token scopes). The auth-code flow methods (authorizeUrl/
+ * exchangeCode/refresh) belong to the external IdP, not to wardby, so they
+ * throw rather than half-implement a flow this adapter doesn't own.
+ */
+import { type JWTVerifyGetKey } from "jose";
+import type { AuthProfile, AuthProvider, AuthTokens, VerifiedToken } from "./types.js";
+export interface DelegatingAuthConfig {
+    issuer?: string;
+    audience?: string;
+    jwksUri?: string;
+}
+/**
+ * Every spelling of the configured audience a token may legitimately carry.
+ *
+ * `aud` is compared as an exact string, but for an http(s) URI an empty path
+ * and "/" denote the same resource (RFC 3986 §6.2.3) — and the two halves of
+ * this system disagree about which spelling to use. The protected-resource
+ * metadata advertises the normalized ("/") form, so a spec-compliant client
+ * asks its IdP for that; an IdP whose audience is configured from a
+ * hand-written identifier (Auth0's API Identifier, say) echoes back whatever
+ * the operator typed, usually without the slash. Matching only one form
+ * rejects real tokens from the other, and the startup check in
+ * mcp/index.ts normalizes both sides, so the misconfiguration passes
+ * validation and only surfaces as an opaque invalid_token at request time.
+ *
+ * A non-URL audience (some IdPs use opaque identifiers) has exactly one form.
+ */
+export declare function audienceCandidates(audience: string): string[];
+export declare class DelegatingAuthProvider implements AuthProvider {
+    private readonly config;
+    private readonly audiences;
+    private readonly jwks;
+    constructor(config: DelegatingAuthConfig, jwks?: JWTVerifyGetKey);
+    verifyBearer(token: string): Promise<VerifiedToken>;
+    profile(idToken: string): Promise<AuthProfile>;
+    authorizeUrl(_state: string, _redirectUri: string): string;
+    exchangeCode(_code: string, _redirectUri: string): Promise<AuthTokens>;
+    refresh(_refreshToken: string): Promise<AuthTokens>;
+}

package/dist/providers/auth/delegating.js

@@ -0,0 +1,105 @@
+/**
+ * Resource-server-only AuthProvider: wardby never issues tokens itself, an
+ * external OIDC/OAuth IdP is the authorization server. verifyBearer is the
+ * whole job — validate a caller-supplied access token (signature via JWKS,
+ * audience, expiry, issuer) and map its claims to a VerifiedToken (subject
+ * + per-token scopes). The auth-code flow methods (authorizeUrl/
+ * exchangeCode/refresh) belong to the external IdP, not to wardby, so they
+ * throw rather than half-implement a flow this adapter doesn't own.
+ */
+import { createRemoteJWKSet, jwtVerify, errors as joseErrors } from "jose";
+import { AudienceError, NotSupportedError } from "./types.js";
+import { requireSubject } from "./subject.js";
+/**
+ * Every spelling of the configured audience a token may legitimately carry.
+ *
+ * `aud` is compared as an exact string, but for an http(s) URI an empty path
+ * and "/" denote the same resource (RFC 3986 §6.2.3) — and the two halves of
+ * this system disagree about which spelling to use. The protected-resource
+ * metadata advertises the normalized ("/") form, so a spec-compliant client
+ * asks its IdP for that; an IdP whose audience is configured from a
+ * hand-written identifier (Auth0's API Identifier, say) echoes back whatever
+ * the operator typed, usually without the slash. Matching only one form
+ * rejects real tokens from the other, and the startup check in
+ * mcp/index.ts normalizes both sides, so the misconfiguration passes
+ * validation and only surfaces as an opaque invalid_token at request time.
+ *
+ * A non-URL audience (some IdPs use opaque identifiers) has exactly one form.
+ */
+export function audienceCandidates(audience) {
+    try {
+        const url = new URL(audience);
+        const forms = [audience, url.href];
+        // Only an empty path is interchangeable with "/". A trailing slash on a
+        // non-empty path ("…/mcp/" vs "…/mcp") is significant, so those stay
+        // distinct resources and keep matching strictly.
+        if (url.pathname === "/")
+            forms.push(url.href.replace(/\/$/, ""));
+        return [...new Set(forms)];
+    }
+    catch {
+        return [audience];
+    }
+}
+/** Splits an OAuth `scope`/`scp` claim (space-delimited string, or already an array) into scopes. */
+function scopesFromClaim(claim) {
+    if (Array.isArray(claim))
+        return claim.map(String);
+    if (typeof claim === "string")
+        return claim.split(/\s+/).filter(Boolean);
+    return [];
+}
+export class DelegatingAuthProvider {
+    config;
+    audiences;
+    jwks;
+    constructor(config, jwks) {
+        if (!config.issuer || !config.audience)
+            throw new Error("AUTH_ISSUER and AUTH_AUDIENCE are required.");
+        this.config = config;
+        this.audiences = audienceCandidates(config.audience);
+        if (jwks) {
+            this.jwks = jwks;
+        }
+        else {
+            if (!config.jwksUri) {
+                throw new Error("AUTH_JWKS_URI is not set — required by the delegating AuthProvider adapter.");
+            }
+            this.jwks = createRemoteJWKSet(new URL(config.jwksUri));
+        }
+    }
+    async verifyBearer(token) {
+        try {
+            const { payload } = await jwtVerify(token, this.jwks, {
+                issuer: this.config.issuer,
+                audience: this.audiences,
+                requiredClaims: ["sub", "exp", "iss", "aud"],
+            });
+            return {
+                subject: requireSubject(payload.sub),
+                email: typeof payload.email === "string" ? payload.email : undefined,
+                roles: Array.isArray(payload.roles) ? payload.roles.map(String) : [],
+                scopes: scopesFromClaim(payload.scope ?? payload.scp),
+            };
+        }
+        catch (err) {
+            if (err instanceof joseErrors.JWTClaimValidationFailed && err.claim === "aud") {
+                throw new AudienceError(`Token audience does not match the configured resource ("${this.config.audience}").`);
+            }
+            throw err;
+        }
+    }
+    async profile(idToken) {
+        const verified = await this.verifyBearer(idToken);
+        return { subject: verified.subject, email: verified.email, roles: verified.roles ?? [] };
+    }
+    authorizeUrl(_state, _redirectUri) {
+        throw new NotSupportedError("DelegatingAuthProvider is resource-server-only; the external IdP's own authorization endpoint issues tokens.");
+    }
+    async exchangeCode(_code, _redirectUri) {
+        throw new NotSupportedError("DelegatingAuthProvider is resource-server-only; the external IdP's own token endpoint issues tokens.");
+    }
+    async refresh(_refreshToken) {
+        throw new NotSupportedError("DelegatingAuthProvider is resource-server-only; the external IdP's own token endpoint handles refresh.");
+    }
+}

package/dist/providers/auth/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AuthProvider selector — builds the adapter for the configured AUTH_PROVIDER
+ * kind. Both adapters implement the same AuthProvider (incl. verifyBearer),
+ * so the resource-server middleware and tool handlers never branch on mode.
+ */
+import type { PrismaClient } from "@prisma/client";
+import type { AuthProviderKind, AuthConfig } from "../../config/providers.js";
+import type { AuthProvider } from "./types.js";
+export { DelegatingAuthProvider } from "./delegating.js";
+export { SelfHostedAuthProvider } from "./self-hosted.js";
+export declare function buildAuthProvider(kind: AuthProviderKind, config: AuthConfig, db: PrismaClient): AuthProvider;

package/dist/providers/auth/index.js

@@ -0,0 +1,20 @@
+import { DelegatingAuthProvider } from "./delegating.js";
+import { SelfHostedAuthProvider } from "./self-hosted.js";
+export { DelegatingAuthProvider } from "./delegating.js";
+export { SelfHostedAuthProvider } from "./self-hosted.js";
+export function buildAuthProvider(kind, config, db) {
+    if (kind === "self-hosted") {
+        if (!config.audience || !config.signingKey || !config.credentialHashKey) {
+            throw new Error("AUTH_AUDIENCE, AUTH_SIGNING_KEY, and AUTH_CREDENTIAL_HASH_KEY are required.");
+        }
+        if (config.credentialHashKey.toLowerCase() === process.env.SECRET_APP_KEY?.toLowerCase())
+            throw new Error("Credential and encryption keys must be distinct.");
+        return new SelfHostedAuthProvider({
+            canonicalUri: config.audience,
+            signingKey: config.signingKey,
+            credentialHashKey: config.credentialHashKey,
+            maxClients: config.maxClients,
+        }, db);
+    }
+    return new DelegatingAuthProvider(config);
+}

package/dist/providers/auth/release-gate.d.ts

@@ -0,0 +1 @@
+export declare function assertSelfHostedReleased(): void;

package/dist/providers/auth/release-gate.js

@@ -0,0 +1,4 @@
+// Remove only after the database, browser, migration, and independent review gates pass.
+export function assertSelfHostedReleased() {
+    throw new Error("Self-hosted OAuth issuance is quarantined pending the security release gates. Use delegating OAuth or stdio.");
+}

package/dist/providers/auth/self-hosted.d.ts

@@ -0,0 +1,78 @@
+import type { PrismaClient } from "@prisma/client";
+import type { AuthProfile, AuthProvider, AuthTokens, VerifiedToken } from "./types.js";
+import { Credentials } from "../../mcp/auth/self-hosted/credentials.js";
+import { Sessions } from "../../mcp/auth/self-hosted/session.js";
+import type { AuthorizeParams, RegisterClientParams, SelfHostedAuthConfig, TokenParams, TokenResult } from "./authorization-server.js";
+export type { AuthorizeParams, RegisterClientParams, SelfHostedAuthConfig, TokenParams, TokenResult, } from "./authorization-server.js";
+export declare class SelfHostedAuthProvider implements AuthProvider {
+    readonly db: PrismaClient;
+    readonly credentials: Credentials;
+    readonly sessions: Sessions;
+    readonly config: SelfHostedAuthConfig;
+    private readonly key;
+    constructor(config: SelfHostedAuthConfig, db: PrismaClient);
+    asMetadata(): {
+        issuer: string;
+        authorization_endpoint: string;
+        token_endpoint: string;
+        registration_endpoint: string;
+        revocation_endpoint: string;
+        response_types_supported: string[];
+        grant_types_supported: string[];
+        code_challenge_methods_supported: string[];
+        token_endpoint_auth_methods_supported: string[];
+        revocation_endpoint_auth_methods_supported: string[];
+        scopes_supported: string[];
+        authorization_response_iss_parameter_supported: boolean;
+    };
+    registerClient(params: RegisterClientParams): Promise<{
+        clientId: `${string}-${string}-${string}-${string}-${string}`;
+    }>;
+    handleAuthorize(input: AuthorizeParams): Promise<{
+        interactionId: string;
+    }>;
+    consentPage(sessionToken: string, interactionId: string): Promise<{
+        interaction: {
+            client: {
+                metadata: import("@prisma/client/runtime/library").JsonValue;
+                createdAt: Date;
+                clientId: string;
+            };
+        } & {
+            id: string;
+            createdAt: Date;
+            state: string | null;
+            expiresAt: Date;
+            resource: string;
+            clientId: string;
+            consumedAt: Date | null;
+            redirectUri: string;
+            codeChallenge: string;
+            requestedScope: string;
+        };
+        challenge: string;
+    }>;
+    consent(sessionToken: string, interactionId: string, challenge: string, approve: boolean): Promise<string>;
+    handleToken(params: TokenParams): Promise<TokenResult>;
+    /**
+     * Whether a token request's `resource` names this server: the canonical URI
+     * itself, or a URL beneath it. The MCP SDK sends the metadata's canonical
+     * URI when it has it, but falls back to the MCP endpoint URL (e.g. `/mcp`
+     * under a root canonical URI) on refresh - rejecting that logged every
+     * Claude Code session out after one access-token lifetime. The issued
+     * token's audience still comes from the grant (code.resource /
+     * family.resource), never from this parameter.
+     */
+    private withinCanonical;
+    private exchange;
+    private rotate;
+    private issue;
+    private revokeFamily;
+    revoke(token: string, clientId: string): Promise<void>;
+    verifyBearer(token: string): Promise<VerifiedToken>;
+    cleanup(): Promise<void>;
+    profile(token: string): Promise<AuthProfile>;
+    authorizeUrl(): string;
+    exchangeCode(): Promise<AuthTokens>;
+    refresh(): Promise<AuthTokens>;
+}