# Backend apps

### What a backend app is for

1. **A backend app is an API server.** A backend app (a `@simple_server` server behind root) answers API calls from pages and agents: JSON, files, redirects, webhooks. Browser pages (an HTML UI) live in a frontend app (`https://pam.pilely.app/specs/frontend_apps`), and those pages call the backend. This is a guideline: root does not enforce it, and forwards whatever the backend answers (`### Forwarding to backend apps`). A backend that serves browser pages is outside what the platform supports, and root adds nothing to make it work. On a `public` app such a page may load. On a `protected` or `private` app a browser page load carries no token and gets the uniform `404`: no bootstrap page and no shell ticket stand in front of a backend app. Anything else you build on a backend's pages is at your own risk.
2. **How a frontend app's pages call the backend.** A page calls the backend's host with `fetch`, and root grants it CORS (`### Forwarding to backend apps`, item 7). With no token, the call is the anonymous caller shape (`### Forwarding to backend apps`, item 3): it reaches a `public` app's reads (`GET`, `HEAD`, `OPTIONS`), and anything else only through a `public` public route (items 4 and 5 there). The frontend app's token, sent with `window.pilely.fetch`, is another app's token on the backend's host: root admits it only on a path covered by an `app` public route whose `@simple_group` holds the frontend app as an `app` member (item 5 there), and the backend then receives the person as `user:<id>` on the frontend app (item 3 there). Everywhere else root treats it as no token. **The usual setup:** put the routes the pages call under `/api`, and add one `app` public route at `/api` with `methods: ["GET", "POST"]` whose `@simple_group` holds the frontend app as an `app` member (`https://pilely.app/README.md` → `### POST /~/apps/{pile_id}/public_routes/add`). A sender with no token, such as a webhook, gets its own `public` public route.

### Forwarding to backend apps

