reploid 0.0.0-stage → 0.1.1

package/server/search/page-fetch.js

@@ -0,0 +1,185 @@
+/**
+ * @fileoverview Bounded server-side page fetch for cited search results. Only http(s) to public addresses:
+ * every hop's addresses are checked inside the socket's own DNS lookup, so a rebinding answer cannot reach a
+ * private network, and IP-literal hosts are checked before connecting. Redirects are followed manually and
+ * re-checked. Content type is checked before the body is read; raw and decompressed bytes are capped.
+ * PDF is declared unsupported rather than extracted.
+ */
+import dns from 'node:dns';
+import http from 'node:http';
+import https from 'node:https';
+import net from 'node:net';
+import zlib from 'node:zlib';
+import { PageFetchError } from './errors.js';
+import { sha256Digest } from '../hashing.js';
+// The limits device-side extractors share (packages/reploid/src/retrieval/page-fetch.json).
+import policy from '../../packages/reploid/src/retrieval/page-fetch.json' with { type: 'json' };
+
+export const DEFAULT_ALLOWED_TYPES = Object.freeze([...policy.contentTypes]);
+const UNSUPPORTED_TYPES = new Set(policy.unsupportedContentTypes);
+const BLOCKED_LOOKUP = 'EREPLOIDBLOCKEDADDRESS';
+
+const IPV4_BLOCKS = [['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8], ['169.254.0.0', 16], ['172.16.0.0', 12],
+  ['192.0.0.0', 24], ['192.0.2.0', 24], ['192.168.0.0', 16], ['198.18.0.0', 15], ['198.51.100.0', 24], ['203.0.113.0', 24],
+  ['224.0.0.0', 4], ['240.0.0.0', 4]].map(([base, bits]) => [ipv4Number(base), bits]);
+
+function ipv4Number(address) {
+  return address.split('.').reduce((value, part) => value * 256 + Number(part), 0);
+}
+function blockedIpv4(address) {
+  const value = ipv4Number(address);
+  return IPV4_BLOCKS.some(([base, bits]) => Math.floor(value / 2 ** (32 - bits)) === Math.floor(base / 2 ** (32 - bits)));
+}
+
+/** Eight 16-bit groups, with an embedded dotted IPv4 tail expanded. */
+function ipv6Groups(address) {
+  let text = address.toLowerCase().split('%')[0];
+  const dotted = text.match(/(\d+\.\d+\.\d+\.\d+)$/);
+  if (dotted) {
+    const value = ipv4Number(dotted[1]);
+    text = text.slice(0, -dotted[1].length) + `${(value >>> 16).toString(16)}:${(value & 0xffff).toString(16)}`;
+  }
+  const [head, tail] = text.split('::');
+  const left = head ? head.split(':') : [], right = tail ? tail.split(':') : [];
+  const groups = text.includes('::') ? [...left, ...Array(8 - left.length - right.length).fill('0'), ...right] : left;
+  return groups.map(group => parseInt(group, 16));
+}
+
+/** True for loopback, private, link-local, shared, multicast, reserved and documentation addresses. */
+export function isBlockedAddress(address) {
+  const family = net.isIP(String(address || '').split('%')[0]);
+  if (family === 4) return blockedIpv4(address);
+  if (family !== 6) return true;
+  const groups = ipv6Groups(address);
+  if (groups.length !== 8 || groups.some(group => !Number.isInteger(group))) return true;
+  const embedded = () => `${groups[6] >> 8}.${groups[6] & 255}.${groups[7] >> 8}.${groups[7] & 255}`;
+  if (groups.slice(0, 7).every(group => group === 0) && groups[7] <= 1) return true; // :: and ::1
+  if (groups.slice(0, 5).every(group => group === 0) && (groups[5] === 0xffff || groups[5] === 0)) return blockedIpv4(embedded()); // IPv4-mapped/compatible
+  if (groups[0] === 0x64 && groups[1] === 0xff9b && groups.slice(2, 6).every(group => group === 0)) return blockedIpv4(embedded()); // NAT64
+  if ((groups[0] & 0xfe00) === 0xfc00) return true; // fc00::/7 unique local
+  if ((groups[0] & 0xffc0) === 0xfe80) return true; // fe80::/10 link-local
+  if ((groups[0] & 0xff00) === 0xff00) return true; // ff00::/8 multicast
+  if (groups[0] === 0x2001 && groups[1] === 0x0db8) return true; // documentation
+  if (groups[0] === 0x0100 && groups.slice(1, 4).every(group => group === 0)) return true; // discard-only
+  return false;
+}
+
+/** A dns.lookup-compatible function that refuses blocked answers, for the socket to use itself. */
+export function guardedLookup(base = dns.lookup, isBlocked = isBlockedAddress) {
+  return (hostname, options, callback) => {
+    if (typeof options === 'function') { callback = options; options = {}; }
+    const settings = typeof options === 'number' ? { family: options } : options || {};
+    base(hostname, { ...settings, all: true }, (error, addresses) => {
+      if (error) { callback(error); return; }
+      const rows = (Array.isArray(addresses) ? addresses : [{ address: addresses, family: net.isIP(addresses) }]).filter(row => row?.address);
+      if (!rows.length || rows.some(row => isBlocked(row.address))) {
+        callback(Object.assign(new Error(`${hostname} resolves to a blocked address`), { code: BLOCKED_LOOKUP })); return;
+      }
+      if (settings.all) callback(null, rows);
+      else callback(null, rows[0].address, rows[0].family || net.isIP(rows[0].address));
+    });
+  };
+}
+
+const mimeOf = value => String(value || '').split(';')[0].trim().toLowerCase();
+const charsetOf = value => String(value || '').match(/charset\s*=\s*["']?([\w.:-]+)/i)?.[1] || null;
+
+function decoder(encoding) {
+  const name = String(encoding || '').trim().toLowerCase();
+  if (!name || name === 'identity') return null;
+  if (name === 'gzip' || name === 'x-gzip') return zlib.createGunzip();
+  if (name === 'deflate') return zlib.createInflate();
+  if (name === 'br') return zlib.createBrotliDecompress();
+  throw new PageFetchError('fetch-failed', { detail: `Unsupported content encoding ${name}` });
+}
+
+export function createPageFetcher({ maxBytes = policy.maxBytes, timeoutMs = policy.timeoutMs, maxRedirects = policy.maxRedirects,
+  allowedTypes = DEFAULT_ALLOWED_TYPES,
+  lookup = dns.lookup, allowPrivateAddresses = false, isBlocked = isBlockedAddress,
+  userAgent = 'ReploidSourceFetcher/1 (+https://github.com/clocksmith/reploid)' } = {}) {
+  // allowPrivateAddresses is for tests and local development only.
+  const blocked = allowPrivateAddresses ? () => false : isBlocked, resolve = guardedLookup(lookup, blocked);
+  const allowed = new Set(allowedTypes.map(type => type.toLowerCase()));
+
+  function target(value) {
+    let url;
+    try { url = new URL(value); } catch { throw new PageFetchError('invalid-url'); }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.href.length > policy.maxUrlCharacters) throw new PageFetchError('invalid-url');
+    const host = url.hostname.replace(/^\[|\]$/g, '');
+    if (net.isIP(host) && blocked(host)) throw new PageFetchError('blocked-address', { detail: host });
+    return url;
+  }
+
+  /** One request; resolves { response } with the body unread. */
+  function request(url, signal) {
+    return new Promise((done, fail) => {
+      const client = url.protocol === 'https:' ? https : http;
+      const outgoing = client.request(url, { method: 'GET', lookup: resolve, signal, agent: false,
+        headers: { 'User-Agent': userAgent, Accept: 'text/html,application/xhtml+xml,text/plain;q=0.9', 'Accept-Encoding': 'gzip, deflate, br' } });
+      outgoing.on('response', response => done(response));
+      outgoing.on('error', error => fail(error));
+      outgoing.end();
+    });
+  }
+
+  function readBody(response, signal) {
+    return new Promise((done, fail) => {
+      const declared = Number(response.headers['content-length']);
+      if (Number.isFinite(declared) && declared > maxBytes) { response.destroy(); fail(new PageFetchError('too-large', { detail: `${declared} bytes` })); return; }
+      let stream = response, raw = 0, size = 0;
+      const chunks = [];
+      const stop = error => { response.destroy(); stream.destroy?.(); fail(error); };
+      try { const decode = decoder(response.headers['content-encoding']); if (decode) stream = response.pipe(decode); }
+      catch (error) { stop(error); return; }
+      response.on('data', chunk => { raw += chunk.length; if (raw > maxBytes) stop(new PageFetchError('too-large', { detail: 'Transfer exceeds the byte limit' })); });
+      stream.on('data', chunk => {
+        size += chunk.length;
+        if (size > maxBytes) { stop(new PageFetchError('too-large', { detail: 'Decoded body exceeds the byte limit' })); return; }
+        chunks.push(chunk);
+      });
+      stream.on('end', () => done(Buffer.concat(chunks)));
+      stream.on('error', error => fail(signal.aborted ? signal.reason : new PageFetchError('fetch-failed', { detail: error.code || 'decode error' })));
+      response.on('error', error => fail(signal.aborted ? signal.reason : new PageFetchError('fetch-failed', { detail: error.code || 'read error' })));
+      // A connection that closes before the body ends (including on timeout) settles as a failure.
+      stream.on('close', () => { if (!stream.readableEnded) fail(signal.aborted ? signal.reason : new PageFetchError('fetch-failed', { detail: 'connection closed' })); });
+    });
+  }
+
+  async function fetchPage(value, { signal = null } = {}) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new PageFetchError('timeout', { detail: `${timeoutMs} ms` })), timeoutMs);
+    const forward = () => controller.abort(new PageFetchError('cancelled'));
+    if (signal?.aborted) forward(); else signal?.addEventListener('abort', forward, { once: true });
+    try {
+      let url = target(value);
+      for (let hop = 0; ; hop++) {
+        let response;
+        try { response = await request(url, controller.signal); }
+        catch (error) {
+          if (controller.signal.aborted) throw controller.signal.reason;
+          if (error.code === BLOCKED_LOOKUP) throw new PageFetchError('blocked-address', { detail: url.hostname });
+          throw new PageFetchError('fetch-failed', { detail: error.code || error.message });
+        }
+        const status = response.statusCode;
+        if (status >= 300 && status < 400 && response.headers.location) {
+          response.resume();
+          if (hop >= maxRedirects) throw new PageFetchError('too-many-redirects', { status });
+          url = target(new URL(response.headers.location, url).href);
+          continue;
+        }
+        if (status < 200 || status >= 300) { response.resume(); throw new PageFetchError('http-error', { status }); }
+        const contentType = String(response.headers['content-type'] || ''), mime = mimeOf(contentType);
+        if (UNSUPPORTED_TYPES.has(mime)) { response.destroy(); throw new PageFetchError('unsupported-content-type', { status, detail: 'PDF text extraction is not supported' }); }
+        if (!allowed.has(mime)) { response.destroy(); throw new PageFetchError('unsupported-content-type', { status, detail: mime ? `${mime} is not supported` : 'The page has no content type' }); }
+        let body;
+        try { body = await readBody(response, controller.signal); }
+        catch (error) { if (controller.signal.aborted) throw controller.signal.reason; throw error; }
+        return { url: url.href, status, contentType, charset: charsetOf(contentType), bytes: body.length,
+          byteSha256: sha256Digest(body), body };
+      }
+    } finally {
+      clearTimeout(timer); signal?.removeEventListener('abort', forward);
+    }
+  }
+  return Object.freeze({ fetchPage, maxBytes, timeoutMs });
+}

