@zhin.js/host-http 1.1.17 → 1.2.0

package/src/token-registry.ts

@@ -1,29 +1,27 @@
+import {
+  CONSOLE_PERMISSION_LIST,
+  pluginPermissionLevelResolver,
+  type ConsolePluginPermissionInfo,
+  type ConsolePluginPermissionLevelResolver,
+} from '@zhin.js/console-protocol';
 import { timingSafeEqualString } from './timing-safe-equal.js';
+import { isLoopbackAddress } from './protocol-auth.js';
+import {
+  globalPermissions,
+  type ConsoleAccessProvider,
+  type ConsolePrincipal,
+  type ConsoleRequestMeta,
+} from './access-control.js';
 
-/** Demo Host token scope (ADR 0016 subset for Plugin Runtime Host). */
-export type AuthScope = 'full' | 'demo';
-
-export type ScopedTokenConfig = {
-  readonly token: string;
-  /**
-   * `full` is the operator. `user` is an alias of `demo`: an ordinary Console user who sees and
-   * calls only what its `permissions` / `roles` allow. Stored and reported as `demo`.
-   */
-  readonly scope: AuthScope | 'user';
-  /** Root-configured subject binding; never accepted from an HTTP payload. */
-  readonly principalId?: string;
-  /**
-   * Console permissions held by this token (matched against Page `requiredPermissions`).
-   * Ignored for `full` scope, which already holds every Console permission.
-   */
-  readonly permissions?: readonly string[];
-  /** Console roles held by this token (matched against Page `requiredRoles`). */
-  readonly roles?: readonly string[];
-};
+/**
+ * Scope a Host handler runs with. Every admitted request is `full`: authorization happens
+ * before dispatch against the request's `ConsolePrincipal` (ADR 0049).
+ */
+export type AuthScope = 'full';
 
 /**
- * What a Console caller may see. `unrestricted` is the operator (full scope, or a Host with no
- * tokens configured); otherwise only the listed permissions and roles count.
+ * What a Console caller may see. `unrestricted` is an open Host before setup; otherwise only
+ * the listed permissions and roles count.
  */
 export interface ConsoleAccess {
   readonly unrestricted: boolean;
@@ -49,160 +47,152 @@ export interface AuthenticatedTokenPrincipal {
 }
 
 export type TokenRegistryConfig = {
+  /** `http.token`: the bootstrap credential, valid only until the first owner exists. */
   readonly primaryToken?: string;
-  readonly scopedTokens?: readonly ScopedTokenConfig[];
-};
-
-export type DynamicTokenConfig = ScopedTokenConfig & {
-  /** Unix epoch milliseconds; omitted credentials remain valid until explicitly revoked. */
-  readonly expiresAt?: number;
 };
 
-type TokenBinding = Readonly<{
-  scope: AuthScope;
-  principalId?: string;
-  permissions: readonly string[];
-  roles: readonly string[];
-  expiresAt?: number;
-  dynamic: boolean;
-}>;
+const openBootstrap: ConsolePrincipal = Object.freeze({ kind: 'bootstrap', open: true });
+const tokenBootstrap: ConsolePrincipal = Object.freeze({ kind: 'bootstrap', open: false });
 
+/**
+ * Bearer authentication for the Host (ADR 0049).
+ * - Before setup: no credential configured → open; `http.token` → bootstrap (setup only).
+ * - After setup (an enabled global owner exists): only user sessions and API tokens from the
+ *   {@link ConsoleAccessProvider}; `http.token` is rejected everywhere.
+ */
 export class TokenRegistry {
-  readonly #entries = new Map<string, TokenBinding>();
+  readonly #primaryToken: string | undefined;
+  #provider: ConsoleAccessProvider | undefined;
+  #pluginPermissions: (() => readonly ConsolePluginPermissionInfo[]) | undefined;
 
   constructor(config: TokenRegistryConfig = {}) {
-    if (config.primaryToken) {
-      this.#entries.set(config.primaryToken, Object.freeze({ scope: 'full', permissions: [], roles: [], dynamic: false }));
-    }
-    for (const { token, scope, principalId, permissions, roles } of config.scopedTokens ?? []) {
-      if (!token) continue;
-      if (principalId !== undefined && (!principalId.trim() || principalId !== principalId.trim())) {
-        throw new Error('HTTP token principalId is invalid');
-      }
-      const candidate: TokenBinding = Object.freeze({
-        scope: scope === 'full' ? 'full' : 'demo',
-        ...(principalId === undefined ? {} : { principalId }),
-        permissions: accessList(permissions, 'permissions'),
-        roles: accessList(roles, 'roles'),
-        dynamic: false,
-      });
-      const existing = this.#entries.get(token);
-      if (existing && (existing.scope !== candidate.scope || existing.principalId !== candidate.principalId
-        || existing.permissions.join('\n') !== candidate.permissions.join('\n')
-        || existing.roles.join('\n') !== candidate.roles.join('\n'))) {
-        throw new Error('HTTP token has conflicting authority bindings');
-      }
-      this.#entries.set(token, candidate);
-    }
+    this.#primaryToken = config.primaryToken || undefined;
   }
 
-  resolve(token: string): AuthScope | null {
-    if (!token) return null;
-    for (const [known, binding] of this.#entries) {
-      if (!timingSafeEqualString(known, token)) continue;
-      if (this.#expired(known, binding)) return null;
-      return binding.scope;
-    }
-    return null;
-  }
-
-  resolvePrincipal(token: string): AuthenticatedTokenPrincipal | null {
-    if (!token) return null;
-    for (const [known, binding] of this.#entries) {
-      if (timingSafeEqualString(known, token)) {
-        if (this.#expired(known, binding)) return null;
-        return binding.principalId
-          ? Object.freeze({ principalId: binding.principalId, scope: binding.scope })
-          : null;
-      }
-    }
-    return null;
+  /** Installs the user/session backend; returns an idempotent uninstaller. */
+  useAccessProvider(provider: ConsoleAccessProvider): () => void {
+    if (this.#provider && this.#provider !== provider) throw new Error('Console access provider is already installed');
+    this.#provider = provider;
+    return () => {
+      if (this.#provider === provider) this.#provider = undefined;
+    };
+  }
+
+  get accessProvider(): ConsoleAccessProvider | undefined {
+    return this.#provider;
   }
 
   /**
-   * Console access for a bearer token. With no tokens configured the Host is local and open,
-   * so every caller is the operator. An unknown or missing token gets public access only.
+   * Installs the plugin permission catalog source (the runtime composition root reads it from
+   * the current generation); returns an idempotent uninstaller.
    */
-  resolveAccess(token: string): ConsoleAccess {
-    if (!this.hasAnyToken()) return unrestrictedConsoleAccess;
-    if (!token) return publicConsoleAccess;
-    for (const [known, binding] of this.#entries) {
-      if (!timingSafeEqualString(known, token)) continue;
-      if (this.#expired(known, binding)) return publicConsoleAccess;
-      if (binding.scope === 'full') return unrestrictedConsoleAccess;
-      return Object.freeze({ unrestricted: false, permissions: binding.permissions, roles: binding.roles });
+  usePluginPermissions(source: () => readonly ConsolePluginPermissionInfo[]): () => void {
+    if (this.#pluginPermissions && this.#pluginPermissions !== source) throw new Error('Plugin permission catalog is already installed');
+    this.#pluginPermissions = source;
+    return () => {
+      if (this.#pluginPermissions === source) this.#pluginPermissions = undefined;
+    };
+  }
+
+  /** Plugin permissions the loaded plugins use or declare, with their levels (empty when none). */
+  pluginPermissions(): readonly ConsolePluginPermissionInfo[] {
+    try {
+      return this.#pluginPermissions?.() ?? [];
+    } catch {
+      return [];
     }
-    return publicConsoleAccess;
   }
 
+  /** Declared-or-inferred level lookup over {@link pluginPermissions}. */
+  pluginPermissionLevels(): ConsolePluginPermissionLevelResolver {
+    return pluginPermissionLevelResolver(this.pluginPermissions());
+  }
+
+  /** An enabled global owner exists. */
+  initialized(): boolean {
+    return this.#provider?.initialized() === true;
+  }
+
+  /** Whether `/api` requires a credential (a bootstrap token is configured, or setup is done). */
   hasAnyToken(): boolean {
-    for (const [token, binding] of this.#entries) {
-      if (!this.#expired(token, binding)) return true;
-    }
-    return false;
+    return this.#primaryToken !== undefined || this.initialized();
   }
 
-  /** Registers a runtime-issued credential and returns an idempotent revoker. */
-  register(config: DynamicTokenConfig): () => void {
-    if (!config.token) throw new Error('Dynamic HTTP token is required');
-    if (config.principalId !== undefined
-      && (!config.principalId.trim() || config.principalId !== config.principalId.trim())) {
-      throw new Error('Dynamic HTTP token principalId is invalid');
-    }
-    if (config.expiresAt !== undefined
-      && (!Number.isSafeInteger(config.expiresAt) || config.expiresAt <= Date.now())) {
-      throw new Error('Dynamic HTTP token expiresAt must be a future epoch millisecond');
+  /** Whether `token` is the bootstrap token and still accepted (setup not done). */
+  isBootstrapToken(token: string): boolean {
+    return !this.initialized() && this.#primaryToken !== undefined && !!token
+      && timingSafeEqualString(this.#primaryToken, token);
+  }
+
+  /** Resolves a bearer to a principal; null when it is not (or no longer) valid. */
+  async authenticate(token: string, meta: ConsoleRequestMeta = {}): Promise<ConsolePrincipal | null> {
+    // An open Host (no bootstrap token, no owner) holds every permission, so it is only open to
+    // loopback peers that did not come through a proxy, and to callers that explicitly mark
+    // themselves in-process (tests, embedding). An unknown peer address is not local.
+    if (!this.hasAnyToken()) return isOpenHostPeer(meta) ? openBootstrap : null;
+    if (this.isBootstrapToken(token)) return tokenBootstrap;
+    if (!token || !this.#provider) return null;
+    try {
+      return await this.#provider.authenticate(token, meta);
+    } catch {
+      return null;
     }
-    const candidate: TokenBinding = Object.freeze({
-      scope: config.scope === 'full' ? 'full' : 'demo',
-      ...(config.principalId === undefined ? {} : { principalId: config.principalId }),
-      permissions: accessList(config.permissions, 'permissions'),
-      roles: accessList(config.roles, 'roles'),
-      ...(config.expiresAt === undefined ? {} : { expiresAt: config.expiresAt }),
-      dynamic: true,
-    });
-    const existing = this.#entries.get(config.token);
-    if (existing) throw new Error('Dynamic HTTP token conflicts with an existing credential');
-    this.#entries.set(config.token, candidate);
-    let active = true;
-    return () => {
-      if (!active) return;
-      active = false;
-      if (this.#entries.get(config.token) === candidate) this.#entries.delete(config.token);
-    };
   }
 
-  revoke(token: string): boolean {
-    const binding = this.#entries.get(token);
-    return binding?.dynamic === true && this.#entries.delete(token);
+  /**
+   * Bearer check for non-Console protocol surfaces (MCP, A2A): the bootstrap token before
+   * setup, or a user credential holding `permission` globally. An open Host yields false so
+   * the surface keeps its own unauthenticated (loopback) policy.
+   */
+  async authorizeBearer(token: string, permission: string, meta: ConsoleRequestMeta = {}): Promise<boolean> {
+    if (!token || !this.hasAnyToken()) return false;
+    return this.authorizePrincipal(await this.authenticate(token, meta), permission);
   }
 
-  primaryTokenPrefixForLog(): string {
-    for (const [tok, binding] of this.#entries) {
-      if (binding.scope === 'full') return tok.slice(0, 6);
-    }
-    const first = this.#entries.keys().next().value;
-    return first ? first.slice(0, 6) : '';
+  /**
+   * {@link authorizeBearer} for a principal already resolved from the request's bearer (by this
+   * registry, or by the gateway that forwarded the request): the bootstrap token before setup,
+   * or a user credential holding `permission` globally. An open Host yields false.
+   */
+  authorizePrincipal(principal: ConsolePrincipal | null | undefined, permission: string): boolean {
+    if (!principal) return false;
+    if (principal.kind === 'bootstrap') return !principal.open;
+    return principal.grants.some(grant => grant.scope.kind === 'global' && grant.permissions.includes(permission));
   }
 
-  #expired(token: string, binding: TokenBinding): boolean {
-    if (binding.expiresAt === undefined || binding.expiresAt > Date.now()) return false;
-    if (binding.dynamic) this.#entries.delete(token);
-    return true;
+  /**
+   * Synchronous explicit-credential check: `full` only for the still-valid bootstrap token.
+   * User credentials need {@link authenticate} (or the request's bound principal).
+   */
+  resolve(token: string): AuthScope | null {
+    // An open Host has no explicit credential: routes that demand one keep refusing it.
+    return this.isBootstrapToken(token) ? 'full' : null;
   }
-}
 
-function accessList(value: readonly string[] | undefined, label: string): readonly string[] {
-  if (value === undefined) return Object.freeze([]);
-  if (!Array.isArray(value) || !value.every((item) => typeof item === 'string' && item.length > 0 && item.trim() === item)) {
-    throw new Error(`HTTP token ${label} must be non-empty trimmed strings`);
+  /** Console access for a resolved principal. */
+  accessFor(principal: ConsolePrincipal | null | undefined): ConsoleAccess {
+    if (!principal) return publicConsoleAccess;
+    if (principal.kind === 'bootstrap') return principal.open ? unrestrictedConsoleAccess : publicConsoleAccess;
+    // A global owner sees every page, including plugin pages whose permissions no plugin reports.
+    // An owner API token narrowed below the full catalog is not unrestricted.
+    if (principal.grants.some(grant => grant.role === 'owner' && grant.scope.kind === 'global'
+      && CONSOLE_PERMISSION_LIST.every(permission => grant.permissions.includes(permission)))) return unrestrictedConsoleAccess;
+    return Object.freeze({
+      unrestricted: false,
+      permissions: globalPermissions(principal, this.pluginPermissions()),
+      roles: Object.freeze([...principal.roles].sort()),
+    });
   }
-  return Object.freeze([...new Set(value)].sort());
-}
 
-/** WebSocket upgrade paths allowed for demo scope. */
-export function isDemoWebSocketPath(pathname: string): boolean {
-  return pathname === '/sandbox';
+  /** Synchronous legacy access: only an open Host is unrestricted. */
+  resolveAccess(_token: string): ConsoleAccess {
+    return this.hasAnyToken() ? publicConsoleAccess : unrestrictedConsoleAccess;
+  }
+
+  primaryTokenPrefixForLog(): string {
+    if (this.initialized()) return '(users)';
+    return this.#primaryToken ? `${this.#primaryToken.slice(0, 6)}…` : '';
+  }
 }
 
 export function extractBearerToken(
@@ -212,3 +202,10 @@ export function extractBearerToken(
   if (authorization?.startsWith('Bearer ')) return authorization.slice(7).trim();
   return queryToken?.trim() ?? '';
 }
+
+/** Who may use an open Host: no proxy hop, and a loopback peer or an explicit in-process caller. */
+function isOpenHostPeer(meta: ConsoleRequestMeta): boolean {
+  if (meta.forwarded) return false;
+  if (meta.ip === undefined) return meta.inProcess === true;
+  return isLoopbackAddress(meta.ip);
+}

package/src/trust-proxy.ts

@@ -0,0 +1,178 @@
+/**
+ * Client address behind reverse proxies (`http.trustProxy`). Without it every request is
+ * attributed to its TCP peer and forwarding headers are ignored, so a client can never spoof its
+ * address. With it, `X-Forwarded-For` (or RFC 7239 `Forwarded`) is walked from the peer towards
+ * the client while each hop is trusted.
+ */
+import { isIP } from 'node:net';
+
+/**
+ * `true` trusts every hop; a number trusts that many hops next to the server; a list trusts
+ * peers matching an IP or CIDR (`10.0.0.0/8`, `::1`, `fd00::/8`) and the aliases `loopback`,
+ * `private` (RFC 1918 / ULA) and `linklocal`.
+ */
+export type TrustProxySetting = boolean | number | readonly string[];
+
+/** Decides whether a hop is a trusted proxy; `index` 0 is the TCP peer. */
+export type TrustProxyPredicate = (address: string, index: number) => boolean;
+
+const ALIASES: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  loopback: ['127.0.0.0/8', '::1/128'],
+  private: ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16', 'fc00::/7'],
+  linklocal: ['169.254.0.0/16', 'fe80::/10'],
+});
+
+export class TrustProxyConfigError extends Error {
+  constructor(message: string) {
+    super(`http.trustProxy: ${message}`);
+    this.name = 'TrustProxyConfigError';
+  }
+}
+
+/** Validates a raw config value; `undefined` / `false` → undefined (feature off). */
+export function parseTrustProxy(value: unknown): TrustProxySetting | undefined {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (typeof value === 'string') {
+    // Environment placeholders expand to strings: "true", "2", "10.0.0.0/8, ::1".
+    const text = value.trim().toLowerCase();
+    if (text === '' || text === 'false') return undefined;
+    if (text === 'true') return true;
+    if (/^\d+$/u.test(text)) return parseTrustProxy(Number(text));
+  }
+  if (value === true) return true;
+  if (typeof value === 'number') {
+    if (!Number.isSafeInteger(value) || value < 0 || value > 32) throw new TrustProxyConfigError('hop count must be an integer 0–32');
+    return value === 0 ? undefined : value;
+  }
+  const list = typeof value === 'string' ? value.split(',') : value;
+  if (!Array.isArray(list)) throw new TrustProxyConfigError('must be true, a hop count, or a list of proxy IPs / CIDRs');
+  const entries = list.map(entry => String(entry).trim()).filter(Boolean);
+  for (const entry of entries) compileEntry(entry);
+  return entries.length === 0 ? undefined : Object.freeze(entries);
+}
+
+/** Predicate for a setting; undefined means no hop is trusted. */
+export function compileTrustProxy(setting: TrustProxySetting | undefined): TrustProxyPredicate | undefined {
+  if (setting === undefined || setting === false) return undefined;
+  if (setting === true) return () => true;
+  if (typeof setting === 'number') return (_address, index) => index < setting;
+  const matchers = setting.flatMap(entry => compileEntry(entry));
+  return (address) => {
+    const parsed = parseAddress(address);
+    return parsed !== undefined && matchers.some(matcher => matcher(parsed));
+  };
+}
+
+/** True when the request carries any proxy forwarding header. */
+export function hasForwardingHeaders(headers: Headers | Readonly<Record<string, unknown>>): boolean {
+  const get = (name: string): unknown => headers instanceof Headers ? headers.get(name) : headers[name];
+  return get('x-forwarded-for') != null || get('forwarded') != null;
+}
+
+/**
+ * Client address for one request. Returns the peer unchanged unless the peer is trusted; then
+ * walks the forwarded chain right to left and returns the first untrusted hop (or the leftmost).
+ */
+export function resolveClientAddress(
+  peer: string | undefined,
+  headers: Headers | Readonly<Record<string, unknown>>,
+  trust: TrustProxyPredicate | undefined,
+): string | undefined {
+  if (!peer || !trust) return peer;
+  const chain = forwardedChain(headers);
+  if (chain === undefined) return peer;
+  const hops = [normalizeAddress(peer), ...chain.reverse()];
+  let index = 0;
+  while (index < hops.length - 1 && trust(hops[index]!, index)) index += 1;
+  return hops[index];
+}
+
+/** Forwarded addresses, client first; undefined when absent or malformed (fail closed to the peer). */
+function forwardedChain(headers: Headers | Readonly<Record<string, unknown>>): string[] | undefined {
+  const read = (name: string): string | undefined => {
+    const value = headers instanceof Headers ? headers.get(name) : headers[name];
+    if (value == null) return undefined;
+    return Array.isArray(value) ? value.join(',') : String(value);
+  };
+  const xff = read('x-forwarded-for');
+  const raw = xff !== undefined
+    ? xff.split(',').map(part => part.trim())
+    : read('forwarded')?.split(',').map(part => forwardedFor(part));
+  if (!raw || raw.length === 0) return undefined;
+  const chain: string[] = [];
+  for (const entry of raw) {
+    const address = entry === undefined ? undefined : normalizeAddress(stripPort(entry));
+    if (!address || isIP(address) === 0) return undefined;
+    chain.push(address);
+  }
+  return chain;
+}
+
+/** `for=` of one RFC 7239 element; `for="[2001:db8::1]:80"`, `for=192.0.2.1`. */
+function forwardedFor(element: string): string | undefined {
+  for (const pair of element.split(';')) {
+    const [key, ...rest] = pair.split('=');
+    if (key?.trim().toLowerCase() !== 'for') continue;
+    return rest.join('=').trim().replace(/^"|"$/gu, '');
+  }
+  return undefined;
+}
+
+function stripPort(value: string): string {
+  const bracketed = /^\[([^\]]+)\](?::\d+)?$/u.exec(value);
+  if (bracketed) return bracketed[1]!;
+  const v4 = /^(\d{1,3}(?:\.\d{1,3}){3}):\d+$/u.exec(value);
+  return v4 ? v4[1]! : value;
+}
+
+function normalizeAddress(address: string): string {
+  const lower = address.trim().toLowerCase();
+  const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/u.exec(lower);
+  return mapped ? mapped[1]! : lower;
+}
+
+interface ParsedAddress {
+  readonly family: 4 | 6;
+  readonly value: bigint;
+}
+
+function parseAddress(address: string): ParsedAddress | undefined {
+  const normalized = normalizeAddress(address);
+  const family = isIP(normalized);
+  if (family === 4) {
+    return { family: 4, value: normalized.split('.').reduce((sum, part) => (sum << 8n) + BigInt(Number(part)), 0n) };
+  }
+  if (family === 6) return { family: 6, value: ipv6ToBigInt(normalized) };
+  return undefined;
+}
+
+function ipv6ToBigInt(address: string): bigint {
+  let text = address.split('%')[0]!;
+  const v4Tail = /(\d{1,3}(?:\.\d{1,3}){3})$/u.exec(text);
+  if (v4Tail) {
+    const parts = v4Tail[1]!.split('.').map(Number);
+    text = `${text.slice(0, -v4Tail[1]!.length)}${((parts[0]! << 8) | parts[1]!).toString(16)}:${((parts[2]! << 8) | parts[3]!).toString(16)}`;
+  }
+  const [head, tail] = text.split('::') as [string, string | undefined];
+  const headParts = head ? head.split(':') : [];
+  const tailParts = tail ? tail.split(':') : [];
+  const missing = tail === undefined ? 0 : 8 - headParts.length - tailParts.length;
+  const groups = [...headParts, ...Array<string>(missing).fill('0'), ...tailParts];
+  return groups.reduce((sum, group) => (sum << 16n) + BigInt(parseInt(group || '0', 16)), 0n);
+}
+
+function compileEntry(entry: string): Array<(address: ParsedAddress) => boolean> {
+  const alias = ALIASES[entry.toLowerCase()];
+  if (alias) return alias.flatMap(compileEntry);
+  const [ip, prefixText] = entry.split('/') as [string, string | undefined];
+  const parsed = parseAddress(ip);
+  if (!parsed) throw new TrustProxyConfigError(`"${entry}" is not an IP address, CIDR or alias (loopback, private, linklocal)`);
+  const bits = parsed.family === 4 ? 32 : 128;
+  const prefix = prefixText === undefined ? bits : Number(prefixText);
+  if (!Number.isInteger(prefix) || prefix < 0 || prefix > bits || (prefixText !== undefined && !/^\d+$/u.test(prefixText))) {
+    throw new TrustProxyConfigError(`"${entry}" has an invalid prefix length`);
+  }
+  const shift = BigInt(bits - prefix);
+  const network = parsed.value >> shift;
+  return [(address) => address.family === parsed.family && (address.value >> shift) === network];
+}