@fusionkit/plane 0.1.0

package/dist/policy.js

@@ -0,0 +1,92 @@
+import { PolicyDeniedError } from "@fusionkit/protocol";
+/**
+ * Evaluate a run request against policy at contract time. Fail closed:
+ * anything not allowed throws PolicyDeniedError; anything allowed but
+ * matching a consent rule returns "ask" with the named requirements.
+ */
+export function evaluatePolicy(policy, request) {
+    const denials = [];
+    if (!policy.agents.allow.includes(request.agentKind)) {
+        denials.push(`agent kind "${request.agentKind}" is not allowed`);
+    }
+    if (!policy.runners.allowPools.includes(request.pool)) {
+        denials.push(`runner pool "${request.pool}" is not allowed`);
+    }
+    for (const name of request.secretNames) {
+        const rule = policy.secrets.releasable.find((r) => r.name === name);
+        if (!rule) {
+            denials.push(`secret "${name}" is not releasable under policy`);
+        }
+        else if (!rule.pools.includes(request.pool)) {
+            denials.push(`secret "${name}" is not releasable to pool "${request.pool}"`);
+        }
+    }
+    if (policy.network.defaultDeny) {
+        const allowed = new Set(policy.network.allowHosts);
+        for (const host of request.allowHosts) {
+            if (!allowed.has(host)) {
+                denials.push(`network host "${host}" is not in the policy allowlist`);
+            }
+        }
+    }
+    const spend = request.maxSpendUsd ?? policy.budget.maxSpendUsd;
+    if (spend > policy.budget.maxSpendUsd) {
+        denials.push(`requested budget $${spend} exceeds policy ceiling $${policy.budget.maxSpendUsd}`);
+    }
+    const duration = request.maxDurationMin ?? policy.budget.maxDurationMin;
+    if (duration > policy.budget.maxDurationMin) {
+        denials.push(`requested duration ${duration}m exceeds policy ceiling ${policy.budget.maxDurationMin}m`);
+    }
+    if (denials.length > 0) {
+        throw new PolicyDeniedError(denials);
+    }
+    const consentRequirements = [];
+    for (const rule of policy.consent) {
+        switch (rule.when) {
+            case "any-run":
+                consentRequirements.push("any-run");
+                break;
+            case "secret-release":
+                if (request.secretNames.length > 0) {
+                    consentRequirements.push(`secret-release:${request.secretNames.join(",")}`);
+                }
+                break;
+            case "agent-kind":
+                if (rule.match === request.agentKind) {
+                    consentRequirements.push(`agent-kind:${request.agentKind}`);
+                }
+                break;
+            default: {
+                const exhausted = rule.when;
+                throw new Error(`unreachable consent rule: ${String(exhausted)}`);
+            }
+        }
+    }
+    if (consentRequirements.length > 0) {
+        return {
+            decision: "ask",
+            reason: `consent required: ${consentRequirements.join("; ")}`,
+            consentRequirements
+        };
+    }
+    return { decision: "allow", reason: "policy allows this run", consentRequirements: [] };
+}
+/**
+ * Opinionated starter policy for `warrant init` and the in-process test/demo
+ * stacks. Production deployments edit `policy.json` (or supply their own
+ * Policy); these defaults are intentionally permissive-but-bounded for a
+ * single-node dev/demo setup, not a recommended production posture.
+ */
+export function defaultPolicy() {
+    return {
+        version: "warrant.policy.v1",
+        runners: { allowPools: ["default"] },
+        agents: { allow: ["claude-code", "codex", "pi", "mock", "command"] },
+        dataClasses: [],
+        network: { defaultDeny: true, allowHosts: [] },
+        secrets: { releasable: [] },
+        budget: { maxSpendUsd: 25, maxDurationMin: 60 },
+        consent: [],
+        retention: { receiptsDays: 365, artifactsDays: 90 }
+    };
+}

package/dist/ratelimit.d.ts