package/server/text-api.js

@@ -0,0 +1,83 @@
+import { availablePartitionRoute, currentPartitionRoute } from '../apps/poolday/host/partition-release.js';
+/** One authenticated HTTP surface over a borrowed requester. Production execution
+ * must be wrapped by the accounting owner; test execution is explicitly unbilled. */
+import { createChatCompletions } from './chat-completions.js';
+import { createResponses } from './responses.js';
+import { createTextRecovery, TEXT_RECOVERY_PATH } from './text-recovery.js';
+import { partitionAdapterIdentities } from '../packages/reploid/src/mesh/partitions/partition-contract.js';
+import policy from '../apps/poolday/config/partition-policy.json' with { type: 'json' };
+
+export const TEXT_API_PATHS = Object.freeze(['/v1/chat/completions', '/v1/responses', '/v1/models', TEXT_RECOVERY_PATH]);
+export function createTextApi({ participant, authenticate, authorize, accounting, production = true, allowUnbilledTest = false }) {
+  if (!participant || typeof authenticate !== 'function' || typeof authorize !== 'function') throw Error('Text API requires requester authentication and authorization');
+  if (typeof accounting?.run !== 'function' && (production || !allowUnbilledTest)) throw Error('Text API requires accounted execution; unbilled tests must be explicit');
+  if (accounting && typeof accounting.run !== 'function') throw Error('Invalid text API accounting port');
+  const assertRoute = request => {
+    if (request.model.partition && !currentPartitionRoute(request.model, participant.getState().models || [])) {
+      throw Object.assign(Error('Selected distributed route is unavailable or not qualified for public use'), { status: 503 });
+    }
+  };
+  const execute = (request, controls) => { assertRoute(request); return participant.generate(request, controls); };
+  const requester = { ...participant,
+    getState() {
+      const state = participant.getState();
+      return { ...state, models: (state.models || []).filter(model => !model.partition || availablePartitionRoute(model)) };
+    },
+    generate(request, controls) {
+      assertRoute(request);
+      return accounting ? accounting.run(request, controls, (nextRequest = request, nextControls = controls) => execute(nextRequest, nextControls))
+        : execute(request, controls);
+    }
+  };
+  const options = { participant: requester, authenticate, authorize };
+  const completions = createChatCompletions(options), responses = createResponses(options);
+  const recovery = createTextRecovery({ participant, authenticate, authorize, accounting });
+  const listing = new Set(); let closed = false;
+  const json = (res, status, body) => { res.writeHead(status, { 'content-type': 'application/json' }); res.end(JSON.stringify(body)); };
+  return Object.freeze({
+    async handle(req, res) {
+      let path;
+      try { path = new URL(req.url || '/', 'http://localhost').pathname; }
+      catch { return json(res, 400, { error: { message: 'Invalid API route' } }); }
+      if (path === '/v1/chat/completions') return completions.handle(req, res);
+      if (path === '/v1/responses') return responses.handle(req, res);
+      if (path === TEXT_RECOVERY_PATH) return recovery.handle(req, res);
+      if (path !== '/v1/models') return json(res, 404, { error: { message: 'Unsupported API route' } });
+      if (closed) return json(res, 503, { error: { message: 'Text API is closed' } });
+      if (listing.size >= policy.inputLimits.maxConcurrentAttempts) return json(res, 429, { error: { message: 'Model listing admission unavailable' } });
+      if (req.method !== 'GET') { res.writeHead(405, { allow: 'GET' }); res.end(); return; }
+      const controller = new AbortController(), { signal } = controller;
+      listing.add(controller);
+      const cancel = () => controller.abort(Error('Model listing disconnected'));
+      const timer = setTimeout(() => controller.abort(Error('Model listing deadline exceeded')), policy.controlChannel.timeoutMs);
+      req.once('aborted', cancel); res.once('close', cancel);
+      try {
+        const principal = await authenticate(req, { signal }); signal.throwIfAborted();
+        if (typeof principal?.subject !== 'string' || !principal.subject || principal.subject.length > 512) return json(res, 401, { error: { message: 'Authentication required' } });
+        if (await authorize({ action: 'models.list', principal: Object.freeze({ subject: principal.subject }), signal }) !== true) {
+          return json(res, 403, { error: { message: 'Model listing denied' } });
+        }
+        signal.throwIfAborted();
+        const rows = (requester.getState().models || []).filter(model => !model.canonical
+          && (model.partition ? availablePartitionRoute(model) : ['ready', 'busy'].includes(model.availability) && model.providerIds?.length));
+        const variants = new Map();
+        for (const model of rows) {
+          const value = { id: model.selectionId || model.id, object: 'model', owned_by: 'reploid',
+            model_identity: model.identity, adapter_identities: partitionAdapterIdentities(model) };
+          if (variants.has(value.id) && JSON.stringify(variants.get(value.id)) !== JSON.stringify(value)) {
+            return json(res, 409, { error: { message: 'Model id has ambiguous execution identity' } });
+          }
+          variants.set(value.id, value);
+        }
+        json(res, 200, { object: 'list', data: [...variants.values()] });
+      } catch (error) {
+        if (!res.destroyed && !res.writableEnded) json(res, 503, { error: { message: error.message } });
+      } finally { clearTimeout(timer); listing.delete(controller); req.removeListener('aborted', cancel); res.removeListener('close', cancel); }
+    },
+    async close() {
+      closed = true;
+      for (const controller of listing) controller.abort(Error('Text API closing'));
+      await Promise.all([completions.close(), responses.close(), recovery.close()]);
+    }
+  });
+}

