@ixo/oracle-runtime-workers 0.13.0 → 0.16.0

package/src/shell/app.ts

@@ -1,3 +1,14 @@
+import {
+  authenticateChannel,
+  assertActiveChannelBinding,
+  channelAuthConfig,
+} from '../channels/auth';
+import {
+  ChannelError,
+  ChannelTurnBody,
+  channelRequestHash,
+  readChannelBody,
+} from '../channels/contract';
 /* eslint-disable no-console -- console IS the logger on Workers (Logs/observability). */
 /**
  * The HTTP shell — a Hono app that speaks the same wire protocol as the Node
@@ -6,8 +17,18 @@
  * work unchanged. Every authenticated route resolves the caller's
  * `UserOracleDO` and forwards to it; streaming turns are proxied byte-for-byte.
  */
+import { FRONTEND_BRIDGE } from '@ixo/common/ai/frontend-bridge';
+import { bodyLimit } from 'hono/body-limit';
+import { HTTPException } from 'hono/http-exception';
+import {
+  TopicOperationId,
+  TopicDeliverableRequestSchema,
+  TOPIC_DELIVERABLE_BODY_BYTES,
+  type TopicDeliverableCommand,
+} from '../tasks/topic-deliverables';
 import { parseTranscriptPageQuery } from '../do/transcript';
 import { Hono } from 'hono';
+import { routePath } from 'hono/route';
 import { cors } from 'hono/cors';
 import type { OracleWorkerEnv, TurnIdentity } from '../do/contracts';
 import { parseOwnerCopyFailure } from '../owner-store/owner-copy-errors';
@@ -22,12 +43,26 @@ import {
   type DelegatedCapability,
 } from '../do/ucan-service';
 import {
+  authConfigFromEnv,
   authenticate,
   isExcluded,
+  validateDelegation,
   type AuthResult,
   type RouteExclusion,
 } from './auth';
