@ontrails/permits 1.0.0-beta.12

package/dist/rules.js

@@ -0,0 +1,127 @@
+/** Check whether a trail has any permit declaration (scopes object or 'public'). */
+const hasPermit = (t) => t.permit !== undefined;
+/** Extract scopes from a trail's permit declaration, or empty array. */
+const getScopes = (t) => {
+    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 = (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',
+    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 = (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',
+    trailId: t.id,
+}));
+// ---------------------------------------------------------------------------
+// Rule: scopeNamingConsistency
+// ---------------------------------------------------------------------------
+/** Returns true when a scope follows the `entity:action` convention. */
+const isValidScopeFormat = (scope) => {
+    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 = (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',
+    trailId: t.id,
+})));
+// ---------------------------------------------------------------------------
+// Rule: orphanScopeDetection
+// ---------------------------------------------------------------------------
+/** Build a map of scope -> set of trail IDs that declare it. */
+const buildScopeMap = (trails) => {
+    const map = new Map();
+    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) => trails.filter((t) => t.permit !== undefined && t.permit !== 'public');
+/** Convert orphan scope map entries into diagnostics. */
+const orphanDiagnostics = (scopeMap) => [...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',
+    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 = (trails) => {
+    const scoped = trailsWithScopedPermit(trails);
+    if (scoped.length < 2) {
+        return [];
+    }
+    return orphanDiagnostics(buildScopeMap(scoped));
+};
+// ---------------------------------------------------------------------------
+// Top-level validator
+// ---------------------------------------------------------------------------
+const allRules = [
+    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) => allRules.flatMap((rule) => rule(trails));
+//# sourceMappingURL=rules.js.map

package/dist/rules.js.map

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

package/dist/testing.d.ts

@@ -0,0 +1,20 @@
+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 declare const mintTestPermit: (options?: {
+    readonly id?: string;
+    readonly scopes?: readonly string[];
+    readonly roles?: readonly string[];
+    readonly tenantId?: string;
+}) => Permit;
+/**
+ * Create a test permit matching a trail's permit requirement.
+ * Extracts scopes from the requirement and mints a permit with exactly those scopes.
+ */
+export declare const mintPermitForTrail: (trail: {
+    readonly permit?: PermitRequirement | undefined;
+}) => Permit | undefined;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,UAAU;IACvC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B,KAAG,MAOF,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACjD,KAAG,MAAM,GAAG,SAKZ,CAAC"}

package/dist/testing.js

@@ -0,0 +1,22 @@
+/**
+ * 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) => ({
+    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) => {
+    if (!trail.permit || trail.permit === 'public') {
+        return undefined;
+    }
+    return mintTestPermit({ scopes: trail.permit.scopes });
+};
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAK9B,EAAU,EAAE,CAAC,CAAC;IACb,EAAE,EACA,OAAO,EAAE,EAAE;QACX,QAAQ,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE;IAChE,MAAM,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC;IACpC,GAAG,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;IACtE,GAAG,CAAC,OAAO,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;CAC3E,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,KAElC,EAAsB,EAAE;IACvB,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/C,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,cAAc,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AACzD,CAAC,CAAC"}

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

@@ -0,0 +1,22 @@
+/**
+ * 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 declare const authVerify: import("@ontrails/core").Trail<{
+    token: string;
+}, {
+    valid: boolean;
+    error?: string | undefined;
+    errorCode?: "expired_token" | "insufficient_scope" | "invalid_token" | "missing_credentials" | undefined;
+    permit?: {
+        id: string;
+        scopes: string[];
+        metadata?: Record<string, unknown> | undefined;
+        roles?: string[] | undefined;
+        tenantId?: string | undefined;
+    } | undefined;
+}>;
+//# sourceMappingURL=auth-verify.d.ts.map

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

@@ -0,0 +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"}

package/dist/trails/auth-verify.js

@@ -0,0 +1,85 @@
+import { Result, SURFACE_KEY, trail } from '@ontrails/core';
+import { z } from 'zod';
+import { authService } from '../auth-service.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.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) => value === 'http' || value === 'mcp' || value === 'cli';
+const getSurface = (ctx) => {
+    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],
+});
+//# sourceMappingURL=auth-verify.js.map

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

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

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@ontrails/permits",
+  "version": "1.0.0-beta.12",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./jwt": "./src/adapters/jwt.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": "^1.0.0-beta.12",
+    "zod": "^4.3.5"
+  }
+}

package/src/__tests__/adapter.test.ts

@@ -0,0 +1,338 @@
+import { describe, expect, test } from 'bun:test';
+
+import { Result } from '@ontrails/core';
+
+import type { AuthAdapter, AuthError } from '../adapter.js';
+import type { PermitExtractionInput } from '../extraction.js';
+import type { Permit } from '../permit.js';
+import { createJwtAdapter } from '../adapters/jwt.js';
+
+// ---------------------------------------------------------------------------
+// Test helper: sign a JWT with HMAC-SHA256 using crypto.subtle
+// ---------------------------------------------------------------------------
+
+const base64url = (buf: ArrayBuffer): string => {
+  const bytes = new Uint8Array(buf);
+  let binary = '';
+  for (const b of bytes) {
+    binary += String.fromCodePoint(b);
+  }
+  return btoa(binary)
+    .replaceAll('+', '-')
+    .replaceAll('/', '_')
+    .replace(/=+$/, '');
+};
+
+const base64urlEncode = (str: string): string => {
+  const encoder = new TextEncoder();
+  return base64url(encoder.encode(str).buffer as ArrayBuffer);
+};
+
+const signJwt = async (
+  payload: Record<string, unknown>,
+  secret: string
+): Promise<string> => {
+  const header = base64urlEncode(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+  const body = base64urlEncode(JSON.stringify(payload));
+  const data = `${header}.${body}`;
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    { hash: 'SHA-256', name: 'HMAC' },
+    false,
+    ['sign']
+  );
+  const sig = await crypto.subtle.sign('HMAC', key, encoder.encode(data));
+  return `${data}.${base64url(sig)}`;
+};
+
+const TEST_SECRET = 'test-secret-for-hmac-256';
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+/** Minimal extraction input for tests that don't need all fields. */
+const testInput = (
+  overrides?: Partial<PermitExtractionInput>
+): PermitExtractionInput => ({
+  requestId: 'test-req',
+  surface: 'http',
+  ...overrides,
+});
+
+describe('AuthAdapter interface', () => {
+  test('accepts a valid adapter implementation', async () => {
+    const adapter: AuthAdapter = {
+      // oxlint-disable-next-line require-await -- stub adapter for type test
+      authenticate: async (_input: PermitExtractionInput) => Result.ok(null),
+    };
+    const result = await adapter.authenticate(testInput());
+    expect(result.isOk()).toBe(true);
+  });
+});
+
+/* oxlint-disable max-statements -- test suite with multiple concern groups */
+describe('createJwtAdapter', () => {
+  test('returns an AuthAdapter', () => {
+    const adapter = createJwtAdapter({ secret: TEST_SECRET });
+    expect(adapter).toBeDefined();
+    expect(adapter.authenticate).toBeInstanceOf(Function);
+  });
+
+  test('verifies a valid HS256 token and returns a Permit', async () => {
+    const adapter = createJwtAdapter({ secret: TEST_SECRET });
+    const now = Math.floor(Date.now() / 1000);
+    const token = await signJwt(
+      { exp: now + 3600, scope: 'read write', sub: 'user-123' },
+      TEST_SECRET
+    );
+    const result = await adapter.authenticate(
+      testInput({ bearerToken: token })
+    );
+    expect(result.isOk()).toBe(true);
+    const permit = result.unwrap() as Permit;
+    expect(permit).not.toBeNull();
+    expect(permit.id).toBe('user-123');
+    expect(permit.scopes).toEqual(['read', 'write']);
+  });
+
+  test('rejects an expired token', async () => {
+    const adapter = createJwtAdapter({ secret: TEST_SECRET });
+    const past = Math.floor(Date.now() / 1000) - 3600;
+    const token = await signJwt(
+      { exp: past, sub: 'user-expired' },
+      TEST_SECRET
+    );
+    const result = await adapter.authenticate(
+      testInput({ bearerToken: token })
+    );
+    expect(result.isErr()).toBe(true);
+    const err = (result as ReturnType<typeof Result.err<AuthError>>).error;
+    expect(err.code).toBe('expired_token');
+  });
+
+  test('rejects an invalid signature', async () => {
+    const adapter = createJwtAdapter({ secret: TEST_SECRET });
+    const now = Math.floor(Date.now() / 1000);
+    const token = await signJwt(
+      { exp: now + 3600, sub: 'user-bad-sig' },
+      'wrong-secret'
+    );
+    const result = await adapter.authenticate(
+      testInput({ bearerToken: token })
+    );
+    expect(result.isErr()).toBe(true);
+    const err = (result as ReturnType<typeof Result.err<AuthError>>).error;
+    expect(err.code).toBe('invalid_token');
+  });
+
+  test('rejects tokens with a missing subject claim', async () => {
+    const adapter = createJwtAdapter({ secret: TEST_SECRET });
+    const now = Math.floor(Date.now() / 1000);
+    const token = await signJwt(
+      { exp: now + 3600, scope: 'read' },
+      TEST_SECRET
+    );
+    const result = await adapter.authenticate(
+      testInput({ bearerToken: token })
+    );
+    expect(result.isErr()).toBe(true);
+    const err = (result as ReturnType<typeof Result.err<AuthError>>).error;
+    expect(err.code).toBe('invalid_token');
+    expect(err.message).toContain('Missing subject claim');
+  });
+
+  test('extracts scopes from token claims', async () => {
+    const adapter = createJwtAdapter({
+      scopesClaim: 'permissions',
+      secret: TEST_SECRET,
+    });
+    const now = Math.floor(Date.now() / 1000);
+    const token = await signJwt(
+      {
+        exp: now + 3600,
+        permissions: 'admin:read admin:write',
+        sub: 'user-scopes',
+      },
+      TEST_SECRET
+    );
+    const result = await adapter.authenticate(
+      testInput({ bearerToken: token })
+    );
+    expect(result.isOk()).toBe(true);
+    const permit = result.unwrap() as Permit;
+    expect(permit.scopes).toEqual(['admin:read', 'admin:write']);
+  });
+
+  test('extracts roles from token claims', async () => {
+    const adapter = createJwtAdapter({ secret: TEST_SECRET });
+    const now = Math.floor(Date.now() / 1000);
+    const token = await signJwt(
+      { exp: now + 3600, roles: ['admin', 'editor'], sub: 'user-roles' },
+      TEST_SECRET
+    );
+    const result = await adapter.authenticate(
+      testInput({ bearerToken: token })
+    );
+    expect(result.isOk()).toBe(true);
+    const permit = result.unwrap() as Permit;
+    expect(permit.roles).toEqual(['admin', 'editor']);
+  });
+
+  test('returns null for missing credentials', async () => {
+    const adapter = createJwtAdapter({ secret: TEST_SECRET });
+    const result = await adapter.authenticate(testInput());
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toBeNull();
+  });
+
+  test('checks issuer claim when configured', async () => {
+    const adapter = createJwtAdapter({
+      issuer: 'https://auth.example.com',
+      secret: TEST_SECRET,
+    });
+    const now = Math.floor(Date.now() / 1000);
+    const token = await signJwt(
+      { exp: now + 3600, iss: 'https://evil.example.com', sub: 'user-iss' },
+      TEST_SECRET
+    );
+    const result = await adapter.authenticate(
+      testInput({ bearerToken: token })
+    );
+    expect(result.isErr()).toBe(true);
+    const err = (result as ReturnType<typeof Result.err<AuthError>>).error;
+    expect(err.code).toBe('invalid_token');
+  });
+
+  test('checks audience claim when configured', async () => {
+    const adapter = createJwtAdapter({
+      audience: 'my-api',
+      secret: TEST_SECRET,
+    });
+    const now = Math.floor(Date.now() / 1000);
+    const token = await signJwt(
+      { aud: 'other-api', exp: now + 3600, sub: 'user-aud' },
+      TEST_SECRET
+    );
+    const result = await adapter.authenticate(
+      testInput({ bearerToken: token })
+    );
+    expect(result.isErr()).toBe(true);
+    const err = (result as ReturnType<typeof Result.err<AuthError>>).error;
+    expect(err.code).toBe('invalid_token');
+  });
+
+  test('accepts array-format audience containing configured value', async () => {
+    const adapter = createJwtAdapter({
+      audience: 'my-api',
+      secret: TEST_SECRET,
+    });
+    const now = Math.floor(Date.now() / 1000);
+    const token = await signJwt(
+      { aud: ['my-api', 'account'], exp: now + 3600, sub: 'user-arr-aud' },
+      TEST_SECRET
+    );
+    const result = await adapter.authenticate(
+      testInput({ bearerToken: token })
+    );
+    expect(result.isOk()).toBe(true);
+    const permit = result.unwrap() as Permit;
+    expect(permit.id).toBe('user-arr-aud');
+  });
+
+  test('rejects array-format audience not containing configured value', async () => {
+    const adapter = createJwtAdapter({
+      audience: 'my-api',
+      secret: TEST_SECRET,
+    });
+    const now = Math.floor(Date.now() / 1000);
+    const token = await signJwt(
+      { aud: ['other-api', 'account'], exp: now + 3600, sub: 'user-no-aud' },
+      TEST_SECRET
+    );
+    const result = await adapter.authenticate(
+      testInput({ bearerToken: token })
+    );
+    expect(result.isErr()).toBe(true);
+    const err = (result as ReturnType<typeof Result.err<AuthError>>).error;
+    expect(err.code).toBe('invalid_token');
+  });
+
+  test('extracts scopes from array-format claim', async () => {
+    const adapter = createJwtAdapter({ secret: TEST_SECRET });
+    const now = Math.floor(Date.now() / 1000);
+    const token = await signJwt(
+      { exp: now + 3600, scope: ['read', 'write'], sub: 'user-arr-scope' },
+      TEST_SECRET
+    );
+    const result = await adapter.authenticate(
+      testInput({ bearerToken: token })
+    );
+    expect(result.isOk()).toBe(true);
+    const permit = result.unwrap() as Permit;
+    expect(permit.scopes).toEqual(['read', 'write']);
+  });
+
+  test('filters empty strings from array-format scope claims', async () => {
+    const adapter = createJwtAdapter({ secret: TEST_SECRET });
+    const now = Math.floor(Date.now() / 1000);
+    const token = await signJwt(
+      {
+        exp: now + 3600,
+        scope: ['', 'read', '', 'write'],
+        sub: 'user-arr-scope-empty',
+      },
+      TEST_SECRET
+    );
+    const result = await adapter.authenticate(
+      testInput({ bearerToken: token })
+    );
+    expect(result.isOk()).toBe(true);
+    const permit = result.unwrap() as Permit;
+    expect(permit.scopes).toEqual(['read', 'write']);
+  });
+
+  test('returns error for malformed signature bytes', async () => {
+    const adapter = createJwtAdapter({ secret: TEST_SECRET });
+    const now = Math.floor(Date.now() / 1000);
+    const token = await signJwt(
+      { exp: now + 3600, sub: 'user-bad' },
+      TEST_SECRET
+    );
+    const parts = token.split('.');
+    const malformed = `${parts[0]}.${parts[1]}.!!!invalid-base64!!!`;
+    const result = await adapter.authenticate(
+      testInput({ bearerToken: malformed })
+    );
+    expect(result.isErr()).toBe(true);
+    const err = (result as ReturnType<typeof Result.err<AuthError>>).error;
+    expect(err.code).toBe('invalid_token');
+  });
+
+  test('accepts token with matching issuer and audience', async () => {
+    const adapter = createJwtAdapter({
+      audience: 'my-api',
+      issuer: 'https://auth.example.com',
+      secret: TEST_SECRET,
+    });
+    const now = Math.floor(Date.now() / 1000);
+    const token = await signJwt(
+      {
+        aud: 'my-api',
+        exp: now + 3600,
+        iss: 'https://auth.example.com',
+        scope: 'read',
+        sub: 'user-valid',
+      },
+      TEST_SECRET
+    );
+    const result = await adapter.authenticate(
+      testInput({ bearerToken: token })
+    );
+    expect(result.isOk()).toBe(true);
+    const permit = result.unwrap() as Permit;
+    expect(permit.id).toBe('user-valid');
+  });
+});