my-durable 0.0.0-stage → 0.0.2

package/apps/dpi-sdk/src/protocol/limits.ts

@@ -0,0 +1,199 @@
+/**
+ * Centralized protocol limits and constants — Durable Agent Network P2.
+ *
+ * Single source of truth for every CANON number referenced by
+ * specs 03 (pairing) and 04 (tunnel transport). Runtime code MUST NOT accept
+ * TTL/counter/limit overrides from requests: these constants are server-side
+ * policy. Config that derives from them is validated by `assertLimitsConfig`.
+ */
+
+/** WebSocket maxPayload for one fully-assembled RFC message (both sides). 1 MiB. */
+export const WS_MAX_MESSAGE_BYTES = 1_048_576;
+/** Application-layer chunk raw size (before base64). 64 KiB. */
+export const CHUNK_RAW_BYTES = 65_536;
+/** Maximum chunks per logical message. 256. */
+export const MAX_CHUNKS_PER_MESSAGE = 256;
+/** Maximum logical message size including envelope. 16 MiB. */
+export const LOGICAL_MESSAGE_MAX_BYTES = 16_777_216;
+/** Handshake/control/fault frames must fit without chunking. 4 KiB. */
+export const CONTROL_FRAME_MAX_BYTES = 4_096;
+/** Per-message reassembly timeout. 30 s. */
+export const REASSEMBLY_TIMEOUT_MS = 30_000;
+/** Concurrent messages being reassembled per connection. */
+export const REASSEMBLY_CONCURRENT_PER_CONNECTION = 4;
+/** Total reassembly + outbound queue budget per device connection. 32 MiB. */
+export const CONNECTION_BUFFER_BUDGET_BYTES = 33_554_432;
+/** Total hub-wide budget (reassembly + outbound queues + pending REST). 64 MiB. */
+export const HUB_BUFFER_BUDGET_BYTES = 67_108_864;
+
+/** Hub → browser SSE buffered-output cap before the viewer is ended. 4 MB. */
+export const SSE_HUB_VIEWER_BYTES = 4_000_000;
+/** Hub ↔ device WS buffered-output cap per direction before close(1011). 4 MB. */
+export const WS_BACKPRESSURE_BYTES = 4_000_000;
+/**
+ * Pacing mark for the connector's outbound WS queue: a sender holds back while more than this is queued,
+ * so a valid message up to the 16 MiB logical cap flows through without ever reaching the close above. 1 MiB.
+ */
+export const WS_PACE_LOW_WATER_BYTES = 1_048_576;
+/** Backend → SSE viewer cap (LAN or connector). 2 MB. */
+export const BACKEND_SSE_VIEWER_BYTES = 2_000_000;
+/** Paced write segment for SSE/WS writers. 64 KiB. */
+export const PACE_WRITE_BYTES = 65_536;
+
+/** Subscription keys per browser SSE connection. */
+export const SUBSCRIPTION_KEYS_PER_BROWSER_CONNECTION = 20;
+/** Active readers per device, monitor included. */
+export const READERS_PER_DEVICE = 128;
+/** Active readers hub-wide. */
+export const READERS_PER_HUB = 1_024;
+
+/** REST request body cap (checked before and after reassembly). 256 KiB. */
+export const REST_BODY_MAX_BYTES = 262_144;
+/** REST end-to-end timeout (send + chunk + reassembly). 330 s. */
+export const REST_TIMEOUT_MS = 330_000;
+/** Pending REST requests per device. */
+export const REST_PENDING_PER_DEVICE = 32;
+/** Pending REST requests hub-wide. */
+export const REST_PENDING_PER_HUB = 256;
+
+/** Tunnel identity handshake deadline after 101. 5 s. */
+export const HANDSHAKE_DEADLINE_MS = 5_000;
+/** WS ping interval, both directions. 15 s. */
+export const PING_INTERVAL_MS = 15_000;
+/** Missed pings before close. */
+export const PING_MISS_LIMIT = 2;
+/** No-byte idle safety net. 45 s. */
+export const IDLE_TIMEOUT_MS = 45_000;
+/**
+ * Reconnect backoff shared by the device connector, the hub's mux reader and the SDK stream follower:
+ * 1, 2, 4, 8, 15, 15 s, back to 1 s on hello (see `Backoff`).
+ */
+export const RECONNECT_BACKOFF_S = { initS: 1, capS: 15 } as const;
+/** Monitor probe backoff: the same curve with a 30 s cap. */
+export const MONITOR_BACKOFF_S = { initS: 1, capS: 30 } as const;
+
+/** Pairing code TTL by hub clock. 5 min. */
+export const PAIR_CODE_TTL_MS = 300_000;
+/** Challenge nonce TTL. 60 s. */
+export const PAIR_NONCE_TTL_MS = 60_000;
+/** Grace after code expiry for retrying an ALREADY issued TokenIssue. 120 s. */
+export const PAIR_RECEIPT_GRACE_MS = 120_000;
+/** Wrong signatures before an enrollment is cancelled. */
+export const PAIR_SIGNATURE_FAIL_LIMIT = 3;
+/** Clock-skew tolerance for challenges accepted by the device. ±60 s. */
+export const PAIR_CLOCK_SKEW_MS = 60_000;
+
+/** Rate limits (per real-IP, hub-side token buckets). */
+export const PAIR_RATE_LIMITS = {
+  codeCreate: { perMinute: 5, capacity: 5 },
+  start: { perMinute: 20, capacity: 20 },
+  verifyFails: { perWindow: 100, windowMinutes: 15 },
+  verifyTotal: { perMinute: 300, capacity: 300 },
+} as const;
+
+/** RAM caps for pending pairing state. */
+export const PAIR_RAM_CAPS = { codes: 1_000, enrollments: 1_000 } as const;
+/** Pairing endpoint body cap. 16 KiB. */
+export const PAIRING_BODY_MAX_BYTES = 16_384;
+/** HTTP pairing operation timeout / retry budget. */
+export const PAIR_HTTP_TIMEOUT_MS = 10_000;
+export const PAIR_HTTP_MAX_RETRIES = 3;
+/** Approved-code polling cadence. 1 s. */
+export const PAIR_POLL_MS = 1_000;
+
+/** Hub admin REST rate limit (per real IP): refill 60/min, burst capacity 120. */
+export const API_RATE_LIMITS = { perMinute: 60, capacity: 120 } as const;
+
+/** Per-address limiter tables (pairing, admin API, tunnel upgrade): key cap and idle TTL. A full table refuses new keys. */
+export const IP_BUCKET_MAX_KEYS = 10_000;
+export const IP_BUCKET_IDLE_TTL_MS = 900_000;
+
+/**
+ * Tunnel upgrade allocation (05 §4.3 / S-10): attempts per real IP (refill and burst), pending+live
+ * connections per real IP, and the hub-wide pending-handshake and authenticated-connection caps.
+ */
+export const WS_UPGRADE_LIMITS = {
+  perMinutePerIp: 30,
+  burstPerIp: 10,
+  connectionsPerIp: 5,
+  pendingPerHub: 100,
+  livePerHub: 1_000,
+} as const;
+
+/** Routine credential rotation interval. 90 days. */
+export const ROTATION_INTERVAL_DAYS = 90;
+
+/**
+ * Tunneled REST paths live under /v1 and must match the route allowlist (rest-routes.ts). SSE endpoints (streams
+ * are subscription-based) and the device-LOCAL control surface (pairing/tunnel status) are not on it: they belong
+ * to the device operator, not to remote hub callers.
+ */
+export const REST_PATH_PREFIX = "/v1/";
+
+/** Canonical snapshot of every startup-validated number (testability: callers may pass mutated copies to validateLimits). */
+export interface LimitsSnapshot {
+  wsMaxMessageBytes: number;
+  chunkRawBytes: number;
+  maxChunksPerMessage: number;
+  logicalMessageMaxBytes: number;
+  connectionBufferBudgetBytes: number;
+  hubBufferBudgetBytes: number;
+  readersPerDevice: number;
+  readersPerHub: number;
+  restPendingPerDevice: number;
+  restPendingPerHub: number;
+  connectorBackoffFirstS: number;
+  pairVerifyFailsPerWindow: number;
+  pairVerifyFailWindowMinutes: number;
+  apiPerMinute: number;
+  apiCapacity: number;
+}
+
+/** CANON snapshot — the single source validated at startup. */
+const CANON_SNAPSHOT: LimitsSnapshot = {
+  wsMaxMessageBytes: WS_MAX_MESSAGE_BYTES,
+  chunkRawBytes: CHUNK_RAW_BYTES,
+  maxChunksPerMessage: MAX_CHUNKS_PER_MESSAGE,
+  logicalMessageMaxBytes: LOGICAL_MESSAGE_MAX_BYTES,
+  connectionBufferBudgetBytes: CONNECTION_BUFFER_BUDGET_BYTES,
+  hubBufferBudgetBytes: HUB_BUFFER_BUDGET_BYTES,
+  readersPerDevice: READERS_PER_DEVICE,
+  readersPerHub: READERS_PER_HUB,
+  restPendingPerDevice: REST_PENDING_PER_DEVICE,
+  restPendingPerHub: REST_PENDING_PER_HUB,
+  connectorBackoffFirstS: RECONNECT_BACKOFF_S.initS,
+  pairVerifyFailsPerWindow: PAIR_RATE_LIMITS.verifyFails.perWindow,
+  pairVerifyFailWindowMinutes: PAIR_RATE_LIMITS.verifyFails.windowMinutes,
+  apiPerMinute: API_RATE_LIMITS.perMinute,
+  apiCapacity: API_RATE_LIMITS.capacity,
+};
+
+/**
+ * Pure validation over a snapshot: every number must be a positive safe
+ * integer within sane bounds, and structural relations must hold. Exported
+ * for compile-negative tests; production calls assertLimitsConfig() (CANON).
+ */
+export function validateLimits(l: LimitsSnapshot): void {
+  const fields = Object.entries(l) as Array<[keyof LimitsSnapshot, number]>;
+  for (const [name, v] of fields) {
+    if (!Number.isSafeInteger(v) || v <= 0) throw new Error(`limits: ${name} must be a positive safe integer (got ${v})`);
+  }
+  if (l.maxChunksPerMessage > 65_536 || l.wsMaxMessageBytes > 64 * 1_048_576 || l.hubBufferBudgetBytes > (1 << 30))
+    throw new Error("limits: value out of sane range");
+  if (l.maxChunksPerMessage * l.chunkRawBytes < l.logicalMessageMaxBytes)
+    throw new Error("limits: chunk count cannot cover logical message budget");
+  if (l.chunkRawBytes * 2 > l.wsMaxMessageBytes)
+    throw new Error("limits: single chunk + envelope must fit one WS message");
+  if (l.connectionBufferBudgetBytes >= l.hubBufferBudgetBytes)
+    throw new Error("limits: connection budget must be smaller than hub budget");
+  if (l.readersPerDevice > l.readersPerHub)
+    throw new Error("limits: per-device reader cap exceeds hub cap");
+  if (l.restPendingPerDevice > l.restPendingPerHub)
+    throw new Error("limits: per-device pending cap exceeds hub cap");
+  if (l.apiCapacity < l.apiPerMinute)
+    throw new Error("limits: API burst capacity must be >= per-minute refill");
+}
+
+export function assertLimitsConfig(): void {
+  validateLimits(CANON_SNAPSHOT);
+}

