@vellumai/credential-executor 0.4.55

package/src/grants/persistent-store.ts

@@ -0,0 +1,247 @@
+/**
+ * CES persistent grant store.
+ *
+ * Stores canonical validated grants by stable ID in a `grants.json` file
+ * inside the CES-private data root. This file is never co-mingled with
+ * assistant trust files or credential metadata.
+ *
+ * Design principles:
+ * - **Fail closed**: If the store file is unreadable or malformed, all
+ *   reads return empty and all writes throw. The CES must never fall back
+ *   to a permissive default when the persistent state is corrupt.
+ * - **Atomic writes**: Uses rename-over-tmp to prevent partial writes.
+ * - **Deduplication**: Grants are keyed by a canonical hash (the `id`
+ *   field) — adding a grant with an existing ID is a no-op.
+ */
+
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+import { getCesGrantsDir } from "../paths.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A canonical persistent grant stored on disk. */
+export interface PersistentGrant {
+  /** Stable canonical hash identifying this grant. */
+  id: string;
+  /** The tool or command pattern this grant authorises. */
+  tool: string;
+  /** Glob pattern scoping the grant. */
+  pattern: string;
+  /** Scope constraint (directory path or "everywhere"). */
+  scope: string;
+  /** When the grant was created (epoch ms). */
+  createdAt: number;
+}
+
+/** On-disk format for the grants file. */
+interface GrantsFile {
+  version: number;
+  grants: PersistentGrant[];
+}
+
+const GRANTS_FILE_VERSION = 1;
+const GRANTS_FILENAME = "grants.json";
+
+// ---------------------------------------------------------------------------
+// Store implementation
+// ---------------------------------------------------------------------------
+
+export class PersistentGrantStore {
+  private readonly filePath: string;
+  private cache: PersistentGrant[] | null = null;
+  /** Set to true when the store detects corruption; blocks all operations. */
+  private corrupt = false;
+
+  constructor(grantsDir?: string) {
+    const dir = grantsDir ?? getCesGrantsDir();
+    this.filePath = join(dir, GRANTS_FILENAME);
+  }
+
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+
+  /**
+   * Initialise the store, ensuring the parent directory exists and the
+   * grants file is readable. If the file does not exist it is created
+   * with an empty grant list.
+   *
+   * Throws if the directory cannot be created or an existing file is
+   * malformed (fail-closed).
+   */
+  init(): void {
+    const dir = dirname(this.filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    if (!existsSync(this.filePath)) {
+      this.writeToDisk([]);
+      return;
+    }
+
+    // Validate the existing file is readable and well-formed.
+    // If it isn't, mark corrupt and throw (fail closed).
+    this.loadFromDisk();
+  }
+
+  /**
+   * Return all persisted grants.
+   *
+   * Returns an empty array if the store has never been initialised
+   * (no file on disk). Throws if the store is corrupt.
+   */
+  getAll(): PersistentGrant[] {
+    this.assertNotCorrupt();
+    if (this.cache !== null) return [...this.cache];
+    if (!existsSync(this.filePath)) return [];
+    return [...this.loadFromDisk()];
+  }
+
+  /**
+   * Look up a grant by its canonical ID.
+   *
+   * Returns `undefined` if not found. Throws if the store is corrupt.
+   */
+  getById(id: string): PersistentGrant | undefined {
+    return this.getAll().find((g) => g.id === id);
+  }
+
+  /**
+   * Add a grant. If a grant with the same `id` already exists, this is
+   * a no-op (idempotent deduplication by canonical hash).
+   *
+   * Returns `true` if the grant was newly added, `false` if it was a
+   * duplicate.
+   */
+  add(grant: PersistentGrant): boolean {
+    this.assertNotCorrupt();
+    const grants = this.loadFromDisk();
+    if (grants.some((g) => g.id === grant.id)) {
+      return false;
+    }
+    grants.push(grant);
+    this.writeToDisk(grants);
+    return true;
+  }
+
+  /**
+   * Remove a grant by its canonical ID.
+   *
+   * Returns `true` if the grant was found and removed, `false` otherwise.
+   */
+  remove(id: string): boolean {
+    this.assertNotCorrupt();
+    const grants = this.loadFromDisk();
+    const index = grants.findIndex((g) => g.id === id);
+    if (index === -1) return false;
+    grants.splice(index, 1);
+    this.writeToDisk(grants);
+    return true;
+  }
+
+  /**
+   * Check whether a grant with the given ID exists.
+   */
+  has(id: string): boolean {
+    return this.getById(id) !== undefined;
+  }
+
+  /**
+   * Remove all grants and reset the store to an empty state.
+   */
+  clear(): void {
+    this.assertNotCorrupt();
+    this.writeToDisk([]);
+  }
+
+  // -----------------------------------------------------------------------
+  // Internals
+  // -----------------------------------------------------------------------
+
+  private assertNotCorrupt(): void {
+    if (this.corrupt) {
+      throw new Error(
+        "CES persistent grant store is corrupt — refusing to operate (fail closed)",
+      );
+    }
+  }
+
+  private loadFromDisk(): PersistentGrant[] {
+    try {
+      const raw = readFileSync(this.filePath, "utf-8");
+      const data = JSON.parse(raw) as unknown;
+
+      if (
+        typeof data !== "object" ||
+        data === null ||
+        !("version" in data) ||
+        !("grants" in data)
+      ) {
+        this.corrupt = true;
+        throw new Error(
+          "CES grants file is malformed: missing version or grants field",
+        );
+      }
+
+      const file = data as GrantsFile;
+
+      if (file.version !== GRANTS_FILE_VERSION) {
+        this.corrupt = true;
+        throw new Error(
+          `CES grants file has unsupported version ${file.version} (expected ${GRANTS_FILE_VERSION})`,
+        );
+      }
+
+      if (!Array.isArray(file.grants)) {
+        this.corrupt = true;
+        throw new Error("CES grants file is malformed: grants is not an array");
+      }
+
+      this.cache = file.grants;
+      return [...file.grants];
+    } catch (err) {
+      if (this.corrupt) throw err;
+      // Any other read/parse error → fail closed
+      this.corrupt = true;
+      throw new Error(
+        `CES persistent grant store failed to read ${this.filePath}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  private writeToDisk(grants: PersistentGrant[]): void {
+    const dir = dirname(this.filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    const data: GrantsFile = {
+      version: GRANTS_FILE_VERSION,
+      grants,
+    };
+
+    const tmpPath = join(dir, `.tmp-${randomUUID()}`);
+    writeFileSync(tmpPath, JSON.stringify(data, null, 2), {
+      mode: 0o600,
+    });
+    renameSync(tmpPath, this.filePath);
+    // Enforce owner-only permissions even if the file already existed
+    // with wider permissions.
+    chmodSync(this.filePath, 0o600);
+
+    this.cache = grants;
+  }
+}

package/src/grants/rpc-handlers.ts

@@ -0,0 +1,269 @@
+/**
+ * CES RPC handlers for grant and audit management.
+ *
+ * Implements the server-side handlers for:
+ * - `record_grant` — Record a grant decision after guardian approval.
+ * - `list_grants` — List grants filtered by session, handle, or status.
+ * - `revoke_grant` — Revoke a specific grant by its stable ID.
+ * - `list_audit_records` — List audit records with filtering and pagination.
+ *
+ * All handlers operate strictly on CES-owned state and never expose raw
+ * secret material, raw tokens, or raw headers/bodies. Grant records returned
+ * to the assistant contain only metadata (handle, proposal type, status,
+ * timestamps).
+ */
+
+import type {
+  ListGrants,
+  ListGrantsResponse,
+  RecordGrant,
+  RecordGrantResponse,
+  RevokeGrant,
+  RevokeGrantResponse,
+  ListAuditRecords,
+  ListAuditRecordsResponse,
+  PersistentGrantRecord,
+} from "@vellumai/ces-contracts";
+
+import type { PersistentGrantStore, PersistentGrant } from "./persistent-store.js";
+import type { TemporaryGrantStore } from "./temporary-store.js";
+import type { AuditStore } from "../audit/store.js";
+import type { RpcMethodHandler } from "../server.js";
+
+// ---------------------------------------------------------------------------
+// Grant → PersistentGrantRecord projection
+// ---------------------------------------------------------------------------
+
+/**
+ * Project a CES internal PersistentGrant into the wire-format
+ * PersistentGrantRecord. The internal store uses a simpler schema;
+ * the wire format includes additional status/lifecycle fields.
+ *
+ * Since the persistent store does not track lifecycle states (expiry,
+ * revocation, consumption), all persisted grants are considered "active".
+ */
+function projectGrant(
+  grant: PersistentGrant,
+  sessionId: string,
+): PersistentGrantRecord {
+  return {
+    grantId: grant.id,
+    sessionId,
+    credentialHandle: grant.scope,
+    proposalType: grant.tool as "http" | "command",
+    proposalHash: grant.id,
+    allowedPurposes: [grant.pattern],
+    status: "active",
+    grantedBy: "user",
+    createdAt: new Date(grant.createdAt).toISOString(),
+    expiresAt: null,
+    consumedAt: null,
+    revokedAt: null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// record_grant handler
+// ---------------------------------------------------------------------------
+
+export interface RecordGrantHandlerDeps {
+  persistentGrantStore: PersistentGrantStore;
+  temporaryGrantStore: TemporaryGrantStore;
+}
+
+/**
+ * Create an RPC handler for the `record_grant` method.
+ *
+ * Receives a `TemporaryGrantDecision` from the approval bridge and persists
+ * it as a `PersistentGrant` (for approved decisions) or returns a success
+ * acknowledgement (for denied decisions). The handler also adds an
+ * in-memory temporary grant so the caller can immediately retry the
+ * original tool invocation.
+ *
+ * For approved decisions with a TTL of "PT10M", the grant is stored as
+ * a timed temporary grant. Otherwise it is persisted as a permanent grant.
+ */
+export function createRecordGrantHandler(
+  deps: RecordGrantHandlerDeps,
+): RpcMethodHandler<RecordGrant, RecordGrantResponse> {
+  return (request) => {
+    const { decision, sessionId } = request;
+
+    // Denied decisions are acknowledged but produce no grant record.
+    if (decision.decision === "denied") {
+      return { success: true };
+    }
+
+    // Build a PersistentGrant from the decision.
+    const proposal = decision.proposal;
+    const now = Date.now();
+    const grantId = decision.proposalHash;
+
+    const persistentGrant: PersistentGrant = {
+      id: grantId,
+      tool: proposal.type,
+      pattern:
+        proposal.type === "http"
+          ? `${proposal.method} ${proposal.url}`
+          : proposal.command,
+      scope: proposal.credentialHandle,
+      createdAt: now,
+    };
+
+    // Persist the grant.
+    deps.persistentGrantStore.add(persistentGrant);
+
+    // Also record a temporary grant so the caller can use it immediately.
+    // Map TTL to the appropriate temporary grant kind.
+    if (decision.ttl === "PT10M") {
+      deps.temporaryGrantStore.add("allow_10m", decision.proposalHash);
+    } else {
+      deps.temporaryGrantStore.add("allow_once", decision.proposalHash);
+    }
+
+    // Compute expiry from TTL if present.
+    let expiresAt: string | null = null;
+    if (decision.ttl === "PT10M") {
+      expiresAt = new Date(now + 10 * 60 * 1000).toISOString();
+    }
+
+    const grantRecord: PersistentGrantRecord = {
+      grantId,
+      sessionId,
+      credentialHandle: proposal.credentialHandle,
+      proposalType: proposal.type,
+      proposalHash: decision.proposalHash,
+      allowedPurposes:
+        proposal.type === "http"
+          ? proposal.allowedUrlPatterns ?? [`${proposal.method} ${proposal.url}`]
+          : proposal.allowedCommandPatterns ?? [proposal.command],
+      status: "active",
+      grantedBy: decision.decidedBy,
+      createdAt: new Date(now).toISOString(),
+      expiresAt,
+      consumedAt: null,
+      revokedAt: null,
+    };
+
+    return {
+      success: true,
+      grant: grantRecord,
+    };
+  };
+}
+
+// ---------------------------------------------------------------------------
+// list_grants handler
+// ---------------------------------------------------------------------------
+
+export interface ListGrantsHandlerDeps {
+  persistentGrantStore: PersistentGrantStore;
+  /** Default session ID for grants that don't track session. */
+  sessionId: string;
+}
+
+/**
+ * Create an RPC handler for the `list_grants` method.
+ *
+ * Lists all persistent grants, optionally filtered by session ID,
+ * credential handle, or status. Returns wire-format PersistentGrantRecords
+ * that never include raw secret material.
+ */
+export function createListGrantsHandler(
+  deps: ListGrantsHandlerDeps,
+): RpcMethodHandler<ListGrants, ListGrantsResponse> {
+  return (request) => {
+    const allGrants = deps.persistentGrantStore.getAll();
+    const projected = allGrants.map((g) => projectGrant(g, deps.sessionId));
+
+    let filtered = projected;
+
+    if (request.sessionId) {
+      filtered = filtered.filter((g) => g.sessionId === request.sessionId);
+    }
+
+    if (request.credentialHandle) {
+      filtered = filtered.filter(
+        (g) => g.credentialHandle === request.credentialHandle,
+      );
+    }
+
+    if (request.status) {
+      filtered = filtered.filter((g) => g.status === request.status);
+    }
+
+    return { grants: filtered };
+  };
+}
+
+// ---------------------------------------------------------------------------
+// revoke_grant handler
+// ---------------------------------------------------------------------------
+
+export interface RevokeGrantHandlerDeps {
+  persistentGrantStore: PersistentGrantStore;
+}
+
+/**
+ * Create an RPC handler for the `revoke_grant` method.
+ *
+ * Removes a grant from the persistent store by its stable ID. Returns
+ * success/failure. The reason field is logged but not persisted (the
+ * persistent store does not track revocation metadata).
+ */
+export function createRevokeGrantHandler(
+  deps: RevokeGrantHandlerDeps,
+): RpcMethodHandler<RevokeGrant, RevokeGrantResponse> {
+  return (request) => {
+    const removed = deps.persistentGrantStore.remove(request.grantId);
+
+    if (!removed) {
+      return {
+        success: false,
+        error: {
+          code: "GRANT_NOT_FOUND",
+          message: `No grant found with ID "${request.grantId}"`,
+        },
+      };
+    }
+
+    return { success: true };
+  };
+}
+
+// ---------------------------------------------------------------------------
+// list_audit_records handler
+// ---------------------------------------------------------------------------
+
+export interface ListAuditRecordsHandlerDeps {
+  auditStore: AuditStore;
+}
+
+/**
+ * Create an RPC handler for the `list_audit_records` method.
+ *
+ * Lists audit records with optional filtering by session, credential
+ * handle, or grant ID. Supports limit and cursor-based pagination.
+ *
+ * Audit records never contain raw secrets, raw tokens, or raw
+ * headers/bodies — they are token-free summaries generated at
+ * execution time.
+ */
+export function createListAuditRecordsHandler(
+  deps: ListAuditRecordsHandlerDeps,
+): RpcMethodHandler<ListAuditRecords, ListAuditRecordsResponse> {
+  return (request) => {
+    const result = deps.auditStore.list({
+      sessionId: request.sessionId,
+      credentialHandle: request.credentialHandle,
+      grantId: request.grantId,
+      limit: request.limit,
+      cursor: request.cursor,
+    });
+
+    return {
+      records: result.records,
+      nextCursor: result.nextCursor,
+    };
+  };
+}