@vellumai/credential-executor 0.10.7-dev.202607102035.64f07ea → 0.10.7-staging.1

package/node_modules/@vellumai/service-contracts/src/credential-rpc.ts

@@ -2,13 +2,13 @@
  * @vellumai/service-contracts/credential-rpc
  *
  * Domain entrypoint for the CES (Credential Execution Service) transport and
- * RPC surface. Re-exports the transport/RPC/handles/error contracts without
- * the trust-rule helpers.
+ * RPC surface. Re-exports the transport/RPC/handles/grants/rendering/error
+ * contracts without the trust-rule helpers.
  *
  * Prefer this subpath over the root `.` import when you only need the
  * credential RPC surface:
  *
- *   import { CesRpcMethod, GetCredentialSchema } from "@vellumai/service-contracts/credential-rpc";
+ *   import { CesRpcMethod, MakeAuthenticatedRequestSchema } from "@vellumai/service-contracts/credential-rpc";
  *
  * For trust-rule types use the dedicated subpath:
  *
@@ -18,4 +18,6 @@
 export * from "./transport.js";
 export * from "./error.js";
 export * from "./handles.js";
+export * from "./grants.js";
+export * from "./rendering.js";
 export * from "./rpc.js";

package/node_modules/@vellumai/service-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";
+
+// ---------------------------------------------------------------------------
+// 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/service-contracts/src/index.ts

@@ -4,13 +4,13 @@
  * This is a compatibility aggregate that re-exports everything from all
  * submodules. Prefer the explicit domain subpaths for new code:
  *
- *   - `@vellumai/service-contracts/credential-rpc`  — transport, RPC, handles, error
+ *   - `@vellumai/service-contracts/credential-rpc`  — transport, RPC, handles, grants, rendering, error
  *   - `@vellumai/service-contracts/trust-rules`     — trust-rule types and parsing helpers
  *   - `@vellumai/service-contracts/twilio-ingress`  — shared Twilio ingress config constants
  *   - `@vellumai/service-contracts/ingress`         — shared public ingress URL helpers
  *
  * Fine-grained subpaths are also available for low-friction migration:
- *   `./rpc`, `./handles`, `./error`, `./trust-rules`, `./ingress`, `./twilio-ingress`
+ *   `./rpc`, `./handles`, `./grants`, `./rendering`, `./error`, `./trust-rules`, `./ingress`, `./twilio-ingress`
  *
  * Neutral wire-protocol contracts for communication between the assistant
  * daemon and the Credential Execution Service (CES). This package is
@@ -23,7 +23,9 @@ export * from "./client-metadata.js";
 export * from "./transport.js";
 export * from "./error.js";
 export * from "./handles.js";
+export * from "./grants.js";
 export * from "./rpc.js";
+export * from "./rendering.js";
 export * from "./trust-rules.js";
 export * from "./ingress.js";
 export * from "./twilio-ingress.js";

package/node_modules/@vellumai/service-contracts/src/rendering.ts

@@ -0,0 +1,135 @@
+/**
+ * Canonical proposal rendering and deterministic hashing.
+ *
+ * Both the assistant and CES must produce identical human-readable text and
+ * proposal hashes for the same proposal object. This module provides the
+ * shared implementations so neither side has to duplicate the logic.
+ *
+ * Hashing algorithm:
+ *   1. Recursively sort object keys (depth-first).
+ *   2. Serialize to a canonical JSON string with no whitespace.
+ *   3. SHA-256 hash the UTF-8 bytes and return a lowercase hex digest.
+ *
+ * This matches the algorithm used by `tool-approval-digest.ts` in the
+ * assistant, ensuring consistency across the approval pipeline.
+ */
+
+import { createHash } from "node:crypto";
+import type { GrantProposal } from "./grants.js";
+
+// ---------------------------------------------------------------------------
+// Canonical JSON serialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively sort all object keys and return a deterministic JSON string.
+ *
+ * Handles nested objects, arrays (element order preserved), and primitive
+ * values. `undefined` values inside objects are omitted (matching
+ * JSON.stringify semantics). `null` is preserved.
+ */
+export function canonicalJsonSerialize(value: unknown): string {
+  return JSON.stringify(sortKeysDeep(value));
+}
+
+function sortKeysDeep(value: unknown): unknown {
+  if (value == null) return value;
+
+  if (Array.isArray(value)) {
+    return value.map(sortKeysDeep);
+  }
+
+  if (typeof value === "object") {
+    const sorted: Record<string, unknown> = {};
+    const keys = Object.keys(value as Record<string, unknown>).sort();
+    for (const key of keys) {
+      sorted[key] = sortKeysDeep((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+
+  // Primitive — number, string, boolean
+  return value;
+}
+
+// ---------------------------------------------------------------------------
+// Proposal hashing
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute a deterministic SHA-256 hex digest for a grant proposal.
+ *
+ * Two proposals with the same canonical content (regardless of key ordering)
+ * will always produce the same hash. This hash is used to match grant
+ * decisions to proposals in the approval pipeline.
+ */
+export function hashProposal(proposal: GrantProposal): string {
+  const canonical = canonicalJsonSerialize(proposal);
+  return createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+
+// ---------------------------------------------------------------------------
+// Human-readable proposal rendering
+// ---------------------------------------------------------------------------
+
+/**
+ * Render a grant proposal as a human-readable text block suitable for
+ * display in approval UIs and guardian notifications.
+ *
+ * The rendering is deterministic for the same proposal, so both assistant
+ * and CES produce identical text.
+ */
+export function renderProposal(proposal: GrantProposal): string {
+  switch (proposal.type) {
+    case "http":
+      return renderHttpProposal(proposal);
+    case "command":
+      return renderCommandProposal(proposal);
+    default: {
+      const _exhaustive: never = proposal;
+      throw new Error(`Unknown proposal type: ${(_exhaustive as GrantProposal).type}`);
+    }
+  }
+}
+
+function renderHttpProposal(proposal: GrantProposal & { type: "http" }): string {
+  const lines: string[] = [
+    `Authenticated HTTP Request`,
+    `  Method: ${proposal.method}`,
+    `  URL: ${proposal.url}`,
+    `  Credential: ${proposal.credentialHandle}`,
+    `  Purpose: ${proposal.purpose}`,
+  ];
+
+  if (proposal.allowedUrlPatterns && proposal.allowedUrlPatterns.length > 0) {
+    lines.push(`  Allowed URL patterns:`);
+    for (const pattern of proposal.allowedUrlPatterns) {
+      lines.push(`    - ${pattern}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function renderCommandProposal(
+  proposal: GrantProposal & { type: "command" },
+): string {
+  const lines: string[] = [
+    `Authenticated Command Execution`,
+    `  Command: ${proposal.command}`,
+    `  Credential: ${proposal.credentialHandle}`,
+    `  Purpose: ${proposal.purpose}`,
+  ];
+
+  if (
+    proposal.allowedCommandPatterns &&
+    proposal.allowedCommandPatterns.length > 0
+  ) {
+    lines.push(`  Allowed command patterns:`);
+    for (const pattern of proposal.allowedCommandPatterns) {
+      lines.push(`    - ${pattern}`);
+    }
+  }
+
+  return lines.join("\n");
+}