package/apps/dpi-sdk/src/protocol/pairing.ts

@@ -0,0 +1,311 @@
+/**
+ * Pairing protocol DTOs — Durable Agent Network P2 (spec 03 §5).
+ *
+ * Strict TypeBox schemas: unknown fields are rejected everywhere. Schema
+ * checks are necessary but NOT sufficient: cross-field/state invariants and
+ * origin normalization live in the exported helpers below and in the hub
+ * state machine (03 §4).
+ *
+ * This module must stay browser-safe: no Node builtin imports.
+ */
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+
+const Strict = { additionalProperties: false } as const;
+
+const Uuid = Type.String({
+  pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+  minLength: 36,
+  maxLength: 36,
+});
+// Strict end anchor: JS `$` alone can still match before a final newline, so
+// DeviceId uses an explicit lookahead. All other patterns are length-clamped
+// (min===max), which also rejects trailing-newline inputs.
+const DeviceId = Type.String({
+  pattern: "^[a-z0-9][a-z0-9-]{0,31}(?![\\s\\S])",
+  minLength: 1,
+  maxLength: 32,
+});
+const Fingerprint = Type.String({ pattern: "^sha256:[0-9a-f]{64}$", minLength: 71, maxLength: 71 });
+const Nonce = Type.String({ pattern: "^[A-Za-z0-9_-]{43}$", minLength: 43, maxLength: 43 });
+const TunnelToken = Type.String({ pattern: "^dpt_[A-Za-z0-9_-]{43}$", minLength: 47, maxLength: 47 });
+const PairCode = Type.String({ pattern: "^[A-Z2-7]{8}$", minLength: 8, maxLength: 8 });
+
+export const PairRequest = Type.Object(
+  {
+    type: Type.Literal("pair.request"),
+    v: Type.Literal(1),
+    requestId: Uuid,
+    code: PairCode,
+    deviceUid: Uuid,
+    deviceName: Type.String({ minLength: 1, maxLength: 64 }),
+    publicKey: Type.String({ minLength: 1, maxLength: 256 }), // Ed25519 SPKI PEM
+    keyFingerprint: Fingerprint,
+    clientTime: Type.Integer(),
+  },
+  Strict,
+);
+
+export const PairChallenge = Type.Object(
+  {
+    type: Type.Literal("pair.challenge"),
+    v: Type.Literal(1),
+    enrollmentId: Uuid,
+    nonce: Nonce,
+    issuedAt: Type.Integer(),
+    hubId: Uuid, // deployment ID, not a cryptographic fingerprint
+  },
+  Strict,
+);
+
+export const PairResponse = Type.Object(
+  {
+    type: Type.Literal("pair.response"),
+    v: Type.Literal(1),
+    enrollmentId: Uuid,
+    nonce: Nonce,
+    signature: Type.String({ pattern: "^[A-Za-z0-9_-]{86}$", minLength: 86, maxLength: 86 }),
+  },
+  Strict,
+);
+
+export const PairPending = Type.Object(
+  {
+    type: Type.Literal("pair.pending"),
+    v: Type.Literal(1),
+    enrollmentId: Uuid,
+    state: Type.Literal("awaiting_approval"),
+    expiresAt: Type.Integer(),
+    pollAfterMs: Type.Integer({ minimum: 1 }),
+  },
+  Strict,
+);
+
+export const TokenIssue = Type.Object(
+  {
+    type: Type.Literal("pair.token"),
+    v: Type.Literal(1),
+    enrollmentId: Uuid,
+    deviceUid: Uuid,
+    deviceId: DeviceId,
+    pairingEpoch: Uuid,
+    credentialId: Uuid,
+    generation: Type.Integer({ minimum: 1 }),
+    hubId: Uuid,
+    hubOrigin: Type.String(),
+    hubUrl: Type.String(),
+    tunnelToken: TunnelToken,
+    issuedAt: Type.Integer(),
+    expiresAt: Type.Null(),
+  },
+  Strict,
+);
+
+export const PairApproval = Type.Object(
+  {
+    enrollmentId: Uuid,
+    deviceUid: Uuid,
+    keyFingerprint: Fingerprint,
+    replaceKey: Type.Optional(Type.Boolean()),
+  },
+  Strict,
+);
+
+export const RevokeNotice = Type.Object(
+  {
+    type: Type.Literal("pair.revoke"),
+    v: Type.Literal(1),
+    deviceId: DeviceId,
+    pairingEpoch: Uuid,
+    reason: Type.Union([
+      Type.Literal("user"),
+      Type.Literal("compromise"),
+      Type.Literal("hub_migrated"),
+    ]),
+    revokedAt: Type.Integer(),
+  },
+  Strict,
+);
+
+export const PairError = Type.Object(
+  {
+    type: Type.Literal("pair.error"),
+    v: Type.Literal(1),
+    code: Type.Union([
+      Type.Literal("code_invalid"),
+      Type.Literal("code_expired"),
+      Type.Literal("code_used"),
+      Type.Literal("code_in_use"),
+      Type.Literal("rate_limited"),
+      Type.Literal("signature_invalid"),
+      Type.Literal("clock_skew"),
+      Type.Literal("paired_elsewhere"),
+      Type.Literal("hub_required"),
+      Type.Literal("fingerprint_mismatch"),
+      Type.Literal("identity_conflict"),
+      Type.Literal("enrollment_lost"),
+      Type.Literal("enrollment_cancelled"),
+      Type.Literal("already_issued"),
+      Type.Literal("challenge_expired"),
+    ]),
+    message: Type.String({ maxLength: 512 }),
+    retryAfterMs: Type.Optional(Type.Integer({ minimum: 1 })),
+  },
+  Strict,
+);
+
+export const PairCodeIssue = Type.Object(
+  {
+    type: Type.Literal("pair.code"),
+    v: Type.Literal(1),
+    codeId: Uuid,
+    code: PairCode,
+    expiresAt: Type.Integer(),
+    hubOrigin: Type.String({ maxLength: 2048 }),
+    pairUrl: Type.String({ maxLength: 4096 }),
+  },
+  Strict,
+);
+
+const PairCodeStatePhase = Type.Union([
+  Type.Literal("open"),
+  Type.Literal("awaiting_proof"),
+  Type.Literal("awaiting_approval"),
+  Type.Literal("approved"),
+  Type.Literal("issued"),
+  Type.Literal("connected"),
+  Type.Literal("cancelled"),
+  Type.Literal("expired"),
+]);
+
+export const PairCodeState = Type.Object(
+  {
+    type: Type.Literal("pair.code-state"),
+    v: Type.Literal(1),
+    codeId: Uuid,
+    expiresAt: Type.Integer(),
+    phase: PairCodeStatePhase,
+    enrollment: Type.Optional(
+      Type.Object(
+        {
+          enrollmentId: Uuid,
+          deviceUid: Uuid,
+          deviceName: Type.String({ minLength: 1, maxLength: 64 }),
+          keyFingerprint: Fingerprint,
+          proofVerified: Type.Boolean(),
+          keyChanged: Type.Boolean(),
+        },
+        Strict,
+      ),
+    ),
+    deviceId: Type.Optional(DeviceId),
+    error: Type.Optional(PairError),
+  },
+  Strict,
+);
+
+export type PairRequest = Static<typeof PairRequest>;
+export type PairChallenge = Static<typeof PairChallenge>;
+export type PairResponse = Static<typeof PairResponse>;
+export type PairPending = Static<typeof PairPending>;
+export type TokenIssue = Static<typeof TokenIssue>;
+export type PairApproval = Static<typeof PairApproval>;
+export type RevokeNotice = Static<typeof RevokeNotice>;
+export type PairError = Static<typeof PairError>;
+export type PairCodeIssue = Static<typeof PairCodeIssue>;
+export type PairCodeState = Static<typeof PairCodeState>;
+
+/** The ten wire DTOs — used by schema-coverage tests (W-3). */
+export const PAIRING_DTOS = [
+  PairRequest,
+  PairChallenge,
+  PairResponse,
+  PairPending,
+  TokenIssue,
+  PairApproval,
+  RevokeNotice,
+  PairError,
+  PairCodeIssue,
+  PairCodeState,
+] as const;
+
+export function checkPairingDto<T extends (typeof PAIRING_DTOS)[number]>(
+  schema: T,
+  value: unknown,
+): value is Static<T> {
+  return Value.Check(schema, value);
+}
+
+/**
+ * Canonical hub origin: HTTPS only, no userinfo/query/fragment/base path.
+ * The tunnel WSS URL is always derived from this same origin + /api/tunnel.
+ */
+export function parseHubOrigin(
+  input: string,
+): { ok: true; origin: string; tunnelUrl: string } | { ok: false; error: string } {
+  if (typeof input !== "string" || input.length === 0 || input.length > 2048) {
+    return { ok: false, error: "origin: empty or too long" };
+  }
+  if (/\s|\n|\r|\t/.test(input)) {
+    return { ok: false, error: "origin: whitespace not allowed" };
+  }
+  let url: URL;
+  try {
+    url = new URL(input);
+  } catch {
+    return { ok: false, error: "origin: not a valid URL" };
+  }
+  if (url.protocol !== "https:") {
+    return { ok: false, error: "origin: HTTPS origin required" };
+  }
+  if (url.username || url.password) {
+    return { ok: false, error: "origin: userinfo not allowed" };
+  }
+  if (url.search || url.hash) {
+    return { ok: false, error: "origin: query/fragment not allowed" };
+  }
+  if (url.pathname !== "/" && url.pathname !== "") {
+    return { ok: false, error: "origin: base path not allowed" };
+  }
+  return { ok: true, origin: url.origin, tunnelUrl: `${url.origin}/api/tunnel` };
+}
+
+/** Exact Ed25519 signing payload — element order is normative (03 §4.2). */
+export function pairingSigningPayload(parts: {
+  hubOrigin: string;
+  hubId: string;
+  enrollmentId: string;
+  nonce: string;
+  issuedAt: number;
+  deviceUid: string;
+  keyFingerprint: string;
+}): string {
+  return JSON.stringify([
+    "dpi-pair-v1",
+    parts.hubOrigin,
+    parts.hubId,
+    parts.enrollmentId,
+    parts.nonce,
+    parts.issuedAt,
+    parts.deviceUid,
+    parts.keyFingerprint,
+  ]);
+}
+
+/**
+ * Base64url byte-length validation for credential-bearing strings read from
+ * files/env (which may carry a trailing newline). Protocol contexts use the
+ * strict patterns above; this guards the persistence/compare layer.
+ */
+export function strictTokenBytes(input: string, expectedBytes: number): boolean {
+  if (input.includes("=") || input.includes("+") || input.includes("/")) return false;
+  if (!/^[A-Za-z0-9_-]+$/.test(input)) return false; // trailing newline/space/charset
+  const chars = input.length;
+  if (chars !== Math.ceil((expectedBytes * 8) / 6)) return false;
+  try {
+    const b64 = input.replace(/-/g, "+").replace(/_/g, "/");
+    return globalThis.atob(b64).length === expectedBytes;
+  } catch {
+    return false;
+  }
+}

