@fusionkit/plane 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,18 @@
+import type { PrincipalRecord, PrincipalRole } from "./store.js";
+/** The authenticated caller behind a request. */
+export type Principal = {
+    principalId: string;
+    name: string;
+    role: PrincipalRole;
+};
+/**
+ * Tokens are stored only as their sha256. Every token the plane issues is
+ * 256 bits of CSPRNG output, so a plain SHA-256 lookup key is safe: there
+ * is nothing to brute-force and no need for a slow password hash. (Short,
+ * human-chosen tokens are never issued; if they were, this would need a
+ * peppered KDF instead.)
+ */
+export declare function hashToken(token: string): string;
+export declare function toPrincipal(record: PrincipalRecord): Principal;
+export type Capability = "runs:read" | "runs:create" | "runs:approve" | "runs:cancel" | "runners:read" | "policy:read" | "blobs:write" | "export:read" | "principals:manage";
+export declare function principalCan(role: PrincipalRole, capability: Capability): boolean;

package/dist/auth.js

@@ -0,0 +1,46 @@
+import { sha256Hex } from "@fusionkit/protocol";
+/**
+ * Tokens are stored only as their sha256. Every token the plane issues is
+ * 256 bits of CSPRNG output, so a plain SHA-256 lookup key is safe: there
+ * is nothing to brute-force and no need for a slow password hash. (Short,
+ * human-chosen tokens are never issued; if they were, this would need a
+ * peppered KDF instead.)
+ */
+export function hashToken(token) {
+    return sha256Hex(token);
+}
+export function toPrincipal(record) {
+    return {
+        principalId: record.principalId,
+        name: record.name,
+        role: record.role
+    };
+}
+/**
+ * Role capability model, defined in code as the plane's authorization
+ * policy. `admin` can do anything; the others are scoped to the actions the
+ * spec assigns them. Runner enrollment is gated separately (enroller role
+ * or a single-use enroll token), and runner-claim/event/completion
+ * endpoints authenticate with runner tokens + claim tokens, not principals.
+ * Per-deployment custom roles are intentionally out of scope; this matrix
+ * is the contract.
+ */
+const CAPABILITIES = {
+    admin: new Set([
+        "runs:read",
+        "runs:create",
+        "runs:approve",
+        "runs:cancel",
+        "runners:read",
+        "policy:read",
+        "blobs:write",
+        "export:read",
+        "principals:manage"
+    ]),
+    requester: new Set(["runs:read", "runs:create", "runs:cancel", "blobs:write", "policy:read"]),
+    approver: new Set(["runs:read", "runs:approve", "policy:read"]),
+    enroller: new Set(["runners:read"])
+};
+export function principalCan(role, capability) {
+    return CAPABILITIES[role].has(capability);
+}

package/dist/claim-token-service.d.ts

@@ -0,0 +1,23 @@
+export type ClaimTokenPayload = {
+    runId: string;
+    runnerId: string;
+    nonce: string;
+    exp: string;
+};
+export type VerifiedClaimToken = ClaimTokenPayload & {
+    expMs: number;
+};
+export type ClaimTokenServiceOptions = {
+    planePrivateKeyPem: string;
+    planePublicKeyPem: string;
+    claimTokenTtlMs: number;
+};
+export declare class ClaimTokenService {
+    private readonly options;
+    constructor(options: ClaimTokenServiceOptions);
+    issue(input: {
+        runId: string;
+        runnerId: string;
+    }): string;
+    parse(token: string): VerifiedClaimToken;
+}

package/dist/claim-token-service.js

