Status: Draft
Type: Standards Track
Category: Core
Created: 2026-03-07
Updated: 2026-11-03
Requires: CIP-9 (Runner Attached Storage), CIP-11 (native runner routes), CIP-14 (DNS-Addressable Actors), CIP-18 (price tables); workload registry records for
Workload-target routes onlyCowboy Cloud and Cowboy Chain. This CIP specifies the Cowboy protocol. Cowboy Cloud runs on this protocol today. Cowboy Chain, a public network on the same protocol, is under consideration for a future release. Where the two differ, this CIP says so.
1. Abstract
Background
An actor can serve static files, handle dynamic requests, and run off-chain services under the same domain. Each request needs a destination and a payment policy.Goal
This CIP specifies a routes table in actor KV state for the CIP-14 Gateway network. Each(verb, path) entry selects a CBFS Visibility::Public volume, a named actor handler, an off-chain runner, or a registered workload. It also selects whether the actor or caller pays. An actor publishes its Workload URL routes in __cowboy/routes (§8.15), without a per-actor Gateway configuration change.
- A unified route schema (verb, path, target, payment policy, priority, enabled) stored in actor KV at the reserved key
__cowboy/routes. - A verb-aware route resolution algorithm that determines per-request dispatch (volume mount, actor handler, or off-chain runner) and payment policy.
- A
Runnertarget that proxies a route off-chain for endpoints that cannot run in consensus, such as LLM inference, outbound API calls, and streaming. Current dispatch requires an explicit runner pin and its advertised endpoint. Selection throughrunner_bindingsand binding-scoped CBFS mount authorization are unimplemented target design (§7.5, §8.14). - A
Workloadtarget that relays an actor-declared route, including WebSocket upgrades and unbuffered SSE, to a single long-lived registered workload backend (§8.15), for streaming app endpoints: inference SSE, agent chat UIs, application websockets. - A per-route payment policy (
pays = actor | caller) withactoras the default.calleropts the route into payment gating per CIP-18. - An extension to the
ingress.httpentitlement withstatic_volumesandmax_static_response_bytesparameters. - A Gateway-to-Relay-Node fetch protocol for retrieving, reconstructing, caching, and serving public-volume objects.
- A Gateway-to-Runner fetch protocol for reading the routes table from actor state with Merkle-proof verification.
- A CORS configuration schema (
_meta/cors.json) with defaults for static assets. - Cache invalidation driven by on-chain state-root and
manifest_rootchanges. - The build lowers an actor’s route declarations to the canonical table. The deploy and upgrade instructions carry it. The chain validates and installs it into a protected slot that actor code cannot write.
- Pre-compressed asset variants (
.gz,.brfiles in the volume). - Small object inlining (bypassing erasure coding for tiny files).
- Image optimization or resizing at the Gateway edge.
- Range requests and chunked transfer for streaming large assets.
- Caller-pays static-asset downloads (paid public-volume content).
2. Motivation
CIP-14 makes actors reachable over HTTP through a singlehttp.request handler. An actor can serve static assets, dynamic API endpoints, and off-chain work such as LLM inference, outbound API calls, and streaming. Each needs a different execution path. A static file should come straight from storage. A state-changing call needs the actor’s deterministic handler under consensus. A model call cannot run in the PVM at all.
The routes table assigns each (verb, path) a destination and payer. It supports the following behavior:
- The Gateway serves static assets from its cache or reconstructs them from Relay Node shards without invoking an actor handler.
- Static and runner routes consume no actor-handler execution or
max_query_cyclesbudget. - Gateways cache reconstructed objects, serve conditional requests using ETags, and set
Cache-Controlheaders without invoking the actor. - Routes target named actor handlers, not a single
http.requestcatchall.GET /postandPOST /postgo to different methods. Path parameters (/users/{id}) bind to handler arguments. Actors no longer reimplement routing. - Each route declares
pays = actor | caller.actoris the default and needs no caller wallet when no enabled CIP-18price_tableoverrides it;callerselects 402/x402 gating under the same fallback. An enabled table’s rule ordefault_modeis authoritative. - The build produces the routes table from actor source. The chain installs it with the code it routes to. What the Gateway serves is always what the deployed code declares; no admin handler or later write can make the two drift. Prices that change at runtime live in the CIP-18
price_table, and assets change by republishing their volume. - Authors declare routes with decorators on handler functions (FastAPI / axum / Hono style). The build lowers them to the canonical schema.
- Authors declare endpoints for LLM inference, outbound API calls, and streaming responses as
Runnertargets. The Gateway proxies these requests off-chain to a runner. The same routing table decides, per(verb, path), what runs in consensus, what serves static, and what runs off-chain. - WebSocket and SSE connections terminate at a registered persistent workload under the same URL space (
Workloadtarget, §8.15). One domain serves static from a volume, consensus methods from the actor, and live streams from a workload the actor owns.
3. Design Goals
- Serve static assets without invoking any actor handler or consuming PVM cycles.
- Let actors declare routes per
(verb, path), targeting a CBFS volume mount, a named actor handler, or an off-chain runner, with explicit priority ordering. - Let a route execute off-chain on a runner (
Runnertarget) for work that cannot or should not run in consensus, with optional caller authentication and actor- or caller-owned CBFS mounts. - Relay long-lived streaming connections (WebSocket, SSE) unbuffered to a registered persistent workload (
Workloadtarget), with explicit idle-timeout and connection-lifetime policy. - Make
pays = actorthe fallback default so that browser GETs do not require a wallet absent an enabled CIP-18price_table; let actors opt specific routes intopays = calleras the client-paid fallback for payment-gated endpoints. - Support SPA (single-page application) fallback patterns (
index.htmlfor all non-file paths). - Reuse CIP-9’s existing
_meta/content_types.jsonand_meta/cache_config.jsonfor HTTP header generation. - Provide CORS headers for static assets by default (browsers need them).
- Define the Gateway-to-Relay-Node fetch protocol for static assets and the Gateway-to-Runner fetch protocol for routes: retrieval, integrity verification, and caching.
- Extend the existing
ingress.httpentitlement. No new entitlement type is introduced. - Install the routes table only with the code it routes to. The build produces it; the chain writes it at deploy and upgrade. Actor code can never write it.
4. Non-Goals
- Replacing actor handlers for dynamic requests. Volume and method targets coexist; the routes table controls which
(verb, path)pair goes where. - Server-side rendering. Actors that need SSR use a method target.
- Pre-compressed asset variants (
.gz,.br). Compression is on-the-fly only. - Image optimization, resizing, or transformation at the Gateway edge.
- Range requests (
Rangeheader) for partial content delivery. - Verifiable or multi-operator runner serving. A
Runner-target route is trusted to the selected runner in this CIP; attested / trustless serving and on-chain settlement of off-chain work are deferred (§13). The same applies toWorkload-target routes: a workload-served route is exactly as trustworthy as its host (§8.15). - Metered billing of streamed content. A
Workloadroute can payment-gate connection establishment (pays = caller, CIP-18); usage-metered streaming settlement (per-token, per-message) is the streaming-payments protocol’s scope, not this CIP’s.
5. Definitions
- A route is an entry in the actor’s routes table that maps a
(verb, path)pattern to aTarget, with a payment policy, priority, and enabled flag. - A verb is an HTTP method (
GET,HEAD,POST,PUT,PATCH,DELETE) orANY(matches any verb at lowest specificity). - A target is the destination of a route, a
Method(named actor handler, executed via actor RPC under consensus), aVolume(CBFS public volume mount), aRunner(the request proxied off-chain to a selected runner endpoint for non-consensus execution), or aWorkload(a registered persistent service). - A
Runnertarget is a route whose handler runs off-chain on a selected runner (the CIP-9 / RAS execution tier), not in consensus. Distinct from the state read of §8.12 (GET_STATEagainst a full node), which only serves verified reads of the actor’s KV state; aRunnertarget serves the route’s request and response itself. - A
Workloadtarget relays to a single long-lived registered service with a control-plane registry record (identity, owning actor, serving endpoint). It uses no per-request runner selection, handler dispatch, or route mounts. The Gateway relays bytes to one durable backend, including upgraded WebSocket connections and streamed SSE responses (§8.15). - A workload registry record is the control-plane record describing a persistent workload. This CIP consumes five of its fields,
workload_id,owning_actor,serving_endpoint,reporter, andhost_pool, and the reporter’s CIP-2 Runner pool entitlement for that pool.Workload-target routes are unavailable where that registry does not exist. - The
paysfield selects the fallback route payment gate when no enabled CIP-18price_tableapplies,actor(default; the caller pays nothing at establishment) orcaller(Gateway requires payment proof; on missing/invalid proof returns402 Payment Required). An enabled table’s matching rule ordefault_modetakes precedence. Workload hosting costs and any actor-funded serving-budget charge follow their own policies. - The routes table is the CBOR-encoded
Routesvalue stored in actor KV at the reserved key__cowboy/routes. - A mount is a
Volume-target route with a wildcard path, declared at the SDK module level (e.g.,actor.mount("/assets", volume="web-assets")). - An object is a single file stored in a CBFS volume (e.g.,
assets/logo.png). Objects are erasure-coded into shards and distributed across Relay Nodes. - A shard is one piece of an erasure-coded object, stored on a single Relay Node. Any K of K+M shards are sufficient to reconstruct the original object.
6. Routes
6.1 Storage Location
The routes table is stored in the actor’s KV state at the reserved key__cowboy/routes. The CIP-11 sponsorship ceiling for native runner routes is stored beside it at __cowboy/route_sponsorship. Both are protected slots: they are written only by the chain’s install path (§6.9), during deployment, upgrade, or a fork that copies its parent’s code. The host refuses every actor write or delete of either key.
KV storage, rather than a volume file or an actor method, gives the Gateway a table it can verify without executing the actor: the unified state root is committed in every block header, and the Gateway fetches __cowboy/routes with a CIP-17 proof against it (§8.12). An actor that serves only dynamic methods needs no CBFS volume to publish routes.
Protection makes the table part of the code’s identity. It is validated once, by the node, at installation, including the static_volumes membership of every Volume target (§7.3). It can change only together with the code it routes to.
6.2 Schema
price values are canonical positive integer native base-unit strings, without a denomination suffix, sign, fraction or leading zero. They are the net actor fee. One CBY is 1,000,000,000 base units; SDK/compiler declarations MAY accept an exact decimal such as price="0.05 CBY", but MUST lower it to "50000000" before installation, as in CIP-18 §8.5. The caller’s total adds the 5% protocol fee, rounded down in base units; transaction gas is separate. A route price of 50,000,000 therefore quotes 52,500,000 base units before gas. Price-table entries follow their asset and model rules in CIP-18.
For Method targets, an explicit mode overrides the HTTP verb. If absent,
GET/HEAD resolve to "read" and other verbs to "submit" (after ANY matches,
use the request’s actual method). For unpaid invocation, "read" uses the unsigned query path;
"submit" signs and waits for a transaction result; "submit_no_wait" signs
and submits without waiting for that result. Both submit modes charge gas to
the Gateway signing wallet under CIP-14 §8.4.3.
For this Gateway-signed command path, timeout_ms sets the submit receipt wait (default 3,000 ms), not a transaction expiry or a guarantee that the handler has stopped. After confirmed admission, a submit receipt wait that reports timed_out, or a submit_no_wait acknowledgement, returns 202 Accepted with x-cowboy-submit-status: admitted-pending. The Gateway preserves the configured fallback_response body and other headers, but overrides its status and replaces any case-insensitive admission-status header. Without a fallback, this acknowledgement has an empty body. A succeeded submit result with missing/empty output instead returns the configured fallback unmodified, or empty 202 when absent; a valid non-empty response envelope takes precedence. Read responses and malformed non-empty command responses do not use this fallback. See CIP-14 §8.2.1. The native paid Method path below returns its atomic committed response under CIP-18 §8.5.
Native paid Method requests are an exception. A Method request selected for payment follows CIP-18 §8.5, with the current route and policy resolved by the node. Payment and handler execution share a consensus savepoint. Even Read / GET / HEAD enters through the signed atomic wrapper while its business handler stays read-only; unsigned /actor/read or an opaque direct message cannot bypass paid-handler admission. SubmitNoWait also returns the committed atomic response, rather than authorizing a second dispatch or a fire-and-forget fallback. External Runner and Workload routes retain their distinct confirmation-before-dispatch lifecycle in CIP-18 §6.
pays = "actor" (the default) means the caller pays no service price and needs no payment proof when no enabled CIP-18 price_table applies. For actor handlers, GET/HEAD default to unsigned Read mode with no transaction gas; an explicit route mode overrides the verb. In Submit or SubmitNoWait mode, the Gateway signs the call and pays its gas from its own wallet under CIP-14 §8.4.3. The actor’s hot balance is not debited for the Gateway-signed top-level transaction; deferred work the handler emits is billed to the emitting actor, then its FallbackToOwnerBalance owner for any shortfall, at basefee with zero tip (CIP-28 §3.4). The Gateway enforces a per-actor budget alongside the Gateway’s per-transaction cap under CIP-14 §8.4.3, including its same-nonce recovery rules. The actor budget counts actual committed gas plus unresolved signed maxima. Unresolved evidence keeps the maximum while retryable lookups remain queued; later valid evidence settles the actual charge. A definitive miss (strict not-found for all signed variants), malformed or mismatched evidence, or queue overflow keeps its maximum for the process lifetime. Evidence retry and exhaustion rules follow CIP-14 §8.4.3. A callee cannot bill the Gateway for timers: CIP-5 §4.2 requires an actor to pay for its own timers (the canonical Watchtower Feed’s owner-paid start/restart applies only to the Feed owner’s own signed call). There is no callee-scheduled, sender-billed timer path to exclude from the Gateway budgets under this rule (CIP-14 §8.4.3).
A Workload route does not execute the actor per request: without an enabled table, the Gateway treats pays = "actor" as free. An enabled table’s matching rule or default_mode can instead require caller payment or charge the actor’s serving budget. Workload hosting and bandwidth costs are governed separately; the route declaration alone does not fund serving.
pays = "caller" selects the client-paid fallback when no enabled CIP-18 price_table applies. Under that model the Gateway returns 402 Payment Required with x402-compatible headers until the caller submits a valid payment proof. price is required and is the per-request fallback charge interpreted by CIP-18. An enabled table’s matching rule or default_mode can instead make the route free or actor-funded.
For Volume targets, pays MUST be "actor". Caller-pays static downloads are deferred to a follow-on CIP.
A Runner target proxies the request off-chain, outside consensus; the body and any stream never enter a transaction. In the current implementation, the route must set an explicit runner pin that resolves to an advertised route_serving_endpoint. Missing pins, unavailable records, and missing or unusable endpoints return 503 Service Unavailable. Current selection does not apply requires or affinity, and an explicit pin does not establish a runner_bindings authorization check.
Under the unimplemented selection and binding-authorization design, an omitted requires selector would admit runners in the actor’s runner_bindings (§7.5); a selector would narrow that set, and the Gateway would choose a healthy runner with the requested affinity. A runner pin would then have to belong to that eligible set (§8.14). Actor- and caller-owned mount issuance under those bindings is also target design, not a guarantee of the current proxy.
This is the path for endpoints that cannot or should not run in the deterministic PVM: LLM inference, outbound API calls, long-running or streaming work. On-chain state changes still belong behind a Method target; a Runner handler’s execution is never consensus. Payment and caller authentication follow §8.14; they do not implement the missing binding authorization.
A Workload target relays the request to one registered persistent workload, such as a model server, agent chat backend, or app relay, using its control-plane registry record. This is the streaming path: the Gateway upgrades and pipes WebSocket connections, relays SSE unbuffered, and applies stream-lifetime policy (idle_timeout_ms, max_connection_ms) instead of the request-scoped timeout_ms (§8.15). The resolved client-paid model gates connection establishment; pays = "caller" selects that model only when no enabled price_table overrides it. auth = "account" authenticates the establishing caller. There is no runner selection, no handler name, and no route mounts. The workload’s registry record carries its volume mounts and any future capabilities. The actor publishes the route in __cowboy/routes; the Gateway resolves the serving endpoint from the workload registry (§8.15).
6.3 Path Patterns
Route paths use the following syntax:/api/users/{user_id}binds a named path parameter to a single segment./static/*restmatches zero or more segments and binds the remainder torest./aboutmatches exactly./assets/*matches anything under the prefix without binding.
HttpRequestEnvelope.path_params field (§15.2). Static (Volume-target) routes do not bind path parameters; the matched suffix is handled per §6.7.
6.4 Example: Full-Stack Application
This CIP defines the canonical wire format (theRoutes value at __cowboy/routes) and the Gateway’s resolution algorithm. SDK authors choose the authoring API. This example uses Python and the Actor subclass style from CIP-6.
The Runner branch below illustrates the target selector and mount design. It does not configure a currently serving runner: current dispatch needs an explicit runner pin (§6.2), and selector-based choice and binding-scoped mount issuance remain unimplemented (§7.5, §8.14).
mount(...) declarations to the canonical Routes value, and the deploy installs it at __cowboy/routes (§6.9):
GET /api/users/abcmatches/api/users/{user_id}(priority 100). The Gateway dispatches an unsigned read tousers_getwithpath_params = {"user_id": "abc"}. The caller pays no service price (pays = "actor"); no transaction gas is charged.POST /api/inferencematches/api/inference. The Gateway returns402with x402 headers until the caller pays the quoted total (a net actor price of0.05 CBYplus the 5% protocol fee,0.0525 CBYbefore gas), then, in the target design, proxies the request off-chain to a runner selected from the eligible set (§8.14); current dispatch instead requires an explicit pin (§6.2);inference_runruns on the runner, not the actor PVM.GET /assets/logo.pngmatches/assets/*(priority 10). The Gateway servesassets/logo.pngfrom theweb-assetsvolume without invoking the actor.GET /aboutmatches/*(priority 0). The Gateway looks upaboutinweb-assets. If absent, it servesindex.htmlwith status200as the SPA fallback.- The Gateway always intercepts the reserved path
GET /_cowboy/health(CIP-14 §8.6). It never consults the routes table.
@get/@post/etc. are single-verb sugar for the underlying multi-verb @route(verbs, path) decorator; both can coexist:
foo.
The runner selector ergonomics in this paragraph are informative target design and are unimplemented. requires is optional, so runner() with no selector inherits the actor’s runner_bindings. This needs no configuration when the bound pool is already capable. An SDK SHOULD also offer helpers that lower to capability tags. For example, runner(model="claude-sonnet") lowers to requires.capabilities = ["llm", "model:claude-sonnet"]. Typed helpers like runner.llm(...) / runner.mcp(...) let common routes omit tag strings, while requires={…} stays the explicit form. Routes may serve LLMs, image generation, webhooks, or plain compute. The default therefore inherits the entitlement’s capabilities.
6.5 Canonical Encoding
TheRoutes value is encoded as CBOR (RFC 8949) with deterministic key ordering (CBOR §4.2.1 Core Deterministic Encoding). The routes list is sorted before encoding by:
-
prioritydescending, -
then
pathdescending (UTF-8 byte order), -
then
verbascending in declaration order:
6.6 Route Resolution Algorithm
When a Gateway receives an HTTP request for a registered actor:-
If the path starts with
/_cowboy/, handle per CIP-14 §8.6. Highest priority, not overridable by the routes table. -
Read cached routes for this actor. Refresh every poll interval (§8.12). Filter to routes with
enabled = true. -
A route is a candidate if:
- Its
pathpattern matches the request path (literal segments + named params + wildcards). - Its
verbmatches the request method, orverb = "ANY".
- Its
-
The Gateway selects one winner among the matching routes:
- Highest
prioritywins. - On a tie, the longest concrete prefix wins. Count the UTF-8 bytes of the matched path before a terminal wildcard, including matched parameter segments. A named wildcard and an anonymous wildcard have the same prefix length; neither includes the wildcard remainder. A matching path without a terminal wildcard consumes the whole path. Do not add an exact/prefix/template category rank ahead of this comparison.
- On a further tie, a more specific verb (any non-
ANY) wins overANY. - On a further tie, prefer
Method, thenRunner, thenWorkload, thenVolume(safety: prefer the consensus handler, then per-request off-chain compute, then the long-lived proxy, over static). - If these comparisons still tie, take the first route in the canonical table order from §6.5. Installed tables are already canonical; configuration-built routers MUST canonicalize before resolution so reordering equivalent declarations does not change the winner.
RunnerRouteentries are not Gateway dispatch targets; they are admitted and invoked per CIP-11 and never match an HTTP request here.
- Highest
OPTIONS preflights are answered per §9.5 before this step. For any other request, apply the current site gate and the winning route’s access per CIP-37 §7 and §9, before the body is read and before payment is evaluated. Site Owner dominates route Public; missing route tables inherit the site gate through Site fallback. Current policy must be established before cached content can answer. A caller that is not admitted receives 302, 401 or 403 and the target is not reached.
-
If a
Volumetarget wins:- The verb MUST be
GETorHEAD. Other verbs on a route whose only match is aVolumetarget return405 Method Not Allowed. - The Gateway resolves the volume object path per §6.7.
- If the object exists, serve it from the named volume (§8).
- If the object does not exist and
fallbackis set, serve the fallback object from the same volume withfallback_status. - If no fallback, return
404 Not Found.
- The verb MUST be
-
If a
Methodtarget wins:- Resolve the payment model using the enabled CIP-18
price_tablefirst, falling back toroute.paysonly when no enabled table applies. If the policy read or decode fails, return503 Service Unavailable. - For a resolved free model, dispatch without a payment check. For a resolved actor-funded model, check the actor budget before dispatch; a depleted budget MUST NOT authorize free service. CIP-18 §7.2 defines the fallback and deduction rules. The Gateway invokes the named handler, passing the
HttpRequestEnvelopewithpath_paramspopulated. Unless the route setsmode,GET/HEADuse the CIP-14 query path andPOST/PUT/PATCH/DELETEuse the command path; an explicitmodeselects the path instead. - For a client-paid model selected by an enabled
price_tableor fallbackpays = "caller", verify the caller’s payment proof per CIP-18. On missing or invalid proof, return402 Payment Requiredwith x402-compatible headers (X-PAYMENT-Required,X-PAYMENT-Receipt, etc., per CIP-18). On valid proof, dispatch to the named handler.
- Resolve the payment model using the enabled CIP-18
-
If a
Runnertarget wins:- If
auth = "account", the request MUST carry the caller’s Cowboy-account signature; the runner verifies it (§8.14) and the Gateway returns401 Unauthorizedif the runner rejects it. Identity is401, payment is402. Both checks apply. - If the resolved payment model is client-paid, apply CIP-18 payment gating exactly as for
Method(return402 Payment Requireduntil a valid proof is presented). - Current dispatch resolves the explicit
runnerpin and its advertised endpoint (§6.2), then proxies the request off-chain; the actor’s PVM is not invoked. Selection from a binding-authorized eligible set and per-request scoped mount issuance are target design (§7.5, §8.14), not checks performed by the current proxy.
- If
-
If a
Workloadtarget wins:- If
auth = "account", the establishment request MUST carry the caller’s Cowboy-account signature; the workload verifies it (§8.15) and the Gateway returns401 Unauthorizedwhen it is rejected. - If the resolved payment model is client-paid, apply CIP-18 payment gating to connection establishment (return
402 Payment Requiredbefore any upgrade or first streamed byte). - The Gateway resolves the workload’s serving endpoint from its registry record and relays the connection per §8.15, using a WebSocket upgrade and byte relay, or an unbuffered streamed HTTP response. The actor’s PVM is not invoked.
- If
-
If no route matches, return
404 Not Found. Explicit routes are required; there is no fallbackdefault_behavior.
6.7 Volume Object Path Resolution
Given aVolume-target route match and a request path:
strip_prefix is false, the full request path (minus leading /) is used:
6.8 Validation
The node validates a table when it installs it (§6.9) and rejects the deployment or upgrade that carries an invalid one. It decodes the table with the strict admission decoder, which bounds size and rejects unknown fields and duplicate map keys. It requires the canonical encoding (§6.5). Every rule below is checked at install except those marked dispatch, which depend on state outside the table and are checked when a request is served or a connection established. Gateways apply the same structural rules when they load a table.-
versionMUST be2, the final launch schema, with the encodedaccessfield. Other versions return503without application dispatch (CIP-37 §7.2). -
routesMUST NOT exceedMAX_ROUTESentries. -
Total CBOR-encoded size MUST NOT exceed
MAX_ROUTES_SIZE. -
Each
pathMUST start with/. -
pathMUST NOT equal/_cowboy/or start with/_cowboy/(reserved by CIP-14). -
verbMUST be one of the seven valid values. -
mode, when present, MUST be exactly"read","submit", or"submit_no_wait"; unknown values reject the table. When absent, aMethodroute usesreadfor GET/HEAD andsubmitfor other verbs. -
target.kindMUST be"method","volume","runner","workload", or"runner_route". -
For
Methodtargets:nameMUST be a non-empty string. (The build checks that the named handler exists and declares a permission; a missing method at dispatch returns502 Bad Gateway.) -
For
Volumetargets:volume_nameMUST be one of the actor’singress.httpstatic_volumes;paysMUST be"actor";fallback_statusMUST be a valid HTTP status code (100–599). -
For
Runnertargets,handlerMUST be a non-empty string;affinityMUST benone/caller/session, andaffinity = "caller"REQUIRESauth = "account";authMUST be"public"or"account"; a mount withowner = "caller"REQUIRESauth = "account";timeout_msMUST be ≤MAX_RUNNER_TIMEOUT_MS(§10). Current dispatch additionally needs an explicitrunnerpin and a usable advertised endpoint (§6.2); this is not arunner_bindingscheck. Target design, unimplemented:requiresmust be covered by a binding, an omitted selector inherits the bindings, the eligible set must be non-empty, and any pin must belong to that set. Binding-scoped actor-owned mount authorization and caller-grant checks/issuance at dispatch are also target design (§7.5, §8.14). Do not passrunner_bindingsat deployment: the manifest validator rejects this unknown parameter, including[]. -
For
Workloadtargets, route-table/config validation is structural:workloadMUST be exactly 32 bytes (a text form MUST be canonical 64-char lowercase hex; wrong length or noncanonical encodings reject);authMUST be"public"or"account";idle_timeout_msMUST be in1..=MAX_WORKLOAD_IDLE_TIMEOUT_MS;max_connection_ms, if present, MUST be at least 1; andmax_concurrent_streams, if present, MUST be in1..=MAX_CONCURRENT_STREAMS_CEILING(§10). Registry existence, ownership, route eligibility, and endpoint validity are establishment-time checks (§8.15), not route-load checks: a transiently unavailable registry MUST NOT make the Gateway discard an otherwise valid actor route table. -
paysMUST be"actor"or"caller". -
When
pays = "caller":priceMUST be present and non-empty; it is interpreted per CIP-18 at dispatch. Whenpays = "actor":priceMUST be absent. -
timeout_ms, when present, MUST be ≤MAX_RUNNER_TIMEOUT_MS. -
accessMUST be present and one of the fiveAccessforms; anAllowlistMUST satisfy CIP-37 §7.2. Missing access rejects the table. -
For
RunnerRoutetargets: the declaration MUST decode and validate per CIP-11, its verb, path and enabled flag MUST equal the outer route’s,paysMUST be"actor", and the route MUST carry noprice,mode,timeout_msorfallback_response. -
No two routes may share a
(verb, path). -
The sponsorship value MUST be present exactly when the table contains a
RunnerRoutetarget, and MUST validate per CIP-11.
6.9 Installation
The routes table is fixed when code is installed: produced by the build, carried by the instruction that installs the code, validated by the node, and written by the chain. The installing instructions carry an optionalDeployActor, the final field of UpgradeActor, and the third argument of the actor-initiated upgrade_self(code, manifest?, routes?). Its bytes pay the per-byte deploy or upgrade rate (CIP-3’s governed gas.deploy.* rates; initially 12 Cycles + 40 Cells) but not the 10-Cycle AST parse. The parse applies to code bytes only, because routes are never parsed.
The node validates routes (§6.8) against the manifest being deployed, resolves every Volume target’s volume_id (below), and writes both slots in the same write set as the actor’s code, before the init handler runs. An invalid table rejects the deployment; a failing init handler reverts the slots with everything else.
An upgrade validates routes against the new manifest when it carries one and the current manifest otherwise, then replaces both slots in the same write set as the new code. An upgrade without routes removes both slots: the installed routes always describe the code that is running. UpgradeActor is issued by a genesis system deployer, and upgrade_self requires sys.upgrade, which only system deployers may grant; any other actor changes its routes by deploying a new actor. Native runner-route sessions already open keep the declaration they were admitted under (CIP-11).
fork_actor copies the parent’s code and storage; the child carries the parent’s installed routes and sponsorship unchanged.
For each Volume target the node writes volume_id into the stored table: the declared volume_id when the declaration names one, otherwise keccak256(installer || volume_name) (CIP-9 §11.1), where installer is the deploying account for a deployment and the actor’s owner for an upgrade. The Gateway serves only the stored volume_id; later changes to the actor’s owner do not move a mount.
The host refuses state_set, state_set_checkpoint and state_delete on __cowboy/routes and __cowboy/route_sponsorship from every frame, including the deploy init handler and reserved-state writes. The install path is the only writer.
The build reads an actor’s declared routes and lowers them to a RouteInstall:
- method routes from
@get,@head,@post,@put,@patch,@deleteand@routedecorators on theActorsubclass’s handlers; Volume,RunnerandWorkloadroutes frommount(...),runner(...)andworkload(...)entries in the class-levelroutestuple or list.
@public / @callable_by), a mount(...) whose volume the manifest does not grant in static_volumes, and any table that fails §6.8. It records the table’s digest with the artifact so a reviewer sees exactly what the deploy installs.
A deploying tool may supply RouteInstall bytes that are not lowered from source. For example, a room provisioner bakes one instance’s owner, secret references, metering key and bundle hashes into its CIP-11 native route declarations. The node applies identical validation. Because an actor’s address does not depend on its routes, a provisioner can derive the address and bake actor-scoped references before deploying; changing them later is an upgrade.
A project declares the directory that holds its static assets and the public volume that serves them. cowboy deploy publishes the directory to that volume before submitting the deployment and refuses to deploy when the manifest does not grant the volume in static_volumes. Republishing the volume later updates the served assets without changing routes or code.
Method and Runner route prices that change at runtime live in the CIP-18 price_table. A native runner route’s price is fixed by its declaration (CIP-11).
Installing a deployment or an upgrade advances the actor’s state root. Gateways pick up the new table within MANIFEST_POLL_INTERVAL blocks.
7. Entitlement Extension
7.1 New Parameters
This CIP extends theingress.http entitlement (CIP-14 §6.2) with two new parameters:
static_volumes is an array of volume-name strings. Per-volume
max_cache_bytes bindings are a proposed extension (§7.4).
The existing CIP-14 parameters (allowlist_methods, max_request_bytes, max_response_bytes, max_query_cycles) are unchanged and continue to govern Method-target route behavior. max_static_response_bytes is separate from max_response_bytes because static assets (images, video thumbnails, font files) are typically much larger than dynamic API responses.
static_volumes names must be valid CBFS volume
names; *, empty names, . and .. are invalid. The response cap must be in
1..=104_857_600 (100 MiB).
Both parameters are actor-controlled configuration and are exempt from the
upgrade-subset monotone-narrowing rule: an upgrade retaining ingress.http may
add, grow, shrink, or remove them. The replacement manifest still passes name,
type, and cap validation. Other ingress.http parameters retain their existing
upgrade restrictions; this is a narrow exception to CIP-6 §12.7.
When max_static_response_bytes is absent, the Gateway applies the 10 MiB
default, so removing it on upgrade resets the cap to that default rather than
making it unbounded.
7.2 Example Manifest
7.3 Enforcement
- When the node installs a routes table (§6.9), every
Volumetarget MUST name a volume in the manifest’sstatic_volumes; otherwise the deployment or upgrade is rejected. The node writes the resolvedvolume_idinto the stored table. Because the table changes only through that path, the Gateway serves the storedvolume_idwithout re-checking membership per request. - The Gateway applies
max_static_response_bytes, using the 10 MiB default when absent. Objects larger than that limit return HTTP413 Content Too Large. - The Gateway’s serving authority follows the volume’s CIP-9 status (§8.13). If a mounted volume is
DELETEDorGARBAGE_COLLECTING, the Gateway returns the corresponding HTTP status without invoking the actor. Restoring or replacing the volume resumes serving.
7.4 Proposed Per-Volume Cache Bindings
Per-volumemax_cache_bytes is not present in the on-chain string-array
representation and is not enforced through entitlement reads by the Gateway.
The earlier object-binding proposal placed cache limits in the entitlement to
declare a Gateway resource quota. Such a quota would require its own schema,
validation, upgrade policy, and Gateway enforcement; rules-v2 does not provide
those guarantees.
7.5 Runner Bindings
The route-binding design below is unimplemented.runner_bindings is absent from the current ingress.http registry schema. Manifest validation rejects it as an unknown parameter, even when the value is []; omitting it does not materialize a binding or disable a separately pinned route. The current Gateway requires an explicit runner pin and advertised endpoint (§6.2). It does not implement the binding/selector intersection, health-based selection, affinity, or binding-scoped mount issuance described below.
The parameter, RunnerBinding model, and deployment/request-time enforcement rules in the remainder of this section specify the target design. Existing job mount machinery does not mean these route-specific authorization checks have shipped.
Runner-target routes require the actor to authorize, at deploy time, which runners may serve them and which actor-owned volumes those runners may be issued CapTokens for, through the ingress.http parameter runner_bindings:
MountPrincipal (Actor or Account). It never grants access to a runner directly. The runner holds no standing grant; at dispatch it receives a scoped CapToken (and, for a private volume, a CBSS-sealed DEK) issued by the same dispatcher path that attaches volumes to a job. runner_bindings does not create a CIP-9 grant. It authorizes the Gateway to dispatch this actor’s Runner routes to runners in the bound pool / capability set and bounds which actor-owned volumes a route may reference.
Runner pools are CIP-2 Runner pools, whose membership is granted by the pool’s owner (CIP-2 §7.3). The pool-based authorization and selection below use that membership.
The following target enforcement is unimplemented for these route bindings:
- Deployment-time (actor-owned mounts). Each binding’s
pool/capabilitiesMUST be ones the actor is entitled to (CIP-2). Eachowner = "actor"mount volume MUST be owned by the deploying account (or carry anActor-principal grant to it). A route’srequiresMUST be covered by someRunnerBinding(itspool/capabilitiesa subset of the binding’s), and itsowner = "actor"mounts MUST appear in that binding with the route’smodeand canonicalizedpath_prefixwithin the grant. Runners chosen at dispatch (§8.14) must be RAS-registered, healthy, and advertise a route-serving endpoint. - Request-time (caller-owned mounts).
owner = "caller"mounts are authorized by the caller, not the actor: the caller must own the volume and have granted the agent actor (MountPrincipal::Actor) mount access via the CIP-9 allowlist. After the runner authenticates the caller (§8.14), the dispatcher issues the runner a CapToken (+ sealed DEK) for that caller’s volume under the actor principal; the authenticated caller’s identity is what selects which caller-owned volume. This lets one endpoint give every caller scoped access to their own owned storage without the actor hosting it.
caller-owned volume from the authenticated HTTP caller per request.
8. Gateway-to-Relay-Node Fetch Protocol
8.1 Request Flow
When a Gateway receives an HTTP request that resolves to aVolume-target route:
8.2 Gateway-Side Caching
The Gateway maintains a layered cache: Layer 1a is the per-volume metadata cache. The Gateway keeps it warm for every active volume.volume_id. Refreshed when the on-chain manifest_root changes.
Layer 1b is the per-actor routes cache. The Gateway keeps it warm for every active actor.
actor_address. Refreshed when the verified __cowboy/routes value changes (§8.12).
Layer 2 is the object cache, a bounded LRU cache of reconstructed objects.
(volume_id, object_path). MAX_GATEWAY_CACHE_BYTES bounds the total across all volumes. Per-volume max_cache_bytes from an entitlement is proposed but unimplemented (§7.4). Eviction follows LRU with frequency weighting. The Gateway retains frequently accessed objects longer.
8.3 Cache Invalidation
Cache invalidation is driven by changes to the on-chainStorageCommitment.manifest_root. When volume contents change (new deploy via commit_manifest), the manifest root changes.
- The Gateway polls the on-chain
StorageCommitment.manifest_rootfor each actively-cached volume everyMANIFEST_POLL_INTERVALblocks (default: 6, ~6 seconds at 1 block/sec). - If
manifest_roothas changed: a. Fetch the new volume manifest from any Relay Node. b. Diff old and new manifests to identify changed, added, and removed objects. c. Evict all changed and removed objects from the object cache. d. Update the per-volume metadata cache (content-type map, cache config, CORS config). - If
manifest_rootis unchanged, all cached objects remain valid.
__cowboy/routes each poll; see §8.12.
Relay Nodes provide no push notifications for storage changes. Subscribing to on-chain events for every cached volume creates scaling concerns. Polling the manifest_root (a single 32-byte on-chain read) suffices because static assets tolerate invalidation delays of a few seconds.
8.4 Relay Node RPC
Gateways interact with Relay Nodes using the existing CIP-9GET_SHARD RPC (CIP-9 §16.3) plus GET_MANIFEST for direct manifest retrieval.
GET_MANIFEST
Retrieves the canonical serialized volume manifest for a given volume.
- A Gateway reads only public volumes with
GET_MANIFEST. It is an unauthenticated public reader (§8.13 and CIP-9 §7.6.3) and holds no CapToken or DEK. A private manifest is read node-by-node viaGET_SHARDby a DEK holder. CIP-9 §5.3.2 distinguishes this assembly restriction from the reference implementation’s admission of the volume owner’sREAD_WRITEtoken; grant-scoped tokens do not admitGET_MANIFEST. - The Gateway, as caller, supplies the root. It reads
manifest_root,erasure_kanderasure_mfrom the volume’s on-chainStorageCommitmentand passes them in the request. The response carries no root: the Gateway MUST rebuild the manifest from the returned entries, recompute its DAG root, and reject unless it equals the root it supplied. On mismatch, try another Relay Node and mark the offending one suspect.
GET_MANIFEST is not available on a given Relay Node, the Gateway MAY fall back to node-by-node traversal via GET_SHARD from the on-chain root, fetching each manifest node at manifest_node_shard_id(volume_id, locator) as defined in CIP-9 §5.3.2 and the storage whitepaper’s Manifest section. There is no well-known single manifest blob fallback.
A Relay Node does not hold the whole manifest, and no push propagates one to it: each DAG node is itself an erasure-coded object spread across a placement set, and a relay stores only its assigned shard indices. It answers GET_MANIFEST by assembling the DAG from peers, or from a cache it built for itself; see CIP-9 §5.3.2, “Server-side model”. A relay that cannot assemble it does not implement the RPC, and the Gateway falls back to node-by-node traversal as above.
GET_SHARD (existing CIP-9 §16.3)
volume_id is required, not decorative: CIP-9 §7.6.2/§7.6.3 make an anonymous
read conditional on the shard’s recorded volume matching the volume the request
names, and a request that names none is refused. The response is the shard bytes
alone. The relay returns no hash, because a relay-chosen hash would verify nothing.
The Gateway verifies each shard against the shard_hash carried in the object’s
own descriptor from the manifest it has already verified against the chain
(§8.5). Shards that fail verification are discarded and replacements are fetched
from alternative Relay Nodes.
For public volumes, no CapToken is required (CIP-9 §7.6.3), subject to the
status gate there: a volume that is not ACTIVE or GRACE_PERIOD is not served
anonymously.
8.5 Canonical Manifest Serialization and Verification
GET_MANIFEST returns bincode(BTreeMap<String, ManifestEntry>), an entry map ordered by path. The map is not the stored DAG encoding and its serialized bytes MUST NOT be hashed directly as the manifest root. Verification MUST rebuild the canonical public manifest DAG specified in CIP-9 §3.1: group entries into leaf nodes, build interior nodes, and compute each locator from its canonical stored bytes. The top node’s locator is the computed root. A flat ShardMap list or an RFC-6962 tree is not this format.
- Read
manifest_root,erasure_kanderasure_mfrom the volume’s authoritative on-chainStorageCommitment. Require public visibility and a serveable status as specified in CIP-9 §5.3.2. - Fetch
GET_MANIFEST { volume_id, manifest_root, erasure_k, erasure_m }, using the values read in step 1. - Decode the entry map with a bincode byte budget bounded by the received payload length and construct its canonical path index using CIP-9 §5.3.2, Entry-map decoding and lookup. Every lookup key must come from the corresponding value’s
entry.path(). Reject inconsistent keys or duplicate entry paths, or normalize them exactly as specified there before verification. - Rebuild the canonical public DAG from that canonical path index and compute its root.
- Require the computed root to equal the authoritative root from step 1. On mismatch, reject the manifest without caching or serving its content and try another Relay Node.
ObjectDescriptor; a PlacementRecord supplies shard locations, not the content trust anchor.
8.6 Integrity Verification
The Gateway MUST verify every layer of the integrity chain:- Verify the fetched manifest against the on-chain
manifest_rootusing the Merkle verification protocol (§8.5). A manifest that does not match the on-chain root MUST be rejected. - For each fetched shard, verify
BLAKE3(shard_bytes) == shard_hashfrom the verified ObjectDescriptor. Shards that fail verification are discarded; the Gateway fetches a replacement from an alternative Relay Node. - After Reed-Solomon reconstruction, verify
BLAKE3(reconstructed_bytes) == content_hashfrom the verified ObjectDescriptor. If verification fails, the Gateway MUST NOT serve the object and MUST return HTTP502 Bad Gateway.
8.7 Parallel Fetch and Hedging
For latency-sensitive serving, the Gateway employs adaptive parallel fetch:- Request K shards from the K lowest-latency Relay Nodes (based on historical RTT for that volume’s shard assignments).
- If any shard request takes longer than
HEDGE_THRESHOLD_MS(default: 100ms), issue a speculative request to an alternative Relay Node for a parity shard. Use whichever response arrives first. - The Gateway prefers data shards (indices
0..K-1) but accepts parity shards. Any K of the K+M shards suffice for reconstruction. - Allow no more than
MAX_CONCURRENT_SHARD_FETCHES(default: 8) outstanding shard requests per object reconstruction.
8.8 HTTP Response Headers
When serving a static asset, the Gateway sets the following headers:
Clients requiring strict consistency MAY send
X-Cowboy-Manifest-Root: <hex> as a request header; the Gateway returns 409 Conflict if its cached manifest does not match.
8.9 Conditional Requests
- For
If-None-Match, the Gateway compares the client’s ETag against the cached object’scontent_hash("b3_" + hex(content_hash), §8.8) under RFC 7232 §3.2 weak comparison. If it matches, return304 Not Modifiedwith no body. The decision uses only the content-hash ETag. The manifest is deliberately not consulted here: byte-identical content under a changedmanifest_rootstill returns304, which is HTTP-correct because the representation the client holds is unchanged. Manifest-root coherence is enforced separately by theX-Cowboy-Manifest-Rootrequest pin, which yields409on mismatch (§8.8), not as a condition on the ETag match; the304still echoesx-cowboy-manifest-rootso a pinning client still observes a manifest change. - The Gateway does not directly support
If-Modified-Since. Volume objects do not have per-file modification timestamps. Clients SHOULD useIf-None-Match(ETag-based) for conditional requests.
8.10 Compression
Gateways SHOULD supportAccept-Encoding: gzip, br and compress responses on-the-fly for compressible content types: text/html, text/css, application/javascript, application/json, image/svg+xml, text/plain, application/xml.
Binary content types (image/png, image/jpeg, font/woff2, application/octet-stream) MUST NOT be compressed. They are already optimally encoded and compression wastes CPU.
Gateways MAY cache compressed variants alongside the uncompressed object to avoid re-compressing on subsequent requests.
8.11 Relay Node Bandwidth Economics
CIP-9 specifies that Relay Nodes earn storage fees proportional to the shards they store (CIP-9 §10). This CIP introduces Gateways as readers that may fetch many shards for popular static sites. The bandwidth cost model:- The volume owner (actor’s account) pays for Relay Node storage via per-epoch storage fees (CIP-9 §10). These fees cover the cost of storing and serving shards.
- Gateways do NOT pay per-shard-fetch fees directly. The bandwidth cost is absorbed into the Relay Node’s storage fee revenue, analogous to how a CDN origin server absorbs bandwidth from CDN edge pulls.
GET_SHARD and GET_MANIFEST requests to prevent bandwidth abuse:
- Per-source-IP rate limiting (suggested:
MAX_SHARD_READS_PER_SECOND = 1000per IP). - Per-volume rate limiting (suggested:
MAX_SHARD_READS_PER_VOLUME_PER_SECOND = 500per volume per IP). - Total bandwidth throttling per connection.
8.12 Routes Fetching (Gateway ↔ Full Node)
The routes table is fetched from the actor’s KV state, not from a Relay Node. The Gateway reads it withGET_STATE (CIP-17) against a full node; Runners do not serve GET_STATE yet (CIP-17 §1).
- The Gateway fetches via
GET_STATE(actor_address, "__cowboy/routes"). - The Gateway verifies the response per CIP-17 §5.3:
state_rootequals the unified state root of a block header it trusts atblock_height, and the QMDB/MMR operation proof (CIP-17 §5.2) authenticates the(actor_address, key)operation against that root. Cowboy has no per-actor storage trie or per-actor state root. - If both checks pass, the Gateway deserializes
valueasRoutesand validates per §6.8. - The verified routes table is cached, keyed by
actor_address.
__cowboy/routes every MANIFEST_POLL_INTERVAL blocks and replaces the cached routes table when the verified value changes.
If value is empty (the actor declares no routes), the Gateway falls back to all-CIP-14 dispatch: every request the CIP-37 site gate admits reaches the http.request handler.
State reads against a full node are part of normal protocol operation (block production, RPC) and do not incur additional fees. Per-read rate limits MAY be enforced locally by full nodes (suggested: same MAX_SHARD_READS_PER_SECOND as Relay Nodes).
8.13 Serving Authority by Volume Status
Gateway HTTP serving authority follows the CBFS volume lifecycle (CIP-9 §13) throughACTIVE, GRACE_PERIOD, DELETED, and GARBAGE_COLLECTING in that order.
Continuing to serve in
GRACE_PERIOD lets the owner top up storage fees while the Gateway serves responses with an advisory header instead of abrupt 503s. The hard halt happens at DELETED (intentional removal) and GARBAGE_COLLECTING (irreversible). This bounds the “free CDN” externality (Gateway caches continuing to serve after the owner stops paying) within STORAGE_GRACE_EPOCHS per CIP-9.
8.14 Runner-Target Dispatch (Gateway → Runner)
For aRunner-target route (resolution §6.6 step 7), the Gateway does not invoke the actor’s PVM. It proxies the request off-chain to a runner and relays the response.
The current Gateway resolves only the explicit runner pin to its advertised endpoint; absent pins or unavailable endpoints return 503 (§6.2). The eligible-set algorithm below is target design in its entirety: job filters, runner_bindings/requires intersection, pin-in-set validation, HRW affinity, and load balancing are not current selection guarantees. The binding-scoped mount issuance below is likewise unimplemented. A forwarded mount declaration is not evidence of a scoped CapToken or DEK grant.
In the unimplemented target design, the Gateway would resolve the route to a runner per request. It reads runner registry state (as it already does to fetch routes) and applies the same eligibility filters the dispatcher applies to jobs (the registry’s filter_job_candidates): capability / job-type, the CIP-2 required_runner_pool entitlement (CIP-2 §7.3), TEE, rate card, active-job capacity, and health / heartbeat (derived from last_heartbeat). It then makes the pick itself:
- Build the eligible set
E= runners passing those filters, intersected with the route’srequires, the actor’srunner_bindingsentitlement (§7.5), and current RAS health. (requires.regionis checked route-side against the runner’s advertisedcapabilities.regions; the job filter doesn’t apply region today.) IfEis empty, return503 Service Unavailable. - If the optional
runnerpin is set: use it if it is inE, else503. - Else if
affinity ≠ none: pickargmax(r in E) of H(affinity_key, r.id)using rendezvous (HRW) hashing. The same key maps to the same runner while it stays inE; when a runner leavesE, only the keys that were on it move to their next-best, leaving every other key undisturbed. Theaffinity_keyis the caller account (caller), a client-supplied session id (session), or unused (none). - Otherwise, spread across
Eby selecting the least-loaded runner by advertised active-job count, or by round-robin selection.
route_serving_endpoint in its RAS registration. This CIP requires that new registration field. The Gateway reuses existing registry data and mirrors the job-dispatch eligibility filters where they exist; the route-only additions are region filtering, HRW affinity, optional route-pin validation, and the route_serving_endpoint proxy.
The Gateway dispatches to the selected runner’s route_serving_endpoint:
(actor_address, handler) to deployed code; it MUST already have a handler registered for (actor_address, handler) before the Gateway may dispatch. Deployment and registration are out of scope. The runner returns 502 if the handler is absent. The runner returns a normal HTTP response (status, headers, body or chunked stream); the Gateway relays it verbatim, applying only the CORS rule (§9.4), timeout_ms, and the 502/504 mapping. For auth = "account" the Gateway is untrusted transport and asserts no caller identity; the identity it attests for access (CIP-37 §9) does not replace the runner’s check.
For auth = "account", the caller uses a new signed-request scheme. The payment-specific EIP-712 SessionVoucher does not authenticate the caller. The caller signs, with their Cowboy-account secp256k1 key, a canonical preimage over:
handler="a",verb="bc" and handler="ab",verb="c" would share a signature). The signature is over keccak256(preimage), recoverable to the caller’s account. The recovered signer is the caller, which may be any Cowboy account, authenticating as itself and not as the actor. A single endpoint serves every authenticated user under their own identity (the multi-user model). The runner recovers the signer (reusing the runner’s existing secp256k1 recovery utilities), verifies chain_id and network against its own deployment (rejecting a signature minted for another chain, preventing cross-deployment replay that per-runner nonce stores cannot prevent), checks expiry (a bounded validity window) and the single-use nonce for replay, forwards the recovered caller to the handler, and binds the request to that account; on any failure it returns 401, which the Gateway relays. For auth = "account" the Gateway never asserts caller identity. (host is gateway-forwarded and not independently verifiable by the runner under the untrusted-gateway model, so it is not bound.) The recovered account is what authorizes a caller-owned mount (§7.5).
The runner self-enforces auth from RouteContext.auth: a route with auth = "account" and no account_sig is rejected 401 even when a request reaches the runner directly. The Gateway’s account_sig presence check supplements this runner check.
In the unimplemented target design for route-binding mount issuance, the runner would hold no standing grant; the dispatcher issues it a CapToken (and, for a private volume, a CBSS-sealed DEK) per mount, scoped to the mount’s volume, mode, and path_prefix and never broader than the relevant grant. The same issuance path attaches volumes to a job:
- For
owner = "actor", the dispatcher issues the token under the actor principal, bounded by the actor’srunner_bindings(§7.5). - For
owner = "caller", the dispatcher issues the token under the actor principal for the authenticated caller’s volume. This is valid only because the caller granted the agent actor mount access (§7.5) and the runner verified the caller’s signature. Writes commit back to CBFS (advancing the volumemanifest_root) as normal, leaving the data owned by the caller.
ingress.http max_request_bytes cap) before forwarding. This lets body_sha256 bind the signed request. The runner executes the handler off-chain (no consensus, no deterministic-PVM constraint: LLM inference, outbound HTTP, streaming) within timeout_ms, and the Gateway streams the response back as it arrives. Streaming request bodies (with a stream_session_id-bound signature) are deferred. On timeout_ms expiry the Gateway returns 504 Gateway Timeout; on a runner transport/handler error, 502 Bad Gateway.
A resolved client-paid model is gated exactly as for Method (§6.6): the Gateway enforces CIP-18 (402) before forwarding. Metering of the off-chain work itself (tokens, wall-time) is a runner/RAS concern, out of scope here.
Runner-target CORS follows the Method rule (§9.4): the runner’s response headers are authoritative; the Gateway fills CORS only when the runner sets none.
In v0, the runner is trusted to execute the route faithfully, as for any runner to which an actor dispatches a job. Verifiable / multi-operator runner serving (attested execution, on-chain settlement) is deferred (§13).
CIP-9 mount-allowlist grants to a principal, dispatcher-issued per-runner CapTokens, and CBSS DEK seal for private volumes already ship. This CIP adds the Runner route target; the proxy from the Gateway to the runner; a route-serving endpoint advertised in RAS registration; a route caller-auth signing scheme (distinct from the payment voucher); and selecting a caller-owned volume from the authenticated HTTP caller per request.
8.15 Workload-Target Dispatch (Gateway → Workload)
For aWorkload-target route (resolution §6.6 step 8), the Gateway relays the connection to one long-lived registered workload. There is no per-request selection: the route names a workload registry record, and the record names the backend.
A persistent workload carries a control-plane workload registry record. This CIP consumes five of its fields, workload_id (what Workload.workload names), owning_actor (what the §6.8 validation binds routes to), serving_endpoint (where the Gateway relays), reporter (the claiming Runner), and host_pool (the CIP-2 Runner pool its claim came through); the Gateway reads the reporter’s pool entitlement, its slot binding and its accountable registration (the host Runner’s RunnerRegistration for a bound slot, its own otherwise, CIP-10 §17.3.5) at the same proof point to decide whether the workload is still eligible and whether the endpoint must be public (CIP-10 §17.4.1 and §17.3.4). It also checks route eligibility: the Gateway relays only to a workload whose desired_state is Running and whose current attempt is either Running or a finalized Prepared attempt within its preparation lease, with a fresh liveness lease (CIP-10 §17.4.1); an ineligible workload returns 503. The initial record carries volume mounts only. Secrets and egress capabilities are deferred. There is no route-binding field; route binding lives in the actor’s __cowboy/routes table. A Workload target has no mounts of its own. Workload-target routes are a hard dependency on that registry: no record, no route.
The actor declares a Workload target, installed in its proof-backed __cowboy/routes table (§6.9). The Gateway resolves that table through its normal actor-route cache and requires the registry record’s owning_actor to equal the URL actor at every connection establishment. An upgrade can replace a Volume target with a Workload target under the same actor URL, without a Gateway configuration edit or restart. The operator may still configure fallback routes for infrastructure-owned cases; their schema is:
Workload target shape is the same for actor-owned and operator fallback routes. expected_workload_owner exists only in operator configuration; an actor-declared route cannot override the registry owner check.
Operator-configured workload routes remain owner-only under CIP-37, even on a published site. Public workload routing requires the owner-approved canonical manifest and its exact target binding; a local configuration entry cannot inherit an absent-table publication approval.
The operator configuration key is (actor, verb, path). A static entry belongs to a specific actor’s URL space, never a hostless global. Duplicate keys are invalid. Ownership is validated at every establishment: an actor-declared route MUST resolve only a record whose owning_actor equals that actor. For an operator route, absent expected_workload_owner, the named record’s owning_actor MUST equal the entry’s actor; present, owning_actor MUST equal expected_workload_owner, which MUST differ from actor. This is the explicit cross-owner form (one actor’s URL space fronting another principal’s workload), with a typed principal. A record later repointed to a different owner fails closed (§8.15 tests require the record-swap negative).
Collision depends on semantic overlap, not key equality. An operator static entry collides when its verb set intersects an actor-declared route’s verb set (ANY intersects every verb) and the two path patterns can match any common path (wildcard, parameter, and literal segments considered; /api/* overlaps /api/admin; ANY /chat overlaps GET /chat). The Gateway MUST reject such entries when loading configuration against the current actor-route snapshot. Because actor routes can change after startup, it MUST recheck overlap against the current actor-route snapshot before serving any operator fallback candidate. If a newly observed actor route overlaps an already loaded static workload route, the actor-declared route wins and the Gateway MUST reject the conflicting fallback while that actor-route snapshot applies, emitting a high-severity diagnostic identifying both patterns when the fallback is attempted. A stale cache or lookup order MUST NOT let operator configuration override a consensus Method route or its payment policy. Both binding modes share the dispatch semantics below, so promoting a static route to an actor-declared one changes where the route lives, not how it serves.
The registry serving_endpoint is a base URL. The Gateway appends the matched request path (after applying strip_prefix; preserving a leading /) to the endpoint’s base-path prefix and forwards the original query string verbatim. It MUST NOT follow backend redirects. It forwards end-to-end request headers, replaces Host with the backend authority, removes the standard hop-by-hop headers and every header named by Connection, and adds X-Cowboy-Route-Context; response headers receive the same hop-by-hop filtering before relay. The original Origin is end-to-end and MUST NOT be rewritten. The Gateway forwards Authorization byte-for-byte. It MAY parse and validate the Payment scheme for CIP-18 gating; other application schemes remain opaque. It MUST NOT log the header value.
For a plain or streamed HTTP exchange the Gateway buffers the request body per §8.14’s max_request_bytes rule, establishes the backend response within WORKLOAD_CONNECT_TIMEOUT_MS, then relays the response body unbuffered: each non-empty backend body chunk is yielded downstream as it arrives, without applying the Runner response-byte cap. SSE (Content-Type: text/event-stream) is the motivating case: events MUST NOT be accumulated into a complete body, deliberately coalesced, or compressed by the Gateway. idle_timeout_ms bounds response-body silence after headers arrive. Each non-empty body chunk resets it; on expiry the Gateway drops the body stream. max_connection_ms, when set, starts when the route is admitted and hard-caps establishment plus the response body’s lifetime. Client disconnect MUST immediately drop the backend response/body, which cancels upstream reads, and release the route’s concurrency permit.
For a valid WebSocket upgrade request the Gateway applies auth / pays gating, resolves and checks the workload record, and completes the backend handshake before sending 101 Switching Protocols to the client. A backend HTTP rejection (including 401) is relayed as an HTTP response; timeout and transport failures use the mappings below. The Gateway forwards the client’s Sec-WebSocket-Protocol offers and returns only the protocol selected by the backend. The Gateway does not negotiate WebSocket extensions: it removes Sec-WebSocket-Extensions on both handshakes rather than claiming an extension independently on either leg.
After both upgrades, the Gateway terminates the two WebSocket legs and relays data messages and close semantics in both directions without inspecting application payloads. Message bytes and text/binary opcode MUST be preserved, but fragmentation and masking are hop-local and MAY be re-encoded. Ping and pong are handled hop-locally by each terminated leg (not forwarded, which would create duplicate automatic pong responses) and count as traffic for idle_timeout_ms; silence means no frame in either direction. max_connection_ms starts at route admission and includes both handshakes. On backend transport death without a close frame the Gateway sends the client close code 1011 and closes; a normal backend close is forwarded, and client disconnect or close closes the backend side. Streaming request bodies outside an upgraded connection remain deferred (§13).
auth = "account" follows the §8.14 signing scheme’s construction, with length-prefixed fields, keccak256, secp256k1 recovery, chain_id/network binding, expiry, and a single-use nonce. It uses a distinct fixed domain tag for workload route authentication, the literal ASCII bytes "cowboy/cip15/workload-route-auth/v1", pinned here so independent client and workload implementations can produce matching golden vectors (§8.15 tests require them, alongside the cross-target negatives). The workload record id (32 bytes) occupies the slot handler occupies in §8.14; for a body-less upgrade request body_sha256 is the hash of the empty body. The distinct tag means a signature minted for a Runner route can never validate on a Workload route or vice versa, even if a handler string collides with a workload id. The two targets have separate verifiers and nonce stores, so shared-domain reuse would replay once in each (§8.15 tests require the cross-target negative vector).
The Gateway forwards X-Cowboy-Route-Context: base64url(CBOR(WorkloadRouteContext)), where WorkloadRouteContext contains actor_address: bytes20, workload: bytes32, verb: string, the forwarded path: string, path_params: list<(string,string)>, authenticated_sender: bytes20? (CIP-37 §9), auth, optional payment_proof, optional account_sig, optional account_expiry, optional account_nonce, chain_id: u64, and network: string. It has no handler or mounts fields. payment_proof is only raw client X-Payment header material when supplied; it is not an authenticated payment result and may be absent even when another payment credential was accepted. The workload verifies the signature and self-enforces auth from this context. The Gateway’s complete-field presence check supplements that verification; the Gateway asserts no caller identity. Per-message authentication inside an established stream is the workload’s own concern (it holds the authenticated identity from establishment).
A resolved client-paid model gates establishment exactly as for Method (§6.6): 402 before the upgrade or first streamed byte. A successful payment gate authorizes establishment of that connection; a pass or subscription may clear it without a new per-connection charge. The streaming-payments protocol handles usage-metered settlement above this transport. Metering tokens, messages, or wall-time is out of scope here.
SSE and plain HTTP responses follow the Method rule (§9.4): the workload’s response headers are authoritative; the Gateway fills CORS only when the workload sets none. Browsers do not enforce CORS on WebSocket connections. An auth = "public" WS route is reachable from any origin’s JavaScript. Therefore the workload MUST validate the Origin header itself for browser-facing endpoints (§12.12), and user-bound streams SHOULD use auth = "account".
A Gateway deployed behind a load balancer or reverse proxy (ALB, nginx) MUST have that layer configured for long-lived streams, or the layer silently breaks what this section specifies: idle timeout above the workload’s heartbeat interval (or the LB kills healthy connections), response buffering disabled on streaming routes (or SSE events arrive in bursts after the fact), and request-body size caps reviewed (an intermediary defaulting to small body caps rejects requests far below the application’s own limits, as observed on public RPC endpoints). Operators configure these settings in their deployment; the settings are outside the protocol parameter set.
For actor-declared routes, the concurrency key includes actor, verb, path, workload ID, and route limit so concurrent establishments of the same route share a cap; an updated workload binding receives its own cap. Operator fallback entries use their static (actor, verb, path) identity. The Gateway acquires a permit before registry resolution or backend dialing and holds it through the complete HTTP body or WebSocket lifetime; handshake attempts therefore count against the cap and cannot form an unbounded slow-establishment queue. At max_concurrent_streams (default DEFAULT_MAX_CONCURRENT_STREAMS) it returns 503 Service Unavailable immediately.
For every admitted establishment, the Gateway reads the current registry record and checks: the id exists; owning_actor satisfies the rule above; route eligibility is true at the record snapshot’s current block; and serving_endpoint passes workload-registry validation plus the Gateway’s transport policy. Missing, ineligible, owner-mismatched, or invalid records return 503 Service Unavailable without dialing. Backend DNS/connect/TLS failure or connection refusal returns 502 Bad Gateway. A backend HTTP or WebSocket handshake not completed within WORKLOAD_CONNECT_TIMEOUT_MS returns 504 Gateway Timeout. After response headers or 101 have been sent, later timeout or transport failure terminates the stream because its HTTP status can no longer be changed.
The host determines the trustworthiness of a workload-served route. Gateway relaying adds no verification. Authors choose verification per route: the same actor’s URL space can mix Volume routes (content-addressed, verifiable), Method routes (consensus), and Workload routes (host-trusted). The actor’s route authority does not attest to the host’s execution; verifiable workload serving is deferred (§13).
9. CORS
9.1 Why CORS Is Specified Here
This CIP is the first specification where browsers will directly consume Gateway responses. Static HTML pages served from one actor’s domain will fetch JavaScript, CSS, and API endpoints from the same or other actors. Without CORS headers, browsers block cross-origin requests. Deferring CORS any further would make this CIP unusable for real web applications.9.2 Configuration
CORS is configured via_meta/cors.json in the CBFS public volume:
9.3 Example
9.4 Default CORS Policy and Precedence
When no_meta/cors.json exists, the Gateway applies a permissive default for routes whose target is a Volume:
Visibility::Public volume are public by definition. Restricting their CORS policy by default would break most web applications. The permissive default matches CDN behavior (Cloudflare, Fastly, S3).
- For
Method-target routes, the actor’sHttpResponseEnvelopeis authoritative. If the response includes anyAccess-Control-*headers, the Gateway passes them through unmodified and adds nothing. Otherwise, the Gateway applies matchingcors_configrules. Otherwise, no CORS headers are added. The actor retains control of CORS for its dynamic responses. - For
Volume-target routes, the Gateway appliescors_configrules. If no rule matches, the default policy above applies. The actor is not invoked. - For
Runner-target routes, the runner’s response is authoritative, exactly as forMethod. If it sets anyAccess-Control-*headers, the Gateway passes them through unmodified; otherwise the Gateway applies matchingcors_configrules, else no CORS headers are added. The permissiveVolumestatic-asset default is never applied to aRunnerroute. - For
Workload-target routes, the workload’s response is authoritative, exactly as forMethodandRunner. The Gateway passes through anyAccess-Control-*headers the workload sets. Otherwise it applies matchingcors_configrules, or adds no CORS headers if none match; theVolumedefault is never applied. WebSocket upgrades are outside CORS entirely (browsers do not enforce it on WS): Origin validation is the workload’s responsibility (§12.12).
9.5 Preflight Handling
The Gateway handlesOPTIONS requests for all routes directly, without dispatching to the actor or runner:
- Match the request path against
_meta/cors.jsonrules. The permissive default policy applies only when the matched route’s target is aVolume; forMethod,Runner, andWorkloadtargets, preflight usescors_configrules or, failing a match, noAccess-Control-*headers. It never uses theVolumedefault or the backend’s response headers. - If the
Originheader matchesallowed_originsand theAccess-Control-Request-Methodmatchesallowed_methods, return204 No Contentwith the appropriateAccess-Control-*headers. - If no match, return
204 No Contentwith noAccess-Control-*headers (the browser will block the actual request).
OPTIONS in the allowlist_methods entitlement parameter and waste query-path cycles on a pure CORS check.
10. Protocol Constants
11. Rationale
11.1 Why Routes Are Installed With Code
Routes decide which code answers which request and who pays for it. Writing them through the actor’s own KV path would let them drift from the code. An admin handler could install a stale table, or an upgrade could rename a handler without updating the table. Each write would require validation. Tying the table to deployment and upgrade gives one validated install per code version, lets the node enforcestatic_volumes membership once instead of the Gateway on every request, and leaves actor code with no path to the table at all.
Prices live in the CIP-18 price_table, assets in their volume, and everything else in a code upgrade.
KV storage remains the location because the Gateway verifies a single Merkle-proven value without executing the actor (§8.12), and an API-only actor needs no volume. An actor routes() method was rejected because every dispatch would require PVM execution to read the table.
11.2 Why Extend ingress.http Instead of a New Entitlement
Routes select how the Gateway handles HTTP requests. The Gateway dispatches some to named handlers and serves others from a volume. A separate ingress.static entitlement would require checking two entitlements on every request and complicate the Gateway’s dispatch logic. Extending ingress.http keeps the parameter space unified.
11.3 Why Polling-Based Cache Invalidation
Relay Nodes and Runners do not support push notifications for cached state. Subscribing to on-chain events for every cached volume and actor creates scaling concerns as the number of active actors grows. PollingStorageCommitment.manifest_root for volumes and the proven __cowboy/routes value for routes is cheap (one small read per anchor per MANIFEST_POLL_INTERVAL blocks) and sufficient. The resulting invalidation latency (up to ~6 seconds) is acceptable for both asset deploys and route updates.
11.4 Why Include CORS
This CIP is the first specification where browsers will directly consume Gateway responses at scale. Without CORS headers, a static HTML page served fromapp.example.org cannot load JavaScript from api.example.org or fetch data from its own /api/ endpoints if they are on a different subdomain. Deferring CORS to yet another CIP would make this one impractical for real web applications.
11.5 Why Permissive CORS Default for Static Assets
Public volume assets are, by definition, publicly readable. Any party can fetch them from Relay Nodes directly without authentication. Restricting CORS origins by default would create a mismatch: the data is public, but browsers cannot access it. This matches the behavior of every major CDN and static hosting provider.11.6 Why Actor-Wins CORS Precedence on Method-Target Routes
ForMethod-target routes, the actor’s response envelope is authoritative for CORS. The Gateway only fills in CORS headers when the actor sets none. Allowing cors_config to override actor-set headers could remove a security restriction, such as an Access-Control-Allow-Origin limited to a single trusted origin.
11.7 Why b3_ ETag Prefix
ETags are opaque strings in HTTP, but clients and intermediary caches may compare them. The b3_ prefix:
- Distinguishes BLAKE3 hashes from MD5, SHA-256, or other ETag formats used by other servers.
- Enables clients that understand BLAKE3 to verify content integrity end-to-end by stripping the prefix and comparing against
BLAKE3(response_body). - Avoids collision with weak ETags (which use the
W/prefix per RFC 7232).
11.8 Why a Runner Target (Off-Chain Compute Belongs Off Consensus)
The deterministic PVM cannot run LLM inference, call external APIs, or stream long responses. Consensus execution also imposes cycle, block-time, and RPC body limits. For a Runner target, the Gateway proxies the request to the runner without a transaction and streams the response back. This uses existing runner execution, mounts, and secp256k1 recovery utilities. The caller-authentication scheme is new (§8.14). Method targets execute actor handlers through the query or command path selected by their mode; Runner targets execute off-chain.
12. Security Considerations
12.1 Cache Poisoning
A compromised Relay Node serves corrupted shards, causing the Gateway to cache and serve incorrect content. The Gateway verifies every layer of the integrity chain (§8.5–§8.6):- Manifest against on-chain
manifest_root(Merkle root). - Each shard against its
shard_hash(BLAKE3) from the verified ObjectDescriptor. - Reconstructed object against its
content_hash(BLAKE3).
manifest_root (requires consensus compromise).
12.2 Volume Impersonation
An actor declaresstatic_volumes pointing to a volume it does not own, serving another account’s data under its own domain.
Every Volume target’s name must be in static_volumes (§7.3). Without an explicit volume_id, the node resolves it at install from the installing account (§6.9), so the mount serves that account’s own volume and cannot be moved afterwards by changing the actor’s owner. An explicit volume_id serves another account’s Visibility::Public volume, and only when the owner grants that name in static_volumes; the content is already public, and the route claims no ownership over it.
12.3 Large Asset DoS
An actor stores very large objects in a public volume and drives traffic to them, exhausting Gateway resources. The following measures limit this attack:- The Gateway caps individual object sizes at
max_static_response_bytes(default 10 MiB, ceiling 100 MiB) and returns413 Content Too Largeabove the cap. - Per-volume
max_cache_bytesis a proposed mitigation and is not an on-chain field or an enforced entitlement quota (§7.4). MAX_GATEWAY_CACHE_BYTEScaps total cache across all volumes.- CIP-14 rate limits apply:
MAX_REQUESTS_PER_SECOND = 100per actor per Gateway. - CIP-9 storage billing makes hosting large volumes expensive for the account owner.
12.4 Stale Manifest
A Gateway serves content from an old manifest after the volume owner has deployed an update (e.g., serving a version with a known security vulnerability).MANIFEST_POLL_INTERVAL (6 blocks) bounds the maximum staleness to ~6 seconds. The X-Cowboy-Block and X-Cowboy-Manifest-Root response headers tell the client which block and manifest were used. Clients requiring strict freshness can include X-Cowboy-Min-Block (CIP-14 §8.3) or X-Cowboy-Manifest-Root (§8.8) request headers; mismatch yields 409 Conflict.
12.5 Routes Table Manipulation
A malicious or compromised actor routes handler-served paths to aVolume target (bypassing authentication logic), changes the fallback payment gate from pays = caller to pays = actor when no enabled price_table applies, or points a route at a different handler than expected.
The routes table is authored by the actor owner and installed with the owner’s code. A malicious table means a malicious owner, which is outside the protocol’s threat model. The following invariants hold regardless:
/_cowboy/*paths are always Gateway-intercepted (CIP-14 §8.6).- Actor code cannot write the table. Routing changes only with new code: a system deployer’s
UpgradeActor, orupgrade_selffrom code holdingsys.upgrade(§6.9). Any other actor keeps its deployed routes for life. Volumetargets are restricted to the actor’sstatic_volumesat install (§7.3).- The node rejects invalid tables at install (§6.8), so a table never reaches the Gateway unvalidated.
12.6 Routes Cache Poisoning
A compromised Runner serves a tampered routes value viaGET_STATE, causing the Gateway to dispatch requests according to attacker-controlled routes.
The Gateway verifies every GET_STATE response against the unified state root of a trusted block header using the supplied QMDB/MMR proof (§8.12, CIP-17 §5.3). A response that does not verify is rejected; the Gateway tries another full node. To poison the cache, an attacker would need to forge the on-chain state root (consensus compromise) or produce a Merkle proof collision (computationally infeasible).
12.7 Free-CDN Externality on Delinquent Storage
A Gateway continues to serve cached objects for a volume whose owner has stopped paying storage fees, externalizing bandwidth onto Relay Nodes that are no longer compensated. §8.13 ties Gateway serving authority to the volume’s CIP-9 status. Serving terminates atDELETED and GARBAGE_COLLECTING. The GRACE_PERIOD window is bounded by STORAGE_GRACE_EPOCHS, beyond which the volume transitions to DELETED regardless of cache state.
12.8 CORS Misconfiguration
An overly permissive CORS configuration (allowed_origins: ["*"] with allow_credentials: true) could enable credential-leaking cross-origin attacks.
Gateways MUST reject CORS configurations where allowed_origins includes "*" and allow_credentials is true. The CORS specification forbids this combination; browsers also reject it. If detected, the Gateway falls back to the default CORS policy.
12.9 Runner-Target Trust
A selected runner may return a wrong result, leak a request, or misuse a mounted volume on aRunner-target route.
An explicit pin selects a trusted operator, and current Gateway selection provides no runner_bindings authorization or binding-scoped mount-issuance guarantee. Do not rely on the following target rules as a current blast-radius bound.
Under the unimplemented route-binding design, the actor trusts the runner to execute the route faithfully, as with runner jobs. The blast radius is bounded by what the route authorizes: a runner may only mount volumes named in the actor’s runner_bindings (owner = "actor") or a volume the caller granted it (owner = "caller"), each under a scoped CIP-9 mount-allowlist grant and, for private volumes, a per-job CBSS-sealed DEK. The Gateway is untrusted transport and asserts no result authority. Verifiable runner execution (attestation, fraud proofs) and on-chain settlement of off-chain work are deferred to a follow-on CIP (§13).
12.10 Caller Authentication and the Untrusted Gateway
For anauth = "account" route, a malicious Gateway forges or strips the caller’s identity to reach a handler as the wrong account (e.g., to mount another user’s caller-owned volume).
Caller authentication is performed by the runner, not the Gateway. The runner verifies the caller’s secp256k1 signature (ecrecover) over the request. Binding a caller-owned mount to that account and issuing its scoped grant are unimplemented target design (§7.5, §8.14). A Gateway cannot forge a signature it does not hold, and a stripped signature simply yields 401. The Gateway’s own attestation under CIP-37 (authenticated_sender) is separate and is not accepted as a substitute for this check. Confidential request bodies SHOULD be encrypted to the runner so the Gateway sees only ciphertext (mechanism out of scope).
12.11 Streaming Connection Exhaustion
Long-livedWorkload connections are held open en masse (slow-loris on upgrade requests, idle websockets, abandoned SSE streams), exhausting Gateway or workload connection capacity that request-scoped timeouts never reclaim.
Every established stream is bounded by idle_timeout_ms (silence in both directions tears it down) and optionally max_connection_ms; establishment is bounded by WORKLOAD_CONNECT_TIMEOUT_MS; per-route concurrency is capped at max_concurrent_streams with 503 beyond it. The Gateway does not queue excess streams, preventing an unbounded backlog. A resolved client-paid policy gates establishment.
12.12 Cross-Origin WebSocket Hijacking
Browsers do not apply CORS to WebSocket connections, so any origin’s JavaScript can open a WS to anauth = "public" Workload route and act with the visiting user’s ambient context.
The workload MUST validate the Origin header on browser-facing WS endpoints and reject unexpected origins. User-bound streams SHOULD require auth = "account", which binds establishment to a caller signature no foreign origin can produce. The Gateway relays Origin verbatim and never rewrites it.
12.13 Workload Endpoint Hijack
An attacker redirects aWorkload route’s traffic by tampering with the serving endpoint or substituting another workload ID, turning a trusted route into an attacker-controlled backend.
The registry record is the single binding authority for the endpoint. Registration and updates are authorized by the owning actor’s controller, and the endpoint is written only by a claim from a Runner holding the record’s host-pool entitlement whose accountable registration, its own or its host Runner’s, is staked (CIP-10 §17.3.2, §17.3.3, §17.3.5). The Gateway resolves the endpoint from the record at connection time and never accepts an endpoint from request data. An actor-owned route can name only a workload whose registry owner is that actor; a wrong-owner ID fails closed. Operator static configuration for first-party workloads is operator-trusted by definition. A claimant admitted through a reserved cby- pool MAY use a private-network endpoint, and platform deployments MAY use mutually authenticated transport. Any other claimant’s endpoint MUST be public, and the Gateway MUST resolve it and refuse a non-public address before every dial, so a repointed DNS name cannot reach an internal service (CIP-10 §17.3.4).
13. Future Work
14. Relationship to CIP-14
- An actor that declares no routes has no
__cowboy/routesvalue. Gateways dispatch every request for it that the CIP-37 site gate admits to thehttp.requesthandler per CIP-14. static_volumesandmax_static_response_bytesare optional. An absentstatic_volumesadmits noVolumeroutes; an absent cap means the 10 MiB default.runner_bindingsis an unimplemented target-design parameter (§7.5). Current manifest validation rejects it, even as[]; currentRunnerdispatch instead requires an explicit pin and advertised endpoint (§6.2). The target default[]is not a currently accepted deployment value.- A
Visibility::Publicvolume is served only when an actor grants it instatic_volumesand declares a route that mounts it. - The
_meta/cors.jsonfile is optional. Volumes without it use the default CORS policy (§9.4). - A Gateway without routes support dispatches every request to the
http.requesthandler. - Every gateway serving a host must enforce CIP-37 before exposing that host. Provisioning, policy refresh, or enforcement failure serves no application traffic.
frame-ancestors 'none'. API and asset responses are not rewritten. CIP-37 §10 governs private receipts, direct backends, and indexing, and §11 distinguishes access control from confidentiality of public storage.
15. Host Resolution and HTTP Envelopes
15.1 Actor resolution
The operated Gateway resolves an actor using its configuredresolution.mode:
For host resolution, the Gateway strips the optional port from the
Host header before looking up the static map. A configured mapping takes precedence over actor-address subdomain parsing. The operator supplies mappings such as:
15.2 HTTP envelopes
The Gateway’s Method-target dispatch uses the following request and response shapes (gateway-types::HttpRequestEnvelope and HttpResponseEnvelope). This section is authoritative for these envelope fields.
path_params contains named parameters extracted from the matched route (§6). Headers are pairs so repeated header names can be represented. The envelope is CBOR-encoded for actor dispatch; body is a byte string.
host is request metadata, not proof of domain ownership or tenant authorization. The envelope contains no protocol-attested verified_fqdn or namespace_kind. Actor authorization MUST use the application’s authenticated identity and policy rather than treating a hostname as a domain-control attestation.