@zhin.js/host-http 1.1.17 → 1.2.1

package/lib/token-registry.js

@@ -1,4 +1,7 @@
+import { CONSOLE_PERMISSION_LIST, pluginPermissionLevelResolver, } from '@zhin.js/console-protocol';
 import { timingSafeEqualString } from './timing-safe-equal.js';
+import { isLoopbackAddress } from './protocol-auth.js';
+import { globalPermissions, } from './access-control.js';
 export const publicConsoleAccess = Object.freeze({
     unrestricted: false,
     permissions: Object.freeze([]),
@@ -9,154 +12,158 @@ export const unrestrictedConsoleAccess = Object.freeze({
     permissions: Object.freeze([]),
     roles: Object.freeze([]),
 });
+const openBootstrap = Object.freeze({ kind: 'bootstrap', open: true });
+const tokenBootstrap = 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 {
-    #entries = new Map();
+    #primaryToken;
+    #provider;
+    #pluginPermissions;
     constructor(config = {}) {
-        if (config.primaryToken) {
-            this.#entries.set(config.primaryToken, Object.freeze({ scope: 'full', permissions: [], roles: [], dynamic: false }));
+        this.#primaryToken = config.primaryToken || undefined;
+    }
+    /** Installs the user/session backend; returns an idempotent uninstaller. */
+    useAccessProvider(provider) {
+        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() {
+        return this.#provider;
+    }
+    /**
+     * Installs the plugin permission catalog source (the runtime composition root reads it from
+     * the current generation); returns an idempotent uninstaller.
+     */
+    usePluginPermissions(source) {
+        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() {
+        try {
+            return this.#pluginPermissions?.() ?? [];
         }
-        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 = 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);
+        catch {
+            return [];
         }
     }
-    resolve(token) {
-        if (!token)
+    /** Declared-or-inferred level lookup over {@link pluginPermissions}. */
+    pluginPermissionLevels() {
+        return pluginPermissionLevelResolver(this.pluginPermissions());
+    }
+    /** An enabled global owner exists. */
+    initialized() {
+        return this.#provider?.initialized() === true;
+    }
+    /** Whether `/api` requires a credential (a bootstrap token is configured, or setup is done). */
+    hasAnyToken() {
+        return this.#primaryToken !== undefined || this.initialized();
+    }
+    /** Whether `token` is the bootstrap token and still accepted (setup not done). */
+    isBootstrapToken(token) {
+        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, meta = {}) {
+        // 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;
-        for (const [known, binding] of this.#entries) {
-            if (!timingSafeEqualString(known, token))
-                continue;
-            if (this.#expired(known, binding))
-                return null;
-            return binding.scope;
+        try {
+            return await this.#provider.authenticate(token, meta);
         }
-        return null;
-    }
-    resolvePrincipal(token) {
-        if (!token)
+        catch {
             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;
     }
     /**
-     * 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.
+     * 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.
      */
-    resolveAccess(token) {
-        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 });
-        }
-        return publicConsoleAccess;
+    async authorizeBearer(token, permission, meta = {}) {
+        if (!token || !this.hasAnyToken())
+            return false;
+        return this.authorizePrincipal(await this.authenticate(token, meta), permission);
     }
-    hasAnyToken() {
-        for (const [token, binding] of this.#entries) {
-            if (!this.#expired(token, binding))
-                return true;
-        }
-        return false;
+    /**
+     * {@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, permission) {
+        if (!principal)
+            return false;
+        if (principal.kind === 'bootstrap')
+            return !principal.open;
+        return principal.grants.some(grant => grant.scope.kind === 'global' && grant.permissions.includes(permission));
     }
-    /** Registers a runtime-issued credential and returns an idempotent revoker. */
-    register(config) {
-        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');
-        }
-        const candidate = 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,
+    /**
+     * 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) {
+        // An open Host has no explicit credential: routes that demand one keep refusing it.
+        return this.isBootstrapToken(token) ? 'full' : null;
+    }
+    /** Console access for a resolved principal. */
+    accessFor(principal) {
+        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()),
         });
-        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) {
-        const binding = this.#entries.get(token);
-        return binding?.dynamic === true && this.#entries.delete(token);
+    /** Synchronous legacy access: only an open Host is unrestricted. */
+    resolveAccess(_token) {
+        return this.hasAnyToken() ? publicConsoleAccess : unrestrictedConsoleAccess;
     }
     primaryTokenPrefixForLog() {
-        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) : '';
-    }
-    #expired(token, binding) {
-        if (binding.expiresAt === undefined || binding.expiresAt > Date.now())
-            return false;
-        if (binding.dynamic)
-            this.#entries.delete(token);
-        return true;
+        if (this.initialized())
+            return '(users)';
+        return this.#primaryToken ? `${this.#primaryToken.slice(0, 6)}…` : '';
     }
 }
-function accessList(value, label) {
-    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`);
-    }
-    return Object.freeze([...new Set(value)].sort());
-}
-/** WebSocket upgrade paths allowed for demo scope. */
-export function isDemoWebSocketPath(pathname) {
-    return pathname === '/sandbox';
-}
 export function extractBearerToken(authorization, queryToken) {
     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) {
+    if (meta.forwarded)
+        return false;
+    if (meta.ip === undefined)
+        return meta.inProcess === true;
+    return isLoopbackAddress(meta.ip);
+}

package/lib/trust-proxy.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `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;
+export declare class TrustProxyConfigError extends Error {
+    constructor(message: string);
+}
+/** Validates a raw config value; `undefined` / `false` → undefined (feature off). */
+export declare function parseTrustProxy(value: unknown): TrustProxySetting | undefined;
+/** Predicate for a setting; undefined means no hop is trusted. */
+export declare function compileTrustProxy(setting: TrustProxySetting | undefined): TrustProxyPredicate | undefined;
+/** True when the request carries any proxy forwarding header. */
+export declare function hasForwardingHeaders(headers: Headers | Readonly<Record<string, unknown>>): boolean;
+/**
+ * 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 declare function resolveClientAddress(peer: string | undefined, headers: Headers | Readonly<Record<string, unknown>>, trust: TrustProxyPredicate | undefined): string | undefined;

package/lib/trust-proxy.js

@@ -0,0 +1,168 @@
+/**
+ * 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';
+const ALIASES = 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) {
+        super(`http.trustProxy: ${message}`);
+        this.name = 'TrustProxyConfigError';
+    }
+}
+/** Validates a raw config value; `undefined` / `false` → undefined (feature off). */
+export function parseTrustProxy(value) {
+    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) {
+    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) {
+    const get = (name) => 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, headers, trust) {
+    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) {
+    const read = (name) => {
+        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 = [];
+    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) {
+    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) {
+    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) {
+    const lower = address.trim().toLowerCase();
+    const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/u.exec(lower);
+    return mapped ? mapped[1] : lower;
+}
+function parseAddress(address) {
+    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) {
+    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('::');
+    const headParts = head ? head.split(':') : [];
+    const tailParts = tail ? tail.split(':') : [];
+    const missing = tail === undefined ? 0 : 8 - headParts.length - tailParts.length;
+    const groups = [...headParts, ...Array(missing).fill('0'), ...tailParts];
+    return groups.reduce((sum, group) => (sum << 16n) + BigInt(parseInt(group || '0', 16)), 0n);
+}
+function compileEntry(entry) {
+    const alias = ALIASES[entry.toLowerCase()];
+    if (alias)
+        return alias.flatMap(compileEntry);
+    const [ip, prefixText] = entry.split('/');
+    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];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/host-http",
-  "version": "1.1.17",
+  "version": "1.2.1",
   "description": "Minimal HTTP and WebSocket host for Plugin Runtime (no Koa)",
   "type": "module",
   "main": "./lib/index.js",
@@ -9,6 +9,14 @@
     ".": {
       "types": "./lib/index.d.ts",
       "import": "./lib/index.js"
+    },
+    "./node": {
+      "types": "./lib/node/index.d.ts",
+      "import": "./lib/node/index.js"
+    },
+    "./bridge": {
+      "types": "./lib/bridge/index.d.ts",
+      "import": "./lib/bridge/index.js"
     }
   },
   "files": [
@@ -17,11 +25,11 @@
   ],
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/console-protocol": "1.1.14",
-    "@zhin.js/host-http-contract": "1.1.1",
-    "@zhin.js/logger": "1.1.2",
-    "@zhin.js/schedule": "1.1.4",
-    "@zhin.js/plugin-runtime": "1.1.23"
+    "@zhin.js/console-protocol": "1.2.1",
+    "@zhin.js/host-http-contract": "1.2.0",
+    "@zhin.js/logger": "1.1.3",
+    "@zhin.js/schedule": "1.1.5",
+    "@zhin.js/plugin-runtime": "1.2.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",