@ontrails/permits 1.0.0-beta.12

package/src/__tests__/rules.test.ts

@@ -0,0 +1,239 @@
+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', {
+      input: emptyInput,
+      intent: 'destroy',
+      run: noopRun,
+    });
+    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', {
+      input: emptyInput,
+      intent: 'destroy',
+      permit: { scopes: ['user:delete'] },
+      run: noopRun,
+    });
+    const diagnostics = destroyWithoutPermit([t]);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test('error when destroy trail has permit: public', () => {
+    const t = trail('user.delete', {
+      input: emptyInput,
+      intent: 'destroy',
+      permit: 'public',
+      run: noopRun,
+    });
+    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', {
+      input: emptyInput,
+      run: noopRun,
+    });
+    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', {
+      input: emptyInput,
+      permit: 'public',
+      run: noopRun,
+    });
+    const diagnostics = writeWithoutPermit([t]);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test('warning when trail has no intent (defaults to write)', () => {
+    const t = trail('user.update', {
+      input: emptyInput,
+      run: noopRun,
+    });
+    // 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', {
+      input: emptyInput,
+      intent: 'read',
+      run: noopRun,
+    });
+    const diagnostics = writeWithoutPermit([t]);
+    expect(diagnostics).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// scopeNamingConsistency
+// ---------------------------------------------------------------------------
+
+describe('scopeNamingConsistency', () => {
+  test('scope user:write passes naming check', () => {
+    const t = trail('user.update', {
+      input: emptyInput,
+      permit: { scopes: ['user:write'] },
+      run: noopRun,
+    });
+    const diagnostics = scopeNamingConsistency([t]);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test('warning for scope without colon', () => {
+    const t = trail('admin.panel', {
+      input: emptyInput,
+      permit: { scopes: ['admin'] },
+      run: noopRun,
+    });
+    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', {
+      input: emptyInput,
+      permit: { scopes: ['user:read'] },
+      run: noopRun,
+    });
+    const t2 = trail('user.write', {
+      input: emptyInput,
+      permit: { scopes: ['user:wirte'] },
+      run: noopRun,
+    });
+    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', {
+      input: emptyInput,
+      permit: { scopes: ['user:read'] },
+      run: noopRun,
+    });
+    const t2 = trail('user.profile', {
+      input: emptyInput,
+      permit: { scopes: ['user:read'] },
+      run: noopRun,
+    });
+    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', {
+      input: emptyInput,
+      intent: 'destroy',
+      run: noopRun,
+    });
+    const writeNoPerm = trail('user.create', {
+      input: emptyInput,
+      run: noopRun,
+    });
+    const badScope = trail('admin.panel', {
+      input: emptyInput,
+      permit: { scopes: ['admin'] },
+      run: noopRun,
+    });
+    const orphanScope = trail('analytics.export', {
+      input: emptyInput,
+      permit: { scopes: ['analytics:exportt'] },
+      run: noopRun,
+    });
+
+    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);
+  });
+});

package/src/__tests__/testing.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from 'bun:test';
+
+import { mintPermitForTrail, mintTestPermit } from '../testing';
+
+describe('mintTestPermit()', () => {
+  test('returns a Permit with the given scopes', () => {
+    const permit = mintTestPermit({ scopes: ['user:read', 'user:write'] });
+    expect(permit.scopes).toEqual(['user:read', 'user:write']);
+  });
+
+  test('generates a unique id when not specified', () => {
+    const a = mintTestPermit();
+    const b = mintTestPermit();
+    expect(a.id).not.toBe(b.id);
+  });
+
+  test('uses the provided id when specified', () => {
+    const permit = mintTestPermit({ id: 'custom-id' });
+    expect(permit.id).toBe('custom-id');
+  });
+
+  test('returns empty scopes when no options provided', () => {
+    const permit = mintTestPermit();
+    expect(permit.scopes).toEqual([]);
+  });
+
+  test('includes roles when provided', () => {
+    const permit = mintTestPermit({ roles: ['admin', 'editor'] });
+    expect(permit.roles).toEqual(['admin', 'editor']);
+  });
+
+  test('includes tenantId when provided', () => {
+    const permit = mintTestPermit({ tenantId: 'tenant_abc' });
+    expect(permit.tenantId).toBe('tenant_abc');
+  });
+});
+
+describe('mintPermitForTrail()', () => {
+  test('extracts scopes from trail permit requirement', () => {
+    const trail = { permit: { scopes: ['entity:read', 'entity:write'] } };
+    const permit = mintPermitForTrail(trail);
+    expect(permit).toBeDefined();
+    expect(permit?.scopes).toEqual(['entity:read', 'entity:write']);
+  });
+
+  test('returns undefined for public trails', () => {
+    const trail = { permit: 'public' as const };
+    const permit = mintPermitForTrail(trail);
+    expect(permit).toBeUndefined();
+  });
+
+  test('returns undefined when no permit declared', () => {
+    const trail = {};
+    const permit = mintPermitForTrail(trail);
+    expect(permit).toBeUndefined();
+  });
+});

