@lostgradient/weft 0.2.0

package/dist/server/authentication/types.d.ts

@@ -0,0 +1,290 @@
+import type { AuthorizationScope } from '../authorization-scope.ts';
+import type { AuthenticatedPrincipal } from '../principal.ts';
+import type { AuthAuditSink } from './audit.ts';
+type HMACAlgorithm = 'HS256' | 'HS384' | 'HS512';
+type RSAAlgorithm = 'RS256' | 'RS384' | 'RS512';
+type ECDSAAlgorithm = 'ES256' | 'ES384' | 'ES512';
+/**
+ * JWT signing algorithm supported by {@link JWTConfig}.
+ *
+ * HMAC variants (`HS256`, `HS384`, `HS512`) use a shared secret; RSA variants
+ * (`RS256`, `RS384`, `RS512`) and ECDSA variants (`ES256`, `ES384`, `ES512`) use
+ * asymmetric keys configured via `publicKey` in the {@link JWTConfig}.
+ *
+ * @example
+ * ```ts
+ * import { type JWTAlgorithm, type JWTConfig } from '@lostgradient/weft';
+ *
+ * const algorithm: JWTAlgorithm = 'RS256';
+ * const config: JWTConfig = {
+ *   algorithm,
+ *   publicKey: '-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----',
+ *   issuer: 'https://auth.example.com',
+ * };
+ * void config;
+ * ```
+ */
+export type JWTAlgorithm = HMACAlgorithm | RSAAlgorithm | ECDSAAlgorithm;
+/**
+ * Configuration for JWT signature verification in the Weft HTTP server.
+ *
+ * Supply either `secret` (for HMAC algorithms) or `publicKey` (for RSA/ECDSA).
+ * Optional `issuer`, `audience`, and `clockTolerance` fields guard against
+ * token reuse and clock-skew rejection.
+ *
+ * @example
+ * ```ts
+ * import { type JWTConfig } from '@lostgradient/weft';
+ *
+ * const jwtConfig: JWTConfig = {
+ *   secret: process.env['JWT_SECRET'] ?? '',
+ *   algorithm: 'HS256',
+ *   issuer: 'https://auth.example.com',
+ *   audience: 'weft-api',
+ *   clockTolerance: 30,
+ * };
+ * void jwtConfig;
+ * ```
+ */
+export type JWTConfig = {
+    /** HMAC secret for HS256/HS384/HS512 algorithms. */
+    secret?: string;
+    /** PEM-encoded public key for RS* or ES* algorithms. */
+    publicKey?: string;
+    /** Signing algorithm (default: HS256). */
+    algorithm?: JWTAlgorithm;
+    /** Expected `iss` claim. Rejected if present and mismatched. */
+    issuer?: string;
+    /** Expected `aud` claim. Rejected if present and mismatched. */
+    audience?: string;
+    /** Seconds of clock skew tolerance for `exp` and `nbf` checks (default: 60). */
+    clockTolerance?: number;
+};
+/**
+ * Mutual TLS configuration passed through to `Bun.serve`'s `tls` option.
+ *
+ * When present in an {@link AuthConfig}, the server requires every client to
+ * present a valid certificate signed by the configured CA.  Requests that reach
+ * the application handler are already authenticated at the transport layer.
+ *
+ * @example
+ * ```ts
+ * import { type MTLSConfig } from '@lostgradient/weft';
+ * import { readFileSync } from 'node:fs';
+ *
+ * const mtlsConfig: MTLSConfig = {
+ *   ca: readFileSync('./certs/ca.pem', 'utf8'),
+ *   cert: readFileSync('./certs/server.crt', 'utf8'),
+ *   key: readFileSync('./certs/server.key', 'utf8'),
+ *   rejectUnauthorized: true,
+ * };
+ * void mtlsConfig;
+ * ```
+ */
+export type MTLSConfig = {
+    /** PEM-encoded CA certificate(s) for client certificate verification. */
+    ca: string | string[];
+    /** PEM-encoded server certificate. */
+    cert: string;
+    /** PEM-encoded server private key. */
+    key: string;
+    /** Reject connections without a valid client certificate (default: true). */
+    rejectUnauthorized?: boolean;
+};
+/**
+ * Top-level authentication configuration for {@link serve}.
+ *
+ * At least one of `apiKeys`, `resolveApiKeyPrincipal`, `jwt`, or `mtls` must be
+ * present — the server rejects the config at startup otherwise.  Paths listed in
+ * `publicPaths` bypass all authentication (default: health, metrics, and
+ * discovery document endpoints).
+ *
+ * @example
+ * ```ts
+ * import { type AuthConfig } from '@lostgradient/weft';
+ *
+ * const auth: AuthConfig = {
+ *   apiKeys: [process.env['API_KEY'] ?? ''],
+ *   jwt: {
+ *     secret: process.env['JWT_SECRET'] ?? '',
+ *     issuer: 'https://auth.example.com',
+ *   },
+ *   publicPaths: ['/v1/health', '/openapi.json'],
+ * };
+ * void auth;
+ * ```
+ */
+export type AuthConfig = {
+    /** Allowed API keys. Checked against `Authorization: Bearer <key>` and `X-API-Key` headers. */
+    apiKeys?: string[];
+    /** JWT verification configuration. */
+    jwt?: JWTConfig;
+    /** Mutual TLS configuration. Passed through to Bun.serve's `tls` option. */
+    mtls?: MTLSConfig;
+    /**
+     * Paths that bypass authentication. Defaults to
+     * `['/v1/health', '/v1/metrics', '/.well-known/api-catalog', '/.well-known/mcp.json', '/openapi.json', '/openrpc.json', '/asyncapi.json']`.
+     */
+    publicPaths?: string[];
+    /**
+     * Optional resolver that maps a presented API key to a fully-shaped
+     * `AuthenticatedPrincipal`. When configured, the resolver is
+     * authoritative for the entire API-key space:
+     *   - returns a principal → admitted with that principal entirely
+     *     (scopes authoritative; `defaultApiKeyScopes` IGNORED).
+     *   - returns `null` → key rejected; static `apiKeys` is NOT
+     *     consulted as a fallback.
+     *   - throws → treated as `null` (rejected); server log records the
+     *     throw detail, wire error stays generic.
+     * When not configured, static `apiKeys` admits and the admitted
+     * principal's scopes come from `defaultApiKeyScopes ?? []`.
+     */
+    resolveApiKeyPrincipal?: (key: string) => Promise<AuthenticatedPrincipal | null>;
+    /**
+     * Scopes granted to principals admitted via static `apiKeys`. Ignored
+     * when `resolveApiKeyPrincipal` is configured (the resolver's scopes
+     * are authoritative for keys it admits). Defaults to `[]`.
+     */
+    defaultApiKeyScopes?: ReadonlyArray<AuthorizationScope>;
+    /**
+     * Sink for the authentication audit trail. The authenticator emits one
+     * structured {@link AuthAuditSink} event per non-public decision (admission
+     * or rejection), carrying the authenticated subject, method, and outcome —
+     * never the presented credential. Public-path bypasses are not audited.
+     * Defaults to a sink that writes one JSON line per event to the console
+     * (`console.info` for success, `console.warn` for failure). Set to a custom
+     * sink to forward audit records to a SIEM, or to a no-op to disable auditing.
+     */
+    auditSink?: AuthAuditSink;
+};
+/**
+ * Which authentication path admitted a request.
+ *
+ * Returned inside an {@link AuthResult} when `authenticated: true`.  Use this
+ * to distinguish bearer-token callers from mTLS-authenticated services or to
+ * log the admission method alongside the request trace.
+ *
+ * @example
+ * ```ts
+ * import { createAuthenticator, type AuthMethod } from '@lostgradient/weft';
+ *
+ * const authenticate = await createAuthenticator({ apiKeys: ['key-1'] });
+ * const req = new Request('http://localhost/v1/workflows', {
+ *   headers: { 'X-API-Key': 'key-1' },
+ * });
+ * const result = await authenticate(req);
+ * if (result.authenticated) {
+ *   const method: AuthMethod = result.method;
+ *   console.log(method); // 'api-key'
+ * }
+ * ```
+ */
+export type AuthMethod = 'api-key' | 'jwt' | 'mtls' | 'public';
+/**
+ * Shared context carried from the authenticator through the request
+ * pipeline. Single source of truth for the `{ method, claims?,
+ * principal? }` shape — re-used by `AuthResult`,
+ * `HandlerOptions.authContext`, and the handler's internal
+ * `AuthenticatedRequestContext`.
+ *
+ *   - `method`: which admission path succeeded.
+ *   - `claims`: JWT payload when `method === 'jwt'`.
+ *   - `principal`: fully-shaped principal forwarded from the
+ *     authenticator (resolver admission, or static API-key admission
+ *     with `defaultApiKeyScopes`). Downstream pipeline code uses this
+ *     verbatim; when absent, `authContextToPrincipal` reconstructs a
+ *     minimal principal from `method` + `claims`.
+ */
+export type AuthContext = {
+    method: AuthMethod;
+    claims?: JWTPayload;
+    principal?: AuthenticatedPrincipal;
+};
+/**
+ * Discriminated union returned by an {@link Authenticator}.
+ *
+ * Check `authenticated` first: when `true`, the request was admitted and
+ * `method` (plus optional `claims` / `principal`) are populated.  When
+ * `false`, `error` holds a client-safe rejection message.
+ *
+ * @example
+ * ```ts
+ * import { createAuthenticator, type AuthResult } from '@lostgradient/weft';
+ *
+ * const authenticate = await createAuthenticator({ apiKeys: ['s3cr3t'] });
+ * const req = new Request('http://localhost/v1/workflows');
+ * const result: AuthResult = await authenticate(req);
+ * if (!result.authenticated) {
+ *   console.error('Rejected:', result.error);
+ * } else {
+ *   console.log('Admitted via', result.method);
+ * }
+ * ```
+ */
+export type AuthResult = ({
+    authenticated: true;
+} & AuthContext) | {
+    authenticated: false;
+    error: string;
+};
+/**
+ * Decoded JWT claims payload — the JSON object between the JWT header and
+ * signature after base64url-decoding.
+ *
+ * Populated on an {@link AuthResult} when `method === 'jwt'`.  Standard claims
+ * (`iss`, `sub`, `aud`, `exp`, `nbf`) are validated automatically; any
+ * application-specific claims are accessible as `claims['my-claim']`.
+ *
+ * @example
+ * ```ts
+ * import { createAuthenticator, type JWTPayload } from '@lostgradient/weft';
+ *
+ * const authenticate = await createAuthenticator({
+ *   jwt: { secret: 'test-secret' },
+ * });
+ * const req = new Request('http://localhost/v1/workflows', {
+ *   headers: { Authorization: 'Bearer <token>' },
+ * });
+ * const result = await authenticate(req);
+ * if (result.authenticated && result.method === 'jwt') {
+ *   const payload: JWTPayload = result.claims ?? {};
+ *   console.log(payload['sub']);
+ * }
+ * ```
+ */
+export type JWTPayload = Record<string, unknown>;
+/**
+ * Async function that inspects a `Request` and returns an {@link AuthResult}.
+ *
+ * Obtain an `Authenticator` by calling `createAuthenticator(config)`.  You can
+ * also implement this type directly to plug a custom admission strategy into the
+ * server handler pipeline.
+ *
+ * @example
+ * ```ts
+ * import { createAuthenticator, type Authenticator } from '@lostgradient/weft';
+ *
+ * const authenticate: Authenticator = await createAuthenticator({
+ *   apiKeys: ['my-key'],
+ * });
+ *
+ * const request = new Request('http://localhost/v1/workflows', {
+ *   headers: { 'X-API-Key': 'my-key' },
+ * });
+ * const result = await authenticate(request);
+ * console.log(result.authenticated); // true
+ * ```
+ */
+export type Authenticator = (request: Request) => Promise<AuthResult>;
+export declare const DEFAULT_PUBLIC_PATHS: string[];
+export declare const DEFAULT_CLOCK_TOLERANCE = 60;
+/**
+ * Normalize the request pathname for consistent public-path lookup: strip
+ * trailing slashes (except bare `/`) so that `/v1/health` and `/v1/health/`
+ * resolve to the same key.
+ *
+ * Used by both the authenticator and the request-gate rate-limiting step so
+ * that public-path detection stays consistent across both modules.
+ */
+export declare function normalizeRequestPathname(request: Request): string;
+export {};

