@legionworks/facet 1.9.0

package/src/service/security/auth.ts

@@ -0,0 +1,168 @@
+/**
+ * Bearer token authentication + constant-time comparison.
+ *
+ * `constantTimeEqual` runs in time proportional to `a.length` so a
+ * timing-attack adversary cannot recover `b` byte-by-byte. We normalize
+ * the comparison length to `b.length` (NOT `max(a.length, b.length)`)
+ * so a different-length `a` produces a deterministic mismatch without
+ * leaking position info — the body of the loop still touches the same
+ * number of slots as `b`.
+ */
+
+import { FacetError } from "../../shared/errors/facet-error";
+
+import { isMutationMethod } from "./http-guards";
+
+/**
+ * Constant-time equality check. Both strings are compared slot-by-slot;
+ * the loop runs the full length of `b` regardless of where `a` first
+ * differs, and uses `|=(unsigned or)` to accumulate the diff so the
+ * timing depends only on `b.length`.
+ */
+export function constantTimeEqual(a: string, b: string): boolean {
+  if (typeof a !== "string" || typeof b !== "string") return false;
+  let diff = a.length ^ b.length;
+  const len = b.length;
+  for (let i = 0; i < len; i += 1) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+/**
+ * Parse an HTTP Authorization header and return the Bearer token, or
+ * null when the header is missing, malformed, or carries a different
+ * scheme. The scheme match is case-insensitive per RFC 7235.
+ */
+export function parseBearer(header: string | null | undefined): string | null {
+  if (header === null || header === undefined) return null;
+  const trimmed = header.trim();
+  if (trimmed.length === 0) return null;
+  const space = trimmed.indexOf(" ");
+  if (space <= 0) return null;
+  const scheme = trimmed.slice(0, space).toLowerCase();
+  if (scheme !== "bearer") return null;
+  const token = trimmed.slice(space + 1).trim();
+  if (token.length === 0) return null;
+  return token;
+}
+
+export type BearerAuthResult =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly error: FacetError };
+
+export type AnyBearerAuthResult =
+  | ({ readonly ok: true } & { readonly matchedIndex: number })
+  | { readonly ok: false; readonly error: FacetError };
+
+/**
+ * Validate that a request carries a Bearer token equal to one of the
+ * expected values (constant-time compare). Used for routes where the
+ * install bearer OR the operator promote bearer is acceptable — the
+ * dispatcher then chooses the verb-specific gate based on which token
+ * matched. Comparison is constant-time over every candidate so the
+ * match position does not leak via timing.
+ */
+export function requireAnyBearer(
+  header: string | null | undefined,
+  expected: readonly string[],
+): AnyBearerAuthResult {
+  if (expected.length === 0) {
+    return {
+      ok: false,
+      error: new FacetError("internal", "Server has no tokens configured", {
+        retryable: false,
+      }),
+    };
+  }
+  const token = parseBearer(header);
+  if (token === null) {
+    return {
+      ok: false,
+      error: new FacetError("invalid_envelope", "Missing or malformed Authorization header", {
+        retryable: false,
+        details: { reason: "missing_bearer" },
+      }),
+    };
+  }
+  let matched = -1;
+  for (let i = 0; i < expected.length; i += 1) {
+    const candidate = expected[i]!;
+    if (typeof candidate !== "string" || candidate.length === 0) continue;
+    if (constantTimeEqual(token, candidate)) matched = i;
+  }
+  if (matched < 0) {
+    return {
+      ok: false,
+      error: new FacetError("invalid_envelope", "Invalid bearer token", {
+        retryable: false,
+        details: { reason: "token_mismatch" },
+      }),
+    };
+  }
+  return { ok: true, matchedIndex: matched };
+}
+
+/**
+ * Validate that a request carries a Bearer token equal to the expected
+ * install token (constant-time compare). The caller supplies the request
+ * header and the expected token; this function returns a typed 401
+ * FacetError when the header is missing/malformed/wrong.
+ */
+export function requireBearer(
+  header: string | null | undefined,
+  expected: string,
+): BearerAuthResult {
+  if (typeof expected !== "string" || expected.length === 0) {
+    return {
+      ok: false,
+      error: new FacetError("internal", "Server has no install token configured", {
+        retryable: false,
+      }),
+    };
+  }
+  const token = parseBearer(header);
+  if (token === null) {
+    return {
+      ok: false,
+      error: new FacetError("invalid_envelope", "Missing or malformed Authorization header", {
+        retryable: false,
+        details: { reason: "missing_bearer" },
+      }),
+    };
+  }
+  if (!constantTimeEqual(token, expected)) {
+    return {
+      ok: false,
+      error: new FacetError("invalid_envelope", "Invalid bearer token", {
+        retryable: false,
+        details: { reason: "token_mismatch" },
+      }),
+    };
+  }
+  return { ok: true };
+}
+
+export interface MutationHeaderCheck {
+  readonly method: string;
+  readonly contentType: string | null | undefined;
+}
+
+/**
+ * Enforce `Content-Type: application/json` on every state-changing
+ * request. Anything else (or no content type at all) is rejected with a
+ * typed invalid_request error so a CSRF vector that submits form-encoded
+ * bodies never reaches the dispatcher.
+ */
+export function checkMutationSecurityHeaders(check: MutationHeaderCheck): BearerAuthResult {
+  if (!isMutationMethod(check.method)) return { ok: true };
+  const ct = (check.contentType ?? "").trim().toLowerCase();
+  if (ct === "application/json" || ct.startsWith("application/json;")) return { ok: true };
+  return {
+    ok: false,
+    error: new FacetError("invalid_request", "Mutations require Content-Type: application/json", {
+      retryable: false,
+      details: { received: check.contentType ?? null },
+    }),
+  };
+}