package/src/adapter.ts

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

package/src/adapters/jwt.ts

@@ -0,0 +1,230 @@
+import { Result } from '@ontrails/core';
+
+import type { AuthAdapter, AuthError } from '../adapter.js';
+import type { PermitExtractionInput } from '../extraction.js';
+import type { Permit } from '../permit.js';
+
+/** Configuration for the JWT auth adapter. */
+export interface JwtAdapterOptions {
+  /** HMAC secret for HS256 verification. */
+  readonly secret?: string;
+  /** JWKS endpoint for RS256/ES256 (not yet implemented). */
+  readonly jwksUrl?: string;
+  /** Expected issuer claim. */
+  readonly issuer?: string;
+  /** Expected audience claim. */
+  readonly audience?: string;
+  /** Claim containing scopes (default: 'scope'). */
+  readonly scopesClaim?: string;
+  /** Claim containing roles (default: 'roles'). */
+  readonly rolesClaim?: string;
+}
+
+/** JWT payload with standard claims. */
+interface JwtPayload {
+  readonly sub?: string;
+  readonly iss?: string;
+  readonly aud?: string | readonly string[];
+  readonly exp?: number;
+  readonly [key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers (defined before callers)
+// ---------------------------------------------------------------------------
+
+const authErr = (
+  code: AuthError['code'],
+  message: string
+): Result<never, AuthError> => Result.err({ code, message });
+
+/** Base64url-decode a string to bytes. */
+const base64urlDecode = (input: string): Uint8Array => {
+  const padded = input
+    .replaceAll('-', '+')
+    .replaceAll('_', '/')
+    .padEnd(input.length + ((4 - (input.length % 4)) % 4), '=');
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) {
+    bytes[i] = binary.codePointAt(i) ?? 0;
+  }
+  return bytes;
+};
+
+/** Decode a JWT payload without verifying the signature. */
+const decodePayload = (token: string): JwtPayload | undefined => {
+  const parts = token.split('.');
+  if (parts.length !== 3) {
+    return undefined;
+  }
+  try {
+    const json = new TextDecoder().decode(base64urlDecode(parts[1] ?? ''));
+    return JSON.parse(json) as JwtPayload;
+  } catch {
+    return undefined;
+  }
+};
+
+/** Import a secret as an HMAC CryptoKey. */
+const importHmacKey = (secret: string): Promise<CryptoKey> => {
+  const encoder = new TextEncoder();
+  return crypto.subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    { hash: 'SHA-256', name: 'HMAC' },
+    false,
+    ['verify']
+  );
+};
+
+/** Verify the HMAC-SHA256 signature of a JWT. */
+const verifyHmacSignature = (
+  token: string,
+  key: CryptoKey
+): Promise<boolean> => {
+  const lastDot = token.lastIndexOf('.');
+  if (lastDot === -1) {
+    return Promise.resolve(false);
+  }
+  const data = token.slice(0, lastDot);
+  const signature = base64urlDecode(token.slice(lastDot + 1));
+  const encoder = new TextEncoder();
+  return crypto.subtle.verify(
+    'HMAC',
+    key,
+    signature.buffer as ArrayBuffer,
+    encoder.encode(data)
+  );
+};
+
+/** Validate standard claims (exp, iss, aud). */
+const validateClaims = (
+  payload: JwtPayload,
+  options: JwtAdapterOptions
+): AuthError | undefined => {
+  if (
+    payload.exp !== undefined &&
+    payload.exp < Math.floor(Date.now() / 1000)
+  ) {
+    return { code: 'expired_token', message: 'Token has expired' };
+  }
+  if (options.issuer && payload.iss !== options.issuer) {
+    return { code: 'invalid_token', message: 'Issuer mismatch' };
+  }
+  if (options.audience) {
+    const { aud } = payload;
+    const matches = Array.isArray(aud)
+      ? aud.includes(options.audience)
+      : aud === options.audience;
+    if (!matches) {
+      return { code: 'invalid_token', message: 'Audience mismatch' };
+    }
+  }
+  return undefined;
+};
+
+/** Extract scopes from a payload claim (space-separated string or array). */
+const extractScopes = (
+  payload: JwtPayload,
+  claim: string
+): readonly string[] => {
+  const raw = payload[claim];
+  if (typeof raw === 'string') {
+    return raw.split(' ').filter(Boolean);
+  }
+  if (Array.isArray(raw)) {
+    return raw.filter(
+      (s): s is string => typeof s === 'string' && s.length > 0
+    );
+  }
+  return [];
+};
+
+/** Extract roles from a payload claim (string array). */
+const extractRoles = (
+  payload: JwtPayload,
+  claim: string
+): readonly string[] | undefined => {
+  const raw = payload[claim];
+  if (!Array.isArray(raw)) {
+    return undefined;
+  }
+  return raw.filter((r): r is string => typeof r === 'string');
+};
+
+/** Build a Permit from a validated JWT payload. */
+const buildPermit = (
+  payload: JwtPayload,
+  options: JwtAdapterOptions
+): Result<Permit, AuthError> => {
+  if (!payload.sub) {
+    return authErr('invalid_token', 'Missing subject claim (sub)');
+  }
+  const roles = extractRoles(payload, options.rolesClaim ?? 'roles');
+  return Result.ok({
+    id: payload.sub,
+    scopes: extractScopes(payload, options.scopesClaim ?? 'scope'),
+    ...(roles ? { roles } : {}),
+  });
+};
+
+/** Verify the signature and return the decoded payload, or an error. */
+const decodeAndVerify = async (
+  token: string,
+  secret: string
+): Promise<Result<JwtPayload, AuthError>> => {
+  const payload = decodePayload(token);
+  if (!payload) {
+    return authErr('invalid_token', 'Malformed JWT');
+  }
+  try {
+    const key = await importHmacKey(secret);
+    const valid = await verifyHmacSignature(token, key);
+    return valid
+      ? Result.ok(payload)
+      : authErr('invalid_token', 'Invalid signature');
+  } catch {
+    return authErr('invalid_token', 'Malformed token signature');
+  }
+};
+
+/** Validate claims and build a permit from a verified payload. */
+const payloadToPermit = (
+  payload: JwtPayload,
+  options: JwtAdapterOptions
+): Result<Permit, AuthError> => {
+  const claimError = validateClaims(payload, options);
+  if (claimError) {
+    return Result.err(claimError);
+  }
+  return buildPermit(payload, options);
+};
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a JWT auth adapter 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 => {
+  const authenticate = async (
+    input: PermitExtractionInput
+  ): Promise<Result<Permit | null, AuthError>> => {
+    if (!input.bearerToken) {
+      return Result.ok(null);
+    }
+    if (!options.secret) {
+      return authErr('invalid_token', 'No secret configured');
+    }
+    const decoded = await decodeAndVerify(input.bearerToken, options.secret);
+    return decoded.isErr() ? decoded : payloadToPermit(decoded.value, options);
+  };
+
+  return { authenticate };
+};

