@lostgradient/weft 0.2.0

package/dist/server/authentication/index.js

@@ -0,0 +1,144 @@
+import { tryAdmitApiKey } from "./api-key.js";
+import { defaultAuthAuditSink, emitAuthAuditEvent } from "./audit.js";
+import { importJWTKey, verifyJWT } from "./crypto.js";
+import {
+  DEFAULT_PUBLIC_PATHS,
+  normalizeRequestPathname
+} from "./types.js";
+export {
+  defaultAuthAuditSink,
+  emitAuthAuditEvent
+} from "./audit.js";
+export { importJWTKey, signJWT, verifyJWT } from "./crypto.js";
+export {
+  createRateLimiter,
+  validateRateLimitConfig
+} from "./rate-limiter.js";
+export { isSensitiveHeader, redactCredential, redactHeaders } from "./redaction.js";
+export {
+  createRotatingApiKeyStore
+} from "./rotating-api-key-store.js";
+export {
+  DEFAULT_CLOCK_TOLERANCE,
+  DEFAULT_PUBLIC_PATHS
+} from "./types.js";
+function extractBearerToken(request) {
+  const authorization = request.headers.get("Authorization");
+  if (authorization?.startsWith("Bearer "))
+    return authorization.slice(7);
+  return null;
+}
+function extractApiKey(request) {
+  const headerKey = request.headers.get("X-API-Key");
+  if (headerKey)
+    return headerKey;
+  return extractBearerToken(request);
+}
+function validateJwtConfig(config) {
+  if (config === void 0)
+    return;
+  const algorithm = config.algorithm ?? "HS256";
+  if (algorithm.startsWith("HS") && !config.secret)
+    throw Error('JWT configuration requires "secret" for HMAC algorithms');
+  if ((algorithm.startsWith("RS") || algorithm.startsWith("ES")) && !config.publicKey)
+    throw Error('JWT configuration requires "publicKey" for RSA/ECDSA algorithms');
+}
+function assertAtLeastOneMethod(config) {
+  if (!(config.apiKeys && config.apiKeys.length > 0 || config.jwt !== void 0 || config.mtls !== void 0 || config.resolveApiKeyPrincipal !== void 0))
+    throw Error("AuthConfig must specify at least one authentication method (apiKeys, resolveApiKeyPrincipal, jwt, or mtls)");
+}
+function assertNoConflictingMethods(config) {
+  if (config.resolveApiKeyPrincipal !== void 0 && config.jwt !== void 0)
+    throw Error("AuthConfig cannot combine resolveApiKeyPrincipal with jwt: the resolver consumes every Authorization: Bearer token before JWT verification, so the JWT method would be unreachable.");
+}
+async function authenticateViaApiKey(request, options) {
+  const presentedKey = extractApiKey(request), hasApiKeyPath = options.resolver !== void 0 || options.apiKeySet !== null;
+  if (!presentedKey || !hasApiKeyPath)
+    return { explicitAuthAttempted: !1, result: null };
+  const result = await tryAdmitApiKey(presentedKey, options.resolver, options.apiKeySet, options.defaultApiKeyScopes);
+  return {
+    explicitAuthAttempted: !0,
+    result: result === "continue" ? null : result
+  };
+}
+async function authenticateViaJwt(request, jwtKey, jwtConfig) {
+  if (!jwtKey || !jwtConfig)
+    return { explicitAuthAttempted: !1, result: null };
+  const token = extractBearerToken(request);
+  if (!token)
+    return { explicitAuthAttempted: !1, result: null };
+  if (!token.includes("."))
+    return { explicitAuthAttempted: !0, result: null };
+  try {
+    return { explicitAuthAttempted: !0, result: { authenticated: !0, method: "jwt", claims: await verifyJWT(token, jwtKey, jwtConfig) } };
+  } catch (error) {
+    console.warn("JWT verification failed:", error instanceof Error ? error.message : error);
+    return { explicitAuthAttempted: !0, result: null };
+  }
+}
+export function validateAuthConfig(config) {
+  validateJwtConfig(config.jwt);
+  assertAtLeastOneMethod(config);
+  assertNoConflictingMethods(config);
+}
+export async function createAuthenticator(config) {
+  validateAuthConfig(config);
+  const apiKeySet = config.apiKeys?.length ? new Set(config.apiKeys) : null, resolver = config.resolveApiKeyPrincipal, defaultApiKeyScopes = config.defaultApiKeyScopes ?? [], jwtKey = config.jwt ? await importJWTKey(config.jwt) : null, publicPaths = new Set(config.publicPaths ?? DEFAULT_PUBLIC_PATHS), auditSink = config.auditSink ?? defaultAuthAuditSink;
+  return async (request) => {
+    if (publicPaths.has(normalizeRequestPathname(request)))
+      return { authenticated: !0, method: "public" };
+    const apiKeyAttempt = await authenticateViaApiKey(request, {
+      resolver,
+      apiKeySet,
+      defaultApiKeyScopes
+    });
+    if (apiKeyAttempt.result !== null)
+      return auditDecision(auditSink, request, apiKeyAttempt.result);
+    const jwtAttempt = await authenticateViaJwt(request, jwtKey, config.jwt);
+    if (jwtAttempt.result !== null)
+      return auditDecision(auditSink, request, jwtAttempt.result);
+    const explicitAuthAttempted = apiKeyAttempt.explicitAuthAttempted || jwtAttempt.explicitAuthAttempted;
+    if (config.mtls && !explicitAuthAttempted)
+      return auditDecision(auditSink, request, { authenticated: !0, method: "mtls" });
+    return auditDecision(auditSink, request, {
+      authenticated: !1,
+      error: "No valid credentials provided"
+    });
+  };
+}
+function auditDecision(sink, request, result) {
+  if (result.authenticated)
+    emitAuthAuditEvent(sink, {
+      outcome: "success",
+      method: result.method,
+      subject: subjectFromResult(result),
+      request
+    });
+  else
+    emitAuthAuditEvent(sink, {
+      outcome: "failure",
+      method: "unknown",
+      subject: void 0,
+      request,
+      reason: result.error,
+      presentedCredential: extractApiKey(request)
+    });
+  return result;
+}
+function subjectFromResult(result) {
+  if (result.principal?.subject !== void 0)
+    return result.principal.subject;
+  const sub = result.claims?.sub;
+  return typeof sub === "string" ? sub : void 0;
+}
+export function buildTLSOptions(config) {
+  if (!config?.mtls)
+    return;
+  return {
+    cert: config.mtls.cert,
+    key: config.mtls.key,
+    ca: config.mtls.ca,
+    requestCert: !0,
+    rejectUnauthorized: config.mtls.rejectUnauthorized ?? !0
+  };
+}

