@ontrails/permits 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,416 @@
+# @ontrails/permits
+
+## 0.2.0
+
+### Patch Changes
+
+- [`664e8bb`](https://github.com/outfitter-dev/trails/commit/664e8bb049e61f1d47cec1dd246606707af5d1a8): Point public installation examples at exact approved 0.2.0 versions and distinguish the prepared source release from pending npm publication.
+- [`b3ddf91`](https://github.com/outfitter-dev/trails/commit/b3ddf918ada8211f44983512e2bbdfbc5b66d722): Prepare the first normal Trails release at `0.2.0` on `latest`, replacing the unpublished 1.0.0 source release. The target advances the original `0.1.0` source minor, which was never published under the current package names. Public packages remain in lockstep. Update consumer installation guidance and provide a temporary manifest bridge for old 1.0 beta sources. Published beta versions remain unchanged; minor 0.x releases may carry documented breaking changes.
+
+  The `1.0.0` section retained below records an unpublished preparation, not an npm release. Its accumulated changes are included in `0.2.0`; the section remains as source history alongside the published beta entries.
+
+## 1.0.0
+
+### Major Changes
+
+- [`200bece`](https://github.com/outfitter-dev/trails/commit/200bece897d79af9029492d7cbbe400cf9e4d25c): BREAKING: rename auth connector vocabulary to adapter.
+
+  This stays on the current `1.0.0-beta` prerelease line: the package is part of
+  the fixed `@ontrails/*` beta group, so beta-breaking API renames advance the
+  next beta rather than opening a stable-major release line.
+
+  - `AuthConnector` -> `AuthAdapter`
+  - `authConnectorSchema` -> `authAdapterSchema`
+  - `JwtConnectorOptions` -> `JwtAdapterOptions`
+  - `createJwtConnector` -> `createJwtAdapter`
+  - auth resource config discriminant `{ connector: 'jwt' | 'none' }` -> `{ adapter: 'jwt' | 'none' }`
+
+  The `@ontrails/permits/jwt` subpath is unchanged. The internal `connectors/`
+  source directory becomes `adapters/`. See
+  `docs/migration/connector-to-adapter.md` for the full rename map.
+
+  The Trails CLI package updates its generated auth-resource configuration to use
+  the new `adapter` discriminant.
+
+### Minor Changes
+
+- [`73622ae`](https://github.com/outfitter-dev/trails/commit/73622aec93125756d589af3e056d252bdb91169e): Thread `ResourceSpec.config` through the built-in auth resource. Resource config schemas that accept `undefined` now receive their parsed default when config values are omitted, and `authResource` can materialize the no-op or JWT adapter from typed config while preserving existing mock and override paths.
+- [`6944147`](https://github.com/outfitter-dev/trails/commit/694414712949a1107235684a2492ac982ed39a20): Complete trifecta for config, permits, and tracker (formerly tracks)
+
+  - **config**: Add `configResource`, `config.trail`, and `config.workspace` trails with full `defineConfig`, `resolve`, `describe`, `explain`, `doctor`, and code generation support
+  - **permits**: Add `authResource` and `auth.verify` trail for runtime authorization checks
+  - **tracing**: Rename tracks to tracing; add `tracingResource` and `tracing.status` trail for structured signal tracking
+  - **cli**: Fix build flag handling and improve bootstrap scaffolding
+  - **testing**: Expand test context helpers and example-based testing utilities
+  - **core/mcp/http**: Internal alignment for resource and composition updates
+
+- [`69057e9`](https://github.com/outfitter-dev/trails/commit/69057e9348006b2b70c9f6237572a5aa8de3ee1f): Add hierarchical CLI command trees and structured input, enforce established-only topo exports across surfaces, move developer topo and tracing state onto shared `trails.db` with pins and maintenance flows, and ship schema-derived stores through `@ontrails/store` and its Drizzle runtime.
+- [`4b8d13b`](https://github.com/outfitter-dev/trails/commit/4b8d13b6bbac0de4e78bcb0ea0aae6cf06638f1e): **BREAKING:** Remove the deprecated `AuthCredentials` alias from the permits public API.
+
+  Use `PermitExtractionInput` instead. See `docs/migration/trailhead-to-surface.md` for the full migration map.
+
+- [`5adb995`](https://github.com/outfitter-dev/trails/commit/5adb99551c2dda6190d46cce7f60bb08d63c99aa): Complete the v1 hard cutover from the authored `blaze` field to
+  `implementation` across trail contracts, surface projections, tests, examples,
+  and public source-analysis helpers. Existing applications must rename authored
+  trail behavior fields and direct trail-object access before upgrading.
+- [`66056ac`](https://github.com/outfitter-dev/trails/commit/66056ac3325e513519bc788e4bf27ccba202ddb0): **BREAKING:** TRL-475 drops user-facing exports of `authLayer`, `autoIterateLayer`, and `dateShortcutsLayer`. Breaking change for any app still wiring these layers manually.
+
+  Migration:
+
+  - **`autoIterateLayer`** — remove from `blaze`/`run`/`surface` options. The CLI surface now derives the `--all` flag and multi-page collection automatically from any trail whose output matches the pagination pattern (`items`, `hasMore`, `nextCursor`). See TRL-469.
+  - **`dateShortcutsLayer`** — remove from `blaze`/`run`/`surface` options. The CLI surface now expands `since`/`until` shortcut strings (`today`, `yesterday`, `7d`, `30d`, `this-week`, `this-month`) automatically from input schema shape. See TRL-470.
+  - **`authLayer`** — remove from `blaze`/`run`/`surface` options. Permit scope enforcement is intrinsic to `executeTrail` (`enforcePermitRequirement` runs before resource creation and layer composition). The compatibility shim was already a no-op.
+
+  The `Layer` type, `composeLayers`, and canonical per-call `executeTrail({ layers })` option remain available; only the legacy layer exports were removed.
+
+- [`fde5516`](https://github.com/outfitter-dev/trails/commit/fde5516ad396faa718936b10ff658b3ade3383b9): Trail-native vocabulary cutover. Breaking API field renames across all packages:
+
+  - Trail spec: `run:` → `blaze:`, `follow:` → `crosses:`, `services:` → `resources:`, `metadata:` → `meta:`, `emits:` → `fires:`
+  - Runtime: `ctx.follow()` → `ctx.cross()`, `ctx.emit()` → `ctx.fire()`, `ctx.signal` (abort) → `ctx.abortSignal`
+  - Entry points: `trailhead(app)` → `surface(app)`
+  - Package rename: `@ontrails/crumbs` / `@ontrails/tracker` → `@ontrails/tracing`
+  - Wrapper types: retired gate/middleware vocabulary in favor of `Layer` and `layers`
+  - Package taxonomy: retired connector vocabulary in favor of adapters
+
+### Patch Changes
+
+- [`3e5c0fc`](https://github.com/outfitter-dev/trails/commit/3e5c0fc1f2db8fae130782d167cd6b7bb141f4e5): Export shared diagnostic base types from core and align governance diagnostic
+  severity vocabulary across adapter checks, permits, and Warden.
+- [`199304e`](https://github.com/outfitter-dev/trails/commit/199304ec8d46dff22d65c81a5c8a9dd2d037bfa9): Harden JWT permit validation by requiring `exp` by default, validating the
+  header algorithm allowlist before signature verification, and enforcing finite
+  clock skew for `exp` and `nbf` checks.
+- [`e4beec9`](https://github.com/outfitter-dev/trails/commit/e4beec9e756dbd44b333a26215ea03d50eafd7e7): Document `@ontrails/permits/jwt` as the canonical JWT adapter import while keeping root JWT re-exports as intentional convenience exports.
+- [`88a6a62`](https://github.com/outfitter-dev/trails/commit/88a6a62a9e9e230ca6d368fa78dc3ece6c816204): Complete the v1 classification-first cutover from projection/project vocabulary
+  to derive/derived for contract-owned fact production and render/rendered for
+  surface presentation. Public type, helper, rule, relation, and report names move
+  without compatibility aliases; ordinary repository/project nouns remain
+  explicit preserves or structured review inventory.
+- [`b1fbe57`](https://github.com/outfitter-dev/trails/commit/b1fbe574e6f44d1fecb5e3a000270955c0a77b7b): Publish Bun-validated package tarballs through an npm trusted-publishing adapter
+  binding, add exact repository metadata for each public workspace package, and
+  correct the native Bun release descriptor to its pack-only runtime boundary.
+- [`5d88104`](https://github.com/outfitter-dev/trails/commit/5d88104c6c269e2ef1e92ba3b9e09a410df10c7b): Polish Trails blaze terminology across package docs and Warden guidance.
+- [`99523f2`](https://github.com/outfitter-dev/trails/commit/99523f2a67e92091781165b6c847252b910554e2): Clean up resource context naming in shipped source and examples so resource
+  factories consistently use resource vocabulary.
+
+## 1.0.0-beta.50
+
+## 1.0.0-beta.49
+
+## 1.0.0-beta.48
+
+## 1.0.0-beta.47
+
+## 1.0.0-beta.46
+
+## 1.0.0-beta.45
+
+## 1.0.0-beta.44
+
+### Patch Changes
+
+- [`b1fbe57`](https://github.com/outfitter-dev/trails/commit/b1fbe574e6f44d1fecb5e3a000270955c0a77b7b): Publish Bun-validated package tarballs through an npm trusted-publishing adapter
+  binding, add exact repository metadata for each public workspace package, and
+  correct the native Bun release descriptor to its pack-only runtime boundary.
+
+## 1.0.0-beta.43
+
+### Patch Changes
+
+- [`88a6a62`](https://github.com/outfitter-dev/trails/commit/88a6a62a9e9e230ca6d368fa78dc3ece6c816204): Complete the v1 classification-first cutover from projection/project vocabulary
+  to derive/derived for contract-owned fact production and render/rendered for
+  surface presentation. Public type, helper, rule, relation, and report names move
+  without compatibility aliases; ordinary repository/project nouns remain
+  explicit preserves or structured review inventory.
+
+## 1.0.0-beta.42
+
+## 1.0.0-beta.41
+
+## 1.0.0-beta.40
+
+### Minor Changes
+
+- [`5adb995`](https://github.com/outfitter-dev/trails/commit/5adb99551c2dda6190d46cce7f60bb08d63c99aa): Complete the v1 hard cutover from the authored `blaze` field to
+  `implementation` across trail contracts, surface projections, tests, examples,
+  and public source-analysis helpers. Existing applications must rename authored
+  trail behavior fields and direct trail-object access before upgrading.
+
+## 1.0.0-beta.39
+
+## 1.0.0-beta.38
+
+## 1.0.0-beta.37
+
+## 1.0.0-beta.36
+
+## 1.0.0-beta.35
+
+## 1.0.0-beta.34
+
+## 1.0.0-beta.33
+
+## 1.0.0-beta.32
+
+### Patch Changes
+
+- 3e5c0fc: Export shared diagnostic base types from core and align governance diagnostic
+  severity vocabulary across adapter checks, permits, and Warden.
+- Updated dependencies [3e5c0fc]
+- Updated dependencies [f3c4fef]
+- Updated dependencies [cb0a9d8]
+- Updated dependencies [21c6dda]
+- Updated dependencies [fe72b84]
+  - @ontrails/core@1.0.0-beta.32
+
+## 1.0.0-beta.31
+
+### Patch Changes
+
+- Updated dependencies [4cd5d4e]
+- Updated dependencies [38907cc]
+  - @ontrails/core@1.0.0-beta.31
+
+## 1.0.0-beta.30
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.30
+
+## 1.0.0-beta.29
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.29
+
+## 1.0.0-beta.28
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.28
+
+## 1.0.0-beta.27
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.27
+
+## 1.0.0-beta.26
+
+### Patch Changes
+
+- Updated dependencies [1307568]
+- Updated dependencies [371d19e]
+  - @ontrails/core@1.0.0-beta.26
+
+## 1.0.0-beta.25
+
+### Patch Changes
+
+- Updated dependencies [c36aca9]
+- Updated dependencies [3befcf1]
+- Updated dependencies [a4f9cf6]
+- Updated dependencies [9bcf34e]
+  - @ontrails/core@1.0.0-beta.25
+
+## 1.0.0-beta.24
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.24
+
+## 1.0.0-beta.23
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.23
+
+## 1.0.0-beta.22
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.22
+
+## 1.0.0-beta.21
+
+### Patch Changes
+
+- 99523f2: Clean up resource context naming in shipped source and examples so resource
+  factories consistently use resource vocabulary.
+- Updated dependencies [99523f2]
+  - @ontrails/core@1.0.0-beta.21
+
+## 1.0.0-beta.20
+
+### Patch Changes
+
+- Updated dependencies [851a2a3]
+  - @ontrails/core@1.0.0-beta.20
+
+## 1.0.0-beta.19
+
+### Patch Changes
+
+- 5d88104: Polish Trails blaze terminology across package docs and Warden guidance.
+- Updated dependencies [e41c382]
+- Updated dependencies [1eb5bdc]
+- Updated dependencies [f8d80b9]
+- Updated dependencies [846a597]
+- Updated dependencies [223aaad]
+- Updated dependencies [3125f4d]
+- Updated dependencies [2494dc6]
+- Updated dependencies [2d53717]
+- Updated dependencies [16cb740]
+- Updated dependencies [8894ecb]
+- Updated dependencies [fdf7ec9]
+- Updated dependencies [d76be13]
+- Updated dependencies [84f56a5]
+- Updated dependencies [431b04c]
+- Updated dependencies [5d88104]
+- Updated dependencies [f04a9ef]
+  - @ontrails/core@1.0.0-beta.19
+
+## 1.0.0-beta.18
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.18
+
+## 1.0.0-beta.17
+
+### Patch Changes
+
+- Updated dependencies [3dc8254]
+  - @ontrails/core@1.0.0-beta.17
+
+## 1.0.0-beta.16
+
+### Major Changes
+
+- 200bece: BREAKING: rename auth connector vocabulary to adapter.
+
+  This stays on the current `1.0.0-beta` prerelease line: the package is part of
+  the fixed `@ontrails/*` beta group, so beta-breaking API renames advance the
+  next beta rather than opening a stable-major release line.
+
+  - `AuthConnector` -> `AuthAdapter`
+  - `authConnectorSchema` -> `authAdapterSchema`
+  - `JwtConnectorOptions` -> `JwtAdapterOptions`
+  - `createJwtConnector` -> `createJwtAdapter`
+  - auth resource config discriminant `{ connector: 'jwt' | 'none' }` -> `{ adapter: 'jwt' | 'none' }`
+
+  The `@ontrails/permits/jwt` subpath is unchanged. The internal `connectors/`
+  source directory becomes `adapters/`. See
+  `docs/migration/connector-to-adapter.md` for the full rename map.
+
+  The Trails CLI package updates its generated auth-resource configuration to use
+  the new `adapter` discriminant.
+
+### Minor Changes
+
+- 73622ae: Thread `ResourceSpec.config` through the built-in auth resource. Resource config schemas that accept `undefined` now receive their parsed default when config values are omitted, and `authResource` can materialize the no-op or JWT adapter from typed config while preserving existing mock and override paths.
+- 4b8d13b: **BREAKING:** Remove the deprecated `AuthCredentials` alias from the permits public API.
+
+  Use `PermitExtractionInput` instead. See `docs/migration/trailhead-to-surface.md` for the full migration map.
+
+- 66056ac: **BREAKING:** TRL-475 drops user-facing exports of `authLayer`, `autoIterateLayer`, and `dateShortcutsLayer`. Breaking change for any app still wiring these layers manually.
+
+  Migration:
+
+  - **`autoIterateLayer`** — remove from `blaze`/`run`/`surface` options. The CLI surface now derives the `--all` flag and multi-page collection automatically from any trail whose output matches the pagination pattern (`items`, `hasMore`, `nextCursor`). See TRL-469.
+  - **`dateShortcutsLayer`** — remove from `blaze`/`run`/`surface` options. The CLI surface now expands `since`/`until` shortcut strings (`today`, `yesterday`, `7d`, `30d`, `this-week`, `this-month`) automatically from input schema shape. See TRL-470.
+  - **`authLayer`** — remove from `blaze`/`run`/`surface` options. Permit scope enforcement is intrinsic to `executeTrail` (`enforcePermitRequirement` runs before resource creation and layer composition). The compatibility shim was already a no-op.
+
+  The `Layer` type, `composeLayers`, and canonical per-call `executeTrail({ layers })` option remain available; only the legacy layer exports were removed.
+
+### Patch Changes
+
+- 199304e: Harden JWT permit validation by requiring `exp` by default, validating the
+  header algorithm allowlist before signature verification, and enforcing finite
+  clock skew for `exp` and `nbf` checks.
+- e4beec9: Document `@ontrails/permits/jwt` as the canonical JWT adapter import while keeping root JWT re-exports as intentional convenience exports.
+- Updated dependencies [73622ae]
+- Updated dependencies [6300f70]
+- Updated dependencies [d172013]
+- Updated dependencies [c3fc5c3]
+- Updated dependencies [20d7a5c]
+- Updated dependencies [be5fb46]
+- Updated dependencies [e898cc4]
+- Updated dependencies [3395234]
+- Updated dependencies [bcdc484]
+- Updated dependencies [331e3a9]
+- Updated dependencies [4399fdb]
+- Updated dependencies [4b8d13b]
+- Updated dependencies [112b9f2]
+- Updated dependencies [893025e]
+- Updated dependencies [eec5e9d]
+- Updated dependencies [ebd4434]
+- Updated dependencies [863d473]
+- Updated dependencies [344f2f7]
+- Updated dependencies [26f9ffd]
+- Updated dependencies [10eae9a]
+- Updated dependencies [22c6c06]
+  - @ontrails/core@1.0.0-beta.16
+
+## 1.0.0-beta.15
+
+### Patch Changes
+
+- Updated dependencies [4ad6b25]
+  - @ontrails/core@1.0.0-beta.15
+
+## 1.0.0-beta.14
+
+### Minor Changes
+
+- 69057e9: Add hierarchical CLI command trees and structured input, enforce established-only topo exports across trailheads, move developer topo and tracker state onto shared `trails.db` with pins and maintenance flows, and ship schema-derived stores through `@ontrails/store` and its Drizzle runtime.
+
+### Patch Changes
+
+- Updated dependencies [69057e9]
+  - @ontrails/core@1.0.0-beta.14
+
+## 1.0.0-beta.13
+
+### Minor Changes
+
+- 6944147: Complete trifecta for config, permits, and tracker (formerly tracks)
+
+  - **config**: Add `configProvision`, `configGate`, `config.trail`, and `config.workspace` trails with full `defineConfig`, `resolve`, `describe`, `explain`, `doctor`, and code generation support
+  - **permits**: Add `authService` and `auth.verify` trail for runtime authorization checks
+  - **tracker**: Rename tracks to tracker; add `trackerProvision` and `tracker.status` trail for structured signal tracking
+  - **cli**: Fix build flag handling and improve bootstrap scaffolding
+  - **testing**: Expand test context helpers and example-based testing utilities
+  - **core/mcp/http**: Internal alignment for provision and composition updates
+
+- Trail-native vocabulary cutover. Breaking API field renames across all packages:
+
+  - Trail spec: `run:` → `blaze:`, `follow:` → `crosses:`, `services:` → `provisions:`, `metadata:` → `meta:`, `emits:` → `signals:`
+  - Runtime: `ctx.follow()` → `ctx.cross()`, `ctx.emit()` → `ctx.signal()`, `ctx.signal` (abort) → `ctx.abortSignal`
+  - Entry points: `blaze(app)` → `trailhead(app)`
+  - Package rename: `@ontrails/crumbs` → `@ontrails/tracker`
+  - Wrapper types: `Layer` → `Gate`, `layers`/`middleware` → `gates`
+  - Transport: `surface` → `trailhead`, `adapter` → `connector`
+
+### Patch Changes
+
+- Updated dependencies [6944147]
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.13
+
+## 1.0.0-beta.12
+
+### Minor Changes
+
+- Complete trifecta for config, permits, and tracker (formerly tracks)
+
+  - **config**: Add `configProvision`, `config.gate`, `config.trail`, and `config.workspace` trails with full `defineConfig`, `resolve`, `describe`, `explain`, `doctor`, and code generation support
+  - **permits**: Add `authProvision` and `auth.verify` trail for runtime authorization checks
+  - **tracker**: Rename tracks to tracker; add `trackerProvision` and `tracker.status` trail for structured event tracking
+  - **cli**: Fix build flag handling and improve bootstrap scaffolding
+  - **testing**: Expand test context helpers and example-based testing utilities
+  - **core/mcp/http**: Internal alignment for provision and composition updates
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.12

package/README.md

@@ -0,0 +1,182 @@
+# @ontrails/permits
+
+Scope-based authorization for Trails.
+
+The permits package owns adapter-agnostic auth resources, adapters, and helpers. Core `executeTrail` enforces trail `permit` declarations once a surface has resolved a permit into `ctx.permit`.
+
+## The core pattern
+
+### 1. Declare permit requirements on trails
+
+```typescript
+export const create = trail('gist.create', {
+  permit: { scopes: ['gist:write'] },
+  implementation: async (input, ctx) => {
+    // executeTrail enforces scopes before execution enters the implementation
+    return Result.ok(newGist);
+  },
+});
+
+export const search = trail('gist.search', {
+  permit: 'public',
+  implementation: async (input, ctx) => {
+    // No authentication required
+    return Result.ok(results);
+  },
+});
+```
+
+### 2. Resolve a permit at the surface
+
+```typescript
+export const graph = topo('my-app', gistModule);
+// Surface auth verifies credentials and passes { permit } into executeTrail.
+```
+
+The execution pipeline reads each trail's `permit` field:
+
+- `'public'` or `undefined` — execution passes through
+- `{ scopes: [...] }` — execution checks that `ctx.permit` contains all required scopes
+
+Permit enforcement is intrinsic to `executeTrail`; there is no opt-in layer to wire. The previously deprecated `authLayer` compatibility wrapper has been removed (TRL-475).
+
+### 3. Bind an adapter at bootstrap
+
+```typescript
+import { createJwtAdapter } from '@ontrails/permits/jwt';
+
+const adapter = createJwtAdapter({
+  secret: process.env.JWT_SECRET,
+  issuer: 'https://auth.example.com',
+  audience: 'api.example.com',
+});
+```
+
+## Auth adapters
+
+An auth adapter authenticates requests and produces permits.
+
+### Built-in: JWT adapter
+
+Verifies HS256-signed JWTs and extracts claims into permits:
+
+```typescript
+import { createJwtAdapter } from '@ontrails/permits/jwt';
+
+const adapter = createJwtAdapter({
+  secret: 'your-hmac-secret',
+  issuer: 'https://auth.example.com',
+  audience: 'api.example.com',
+  scopesClaim: 'scope',
+  rolesClaim: 'roles',
+});
+```
+
+`@ontrails/permits/jwt` is the canonical built-in JWT adapter subpath. The root package intentionally keeps convenience re-exports for interactive discovery, but generated code, docs, and adapter-specific examples should import JWT names from the subpath.
+
+### Custom adapters
+
+Implement the `AuthAdapter` interface:
+
+```typescript
+import type { AuthAdapter, PermitExtractionInput, Permit } from '@ontrails/permits';
+
+const myAdapter: AuthAdapter = {
+  authenticate: async (input: PermitExtractionInput) => {
+    if (!input.bearerToken) return Result.ok(null);
+    const permit: Permit = {
+      id: 'user-42',
+      scopes: ['user:read', 'user:write'],
+      roles: ['admin'],
+    };
+    return Result.ok(permit);
+  },
+};
+```
+
+## Permits and scopes
+
+A `Permit` is the resolved identity and scopes from successful authentication:
+
+```typescript
+interface Permit {
+  readonly id: string;
+  readonly scopes: readonly string[];
+  readonly roles?: readonly string[];
+  readonly tenantId?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+```
+
+Access the permit in your implementation:
+
+```typescript
+import { getPermit } from '@ontrails/permits';
+
+const myTrail = trail('do.something', {
+  implementation: async (_input, ctx) => {
+    const permit = getPermit(ctx);
+    if (!permit) return Result.err(new Error('Not authenticated'));
+    return Result.ok({ userId: permit.id });
+  },
+});
+```
+
+Scopes follow the `entity:action` convention: `user:read`, `gist:write`, etc.
+
+## The auth.verify trail
+
+An infrastructure trail that verifies bearer tokens and returns permits:
+
+```typescript
+import { authVerify } from '@ontrails/permits';
+
+// Returns { valid: true, permit: { id, scopes, roles } }
+// or { valid: false, error: 'Token has expired', errorCode: 'expired_token' }
+```
+
+## Testing with mock permits
+
+Use `createTestPermit()` and `createPermitForTrail()` in tests:
+
+```typescript
+import {
+  createTestPermit,
+  createPermitForTrail,
+} from '@ontrails/permits/testing';
+
+const permit = createTestPermit({
+  id: 'user-123',
+  scopes: ['gist:read', 'gist:write'],
+  roles: ['editor'],
+});
+
+// Create a permit matching a trail's requirements
+const trailPermit = createPermitForTrail(myTrail);
+// { id: 'test-...', scopes: ['gist:write'] }
+```
+
+## Permit governance
+
+Use `validatePermits()` to check trails against governance rules:
+
+```typescript
+import { validatePermits } from '@ontrails/permits';
+
+const diagnostics = validatePermits(app.list());
+```
+
+Built-in rules:
+
+- `destroyWithoutPermit` — error if a destroy trail has no permit
+- `writeWithoutPermit` — warning if a write trail has no permit
+- `scopeNamingConsistency` — warning if a scope doesn't follow `entity:action`
+- `orphanScopeDetection` — warning if a scope appears in only one trail
+
+## Installation
+
+These commands target stable `0.2.0`. Run them after that version is published to npm.
+
+```bash
+bun add --exact @ontrails/permits@0.2.0 @ontrails/core@0.2.0 zod
+```

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ontrails/permits",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/outfitter-dev/trails.git",
+    "directory": "packages/permits"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./jwt": "./src/adapters/jwt.ts",
+    "./testing": "./src/testing.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "peerDependencies": {
+    "@ontrails/core": "^0.2.0",
+    "zod": "^4.3.5"
+  }
+}

package/src/adapters/adapter.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import type { Result } from '@ontrails/core';
+
+import type { PermitExtractionInput } from '../extraction.js';
+import type { Permit } from '../permit.js';
+
+/** Errors from auth adapters. */
+export const authErrorSchema = z
+  .object({
+    code: z.enum([
+      'expired_token',
+      'insufficient_scope',
+      'invalid_token',
+      'missing_credentials',
+    ]),
+    message: z.string(),
+  })
+  .readonly();
+
+export type AuthError = z.infer<typeof authErrorSchema>;
+
+export const authAdapterSchema = z
+  .object({
+    authenticate: z.function(),
+  })
+  .readonly();
+
+/**
+ * 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>>;
+}