@@ -0,0 +1,54 @@
+import { randomBytes } from "node:crypto";
+import { signData, verifyData } from "@fusionkit/protocol";
+import { badRequest, unauthorized } from "./domain-errors.js";
+export class ClaimTokenService {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    issue(input) {
+        const payload = {
+            runId: input.runId,
+            runnerId: input.runnerId,
+            nonce: randomBytes(16).toString("base64url"),
+            exp: new Date(Date.now() + this.options.claimTokenTtlMs).toISOString()
+        };
+        const encoded = Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+        const sig = signData(this.options.planePrivateKeyPem, encoded);
+        return `${encoded}.${Buffer.from(sig, "base64").toString("base64url")}`;
+    }
+    parse(token) {
+        const [encoded, sigB64url] = token.split(".");
+        if (!encoded || !sigB64url)
+            throw badRequest("malformed claim token");
+        const sig = Buffer.from(sigB64url, "base64url").toString("base64");
+        if (!verifyData(this.options.planePublicKeyPem, encoded, sig)) {
+            throw unauthorized("claim token signature invalid");
+        }
+        let payload;
+        try {
+            payload = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+        }
+        catch {
+            throw badRequest("claim token payload is not valid JSON");
+        }
+        if (typeof payload.runId !== "string" ||
+            typeof payload.runnerId !== "string" ||
+            typeof payload.nonce !== "string" ||
+            typeof payload.exp !== "string") {
+            throw badRequest("claim token payload is missing required fields");
+        }
+        const expMs = new Date(payload.exp).getTime();
+        if (!Number.isFinite(expMs))
+            throw badRequest("claim token expiry is invalid");
+        if (expMs < Date.now())
+            throw unauthorized("claim token expired");
+        return {
+            runId: payload.runId,
+            runnerId: payload.runnerId,
+            nonce: payload.nonce,
+            exp: payload.exp,
+            expMs
+        };
+    }
+}

package/dist/contract-service.d.ts

@@ -0,0 +1,14 @@
+import { type ActorRef, type RunContract } from "@fusionkit/protocol";
+import type { RunRequest } from "./store.js";
+export type ContractServiceOptions = {
+    planePrivateKeyPem: string;
+    planePublicKeyPem: string;
+    policyHash: string;
+    contractTtlMs: number;
+    buildSecretClaims: (secretNames: string[], pool: string) => RunContract["secrets"];
+};
+export declare class ContractService {
+    private readonly options;
+    constructor(options: ContractServiceOptions);
+    issue(request: RunRequest, approvedBy: ActorRef[]): RunContract;
+}

package/dist/contract-service.js

@@ -0,0 +1,39 @@
+import { executionFromRunRequest, keyIdFromPublicPem, PROTOCOL_VERSIONS, signContract } from "@fusionkit/protocol";
+export class ContractService {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    issue(request, approvedBy) {
+        const now = Date.now();
+        const unsigned = {
+            version: PROTOCOL_VERSIONS.contract,
+            runId: request.runId,
+            issuedAt: new Date(now).toISOString(),
+            issuer: {
+                keyId: keyIdFromPublicPem(this.options.planePublicKeyPem),
+                role: "plane"
+            },
+            requestedBy: request.requestedBy,
+            ...(approvedBy.length > 0 ? { approvedBy } : {}),
+            agent: {
+                kind: request.agentKind,
+                ...(request.agentVersion ? { version: request.agentVersion } : {})
+            },
+            task: { prompt: request.prompt },
+            runner: { pool: request.pool },
+            workspace: request.workspace,
+            policyHash: this.options.policyHash,
+            secrets: this.options.buildSecretClaims(request.secretNames, request.pool),
+            network: request.network,
+            budget: request.budget,
+            disclosure: request.disclosure,
+            execution: executionFromRunRequest(request),
+            ...(request.isolation ? { isolation: request.isolation } : {}),
+            ...(request.continuation ? { continuation: request.continuation } : {}),
+            expiresAt: new Date(now + this.options.contractTtlMs).toISOString(),
+            signatures: []
+        };
+        return signContract(unsigned, this.options.planePrivateKeyPem, this.options.planePublicKeyPem, "plane");
+    }
+}

package/dist/domain-errors.d.ts

@@ -0,0 +1,13 @@
+export type PlaneErrorCode = "bad_request" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "capability_mismatch";
+export declare class PlaneDomainError extends Error {
+    readonly status: number;
+    readonly code: PlaneErrorCode;
+    constructor(status: number, code: PlaneErrorCode, message: string);
+}
+export declare function badRequest(message: string): PlaneDomainError;
+export declare function unauthorized(message: string): PlaneDomainError;
+export declare function forbidden(message: string): PlaneDomainError;
+export declare function notFound(message: string): PlaneDomainError;
+export declare function conflict(message: string): PlaneDomainError;
+export declare function capabilityMismatch(message: string): PlaneDomainError;
+export declare function isPlaneDomainError(error: unknown): error is PlaneDomainError;

package/dist/domain-errors.js

