@robota-sdk/agent-transport 3.0.0-beta.82 → 3.0.0-beta.84

package/src/message-decoders.ts

@@ -14,6 +14,11 @@
  * owner and is tracked there, not duplicated in a transport package.
  */
 
+import {
+  SESSION_CHANGE_REFUSAL_CODES,
+  SESSION_DELETE_REFUSAL_CODES,
+} from '@robota-sdk/agent-interface-session';
+
 import type { TBackgroundControlAction, TClientMessage, TServerMessage } from './wire-messages.js';
 
 export type TMessageDecodeResult<TMessage> =
@@ -32,6 +37,7 @@ const isString = (v: unknown): v is string => typeof v === 'string';
 const isNonEmptyString = (v: unknown): v is string => typeof v === 'string' && v.length > 0;
 const isBoolean = (v: unknown): v is boolean => typeof v === 'boolean';
 const isFiniteNumber = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+const isCount = (v: unknown): v is number => Number.isSafeInteger(v) && (v as number) >= 0;
 const isOptional =
   (check: (v: unknown) => boolean) =>
   (v: unknown): boolean =>
@@ -42,6 +48,24 @@ const oneOf =
   (members: readonly string[]) =>
   (v: unknown): boolean =>
     typeof v === 'string' && members.includes(v);
+/** A record, not an array, so a turn source added to the union without one here fails to compile. */
+const TURN_SOURCES: Readonly<
+  Record<Extract<TServerMessage, { type: 'turn_source' }>['source'], true>
+> = { user: true, 'agent-wakeup': true, peer: true, external: true };
+/** A history entry's envelope is this package's (`IWireHistoryEntry`); its `data` is the recorder's. */
+const isWireHistoryEntry = (v: unknown): boolean =>
+  isRecord(v) &&
+  isString(v['id']) &&
+  isString(v['timestamp']) &&
+  isString(v['category']) &&
+  isString(v['type']);
+const isWireHistoryEntries = (v: unknown): boolean =>
+  Array.isArray(v) && v.every(isWireHistoryEntry);
+/** #3282 §4: one row of `agent_definitions` — name, one-line description, plain-words location. */
+const isWireAgentDefinition = (v: unknown): boolean =>
+  isRecord(v) && isString(v['name']) && isString(v['description']) && isString(v['definedIn']);
+const isWireAgentDefinitions = (v: unknown): boolean =>
+  Array.isArray(v) && v.every(isWireAgentDefinition);
 
 type TFieldCheck = (value: unknown) => boolean;
 type TVariantShape = Readonly<Record<string, TFieldCheck>>;
@@ -69,6 +93,7 @@ const isBackgroundTaskListFilter: TFieldCheck = (v) =>
 const isBackgroundTaskInput: TFieldCheck = (v) =>
   isRecord(v) && isOptional(isString)(v['prompt']) && isOptional(isString)(v['stdin']);
 const isBackgroundTaskLogCursor: TFieldCheck = (v) => isRecord(v) && isFiniteNumber(v['offset']);
+const isExecutionDetailCursor: TFieldCheck = (v) => isRecord(v) && isCount(v['offset']);
 const isPermissionResultValue: TFieldCheck = (v) =>
   isBoolean(v) || v === 'allow-session' || v === 'allow-project';
 const isActionResponse: TFieldCheck = (v) =>
@@ -79,14 +104,149 @@ const isActionResponse: TFieldCheck = (v) =>
     isOptional(isString)(v['text'])) ||
     (v['type'] === 'cancelled' && v['values'] === undefined && v['text'] === undefined));
 