1. **Root forwards every request unchanged.** On a backend app's host (`<label>.pilely.app`, or a custom domain bound to it) root forwards every request to the app's server exactly as the caller sent it: `GET`, `HEAD`, `POST`, any method, any path (a path ending in `.md` included, untouched), the caller's own `Accept` and query string. One exception is `/README.md` on a user-owned app, which root answers itself for every method and never forwards (below). The other is a path root refuses on every host, before it even looks up the app: one that a standard URL parser would change before sending it on — a `\`, a `.` or `..` segment in any spelling (`/../`, `%2e%2e`, `.%2E`), or a character it would percent-encode (a raw `"`, `{`, `}` or non-ASCII byte; send those percent-encoded) — or one carrying an encoded separator, `%2F` or `%5C` in either case. It answers the same `404 pile_not_found` envelope the access gate answers, and the server receives nothing; so every path the server does receive is byte for byte the path root's gates checked. Send the plain form of a path (`/admin`, not `/webhooks/../admin`). Before forwarding it runs its edge gates in this order: token resolution, the public-route lookup, the access gate (`404 pile_not_found`, `401 login_required`, or `401 token_expired`), the owner's limiter policies (`429 rate_limited` with `Retry-After`), the owner's traffic quota (`503 out_of_traffic_credits`), and the owner's storage standing (`503 storage_over_quota` to everyone, the owner included, while the owner is over their storage allowance: `https://pam.pilely.app/pricing.md` → `### Over the allowance`); then it stamps the forwarded identity. Past those gates root never answers for the backend and serves no bundle or SPA shell in front of it; a bundle on a backend row is never read. The backend owns every answer on its host (an API answer: a backend serving browser pages is unsupported, `### What a backend app is for`) except three: `/.well-known/*`, which root owns on every app host because it holds root's shell-ticket mint (`/.well-known/pilely/spa_ticket`): every other path under it is root's plain `404 not found`, never forwarded, so a backend cannot serve a file there, and a service that verifies a site by a `/.well-known/` file needs one of its methods that uses no file there instead, such as a DNS record on a custom domain you control (a method that reads a meta tag from an HTML page on the host is page serving, which a backend app does not support); `/README.md`, the app's one agent manual, which the owner uploads to root (`readme_md` at register, `POST /~/apps/{pile_id}/update_readme` later) and root answers after the same gates, so the backend never receives a request for it, whatever the method (both: `https://pam.pilely.app/specs/frontend_apps` → `### Serving frontend apps`, item 2); and any WebSocket upgrade, which is refused with `400 websocket_not_forwarded` before the app is even resolved (real-time sessions go through `@simple_wss`: `https://simple-wss.pilely.app/README.md`). Forward failures map to `503 pile_offline` (no running box), `504 pile_timeout` (past the app's registered `request_timeout_secs`, default 30s, capped), and a bare `502` with an empty body for a transport error or a response over the cap below. **Request and response bodies are capped at 5 MiB each**, because root buffers every forwarded body whole: a request body over 5 MiB is answered `413 body_too_large` before any edge gate runs, and a backend response over 5 MiB never reaches the caller, who gets that bare `502` and nothing of the body. Files are a `simple_db` column type and never need to ride this cap: a file belongs to the row that holds it, and the row's table decides who uploads, reads, replaces and deletes it (`https://simple-db.pilely.app/README.md` → `### File columns`). The bytes go straight between the caller and the storage host on signed links, never through root or the backend: for a file in the backend app's own tables, the server starts the upload with its backend token (a member of the table's groups through an `app` member) and hands the page the `upload_url`, the page PUTs the bytes there, and the server attaches the `upload_id` in its row write; to serve a file, the server answers its download link (`file_urls: true`, or the `download` route) or redirects to it. A file a user sends for the server to work on reaches it as request bytes within this cap, or through such an upload, which the server then reads from its link. **What comes back.** The backend's status and body reach the caller as the backend sent them: root never decodes or re-encodes the body, so a `Content-Encoding: gzip` answer arrives compressed with its header, and a `206` arrives with its `Content-Range`. Of the backend's response headers only these pass: `Content-Type` (the backend's value, else a fallback derived from the path; none on a `304` or a `HEAD` answer), `Location` (verbatim on any status, relative or absolute, never rewritten), `Set-Cookie` (under the cookie rules in item 5), `Cache-Control` (below), `ETag`, `Last-Modified`, `Expires`, `Vary` (the backend's values, then root's own `origin, accept, authorization`), `Content-Disposition`, `Content-Language`, `Content-Encoding`, `Content-Range`, `Accept-Ranges`, `Retry-After`, and every `X-*` header except `X-Pile-*`, `X-Pilely-*` and `X-Frame-Options`. Repeated headers stay repeated, in the backend's order; root computes `Content-Length` and the framing itself; every other header is dropped. `Cache-Control` passes verbatim on an anonymous answer that relays no `Set-Cookie`. Root makes it `private` on an answer that relays a `Set-Cookie` or answers a credentialed request (the caller presented a token, or root forwarded the backend a `Cookie`): it drops the backend's `public` and `s-maxage`, keeps every other directive in order (several lines merged into one), and puts `private` first unless a bare `private` or `no-store` is already there; a backend that sent no `Cache-Control` gets `private`. So `public, max-age=300` with a `Set-Cookie` arrives as `private, max-age=300`, and `no-cache` answered to a token as `private, no-cache`. Root follows no redirect: every `3xx` reaches the caller with its status, `Location` and body, on the same host or not, and the caller's own client follows it. A conditional `GET` (`If-None-Match`, `If-Modified-Since`) reaches the backend, and its `304` reaches the caller. Root's own headers always win: every answer carries root's `Content-Security-Policy: frame-ancestors 'self'`, `Cross-Origin-Opener-Policy: same-origin`, `Referrer-Policy: no-referrer` and CORS answer (item 7), and a backend can never set or change those, `Access-Control-*`, `Strict-Transport-Security` or `X-Frame-Options`. Root's own answers (`404 pile_not_found`, `401 login_required`, `401 token_expired`, `429 rate_limited`, `503 pile_offline`, `503 out_of_traffic_credits`, `503 storage_over_quota`, `504 pile_timeout`, the bare `502`) never carry a backend's headers.
2. **Where the backend listens.** `server/add` on `@simple_server` launches the backend on a managed box and injects `PORT=8080` into the app's environment; every box binds 8080, and the box security group carries the matching ingress rule. The value 8080 comes from `@simple_server`. The box is never reachable from the public internet: root reaches it over the private network (`http://<box ip>:8080` across the VPC peering) and nothing else can. Every user backend row has `forward_mode = managed_http` (register always writes it); root takes the app's live box list from a Redis-cached lookup, picks one at random, and retries once against a different box only on a connect failure. An empty list is an offline backend (`503 pile_offline`).
3. **Forwarded identity.** Root authenticates the caller at the edge and stamps the identity onto the forwarded request; it is stamped last, after the caller's headers, and every caller-sent `X-Pile-*` is stripped first, so a forged `X-Pile-Requester-*` cannot survive the hop.
   - Headers: exactly two, on every request, for every caller shape. `X-Pile-Requester-Entity` is who is calling: `user:<user uuid>` (a person), `app:<app pile uuid>` (an app's backend acting as itself: any of its boxes, never its owner), `agent:<agent uuid>` (toward the platform's internal services only) or `anonymous`. `X-Pile-Requester-App` is the pile uuid of the app the entity was authenticated on, always present. A uuid is always lowercase and hyphenated. Root copies the pair from the verified token unchanged and stamps nothing else: no handle and no box id. The handle is not part of the identity; key what you store on the user id.
   - There are five caller shapes. What a user backend receives for each:
   - **User**, a signed-in person's app token: `user:<id>`. The app's own token (minted for this app's host, for example by an agent with `POST /~/mint/app_id_token`) carries this app's pile uuid as the app. Another app's token, admitted by an `app` public route (item 5), carries that app's pile uuid; a delegation token carries the delegation's `azp` (the client app). An app other than this one means a foreign app is in the loop: decide on it, never treat it as a wildcard.
   - **Anonymous via app**, an app's anonymous token (the app's own, minted for a `public` app, or another app's, admitted by an `app` public route): `anonymous` on the app the token names. Root forwards its reads and its writes alike (item 4); what such a caller may read or write is the backend's choice, and the platform's own `simple_*` services refuse its writes.
   - **Anonymous**, no token: `anonymous` on this app. A bearer root does not admit on this host counts as no token; when the request is then refused and the bearer is an expired or revoked token that would have been admitted fresh, root answers `401 token_expired` instead (item 4). So `anonymous` on this app is both a signed-out visitor holding this app's anonymous token and a caller with no token at all; root refuses a tokenless write before it reaches the backend (item 4) unless a public route admits it.
   - **Agent**, an agent id token: it never reaches a user backend as an agent. Root decodes it only toward an internal service, so at a user backend the bearer counts as no token and the backend receives `anonymous` on this app (a write to a `public` app is then `401 login_required`, item 4). `agent:<uuid>` is stamped only toward internal services.
   - **Box**, a `@simple_server` box's backend token: it reaches a user backend only through an `app` public route (item 5) that admits the box's app, which is another app than the target. The backend then receives `app:<that app>` on that app: the app acting as itself, never its owner. Anywhere else, including a box calling its own app's host, the backend token counts as no token and the backend receives `anonymous` on this app. (corrected from /skill)
   - **Your own boxes, outbound.** A box of this app calling the platform's `simple-*` services with its `PILELY_BACKEND_TOKEN` is `app:<this app>` on this app there, the same caller for every box: never the owner, and never able to perform an owner-only action. It reaches a resource of this app only where the owner made the app an `app` member (`subject_type: "app"`, the app's pile uuid) of the group that guards that resource, at `https://simple-group.pilely.app/README.md`; a `null` group, or a resource action guarded by no group, admits no box (`https://simple-server.pilely.app/README.md` → `### The box's backend token`). Two calls need no group: `https://simple-group.pilely.app/README.md` → `### POST /users/lookup`, and `simple_server`'s reads of this app's own servers (`### POST /{app_uuid}/server/list`, `### POST /{app_uuid}/server/{server_id}`, `### POST /{app_uuid}/status`).
   - A request missing either header, carrying either more than once, or with a value not in its exact form (an entity kind other than the four, a uuid that is not lowercase and hyphenated, `anonymous` with anything after it, an app that is not a uuid) is a bad pair: answer it `401 bad_forwarded_identity`. That rejection is the backend's own job: root never produces that shape and does not answer it; the platform's own backends implement it in their access middleware, before any route runs.
   - Host headers: every request forwarded to a backend app, for every caller shape, also carries `X-Pile-Original-Host` and `X-Forwarded-Host`, both holding the host the caller used, lowercased and without a port: the app's `<label>.pilely.app` (or vanity label) host, or the bound custom domain. Root writes both; a caller-sent copy of either never arrives. Build absolute URLs (redirect targets, payment return URLs, links in emails) from it. Internal piles get neither.
   - Trust comes from network position ("trust-by-edge"): the headers are believed because only root can reach the private backend. There is no signature and the backend holds no key.
4. **Anonymous writes to a public backend.** On a `public` app any caller may read (`GET`, `HEAD`, `OPTIONS`), and a write (any other method) is allowed for a signed-in user and for an anonymous-via-app caller holding an anonymous token for the app. Only a tokenless write is rejected at the edge: `401 login_required` ("log in to write to this pile"), the access mode's one denial that is not the uniform `404`, because a public app's existence is already public. On an app host a session cookie is not a credential (only app tokens are), so a cookie-only write counts as tokenless. An anonymous-token write is forwarded to the backend as `anonymous` on the app the token names (item 3). Forwarding it is the platform's part; accepting or refusing it is the backend's choice. The platform's own `simple_*` services refuse it. A matching public route (item 5) decides instead of this rule. A `protected` app admits its owner and signed-in callers whose account email is on its allow list (`https://pam.pilely.app/specs/frontend_apps` → `### Publishing frontend apps`, item 1); a `private` app admits its owner only. On `protected` and `private` apps every denial is the uniform `404`, with one exception that holds on every access mode and on public routes (item 5) alike: a request refused while carrying an app, anonymous or agent token that is correctly signed but has expired or been revoked, and that the same gate would have admitted had the token been fresh (the owner's own token, an allow-listed user's on a `protected` app, a member app's token on an `app` public route), answers `401 token_expired` ("the token has expired or been revoked; mint a fresh one and retry") in the same JSON envelope and with the same CORS grant as the `404` it replaces, so the page can read it and mint a fresh token. A stale token that would be refused even fresh gets the uniform `404`, byte-identical to an unknown app's, so a stale token reveals nothing a fresh one would not. A stale token on a request the gate admits without one (a read of a `public` app) is forwarded as no token. (corrected from /skill)
5. **Public routes and forwarded headers.** A public route is a record on a backend app (frontend apps have none): a `path_prefix`, the `methods` it covers, and who it admits — `public` (anyone, signed-out callers included, optionally only from `ip_allow_cidrs`, checked against the trusted client IP `CF-Connecting-IP`; a missing IP fails) or `app` (only a call carrying a verified token that names another app — that app's own token, its anonymous token, or its `@simple_server` box's backend token — where that app is an `app` member of an `@simple_group` the owner names on the record). For a caller that is not the app's own, the record with the longest `path_prefix` covering the pile-local path, matched segment by segment against the path the server receives (`/webhooks` covers `/webhooks/stripe`, not `/webhooksx`; `/webhooks/..\admin` never reaches a record, it is the `404 pile_not_found` of item 1 for every caller), decides instead of `access_mode` when it lists the method. A refusal is the uniform `404 pile_not_found`, byte-identical for every caller that would be refused even with a fresh token: a non-member app's token gets it fresh, expired or revoked alike. A member app's expired or revoked token gets `401 token_expired` (item 4), which `window.pilely.fetch` turns into a fresh token (`https://pam.pilely.app/specs/frontend_apps` → `### The browser runtime`, item 1). The app's own callers are never decided by a record. A record can make a public app stricter on one path: an `app` route at `/api` refuses signed-out callers there. A change applies from the next request, and a lookup failure falls back to the default gate. Every request forwarded to an owner backend (`managed_http`, or `direct_http` with a non-internal owner) — not only one decided by a public route — carries the caller's headers minus a deny-list: `Authorization`, `Host`, `Content-Length`, `Connection`, `Keep-Alive`, `TE`, `Trailer`, `Transfer-Encoding`, `Upgrade`, every `Proxy-*`, any header named in `Connection`, every caller-sent `X-Pile-*`, a caller-sent `X-Forwarded-Host` (root writes its own, item 3), and `Accept` and `Content-Type` (sent as their own fields). `Accept-Encoding`, `Range` and `If-Range` pass as the caller sent them, so a box may compress its answer or answer part of it (item 1). So a box can verify a webhook signature such as `Stripe-Signature`; identity still comes only from the two `X-Pile-Requester-*` headers root stamps. **Cookies are host-only, both ways.** A cookie name is platform-reserved when, after an optional `__Host-` or `__Secure-` prefix, it starts with `pilely`, in any case (`pilely_session`, `__Host-pilely_session`, `Pilely_x`); every other name belongs to the app. The caller's `Cookie` reaches the box with every reserved pair removed (no `Cookie` at all when no pair is left), and only when one of these holds: the request has no `Sec-Fetch-Site` header (a non-browser client); `Sec-Fetch-Site` is `same-origin` or `none`; or the method is `GET` or `HEAD` and `Sec-Fetch-Mode` is `navigate` (a top-level navigation, from any site). Otherwise, for example a `fetch` or a form post from another app's page, the request is still forwarded, without `Cookie`: every app on `<label>.pilely.app` is same-site with every other, so this rule, not `SameSite`, keeps one app's page from sending another app's cookies. A backend's `Set-Cookie` reaches the browser only when it has no `Domain` attribute at all (even one naming the app's own host is dropped) and its name is readable and not reserved; its other attributes (`Path`, `Max-Age`, `Expires`, `Secure`, `HttpOnly`, `SameSite`, `Partitioned`) pass unchanged, and a dropped `Set-Cookie` does not affect the others in the same answer. Root itself never sets or reads a cookie on an app host or a bound custom domain. Internal piles get none of the caller's headers, and their answers keep only status, body and `Content-Type`. (corrected from /skill)
6. **There is no scheduler or cron on the platform.** Nothing on the platform calls an app on a timer. A frontend app has nothing that runs on its own: its code runs only in a visitor's browser. A backend app's boxes are always on, and its server process may run its own loop or timer beside its HTTP listener; that is how a backend does work on a schedule (the loop in `https://pam.pilely.app/recipes/frontend_and_backend/timers_and_inbound_hooks` is that pattern). This is an absence: no pile server in the repository exposes a scheduler, cron or timer route.
7. **Cross-origin calls to a backend app.** Root answers CORS on a backend app's host (`<label>.pilely.app`, or a custom domain bound to it), preflights included; a backend never answers its own preflight, and its `Access-Control-*` headers are dropped (item 1). A request whose `Origin` is another app's page on `<label>.pilely.app` or on a bound custom domain gets that origin reflected with allowed methods `GET, POST, OPTIONS`, allowed request headers `authorization, content-type`, preflight max-age `600`, `Vary: origin`, and no `Access-Control-Allow-Credentials`, so that page can `fetch` the backend and read the answer. This is how a frontend app's pages call their backend (`### What a backend app is for`, item 2). A bound custom domain gets exactly a subdomain's grant. Bound means what `/~/mint/exchange`, `/~/mint/anon` and the `simple-*` hosts reflect (`https://pam.pilely.app/specs/frontend_apps` → `### The browser runtime`, item 6): the grants never disagree about an origin, and a failed registry lookup grants nothing. An origin that is neither (the apex `https://pilely.app`, an unbound custom host, any other site) gets no grant. Root's own answers carry the same grant, so a page reads a `404 pile_not_found` or a `401 token_expired` the same way. A cross-origin page reads only the CORS-safelisted response headers.