@christianirack/brainllm-runtime 0.6.1 → 0.8.0

package/server/server.mjs

@@ -6,6 +6,7 @@
 //
 // It serves, in this order:
 //   GET  /_health                → 200 {"ok":true,"build":"<sig>"}
+//   GET  /health[/live|/ready]   → forwarded to the native backend, or 200 {"ok":true} without one
 //   POST /_r/<hash>/<fn>         → RPC to a `server:` function (same origin + X-Brain-RPC; body, rate and time limits from brain.json `server`)
 //   GET  routes in the manifest  → SSR: load(ctx) → render the view on the DOM shim → page with props and SEO head
 //   GET  files in dist/          → static (the smallest accepted .zst/.br/.gz sibling; /_b/* immutable), clean URLs
@@ -18,11 +19,14 @@
 // A page template (`page`) is the route's final HTML with `<!--brain:ssr-->` inside #brain-view and
 // `<!--brain:props-->` inside <script type="application/json" id="brain-props">.
 import { createServer as http, STATUS_CODES, request as httpRequest, Agent as HttpAgent } from 'node:http'
+import { AsyncLocalStorage } from 'node:async_hooks'
 import net from 'node:net'
 import { installNativeSockets } from './native-sockets.mjs'
+import { llmClient } from './llm.mjs'
+import { BlockList, isIP } from 'node:net'
 import { Readable } from 'node:stream'
 import zlib from 'node:zlib'