+type TSettingsPatch = Extract<TClientMessage, { type: 'update-settings' }>['patch'];
+/** Keyed by `field`, so a patch variant added to the union without a shape here fails to compile. */
+const SETTINGS_PATCH_SHAPES: Readonly<Record<TSettingsPatch['field'], TVariantShape>> = {
+  language: { language: isNonEmptyString },
+  outputStyle: { styleId: isNonEmptyString },
+  preset: { presetId: isNonEmptyString },
+  permissionMode: { mode: isNonEmptyString },
+  sandbox: { enabled: isBoolean },
+  removePermissionRule: {
+    scope: isNonEmptyString,
+    kind: oneOf(['allow', 'deny', 'ask']),
+    pattern: isNonEmptyString,
+  },
+  mcpServerEnabled: { serverId: isNonEmptyString, enabled: isBoolean },
+  reloadMcpServers: {},
+  pluginEnabled: { pluginId: isNonEmptyString, enabled: isBoolean },
+  reloadPlugins: {},
+  installPlugin: { pluginId: isNonEmptyString },
+  uninstallPlugin: { pluginId: isNonEmptyString },
+  // #3282 §4b: "Providers & Models" — Use, Model, Delete.
+  providerProfile: { profileName: isNonEmptyString },
+  providerModel: { profileName: isNonEmptyString, modelId: isNonEmptyString },
+  deleteProviderProfile: { profileName: isNonEmptyString },
+};
+const isSettingsPatch: TFieldCheck = (v) => {
+  if (!isRecord(v) || !isString(v['field'])) return false;
+  const field = v['field'];
+  if (!Object.prototype.hasOwnProperty.call(SETTINGS_PATCH_SHAPES, field)) return false;
+  const shape = SETTINGS_PATCH_SHAPES[field as TSettingsPatch['field']];
+  return Object.entries(shape).every(([key, check]) => check(v[key]));
+};
+
+type TWaitingLoopStopOutcome = Extract<TServerMessage, { type: 'waiting_loop_stop' }>['outcome'];
+/** Keyed by `kind`, so an outcome added to the union without a shape here fails to compile. */
+const WAITING_LOOP_STOP_OUTCOME_SHAPES: Readonly<
+  Record<TWaitingLoopStopOutcome['kind'], TVariantShape>
+> = {
+  none: {},
+  several: { message: isString },
+  stopped: { loopId: isNonEmptyString, message: isOptional(isString) },
+  failed: { loopId: isOptional(isNonEmptyString), message: isString },
+};
+const isWaitingLoopStopOutcome: TFieldCheck = (v) => {
+  if (!isRecord(v) || !isString(v['kind'])) return false;
+  const kind = v['kind'];
+  if (!Object.prototype.hasOwnProperty.call(WAITING_LOOP_STOP_OUTCOME_SHAPES, kind)) return false;
+  const shape = WAITING_LOOP_STOP_OUTCOME_SHAPES[kind as TWaitingLoopStopOutcome['kind']];
+  return Object.entries(shape).every(([field, check]) => check(v[field]));
+};
+
+/** Decode a `kind`-discriminated result union (the `TWaitingLoopStopOutcome` convention) from a shape
+ *  map keyed by `kind`. */
+function isKindDiscriminated(shapes: Readonly<Record<string, TVariantShape>>): TFieldCheck {
+  return (v) => {
+    if (!isRecord(v) || !isString(v['kind'])) return false;
+    const shape = Object.prototype.hasOwnProperty.call(shapes, v['kind']) ? shapes[v['kind']] : undefined;
+    if (shape === undefined) return false;
+    return Object.entries(shape).every(([field, check]) => check(v[field]));
+  };
+}
+
+// #3282 §4c: the Project panel's reads. Each result is the session method's own return value, crossing
+// the wire unchanged (the `TWaitingLoopStopOutcome` convention above) — decoded from a `kind`-keyed
+// shape map the same way.
+const PROJECT_FILE_STATUSES = [
+  'Added',
+  'Modified',
+  'Deleted',
+  'Renamed',
+  'Copied',
+  'Untracked',
+  'Conflicted',
+] as const;
+const isProjectStatusFile: TFieldCheck = (v) =>
+  isRecord(v) &&
+  isNonEmptyString(v['path']) &&
+  oneOf(PROJECT_FILE_STATUSES)(v['status']) &&
+  isOptional(isNonEmptyString)(v['renamedFrom']) &&
+  isOptional(isFiniteNumber)(v['added']) &&
+  isOptional(isFiniteNumber)(v['removed']);
+const isProjectStatusFiles: TFieldCheck = (v) => Array.isArray(v) && v.every(isProjectStatusFile);
+
+type TProjectStatusReadResult = Extract<TServerMessage, { type: 'project_status' }>['result'];
+const PROJECT_STATUS_READ_SHAPES: Readonly<Record<TProjectStatusReadResult['kind'], TVariantShape>> = {
+  status: {
+    branch: isOptional(isString),
+    unborn: isBoolean,
+    files: isProjectStatusFiles,
+    truncated: isBoolean,
+  },
+  'not-a-repository': {},
+  failed: { message: isString },
+};
+const isProjectStatusRead = isKindDiscriminated(PROJECT_STATUS_READ_SHAPES);
+
+const DIFF_LINE_TYPES = ['add', 'remove', 'context', 'hunk'] as const;
+const isDiffLine: TFieldCheck = (v) =>
+  isRecord(v) && oneOf(DIFF_LINE_TYPES)(v['type']) && isString(v['text']) && isFiniteNumber(v['lineNumber']);
+const isDiffLines: TFieldCheck = (v) => Array.isArray(v) && v.every(isDiffLine);
+
+type TProjectDiffReadResult = Extract<TServerMessage, { type: 'project_diff' }>['result'];
+const PROJECT_DIFF_READ_SHAPES: Readonly<Record<TProjectDiffReadResult['kind'], TVariantShape>> = {
+  diff: { diffLines: isDiffLines, truncated: isBoolean },
+  'not-a-repository': {},
+  'outside-workspace': {},
+  failed: { message: isString },
+};
+const isProjectDiffRead = isKindDiscriminated(PROJECT_DIFF_READ_SHAPES);
+
+type TProjectMemoryReadResult = Extract<TServerMessage, { type: 'project_memory' }>['result'];
+const PROJECT_MEMORY_READ_SHAPES: Readonly<Record<TProjectMemoryReadResult['kind'], TVariantShape>> = {
+  memory: { content: isString, path: isNonEmptyString, truncated: isBoolean },
+  unavailable: { message: isString },
+};
+const isProjectMemoryRead = isKindDiscriminated(PROJECT_MEMORY_READ_SHAPES);
+
 /** One entry per `TClientMessage` variant — a variant added to the union without one fails the test. */
 export const CLIENT_MESSAGE_SHAPES: Readonly<Record<TClientMessage['type'], TVariantShape>> = {
   submit: { prompt: isNonEmptyString },
-  command: { name: isNonEmptyString, args: isOptional(isString) },
+  command: {
+    name: isNonEmptyString,
+    args: isOptional(isString),
+    requestId: isOptional(isNonEmptyString),
+  },
   abort: {},
   'cancel-queue': {},
   'get-messages': {},
+  'get-history': { fromIndex: isOptional(isCount) },
+  'get-prompts': {},
   'get-context': {},
+  'get-commands': {},
+  'get-status': {},
+  'list-models': { requestId: isNonEmptyString },
+  'get-agent-definitions': { requestId: isNonEmptyString },
+  'list-sessions': { requestId: isNonEmptyString },
+  'new-session': { requestId: isOptional(isNonEmptyString) },
+  'switch-session': { sessionId: isNonEmptyString, requestId: isOptional(isNonEmptyString) },
+  'rename-session': {
+    sessionId: isNonEmptyString,
+    name: isNonEmptyString,
+    requestId: isNonEmptyString,
+  },
+  'delete-session': { sessionId: isNonEmptyString, requestId: isNonEmptyString },
   'get-usage-report': {},
   'get-personal-usage-report': {
     requestId: isNonEmptyString,
@@ -100,6 +260,15 @@ export const CLIENT_MESSAGE_SHAPES: Readonly<Record<TClientMessage['type'], TVar
   'get-executing': {},
   'get-pending': {},
   'get-execution-workspace': {},
+  'read-execution-detail': {
+    requestId: isNonEmptyString,
+    entryId: isNonEmptyString,
+    cursor: isOptional(isExecutionDetailCursor),
+  },
+  'stop-waiting-loop': { requestId: isNonEmptyString },
+  'project-status': { requestId: isNonEmptyString },
+  'project-diff': { requestId: isNonEmptyString, path: isNonEmptyString },
+  'project-memory': { requestId: isNonEmptyString },
   'get-background-tasks': { filter: isOptional(isBackgroundTaskListFilter) },
   'get-background-task': { taskId: isNonEmptyString },
   'get-background-job-groups': {},
@@ -116,6 +285,8 @@ export const CLIENT_MESSAGE_SHAPES: Readonly<Record<TClientMessage['type'], TVar
   'ask-response': { id: isNonEmptyString, response: isActionResponse },
   resume: { lastSeq: isFiniteNumber },
   ack: { seq: isFiniteNumber },
+  'get-settings': { requestId: isNonEmptyString },
+  'update-settings': { requestId: isNonEmptyString, patch: isSettingsPatch },
 };
 
 const authored: TVariantShape = { driverId: isOptional(isString) };
@@ -129,10 +300,58 @@ export const SERVER_MESSAGE_SHAPES: Readonly<Record<TServerMessage['type'], TVar
   thinking: { isThinking: isBoolean, ...authored },
   complete: { result: isRecord, ...authored },
   interrupted: { result: isRecord, ...authored },
-  error: { message: isString, ...authored },
-  command_result: { name: isString, message: isString, success: isBoolean },
-  messages: { messages: isRecordArray },
+  error: {
+    message: isString,
+    code: isOptional(oneOf(['auth', 'rate_limit', 'model_unavailable', 'network', 'provider'])),
+    provider: isOptional(isString),
+    retryAfterSeconds: isOptional(isFiniteNumber),
+    model: isOptional(isString),
+    ...authored,
+  },
+  command_result: {
+    name: isString,
+    message: isString,
+    success: isBoolean,
+    requestId: isOptional(isString),
+  },
+  messages: { messages: isRecordArray, display: isOptional(isRecordArray), ...authored },
+  history: { startIndex: isCount, total: isCount, entries: isWireHistoryEntries },
   context: { state: isRecord },
+  history_changed: {},
+  turn_source: { source: oneOf(Object.keys(TURN_SOURCES)) },
+  commands: { commands: isRecordArray, skills: isRecordArray },
+  session_status: { status: isRecord },
+  model_list: {
+    requestId: isNonEmptyString,
+    groups: isRecordArray,
+    currentProfile: isOptional(isString),
+    currentModel: isString,
+  },
+  agent_definitions: {
+    requestId: isNonEmptyString,
+    agents: isWireAgentDefinitions,
+    current: isNonEmptyString,
+  },
+  sessions: { requestId: isNonEmptyString, listing: isRecord },
+  sessions_error: {
+    requestId: isNonEmptyString,
+    code: oneOf(['not_available', 'list_failed']),
+    message: isString,
+  },
+  session_switched: { event: isRecord },
+  session_change_failed: {
+    code: oneOf(SESSION_CHANGE_REFUSAL_CODES),
+    message: isString,
+    requestId: isOptional(isString),
+  },
+  session_renamed_in_list: { requestId: isNonEmptyString, sessionId: isString, name: isString },
+  session_rename_failed: { requestId: isNonEmptyString, message: isString },
+  session_deleted: { requestId: isNonEmptyString, sessionId: isString },
+  session_delete_failed: {
+    requestId: isNonEmptyString,
+    code: oneOf(SESSION_DELETE_REFUSAL_CODES),
+    message: isString,
+  },
   usage_report: { report: isRecord },
   personal_usage_report: { requestId: isNonEmptyString, report: isRecord },
   personal_usage_report_error: {
@@ -152,8 +371,15 @@ export const SERVER_MESSAGE_SHAPES: Readonly<Record<TServerMessage['type'], TVar
     message: isString,
   },
   executing: { executing: isBoolean },
-  pending: { pending: (v) => v === null || isString(v) },
+  // An older host sends no count; a client then counts the one prompt it can see.
+  pending: { pending: (v) => v === null || isString(v), pendingCount: isOptional(isCount) },
   execution_workspace_event: { snapshot: isRecord },
+  execution_detail: { requestId: isNonEmptyString, page: isRecord },
+  execution_detail_error: { requestId: isNonEmptyString, message: isString },
+  waiting_loop_stop: { requestId: isNonEmptyString, outcome: isWaitingLoopStopOutcome },
+  project_status: { requestId: isNonEmptyString, result: isProjectStatusRead },
+  project_diff: { requestId: isNonEmptyString, result: isProjectDiffRead },
+  project_memory: { requestId: isNonEmptyString, result: isProjectMemoryRead },
   background_task_event: { event: isRecord },
   background_job_group_event: { event: isRecord },
   plan_event: { event: isRecord },
@@ -176,8 +402,14 @@ export const SERVER_MESSAGE_SHAPES: Readonly<Record<TServerMessage['type'], TVar
     success: isBoolean,
     message: isOptional(isString),
   },