package/dist/server/authentication/rate-limiter.d.ts

@@ -0,0 +1,126 @@
+/**
+ * In-process request rate limiting keyed by principal or client address.
+ *
+ * Weft's request pipeline previously capped only body size (1 MB) and JSON-RPC
+ * batch length (100 items); a single principal or IP could otherwise flood the
+ * server with unbounded request volume. This limiter adds a configurable
+ * fixed-window counter so a hostile or runaway caller is throttled with HTTP
+ * 429 once it exceeds its budget.
+ *
+ * **Scope and trust posture.** This is a single-process, in-memory limiter — it
+ * is a load-shedding guardrail, not a distributed quota. Behind multiple server
+ * instances each process keeps its own counters; deployments that need a global
+ * budget should still front Weft with a shared reverse-proxy limiter. The
+ * in-process limiter exists so a single instance cannot be trivially flooded
+ * even when no proxy is present.
+ *
+ * The window clock is injectable so tests advance time deterministically rather
+ * than sleeping against the wall clock.
+ *
+ * @module server/authentication/rate-limiter
+ */
+/**
+ * Configuration for the request rate limiter, supplied via
+ * `serve({ rateLimit })`. Omitting `rateLimit` entirely disables limiting (the
+ * historical behavior), so it is opt-in and never silently changes an existing
+ * deployment.
+ *
+ * @example
+ * ```ts
+ * import { type RateLimitConfig } from '@lostgradient/weft/server';
+ *
+ * const rateLimit: RateLimitConfig = {
+ *   maxRequests: 100,
+ *   windowMs: 60_000,
+ * };
+ * void rateLimit;
+ * ```
+ */
+export type RateLimitConfig = {
+    /** Maximum requests permitted per key within each `windowMs` window. Must be a positive integer. */
+    maxRequests: number;
+    /** Length of the fixed window in milliseconds. Must be positive. */
+    windowMs: number;
+    /**
+     * Upper bound on the number of distinct keys tracked at once. When exceeded,
+     * the oldest-expiring entries are evicted so a high-cardinality flood of
+     * unique keys cannot grow memory without bound. Defaults to 10 000.
+     */
+    maxTrackedKeys?: number;
+};
+/**
+ * Outcome of a single {@link RateLimiter.check} call.
+ *
+ * @example
+ * ```ts
+ * import { type RateLimitDecision } from '@lostgradient/weft/server';
+ *
+ * function describe(decision: RateLimitDecision): string {
+ *   return decision.allowed ? 'ok' : `retry after ${decision.retryAfterSeconds}s`;
+ * }
+ * void describe;
+ * ```
+ */
+export type RateLimitDecision = {
+    /** Whether the request is within budget and may proceed. */
+    allowed: boolean;
+    /** Requests still available in the current window after this one. */
+    remaining: number;
+    /** Seconds until the current window resets — surfaced as the `Retry-After` header on a 429. */
+    retryAfterSeconds: number;
+    /** The configured per-window ceiling, surfaced as `X-RateLimit-Limit`. */
+    limit: number;
+};
+/**
+ * A request rate limiter. Call {@link RateLimiter.check} once per request with
+ * a stable key (principal subject when authenticated, otherwise client
+ * address). `dispose` clears the internal state and is invoked on server
+ * shutdown.
+ *
+ * @example
+ * ```ts
+ * import { createRateLimiter, type RateLimiter } from '@lostgradient/weft/server';
+ *
+ * const limiter: RateLimiter = createRateLimiter({ maxRequests: 2, windowMs: 1_000 });
+ * console.log(limiter.check('caller-1').allowed); // true
+ * console.log(limiter.check('caller-1').allowed); // true
+ * console.log(limiter.check('caller-1').allowed); // false
+ * limiter.dispose();
+ * ```
+ */
+export type RateLimiter = {
+    check(key: string): RateLimitDecision;
+    dispose(): void;
+};
+/**
+ * Validate a {@link RateLimitConfig}, throwing on invalid values so a
+ * misconfiguration fails fast at `serve()` time rather than admitting an
+ * accidentally-unlimited or always-zero limiter.
+ *
+ * @example
+ * ```ts
+ * import { validateRateLimitConfig } from '@lostgradient/weft/server';
+ *
+ * validateRateLimitConfig({ maxRequests: 100, windowMs: 60_000 });
+ * console.log('config is valid');
+ * ```
+ */
+export declare function validateRateLimitConfig(config: RateLimitConfig): void;
+/**
+ * Create a fixed-window {@link RateLimiter}. The optional `now` clock is for
+ * deterministic testing; production callers omit it and the limiter reads
+ * `Date.now()`.
+ *
+ * @example
+ * ```ts
+ * import { createRateLimiter } from '@lostgradient/weft/server';
+ *
+ * let clock = 0;
+ * const limiter = createRateLimiter({ maxRequests: 1, windowMs: 1_000 }, () => clock);
+ * console.log(limiter.check('a').allowed); // true
+ * console.log(limiter.check('a').allowed); // false — window not yet reset
+ * clock = 1_000;
+ * console.log(limiter.check('a').allowed); // true — window rolled over
+ * ```
+ */
+export declare function createRateLimiter(config: RateLimitConfig, now?: () => number): RateLimiter;