package/src/service/security/host-origin.ts

@@ -0,0 +1,138 @@
+/**
+ * Host + Origin + Sec-Fetch-Site guard.
+ *
+ * DNS-rebinding defense: a request whose `Host` header is anything other
+ * than `127.0.0.1:<port>` is rejected — the loopback service must NOT
+ * serve a request that was forged from an external DNS name pointing
+ * at it.
+ *
+ * Cross-site forgery defense: a mutation that arrives with an `Origin`
+ * header not equal to the service's own origin OR with `Sec-Fetch-Site`
+ * set to anything other than `same-origin` / `none` is rejected. Reads
+ * (GET) intentionally bypass these checks so a same-process client can
+ * poll status without Origin noise.
+ */
+
+import { FacetError } from "../../shared/errors/facet-error";
+
+import { isMutationMethod } from "./http-guards";
+
+export interface HostOriginInput {
+  readonly method: string;
+  readonly host: string | null | undefined;
+  readonly origin: string | null | undefined;
+  readonly secFetchSite: string | null | undefined;
+  readonly expectedHost: string;
+  readonly ownOrigin: string;
+}
+
+export type HostOriginResult =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly error: FacetError };
+
+const SAFE_SEC_FETCH_SITE = new Set(["same-origin", "none", ""]);
+
+/**
+ * Reject when `Host` !== `expectedHost` exactly. The check is byte-exact
+ * — no canonicalization of `127.0.0.1.` with a trailing dot, no
+ * case-folding — so a forged header cannot sneak through a quirk of
+ * the URL parser. A null/empty `Host` is its own typed 400 (`reason:
+ * "missing_host"`) so the caller can distinguish "no host at all"
+ * from "host mismatch" — both fail-closed, neither is a 500.
+ */
+export const HOST_MISSING_REASON = "missing_host" as const;
+
+export function checkHost(host: string | null | undefined, expectedHost: string): HostOriginResult {
+  if (host === null || host === undefined || host.length === 0) {
+    return {
+      ok: false,
+      error: new FacetError("invalid_request", "Missing Host header", {
+        retryable: false,
+        details: { reason: HOST_MISSING_REASON },
+      }),
+    };
+  }
+  if (host !== expectedHost) {
+    return {
+      ok: false,
+      error: new FacetError("invalid_request", `Host header does not match service origin`, {
+        retryable: false,
+        details: { reason: "host_mismatch", expected: expectedHost, received: host },
+      }),
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Resolve a host configuration value: either a static string or a
+ * function that returns the live value. Exported so router.ts and
+ * stream.ts can use the same accessor (a duplicated copy in either
+ * file would risk one of them forgetting to call the function form).
+ */
+export function resolveHost(value: string | (() => string)): string {
+  return typeof value === "function" ? value() : value;
+}
+
+export const CROSS_SITE_REASON = "cross_site_mutation" as const;
+
+/**
+ * Combined check used by the route guard. Reads (`GET`) require only a
+ * matching Host. Mutations additionally require:
+ *   - Origin absent OR equal to ownOrigin
+ *   - Sec-Fetch-Site absent OR in {same-origin, none}
+ * Any other value is a typed rejection. Cross-site mutation failures
+ * carry `details.reason === CROSS_SITE_REASON` so the caller can map
+ * them to a 403 (CSRF) status instead of a 400 (malformed request).
+ */
+export function checkHostOrigin(input: HostOriginInput): HostOriginResult {
+  const hostResult = checkHost(input.host, input.expectedHost);
+  if (!hostResult.ok) return hostResult;
+
+  if (!isMutationMethod(input.method)) return { ok: true };
+
+  const secFetchSite = (input.secFetchSite ?? "").toLowerCase();
+  if (secFetchSite.length > 0 && !SAFE_SEC_FETCH_SITE.has(secFetchSite)) {
+    return {
+      ok: false,
+      error: new FacetError("invalid_request", `Cross-site mutation rejected`, {
+        retryable: false,
+        details: { reason: CROSS_SITE_REASON, secFetchSite },
+      }),
+    };
+  }
+
+  const origin = input.origin;
+  if (origin !== null && origin !== undefined && origin.length > 0) {
+    if (origin !== input.ownOrigin) {
+      return {
+        ok: false,
+        error: new FacetError("invalid_request", `Origin does not match service origin`, {
+          retryable: false,
+          details: { reason: CROSS_SITE_REASON, received: origin, expected: input.ownOrigin },
+        }),
+      };
+    }
+  }
+
+  return { ok: true };
+}
+
+export function isCrossSiteRejection(error: FacetError | undefined): boolean {
+  return (
+    error?.code === "invalid_request" &&
+    (error.details as { reason?: string } | undefined)?.reason === CROSS_SITE_REASON
+  );
+}
+
+/**
+ * True when a host-check rejection is a missing-host case (vs a host
+ * mismatch). Useful for the route guard to map both to 400 but log /
+ * surface them differently.
+ */
+export function isMissingHostRejection(error: FacetError | undefined): boolean {
+  return (
+    error?.code === "invalid_request" &&
+    (error.details as { reason?: string } | undefined)?.reason === HOST_MISSING_REASON
+  );
+}

package/src/service/security/http-guards.ts

@@ -0,0 +1,13 @@
+/**
+ * HTTP method guards shared between `auth.ts` and `host-origin.ts`.
+ *
+ * Both files need to recognise state-changing methods (POST / PUT /
+ * DELETE / PATCH) for their respective checks (mutation Content-Type
+ * gate, cross-site forgery defense). Single source of truth so the two
+ * checks can never disagree on what counts as a mutation.
+ */
+
+export function isMutationMethod(method: string): boolean {
+  const upper = method.toUpperCase();
+  return upper === "POST" || upper === "PUT" || upper === "DELETE" || upper === "PATCH";
+}

package/src/service/security/leases.ts

@@ -0,0 +1,182 @@
+/**
+ * Gallery lease manager.
+ *
+ * A lease is a short-lived token bound to (artifactId, pid) that
+ * authorizes an SSE stream reconnection for that specific artifact from
+ * a specific client process. The token is never embedded in a URL —
+ * clients reconnect using rotated Bearer authorization, so the SSE
+ * transport never carries a query-string token (EventSource has no way
+ * to set headers).
+ *
+ * Expiry is implemented via per-lease timers — NOT a global polling
+ * loop. This avoids the cost of a periodic wakeup and bounds the cost
+ * of the manager to the number of currently active leases.
+ */
+
+export interface GalleryLease {
+  readonly leaseId: string;
+  readonly artifactId: string;
+  readonly pid: number;
+  readonly expiresAt: number;
+}
+
+export interface GalleryLeaseManagerOptions {
+  readonly leaseTtlMs: number;
+  readonly now?: () => number;
+  readonly onExpire?: (entry: { leaseId: string; artifactId: string }) => void;
+  readonly onExpireNotify?: () => void;
+}
+
+export interface GalleryLeaseManager {
+  issue(input: { artifactId: string; pid: number }): GalleryLease;
+  validate(lease: GalleryLease): boolean;
+  renew(leaseId: string): boolean;
+  release(leaseId: string): void;
+  /**
+   * Register a callback fired exactly once when the lease goes away —
+   * either the per-lease timer firing (`expire`) or a caller-initiated
+   * `release`. Used to bind SSE stream lifetime to lease lifetime: the
+   * stream installs a hook here so its close-controller teardown runs
+   * whichever path removes the lease. Without this the stream kept its
+   * own idle reason forever and pinned the service idle path.
+   */
+  onExpireNotify(leaseId: string, callback: () => void): void;
+  list(): readonly GalleryLease[];
+  clear(): void;
+}
+
+interface ActiveLease {
+  readonly leaseId: string;
+  readonly artifactId: string;
+  readonly pid: number;
+  readonly expiresAt: number;
+}
+
+export function createLeaseManager(options: GalleryLeaseManagerOptions): GalleryLeaseManager {
+  const now = options.now ?? Date.now;
+  const active = new Map<string, ActiveLease>();
+  const timers = new Map<string, ReturnType<typeof setTimeout>>();
+  // One-shot notifications registered per lease. Fired by both `expire`
+  // and `release` — from the stream's perspective a released lease and
+  // an expired lease are the same event ("this lease is gone"). The
+  // stream handler installs its close-controller hook here so lease
+  // expiry OR explicit release closes the stream — without this binding
+  // the stream would outlast its lease and pin the idle controller.
+  const expireListeners = new Map<string, Array<() => void>>();
+
+  function expire(leaseId: string): void {
+    const removed = active.get(leaseId);
+    if (!removed) return;
+    active.delete(leaseId);
+    timers.delete(leaseId);
+    const listeners = expireListeners.get(leaseId);
+    expireListeners.delete(leaseId);
+    options.onExpire?.({ leaseId: removed.leaseId, artifactId: removed.artifactId });
+    if (listeners !== undefined) {
+      for (const cb of listeners) {
+        try {
+          cb();
+        } catch {
+          // notification handler errors must not break the timer path
+        }
+      }
+    }
+  }
+
+  function schedule(leaseId: string, ttl: number): void {
+    const existing = timers.get(leaseId);
+    if (existing !== undefined) clearTimeout(existing);
+    const handle = setTimeout(() => expire(leaseId), ttl);
+    // Don't keep the event loop alive solely for lease timers — the
+    // service goes idle when the last reason clears, and a pending
+    // timer should not block shutdown.
+    if (typeof handle.unref === "function") handle.unref();
+    timers.set(leaseId, handle);
+  }
+
+  return {
+    issue(input) {
+      const issuedAt = now();
+      const leaseId = crypto.randomUUID();
+      const lease: ActiveLease = {
+        leaseId,
+        artifactId: input.artifactId,
+        pid: input.pid,
+        expiresAt: issuedAt + options.leaseTtlMs,
+      };
+      active.set(leaseId, lease);
+      schedule(leaseId, options.leaseTtlMs);
+      return lease;
+    },
+    validate(lease) {
+      const record = active.get(lease.leaseId);
+      if (!record) return false;
+      if (record.expiresAt <= now()) return false;
+      if (record.artifactId !== lease.artifactId) return false;
+      if (record.pid !== lease.pid) return false;
+      return true;
+    },
+    renew(leaseId) {
+      const record = active.get(leaseId);
+      if (!record) return false;
+      if (record.expiresAt <= now()) {
+        expire(leaseId);
+        return false;
+      }
+      active.set(leaseId, { ...record, expiresAt: now() + options.leaseTtlMs });
+      schedule(leaseId, options.leaseTtlMs);
+      return true;
+    },
+    release(leaseId) {
+      const removed = active.get(leaseId);
+      if (!removed) return;
+      const handle = timers.get(leaseId);
+      if (handle !== undefined) {
+        clearTimeout(handle);
+        timers.delete(leaseId);
+      }
+      active.delete(leaseId);
+      // A caller-initiated release and a timer-driven expiry are the
+      // same event from the stream's perspective — "this lease is
+      // gone". Fire the per-lease listeners so a stream bound to this
+      // lease tears itself down (releasing its idle reason + broadcaster
+      // slot) instead of waiting forever for a timer that was just
+      // cancelled. `active` is deleted before the listeners run, so a
+      // re-entrant `release`/`renew` from inside a listener no-ops and
+      // the lease stays un-resurrectable.
+      const listeners = expireListeners.get(leaseId);
+      expireListeners.delete(leaseId);
+      if (listeners !== undefined) {
+        for (const cb of listeners) {
+          try {
+            cb();
+          } catch {
+            // notification handler errors must not break the release path
+          }
+        }
+      }
+    },
+    onExpireNotify(leaseId, callback) {
+      const existing = expireListeners.get(leaseId);
+      if (existing === undefined) {
+        expireListeners.set(leaseId, [callback]);
+      } else {
+        existing.push(callback);
+      }
+    },
+    list() {
+      const cutoff = now();
+      const out: GalleryLease[] = [];
+      for (const entry of active.values()) {
+        if (entry.expiresAt > cutoff) out.push({ ...entry });
+      }
+      return out;
+    },
+    clear() {
+      for (const handle of timers.values()) clearTimeout(handle);
+      timers.clear();
+      active.clear();
+      expireListeners.clear();
+    },
+  };
+}

package/src/service/security/token-store.ts

@@ -0,0 +1,138 @@
+/**
+ * Token store.
+ *
+ * Two distinct files, two distinct lifecycles:
+ *
+ *   - INSTALL token (long-lived, auto-generated, mode 0600). Created on
+ *     first service start. Used by the CLI to authenticate to the
+ *     loopback service. Rotate() generates a new value and persists it
+ *     — this is what enables "reconnect with rotated auth" without
+ *     invalidating open connections: clients always re-read on
+ *     reconnect.
+ *
+ *   - OPERATOR PROMOTE token (NOT provisioned here). Absent → promote
+ *     fails typed. Provisioning the operator token is an out-of-band
+ *     action; this module simply refuses to fabricate one.
+ */
+
+import { chmodSync, existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import { ensureOwnerOnlyDirectory } from "../../shared/util/dir-permissions";
+
+export interface InstallTokenStoreOptions {
+  readonly tokenPath: string;
+  /** Test seam for forcing the losing first-write path without timing races. */
+  readonly beforeFirstWrite?: () => void;
+}
+
+export interface InstallTokenStore {
+  read(): string;
+  rotate(): string;
+}
+
+export interface PromoteTokenStoreOptions {
+  readonly tokenPath: string;
+}
+
+export interface PromoteTokenStore {
+  exists(): boolean;
+  read(): string | null;
+}
+
+export function generateInstallToken(): string {
+  // 32 random bytes → 64 hex chars. URL-safe and constant-time friendly.
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+function ensureTightPermissions(path: string): void {
+  try {
+    chmodSync(path, 0o600);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}
+
+export function recoverInstallTokenAfterWriteFailure(path: string, error: unknown): string {
+  if (existsSync(path)) {
+    const value = readFileSync(path, "utf8").trim();
+    if (value.length > 0) {
+      ensureTightPermissions(path);
+      return value;
+    }
+  }
+  throw error;
+}
+
+export function createInstallTokenStore(options: InstallTokenStoreOptions): InstallTokenStore {
+  let cached: string | null = null;
+
+  function loadFromDisk(): string {
+    let emptyRecoveryPath: string | null = null;
+    if (existsSync(options.tokenPath)) {
+      const value = readFileSync(options.tokenPath, "utf8").trim();
+      if (value.length > 0) {
+        ensureTightPermissions(options.tokenPath);
+        return value;
+      }
+      emptyRecoveryPath = `${options.tokenPath}.empty-${crypto.randomUUID()}`;
+      try {
+        renameSync(options.tokenPath, emptyRecoveryPath);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") return loadFromDisk();
+        throw error;
+      }
+    }
+    // Atomic first-write: O_EXCL ensures exactly one writer wins the
+    // race. Losers (EEXIST) re-read what the winner persisted — they
+    // never cache a different token than the one on disk. The
+    // containing directory lands at mode 0700 via the shared helper so
+    // a hostile umask cannot widen the secret-bearing layout.
+    ensureOwnerOnlyDirectory(dirname(options.tokenPath));
+    const fresh = generateInstallToken();
+    try {
+      options.beforeFirstWrite?.();
+      writeFileSync(options.tokenPath, fresh, {
+        mode: 0o600,
+        flag: "wx",
+      });
+      ensureTightPermissions(options.tokenPath);
+      return fresh;
+    } catch (error) {
+      return recoverInstallTokenAfterWriteFailure(options.tokenPath, error);
+    } finally {
+      if (emptyRecoveryPath !== null) rmSync(emptyRecoveryPath, { force: true });
+    }
+  }
+
+  return {
+    read() {
+      if (cached === null) cached = loadFromDisk();
+      else ensureTightPermissions(options.tokenPath);
+      return cached;
+    },
+    rotate() {
+      const fresh = generateInstallToken();
+      ensureOwnerOnlyDirectory(dirname(options.tokenPath));
+      writeFileSync(options.tokenPath, fresh, { mode: 0o600 });
+      ensureTightPermissions(options.tokenPath);
+      cached = fresh;
+      return fresh;
+    },
+  };
+}
+
+export function createPromoteTokenStore(options: PromoteTokenStoreOptions): PromoteTokenStore {
+  return {
+    exists() {
+      return existsSync(options.tokenPath);
+    },
+    read() {
+      if (!existsSync(options.tokenPath)) return null;
+      const value = readFileSync(options.tokenPath, "utf8").trim();
+      return value.length > 0 ? value : null;
+    },
+  };
+}