@ontrails/permits 0.2.0

package/src/adapters/jwt.ts

@@ -0,0 +1,359 @@
+import { Result } from '@ontrails/core';
+
+import type { AuthAdapter, AuthError } from './adapter.js';
+import type { PermitExtractionInput } from '../extraction.js';
+import type { Permit } from '../permit.js';
+
+/** Configuration for the JWT auth adapter. */
+export interface JwtAdapterOptions {
+  /** Accepted JWT header algorithms (default: ['HS256']). */
+  readonly allowedAlgorithms?: readonly JwtAlgorithm[];
+  /** Clock skew tolerated for exp/nbf checks, in seconds (default: 60). */
+  readonly clockSkewSeconds?: number;
+  /** HMAC secret for HS256 verification. */
+  readonly secret?: string;
+  /** Whether accepted tokens must include exp (default: true). */
+  readonly requireExpiration?: boolean;
+  /** 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;
+}
+
+/** JWT algorithms this adapter can verify today. */
+export type JwtAlgorithm = 'HS256';
+
+interface JwtHeader {
+  readonly alg?: unknown;
+  readonly typ?: unknown;
+  readonly [key: string]: unknown;
+}
+
+/** JWT payload with standard claims. */
+interface JwtPayload {
+  readonly sub?: string;
+  readonly iss?: string;
+  readonly aud?: string | readonly string[];
+  readonly exp?: number | null;
+  readonly nbf?: number;
+  readonly [key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers (defined before callers)
+// ---------------------------------------------------------------------------
+
+const DEFAULT_ALLOWED_ALGORITHMS = [
+  'HS256',
+] as const satisfies readonly JwtAlgorithm[];
+const SUPPORTED_JWT_ALGORITHMS = [
+  'HS256',
+] as const satisfies readonly JwtAlgorithm[];
+const DEFAULT_CLOCK_SKEW_SECONDS = 60;
+
+const authErr = (
+  code: AuthError['code'],
+  message: string
+): Result<never, AuthError> => Result.err({ code, message });
+
+/** Base64url-decode a string to bytes. */
+const base64urlDecode = (input: string): Uint8Array => {
+  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;
+};
+
+const splitToken = (
+  token: string
+): readonly [string, string, string] | undefined => {
+  const parts = token.split('.');
+  if (parts.length !== 3) {
+    return undefined;
+  }
+  return [parts[0] ?? '', parts[1] ?? '', parts[2] ?? ''];
+};
+
+const decodeJsonPart = <T>(part: string): T | undefined => {
+  try {
+    const json = new TextDecoder().decode(base64urlDecode(part));
+    return JSON.parse(json) as T;
+  } catch {
+    return undefined;
+  }
+};
+
+const normalizeClockSkewSeconds = (options: JwtAdapterOptions): number => {
+  const raw = options.clockSkewSeconds ?? DEFAULT_CLOCK_SKEW_SECONDS;
+  const value = Math.floor(raw);
+  return Number.isFinite(value)
+    ? Math.max(0, value)
+    : DEFAULT_CLOCK_SKEW_SECONDS;
+};
+
+const allowedAlgorithms = (
+  options: JwtAdapterOptions
+): readonly JwtAlgorithm[] =>
+  options.allowedAlgorithms ?? DEFAULT_ALLOWED_ALGORITHMS;
+
+const isSupportedJwtAlgorithm = (
+  algorithm: string
+): algorithm is JwtAlgorithm =>
+  (SUPPORTED_JWT_ALGORITHMS as readonly string[]).includes(algorithm);
+
+const validateHeader = (
+  header: JwtHeader,
+  options: JwtAdapterOptions
+): Result<JwtAlgorithm, AuthError> => {
+  if (typeof header.alg !== 'string') {
+    return authErr('invalid_token', 'Missing JWT alg header');
+  }
+  if (!isSupportedJwtAlgorithm(header.alg)) {
+    return authErr('invalid_token', 'Unsupported JWT alg header');
+  }
+  const configuredAlgorithms = allowedAlgorithms(options);
+  if (configuredAlgorithms.length === 0) {
+    return authErr(
+      'invalid_token',
+      'JWT allowedAlgorithms must include at least one algorithm'
+    );
+  }
+  if (!configuredAlgorithms.includes(header.alg)) {
+    return authErr('invalid_token', 'Unsupported JWT alg header');
+  }
+  return Result.ok(header.alg);
+};
+
+/** Import a secret as an HMAC CryptoKey. */
+const importHmacKey = (secret: string): Promise<CryptoKey> => {
+  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: string,
+  key: CryptoKey
+): Promise<boolean> => {
+  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 as ArrayBuffer,
+    encoder.encode(data)
+  );
+};
+
+const verifyJwtSignature = async (
+  token: string,
+  secret: string,
+  algorithm: JwtAlgorithm
+): Promise<boolean> => {
+  switch (algorithm) {
+    case 'HS256': {
+      const key = await importHmacKey(secret);
+      return await verifyHmacSignature(token, key);
+    }
+    default: {
+      const exhaustive: never = algorithm;
+      void exhaustive;
+      return false;
+    }
+  }
+};
+
+/** Validate standard claims (exp, iss, aud). */
+const validateClaims = (
+  payload: JwtPayload,
+  options: JwtAdapterOptions
+): AuthError | undefined => {
+  const now = Math.floor(Date.now() / 1000);
+  const skew = normalizeClockSkewSeconds(options);
+  const hasExpirationClaim = payload.exp !== undefined && payload.exp !== null;
+  if (!hasExpirationClaim && options.requireExpiration !== false) {
+    return { code: 'invalid_token', message: 'Missing expiration claim (exp)' };
+  }
+  if (
+    payload.exp !== undefined &&
+    (typeof payload.exp !== 'number' || !Number.isFinite(payload.exp))
+  ) {
+    return { code: 'invalid_token', message: 'Invalid expiration claim (exp)' };
+  }
+  if (
+    payload.exp !== undefined &&
+    payload.exp !== null &&
+    payload.exp < now - skew
+  ) {
+    return { code: 'expired_token', message: 'Token has expired' };
+  }
+  if (payload.nbf !== undefined) {
+    if (typeof payload.nbf !== 'number' || !Number.isFinite(payload.nbf)) {
+      return {
+        code: 'invalid_token',
+        message: 'Invalid not-before claim (nbf)',
+      };
+    }
+    if (payload.nbf > now + skew) {
+      return { code: 'invalid_token', message: 'Token is not valid yet' };
+    }
+  }
+  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: JwtPayload,
+  claim: string
+): readonly string[] => {
+  const raw = payload[claim];
+  if (typeof raw === 'string') {
+    return raw.split(' ').filter(Boolean);
+  }
+  if (Array.isArray(raw)) {
+    return raw.filter(
+      (s): s is string => typeof s === 'string' && s.length > 0
+    );
+  }
+  return [];
+};
+
+/** Extract roles from a payload claim (string array). */
+const extractRoles = (
+  payload: JwtPayload,
+  claim: string
+): readonly string[] | undefined => {
+  const raw = payload[claim];
+  if (!Array.isArray(raw)) {
+    return undefined;
+  }
+  return raw.filter((r): r is string => typeof r === 'string');
+};
+
+/** Build a Permit from a validated JWT payload. */
+const buildPermit = (
+  payload: JwtPayload,
+  options: JwtAdapterOptions
+): Result<Permit, AuthError> => {
+  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: string,
+  secret: string,
+  options: JwtAdapterOptions
+): Promise<Result<JwtPayload, AuthError>> => {
+  const parts = splitToken(token);
+  if (!parts) {
+    return authErr('invalid_token', 'Malformed JWT');
+  }
+  const [rawHeader, rawPayload] = parts;
+  const header = decodeJsonPart<JwtHeader>(rawHeader);
+  if (!header) {
+    return authErr('invalid_token', 'Malformed JWT header');
+  }
+  const headerResult = validateHeader(header, options);
+  if (headerResult.isErr()) {
+    return headerResult;
+  }
+  const payload = decodeJsonPart<JwtPayload>(rawPayload);
+  if (!payload) {
+    return authErr('invalid_token', 'Malformed JWT');
+  }
+  try {
+    const valid = await verifyJwtSignature(token, secret, headerResult.value);
+    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: JwtPayload,
+  options: JwtAdapterOptions
+): Result<Permit, AuthError> => {
+  const claimError = validateClaims(payload, options);
+  if (claimError) {
+    return Result.err(claimError);
+  }
+  return buildPermit(payload, options);
+};
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a JWT auth adapter 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 createJwtAdapter = (options: JwtAdapterOptions): AuthAdapter => {
+  const authenticate = async (
+    input: PermitExtractionInput
+  ): Promise<Result<Permit | null, AuthError>> => {
+    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,
+      options
+    );
+    return decoded.isErr() ? decoded : payloadToPermit(decoded.value, options);
+  };
+
+  return { authenticate };
+};

package/src/auth-resource.ts

@@ -0,0 +1,90 @@
+import { Result, resource } from '@ontrails/core';
+import { z } from 'zod';
+
+import type { AuthAdapter } from './adapters/adapter.js';
+import { createJwtAdapter } from './adapters/jwt.js';
+import type { JwtAdapterOptions } from './adapters/jwt.js';
+
+const authNoneConfigSchema = z
+  .object({
+    adapter: z.literal('none'),
+  })
+  .readonly();
+
+const authJwtConfigSchema = z
+  .object({
+    adapter: z.literal('jwt'),
+    allowedAlgorithms: z.array(z.literal('HS256')).readonly().optional(),
+    audience: z.string().optional(),
+    clockSkewSeconds: z.number().int().nonnegative().optional(),
+    issuer: z.string().optional(),
+    requireExpiration: z.boolean().optional(),
+    rolesClaim: z.string().min(1).optional(),
+    scopesClaim: z.string().min(1).optional(),
+    secret: z.string().min(1),
+  })
+  .strict()
+  .readonly();
+
+export const authResourceConfigSchema = z
+  .discriminatedUnion('adapter', [authNoneConfigSchema, authJwtConfigSchema])
+  .default({ adapter: 'none' });
+
+export type AuthResourceConfig = z.infer<typeof authResourceConfigSchema>;
+
+const createNoopAdapter = (): AuthAdapter => ({
+  // oxlint-disable-next-line require-await -- no-op adapter satisfies async interface
+  authenticate: async () => Result.ok(null),
+});
+
+const createAdapter = (config: AuthResourceConfig): AuthAdapter => {
+  switch (config.adapter) {
+    case 'none': {
+      return createNoopAdapter();
+    }
+    case 'jwt': {
+      const jwtOptions: JwtAdapterOptions = {
+        ...(config.allowedAlgorithms === undefined
+          ? {}
+          : { allowedAlgorithms: config.allowedAlgorithms }),
+        ...(config.audience === undefined ? {} : { audience: config.audience }),
+        ...(config.clockSkewSeconds === undefined
+          ? {}
+          : { clockSkewSeconds: config.clockSkewSeconds }),
+        ...(config.issuer === undefined ? {} : { issuer: config.issuer }),
+        ...(config.requireExpiration === undefined
+          ? {}
+          : { requireExpiration: config.requireExpiration }),
+        ...(config.rolesClaim === undefined
+          ? {}
+          : { rolesClaim: config.rolesClaim }),
+        ...(config.scopesClaim === undefined
+          ? {}
+          : { scopesClaim: config.scopesClaim }),
+        secret: config.secret,
+      };
+      return createJwtAdapter(jwtOptions);
+    }
+    default: {
+      const exhaustive: never = config;
+      void exhaustive;
+      return createNoopAdapter();
+    }
+  }
+};
+
+/**
+ * Auth resource — manages the auth adapter lifecycle.
+ *
+ * Defaults to a no-op adapter that always succeeds with a null permit, and
+ * can be configured through `ResourceSpec.config` to materialize built-in
+ * adapters such as JWT.
+ */
+export const authResource = resource<AuthAdapter>('auth', {
+  config: authResourceConfigSchema,
+  create: (resourceCtx) =>
+    Result.ok(createAdapter(resourceCtx.config as AuthResourceConfig)),
+  description: 'Authentication adapter',
+  meta: { category: 'infrastructure' },
+  mock: createNoopAdapter,
+});

package/src/boundary.ts

@@ -0,0 +1,200 @@
+import type {
+  AnyResource,
+  BasePermit,
+  ResourceOverrideMap,
+  SurfaceConfigValues,
+  Topo,
+} from '@ontrails/core';
+import {
+  AuthError,
+  Result,
+  ValidationError,
+  basePermitSchema,
+  resolveResourceConfig,
+} from '@ontrails/core';
+
+import type { AuthAdapter } from './adapters/adapter.js';
+import { authAdapterSchema, authErrorSchema } from './adapters/adapter.js';
+import type { PermitExtractionInput } from './extraction.js';
+import { permitExtractionInputSchema } from './extraction.js';
+
+/** Resource id of the auth adapter resource provided by `@ontrails/permits`. */
+export const AUTH_RESOURCE_ID = 'auth';
+
+type LocatedAuthResource =
+  | { readonly kind: 'override'; readonly value: unknown }
+  | { readonly kind: 'declared'; readonly resource: AnyResource };
+
+export interface ResolvePermitFromBearerTokenOptions {
+  readonly bearerToken: string;
+  readonly graph: Topo;
+  readonly requestId: string;
+  readonly surface: PermitExtractionInput['surface'];
+  readonly resources?: ResourceOverrideMap | undefined;
+  readonly configValues?: SurfaceConfigValues | undefined;
+  readonly headers?: Headers | undefined;
+  readonly sessionId?: string | undefined;
+  readonly cwd?: string | undefined;
+  readonly env?: Record<string, string | undefined> | undefined;
+  readonly workspaceRoot?: string | undefined;
+  readonly missingAuthResourceMessage?: string | undefined;
+  readonly nullPermitMessage?: string | undefined;
+}
+
+/** Resolve the auth resource override or registered resource on the topo. */
+const lookupAuthResource = (
+  graph: Topo,
+  resources: ResourceOverrideMap | undefined,
+  missingAuthResourceMessage: string | undefined
+): Result<LocatedAuthResource, ValidationError> => {
+  if (resources !== undefined && Object.hasOwn(resources, AUTH_RESOURCE_ID)) {
+    return Result.ok({
+      kind: 'override',
+      value: resources[AUTH_RESOURCE_ID],
+    });
+  }
+  const declared = graph.getResource(AUTH_RESOURCE_ID);
+  if (declared !== undefined) {
+    return Result.ok({ kind: 'declared', resource: declared });
+  }
+  return Result.err(
+    new ValidationError(
+      missingAuthResourceMessage ??
+        'Bearer token auth requires an auth adapter. Register authResource from @ontrails/permits in your topo.'
+    )
+  );
+};
+
+/**
+ * Materialize the auth adapter from an override or by invoking the declared
+ * resource's `create()` factory.
+ */
+const materializeAuthAdapter = async (
+  resolved: LocatedAuthResource,
+  options: Pick<
+    ResolvePermitFromBearerTokenOptions,
+    'configValues' | 'cwd' | 'env' | 'workspaceRoot'
+  >
+): Promise<Result<AuthAdapter, Error>> => {
+  if (resolved.kind === 'override') {
+    const parsed = authAdapterSchema.safeParse(resolved.value);
+    if (!parsed.success) {
+      return Result.err(
+        new ValidationError(
+          'Override for resource "auth" does not expose an authenticate() function.'
+        )
+      );
+    }
+    return Result.ok(resolved.value as AuthAdapter);
+  }
+
+  const cwd = options.cwd ?? process.cwd();
+  const configResult = resolveResourceConfig(
+    resolved.resource,
+    options.configValues
+  );
+  if (configResult.isErr()) {
+    return configResult;
+  }
+  const created = await resolved.resource.create({
+    config: configResult.value,
+    cwd,
+    env: options.env ?? {},
+    workspaceRoot: options.workspaceRoot ?? cwd,
+  });
+  if (created.isErr()) {
+    return created;
+  }
+  const parsed = authAdapterSchema.safeParse(created.value);
+  if (!parsed.success) {
+    return Result.err(
+      new ValidationError(
+        'Auth resource factory returned a value without an authenticate() function.'
+      )
+    );
+  }
+  return Result.ok(created.value as AuthAdapter);
+};
+
+/**
+ * Resolve a surface-extracted bearer token to a `BasePermit`.
+ *
+ * Surfaces own credential extraction. This helper owns the shared auth
+ * adapter lookup, invocation, error normalization, and BasePermit rendering.
+ */
+export const resolvePermitFromBearerToken = async (
+  options: ResolvePermitFromBearerTokenOptions
+): Promise<Result<BasePermit, Error>> => {
+  const located = lookupAuthResource(
+    options.graph,
+    options.resources,
+    options.missingAuthResourceMessage
+  );
+  if (located.isErr()) {
+    return located;
+  }
+  const adapterResult = await materializeAuthAdapter(located.value, options);
+  if (adapterResult.isErr()) {
+    return adapterResult;
+  }
+  const inputResult = permitExtractionInputSchema.safeParse({
+    bearerToken: options.bearerToken,
+    ...(options.headers === undefined ? {} : { headers: options.headers }),
+    requestId: options.requestId,
+    ...(options.sessionId === undefined
+      ? {}
+      : { sessionId: options.sessionId }),
+    surface: options.surface,
+  });
+  if (!inputResult.success) {
+    return Result.err(
+      new ValidationError('Invalid bearer token extraction input.', {
+        context: { issues: inputResult.error.issues },
+      })
+    );
+  }
+  let authResult: Awaited<ReturnType<AuthAdapter['authenticate']>>;
+  try {
+    authResult = await adapterResult.value.authenticate(inputResult.data);
+  } catch (error) {
+    const errorOptions =
+      error instanceof Error
+        ? { cause: error, context: { code: 'invalid_token' } }
+        : { context: { code: 'invalid_token' } };
+    return Result.err(
+      new AuthError('Auth adapter threw while authenticating bearer token', {
+        ...errorOptions,
+      })
+    );
+  }
+  if (authResult.isErr()) {
+    const parsedError = authErrorSchema.safeParse(authResult.error);
+    const { code, message } = parsedError.success
+      ? parsedError.data
+      : {
+          code: 'invalid_token' as const,
+          message: 'Auth adapter returned a malformed error',
+        };
+    return Result.err(new AuthError(message, { context: { code } }));
+  }
+  if (authResult.value === null) {
+    return Result.err(
+      new AuthError(
+        options.nullPermitMessage ??
+          'Auth adapter did not produce a permit for bearer token',
+        {
+          context: { code: 'missing_credentials' },
+        }
+      )
+    );
+  }
+  const permit = basePermitSchema.safeParse(authResult.value);
+  if (!permit.success) {
+    return Result.err(
+      new AuthError('Auth adapter returned a malformed permit', {
+        context: { code: 'invalid_token', issues: permit.error.issues },
+      })
+    );
+  }
+  return Result.ok(permit.data);
+};

package/src/errors.ts

@@ -0,0 +1 @@
+export { PermitError } from '@ontrails/core';

package/src/extraction.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+
+export const permitExtractionInputSchema = z
+  .object({
+    /** Bearer token from Authorization header or equivalent. */
+    bearerToken: z.string().optional(),
+    /** Raw headers (HTTP surface only, typically). */
+    headers: z.instanceof(Headers).optional(),
+    /** Correlation ID for tracing. */
+    requestId: z.string(),
+    /** Session identifier from transport handshake. */
+    sessionId: z.string().optional(),
+    /** Which surface produced this extraction. */
+    surface: z.enum(['http', 'mcp', 'cli']),
+  })
+  .readonly();
+
+/**
+ * Normalized input for auth adapters.
+ *
+ * Each surface extracts raw credentials from its transport and normalizes them
+ * into this shape. No surface types (Request, McpSession, etc.) cross into
+ * core -- only this schema-derived contract.
+ */
+export type PermitExtractionInput = z.infer<typeof permitExtractionInputSchema>;

package/src/index.ts

@@ -0,0 +1,33 @@
+export {
+  authAdapterSchema,
+  authErrorSchema,
+  type AuthAdapter,
+  type AuthError,
+} from './adapters/adapter.js';
+export {
+  createJwtAdapter,
+  type JwtAlgorithm,
+  type JwtAdapterOptions,
+} from './adapters/jwt.js';
+export {
+  authResource,
+  authResourceConfigSchema,
+  type AuthResourceConfig,
+} from './auth-resource.js';
+export {
+  AUTH_RESOURCE_ID,
+  resolvePermitFromBearerToken,
+  type ResolvePermitFromBearerTokenOptions,
+} from './boundary.js';
+export { authVerify } from './trails/auth-verify.js';
+export { PermitError } from './errors.js';
+export {
+  permitExtractionInputSchema,
+  type PermitExtractionInput,
+} from './extraction.js';
+export { type Permit, getPermit } from './permit.js';
+export {
+  validatePermits,
+  type PermitDiagnostic,
+  type PermitDiagnosticSeverity,
+} from './rules.js';