@vellumai/credential-executor 0.10.7 → 0.10.8-dev.202607102228.5945895

package/src/materializers/managed-platform.ts

@@ -1,295 +0,0 @@
-/**
- * Managed platform OAuth materializer.
- *
- * Materializes a `platform_oauth` handle into a short-lived access token
- * by calling the platform's CES token-materialization endpoint. The
- * materialized token is returned to the caller for immediate use (e.g.
- * injection into an HTTP request or command environment) but is **never**
- * persisted to any local storage — it exists only in memory for the
- * duration of the execution.
- *
- * Security invariants:
- * - Materialized tokens are never written to disk.
- * - Materialized tokens are never logged (not even partially).
- * - Platform errors are surfaced as structured errors without leaking secrets.
- * - If the platform cannot be reached, materialization fails closed.
- *
- * The materializer expects a resolved `ManagedSubject` from
- * `subjects/managed.ts`. It does not perform handle parsing or catalog
- * lookup — that is the resolver's responsibility.
- */
-
-import type { ManagedSubject } from "../subjects/managed.js";
-
-// ---------------------------------------------------------------------------
-// Materialization result
-// ---------------------------------------------------------------------------
-
-/**
- * Successful materialization result.
- *
- * The `accessToken` field contains the short-lived token obtained from
- * the platform. Callers MUST NOT persist this value — it should be used
- * immediately for request injection and then discarded.
- */
-export interface MaterializedToken {
-  /** The short-lived access token. */
-  accessToken: string;
-  /** Token type (typically "Bearer"). */
-  tokenType: string;
-  /** Epoch ms when the token expires (null if the platform didn't report expiry). */
-  expiresAt: number | null;
-  /** Provider key (mirrored from the subject for convenience). */
-  provider: string;
-  /** Connection ID (mirrored from the subject for convenience). */
-  connectionId: string;
-}
-
-export type MaterializeResult =
-  | { ok: true; token: MaterializedToken }
-  | { ok: false; error: MaterializationError };
-
-// ---------------------------------------------------------------------------
-// Materialization errors
-// ---------------------------------------------------------------------------
-
-export class MaterializationError extends Error {
-  readonly code: string;
-
-  constructor(code: string, message: string) {
-    super(message);
-    this.name = "MaterializationError";
-    this.code = code;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Platform token response shape
-// ---------------------------------------------------------------------------
-
-/**
- * Shape of the platform's CES token-materialization response.
- *
- * Field names match the platform's ManagedTokenMaterializeResponseSerializer:
- *   access_token, token_type, expires_at, provider, handle
- *
- * The platform issues a short-lived access token for the specified
- * connection. The token is pre-authorized for the scopes granted on
- * the connection.
- */
-interface PlatformTokenResponse {
-  access_token: string;
-  token_type?: string;
-  /** ISO-8601 datetime when the token expires (null if no expiry). */
-  expires_at?: string | null;
-  provider?: string;
-  handle?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Materializer options
-// ---------------------------------------------------------------------------
-
-export interface ManagedMaterializerOptions {
-  /**
-   * Platform base URL (without trailing slash).
-   */
-  platformBaseUrl: string;
-  /**
-   * Assistant API key for authenticating with the platform.
-   */
-  assistantApiKey: string;
-  /**
-   * Platform-assigned assistant UUID. Required for building the
-   * platform materialize URL: /v1/assistants/<id>/oauth/managed/materialize/
-   */
-  assistantId: string;
-  /**
-   * Optional custom fetch implementation (for testing).
-   */
-  fetch?: typeof globalThis.fetch;
-}
-
-// ---------------------------------------------------------------------------
-// Materializer implementation
-// ---------------------------------------------------------------------------
-
-/**
- * Materialize a managed OAuth subject into a short-lived access token
- * by calling the platform's token-materialization endpoint.
- *
- * The endpoint is:
- *   POST {platformBaseUrl}/v1/assistants/{assistantId}/oauth/managed/materialize/
- *
- * The request body contains `{ connection_id: <uuid> }`.
- *
- * The platform validates the assistant API key, checks that the connection
- * is active, and returns a fresh access token (refreshing upstream if
- * needed).
- *
- * Fail-closed: any error results in a structured `MaterializationError`
- * rather than a partial or fallback result.
- */
-export async function materializeManagedToken(
-  subject: ManagedSubject,
-  options: ManagedMaterializerOptions
-): Promise<MaterializeResult> {
-  // -- Validate prerequisites -----------------------------------------------
-  if (!options.platformBaseUrl) {
-    return {
-      ok: false,
-      error: new MaterializationError(
-        "MISSING_PLATFORM_URL",
-        "Platform base URL is required for managed token materialization"
-      ),
-    };
-  }
-
-  if (!options.assistantApiKey) {
-    return {
-      ok: false,
-      error: new MaterializationError(
-        "MISSING_API_KEY",
-        "Assistant API key is required for managed token materialization"
-      ),
-    };
-  }
-
-  if (!options.assistantId) {
-    return {
-      ok: false,
-      error: new MaterializationError(
-        "MISSING_ASSISTANT_ID",
-        "Assistant ID is required for managed token materialization"
-      ),
-    };
-  }
-
-  // -- Call platform token endpoint -----------------------------------------
-  const fetchFn = options.fetch ?? globalThis.fetch;
-  const materializeUrl = `${
-    options.platformBaseUrl
-  }/v1/assistants/${encodeURIComponent(
-    options.assistantId
-  )}/oauth/managed/materialize/`;
-
-  let response: Response;
-  try {
-    response = await fetchFn(materializeUrl, {
-      method: "POST",
-      headers: {
-        Authorization: `Api-Key ${options.assistantApiKey}`,
-        Accept: "application/json",
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ connection_id: subject.connectionId }),
-    });
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return {
-      ok: false,
-      error: new MaterializationError(
-        "PLATFORM_UNREACHABLE",
-        `Failed to reach platform token endpoint: ${sanitizeError(message)}`
-      ),
-    };
-  }
-
-  // -- Handle error responses -----------------------------------------------
-  if (!response.ok) {
-    return {
-      ok: false,
-      error: mapPlatformError(response.status, subject.connectionId),
-    };
-  }
-
-  // -- Parse token response -------------------------------------------------
-  let body: PlatformTokenResponse;
-  try {
-    body = (await response.json()) as PlatformTokenResponse;
-  } catch {
-    return {
-      ok: false,
-      error: new MaterializationError(
-        "INVALID_TOKEN_RESPONSE",
-        "Platform token endpoint returned invalid JSON"
-      ),
-    };
-  }
-
-  if (!body.access_token || typeof body.access_token !== "string") {
-    return {
-      ok: false,
-      error: new MaterializationError(
-        "INVALID_TOKEN_RESPONSE",
-        "Platform token response missing access_token"
-      ),
-    };
-  }
-
-  // -- Build materialized token ---------------------------------------------
-  const expiresAt = parseExpiresAt(body.expires_at);
-
-  const token: MaterializedToken = {
-    accessToken: body.access_token,
-    tokenType: body.token_type ?? "Bearer",
-    expiresAt,
-    provider: subject.provider,
-    connectionId: subject.connectionId,
-  };
-
-  return { ok: true, token };
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Map a platform HTTP error status to a structured MaterializationError.
- */
-function mapPlatformError(
-  status: number,
-  connectionId: string
-): MaterializationError {
-  switch (status) {
-    case 401:
-      return new MaterializationError(
-        "PLATFORM_AUTH_FAILED",
-        "Assistant API key is invalid or expired (HTTP 401)"
-      );
-    case 403:
-      return new MaterializationError(
-        "PLATFORM_FORBIDDEN",
-        "Assistant is not authorized to materialize this connection (HTTP 403)"
-      );
-    case 404:
-      return new MaterializationError(
-        "CONNECTION_NOT_FOUND",
-        `Connection ${connectionId} not found on the platform (HTTP 404)`
-      );
-    default:
-      return new MaterializationError(
-        `PLATFORM_HTTP_${status}`,
-        `Platform token endpoint returned HTTP ${status}`
-      );
-  }
-}
-
-/**
- * Parse an ISO-8601 `expires_at` datetime string into epoch milliseconds.
- * Returns null if the value is missing or invalid.
- */
-function parseExpiresAt(expiresAt: string | null | undefined): number | null {
-  if (expiresAt == null) return null;
-  const ts = new Date(expiresAt).getTime();
-  if (Number.isNaN(ts)) return null;
-  return ts;
-}
-
-/**
- * Sanitize error messages to avoid leaking secrets.
- */
-function sanitizeError(message: string): string {
-  return message.replace(/Api-Key\s+\S+/gi, "Api-Key [REDACTED]");
-}

package/src/subjects/local.ts

@@ -1,177 +0,0 @@
-/**
- * CES local subject resolution.
- *
- * Resolves CES credential handles to their underlying storage subjects
- * using the shared `@vellumai/credential-storage` primitives. This module
- * is the CES-side counterpart to the assistant's credential resolver, but
- * operates independently — it never imports from the assistant daemon.
- *
- * Subject resolution is the first phase of credential materialisation:
- * 1. Parse the handle (via `@vellumai/service-contracts`)
- * 2. Look up the metadata/connection record in local storage
- * 3. Return a resolved subject that the materialiser can consume
- *
- * Both `local_static` and `local_oauth` handle types are supported.
- * Unknown or disconnected handles fail before any outbound work starts.
- */
-
-import {
-  credentialKey,
-  type OAuthConnectionRecord,
-  type StaticCredentialRecord,
-  StaticCredentialMetadataStore,
-} from "@vellumai/credential-storage";
-import {
-  HandleType,
-  parseHandle,
-  type LocalOAuthHandle,
-  type LocalStaticHandle,
-} from "@vellumai/service-contracts/credential-rpc";
-
-// ---------------------------------------------------------------------------
-// Resolved subject types
-// ---------------------------------------------------------------------------
-
-/**
- * A resolved local static credential subject. Contains the metadata record
- * and the secure-key storage key needed to materialise the secret value.
- */
-export interface ResolvedStaticSubject {
-  type: typeof HandleType.LocalStatic;
-  /** The parsed handle. */
-  handle: LocalStaticHandle;
-  /** Non-secret metadata record from the credential store. */
-  metadata: StaticCredentialRecord;
-  /** Secure-key path where the secret value is stored. */
-  storageKey: string;
-}
-
-/**
- * A resolved local OAuth credential subject. Contains the connection record
- * and the connection ID needed to materialise the access token.
- */
-export interface ResolvedOAuthSubject {
-  type: typeof HandleType.LocalOAuth;
-  /** The parsed handle. */
-  handle: LocalOAuthHandle;
-  /** OAuth connection record from local persistence. */
-  connection: OAuthConnectionRecord;
-}
-
-export type ResolvedLocalSubject =
-  | ResolvedStaticSubject
-  | ResolvedOAuthSubject;
-
-// ---------------------------------------------------------------------------
-// Resolution result
-// ---------------------------------------------------------------------------
-
-export type SubjectResolutionResult =
-  | { ok: true; subject: ResolvedLocalSubject }
-  | { ok: false; error: string };
-
-// ---------------------------------------------------------------------------
-// OAuth connection lookup abstraction
-// ---------------------------------------------------------------------------
-
-/**
- * Abstraction for looking up local OAuth connection records.
- *
- * CES does not import the assistant's SQLite-backed oauth-store. Instead,
- * callers provide a lightweight lookup interface that can be backed by
- * any persistence mechanism (JSON file, SQLite, in-memory map).
- */
-export interface OAuthConnectionLookup {
-  /** Look up a connection by its ID. Returns undefined if not found. */
-  getById(connectionId: string): OAuthConnectionRecord | undefined;
-}
-
-// ---------------------------------------------------------------------------
-// Local subject resolver
-// ---------------------------------------------------------------------------
-
-export interface LocalSubjectResolverDeps {
-  /** Metadata store for local static credentials. */
-  metadataStore: StaticCredentialMetadataStore;
-  /** Lookup for local OAuth connections. */
-  oauthConnections: OAuthConnectionLookup;
-}
-
-/**
- * Resolve a CES credential handle to a local subject.
- *
- * Supports `local_static` and `local_oauth` handle types. Returns a
- * discriminated result so callers can inspect errors without catching
- * exceptions.
- *
- * Resolution is fail-closed: unknown handle types, missing metadata,
- * and disconnected OAuth connections all return errors before any
- * outbound work starts.
- */
-export function resolveLocalSubject(
-  rawHandle: string,
-  deps: LocalSubjectResolverDeps,
-): SubjectResolutionResult {
-  const parseResult = parseHandle(rawHandle);
-  if (!parseResult.ok) {
-    return { ok: false, error: parseResult.error };
-  }
-
-  const parsed = parseResult.handle;
-
-  switch (parsed.type) {
-    case HandleType.LocalStatic: {
-      const metadata = deps.metadataStore.getByServiceField(
-        parsed.service,
-        parsed.field,
-      );
-      if (!metadata) {
-        return {
-          ok: false,
-          error: `No local static credential found for service="${parsed.service}", field="${parsed.field}"`,
-        };
-      }
-      const storageKey = credentialKey(parsed.service, parsed.field);
-      return {
-        ok: true,
-        subject: {
-          type: HandleType.LocalStatic,
-          handle: parsed,
-          metadata,
-          storageKey,
-        },
-      };
-    }
-
-    case HandleType.LocalOAuth: {
-      const connection = deps.oauthConnections.getById(parsed.connectionId);
-      if (!connection) {
-        return {
-          ok: false,
-          error: `No local OAuth connection found for connectionId="${parsed.connectionId}"`,
-        };
-      }
-      // Verify the provider key matches the connection's provider
-      if (connection.providerKey !== parsed.providerKey) {
-        return {
-          ok: false,
-          error: `OAuth connection "${parsed.connectionId}" has providerKey="${connection.providerKey}" but handle specifies "${parsed.providerKey}"`,
-        };
-      }
-      return {
-        ok: true,
-        subject: {
-          type: HandleType.LocalOAuth,
-          handle: parsed,
-          connection,
-        },
-      };
-    }
-
-    default:
-      return {
-        ok: false,
-        error: `Handle type "${parsed.type}" is not a local handle and cannot be resolved by the local subject resolver`,
-      };
-  }
-}