@vellumai/assistant 0.4.13 → 0.4.15

package/src/runtime/actor-token-service.ts

@@ -1,234 +0,0 @@
-/**
- * Actor-token mint/verify service.
- *
- * Mints HMAC-signed actor tokens bound to (assistantId, guardianPrincipalId,
- * deviceId, platform). Only the SHA-256 hash of the token is persisted —
- * the raw plaintext is returned to the caller once and never stored.
- *
- * Token format: base64url(JSON claims) + '.' + base64url(HMAC-SHA256 signature)
- */
-
-import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-
-import { getLogger } from '../util/logger.js';
-import { getRootDir } from '../util/platform.js';
-
-const log = getLogger('actor-token-service');
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface ActorTokenClaims {
-  /** The assistant this token is scoped to. */
-  assistantId: string;
-  /** Platform: 'macos' | 'ios' */
-  platform: string;
-  /** Opaque device identifier (hashed for storage). */
-  deviceId: string;
-  /** The guardian principal this token is bound to. */
-  guardianPrincipalId: string;
-  /** Token issuance timestamp (epoch ms). */
-  iat: number;
-  /** Token expiration timestamp (epoch ms). Null means non-expiring. */
-  exp: number | null;
-  /** Random jti (JWT ID) for uniqueness. */
-  jti: string;
-}
-
-export interface MintResult {
-  /** The raw actor token string — returned once, never persisted. */
-  token: string;
-  /** SHA-256 hex hash of the token (for storage/lookup). */
-  tokenHash: string;
-  /** The decoded claims. */
-  claims: ActorTokenClaims;
-}
-
-export type VerifyResult =
-  | { ok: true; claims: ActorTokenClaims }
-  | { ok: false; reason: string };
-
-// ---------------------------------------------------------------------------
-// Signing key management
-// ---------------------------------------------------------------------------
-
-let signingKey: Buffer | null = null;
-
-/**
- * Path to the persisted signing key file.
- * Stored in the protected directory alongside other sensitive material.
- */
-function getSigningKeyPath(): string {
-  return join(getRootDir(), 'protected', 'actor-token-signing-key');
-}
-
-/**
- * Load a signing key from disk or generate and persist a new one.
- * Uses the same atomic-write + chmod 0o600 pattern as approved-devices-store.ts.
- */
-export function loadOrCreateSigningKey(): Buffer {
-  const keyPath = getSigningKeyPath();
-
-  // Try to load existing key
-  if (existsSync(keyPath)) {
-    try {
-      const raw = readFileSync(keyPath);
-      if (raw.length === 32) {
-        log.info('Actor-token signing key loaded from disk');
-        return raw;
-      }
-      log.warn('Signing key file has unexpected length, regenerating');
-    } catch (err) {
-      log.warn({ err }, 'Failed to read signing key file, regenerating');
-    }
-  }
-
-  // Generate and persist a new key
-  const newKey = randomBytes(32);
-  const dir = dirname(keyPath);
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-  const tmpPath = keyPath + '.tmp.' + process.pid;
-  writeFileSync(tmpPath, newKey, { mode: 0o600 });
-  renameSync(tmpPath, keyPath);
-  chmodSync(keyPath, 0o600);
-
-  log.info('Actor-token signing key generated and persisted');
-  return newKey;
-}
-
-/**
- * Initialize (or reinitialize) the signing key. Called at daemon startup
- * with a key loaded from disk via loadOrCreateSigningKey(), or by tests
- * with a deterministic key.
- */
-export function initSigningKey(key: Buffer): void {
-  signingKey = key;
-}
-
-function getSigningKey(): Buffer {
-  if (!signingKey) {
-    throw new Error('Actor-token signing key not initialized — call initSigningKey() during startup');
-  }
-  return signingKey;
-}
-
-// ---------------------------------------------------------------------------
-// Base64url helpers
-// ---------------------------------------------------------------------------
-
-function base64urlEncode(data: Buffer | string): string {
-  const buf = typeof data === 'string' ? Buffer.from(data, 'utf-8') : data;
-  return buf.toString('base64url');
-}
-
-function base64urlDecode(str: string): Buffer {
-  return Buffer.from(str, 'base64url');
-}
-
-// ---------------------------------------------------------------------------
-// Hashing
-// ---------------------------------------------------------------------------
-
-/** SHA-256 hex digest of a raw token string. */
-export function hashToken(token: string): string {
-  return createHash('sha256').update(token).digest('hex');
-}
-
-// ---------------------------------------------------------------------------
-// Mint
-// ---------------------------------------------------------------------------
-
-/** Default TTL for actor tokens: 30 days in milliseconds. */
-const DEFAULT_TOKEN_TTL_MS = 30 * 24 * 60 * 60 * 1000;
-
-/**
- * Mint a new actor token.
- *
- * @param params Token claims (assistantId, platform, deviceId, guardianPrincipalId).
- * @param ttlMs  Optional TTL in milliseconds. Defaults to 30 days.
- *               Pass `null` explicitly for a non-expiring token.
- * @returns The raw token, its hash, and the embedded claims.
- */
-export function mintActorToken(params: {
-  assistantId: string;
-  platform: string;
-  deviceId: string;
-  guardianPrincipalId: string;
-  ttlMs?: number | null;
-}): MintResult {
-  const now = Date.now();
-  const effectiveTtl = params.ttlMs === undefined ? DEFAULT_TOKEN_TTL_MS : params.ttlMs;
-  const claims: ActorTokenClaims = {
-    assistantId: params.assistantId,
-    platform: params.platform,
-    deviceId: params.deviceId,
-    guardianPrincipalId: params.guardianPrincipalId,
-    iat: now,
-    exp: effectiveTtl != null ? now + effectiveTtl : null,
-    jti: randomBytes(16).toString('hex'),
-  };
-
-  const payload = base64urlEncode(JSON.stringify(claims));
-  const sig = createHmac('sha256', getSigningKey())
-    .update(payload)
-    .digest();
-  const token = payload + '.' + base64urlEncode(sig);
-  const tokenHash = hashToken(token);
-
-  return { token, tokenHash, claims };
-}
-
-// ---------------------------------------------------------------------------
-// Verify
-// ---------------------------------------------------------------------------
-
-/**
- * Verify an actor token's structural integrity and signature.
- *
- * Does NOT check revocation — callers must additionally verify the
- * token hash exists in the actor-token store with status='active'.
- */
-export function verifyActorToken(token: string): VerifyResult {
-  const dotIndex = token.indexOf('.');
-  if (dotIndex < 0) {
-    return { ok: false, reason: 'malformed_token' };
-  }
-
-  const payload = token.slice(0, dotIndex);
-  const sigPart = token.slice(dotIndex + 1);
-
-  // Recompute HMAC
-  const expectedSig = createHmac('sha256', getSigningKey())
-    .update(payload)
-    .digest();
-  const actualSig = base64urlDecode(sigPart);
-
-  if (expectedSig.length !== actualSig.length) {
-    return { ok: false, reason: 'invalid_signature' };
-  }
-
-  // Constant-time comparison
-  if (!timingSafeEqual(expectedSig, actualSig)) {
-    return { ok: false, reason: 'invalid_signature' };
-  }
-
-  let claims: ActorTokenClaims;
-  try {
-    const decoded = base64urlDecode(payload).toString('utf-8');
-    claims = JSON.parse(decoded) as ActorTokenClaims;
-  } catch {
-    return { ok: false, reason: 'malformed_claims' };
-  }
-
-  // Expiration check
-  if (claims.exp != null && Date.now() > claims.exp) {
-    return { ok: false, reason: 'token_expired' };
-  }
-
-  return { ok: true, claims };
-}

