@ontrails/permits 1.0.0-beta.12 → 1.0.0-beta.14

package/src/__tests__/{adapter.test.ts → connector.test.ts}

@@ -2,10 +2,10 @@ import { describe, expect, test } from 'bun:test';
 
 import { Result } from '@ontrails/core';
 
-import type { AuthAdapter, AuthError } from '../adapter.js';
+import type { AuthConnector, AuthError } from '../connectors/connector.js';
 import type { PermitExtractionInput } from '../extraction.js';
 import type { Permit } from '../permit.js';
-import { createJwtAdapter } from '../adapters/jwt.js';
+import { createJwtConnector } from '../connectors/jwt.js';
 
 // ---------------------------------------------------------------------------
 // Test helper: sign a JWT with HMAC-SHA256 using crypto.subtle
@@ -58,37 +58,37 @@ const testInput = (
   overrides?: Partial<PermitExtractionInput>
 ): PermitExtractionInput => ({
   requestId: 'test-req',
-  surface: 'http',
+  trailhead: 'http',
   ...overrides,
 });
 
-describe('AuthAdapter interface', () => {
-  test('accepts a valid adapter implementation', async () => {
-    const adapter: AuthAdapter = {
-      // oxlint-disable-next-line require-await -- stub adapter for type test
+describe('AuthConnector interface', () => {
+  test('accepts a valid connector implementation', async () => {
+    const connector: AuthConnector = {
+      // oxlint-disable-next-line require-await -- stub connector for type test
       authenticate: async (_input: PermitExtractionInput) => Result.ok(null),
     };
-    const result = await adapter.authenticate(testInput());
+    const result = await connector.authenticate(testInput());
     expect(result.isOk()).toBe(true);
   });
 });
 
 /* oxlint-disable max-statements -- test suite with multiple concern groups */
-describe('createJwtAdapter', () => {
-  test('returns an AuthAdapter', () => {
-    const adapter = createJwtAdapter({ secret: TEST_SECRET });
-    expect(adapter).toBeDefined();
-    expect(adapter.authenticate).toBeInstanceOf(Function);
+describe('createJwtConnector', () => {
+  test('returns an AuthConnector', () => {
+    const connector = createJwtConnector({ secret: TEST_SECRET });
+    expect(connector).toBeDefined();
+    expect(connector.authenticate).toBeInstanceOf(Function);
   });
 
   test('verifies a valid HS256 token and returns a Permit', async () => {
-    const adapter = createJwtAdapter({ secret: TEST_SECRET });
+    const connector = createJwtConnector({ secret: TEST_SECRET });
     const now = Math.floor(Date.now() / 1000);
     const token = await signJwt(
       { exp: now + 3600, scope: 'read write', sub: 'user-123' },
       TEST_SECRET
     );
-    const result = await adapter.authenticate(
+    const result = await connector.authenticate(
       testInput({ bearerToken: token })
     );
     expect(result.isOk()).toBe(true);
@@ -99,13 +99,13 @@ describe('createJwtAdapter', () => {
   });
 
   test('rejects an expired token', async () => {
-    const adapter = createJwtAdapter({ secret: TEST_SECRET });
+    const connector = createJwtConnector({ secret: TEST_SECRET });
     const past = Math.floor(Date.now() / 1000) - 3600;
     const token = await signJwt(
       { exp: past, sub: 'user-expired' },
       TEST_SECRET
     );
-    const result = await adapter.authenticate(
+    const result = await connector.authenticate(
       testInput({ bearerToken: token })
     );
     expect(result.isErr()).toBe(true);
@@ -114,13 +114,13 @@ describe('createJwtAdapter', () => {
   });
 
   test('rejects an invalid signature', async () => {
-    const adapter = createJwtAdapter({ secret: TEST_SECRET });
+    const connector = createJwtConnector({ secret: TEST_SECRET });
     const now = Math.floor(Date.now() / 1000);
     const token = await signJwt(
       { exp: now + 3600, sub: 'user-bad-sig' },
       'wrong-secret'
     );
-    const result = await adapter.authenticate(
+    const result = await connector.authenticate(
       testInput({ bearerToken: token })
     );
     expect(result.isErr()).toBe(true);
@@ -129,13 +129,13 @@ describe('createJwtAdapter', () => {
   });
 
   test('rejects tokens with a missing subject claim', async () => {
-    const adapter = createJwtAdapter({ secret: TEST_SECRET });
+    const connector = createJwtConnector({ secret: TEST_SECRET });
     const now = Math.floor(Date.now() / 1000);
     const token = await signJwt(
       { exp: now + 3600, scope: 'read' },
       TEST_SECRET
     );
-    const result = await adapter.authenticate(
+    const result = await connector.authenticate(
       testInput({ bearerToken: token })
     );
     expect(result.isErr()).toBe(true);
@@ -145,7 +145,7 @@ describe('createJwtAdapter', () => {
   });
 
   test('extracts scopes from token claims', async () => {
-    const adapter = createJwtAdapter({
+    const connector = createJwtConnector({
       scopesClaim: 'permissions',
       secret: TEST_SECRET,
     });
@@ -158,7 +158,7 @@ describe('createJwtAdapter', () => {
       },
       TEST_SECRET
     );
-    const result = await adapter.authenticate(
+    const result = await connector.authenticate(
       testInput({ bearerToken: token })
     );
     expect(result.isOk()).toBe(true);
@@ -167,13 +167,13 @@ describe('createJwtAdapter', () => {
   });
 
   test('extracts roles from token claims', async () => {
-    const adapter = createJwtAdapter({ secret: TEST_SECRET });
+    const connector = createJwtConnector({ secret: TEST_SECRET });
     const now = Math.floor(Date.now() / 1000);
     const token = await signJwt(
       { exp: now + 3600, roles: ['admin', 'editor'], sub: 'user-roles' },
       TEST_SECRET
     );
-    const result = await adapter.authenticate(
+    const result = await connector.authenticate(
       testInput({ bearerToken: token })
     );
     expect(result.isOk()).toBe(true);
@@ -182,14 +182,14 @@ describe('createJwtAdapter', () => {
   });
 
   test('returns null for missing credentials', async () => {
-    const adapter = createJwtAdapter({ secret: TEST_SECRET });
-    const result = await adapter.authenticate(testInput());
+    const connector = createJwtConnector({ secret: TEST_SECRET });
+    const result = await connector.authenticate(testInput());
     expect(result.isOk()).toBe(true);
     expect(result.unwrap()).toBeNull();
   });
 
   test('checks issuer claim when configured', async () => {
-    const adapter = createJwtAdapter({
+    const connector = createJwtConnector({
       issuer: 'https://auth.example.com',
       secret: TEST_SECRET,
     });
@@ -198,7 +198,7 @@ describe('createJwtAdapter', () => {
       { exp: now + 3600, iss: 'https://evil.example.com', sub: 'user-iss' },
       TEST_SECRET
     );
-    const result = await adapter.authenticate(
+    const result = await connector.authenticate(
       testInput({ bearerToken: token })
     );
     expect(result.isErr()).toBe(true);
@@ -207,7 +207,7 @@ describe('createJwtAdapter', () => {
   });
 
   test('checks audience claim when configured', async () => {
-    const adapter = createJwtAdapter({
+    const connector = createJwtConnector({
       audience: 'my-api',
       secret: TEST_SECRET,
     });
@@ -216,7 +216,7 @@ describe('createJwtAdapter', () => {
       { aud: 'other-api', exp: now + 3600, sub: 'user-aud' },
       TEST_SECRET
     );
-    const result = await adapter.authenticate(
+    const result = await connector.authenticate(
       testInput({ bearerToken: token })
     );
     expect(result.isErr()).toBe(true);
@@ -225,7 +225,7 @@ describe('createJwtAdapter', () => {
   });
 
   test('accepts array-format audience containing configured value', async () => {
-    const adapter = createJwtAdapter({
+    const connector = createJwtConnector({
       audience: 'my-api',
       secret: TEST_SECRET,
     });
@@ -234,7 +234,7 @@ describe('createJwtAdapter', () => {
       { aud: ['my-api', 'account'], exp: now + 3600, sub: 'user-arr-aud' },
       TEST_SECRET
     );
-    const result = await adapter.authenticate(
+    const result = await connector.authenticate(
       testInput({ bearerToken: token })
     );
     expect(result.isOk()).toBe(true);
@@ -243,7 +243,7 @@ describe('createJwtAdapter', () => {
   });
 
   test('rejects array-format audience not containing configured value', async () => {
-    const adapter = createJwtAdapter({
+    const connector = createJwtConnector({
       audience: 'my-api',
       secret: TEST_SECRET,
     });
@@ -252,7 +252,7 @@ describe('createJwtAdapter', () => {
       { aud: ['other-api', 'account'], exp: now + 3600, sub: 'user-no-aud' },
       TEST_SECRET
     );
-    const result = await adapter.authenticate(
+    const result = await connector.authenticate(
       testInput({ bearerToken: token })
     );
     expect(result.isErr()).toBe(true);
@@ -261,13 +261,13 @@ describe('createJwtAdapter', () => {
   });
 
   test('extracts scopes from array-format claim', async () => {
-    const adapter = createJwtAdapter({ secret: TEST_SECRET });
+    const connector = createJwtConnector({ secret: TEST_SECRET });
     const now = Math.floor(Date.now() / 1000);
     const token = await signJwt(
       { exp: now + 3600, scope: ['read', 'write'], sub: 'user-arr-scope' },
       TEST_SECRET
     );
-    const result = await adapter.authenticate(
+    const result = await connector.authenticate(
       testInput({ bearerToken: token })
     );
     expect(result.isOk()).toBe(true);
@@ -276,7 +276,7 @@ describe('createJwtAdapter', () => {
   });
 
   test('filters empty strings from array-format scope claims', async () => {
-    const adapter = createJwtAdapter({ secret: TEST_SECRET });
+    const connector = createJwtConnector({ secret: TEST_SECRET });
     const now = Math.floor(Date.now() / 1000);
     const token = await signJwt(
       {
@@ -286,7 +286,7 @@ describe('createJwtAdapter', () => {
       },
       TEST_SECRET
     );
-    const result = await adapter.authenticate(
+    const result = await connector.authenticate(
       testInput({ bearerToken: token })
     );
     expect(result.isOk()).toBe(true);
@@ -295,7 +295,7 @@ describe('createJwtAdapter', () => {
   });
 
   test('returns error for malformed signature bytes', async () => {
-    const adapter = createJwtAdapter({ secret: TEST_SECRET });
+    const connector = createJwtConnector({ secret: TEST_SECRET });
     const now = Math.floor(Date.now() / 1000);
     const token = await signJwt(
       { exp: now + 3600, sub: 'user-bad' },
@@ -303,7 +303,7 @@ describe('createJwtAdapter', () => {
     );
     const parts = token.split('.');
     const malformed = `${parts[0]}.${parts[1]}.!!!invalid-base64!!!`;
-    const result = await adapter.authenticate(
+    const result = await connector.authenticate(
       testInput({ bearerToken: malformed })
     );
     expect(result.isErr()).toBe(true);
@@ -312,7 +312,7 @@ describe('createJwtAdapter', () => {
   });
 
   test('accepts token with matching issuer and audience', async () => {
-    const adapter = createJwtAdapter({
+    const connector = createJwtConnector({
       audience: 'my-api',
       issuer: 'https://auth.example.com',
       secret: TEST_SECRET,
@@ -328,7 +328,7 @@ describe('createJwtAdapter', () => {
       },
       TEST_SECRET
     );
-    const result = await adapter.authenticate(
+    const result = await connector.authenticate(
       testInput({ bearerToken: token })
     );
     expect(result.isOk()).toBe(true);

package/src/__tests__/permit.test.ts

@@ -60,7 +60,7 @@ describe('getPermit()', () => {
     expect(result).toBeUndefined();
   });
 
-  test('preserves extended permit fields from the auth layer', () => {
+  test('preserves extended permit fields from the auth gate', () => {
     const ctx = {
       permit: {
         id: 'usr_2',
@@ -77,42 +77,42 @@ describe('getPermit()', () => {
 });
 
 describe('PermitExtractionInput', () => {
-  test('accepts HTTP surface extraction', () => {
+  test('accepts HTTP trailhead extraction', () => {
     const input: PermitExtractionInput = {
       bearerToken: 'eyJhbGciOiJSUzI1NiJ9.test',
       headers: new Headers({
         authorization: 'Bearer eyJhbGciOiJSUzI1NiJ9.test',
       }),
       requestId: 'req-http-1',
-      surface: 'http',
+      trailhead: 'http',
     };
-    expect(input.surface).toBe('http');
+    expect(input.trailhead).toBe('http');
     expect(input.bearerToken).toBeDefined();
   });
 
-  test('accepts MCP surface extraction', () => {
+  test('accepts MCP trailhead extraction', () => {
     const input: PermitExtractionInput = {
       requestId: 'req-mcp-1',
       sessionId: 'mcp-session-abc',
-      surface: 'mcp',
+      trailhead: 'mcp',
     };
-    expect(input.surface).toBe('mcp');
+    expect(input.trailhead).toBe('mcp');
     expect(input.sessionId).toBe('mcp-session-abc');
   });
 
-  test('accepts CLI surface extraction', () => {
+  test('accepts CLI trailhead extraction', () => {
     const input: PermitExtractionInput = {
       bearerToken: 'cli-token-from-keyring',
       requestId: 'req-cli-1',
-      surface: 'cli',
+      trailhead: 'cli',
     };
-    expect(input.surface).toBe('cli');
+    expect(input.trailhead).toBe('cli');
   });
 
   test('accepts minimal extraction with only required fields', () => {
     const input: PermitExtractionInput = {
       requestId: 'req-minimal',
-      surface: 'http',
+      trailhead: 'http',
     };
     expect(input.requestId).toBe('req-minimal');
     expect(input.bearerToken).toBeUndefined();

package/src/__tests__/rules.test.ts

@@ -24,9 +24,9 @@ const noopRun = () => Result.ok({});
 describe('destroyWithoutPermit', () => {
   test('error when destroy trail has no permit', () => {
     const t = trail('user.delete', {
+      blaze: noopRun,
       input: emptyInput,
       intent: 'destroy',
-      run: noopRun,
     });
     const diagnostics = destroyWithoutPermit([t]);
     expect(diagnostics).toHaveLength(1);
@@ -40,10 +40,10 @@ describe('destroyWithoutPermit', () => {
 
   test('no diagnostic when destroy trail has a scoped permit', () => {
     const t = trail('user.delete', {
+      blaze: noopRun,
       input: emptyInput,
       intent: 'destroy',
       permit: { scopes: ['user:delete'] },
-      run: noopRun,
     });
     const diagnostics = destroyWithoutPermit([t]);
     expect(diagnostics).toHaveLength(0);
@@ -51,10 +51,10 @@ describe('destroyWithoutPermit', () => {
 
   test('error when destroy trail has permit: public', () => {
     const t = trail('user.delete', {
+      blaze: noopRun,
       input: emptyInput,
       intent: 'destroy',
       permit: 'public',
-      run: noopRun,
     });
     const diagnostics = destroyWithoutPermit([t]);
     expect(diagnostics).toHaveLength(1);
@@ -73,8 +73,8 @@ describe('destroyWithoutPermit', () => {
 describe('writeWithoutPermit', () => {
   test('warning when write trail has no permit', () => {
     const t = trail('user.create', {
+      blaze: noopRun,
       input: emptyInput,
-      run: noopRun,
     });
     const diagnostics = writeWithoutPermit([t]);
     expect(diagnostics).toHaveLength(1);
@@ -87,9 +87,9 @@ describe('writeWithoutPermit', () => {
 
   test('no warning when write trail has permit: public', () => {
     const t = trail('user.create', {
+      blaze: noopRun,
       input: emptyInput,
       permit: 'public',
-      run: noopRun,
     });
     const diagnostics = writeWithoutPermit([t]);
     expect(diagnostics).toHaveLength(0);
@@ -97,8 +97,8 @@ describe('writeWithoutPermit', () => {
 
   test('warning when trail has no intent (defaults to write)', () => {
     const t = trail('user.update', {
+      blaze: noopRun,
       input: emptyInput,
-      run: noopRun,
     });
     // Override intent to undefined to simulate a manually constructed trail
     const noIntent = { ...t, intent: undefined } as unknown as ReturnType<
@@ -115,9 +115,9 @@ describe('writeWithoutPermit', () => {
 
   test('no diagnostic for read trail without permit', () => {
     const t = trail('user.list', {
+      blaze: noopRun,
       input: emptyInput,
       intent: 'read',
-      run: noopRun,
     });
     const diagnostics = writeWithoutPermit([t]);
     expect(diagnostics).toHaveLength(0);
@@ -131,9 +131,9 @@ describe('writeWithoutPermit', () => {
 describe('scopeNamingConsistency', () => {
   test('scope user:write passes naming check', () => {
     const t = trail('user.update', {
+      blaze: noopRun,
       input: emptyInput,
       permit: { scopes: ['user:write'] },
-      run: noopRun,
     });
     const diagnostics = scopeNamingConsistency([t]);
     expect(diagnostics).toHaveLength(0);
@@ -141,9 +141,9 @@ describe('scopeNamingConsistency', () => {
 
   test('warning for scope without colon', () => {
     const t = trail('admin.panel', {
+      blaze: noopRun,
       input: emptyInput,
       permit: { scopes: ['admin'] },
-      run: noopRun,
     });
     const diagnostics = scopeNamingConsistency([t]);
     expect(diagnostics).toHaveLength(1);
@@ -163,14 +163,14 @@ describe('scopeNamingConsistency', () => {
 describe('orphanScopeDetection', () => {
   test('warning for orphan scope (typo)', () => {
     const t1 = trail('user.read', {
+      blaze: noopRun,
       input: emptyInput,
       permit: { scopes: ['user:read'] },
-      run: noopRun,
     });
     const t2 = trail('user.write', {
+      blaze: noopRun,
       input: emptyInput,
       permit: { scopes: ['user:wirte'] },
-      run: noopRun,
     });
     const diagnostics = orphanScopeDetection([t1, t2]);
     // Both scopes are unique (appear in only 1 trail each)
@@ -181,14 +181,14 @@ describe('orphanScopeDetection', () => {
 
   test('no warning for shared scopes', () => {
     const t1 = trail('user.read', {
+      blaze: noopRun,
       input: emptyInput,
       permit: { scopes: ['user:read'] },
-      run: noopRun,
     });
     const t2 = trail('user.profile', {
+      blaze: noopRun,
       input: emptyInput,
       permit: { scopes: ['user:read'] },
-      run: noopRun,
     });
     const diagnostics = orphanScopeDetection([t1, t2]);
     expect(diagnostics).toHaveLength(0);
@@ -203,23 +203,23 @@ describe('orphanScopeDetection', () => {
 describe('validatePermits', () => {
   test('runs all rules and aggregates diagnostics', () => {
     const destroyNoPerm = trail('user.delete', {
+      blaze: noopRun,
       input: emptyInput,
       intent: 'destroy',
-      run: noopRun,
     });
     const writeNoPerm = trail('user.create', {
+      blaze: noopRun,
       input: emptyInput,
-      run: noopRun,
     });
     const badScope = trail('admin.panel', {
+      blaze: noopRun,
       input: emptyInput,
       permit: { scopes: ['admin'] },
-      run: noopRun,
     });
     const orphanScope = trail('analytics.export', {
+      blaze: noopRun,
       input: emptyInput,
       permit: { scopes: ['analytics:exportt'] },
-      run: noopRun,
     });
 
     const diagnostics = validatePermits([

package/src/{auth-layer.ts → auth-gate.ts}

@@ -1,5 +1,5 @@
 import { Result } from '@ontrails/core';
-import type { Layer } from '@ontrails/core';
+import type { Gate } from '@ontrails/core';
 
 import { PermitError } from './errors.js';
 import { getPermit } from './permit.js';
@@ -25,25 +25,25 @@ const findMissing = (
 ): readonly string[] => required.filter((s) => !held.includes(s));
 
 // ---------------------------------------------------------------------------
-// Auth layer
+// Auth gate
 // ---------------------------------------------------------------------------
 
 /**
- * A {@link Layer} that enforces permit scopes declared on trails.
+ * A {@link Gate} that enforces permit scopes declared on trails.
  *
- * The layer reads the trail's `permit` field (a `PermitRequirement`):
+ * The gate reads the trail's `permit` field (a `PermitRequirement`):
  *
- * - If `permit` is `'public'` or `undefined` the layer passes through.
- * - If `permit` has `scopes`, the layer checks that `ctx.permit` contains
+ * - If `permit` is `'public'` or `undefined` the gate passes through.
+ * - If `permit` has `scopes`, the gate checks that `ctx.permit` contains
  *   all required scopes. A superset is fine; missing scopes produce a
  *   `PermitError`.
  *
- * Because `ctx.follow()` re-enters `executeTrail` (which applies layers),
- * this layer automatically re-checks on every invocation in a follow chain.
- * No special follow-chain handling is needed — it is built into the
+ * Because `ctx.cross()` re-enters `executeTrail` (which applies gates),
+ * this gate automatically re-checks on every invocation in a crossing chain.
+ * No special crossing-chain handling is needed — it is built into the
  * architecture.
  */
-export const authLayer: Layer = {
+export const authGate: Gate = {
   description: 'Enforces permit scopes declared on trails',
   name: 'auth',
   wrap: (_trail, impl) => {

package/src/auth-provision.ts

@@ -0,0 +1,26 @@
+import { Result, provision } from '@ontrails/core';
+
+import type { AuthConnector } from './connectors/connector.js';
+
+/**
+ * Auth provision — manages the auth connector lifecycle.
+ *
+ * The v1 factory returns a no-op connector that always succeeds (null permit).
+ * Real connector configuration will come through `ProvisionSpec.config`
+ * (TRL-91). The mock factory provides a synthetic connector that always
+ * succeeds.
+ */
+export const authProvision = provision<AuthConnector>('auth', {
+  create: (_svc) =>
+    Result.ok({
+      // oxlint-disable-next-line require-await -- stub connector satisfies async interface
+      authenticate: async () => Result.ok(null),
+    } satisfies AuthConnector),
+  description: 'Authentication connector',
+  meta: { category: 'infrastructure' },
+  mock: () =>
+    ({
+      // oxlint-disable-next-line require-await -- mock connector satisfies async interface
+      authenticate: async () => Result.ok(null),
+    }) satisfies AuthConnector,
+});

package/src/{adapter.ts → connectors/connector.ts}

@@ -1,7 +1,7 @@
 import type { Result } from '@ontrails/core';
 
-import type { PermitExtractionInput } from './extraction.js';
-import type { Permit } from './permit.js';
+import type { PermitExtractionInput } from '../extraction.js';
+import type { Permit } from '../permit.js';
 
 /**
  * @deprecated Use {@link PermitExtractionInput} instead. Kept as an alias
@@ -9,7 +9,7 @@ import type { Permit } from './permit.js';
  */
 export type AuthCredentials = PermitExtractionInput;
 
-/** Errors from auth adapters. */
+/** Errors from auth connectors. */
 export interface AuthError {
   readonly code:
     | 'expired_token'
@@ -20,15 +20,15 @@ export interface AuthError {
 }
 
 /**
- * Auth adapter port. Given extraction input, produce a permit or an error.
+ * Auth connector port. Given extraction input, produce a permit or an error.
  *
- * The adapter receives the full {@link PermitExtractionInput} — surface,
+ * The connector receives the full {@link PermitExtractionInput} — trailhead,
  * headers, requestId, and credential fields — so it can make richer
- * decisions (e.g., rate-limit by surface or correlate via requestId).
+ * decisions (e.g., rate-limit by trailhead or correlate via requestId).
  *
  * Deliberately narrow — no session management, no token refresh.
  */
-export interface AuthAdapter {
+export interface AuthConnector {
   readonly authenticate: (
     input: PermitExtractionInput
   ) => Promise<Result<Permit | null, AuthError>>;

package/src/{adapters → connectors}/jwt.ts

@@ -1,11 +1,11 @@
 import { Result } from '@ontrails/core';
 
-import type { AuthAdapter, AuthError } from '../adapter.js';
+import type { AuthConnector, AuthError } from './connector.js';
 import type { PermitExtractionInput } from '../extraction.js';
 import type { Permit } from '../permit.js';
 
-/** Configuration for the JWT auth adapter. */
-export interface JwtAdapterOptions {
+/** Configuration for the JWT auth connector. */
+export interface JwtConnectorOptions {
   /** HMAC secret for HS256 verification. */
   readonly secret?: string;
   /** JWKS endpoint for RS256/ES256 (not yet implemented). */
@@ -101,7 +101,7 @@ const verifyHmacSignature = (
 /** Validate standard claims (exp, iss, aud). */
 const validateClaims = (
   payload: JwtPayload,
-  options: JwtAdapterOptions
+  options: JwtConnectorOptions
 ): AuthError | undefined => {
   if (
     payload.exp !== undefined &&
@@ -156,7 +156,7 @@ const extractRoles = (
 /** Build a Permit from a validated JWT payload. */
 const buildPermit = (
   payload: JwtPayload,
-  options: JwtAdapterOptions
+  options: JwtConnectorOptions
 ): Result<Permit, AuthError> => {
   if (!payload.sub) {
     return authErr('invalid_token', 'Missing subject claim (sub)');
@@ -192,7 +192,7 @@ const decodeAndVerify = async (
 /** Validate claims and build a permit from a verified payload. */
 const payloadToPermit = (
   payload: JwtPayload,
-  options: JwtAdapterOptions
+  options: JwtConnectorOptions
 ): Result<Permit, AuthError> => {
   const claimError = validateClaims(payload, options);
   if (claimError) {
@@ -206,13 +206,15 @@ const payloadToPermit = (
 // ---------------------------------------------------------------------------
 
 /**
- * Create a JWT auth adapter using Bun's native crypto.
+ * Create a JWT auth connector using Bun's native crypto.
  *
  * Verifies HS256-signed JWTs, extracts claims into a Permit, and checks
  * issuer/audience when configured. Returns `Result.ok(null)` when no
  * credentials are provided.
  */
-export const createJwtAdapter = (options: JwtAdapterOptions): AuthAdapter => {
+export const createJwtConnector = (
+  options: JwtConnectorOptions
+): AuthConnector => {
   const authenticate = async (
     input: PermitExtractionInput
   ): Promise<Result<Permit | null, AuthError>> => {