@@ -0,0 +1,40 @@
+/**
+ * In-memory token-bucket rate limiter plus failed-auth backoff. Per-key
+ * (principal id or client IP). In-memory is correct for a single-node
+ * plane; a multi-node deployment would back this with the shared store,
+ * which is why the limiter is injected rather than global.
+ */
+export type RateLimitConfig = {
+    /** Sustained requests per second per key. */
+    ratePerSec: number;
+    /** Maximum burst (bucket capacity). */
+    burst: number;
+    /** Lock a key out for this long after too many auth failures. */
+    authFailureWindowMs: number;
+    /** Auth failures within the window before lockout. */
+    authFailureLimit: number;
+};
+/** Tunable defaults; override per deployment via PlaneServerOptions.rateLimit. */
+export declare const DEFAULT_RATE_LIMIT: RateLimitConfig;
+/**
+ * In-memory token-bucket limiter. Correct for a single-node plane; a
+ * multi-node deployment would back this with the shared store (the limiter
+ * is injected, not global, so that swap is local). Idle entries are evicted
+ * once the maps grow large, so a long-lived process does not accumulate
+ * unbounded keys.
+ */
+export declare class RateLimiter {
+    private readonly buckets;
+    private readonly failures;
+    private readonly config;
+    private readonly now;
+    constructor(config?: Partial<RateLimitConfig>, now?: () => number);
+    /** Drop entries that have fully refilled / expired and are idle. */
+    private evictIdle;
+    /** Consume one token for `key`; returns false when the bucket is empty. */
+    allow(key: string): boolean;
+    /** Is the key currently locked out for repeated auth failures? */
+    isLockedOut(key: string): boolean;
+    recordAuthFailure(key: string): void;
+    recordAuthSuccess(key: string): void;
+}

package/dist/ratelimit.js

@@ -0,0 +1,94 @@
+/**
+ * In-memory token-bucket rate limiter plus failed-auth backoff. Per-key
+ * (principal id or client IP). In-memory is correct for a single-node
+ * plane; a multi-node deployment would back this with the shared store,
+ * which is why the limiter is injected rather than global.
+ */
+/** Tunable defaults; override per deployment via PlaneServerOptions.rateLimit. */
+export const DEFAULT_RATE_LIMIT = {
+    ratePerSec: 50,
+    burst: 100,
+    authFailureWindowMs: 60_000,
+    authFailureLimit: 20
+};
+/** Evict idle bucket/failure entries once the map grows past this size. */
+const EVICTION_THRESHOLD = 10_000;
+/**
+ * In-memory token-bucket limiter. Correct for a single-node plane; a
+ * multi-node deployment would back this with the shared store (the limiter
+ * is injected, not global, so that swap is local). Idle entries are evicted
+ * once the maps grow large, so a long-lived process does not accumulate
+ * unbounded keys.
+ */
+export class RateLimiter {
+    buckets = new Map();
+    failures = new Map();
+    config;
+    now;
+    constructor(config = {}, now = Date.now) {
+        this.config = { ...DEFAULT_RATE_LIMIT, ...config };
+        this.now = now;
+    }
+    /** Drop entries that have fully refilled / expired and are idle. */
+    evictIdle(nowMs) {
+        if (this.buckets.size > EVICTION_THRESHOLD) {
+            for (const [key, bucket] of this.buckets) {
+                const elapsedSec = (nowMs - bucket.updatedMs) / 1000;
+                if (bucket.tokens + elapsedSec * this.config.ratePerSec >= this.config.burst) {
+                    this.buckets.delete(key);
+                }
+            }
+        }
+        if (this.failures.size > EVICTION_THRESHOLD) {
+            for (const [key, state] of this.failures) {
+                if (nowMs >= state.lockedUntilMs && nowMs - state.windowStartMs > this.config.authFailureWindowMs) {
+                    this.failures.delete(key);
+                }
+            }
+        }
+    }
+    /** Consume one token for `key`; returns false when the bucket is empty. */
+    allow(key) {
+        const nowMs = this.now();
+        this.evictIdle(nowMs);
+        const bucket = this.buckets.get(key) ?? {
+            tokens: this.config.burst,
+            updatedMs: nowMs
+        };
+        const elapsedSec = (nowMs - bucket.updatedMs) / 1000;
+        bucket.tokens = Math.min(this.config.burst, bucket.tokens + elapsedSec * this.config.ratePerSec);
+        bucket.updatedMs = nowMs;
+        if (bucket.tokens < 1) {
+            this.buckets.set(key, bucket);
+            return false;
+        }
+        bucket.tokens -= 1;
+        this.buckets.set(key, bucket);
+        return true;
+    }
+    /** Is the key currently locked out for repeated auth failures? */
+    isLockedOut(key) {
+        const state = this.failures.get(key);
+        return state !== undefined && this.now() < state.lockedUntilMs;
+    }
+    recordAuthFailure(key) {
+        const nowMs = this.now();
+        const state = this.failures.get(key) ?? {
+            count: 0,
+            windowStartMs: nowMs,
+            lockedUntilMs: 0
+        };
+        if (nowMs - state.windowStartMs > this.config.authFailureWindowMs) {
+            state.count = 0;
+            state.windowStartMs = nowMs;
+        }
+        state.count += 1;
+        if (state.count >= this.config.authFailureLimit) {
+            state.lockedUntilMs = nowMs + this.config.authFailureWindowMs;
+        }
+        this.failures.set(key, state);
+    }
+    recordAuthSuccess(key) {
+        this.failures.delete(key);
+    }
+}