package/src/auth-layer.ts

@@ -0,0 +1,80 @@
+import { Result } from '@ontrails/core';
+import type { Layer } from '@ontrails/core';
+
+import { PermitError } from './errors.js';
+import { getPermit } from './permit.js';
+
+// ---------------------------------------------------------------------------
+// Helpers (defined before callers — no use-before-define)
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns `true` when the permit requirement means "no enforcement needed."
+ * Either the trail hasn't declared a permit posture or has explicitly
+ * opted out with `'public'`.
+ */
+const isPassThrough = (
+  requirement: unknown
+): requirement is undefined | 'public' =>
+  requirement === undefined || requirement === 'public';
+
+/** Returns scopes present in `required` but absent from `held`. */
+const findMissing = (
+  required: readonly string[],
+  held: readonly string[]
+): readonly string[] => required.filter((s) => !held.includes(s));
+
+// ---------------------------------------------------------------------------
+// Auth layer
+// ---------------------------------------------------------------------------
+
+/**
+ * A {@link Layer} that enforces permit scopes declared on trails.
+ *
+ * The layer 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
+ *   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
+ * architecture.
+ */
+export const authLayer: Layer = {
+  description: 'Enforces permit scopes declared on trails',
+  name: 'auth',
+  wrap: (_trail, impl) => {
+    const requirement = _trail.permit;
+
+    if (isPassThrough(requirement)) {
+      return impl;
+    }
+
+    return (input, ctx) => {
+      const permit = getPermit(ctx);
+
+      if (!permit) {
+        return Promise.resolve(
+          Result.err(new PermitError('No permit provided'))
+        );
+      }
+
+      const missing = findMissing(requirement.scopes, permit.scopes);
+
+      if (missing.length > 0) {
+        return Promise.resolve(
+          Result.err(
+            new PermitError(`Missing scopes: ${missing.join(', ')}`, {
+              context: { missing, required: requirement.scopes },
+            })
+          )
+        );
+      }
+
+      return Promise.resolve(impl(input, ctx));
+    };
+  },
+};

package/src/auth-service.ts

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

package/src/errors.ts

@@ -0,0 +1,18 @@
+import { PermissionError } from '@ontrails/core';
+
+/**
+ * Error returned when permit scope enforcement fails.
+ *
+ * Extends `PermissionError` (category `'permission'`, HTTP 403) because
+ * it represents an *authorization* failure — the caller's identity is known
+ * but lacks the required scopes.
+ */
+export class PermitError extends PermissionError {
+  constructor(
+    message: string,
+    options?: { cause?: Error; context?: Record<string, unknown> }
+  ) {
+    super(message, options);
+    this.name = 'PermitError';
+  }
+}