package/dist/server/authentication/rate-limiter.js

@@ -0,0 +1,61 @@
+const DEFAULT_MAX_TRACKED_KEYS = 1e4;
+export function validateRateLimitConfig(config) {
+  if (!Number.isInteger(config.maxRequests) || config.maxRequests <= 0)
+    throw Error("rateLimit.maxRequests must be a positive integer");
+  if (!Number.isFinite(config.windowMs) || config.windowMs <= 0)
+    throw Error("rateLimit.windowMs must be a positive number");
+  if (config.maxTrackedKeys !== void 0 && (!Number.isInteger(config.maxTrackedKeys) || config.maxTrackedKeys <= 0))
+    throw Error("rateLimit.maxTrackedKeys must be a positive integer when set");
+}
+export function createRateLimiter(config, now = Date.now) {
+  validateRateLimitConfig(config);
+  const maxTrackedKeys = config.maxTrackedKeys ?? DEFAULT_MAX_TRACKED_KEYS, windows = new Map;
+  function evictIfOverCapacity() {
+    if (windows.size <= maxTrackedKeys)
+      return;
+    const overflow = windows.size - maxTrackedKeys;
+    let removed = 0;
+    for (const key of windows.keys()) {
+      windows.delete(key);
+      removed += 1;
+      if (removed >= overflow)
+        break;
+    }
+  }
+  return {
+    check(key) {
+      const currentTime = now(), existing = windows.get(key);
+      if (existing === void 0 || currentTime >= existing.resetAt) {
+        if (existing !== void 0)
+          windows.delete(key);
+        const resetAt = currentTime + config.windowMs;
+        windows.set(key, { count: 1, resetAt });
+        evictIfOverCapacity();
+        return {
+          allowed: !0,
+          remaining: config.maxRequests - 1,
+          retryAfterSeconds: Math.ceil(config.windowMs / 1000),
+          limit: config.maxRequests
+        };
+      }
+      const retryAfterSeconds = Math.max(1, Math.ceil((existing.resetAt - currentTime) / 1000));
+      if (existing.count >= config.maxRequests)
+        return {
+          allowed: !1,
+          remaining: 0,
+          retryAfterSeconds,
+          limit: config.maxRequests
+        };
+      existing.count += 1;
+      return {
+        allowed: !0,
+        remaining: config.maxRequests - existing.count,
+        retryAfterSeconds,
+        limit: config.maxRequests
+      };
+    },
+    dispose() {
+      windows.clear();
+    }
+  };
+}

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