package/dist/receipt-service.d.ts

@@ -0,0 +1,16 @@
+import { type ChainedEvent, type Receipt, type RunContract } from "@fusionkit/protocol";
+export type ReceiptServiceConfig = {
+    planePrivateKeyPem: string;
+    planePublicKeyPem: string;
+};
+export declare class ReceiptService {
+    private readonly config;
+    constructor(config: ReceiptServiceConfig);
+    verifyRunnerReceipt(input: {
+        contract: RunContract;
+        receipt: Receipt;
+        events: ChainedEvent[];
+        runnerPublicKeyPem: string;
+    }): void;
+    countersign(receipt: Receipt): Receipt;
+}

package/dist/receipt-service.js

@@ -0,0 +1,17 @@
+import { signReceipt, verifyRunnerReceipt } from "@fusionkit/protocol";
+import { badRequest } from "./domain-errors.js";
+export class ReceiptService {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    verifyRunnerReceipt(input) {
+        const result = verifyRunnerReceipt(input);
+        if (!result.ok) {
+            throw badRequest(`receipt runner verification failed: ${result.problems.join("; ")}`);
+        }
+    }
+    countersign(receipt) {
+        return signReceipt(receipt, this.config.planePrivateKeyPem, this.config.planePublicKeyPem, "plane");
+    }
+}

package/dist/retention.d.ts

@@ -0,0 +1,33 @@
+import type { RetentionPolicy } from "@fusionkit/protocol";
+import type { Logger } from "./logging.js";
+import type { PlaneStore } from "./store.js";
+/**
+ * Compute every blob hash still referenced by a surviving run: workspace
+ * manifests, continuation envelopes (and the transcript/journal blobs those
+ * envelopes reference), event artifacts, and receipt outputs. Anything not
+ * in this set is unreachable and safe to GC.
+ */
+export declare function collectReferencedBlobs(store: PlaneStore): Set<string>;
+export type RetentionResult = {
+    deletedRuns: string[];
+    deletedBlobs: number;
+    prunedNonces: number;
+};
+export declare class RetentionSweeper {
+    private readonly store;
+    private readonly policy;
+    private readonly intervalMs;
+    private readonly logger?;
+    private timer;
+    constructor(store: PlaneStore, policy: RetentionPolicy, intervalMs?: number, logger?: Logger | undefined);
+    /**
+     * Run one retention pass: expire terminal runs past the retention horizon,
+     * GC unreferenced blobs, and prune expired nonces. A run is retained for
+     * `receiptsDays`; its artifacts live exactly as long as the run does, so
+     * `artifactsDays` is honored as the floor — artifacts never outlive their
+     * receipt, which must stay verifiable while the receipt is retained.
+     */
+    sweepOnce(now?: number): RetentionResult;
+    start(): void;
+    stop(): void;
+}

