@ontrails/permits 0.2.0

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,189 @@
+import type {
+  DiagnosticSeverity,
+  RuleDiagnosticBase,
+  Trail,
+} from '@ontrails/core';
+
+// ---------------------------------------------------------------------------
+// Diagnostic type
+// ---------------------------------------------------------------------------
+
+export type PermitDiagnosticSeverity = DiagnosticSeverity;
+
+/** A single governance finding from a permit rule. */
+export interface PermitDiagnostic extends RuleDiagnosticBase {
+  readonly trailId: string;
+  readonly rule: string;
+  readonly severity: PermitDiagnosticSeverity;
+  readonly message: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+type AnyTrail = Trail<unknown, 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: 'warn' 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: 'warn' 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: 'warn' 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, 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';
+
+/**
+ * Create a synthetic test permit with exactly the declared scopes.
+ * No admin permit, no wildcard — tests get only what the trail declares.
+ */
+export const createTestPermit = (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 creates a permit with exactly those scopes.
+ */
+export const createPermitForTrail = (trail: {
+  readonly permit?: PermitRequirement | undefined;
+}): Permit | undefined => {
+  if (!trail.permit || trail.permit === 'public') {
+    return undefined;
+  }
+  return createTestPermit({ scopes: trail.permit.scopes });
+};

package/src/trails/auth-verify.ts

@@ -0,0 +1,99 @@
+import { Result, SURFACE_KEY, trail } from '@ontrails/core';
+import type { TrailContext } from '@ontrails/core';
+import { z } from 'zod';
+
+import { authResource } from '../auth-resource.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 isSurfaceName = (
+  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 isSurfaceName(surface) ? surface : 'http';
+};
+
+/**
+ * Infrastructure trail that verifies a bearer token and returns the resolved permit.
+ *
+ * Reads the auth adapter from `authResource` — 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',
+    },
+  ],
+  implementation: async (input, ctx) => {
+    const adapter = authResource.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,
+    });
+  },
+  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],
+});