@vellumai/credential-executor 0.4.55 → 0.4.56

package/node_modules/@vellumai/ces-contracts/src/error.ts

@@ -0,0 +1,25 @@
+/**
+ * RPC error schema — extracted to its own module to avoid circular
+ * dependencies between index.ts and rpc.ts.
+ */
+
+import { z } from "zod/v4";
+
+export const RpcErrorSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+  /** Optional structured details for debugging. */
+  details: z.record(z.string(), z.unknown()).optional(),
+});
+export type RpcError = z.infer<typeof RpcErrorSchema>;
+
+/**
+ * Error returned when a local_static credential handle is used in managed
+ * mode. The encrypted key store uses PBKDF2 key derivation from user
+ * identity (username, homedir), but the assistant container runs as root
+ * while CES runs as ces — different derived keys make decryption silently
+ * fail. Managed deployments must use platform_oauth handles exclusively.
+ */
+export const MANAGED_LOCAL_STATIC_REJECTION_ERROR =
+  "local_static credential handles are not supported in managed mode. " +
+  "Use platform_oauth handles for managed deployments.";

package/node_modules/@vellumai/ces-contracts/src/grants.ts

@@ -0,0 +1,184 @@
+/**
+ * CES grant proposal, grant record, and audit record schemas.
+ *
+ * These schemas define the wire format for:
+ * - HTTP grant proposals (requesting permission to make an authenticated HTTP call)
+ * - Command grant proposals (requesting permission to run an authenticated command)
+ * - Temporary grant decisions (approval/denial from a guardian)
+ * - Persistent grant records (stored by CES after approval)
+ * - Audit record summaries (materialization events)
+ */
+
+import { z } from "zod/v4";
+
+// ---------------------------------------------------------------------------
+// Grant proposal types
+// ---------------------------------------------------------------------------
+
+/**
+ * Proposal to make an authenticated HTTP request using a credential.
+ */
+export const HttpGrantProposalSchema = z.object({
+  type: z.literal("http"),
+  /** CES credential handle identifying which credential to use. */
+  credentialHandle: z.string(),
+  /** HTTP method (e.g. "GET", "POST"). */
+  method: z.string(),
+  /** Target URL. */
+  url: z.string(),
+  /** Human-readable description of why this request is needed. */
+  purpose: z.string(),
+  /** Optional constrained set of URL patterns this grant covers. */
+  allowedUrlPatterns: z.array(z.string()).optional(),
+});
+export type HttpGrantProposal = z.infer<typeof HttpGrantProposalSchema>;
+
+/**
+ * Proposal to run an authenticated command using credential environment variables.
+ */
+export const CommandGrantProposalSchema = z.object({
+  type: z.literal("command"),
+  /** CES credential handle identifying which credential to use. */
+  credentialHandle: z.string(),
+  /** The command to execute (without credential values — CES injects those). */
+  command: z.string(),
+  /** Human-readable description of why this command is needed. */
+  purpose: z.string(),
+  /** Optional constrained set of command patterns this grant covers. */
+  allowedCommandPatterns: z.array(z.string()).optional(),
+});
+export type CommandGrantProposal = z.infer<typeof CommandGrantProposalSchema>;
+
+/**
+ * Union of all grant proposal types.
+ */
+export const GrantProposalSchema = z.discriminatedUnion("type", [
+  HttpGrantProposalSchema,
+  CommandGrantProposalSchema,
+]);
+export type GrantProposal = z.infer<typeof GrantProposalSchema>;
+
+// ---------------------------------------------------------------------------
+// Grant decisions (temporary — before persistence)
+// ---------------------------------------------------------------------------
+
+export const GrantDecision = {
+  Approved: "approved",
+  Denied: "denied",
+} as const;
+
+export type GrantDecision = (typeof GrantDecision)[keyof typeof GrantDecision];
+
+/**
+ * A temporary grant decision from a guardian, before CES persists it.
+ */
+export const TemporaryGrantDecisionSchema = z.object({
+  /** The proposal this decision applies to. */
+  proposal: GrantProposalSchema,
+  /** Deterministic hash of the proposal (see rendering.ts). */
+  proposalHash: z.string(),
+  /** The guardian's decision. */
+  decision: z.enum(["approved", "denied"]),
+  /** Who made the decision (guardian identifier). */
+  decidedBy: z.string(),
+  /** ISO-8601 timestamp of the decision. */
+  decidedAt: z.string(),
+  /** Optional human-readable reason for the decision. */
+  reason: z.string().optional(),
+  /** How long the grant should remain valid (ISO-8601 duration, e.g. "PT1H"). */
+  ttl: z.string().optional(),
+  /**
+   * The type of grant to create. Determines persistence behaviour:
+   * - `allow_once`: Temporary single-use grant (consumed after one use)
+   * - `allow_10m`: Temporary timed grant (10-minute TTL)
+   * - `allow_conversation`: Temporary conversation-scoped grant (lives for conversation)
+   * - `always_allow`: Persistent grant (survives restart)
+   *
+   * When omitted, defaults to `always_allow` for backwards compatibility.
+   */
+  grantType: z.enum(["allow_once", "allow_10m", "allow_conversation", "always_allow"]).optional(),
+});
+export type TemporaryGrantDecision = z.infer<
+  typeof TemporaryGrantDecisionSchema
+>;
+
+// ---------------------------------------------------------------------------
+// Persistent grant records (CES-owned)
+// ---------------------------------------------------------------------------
+
+export const GrantStatus = {
+  Active: "active",
+  Expired: "expired",
+  Revoked: "revoked",
+  Consumed: "consumed",
+} as const;
+
+export type GrantStatus = (typeof GrantStatus)[keyof typeof GrantStatus];
+
+/**
+ * A persistent grant record stored by CES.
+ *
+ * Grants authorize a specific agent connection to use a credential for a
+ * constrained purpose. They are never sent to the assistant with secret
+ * values — only metadata.
+ */
+export const PersistentGrantRecordSchema = z.object({
+  /** Unique grant identifier. */
+  grantId: z.string(),
+  /** The CES connection that created this grant. */
+  sessionId: z.string(),
+  /** The credential handle this grant authorizes. */
+  credentialHandle: z.string(),
+  /** The proposal type (http or command). */
+  proposalType: z.enum(["http", "command"]),
+  /** Deterministic hash of the original proposal. */
+  proposalHash: z.string(),
+  /** Constrained purposes — URL patterns for HTTP, command patterns for commands. */
+  allowedPurposes: z.array(z.string()),
+  /** Current grant status. */
+  status: z.enum(["active", "expired", "revoked", "consumed"]),
+  /** Who approved the grant. */
+  grantedBy: z.string(),
+  /** ISO-8601 timestamp when the grant was created. */
+  createdAt: z.string(),
+  /** ISO-8601 timestamp when the grant expires (null if no expiry). */
+  expiresAt: z.string().nullable(),
+  /** ISO-8601 timestamp when the grant was consumed (null if unconsumed). */
+  consumedAt: z.string().nullable(),
+  /** ISO-8601 timestamp when the grant was revoked (null if active). */
+  revokedAt: z.string().nullable(),
+});
+export type PersistentGrantRecord = z.infer<typeof PersistentGrantRecordSchema>;
+
+// ---------------------------------------------------------------------------
+// Audit record summaries
+// ---------------------------------------------------------------------------
+
+/**
+ * Summary of a credential materialization event, as exposed by CES
+ * for audit inspection.
+ *
+ * Audit records never contain secret values — only metadata about what
+ * was accessed, when, by whom, and whether it succeeded.
+ */
+export const AuditRecordSummarySchema = z.object({
+  /** Unique audit record identifier. */
+  auditId: z.string(),
+  /** The grant that authorized this materialization. */
+  grantId: z.string(),
+  /** The credential handle that was materialized. */
+  credentialHandle: z.string(),
+  /** The tool that triggered materialization. */
+  toolName: z.string(),
+  /** Target of the operation (URL for HTTP, command summary for commands). */
+  target: z.string(),
+  /** The CES connection that triggered materialization. */
+  sessionId: z.string(),
+  /** Whether the execution succeeded. */
+  success: z.boolean(),
+  /** Error message if execution failed (no secrets). */
+  errorMessage: z.string().optional(),
+  /** ISO-8601 timestamp of the materialization event. */
+  timestamp: z.string(),
+});
+export type AuditRecordSummary = z.infer<typeof AuditRecordSummarySchema>;