package/dist/retention.js

@@ -0,0 +1,123 @@
+import { TERMINAL_RUN_STATUSES } from "@fusionkit/protocol";
+const TERMINAL = TERMINAL_RUN_STATUSES;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Default interval between background retention passes (override in ctor). */
+const DEFAULT_SWEEP_INTERVAL_MS = 60 * 60 * 1000;
+function addManifestHashes(keep, manifest) {
+    keep.add(manifest.bundleHash);
+    if (manifest.dirtyDiffHash)
+        keep.add(manifest.dirtyDiffHash);
+    for (const file of manifest.untrackedFiles)
+        keep.add(file.hash);
+}
+/**
+ * Compute every blob hash still referenced by a surviving run: workspace
+ * manifests, continuation envelopes (and the transcript/journal blobs those
+ * envelopes reference), event artifacts, and receipt outputs. Anything not
+ * in this set is unreachable and safe to GC.
+ */
+export function collectReferencedBlobs(store) {
+    const keep = new Set();
+    const envelopeHashes = new Set();
+    for (const run of store.listRuns()) {
+        addManifestHashes(keep, run.request.workspace);
+        if (run.request.continuation) {
+            keep.add(run.request.continuation.envelopeHash);
+            envelopeHashes.add(run.request.continuation.envelopeHash);
+        }
+        if (run.contract) {
+            addManifestHashes(keep, run.contract.workspace);
+            if (run.contract.continuation) {
+                keep.add(run.contract.continuation.envelopeHash);
+                envelopeHashes.add(run.contract.continuation.envelopeHash);
+            }
+        }
+        const receipt = store.getReceipt(run.id);
+        if (receipt) {
+            if (receipt.workspaceOut.diffHash)
+                keep.add(receipt.workspaceOut.diffHash);
+            for (const hash of receipt.workspaceOut.artifactHashes)
+                keep.add(hash);
+        }
+    }
+    for (const { event } of store.exportEvents(0)) {
+        if (event.event.type === "artifact.created")
+            keep.add(event.event.hash);
+        if (event.event.type === "boundary.crossed")
+            keep.add(event.event.contentHash);
+    }
+    // Envelopes reference transcript/journal/workspace blobs from inside their
+    // (content-addressed) JSON; parse the surviving ones to keep those too.
+    for (const hash of envelopeHashes) {
+        const blob = store.getBlob(hash);
+        if (!blob)
+            continue;
+        // The envelope blob is content-addressed (its hash is what we looked it
+        // up by), so its bytes are exactly what was sealed at submission time; a
+        // parse failure here means a truncated/foreign blob, which we skip
+        // rather than letting it abort the whole GC pass.
+        let envelope;
+        try {
+            envelope = JSON.parse(blob.toString("utf8"));
+        }
+        catch {
+            continue;
+        }
+        const semantic = envelope.checkpoint.semantic;
+        if (semantic?.transcriptHash)
+            keep.add(semantic.transcriptHash);
+        if (semantic?.toolJournalHash)
+            keep.add(semantic.toolJournalHash);
+        if (envelope.checkpoint.workspace) {
+            addManifestHashes(keep, envelope.checkpoint.workspace);
+        }
+    }
+    return keep;
+}
+export class RetentionSweeper {
+    store;
+    policy;
+    intervalMs;
+    logger;
+    timer;
+    constructor(store, policy, intervalMs = DEFAULT_SWEEP_INTERVAL_MS, logger) {
+        this.store = store;
+        this.policy = policy;
+        this.intervalMs = intervalMs;
+        this.logger = logger;
+    }
+    /**
+     * Run one retention pass: expire terminal runs past the retention horizon,
+     * GC unreferenced blobs, and prune expired nonces. A run is retained for
+     * `receiptsDays`; its artifacts live exactly as long as the run does, so
+     * `artifactsDays` is honored as the floor — artifacts never outlive their
+     * receipt, which must stay verifiable while the receipt is retained.
+     */
+    sweepOnce(now = Date.now()) {
+        const cutoff = now - this.policy.receiptsDays * DAY_MS;
+        const deletedRuns = this.store.deleteRunsUpdatedBefore(cutoff, [...TERMINAL]);
+        const keep = collectReferencedBlobs(this.store);
+        const deletedBlobs = this.store.deleteBlobsExcept(keep);
+        const prunedNonces = this.store.pruneClaimNonces(now);
+        return { deletedRuns, deletedBlobs, prunedNonces };
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            try {
+                this.sweepOnce();
+            }
+            catch (error) {
+                // Never let a sweep failure crash the plane; surface it for ops.
+                this.logger?.error({ err: error instanceof Error ? error.message : String(error) }, "retention sweep failed");
+            }
+        }, this.intervalMs);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+    }
+}

