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

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 gate', () => {
-    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);
-  });
-});

package/src/__tests__/testing.test.ts

@@ -1,57 +0,0 @@
-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/auth-gate.ts

@@ -1,80 +0,0 @@
-import { Result } from '@ontrails/core';
-import type { Gate } 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 gate
-// ---------------------------------------------------------------------------
-
-/**
- * A {@link Gate} that enforces permit scopes declared on trails.
- *
- * The gate reads the trail's `permit` field (a `PermitRequirement`):
- *
- * - If `permit` is `'public'` or `undefined` the gate passes through.
- * - If `permit` has `scopes`, the gate checks that `ctx.permit` contains
- *   all required scopes. A superset is fine; missing scopes produce a
- *   `PermitError`.
- *
- * Because `ctx.cross()` re-enters `executeTrail` (which applies gates),
- * this gate automatically re-checks on every invocation in a crossing chain.
- * No special crossing-chain handling is needed — it is built into the
- * architecture.
- */
-export const authGate: Gate = {
-  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-provision.ts

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

package/src/connectors/connector.ts

@@ -1,35 +0,0 @@
-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 connectors. */
-export interface AuthError {
-  readonly code:
-    | 'expired_token'
-    | 'insufficient_scope'
-    | 'invalid_token'
-    | 'missing_credentials';
-  readonly message: string;
-}
-
-/**
- * Auth connector port. Given extraction input, produce a permit or an error.
- *
- * The connector receives the full {@link PermitExtractionInput} — trailhead,
- * headers, requestId, and credential fields — so it can make richer
- * decisions (e.g., rate-limit by trailhead or correlate via requestId).
- *
- * Deliberately narrow — no session management, no token refresh.
- */
-export interface AuthConnector {
-  readonly authenticate: (
-    input: PermitExtractionInput
-  ) => Promise<Result<Permit | null, AuthError>>;
-}

package/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src"
-  },
-  "include": ["src"],
-  "exclude": ["**/__tests__/**", "**/*.test.ts", "dist"]
-}

package/tsconfig.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["./src/auth-gate.ts","./src/auth-provision.ts","./src/errors.ts","./src/extraction.ts","./src/index.ts","./src/permit.ts","./src/rules.ts","./src/testing.ts","./src/connectors/connector.ts","./src/connectors/jwt.ts","./src/trails/auth-verify.ts"],"version":"5.9.3"}