@@ -0,0 +1,31 @@
+export class PlaneDomainError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "PlaneDomainError";
+    }
+}
+export function badRequest(message) {
+    return new PlaneDomainError(400, "bad_request", message);
+}
+export function unauthorized(message) {
+    return new PlaneDomainError(401, "unauthorized", message);
+}
+export function forbidden(message) {
+    return new PlaneDomainError(403, "forbidden", message);
+}
+export function notFound(message) {
+    return new PlaneDomainError(404, "not_found", message);
+}
+export function conflict(message) {
+    return new PlaneDomainError(409, "conflict", message);
+}
+export function capabilityMismatch(message) {
+    return new PlaneDomainError(422, "capability_mismatch", message);
+}
+export function isPlaneDomainError(error) {
+    return error instanceof PlaneDomainError;
+}

package/dist/idp.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Verifies IdP-issued approval assertions so a consent decision is bound to
+ * a real, externally-authenticated subject rather than to whoever holds an
+ * admin token. The plane is configured with the IdP issuer, audience, and a
+ * JWKS (resolved out-of-band by the operator and passed in); approvals
+ * present a JWT, which is verified against that JWKS.
+ */
+export type IdpConfig = {
+    issuer: string;
+    audience: string;
+    /** JWKS contents (the operator fetches and pins these). */
+    jwks: {
+        keys: Record<string, unknown>[];
+    };
+};
+export type VerifiedApproval = {
+    subject: string;
+    issuer: string;
+};
+export declare class IdpVerifier {
+    private readonly issuer;
+    private readonly audience;
+    private readonly getKey;
+    constructor(config: IdpConfig);
+    verify(token: string): Promise<VerifiedApproval>;
+}

package/dist/idp.js