package/dist/run-lifecycle.d.ts

@@ -0,0 +1,2 @@
+import type { RunStatus } from "@fusionkit/protocol";
+export declare function assertRunTransition(from: RunStatus, to: RunStatus): void;

package/dist/run-lifecycle.js

@@ -0,0 +1,19 @@
+import { conflict } from "./domain-errors.js";
+const ALLOWED_TRANSITIONS = new Map([
+    ["created", ["claimed", "cancelled"]],
+    ["awaiting_approval", ["created", "cancelled"]],
+    ["claimed", ["running", "completed", "failed", "cancelled"]],
+    ["provisioning", ["running", "failed", "cancelled"]],
+    ["running", ["completed", "failed", "cancelled"]],
+    ["completed", []],
+    ["failed", []],
+    ["cancelled", []]
+]);
+function canTransitionRunStatus(from, to) {
+    return ALLOWED_TRANSITIONS.get(from)?.includes(to) ?? false;
+}
+export function assertRunTransition(from, to) {
+    if (!canTransitionRunStatus(from, to)) {
+        throw conflict(`cannot transition run from ${from} to ${to}`);
+    }
+}

package/dist/secrets.d.ts

@@ -0,0 +1,25 @@
+import type { MasterKey } from "./keys.js";
+/**
+ * Org secret store: a single AES-256-GCM file sealed with the plane master
+ * key (scrypt-derived per write). Values exist in plaintext only in memory
+ * and in the broker-to-runner release channel; they never appear in
+ * contracts, events, or receipts, and the encryption key is not derivable
+ * from config.json alone.
+ */
+export declare class SecretStore {
+    private readonly path;
+    private readonly master;
+    private cache?;
+    constructor(path: string, master: MasterKey);
+    private load;
+    private save;
+    set(name: string, value: string): void;
+    /** Rotate a secret's value, preserving its name; errors if absent. */
+    rotate(name: string, value: string): void;
+    remove(name: string): boolean;
+    names(): string[];
+    release(names: string[]): {
+        name: string;
+        value: string;
+    }[];
+}

package/dist/secrets.js