package/dist/server/authentication/types.js

@@ -0,0 +1,13 @@
+export const DEFAULT_PUBLIC_PATHS = [
+  "/v1/health",
+  "/v1/metrics",
+  "/.well-known/api-catalog",
+  "/.well-known/mcp.json",
+  "/openapi.json",
+  "/openrpc.json",
+  "/asyncapi.json"
+], DEFAULT_CLOCK_TOLERANCE = 60;
+export function normalizeRequestPathname(request) {
+  const url = new URL(request.url);
+  return url.pathname.length > 1 ? url.pathname.replace(/\/+$/, "") : url.pathname;
+}

package/dist/server/authentication.d.ts

@@ -0,0 +1 @@
+export * from './authentication/index.ts';

package/dist/server/authentication.js

@@ -0,0 +1 @@
+export * from "./authentication/index.js";

package/dist/server/authorization-scope.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Authorization scope vocabulary — extracted into its own module to avoid a
+ * dependency cycle between `principal.ts` and `authorization.ts`.
+ *
+ * All authorization-scope-related types and runtime helpers live here. Access
+ * policies, scope requirements, and the access-check pipeline live in
+ * `authorization.ts`.
+ */
+/**
+ * All authorization scopes recognized by the runtime. Full-word, colon-separated,
+ * one entry per (domain, action) pair. Add new scopes here when introducing a
+ * new domain; never derive scope strings dynamically.
+ *
+ * Scope semantics are deliberately FLAT for v1 — `workflows:admin` does NOT
+ * imply `workflows:read` or `workflows:write`. Operation authors must declare
+ * the exact scope they require. Scope-implication semantics (if any) are a
+ * future track.
+ */
+export declare const AUTHORIZATION_SCOPES: readonly ["workflows:read", "workflows:write", "workflows:admin", "schedules:read", "schedules:write", "signals:write", "updates:write", "queries:read", "reviews:read", "reviews:write", "attributes:read", "attributes:write", "tags:write", "streams:read", "events:read", "budget:read", "budget:write", "storage:read", "storage:write", "storage:admin", "workers:write", "system:read", "system:admin"];
+/** String-literal union of every authorization scope. */
+export type AuthorizationScope = (typeof AUTHORIZATION_SCOPES)[number];
+/** Runtime type guard for the `AuthorizationScope` union. */
+export declare function isAuthorizationScope(value: string): value is AuthorizationScope;
+/**
+ * Extract the full set of scopes granted by a JWT payload by *merging* every
+ * recognized claim source. Real-world tokens commonly carry OIDC scopes (e.g.
+ * `openid profile`) in `scope` while application scopes live in `permissions`;
+ * a short-circuit on the first present claim would silently drop privileges.
+ *
+ * Sources merged (all consulted, all unioned):
+ *   - `scope` — RFC 8693-style space-delimited string
+ *   - `scp` — alternate space-delimited string used by some IdPs
+ *   - `permissions` — array of strings
+ *
+ * Whitespace-only values are treated as absent so they never block fallback to
+ * other sources. Unknown scope strings are silently filtered out — the
+ * vocabulary in `AUTHORIZATION_SCOPES` is the single source of truth and a
+ * misspelled scope cannot grant unintended privileges.
+ *
+ * Credential *validation* (signature verification, expiry, revocation) happens
+ * at the transport edge before the claims object reaches this function.
+ */
+export declare function extractScopesFromClaims(claims: Record<string, unknown>): ReadonlySet<AuthorizationScope>;

