@fusionkit/plane 0.1.0

package/dist/plane.d.ts

@@ -0,0 +1,167 @@
+import type { ActorRef, ChainedEvent, ClaimResult, DisclosureReport, Policy, PolicyDecision, Receipt, ReceiptBundle, RunnerSummary, RunSummary } from "@fusionkit/protocol";
+import type { Capability, Principal } from "./auth.js";
+import type { IdpVerifier } from "./idp.js";
+import { Metrics } from "./logging.js";
+import type { Logger } from "./logging.js";
+import { RetentionSweeper } from "./retention.js";
+import { SecretStore } from "./secrets.js";
+import type { PlaneStore, PrincipalRole, RunRecord, RunRequest } from "./store.js";
+export type PlaneConfig = {
+    dataDir: string;
+    policy: Policy;
+    planePrivateKeyPem: string;
+    planePublicKeyPem: string;
+    /** Bootstrap admin principal token. */
+    adminToken: string;
+    /** Bootstrap reusable enroller credential (also accepts single-use tokens). */
+    enrollToken: string;
+    secretStore: SecretStore;
+    /** Inject a store (tests); defaults to SQLite at <dataDir>/<sqliteFilename>. */
+    store?: PlaneStore;
+    /** Verifier for IdP-issued approval assertions, when configured. */
+    idp?: IdpVerifier;
+    logger?: Logger;
+    metrics?: Metrics;
+    /** Start the background retention sweeper. Defaults to false. */
+    startRetention?: boolean;
+    /** Timeouts, sizes, and names; sensible defaults below. */
+    tuning?: Partial<PlaneTuning>;
+};
+/** Tunable plane parameters. Defaults are in DEFAULT_PLANE_TUNING. */
+export type PlaneTuning = {
+    /** Validity of a runner claim token. */
+    claimTokenTtlMs: number;
+    /** Validity of an issued run contract. */
+    contractTtlMs: number;
+    /** How long a completion nonce is retained past claim-token expiry. */
+    nonceTtlMs: number;
+    /** Default validity of a minted single-use enroll token. */
+    enrollTokenTtlMs: number;
+    /** Random bytes of entropy in issued principal/runner/enroll tokens. */
+    tokenBytes: number;
+    /** SQLite database filename under dataDir. */
+    sqliteFilename: string;
+    /** Bootstrap principal names. */
+    bootstrapAdminName: string;
+    bootstrapEnrollerName: string;
+};
+export declare const DEFAULT_PLANE_TUNING: PlaneTuning;
+export type { ClaimResult, DisclosureReport, PolicyDecision };
+export type IssuedPrincipal = {
+    principalId: string;
+    name: string;
+    role: PrincipalRole;
+    token: string;
+};
+export declare class Plane {
+    private readonly config;
+    private readonly store;
+    private readonly policyHash;
+    private readonly receipts;
+    private readonly claimTokens;
+    private readonly contracts;
+    private readonly logger;
+    private readonly idp?;
+    readonly metrics: Metrics;
+    private readonly sweeper;
+    private readonly tuning;
+    constructor(config: PlaneConfig);
+    /** Ensure the bootstrap admin and enroller principals match the config. */
+    private seedBootstrapPrincipals;
+    /** Mint a fresh bearer token with the configured entropy. */
+    private newToken;
+    private upsertPrincipal;
+    close(): void;
+    get blobs(): PlaneStore;
+    get policySnapshot(): {
+        policy: Policy;
+        policyHash: string;
+    };
+    get log(): Logger;
+    /** Run one retention pass synchronously (also used by tests). */
+    sweepRetention(): ReturnType<RetentionSweeper["sweepOnce"]>;
+    /** Resolve a bearer token to a principal, or undefined if invalid/revoked. */
+    authenticate(token: string | undefined): Principal | undefined;
+    authorize(token: string | undefined, capability: Capability): Principal | undefined;
+    /** Backward-compatible admin check used by older callers. */
+    checkAdminToken(token: string | undefined): boolean;
+    issuePrincipal(name: string, role: PrincipalRole): IssuedPrincipal;
+    rotatePrincipal(name: string): {
+        token: string;
+    };
+    revokePrincipal(name: string): boolean;
+    listPrincipals(): {
+        name: string;
+        role: PrincipalRole;
+        createdAt: string;
+        revoked: boolean;
+    }[];
+    /** Mint a single-use, expiring runner enrollment token. */
+    issueEnrollToken(options?: {
+        pool?: string;
+        ttlMs?: number;
+    }): {
+        token: string;
+        expiresAt: string;
+    };
+    enrollRunner(input: {
+        enrollToken: string;
+        publicKeyPem: string;
+        pool: string;
+    }): {
+        runnerId: string;
+        runnerToken: string;
+    };
+    listRunners(): RunnerSummary[];
+    listRuns(): RunSummary[];
+    private authRunner;
+    private buildSecretClaims;
+    private evaluateRequest;
+    dryRun(request: Omit<RunRequest, "runId">): DisclosureReport;
+    requestRun(request: Omit<RunRequest, "runId">): RunRecord;
+    private continuationEvents;
+    approve(runId: string, actor: ActorRef, verified?: {
+        idpSubject: string;
+        idpIssuer: string;
+    }): RunRecord;
+    cancel(runId: string, actor: ActorRef): RunRecord;
+    private issueContract;
+    private appendPlaneEvents;
+    claim(input: {
+        runnerToken: string;
+        pool: string;
+    }): ClaimResult | undefined;
+    /**
+     * Single decoder for claim tokens: verifies the plane signature, validates
+     * every payload field is present and well-formed, and checks expiry.
+     * Throws on any defect; both public verifiers below build on this.
+     */
+    private parseClaimToken;
+    /**
+     * Verify a claim token's plane signature, payload shape, and expiry, plus
+     * that the named run is actually claimed by the named runner. Used to
+     * authorize artifact blob uploads from a runner holding an active claim;
+     * unlike verifyClaimToken it does not require the caller to know the run
+     * id ahead of time, but it still enforces the token's own run binding.
+     */
+    verifyClaimTokenSignature(token: string): boolean;
+    private verifyClaimToken;
+    appendRunnerEvents(runId: string, claimToken: string, events: ChainedEvent[]): void;
+    complete(runId: string, claimToken: string, receipt: Receipt): Receipt;
+    getRun(runId: string): RunRecord | undefined;
+    getEvents(runId: string): ChainedEvent[];
+    getBundle(runId: string): ReceiptBundle | undefined;
+    exportJsonl(sinceIso?: string): string;
+    /**
+     * Readiness: store reachable and the signing keypair actually usable —
+     * the private key must parse and its public half must match the
+     * configured public key, so a plane with mismatched key material reports
+     * not-ready instead of issuing unverifiable contracts.
+     */
+    ready(): boolean;
+    verifyIdpToken(token: string): Promise<{
+        idpSubject: string;
+        idpIssuer: string;
+    }>;
+    private mustGetRun;
+}