package/server/text-recovery.js

@@ -0,0 +1,45 @@
+import { createHttpRequestOwner } from './http-request-owner.js';
+/** Authenticated recovery of an existing accepted request; this never generates. */
+import { readBody, fail, object } from './text-requester.js';
+import policy from '../apps/poolday/config/partition-policy.json' with { type: 'json' };
+
+export const TEXT_RECOVERY_PATH = '/v1/reploid/recover';
+export function createTextRecovery({ participant, accounting, authenticate, authorize }) {
+  const requests = createHttpRequestOwner({ timeoutMs: policy.controlChannel.timeoutMs });
+  const json = (res, status, body) => { res.writeHead(status, { 'content-type': 'application/json' }); res.end(JSON.stringify(body)); };
+  return {
+    async handle(req, res) {
+      if (req.method !== 'POST') { res.writeHead(405, { allow: 'POST' }); res.end(); return; }
+      if (requests.closed || typeof accounting?.recover !== 'function' || typeof participant.recoverGeneration !== 'function') {
+        return json(res, 503, { error: { message: 'Request recovery unavailable' } });
+      }
+      if (requests.size >= policy.inputLimits.maxConcurrentAttempts) return json(res, 429, { error: { message: 'Recovery admission unavailable' } });
+      const scope = requests.begin(req, res, {
+        disconnectError: () => Error('Recovery disconnected'), deadlineError: () => Error('Recovery deadline exceeded')
+      });
+      const { signal } = scope;
+      try {
+        if (!/^application\/json(?:;|$)/i.test(req.headers['content-type'] || '')) throw fail(415, 'application/json required');
+        const principal = await authenticate(req, { signal }); signal.throwIfAborted();
+        if (!object(principal) || typeof principal.subject !== 'string' || !principal.subject || principal.subject.length > 512) throw fail(401, 'Authentication required');
+        const input = await readBody(req, signal, body => {
+          if (!object(body) || Object.keys(body).some(key => !['reservationId', 'messages', 'providerId'].includes(key))
+            || typeof body.reservationId !== 'string' || !body.reservationId || body.reservationId.length > 512
+            || !Array.isArray(body.messages) || !body.messages.length) throw fail(400, 'Expected accepted reservationId and original messages');
+          return body;
+        });
+        if (await authorize({ action: 'chat.recover', principal: Object.freeze({ subject: principal.subject }),
+          reservationId: input.reservationId, signal }) !== true) throw fail(403, 'Request recovery denied');
+        signal.throwIfAborted();
+        const result = await accounting.recover(input, { principal: { subject: principal.subject }, signal },
+          (request, reference, controls) => participant.recoverGeneration(request, reference, controls));
+        signal.throwIfAborted(); json(res, 200, result);
+      } catch (error) {
+        if (!res.destroyed && !res.writableEnded) json(res, error.status || 502, { error: { message: error.message } });
+      } finally {
+        scope.finish();
+      }
+    },
+    close: () => requests.close(() => Error('Recovery closed'), () => Error('Recovery cleanup remains unsettled'))
+  };
+}

