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

package/src/__tests__/auth-verify.test.ts

@@ -1,278 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-
-import {
-  Result,
-  TRAILHEAD_KEY,
-  ValidationError,
-  executeTrail,
-} from '@ontrails/core';
-
-import type { AuthConnector } from '../connectors/connector.js';
-import { authProvision } from '../auth-provision.js';
-import { createJwtConnector } from '../connectors/jwt.js';
-import type { Permit } from '../permit.js';
-import { authVerify } from '../trails/auth-verify.js';
-
-// ---------------------------------------------------------------------------
-// Test helper: sign a JWT with HMAC-SHA256 using crypto.subtle
-// ---------------------------------------------------------------------------
-
-const base64url = (buf: ArrayBuffer): string => {
-  const bytes = new Uint8Array(buf);
-  let binary = '';
-  for (const b of bytes) {
-    binary += String.fromCodePoint(b);
-  }
-  return btoa(binary)
-    .replaceAll('+', '-')
-    .replaceAll('/', '_')
-    .replace(/=+$/, '');
-};
-
-const base64urlEncode = (str: string): string => {
-  const encoder = new TextEncoder();
-  return base64url(encoder.encode(str).buffer as ArrayBuffer);
-};
-
-const signJwt = async (
-  payload: Record<string, unknown>,
-  secret: string
-): Promise<string> => {
-  const header = base64urlEncode(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
-  const body = base64urlEncode(JSON.stringify(payload));
-  const data = `${header}.${body}`;
-  const encoder = new TextEncoder();
-  const key = await crypto.subtle.importKey(
-    'raw',
-    encoder.encode(secret),
-    { hash: 'SHA-256', name: 'HMAC' },
-    false,
-    ['sign']
-  );
-  const sig = await crypto.subtle.sign('HMAC', key, encoder.encode(data));
-  return `${data}.${base64url(sig)}`;
-};
-
-const TEST_SECRET = 'test-secret-for-hmac-256';
-
-/** Create an AuthConnector wired to a JWT secret. */
-const jwtConnector = (): AuthConnector =>
-  createJwtConnector({ secret: TEST_SECRET });
-
-/** Execute auth.verify with a given connector injected as the auth provision. */
-const runVerify = async (
-  token: string,
-  connector: AuthConnector,
-  options?: {
-    trailhead?: 'http' | 'mcp' | 'cli';
-  }
-): Promise<
-  Result<
-    {
-      error?: string;
-      errorCode?:
-        | 'expired_token'
-        | 'insufficient_scope'
-        | 'invalid_token'
-        | 'missing_credentials';
-      permit?: {
-        id: string;
-        metadata?: Record<string, unknown>;
-        roles?: string[];
-        scopes: string[];
-        tenantId?: string;
-      };
-      valid: boolean;
-    },
-    Error
-  >
-> => {
-  const result = await executeTrail(
-    authVerify,
-    { token },
-    {
-      ctx:
-        options?.trailhead === undefined
-          ? undefined
-          : { extensions: { [TRAILHEAD_KEY]: options.trailhead } },
-      provisions: { [authProvision.id]: connector },
-    }
-  );
-  return result as Result<
-    {
-      error?: string;
-      permit?: {
-        id: string;
-        metadata?: Record<string, unknown>;
-        roles?: string[];
-        scopes: string[];
-        tenantId?: string;
-      };
-      valid: boolean;
-    },
-    Error
-  >;
-};
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-describe('auth.verify trail', () => {
-  describe('contract', () => {
-    test('has correct id and intent', () => {
-      expect(authVerify.id).toBe('auth.verify');
-      expect(authVerify.intent).toBe('read');
-    });
-
-    test('has infrastructure meta', () => {
-      expect(authVerify.meta).toEqual({ category: 'infrastructure' });
-    });
-
-    test('has examples', () => {
-      expect(authVerify.examples).toBeDefined();
-      expect(authVerify.examples?.length).toBeGreaterThan(0);
-    });
-
-    test('declares authProvision dependency', () => {
-      expect(authVerify.provisions).toHaveLength(1);
-      expect(authVerify.provisions[0]?.id).toBe('auth');
-    });
-  });
-
-  describe('with mock connector (no credentials)', () => {
-    test('returns valid: false with error message', async () => {
-      const noopConnector: AuthConnector = {
-        // oxlint-disable-next-line require-await -- satisfies async interface
-        authenticate: async () => Result.ok(null),
-      };
-
-      const result = await runVerify('some-token', noopConnector);
-
-      expect(result.isOk()).toBe(true);
-      const value = result.unwrap();
-      expect(value.valid).toBe(false);
-      expect(value.error).toBe('No credentials');
-      expect(value.errorCode).toBe('missing_credentials');
-      expect(value.permit).toBeUndefined();
-    });
-  });
-
-  describe('with valid token and secret', () => {
-    test('returns valid: true with permit', async () => {
-      const now = Math.floor(Date.now() / 1000);
-      const token = await signJwt(
-        { exp: now + 3600, scope: 'read write', sub: 'user-42' },
-        TEST_SECRET
-      );
-
-      const result = await runVerify(token, jwtConnector());
-
-      expect(result.isOk()).toBe(true);
-      const value = result.unwrap();
-      expect(value.valid).toBe(true);
-      expect(value.permit).toEqual({
-        id: 'user-42',
-        scopes: ['read', 'write'],
-      });
-      expect(value.error).toBeUndefined();
-    });
-
-    test('returns the full permit payload from the connector', async () => {
-      const permit: Permit = {
-        id: 'user-42',
-        metadata: { plan: 'pro' },
-        roles: ['admin'],
-        scopes: ['read', 'write'],
-        tenantId: 'tenant-1',
-      };
-      const connector: AuthConnector = {
-        // oxlint-disable-next-line require-await -- satisfies async interface
-        authenticate: async () => Result.ok(permit),
-      };
-
-      const result = await runVerify('full-permit-token', connector);
-
-      expect(result.isOk()).toBe(true);
-      expect(result.unwrap().permit).toEqual({
-        id: 'user-42',
-        metadata: { plan: 'pro' },
-        roles: ['admin'],
-        scopes: ['read', 'write'],
-        tenantId: 'tenant-1',
-      });
-    });
-
-    test('forwards the invoking trailhead from trail context', async () => {
-      let seenTrailhead: string | undefined;
-      const connector: AuthConnector = {
-        // oxlint-disable-next-line require-await -- captures connector input
-        authenticate: async (input) => {
-          seenTrailhead = input.trailhead;
-          return Result.ok({
-            id: 'user-42',
-            scopes: ['read'],
-          });
-        },
-      };
-
-      const result = await runVerify('trailhead-aware-token', connector, {
-        trailhead: 'mcp',
-      });
-
-      expect(result.isOk()).toBe(true);
-      expect(seenTrailhead).toBe('mcp');
-    });
-  });
-
-  describe('with invalid token', () => {
-    test('returns valid: false with error for bad signature', async () => {
-      const now = Math.floor(Date.now() / 1000);
-      const token = await signJwt(
-        { exp: now + 3600, sub: 'user-bad' },
-        'wrong-secret'
-      );
-
-      const result = await runVerify(token, jwtConnector());
-
-      expect(result.isOk()).toBe(true);
-      const value = result.unwrap();
-      expect(value.valid).toBe(false);
-      expect(value.error).toBeDefined();
-      expect(value.errorCode).toBe('invalid_token');
-      expect(value.permit).toBeUndefined();
-    });
-
-    test('returns valid: false for expired token', async () => {
-      const past = Math.floor(Date.now() / 1000) - 3600;
-      const token = await signJwt(
-        { exp: past, sub: 'user-expired' },
-        TEST_SECRET
-      );
-
-      const result = await runVerify(token, jwtConnector());
-
-      expect(result.isOk()).toBe(true);
-      const value = result.unwrap();
-      expect(value.valid).toBe(false);
-      expect(value.error).toBeDefined();
-      expect(value.errorCode).toBe('expired_token');
-      expect(value.permit).toBeUndefined();
-    });
-  });
-
-  describe('input validation', () => {
-    test('rejects empty bearer tokens at the boundary', async () => {
-      const result = await executeTrail(
-        authVerify,
-        { token: '' },
-        {
-          provisions: { [authProvision.id]: jwtConnector() },
-        }
-      );
-
-      expect(result.isErr()).toBe(true);
-      expect(result.error).toBeInstanceOf(ValidationError);
-    });
-  });
-});

package/src/__tests__/connector.test.ts

@@ -1,338 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-
-import { Result } from '@ontrails/core';
-
-import type { AuthConnector, AuthError } from '../connectors/connector.js';
-import type { PermitExtractionInput } from '../extraction.js';
-import type { Permit } from '../permit.js';
-import { createJwtConnector } from '../connectors/jwt.js';
-
-// ---------------------------------------------------------------------------
-// Test helper: sign a JWT with HMAC-SHA256 using crypto.subtle
-// ---------------------------------------------------------------------------
-
-const base64url = (buf: ArrayBuffer): string => {
-  const bytes = new Uint8Array(buf);
-  let binary = '';
-  for (const b of bytes) {
-    binary += String.fromCodePoint(b);
-  }
-  return btoa(binary)
-    .replaceAll('+', '-')
-    .replaceAll('/', '_')
-    .replace(/=+$/, '');
-};
-
-const base64urlEncode = (str: string): string => {
-  const encoder = new TextEncoder();
-  return base64url(encoder.encode(str).buffer as ArrayBuffer);
-};
-
-const signJwt = async (
-  payload: Record<string, unknown>,
-  secret: string
-): Promise<string> => {
-  const header = base64urlEncode(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
-  const body = base64urlEncode(JSON.stringify(payload));
-  const data = `${header}.${body}`;
-  const encoder = new TextEncoder();
-  const key = await crypto.subtle.importKey(
-    'raw',
-    encoder.encode(secret),
-    { hash: 'SHA-256', name: 'HMAC' },
-    false,
-    ['sign']
-  );
-  const sig = await crypto.subtle.sign('HMAC', key, encoder.encode(data));
-  return `${data}.${base64url(sig)}`;
-};
-
-const TEST_SECRET = 'test-secret-for-hmac-256';
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-/** Minimal extraction input for tests that don't need all fields. */
-const testInput = (
-  overrides?: Partial<PermitExtractionInput>
-): PermitExtractionInput => ({
-  requestId: 'test-req',
-  trailhead: 'http',
-  ...overrides,
-});
-
-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 connector.authenticate(testInput());
-    expect(result.isOk()).toBe(true);
-  });
-});
-
-/* oxlint-disable max-statements -- test suite with multiple concern groups */
-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 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 connector.authenticate(
-      testInput({ bearerToken: token })
-    );
-    expect(result.isOk()).toBe(true);
-    const permit = result.unwrap() as Permit;
-    expect(permit).not.toBeNull();
-    expect(permit.id).toBe('user-123');
-    expect(permit.scopes).toEqual(['read', 'write']);
-  });
-
-  test('rejects an expired token', async () => {
-    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 connector.authenticate(
-      testInput({ bearerToken: token })
-    );
-    expect(result.isErr()).toBe(true);
-    const err = (result as ReturnType<typeof Result.err<AuthError>>).error;
-    expect(err.code).toBe('expired_token');
-  });
-
-  test('rejects an invalid signature', async () => {
-    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 connector.authenticate(
-      testInput({ bearerToken: token })
-    );
-    expect(result.isErr()).toBe(true);
-    const err = (result as ReturnType<typeof Result.err<AuthError>>).error;
-    expect(err.code).toBe('invalid_token');
-  });
-
-  test('rejects tokens with a missing subject claim', async () => {
-    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 connector.authenticate(
-      testInput({ bearerToken: token })
-    );
-    expect(result.isErr()).toBe(true);
-    const err = (result as ReturnType<typeof Result.err<AuthError>>).error;
-    expect(err.code).toBe('invalid_token');
-    expect(err.message).toContain('Missing subject claim');
-  });
-
-  test('extracts scopes from token claims', async () => {
-    const connector = createJwtConnector({
-      scopesClaim: 'permissions',
-      secret: TEST_SECRET,
-    });
-    const now = Math.floor(Date.now() / 1000);
-    const token = await signJwt(
-      {
-        exp: now + 3600,
-        permissions: 'admin:read admin:write',
-        sub: 'user-scopes',
-      },
-      TEST_SECRET
-    );
-    const result = await connector.authenticate(
-      testInput({ bearerToken: token })
-    );
-    expect(result.isOk()).toBe(true);
-    const permit = result.unwrap() as Permit;
-    expect(permit.scopes).toEqual(['admin:read', 'admin:write']);
-  });
-
-  test('extracts roles from token claims', async () => {
-    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 connector.authenticate(
-      testInput({ bearerToken: token })
-    );
-    expect(result.isOk()).toBe(true);
-    const permit = result.unwrap() as Permit;
-    expect(permit.roles).toEqual(['admin', 'editor']);
-  });
-
-  test('returns null for missing credentials', async () => {
-    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 connector = createJwtConnector({
-      issuer: 'https://auth.example.com',
-      secret: TEST_SECRET,
-    });
-    const now = Math.floor(Date.now() / 1000);
-    const token = await signJwt(
-      { exp: now + 3600, iss: 'https://evil.example.com', sub: 'user-iss' },
-      TEST_SECRET
-    );
-    const result = await connector.authenticate(
-      testInput({ bearerToken: token })
-    );
-    expect(result.isErr()).toBe(true);
-    const err = (result as ReturnType<typeof Result.err<AuthError>>).error;
-    expect(err.code).toBe('invalid_token');
-  });
-
-  test('checks audience claim when configured', async () => {
-    const connector = createJwtConnector({
-      audience: 'my-api',
-      secret: TEST_SECRET,
-    });
-    const now = Math.floor(Date.now() / 1000);
-    const token = await signJwt(
-      { aud: 'other-api', exp: now + 3600, sub: 'user-aud' },
-      TEST_SECRET
-    );
-    const result = await connector.authenticate(
-      testInput({ bearerToken: token })
-    );
-    expect(result.isErr()).toBe(true);
-    const err = (result as ReturnType<typeof Result.err<AuthError>>).error;
-    expect(err.code).toBe('invalid_token');
-  });
-
-  test('accepts array-format audience containing configured value', async () => {
-    const connector = createJwtConnector({
-      audience: 'my-api',
-      secret: TEST_SECRET,
-    });
-    const now = Math.floor(Date.now() / 1000);
-    const token = await signJwt(
-      { aud: ['my-api', 'account'], exp: now + 3600, sub: 'user-arr-aud' },
-      TEST_SECRET
-    );
-    const result = await connector.authenticate(
-      testInput({ bearerToken: token })
-    );
-    expect(result.isOk()).toBe(true);
-    const permit = result.unwrap() as Permit;
-    expect(permit.id).toBe('user-arr-aud');
-  });
-
-  test('rejects array-format audience not containing configured value', async () => {
-    const connector = createJwtConnector({
-      audience: 'my-api',
-      secret: TEST_SECRET,
-    });
-    const now = Math.floor(Date.now() / 1000);
-    const token = await signJwt(
-      { aud: ['other-api', 'account'], exp: now + 3600, sub: 'user-no-aud' },
-      TEST_SECRET
-    );
-    const result = await connector.authenticate(
-      testInput({ bearerToken: token })
-    );
-    expect(result.isErr()).toBe(true);
-    const err = (result as ReturnType<typeof Result.err<AuthError>>).error;
-    expect(err.code).toBe('invalid_token');
-  });
-
-  test('extracts scopes from array-format claim', async () => {
-    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 connector.authenticate(
-      testInput({ bearerToken: token })
-    );
-    expect(result.isOk()).toBe(true);
-    const permit = result.unwrap() as Permit;
-    expect(permit.scopes).toEqual(['read', 'write']);
-  });
-
-  test('filters empty strings from array-format scope claims', async () => {
-    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-empty',
-      },
-      TEST_SECRET
-    );
-    const result = await connector.authenticate(
-      testInput({ bearerToken: token })
-    );
-    expect(result.isOk()).toBe(true);
-    const permit = result.unwrap() as Permit;
-    expect(permit.scopes).toEqual(['read', 'write']);
-  });
-
-  test('returns error for malformed signature bytes', async () => {
-    const connector = createJwtConnector({ secret: TEST_SECRET });
-    const now = Math.floor(Date.now() / 1000);
-    const token = await signJwt(
-      { exp: now + 3600, sub: 'user-bad' },
-      TEST_SECRET
-    );
-    const parts = token.split('.');
-    const malformed = `${parts[0]}.${parts[1]}.!!!invalid-base64!!!`;
-    const result = await connector.authenticate(
-      testInput({ bearerToken: malformed })
-    );
-    expect(result.isErr()).toBe(true);
-    const err = (result as ReturnType<typeof Result.err<AuthError>>).error;
-    expect(err.code).toBe('invalid_token');
-  });
-
-  test('accepts token with matching issuer and audience', async () => {
-    const connector = createJwtConnector({
-      audience: 'my-api',
-      issuer: 'https://auth.example.com',
-      secret: TEST_SECRET,
-    });
-    const now = Math.floor(Date.now() / 1000);
-    const token = await signJwt(
-      {
-        aud: 'my-api',
-        exp: now + 3600,
-        iss: 'https://auth.example.com',
-        scope: 'read',
-        sub: 'user-valid',
-      },
-      TEST_SECRET
-    );
-    const result = await connector.authenticate(
-      testInput({ bearerToken: token })
-    );
-    expect(result.isOk()).toBe(true);
-    const permit = result.unwrap() as Permit;
-    expect(permit.id).toBe('user-valid');
-  });
-});