@vellumai/assistant 0.4.13 → 0.4.15

package/src/runtime/auth/context.ts

@@ -0,0 +1,62 @@
+/**
+ * AuthContext builder — combines sub parsing and scope resolution into
+ * a normalized AuthContext that downstream code can consume without
+ * knowing about JWT internals.
+ */
+
+import { DAEMON_INTERNAL_ASSISTANT_ID } from '../assistant-scope.js';
+import { resolveScopeProfile } from './scopes.js';
+import { parseSub } from './subject.js';
+import type { AuthContext, TokenClaims } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Result type
+// ---------------------------------------------------------------------------
+
+export type BuildAuthContextResult =
+  | { ok: true; context: AuthContext }
+  | { ok: false; reason: string };
+
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a normalized AuthContext from verified JWT claims.
+ *
+ * Parses the sub claim and resolves the scope profile into a concrete
+ * set of scopes. Returns a failure result if the sub is malformed.
+ *
+ * When the token audience is `vellum-daemon`, the assistantId is forced
+ * to DAEMON_INTERNAL_ASSISTANT_ID ('self') regardless of what the JWT
+ * sub encodes. Daemon code must never derive internal scoping from
+ * externally-provided assistant IDs.
+ */
+export function buildAuthContext(claims: TokenClaims): BuildAuthContextResult {
+  const subResult = parseSub(claims.sub);
+  if (!subResult.ok) {
+    return { ok: false, reason: subResult.reason };
+  }
+
+  const scopes = resolveScopeProfile(claims.scope_profile);
+
+  // Daemon-audience tokens always scope to the internal assistant ID,
+  // preventing external assistant IDs from leaking into daemon-side
+  // storage and routing.
+  const assistantId = claims.aud === 'vellum-daemon'
+    ? DAEMON_INTERNAL_ASSISTANT_ID
+    : subResult.assistantId;
+
+  const context: AuthContext = {
+    subject: claims.sub,
+    principalType: subResult.principalType,
+    assistantId,
+    actorPrincipalId: subResult.actorPrincipalId,
+    sessionId: subResult.sessionId,
+    scopeProfile: claims.scope_profile,
+    scopes,
+    policyEpoch: claims.policy_epoch,
+  };
+
+  return { ok: true, context };
+}

package/src/runtime/{actor-refresh-token-service.ts → auth/credential-service.ts}

@@ -1,37 +1,51 @@
 /**
- * Refresh token service — mint, rotate, and validate refresh tokens.
+ * JWT credential minting and rotation service.
  *
- * Implements rotating single-use refresh tokens with:
- * - Absolute expiry (365 days)
- * - Inactivity expiry (90 days since last refresh)
- * - Replay detection (reuse of rotated token revokes entire family)
+ * Replaces the legacy actor-token-service + actor-refresh-token-service with
+ * JWT-based access tokens (aud=vellum-gateway) and opaque refresh tokens.
+ *
+ * Access tokens are standard JWTs with:
+ *   - aud: 'vellum-gateway'
+ *   - sub: 'actor:<externalAssistantId>:<guardianPrincipalId>'
+ *   - scope_profile: 'actor_client_v1'
+ *   - policy_epoch: CURRENT_POLICY_EPOCH
+ *   - 30-day TTL
+ *
+ * Refresh tokens remain opaque random bytes with hash-only storage,
+ * family tracking, and replay detection — reusing the existing
+ * actor-refresh-token-store infrastructure.
  */
 
 import { createHash, randomBytes } from 'node:crypto';
 
-import { getDb } from '../memory/db.js';
-import { getLogger } from '../util/logger.js';
+import { getDb } from '../../memory/db.js';
+import { getLogger } from '../../util/logger.js';
 import {
   createRefreshTokenRecord,
   findByTokenHash as findRefreshByHash,
   markRotated,
   revokeByDeviceBinding as revokeRefreshTokensByDevice,
   revokeFamily,
-} from './actor-refresh-token-store.js';
-import { hashToken, mintActorToken } from './actor-token-service.js';
+} from '../actor-refresh-token-store.js';
 import {
   createActorTokenRecord,
   revokeByDeviceBinding as revokeActorTokensByDevice,
-} from './actor-token-store.js';
+} from '../actor-token-store.js';
+import { getExternalAssistantId } from './external-assistant-id.js';
+import { CURRENT_POLICY_EPOCH } from './policy.js';
+import { hashToken, mintToken } from './token-service.js';
 