package/server/text-request-options.js

@@ -0,0 +1,23 @@
+import { fail, object, freeze } from './text-requester.js';
+
+/** Optional private-pool binding; it narrows the host's disclosure authority. */
+export function parseRequesterBinding(value) {
+  if (value === undefined) return undefined;
+  if (!object(value) || Object.keys(value).some(key => !['pool_id', 'expected_model_identity', 'expected_adapter_identities', 'expected_plan_identity', 'allowed_recipients', 'include_execution', 'conversation_id'].includes(key))
+    || typeof value.pool_id !== 'string' || !value.pool_id || value.pool_id.length > 256
+    || typeof value.expected_model_identity !== 'string' || !value.expected_model_identity || value.expected_model_identity.length > 512
+    || value.include_execution !== true || !Array.isArray(value.allowed_recipients) || !value.allowed_recipients.length
+    || value.allowed_recipients.length > 32 || value.allowed_recipients.some(id => typeof id !== 'string' || !id || id.length > 512)
+    || new Set(value.allowed_recipients).size !== value.allowed_recipients.length) {
+    throw fail(400, 'Require exact model identity and permitted recipient identities', 'reploid');
+  }
+  if (value.conversation_id !== undefined && (typeof value.conversation_id !== 'string'
+    || !value.conversation_id || value.conversation_id.length > 128 || !/^[A-Za-z0-9._:-]+$/u.test(value.conversation_id))) {
+    throw fail(400, 'Invalid conversation_id', 'reploid');
+  }
+  if (value.expected_adapter_identities !== undefined && (!Array.isArray(value.expected_adapter_identities)
+    || value.expected_adapter_identities.length > 1 || value.expected_adapter_identities.some(id => !/^sha256:[a-f0-9]{64}$/u.test(id)))) throw fail(400, 'Invalid adapter identities', 'reploid');
+  if (value.expected_plan_identity != null && (typeof value.expected_plan_identity !== 'string' || !value.expected_plan_identity
+    || value.expected_plan_identity.length > 256)) throw fail(400, 'Invalid plan identity', 'reploid');
+  return freeze(structuredClone(value));
+}

