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

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');
-  });
-});

package/src/__tests__/permit.test.ts

@@ -1,122 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-
-import type { Permit, PermitExtractionInput } from '../index';
-import { getPermit } from '../index';
-
-describe('Permit type', () => {
-  test('accepts a valid permit with required fields only', () => {
-    const permit: Permit = {
-      id: 'usr_abc123',
-      scopes: ['user:read', 'user:write'],
-    };
-    expect(permit.id).toBe('usr_abc123');
-    expect(permit.scopes).toEqual(['user:read', 'user:write']);
-  });
-
-  test('accepts a permit with all optional fields', () => {
-    const permit: Permit = {
-      id: 'usr_full',
-      metadata: { plan: 'pro', provider: 'clerk' },
-      roles: ['admin', 'editor'],
-      scopes: ['entity:read'],
-      tenantId: 'tenant_xyz',
-    };
-    expect(permit.roles).toEqual(['admin', 'editor']);
-    expect(permit.tenantId).toBe('tenant_xyz');
-    expect(permit.metadata).toEqual({ plan: 'pro', provider: 'clerk' });
-  });
-
-  test('scopes and roles arrays are readonly', () => {
-    const permit: Permit = {
-      id: 'usr_ro',
-      roles: ['viewer'],
-      scopes: ['read'],
-    };
-    // Structural check: readonly arrays are assignable to readonly string[]
-    const { scopes } = permit;
-    const { roles } = permit;
-    expect(scopes).toEqual(['read']);
-    expect(roles).toEqual(['viewer']);
-  });
-});
-
-describe('getPermit()', () => {
-  test('returns Permit from a context with a permit', () => {
-    const permit: Permit = { id: 'usr_1', scopes: ['user:read'] };
-    const ctx = { permit, requestId: 'req-1' };
-    const result = getPermit(ctx);
-    expect(result).toEqual(permit);
-  });
-
-  test('returns undefined when context has no permit', () => {
-    const ctx = { requestId: 'req-2' };
-    const result = getPermit(ctx);
-    expect(result).toBeUndefined();
-  });
-
-  test('returns undefined when permit is explicitly undefined', () => {
-    const ctx = { permit: undefined, requestId: 'req-3' };
-    const result = getPermit(ctx);
-    expect(result).toBeUndefined();
-  });
-
-  test('preserves extended permit fields from the auth layer', () => {
-    const ctx = {
-      permit: {
-        id: 'usr_2',
-        metadata: { plan: 'pro' },
-        roles: ['admin'],
-        scopes: ['user:read'],
-        tenantId: 'tenant-1',
-      } satisfies Permit,
-      requestId: 'req-4',
-    };
-    const result = getPermit(ctx);
-    expect(result).toEqual(ctx.permit);
-  });
-});
-
-describe('PermitExtractionInput', () => {
-  test('accepts HTTP trailhead extraction', () => {
-    const input: PermitExtractionInput = {
-      bearerToken: 'eyJhbGciOiJSUzI1NiJ9.test',
-      headers: new Headers({
-        authorization: 'Bearer eyJhbGciOiJSUzI1NiJ9.test',
-      }),
-      requestId: 'req-http-1',
-      trailhead: 'http',
-    };
-    expect(input.trailhead).toBe('http');
-    expect(input.bearerToken).toBeDefined();
-  });
-
-  test('accepts MCP trailhead extraction', () => {
-    const input: PermitExtractionInput = {
-      requestId: 'req-mcp-1',
-      sessionId: 'mcp-session-abc',
-      trailhead: 'mcp',
-    };
-    expect(input.trailhead).toBe('mcp');
-    expect(input.sessionId).toBe('mcp-session-abc');
-  });
-
-  test('accepts CLI trailhead extraction', () => {
-    const input: PermitExtractionInput = {
-      bearerToken: 'cli-token-from-keyring',
-      requestId: 'req-cli-1',
-      trailhead: 'cli',
-    };
-    expect(input.trailhead).toBe('cli');
-  });
-
-  test('accepts minimal extraction with only required fields', () => {
-    const input: PermitExtractionInput = {
-      requestId: 'req-minimal',
-      trailhead: 'http',
-    };
-    expect(input.requestId).toBe('req-minimal');
-    expect(input.bearerToken).toBeUndefined();
-    expect(input.sessionId).toBeUndefined();
-    expect(input.headers).toBeUndefined();
-  });
-});

