@ontrails/permits 1.0.0-beta.12

package/src/extraction.ts

@@ -0,0 +1,19 @@
+/**
+ * Normalized input for auth adapters.
+ *
+ * Each surface extracts raw credentials from its transport and normalizes
+ * them into this shape. No surface types (Request, McpSession, etc.) cross
+ * into core — only this interface.
+ */
+export interface PermitExtractionInput {
+  /** Which surface produced this extraction */
+  readonly surface: 'http' | 'mcp' | 'cli';
+  /** Bearer token from Authorization header or equivalent */
+  readonly bearerToken?: string;
+  /** Session identifier from transport handshake */
+  readonly sessionId?: string;
+  /** Raw headers (HTTP surface only, typically) */
+  readonly headers?: Headers;
+  /** Correlation ID for tracing */
+  readonly requestId: string;
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export {
+  type AuthAdapter,
+  type AuthCredentials,
+  type AuthError,
+} from './adapter.js';
+export { createJwtAdapter, type JwtAdapterOptions } from './adapters/jwt.js';
+export { authLayer } from './auth-layer.js';
+export { authService } from './auth-service.js';
+export { authVerify } from './trails/auth-verify.js';
+export { PermitError } from './errors.js';
+export { type PermitExtractionInput } from './extraction.js';
+export { type Permit, getPermit } from './permit.js';
+export { validatePermits, type PermitDiagnostic } from './rules.js';
+export { mintTestPermit, mintPermitForTrail } from './testing.js';

package/src/permit.ts

@@ -0,0 +1,26 @@
+import type { BasePermit } from '@ontrails/core';
+
+/** The resolved identity and scopes from a successful authentication. */
+export interface Permit extends BasePermit {
+  readonly roles?: readonly string[];
+  readonly tenantId?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Type-safe accessor for `ctx.permit` with a downcast to `Permit`.
+ *
+ * `TrailContext.permit` is typed as `BasePermit` (id + scopes). This accessor
+ * returns the full `Permit` when the auth layer has set one. Safe because
+ * the auth layer is the only writer and always sets a full `Permit`.
+ *
+ * @example
+ * ```typescript
+ * const permit = getPermit(ctx);
+ * if (permit) {
+ *   console.log(permit.roles, permit.tenantId);
+ * }
+ * ```
+ */
+export const getPermit = (ctx: { permit?: BasePermit }): Permit | undefined =>
+  ctx.permit === undefined ? undefined : (ctx.permit as Permit);

package/src/rules.ts

@@ -0,0 +1,183 @@
+import type { Trail } from '@ontrails/core';
+
+// ---------------------------------------------------------------------------
+// Diagnostic type
+// ---------------------------------------------------------------------------
+
+/** A single governance finding from a permit rule. */
+export interface PermitDiagnostic {
+  readonly trailId: string;
+  readonly rule: string;
+  readonly severity: 'error' | 'warning';
+  readonly message: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+type AnyTrail = Trail<unknown, unknown>;
+type Rule = (trails: readonly AnyTrail[]) => readonly PermitDiagnostic[];
+
+/** Check whether a trail has any permit declaration (scopes object or 'public'). */
+const hasPermit = (t: AnyTrail): boolean => t.permit !== undefined;
+
+/** Extract scopes from a trail's permit declaration, or empty array. */
+const getScopes = (t: AnyTrail): readonly string[] => {
+  if (t.permit !== undefined && t.permit !== 'public') {
+    return t.permit.scopes;
+  }
+  return [];
+};
+
+// ---------------------------------------------------------------------------
+// Rule: destroyWithoutPermit
+// ---------------------------------------------------------------------------
+
+/**
+ * Destructive trails without a real permit declaration are a governance failure.
+ *
+ * Reports an error for every trail with `intent: 'destroy'` that has no
+ * `permit` field or explicitly opts out with `permit: 'public'`.
+ */
+export const destroyWithoutPermit: Rule = (trails) =>
+  trails
+    .filter(
+      (t) => t.intent === 'destroy' && (!hasPermit(t) || t.permit === 'public')
+    )
+    .map((t) => ({
+      message: `Trail "${t.id}" has intent 'destroy' but no permit declaration`,
+      rule: 'destroyWithoutPermit',
+      severity: 'error' as const,
+      trailId: t.id,
+    }));
+
+// ---------------------------------------------------------------------------
+// Rule: writeWithoutPermit
+// ---------------------------------------------------------------------------
+
+/**
+ * Write trails without a permit declaration get a warning.
+ *
+ * Trails with `intent: 'write'` (or no intent, which defaults to write) that
+ * lack a permit are flagged unless `permit: 'public'` is explicitly set.
+ */
+export const writeWithoutPermit: Rule = (trails) =>
+  trails
+    .filter(
+      (t) => (t.intent === 'write' || t.intent === undefined) && !hasPermit(t)
+    )
+    .map((t) => ({
+      message: `Trail "${t.id}" has write intent but no permit declaration`,
+      rule: 'writeWithoutPermit',
+      severity: 'warning' as const,
+      trailId: t.id,
+    }));
+
+// ---------------------------------------------------------------------------
+// Rule: scopeNamingConsistency
+// ---------------------------------------------------------------------------
+
+/** Returns true when a scope follows the `entity:action` convention. */
+const isValidScopeFormat = (scope: string): boolean => {
+  const parts = scope.split(':');
+  return (
+    parts.length === 2 &&
+    (parts[0]?.length ?? 0) > 0 &&
+    (parts[1]?.length ?? 0) > 0
+  );
+};
+
+/**
+ * Warns for scopes that don't follow the `entity:action` convention.
+ *
+ * A valid scope contains exactly one colon separating a non-empty entity
+ * and a non-empty action.
+ */
+export const scopeNamingConsistency: Rule = (trails) =>
+  trails.flatMap((t) =>
+    getScopes(t)
+      .filter((scope) => !isValidScopeFormat(scope))
+      .map((scope) => ({
+        message: `Scope "${scope}" on trail "${t.id}" does not follow entity:action convention`,
+        rule: 'scopeNamingConsistency',
+        severity: 'warning' as const,
+        trailId: t.id,
+      }))
+  );
+
+// ---------------------------------------------------------------------------
+// Rule: orphanScopeDetection
+// ---------------------------------------------------------------------------
+
+/** Build a map of scope -> set of trail IDs that declare it. */
+const buildScopeMap = (
+  trails: readonly AnyTrail[]
+): ReadonlyMap<string, ReadonlySet<string>> => {
+  const map = new Map<string, Set<string>>();
+  for (const t of trails) {
+    for (const scope of getScopes(t)) {
+      const existing = map.get(scope);
+      if (existing) {
+        existing.add(t.id);
+      } else {
+        map.set(scope, new Set([t.id]));
+      }
+    }
+  }
+  return map;
+};
+
+/** Filter trails that have a scoped (non-public) permit declaration. */
+const trailsWithScopedPermit = (
+  trails: readonly AnyTrail[]
+): readonly AnyTrail[] =>
+  trails.filter((t) => t.permit !== undefined && t.permit !== 'public');
+
+/** Convert orphan scope map entries into diagnostics. */
+const orphanDiagnostics = (
+  scopeMap: ReadonlyMap<string, ReadonlySet<string>>
+): readonly PermitDiagnostic[] =>
+  [...scopeMap.entries()]
+    .filter(([, ids]) => ids.size === 1)
+    .map(([scope, ids]) => ({
+      message: `Scope "${scope}" appears only on trail "${[...ids][0]}" — possible typo`,
+      rule: 'orphanScopeDetection',
+      severity: 'warning' as const,
+      trailId: [...ids][0] ?? '',
+    }));
+
+/**
+ * Warns for scopes that appear in only one trail's permit.
+ *
+ * Catches typos like `user:wirte` by surfacing scopes not shared with any
+ * other trail. Only runs when at least 2 trails have permit declarations.
+ */
+export const orphanScopeDetection: Rule = (trails) => {
+  const scoped = trailsWithScopedPermit(trails);
+  if (scoped.length < 2) {
+    return [];
+  }
+  return orphanDiagnostics(buildScopeMap(scoped));
+};
+
+// ---------------------------------------------------------------------------
+// Top-level validator
+// ---------------------------------------------------------------------------
+
+const allRules: readonly Rule[] = [
+  destroyWithoutPermit,
+  writeWithoutPermit,
+  scopeNamingConsistency,
+  orphanScopeDetection,
+];
+
+/**
+ * Run all permit governance rules against a set of trails.
+ *
+ * Returns a flat array of diagnostics from every rule. An empty array
+ * means the topo passes all permit governance checks.
+ */
+export const validatePermits = (
+  trails: readonly Trail<unknown, unknown>[]
+): readonly PermitDiagnostic[] => allRules.flatMap((rule) => rule(trails));

package/src/testing.ts

@@ -0,0 +1,34 @@
+import type { PermitRequirement } from '@ontrails/core';
+
+import type { Permit } from './permit.js';
+
+/**
+ * Mint a synthetic test permit with exactly the declared scopes.
+ * No admin permit, no wildcard — tests get only what the trail declares.
+ */
+export const mintTestPermit = (options?: {
+  readonly id?: string;
+  readonly scopes?: readonly string[];
+  readonly roles?: readonly string[];
+  readonly tenantId?: string;
+}): Permit => ({
+  id:
+    options?.id ??
+    `test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  scopes: [...(options?.scopes ?? [])],
+  ...(options?.roles === undefined ? {} : { roles: [...options.roles] }),
+  ...(options?.tenantId === undefined ? {} : { tenantId: options.tenantId }),
+});
+
+/**
+ * Create a test permit matching a trail's permit requirement.
+ * Extracts scopes from the requirement and mints a permit with exactly those scopes.
+ */
+export const mintPermitForTrail = (trail: {
+  readonly permit?: PermitRequirement | undefined;
+}): Permit | undefined => {
+  if (!trail.permit || trail.permit === 'public') {
+    return undefined;
+  }
+  return mintTestPermit({ scopes: trail.permit.scopes });
+};

package/src/trails/auth-verify.ts

@@ -0,0 +1,97 @@
+import { Result, SURFACE_KEY, trail } from '@ontrails/core';
+import type { TrailContext } from '@ontrails/core';
+import { z } from 'zod';
+
+import { authService } from '../auth-service.js';
+import type { PermitExtractionInput } from '../extraction.js';
+import type { Permit } from '../permit.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) => ({
+  ...(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 isSurface = (value: unknown): value is PermitExtractionInput['surface'] =>
+  value === 'http' || value === 'mcp' || value === 'cli';
+
+const getSurface = (ctx: TrailContext): PermitExtractionInput['surface'] => {
+  const surface = ctx.extensions?.[SURFACE_KEY];
+  return isSurface(surface) ? surface : 'http';
+};
+
+/**
+ * Infrastructure trail that verifies a bearer token and returns the resolved permit.
+ *
+ * Reads the auth adapter from `authService` — the adapter is configured at
+ * bootstrap (e.g. JWT with HMAC secret). The mock adapter always succeeds with
+ * a null permit, so `testAll(app)` works without configuration.
+ */
+export const authVerify = trail('auth.verify', {
+  examples: [
+    {
+      input: { token: 'test-token' },
+      name: 'Verify a token',
+    },
+  ],
+  input: z.object({
+    token: z.string().min(1).describe('Bearer token to verify'),
+  }),
+  intent: 'read',
+  metadata: { category: 'infrastructure' },
+  output: z.object({
+    error: z.string().optional(),
+    errorCode: authErrorCodeSchema.optional(),
+    permit: permitSchema.optional(),
+    valid: z.boolean(),
+  }),
+  run: async (input, ctx) => {
+    const adapter = authService.from(ctx);
+    const result = await adapter.authenticate({
+      bearerToken: input.token,
+      requestId: ctx.requestId,
+      surface: getSurface(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,
+    });
+  },
+  services: [authService],
+});

package/tsconfig.json

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

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/adapter.ts","./src/auth-layer.ts","./src/auth-service.ts","./src/errors.ts","./src/extraction.ts","./src/index.ts","./src/permit.ts","./src/rules.ts","./src/testing.ts","./src/adapters/jwt.ts","./src/trails/auth-verify.ts"],"version":"5.9.3"}