-import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto'
+import { createCipheriv, createDecipheriv, createHash, createHmac, hkdfSync, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto'
 import { existsSync, readFileSync, realpathSync, statSync, lstatSync } from 'node:fs'
 import * as Module from 'node:module'
 import { basename, dirname, extname, join, normalize, resolve, sep } from 'node:path'
@@ -47,7 +51,7 @@ const SECURITY = {
   'permissions-policy': 'camera=(), microphone=(), geolocation=(), payment=(), usb=()',
   'cross-origin-opener-policy': 'same-origin',
   // what serves the app and where it lives, for crawlers and LLMs that read headers (no version: that stays in the HTML)
-  'x-powered-by': 'BRAINLLM (https://chrisifm.github.io/BRAINLLM/)',
+  'x-generated-by': 'BRAINLLM (https://chrisifm.github.io/BRAINLLM/; https://github.com/chrisifm/BRAINLLM)',
 }
 // The build's policy (manifest `csp`, without hashes: the same one static hosting uses) plus this response's nonce in
 // script-src; without it, a default that lets api() reach HTTPS APIs of other origins.
@@ -68,7 +72,7 @@ const b64u = b => Buffer.from(b).toString('base64url')
 const tag = s => createHash('sha1').update(s).digest('base64url').slice(0, 22)
 
 // Errors a server function may throw on purpose: { errors: { field: msg } } → 422; { status, message } with 4xx → that
-const LIST_OPTIONS = ['search','limit','offset','filter','sort','cursor','after','include','aggregate','count']
+const LIST_OPTIONS = ['search','limit','offset','filter','sort','cursor','after','include','aggregate','count','fields','owner']
 const FILTER_OPS = ['eq','ne','gt','gte','lt','lte','between','in','exists','prefix','iprefix','has']
 export class HttpError extends Error {
   constructor(status, message, extra) {
@@ -103,6 +107,24 @@ function safeLocation(value) {
   if (typeof value !== 'string' || value.length > 8192 || !value.startsWith('/') || value.startsWith('//') || /[\\\x00-\x20\x7f]/.test(value) || /^\/%2f/i.test(value) || /%(?:0[0-9a-f]|1[0-9a-f]|5c|7f)/i.test(value) || /%20/i.test(value.split(/[?#]/,1)[0])) throw new HttpError(500, 'Invalid same-site redirect location')
   return value
 }
+// Internal links keep the page's language (§37): `route.hrefs` is the table of a page outside the default language, the
+// one brain-links.js applies in the browser; `b` is the base path, added later here.
+function linkTo(route, path) {
+  const t = route && route.hrefs
+  if (!t || typeof path !== 'string' || path[0] !== '/' || path[1] === '/') return path
+  const m = /^[^?#]*/.exec(path)[0]
+  const n = t.s[m] || (new RegExp(t.re).test(m) && (m === '/' ? t.p : t.p + m))
+  return n ? n + path.slice(m.length) : path
+}
+function localizeLinks(route, html) {
+  if (!route.hrefs) return html
+  const b = (globalThis.__brainBase || '/').slice(0, -1) // render() set it for this page
+  return html.replace(/<(?:a|form)\s[^>]*>/g, tag => /\shreflang=/.test(tag) ? tag : tag.replace(/(\s(?:href|action)=")(\/[^"]*)"/, (all, at, h) => {
+    const a = b && (h + '/').startsWith(b + '/') ? h.slice(b.length) || '/' : h
+    return at + (a === h ? linkTo(route, a) : b + linkTo(route, a)) + '"'
+  }))
+}
+
 // `throw redirect('/login')` (or return it) from load/guards; same-site paths only.
 export const redirect = (url, status = 303) => {
   if (!REDIRECT_CODES.has(status)) throw new HttpError(500, 'Invalid redirect status')
@@ -187,8 +209,64 @@ function googleSignInPage(page) {
 }
 
 // One configured loopback authority. No user-controlled target, proxy, redirect, auth cache or pending queue.
-export function nativeAuthBridge(raw) {
+// ctx.backend.files(bucket): the same file calls as job and route handlers (docs/backend/files.md).
+function bucketClient(target, key, bucket) {
+  const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i
+  if (typeof bucket !== 'string' || !/^[a-z][a-z0-9_]{0,47}$/.test(bucket)) throw new HttpError(400, 'Invalid native bucket name')
+  const base = '/_brain/files/' + bucket
+  const idPath = id => { if (typeof id !== 'string' || !UUID.test(id)) throw new HttpError(404, 'No file has this id; file ids are UUIDs'); return base + '/' + id }
+  const send = async (method, path, body, timeout) => {
+    let response
+    try { response = await fetch(new URL(path, target), { method, redirect: 'error', signal: AbortSignal.timeout(timeout), headers: { 'x-api-key': key }, body }) } catch { throw new HttpError(503, 'Native backend is unavailable') }
+    if (response.ok) return response
+    await response.body?.cancel()
+    throw new HttpError(response.status >= 400 && response.status < 500 ? response.status : 503, 'Native file request failed')
+  }
+  const json = async response => { try { return await response.json() } catch { throw new HttpError(502, 'Native file response is invalid') } }
+  return Object.freeze({
+    async list(options = {}) {
+      if (!options || typeof options !== 'object' || Array.isArray(options) || Object.keys(options).some(k => !['limit', 'offset', 'record'].includes(k))) throw new HttpError(400, 'Invalid native file list options')
+      const { limit, offset, record } = options
+      if ((limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 100)) || (offset !== undefined && (!Number.isInteger(offset) || offset < 0 || offset > 10000)) || (record !== undefined && !UUID.test(String(record)))) throw new HttpError(400, 'Invalid native file list options')
+      const q = new URLSearchParams(Object.entries({ limit, offset, record }).filter(([, v]) => v !== undefined))
+      return json(await send('GET', base + (q.size ? '?' + q : ''), undefined, 10000))
+    },
+    async meta(id) { return json(await send('GET', idPath(id) + '/meta', undefined, 10000)) },
+    async read(id, { maxBytes = 16 * 1024 * 1024 } = {}) {
+      if (!Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > 64 * 1024 * 1024) throw new HttpError(400, 'Invalid native file read limit')
+      const response = await send('GET', idPath(id), undefined, 30000)
+      if (Number(response.headers.get('content-length')) > maxBytes) { await response.body?.cancel(); throw new HttpError(413, 'The file exceeds the read limit; raise maxBytes up to 64 MiB') }
+      const bytes = Buffer.from(await response.arrayBuffer())
+      if (bytes.length > maxBytes) throw new HttpError(413, 'The file exceeds the read limit; raise maxBytes up to 64 MiB')
+      return { bytes, contentType: response.headers.get('content-type'), etag: response.headers.get('etag') }
+    },
+    async upload({ filename, contentType = 'application/octet-stream', data, record } = {}) {
+      if (typeof filename !== 'string' || !filename || Buffer.byteLength(filename) > 255 || typeof contentType !== 'string' || (record !== undefined && !UUID.test(String(record)))) throw new HttpError(400, 'Invalid native file upload')
+      if (typeof data !== 'string' && !(data instanceof Uint8Array)) throw new HttpError(400, 'File data must be a string, Buffer or Uint8Array')
+      const form = new FormData()
+      form.set('file', new Blob([data], { type: contentType }), filename)
+      return json(await send('POST', base + (record === undefined ? '' : '?record=' + record), form, 60000))
+    },
+    async remove(id) { await send('DELETE', idPath(id), undefined, 10000); return null },
+  })
+}
+export function nativeAuthBridge(raw, refused, serviceKey, report) {
+  // How to fix the configuration is for the operator: a visitor of a production app reads a generic message.
+  const configuration = (status, detail, rid, shown = 'This service is not available right now') => {
+    if (process.env.NODE_ENV !== 'production') return new HttpError(status, detail)
+    report?.('error', 'native backend configuration', { rid, fix: detail })
+    return new HttpError(status, shown)
+  }
   if (!raw) return null
+  // The visitor's cookies only travel for a request from the site itself; the caller's log gets the reason (B0742).
+  const bridgeOrigin = (incoming, rid, message) => {
+    try {
+      const origin = new URL(incoming.headers.origin)
+      if (origin.origin === incoming.headers.origin && origin.host === (incoming.headers['x-forwarded-host'] || incoming.headers.host)) return origin.origin
+    } catch {}
+    if (refused) refused('B0742', incoming, rid, 'native')
+    throw new HttpError(403, 'B0742: ' + message)
+  }
   if (typeof raw !== 'string' || raw.length > 2048) throw Error('BRAIN_BACKEND_URL must be an explicit loopback HTTP origin')
   let target
   try { target = new URL(raw) } catch { throw Error('BRAIN_BACKEND_URL must be an explicit loopback HTTP origin') }
@@ -218,6 +296,7 @@ export function nativeAuthBridge(raw) {
   const call = (incoming, response, path, method, rid, origin) => {
     if (stopped || active >= 8) return Promise.reject(unavailable())
     const cookie = cookies(incoming, method === 'POST')
+    const client = forwardedFor(incoming)
     active++
     return new Promise((resolve, reject) => {
       let outgoing, timer, finished = false
@@ -231,7 +310,7 @@ export function nativeAuthBridge(raw) {
       const cancel = () => outgoing?.destroy(unavailable())
       const disconnected = () => { if (!response.writableEnded) cancel() }
       try {
-        outgoing = httpRequest(new URL(path, target), { method, agent, headers: { accept: 'application/json', ...(cookie ? { cookie } : {}), 'x-request-id': rid, ...(origin ? { origin } : {}), ...(method === 'POST' ? { 'content-length': '0' } : {}) } }, backend => {
+        outgoing = httpRequest(new URL(path, target), { method, agent, headers: { accept: 'application/json', ...(cookie ? { cookie } : {}), 'x-request-id': rid, ...(client ? { 'x-forwarded-for': client } : {}), ...(origin ? { origin } : {}), ...(method === 'POST' ? { 'content-length': '0' } : {}) } }, backend => {
           let bytes = 0; const chunks = []
           if (backend.headers['content-encoding'] || Number(backend.headers['content-length']) > 16384) { backend.destroy(); return finish(true) }
           backend.on('data', chunk => { bytes += chunk.length; if (bytes > 16384) { backend.destroy(); finish(true) } else chunks.push(chunk) })
@@ -260,27 +339,136 @@ export function nativeAuthBridge(raw) {
       } catch { outgoing?.destroy(); finish(true) }
     })
   }
-  let proxyBytes = 0
-  function proxy(req, res, url, rid, reply, responseLimit = 20 * 1024 * 1024) {
+  // The access cookie lives 5 minutes and the session far longer: a password JWT session would read as anonymous on the
+  // next page. The backend answers concurrent refreshes with the same token inside its grace window, so tabs and
+  // prefetches cannot revoke the family. A denied refresh is anonymous; an unavailable backend stays an error.
+  const renew = (req, res, rid) => {
+    const selected = cookies(req, true)
+    let origin
+    try { origin = new URL(process.env.PUBLIC_SITE_URL).origin } catch { origin = 'https://' + (req.headers['x-forwarded-host'] || req.headers.host) }
+    return new Promise((resolve, reject) => {
+      if (stopped || active >= 8) return reject(unavailable())
+      active++
+      let settled = false
+      const done = (error, value) => { if (settled) return; settled = true; active--; clearTimeout(timer); error ? reject(unavailable()) : resolve(value) }
+      const outgoing = httpRequest(new URL('/_brain/auth/refresh', target), { method: 'POST', agent, headers: { accept: 'application/json', cookie: selected, origin, 'x-request-id': rid, 'content-length': '0' } }, backend => {
+        let bytes = 0; const chunks = []
+        backend.on('data', chunk => { bytes += chunk.length; if (bytes > 16384) { backend.destroy(); done(true) } else chunks.push(chunk) })
+        backend.on('error', () => done(true))
+        backend.on('end', () => {
+          if (backend.statusCode === 401 || backend.statusCode === 403) return done(false)
+          if (backend.statusCode !== 200) return done(true)
+          try {
+            const user = safeUser(JSON.parse(Buffer.concat(chunks).toString('utf8'))?.user)
+            const set = (backend.headers['set-cookie'] || []).filter(value => /^__Host-brain-(?:access|refresh)=/.test(value) && value.length <= 8192 && !/[\r\n]/.test(value))
+            if (!set.some(value => value.startsWith('__Host-brain-access='))) return done(true)
+            req.$nativeUser = user
+            req.$nativeLoginHeaders = { 'set-cookie': set, 'cache-control': 'no-store' }
+            // later backend calls of this same request use the new tokens
+            const fresh = new Map(set.map(value => { const pair = value.split(';', 1)[0], at = pair.indexOf('='); return [pair.slice(0, at), pair.slice(at + 1)] }))
+            const kept = (req.headers.cookie || '').split(';').map(part => part.trim()).filter(part => part && !fresh.has(part.split('=', 1)[0]))
+            req.headers.cookie = [...kept, ...[...fresh].map(([name, value]) => name + '=' + value)].join('; ')
+            done(false)
+          } catch { done(true) }
+        })
+      })
+      const timer = setTimeout(() => outgoing.destroy(unavailable()), 2000)
+      owned.add(outgoing); outgoing.once('close', () => owned.delete(outgoing))
+      outgoing.once('error', () => done(true)); outgoing.end()
+    })
+  }
+  let proxyBytes = 0, streams = 0
+  // A file transfer lasts as long as the client needs, so streams have their own sockets and budget and never hold API slots.
+  const streamAgent = new HttpAgent({ keepAlive: false, maxSockets: 32, maxTotalSockets: 32 })
+  const REQUEST_HEADERS = ['origin','authorization','x-api-key','content-type','content-length','x-brain-rpc','accept','if-match','if-none-match','x-brain-webhook-id','x-brain-webhook-timestamp','x-brain-webhook-signature','user-agent','dnt','sec-gpc','cf-ipcountry']
+  const FILE_HEADERS = ['range','if-range','if-modified-since','if-unmodified-since']
+  const RESPONSE_HEADERS = ['content-type','content-disposition','allow','retry-after','www-authenticate','location','etag','last-modified','clear-site-data','cache-control']
+  const FILE_RESPONSE_HEADERS = ['content-length','content-range','accept-ranges','vary','content-security-policy','x-content-type-options','cross-origin-resource-policy','referrer-policy']
+  // The identity the backend resolves through trustProxy: the hops already received plus the peer this gateway observed.
+  // Hops to the left of an untrusted peer are ignored by the backend, so a client header can never choose the identity.
+  const forwardedFor = req => {
+    if (req.$brainForwardedFor) return req.$brainForwardedFor
+    const peer = req.socket?.remoteAddress
+    if (!peer) return undefined
+    const prior = req.headers['x-forwarded-for']
+    return typeof prior === 'string' && prior.length <= 4096 ? prior + ', ' + peer : peer
+  }
+  const requestHeaders = (req, rid, extra = []) => {
+    const headers = { 'x-request-id':rid }
+    for (const key of [...REQUEST_HEADERS, ...extra]) {
+      const value = req.headers[key]
+      if (typeof value === 'string' && value.length <= 8192) headers[key] = value
+    }
+    const selected = []
+    for (const part of String(req.headers.cookie || '').split(';')) {
+      const name = part.trim().split('=')[0]
+      if (['__Host-brain','__Host-brain-access','__Host-brain-refresh','__Host-brain-google'].includes(name)) selected.push(part.trim())
+    }
+    if (selected.length) headers.cookie = selected.join('; ')
+    const client = forwardedFor(req)
+    if (client) headers['x-forwarded-for'] = client
+    return headers
+  }
+  const nativeCookies = values => (values || []).filter(value => /^(?:__Host-brain(?:-access|-refresh|-google)?)=/.test(value) && value.length <= 8192).slice(0,8)
+  // /_brain/files: both directions stream with backpressure. The bucket enforces its own maxBytes and access checks.
+  function fileStream(req, res, url, rid) {
+    if (stopped || streams >= 32) throw new HttpError(503, 'Backend stream capacity is unavailable')
+    if (!['GET','HEAD','POST','DELETE'].includes(req.method)) throw new HttpError(405, 'Method not allowed')
+    const ceiling = 2 * 1024 * 1024 * 1024 + 1024 * 1024
+    if (Number(req.headers['content-length'] || 0) > ceiling) throw new HttpError(413, 'Request body is too large')
+    clearTimeout(req.$brainBodyGuard)
+    streams++
+    return new Promise((resolve, reject) => {
+      let outgoing, deadline, done = false, sent = 0
+      const finish = failure => {
+        if (done) return
+        done = true; streams--; clearTimeout(deadline); owned.delete(outgoing)
+        req.unpipe(outgoing); req.removeListener('data', count); res.removeListener('close', closed)
+        if (failure && !res.headersSent && !res.destroyed) return reject(failure)
+        if (failure && !res.destroyed) res.destroy()
+        outgoing?.destroy(); resolve()
+      }
+      const closed = () => finish()
+      const count = chunk => { sent += chunk.length; if (sent > ceiling) finish(new HttpError(413, 'Request body is too large')) }
+      const unavailable = () => new HttpError(503, 'Backend request unavailable')
+      try {
+        outgoing = httpRequest(new URL(url.pathname + url.search, target), { agent:streamAgent, method:req.method, headers:requestHeaders(req, rid, FILE_HEADERS) }, backend => {
+          const safe = { 'cache-control':'no-store' }
+          for (const key of [...RESPONSE_HEADERS, ...FILE_RESPONSE_HEADERS]) {
+            const value = backend.headers[key]
+            if (typeof value === 'string' && value.length <= 8192) safe[key] = value
+          }
+          const cookies = nativeCookies(backend.headers['set-cookie'])
+          if (cookies.length) safe['set-cookie'] = cookies
+          res.writeHead(backend.statusCode || 502, safe)
+          backend.once('error', () => finish(unavailable()))
+          backend.once('aborted', () => finish(unavailable()))
+          backend.once('end', () => { res.end(() => finish()) })
+          backend.pipe(res)
+        })
+        owned.add(outgoing)
+        // No progress in either direction (a stalled backend, or a client that stopped reading and paused the socket).
+        outgoing.setTimeout(60000, () => finish(new HttpError(504, 'Backend request timed out')))
+        // The backend's own upload deadline is 300 s; nothing else needs a total limit after the headers.
+        if (req.method === 'POST') deadline = setTimeout(() => finish(new HttpError(504, 'Backend request timed out')), 310000)
+        outgoing.once('error', () => finish(unavailable()))
+        res.once('close', closed)
+        req.on('data', count)
+        req.pipe(outgoing)
+      } catch { finish(unavailable()) }
+    })
+  }
+  function proxy(req, res, url, rid, reply, responseLimit = 20 * 1024 * 1024, declared) {
     if (stopped || active >= 8) throw new HttpError(503, 'Backend request capacity is unavailable')
     if (!['GET','HEAD','POST','PUT','PATCH','DELETE','OPTIONS'].includes(req.method)) throw new HttpError(405, 'Method not allowed')
-    const limit = url.pathname === '/_brain/uploads' && req.method === 'POST' ? 5 * 1024 * 1024 + 65536 : 65536
+    const post = req.method === 'POST'
+    const limit = url.pathname === '/_brain/uploads' && post ? 5 * 1024 * 1024 + 65536 : declared || post && /^\/api\/[^/]+\/batch$/.test(url.pathname) ? 1024 * 1024 : 65536
     if (Number(req.headers['content-length'] || 0) > limit) throw new HttpError(413, 'Request body is too large')
     active++
     return new Promise((resolve, reject) => {
       let outgoing, timer, done = false, bytes = 0, requestBytes = 0, failure
       const chunks = []
-      const headers = { 'x-request-id':rid }
-      for (const key of ['origin','authorization','content-type','content-length','x-brain-rpc','accept','x-brain-webhook-id','x-brain-webhook-timestamp','x-brain-webhook-signature','user-agent','dnt','sec-gpc','cf-ipcountry']) {
-        const value = req.headers[key]
-        if (typeof value === 'string' && value.length <= 8192) headers[key] = value
-      }
-      const selected = []
-      for (const part of String(req.headers.cookie || '').split(';')) {
-        const name = part.trim().split('=')[0]
-        if (['__Host-brain','__Host-brain-access','__Host-brain-refresh','__Host-brain-google'].includes(name)) selected.push(part.trim())
-      }
-      if (selected.length) headers.cookie = selected.join('; ')
+      const headers = requestHeaders(req, rid, declared?.headers)
       const finish = (error, backend) => {
         if (done) return
         done = true; clearTimeout(timer); active--; proxyBytes -= bytes; owned.delete(outgoing)
@@ -288,12 +476,16 @@ export function nativeAuthBridge(raw) {
         res.removeListener('close',cancel)
         if (error) { if (!res.destroyed) reject(failure || new HttpError(503,'Backend request unavailable')); else resolve(); return }
         const safe = { 'cache-control':'no-store' }
-        for (const key of ['content-type','content-disposition','allow','retry-after','www-authenticate','location','etag','last-modified','clear-site-data']) {
+        for (const key of RESPONSE_HEADERS) {
           const value = backend.headers[key]
           if (typeof value === 'string' && value.length <= 8192) safe[key] = value
         }
-        const cookies = (backend.headers['set-cookie'] || []).filter(value => /^(?:__Host-brain(?:-access|-refresh|-google)?)=/.test(value) && value.length <= 8192)
-        if (cookies.length) safe['set-cookie'] = cookies.slice(0,8)
+        // the response headers a route contract allows its handler to set (docs/backend/routes.md)
+        if (declared) for (const [key, value] of Object.entries(backend.headers)) {
+          if ((key === 'link' || key === 'content-language' || key.startsWith('x-') && key !== 'x-request-id') && typeof value === 'string' && value.length <= 8192) safe[key] = value
+        }
+        const cookies = nativeCookies(backend.headers['set-cookie'])
+        if (cookies.length) safe['set-cookie'] = cookies
         try { reply(res,backend.statusCode || 502,req.method === 'HEAD' ? '' : Buffer.concat(chunks,bytes),safe); resolve() } catch (e) { reject(e) }
       }
       const cancel = () => { outgoing?.destroy(); finish(true) }
@@ -313,17 +505,17 @@ export function nativeAuthBridge(raw) {
           backend.once('end',()=>finish(false,backend)); backend.once('error',()=>finish(true)); backend.once('aborted',()=>finish(true))
         })
         owned.add(outgoing)
-        timer = setTimeout(()=>{failure = new HttpError(504,'Backend request timed out');outgoing.destroy();finish(true)},url.pathname === '/_brain/uploads' || url.pathname.startsWith('/_brain/uploads/') ? 35000 : 10000)
+        timer = setTimeout(()=>{failure = new HttpError(504,'Backend request timed out');outgoing.destroy();finish(true)},declared || url.pathname === '/_brain/uploads' || url.pathname.startsWith('/_brain/uploads/') ? 35000 : 10000)
         outgoing.once('error',()=>finish(true)); req.once('aborted',cancel); res.once('close',cancel)
         req.on('data',data); req.once('end',end)
         if (req.readableEnded) end()
       } catch { outgoing?.destroy(); finish(true) }
     })
   }
-  const resource = (incoming, response, rid, name) => {
+  const resource = (incoming, response, rid, name, serviceKey) => {
     if (typeof name !== 'string' || !/^[a-z][a-z0-9_]{0,47}$/.test(name)) throw new HttpError(400, 'Invalid native resource name')
     const idPath = id => {
-      if (typeof id !== 'string' || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(id)) throw new HttpError(400, 'Invalid native record identifier')
+      if (typeof id !== 'string' || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(id)) throw new HttpError(404, 'No record has this id; record ids are UUIDs')
       return '/api/' + name + '/' + id
     }
     const request = async (method, path, body, notFound) => {
@@ -337,11 +529,11 @@ export function nativeAuthBridge(raw) {
       }
       const req = Readable.from(bytes.length ? [bytes] : [])
       req.method = method
-      req.headers = { cookie: cookies(incoming, false), accept: 'application/json', 'content-type':'application/json', 'content-length':String(bytes.length) }
+      req.$brainForwardedFor = forwardedFor(incoming)
+      // A service call acts as the key's owner, never as the visitor: it sends no session.
+      req.headers = { ...(serviceKey ? { authorization: 'Bearer ' + serviceKey } : { cookie: cookies(incoming, false) }), accept: 'application/json', 'content-type':'application/json', 'content-length':String(bytes.length) }
       if (method !== 'GET') {
-        let origin
-        try { origin = new URL(incoming.headers.origin); if (origin.origin !== incoming.headers.origin || origin.host !== (incoming.headers['x-forwarded-host'] || incoming.headers.host)) throw Error() } catch { throw new HttpError(403, 'Native writes require a same-origin server request') }
-        req.headers.origin = origin.origin
+        req.headers.origin = bridgeOrigin(incoming, rid, 'Native writes require a same-origin server request')
       }
       let value
       try {
@@ -354,7 +546,14 @@ export function nativeAuthBridge(raw) {
             throw new HttpError(422, 'Invalid input', { errors })
           }
           if (status === 404 && notFound) { value = notFound(); return }
-          if (status < 200 || status >= 300) throw new HttpError(status >= 400 && status < 500 ? status : 503, 'Native resource request failed')
+          if (status < 200 || status >= 300) {
+            // the message stays generic; the backend's own code and fix (never driver text) let server code branch on it
+            let answer
+            try { answer = JSON.parse(data.toString('utf8'))?.error } catch {}
+            const code = typeof answer?.code === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(answer.code) ? answer.code : undefined
+            const fix = code && typeof answer.fix === 'string' ? answer.fix.slice(0, 512) : undefined
+            throw new HttpError(status >= 400 && status < 500 ? status : 503, NATIVE_FAILED, { code, fix })
+          }
           if (status === 204) { value = null; return }
           if (!String(headers['content-type'] || '').startsWith('application/json')) throw new HttpError(502, 'Native resource response must be JSON')
           try { value = JSON.parse(data.toString('utf8')) } catch { throw new HttpError(502, 'Native resource response is invalid') }
@@ -365,7 +564,8 @@ export function nativeAuthBridge(raw) {
     }
     const names = (value, label) => {
       const list = typeof value === 'string' ? value.split(',') : value
-      if (!Array.isArray(list) || list.length > 16 || list.some(item => typeof item !== 'string' || !/^[a-z][a-z0-9_]{0,47}$/.test(item))) throw new HttpError(400, `Invalid native ${label} names`)
+      const shape = label === 'include' ? /^[a-z][a-z0-9_]{0,47}(?:\.[a-z][a-z0-9_]{0,47}){0,2}$/ : /^[a-z][a-z0-9_]{0,47}$/
+      if (!Array.isArray(list) || list.length > 16 || list.some(item => typeof item !== 'string' || !shape.test(item))) throw new HttpError(400, `Invalid native ${label} names`)
       return list.join(',')
     }
     return Object.freeze({
@@ -373,7 +573,7 @@ export function nativeAuthBridge(raw) {
       // filters and sorts and answers 422 {errors}; this only rejects shapes the query string cannot express
       list(options = {}) {
         if (!options || typeof options !== 'object' || Array.isArray(options) || Object.keys(options).some(key => !LIST_OPTIONS.includes(key))) throw new HttpError(400, 'Invalid native list options')
-        const {search, limit, offset, filter, sort, cursor, after, include, aggregate, count} = options
+        const {search, limit, offset, filter, sort, cursor, after, include, aggregate, count, fields} = options
         if ((search !== undefined && (typeof search !== 'string' || Buffer.byteLength(search) > 256)) || (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 100)) || (offset !== undefined && (!Number.isInteger(offset) || offset < 0 || offset > 10000))) throw new HttpError(400, 'Invalid native list pagination or search')
         const q = new URLSearchParams()
         if (filter !== undefined) {
@@ -415,7 +615,11 @@ export function nativeAuthBridge(raw) {
           if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{1,2048}$/.test(value)) throw new HttpError(400, 'Invalid native list cursor')
           q.set(key, value)
         }
-        for (const [key, value] of [['include', include], ['aggregate', aggregate], ['count', count]]) if (value !== undefined) q.set(key, names(value, key))
+        for (const [key, value] of [['include', include], ['aggregate', aggregate], ['count', count], ['fields', fields]]) if (value !== undefined) q.set(key, names(value, key))
+        if (options.owner !== undefined) {
+          if (options.owner !== 'me') throw new HttpError(400, "Invalid native list owner; use 'me'")
+          q.set('owner', 'me')
+        }
         const query = q.toString()
         return request('GET', '/api/' + name + (query ? '?' + query : ''))
       },
@@ -431,27 +635,30 @@ export function nativeAuthBridge(raw) {
         if (values && typeof values === 'object' && !Array.isArray(values) && !Object.keys(values).length) throw new HttpError(422, 'Send at least one field', { errors: { body: 'Send at least one field to change' } })
         return request('PATCH', idPath(id), values)
       },
+      // a declared atomic action or state transition (docs/backend/atomic-updates.md); the key still needs `<resource>:write`
+      action: (id, action, input = {}) => request('POST', idPath(id) + '/actions/' + encodeURIComponent(action), input),
+      transition: (id, transition, input = {}) => request('POST', idPath(id) + '/transitions/' + encodeURIComponent(transition), input),
       remove: id => request('DELETE', idPath(id)),
       // an earlier slug of a readable record → its current slug; live, unknown or unreadable slugs → null
       slugRedirect(slug) {
-        if (typeof slug !== 'string' || !/^[A-Za-z0-9._~-]{1,512}$/.test(slug)) throw new HttpError(400, 'Invalid native slug')
+        if (typeof slug !== 'string' || !/^[A-Za-z0-9._~-]{1,512}$/.test(slug)) return Promise.resolve(null)
         return request('GET', '/api/' + name + '/redirects/' + slug, undefined, () => null).then(value => typeof value?.slug === 'string' ? value.slug : null)
       },
     })
   }
   async function login(incoming,response,rid,credentials) {
-    if (incoming.method !== 'POST' || response.headersSent || response.writableEnded || response.destroyed) throw new HttpError(403,'Sign in through a same-origin POST server function')
+    if (incoming.method !== 'POST' || response.headersSent || response.writableEnded || response.destroyed) throw new HttpError(403,'B0742: Sign in through a same-origin POST server function')
     if (incoming.$nativeLoginStarted || incoming.$nativeLogout) throw new HttpError(409,'Use one authentication change per server request')
     if (!credentials || typeof credentials !== 'object' || Array.isArray(credentials) || Object.keys(credentials).some(key=>!['email','password'].includes(key)) || typeof credentials.email !== 'string' || typeof credentials.password !== 'string' || Buffer.byteLength(credentials.email)>254 || Buffer.byteLength(credentials.password)>1024) throw new HttpError(422,'Enter a valid email and password')
-    let origin
-    try { origin=new URL(incoming.headers.origin);if(origin.origin!==incoming.headers.origin || origin.host!==(incoming.headers['x-forwarded-host']||incoming.headers.host))throw Error() }catch{throw new HttpError(403,'Sign in through a same-origin POST server function')}
+    const origin=bridgeOrigin(incoming,rid,'Sign in through a same-origin POST server function')
     incoming.$nativeLoginStarted=true
     const bytes=Buffer.from(JSON.stringify({email:credentials.email,password:credentials.password}))
-    const request=Readable.from([bytes]);request.method='POST';request.headers={origin:origin.origin,accept:'application/json','content-type':'application/json','content-length':String(bytes.length)}
+    const request=Readable.from([bytes]);request.method='POST';request.$brainForwardedFor=forwardedFor(incoming);request.headers={origin,accept:'application/json','content-type':'application/json','content-length':String(bytes.length)}
     let user
     try {
       await proxy(request,response,new URL('/_brain/auth/login',target),rid,(_res,status,data,headers)=>{
-        if(status!==200)throw new HttpError(status===400||status===401||status===422?401:status===429?429:503,status===429?'Too many attempts. Wait before trying again.':status<500?'Wrong email or password':'Sign-in is temporarily unavailable')
+        if(status===403)throw new HttpError(403,"B0740: the backend refused this site's origin; fix: add the site origin to backend.origins in brain.json. The backend log has the seen and allowed origins. Run brain explain B0740")
+        if(status!==200)throw new HttpError(status===400||status===401||status===422?401:status===429?429:503,status===429?'Too many attempts. Wait before trying again.':status===400||status===401||status===422?'Wrong email or password':'Sign-in is temporarily unavailable')
         let payload
         try {payload=JSON.parse(data.toString('utf8'))}catch{throw unavailable()}
         user=safeUser(payload?.user)
@@ -464,11 +671,88 @@ export function nativeAuthBridge(raw) {
     } finally {request.destroy();bytes.fill(0)}
     return {user}
   }
+  // Creates the account and leaves the session alone: `await ctx.backend.signup(v); return ctx.backend.login(v)` signs in
+  // too. A refused address is the email field's error: the same 422 for an invalid one and for one already taken, and no
+  // more than any signup form reveals by succeeding.
+  async function signup(incoming,response,rid,credentials) {
+    if (incoming.method !== 'POST' || response.headersSent || response.writableEnded || response.destroyed) throw new HttpError(403,'B0742: Sign up through a same-origin POST server function')
+    if (!credentials || typeof credentials !== 'object' || Array.isArray(credentials) || Object.keys(credentials).some(key=>!['email','password'].includes(key)) || typeof credentials.email !== 'string' || typeof credentials.password !== 'string' || Buffer.byteLength(credentials.email)>254 || Buffer.byteLength(credentials.password)>1024) throw new HttpError(422,'Enter a valid email and password')
+    if (Buffer.byteLength(credentials.password) < 12 || Buffer.byteLength(credentials.password) > 1024) throw new HttpError(422,'Use a password of 12 to 1024 bytes',{errors:{password:'Use a password of 12 to 1024 bytes'}})
+    const origin=bridgeOrigin(incoming,rid,'Sign up through a same-origin POST server function')
+    const bytes=Buffer.from(JSON.stringify({email:credentials.email,password:credentials.password}))
+    const request=Readable.from([bytes]);request.method='POST';request.$brainForwardedFor=forwardedFor(incoming);request.headers={origin,accept:'application/json','content-type':'application/json','content-length':String(bytes.length)}
+    let user
+    try {
+      await proxy(request,response,new URL('/_brain/auth/signup',target),rid,(_res,status,data)=>{
+        if(status===403)throw new HttpError(403,"B0740: the backend refused this site's origin; fix: add the site origin to backend.origins in brain.json. Run brain explain B0740")
+        if(status===422)throw new HttpError(422,'This email cannot be used',{errors:{email:'This email cannot be used'}})
+        if(status===429)throw new HttpError(429,'Too many attempts. Wait before trying again.')
+        if(status!==200&&status!==201)throw unavailable()
+        try {user=safeUser(JSON.parse(data.toString('utf8'))?.user)}catch{throw unavailable()}
+      },16384)
+    } finally {request.destroy();bytes.fill(0)}
+    return {user}
+  }
+  // Google needs its nonce bound to the browser that asked for it, so both steps relay the HttpOnly nonce cookie. The page
+  // only ever sees the public client id and nonce it hands to Google.
+  const sessionCookie = /^(?:__Host-brain|__Host-brain-access|__Host-brain-refresh|__Host-brain-google)=/
+  const strictCookie = value => /(?:^|;)\s*HttpOnly(?:;|$)/i.test(value) && /(?:^|;)\s*Secure(?:;|$)/i.test(value) && /(?:^|;)\s*Path=\/(?:;|$)/i.test(value) && /(?:^|;)\s*SameSite=Lax(?:;|$)/i.test(value)
+  async function googleStep(incoming,response,rid,path,payload,cookie,read) {
+    if (incoming.method !== 'POST' || response.headersSent || response.writableEnded || response.destroyed) throw new HttpError(403,'Sign in through a same-origin POST server function')
+    if (incoming.$nativeLoginStarted || incoming.$nativeLogout) throw new HttpError(409,'Use one authentication change per server request')
+    let origin
+    try { origin=new URL(incoming.headers.origin);if(origin.origin!==incoming.headers.origin || origin.host!==(incoming.headers['x-forwarded-host']||incoming.headers.host))throw Error() }catch{throw new HttpError(403,'Sign in through a same-origin POST server function')}
+    incoming.$nativeLoginStarted=true
+    const bytes=Buffer.from(JSON.stringify(payload))
+    const request=Readable.from([bytes]);request.method='POST';request.headers={origin:origin.origin,accept:'application/json','content-type':'application/json','content-length':String(bytes.length),...(cookie?{cookie}:{})}
+    let result
+    try {
+      await proxy(request,response,new URL(path,target),rid,(_res,status,data,headers)=>{
+        if(status!==200)throw new HttpError(status===429?429:status<500?401:503,status===429?'Too many attempts. Wait before trying again.':status<500?'Google sign-in was not accepted':'Sign-in is temporarily unavailable')
+        let parsed
+        try {parsed=JSON.parse(data.toString('utf8'))}catch{throw unavailable()}
+        const selected=headers['set-cookie']||[]
+        if(new Set(selected.map(value=>value.split('=',1)[0])).size!==selected.length||!selected.length||selected.length>4||selected.some(value=>!sessionCookie.test(value)||!strictCookie(value)))throw unavailable()
+        result=read(parsed)
+        if(response.writableEnded||response.destroyed)throw unavailable()
+        incoming.$nativeLoginHeaders={'set-cookie':selected,'cache-control':'no-store'}
+      },16384)
+    } finally {request.destroy();bytes.fill(0)}
+    return result
+  }
+  const googleChallenge = (incoming,response,rid) => googleStep(incoming,response,rid,'/_brain/auth/google/challenge',{},null,payload=>{
+    if(typeof payload?.client_id!=='string'||typeof payload?.nonce!=='string'||!/^[a-f0-9]{64}$/.test(payload.nonce)||!Number.isInteger(payload?.expires_in))throw unavailable()
+    return {client_id:payload.client_id,nonce:payload.nonce,expires_in:payload.expires_in}
+  })
+  const googleLogin = (incoming,response,rid,values) => {
+    if(!values||typeof values!=='object'||Array.isArray(values)||Object.keys(values).some(key=>key!=='credential')||typeof values.credential!=='string'||!values.credential||Buffer.byteLength(values.credential)>16384)throw new HttpError(422,'Send the credential Google returned')
+    const nonce=String(incoming.headers.cookie||'').split(';').map(part=>part.trim()).find(part=>part.startsWith('__Host-brain-google='))?.slice('__Host-brain-google='.length)
+    if(!nonce||!/^[a-f0-9]{64}$/.test(nonce))throw new HttpError(401,'Google sign-in was not accepted')
+    return googleStep(incoming,response,rid,'/_brain/auth/google',{credential:values.credential},'__Host-brain-google='+nonce,payload=>{
+      const user=safeUser(payload?.user)
+      return {user}
+    })
+  }
   // ctx.backend for one server request (load, actions, RPC, dev sidecar): the same object everywhere
   const backend = (incoming, response, rid) => Object.freeze({
     resource: name => resource(incoming, response, rid, name),
+    // A server-only resource (`api: false`) from trusted server code, with BRAIN_SERVICE_API_KEY
+    service: name => {
+      if (!serviceKey) throw configuration(503, 'ctx.backend.service needs BRAIN_SERVICE_API_KEY: create an API key with a scope naming the resource')
+      return resource(incoming, response, rid, name, serviceKey)
+    },
+    // A declared file bucket from trusted server code, with BRAIN_SERVICE_API_KEY and its files.<bucket> scope
+    files: bucket => {
+      if (!serviceKey) throw configuration(503, 'ctx.backend.files needs BRAIN_SERVICE_API_KEY: create an API key with a files.<bucket> scope')
+      return bucketClient(target, serviceKey, bucket)
+    },
     slugRedirect: (name, slug) => resource(incoming, response, rid, name).slugRedirect(slug),
     login: credentials => login(incoming, response, rid, credentials),
+    signup: credentials => signup(incoming, response, rid, credentials),
+    google: Object.freeze({
+      challenge: () => googleChallenge(incoming, response, rid),
+      login: values => googleLogin(incoming, response, rid, values),
+    }),
   })
   return {
     proxy,
@@ -476,21 +760,23 @@ export function nativeAuthBridge(raw) {
     backend,
     login,
     async prepare(req, res, rid) {
-      if (!cookies(req, false)) { req.$nativeUser = null; req.$nativeAuth ||= Promise.resolve(); return }
-      if (!req.$nativeAuth) req.$nativeAuth = call(req, res, '/_brain/auth/me', 'GET', rid).then(result => { req.$nativeUser = result.user })
+      if (!cookies(req, true)) { req.$nativeUser = null; req.$nativeAuth ||= Promise.resolve(); return }
+      if (!req.$nativeAuth) req.$nativeAuth = (async () => {
+        req.$nativeUser = cookies(req, false) ? (await call(req, res, '/_brain/auth/me', 'GET', rid)).user : null
+        if (req.$nativeUser === null && /(?:^|;\s*)__Host-brain-refresh=/.test(req.headers.cookie || '')) await renew(req, res, rid)
+      })()
       await req.$nativeAuth
     },
     session(req, res, rid) {
       return {
         user: req.$nativeUser,
-        set() { throw new HttpError(409, 'Use the native authentication API to establish a session') },
+        set() { throw configuration(409, 'With BRAIN_BACKEND_URL the backend owns the session: sign in with ctx.backend.login(credentials), or set BRAIN_BACKEND_SESSION=app so this app keeps its own signed session, and keep a server-only value with ctx.session.setSecret(value)', rid, 'Sign-in is not available right now') },
         clear() {
           if (req.$nativeLoginStarted) throw new HttpError(409,'Use a separate server request to sign out after signing in')
-          if (req.method !== 'POST' || res.headersSent) throw new HttpError(403, 'Sign out through a same-origin POST request')
-          let origin
-          try { origin = new URL(req.headers.origin); if (origin.origin !== req.headers.origin || origin.host !== (req.headers['x-forwarded-host'] || req.headers.host)) throw Error() } catch { throw new HttpError(403, 'Sign out through a same-origin POST request') }
+          if (req.method !== 'POST' || res.headersSent) throw new HttpError(403, 'B0742: Sign out through a same-origin POST request')
+          const origin = bridgeOrigin(req, rid, 'Sign out through a same-origin POST request')
           if (!req.$nativeLogout) {
-            req.$nativeLogout = call(req, res, '/_brain/auth/logout', 'POST', rid, origin.origin).then(headers => { req.$nativeLogoutDone = true; req.$nativeLogoutHeaders = headers }, error => { req.$nativeLogoutDone = true; req.$nativeLogoutError = true; throw error })
+            req.$nativeLogout = call(req, res, '/_brain/auth/logout', 'POST', rid, origin).then(headers => { req.$nativeLogoutDone = true; req.$nativeLogoutHeaders = headers }, error => { req.$nativeLogoutDone = true; req.$nativeLogoutError = true; throw error })
             req.$nativeLogout.catch(() => {})
           }
           return req.$nativeLogout
@@ -498,15 +784,23 @@ export function nativeAuthBridge(raw) {
         headers: () => req.$nativeLoginHeaders || {},
       }
     },
+    fileStream,
     _socketCookie: req => cookies(req, false),
-    close() { stopped = true; for (const request of owned) request.destroy(); agent.destroy() },
+    _forwardedFor: forwardedFor,
+    close() { stopped = true; for (const request of owned) request.destroy(); agent.destroy(); streamAgent.destroy() },
   }
 }
 
 export function createServer(o = {}) {
   const dist = resolve(o.dist || process.cwd())
-  const env = Object.freeze({ ...(o.env || ENV) }) // ctx.env: what the supervisor passed, read-only
-  const native = nativeAuthBridge(o.backendURL ?? env.BRAIN_BACKEND_URL)
+  // ctx.env: what the supervisor passed, read-only; the service key stays with ctx.backend.service
+  const { BRAIN_SERVICE_API_KEY: serviceKey, BRAIN_JOBS_API_KEY: _jobs, BRAIN_JOBS_SYSTEM_KEY: _jobsSystem, BRAIN_ROUTES_API_KEY: _routes, BRAIN_ROUTES_SYSTEM_KEY: _routesSystem, ...visibleEnv } = o.env || ENV
+  const env = Object.freeze(visibleEnv)
+  const native = nativeAuthBridge(o.backendURL ?? env.BRAIN_BACKEND_URL, (...why) => originRefused(...why), serviceKey, (...entry) => log(...entry))
+  // Using the native backend does not have to mean it owns the visitor's session: `app` keeps the signed cookie.
+  const backendSession = o.backendSession ?? env.BRAIN_BACKEND_SESSION
+  if (backendSession && backendSession !== 'app') throw Error("BRAIN_BACKEND_SESSION must be app, or unset for the backend's own session")
+  const nativeSession = native && backendSession !== 'app'
   if (o.nativeSockets !== undefined && typeof o.nativeSockets !== 'boolean') throw Error('nativeSockets must be an explicit boolean')
   const SITEMAP_BYTES = +(o.sitemapBytes ?? 50 * 1024 * 1024) // protocol: 50 MB uncompressed per sitemap file
   const secret = o.secret ?? env.BRAIN_SECRET ?? ''
@@ -532,6 +826,20 @@ export function createServer(o = {}) {
     if (typeof safe.path === 'string') safe.path = safe.path.split(/[?#]/, 1)[0].slice(0, 2048)
     sink(level, msg, safe)
   }
+  // An origin refusal (B0741, B0742): the answer stays minimal and the operator's log gets the reason. It is bounded per
+  // minute because anyone can trigger it, and it never names an allowlist: this server only compares against its own host.
+  let originWindow = 0, originLogs = 0
+  const originRefused = (code, req, rid, kind) => {
+    const minute = Math.floor(Date.now() / 60000)
+    if (originWindow !== minute) { originWindow = minute; originLogs = 0 }
+    if (originLogs++ >= 16) return
+    const bound = v => typeof v === 'string' ? v.slice(0, 256) : null
+    const seenOrigin = bound(req.headers.origin), host = bound(req.headers.host), forwardedHost = bound(req.headers['x-forwarded-host'])
+    const fix = seenOrigin
+      ? `Origin ${seenOrigin} does not match the host this server sees (${forwardedHost || host}). Call it from the site itself; behind a proxy forward the host (nginx: proxy_set_header Host $host;). There is no allowlist to widen. Run brain explain ${code}`
+      : `The request has no Origin${code === 'B0741' ? ' and no Sec-Fetch-Site' : ''}, so its site cannot be proven. Send it from the page's own origin in a browser; a script sets Origin to the site origin. Run brain explain ${code}`
+    log('error', 'origin refused', { code, kind, rid, seenOrigin, secFetchSite: bound(req.headers['sec-fetch-site']), host, forwardedHost, fix })
+  }
   // log fields for a thrown value: its stack (sanitized by log) plus, for B09xx budget failures, the typed fields only
   const trace = e => {
     const out = { stack: String((e && e.stack) || e) }
@@ -546,6 +854,8 @@ export function createServer(o = {}) {
   const SL = mf.server || {}
   const TIMEOUT = +(o.timeout ?? env.BRAIN_TIMEOUT_MS ?? SL.timeoutMs ?? 10000)
   const LIMIT = +(o.rateLimit ?? env.BRAIN_RPC_LIMIT ?? SL.rpcPerMinute ?? 60) // per IP + function, per minute
+  // Off by default: nginx below 1.29 takes a 103 as the final response, and the real one reaches the client as body bytes.
+  const EARLY_HINTS = o.earlyHints ?? (env.BRAIN_EARLY_HINTS ? env.BRAIN_EARLY_HINTS === '1' : SL.earlyHints === true)
   const BODY_KB = +(o.maxBodyKB ?? env.BRAIN_MAX_BODY_KB ?? SL.maxBodyKB ?? 1024)
   if (!Number.isInteger(BODY_KB) || BODY_KB < 1 || BODY_KB > 65536) throw Error('brain.json server.maxBodyKB must be an integer from 1 to 65536 (KB)')
   const MAX_BODY = BODY_KB * 1024 // RPC and form bodies; bounded reads never buffer more
@@ -557,9 +867,25 @@ export function createServer(o = {}) {
   const hasManifestSockets = Object.hasOwn(mf,'nativeSockets')
   if (hasManifestSockets && typeof mf.nativeSockets !== 'boolean') throw Error('Manifest nativeSockets must be an explicit boolean')
   const nativeSockets = o.nativeSockets === undefined ? hasManifestSockets && mf.nativeSockets : o.nativeSockets
-  if (nativeSockets && !native) throw Error('Native sockets require a configured native backend')
+  if (nativeSockets && !native) throw Error('Native sockets require a configured native backend; fix: run `brain backend serve` and set BRAIN_BACKEND_URL to its loopback URL')
   // the build's single route table (#187): already in match order, each with its RegExp source (named groups = params)
   const routes = mf.routes.map(r => ({ ...r, rx: r.rx ? new RegExp(r.rx) : exact(r.path) }))
+  // The address RPC and form limits key on, ctx.req.ip and the logs: a client header counts only through a trusted proxy.
+  const proxies = trustedProxies(o.trustProxy ?? (env.BRAIN_TRUST_PROXY ? env.BRAIN_TRUST_PROXY.split(',').map(entry => entry.trim()) : mf.trustProxy) ?? [])
+  let proxyWarned = false
+  const ipOf = req => {
+    const forwarded = req.headers['x-forwarded-for']
+    if (forwarded && !proxies && !proxyWarned && /^(?:127\.|::1$|::ffff:127\.)/.test(req.socket.remoteAddress || '')) {
+      proxyWarned = true
+      log('warn', 'trust-proxy-not-configured', { fix: 'a local proxy is forwarding client addresses and they are ignored, so all clients share one rate-limit key; set trustProxy in server/platform.jsbrain or BRAIN_TRUST_PROXY=127.0.0.1,::1' })
+    }
+    return resolveClient(req.socket.remoteAddress, forwarded, proxies)
+  }
+  // server/routes/* of the native backend, listed by the build: only these exact shapes cross the bridge
+  const nativeRoutes = (Array.isArray(mf.nativeRoutes) ? mf.nativeRoutes : []).map(route => {
+    if (typeof route?.path !== 'string' || !Array.isArray(route.headers)) throw Error('Manifest nativeRoutes must list path and headers')
+    return { headers: route.headers, rx: new RegExp('^' + route.path.split('/').map(part => /^\{.+\}$/.test(part) ? '[^/]+' : part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('/') + '$') }
+  })
   // the real path: Node imports file URLs through realpath, and the /_b/ hook must name the same modules (a symlinked
   // dist such as /var → /private/var on macOS would otherwise load the core twice)
   const distURL = pathToFileURL(real(dist) + sep).href
@@ -675,6 +1001,13 @@ export function createServer(o = {}) {
     const path = typeof custom === 'string' && file(custom)
     return html(res, status, path ? readFileSync(path, 'utf8') : defaultError(status, rid, BASE))
   }
+  // `/403`, `/404.html`, `/503`…: the status when the app has that page, else 0 and the path is an ordinary one
+  const reservedStatus = pathname => {
+    const m = /^\/(403|404|410|5\d\d)(?:\.html)?$/.exec(pathname)
+    if (!m) return 0
+    const n = +m[1]
+    return file(`${n}.html`) || (mf.errors && mf.errors[n]) || (n === 403 && mf.forbidden) || (n === 404 && mf.notFound) ? n : 0
+  }
   // a file inside dist/ (never outside: no `..`, no absolute paths)
   function file(rel) {
     const p = normalize(join(dist, rel))
@@ -695,13 +1028,14 @@ export function createServer(o = {}) {
 
   const context = (req, res, url, extra) => {
     const cookies = parseCookies(req.headers.cookie)
-    const { user, session: ses } = native ? { user: req.$nativeUser ?? null, session: native.session(req, res, res.getHeader('x-request-id')) } : sessionFrom(cookies, secret)
+    const { user, session: ses } = nativeSession ? { user: req.$nativeUser ?? null, session: sessionSecrets(native.session(req, res, res.getHeader('x-request-id')), cookies, secret) } : sessionFrom(cookies, secret)
+    const signal = lifetime(res)
     return {
       url, query: Object.fromEntries(url.searchParams), cookies, user, session: ses, env,
       ...(native ? { backend: native.backend(req, res, res.getHeader('x-request-id')) } : {}),
       // `prefetch`: the router fetched this page ahead of a click (§19); a `load` with side effects can skip them
-      prefetch: req.headers['x-brain-prefetch'] === '1',
-      req: { method: req.method, headers: req.headers, ip: ipOf(req) }, ...extra,
+      prefetch: req.headers['x-brain-prefetch'] === '1' || /\bprefetch\b/.test(req.headers['sec-purpose'] ?? ''),
+      req: { method: req.method, headers: req.headers, ip: ipOf(req) }, signal, llm: llmClient(env, signal), ...extra,
     }
   }
 
@@ -755,19 +1089,24 @@ export function createServer(o = {}) {
   const anonymous = req => req.method === 'GET' && !req.headers.authorization && !req.headers.cookie
 
   async function ssr(req, res, route, params, url, rid, forms = null, status = 200, fixed = null, nocache = false) {
-    // 103 Early Hints (#232): the route's preloads (the same Link values as _headers) before any work, once
-    if (route.links && route.links.length && res.writeEarlyHints && !res.$capture && !res.$hinted) {
+    // the route's preloads (the same Link values as _headers): on the response, where hosts turn them into early hints,
+    // capped so a long list cannot trip a proxy's header buffer. A 103 (#232) only when opted in, and never to HTTP/1.0.
+    if (route.links && route.links.length && !res.$capture && !res.$hinted) {
       res.$hinted = true
-      try {
-        res.writeEarlyHints({ link: route.links })
-      } catch {}
+      const link = route.links.join(', ')
+      if (link.length <= 2048 && !res.headersSent) res.setHeader('link', link)
+      if (EARLY_HINTS && res.writeEarlyHints && req.httpVersion !== '1.0') {
+        try {
+          res.writeEarlyHints({ link: route.links })
+        } catch {}
+      }
     }
     if (!nocache && route.cache > 0 && !forms && !fixed && status === 200 && anonymous(req)) return cached(req, res, route, params, url, rid)
     if (native) await native.prepare(req, res, rid)
     const ctx = context(req, res, url, { params })
     // a page rendered for a signed-in user is never stored (§35): after logout, Back must not show the previous
     // user's page from the HTTP cache or bfcache. Anonymous pages keep `no-cache` + ETag.
-    const own = ctx.user != null || ctx.cookies[COOKIE] !== undefined || native && /(?:^|;\s*)__Host-brain(?:-access|-refresh)?=/.test(req.headers.cookie || '')
+    const own = ctx.user != null || ctx.cookies[COOKIE] !== undefined || ctx.cookies[SECRET_COOKIE] !== undefined || native && /(?:^|;\s*)__Host-brain(?:-access|-refresh)?=/.test(req.headers.cookie || '')
     const keep = h => (own ? { ...h, 'cache-control': 'private, no-store' } : h)
     let props = fixed || {}, extra = {}
     if (!fixed && ((route.guards && route.guards.length) || (route.middleware && route.middleware.length))) {
@@ -776,19 +1115,19 @@ export function createServer(o = {}) {
         const guards = [], middleware = []
         for (const g of route.guards || []) guards.push(await load(g))
         for (const m of route.middleware || []) middleware.push(await load(m))
-        r = await runChain({ guards, middleware, ctx })
+        r = await pageLocale.run(route.locale, () => runChain({ guards, middleware, ctx }))
       } catch (e) {
         log('error', 'guard failed', { rid, path: url.pathname, ...trace(e) })
         return errorPage(req, res, route, params, url, rid)
       }
       // a guarded page must not reach the index through its login redirect (§33): the redirect itself says noindex
-      if (r.redirect) return send(res, r.status, '', { location: withBase(redirect(r.redirect, r.status ?? 303).redirect), 'cache-control': 'no-store', 'x-robots-tag': NOINDEX, ...ctx.session.headers() })
+      if (r.redirect) return send(res, r.status, '', { location: withBase(linkTo(route, redirect(r.redirect, r.status ?? 303).redirect)), 'cache-control': 'no-store', 'x-robots-tag': NOINDEX, ...ctx.session.headers() })
       if (r.deny !== undefined) return forbidden(req, res, url, rid, r.deny)
       extra = r.headers
     }
     // what load() thrown or returned instead of props answers: redirect, notFound() (F11), deliberate status, failure
     const loadOutcome = e => {
-      if (e && e.redirect) return send(res, e.status || 303, '', { location: withBase(redirect(e.redirect, e.status ?? 303).redirect), ...ctx.session.headers() })
+      if (e && e.redirect) return send(res, e.status || 303, '', { location: withBase(linkTo(route, redirect(e.redirect, e.status ?? 303).redirect)), ...ctx.session.headers() })
       if ((e instanceof HttpError && e.status === 404) || (e && e.notFound === true)) return missing(req, res, e) // `notFound()` 404 / `gone()` 410
       const status = intendedStatus(e) || 500
       log('error', 'load failed', { rid, path: url.pathname, status, ...trace(e) })
@@ -798,7 +1137,8 @@ export function createServer(o = {}) {
     try {
       if (!fixed && route.server) {
         const m = await load(route.server)
-        if (typeof m.load === 'function') props = (await withTimeout(Promise.resolve(m.load(ctx)), TIMEOUT)) ?? {}
+        if (route.i18n) await load(route.i18n) // t() inside load(): the dictionary is there before it runs
+        if (typeof m.load === 'function') props = (await withTimeout(pageLocale.run(route.locale, () => Promise.resolve(m.load(ctx))), TIMEOUT, ctx)) ?? {}
       }
     } catch (e) {
       return loadOutcome(e)
@@ -817,7 +1157,9 @@ export function createServer(o = {}) {
     const page = readFileSync(file(route.page), 'utf8')
       .replace('<!--brain:ssr-->', () => body)
       .replace('<!--brain:props-->', () => jsonInHtml(props))
-    let out = head(page, seo, url.pathname)
+    // a page behind a guard passes it only for its visitor: it stays out of the index even when it renders (§33)
+    if (route.guards && route.guards.length) res.setHeader('x-robots-tag', NOINDEX)
+    let out = head(page, seo, url.pathname, url.search)
     // route params for route() in the browser (the client has no route table)
     if (params && Object.keys(params).length) out = out.replace('</head>', () => `<meta name="brain-params" content="${esc(JSON.stringify(params))}"></head>`)
     if (forms) out = out.replace('</body>', () => `<script type="application/json" id="brain-forms">${jsonInHtml(forms)}</script></body>`)
@@ -833,7 +1175,8 @@ export function createServer(o = {}) {
   async function streamed(req, res, route, params, url, rid, ctx, extra, outcome) {
     const [top, bottom = ''] = readFileSync(file(route.page), 'utf8').split('<!--brain:ssr-->')
     const sm = await load(route.server)
-    const loadP = typeof sm.load === 'function' ? withTimeout(Promise.resolve().then(() => sm.load(ctx)), TIMEOUT) : Promise.resolve(null)
+    if (route.i18n) await load(route.i18n)
+    const loadP = typeof sm.load === 'function' ? withTimeout(pageLocale.run(route.locale, () => Promise.resolve().then(() => sm.load(ctx))), TIMEOUT, ctx) : Promise.resolve(null)
     loadP.catch(() => {}) // handled below; never an unhandled rejection while the loading view renders
     let timer
     const early = await Promise.race([loadP.then(v => ({ v }), e => ({ e })), new Promise(r => (timer = setTimeout(r, STREAM_HOLD)))])
@@ -860,7 +1203,7 @@ export function createServer(o = {}) {
       globalThis.__brainLocale = null
     }
     const at = { path: url.pathname, params: params || {}, query: Object.fromEntries(url.searchParams) }
-    write(n(head(top, seo0, url.pathname)))
+    write(n(head(top, seo0, url.pathname, url.search)))
     // QA #253: the folder's _loading.brain goes in the region with the first chunk (SPEC: shows while load runs),
     // between two marker comments; the last chunk starts with a script that removes them and what is between
     let clear = ''
@@ -892,7 +1235,7 @@ export function createServer(o = {}) {
       if (props.redirect || props.notFound === true) throw props
     } catch (e) {
       // too late for a real redirect: the page says noindex so the stub never enters the index
-      if (e && e.redirect) return end(`<meta name="robots" content="noindex"><script>location.replace(${jsonInHtml(withBase(redirect(e.redirect, e.status ?? 303).redirect))})</script>`)
+      if (e && e.redirect) return end(`<meta name="robots" content="noindex"><script>location.replace(${jsonInHtml(withBase(linkTo(route, redirect(e.redirect, e.status ?? 303).redirect)))})</script>`)
       // a streamed page already sent its 200 head: the region gets the not-found notice and the page is noindex
       if (e && e.notFound === true) return end(`<meta name="robots" content="noindex"><p role="alert" class="brain-fallback">Page not found.</p>`, {}, bottom.replace(/<script type="module">(?:(?!<\/script>)[\s\S])*?brain-view[\s\S]*?<\/script>/g, ''))
       log('error', 'load failed (streamed)', { rid, path: url.pathname, status: 200, ...trace(e) }) // headers already out
@@ -966,7 +1309,7 @@ export function createServer(o = {}) {
     await new Promise(r => setTimeout(r, 0))
     globalThis.__brainSSR = null
     fillValues(root)
-    const body = root.innerHTML
+    const body = localizeLinks(route, root.innerHTML)
     stop()
     // SEO head: the codegen emits `export const seo` / `head` in the view's server module; the client chunk's V.seo
     // (older builds) is the fallback. Still inside the page's locale: `<meta seo title={t('…')}>` is translated.
@@ -987,7 +1330,7 @@ export function createServer(o = {}) {
     const fail = (status, error, { $h, ...extra } = {}) => send(res, status, json({ error, ...extra }), { 'content-type': MIME['.json'], 'cache-control': 'no-store', ...$h })
     if (req.method !== 'POST') return fail(405, 'Use POST', { $h: { allow: 'POST' } })
     if (req.headers['x-brain-rpc'] !== '1') return fail(403, 'Missing X-Brain-RPC header')
-    if (!sameOrigin(req)) return fail(403, 'Cross-origin request')
+    if (!sameOrigin(req)) return originRefused('B0741', req, rid, 'rpc'), fail(403, 'Cross-origin request', { brainCode: 'B0741' })
     const modPath = mf.rpc[hash]
     if (!modPath || !/^[A-Za-z_$][\w$]*$/.test(fn)) return fail(404, 'Unknown function')
     const ra = overLimit(ipOf(req) + ' ' + hash + '/' + fn, LIMIT) // before reading the body
@@ -995,7 +1338,8 @@ export function createServer(o = {}) {
     let raw
     try {
       raw = await body(req, MAX_BODY)
-    } catch {
+    } catch (e) {
+      if (e.aborted) return
       return fail(413, tooBig(rid, url.pathname))
     }
     if (native) await native.prepare(req, res, rid)
@@ -1030,12 +1374,13 @@ export function createServer(o = {}) {
   // ---------- form posted without JS (§38; transport, the logic is callForm, shared with the dev server) ----------
   async function formPost(req, res, route, params, url, rid) {
     const plain = (status, text, h = {}) => send(res, status, text, { 'content-type': MIME['.txt'], 'cache-control': 'no-store', ...h })
-    if (!sameOrigin(req, true)) return plain(403, 'Cross-origin form post')
+    if (!sameOrigin(req, true)) return originRefused('B0741', req, rid, 'form'), plain(403, 'Cross-origin form post', { 'x-brain-code': 'B0741' })
     if (!/^application\/x-www-form-urlencoded/i.test(req.headers['content-type'] || '')) return plain(415, 'Forms are sent as application/x-www-form-urlencoded')
     let raw
     try {
       raw = await body(req, MAX_BODY)
-    } catch {
+    } catch (e) {
+      if (e.aborted) return
       return plain(413, tooBig(rid, url.pathname))
     }
     const id = new URLSearchParams(raw).get('_brain') || '', modPath = mf.rpc[id.split('/')[0]]
@@ -1215,8 +1560,29 @@ export function createServer(o = {}) {
     return false
   }
 
+  // /health is reserved for the backend (B0735), so an app cannot declare it and deploy gates ask this port for it. An app
+  // page at that path still wins: this only runs where the answer would have been a 404. Nothing here names the backend.
+  const isProbe = path => path === '/health' || path === '/health/live' || path === '/health/ready'
+  const answerProbe = async (req, res, url, rid) => {
+    const headers = { 'content-type': MIME['.json'], 'cache-control': 'no-store' }
+    if (req.method !== 'GET' && req.method !== 'HEAD') return notFound(req, res)
+    if (!native) return send(res, 200, json({ ok: true }), headers)
+    try { await native.proxy(req, res, new URL(url.pathname, url), rid, send) }
+    catch { if (!res.headersSent) send(res, 503, json({ ok: false }), headers) }
+  }
+
   // ---------- dispatch ----------
   const server = http(async (req, res) => {
+    // Only a file upload may outlast the 30-second body budget; the dispatcher lifts this guard for that path alone.
+    if (native) {
+      req.$brainBodyGuard = setTimeout(() => {
+        if (req.complete) return
+        if (!res.headersSent) res.writeHead(408, { connection:'close' })
+        res.end(); req.socket?.destroy()
+      }, 30000)
+      req.$brainBodyGuard.unref?.()
+      res.once('close', () => clearTimeout(req.$brainBodyGuard))
+    }
     const rid = req.headers['x-request-id'] && /^[\w-]{1,64}$/.test(req.headers['x-request-id']) ? req.headers['x-request-id'] : randomUUID()
     res.setHeader('x-request-id', rid)
     const t0 = performance.now()
@@ -1225,17 +1591,22 @@ export function createServer(o = {}) {
       if (ms > 1000) log('warn', 'slow request', { rid, path: req.$brainPath || String(req.url || '').split('?')[0], status: res.statusCode, ms: Math.round(ms) })
     })
     try {
+      // `//` makes new URL throw and `//host/x` would be read as another host
+      if (req.url.startsWith('//')) return notFound(req, res)
       const full = new URL(req.url, 'http://' + (req.headers.host || 'localhost'))
       // /_health stays at the root: the supervisor calls it there whatever the base
       if (full.pathname === '/_health' || full.pathname === BASE + '_health') return send(res, 200, json({ ok: true, build: mf.build || null }), { 'content-type': MIME['.json'], 'cache-control': 'no-store' })
       let url = full
       if (BASE !== '/') {
         if (full.pathname === BASE.slice(0, -1)) return send(res, 301, '', { location: BASE + full.search })
-        if (!full.pathname.startsWith(BASE)) return notFound(req, res)
+        if (!full.pathname.startsWith(BASE)) return isProbe(full.pathname) ? await answerProbe(req, res, full, rid) : notFound(req, res)
         url = new URL('/' + full.pathname.slice(BASE.length) + full.search, full) // the app path
       }
       req.$brainPath = url.pathname
+      if (native && /^\/_brain\/files(?:\/|$)/.test(url.pathname)) return await native.fileStream(req,res,url,rid)
       if (native && /^\/(?:api(?:\/|$)|_brain(?:\/|$)|s\/)/.test(url.pathname)) return await native.proxy(req,res,url,rid,send)
+      const declaredRoute = native && nativeRoutes.find(route => route.rx.test(url.pathname))
+      if (declaredRoute) return await native.proxy(req,res,url,rid,send,undefined,declaredRoute)
       // redirects.json (manifest `redirects`, brain-seo server_json): exact sources first, then patterns, on the app path;
       // same-site targets get the base, the query is kept when the target has none; slash policy and host in the same hop
       const to = (req.method === 'GET' || req.method === 'HEAD') && canonicalOf(req, url)
@@ -1246,6 +1617,10 @@ export function createServer(o = {}) {
       if (url.pathname.startsWith('/_server/')) return notFound(req, res) // server code is never served
       const post = req.method === 'POST'
       if (!post && req.method !== 'GET' && req.method !== 'HEAD') return send(res, 405, 'Method not allowed', { allow: 'GET, HEAD, POST' })
+      // a status page opened directly answers its own status: `/403` is never a 200 that a crawler or a probe can trust
+      const reserved = post ? 0 : reservedStatus(url.pathname)
+      if (reserved === 403) return forbidden(req, res, url, rid, '')
+      if (reserved) return failPage(res, reserved, rid)
       for (const route of routes) {
         const m = route.rx.exec(url.pathname)
         if (!m) continue
@@ -1257,6 +1632,9 @@ export function createServer(o = {}) {
       if (post) return send(res, 405, 'Method not allowed', { allow: 'GET, HEAD' })
       if (DYN.length && /^\/sitemap(-static|-dynamic(-\d+)?)?\.xml$/.test(url.pathname) && (await serveSitemap(req, res, url))) return
       if (serveStatic(req, res, url)) return
+      // browsers still ask for /favicon.ico: the app's SVG icon answers it
+      if (url.pathname === '/favicon.ico' && file('favicon.svg')) return send(res, 301, '', { location: withBase('/favicon.svg'), 'cache-control': 'public, max-age=86400' })
+      if (isProbe(url.pathname)) return await answerProbe(req, res, url, rid)
       notFound(req, res)
     } catch (e) {
       log('error', 'unhandled', { rid, path: req.url, ...trace(e) })
@@ -1265,29 +1643,114 @@ export function createServer(o = {}) {
     }
   })
   if (native) server.once('close', () => native.close())
-  if (native && nativeSockets) server.$brainSocketStop = installNativeSockets(server,{target:o.backendURL ?? env.BRAIN_BACKEND_URL,base:BASE,cookie:native._socketCookie,log})
+  if (native && nativeSockets) server.$brainSocketStop = installNativeSockets(server,{target:o.backendURL ?? env.BRAIN_BACKEND_URL,base:BASE,cookie:native._socketCookie,client:native._forwardedFor,log})
   server.headersTimeout = 15000
-  server.requestTimeout = 30000
+  // With a native backend the file upload deadline is enforced per request (above); 30 s stays for every other body.
+  server.requestTimeout = native ? 320000 : 30000
   return server
 }
 
 // ---------- session (signed cookie; shared with the dev server) ----------
-const COOKIE = '__Host-session'
-// The user of a request: the signed `__Host-session` cookie (HMAC-SHA256 with BRAIN_SECRET), plus the session handle
-// to set/clear it. Same in `node server.mjs` and in `brain run` (the dev sidecar imports it).
+const COOKIE = '__Host-session', SECRET_COOKIE = '__Host-session-secret', SECRET_MAX = 3500, DEFAULT_SESSION_SECONDS = 7 * 24 * 3600
+// Keys that still verify and decrypt during a rotation; new cookies always use the current key.
+const previousKeys = () => (process.env.BRAIN_SECRET_PREVIOUS || '').split(',').map(k => k.trim()).filter(Boolean)
+const sessionVersion = () => process.env.BRAIN_SESSION_VERSION || ''
+const sessionSeconds = () => { const n = Number(process.env.BRAIN_SESSION_SECONDS); return Number.isInteger(n) && n > 0 ? n : DEFAULT_SESSION_SECONDS }
+// Cookies of this process signed out before their expiry (mac -> exp). One process only: a shared store does not exist
+// here, so a deployment with several processes signs everybody out with BRAIN_SESSION_VERSION instead.
+const REVOKED = new Map(), REVOKED_MAX = 10000
+const revoke = (mac, exp) => {
+  const now = Date.now()
+  for (const [k, e] of REVOKED) if (e <= now) REVOKED.delete(k)
+  while (REVOKED.size >= REVOKED_MAX) REVOKED.delete(REVOKED.keys().next().value)
+  REVOKED.set(mac, exp)
+}
+const secretKey = secret => Buffer.from(hkdfSync('sha256', secret, '', 'brain session secret v1', 32))
+const seal = (secret, text) => {
+  const iv = randomBytes(12), cipher = createCipheriv('aes-256-gcm', secretKey(secret), iv)
+  cipher.setAAD(Buffer.from(SECRET_COOKIE))
+  const body = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()])
+  return Buffer.concat([iv, cipher.getAuthTag(), body]).toString('base64url')
+}
+const unseal = (secret, value) => {
+  try {
+    const raw = Buffer.from(value, 'base64url')
+    if (raw.length < 29) return null
+    const decipher = createDecipheriv('aes-256-gcm', secretKey(secret), raw.subarray(0, 12))
+    decipher.setAAD(Buffer.from(SECRET_COOKIE))
+    decipher.setAuthTag(raw.subarray(12, 28))
+    return Buffer.concat([decipher.update(raw.subarray(28)), decipher.final()]).toString('utf8')
+  } catch { return null }
+}
+// `ctx.session.setSecret(value, { maxAge })`, `.secret()` and `.clearSecret()` on any session handle (signed cookie or
+// native bridge): server-only values such as a provider token, AES-256-GCM encrypted in their own cookie. They never
+// fill `ctx.user`, and `session.clear()` removes them too.
+const missingSecret = what => new Error(`B0782: BRAIN_SECRET is not set: ${what} need it; fix: set 32+ random bytes in the host environment or in .brain_env (openssl rand -hex 32)`)
+export function sessionSecrets(session, cookies, secret) {
+  const out = []
+  const write = (value, maxAge) => { out.length = 0; out.push(`${SECRET_COOKIE}=${value}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${Math.max(0, maxAge)}`) }
+  let current
+  const read = () => {
+    if (current !== undefined) return current
+    current = null
+    const v = cookies && cookies[SECRET_COOKIE]
+    if (!v || !secret) return current
+    for (const key of [secret, ...previousKeys()]) {
+      const text = unseal(key, v)
+      if (text === null) continue
+      try {
+        const s = JSON.parse(text)
+        if (s && s.exp > Date.now()) current = s.v
+      } catch {}
+      break
+    }
+    return current
+  }
+  const { clear, headers } = session
+  const clearSecret = () => { write('', 0); current = null }
+  return Object.assign(session, {
+    secret: read,
+    setSecret(value, { maxAge = sessionSeconds() } = {}) {
+      if (!secret) throw missingSecret('session secrets')
+      const text = JSON.stringify({ v: value, exp: Date.now() + maxAge * 1000 })
+      if (value === undefined || text === undefined || JSON.parse(text).v === undefined) throw new Error('session.setSecret needs a JSON value')
+      const sealed = seal(secret, text)
+      if (sealed.length > SECRET_MAX) throw new Error(`session secret too large (${sealed.length} bytes, limit ${SECRET_MAX}): keep it server-side and store a reference`)
+      write(sealed, maxAge)
+      current = value
+    },
+    clearSecret,
+    clear(...args) { const result = clear.apply(session, args); if (out.length || (cookies && cookies[SECRET_COOKIE] !== undefined)) clearSecret(); return result },
+    headers() {
+      const base = headers.call(session)
+      if (!out.length) return base
+      const own = base['set-cookie']
+      return { ...base, 'set-cookie': [...(Array.isArray(own) ? own : own ? [own] : []), ...out] }
+    },
+  })
+}
+// The user of a request: the signed `__Host-session` cookie (HMAC-SHA256 with BRAIN_SECRET; BRAIN_SECRET_PREVIOUS still
+// verifies during a rotation, BRAIN_SESSION_VERSION signs everybody out), plus the session handle to set/clear it. Same
+// in `node server.mjs` and in `brain run` (the dev sidecar imports it).
 export function sessionFrom(cookies, secret) {
-  const sign = data => b64u(createHmac('sha256', secret).update(data).digest())
-  let cur = null
+  const signWith = (key, data) => b64u(createHmac('sha256', key).update(data).digest())
+  const sign = data => signWith(secret, data)
+  let cur = null, curMac = null
   const v = cookies && cookies[COOKIE]
   if (v && secret) {
     const i = v.lastIndexOf('.')
     if (i > 0) {
-      const data = v.slice(0, i), mac = Buffer.from(v.slice(i + 1)), good = Buffer.from(sign(data))
-      if (mac.length === good.length && timingSafeEqual(mac, good))
-        try {
-          const s = JSON.parse(Buffer.from(data, 'base64url').toString())
-          if (s && s.exp > Date.now()) cur = s
-        } catch {}
+      const data = v.slice(0, i), mac = Buffer.from(v.slice(i + 1))
+      for (const key of [secret, ...previousKeys()]) {
+        const good = Buffer.from(signWith(key, data))
+        if (mac.length === good.length && timingSafeEqual(mac, good)) {
+          try {
+            const s = JSON.parse(Buffer.from(data, 'base64url').toString())
+            if (s && s.exp > Date.now() && (s.sv ?? '') === sessionVersion() && !REVOKED.has(v.slice(i + 1))) { cur = s; curMac = v.slice(i + 1) }
+          } catch {}
+          break
+        }
+      }
     }
   }
   const set = []
@@ -1296,14 +1759,16 @@ export function sessionFrom(cookies, secret) {
   const user = cur ? cur.u : null
   return {
     user,
-    session: {
+    session: sessionSecrets({
       user,
-      set(u, { maxAge = 7 * 24 * 3600 } = {}) {
-        if (!secret) throw new Error('BRAIN_SECRET is not set: sessions need it (32+ random bytes in .brain_env)')
-        const data = b64u(JSON.stringify({ u, exp: Date.now() + maxAge * 1000 }))
+      set(u, { maxAge = sessionSeconds() } = {}) {
+        if (!secret) throw missingSecret('sessions')
+        const version = sessionVersion()
+        const data = b64u(JSON.stringify({ u, exp: Date.now() + maxAge * 1000, ...(version ? { sv: version } : {}) }))
         set.push(cookie(`${data}.${sign(data)}`, maxAge))
       },
       clear() {
+        if (curMac) revoke(curMac, cur.exp)
         set.push(cookie('', 0))
         cleared = true
       },
@@ -1312,7 +1777,7 @@ export function sessionFrom(cookies, secret) {
       // response, so the logout call took ~18 s (F16). Nothing private is in that cache: RPC is no-store and SSR
       // HTML rendered with a session cookie is `private, no-store` (ssr() → keep).
       headers: () => ({ ...(set.length ? { 'set-cookie': set } : {}), ...(cleared ? { 'clear-site-data': '"storage"' } : {}) }),
-    },
+    }, cookies, secret),
   }
 }
 
@@ -1378,9 +1843,30 @@ export function overLimit(key, max = 60) {
   if (!h || now - h[0] > 60000) HITS.set(key, (h = [now, 0]))
   return ++h[1] > max ? Math.ceil((h[0] + 60000 - now) / 1000) : 0
 }
-const withTimeout = (p, ms) => {
+// t(), fmt and locale() read globalThis.__brainLocale. A render sets it while nothing else runs (renders are serialized);
+// load(), guards and form handlers overlap across awaits, so each carries its page's language in the async context.
+const pageLocale = new AsyncLocalStorage()
+let renderLocale = globalThis.__brainLocale
+Object.defineProperty(globalThis, '__brainLocale', { configurable: true, get: () => pageLocale.getStore() ?? renderLocale, set: v => (renderLocale = v) })
+// ctx.signal: aborted when the client disconnects before the answer ends or the function passes its deadline, so the
+// work it started (fetch, a query) stops with it.
+const aborts = new WeakMap()
+const newSignal = () => {
+  const c = new AbortController()
+  aborts.set(c.signal, c)
+  return c.signal
+}
+const lifetime = res => {
+  const signal = newSignal()
+  res.once?.('close', () => res.writableFinished || aborts.get(signal).abort()) // a captured render has no socket
+  return signal
+}
+const withTimeout = (p, ms, ctx) => {
   let t
-  return Promise.race([p, new Promise((_, rej) => (t = setTimeout(() => rej(new HttpError(504, 'timeout')), ms)))]).finally(() => clearTimeout(t))
+  return Promise.race([p, new Promise((_, rej) => (t = setTimeout(() => {
+    aborts.get(ctx?.signal)?.abort()
+    rej(new HttpError(504, 'timeout'))
+  }, ms)))]).finally(() => clearTimeout(t))
 }
 // RPC body → arguments: a JSON array, with __proto__/constructor/prototype keys dropped. Throws HttpError(400).
 export function parseArgs(raw) {
@@ -1408,7 +1894,8 @@ export async function callRpc({ fn, args, ctx, key, limit = 60, timeout = 10000
     return { status: e.status || 400, body: { error: e.message } }
   }
   try {
-    const v = await withTimeout(Promise.resolve(fn(ctx, ...a)), timeout)
+    ctx.signal ||= newSignal() // the dev sidecar builds its own ctx
+    const v = await withTimeout(Promise.resolve(fn(ctx, ...a)), timeout, ctx)
     return { status: 200, body: v ?? null }
   } catch (e) {
     if (e && e.errors && typeof e.errors === 'object') return { status: 422, body: { error: e.message || 'Invalid input', errors: e.errors } }
@@ -1416,7 +1903,7 @@ export async function callRpc({ fn, args, ctx, key, limit = 60, timeout = 10000
     const pub = publicError(e)
     if (pub) return { status: pub.status, body: { error: pub.message } }
     const deliberate = intendedStatus(e)
-    if (deliberate && deliberate < 500) return { status: deliberate, body: { error: e instanceof HttpError ? e.message : STATUS_CODES[deliberate] } }
+    if (deliberate && deliberate < 500) return { status: deliberate, body: { error: e instanceof HttpError && e.message !== NATIVE_FAILED ? e.message : STATUS_CODES[deliberate] } }
     if (deliberate) return {status:deliberate,body:{error:STATUS_CODES[deliberate]},cause:e}
     return { status: 500, body: { error: 'Internal error' }, cause: e }
   }
@@ -1427,6 +1914,8 @@ export async function callRpc({ fn, args, ctx, key, limit = 60, timeout = 10000
 // `locale` (§37): the page's language, so the schema messages (`form.*`) and the generic error come from its dictionary
 // (globalThis.__brainDict, filled by the page's chunk) like form() in the browser. It is set only around the synchronous
 // validation, so concurrent requests in other languages never see it.
+// English text for the server's log: a form or a server function never shows it to a visitor
+const NATIVE_FAILED = 'Native resource request failed'
 export async function callForm({ module, raw, ctx, rules, key, limit = 60, timeout = 10000, locale }) {
   const q = new URLSearchParams(raw || ''), id = q.get('_brain') || '', fn = id.split('/')[1] || ''
   if (key) {
@@ -1449,10 +1938,11 @@ export async function callForm({ module, raw, ctx, rules, key, limit = 60, timeo
   if (Object.keys(errors).length) return again(errors, '')
   let r
   try {
-    r = await withTimeout(Promise.resolve(module[fn](ctx, values)), timeout)
+    ctx.signal ||= newSignal()
+    r = await withTimeout(pageLocale.run(locale, () => Promise.resolve(module[fn](ctx, values))), timeout, ctx)
   } catch (e) {
     if (e && e.errors && typeof e.errors === 'object') return again(e.errors, '')
-    if (e instanceof HttpError && e.status >= 400 && e.status < 500) return again({}, e.message)
+    if (e instanceof HttpError && e.status >= 400 && e.status < 500) return again({}, e.message === NATIVE_FAILED ? generic : e.message)
     const pub = publicError(e)
     if (pub) return again({}, pub.message)
     const deliberate = intendedStatus(e)
@@ -1509,7 +1999,40 @@ function parseCookies(h = '') {
   }
   return out
 }
-const ipOf = req => String(req.headers['x-forwarded-for'] || '').split(',')[0].trim() || req.socket.remoteAddress || '?'
+const plainIp = text => { const ip = String(text).trim().replace(/^"|"$/g, '').replace(/^\[([^\]]+)\](?::\d+)?$/, '$1').replace(/^(\d+\.\d+\.\d+\.\d+):\d+$/, '$1').replace(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i, '$1'); return isIP(ip) ? ip : null }
+/** platform.trustProxy: one BlockList of proxies. Same limits as the backend's parse_proxy (brain-backend/src/platform.rs). */
+export function trustedProxies(list = []) {
+  const nets = new BlockList()
+  for (const entry of list) {
+    const [address, prefix, extra] = String(entry).split('/')
+    const family = isIP(address)
+    const bits = prefix === undefined ? (family === 4 ? 32 : 128) : Number(prefix)
+    const wide = family === 4 ? bits < 8 : bits < 16 && !(bits === 7 && /^fc00::$/i.test(address))
+    if (!family || extra !== undefined || !Number.isInteger(bits) || bits > (family === 4 ? 32 : 128)) throw Error(`trustProxy entry \`${entry}\` must be an IP address or CIDR range`)
+    if (wide) throw Error(`trustProxy entry \`${entry}\` is too wide; use at least /8 for IPv4 and /16 for IPv6, and list your proxy ranges`)
+    nets.addSubnet(address, bits, family === 4 ? 'ipv4' : 'ipv6')
+  }
+  return list.length ? nets : null
+}
+/**
+ * The client is the right-most forwarded hop that is not a trusted proxy, and only when the TCP peer is trusted: hops
+ * left of it are client-supplied and never consulted. Same walk as resolve_client (brain-backend/src/edge_http.rs).
+ */
+export function resolveClient(peer, forwarded, nets) {
+  const socketPeer = plainIp(peer ?? '')
+  const trusted = ip => nets.check(ip, isIP(ip) === 4 ? 'ipv4' : 'ipv6')
+  if (!socketPeer) return '?'
+  if (!nets || !trusted(socketPeer)) return socketPeer
+  let client = socketPeer
+  for (const text of String(forwarded ?? '').split(',').reverse()) {
+    const ip = plainIp(text)
+    if (!ip) return client
+    client = ip
+    if (!trusted(ip)) return ip
+  }
+  return client
+}
+export function readBody(req, max) { return body(req, max) }
 function body(req, max) {
   return new Promise((ok, fail) => {
     let n = 0
@@ -1521,7 +2044,10 @@ function body(req, max) {
       else if (n <= max) parts.push(c)
     })
     req.on('end', () => (n > max ? fail(new Error('too large')) : ok(Buffer.concat(parts).toString('utf8'))))
-    req.on('error', fail)
+    // a disconnect or the cut above never reaches 'end': the reader settles anyway and nobody is left to answer
+    const aborted = () => fail(Object.assign(new Error('body aborted'), { aborted: true }))
+    req.on('error', aborted)
+    req.on('close', aborted)
   })
 }
 // bind:value / checked are properties; copy them into attributes so the SSR HTML shows them
@@ -1568,19 +2094,27 @@ export function prefersMarkdown(accept) {
   return md > 0 && (md > html || (md === html && mdAt < htmlAt))
 }
 // SEO head from View.seo(props): title, description, canonical, og:*/twitter:*, JSON-LD and the view's <head> block
-// F5: the build writes an SSR route's canonical/og:url from its pattern (/jobs/:slug); the request has the real path.
+// F5: the build writes an SSR route's canonical/og:url from its pattern (/posts/:slug); the request has the real path.
 // A view's own <head> tags replace the generated ones with the same name/property (one tag per key, SPEC «SEO»).
-function head(page, seo, path) {
+function head(page, seo, path, search = '') {
   let h = page
+  // `<meta seo query="page">`: these parameters make a different page; any other (a dialog, a tracking tag) does not
+  let identity = ''
+  h = h.replace(/<meta name="brain-query" content="([^"]*)">/, (_, keys) => {
+    const given = new URLSearchParams(search), kept = new URLSearchParams()
+    for (const key of keys.split(/[\s,]+/)) for (const value of key ? given.getAll(key) : []) kept.append(key, value)
+    if (kept.size) identity = esc('?' + kept)
+    return ''
+  })
   if (path) {
     // the attribute is already escaped HTML: only the request path that replaces a pattern is escaped
-    const real = v => v.replace(/^(https?:\/\/[^/]+)?(\/[^"]*)$/, (m, o = '', p) => (/\/[:*]/.test(p) ? o + esc(path) : m))
+    const real = v => v.replace(/^(https?:\/\/[^/]+)?(\/[^"]*)$/, (m, o = '', p) => (/\/[:*]/.test(p) ? o + esc(path) : m)) + identity
     h = h.replace(/(<link[^>]*rel=["']canonical["'][^>]*href=")([^"]*)(")/i, (m, a, v, b) => a + real(v) + b)
     h = h.replace(/(<meta[^>]*property=["']og:url["'][^>]*content=")([^"]*)(")/i, (m, a, v, b) => a + real(v) + b)
   }
   if (!seo) return h
-  const meta = (attr, key, val) => {
-    const tag = `<meta ${attr}="${esc(key)}" content="${esc(val)}">`
+  const meta = (attr, key, val, escaped) => {
+    const tag = `<meta ${attr}="${esc(key)}" content="${escaped ? val.replace(/"/g, '&quot;') : esc(val)}">`
     const rx = new RegExp(`<meta[^>]*\\b${attr}=["']${key.replace(/[.*+?^${}()|[\]\\:]/g, '\\$&')}["'][^>]*>`, 'i')
     h = rx.test(h) ? h.replace(rx, () => tag) : h.replace('</head>', () => tag + '</head>')
   }
@@ -1596,6 +2130,17 @@ function head(page, seo, path) {
     else if (/^(og|twitter|article):/.test(k)) meta('property', k, v)
     else if (typeof v === 'string') meta('name', k, v)
   }
+  // What the build writes for a prerendered page and can only be known here: the social card of this request's values
+  // (brain-seo social::head, prerender seo_head). The view's own value always wins.
+  const shared = /<title>([\s\S]*?)<\/title>/i.exec(h)?.[1]
+  const origin = /<link[^>]*rel=["']canonical["'][^>]*href="(https?:\/\/[^/"]+)/i.exec(h)?.[1]
+  if (typeof seo['og:image'] === 'string' && origin && /^\/(?!\/)/.test(seo['og:image'])) meta('property', 'og:image', encodeURI(origin + seo['og:image']))
+  if (seo.title != null && seo['og:title'] == null) meta('property', 'og:title', shared, true)
+  if (seo.description != null && seo['og:description'] == null) meta('property', 'og:description', seo.description)
+  if (seo['og:image'] != null) {
+    if (seo['og:image:alt'] == null) meta('property', 'og:image:alt', seo['og:title'] ?? shared, seo['og:title'] == null)
+    if (seo['twitter:card'] == null) meta('name', 'twitter:card', 'summary_large_image')
+  }
   // `<meta seo schema="Article">` without `jsonld` (§32): one node with this request's values. It replaces the node
   // the build wrote into the template from the static attributes (same @type), so the page carries exactly one.
   if (typeof seo.schema === 'string' && seo.jsonld == null && /^[A-Za-z]+$/.test(seo.schema)) {
@@ -1637,6 +2182,7 @@ function hook(base, app = '/') {
   )
 }
 
+const LISTEN_WAIT_MS = 10000
 // `node server.mjs` (directly or under `brain start`); paths compared after symlinks (/var → /private/var on macOS)
 function real(p) {
   try {
@@ -1650,10 +2196,22 @@ if (process.argv[1] && real(process.argv[1]) === real(fileURLToPath(import.meta.
   const s = createServer({ dist: fileURLToPath(new URL('.', import.meta.url)) })
   const fd = ENV.BRAIN_LISTEN_FD
   const where = fd ? { fd: Number(fd) } : { port: +(ENV.PORT || 3000), host: ENV.HOST || '127.0.0.1' }
-  s.listen(where, () => {
+  s.once('listening', () => {
     process.stdout.write(`brain:ready ${process.pid}\n`) // the supervisor waits for this line (§34)
     console.log(json({ t: new Date().toISOString(), level: 'info', msg: 'listening', ...(fd ? { fd: Number(fd) } : where) }))
   })
+  // A restart may find the previous instance still draining: wait for it, briefly. Two live servers never share a port.
+  const waitUntil = Date.now() + LISTEN_WAIT_MS
+  s.on('error', error => {
+    if (error.code === 'EADDRINUSE' && !fd && !s.listening && Date.now() < waitUntil) return void setTimeout(() => s.listen(where), 100)
+    if (s.listening) throw error
+    const port = where.port
+    const fix = error.code === 'EADDRINUSE' ? `find the owner with \`lsof -nP -iTCP:${port} -sTCP:LISTEN\` (Linux: \`ss -ltnp 'sport = :${port}'\`), stop it, or set another PORT` : 'use another HOST or PORT'
+    const cause = error.code === 'EADDRINUSE' ? `another live process still holds the port after ${LISTEN_WAIT_MS / 1000} s` : error.code
+    console.error(json({ t: new Date().toISOString(), level: 'error', msg: `cannot listen on ${where.host}:${port}: ${cause}`, fix }))
+    process.exit(1)
+  })
+  s.listen(where)
   // SIGTERM/SIGINT: stop accepting, answer what is in flight or arrives on open connections (each then closes), for up
   // to BRAIN_DRAIN_MS (10 s), then cut whatever is left; exit 0 either way
   const drain = () => {