wicked-crew 0.5.0 → 0.6.0

package/dist/api/audit.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The crew-side actor audit trail (task #88).
+ *
+ * The engine's `LaunchOptions` carries no actor field, so WHO launched a run,
+ * WHO approved a gate, and WHO rewrote a policy is knowledge only the daemon's
+ * HTTP layer ever holds — this module is where it stops being ephemeral. One
+ * JSON line per privileged action, appended to `~/.wicked-crew/audit.log`
+ * (override: `WICKED_CREW_AUDIT_LOG`), read back by `GET /audit`.
+ *
+ * Posture: LOUD-NON-FATAL, matching the daemon's bus seams — an unwritable
+ * audit file must not turn a valid gate approval into a 500, but it must be
+ * SAID (once per failure) rather than swallowed. Appends are serialized on a
+ * promise chain so concurrent handlers never interleave partial lines.
+ */
+import type { Actor, AuditEntry } from '../core/types.js';
+/** Where the audit trail lives unless overridden. */
+export declare function defaultAuditPath(env?: NodeJS.ProcessEnv): string;
+export interface AuditReadFilter {
+    runId?: string;
+    action?: string;
+    /** Max entries returned (newest first). Default 200, capped at 1000. */
+    limit?: number;
+}
+export declare class AuditLog {
+    readonly path: string;
+    private readonly warn;
+    private chain;
+    private dirReady;
+    private disabled;
+    constructor(path?: string, warn?: (msg: string) => void);
+    /**
+     * A trail that records nothing and reads back empty — the DEFAULT for
+     * directly-driven route sets (unit tests call `registerRoutes` without a
+     * server), so they never write the operator's real `~/.wicked-crew/audit.log`
+     * or leave appends pending after close (Copilot, #250). `createServer`
+     * always builds a real one; this never rides a production path.
+     */
+    static noop(): AuditLog;
+    /**
+     * Record one action. Fire-and-forget by design (the route's answer must not
+     * wait on fsync of a sidecar), serialized so lines never interleave, loud on
+     * failure. `flush()` awaits the chain — tests and shutdown use it.
+     */
+    record(action: string, actor: Actor, fields?: {
+        runId?: string;
+        detail?: Record<string, unknown>;
+    }): void;
+    /** Await every append issued so far. */
+    flush(): Promise<void>;
+    /**
+     * Read the trail, newest first. A line that does not parse is skipped (a
+     * torn final line after a crash is expected once) — the rest of the trail
+     * still answers.
+     */
+    read(filter?: AuditReadFilter): Promise<AuditEntry[]>;
+}
+//# sourceMappingURL=audit.d.ts.map

package/dist/api/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/api/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE1D,qDAAqD;AACrD,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAE7E;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,QAAQ;IAMjB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IANvB,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAS;gBAGd,IAAI,GAAE,MAA2B,EACzB,IAAI,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAA6B;IAGvE;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,IAAI,QAAQ;IAMvB;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI;IAyBzG,wCAAwC;IACxC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB;;;;OAIG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;CA2B5D"}

package/dist/api/audit.js

@@ -0,0 +1,115 @@
+/**
+ * The crew-side actor audit trail (task #88).
+ *
+ * The engine's `LaunchOptions` carries no actor field, so WHO launched a run,
+ * WHO approved a gate, and WHO rewrote a policy is knowledge only the daemon's
+ * HTTP layer ever holds — this module is where it stops being ephemeral. One
+ * JSON line per privileged action, appended to `~/.wicked-crew/audit.log`
+ * (override: `WICKED_CREW_AUDIT_LOG`), read back by `GET /audit`.
+ *
+ * Posture: LOUD-NON-FATAL, matching the daemon's bus seams — an unwritable
+ * audit file must not turn a valid gate approval into a 500, but it must be
+ * SAID (once per failure) rather than swallowed. Appends are serialized on a
+ * promise chain so concurrent handlers never interleave partial lines.
+ */
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** Where the audit trail lives unless overridden. */
+export function defaultAuditPath(env = process.env) {
+    return env['WICKED_CREW_AUDIT_LOG'] ?? join(homedir(), '.wicked-crew', 'audit.log');
+}
+export class AuditLog {
+    path;
+    warn;
+    chain = Promise.resolve();
+    dirReady = false;
+    disabled = false;
+    constructor(path = defaultAuditPath(), warn = (m) => console.warn(m)) {
+        this.path = path;
+        this.warn = warn;
+    }
+    /**
+     * A trail that records nothing and reads back empty — the DEFAULT for
+     * directly-driven route sets (unit tests call `registerRoutes` without a
+     * server), so they never write the operator's real `~/.wicked-crew/audit.log`
+     * or leave appends pending after close (Copilot, #250). `createServer`
+     * always builds a real one; this never rides a production path.
+     */
+    static noop() {
+        const log = new AuditLog();
+        log.disabled = true;
+        return log;
+    }
+    /**
+     * Record one action. Fire-and-forget by design (the route's answer must not
+     * wait on fsync of a sidecar), serialized so lines never interleave, loud on
+     * failure. `flush()` awaits the chain — tests and shutdown use it.
+     */
+    record(action, actor, fields) {
+        if (this.disabled)
+            return;
+        const entry = {
+            ts: Date.now(),
+            action,
+            actor,
+            ...(fields?.runId !== undefined ? { runId: fields.runId } : {}),
+            ...(fields?.detail !== undefined ? { detail: fields.detail } : {}),
+        };
+        this.chain = this.chain.then(async () => {
+            if (!this.dirReady) {
+                await mkdir(dirname(this.path), { recursive: true });
+                this.dirReady = true;
+            }
+            await appendFile(this.path, `${JSON.stringify(entry)}\n`, 'utf8');
+        });
+        this.chain = this.chain.catch((err) => {
+            this.warn(`[audit] FAILED to record ${action} by ${actor.id} at ${this.path}: ${err instanceof Error ? err.message : String(err)} — the action itself succeeded; the trail has a hole`);
+        });
+    }
+    /** Await every append issued so far. */
+    flush() {
+        return this.chain;
+    }
+    /**
+     * Read the trail, newest first. A line that does not parse is skipped (a
+     * torn final line after a crash is expected once) — the rest of the trail
+     * still answers.
+     */
+    async read(filter) {
+        if (this.disabled)
+            return [];
+        await this.flush();
+        let raw;
+        try {
+            raw = await readFile(this.path, 'utf8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return []; // nothing recorded yet
+            throw err;
+        }
+        const entries = [];
+        for (const line of raw.split('\n')) {
+            if (line.trim() === '')
+                continue;
+            try {
+                const e = JSON.parse(line);
+                if (typeof e.ts !== 'number' || typeof e.action !== 'string')
+                    continue;
+                if (filter?.runId !== undefined && e.runId !== filter.runId)
+                    continue;
+                if (filter?.action !== undefined && e.action !== filter.action)
+                    continue;
+                entries.push(e);
+            }
+            catch {
+                /* torn line — skip it, keep the trail readable */
+            }
+        }
+        entries.reverse(); // file order is append order; the API answers newest first
+        const limit = Math.min(Math.max(filter?.limit ?? 200, 1), 1000);
+        return entries.slice(0, limit);
+    }
+}
+//# sourceMappingURL=audit.js.map

package/dist/api/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/api/audit.ts"],"names":[],"mappings":"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"}

package/dist/api/auth.d.ts

@@ -0,0 +1,192 @@
+/**
+ * The daemon's identity/actor seam (task #88, locked decision #6).
+ *
+ * LOCAL IS SACRED: the default deployment stays exactly what it was — a
+ * 127.0.0.1-bound daemon with loopback CORS and NO auth, where every request
+ * implicitly acts as the full-trust local operator. Nothing in this module
+ * runs a verifier, reads a token file, or changes a response in that mode; it
+ * only pins ONE actor shape onto the request so downstream code (audit trail,
+ * bus events, gate decisions) never branches on "was there auth".
+ *
+ * TEAM/HOSTED REQUIRES AUTH: `WICKED_RUNTIME=team` or `WICKED_CREW_AUTH=required`
+ * arms a bearer-token check on `/api/v1/*` and the `/ws` upgrade paths.
+ * Verification is pluggable behind {@link TokenVerifier}; v1 ships the static
+ * workload-token verifier (hashed-at-rest file, {@link loadTokenFile}) and the
+ * OIDC verifier SEAM ({@link OidcConfig} + {@link createOidcVerifier}), whose
+ * implementation is a named follow-up — configuring OIDC today fails the boot
+ * LOUDLY rather than pretending an IdP was consulted.
+ *
+ * Deny semantics: missing/unknown token in required mode → 401 (with
+ * `WWW-Authenticate: Bearer`); an authenticated actor below a route's rung on
+ * the trust ladder → 403. The ladder is {@link requiredTrust} — minimal and
+ * documented (docs/auth.md), not a per-route registry.
+ */
+import type { FastifyInstance, FastifyRequest } from 'fastify';
+import type { Actor, TrustLevel } from '../core/types.js';
+declare module 'fastify' {
+    interface FastifyRequest {
+        /**
+         * The authenticated actor — or {@link LOCAL_ACTOR} when auth is off. Set by
+         * the identity hook for every request under `/api/v1` and `/ws`; routes
+         * outside that scope (SPA assets) never read it.
+         */
+        actor: Actor;
+    }
+}
+export type AuthMode = 'required' | 'off';
+/**
+ * The implicit full-trust local operator. `admin` is the ladder's top rung —
+ * the local single-operator deployment has exactly one human and no boundary
+ * to enforce between that human and the daemon, so "full trust" and "admin"
+ * are the same fact spelled once.
+ */
+export declare const LOCAL_ACTOR: Actor;
+/** True when `actor` sits at or above `min` on the ladder. */
+export declare function trustAtLeast(actor: Actor, min: TrustLevel): boolean;
+/**
+ * Resolve the daemon's auth mode. DENY-DOMINANT: `WICKED_RUNTIME=team` forces
+ * `required` and nothing can talk it back down — a team runtime with auth
+ * switched off is exactly the silently-ungoverned state this seam exists to
+ * prevent. Outside team runtime, `WICKED_CREW_AUTH` (`required`|`off`) is
+ * explicit; unset means the local default, off.
+ */
+export declare function resolveAuthMode(env?: NodeJS.ProcessEnv): AuthMode;
+/**
+ * The verifier seam. A verifier resolves a presented bearer token to an
+ * {@link Actor}, or `null` when the token is not one of its. Verifiers are
+ * tried in order; the first non-null answer wins. v1 ships the static
+ * workload-token verifier; the OIDC verifier is the named follow-up
+ * (docs/auth.md § "The OIDC seam").
+ */
+export interface TokenVerifier {
+    /** Names the verifier in logs and errors (`static-tokens`, `oidc`). */
+    readonly name: string;
+    verify(token: string): Promise<Actor | null>;
+}
+/** Where the workload-token file lives unless overridden. */
+export declare function defaultTokensPath(env?: NodeJS.ProcessEnv): string;
+/** One entry of `tokens.json` — the HASH of a token, never the token itself. */
+export interface TokenFileEntry {
+    /** Lowercase hex SHA-256 of the bearer token (64 chars). */
+    sha256: string;
+    actor: Actor;
+    /** Operator note ("ci runner", "maria's laptop"); never used for decisions. */
+    label?: string;
+}
+/** `sha256` hex of a presented token — the only form the daemon stores or compares. */
+export declare function tokenHash(token: string): string;
+/**
+ * Parse a tokens.json payload into a hash→actor map. FAILS CLOSED on any
+ * malformed entry: a typo'd trust level that silently skipped its entry would
+ * lock an operator out (or, worse, a hand-edit that half-parsed would demote
+ * someone) with nothing saying so. The error names the entry index and field.
+ */
+export declare function parseTokenFile(json: string, source: string): Map<string, Actor>;
+/**
+ * Load `tokens.json` from disk into a static verifier. A MISSING file is a
+ * loud warning, not a boot failure: the daemon still starts and every request
+ * 401s, which is the honest fail-closed posture (an unreachable daemon tells
+ * the operator less than one that answers "no tokens are registered").
+ * A PRESENT-but-malformed file fails the boot — see {@link parseTokenFile}.
+ */
+export declare function loadTokenFile(path: string, warn: (msg: string) => void): Map<string, Actor>;
+/** The static workload-token verifier: sha256 the presented token, look it up. */
+export declare function createStaticVerifier(entries: Map<string, Actor>): TokenVerifier;
+/**
+ * The OIDC verifier's config shape. Lives in `~/.config/wicked-crew/auth.json`
+ * as `{ "oidc": … }`.
+ */
+export interface OidcConfig {
+    /** The issuer URL — discovery happens at `<issuer>/.well-known/openid-configuration`. */
+    issuer: string;
+    /** The audience (`aud`) access tokens must carry to be accepted by this daemon. */
+    audience: string;
+    /** Explicit JWKS URI; omit to use the discovery document's `jwks_uri`. */
+    jwksUri?: string;
+    /**
+     * Claim mapping. `id` defaults to `sub`; `trust` names a claim whose value is
+     * a {@link TrustLevel} (defaults to the `defaultTrust` below when absent).
+     * OIDC-verified principals are always `kind: 'human'` — workloads use tokens.
+     */
+    claims?: {
+        id?: string;
+        trust?: string;
+    };
+    /** Trust assigned when the trust claim is absent (default `observer` — least privilege). */
+    defaultTrust?: TrustLevel;
+}
+/** Where the auth config (OIDC seam) lives unless overridden. */
+export declare function defaultAuthConfigPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Create an OIDC verifier that validates JWTs against the issuer's JWKS.
+ * Supports RS256/384/512, ES256/384/512, PS256/384/512. JWKS keys are cached
+ * per issuer with a 5-minute TTL and auto-refreshed on unknown kid.
+ */
+export declare function createOidcVerifier(config: OidcConfig): TokenVerifier;
+/** `createServer`'s auth options — everything defaults to env/file resolution. */
+export interface AuthOptions {
+    /** Override mode resolution (tests / embedders). Default: {@link resolveAuthMode}. */
+    mode?: AuthMode;
+    /** Token file path. Default: `WICKED_CREW_TOKENS` or `~/.config/wicked-crew/tokens.json`. */
+    tokensPath?: string;
+    /** auth.json path (the OIDC seam's config). Default: `~/.config/wicked-crew/auth.json`. */
+    configPath?: string;
+    /**
+     * Replace the default verifier chain entirely (tests / embedders with their
+     * own identity source). When set, the token file and auth.json are not read.
+     */
+    verifiers?: TokenVerifier[];
+    /**
+     * Origins allowed CORS when auth is required, beyond loopback. Default:
+     * `WICKED_CREW_ALLOWED_ORIGINS` (comma-separated) or — when unset — ANY
+     * origin: bearer auth carries no ambient credential, so cross-origin JS
+     * without a token holds nothing (docs/auth.md § "CORS pairing").
+     */
+    allowedOrigins?: string[];
+}
+/** The resolved auth state `createServer` builds once and hooks consult per request. */
+export interface ResolvedAuth {
+    mode: AuthMode;
+    verifiers: TokenVerifier[];
+    /** `null` = any origin (required mode's default); else an allowlist. Loopback always passes. */
+    allowedOrigins: string[] | null;
+}
+/** Resolve mode + verifier chain. Reads files ONLY in required mode. */
+export declare function resolveAuth(options: AuthOptions | undefined, warn: (msg: string) => void): ResolvedAuth;
+/**
+ * Minimum trust for a request. Minimal by design (the task's rule: no
+ * deny-by-default registry over unknown routes):
+ *
+ * - `/ws/terminals` and any sub-path → `operator` (write-capable WS channel;
+ *   inbound frames are raw PTY stdin regardless of the GET upgrade method)
+ * - reads (GET/HEAD) and the main `/ws` stream → `observer`
+ * - governance writes, settings writes, project archive/restore → `admin`
+ * - every other mutation (launch, gate, cancel, chats, terminals, repos,
+ *   workflows, project CRUD/membership) → `operator`
+ *
+ * `body` is consulted for exactly one rule: `PATCH /projects/:id` is an
+ * `operator` rename/describe unless the patch carries `status` (archive or
+ * restore), which changes what the whole team can attach work to — `admin`.
+ */
+export declare function requiredTrust(method: string, path: string, body: unknown): TrustLevel;
+/** True for the paths the auth boundary covers: the API and the WS upgrades. */
+export declare function isProtectedPath(path: string): boolean;
+/**
+ * Extract the presented bearer token. `Authorization: Bearer <t>` everywhere;
+ * the `/ws` upgrade paths ALSO accept `?access_token=` (RFC 6750 §2.3),
+ * because the browser `WebSocket` constructor cannot set headers. Header wins
+ * when both are present.
+ */
+export declare function extractToken(req: FastifyRequest, path: string): string | null;
+/**
+ * Install the identity (401) and trust (403) hooks.
+ *
+ * Identity runs at `onRequest` — before body parsing, and (per
+ * `@fastify/websocket`) before the upgrade completes, so a bad token is an
+ * HTTP 401 on the wire for REST and WS alike. Trust runs at `preHandler`,
+ * where the parsed body exists (the one body-dependent rule is the project
+ * archive). Both scope to {@link isProtectedPath}; the SPA shell and its
+ * assets stay public so a hosted skin can load and ASK for a token.
+ */
+export declare function registerAuthHooks(app: FastifyInstance, auth: ResolvedAuth): void;
+//# sourceMappingURL=auth.d.ts.map

package/dist/api/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/api/auth.ts"],"names":[],"mappings":"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"}