package/node_modules/@vellumai/ces-contracts/src/handles.ts

@@ -0,0 +1,213 @@
+/**
+ * CES credential handle formats and parser helpers.
+ *
+ * A "handle" is an opaque string that the assistant passes to CES to identify
+ * which credential context should be used for a given execution. Handles never
+ * contain secret material — they are references that CES resolves internally.
+ *
+ * v1 handle formats:
+ *
+ * 1. **Local static** — references a credential stored in the local secure-key
+ *    backend. Format: `local_static:<service>/<field>` (matches the
+ *    `credential/{service}/{field}` key pattern from credential-storage).
+ *
+ * 2. **Local OAuth** — references a locally persisted OAuth connection.
+ *    Format: `local_oauth:<providerKey>/<connectionId>` where providerKey
+ *    uses the existing `integration:*` keys (e.g. `integration:google`).
+ *
+ * 3. **Managed OAuth** — references an OAuth connection managed by the
+ *    platform. Format: `platform_oauth:<connectionId>` where connectionId
+ *    is the platform-assigned connection identifier.
+ */
+
+import { z } from "zod/v4";
+
+// ---------------------------------------------------------------------------
+// Handle type discriminator
+// ---------------------------------------------------------------------------
+
+export const HandleType = {
+  LocalStatic: "local_static",
+  LocalOAuth: "local_oauth",
+  PlatformOAuth: "platform_oauth",
+} as const;
+
+export type HandleType = (typeof HandleType)[keyof typeof HandleType];
+
+// ---------------------------------------------------------------------------
+// Parsed handle shapes
+// ---------------------------------------------------------------------------
+
+export interface LocalStaticHandle {
+  type: typeof HandleType.LocalStatic;
+  /** Service name (e.g. "github", "fal"). */
+  service: string;
+  /** Field name within the service (e.g. "api_key", "password"). */
+  field: string;
+  /** The raw handle string. */
+  raw: string;
+}
+
+export interface LocalOAuthHandle {
+  type: typeof HandleType.LocalOAuth;
+  /** Provider key (e.g. "integration:google", "integration:slack"). */
+  providerKey: string;
+  /** Connection identifier. */
+  connectionId: string;
+  /** The raw handle string. */
+  raw: string;
+}
+
+export interface PlatformOAuthHandle {
+  type: typeof HandleType.PlatformOAuth;
+  /** Platform-assigned connection identifier. */
+  connectionId: string;
+  /** The raw handle string. */
+  raw: string;
+}
+
+export type ParsedHandle =
+  | LocalStaticHandle
+  | LocalOAuthHandle
+  | PlatformOAuthHandle;
+
+// ---------------------------------------------------------------------------
+// Handle construction helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a local static credential handle from service and field.
+ *
+ * Accepts the same service/field values used in `credentialKey()` from
+ * `@vellumai/credential-storage`.
+ */
+export function localStaticHandle(service: string, field: string): string {
+  return `${HandleType.LocalStatic}:${service}/${field}`;
+}
+
+/**
+ * Build a local OAuth credential handle from a provider key and connection ID.
+ */
+export function localOAuthHandle(
+  providerKey: string,
+  connectionId: string,
+): string {
+  return `${HandleType.LocalOAuth}:${providerKey}/${connectionId}`;
+}
+
+/**
+ * Build a managed (platform) OAuth credential handle from a connection ID.
+ */
+export function platformOAuthHandle(connectionId: string): string {
+  return `${HandleType.PlatformOAuth}:${connectionId}`;
+}
+
+// ---------------------------------------------------------------------------
+// Handle parsing
+// ---------------------------------------------------------------------------
+
+export type ParseHandleResult =
+  | { ok: true; handle: ParsedHandle }
+  | { ok: false; error: string };
+
+/**
+ * Parse a raw handle string into a structured `ParsedHandle`.
+ *
+ * Returns a discriminated result so callers can inspect parse errors
+ * without catching exceptions.
+ */
+export function parseHandle(raw: string): ParseHandleResult {
+  const colonIdx = raw.indexOf(":");
+  if (colonIdx === -1) {
+    return { ok: false, error: `Invalid handle format: missing type prefix in "${raw}"` };
+  }
+
+  const prefix = raw.slice(0, colonIdx);
+  const rest = raw.slice(colonIdx + 1);
+
+  switch (prefix) {
+    case HandleType.LocalStatic: {
+      const slashIdx = rest.indexOf("/");
+      if (slashIdx === -1 || slashIdx === 0 || slashIdx === rest.length - 1) {
+        return {
+          ok: false,
+          error: `Invalid local_static handle: expected "local_static:<service>/<field>", got "${raw}"`,
+        };
+      }
+      return {
+        ok: true,
+        handle: {
+          type: HandleType.LocalStatic,
+          service: rest.slice(0, slashIdx),
+          field: rest.slice(slashIdx + 1),
+          raw,
+        },
+      };
+    }
+
+    case HandleType.LocalOAuth: {
+      // providerKey may itself contain a colon (e.g. "integration:google"),
+      // so we split on the *last* "/" to separate providerKey from connectionId.
+      const lastSlashIdx = rest.lastIndexOf("/");
+      if (
+        lastSlashIdx === -1 ||
+        lastSlashIdx === 0 ||
+        lastSlashIdx === rest.length - 1
+      ) {
+        return {
+          ok: false,
+          error: `Invalid local_oauth handle: expected "local_oauth:<providerKey>/<connectionId>", got "${raw}"`,
+        };
+      }
+      return {
+        ok: true,
+        handle: {
+          type: HandleType.LocalOAuth,
+          providerKey: rest.slice(0, lastSlashIdx),
+          connectionId: rest.slice(lastSlashIdx + 1),
+          raw,
+        },
+      };
+    }
+
+    case HandleType.PlatformOAuth: {
+      if (!rest || rest.length === 0) {
+        return {
+          ok: false,
+          error: `Invalid platform_oauth handle: missing connectionId in "${raw}"`,
+        };
+      }
+      return {
+        ok: true,
+        handle: {
+          type: HandleType.PlatformOAuth,
+          connectionId: rest,
+          raw,
+        },
+      };
+    }
+
+    default:
+      return {
+        ok: false,
+        error: `Unknown handle type prefix "${prefix}" in "${raw}"`,
+      };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Zod schema for wire validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Zod schema that validates a string as a well-formed CES credential handle.
+ * Useful in RPC schemas where the handle travels on the wire.
+ */
+export const CredentialHandleSchema = z
+  .string()
+  .check(
+    z.refine((val: string) => {
+      const result = parseHandle(val);
+      return result.ok;
+    }, "Must be a valid CES credential handle (local_static:*, local_oauth:*, or platform_oauth:*)"),
+  );

package/node_modules/@vellumai/ces-contracts/src/index.ts

@@ -0,0 +1,147 @@
+/**
+ * @vellumai/ces-contracts
+ *
+ * Neutral wire-protocol contracts for communication between the assistant
+ * daemon and the Credential Execution Service (CES). This package is
+ * intentionally free of imports from `assistant/` or any CES implementation
+ * module so that both sides can depend on it without circular references.
+ */
+
+import { z } from "zod/v4";
+import { RpcErrorSchema } from "./error.js";
+
+// ---------------------------------------------------------------------------
+// Transport handshake
+// ---------------------------------------------------------------------------
+
+/** Semantic version of the CES wire protocol. */
+export const CES_PROTOCOL_VERSION = "0.1.0" as const;
+
+/**
+ * Sent by the initiator (assistant) when opening a CES transport channel.
+ * The responder (CES) replies with a HandshakeAck.
+ */
+export const HandshakeRequestSchema = z.object({
+  type: z.literal("handshake_request"),
+  protocolVersion: z.string(),
+  /** Opaque session identifier chosen by the initiator. */
+  sessionId: z.string(),
+  /**
+   * Optional assistant API key passed from the assistant runtime.
+   * In managed (sidecar) mode the API key is provisioned after hatch,
+   * so the assistant forwards it during the bootstrap handshake so CES
+   * can use it for platform credential materialisation.
+   */
+  assistantApiKey: z.string().optional(),
+});
+export type HandshakeRequest = z.infer<typeof HandshakeRequestSchema>;
+
+export const HandshakeAckSchema = z.object({
+  type: z.literal("handshake_ack"),
+  protocolVersion: z.string(),
+  sessionId: z.string(),
+  /** Whether the responder accepted the requested protocol version. */
+  accepted: z.boolean(),
+  /** Human-readable reason when `accepted` is false. */
+  reason: z.string().optional(),
+});
+export type HandshakeAck = z.infer<typeof HandshakeAckSchema>;
+
+// ---------------------------------------------------------------------------
+// RPC envelope
+// ---------------------------------------------------------------------------
+
+/**
+ * Every message on the wire is wrapped in an RpcEnvelope so both sides can
+ * demux by `method`, correlate responses via `id`, and distinguish requests
+ * from responses via `kind`.
+ */
+export const RpcEnvelopeSchema = z.object({
+  /** Monotonically increasing per-session request id. */
+  id: z.string(),
+  kind: z.enum(["request", "response"]),
+  method: z.string(),
+  /** JSON-serialisable payload; schema depends on `method`. */
+  payload: z.unknown(),
+  /** ISO-8601 timestamp of when the message was created. */
+  timestamp: z.string(),
+});
+export type RpcEnvelope = z.infer<typeof RpcEnvelopeSchema>;
+
+// ---------------------------------------------------------------------------
+// RPC error (defined in error.ts to avoid circular deps with rpc.ts)
+// ---------------------------------------------------------------------------
+
+export {
+  RpcErrorSchema,
+  type RpcError,
+  MANAGED_LOCAL_STATIC_REJECTION_ERROR,
+} from "./error.js";
+
+// ---------------------------------------------------------------------------
+// Tool request / response base shapes
+// ---------------------------------------------------------------------------
+
+/**
+ * Base shape for a tool execution request sent from the assistant to CES.
+ * Concrete tool requests extend this with tool-specific `params`.
+ */
+export const ToolRequestBaseSchema = z.object({
+  /** The tool identifier as known to both sides. */
+  toolName: z.string(),
+  /** Opaque handle referencing the credential context for this execution. */
+  credentialHandle: z.string(),
+  /** Tool-specific parameters; schema varies per tool. */
+  params: z.record(z.string(), z.unknown()),
+});
+export type ToolRequestBase = z.infer<typeof ToolRequestBaseSchema>;
+
+/**
+ * Base shape for a tool execution response sent from CES back to the
+ * assistant. Modeled as a discriminated union on `success` so malformed
+ * payloads (e.g. `success: false` without `error`, or `success: true`
+ * with `error`) are rejected at parse time.
+ */
+const ToolResponseSuccessSchema = z
+  .object({
+    success: z.literal(true),
+    /** Tool output. */
+    result: z.unknown().optional(),
+  })
+  .strict();
+
+const ToolResponseErrorSchema = z.object({
+  success: z.literal(false),
+  /** Structured error describing the failure. */
+  error: RpcErrorSchema,
+});
+
+export const ToolResponseBaseSchema = z.discriminatedUnion("success", [
+  ToolResponseSuccessSchema,
+  ToolResponseErrorSchema,
+]);
+export type ToolResponseBase = z.infer<typeof ToolResponseBaseSchema>;
+
+// ---------------------------------------------------------------------------
+// Aggregate transport message union
+// ---------------------------------------------------------------------------
+
+/**
+ * Union of all top-level message types that can appear on the transport.
+ * Useful for a single discriminated-union parse at the transport layer.
+ */
+export const TransportMessageSchema = z.discriminatedUnion("type", [
+  HandshakeRequestSchema,
+  HandshakeAckSchema,
+  RpcEnvelopeSchema.extend({ type: z.literal("rpc") }),
+]);
+export type TransportMessage = z.infer<typeof TransportMessageSchema>;
+
+// ---------------------------------------------------------------------------
+// Re-exports from sub-modules
+// ---------------------------------------------------------------------------
+
+export * from "./handles.js";
+export * from "./grants.js";
+export * from "./rpc.js";
+export * from "./rendering.js";