@@ -0,0 +1,73 @@
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { open, seal } from "./keys.js";
+/**
+ * Org secret store: a single AES-256-GCM file sealed with the plane master
+ * key (scrypt-derived per write). Values exist in plaintext only in memory
+ * and in the broker-to-runner release channel; they never appear in
+ * contracts, events, or receipts, and the encryption key is not derivable
+ * from config.json alone.
+ */
+export class SecretStore {
+    path;
+    master;
+    // Decrypt-once cache invalidated by file mtime, so a concurrent writer's
+    // update is still picked up. Single-process optimization; cross-process
+    // coordination is the store's job, not the secret file's.
+    cache;
+    constructor(path, master) {
+        this.path = path;
+        this.master = master;
+    }
+    load() {
+        if (!existsSync(this.path))
+            return {};
+        const mtimeMs = statSync(this.path).mtimeMs;
+        if (this.cache && this.cache.mtimeMs === mtimeMs)
+            return this.cache.values;
+        const blob = JSON.parse(readFileSync(this.path, "utf8"));
+        const plaintext = open(this.master, blob).toString("utf8");
+        const values = JSON.parse(plaintext);
+        this.cache = { mtimeMs, values };
+        return values;
+    }
+    save(values) {
+        const blob = seal(this.master, Buffer.from(JSON.stringify(values), "utf8"));
+        writeFileSync(this.path, JSON.stringify(blob), { mode: 0o600 });
+        this.cache = { mtimeMs: statSync(this.path).mtimeMs, values };
+    }
+    set(name, value) {
+        const values = this.load();
+        values[name] = { value, updatedAt: new Date().toISOString() };
+        this.save(values);
+    }
+    /** Rotate a secret's value, preserving its name; errors if absent. */
+    rotate(name, value) {
+        const values = this.load();
+        if (values[name] === undefined) {
+            throw new Error(`secret "${name}" is not in the store`);
+        }
+        values[name] = { value, updatedAt: new Date().toISOString() };
+        this.save(values);
+    }
+    remove(name) {
+        const values = this.load();
+        if (values[name] === undefined)
+            return false;
+        delete values[name];
+        this.save(values);
+        return true;
+    }
+    names() {
+        return Object.keys(this.load()).sort();
+    }
+    release(names) {
+        const values = this.load();
+        return names.map((name) => {
+            const entry = values[name];
+            if (entry === undefined) {
+                throw new Error(`secret "${name}" is not in the store`);
+            }
+            return { name, value: entry.value };
+        });
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,38 @@
+import type { Server } from "node:http";
+import { Plane } from "./plane.js";
+import type { RateLimitConfig } from "./ratelimit.js";
+/** Default request body cap (workspace bundles can be large). */
+export declare const DEFAULT_MAX_BODY_BYTES: number;
+export type PlaneServerOptions = {
+    port: number;
+    /**
+     * Bind host. Defaults to loopback ("127.0.0.1") as a secure-by-default
+     * choice; container/K8s deployments pass "0.0.0.0" explicitly (the CLI
+     * and docker-compose already do).
+     */
+    host?: string;
+    rateLimit?: Partial<RateLimitConfig>;
+    /** Request body cap in bytes. Defaults to DEFAULT_MAX_BODY_BYTES. */
+    maxBodyBytes?: number;
+    /**
+     * HTTP keep-alive idle timeout in ms. Defaults to 0 (disabled): clients
+     * in this repo retry idempotent requests, and disabling the idle timer
+     * avoids closed-socket races. Set a positive value when fronted by a
+     * reverse proxy whose own idle timeout should win.
+     */
+    keepAliveTimeoutMs?: number;
+    /** Trust X-Forwarded-For from a fronting proxy for rate-limit keys. */
+    trustProxy?: boolean;
+};
+/**
+ * Control-plane HTTP API plus the control panel UI. Every mutating and
+ * data-returning route is authenticated against a principal and gated by
+ * capability; bodies are schema-validated; requests are rate-limited per
+ * principal/IP with auth-failure backoff; everything is logged with a
+ * request id.
+ */
+export declare function startPlaneServer(plane: Plane, options: PlaneServerOptions | number): Promise<{
+    server: Server;
+    port: number;
+    host: string;
+}>;