package/apps/dpi-sdk/src/protocol/rest-routes.ts

@@ -0,0 +1,105 @@
+// The device REST routes a hub may call through the tunnel (04 §9, P2-16), as an allowlist of method + route.
+// Browser-safe: no Node builtins.
+//
+// Everything else under /v1 is refused. That keeps the device-local control surface (/v1/pairing/*, /v1/tunnel)
+// and the three SSE streams (/v1/events, .../events) off the REST channel in every spelling, instead of trying
+// to name each bad spelling. A route the device adds is remote-callable only once it is listed here; the
+// backend's route-parity test fails until a new route is classified as served or as local/stream.
+//
+// `:name` stands for one parameter segment. Every other segment is a literal that must match exactly (lowercase):
+// Express matches routes case-insensitively, so a looser comparison here would let `/v1/Pairing` through.
+
+const ROUTES: readonly (readonly [method: string, pattern: string])[] = [
+  ["GET", "/device"],
+  ["GET", "/tree"],
+  ["GET", "/fs/dirs"],
+  ["GET", "/docs/:kind"],
+
+  ["GET", "/sessions"],
+  ["POST", "/sessions"],
+  ["GET", "/sessions/:s"],
+  ["PATCH", "/sessions/:s"],
+  ["DELETE", "/sessions/:s"],
+  ["GET", "/sessions/:s/compaction"],
+  ["PATCH", "/sessions/:s/compaction"],
+  ["GET", "/sessions/:s/tasks"],
+  ["POST", "/sessions/:s/tasks/:taskId/abort"],
+  ["GET", "/sessions/:s/inspect"],
+  ["GET", "/sessions/:s/submissions/:id"],
+
+  ["GET", "/sessions/:s/agents"],
+  ["POST", "/sessions/:s/agents"],
+  ["GET", "/sessions/:s/agents/:a"],
+  ["PATCH", "/sessions/:s/agents/:a"],
+  ["GET", "/sessions/:s/agents/:a/entries"],
+  ["GET", "/sessions/:s/agents/:a/transcript"],
+  ["POST", "/sessions/:s/agents/:a/messages"],
+  ["DELETE", "/sessions/:s/agents/:a/inbox/:submissionId"],
+  ["POST", "/sessions/:s/agents/:a/abort"],
+  ["POST", "/sessions/:s/agents/:a/fork"],
+  ["GET", "/sessions/:s/agents/:a/config"],
+  ["PATCH", "/sessions/:s/agents/:a/config"],
+  ["GET", "/sessions/:s/agents/:a/extensions"],
+  ["PATCH", "/sessions/:s/agents/:a/extensions"],
+  ["POST", "/sessions/:s/agents/:a/compact"],
+  ["POST", "/sessions/:s/agents/:a/reset"],
+  ["GET", "/sessions/:s/agents/:a/docs/:kind"],
+  ["POST", "/sessions/:s/agents/:a/demo/state"],
+  ["POST", "/sessions/:s/agents/:a/demo/jobs"],
+  ["POST", "/sessions/:s/agents/:a/demo/jobs/:taskId/approval"],
+];
+
+/** The allowlist as data: `route` is relative to /v1. */
+export const REST_ROUTE_ALLOWLIST: readonly { method: string; route: string }[] = ROUTES.map(([method, route]) => ({
+  method,
+  route,
+}));
+
+/** Longest decoded parameter (session and agent names stop at 100 characters). */
+export const REST_PARAM_MAX_CHARS = 256;
+
+const COMPILED = ROUTES.map(([method, pattern]) => ({ method, parts: pattern.slice(1).split("/") }));
+
+const decodeOr = (segment: string): string | undefined => {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return undefined;
+  }
+};
+
+/** One percent-encoded name: not empty, not a dot segment, no separators or control characters once decoded. */
+function isParam(segment: string): boolean {
+  const name = decodeOr(segment);
+  return (
+    name !== undefined &&
+    name.length > 0 &&
+    name.length <= REST_PARAM_MAX_CHARS &&
+    name !== "." &&
+    name !== ".." &&
+    // eslint-disable-next-line no-control-regex
+    !/[\u0000-\u001f\u007f/\\]/.test(name)
+  );
+}
+
+/** `segments` are the raw (still percent-encoded) path segments after /v1. */
+export function matchesRestRoute(method: string, segments: readonly string[]): boolean {
+  return COMPILED.some(
+    (route) =>
+      route.method === method &&
+      route.parts.length === segments.length &&
+      route.parts.every((part, i) => (part.startsWith(":") ? isParam(segments[i]) : part === segments[i])),
+  );
+}
+
+/**
+ * Why a path that matched no route is out of bounds, for the refusal message only (the allowlist alone decides).
+ * Case-insensitive on purpose: `/v1/Events` is still an event stream as far as Express is concerned.
+ */
+export function restRouteKind(segments: readonly string[]): "stream" | "local" | undefined {
+  const s = segments.map((segment) => (decodeOr(segment) ?? segment).toLowerCase());
+  if (s[0] === "pairing" || s[0] === "tunnel") return "local";
+  if (s[0] === "events") return "stream";
+  if (s[0] === "sessions" && (s[2] === "events" || (s[2] === "agents" && s[4] === "events"))) return "stream";
+  return undefined;
+}