@@ -0,0 +1,72 @@
+/**
+ * Credential redaction for logs and audit events.
+ *
+ * Authentication code logs request context (auth outcomes, JWT failures,
+ * resolver throws) and the audit trail records who called what. None of that
+ * may ever carry a live credential: an `Authorization: Bearer <token>` value,
+ * an `X-API-Key`, or a `Cookie`/`Set-Cookie` session token leaking into a log
+ * line is a credential disclosure. These helpers mask such values *before* they
+ * reach `console.*` or an audit sink.
+ *
+ * The redaction is one-way and irreversible. A masked value keeps just enough
+ * shape to correlate two log lines about the same credential (a short stable
+ * fingerprint) without revealing the secret itself.
+ *
+ * @module server/authentication/redaction
+ */
+/**
+ * Mask a credential value so it can appear in a log or audit record without
+ * disclosing the secret. The result reveals only the length bucket and a short
+ * non-reversible fingerprint, which is enough to tell whether two log lines
+ * concern the same credential without exposing it.
+ *
+ * The fingerprint is derived from a non-cryptographic hash of the value. It is
+ * deliberately *not* the raw prefix of the token — revealing even a prefix of a
+ * high-entropy API key narrows a brute-force search. Equal inputs produce equal
+ * fingerprints; differing inputs almost always differ.
+ *
+ * @example
+ * ```ts
+ * import { redactCredential } from '@lostgradient/weft/server';
+ *
+ * const masked = redactCredential('weft_key_super_secret_value');
+ * console.log(masked.startsWith('<redacted:')); // true
+ * console.log(masked.includes('secret')); // false
+ * ```
+ */
+export declare function redactCredential(value: string | null | undefined): string;
+/**
+ * Produce a plain object snapshot of a request's headers with every sensitive
+ * value masked via {@link redactCredential}. Use this when attaching request
+ * headers to a log line or audit record — it guarantees no credential header
+ * passes through verbatim.
+ *
+ * Header names are lower-cased (the `Headers` iterator already lower-cases
+ * them) so the result is stable regardless of the casing the client sent.
+ *
+ * @example
+ * ```ts
+ * import { redactHeaders } from '@lostgradient/weft/server';
+ *
+ * const request = new Request('http://localhost/v1/workflows', {
+ *   headers: { Authorization: 'Bearer secret-token', 'X-Trace-Id': 'abc' },
+ * });
+ * const safe = redactHeaders(request.headers);
+ * console.log(safe['x-trace-id']); // 'abc'
+ * console.log(safe['authorization']?.startsWith('<redacted:')); // true
+ * ```
+ */
+export declare function redactHeaders(headers: Headers): Record<string, string>;
+/**
+ * Whether a header name is treated as credential-bearing and therefore masked
+ * by {@link redactHeaders}. Comparison is case-insensitive.
+ *
+ * @example
+ * ```ts
+ * import { isSensitiveHeader } from '@lostgradient/weft/server';
+ *
+ * console.log(isSensitiveHeader('Authorization')); // true
+ * console.log(isSensitiveHeader('X-Trace-Id')); // false
+ * ```
+ */
+export declare function isSensitiveHeader(name: string): boolean;