package/dist/server/authorization-scope.js

@@ -0,0 +1,53 @@
+export const AUTHORIZATION_SCOPES = [
+  "workflows:read",
+  "workflows:write",
+  "workflows:admin",
+  "schedules:read",
+  "schedules:write",
+  "signals:write",
+  "updates:write",
+  "queries:read",
+  "reviews:read",
+  "reviews:write",
+  "attributes:read",
+  "attributes:write",
+  "tags:write",
+  "streams:read",
+  "events:read",
+  "budget:read",
+  "budget:write",
+  "storage:read",
+  "storage:write",
+  "storage:admin",
+  "workers:write",
+  "system:read",
+  "system:admin"
+];
+const SCOPE_LOOKUP = new Set(AUTHORIZATION_SCOPES);
+export function isAuthorizationScope(value) {
+  return SCOPE_LOOKUP.has(value);
+}
+export function extractScopesFromClaims(claims) {
+  const merged = new Set;
+  addStringClaimScopes(claims.scope, merged);
+  addStringClaimScopes(claims.scp, merged);
+  const permissions = claims.permissions;
+  if (Array.isArray(permissions)) {
+    for (const entry of permissions)
+      if (typeof entry === "string" && isAuthorizationScope(entry))
+        merged.add(entry);
+  }
+  return merged;
+}
+function addStringClaimScopes(value, target) {
+  if (typeof value !== "string")
+    return;
+  if (value.trim().length === 0)
+    return;
+  for (const token of value.split(/\s+/)) {
+    if (token.length === 0)
+      continue;
+    if (isAuthorizationScope(token))
+      target.add(token);
+  }
+}