package/src/__tests__/rules.test.ts

@@ -1,239 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { trail, Result } from '@ontrails/core';
-import { z } from 'zod';
-
-import {
-  destroyWithoutPermit,
-  writeWithoutPermit,
-  scopeNamingConsistency,
-  orphanScopeDetection,
-  validatePermits,
-} from '../rules.js';
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-const emptyInput = z.object({});
-const noopRun = () => Result.ok({});
-
-// ---------------------------------------------------------------------------
-// destroyWithoutPermit
-// ---------------------------------------------------------------------------
-
-describe('destroyWithoutPermit', () => {
-  test('error when destroy trail has no permit', () => {
-    const t = trail('user.delete', {
-      blaze: noopRun,
-      input: emptyInput,
-      intent: 'destroy',
-    });
-    const diagnostics = destroyWithoutPermit([t]);
-    expect(diagnostics).toHaveLength(1);
-    expect(diagnostics[0]).toMatchObject({
-      message: expect.stringContaining('destroy'),
-      rule: 'destroyWithoutPermit',
-      severity: 'error',
-      trailId: 'user.delete',
-    });
-  });
-
-  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'] },
-    });
-    const diagnostics = destroyWithoutPermit([t]);
-    expect(diagnostics).toHaveLength(0);
-  });
-
-  test('error when destroy trail has permit: public', () => {
-    const t = trail('user.delete', {
-      blaze: noopRun,
-      input: emptyInput,
-      intent: 'destroy',
-      permit: 'public',
-    });
-    const diagnostics = destroyWithoutPermit([t]);
-    expect(diagnostics).toHaveLength(1);
-    expect(diagnostics[0]).toMatchObject({
-      rule: 'destroyWithoutPermit',
-      severity: 'error',
-      trailId: 'user.delete',
-    });
-  });
-});
-
-// ---------------------------------------------------------------------------
-// writeWithoutPermit
-// ---------------------------------------------------------------------------
-
-describe('writeWithoutPermit', () => {
-  test('warning when write trail has no permit', () => {
-    const t = trail('user.create', {
-      blaze: noopRun,
-      input: emptyInput,
-    });
-    const diagnostics = writeWithoutPermit([t]);
-    expect(diagnostics).toHaveLength(1);
-    expect(diagnostics[0]).toMatchObject({
-      rule: 'writeWithoutPermit',
-      severity: 'warning',
-      trailId: 'user.create',
-    });
-  });
-
-  test('no warning when write trail has permit: public', () => {
-    const t = trail('user.create', {
-      blaze: noopRun,
-      input: emptyInput,
-      permit: 'public',
-    });
-    const diagnostics = writeWithoutPermit([t]);
-    expect(diagnostics).toHaveLength(0);
-  });
-
-  test('warning when trail has no intent (defaults to write)', () => {
-    const t = trail('user.update', {
-      blaze: noopRun,
-      input: emptyInput,
-    });
-    // Override intent to undefined to simulate a manually constructed trail
-    const noIntent = { ...t, intent: undefined } as unknown as ReturnType<
-      typeof trail
-    >;
-    const diagnostics = writeWithoutPermit([noIntent]);
-    expect(diagnostics).toHaveLength(1);
-    expect(diagnostics[0]).toMatchObject({
-      rule: 'writeWithoutPermit',
-      severity: 'warning',
-      trailId: 'user.update',
-    });
-  });
-
-  test('no diagnostic for read trail without permit', () => {
-    const t = trail('user.list', {
-      blaze: noopRun,
-      input: emptyInput,
-      intent: 'read',
-    });
-    const diagnostics = writeWithoutPermit([t]);
-    expect(diagnostics).toHaveLength(0);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// scopeNamingConsistency
-// ---------------------------------------------------------------------------
-
-describe('scopeNamingConsistency', () => {
-  test('scope user:write passes naming check', () => {
-    const t = trail('user.update', {
-      blaze: noopRun,
-      input: emptyInput,
-      permit: { scopes: ['user:write'] },
-    });
-    const diagnostics = scopeNamingConsistency([t]);
-    expect(diagnostics).toHaveLength(0);
-  });
-
-  test('warning for scope without colon', () => {
-    const t = trail('admin.panel', {
-      blaze: noopRun,
-      input: emptyInput,
-      permit: { scopes: ['admin'] },
-    });
-    const diagnostics = scopeNamingConsistency([t]);
-    expect(diagnostics).toHaveLength(1);
-    expect(diagnostics[0]).toMatchObject({
-      message: expect.stringContaining('admin'),
-      rule: 'scopeNamingConsistency',
-      severity: 'warning',
-      trailId: 'admin.panel',
-    });
-  });
-});
-
-// ---------------------------------------------------------------------------
-// orphanScopeDetection
-// ---------------------------------------------------------------------------
-
-describe('orphanScopeDetection', () => {
-  test('warning for orphan scope (typo)', () => {
-    const t1 = trail('user.read', {
-      blaze: noopRun,
-      input: emptyInput,
-      permit: { scopes: ['user:read'] },
-    });
-    const t2 = trail('user.write', {
-      blaze: noopRun,
-      input: emptyInput,
-      permit: { scopes: ['user:wirte'] },
-    });
-    const diagnostics = orphanScopeDetection([t1, t2]);
-    // Both scopes are unique (appear in only 1 trail each)
-    expect(diagnostics).toHaveLength(2);
-    const messages = diagnostics.map((d) => d.message);
-    expect(messages.some((m) => m.includes('user:wirte'))).toBe(true);
-  });
-
-  test('no warning for shared scopes', () => {
-    const t1 = trail('user.read', {
-      blaze: noopRun,
-      input: emptyInput,
-      permit: { scopes: ['user:read'] },
-    });
-    const t2 = trail('user.profile', {
-      blaze: noopRun,
-      input: emptyInput,
-      permit: { scopes: ['user:read'] },
-    });
-    const diagnostics = orphanScopeDetection([t1, t2]);
-    expect(diagnostics).toHaveLength(0);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// validatePermits
-// ---------------------------------------------------------------------------
-
-/* oxlint-disable max-statements -- integration test validates all rules fire */
-describe('validatePermits', () => {
-  test('runs all rules and aggregates diagnostics', () => {
-    const destroyNoPerm = trail('user.delete', {
-      blaze: noopRun,
-      input: emptyInput,
-      intent: 'destroy',
-    });
-    const writeNoPerm = trail('user.create', {
-      blaze: noopRun,
-      input: emptyInput,
-    });
-    const badScope = trail('admin.panel', {
-      blaze: noopRun,
-      input: emptyInput,
-      permit: { scopes: ['admin'] },
-    });
-    const orphanScope = trail('analytics.export', {
-      blaze: noopRun,
-      input: emptyInput,
-      permit: { scopes: ['analytics:exportt'] },
-    });
-
-    const diagnostics = validatePermits([
-      destroyNoPerm,
-      writeNoPerm,
-      badScope,
-      orphanScope,
-    ]);
-
-    const rules = diagnostics.map((d) => d.rule);
-    expect(rules).toContain('destroyWithoutPermit');
-    expect(rules).toContain('writeWithoutPermit');
-    expect(rules).toContain('scopeNamingConsistency');
-    expect(rules).toContain('orphanScopeDetection');
-    expect(diagnostics.length).toBeGreaterThanOrEqual(4);
-  });
-});