@vellumai/assistant 0.4.13 → 0.4.15

package/src/__tests__/actor-token-service.test.ts

@@ -1,7 +1,10 @@
 /**
- * Tests for actor-token mint/verify service, hash-only storage,
- * guardian bootstrap endpoint idempotency, HTTP middleware strict
- * enforcement, and local IPC identity fallback.
+ * Tests for JWT credential service, hash-only storage,
+ * guardian bootstrap endpoint idempotency, and pairing flow.
+ *
+ * Legacy actor-token HMAC middleware tests have been removed --
+ * that middleware is replaced by the JWT auth middleware in
+ * runtime/auth/middleware.ts (tested in auth/middleware.test.ts).
  */
 import { mkdtempSync, realpathSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -16,6 +19,7 @@ mock.module('../util/platform.js', () => ({
   getDataDir: () => testDir,
   getDbPath: () => join(testDir, 'test.db'),
   normalizeAssistantId: (id: string) => id === 'self' ? 'self' : id,
+  readLockfile: () => null,
   isMacOS: () => process.platform === 'darwin',
   isLinux: () => process.platform === 'linux',
   isWindows: () => process.platform === 'win32',
@@ -36,12 +40,6 @@ import {
   createBinding,
   getActiveBinding,
 } from '../memory/guardian-bindings.js';
-import {
-  hashToken,
-  initSigningKey,
-  mintActorToken,
-  verifyActorToken,
-} from '../runtime/actor-token-service.js';
 import {
   createActorTokenRecord,
   findActiveByDeviceBinding,
@@ -49,20 +47,26 @@ import {
   revokeByDeviceBinding,
   revokeByTokenHash,
 } from '../runtime/actor-token-store.js';
+import { resetExternalAssistantIdCache } from '../runtime/auth/external-assistant-id.js';
+import { hashToken, initAuthSigningKey } from '../runtime/auth/token-service.js';
 import { ensureVellumGuardianBinding } from '../runtime/guardian-vellum-migration.js';
-import { resolveLocalIpcGuardianContext } from '../runtime/local-actor-identity.js';
-import {
-  isActorBoundGuardian,
-  isLocalFallbackBoundGuardian,
-  type ServerWithRequestIP,
-  verifyHttpActorToken,
-  verifyHttpActorTokenWithLocalFallback,
-} from '../runtime/middleware/actor-token.js';
+import { resolveLocalIpcAuthContext, resolveLocalIpcGuardianContext } from '../runtime/local-actor-identity.js';
 
 // ---------------------------------------------------------------------------
-// Mock server helpers for loopback IP checks
+// Test signing key
 // ---------------------------------------------------------------------------
 
+const TEST_KEY = Buffer.from('test-signing-key-32-bytes-long!!');
+
+// ---------------------------------------------------------------------------
+// Mock server helpers for loopback IP checks (used by bootstrap tests)
+// ---------------------------------------------------------------------------
+
+/** Bun server shape needed for requestIP. */
+type ServerWithRequestIP = {
+  requestIP(req: Request): { address: string; family: string; port: number } | null;
+};
+
 /** Creates a mock server that returns the given IP for any request. */
 function mockServer(address: string): ServerWithRequestIP {
   return {
@@ -70,20 +74,20 @@ function mockServer(address: string): ServerWithRequestIP {
   };
 }
 
-/** Mock loopback server — returns 127.0.0.1 for all requests. */
+/** Mock loopback server -- returns 127.0.0.1 for all requests. */
 const loopbackServer = mockServer('127.0.0.1');
 
-/** Mock non-loopback server — returns a LAN IP for all requests. */
+/** Mock non-loopback server -- returns a LAN IP for all requests. */
 const nonLoopbackServer = mockServer('192.168.1.50');
 
 initializeDb();
 
 beforeEach(() => {
-  // Reset the signing key to a deterministic value for reproducibility
-  initSigningKey(Buffer.from('test-signing-key-32-bytes-long!!'));
-  // Clear DB state between tests. resetDb closes the connection; initializeDb
-  // re-opens it and ensures tables exist. We then truncate tables that carry
-  // state across tests so each test starts from a clean slate.
+  // Initialize signing key for JWT verification
+  initAuthSigningKey(TEST_KEY);
+  // Reset the external assistant ID cache so tests don't leak state
+  resetExternalAssistantIdCache();
+  // Clear DB state between tests.
   resetDb();
   initializeDb();
   const db = getSqlite();
@@ -95,136 +99,13 @@ afterAll(() => {
   try { rmSync(testDir, { recursive: true, force: true }); } catch {}
 });
 
-// ---------------------------------------------------------------------------
-// Actor token mint/verify
-// ---------------------------------------------------------------------------
-
-describe('actor-token mint/verify', () => {
-  test('mint returns token, hash, and claims with default 30-day TTL', () => {
-    const result = mintActorToken({
-      assistantId: 'self',
-      platform: 'macos',
-      deviceId: 'device-123',
-      guardianPrincipalId: 'principal-abc',
-    });
-
-    expect(result.token).toBeTruthy();
-    expect(result.tokenHash).toBeTruthy();
-    expect(result.claims.assistantId).toBe('self');
-    expect(result.claims.platform).toBe('macos');
-    expect(result.claims.deviceId).toBe('device-123');
-    expect(result.claims.guardianPrincipalId).toBe('principal-abc');
-    expect(result.claims.iat).toBeGreaterThan(0);
-    // Default TTL is 30 days
-    expect(result.claims.exp).not.toBeNull();
-    const thirtyDaysMs = 30 * 24 * 60 * 60 * 1000;
-    expect(result.claims.exp! - result.claims.iat).toBe(thirtyDaysMs);
-    expect(result.claims.jti).toBeTruthy();
-  });
-
-  test('mint returns non-expiring token when ttlMs is explicitly null', () => {
-    const result = mintActorToken({
-      assistantId: 'self',
-      platform: 'macos',
-      deviceId: 'device-no-exp',
-      guardianPrincipalId: 'principal-no-exp',
-      ttlMs: null,
-    });
-
-    expect(result.claims.exp).toBeNull();
-  });
-
-  test('verify succeeds for valid token', () => {
-    const { token } = mintActorToken({
-      assistantId: 'self',
-      platform: 'ios',
-      deviceId: 'device-456',
-      guardianPrincipalId: 'principal-def',
-    });
-
-    const result = verifyActorToken(token);
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.claims.assistantId).toBe('self');
-      expect(result.claims.platform).toBe('ios');
-    }
-  });
-
-  test('verify fails for tampered token', () => {
-    const { token } = mintActorToken({
-      assistantId: 'self',
-      platform: 'macos',
-      deviceId: 'device-789',
-      guardianPrincipalId: 'principal-ghi',
-    });
-
-    // Tamper with the payload
-    const parts = token.split('.');
-    const tampered = parts[0] + 'X' + '.' + parts[1];
-    const result = verifyActorToken(tampered);
-    expect(result.ok).toBe(false);
-  });
-
-  test('verify fails for malformed token', () => {
-    const result = verifyActorToken('not-a-valid-token');
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.reason).toBe('malformed_token');
-    }
-  });
-
-  test('verify fails for expired token', () => {
-    const { token } = mintActorToken({
-      assistantId: 'self',
-      platform: 'macos',
-      deviceId: 'device-exp',
-      guardianPrincipalId: 'principal-exp',
-      ttlMs: -1000, // Already expired
-    });
-
-    const result = verifyActorToken(token);
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.reason).toBe('token_expired');
-    }
-  });
-
-  test('hashToken produces consistent SHA-256 hex', () => {
-    const hash1 = hashToken('test-token');
-    const hash2 = hashToken('test-token');
-    expect(hash1).toBe(hash2);
-    expect(hash1.length).toBe(64); // SHA-256 hex = 64 chars
-  });
-
-  test('different tokens produce different hashes', () => {
-    const { token: t1 } = mintActorToken({
-      assistantId: 'self',
-      platform: 'macos',
-      deviceId: 'dev1',
-      guardianPrincipalId: 'p1',
-    });
-    const { token: t2 } = mintActorToken({
-      assistantId: 'self',
-      platform: 'macos',
-      deviceId: 'dev2',
-      guardianPrincipalId: 'p2',
-    });
-    expect(hashToken(t1)).not.toBe(hashToken(t2));
-  });
-});
-
 // ---------------------------------------------------------------------------
 // Hash-only storage
 // ---------------------------------------------------------------------------
 
 describe('actor-token store (hash-only)', () => {
   test('createActorTokenRecord stores hash, never raw token', () => {
-    const { tokenHash } = mintActorToken({
-      assistantId: 'self',
-      platform: 'macos',
-      deviceId: 'dev-store',
-      guardianPrincipalId: 'principal-store',
-    });
+    const tokenHash = hashToken('test-token-for-store');
 
     const record = createActorTokenRecord({
       tokenHash,
@@ -237,19 +118,13 @@ describe('actor-token store (hash-only)', () => {
 
     expect(record.tokenHash).toBe(tokenHash);
     expect(record.status).toBe('active');
-    // Verify the record can be found by hash
     const found = findActiveByTokenHash(tokenHash);
     expect(found).not.toBeNull();
     expect(found!.tokenHash).toBe(tokenHash);
   });
 
   test('findActiveByDeviceBinding returns matching record', () => {
-    const { tokenHash } = mintActorToken({
-      assistantId: 'self',
-      platform: 'ios',
-      deviceId: 'dev-bind',
-      guardianPrincipalId: 'principal-bind',
-    });
+    const tokenHash = hashToken('test-token-for-binding');
 
     createActorTokenRecord({
       tokenHash,
@@ -266,12 +141,7 @@ describe('actor-token store (hash-only)', () => {
   });
 
   test('revokeByDeviceBinding marks tokens as revoked', () => {
-    const { tokenHash } = mintActorToken({
-      assistantId: 'self',
-      platform: 'macos',
-      deviceId: 'dev-revoke',
-      guardianPrincipalId: 'principal-revoke',
-    });
+    const tokenHash = hashToken('test-token-for-revoke');
 
     createActorTokenRecord({
       tokenHash,
@@ -285,18 +155,12 @@ describe('actor-token store (hash-only)', () => {
     const count = revokeByDeviceBinding('self', 'principal-revoke', 'hashed-dev-revoke');
     expect(count).toBe(1);
 
-    // Should no longer be found as active
     const found = findActiveByTokenHash(tokenHash);
     expect(found).toBeNull();
   });
 
   test('revokeByTokenHash revokes a single token', () => {
-    const { tokenHash } = mintActorToken({
-      assistantId: 'self',
-      platform: 'macos',
-      deviceId: 'dev-single',
-      guardianPrincipalId: 'principal-single',
-    });
+    const tokenHash = hashToken('test-token-for-single-revoke');
 
     createActorTokenRecord({
       tokenHash,
@@ -334,7 +198,6 @@ describe('guardian vellum migration', () => {
   });
 
   test('ensureVellumGuardianBinding preserves existing bindings for other channels', () => {
-    // Create a telegram binding
     createBinding({
       assistantId: 'self',
       channel: 'telegram',
@@ -344,15 +207,12 @@ describe('guardian vellum migration', () => {
       verifiedVia: 'challenge',
     });
 
-    // Now backfill vellum
     ensureVellumGuardianBinding('self');
 
-    // Telegram binding should still exist
     const tgBinding = getActiveBinding('self', 'telegram');
     expect(tgBinding).not.toBeNull();
     expect(tgBinding!.guardianExternalUserId).toBe('tg-user-123');
 
-    // Vellum binding should also exist
     const vBinding = getActiveBinding('self', 'vellum');
     expect(vBinding).not.toBeNull();
   });
@@ -364,8 +224,6 @@ describe('guardian vellum migration', () => {
 
 describe('bootstrap endpoint idempotency', () => {
   test('calling bootstrap twice returns same guardianPrincipalId', async () => {
-    // We test the logic used by the bootstrap route handler directly
-    // rather than spinning up a full HTTP server.
     const { handleGuardianBootstrap } = await import('../runtime/routes/guardian-bootstrap-routes.js');
 
     const req1 = new Request('http://localhost/v1/integrations/guardian/vellum/bootstrap', {
@@ -378,7 +236,7 @@ describe('bootstrap endpoint idempotency', () => {
     expect(res1.status).toBe(200);
     const body1 = await res1.json() as Record<string, unknown>;
     expect(body1.guardianPrincipalId).toBeTruthy();
-    expect(body1.actorToken).toBeTruthy();
+    expect(body1.accessToken).toBeTruthy();
     expect(body1.isNew).toBe(true);
 
     // Second call with same device
@@ -392,9 +250,9 @@ describe('bootstrap endpoint idempotency', () => {
     expect(res2.status).toBe(200);
     const body2 = await res2.json() as Record<string, unknown>;
     expect(body2.guardianPrincipalId).toBe(body1.guardianPrincipalId);
-    expect(body2.actorToken).toBeTruthy();
+    expect(body2.accessToken).toBeTruthy();
     // New token minted (previous revoked), but same principal
-    expect(body2.actorToken).not.toBe(body1.actorToken);
+    expect(body2.accessToken).not.toBe(body1.accessToken);
     expect(body2.isNew).toBe(false);
   });
 
@@ -447,196 +305,25 @@ describe('bootstrap endpoint idempotency', () => {
 
     // Same principal, different tokens
     expect(body2.guardianPrincipalId).toBe(body1.guardianPrincipalId);
-    expect(body2.actorToken).not.toBe(body1.actorToken);
+    expect(body2.accessToken).not.toBe(body1.accessToken);
   });
-});
 
-// ---------------------------------------------------------------------------
-// HTTP middleware strict enforcement
-// ---------------------------------------------------------------------------
-
-describe('HTTP actor token middleware (strict enforcement)', () => {
-  test('rejects request without X-Actor-Token header', () => {
-    const req = new Request('http://localhost/v1/messages', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-    });
-
-    const result = verifyHttpActorToken(req);
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.status).toBe(401);
-      expect(result.message).toContain('Missing X-Actor-Token');
-    }
-  });
-
-  test('rejects request with invalid (tampered) token', () => {
-    const { token } = mintActorToken({
-      assistantId: 'self',
-      platform: 'macos',
-      deviceId: 'device-tamper',
-      guardianPrincipalId: 'principal-tamper',
-    });
-
-    const parts = token.split('.');
-    const tampered = parts[0] + 'XXXXXX.' + parts[1];
-
-    const req = new Request('http://localhost/v1/messages', {
-      method: 'POST',
-      headers: { 'X-Actor-Token': tampered },
-    });
-
-    const result = verifyHttpActorToken(req);
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.status).toBe(401);
-    }
-  });
-
-  test('rejects request with revoked token', () => {
-    const principalId = ensureVellumGuardianBinding('self');
-    const { token, tokenHash } = mintActorToken({
-      assistantId: 'self',
-      platform: 'macos',
-      deviceId: 'device-revoked',
-      guardianPrincipalId: principalId,
-    });
-
-    createActorTokenRecord({
-      tokenHash,
-      assistantId: 'self',
-      guardianPrincipalId: principalId,
-      hashedDeviceId: 'hashed-device-revoked',
-      platform: 'macos',
-      issuedAt: Date.now(),
-    });
-
-    // Revoke the token
-    revokeByTokenHash(tokenHash);
-
-    const req = new Request('http://localhost/v1/messages', {
-      method: 'POST',
-      headers: { 'X-Actor-Token': token },
-    });
-
-    const result = verifyHttpActorToken(req);
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.status).toBe(401);
-      expect(result.message).toContain('no longer active');
-    }
-  });
-
-  test('accepts request with valid active token and resolves guardian context', () => {
-    const principalId = ensureVellumGuardianBinding('self');
-    const { token, tokenHash } = mintActorToken({
-      assistantId: 'self',
-      platform: 'macos',
-      deviceId: 'device-valid',
-      guardianPrincipalId: principalId,
-    });
-
-    createActorTokenRecord({
-      tokenHash,
-      assistantId: 'self',
-      guardianPrincipalId: principalId,
-      hashedDeviceId: 'hashed-device-valid',
-      platform: 'macos',
-      issuedAt: Date.now(),
-    });
-
-    const req = new Request('http://localhost/v1/messages', {
-      method: 'POST',
-      headers: { 'X-Actor-Token': token },
-    });
-
-    const result = verifyHttpActorToken(req);
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.claims.assistantId).toBe('self');
-      expect(result.claims.guardianPrincipalId).toBe(principalId);
-      expect(result.guardianContext).toBeTruthy();
-      expect(result.guardianContext.trustClass).toBe('guardian');
-    }
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Local IPC fallback (verifyHttpActorTokenWithLocalFallback)
-// ---------------------------------------------------------------------------
-
-describe('HTTP actor token local fallback', () => {
-  test('falls back to local IPC identity when no actor token and no forwarding header', () => {
-    ensureVellumGuardianBinding('self');
+  test('bootstrap access token is a 3-part JWT', async () => {
+    const { handleGuardianBootstrap } = await import('../runtime/routes/guardian-bootstrap-routes.js');
 
-    const req = new Request('http://localhost/v1/messages', {
+    const req = new Request('http://localhost/v1/integrations/guardian/vellum/bootstrap', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ platform: 'macos', deviceId: 'test-device-jwt' }),
     });
 
-    const result = verifyHttpActorTokenWithLocalFallback(req, loopbackServer);
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.guardianContext.trustClass).toBe('guardian');
-      // localFallback should be true when claims are null
-      if ('localFallback' in result) {
-        expect(result.localFallback).toBe(true);
-        expect(result.claims).toBeNull();
-      }
-    }
-  });
-
-  test('rejects gateway-proxied request without actor token (X-Forwarded-For present)', () => {
-    ensureVellumGuardianBinding('self');
-
-    const req = new Request('http://localhost/v1/messages', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'X-Forwarded-For': '1.2.3.4',
-      },
-    });
-
-    const result = verifyHttpActorTokenWithLocalFallback(req, loopbackServer);
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.status).toBe(401);
-      expect(result.message).toContain('Proxied requests require actor identity');
-    }
-  });
-
-  test('uses strict verification when actor token is present even with X-Forwarded-For', () => {
-    const principalId = ensureVellumGuardianBinding('self');
-    const { token, tokenHash } = mintActorToken({
-      assistantId: 'self',
-      platform: 'ios',
-      deviceId: 'device-proxied',
-      guardianPrincipalId: principalId,
-    });
-
-    createActorTokenRecord({
-      tokenHash,
-      assistantId: 'self',
-      guardianPrincipalId: principalId,
-      hashedDeviceId: 'hashed-device-proxied',
-      platform: 'ios',
-      issuedAt: Date.now(),
-    });
-
-    const req = new Request('http://localhost/v1/messages', {
-      method: 'POST',
-      headers: {
-        'X-Actor-Token': token,
-        'X-Forwarded-For': '1.2.3.4',
-      },
-    });
-
-    const result = verifyHttpActorTokenWithLocalFallback(req, loopbackServer);
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.claims).not.toBeNull();
-      expect(result.guardianContext.trustClass).toBe('guardian');
-    }
+    const res = await handleGuardianBootstrap(req, loopbackServer);
+    expect(res.status).toBe(200);
+    const body = await res.json() as Record<string, unknown>;
+    const accessToken = body.accessToken as string;
+    expect(accessToken).toBeTruthy();
+    // JWTs have 3 dot-separated parts
+    expect(accessToken.split('.').length).toBe(3);
   });
 });
 
@@ -654,9 +341,6 @@ describe('resolveLocalIpcGuardianContext', () => {
   });
 
   test('returns guardian context with principal when no vellum binding exists (pre-bootstrap self-heal)', () => {
-    // No binding created — fresh DB state. Pre-bootstrap path self-heals
-    // by creating a vellum binding, then resolves through the shared pipeline
-    // with correct field names (conversationExternalId, actorExternalId).
     const ctx = resolveLocalIpcGuardianContext();
     expect(ctx.trustClass).toBe('guardian');
     expect(ctx.sourceChannel).toBe('vellum');
@@ -670,13 +354,63 @@ describe('resolveLocalIpcGuardianContext', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Local IPC AuthContext resolution
+// ---------------------------------------------------------------------------
+
+describe('resolveLocalIpcAuthContext', () => {
+  test('returns AuthContext with ipc principal type', () => {
+    const ctx = resolveLocalIpcAuthContext('session-123');
+    expect(ctx.principalType).toBe('ipc');
+  });
+
+  test('subject follows ipc:self:<sessionId> pattern', () => {
+    const ctx = resolveLocalIpcAuthContext('session-abc');
+    expect(ctx.subject).toBe('ipc:self:session-abc');
+  });
+
+  test('assistantId is always self', () => {
+    const ctx = resolveLocalIpcAuthContext('session-123');
+    expect(ctx.assistantId).toBe('self');
+  });
+
+  test('uses ipc_v1 scope profile with ipc.all scope', () => {
+    const ctx = resolveLocalIpcAuthContext('session-123');
+    expect(ctx.scopeProfile).toBe('ipc_v1');
+    expect(ctx.scopes.has('ipc.all')).toBe(true);
+  });
+
+  test('enriches actorPrincipalId from vellum guardian binding when present', () => {
+    ensureVellumGuardianBinding('self');
+    const binding = getActiveBinding('self', 'vellum');
+    expect(binding).toBeTruthy();
+
+    const ctx = resolveLocalIpcAuthContext('session-123');
+    expect(ctx.actorPrincipalId).toBe(binding!.guardianExternalUserId);
+  });
+
+  test('actorPrincipalId is undefined when no vellum binding exists', () => {
+    // Reset DB to ensure no binding
+    resetDb();
+    initializeDb();
+
+    const ctx = resolveLocalIpcAuthContext('session-123');
+    // When no binding exists, actorPrincipalId is not set
+    expect(ctx.actorPrincipalId).toBeUndefined();
+  });
+
+  test('sessionId matches the provided argument', () => {
+    const ctx = resolveLocalIpcAuthContext('my-session');
+    expect(ctx.sessionId).toBe('my-session');
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Pairing actor-token flow
 // ---------------------------------------------------------------------------
 
-describe('pairing actor-token flow', () => {
-  test('mintPairingActorToken returns actor token in approved pairing status poll', async () => {
-    // Set up a vellum guardian binding (required for pairing token mint)
+describe('pairing credential flow', () => {
+  test('mintPairingCredentials returns access token in approved pairing status poll', async () => {
     ensureVellumGuardianBinding('self');
 
     const { PairingStore } = await import('../daemon/pairing-store.js');
@@ -689,7 +423,6 @@ describe('pairing actor-token flow', () => {
     const pairingSecret = 'test-secret-123';
     const bearerToken = 'test-bearer';
 
-    // Register a pairing request
     store.register({
       pairingRequestId,
       pairingSecret,
@@ -703,7 +436,6 @@ describe('pairing actor-token flow', () => {
       pairingBroadcast: () => {},
     };
 
-    // iOS initiates pairing
     const pairReq = new Request('http://localhost/v1/pairing/request', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -720,22 +452,20 @@ describe('pairing actor-token flow', () => {
     const pairBody = await pairRes.json() as Record<string, unknown>;
     expect(pairBody.status).toBe('pending');
 
-    // macOS approves the pairing
     store.approve(pairingRequestId, bearerToken);
 
-    // iOS polls for status — should get approved with actor token
     const statusUrl = new URL(`http://localhost/v1/pairing/status?id=${pairingRequestId}&secret=${pairingSecret}`);
     const statusRes = handlePairingStatus(statusUrl, ctx);
     expect(statusRes.status).toBe(200);
     const statusBody = await statusRes.json() as Record<string, unknown>;
     expect(statusBody.status).toBe('approved');
-    expect(statusBody.actorToken).toBeTruthy();
+    expect(statusBody.accessToken).toBeTruthy();
     expect(statusBody.bearerToken).toBe(bearerToken);
 
     store.stop();
   });
 
-  test('approved actor token is available within 5 min TTL window', async () => {
+  test('approved access token is available within 5 min TTL window', async () => {
     ensureVellumGuardianBinding('self');
 
     const { PairingStore } = await import('../daemon/pairing-store.js');
@@ -761,7 +491,6 @@ describe('pairing actor-token flow', () => {
       pairingBroadcast: () => {},
     };
 
-    // iOS initiates pairing
     const pairReq = new Request('http://localhost/v1/pairing/request', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -776,17 +505,15 @@ describe('pairing actor-token flow', () => {
     await handlePairingRequest(pairReq, ctx);
     store.approve(pairingRequestId, bearerToken);
 
-    // First poll — mints the token
     const statusUrl = new URL(`http://localhost/v1/pairing/status?id=${pairingRequestId}&secret=${pairingSecret}`);
     const firstRes = handlePairingStatus(statusUrl, ctx);
     const firstBody = await firstRes.json() as Record<string, unknown>;
-    const firstToken = firstBody.actorToken as string;
+    const firstToken = firstBody.accessToken as string;
     expect(firstToken).toBeTruthy();
 
-    // Second poll — same token from cache
     const secondRes = handlePairingStatus(statusUrl, ctx);
     const secondBody = await secondRes.json() as Record<string, unknown>;
-    expect(secondBody.actorToken).toBe(firstToken);
+    expect(secondBody.accessToken).toBe(firstToken);
 
     store.stop();
   });
@@ -822,7 +549,6 @@ describe('pairing actor-token flow', () => {
       pairingBroadcast: () => {},
     };
 
-    // iOS initiates pairing so the request is device-bound
     const pairReq = new Request('http://localhost/v1/pairing/request', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -837,11 +563,9 @@ describe('pairing actor-token flow', () => {
     const pairRes = await handlePairingRequest(pairReq, ctx);
     expect(pairRes.status).toBe(200);
 
-    // macOS approves, then transient in-memory pairing state is lost (e.g. restart)
     store.approve(pairingRequestId, bearerToken);
     cleanupPairingState(pairingRequestId);
 
-    // Poll includes deviceId so token mint can recover from persisted hashedDeviceId
     const statusUrl = new URL(
       `http://localhost/v1/pairing/status?id=${pairingRequestId}&secret=${pairingSecret}&deviceId=${encodeURIComponent(deviceId)}`,
     );
@@ -850,7 +574,7 @@ describe('pairing actor-token flow', () => {
     const statusBody = await statusRes.json() as Record<string, unknown>;
 
     expect(statusBody.status).toBe('approved');
-    expect(statusBody.actorToken).toBeTruthy();
+    expect(statusBody.accessToken).toBeTruthy();
     expect(statusBody.bearerToken).toBe(bearerToken);
 
     store.stop();
@@ -896,8 +620,6 @@ describe('pairing actor-token flow', () => {
     await handlePairingRequest(pairReq, ctx);
     store.approve(pairingRequestId, bearerToken);
 
-    // Fire two status polls simultaneously — both synchronous so they
-    // should not double-mint
     const statusUrl = new URL(`http://localhost/v1/pairing/status?id=${pairingRequestId}&secret=${pairingSecret}`);
     const res1 = handlePairingStatus(statusUrl, ctx);
     const res2 = handlePairingStatus(statusUrl, ctx);
@@ -905,100 +627,15 @@ describe('pairing actor-token flow', () => {
     const body1 = await res1.json() as Record<string, unknown>;
     const body2 = await res2.json() as Record<string, unknown>;
 
-    // Both should succeed and return the same token (second sees the cached token)
     expect(body1.status).toBe('approved');
     expect(body2.status).toBe('approved');
-    expect(body1.actorToken).toBeTruthy();
-    // The second poll should return the same cached token
-    expect(body2.actorToken).toBe(body1.actorToken);
+    expect(body1.accessToken).toBeTruthy();
+    expect(body2.accessToken).toBe(body1.accessToken);
 
     store.stop();
   });
 });
 
-// ---------------------------------------------------------------------------
-// Loopback IP check tests
-// ---------------------------------------------------------------------------
-
-describe('loopback IP check (verifyHttpActorTokenWithLocalFallback)', () => {
-  test('succeeds with mock server returning loopback IP', () => {
-    ensureVellumGuardianBinding('self');
-
-    const req = new Request('http://localhost/v1/messages', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-    });
-
-    const result = verifyHttpActorTokenWithLocalFallback(req, loopbackServer);
-    expect(result.ok).toBe(true);
-    if (result.ok && 'localFallback' in result) {
-      expect(result.localFallback).toBe(true);
-      expect(result.guardianContext.trustClass).toBe('guardian');
-    }
-  });
-
-  test('succeeds with mock server returning IPv6 loopback (::1)', () => {
-    ensureVellumGuardianBinding('self');
-
-    const req = new Request('http://localhost/v1/messages', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-    });
-
-    const ipv6LoopbackServer = mockServer('::1');
-    const result = verifyHttpActorTokenWithLocalFallback(req, ipv6LoopbackServer);
-    expect(result.ok).toBe(true);
-  });
-
-  test('succeeds with mock server returning IPv4-mapped IPv6 loopback', () => {
-    ensureVellumGuardianBinding('self');
-
-    const req = new Request('http://localhost/v1/messages', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-    });
-
-    const mappedLoopbackServer = mockServer('::ffff:127.0.0.1');
-    const result = verifyHttpActorTokenWithLocalFallback(req, mappedLoopbackServer);
-    expect(result.ok).toBe(true);
-  });
-
-  test('returns 401 with mock server returning non-loopback IP', () => {
-    ensureVellumGuardianBinding('self');
-
-    const req = new Request('http://localhost/v1/messages', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-    });
-
-    const result = verifyHttpActorTokenWithLocalFallback(req, nonLoopbackServer);
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.status).toBe(401);
-      expect(result.message).toContain('Non-loopback requests require actor identity');
-    }
-  });
-
-  test('returns 401 with X-Forwarded-For header present', () => {
-    ensureVellumGuardianBinding('self');
-
-    const req = new Request('http://localhost/v1/messages', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'X-Forwarded-For': '10.0.0.1',
-      },
-    });
-
-    const result = verifyHttpActorTokenWithLocalFallback(req, loopbackServer);
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.status).toBe(401);
-      expect(result.message).toContain('Proxied requests require actor identity');
-    }
-  });
-});
-
 // ---------------------------------------------------------------------------
 // Bootstrap loopback guard tests
 // ---------------------------------------------------------------------------
@@ -1050,54 +687,3 @@ describe('bootstrap loopback guard', () => {
     expect(res.status).toBe(200);
   });
 });
-
-// ---------------------------------------------------------------------------
-// Utility function tests (isActorBoundGuardian, isLocalFallbackBoundGuardian)
-// ---------------------------------------------------------------------------
-
-describe('utility functions', () => {
-  test('isActorBoundGuardian returns true when actor matches bound guardian', () => {
-    const principalId = ensureVellumGuardianBinding('self');
-    const { claims } = mintActorToken({
-      assistantId: 'self',
-      platform: 'macos',
-      deviceId: 'device-bound',
-      guardianPrincipalId: principalId,
-    });
-
-    expect(isActorBoundGuardian(claims)).toBe(true);
-  });
-
-  test('isActorBoundGuardian returns false for mismatched principal', () => {
-    ensureVellumGuardianBinding('self');
-    const { claims } = mintActorToken({
-      assistantId: 'self',
-      platform: 'macos',
-      deviceId: 'device-mismatch',
-      guardianPrincipalId: 'wrong-principal-id',
-    });
-
-    expect(isActorBoundGuardian(claims)).toBe(false);
-  });
-
-  test('isActorBoundGuardian returns false when no vellum binding exists', () => {
-    const { claims } = mintActorToken({
-      assistantId: 'self',
-      platform: 'macos',
-      deviceId: 'device-no-binding',
-      guardianPrincipalId: 'some-principal',
-    });
-
-    expect(isActorBoundGuardian(claims)).toBe(false);
-  });
-
-  test('isLocalFallbackBoundGuardian returns true when vellum binding exists', () => {
-    ensureVellumGuardianBinding('self');
-    expect(isLocalFallbackBoundGuardian()).toBe(true);
-  });
-
-  test('isLocalFallbackBoundGuardian returns true even without binding (pre-bootstrap fallback)', () => {
-    // No binding — local user is inherently the guardian of their own machine
-    expect(isLocalFallbackBoundGuardian()).toBe(true);
-  });
-});