package/dist/server/authorization.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Transport-neutral authorization policy types and the pipeline access check.
+ *
+ * Hosts the `AccessPolicy` / `ScopeRequirement` discriminated unions and
+ * `evaluateAccess`, the function `executeOperation` calls between the
+ * authentication step and the operation invocation. The scope vocabulary
+ * and JWT claim extraction live in `authorization-scope.ts` — separated to
+ * keep `principal.ts` and this file cycle-free.
+ *
+ * See Track 8 design decisions 3, 6, and 10.
+ */
+import { type AuthorizationScope } from './authorization-scope.ts';
+import { type Principal } from './principal.ts';
+/** Non-empty tuple of authorization scopes. Prevents `anyOf([])` / `allOf([])` at the type level. */
+export type ScopeRequirement = {
+    kind: 'anyOf';
+    scopes: [AuthorizationScope, ...AuthorizationScope[]];
+} | {
+    kind: 'allOf';
+    scopes: [AuthorizationScope, ...AuthorizationScope[]];
+};
+/** The only representable access policies for an operation. Invalid combinations are unrepresentable. */
+export type AccessPolicy = {
+    kind: 'public';
+} | {
+    kind: 'authenticated';
+} | {
+    kind: 'scoped';
+    scopes: ScopeRequirement;
+} | {
+    kind: 'scopedAlternatives';
+    alternatives: [ScopeRequirement, ...ScopeRequirement[]];
+} | {
+    kind: 'optionalAuth';
+    authenticatedScopes: ScopeRequirement;
+};
+/**
+ * Result of a pipeline access check. Denials carry a classification so the
+ * caller can emit the correct `Unauthorized` vs `Forbidden` fault.
+ */
+export type AccessCheckResult = {
+    allowed: true;
+} | {
+    allowed: false;
+    classification: 'unauthorized' | 'forbidden';
+    reason: string;
+};
+/**
+ * Evaluate an `AccessPolicy` against the caller's principal. This is the
+ * pipeline step that translates the declarative policy into a pass/fail
+ * decision. Credential *validation* happens at the transport edge, BEFORE
+ * this function runs; by the time we're here, the principal shape tells us
+ * whether the caller is authenticated.
+ */
+export declare function evaluateAccess(policy: AccessPolicy, principal: Principal): AccessCheckResult;