-import { turnBodyTooLarge } from './turn-body-cap';
+import { MAX_TURN_BODY_BYTES } from './turn-body-cap';
+import {
+  artifactDataResponse,
+  artifactPageResponse,
+} from '../artifacts/routes';
+import { ARTIFACT_ID_RE } from '../artifacts/store';
+import { FEEDBACK_BODY_MAX_BYTES } from '../feedback/contract';
+import {
+  feedbackFailure,
+  submitFeedback,
+  withFeedbackCapability,
+  type FeedbackShellOptions,
+} from '../feedback/submit';
 import { z } from 'zod';
 
 const DebugEventBody = z.object({
@@ -54,15 +89,48 @@ export interface PluginRoute {
   ) => Response | Promise<Response>;
 }
 
+/** What `GET /models` hands its payload provider besides the env. */
+export interface ListModelsOptions {
+  waitUntil?: (work: Promise<unknown>) => void;
+}
+
+/**
+ * The request's `waitUntil`, or undefined when the app runs without an
+ * execution context (Hono's `executionCtx` getter throws then).
+ */
+function executionWaitUntil(c: {
+  readonly executionCtx: { waitUntil(work: Promise<unknown>): void };
+}): ((work: Promise<unknown>) => void) | undefined {
+  let ctx: { waitUntil(work: Promise<unknown>): void };
+  try {
+    ctx = c.executionCtx;
+  } catch {
+    return undefined;
+  }
+  return (work) => ctx.waitUntil(work);
+}
+
 export interface ShellOptions {
   /** Routes contributed by plugins (`getRoutes`) and the host. */
   routes?: PluginRoute[];
   /** Auth exclusions contributed by plugins and the host. */
   authExcludedRoutes?: RouteExclusion[];
-  /** `GET /models` payload provider (may fetch live prices). */
-  listModels?: (env: OracleWorkerEnv) => unknown | Promise<unknown>;
+  /**
+   * `GET /models` payload provider (may fetch live prices). `waitUntil`
+   * keeps work it starts in the background (a price refresh) alive past the
+   * response; absent when the request has no execution context.
+   */
+  listModels?: (
+    env: OracleWorkerEnv,
+    options?: ListModelsOptions,
+  ) => unknown | Promise<unknown>;
   /** Version banner for `GET /`. */
   banner?: { name: string; description?: string };
+  /**
+   * Anonymous Agent-response feedback (`src/feedback/`). Absent = off: the
+   * route answers 404 and transcripts do not advertise the capability.
+   */
+  feedback?: FeedbackShellOptions | null;
 }
 
 type Variables = { auth: AuthResult };
@@ -71,6 +139,20 @@ function errorText(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+/** Longest error message an unexpected channel failure logs. */
+const CHANNEL_FAILURE_LOG_CHARS = 300;
+
+/** `<name>: <message>` of an unexpected channel failure, the message bounded. */
+function describeChannelFailure(err: unknown): string {
+  const name = err instanceof Error ? err.name : typeof err;
+  const message = errorText(err);
+  return `${name}: ${
+    message.length > CHANNEL_FAILURE_LOG_CHARS
+      ? `${message.slice(0, CHANNEL_FAILURE_LOG_CHARS)}…`
+      : message
+  }`;
+}
+
 /** The rejection an in-flight RPC gets when `ctx.abort()` resets its object. */
 function isAbortRejection(err: unknown): boolean {
   return /debug reset requested|reset requested by the debug route|durable object reset|no longer active|aborted/i.test(
@@ -78,18 +160,121 @@ function isAbortRejection(err: unknown): boolean {
   );
 }
 
-const BUILTIN_EXCLUSIONS: RouteExclusion[] = [
+/**
+ * Routes that answer without a UCAN invocation: the banner, liveness
+ * probes, the model list, and the gateway's status/start that monitors and
+ * the drills poll. Every one of them is read-only or idempotent; nothing
+ * that changes state for other users is here (the debug routes included —
+ * they authenticate like every other route).
+ */
+export const BUILTIN_EXCLUSIONS: readonly RouteExclusion[] = [
   { path: '/', method: 'GET' },
   { path: '/health', method: 'ALL' },
   { path: '/health/*', method: 'ALL' },
   { path: '/models', method: 'GET' },
   { path: '/matrix/status', method: 'GET' },
   { path: '/matrix/start', method: 'POST' },
-  // Operator-only; the /debug/* middleware 404s unless ORACLE_DEBUG_ROUTES=true.
-  { path: '/debug/matrix/restart', method: 'POST' },
-  { path: '/debug/matrix/stop', method: 'POST' },
 ];
 
+// Body caps of the built-in routes (a turn's is `MAX_TURN_BODY_BYTES`).
+/** `POST /messages/abort`: a session id. */
+export const ABORT_BODY_BYTES = 4 * 1024;
+/** `POST /delegation`: one serialized delegation (a base64 CAR with its proof chain). */
+export const DELEGATION_BODY_BYTES = 64 * 1024;
+/** `/byo-llm/*`: provider credentials and OAuth exchanges. */
+export const BYO_LLM_BODY_BYTES = 64 * 1024;
+/** `/debug/*`: operator drills (the largest is one Matrix event, itself capped at 64 KiB). */
+export const DEBUG_BODY_BYTES = 64 * 1024;
+
+/** A body cap enforced before the body is buffered: over it, 413 and the handler never runs. */
+function limitBody(maxSize: number) {
+  return bodyLimit({
+    maxSize,
+    onError: (c) =>
+      c.json({ statusCode: 413, message: 'request entity too large' }, 413),
+  });
+}
+
+const DID_SEGMENT = String.raw`(?:[A-Za-z0-9._-]|%[0-9A-Fa-f]{2})+`;
+/** A W3C DID (`did:<method>:<method-specific-id>`), bounded in length. */
+const DID_RE = new RegExp(`^did:[a-z0-9]+:${DID_SEGMENT}(?::${DID_SEGMENT})*$`);
+const MAX_DID_LENGTH = 512;
+
+export function isDidShaped(value: string): boolean {
+  return value.length <= MAX_DID_LENGTH && DID_RE.test(value);
+}
+
+/**
+ * The key of one rate-limit budget. Prefixed with the oracle's DID: rate
+ * limiter bindings that share a `namespace_id` share their counters, even
+ * across Workers, so two oracles on one account would otherwise share every
+ * user's budget.
+ */
+export function rateLimitKey(
+  env: Pick<OracleWorkerEnv, 'ORACLE_DID'>,
+  scope: 'user' | 'artifact' | 'socket' | 'status' | 'start',
+  subject: string,
+): string {
+  return `${env.ORACLE_DID}|${scope}|${subject}`;
+}
+
+/**
+ * Whether an unauthenticated caller (keyed by its IP) is over its budget.
+ * No binding or no client IP (local runs, tests): never limited.
+ */
+async function ipOverLimit(
+  env: OracleWorkerEnv,
+  scope: 'artifact' | 'socket' | 'status' | 'start',
+  ip: string | undefined,
+): Promise<boolean> {
+  if (!ip || !env.RATE_LIMIT) return false;
+  const { success } = await env.RATE_LIMIT.limit({
+    key: rateLimitKey(env, scope, ip),
+  });
+  return !success;
+}
+
+/**
+ * The operators allowed onto the gateway-wide debug routes
+ * (`ORACLE_OPERATOR_DIDS`, comma-separated DIDs): null when the variable is
+ * unset, an empty set when it is malformed (fail closed — nobody, and an
+ * error in the log). Parsed once per distinct value.
+ */
+let operatorList: { raw: string; dids: ReadonlySet<string> } | null = null;
+
+function operatorDids(env: OracleWorkerEnv): ReadonlySet<string> | null {
+  const raw = env.ORACLE_OPERATOR_DIDS;
+  if (typeof raw !== 'string' || raw.trim() === '') return null;
+  if (operatorList?.raw === raw) return operatorList.dids;
+  const entries = raw
+    .split(',')
+    .map((did) => did.trim())
+    .filter(Boolean);
+  const malformed = entries.filter((did) => !isDidShaped(did));
+  if (malformed.length > 0)
+    console.error(
+      `[shell] ORACLE_OPERATOR_DIDS has entries that are not DIDs (${malformed.join(', ')}); no caller is let onto /debug/matrix/*`,
+    );
+  operatorList = {
+    raw,
+    dids: new Set(malformed.length > 0 ? [] : entries),
+  };
+  return operatorList.dids;
+}
+
+/** What `GET /health/matrix` answers: the gateway's in-memory `running` flag. */
+async function gatewayRunning(env: OracleWorkerEnv): Promise<boolean> {
+  const res = await gateway(env).fetch('https://matrix-gateway/health');
+  if (!res.ok) return false;
+  const body: unknown = await res.json();
+  return (
+    typeof body === 'object' &&
+    body !== null &&
+    'running' in body &&
+    body.running === true
+  );
+}
+
 export function createShell(
   opts: ShellOptions = {},
 ): Hono<{ Bindings: OracleWorkerEnv; Variables: Variables }> {
@@ -106,6 +291,9 @@ export function createShell(
   // — the shell only routes on `?userDid`, and the object refuses a token
   // that does not belong to that DID. The 101 response must also reach the
   // client untouched (no CORS header rewriting on an upgraded response).
+  // Unauthenticated until CONNECT, so before any object is addressed the
+  // DID must at least look like one and the caller's IP must be within its
+  // budget: each upgrade costs a user object a request and a held socket.
   app.all('/socket.io/*', async (c) => {
     const userDid = c.req.query('userDid');
     if (!userDid) {
@@ -114,6 +302,12 @@ export function createShell(
         400,
       );
     }
+    if (!isDidShaped(userDid)) {
+      return c.json(
+        { code: 3, message: 'userDid query parameter is not a DID.' },
+        400,
+      );
+    }
     if (c.req.header('upgrade')?.toLowerCase() !== 'websocket') {
       return c.json(
         {
@@ -124,6 +318,8 @@ export function createShell(
         426,
       );
     }
+    if (await ipOverLimit(c.env, 'socket', c.req.header('cf-connecting-ip')))
+      return c.json({ code: 3, message: 'Too many requests.' }, 429);
     const target = new URL(c.req.url);
     target.protocol = 'https:';
     target.host = 'user-oracle';
@@ -132,6 +328,22 @@ export function createShell(
     return userStub(c.env, userDid).fetch(forwarded);
   });
 
+  // --- artefact links (public) -----------------------------------------------
+  // Also ahead of CORS and auth: a link is opened by whoever holds it, and
+  // the data route answers any origin itself (a shared viewer on another
+  // host fetches it). Both serve only what is safe without the key, which
+  // stays in the link's fragment: a static page and ciphertext.
+  app.get('/a/:artifactId', (c) =>
+    artifactPageResponse(c.env, c.req.param('artifactId')),
+  );
+  app.get('/a/:artifactId/data', async (c) => {
+    if (await ipOverLimit(c.env, 'artifact', c.req.header('cf-connecting-ip')))
+      return c.text('Too many requests', 429, {
+        'access-control-allow-origin': '*',
+      });
+    return artifactDataResponse(c.env, c.req.param('artifactId'));
+  });
+
   app.use('*', async (c, next) => {
     const origin = c.env.CORS_ORIGIN ?? '*';
     return cors({
@@ -161,43 +373,137 @@ export function createShell(
       timestamp: new Date().toISOString(),
     }),
   );
+  // `frontendTools` is the frontend bridge version: the Portal enables
+  // conversational writes only against a runtime that advertises it. A
+  // version signal, not proof the deployment behaves (see frontend-bridge.md).
   app.get('/health', (c) =>
-    c.json({ status: 'ok', timestamp: new Date().toISOString() }),
+    c.json({
+      status: 'ok',
+      timestamp: new Date().toISOString(),
+      frontendTools: FRONTEND_BRIDGE,
+    }),
   );
+  // A liveness probe: the gateway's in-memory flag, no storage read. The
+  // full picture is `/matrix/status`.
   app.get('/health/matrix', async (c) => {
-    const status = await gateway(c.env).status();
-    return c.json(status, status.running ? 200 : 503);
+    const running = await gatewayRunning(c.env).catch((err: unknown) => {
+      console.warn(`[shell] gateway health check failed: ${errorText(err)}`);
+      return false;
+    });
+    return c.json({ running }, running ? 200 : 503);
   });
-  app.get('/matrix/status', async (c) => c.json(await gateway(c.env).status()));
-  app.post('/matrix/start', async (c) =>
-    c.json(await gateway(c.env).ensureStarted()),
-  );
-  app.get('/models', async (c) =>
-    c.json(
-      (await opts.listModels?.(c.env)) ?? {
+  // Public (monitors and the drills poll it), so limited per IP; the
+  // gateway serves the storage-scanning part from a short cache.
+  app.get('/matrix/status', async (c) => {
+    if (await ipOverLimit(c.env, 'status', c.req.header('cf-connecting-ip')))
+      return c.json({ statusCode: 429, message: 'Too many requests' }, 429);
+    return c.json(await gateway(c.env).status());
+  });
+  app.post('/matrix/start', async (c) => {
+    if (await ipOverLimit(c.env, 'start', c.req.header('cf-connecting-ip')))
+      return c.json({ statusCode: 429, message: 'Too many requests' }, 429);
+    return c.json(await gateway(c.env).ensureStarted());
+  });
+  app.get('/models', async (c) => {
+    const waitUntil = executionWaitUntil(c);
+    return c.json(
+      (await opts.listModels?.(c.env, waitUntil ? { waitUntil } : {})) ?? {
         models: [],
         // Node's `ModelListing` shape (`{ models, default }`); the client SDK
         // reads `default`.
         default: c.env.DEFAULT_MODEL ?? null,
       },
-    ),
-  );
+    );
+  });
+
+  app.post('/channels/turn', async (c) => {
+    try {
+      if (!c.env.CHANNEL_SERVICE_DID)
+        throw new ChannelError(
+          503,
+          'Channels are not configured',
+          'not_configured',
+        );
+      const raw = await readChannelBody(c.req.raw);
+      let json: unknown;
+      try {
+        json = JSON.parse(raw);
+      } catch {
+        throw new ChannelError(400, 'Invalid JSON request', 'invalid_request');
+      }
+      const parsed = ChannelTurnBody.safeParse(json);
+      if (!parsed.success)
+        throw new ChannelError(400, 'Invalid channel turn', 'invalid_request');
+      const identity = await authenticateChannel(
+        c.req.raw.headers,
+        raw,
+        parsed.data,
+        channelAuthConfig(c.env),
+      );
+      // Limited as soon as the user is proven, before the Auth Hub round
+      // trip: a flood or a tight poll must not cost one call there each.
+      if (
+        c.env.RATE_LIMIT &&
+        !(
+          await c.env.RATE_LIMIT.limit({
+            key: rateLimitKey(c.env, 'user', identity.userDid),
+          })
+        ).success
+      )
+        throw new ChannelError(429, 'Too many requests', 'rate_limited');
+      await assertActiveChannelBinding(identity, c.env);
+      const outcome = await userStub(c.env, identity.userDid).channelTurn(
+        identity,
+        parsed.data,
+        await channelRequestHash(raw),
+      );
+      if (!outcome.ok)
+        return c.json(
+          { code: outcome.code, message: outcome.message },
+          outcome.status,
+        );
+      const result = outcome.result;
+      return c.json(
+        result,
+        ['queued', 'running', 'recovering'].includes(result.status) ? 202 : 200,
+      );
+    } catch (error) {
+      if (error instanceof ChannelError)
+        return c.json(
+          { code: error.code, message: error.message },
+          error.status,
+        );
+      // The cause only, never the request or its tokens: a 503 the gateway
+      // retries must leave a trace of why it happened.
+      console.error(
+        `[channels] turn failed unexpectedly: ${describeChannelFailure(error)}`,
+      );
+      return c.json(
+        {
+          code: 'unavailable',
+          message: 'Channel turn is temporarily unavailable',
+        },
+        503,
+      );
+    }
+  });
 
   // --- auth ------------------------------------------------------------------
   app.use('*', async (c, next) => {
     if (isExcluded(c.req.method, c.req.path, exclusions)) return next();
-    const outcome = await authenticate(c.req.raw.headers, {
-      oracleDid: c.env.ORACLE_DID,
-      blocksyncUri: c.env.BLOCKSYNC_GRAPHQL_URL,
-      maxTtlSeconds: c.env.UCAN_AUTH_MAX_TTL_SECONDS
-        ? Number(c.env.UCAN_AUTH_MAX_TTL_SECONDS)
-        : undefined,
-    });
+    const outcome = await authenticate(
+      c.req.raw.headers,
+      authConfigFromEnv(c.env),
+    );
     if (!outcome.ok)
       return c.json(
         { statusCode: outcome.status, message: outcome.error },
         outcome.status as 401,
       );
+    if (outcome.auth.via === 'delegation')
+      console.warn(
+        `[auth] ${c.req.method} ${loggedRoute(c)}: ${outcome.auth.userDid} authenticated with a bare delegation (UCAN_ALLOW_BARE_DELEGATION_AUTH); the client must send a UCAN invocation before the fallback is turned off`,
+      );
     c.set('auth', outcome.auth);
     return next();
   });
@@ -206,15 +512,17 @@ export function createShell(
   // Cloudflare's native limiter; the limit/period live on the binding in
   // wrangler.jsonc. Keyed by DID rather than IP so co-located users (one
   // NAT/proxy) never share a bucket and a single leaked token can't burn
-  // unbounded LLM spend. Auth-excluded routes (health/models/matrix status)
-  // ran `next()` above and never reach here. Absent binding = no limiting
-  // (local harness / tests).
+  // unbounded LLM spend; the key carries the oracle's DID (`rateLimitKey`).
+  // Auth-excluded routes (health/models/matrix status) ran `next()` above
+  // and never reach here. Absent binding = no limiting (local harness / tests).
   app.use('*', async (c, next) => {
     const limiter = c.env.RATE_LIMIT;
     if (!limiter) return next();
     const auth = c.get('auth') as AuthResult | undefined;
     if (!auth) return next();
-    const { success } = await limiter.limit({ key: auth.userDid });
+    const { success } = await limiter.limit({
+      key: rateLimitKey(c.env, 'user', auth.userDid),
+    });
     if (!success)
       return c.json(
         {
@@ -261,8 +569,89 @@ export function createShell(
       : c.json({ message: 'Session not found' }, 404);
   });
 
+  app.use('/topic-deliverables/*', async (c, next) => {
+    if (c.env.TOPIC_DELIVERABLES_ENABLED !== 'true')
+      return c.json({ message: 'Not found.' }, 404);
+    if (c.get('auth')?.via !== 'invocation')
+      return c.json({ message: 'A signed invocation is required.' }, 401);
+    return next();
+  });
+  app.use(
+    '/topic-deliverables/*',
+    bodyLimit({
+      maxSize: TOPIC_DELIVERABLE_BODY_BYTES,
+      onError: (c) => c.json({ message: 'Request is too large.' }, 413),
+    }),
+  );
+  app.on(
+    ['PUT', 'GET', 'POST'],
+    [
+      '/topic-deliverables/:operationId',
+      '/topic-deliverables/:operationId/cancel',
+    ],
+    async (c) => {
+      const cancelling =
+        c.req.routePath === '/topic-deliverables/:operationId/cancel';
+      if (cancelling !== (c.req.method === 'POST'))
+        return c.json({ message: 'Not found.' }, 404);
+      const operationId = TopicOperationId.safeParse(
+        c.req.param('operationId'),
+      );
+      if (!operationId.success)
+        return c.json({ message: 'Invalid operation ID.' }, 400);
+      let command: TopicDeliverableCommand;
+      if (c.req.method === 'PUT' || cancelling) {
+        const parsed = TopicDeliverableRequestSchema.safeParse(
+          await c.req.json().catch(() => null),
+        );
+        if (!parsed.success)
+          return c.json({ message: 'Invalid deliverable request.' }, 400);
+        command = {
+          action: cancelling ? 'cancel' : 'start',
+          request: parsed.data,
+        };
+      } else {
+        command = { action: 'read' };
+      }
+      const auth = c.get('auth');
+      const result = await userStub(c.env, auth.userDid).topicDeliverable(
+        identityOf(auth, c.req.raw.headers),
+        operationId.data,
+        command,
+      );
+      return result.ok
+        ? c.json(result.snapshot)
+        : c.json({ message: result.message }, result.status);
+    },
+  );
+
+  // --- artefacts (owner) ---------------------------------------------------------
+  app.get('/artifacts/:artifactId', async (c) => {
+    const identity = identityOf(c.get('auth'), c.req.raw.headers);
+    const artifactId = c.req.param('artifactId');
+    const artifact = ARTIFACT_ID_RE.test(artifactId)
+      ? await userStub(c.env, identity.userDid).artifact(identity, artifactId)
+      : null;
+    return artifact
+      ? c.json(artifact)
+      : c.json({ statusCode: 404, message: 'Artefact not found' }, 404);
+  });
+  app.delete('/artifacts/:artifactId', async (c) => {
+    const identity = identityOf(c.get('auth'), c.req.raw.headers);
+    const artifactId = c.req.param('artifactId');
+    const revoked =
+      ARTIFACT_ID_RE.test(artifactId) &&
+      (await userStub(c.env, identity.userDid).revokeArtifact(
+        identity,
+        artifactId,
+      ));
+    return revoked
+      ? c.json({ revoked: true })
+      : c.json({ statusCode: 404, message: 'Artefact not found' }, 404);
+  });
+
   // --- messages ----------------------------------------------------------------
-  app.post('/messages/abort', async (c) => {
+  app.post('/messages/abort', limitBody(ABORT_BODY_BYTES), async (c) => {
     const identity = identityOf(c.get('auth'), c.req.raw.headers);
     const body = (await c.req.json().catch(() => ({}))) as {
       sessionId?: string;
@@ -280,10 +669,43 @@ export function createShell(
       identity,
       c.req.param('sessionId'),
     );
-    return new Response(`{"messages":${messages}}`, {
-      headers: { 'content-type': 'application/json' },
-    });
+    return new Response(
+      withFeedbackCapability(`{"messages":${messages}}`, !!opts.feedback),
+      { headers: { 'content-type': 'application/json' } },
+    );
   });
+  // Anonymous feedback on one completed Agent reply (src/feedback/submit.ts).
+  app.post(
+    '/messages/:sessionId/:messageId/feedback',
+    bodyLimit({
+      maxSize: FEEDBACK_BODY_MAX_BYTES,
+      onError: (c) =>
+        c.json({ statusCode: 413, message: 'request entity too large' }, 413),
+    }),
+    async (c) => {
+      if (!opts.feedback) {
+        const off = feedbackFailure(
+          404,
+          'FEEDBACK_DISABLED',
+          'Anonymous feedback is not enabled on this oracle',
+        );
+        return c.json(off.body, off.status);
+      }
+      const identity = identityOf(c.get('auth'), c.req.raw.headers);
+      const result = await submitFeedback({
+        options: opts.feedback,
+        user: userStub(c.env, identity.userDid),
+        identity,
+        sessionId: c.req.param('sessionId'),
+        messageId: c.req.param('messageId'),
+        body: await c.req.json<unknown>().catch(() => undefined),
+        clientIp: c.req.header('cf-connecting-ip'),
+        ipLimiter: c.env.FEEDBACK_RATE_LIMIT ?? c.env.RATE_LIMIT,
+        log: console,
+      });
+      return c.json(result.body, result.status);
+    },
+  );
   // One turn-aligned page of the transcript (docs/plans/transcript-paging.md):
   // the newest `limit` turns, the turns `before=` a cursor, or what came
   // `after=` one. The legacy listing above stays the whole transcript.
@@ -299,7 +721,7 @@ export function createShell(
     );
     if (!page.ok)
       return c.json({ statusCode: page.status, message: page.message }, 400);
-    return new Response(page.json, {
+    return new Response(withFeedbackCapability(page.json, !!opts.feedback), {
       headers: { 'content-type': 'application/json' },
     });
   });
@@ -332,53 +754,64 @@ export function createShell(
     );
     return new Response(res.body, { status: res.status, headers });
   });
-  app.post('/messages/:sessionId', async (c) => {
-    const identity = identityOf(c.get('auth'), c.req.raw.headers);
-    const sessionId = c.req.param('sessionId');
-    const body = await c.req.text();
-    // Bounds the memory one request can pin (see turn-body-cap.ts); the
-    // status and message are the ones Node's body parser uses.
-    if (turnBodyTooLarge(body)) {
-      return c.json(
-        { statusCode: 413, message: 'request entity too large' },
-        413,
-      );
-    }
-    // Node accepts a client-supplied `requestId` (correlates the SSE events
-    // with the client's own bookkeeping); fall back to a fresh UUID.
-    const requestId = clientRequestId(body) ?? crypto.randomUUID();
-    // The user object owns the turn; it returns either an SSE stream or JSON.
-    // We pass the raw body through so attachments/tools/agActions survive.
-    const res = await userStub(c.env, identity.userDid).fetch(
-      `https://user-oracle/turn/${encodeURIComponent(sessionId)}`,
-      {
-        method: 'POST',
-        headers: {
-          'content-type': 'application/json',
-          'x-request-id': requestId,
-          'x-identity': JSON.stringify(identity),
+  // The cap bounds the memory one request can pin (see turn-body-cap.ts); it
+  // is enforced before the body is read, with the status and message Node's
+  // body parser uses.
+  app.post(
+    '/messages/:sessionId',
+    limitBody(MAX_TURN_BODY_BYTES),
+    async (c) => {
+      const identity = identityOf(c.get('auth'), c.req.raw.headers);
+      const sessionId = c.req.param('sessionId');
+      const body = await c.req.text();
+      // Node accepts a client-supplied `requestId` (correlates the SSE events
+      // with the client's own bookkeeping); fall back to a fresh UUID.
+      const requestId = clientRequestId(body) ?? crypto.randomUUID();
+      // The user object owns the turn; it returns either an SSE stream or JSON.
+      // We pass the raw body through so attachments/tools/agActions survive.
+      const res = await userStub(c.env, identity.userDid).fetch(
+        `https://user-oracle/turn/${encodeURIComponent(sessionId)}`,
+        {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+            'x-request-id': requestId,
+            'x-identity': JSON.stringify(identity),
+          },
+          body,
         },
-        body,
-      },
-    );
-    const headers = new Headers(res.headers);
-    headers.set('x-request-id', requestId);
-    headers.set('access-control-expose-headers', 'x-request-id');
-    return new Response(res.body, { status: res.status, headers });
-  });
+      );
+      const headers = new Headers(res.headers);
+      headers.set('x-request-id', requestId);
+      headers.set('access-control-expose-headers', 'x-request-id');
+      return new Response(res.body, { status: res.status, headers });
+    },
+  );
 
   // --- delegation (room-state persisted, for header-less Matrix turns) -----------
-  app.post('/delegation', async (c) => {
+  app.post('/delegation', limitBody(DELEGATION_BODY_BYTES), async (c) => {
     const auth = c.get('auth');
-    const body = (await c.req.json().catch(() => ({}))) as {
-      raw?: string;
-      expiration?: number;
-    };
+    const body = (await c.req.json().catch(() => ({}))) as { raw?: string };
     const raw = body.raw ?? auth.delegation;
     if (!raw) return c.json({ message: 'raw delegation is required' }, 400);
+    // What is stored here authorizes header-less turns long after this
+    // request, so it gets the header's checks: for this oracle, issued by
+    // the caller, with a bounded expiry — and that expiry is the token's,
+    // never a value the client states beside it.
+    const checked = await validateDelegation(raw, authConfigFromEnv(c.env));
+    if (!checked.ok)
+      return c.json(
+        { message: `Invalid UCAN delegation: ${checked.error}` },
+        400,
+      );
+    if (checked.userDid !== auth.userDid)
+      return c.json(
+        { message: 'The delegation was not issued by the authenticated user' },
+        403,
+      );
     const room = await gateway(c.env).resolveUserRoom(auth.userDid);
     if (!room) return c.json({ message: 'No oracle room for this user' }, 404);
-    const expiration = body.expiration ?? auth.delegationExpiration;
+    const { expiration } = checked;
     // The Node runtime's `DelegationStore` record, in its compressed
     // room-state envelope, so a user can move between runtimes without
     // re-authorising (`updatedAt` is required by Node's schema).
@@ -390,7 +823,7 @@ export function createShell(
           raw,
           issuer: auth.userDid,
           audience: c.env.ORACLE_DID,
-          ...(expiration && { expiration }),
+          expiration,
           updatedAt: new Date().toISOString(),
         }),
       ),
@@ -406,10 +839,7 @@ export function createShell(
           `[shell] could not push the deposited delegation to ${auth.userDid}'s object: ${err instanceof Error ? err.message : String(err)}`,
         );
       });
-    return c.json({
-      ok: true,
-      expiration: body.expiration ?? auth.delegationExpiration,
-    });
+    return c.json({ ok: true, expiration });
   });
   app.get('/delegation', async (c) => {
     const auth = c.get('auth');
@@ -477,6 +907,7 @@ export function createShell(
   // so every route is proxied there — same pattern as streaming turns. The
   // shell only short-circuits the disabled case so stray requests never boot
   // a Durable Object.
+  app.use('/byo-llm/*', limitBody(BYO_LLM_BODY_BYTES));
   app.all('/byo-llm/*', async (c) => {
     if (c.env.BYO_LLM_ENABLED !== 'true') {
       return c.req.method === 'GET' && c.req.path === '/byo-llm/status'
@@ -514,6 +945,20 @@ export function createShell(
       return c.json({ statusCode: 404, message: 'Not found' }, 404);
     return next();
   });
+  app.use('/debug/*', limitBody(DEBUG_BODY_BYTES));
+  // The gateway-wide routes act on the one gateway every user depends on
+  // (stop, restart, reset, rotate, every user's outbox). With
+  // ORACLE_OPERATOR_DIDS set only those DIDs may call them; unset, any
+  // authenticated caller may (local and devnet drills).
+  app.use('/debug/matrix/*', async (c, next) => {
+    const operators = operatorDids(c.env);
+    if (operators && !operators.has(c.get('auth').userDid))
+      return c.json(
+        { statusCode: 403, message: 'Operator routes are restricted' },
+        403,
+      );
+    return next();
+  });
   app.get('/debug/storage', async (c) =>
     c.json(await userStub(c.env, c.get('auth').userDid).storageStatus()),
   );
@@ -533,7 +978,11 @@ export function createShell(
     );
   });
   app.post('/debug/storage/reset', async (c) =>
-    c.json(await userStub(c.env, c.get('auth').userDid).resetWorkingCopy()),
+    c.json(
+      await userStub(c.env, c.get('auth').userDid).resetWorkingCopy(
+        identityOf(c.get('auth'), c.req.raw.headers),
+      ),
+    ),
   );
   app.post('/debug/object/abort', async (c) => {
     try {
@@ -665,7 +1114,15 @@ export function createShell(
     ),
   );
   app.onError((err, c) => {
-    console.error(`[shell] ${c.req.method} ${c.req.path} failed:`, err);
+    // Thrown on purpose with a status and a message meant for the client.
+    if (err instanceof HTTPException) return err.getResponse();
+    if (err instanceof ChannelError)
+      return c.json({ code: err.code, message: err.message }, err.status);
+    const requestId = errorRequestId(c.req.header('x-request-id'));
+    console.error(
+      `[shell] ${c.req.method} ${loggedRoute(c)} failed (request ${requestId}):`,
+      err,
+    );
     // A cold boot that could not read the user's owner copy changed nothing.
     // Say precisely why: 503 + retryable for a transient store/VFS failure
     // (the object already retried with backoff), 403 for a missing
@@ -686,9 +1143,16 @@ export function createShell(
         failure.httpStatus,
       );
     }
+    // Anything else may carry internals (SQL, homeserver or Blocksync error
+    // text, room ids): the client gets a generic message and the id that
+    // finds the details in the log.
     return c.json(
-      { statusCode: 500, message: err.message || 'Internal error' },
+      { statusCode: 500, message: 'Internal server error', requestId },
       500,
+      {
+        'x-request-id': requestId,
+        'access-control-expose-headers': 'x-request-id',
+      },
     );
   });
 
@@ -697,6 +1161,11 @@ export function createShell(
 
 const REQUEST_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
 
+/** The client's `x-request-id` when it is a sane opaque token, else a fresh one. */
+function errorRequestId(header: string | undefined): string {
+  return header && REQUEST_ID_RE.test(header) ? header : crypto.randomUUID();
+}
+
 /** The body's `requestId` when it is a sane opaque token; null otherwise. */
 function clientRequestId(rawBody: string): string | null {
   try {
@@ -711,6 +1180,17 @@ function clientRequestId(rawBody: string): string | null {
   return null;
 }
 
+/**
+ * The route pattern a request matched (`/messages/:sessionId`), never the
+ * concrete path: a path carries session and message ids, and a log line
+ * that pairs them with the caller's DID could tie an anonymous feedback
+ * submission to its author. In a middleware `c.req.routePath` is the
+ * middleware's own `*`, so the handler's pattern (the last match) is used.
+ */
+function loggedRoute(c: Parameters<typeof routePath>[0]): string {
+  return routePath(c, -1) || '(unmatched)';
+}
+
 function identityOf(auth: AuthResult, headers: Headers): TurnIdentity {
   return {
     userDid: auth.userDid,