@vellumai/assistant 0.4.13 → 0.4.15

package/src/runtime/auth/route-policy.ts

@@ -0,0 +1,261 @@
+/**
+ * Route policy enforcement for the runtime HTTP server.
+ *
+ * Each protected endpoint declares the scopes and principal types it
+ * requires. `enforcePolicy` checks the AuthContext against these
+ * requirements and returns an error Response when access is denied.
+ *
+ * When auth is bypassed in dev mode, policies are still evaluated for
+ * type safety but always allow the request through.
+ */
+
+import { isHttpAuthDisabled } from '../../config/env.js';
+import { getLogger } from '../../util/logger.js';
+import type { AuthContext, PrincipalType, Scope } from './types.js';
+
+const log = getLogger('route-policy');
+
+// ---------------------------------------------------------------------------
+// Policy definition
+// ---------------------------------------------------------------------------
+
+export interface RoutePolicy {
+  requiredScopes: Scope[];
+  allowedPrincipalTypes: PrincipalType[];
+}
+
+// ---------------------------------------------------------------------------
+// Policy registry
+// ---------------------------------------------------------------------------
+
+const policyRegistry = new Map<string, RoutePolicy>();
+
+/**
+ * Register a route policy. Called at module load time to populate the
+ * registry with all protected endpoint policies.
+ */
+export function registerPolicy(endpoint: string, policy: RoutePolicy): void {
+  policyRegistry.set(endpoint, policy);
+}
+
+/**
+ * Look up the policy for an endpoint. Returns undefined for unregistered
+ * (unprotected) endpoints.
+ */
+export function getPolicy(endpoint: string): RoutePolicy | undefined {
+  return policyRegistry.get(endpoint);
+}
+
+// ---------------------------------------------------------------------------
+// Enforcement
+// ---------------------------------------------------------------------------
+
+/**
+ * Enforce the route policy for the given endpoint against the AuthContext.
+ *
+ * Returns an error Response if the request should be denied, or null if
+ * the request is allowed to proceed.
+ *
+ * When auth is bypassed (dev mode), the policy is still checked against
+ * the synthetic context for type safety but always returns null (allowed).
+ */
+export function enforcePolicy(
+  endpoint: string,
+  authCtx: AuthContext,
+): Response | null {
+  const policy = policyRegistry.get(endpoint);
+  if (!policy) {
+    // No policy registered — unprotected endpoint (e.g. health, debug)
+    return null;
+  }
+
+  // Dev bypass: log but allow everything through
+  if (isHttpAuthDisabled()) {
+    return null;
+  }
+
+  // Check principal type
+  if (!policy.allowedPrincipalTypes.includes(authCtx.principalType)) {
+    log.warn(
+      { endpoint, principalType: authCtx.principalType, allowed: policy.allowedPrincipalTypes },
+      'Route policy denied: principal type not allowed',
+    );
+    return Response.json(
+      { error: { code: 'FORBIDDEN', message: 'Principal type not permitted for this endpoint' } },
+      { status: 403 },
+    );
+  }
+
+  // Check required scopes
+  for (const scope of policy.requiredScopes) {
+    if (!authCtx.scopes.has(scope)) {
+      log.warn(
+        { endpoint, missingScope: scope, principalType: authCtx.principalType },
+        'Route policy denied: missing required scope',
+      );
+      return Response.json(
+        { error: { code: 'FORBIDDEN', message: `Missing required scope: ${scope}` } },
+        { status: 403 },
+      );
+    }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Policy registrations for all protected routes
+// ---------------------------------------------------------------------------
+
+// Standard actor endpoints — chat, approvals, settings, etc.
+const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
+  // Conversation / messaging
+  { endpoint: 'messages:GET', scopes: ['chat.read'] },
+  { endpoint: 'messages:POST', scopes: ['chat.write'] },
+  { endpoint: 'conversations', scopes: ['chat.read'] },
+  { endpoint: 'conversations/attention', scopes: ['chat.read'] },
+  { endpoint: 'conversations/seen', scopes: ['chat.write'] },
+  { endpoint: 'search', scopes: ['chat.read'] },
+  { endpoint: 'suggestion', scopes: ['chat.read'] },
+
+  // Approvals
+  { endpoint: 'confirm', scopes: ['approval.write'] },
+  { endpoint: 'secret', scopes: ['approval.write'] },
+  { endpoint: 'trust-rules', scopes: ['approval.write'] },
+  { endpoint: 'pending-interactions', scopes: ['approval.read'] },
+
+  // Guardian actions
+  { endpoint: 'guardian-actions/pending', scopes: ['approval.read'] },
+  { endpoint: 'guardian-actions/decision', scopes: ['approval.write'] },
+
+  // Events (SSE)
+  { endpoint: 'events', scopes: ['chat.read'] },
+
+  // Attachments
+  { endpoint: 'attachments:POST', scopes: ['attachments.write'] },
+  { endpoint: 'attachments:DELETE', scopes: ['attachments.write'] },
+  { endpoint: 'attachments:GET', scopes: ['attachments.read'] },
+  { endpoint: 'attachments/content:GET', scopes: ['attachments.read'] },
+
+  // Calls
+  { endpoint: 'calls/start', scopes: ['calls.write'] },
+  { endpoint: 'calls:GET', scopes: ['calls.read'] },
+  { endpoint: 'calls/cancel', scopes: ['calls.write'] },
+  { endpoint: 'calls/answer', scopes: ['calls.write'] },
+  { endpoint: 'calls/instruction', scopes: ['calls.write'] },
+
+  // Settings / integrations / identity
+  { endpoint: 'identity', scopes: ['settings.read'] },
+  { endpoint: 'brain-graph', scopes: ['settings.read'] },
+  { endpoint: 'brain-graph-ui', scopes: ['settings.read'] },
+  { endpoint: 'home-base-ui', scopes: ['settings.read'] },
+  { endpoint: 'contacts', scopes: ['settings.read'] },
+  { endpoint: 'contacts/merge', scopes: ['settings.write'] },
+  { endpoint: 'contacts:GET', scopes: ['settings.read'] },
+  { endpoint: 'ingress/members', scopes: ['settings.read'] },
+  { endpoint: 'ingress/members:POST', scopes: ['settings.write'] },
+  { endpoint: 'ingress/members/block', scopes: ['settings.write'] },
+  { endpoint: 'ingress/members:DELETE', scopes: ['settings.write'] },
+  { endpoint: 'ingress/invites', scopes: ['settings.read'] },
+  { endpoint: 'ingress/invites:POST', scopes: ['settings.write'] },
+  { endpoint: 'ingress/invites/redeem', scopes: ['settings.write'] },
+  { endpoint: 'ingress/invites:DELETE', scopes: ['settings.write'] },
+  { endpoint: 'integrations/telegram/config', scopes: ['settings.read'] },
+  { endpoint: 'integrations/telegram/config:POST', scopes: ['settings.write'] },
+  { endpoint: 'integrations/telegram/config:DELETE', scopes: ['settings.write'] },
+  { endpoint: 'integrations/telegram/commands', scopes: ['settings.write'] },
+  { endpoint: 'integrations/telegram/setup', scopes: ['settings.write'] },
+  { endpoint: 'integrations/slack/channel/config', scopes: ['settings.read'] },
+  { endpoint: 'integrations/slack/channel/config:POST', scopes: ['settings.write'] },
+  { endpoint: 'integrations/slack/channel/config:DELETE', scopes: ['settings.write'] },
+  { endpoint: 'integrations/guardian/challenge', scopes: ['settings.write'] },
+  { endpoint: 'integrations/guardian/status', scopes: ['settings.read'] },
+  { endpoint: 'integrations/guardian/outbound/start', scopes: ['settings.write'] },
+  { endpoint: 'integrations/guardian/outbound/resend', scopes: ['settings.write'] },
+  { endpoint: 'integrations/guardian/outbound/cancel', scopes: ['settings.write'] },
+  { endpoint: 'integrations/twilio/config', scopes: ['settings.read'] },
+  { endpoint: 'integrations/twilio/credentials:POST', scopes: ['settings.write'] },
+  { endpoint: 'integrations/twilio/credentials:DELETE', scopes: ['settings.write'] },
+  { endpoint: 'integrations/twilio/numbers', scopes: ['settings.read'] },
+  { endpoint: 'integrations/twilio/numbers/provision', scopes: ['settings.write'] },
+  { endpoint: 'integrations/twilio/numbers/assign', scopes: ['settings.write'] },
+  { endpoint: 'integrations/twilio/numbers/release', scopes: ['settings.write'] },
+  { endpoint: 'integrations/twilio/sms/compliance', scopes: ['settings.read'] },
+  { endpoint: 'integrations/twilio/sms/compliance/tollfree', scopes: ['settings.write'] },
+  { endpoint: 'integrations/twilio/sms/compliance/tollfree:PATCH', scopes: ['settings.write'] },
+  { endpoint: 'integrations/twilio/sms/compliance/tollfree:DELETE', scopes: ['settings.write'] },
+  { endpoint: 'integrations/twilio/sms/test', scopes: ['settings.write'] },
+  { endpoint: 'integrations/twilio/sms/doctor', scopes: ['settings.write'] },
+
+  // Channel readiness
+  { endpoint: 'channels/readiness', scopes: ['settings.read'] },
+  { endpoint: 'channels/readiness/refresh', scopes: ['settings.write'] },
+
+  // Dead letters
+  { endpoint: 'channels/dead-letters', scopes: ['settings.read'] },
+  { endpoint: 'channels/replay', scopes: ['settings.write'] },
+
+  // Secrets
+  { endpoint: 'secrets', scopes: ['settings.write'] },
+
+  // Pairing (authenticated)
+  { endpoint: 'pairing/register', scopes: ['settings.write'] },
+
+  // Apps
+  { endpoint: 'apps/share', scopes: ['settings.write'] },
+  { endpoint: 'apps/shared:GET', scopes: ['settings.read'] },
+  { endpoint: 'apps/shared:DELETE', scopes: ['settings.write'] },
+  { endpoint: 'apps/shared/metadata', scopes: ['settings.read'] },
+
+  // Debug
+  { endpoint: 'debug', scopes: ['settings.read'] },
+
+  // Browser relay
+  { endpoint: 'browser-relay/status', scopes: ['settings.read'] },
+  { endpoint: 'browser-relay/command', scopes: ['settings.write'] },
+
+  // Interfaces
+  { endpoint: 'interfaces', scopes: ['settings.read'] },
+
+  // Trust rule CRUD management
+  { endpoint: 'trust-rules/manage:GET', scopes: ['settings.read'] },
+  { endpoint: 'trust-rules/manage:POST', scopes: ['settings.write'] },
+  { endpoint: 'trust-rules/manage:DELETE', scopes: ['settings.write'] },
+  { endpoint: 'trust-rules/manage:PATCH', scopes: ['settings.write'] },
+
+  // Surface actions
+  { endpoint: 'surface-actions', scopes: ['chat.write'] },
+
+  // Conversation deletion (channel-facing)
+  { endpoint: 'channels/conversation:DELETE', scopes: ['chat.write'] },
+
+  // Delivery ack
+  { endpoint: 'channels/delivery-ack', scopes: ['internal.write'] },
+];
+
+for (const { endpoint, scopes } of ACTOR_ENDPOINTS) {
+  registerPolicy(endpoint, {
+    requiredScopes: scopes,
+    allowedPrincipalTypes: ['actor', 'svc_gateway', 'ipc'],
+  });
+}
+
+// Channel inbound: gateway-only
+registerPolicy('channels/inbound', {
+  requiredScopes: ['ingress.write'],
+  allowedPrincipalTypes: ['svc_gateway'],
+});
+
+// Internal forwarding endpoints: gateway-only
+const INTERNAL_ENDPOINTS = [
+  'internal/twilio/voice-webhook',
+  'internal/twilio/status',
+  'internal/twilio/connect-action',
+  'internal/oauth/callback',
+];
+for (const endpoint of INTERNAL_ENDPOINTS) {
+  registerPolicy(endpoint, {
+    requiredScopes: ['internal.write'],
+    allowedPrincipalTypes: ['svc_gateway'],
+  });
+}

package/src/runtime/auth/scopes.ts

@@ -0,0 +1,64 @@
+/**
+ * Scope profile resolver and scope-check utilities.
+ *
+ * Each scope profile maps to a fixed set of permission scopes. The
+ * mapping is intentionally hard-coded — profile definitions are a
+ * policy decision, not a runtime configuration.
+ */
+
+import type { AuthContext, Scope, ScopeProfile } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Profile -> scope mapping
+// ---------------------------------------------------------------------------
+
+const PROFILE_SCOPES: Record<ScopeProfile, ReadonlySet<Scope>> = {
+  actor_client_v1: new Set<Scope>([
+    'chat.read',
+    'chat.write',
+    'approval.read',
+    'approval.write',
+    'settings.read',
+    'settings.write',
+    'attachments.read',
+    'attachments.write',
+    'calls.read',
+    'calls.write',
+    'feature_flags.read',
+    'feature_flags.write',
+  ]),
+  gateway_ingress_v1: new Set<Scope>([
+    'ingress.write',
+    'internal.write',
+  ]),
+  gateway_service_v1: new Set<Scope>([
+    'chat.write',
+    'settings.read',
+    'settings.write',
+    'attachments.read',
+    'attachments.write',
+    'internal.write',
+  ]),
+  ipc_v1: new Set<Scope>([
+    'ipc.all',
+  ]),
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** Resolve a scope profile name to its set of granted scopes. */
+export function resolveScopeProfile(profile: ScopeProfile): ReadonlySet<Scope> {
+  return PROFILE_SCOPES[profile];
+}
+
+/** Check whether the auth context includes a specific scope. */
+export function hasScope(ctx: AuthContext, scope: Scope): boolean {
+  return ctx.scopes.has(scope);
+}
+
+/** Check whether the auth context includes all of the given scopes. */
+export function hasAllScopes(ctx: AuthContext, ...scopes: Scope[]): boolean {
+  return scopes.every((s) => ctx.scopes.has(s));
+}

package/src/runtime/auth/subject.ts

@@ -0,0 +1,68 @@
+/**
+ * Sub (subject) pattern parser for JWT tokens.
+ *
+ * The sub claim encodes principal type, assistant scope, and optional
+ * actor/session identifiers in a colon-delimited string.
+ */
+
+import type { PrincipalType } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Result types
+// ---------------------------------------------------------------------------
+
+export type ParseSubResult =
+  | {
+      ok: true;
+      principalType: PrincipalType;
+      assistantId: string;
+      actorPrincipalId?: string;
+      sessionId?: string;
+    }
+  | { ok: false; reason: string };
+
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a JWT sub claim into its constituent parts.
+ *
+ * Supported patterns:
+ *   actor:<assistantId>:<actorPrincipalId>
+ *   svc:gateway:<assistantId>
+ *   ipc:<assistantId>:<sessionId>
+ */
+export function parseSub(sub: string): ParseSubResult {
+  if (!sub || typeof sub !== 'string') {
+    return { ok: false, reason: 'sub is empty or not a string' };
+  }
+
+  const parts = sub.split(':');
+
+  if (parts[0] === 'actor' && parts.length === 3) {
+    const [, assistantId, actorPrincipalId] = parts;
+    if (!assistantId || !actorPrincipalId) {
+      return { ok: false, reason: 'actor sub has empty assistantId or actorPrincipalId' };
+    }
+    return { ok: true, principalType: 'actor', assistantId, actorPrincipalId };
+  }
+
+  if (parts[0] === 'svc' && parts[1] === 'gateway' && parts.length === 3) {
+    const assistantId = parts[2];
+    if (!assistantId) {
+      return { ok: false, reason: 'svc:gateway sub has empty assistantId' };
+    }
+    return { ok: true, principalType: 'svc_gateway', assistantId };
+  }
+
+  if (parts[0] === 'ipc' && parts.length === 3) {
+    const [, assistantId, sessionId] = parts;
+    if (!assistantId || !sessionId) {
+      return { ok: false, reason: 'ipc sub has empty assistantId or sessionId' };
+    }
+    return { ok: true, principalType: 'ipc', assistantId, sessionId };
+  }
+
+  return { ok: false, reason: `unrecognized sub pattern: ${sub}` };
+}

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

@@ -0,0 +1,275 @@
+/**
+ * JWT token service for the single-header auth system.
+ *
+ * Mints and verifies standard JWTs (header.payload.signature) using
+ * HMAC-SHA256. Owns the signing key lifecycle (load/create/persist).
+ */
+
+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';
+import { CURRENT_POLICY_EPOCH, isStaleEpoch } from './policy.js';
+import type { ScopeProfile, TokenAudience, TokenClaims } from './types.js';
+
+const log = getLogger('token-service');
+
+// ---------------------------------------------------------------------------
+// Signing key management
+// ---------------------------------------------------------------------------
+
+let _authSigningKey: Buffer | undefined;
+
+/**
+ * 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 atomic-write + chmod 0o600 for safe persistence.
+ */
+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('Auth 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('Auth signing key generated and persisted');
+  return newKey;
+}
+
+function getSigningKey(): Buffer {
+  if (!_authSigningKey) {
+    throw new Error('Auth signing key not initialized — call initAuthSigningKey() during startup');
+  }
+  return _authSigningKey;
+}
+
+/**
+ * Initialize the auth signing key. Called at daemon startup with a key
+ * loaded from disk via loadOrCreateSigningKey(), or by tests with a
+ * deterministic key.
+ */
+export function initAuthSigningKey(key: Buffer): void {
+  _authSigningKey = key;
+}
+
+/**
+ * Check whether the auth signing key has been initialized.
+ *
+ * Useful for out-of-process contexts (CLI) that may run without
+ * daemon startup, where callers need to decide whether they can
+ * mint JWTs or must fall back to the legacy shared-secret token.
+ */
+export function isSigningKeyInitialized(): boolean {
+  return _authSigningKey !== undefined;
+}
+
+// ---------------------------------------------------------------------------
+// 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');
+}
+
+// ---------------------------------------------------------------------------
+// Result types
+// ---------------------------------------------------------------------------
+
+export type VerifyResult =
+  | { ok: true; claims: TokenClaims }
+  | { ok: false; reason: string };
+
+// ---------------------------------------------------------------------------
+// JWT header — static for HMAC-SHA256
+// ---------------------------------------------------------------------------
+
+const JWT_HEADER = base64urlEncode(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+
+// ---------------------------------------------------------------------------
+// Mint
+// ---------------------------------------------------------------------------
+
+/**
+ * Mint a new JWT token with the given parameters.
+ *
+ * Returns the complete JWT string (header.payload.signature).
+ */
+export function mintToken(params: {
+  aud: TokenAudience;
+  sub: string;
+  scope_profile: ScopeProfile;
+  policy_epoch: number;
+  ttlSeconds: number;
+}): string {
+  const now = Math.floor(Date.now() / 1000);
+  const claims: TokenClaims = {
+    iss: 'vellum-auth',
+    aud: params.aud,
+    sub: params.sub,
+    scope_profile: params.scope_profile,
+    exp: now + params.ttlSeconds,
+    policy_epoch: params.policy_epoch,
+    iat: now,
+    jti: randomBytes(16).toString('hex'),
+  };
+
+  const payload = base64urlEncode(JSON.stringify(claims));
+  const sigInput = JWT_HEADER + '.' + payload;
+  const sig = createHmac('sha256', getSigningKey())
+    .update(sigInput)
+    .digest();
+
+  return sigInput + '.' + base64urlEncode(sig);
+}
+
+// ---------------------------------------------------------------------------
+// Verify
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify a JWT token's structural integrity, signature, expiration,
+ * audience, and policy epoch.
+ *
+ * Does NOT check revocation — callers must additionally verify the
+ * token hash against a revocation store if needed.
+ */
+export function verifyToken(token: string, expectedAud: TokenAudience): VerifyResult {
+  const parts = token.split('.');
+  if (parts.length !== 3) {
+    return { ok: false, reason: 'malformed_token: expected 3 dot-separated parts' };
+  }
+
+  const [headerPart, payloadPart, sigPart] = parts;
+
+  // Recompute HMAC over header.payload
+  const sigInput = headerPart + '.' + payloadPart;
+  const expectedSig = createHmac('sha256', getSigningKey())
+    .update(sigInput)
+    .digest();
+  const actualSig = base64urlDecode(sigPart);
+
+  if (expectedSig.length !== actualSig.length) {
+    return { ok: false, reason: 'invalid_signature' };
+  }
+
+  if (!timingSafeEqual(expectedSig, actualSig)) {
+    return { ok: false, reason: 'invalid_signature' };
+  }
+
+  // Decode and parse claims
+  let claims: TokenClaims;
+  try {
+    const decoded = base64urlDecode(payloadPart).toString('utf-8');
+    claims = JSON.parse(decoded) as TokenClaims;
+  } catch {
+    return { ok: false, reason: 'malformed_claims' };
+  }
+
+  // Audience check
+  if (claims.aud !== expectedAud) {
+    return { ok: false, reason: `audience_mismatch: expected ${expectedAud}, got ${claims.aud}` };
+  }
+
+  // Expiration check (claims.exp is in seconds)
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  if (claims.exp <= nowSeconds) {
+    return { ok: false, reason: 'token_expired' };
+  }
+
+  // Policy epoch check
+  if (isStaleEpoch(claims.policy_epoch)) {
+    return { ok: false, reason: 'stale_policy_epoch' };
+  }
+
+  return { ok: true, claims };
+}
+
+// ---------------------------------------------------------------------------
+// Daemon delivery token
+// ---------------------------------------------------------------------------
+
+/**
+ * Mint a short-lived JWT for daemon-to-gateway delivery callbacks.
+ *
+ * Used when the daemon needs to call gateway /deliver/* endpoints. The
+ * gateway's deliver-auth middleware validates aud=vellum-daemon, so both
+ * sides share the same signing key and audience convention.
+ *
+ * sub=svc:daemon:self, scope_profile=gateway_service_v1
+ */
+export function mintDaemonDeliveryToken(): string {
+  return mintToken({
+    aud: 'vellum-daemon',
+    sub: 'svc:daemon:self',
+    scope_profile: 'gateway_service_v1',
+    policy_epoch: CURRENT_POLICY_EPOCH,
+    ttlSeconds: 60,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Edge relay token
+// ---------------------------------------------------------------------------
+
+/**
+ * Mint a short-lived JWT for relay WebSocket connections through the gateway.
+ *
+ * The gateway's relay WS handler validates tokens with validateEdgeToken(),
+ * which expects aud=vellum-gateway. This is distinct from daemon delivery
+ * tokens (aud=vellum-daemon) used for gateway /deliver/* endpoints.
+ *
+ * sub=svc:daemon:self, scope_profile=gateway_service_v1
+ */
+export function mintEdgeRelayToken(): string {
+  return mintToken({
+    aud: 'vellum-gateway',
+    sub: 'svc:daemon:self',
+    scope_profile: 'gateway_service_v1',
+    policy_epoch: CURRENT_POLICY_EPOCH,
+    ttlSeconds: 60,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Hash
+// ---------------------------------------------------------------------------
+
+/** SHA-256 hex digest of a raw token string (for revocation store lookups). */
+export function hashToken(token: string): string {
+  return createHash('sha256').update(token).digest('hex');
+}