package/dist/server/authorization.js

@@ -0,0 +1,87 @@
+import { isAuthenticated } from "./principal.js";
+export function evaluateAccess(policy, principal) {
+  switch (policy.kind) {
+    case "public":
+      return { allowed: !0 };
+    case "authenticated":
+      if (isAuthenticated(principal))
+        return { allowed: !0 };
+      return {
+        allowed: !1,
+        classification: "unauthorized",
+        reason: "authentication required"
+      };
+    case "scoped":
+      if (!isAuthenticated(principal))
+        return {
+          allowed: !1,
+          classification: "unauthorized",
+          reason: "authentication required"
+        };
+      return checkScopeRequirement(policy.scopes, principal.scopes);
+    case "scopedAlternatives":
+      if (!isAuthenticated(principal))
+        return {
+          allowed: !1,
+          classification: "unauthorized",
+          reason: "authentication required"
+        };
+      return checkScopeAlternatives(policy.alternatives, principal.scopes);
+    case "optionalAuth":
+      if (!isAuthenticated(principal))
+        return { allowed: !0 };
+      return checkScopeRequirement(policy.authenticatedScopes, principal.scopes);
+    default:
+      return assertExhaustive(policy);
+  }
+}
+function assertExhaustive(value) {
+  throw Error(`authorization received a discriminated value with unknown kind: ${String(value.kind)}`);
+}
+function checkScopeRequirement(requirement, held) {
+  if (!Array.isArray(requirement.scopes))
+    throw Error(`authorization: ${requirement.kind} ScopeRequirement.scopes is not an array at runtime`);
+  switch (requirement.kind) {
+    case "anyOf": {
+      if (requirement.scopes.some((scope) => held.has(scope)))
+        return { allowed: !0 };
+      return {
+        allowed: !1,
+        classification: "forbidden",
+        reason: `requires any of: ${requirement.scopes.join(", ")}`
+      };
+    }
+    case "allOf": {
+      if (requirement.scopes.length === 0)
+        throw Error("authorization: allOf ScopeRequirement has an empty scopes array (the non-empty tuple invariant was violated at runtime)");
+      const missing = requirement.scopes.filter((scope) => !held.has(scope));
+      if (missing.length === 0)
+        return { allowed: !0 };
+      return {
+        allowed: !1,
+        classification: "forbidden",
+        reason: `missing required scopes: ${missing.join(", ")}`
+      };
+    }
+    default:
+      return assertExhaustive(requirement);
+  }
+}
+function checkScopeAlternatives(alternatives, held) {
+  if (!Array.isArray(alternatives))
+    throw Error("authorization: scopedAlternatives.alternatives is not an array at runtime");
+  if (alternatives.length === 0)
+    throw Error("authorization: scopedAlternatives has an empty alternatives array (the non-empty tuple invariant was violated at runtime)");
+  const deniedReasons = [];
+  for (const alternative of alternatives) {
+    const result = checkScopeRequirement(alternative, held);
+    if (result.allowed)
+      return { allowed: !0 };
+    deniedReasons.push(result.reason);
+  }
+  return {
+    allowed: !1,
+    classification: "forbidden",
+    reason: `requires one of: ${deniedReasons.join("; ")}`
+  };
+}