-const log = getLogger('actor-refresh-token-service');
+const log = getLogger('credential-service');
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
-/** Access token TTL: 30 days (reduced from 90). */
-const ACCESS_TOKEN_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/** Access token TTL: 30 days in seconds. */
+const ACCESS_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
+
+/** Access token TTL in ms (for refresh-after hints). */
+const ACCESS_TOKEN_TTL_MS = ACCESS_TOKEN_TTL_SECONDS * 1000;
 
 /** Refresh token absolute expiry: 365 days from issuance. */
 const REFRESH_ABSOLUTE_TTL_MS = 365 * 24 * 60 * 60 * 1000;
@@ -53,51 +67,83 @@ export type RefreshErrorCode =
   | 'device_binding_mismatch'
   | 'revoked';
 
-export interface RefreshResult {
-  guardianPrincipalId: string;
-  actorToken: string;
-  actorTokenExpiresAt: number;
+export interface CredentialPairResult {
+  accessToken: string;
+  accessTokenExpiresAt: number;
   refreshToken: string;
   refreshTokenExpiresAt: number;
   refreshAfter: number;
+  guardianPrincipalId: string;
 }
 
-export interface MintRefreshTokenResult {
+export interface RotateResult {
+  guardianPrincipalId: string;
+  accessToken: string;
+  accessTokenExpiresAt: number;
   refreshToken: string;
-  refreshTokenHash: string;
   refreshTokenExpiresAt: number;
   refreshAfter: number;
 }
 
 // ---------------------------------------------------------------------------
-// Mint a fresh refresh token (used by bootstrap/pairing)
+// Internal: refresh token helpers
 // ---------------------------------------------------------------------------
 
-/** Hash a raw refresh token for storage. Reuses the actor-token hash function. */
+function generateRefreshToken(): string {
+  return randomBytes(32).toString('base64url');
+}
+
 function hashRefreshToken(token: string): string {
   return hashToken(token);
 }
 
-/** Generate a cryptographically random refresh token. */
-function generateRefreshToken(): string {
-  return randomBytes(32).toString('base64url');
+// ---------------------------------------------------------------------------
+// Internal: mint a JWT access token
+// ---------------------------------------------------------------------------
+
+function mintAccessToken(guardianPrincipalId: string): {
+  token: string;
+  tokenHash: string;
+  expiresAt: number;
+  issuedAt: number;
+} {
+  const externalAssistantId = getExternalAssistantId();
+  const sub = `actor:${externalAssistantId}:${guardianPrincipalId}`;
+
+  const token = mintToken({
+    aud: 'vellum-gateway',
+    sub,
+    scope_profile: 'actor_client_v1',
+    policy_epoch: CURRENT_POLICY_EPOCH,
+    ttlSeconds: ACCESS_TOKEN_TTL_SECONDS,
+  });
+
+  const now = Date.now();
+  return {
+    token,
+    tokenHash: hashToken(token),
+    expiresAt: now + ACCESS_TOKEN_TTL_MS,
+    issuedAt: now,
+  };
 }
 
-/**
- * Mint a new refresh token and persist its hash.
- * Called during bootstrap, pairing, and rotation.
- */
-export function mintRefreshToken(params: {
+// ---------------------------------------------------------------------------
+// Internal: mint a fresh refresh token and persist its hash
+// ---------------------------------------------------------------------------
+
+function mintRefreshTokenInternal(params: {
   assistantId: string;
   guardianPrincipalId: string;
   hashedDeviceId: string;
   platform: string;
   familyId?: string;
-  /** When provided (during rotation), inherit the parent token's absolute expiry
-   *  instead of computing a fresh one. This ensures refresh rotation resets the
-   *  inactivity window but does NOT extend the absolute session lifetime. */
   absoluteExpiresAt?: number;
-}): MintRefreshTokenResult {
+}): {
+  refreshToken: string;
+  refreshTokenHash: string;
+  refreshTokenExpiresAt: number;
+  refreshAfter: number;
+} {
   const now = Date.now();
   const familyId = params.familyId ?? randomBytes(16).toString('hex');
   const refreshToken = generateRefreshToken();
@@ -125,9 +171,15 @@ export function mintRefreshToken(params: {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Public: mint credential pair (access token + refresh token)
+// ---------------------------------------------------------------------------
+
 /**
- * Mint both an access token and a refresh token for initial credential issuance.
+ * Mint a JWT access token and an opaque refresh token for initial issuance.
  * Used by bootstrap and pairing flows.
+ *
+ * Revokes any existing credentials for the device before minting.
  */
 export function mintCredentialPair(params: {
   assistantId: string;
@@ -135,39 +187,26 @@ export function mintCredentialPair(params: {
   deviceId: string;
   guardianPrincipalId: string;
   hashedDeviceId: string;
-}): {
-  actorToken: string;
-  actorTokenExpiresAt: number;
-  refreshToken: string;
-  refreshTokenExpiresAt: number;
-  refreshAfter: number;
-  guardianPrincipalId: string;
-} {
+}): CredentialPairResult {
   // Revoke any existing credentials for this device
   revokeActorTokensByDevice(params.assistantId, params.guardianPrincipalId, params.hashedDeviceId);
   revokeRefreshTokensByDevice(params.assistantId, params.guardianPrincipalId, params.hashedDeviceId);
 
-  // Mint new access token with 30-day TTL
-  const { token: actorToken, tokenHash: actorTokenHash, claims } = mintActorToken({
-    assistantId: params.assistantId,
-    platform: params.platform,
-    deviceId: params.deviceId,
-    guardianPrincipalId: params.guardianPrincipalId,
-    ttlMs: ACCESS_TOKEN_TTL_MS,
-  });
+  // Mint new JWT access token
+  const access = mintAccessToken(params.guardianPrincipalId);
 
   createActorTokenRecord({
-    tokenHash: actorTokenHash,
+    tokenHash: access.tokenHash,
     assistantId: params.assistantId,
     guardianPrincipalId: params.guardianPrincipalId,
     hashedDeviceId: params.hashedDeviceId,
     platform: params.platform,
-    issuedAt: claims.iat,
-    expiresAt: claims.exp,
+    issuedAt: access.issuedAt,
+    expiresAt: access.expiresAt,
   });
 
   // Mint new refresh token
-  const refresh = mintRefreshToken({
+  const refresh = mintRefreshTokenInternal({
     assistantId: params.assistantId,
     guardianPrincipalId: params.guardianPrincipalId,
     hashedDeviceId: params.hashedDeviceId,
@@ -175,8 +214,8 @@ export function mintCredentialPair(params: {
   });
 
   return {
-    actorToken,
-    actorTokenExpiresAt: claims.exp!,
+    accessToken: access.token,
+    accessTokenExpiresAt: access.expiresAt,
     refreshToken: refresh.refreshToken,
     refreshTokenExpiresAt: refresh.refreshTokenExpiresAt,
     refreshAfter: refresh.refreshAfter,
@@ -185,19 +224,20 @@ export function mintCredentialPair(params: {
 }
 
 // ---------------------------------------------------------------------------
-// Rotate (the core refresh operation)
+// Public: rotate credentials
 // ---------------------------------------------------------------------------
 
 /**
  * Rotate credentials: validate refresh token, revoke old, mint new pair.
  *
- * Returns either a successful result or an error code.
+ * Returns either a successful result or an error code. The rotation is
+ * wrapped in a SQLite transaction for atomicity.
  */
 export function rotateCredentials(params: {
   refreshToken: string;
   platform: string;
   deviceId: string;
-}): { ok: true; result: RefreshResult } | { ok: false; error: RefreshErrorCode } {
+}): { ok: true; result: RotateResult } | { ok: false; error: RefreshErrorCode } {
   const refreshTokenHash = hashRefreshToken(params.refreshToken);
   const hashedDeviceId = createHash('sha256').update(params.deviceId).digest('hex');
 
@@ -245,12 +285,10 @@ export function rotateCredentials(params: {
     return { ok: false, error: 'device_binding_mismatch' };
   }
 
-  // Wrap the entire rotate-revoke-remint sequence in a transaction so that
-  // partial failures (e.g., DB write error after revoking old tokens) roll back
-  // atomically instead of stranding device credentials.
+  // Wrap the entire rotate-revoke-remint sequence in a transaction
   const db = getDb();
   return db.transaction(() => {
-    // Mark old refresh token as rotated (atomic CAS — fails if a concurrent request already consumed it)
+    // Mark old refresh token as rotated (atomic CAS)
     const didRotate = markRotated(refreshTokenHash);
     if (!didRotate) {
       return { ok: false as const, error: 'refresh_reuse_detected' as const };
@@ -259,28 +297,23 @@ export function rotateCredentials(params: {
     // Revoke old access tokens for this device
     revokeActorTokensByDevice(record.assistantId, record.guardianPrincipalId, record.hashedDeviceId);
 
-    // Mint new access token
-    const { token: actorToken, tokenHash: actorTokenHash, claims } = mintActorToken({
-      assistantId: record.assistantId,
-      platform: params.platform,
-      deviceId: params.deviceId,
-      guardianPrincipalId: record.guardianPrincipalId,
-      ttlMs: ACCESS_TOKEN_TTL_MS,
-    });
+    // Mint new JWT access token
+    const access = mintAccessToken(record.guardianPrincipalId);
 
     createActorTokenRecord({
-      tokenHash: actorTokenHash,
+      tokenHash: access.tokenHash,
       assistantId: record.assistantId,
       guardianPrincipalId: record.guardianPrincipalId,
       hashedDeviceId: record.hashedDeviceId,
       platform: params.platform,
-      issuedAt: claims.iat,
-      expiresAt: claims.exp,
+      issuedAt: access.issuedAt,
+      expiresAt: access.expiresAt,
     });
 
-    // Mint new refresh token in the same family, inheriting the parent's absolute
-    // expiry so rotation resets inactivity but never extends the session lifetime.
-    const refresh = mintRefreshToken({
+    // Mint new refresh token in the same family, inheriting the parent's
+    // absolute expiry so rotation resets inactivity but never extends
+    // the session lifetime.
+    const refresh = mintRefreshTokenInternal({
       assistantId: record.assistantId,
       guardianPrincipalId: record.guardianPrincipalId,
       hashedDeviceId: record.hashedDeviceId,
@@ -298,8 +331,8 @@ export function rotateCredentials(params: {
       ok: true as const,
       result: {
         guardianPrincipalId: record.guardianPrincipalId,
-        actorToken,
-        actorTokenExpiresAt: claims.exp!,
+        accessToken: access.token,
+        accessTokenExpiresAt: access.expiresAt,
         refreshToken: refresh.refreshToken,
         refreshTokenExpiresAt: refresh.refreshTokenExpiresAt,
         refreshAfter: refresh.refreshAfter,

package/src/runtime/auth/external-assistant-id.ts

@@ -0,0 +1,69 @@
+/**
+ * External assistant ID resolver.
+ *
+ * Reads the external assistant ID from the lockfile for use in
+ * edge-facing JWT tokens (aud=vellum-gateway). The external ID is
+ * needed because the gateway must identify which assistant the token
+ * belongs to, while the daemon internally uses 'self'.
+ *
+ * The value is cached in memory after the first successful read.
+ * Falls back to 'self' if the lockfile is unreadable or has no
+ * assistant entries.
+ */
+
+import { getLogger } from '../../util/logger.js';
+import { readLockfile } from '../../util/platform.js';
+
+const log = getLogger('external-assistant-id');
+
+let cached: string | undefined;
+
+/**
+ * Get the external assistant ID from the lockfile.
+ *
+ * Resolution order:
+ *   1. Cached in-memory value (populated on first call)
+ *   2. Most recently hatched entry in lockfile assistants array
+ *      (sorted by `hatchedAt` descending) → assistantId
+ *   3. Fallback: 'self'
+ */
+export function getExternalAssistantId(): string {
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  try {
+    const lockData = readLockfile();
+    if (lockData) {
+      const assistants = lockData.assistants as Array<Record<string, unknown>> | undefined;
+      if (assistants && assistants.length > 0) {
+        // Sort by hatchedAt descending to use the most recent entry,
+        // matching the pattern used elsewhere in the codebase.
+        const sorted = [...assistants].sort((a, b) => {
+          const dateA = new Date((a.hatchedAt as string) || 0).getTime();
+          const dateB = new Date((b.hatchedAt as string) || 0).getTime();
+          return dateB - dateA;
+        });
+        const latest = sorted[0];
+        if (typeof latest.assistantId === 'string') {
+          cached = latest.assistantId;
+          log.info({ externalAssistantId: cached }, 'Resolved external assistant ID from lockfile');
+          return cached;
+        }
+      }
+    }
+  } catch (err) {
+    log.warn({ err }, 'Failed to read lockfile for external assistant ID — falling back to self');
+  }
+
+  cached = 'self';
+  return cached;
+}
+
+/**
+ * Reset the cached external assistant ID. Used by tests to force
+ * re-resolution on the next call.
+ */
+export function resetExternalAssistantIdCache(): void {
+  cached = undefined;
+}

package/src/runtime/auth/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Auth module barrel export.
+ *
+ * Re-exports all public types and functions from the auth subsystem
+ * so consumers can import from a single path.
+ */
+
+export type { BuildAuthContextResult } from './context.js';
+export { buildAuthContext } from './context.js';
+export type { CredentialPairResult, RefreshErrorCode, RotateResult } from './credential-service.js';
+export { mintCredentialPair, rotateCredentials } from './credential-service.js';
+export { getExternalAssistantId, resetExternalAssistantIdCache } from './external-assistant-id.js';
+export type { AuthenticateResult } from './middleware.js';
+export { authenticateRequest } from './middleware.js';
+export { CURRENT_POLICY_EPOCH, isStaleEpoch } from './policy.js';
+export type { RoutePolicy } from './route-policy.js';
+export { enforcePolicy, getPolicy, registerPolicy } from './route-policy.js';
+export { hasAllScopes, hasScope, resolveScopeProfile } from './scopes.js';
+export type { ParseSubResult } from './subject.js';
+export { parseSub } from './subject.js';
+export type { VerifyResult } from './token-service.js';
+export {
+  hashToken,
+  initAuthSigningKey,
+  loadOrCreateSigningKey,
+  mintDaemonDeliveryToken,
+  mintToken,
+  verifyToken,
+} from './token-service.js';
+export type {
+  AuthContext,
+  PrincipalType,
+  Scope,
+  ScopeProfile,
+  TokenAudience,
+  TokenClaims,
+} from './types.js';

package/src/runtime/auth/middleware.ts

@@ -0,0 +1,127 @@
+/**
+ * JWT bearer auth middleware for the runtime HTTP server.
+ *
+ * Extracts `Authorization: Bearer <token>`, verifies the JWT with
+ * `aud=vellum-daemon`, and builds an AuthContext from the claims.
+ *
+ * Replaces both the legacy bearer shared-secret check and the
+ * actor-token HMAC middleware with a single JWT verification path.
+ *
+ * In dev mode (DISABLE_HTTP_AUTH + VELLUM_UNSAFE_AUTH_BYPASS), JWT
+ * verification is skipped and a synthetic AuthContext is constructed
+ * so downstream code always has a typed context to consume.
+ */
+
+import { isHttpAuthDisabled } from '../../config/env.js';
+import { getLogger } from '../../util/logger.js';
+import { DAEMON_INTERNAL_ASSISTANT_ID } from '../assistant-scope.js';
+import { extractBearerToken } from '../middleware/auth.js';
+import { buildAuthContext } from './context.js';
+import { resolveScopeProfile } from './scopes.js';
+import { verifyToken } from './token-service.js';
+import type { AuthContext } from './types.js';
+
+const log = getLogger('auth-middleware');
+
+// ---------------------------------------------------------------------------
+// Result type
+// ---------------------------------------------------------------------------
+
+export type AuthenticateResult =
+  | { ok: true; context: AuthContext }
+  | { ok: false; response: Response };
+
+// ---------------------------------------------------------------------------
+// Dev bypass synthetic context
+// ---------------------------------------------------------------------------
+
+/**
+ * Construct a synthetic AuthContext for dev mode when auth is bypassed.
+ * Grants the broadest profile so all routes are accessible during
+ * local development.
+ */
+function buildDevBypassContext(): AuthContext {
+  return {
+    subject: `actor:${DAEMON_INTERNAL_ASSISTANT_ID}:dev-bypass`,
+    principalType: 'actor',
+    assistantId: DAEMON_INTERNAL_ASSISTANT_ID,
+    actorPrincipalId: 'dev-bypass',
+    scopeProfile: 'actor_client_v1',
+    scopes: resolveScopeProfile('actor_client_v1'),
+    policyEpoch: Number.MAX_SAFE_INTEGER,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Authenticate an incoming HTTP request via JWT bearer token.
+ *
+ * Returns an AuthContext on success, or an error Response on failure.
+ * The caller should return the error Response directly to the client.
+ */
+export function authenticateRequest(req: Request): AuthenticateResult {
+  // Dev bypass: skip JWT verification entirely
+  if (isHttpAuthDisabled()) {
+    return { ok: true, context: buildDevBypassContext() };
+  }
+
+  const path = new URL(req.url).pathname;
+
+  const rawToken = extractBearerToken(req);
+  if (!rawToken) {
+    log.warn({ reason: 'missing_token', path }, 'Auth denied: missing Authorization header');
+    return {
+      ok: false,
+      response: Response.json(
+        { error: { code: 'UNAUTHORIZED', message: 'Missing Authorization header' } },
+        { status: 401 },
+      ),
+    };
+  }
+
+  // Verify the JWT with audience = vellum-daemon
+  const verifyResult = verifyToken(rawToken, 'vellum-daemon');
+  if (!verifyResult.ok) {
+    // Stale policy epoch gets a specific error code so clients can refresh
+    if (verifyResult.reason === 'stale_policy_epoch') {
+      log.warn({ reason: 'stale_policy_epoch', path }, 'Auth denied: stale policy epoch');
+      return {
+        ok: false,
+        response: Response.json(
+          { error: { code: 'refresh_required', message: 'Token policy epoch is stale; refresh required' } },
+          { status: 401 },
+        ),
+      };
+    }
+
+    log.warn({ reason: verifyResult.reason, path }, 'Auth denied: JWT verification failed');
+    return {
+      ok: false,
+      response: Response.json(
+        { error: { code: 'UNAUTHORIZED', message: `Invalid token: ${verifyResult.reason}` } },
+        { status: 401 },
+      ),
+    };
+  }
+
+  // Build normalized AuthContext from verified claims
+  const contextResult = buildAuthContext(verifyResult.claims);
+  if (!contextResult.ok) {
+    log.warn(
+      { reason: contextResult.reason, path, sub: verifyResult.claims.sub },
+      'Auth denied: invalid JWT claims',
+    );
+    return {
+      ok: false,
+      response: Response.json(
+        { error: { code: 'UNAUTHORIZED', message: `Invalid token claims: ${contextResult.reason}` } },
+        { status: 401 },
+      ),
+    };
+  }
+
+  return { ok: true, context: contextResult.context };
+}

package/src/runtime/auth/policy.ts

@@ -0,0 +1,17 @@
+/**
+ * Policy epoch management.
+ *
+ * The policy epoch is a monotonic counter embedded in every JWT. When
+ * the auth policy changes (e.g., scope profiles are redefined), the
+ * epoch is bumped, and tokens carrying a stale epoch are rejected.
+ * This gives us a hard revocation mechanism without maintaining a
+ * per-token blocklist.
+ */
+
+/** Current policy epoch — bump this when auth policy changes. */
+export const CURRENT_POLICY_EPOCH = 1;
+
+/** Returns true if the given epoch is older than the current policy. */
+export function isStaleEpoch(epoch: number): boolean {
+  return epoch < CURRENT_POLICY_EPOCH;
+}