@ontrails/permits 1.0.0-beta.12

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

@@ -0,0 +1,130 @@
+/* oxlint-disable require-await -- layer wrappers satisfy async interfaces without awaiting */
+import { describe, expect, test } from 'bun:test';
+
+import { Result, trail } from '@ontrails/core';
+import type { TrailContext } from '@ontrails/core';
+import { z } from 'zod';
+
+import { authLayer } from '../auth-layer';
+import { PermitError } from '../errors';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const makeCtx = (permit?: {
+  id: string;
+  scopes: readonly string[];
+}): TrailContext => ({
+  permit,
+  requestId: 'test-auth',
+  signal: AbortSignal.timeout(5000),
+});
+
+const okImpl = async () => Result.ok({ done: true });
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('authLayer', () => {
+  test('has correct name and description', () => {
+    expect(authLayer.name).toBe('auth');
+    expect(authLayer.description).toBeDefined();
+  });
+
+  describe('pass-through cases', () => {
+    test('passes through when trail has no permit field', async () => {
+      const t = trail('test.nopermit', {
+        input: z.object({}),
+        output: z.object({ done: z.boolean() }),
+        run: okImpl,
+      });
+
+      const wrapped = authLayer.wrap(t, okImpl);
+      const result = await wrapped({}, makeCtx());
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({ done: true });
+    });
+
+    test('passes through when trail permit is public', async () => {
+      const t = trail('test.public', {
+        input: z.object({}),
+        output: z.object({ done: z.boolean() }),
+        permit: 'public',
+        run: okImpl,
+      });
+
+      const wrapped = authLayer.wrap(t, okImpl);
+      const result = await wrapped({}, makeCtx());
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({ done: true });
+    });
+  });
+
+  describe('scope enforcement', () => {
+    const scopedTrail = trail('test.scoped', {
+      input: z.object({}),
+      output: z.object({ done: z.boolean() }),
+      permit: { scopes: ['user:read'] },
+      run: okImpl,
+    });
+
+    test('passes when ctx.permit has matching scopes', async () => {
+      const wrapped = authLayer.wrap(scopedTrail, okImpl);
+      const result = await wrapped(
+        {},
+        makeCtx({ id: 'usr-1', scopes: ['user:read'] })
+      );
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({ done: true });
+    });
+
+    test('returns error when ctx has no permit', async () => {
+      const wrapped = authLayer.wrap(scopedTrail, okImpl);
+      const result = await wrapped({}, makeCtx());
+
+      expect(result.isErr()).toBe(true);
+      const err = (result as unknown as { error: PermitError }).error;
+      expect(err).toBeInstanceOf(PermitError);
+      expect(err.message).toContain('No permit');
+    });
+
+    test('returns error when permit is missing required scopes', async () => {
+      const multiScopeTrail = trail('test.multi', {
+        input: z.object({}),
+        output: z.object({ done: z.boolean() }),
+        permit: { scopes: ['user:read', 'user:write'] },
+        run: okImpl,
+      });
+
+      const wrapped = authLayer.wrap(multiScopeTrail, okImpl);
+      const result = await wrapped(
+        {},
+        makeCtx({ id: 'usr-1', scopes: ['user:read'] })
+      );
+
+      expect(result.isErr()).toBe(true);
+      const err = (result as unknown as { error: PermitError }).error;
+      expect(err).toBeInstanceOf(PermitError);
+      expect(err.message).toContain('user:write');
+    });
+
+    test('passes when permit has superset of required scopes', async () => {
+      const wrapped = authLayer.wrap(scopedTrail, okImpl);
+      const result = await wrapped(
+        {},
+        makeCtx({
+          id: 'usr-1',
+          scopes: ['user:read', 'user:write', 'admin'],
+        })
+      );
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({ done: true });
+    });
+  });
+});

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