package/dist/server/authentication/redaction.js

@@ -0,0 +1,30 @@
+const SENSITIVE_HEADER_NAMES = new Set([
+  "authorization",
+  "x-api-key",
+  "cookie",
+  "set-cookie",
+  "proxy-authorization"
+]), EMPTY_REDACTION = "<redacted:empty>";
+export function redactCredential(value) {
+  if (value === null || value === void 0 || value.length === 0)
+    return EMPTY_REDACTION;
+  const token = value.startsWith("Bearer ") ? value.slice(7) : value, fingerprint = fingerprintToken(token);
+  return `<redacted:len=${token.length}:fp=${fingerprint}>`;
+}
+function fingerprintToken(token) {
+  let hash = 2166136261;
+  for (let index = 0;index < token.length; index++) {
+    hash ^= token.charCodeAt(index);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+export function redactHeaders(headers) {
+  const snapshot = {};
+  for (const [name, value] of headers)
+    snapshot[name] = SENSITIVE_HEADER_NAMES.has(name) ? redactCredential(value) : value;
+  return snapshot;
+}
+export function isSensitiveHeader(name) {
+  return SENSITIVE_HEADER_NAMES.has(name.toLowerCase());
+}

package/dist/server/authentication/rotating-api-key-store.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Rotatable API-key store with overlapping-validity windows.
+ *
+ * Static `apiKeys` are fixed for the lifetime of a `serve()` call — rotating
+ * them means a config change and a restart, which forces downtime or a
+ * flag-day cutover. This store closes that gap: it is a mutable, in-process key
+ * registry that the authenticator consults on every request through the
+ * existing `resolveApiKeyPrincipal` hook, so an operator can introduce a new
+ * key, let it run alongside the old one, and revoke the old key — all without
+ * restarting the server.
+ *
+ * Overlapping validity is the core rotation primitive: add the replacement key
+ * (clients begin presenting it), keep the outgoing key valid until traffic has
+ * migrated, then revoke the outgoing key. During the overlap window both keys
+ * authenticate. Each key may also carry an absolute `expiresAt`, after which it
+ * is rejected automatically without an explicit revoke.
+ *
+ * Lookups are constant-time map reads; the comparison is the map key itself,
+ * not a per-byte string compare, so no early-exit timing channel is introduced
+ * beyond what the JS engine's map hashing already does.
+ *
+ * @module server/authentication/rotating-api-key-store
+ */
+import type { AuthorizationScope } from '../authorization-scope.ts';
+import { type AuthenticatedPrincipal } from '../principal.ts';
+/**
+ * Registration options for a single key in a {@link RotatingApiKeyStore}.
+ *
+ * @example
+ * ```ts
+ * import { type ApiKeyRegistration } from '@lostgradient/weft/server';
+ *
+ * const registration: ApiKeyRegistration = {
+ *   subject: 'service-account-7',
+ *   scopes: ['workflows:read', 'workflows:write'],
+ *   expiresAt: Date.now() + 86_400_000,
+ * };
+ * void registration;
+ * ```
+ */
+export type ApiKeyRegistration = {
+    /** Principal subject minted for callers presenting this key. */
+    subject: string;
+    /** Authorization scopes granted to this key's principal. Defaults to `[]`. */
+    scopes?: ReadonlyArray<AuthorizationScope>;
+    /**
+     * Absolute expiry timestamp (epoch ms). After this instant the key is
+     * rejected automatically. Omit for a key with no scheduled expiry.
+     */
+    expiresAt?: number;
+};
+/**
+ * A mutable, rotatable API-key registry. Wire it into authentication by passing
+ * its {@link RotatingApiKeyStore.resolve} method as `resolveApiKeyPrincipal`.
+ * Mutate the live set with {@link RotatingApiKeyStore.add} and
+ * {@link RotatingApiKeyStore.revoke} to rotate keys without restarting.
+ *
+ * @example
+ * ```ts
+ * import { createRotatingApiKeyStore, type RotatingApiKeyStore } from '@lostgradient/weft/server';
+ *
+ * const store: RotatingApiKeyStore = createRotatingApiKeyStore();
+ * store.add('key-old', { subject: 'svc', scopes: ['workflows:read'] });
+ * store.add('key-new', { subject: 'svc', scopes: ['workflows:read'] });
+ * // Both authenticate during the overlap window.
+ * store.revoke('key-old');
+ * ```
+ */
+export type RotatingApiKeyStore = {
+    /** Register or replace a key. Replacing an existing key updates its registration in place. */
+    add(key: string, registration: ApiKeyRegistration): void;
+    /** Remove a key immediately. Returns `true` if the key was present. */
+    revoke(key: string): boolean;
+    /** Whether `key` is currently registered and not expired (evaluated against `now()`). */
+    has(key: string): boolean;
+    /** Number of currently-registered keys (including not-yet-expired ones). */
+    readonly size: number;
+    /**
+     * Resolve a presented key to a principal, or `null` when the key is unknown,
+     * revoked, or expired. Shaped to drop directly into
+     * `AuthConfig.resolveApiKeyPrincipal`.
+     */
+    resolve(presentedKey: string): Promise<AuthenticatedPrincipal | null>;
+};
+/**
+ * Create an empty {@link RotatingApiKeyStore}. The optional `now` clock is for
+ * deterministic testing of expiry; production callers omit it and the store
+ * reads `Date.now()`.
+ *
+ * @example
+ * ```ts
+ * import { createRotatingApiKeyStore } from '@lostgradient/weft/server';
+ * import { serve } from '@lostgradient/weft/server';
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ *
+ * const store = createRotatingApiKeyStore();
+ * store.add('initial-key', { subject: 'svc', scopes: ['workflows:read'] });
+ *
+ * await using engine = new Engine({ storage: new MemoryStorage() });
+ * await using server = serve({
+ *   engine,
+ *   auth: { resolveApiKeyPrincipal: store.resolve },
+ * });
+ * void server;
+ * ```
+ */
+export declare function createRotatingApiKeyStore(now?: () => number): RotatingApiKeyStore;

package/dist/server/authentication/rotating-api-key-store.js

@@ -0,0 +1,43 @@
+import { principalFromApiKey } from "../principal.js";
+function isExpired(stored, currentTime) {
+  return stored.expiresAt !== void 0 && currentTime >= stored.expiresAt;
+}
+export function createRotatingApiKeyStore(now = Date.now) {
+  const keys = new Map;
+  return {
+    add(key, registration) {
+      if (key.length === 0)
+        throw Error("Cannot register an empty API key");
+      keys.set(key, {
+        subject: registration.subject,
+        scopes: registration.scopes ?? [],
+        expiresAt: registration.expiresAt
+      });
+    },
+    revoke(key) {
+      return keys.delete(key);
+    },
+    has(key) {
+      const stored = keys.get(key);
+      if (stored === void 0)
+        return !1;
+      if (isExpired(stored, now())) {
+        keys.delete(key);
+        return !1;
+      }
+      return !0;
+    },
+    get size() {
+      return keys.size;
+    },
+    resolve(presentedKey) {
+      const stored = keys.get(presentedKey);
+      if (stored === void 0 || isExpired(stored, now())) {
+        if (stored !== void 0)
+          keys.delete(presentedKey);
+        return Promise.resolve(null);
+      }
+      return Promise.resolve(principalFromApiKey({ subject: stored.subject, scopes: stored.scopes }));
+    }
+  };
+}