package/src/runtime/middleware/actor-token.ts

@@ -1,265 +0,0 @@
-/**
- * Actor-token verification middleware for HTTP routes.
- *
- * Extracts the X-Actor-Token header, verifies the HMAC signature,
- * checks that the token is active in the store, and returns the
- * verified claims and resolved guardian runtime context.
- *
- * Used by vellum-channel HTTP routes (POST /v1/messages, POST /v1/confirm,
- * POST /v1/guardian-actions/decision, etc.) to enforce identity-based
- * authentication.
- *
- * For backward compatibility with bearer-authenticated local clients (CLI),
- * provides fallback functions that resolve identity through the local IPC
- * guardian context pathway when no actor token is present.
- */
-
-import type { GuardianRuntimeContext } from '../../daemon/session-runtime-assembly.js';
-import { getActiveBinding } from '../../memory/guardian-bindings.js';
-import { getLogger } from '../../util/logger.js';
-import { type ActorTokenClaims, hashToken, verifyActorToken } from '../actor-token-service.js';
-import { findActiveByTokenHash } from '../actor-token-store.js';
-import { DAEMON_INTERNAL_ASSISTANT_ID } from '../assistant-scope.js';
-import { resolveGuardianContext } from '../guardian-context-resolver.js';
-import { resolveLocalIpcGuardianContext } from '../local-actor-identity.js';
-
-const log = getLogger('actor-token-middleware');
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface ActorTokenResult {
-  ok: true;
-  claims: ActorTokenClaims;
-  guardianContext: GuardianRuntimeContext;
-}
-
-export interface ActorTokenError {
-  ok: false;
-  status: number;
-  message: string;
-}
-
-export type ActorTokenVerification = ActorTokenResult | ActorTokenError;
-
-// ---------------------------------------------------------------------------
-// Header extraction
-// ---------------------------------------------------------------------------
-
-const ACTOR_TOKEN_HEADER = 'x-actor-token';
-
-export function extractActorToken(req: Request): string | null {
-  return req.headers.get(ACTOR_TOKEN_HEADER) || null;
-}
-
-// ---------------------------------------------------------------------------
-// Full verification pipeline
-// ---------------------------------------------------------------------------
-
-/**
- * Verify the X-Actor-Token header and resolve a guardian runtime context.
- *
- * Steps:
- * 1. Extract the header value.
- * 2. Verify HMAC signature and expiration.
- * 3. Check the token hash is active in the actor-token store.
- * 4. Resolve a guardian context through the standard trust pipeline using
- *    the claims' guardianPrincipalId as the sender identity.
- *
- * Returns an ok result with claims and guardianContext, or an error with
- * the HTTP status code and message to return.
- */
-export function verifyHttpActorToken(req: Request): ActorTokenVerification {
-  const rawToken = extractActorToken(req);
-  if (!rawToken) {
-    return {
-      ok: false,
-      status: 401,
-      message: 'Missing X-Actor-Token header. Vellum HTTP requests require actor identity.',
-    };
-  }
-
-  // Structural + signature verification
-  const verifyResult = verifyActorToken(rawToken);
-  if (!verifyResult.ok) {
-    log.warn({ reason: verifyResult.reason }, 'Actor token verification failed');
-    return {
-      ok: false,
-      status: 401,
-      message: `Invalid actor token: ${verifyResult.reason}`,
-    };
-  }
-
-  // Check the token is active in the store (not revoked)
-  const tokenHash = hashToken(rawToken);
-  const record = findActiveByTokenHash(tokenHash);
-  if (!record) {
-    log.warn('Actor token not found in active store (possibly revoked)');
-    return {
-      ok: false,
-      status: 401,
-      message: 'Actor token is no longer active',
-    };
-  }
-
-  const { claims } = verifyResult;
-
-  // Resolve guardian context through the shared trust pipeline.
-  // The guardianPrincipalId from the token is used as the sender identity,
-  // and 'vellum' is used as the channel for binding lookup.
-  const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
-  const guardianCtx = resolveGuardianContext({
-    assistantId,
-    sourceChannel: 'vellum',
-    conversationExternalId: 'local',
-    actorExternalId: claims.guardianPrincipalId,
-  });
-
-  return {
-    ok: true,
-    claims,
-    guardianContext: guardianCtx,
-  };
-}
-
-/**
- * Verify that the actor identity from a verified token matches the bound
- * guardian for the vellum channel. Used for guardian-decision endpoints
- * where only the guardian should be able to approve/reject.
- *
- * Returns true if the actor is the bound guardian, false otherwise.
- */
-export function isActorBoundGuardian(claims: ActorTokenClaims): boolean {
-  const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
-  const binding = getActiveBinding(assistantId, 'vellum');
-  if (!binding) return false;
-  return binding.guardianExternalUserId === claims.guardianPrincipalId;
-}
-
-// ---------------------------------------------------------------------------
-// Bearer-auth fallback variants
-// ---------------------------------------------------------------------------
-
-/** Loopback addresses — used to gate the local identity fallback. */
-const LOOPBACK_ADDRESSES = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
-
-/** Bun server shape needed for requestIP — avoids importing the full Bun type. */
-export type ServerWithRequestIP = {
-  requestIP(req: Request): { address: string; family: string; port: number } | null;
-};
-
-/**
- * Result for the fallback verification path where the actor token is absent
- * but the request is bearer-authenticated (local trusted client like CLI).
- */
-export interface ActorTokenLocalFallbackResult {
-  ok: true;
-  claims: null;
-  guardianContext: GuardianRuntimeContext;
-  localFallback: true;
-}
-
-export type ActorTokenVerificationWithFallback =
-  | ActorTokenResult
-  | ActorTokenLocalFallbackResult
-  | ActorTokenError;
-
-/**
- * Verify the actor token with fallback to local IPC identity resolution.
- *
- * When an actor token is present, the full verification pipeline runs.
- * When absent AND the request originates from a loopback address, the
- * request is treated as a trusted local client (e.g. CLI) and we fall
- * back to `resolveLocalIpcGuardianContext()` which produces the same
- * guardian context as the IPC pathway.
- *
- * Two conditions must BOTH be met for the local fallback:
- * 1. No X-Forwarded-For header (rules out gateway-proxied requests).
- * 2. The peer remote address is a loopback address (rules out LAN/container
- *    connections when the runtime binds to 0.0.0.0).
- *
- * The peer address is checked via `server.requestIP(req)`.
- *
- * --- CLI compatibility note ---
- *
- * The local fallback is an intentional CLI compatibility path, not a
- * security gap. The CLI currently sends only `Authorization: Bearer <token>`
- * without `X-Actor-Token`. This fallback allows the CLI to function until
- * it is migrated to actor tokens in a future milestone.
- *
- * The fallback is gated by three conditions that together ensure only
- * genuinely local connections receive guardian identity:
- *   (1) Absence of X-Forwarded-For header — the gateway always injects
- *       this header when proxying, so its presence indicates a remote client.
- *   (2) Loopback origin check — verifies the peer IP is 127.0.0.1/::1,
- *       preventing LAN or container peers.
- *   (3) Valid bearer authentication — already enforced upstream by the
- *       HTTP server's auth gate before this function is called.
- *
- * Once the CLI adopts actor tokens, this fallback can be removed.
- */
-export function verifyHttpActorTokenWithLocalFallback(
-  req: Request,
-  server: ServerWithRequestIP,
-): ActorTokenVerificationWithFallback {
-  const rawToken = extractActorToken(req);
-
-  // If an actor token is present, use the strict verification pipeline.
-  if (rawToken) {
-    return verifyHttpActorToken(req);
-  }
-
-  // Gate the local fallback on provably-local origin. The gateway runtime
-  // proxy always injects X-Forwarded-For with the real client IP when
-  // forwarding requests. Direct local connections (CLI, macOS app) never
-  // set this header. If X-Forwarded-For is present, the request was
-  // proxied through the gateway on behalf of a potentially remote client
-  // and must not receive local guardian identity.
-  if (req.headers.get('x-forwarded-for')) {
-    log.warn('Rejecting local identity fallback: request has X-Forwarded-For (proxied through gateway)');
-    return {
-      ok: false,
-      status: 401,
-      message: 'Missing X-Actor-Token header. Proxied requests require actor identity.',
-    };
-  }
-
-  // Verify the peer address is actually loopback. This prevents LAN or
-  // container peers from receiving local guardian identity when the
-  // runtime binds to 0.0.0.0.
-  const peerIp = server.requestIP(req)?.address;
-  if (!peerIp || !LOOPBACK_ADDRESSES.has(peerIp)) {
-    log.warn({ peerIp }, 'Rejecting local identity fallback: peer is not loopback');
-    return {
-      ok: false,
-      status: 401,
-      message: 'Missing X-Actor-Token header. Non-loopback requests require actor identity.',
-    };
-  }
-
-  // No actor token, no forwarding header, and the peer is on loopback
-  // — this is a direct local connection that passed bearer auth at the
-  // HTTP server layer. Resolve identity the same way as IPC.
-  log.debug('No actor token present on direct local request; using local IPC identity fallback');
-  const guardianContext = resolveLocalIpcGuardianContext('vellum');
-  return {
-    ok: true,
-    claims: null,
-    guardianContext,
-    localFallback: true,
-  };
-}
-
-/**
- * Check whether the local fallback identity is the bound guardian.
- *
- * When no actor token is present (local fallback), the local user is
- * treated as the guardian of their own machine — equivalent to IPC.
- * This returns true when either the resolved trust class is 'guardian'
- * or no vellum binding exists yet (pre-bootstrap).
- */
-export function isLocalFallbackBoundGuardian(): boolean {
-  const guardianContext = resolveLocalIpcGuardianContext('vellum');
-  return guardianContext.trustClass === 'guardian';
-}