@@ -0,0 +1,62 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { ServiceContext } from '@ontrails/core';
+
+import type { AuthAdapter } from '../adapter.js';
+import { authService } from '../auth-service.js';
+import type { PermitExtractionInput } from '../extraction.js';
+
+/** Minimal extraction input for tests. */
+const testInput = (
+  overrides?: Partial<PermitExtractionInput>
+): PermitExtractionInput => ({
+  requestId: 'test-svc-req',
+  surface: 'http',
+  ...overrides,
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const testSvcCtx: ServiceContext = {
+  config: undefined,
+  cwd: '/tmp',
+  env: {},
+  workspaceRoot: '/tmp',
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('authService', () => {
+  test('has correct id and kind', () => {
+    expect(authService.id).toBe('auth');
+    expect(authService.kind).toBe('service');
+  });
+
+  test('has infrastructure metadata', () => {
+    expect(authService.metadata).toEqual({ category: 'infrastructure' });
+  });
+
+  test('mock returns an AuthAdapter', async () => {
+    const mock = authService.mock?.();
+    expect(mock).toBeDefined();
+
+    const adapter = mock as AuthAdapter;
+    const result = await adapter.authenticate(testInput());
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toBeNull();
+  });
+
+  test('create returns Result.ok with an AuthAdapter', async () => {
+    const result = await authService.create(testSvcCtx);
+    expect(result.isOk()).toBe(true);
+
+    const adapter = result.unwrap() as AuthAdapter;
+    const authResult = await adapter.authenticate(testInput());
+    expect(authResult.isOk()).toBe(true);
+    expect(authResult.unwrap()).toBeNull();
+  });
+});

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

@@ -0,0 +1,277 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  Result,
+  SURFACE_KEY,
+  ValidationError,
+  executeTrail,
+} from '@ontrails/core';
+
+import type { AuthAdapter } from '../adapter.js';
+import { authService } from '../auth-service.js';
+import { createJwtAdapter } from '../adapters/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 AuthAdapter wired to a JWT secret. */
+const jwtAdapter = (): AuthAdapter => createJwtAdapter({ secret: TEST_SECRET });
+
+/** Execute auth.verify with a given adapter injected as the auth service. */
+const runVerify = async (
+  token: string,
+  adapter: AuthAdapter,
+  options?: {
+    surface?: '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?.surface === undefined
+          ? undefined
+          : { extensions: { [SURFACE_KEY]: options.surface } },
+      services: { [authService.id]: adapter },
+    }
+  );
+  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 metadata', () => {
+      expect(authVerify.metadata).toEqual({ category: 'infrastructure' });
+    });
+
+    test('has examples', () => {
+      expect(authVerify.examples).toBeDefined();
+      expect(authVerify.examples?.length).toBeGreaterThan(0);
+    });
+
+    test('declares authService dependency', () => {
+      expect(authVerify.services).toHaveLength(1);
+      expect(authVerify.services[0]?.id).toBe('auth');
+    });
+  });
+
+  describe('with mock adapter (no credentials)', () => {
+    test('returns valid: false with error message', async () => {
+      const noopAdapter: AuthAdapter = {
+        // oxlint-disable-next-line require-await -- satisfies async interface
+        authenticate: async () => Result.ok(null),
+      };
+
+      const result = await runVerify('some-token', noopAdapter);
+
+      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, jwtAdapter());
+
+      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 adapter', async () => {
+      const permit: Permit = {
+        id: 'user-42',
+        metadata: { plan: 'pro' },
+        roles: ['admin'],
+        scopes: ['read', 'write'],
+        tenantId: 'tenant-1',
+      };
+      const adapter: AuthAdapter = {
+        // oxlint-disable-next-line require-await -- satisfies async interface
+        authenticate: async () => Result.ok(permit),
+      };
+
+      const result = await runVerify('full-permit-token', adapter);
+
+      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 surface from trail context', async () => {
+      let seenSurface: string | undefined;
+      const adapter: AuthAdapter = {
+        // oxlint-disable-next-line require-await -- captures adapter input
+        authenticate: async (input) => {
+          seenSurface = input.surface;
+          return Result.ok({
+            id: 'user-42',
+            scopes: ['read'],
+          });
+        },
+      };
+
+      const result = await runVerify('surface-aware-token', adapter, {
+        surface: 'mcp',
+      });
+
+      expect(result.isOk()).toBe(true);
+      expect(seenSurface).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, jwtAdapter());
+
+      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, jwtAdapter());
+
+      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: '' },
+        {
+          services: { [authService.id]: jwtAdapter() },
+        }
+      );
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(ValidationError);
+    });
+  });
+});

package/src/__tests__/permit.test.ts

@@ -0,0 +1,122 @@
+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 surface extraction', () => {
+    const input: PermitExtractionInput = {
+      bearerToken: 'eyJhbGciOiJSUzI1NiJ9.test',
+      headers: new Headers({
+        authorization: 'Bearer eyJhbGciOiJSUzI1NiJ9.test',
+      }),
+      requestId: 'req-http-1',
+      surface: 'http',
+    };
+    expect(input.surface).toBe('http');
+    expect(input.bearerToken).toBeDefined();
+  });
+
+  test('accepts MCP surface extraction', () => {
+    const input: PermitExtractionInput = {
+      requestId: 'req-mcp-1',
+      sessionId: 'mcp-session-abc',
+      surface: 'mcp',
+    };
+    expect(input.surface).toBe('mcp');
+    expect(input.sessionId).toBe('mcp-session-abc');
+  });
+
+  test('accepts CLI surface extraction', () => {
+    const input: PermitExtractionInput = {
+      bearerToken: 'cli-token-from-keyring',
+      requestId: 'req-cli-1',
+      surface: 'cli',
+    };
+    expect(input.surface).toBe('cli');
+  });
+
+  test('accepts minimal extraction with only required fields', () => {
+    const input: PermitExtractionInput = {
+      requestId: 'req-minimal',
+      surface: 'http',
+    };
+    expect(input.requestId).toBe('req-minimal');
+    expect(input.bearerToken).toBeUndefined();
+    expect(input.sessionId).toBeUndefined();
+    expect(input.headers).toBeUndefined();
+  });
+});