@@ -0,0 +1,24 @@
+import { createLocalJWKSet, jwtVerify } from "jose";
+export class IdpVerifier {
+    issuer;
+    audience;
+    getKey;
+    constructor(config) {
+        this.issuer = config.issuer;
+        this.audience = config.audience;
+        // JWKS is pinned by the operator out-of-band (the plan's design): the
+        // plane verifies against exactly the keys it was configured with. Key
+        // rotation is an operator action (re-pin the JWKS), which keeps approval
+        // verification deterministic and offline-friendly.
+        this.getKey = createLocalJWKSet(config.jwks);
+    }
+    async verify(token) {
+        const { payload } = await jwtVerify(token, this.getKey, { issuer: this.issuer, audience: this.audience });
+        if (!payload.sub) {
+            throw new Error("IdP token has no subject (sub) claim");
+        }
+        // jwtVerify already rejects any token whose `iss` is not this issuer, so
+        // returning the configured issuer reflects the verified value.
+        return { subject: payload.sub, issuer: this.issuer };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @fusionkit/plane — control plane: contracts, policy evaluation, approvals,
+ * receipt countersignature, secret broker, audit export, durable SQLite
+ * storage, identity/auth, rate limiting, retention, and the control panel UI.
+ */
+export { Plane } from "./plane.js";
+export type { PlaneConfig, IssuedPrincipal } from "./plane.js";
+export { startPlaneServer } from "./server.js";
+export type { PlaneServerOptions } from "./server.js";
+export { defaultPolicy, evaluatePolicy } from "./policy.js";
+export type { PolicyDecision, PolicyRequest } from "./policy.js";
+export { badRequest, capabilityMismatch, conflict, forbidden, isPlaneDomainError, notFound, PlaneDomainError, unauthorized } from "./domain-errors.js";
+export type { PlaneErrorCode } from "./domain-errors.js";
+export { ClaimTokenService } from "./claim-token-service.js";
+export type { ClaimTokenPayload, ClaimTokenServiceOptions, VerifiedClaimToken } from "./claim-token-service.js";
+export { ContractService } from "./contract-service.js";
+export type { ContractServiceOptions } from "./contract-service.js";
+export { ReceiptService } from "./receipt-service.js";
+export type { ReceiptServiceConfig } from "./receipt-service.js";
+export { SqliteStore } from "./sqlite-store.js";
+export type { EnrollTokenRecord, PlaneStore, PrincipalRecord, PrincipalRole, RunRecord, RunRequest, RunnerRecord } from "./store.js";
+export { SecretStore } from "./secrets.js";
+export { FileKeyProvider, generateMasterKeyHex, masterKeyFromMaterial, open, openFromFile, resolveMasterKey, seal, sealToFile } from "./keys.js";
+export type { KeyProvider, MasterKey, OrgKeyPair, SealedBlob } from "./keys.js";
+export { hashToken, principalCan, toPrincipal } from "./auth.js";
+export type { Capability, Principal } from "./auth.js";
+export { IdpVerifier } from "./idp.js";
+export type { IdpConfig, VerifiedApproval } from "./idp.js";
+export { DEFAULT_RATE_LIMIT, RateLimiter } from "./ratelimit.js";
+export type { RateLimitConfig } from "./ratelimit.js";
+export { createLogger, Metrics } from "./logging.js";
+export type { Logger } from "./logging.js";
+export { collectReferencedBlobs, RetentionSweeper } from "./retention.js";
+export type { RetentionResult } from "./retention.js";
+export { approveBodySchema, cancelBodySchema, claimBodySchema, completeBodySchema, createRunBodySchema, enrollBodySchema, eventsBodySchema, issuePrincipalBodySchema, parseBody, runRequestSchema, ValidationError } from "./validation.js";

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * @fusionkit/plane — control plane: contracts, policy evaluation, approvals,
+ * receipt countersignature, secret broker, audit export, durable SQLite
+ * storage, identity/auth, rate limiting, retention, and the control panel UI.
+ */
+export { Plane } from "./plane.js";
+export { startPlaneServer } from "./server.js";
+export { defaultPolicy, evaluatePolicy } from "./policy.js";
+export { badRequest, capabilityMismatch, conflict, forbidden, isPlaneDomainError, notFound, PlaneDomainError, unauthorized } from "./domain-errors.js";
+export { ClaimTokenService } from "./claim-token-service.js";
+export { ContractService } from "./contract-service.js";
+export { ReceiptService } from "./receipt-service.js";
+export { SqliteStore } from "./sqlite-store.js";
+export { SecretStore } from "./secrets.js";
+export { FileKeyProvider, generateMasterKeyHex, masterKeyFromMaterial, open, openFromFile, resolveMasterKey, seal, sealToFile } from "./keys.js";
+export { hashToken, principalCan, toPrincipal } from "./auth.js";
+export { IdpVerifier } from "./idp.js";
+export { DEFAULT_RATE_LIMIT, RateLimiter } from "./ratelimit.js";
+export { createLogger, Metrics } from "./logging.js";
+export { collectReferencedBlobs, RetentionSweeper } from "./retention.js";
+export { approveBodySchema, cancelBodySchema, claimBodySchema, completeBodySchema, createRunBodySchema, enrollBodySchema, eventsBodySchema, issuePrincipalBodySchema, parseBody, runRequestSchema, ValidationError } from "./validation.js";

package/dist/keys.d.ts

@@ -0,0 +1,60 @@
+/**
+ * A master key protects everything the plane stores at rest (the org
+ * signing key, the secret store). It is supplied out-of-band via the
+ * WARRANT_MASTER_KEY environment variable, or persisted to a 0600 key file
+ * generated at init. It is never written into config.json, so config alone
+ * is not enough to decrypt anything.
+ */
+export type MasterKey = {
+    readonly material: Buffer;
+};
+/** Default env var carrying the master key; override via resolveMasterKey. */
+export declare const DEFAULT_MASTER_KEY_ENV = "WARRANT_MASTER_KEY";
+export declare function generateMasterKeyHex(): string;
+/** Build a MasterKey from raw material (hex/base64/utf8); for tests and CLI. */
+export declare function masterKeyFromMaterial(raw: string): MasterKey;
+/**
+ * Resolve the master key: WARRANT_MASTER_KEY if set, otherwise the key file
+ * at `keyFilePath`. When `createIfMissing` is true and neither exists, a new
+ * key is generated and written to the key file (mode 0600).
+ */
+export declare function resolveMasterKey(keyFilePath: string, options?: {
+    createIfMissing?: boolean;
+    envVar?: string;
+}): MasterKey;
+export type SealedBlob = {
+    version: "warrant.sealed.v1";
+    salt: string;
+    iv: string;
+    tag: string;
+    data: string;
+};
+/** AES-256-GCM with a per-blob scrypt-derived key. */
+export declare function seal(master: MasterKey, plaintext: Buffer): SealedBlob;
+export declare function open(master: MasterKey, blob: SealedBlob): Buffer;
+export declare function sealToFile(master: MasterKey, path: string, plaintext: Buffer): void;
+export declare function openFromFile(master: MasterKey, path: string): Buffer;
+export type OrgKeyPair = {
+    publicKeyPem: string;
+    privateKeyPem: string;
+};
+/**
+ * Source of the org signing key pair. The private key is held in memory by
+ * the plane but stored encrypted at rest by the provider. External KMS
+ * integrations implement this same interface.
+ */
+export interface KeyProvider {
+    getOrgKeyPair(): OrgKeyPair;
+}
+/**
+ * File-backed key provider: public key in PEM, private key sealed with the
+ * master key. Generates a fresh key pair on first use when allowed.
+ */
+export declare class FileKeyProvider implements KeyProvider {
+    private readonly master;
+    private readonly publicKeyPath;
+    private readonly privateKeySealedPath;
+    constructor(master: MasterKey, publicKeyPath: string, privateKeySealedPath: string);
+    ensure(): OrgKeyPair;
+    getOrgKeyPair(): OrgKeyPair;
+}

package/dist/keys.js

@@ -0,0 +1,132 @@
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { generateEd25519KeyPair } from "@fusionkit/protocol";
+/** Default env var carrying the master key; override via resolveMasterKey. */
+export const DEFAULT_MASTER_KEY_ENV = "WARRANT_MASTER_KEY";
+/**
+ * Decode master-key material. Canonical form is 64 hex chars (32 bytes) —
+ * what generateMasterKeyHex produces and what we recommend. A non-hex value
+ * is treated as raw UTF-8 bytes (a passphrase). We deliberately do NOT
+ * second-guess with base64 decoding, which is what made the order
+ * ambiguous: hex or passphrase, nothing in between.
+ */
+function decodeMaterial(raw) {
+    const trimmed = raw.trim();
+    if (/^[0-9a-f]{64}$/i.test(trimmed))
+        return Buffer.from(trimmed, "hex");
+    return Buffer.from(trimmed, "utf8");
+}
+export function generateMasterKeyHex() {
+    return randomBytes(32).toString("hex");
+}
+/** Build a MasterKey from raw material (hex/base64/utf8); for tests and CLI. */
+export function masterKeyFromMaterial(raw) {
+    return { material: decodeMaterial(raw) };
+}
+/**
+ * Resolve the master key: WARRANT_MASTER_KEY if set, otherwise the key file
+ * at `keyFilePath`. When `createIfMissing` is true and neither exists, a new
+ * key is generated and written to the key file (mode 0600).
+ */
+export function resolveMasterKey(keyFilePath, options = {}) {
+    const fromEnv = process.env[options.envVar ?? DEFAULT_MASTER_KEY_ENV];
+    if (fromEnv && fromEnv.length > 0) {
+        return { material: decodeMaterial(fromEnv) };
+    }
+    if (existsSync(keyFilePath)) {
+        return { material: decodeMaterial(readFileSync(keyFilePath, "utf8")) };
+    }
+    if (options.createIfMissing) {
+        mkdirSync(dirname(keyFilePath), { recursive: true });
+        const hex = generateMasterKeyHex();
+        writeFileSync(keyFilePath, hex, { mode: KEY_FILE_MODE });
+        return { material: Buffer.from(hex, "hex") };
+    }
+    throw new Error(`no master key: set ${options.envVar ?? DEFAULT_MASTER_KEY_ENV} or provide a key file at ${keyFilePath}`);
+}
+// AES-256-GCM sealing parameters. These bind to AES-256 (32-byte key,
+// 12-byte GCM IV) and a 16-byte scrypt salt. scrypt uses Node's defaults
+// (N=16384, r=8, p=1), which are appropriate for sealing small, infrequent
+// payloads (the org key and the secret file). scryptSync is acceptable here
+// precisely because these payloads are small and sealed/opened rarely.
+const SALT_BYTES = 16;
+const IV_BYTES = 12;
+const KEY_BYTES = 32;
+const KEY_FILE_MODE = 0o600;
+/** AES-256-GCM with a per-blob scrypt-derived key. */
+export function seal(master, plaintext) {
+    const salt = randomBytes(SALT_BYTES);
+    const key = scryptSync(master.material, salt, KEY_BYTES);
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const data = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return {
+        version: "warrant.sealed.v1",
+        salt: salt.toString("base64"),
+        iv: iv.toString("base64"),
+        tag: cipher.getAuthTag().toString("base64"),
+        data: data.toString("base64")
+    };
+}
+function assertSealedBlob(value) {
+    const blob = value;
+    if (!blob ||
+        blob.version !== "warrant.sealed.v1" ||
+        typeof blob.salt !== "string" ||
+        typeof blob.iv !== "string" ||
+        typeof blob.tag !== "string" ||
+        typeof blob.data !== "string") {
+        throw new Error("sealed blob is malformed or not a warrant.sealed.v1 envelope");
+    }
+}
+export function open(master, blob) {
+    assertSealedBlob(blob);
+    const key = scryptSync(master.material, Buffer.from(blob.salt, "base64"), KEY_BYTES);
+    const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(blob.iv, "base64"));
+    decipher.setAuthTag(Buffer.from(blob.tag, "base64"));
+    return Buffer.concat([
+        decipher.update(Buffer.from(blob.data, "base64")),
+        decipher.final()
+    ]);
+}
+export function sealToFile(master, path, plaintext) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(seal(master, plaintext)), { mode: 0o600 });
+}
+export function openFromFile(master, path) {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    assertSealedBlob(parsed);
+    return open(master, parsed);
+}
+/**
+ * File-backed key provider: public key in PEM, private key sealed with the
+ * master key. Generates a fresh key pair on first use when allowed.
+ */
+export class FileKeyProvider {
+    master;
+    publicKeyPath;
+    privateKeySealedPath;
+    constructor(master, publicKeyPath, privateKeySealedPath) {
+        this.master = master;
+        this.publicKeyPath = publicKeyPath;
+        this.privateKeySealedPath = privateKeySealedPath;
+    }
+    ensure() {
+        if (existsSync(this.publicKeyPath) &&
+            existsSync(this.privateKeySealedPath)) {
+            return this.getOrgKeyPair();
+        }
+        const pair = generateEd25519KeyPair();
+        mkdirSync(dirname(this.publicKeyPath), { recursive: true });
+        writeFileSync(this.publicKeyPath, pair.publicKeyPem, { mode: 0o600 });
+        sealToFile(this.master, this.privateKeySealedPath, Buffer.from(pair.privateKeyPem, "utf8"));
+        return pair;
+    }
+    getOrgKeyPair() {
+        return {
+            publicKeyPem: readFileSync(this.publicKeyPath, "utf8"),
+            privateKeyPem: openFromFile(this.master, this.privateKeySealedPath).toString("utf8")
+        };
+    }
+}