-  protocol_error: { message: isString },
+  protocol_error: { message: isString, requestId: isOptional(isString) },
   resume_gap: {},
+  settings: { requestId: isNonEmptyString, settings: isRecord },
+  settings_error: {
+    requestId: isNonEmptyString,
+    code: oneOf(['not_available', 'invalid', 'refused', 'update_failed']),
+    message: isString,
+  },
 };
 
 function decodeVariant<TMessage extends { type: string }>(

package/src/node/bearer-resource-gate.ts

@@ -0,0 +1,291 @@
+/**
+ * The shared admission gate of an OAuth resource server reached over HTTP: RFC 6750 bearer challenges,
+ * RFC 9728 protected-resource metadata, the public-URL name checks, and a failure-only throttle per
+ * peer address. Every remote HTTP carrier that admits by access token composes these pieces, so the
+ * rules are one set of code rather than one per carrier.
+ *
+ * The host is reached through its PUBLIC URL, usually behind a reverse proxy, so every name the gate
+ * checks comes from that URL rather than from the listener: the Host and Origin a request must carry
+ * (the proxy must preserve Host) and the paths it serves. The listener's own address is never a name a
+ * client uses.
+ *
+ * Refusals answer with an empty body and, for a token problem, only the standard challenge: an error
+ * code from RFC 6750 and where the metadata lives. Only failures are counted, so a peer holding a valid
+ * token is never throttled, however many failures share its address. What a carrier reports about a
+ * refused peer is a coarse address class, never the address.
+ *
+ * This module binds no listener; a carrier owns its socket and calls these per request.
+ */
+
+import { BlockList, isIP } from 'node:net';
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+const WELL_KNOWN_PREFIX = '/.well-known/oauth-protected-resource';
+/** Window over which one address's failures are counted. */
+const FAILURE_WINDOW_MS = 60_000;
+/** Failures one address may have in a window before its further failures answer 429. */
+const MAX_FAILURES_PER_WINDOW = 20;
+/** Addresses tracked at once; the oldest is forgotten first, so a spray cannot grow memory. */
+const MAX_TRACKED_ADDRESSES = 4096;
+/** RFC 6749 scope-token characters: printable ASCII except space, `"` and `\`. */
+const SCOPE_TOKEN = /^[\x21\x23-\x5b\x5d-\x7e]+$/;
+
+/** A coarse class of a peer's address; the address itself is never reported. */
+export type TRemoteAddressClass = 'loopback' | 'private' | 'public' | 'unknown';
+
+/** Where a refused request came from, and whether its address is over the failure budget. */
+export interface IBearerFailure {
+  readonly remote: TRemoteAddressClass;
+  readonly throttled: boolean;
+  readonly retryAfterSeconds: number;
+}
+
+/** The public-facing identity of one resource server and its per-address failure budget. */
+export interface IBearerResourceServer {
+  /** The parsed public URL; its path is the resource's base path. */
+  readonly url: URL;
+  /**
+   * Host and Origin must name the public URL. On a mismatch the 403 is written and false returned;
+   * nothing is counted, since no credential was judged.
+   */
+  checkNames(req: IncomingMessage, res: ServerResponse): boolean;
+  /** Count one failure against the request's peer. */
+  fail(req: IncomingMessage): IBearerFailure;
+  /** The request's peer class without counting anything. */
+  remote(req: IncomingMessage): TRemoteAddressClass;
+}
+
+/** The challenges and metadata of one protected resource (one audience). */
+export interface IProtectedResource {
+  /** The RFC 9728 path clients fetch the metadata from. */
+  readonly wellKnownPath: string;
+  readonly metadata: string;
+  readonly challenges: {
+    readonly missing: string;
+    readonly invalid: string;
+    readonly scope: string;
+  };
+}
+
+const LOOPBACK_RANGES = new BlockList();
+LOOPBACK_RANGES.addSubnet('127.0.0.0', 8, 'ipv4');
+LOOPBACK_RANGES.addAddress('::1', 'ipv6');
+const PRIVATE_RANGES = new BlockList();
+PRIVATE_RANGES.addSubnet('10.0.0.0', 8, 'ipv4');
+PRIVATE_RANGES.addSubnet('172.16.0.0', 12, 'ipv4');
+PRIVATE_RANGES.addSubnet('192.168.0.0', 16, 'ipv4');
+PRIVATE_RANGES.addSubnet('169.254.0.0', 16, 'ipv4');
+PRIVATE_RANGES.addSubnet('100.64.0.0', 10, 'ipv4');
+PRIVATE_RANGES.addSubnet('fc00::', 7, 'ipv6');
+PRIVATE_RANGES.addSubnet('fe80::', 10, 'ipv6');
+
+/** A literal address in one spelling: IPv4-mapped IPv6 folded to IPv4, IPv6 lowercased. */
+function normalizeAddress(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  const text = value.trim().toLowerCase();
+  const mapped = text.startsWith('::ffff:') ? text.slice('::ffff:'.length) : undefined;
+  if (mapped !== undefined && isIP(mapped) === 4) return mapped;
+  return isIP(text) === 0 ? undefined : text;
+}
+
+function classifyAddress(address: string | undefined): TRemoteAddressClass {
+  if (address === undefined) return 'unknown';
+  const family = isIP(address) === 4 ? 'ipv4' : 'ipv6';
+  if (LOOPBACK_RANGES.check(address, family)) return 'loopback';
+  if (PRIVATE_RANGES.check(address, family)) return 'private';
+  return 'public';
+}
+
+/** Parse a resource server's public URL: plain `https`, no credentials, query or fragment. */
+export function parsePublicHttpsUrl(publicUrl: string, label: string): URL {
+  let url: URL;
+  try {
+    url = new URL(publicUrl);
+  } catch {
+    throw new Error(`${label} public URL must be an absolute https URL`);
+  }
+  if (url.protocol !== 'https:') throw new Error(`${label} public URL must use https`);
+  if (url.username !== '' || url.password !== '' || url.search !== '' || url.hash !== '') {
+    throw new Error(`${label} public URL must not carry credentials, a query or a fragment`);
+  }
+  return url;
+}
+
+interface IFailureWindow {
+  count: number;
+  startedAt: number;
+}
+
+/** Counts failures per address in fixed windows. Only failures are ever recorded here. */
+function createFailureCounter(now: () => number) {
+  const windows = new Map<string, IFailureWindow>();
+  return (address: string): { throttled: boolean; retryAfterSeconds: number } => {
+    const at = now();
+    let entry = windows.get(address);
+    if (entry === undefined || at - entry.startedAt >= FAILURE_WINDOW_MS) {
+      windows.delete(address);
+      if (windows.size >= MAX_TRACKED_ADDRESSES) {
+        for (const [key, value] of windows) {
+          if (at - value.startedAt >= FAILURE_WINDOW_MS) windows.delete(key);
+        }
+        const oldest = windows.keys().next();
+        if (windows.size >= MAX_TRACKED_ADDRESSES && oldest.done !== true) {
+          windows.delete(oldest.value);
+        }
+      }
+      entry = { count: 0, startedAt: at };
+      windows.set(address, entry);
+    }
+    entry.count += 1;
+    const remainingMs = FAILURE_WINDOW_MS - (at - entry.startedAt);
+    return {
+      throttled: entry.count > MAX_FAILURES_PER_WINDOW,
+      retryAfterSeconds: Math.max(1, Math.ceil(remainingMs / 1000)),
+    };
+  };
+}
+
+/**
+ * Build the public identity of a resource server. Throws when the public URL is not plain `https`,
+ * or a trusted proxy is not a literal address. `label` names the carrier in those messages.
+ */
+export function createBearerResourceServer(options: {
+  readonly publicUrl: string;
+  /** Proxy addresses whose `X-Forwarded-For` is believed. Absent: the header is ignored. */
+  readonly trustedProxies?: readonly string[];
+  readonly label: string;
+  readonly now?: () => number;
+}): IBearerResourceServer {
+  const url = parsePublicHttpsUrl(options.publicUrl, options.label);
+  const trustedProxies = new Set<string>();
+  for (const proxy of options.trustedProxies ?? []) {
+    const address = normalizeAddress(proxy);
+    if (address === undefined) {
+      throw new Error(`${options.label} trusted proxy must be a literal IP address`);
+    }
+    trustedProxies.add(address);
+  }
+  const expectedHosts = new Set([url.host]);
+  if (url.port === '') expectedHosts.add(`${url.hostname}:443`);
+  const failures = createFailureCounter(options.now ?? (() => performance.now()));
+
+  function remoteAddress(req: IncomingMessage): string | undefined {
+    const peer = normalizeAddress(req.socket.remoteAddress);
+    if (peer === undefined || !trustedProxies.has(peer)) return peer;
+    const header = req.headers['x-forwarded-for'];
+    const hops = (Array.isArray(header) ? header.join(',') : (header ?? '')).split(',');
+    // Walk from the proxy inward: the nearest hop not itself a trusted proxy is the client, as the
+    // trusted proxy saw it. Hops further left were written by the client and are not believed.
+    for (let index = hops.length - 1; index >= 0; index -= 1) {
+      const hop = normalizeAddress(hops[index]);
+      if (hop === undefined) return peer;
+      if (!trustedProxies.has(hop)) return hop;
+    }
+    return peer;
+  }
+
+  return {
+    url,
+    checkNames(req, res) {
+      const host = req.headers.host?.toLowerCase();
+      const origin = req.headers.origin;
+      if (
+        host === undefined ||
+        !expectedHosts.has(host) ||
+        (origin !== undefined && origin !== url.origin)
+      ) {
+        res.writeHead(403).end();
+        return false;
+      }
+      return true;
+    },
+    fail(req) {
+      const address = remoteAddress(req);
+      return { remote: classifyAddress(address), ...failures(address ?? 'unknown') };
+    },
+    remote(req) {
+      return classifyAddress(remoteAddress(req));
+    },
+  };
+}
+
+/**
+ * Describe one protected resource: where its RFC 9728 metadata lives and the challenges that point
+ * there. Throws for a non-`https` issuer, or no scope or a scope a challenge cannot quote.
+ */
+export function describeProtectedResource(options: {
+  /** The resource identifier (`aud`), an `https` URL. */
+  readonly resource: string;
+  readonly issuer: string;
+  readonly scopes: readonly string[];
+  readonly label: string;
+}): IProtectedResource {
+  const url = parsePublicHttpsUrl(options.resource, options.label);
+  let issuer: URL;
+  try {
+    issuer = new URL(options.issuer);
+  } catch {
+    throw new Error(`${options.label} authorization issuer must be an absolute https URL`);
+  }
+  if (issuer.protocol !== 'https:') {
+    throw new Error(`${options.label} authorization issuer must use https`);
+  }
+  if (options.scopes.length === 0 || !options.scopes.every((scope) => SCOPE_TOKEN.test(scope))) {
+    throw new Error(`${options.label} authorization needs at least one valid scope`);
+  }
+  // RFC 9728 §3.1: the well-known segment goes between the host and the resource's path, with a
+  // lone terminating slash dropped.
+  const wellKnownPath = `${WELL_KNOWN_PREFIX}${url.pathname === '/' ? '' : url.pathname}`;
+  const metadataUrl = `${url.origin}${wellKnownPath}`;
+  const scopeList = options.scopes.join(' ');
+  return {
+    wellKnownPath,
+    metadata: JSON.stringify({
+      resource: options.resource,
+      authorization_servers: [options.issuer],
+      scopes_supported: [...options.scopes],
+      bearer_methods_supported: ['header'],
+    }),
+    challenges: {
+      missing: `Bearer resource_metadata="${metadataUrl}"`,
+      invalid: `Bearer error="invalid_token", resource_metadata="${metadataUrl}"`,
+      scope: `Bearer error="insufficient_scope", scope="${scopeList}", resource_metadata="${metadataUrl}"`,
+    },
+  };
+}
+
+/** Answer a metadata request: GET only, the JSON document, nothing else. */
+export function serveProtectedResourceMetadata(
+  req: IncomingMessage,
+  res: ServerResponse,
+  resource: IProtectedResource,
+): void {
+  if (req.method !== 'GET') {
+    res.writeHead(405, { Allow: 'GET' }).end();
+    return;
+  }
+  res.writeHead(200, { 'Content-Type': 'application/json' }).end(resource.metadata);
+}
+
+/**
+ * Answer a refused bearer token after its failure was counted: 429 once the peer is over budget,
+ * 403 `insufficient_scope` for a missing scope, otherwise 401 with the missing-token or
+ * `invalid_token` challenge. Always an empty body.
+ */
+export function refuseBearerToken(
+  res: ServerResponse,
+  resource: IProtectedResource,
+  refusal: 'missing-token' | 'missing-scope' | 'invalid-token',
+  failure: IBearerFailure,
+): void {
+  if (failure.throttled) {
+    res.writeHead(429, { 'Retry-After': String(failure.retryAfterSeconds) }).end();
+  } else if (refusal === 'missing-scope') {
+    res.writeHead(403, { 'WWW-Authenticate': resource.challenges.scope }).end();
+  } else {
+    const challenge =
+      refusal === 'missing-token' ? resource.challenges.missing : resource.challenges.invalid;
+    res.writeHead(401, { 'WWW-Authenticate': challenge }).end();
+  }
+}

package/src/node/index.ts

@@ -8,6 +8,19 @@ export { sealHandoffRecord, verifyHandoffPayload } from './handoff-manifest.js';
 export type { IIntegrityVerdict, TIntegrityFailure } from './handoff-manifest.js';
 export { createAccessTokenVerifier } from './access-token-verifier.js';
 export type { IAccessTokenVerifierDeps } from './access-token-verifier.js';
+export {
+  createBearerResourceServer,
+  describeProtectedResource,
+  parsePublicHttpsUrl,
+  refuseBearerToken,
+  serveProtectedResourceMetadata,
+} from './bearer-resource-gate.js';
+export type {
+  IBearerFailure,
+  IBearerResourceServer,
+  IProtectedResource,
+  TRemoteAddressClass,
+} from './bearer-resource-gate.js';
 export {
   DEFAULT_MAX_FILE_BYTES,
   FILE_CHUNK_BYTES,

package/src/observer-messages.ts

@@ -0,0 +1,47 @@
+import type { TClientMessage } from './wire-messages.js';
+
+/**
+ * The only inbound messages an observer may send: reads of this session. An allowlist, so a message
+ * type added later is refused to observers until someone decides it is a read. `get-prompts` is left
+ * out: an observer never receives prompts, open ones included.
+ *
+ * The host refuses anything else from an observer, and a client in observe mode sends only these, so
+ * both sides read this one list.
+ */
+export const OBSERVER_MESSAGES: ReadonlySet<TClientMessage['type']> = new Set<
+  TClientMessage['type']
+>([
+  'get-messages',
+  'get-history',
+  'get-context',
+  'get-status',
+  'get-commands',
+  'list-models',
+  'get-executing',
+  'get-pending',
+  'get-execution-workspace',
+  'read-execution-detail',
+  'get-agent-definitions',
+  'get-usage-report',
+  'list-sessions',
+  'get-background-tasks',
+  'get-background-task',
+  'get-background-job-groups',
+  'get-background-job-group',
+  'wait-background-job-group',
+  'read-background-task-log',
+  // #3282 §4a: reading the Settings snapshot is a pure read of this session's own configuration.
+  // `update-settings` stays out — an observer never writes.
+  'get-settings',
+  // #3282 §4c: the Project panel's reads — git status, one file's diff, project memory. All three are
+  // read-only (there is no "restore"/write counterpart in this feature — see the SPEC.md design
+  // decision on why checkpoints/rewind are excluded entirely), so all three are observer-safe.
+  'project-status',
+  'project-diff',
+  'project-memory',
+]);
+
+/** Whether an observer may send a message of this type. */
+export function isObserverMessageType(type: string): boolean {
+  return (OBSERVER_MESSAGES as ReadonlySet<string>).has(type);
+}