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

package/.turbo/turbo-lint.log

@@ -1,3 +1,3 @@
 $ oxlint ./src
 Found 0 warnings and 0 errors.
-Finished in 44ms on 18 files with 93 rules using 24 threads.
+Finished in 57ms on 18 files with 93 rules using 24 threads.

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @ontrails/permits
 
+## 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

package/README.md

@@ -0,0 +1,175 @@
+# @ontrails/permits
+
+Scope-based authorization for Trails.
+
+The permits package owns the connector-agnostic `authProvision` and `authGate`. Connector packages bind those declarations to concrete auth logic, just like a trailhead connector binds a topo to CLI, MCP, or HTTP.
+
+## The core pattern
+
+### 1. Declare permit requirements on trails
+
+```typescript
+export const create = trail('gist.create', {
+  permit: { scopes: ['gist:write'] },
+  blaze: async (input, ctx) => {
+    // authGate enforces scopes before blaze runs
+    return Result.ok(newGist);
+  },
+});
+
+export const search = trail('gist.search', {
+  permit: 'public',
+  blaze: async (input, ctx) => {
+    // No authentication required
+    return Result.ok(results);
+  },
+});
+```
+
+### 2. Register the auth gate
+
+```typescript
+import { authGate } from '@ontrails/permits';
+
+export const app = topo('my-app', gistModule);
+// Register authGate with your trailhead
+```
+
+The gate reads each trail's `permit` field:
+
+- `'public'` or `undefined` — gate passes through
+- `{ scopes: [...] }` — gate checks that `ctx.permit` contains all required scopes
+
+### 3. Bind a connector at bootstrap
+
+```typescript
+import { createJwtConnector } from '@ontrails/permits/jwt';
+
+const connector = createJwtConnector({
+  secret: process.env.JWT_SECRET,
+  issuer: 'https://auth.example.com',
+  audience: 'api.example.com',
+});
+```
+
+## Auth connectors
+
+An auth connector authenticates requests and produces permits.
+
+### Built-in: JWT connector
+
+Verifies HS256-signed JWTs and extracts claims into permits:
+
+```typescript
+import { createJwtConnector } from '@ontrails/permits/jwt';
+
+const connector = createJwtConnector({
+  secret: 'your-hmac-secret',
+  issuer: 'https://auth.example.com',
+  audience: 'api.example.com',
+  scopesClaim: 'scope',
+  rolesClaim: 'roles',
+});
+```
+
+### Custom connectors
+
+Implement the `AuthConnector` interface:
+
+```typescript
+import type { AuthConnector, PermitExtractionInput, Permit } from '@ontrails/permits';
+
+const myConnector: AuthConnector = {
+  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 blaze:
+
+```typescript
+import { getPermit } from '@ontrails/permits';
+
+const myTrail = trail('do.something', {
+  blaze: 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 `mintTestPermit()` and `mintPermitForTrail()` in tests:
+
+```typescript
+import { mintTestPermit, mintPermitForTrail } from '@ontrails/permits';
+
+const permit = mintTestPermit({
+  id: 'user-123',
+  scopes: ['gist:read', 'gist:write'],
+  roles: ['editor'],
+});
+
+// Mint a permit matching a trail's requirements
+const trailPermit = mintPermitForTrail(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
+
+```bash
+bun add @ontrails/permits @ontrails/core zod
+```

package/dist/auth-gate.d.ts

@@ -0,0 +1,18 @@
+import type { Gate } from '@ontrails/core';
+/**
+ * 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 declare const authGate: Gate;
+//# sourceMappingURL=auth-gate.d.ts.map

package/dist/auth-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-gate.d.ts","sourceRoot":"","sources":["../src/auth-gate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AA6B3C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ,EAAE,IAkCtB,CAAC"}

package/dist/auth-gate.js

@@ -0,0 +1,56 @@
+import { Result } 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) => requirement === undefined || requirement === 'public';
+/** Returns scopes present in `required` but absent from `held`. */
+const findMissing = (required, held) => 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 = {
+    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));
+        };
+    },
+};
+//# sourceMappingURL=auth-gate.js.map

package/dist/auth-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-gate.js","sourceRoot":"","sources":["../src/auth-gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAGxC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,8EAA8E;AAC9E,0DAA0D;AAC1D,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,aAAa,GAAG,CACpB,WAAoB,EACiB,EAAE,CACvC,WAAW,KAAK,SAAS,IAAI,WAAW,KAAK,QAAQ,CAAC;AAExD,mEAAmE;AACnE,MAAM,WAAW,GAAG,CAClB,QAA2B,EAC3B,IAAuB,EACJ,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AAElE,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAS;IAC5B,WAAW,EAAE,2CAA2C;IACxD,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE;QACrB,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC;QAElC,IAAI,aAAa,CAAC,WAAW,CAAC,EAAE,CAAC;YAC/B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;YACpB,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;YAE9B,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,OAAO,OAAO,CAAC,OAAO,CACpB,MAAM,CAAC,GAAG,CAAC,IAAI,WAAW,CAAC,oBAAoB,CAAC,CAAC,CAClD,CAAC;YACJ,CAAC;YAED,MAAM,OAAO,GAAG,WAAW,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;YAE/D,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvB,OAAO,OAAO,CAAC,OAAO,CACpB,MAAM,CAAC,GAAG,CACR,IAAI,WAAW,CAAC,mBAAmB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE;oBACvD,OAAO,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE;iBACnD,CAAC,CACH,CACF,CAAC;YACJ,CAAC;YAED,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;QAC3C,CAAC,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/auth-provision.d.ts

@@ -0,0 +1,11 @@
+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 declare const authProvision: import("@ontrails/core").Provision<AuthConnector>;
+//# sourceMappingURL=auth-provision.d.ts.map

package/dist/auth-provision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-provision.d.ts","sourceRoot":"","sources":["../src/auth-provision.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,mDAaxB,CAAC"}

package/dist/auth-provision.js

@@ -0,0 +1,22 @@
+import { Result, provision } from '@ontrails/core';
+/**
+ * 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('auth', {
+    create: (_svc) => Result.ok({
+        // oxlint-disable-next-line require-await -- stub connector satisfies async interface
+        authenticate: async () => Result.ok(null),
+    }),
+    description: 'Authentication connector',
+    meta: { category: 'infrastructure' },
+    mock: () => ({
+        // oxlint-disable-next-line require-await -- mock connector satisfies async interface
+        authenticate: async () => Result.ok(null),
+    }),
+});
+//# sourceMappingURL=auth-provision.js.map

package/dist/auth-provision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-provision.js","sourceRoot":"","sources":["../src/auth-provision.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAInD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAgB,MAAM,EAAE;IAC5D,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CACf,MAAM,CAAC,EAAE,CAAC;QACR,qFAAqF;QACrF,YAAY,EAAE,KAAK,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC;KAClB,CAAC;IAC5B,WAAW,EAAE,0BAA0B;IACvC,IAAI,EAAE,EAAE,QAAQ,EAAE,gBAAgB,EAAE;IACpC,IAAI,EAAE,GAAG,EAAE,CACT,CAAC;QACC,qFAAqF;QACrF,YAAY,EAAE,KAAK,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC;KAC1C,CAAyB;CAC7B,CAAC,CAAC"}

package/dist/connectors/connector.d.ts

@@ -0,0 +1,26 @@
+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>>;
+}
+//# sourceMappingURL=connector.d.ts.map

package/dist/connectors/connector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../../src/connectors/connector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,qBAAqB,CAAC;AAEpD,mCAAmC;AACnC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EACT,eAAe,GACf,oBAAoB,GACpB,eAAe,GACf,qBAAqB,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,YAAY,EAAE,CACrB,KAAK,EAAE,qBAAqB,KACzB,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;CAChD"}

package/dist/connectors/connector.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=connector.js.map

package/dist/connectors/connector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.js","sourceRoot":"","sources":["../../src/connectors/connector.ts"],"names":[],"mappings":""}

package/dist/connectors/jwt.d.ts

@@ -0,0 +1,25 @@
+import type { AuthConnector } from './connector.js';
+/** Configuration for the JWT auth connector. */
+export interface JwtConnectorOptions {
+    /** 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;
+}
+/**
+ * Create a JWT auth connector 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 declare const createJwtConnector: (options: JwtConnectorOptions) => AuthConnector;
+//# sourceMappingURL=jwt.d.ts.map

package/dist/connectors/jwt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../src/connectors/jwt.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAa,MAAM,gBAAgB,CAAC;AAI/D,gDAAgD;AAChD,MAAM,WAAW,mBAAmB;IAClC,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,iDAAiD;IACjD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AA2LD;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,mBAAmB,KAC3B,aAeF,CAAC"}

package/dist/connectors/jwt.js

@@ -0,0 +1,148 @@
+import { Result } from '@ontrails/core';
+// ---------------------------------------------------------------------------
+// Helpers (defined before callers)
+// ---------------------------------------------------------------------------
+const authErr = (code, message) => Result.err({ code, message });
+/** Base64url-decode a string to bytes. */
+const base64urlDecode = (input) => {
+    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) => {
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+        return undefined;
+    }
+    try {
+        const json = new TextDecoder().decode(base64urlDecode(parts[1] ?? ''));
+        return JSON.parse(json);
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Import a secret as an HMAC CryptoKey. */
+const importHmacKey = (secret) => {
+    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, key) => {
+    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, encoder.encode(data));
+};
+/** Validate standard claims (exp, iss, aud). */
+const validateClaims = (payload, options) => {
+    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, claim) => {
+    const raw = payload[claim];
+    if (typeof raw === 'string') {
+        return raw.split(' ').filter(Boolean);
+    }
+    if (Array.isArray(raw)) {
+        return raw.filter((s) => typeof s === 'string' && s.length > 0);
+    }
+    return [];
+};
+/** Extract roles from a payload claim (string array). */
+const extractRoles = (payload, claim) => {
+    const raw = payload[claim];
+    if (!Array.isArray(raw)) {
+        return undefined;
+    }
+    return raw.filter((r) => typeof r === 'string');
+};
+/** Build a Permit from a validated JWT payload. */
+const buildPermit = (payload, options) => {
+    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, secret) => {
+    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, options) => {
+    const claimError = validateClaims(payload, options);
+    if (claimError) {
+        return Result.err(claimError);
+    }
+    return buildPermit(payload, options);
+};
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a JWT auth connector 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 createJwtConnector = (options) => {
+    const authenticate = async (input) => {
+        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 };
+};
+//# sourceMappingURL=jwt.js.map

package/dist/connectors/jwt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.js","sourceRoot":"","sources":["../../src/connectors/jwt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AA+BxC,8EAA8E;AAC9E,mCAAmC;AACnC,8EAA8E;AAE9E,MAAM,OAAO,GAAG,CACd,IAAuB,EACvB,OAAe,EACW,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;AAE7D,0CAA0C;AAC1C,MAAM,eAAe,GAAG,CAAC,KAAa,EAAc,EAAE;IACpD,MAAM,MAAM,GAAG,KAAK;SACjB,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC;SACpB,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC;SACpB,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9D,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AAEF,4DAA4D;AAC5D,MAAM,aAAa,GAAG,CAAC,KAAa,EAA0B,EAAE;IAC9D,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACvE,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAe,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC,CAAC;AAEF,4CAA4C;AAC5C,MAAM,aAAa,GAAG,CAAC,MAAc,EAAsB,EAAE;IAC3D,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,OAAO,MAAM,CAAC,MAAM,CAAC,SAAS,CAC5B,KAAK,EACL,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EACtB,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,EACjC,KAAK,EACL,CAAC,QAAQ,CAAC,CACX,CAAC;AACJ,CAAC,CAAC;AAEF,iDAAiD;AACjD,MAAM,mBAAmB,GAAG,CAC1B,KAAa,EACb,GAAc,EACI,EAAE;IACpB,MAAM,OAAO,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC;QACnB,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACrC,MAAM,SAAS,GAAG,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;IAC5D,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CACzB,MAAM,EACN,GAAG,EACH,SAAS,CAAC,MAAqB,EAC/B,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CACrB,CAAC;AACJ,CAAC,CAAC;AAEF,gDAAgD;AAChD,MAAM,cAAc,GAAG,CACrB,OAAmB,EACnB,OAA4B,EACL,EAAE;IACzB,IACE,OAAO,CAAC,GAAG,KAAK,SAAS;QACzB,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,EAC3C,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC;IACjE,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC;QACrD,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC/D,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,MAAM,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;QACxB,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YAChC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC;YAChC,CAAC,CAAC,GAAG,KAAK,OAAO,CAAC,QAAQ,CAAC;QAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC;QACjE,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAEF,6EAA6E;AAC7E,MAAM,aAAa,GAAG,CACpB,OAAmB,EACnB,KAAa,EACM,EAAE;IACrB,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3B,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC,MAAM,CACf,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAC1D,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC,CAAC;AAEF,yDAAyD;AACzD,MAAM,YAAY,GAAG,CACnB,OAAmB,EACnB,KAAa,EACkB,EAAE;IACjC,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;AAC/D,CAAC,CAAC;AAEF,mDAAmD;AACnD,MAAM,WAAW,GAAG,CAClB,OAAmB,EACnB,OAA4B,EACD,EAAE;IAC7B,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;QACjB,OAAO,OAAO,CAAC,eAAe,EAAE,6BAA6B,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,CAAC;IACnE,OAAO,MAAM,CAAC,EAAE,CAAC;QACf,EAAE,EAAE,OAAO,CAAC,GAAG;QACf,MAAM,EAAE,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC;QAC9D,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5B,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,wEAAwE;AACxE,MAAM,eAAe,GAAG,KAAK,EAC3B,KAAa,EACb,MAAc,EAC0B,EAAE;IAC1C,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,OAAO,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;IACnD,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,KAAK,GAAG,MAAM,mBAAmB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACpD,OAAO,KAAK;YACV,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC;YACpB,CAAC,CAAC,OAAO,CAAC,eAAe,EAAE,mBAAmB,CAAC,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC,eAAe,EAAE,2BAA2B,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC,CAAC;AAEF,kEAAkE;AAClE,MAAM,eAAe,GAAG,CACtB,OAAmB,EACnB,OAA4B,EACD,EAAE;IAC7B,MAAM,UAAU,GAAG,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACpD,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AACvC,CAAC,CAAC;AAEF,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,OAA4B,EACb,EAAE;IACjB,MAAM,YAAY,GAAG,KAAK,EACxB,KAA4B,EACe,EAAE;QAC7C,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;YACvB,OAAO,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YACpB,OAAO,OAAO,CAAC,eAAe,EAAE,sBAAsB,CAAC,CAAC;QAC1D,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QACzE,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC7E,CAAC,CAAC;IAEF,OAAO,EAAE,YAAY,EAAE,CAAC;AAC1B,CAAC,CAAC"}

package/dist/extraction.d.ts

@@ -1,18 +1,18 @@
 /**
- * Normalized input for auth adapters.
+ * Normalized input for auth connectors.
  *
- * Each surface extracts raw credentials from its transport and normalizes
- * them into this shape. No surface types (Request, McpSession, etc.) cross
+ * Each trailhead extracts raw credentials from its transport and normalizes
+ * them into this shape. No trailhead types (Request, McpSession, etc.) cross
  * into core — only this interface.
  */
 export interface PermitExtractionInput {
-    /** Which surface produced this extraction */
-    readonly surface: 'http' | 'mcp' | 'cli';
+    /** Which trailhead produced this extraction */
+    readonly trailhead: '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) */
+    /** Raw headers (HTTP trailhead only, typically) */
     readonly headers?: Headers;
     /** Correlation ID for tracing */
     readonly requestId: string;

package/dist/extraction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extraction.d.ts","sourceRoot":"","sources":["../src/extraction.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;IACzC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,iCAAiC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B"}
+{"version":3,"file":"extraction.d.ts","sourceRoot":"","sources":["../src/extraction.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;IAC3C,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,iCAAiC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B"}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-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 { type AuthConnector, type AuthCredentials, type AuthError, } from './connectors/connector.js';
+export { createJwtConnector, type JwtConnectorOptions, } from './connectors/jwt.js';
+export { authGate } from './auth-gate.js';
+export { authProvision } from './auth-provision.js';
 export { authVerify } from './trails/auth-verify.js';
 export { PermitError } from './errors.js';
 export { type PermitExtractionInput } from './extraction.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,SAAS,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,KAAK,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,SAAS,GACf,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,kBAAkB,EAClB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,KAAK,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -1,7 +1,7 @@
-export {} from './adapter.js';
-export { createJwtAdapter } from './adapters/jwt.js';
-export { authLayer } from './auth-layer.js';
-export { authService } from './auth-service.js';
+export {} from './connectors/connector.js';
+export { createJwtConnector, } from './connectors/jwt.js';
+export { authGate } from './auth-gate.js';
+export { authProvision } from './auth-provision.js';
 export { authVerify } from './trails/auth-verify.js';
 export { PermitError } from './errors.js';
 export {} from './extraction.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIN,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAA0B,MAAM,mBAAmB,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAA8B,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAe,SAAS,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,eAAe,EAAyB,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIN,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,kBAAkB,GAEnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAA8B,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAe,SAAS,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,eAAe,EAAyB,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/permit.d.ts

@@ -9,8 +9,8 @@ export interface Permit extends BasePermit {
  * 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`.
+ * returns the full `Permit` when the auth gate has set one. Safe because
+ * the auth gate is the only writer and always sets a full `Permit`.
  *
  * @example
  * ```typescript

package/dist/permit.js

@@ -2,8 +2,8 @@
  * 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`.
+ * returns the full `Permit` when the auth gate has set one. Safe because
+ * the auth gate is the only writer and always sets a full `Permit`.
  *
  * @example
  * ```typescript

package/dist/trails/auth-verify.d.ts

@@ -1,9 +1,9 @@
 /**
  * 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.
+ * Reads the auth connector from `authProvision` — the connector is configured
+ * at bootstrap (e.g. JWT with HMAC secret). The mock connector always
+ * succeeds with a null permit, so `testAll(app)` works without configuration.
  */
 export declare const authVerify: import("@ontrails/core").Trail<{
     token: string;

package/dist/trails/auth-verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-verify.d.ts","sourceRoot":"","sources":["../../src/trails/auth-verify.ts"],"names":[],"mappings":"AAwCA;;;;;;GAMG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;EAiDrB,CAAC"}
+{"version":3,"file":"auth-verify.d.ts","sourceRoot":"","sources":["../../src/trails/auth-verify.ts"],"names":[],"mappings":"AA4CA;;;;;;GAMG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;EAiDrB,CAAC"}

package/dist/trails/auth-verify.js

@@ -1,6 +1,6 @@
-import { Result, SURFACE_KEY, trail } from '@ontrails/core';
+import { Result, TRAILHEAD_KEY, trail } from '@ontrails/core';
 import { z } from 'zod';
-import { authService } from '../auth-service.js';
+import { authProvision } from '../auth-provision.js';
 const permitSchema = z.object({
     id: z.string(),
     metadata: z.record(z.string(), z.unknown()).optional(),
@@ -23,42 +23,25 @@ const toOutputPermit = (permit) => ({
     id: permit.id,
     scopes: [...permit.scopes],
 });
-const isSurface = (value) => value === 'http' || value === 'mcp' || value === 'cli';
-const getSurface = (ctx) => {
-    const surface = ctx.extensions?.[SURFACE_KEY];
-    return isSurface(surface) ? surface : 'http';
+const isTrailhead = (value) => value === 'http' || value === 'mcp' || value === 'cli';
+const getTrailhead = (ctx) => {
+    const trailhead = ctx.extensions?.[TRAILHEAD_KEY];
+    return isTrailhead(trailhead) ? trailhead : '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.
+ * Reads the auth connector from `authProvision` — the connector is configured
+ * at bootstrap (e.g. JWT with HMAC secret). The mock connector 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({
+    blaze: async (input, ctx) => {
+        const connector = authProvision.from(ctx);
+        const result = await connector.authenticate({
             bearerToken: input.token,
             requestId: ctx.requestId,
-            surface: getSurface(ctx),
+            trailhead: getTrailhead(ctx),
         });
         if (result.isErr()) {
             return Result.ok({
@@ -80,6 +63,23 @@ export const authVerify = trail('auth.verify', {
             valid: true,
         });
     },
-    services: [authService],
+    examples: [
+        {
+            input: { token: 'test-token' },
+            name: 'Verify a token',
+        },
+    ],
+    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(),
+    }),
+    provisions: [authProvision],
 });
 //# sourceMappingURL=auth-verify.js.map

package/dist/trails/auth-verify.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-verify.js","sourceRoot":"","sources":["../../src/trails/auth-verify.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth-verify.js","sourceRoot":"","sources":["../../src/trails/auth-verify.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/permits",
-  "version": "1.0.0-beta.13",
+  "version": "1.0.0-beta.14",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -15,7 +15,7 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "peerDependencies": {
-    "@ontrails/core": "^1.0.0-beta.12",
+    "@ontrails/core": "^1.0.0-beta.13",
     "zod": "^4.3.5"
   }
 }

package/tsconfig.tsbuildinfo

@@ -1 +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"}
+{"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"}