package/dist/logging.d.ts

@@ -0,0 +1,21 @@
+import type { Logger } from "pino";
+/**
+ * Structured plane logger. Level via the `level` argument or LOG_LEVEL,
+ * defaulting to "silent" so the library never pollutes a host's stdout
+ * unless logging is explicitly requested (operators set LOG_LEVEL=info, or
+ * inject a configured logger via PlaneConfig.logger).
+ */
+export declare function createLogger(name?: string, level?: string): Logger;
+/** Counters the plane increments for operational visibility. */
+/**
+ * Lightweight in-process counters exposed at /v1/metrics as JSON. This is a
+ * deliberately minimal surface (counts, not histograms/labels): a deployment
+ * that needs a Prometheus scrape format wraps these counters in its own
+ * exporter rather than the plane taking on that dependency.
+ */
+export declare class Metrics {
+    private readonly counters;
+    inc(name: string, by?: number): void;
+    snapshot(): Record<string, number>;
+}
+export type { Logger };

package/dist/logging.js

@@ -0,0 +1,42 @@
+import { pino } from "pino";
+/**
+ * Structured plane logger. Level via the `level` argument or LOG_LEVEL,
+ * defaulting to "silent" so the library never pollutes a host's stdout
+ * unless logging is explicitly requested (operators set LOG_LEVEL=info, or
+ * inject a configured logger via PlaneConfig.logger).
+ */
+export function createLogger(name = "warrant-plane", level = process.env.LOG_LEVEL ?? "silent") {
+    return pino({
+        name,
+        level,
+        // The plane handles secrets and tokens; redact common carriers defensively.
+        redact: {
+            paths: [
+                "token",
+                "claimToken",
+                "runnerToken",
+                "enrollToken",
+                "idpToken",
+                "*.token",
+                "req.headers.authorization"
+            ],
+            censor: "[redacted]"
+        }
+    });
+}
+/** Counters the plane increments for operational visibility. */
+/**
+ * Lightweight in-process counters exposed at /v1/metrics as JSON. This is a
+ * deliberately minimal surface (counts, not histograms/labels): a deployment
+ * that needs a Prometheus scrape format wraps these counters in its own
+ * exporter rather than the plane taking on that dependency.
+ */
+export class Metrics {
+    counters = new Map();
+    inc(name, by = 1) {
+        this.counters.set(name, (this.counters.get(name) ?? 0) + by);
+    }
+    snapshot() {
+        return Object.fromEntries([...this.counters.entries()].sort());
+    }
+}