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

package/dist/trails/auth-verify.js

@@ -1,85 +0,0 @@
-import { Result, TRAILHEAD_KEY, trail } from '@ontrails/core';
-import { z } from 'zod';
-import { authResource } from '../auth-resource.js';
-const permitSchema = z.object({
-    id: z.string(),
-    metadata: z.record(z.string(), z.unknown()).optional(),
-    roles: z.array(z.string()).optional(),
-    scopes: z.array(z.string()),
-    tenantId: z.string().optional(),
-});
-const authErrorCodeSchema = z.enum([
-    'expired_token',
-    'insufficient_scope',
-    'invalid_token',
-    'missing_credentials',
-]);
-const toOutputPermit = (permit) => ({
-    ...(permit.metadata === undefined
-        ? {}
-        : { metadata: { ...permit.metadata } }),
-    ...(permit.roles === undefined ? {} : { roles: [...permit.roles] }),
-    ...(permit.tenantId === undefined ? {} : { tenantId: permit.tenantId }),
-    id: permit.id,
-    scopes: [...permit.scopes],
-});
-const isTrailhead = (value) => value === 'http' || value === 'mcp' || value === 'cli';
-const getTrailhead = (ctx) => {
-    const trailhead = ctx.extensions?.[TRAILHEAD_KEY];
-    return isTrailhead(trailhead) ? trailhead : 'http';
-};
-/**
- * Infrastructure trail that verifies a bearer token and returns the resolved permit.
- *
- * Reads the auth connector from `authResource` — the connector is configured
- * at bootstrap (e.g. JWT with HMAC secret). The mock connector always
- * succeeds with a null permit, so `testAll(app)` works without configuration.
- */
-export const authVerify = trail('auth.verify', {
-    blaze: async (input, ctx) => {
-        const connector = authResource.from(ctx);
-        const result = await connector.authenticate({
-            bearerToken: input.token,
-            requestId: ctx.requestId,
-            trailhead: getTrailhead(ctx),
-        });
-        if (result.isErr()) {
-            return Result.ok({
-                error: result.error.message,
-                errorCode: result.error.code,
-                valid: false,
-            });
-        }
-        const permit = result.value;
-        if (!permit) {
-            return Result.ok({
-                error: 'No credentials',
-                errorCode: 'missing_credentials',
-                valid: false,
-            });
-        }
-        return Result.ok({
-            permit: toOutputPermit(permit),
-            valid: true,
-        });
-    },
-    examples: [
-        {
-            input: { token: 'test-token' },
-            name: 'Verify a token',
-        },
-    ],
-    input: z.object({
-        token: z.string().min(1).describe('Bearer token to verify'),
-    }),
-    intent: 'read',
-    meta: { category: 'infrastructure' },
-    output: z.object({
-        error: z.string().optional(),
-        errorCode: authErrorCodeSchema.optional(),
-        permit: permitSchema.optional(),
-        valid: z.boolean(),
-    }),
-    resources: [authResource],
-});
-//# sourceMappingURL=auth-verify.js.map

package/dist/trails/auth-verify.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"auth-verify.js","sourceRoot":"","sources":["../../src/trails/auth-verify.ts"],"names":[],"mappings":"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"}

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

@@ -1,130 +0,0 @@
-/* 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 => ({
-  abortSignal: AbortSignal.timeout(5000),
-  permit,
-  requestId: 'test-auth',
-});
-
-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', {
-        blaze: okImpl,
-        input: z.object({}),
-        output: z.object({ done: z.boolean() }),
-      });
-
-      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', {
-        blaze: okImpl,
-        input: z.object({}),
-        output: z.object({ done: z.boolean() }),
-        permit: 'public',
-      });
-
-      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', {
-      blaze: okImpl,
-      input: z.object({}),
-      output: z.object({ done: z.boolean() }),
-      permit: { scopes: ['user:read'] },
-    });
-
-    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', {
-        blaze: okImpl,
-        input: z.object({}),
-        output: z.object({ done: z.boolean() }),
-        permit: { scopes: ['user:read', 'user:write'] },
-      });
-
-      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-resource.test.ts

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

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 { authResource } from '../auth-resource.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 resource. */
-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 } },
-      resources: { [authResource.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 authResource dependency', () => {
-      expect(authVerify.resources).toHaveLength(1);
-      expect(authVerify.resources[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: '' },
-        {
-          resources: { [authResource.id]: jwtConnector() },
-        }
-      );
-
-      expect(result.isErr()).toBe(true);
-      expect(result.error).toBeInstanceOf(ValidationError);
-    });
-  });
-});