package/dist/server/deadline-tracker.d.ts

@@ -0,0 +1,47 @@
+/**
+ * In-memory min-heap that tracks inflight task deadlines.
+ *
+ * Used by the visibility timeout scanner to avoid a full storage scan
+ * on every tick. The scanner pops expired entries from the heap instead
+ * of iterating all `op:inflight:*` records.
+ *
+ * Uses generation-based lazy deletion: each operation ID has a generation
+ * counter. `remove()` bumps the generation in O(1), and heap entries with
+ * an older generation are skipped during `popMin()` and `drainExpired()`.
+ *
+ * @module server/deadline-tracker
+ */
+/** A single tracked deadline entry. */
+export type DeadlineEntry = {
+    operationId: string;
+    deadline: number;
+};
+/**
+ * Min-heap ordered by deadline with O(1) lazy removal.
+ *
+ * - `add`: O(log n)
+ * - `remove`: O(1) — bumps generation counter
+ * - `popMin`: O(log n) amortized — skips stale entries
+ * - `drainExpired`: O(k log n) where k is the number of expired entries
+ */
+export declare class DeadlineTracker {
+    #private;
+    constructor();
+    /** Number of tracked deadlines (excludes stale entries). */
+    get size(): number;
+    /** Peek at the earliest non-stale deadline. Returns `undefined` if empty. */
+    peekDeadline(): number | undefined;
+    /**
+     * Add a new deadline entry. Any previous entry for this operation ID
+     * becomes stale and will be skipped during pop/drain.
+     */
+    add(entry: DeadlineEntry): void;
+    /** Remove and return the entry with the earliest deadline, or `undefined` if empty. */
+    popMin(): DeadlineEntry | undefined;
+    /** Invalidate all entries for the given operation ID in O(1). */
+    remove(operationId: string): void;
+    /** Drain all non-stale entries whose deadline is at or before `now`. */
+    drainExpired(now: number): DeadlineEntry[];
+    /** Remove all entries. */
+    clear(): void;
+}