package/server/text-requester.js

@@ -0,0 +1,231 @@
+import { createHttpRequestOwner } from './http-request-owner.js';
+import { canonicalPartitionJson, partitionAdapterIdentities } from '../packages/reploid/src/mesh/partitions/partition-contract.js';
+import { requireGenerationCapability, tokenUsage } from '../packages/reploid/src/mesh/partitions/partition-generation-request.js';
+/** Text-only HTTP projection of admitted whole-model and partition routes. No model fallback. */
+import { randomUUID } from 'node:crypto';
+import policy from '../apps/poolday/config/partition-policy.json' with { type: 'json' };
+
+export const fail = (status, message, param = null) => Object.assign(new Error(message), { status, param });
+export const assert = (ok, message) => { if (!ok) throw fail(502, message); };
+export const object = value => value && typeof value === 'object' && !Array.isArray(value);
+export const freeze = value => { if (object(value) || Array.isArray(value)) { for (const item of Object.values(value)) freeze(item); Object.freeze(value); } return value; };
+const json = (res, status, value) => { res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' }); res.end(JSON.stringify(value)); };
+const errorBody = error => ({ error: { message: error.message, type: error.status < 500 ? 'invalid_request_error' : 'server_error',
+  param: error.param || null, code: error.status === 401 ? 'unauthorized' : error.status === 403 ? 'permission_denied'
+    : error.code === 'CONTEXT_LENGTH_EXCEEDED' ? 'context_length_exceeded' : null } });
+// Protocol adapters borrowing the same requester share its HTTP admission budget.
+// Each adapter still owns only its own request cancellation/settlement.
+const requesterAdmission = new WeakMap();
+
+export async function readBody(req, signal, parse) {
+  const chunks = []; let bytes = 0;
+  const aborted = () => req.destroy();
+  signal.addEventListener('abort', aborted, { once: true });
+  try {
+    for await (const chunk of req) {
+      signal.throwIfAborted(); bytes += chunk.length;
+      if (bytes > policy.controlChannel.maxControlBytes) throw fail(413, 'Request body limit exceeded');
+      chunks.push(chunk);
+    }
+    try { return parse(JSON.parse(Buffer.concat(chunks).toString('utf8'))); }
+    catch (error) { if (error.status) throw error; throw fail(400, 'Invalid JSON'); }
+  } finally { signal.removeEventListener('abort', aborted); }
+}
+
+/** Explicit opt-in: the host authenticates callers AND approves each exact disclosure.
+ * The participant and its model/cleanup owners are borrowed, never replaced or closed here.
+ */
+export function createTextRequester({ participant, authenticate, authorize }, protocol) {
+  if (!participant || typeof participant.generate !== 'function' || typeof participant.getState !== 'function'
+    || typeof authenticate !== 'function' || typeof authorize !== 'function') throw Error('Text requester requires an actual requester and explicit authentication/authorization ports');
+  const formatError = protocol.errorBody || errorBody;
+  const requests = createHttpRequestOwner({ timeoutMs: policy.controlChannel.timeoutMs });
+  if (!requesterAdmission.has(participant)) requesterAdmission.set(participant, new Set());
+  const admitted = requesterAdmission.get(participant);
+  const handle = async (req, res) => {
+    let pathname;
+    try { pathname = new URL(req.url || '/', 'http://localhost').pathname; }
+    catch { json(res, 400, formatError(fail(400, 'Invalid API route'))); return; }
+    if (pathname !== protocol.path) {
+      json(res, 404, formatError(fail(404, 'Unsupported API route'))); return;
+    }
+    if (req.method !== 'POST') { res.writeHead(405, { allow: 'POST' }); res.end(); return; }
+    if (requests.closed || admitted.size >= policy.inputLimits.maxConcurrentAttempts) {
+      json(res, requests.closed ? 503 : 429, formatError(fail(requests.closed ? 503 : 429, 'Requester admission unavailable'))); return;
+    }
+    const scope = requests.begin(req, res, {
+      disconnectError: () => Error('HTTP requester disconnected'),
+      deadlineError: () => fail(408, 'Request admission deadline exceeded'),
+      onFinish: item => admitted.delete(item)
+    });
+    const { controller, signal } = scope;
+    admitted.add(scope.item);
+    let streaming = false, emitted = '', sequence = 0, observedUsage = null, disclosureApproved = false, acceptingCallbacks = true;
+    let approvedRecipients = [];
+    const id = protocol.idPrefix + randomUUID().replaceAll('-', ''), created = Math.floor(Date.now() / 1000);
+    let threadId = randomUUID().replaceAll('-', '');
+    const attemptId = randomUUID().replaceAll('-', '');
+    let model, output;
+    const write = data => {
+      signal.throwIfAborted();
+      if (!streaming) {
+        res.writeHead(200, { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache' }); streaming = true;
+      }
+      if (!res.write(data) && res.writableLength > policy.controlChannel.maxBufferedBytes) {
+        controller.abort(Error('HTTP stream output buffer exceeded')); signal.throwIfAborted();
+      }
+    };
+    try {
+      protocol.validateRequest?.(req);
+      if (!/^application\/json(?:;|$)/i.test(req.headers['content-type'] || '')) throw fail(415, 'application/json required');
+      const authenticated = await authenticate(req, { signal }); signal.throwIfAborted();
+      if (!object(authenticated) || typeof authenticated.subject !== 'string' || !authenticated.subject || authenticated.subject.length > 512) throw fail(401, 'Authentication required');
+      const principal = freeze({ subject: authenticated.subject });
+      const input = await readBody(req, signal, protocol.parse); signal.throwIfAborted();
+      if (input.reploid?.conversation_id) threadId = input.reploid.conversation_id;
+      const requirePrivateScope = () => {
+        if (input.reploid && (participant.roomId !== input.reploid.pool_id
+          || !['private-pool', 'local-only'].includes(participant.executionClass))) throw fail(403, 'Requester is not in the permitted private pool');
+      };
+      requirePrivateScope();
+      const models = participant.getState().models || [];
+      let eligible = models.filter(value => (value.selectionId === input.model || value.id === input.model && !partitionAdapterIdentities(value).length) && !value.canonical
+        && (value.partition || ['ready', 'busy'].includes(value.availability) && value.providerIds?.length));
+      if (!eligible.length) throw fail(503, 'No ready route for this exact model variant', 'model');
+      if (input.reploid) {
+        eligible = eligible.filter(value => value.identity === input.reploid.expected_model_identity
+          && (input.reploid.expected_adapter_identities === undefined || canonicalPartitionJson(partitionAdapterIdentities(value)) === canonicalPartitionJson(input.reploid.expected_adapter_identities))
+          && (!input.reploid.expected_plan_identity || value.partition?.planId === input.reploid.expected_plan_identity));
+        if (!eligible.length) throw fail(409, 'Requested model identity changed');
+      }
+      if (new Set(eligible.map(value => canonicalPartitionJson([value.identity, partitionAdapterIdentities(value)]))).size !== 1) throw fail(409, 'Model id has ambiguous execution identity', 'model');
+      eligible.sort((a, b) => Number(!!a.partition) - Number(!!b.partition));
+      model = freeze(structuredClone(eligible[0]));
+      assert(typeof model.identity === 'string' && model.identity.length > 0, 'Requester model identity missing');
+      if (input.reploid && input.reploid.expected_model_identity !== model.identity) throw fail(409, 'Requested model identity changed');
+      const requested = requireGenerationCapability(model, input.generationRequest);
+      const request = freeze({ threadId, attemptId, model, messages: input.messages, ...(requested ? {generationRequest:requested} : {}) });
+      if (await authorize({ action: 'chat.execute', principal, request, signal }) !== true) throw fail(403, 'Request execution denied');
+      requirePrivateScope();
+      signal.throwIfAborted(); scope.clearDeadline();
+      res.setHeader('x-request-id', id); res.setHeader('x-reploid-attempt-id', attemptId);
+      res.setHeader('x-reploid-model-identity', model.identity);
+      if (requested) res.setHeader('x-reploid-token-usage', requested.usage);
+      output = protocol.output({ id, created, model: model.id, input, write, end: value => res.end(value), json: value => json(res, 200, value) });
+      const result = await participant.generate(request, {
+        signal, principal, onState() {},
+        onReservation(reservationId) {
+          if (!res.headersSent && typeof reservationId === 'string' && reservationId.length > 0 && reservationId.length <= 512) {
+            res.setHeader('x-reploid-reservation-id', reservationId);
+          }
+        },
+        onUsage(event) {
+          try {
+            signal.throwIfAborted();
+            assert(acceptingCallbacks, 'Requester callback after completion');
+            assert(disclosureApproved, 'Recipient disclosure must precede output');
+            assert(requested && !observedUsage && sequence === 0 && event?.threadId === threadId && event.attemptId === attemptId
+              && event.schema === requested.usage && event.outputTokens === 0, 'Unbound or out-of-order provider token usage');
+            observedUsage = tokenUsage(event.inputTokens, event.outputTokens, requested);
+            if (input.stream) output.usage?.(observedUsage);
+          } catch (error) { controller.abort(error); throw error; }
+        },
+        async requestApproval(preview) {
+          assert(acceptingCallbacks, 'Requester callback after completion');
+          disclosureApproved = false;
+          try {
+            signal.throwIfAborted();
+            preview = freeze(structuredClone(preview));
+            const recipients = [...new Set([...(preview.recipients || []), ...(preview.input?.recipients || []),
+              ...(preview.route?.stages?.map(stage => stage.participantId) || []),
+              ...[preview.participantA, preview.participantB, preview.recipientIdentity || preview.providerId].filter(Boolean)])];
+            if (input.reploid && (!recipients.length || recipients.some(id => !input.reploid.allowed_recipients.includes(id)))) {
+              throw fail(403, 'Actual route recipients exceed the permitted private pool');
+            }
+            if (input.reploid && ((input.reploid.expected_plan_identity && preview.planId !== input.reploid.expected_plan_identity)
+              || canonicalPartitionJson(preview.adapterIdentities || []) !== canonicalPartitionJson(partitionAdapterIdentities(model)))) throw fail(409, 'Disclosure execution identity changed');
+            assert(preview?.threadId === threadId && preview.attemptId === attemptId
+              && preview.modelId === model.id && preview.modelIdentity === model.identity
+              && canonicalPartitionJson(preview.input?.messages ?? null) === canonicalPartitionJson(request.messages)
+              && canonicalPartitionJson(preview.input?.generationRequest ?? null) === canonicalPartitionJson(requested ?? null),
+            'Disclosure preview differs from the admitted request');
+            const approved = await authorize({ action: 'chat.disclose', principal, request,
+              preview, signal });
+            signal.throwIfAborted();
+            if (approved !== true) throw fail(403, 'Recipient disclosure denied');
+            requirePrivateScope();
+            assert(acceptingCallbacks, 'Requester callback after completion');
+            disclosureApproved = true;
+            approvedRecipients = recipients;
+            return true;
+          } catch (error) { controller.abort(error); throw error; }
+        },
+        onDelta(event) {
+          try {
+            signal.throwIfAborted();
+            assert(acceptingCallbacks, 'Requester callback after completion');
+            assert(disclosureApproved, 'Recipient disclosure must precede output');
+            assert(event?.threadId === threadId && event.attemptId === attemptId && event.sequence === sequence++
+              && typeof event.text === 'string', 'Requester delta identity or sequence mismatch');
+            assert(!model.partition || !requested || observedUsage, 'Provider token usage must precede text');
+            emitted += event.text;
+            assert(emitted.length <= policy.inputLimits.maxOutputCharacters, 'Output text limit exceeded');
+            if (input.stream) output.delta(event.text);
+          } catch (error) { controller.abort(error); throw error; }
+        }
+      });
+      acceptingCallbacks = false;
+      signal.throwIfAborted();
+      assert(disclosureApproved, 'Recipient disclosure must precede completion');
+      requirePrivateScope();
+      assert(result?.threadId === threadId && result.attemptId === attemptId && result.modelId === model.id
+        && result.modelIdentity === model.identity, 'Requester result identity mismatch');
+      if (!model.partition) assert(canonicalPartitionJson(result.adapterIdentities || []) === canonicalPartitionJson(partitionAdapterIdentities(model)), 'Requester adapter identity mismatch');
+      assert(typeof result.content === 'string' && result.content.length <= policy.inputLimits.maxOutputCharacters, 'Invalid requester text result');
+      assert(!sequence || emitted === result.content, 'Requester final text differs from streamed text');
+      const reason = result.execution?.stopReason;
+      assert(['length', 'max-tokens', 'stop', 'eos', 'eos-token', 'stop-token', 'stop-sequence', 'context-limit'].includes(reason), 'Requester termination reason unavailable');
+      const finishReason = ['length', 'max-tokens', 'context-limit'].includes(reason) ? 'length' : 'stop';
+      let usage;
+      if (!model.partition && result.usage !== undefined) {
+        assert(result.usage.schema === 'raw-model-tokens/v1'
+          && Number.isSafeInteger(result.usage.inputTokens) && result.usage.inputTokens >= 0
+          && Number.isSafeInteger(result.usage.outputTokens) && result.usage.outputTokens >= 0
+          && Number.isSafeInteger(result.usage.inputTokens + result.usage.outputTokens), 'Invalid whole-model token usage');
+        usage = Object.freeze({ schema: result.usage.schema, inputTokens: result.usage.inputTokens, outputTokens: result.usage.outputTokens });
+      }
+      if (requested) {
+        usage = tokenUsage(result.usage?.inputTokens, result.usage?.outputTokens, requested);
+        assert(model.partition
+          ? observedUsage && usage.inputTokens === observedUsage.inputTokens && result.usage.schema === usage.schema
+            && usage.outputTokens === (result.execution?.stepSummary?.count ?? result.execution?.steps?.length)
+          : !observedUsage && result.usage?.schema === usage.schema
+            && usage.inputTokens === result.execution?.completion?.promptTokenCount
+            && usage.outputTokens === result.execution?.completion?.generatedTokenCount,
+        'Provider final token usage differs from input observation');
+      }
+      if (input.stream && !sequence) {
+        assert(!model.partition || !requested || observedUsage, 'Provider token usage must precede text');
+        output.delta(result.content);
+      }
+      const evidence = input.reploid?.include_execution ? { schema: 'reploid.http-execution/v1',
+        threadId, attemptId, poolId: participant.roomId, executionClass: participant.executionClass,
+        modelIdentity: model.identity, adapterIdentities: partitionAdapterIdentities(model), planIdentity: model.partition?.planId || null, recipients: approvedRecipients,
+        execution: structuredClone(result.execution) } : undefined;
+      output.complete(result.content, finishReason, reason, usage, evidence);
+    } catch (cause) {
+      const error = cause instanceof Error ? cause : fail(502, 'Requester failed');
+      controller.abort(error);
+      if (!res.destroyed && !res.writableEnded) {
+        const body = formatError(error);
+        if (streaming) output.error(body.error);
+        else json(res, error.status || 502, body);
+      }
+    } finally {
+      acceptingCallbacks = false;
+      scope.finish();
+    }
+  };
+  return Object.freeze({ handle, getState: () => ({ closed: requests.closed, active: requests.size, scope: 'http-requests' }),
+    close: () => requests.close(() => Error('Text requester server closing'), () => Error('HTTP requester cleanup remains unsettled')) });
+}

package/server/token-auth.js

@@ -0,0 +1,9 @@
+import { timingSafeEqual } from 'node:crypto';
+
+/** Compare already-normalized tokens; do not coerce absent or non-string input. */
+export const tokensEqual = (left, right) => {
+  if (typeof left !== 'string' || typeof right !== 'string') return false;
+  const leftBytes = Buffer.from(left);
+  const rightBytes = Buffer.from(right);
+  return leftBytes.length === rightBytes.length && timingSafeEqual(leftBytes, rightBytes);
+};