# Frontend apps ### The browser runtime 1. **`client.js` is mandatory and runs the whole sign-in.** Every app `index.html` loads `` before its own bundle; apps never reimplement it. It runs on any app-origin page that is not root's bootstrap page, whatever the app type; a backend app is an API server, and a backend serving browser pages is unsupported (`https://pam.pilely.app/specs/backend_apps` → `### What a backend app is for`). It runs the PKCE handshake (a random 32-byte verifier and a SHA-256 `code_challenge`), the state nonce (16 random bytes), the navigation to `auth.pilely.app/~/mint/authorize?target=&state=&code_challenge=`, the state check on return, the `POST https://pilely.app/~/mint/exchange` of `{code, code_verifier}`, token storage (sessionStorage key `pilely_app_token`), and stripping `pilely_code`/`pilely_state` from the URL with `history.replaceState` before anything else runs, even on a malformed callback. The re-mint, on an app origin only (off an app origin no re-mint happens): before every `window.pilely.fetch` send and on boot, a stored token past its `exp` is refreshed first. An expired anonymous token is replaced by a fresh anonymous mint before the call goes out; an expired user token starts the mint dance (a navigation that is invisible while the apex login is still valid), and the call goes out as it is. After a send, a `401` on a user token clears it and re-runs the mint dance, which shows the login screen only when the apex login is gone; a `401` with code `token_expired` on an anonymous token refreshes it, and any other `401` on a still-valid anonymous token is returned to the caller as is. Every refresh is bounded by one 30-second cooldown, and a refresh the cooldown refuses never holds the call: it goes out as it is. A `404` never triggers a refresh. Expiry is read on the server's clock: when a token is stored, `client.js` records the offset between the device clock and the token's `iat` (sessionStorage key `pilely_app_token_clock`), so a device whose clock is wrong never enters a mint or sign-in loop and its calls are never blocked by the expiry check. It is served from the apex only — on an app host `/~/client.js` is the app's own path — with `Content-Type: application/javascript; charset=utf-8`, `Access-Control-Allow-Origin: *` and `Cache-Control: public, max-age=300`, baked into the binary with `include_str!`. Root answers it in the serving-split layer before the routers, so the credentialed CORS layer never overwrites the wildcard. 2. **The `window.pilely` API.** `ready` is a promise that resolves once the mint callback has been consumed (and the anonymous boot, or the refresh of an expired stored token, attempted); call it before the first render. `user()` returns `{ id, handle, app }` from the token claims (`sub`, `handle`, `pile_id`), or `null` with no token or a `sub`-less anonymous token. `signIn(target?)` starts the mint dance; the target defaults to this origin's host on an app origin, else the `pilely-app` meta tag. `signOut()` clears the token and navigates to `auth.pilely.app/~/logout`. `fetch(input, init)` attaches `Authorization: Bearer `, sets `accept: application/json` when absent, refreshes an expired token before the send, and re-mints on a `401` as in item 1; the `401` it returns is readable by the page. `isAppOrigin()` is true on an app host or a bound custom domain, false on the apex and on `localhost`/`127.0.0.1`/`[::1]`. `apexOrigin()` is the origin `client.js` was loaded from. `authOrigin()` is `auth.`, or on loopback the `` value, else `http://auth.localhost:8080`. `claims()` is the raw decoded token payload (not verified; the server verifies). `token()` is the current token string or `null`. `appId()` returns, in order: the `pilely-app` meta tag when present; else the token's `pile_id` claim, only once `ready` has settled; else `null`. `takeReturnPath()` returns the path the page was on before the dance, consumed once. 3. **The `` tag is optional.** On an app origin (a registered subdomain or a bound custom domain) `signIn()`, the anonymous boot and the silent re-mint all target `location.host`, and the mint resolves the host through the registry; the tag is never read there. Off an app origin (local dev on `localhost`) the tag is the only mint target, and with neither a host nor a tag `signIn()` rejects with "no mint target". The tag also feeds `appId()` before `ready` has resolved, and on any origin it wins over the token's `pile_id` claim. A stale or placeholder value therefore breaks sign-in only on `localhost`, where it is the mint target; on any origin it makes `appId()` return the wrong id. The value must be the real `pile_id` that register returned. (corrected from /skill) 4. **Identity comes from the token's claims.** `user()` and `claims()` decode the token locally; there is no identity round trip. A `/~/me` call does not work off the apex: an app host owns every path, `/~` included, so `/~/me` there is the app's own path, and the session cookie (`__Host-pilely_session`, no `Domain`) exists only on the apex. Root sets exactly one cookie of its own on an app subdomain, the asset cookie: `__Host-pilely_asset=; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=43200` (no `Domain`, so host-only; 12 hours; named `pilely_asset`, without `Secure`, on a local http deployment). It is set on a successful `POST /.well-known/pilely/spa_ticket` for a protected or private frontend app, a fresh one on every mint, and it releases that app's files, never its shell (`### Serving frontend apps`, item 1). A refused mint, a public app's host, a backend app's host and a bound custom domain get no cookie from root. Its name carries the reserved `pilely` prefix, so no backend can set it or receive it; any other cookie on an app host is the app backend's own (`https://pam.pilely.app/specs/backend_apps` → `### Forwarding to backend apps`, item 5). A bare `fetch` carries no token and goes out anonymous; only `window.pilely.fetch` attaches the Bearer. 5. **Public apps get an anonymous credential at boot.** On every app-origin page except the bootstrap page, holding no token, `client.js` POSTs `{target}` to `https://pilely.app/~/mint/anon` before app code runs (`https://pam.pilely.app/specs/accounts_and_tokens` → `### /~/mint/exchange and /~/mint/anon`). It returns a token only when the target is an existing, mint-eligible app with `access_mode = public`, frontend or backend alike; every other case (bad target, unknown app, unbound custom host, protected or private app) gets one byte-identical `404`, which the runtime negative-caches for 5 minutes per app. The anonymous token is `sub`-less, lives 15 minutes, and lets `window.pilely.fetch` read data opened with `anon_read`. When it has expired, the boot and every `window.pilely.fetch` send replace it with a fresh anonymous mint first (item 1), so a page left open keeps working with no action by the visitor. Because the mint never checks the app type, the boot also runs on an HTML page a public backend app answers; that is page serving on a backend, which is unsupported (`https://pam.pilely.app/specs/backend_apps` → `### What a backend app is for`). `user()` stays `null` on it. A user-only call made with it answers the uniform `404` (simple_db refuses an anonymous-via-app caller with `NotFound`), not `401`, so on a public app the sign-in affordance is gated on `window.pilely.user() === null` and calls `window.pilely.signIn()`; the "auto-sign-in on the first 401" pattern applies only to protected and private apps, where no anonymous credential exists. 6. **The `simple-*` hosts answer CORS preflights from app pages.** Root, not the services, grants it: on a request whose Host is a `simple-*` label or the exact `pilely` label (`pilely.pilely.app`, the `@pilely` pile), and whose `Origin` is a `.pilely.app` app subdomain or a bound custom domain, root reflects that origin with allowed methods `GET, POST, OPTIONS`, allowed request headers `content-type, authorization`, preflight max-age `600`, `Vary: origin`, and no `Access-Control-Allow-Credentials`. A bound custom domain gets exactly the subdomain's grant, so its page reads `simple-db` and every other official service just as the same app does on `.pilely.app`. Bound means what `/~/mint/exchange` and `/~/mint/anon` reflect: the two grants never disagree about an origin, and a failed registry lookup grants nothing. An unbound custom host or any other origin gets no grant. A backend app's own host gives app pages the same grant (`https://pam.pilely.app/specs/backend_apps` → `### Forwarding to backend apps`, item 7). The services themselves (for example simple_db) have no CORS layer. The grant cannot be tested from `curl` or Node; it is verified from a page. (corrected from /skill) 7. **Auth is unified.** One platform account works in every app; the platform owns sign-up, sign-in, sessions, token minting and refresh. Apps never build accounts: no registration screen, no password form, no user table, no session code. The same sign-in flow signs up a visitor with no account, so there is no separate "create account" path. Backends read the visitor from the forwarded identity headers and never see a password. The sign-in affordance is always labelled "Login with Pilely", translated per locale with the Pilely name kept, and wired to `window.pilely.signIn()`. The reference component `reusable_components/sign_in_button` (a dependency-free component, its CSS and a `preview.html`) shows it; its look is a starting point, the name is contractual, and it waits for `window.pilely.ready` and gates on `user() === null`. No platform code enforces the no-accounts rule. (unverified — external) 8. **The `window.__PILELY_APP__` v1 contract.** Inside the Pilely phone app the WebView injects a frozen global before any page script runs (`injectedJavaScriptBeforeContentLoaded`): `{ v: 1, platform: "ios" | "android", appVersion: , safeAreaTop: , chrome: { capsule: true, chip: true } }`. Fields are only ever added under `v: 1`, existing ones never change meaning, and the global is one-way (no bridge back into the app). Its presence means the page is inside the app; its absence means a plain browser, since every app release injects it. The app floats a 34px capsule 8px below the inset, so it occupies the 42px band below `safeAreaTop`; `safeAreaTop + 56` clears it. Apps ship `` unconditionally, and apply the top clearance only in-app: in CSS `calc(env(safe-area-inset-top, 24px) + 56px)`, or a flat `104px` when `env()` is unusable. The recommended bootstrap tags `` with `pilely-in-app` when the global is present and sets `--pilely-safe-top` to `safeAreaTop + 56`px; CSS sets `--pilely-top-clearance` to `0px` by default and to `var(--pilely-safe-top, calc(env(safe-area-inset-top, 24px) + 56px))` under `:root.pilely-in-app`. ### Publishing frontend apps 1. **The access mode is chosen at register and is final.** `access_mode` (`public`, `protected` or `private`) is set by `POST /~/apps/register` and no route changes it afterwards, for frontend and backend apps alike: `POST /~/apps/{pile_id}/update_config` refuses any body that carries `access_mode` (`400 access_mode_immutable`, nothing in the body applied), and still edits the allow list without it. The allow list names people by the email they sign in with: up to 256 emails, compared case-insensitively and stored lowercase; an email with no account yet is accepted and admits that person as soon as they sign up with it; a malformed email is refused with a `400` naming it. A signed-in caller whose account email is not on the list gets the same `404` as for an unknown app, whatever their handle. Only the owner ever sees the list (`POST /~/apps/register`, `update_config` and the owner's `/~/apps/list` answer it); the public profile, the handle catalog and app search never show it. To use another mode, register a new app and publish the bundle there. A `public` app's bundle is uploaded to and served from Pilely's public CDN bucket and lives nowhere else; a `protected` or `private` app's bundle lives only in the private bundle bucket. 2. **Publishing is three steps: `bundle/start`, a `PUT` of each file, `bundle/commit`.** Both routes take the owner's login token, and are frozen by a pending account deletion (`https://pilely.app/README.md` → `### POST /~/apps/{pile_id}/bundle/start` and `### POST /~/apps/{pile_id}/bundle/commit`). First, `POST https://pilely.app/~/apps/{pile_id}/bundle/start` with `{ "files": [ { "path": "", "size": } ] }`, one entry for every file of the build output: `path` relative to the bundle root, exactly as visitors will request it (`index.html`, `_assets/app-3f2a.js`), and `size` its exact byte count. It answers `{ "version_ms": , "expires_at": "", "uploads": [ { "path", "url", "headers": { "Content-Type": "…" } } ] }`, one entry per file. Then `PUT` each file's bytes to its `url`, sending exactly its `headers` and a body of exactly the declared size; storage refuses anything else. The bytes go straight to storage, never through `pilely.app`. Last, once every `PUT` has finished, `POST https://pilely.app/~/apps/{pile_id}/bundle/commit` with `{ "version_ms": }`: the version is live at once, and a public app's files come from the public CDN as soon as `commit` returns. Every publish is a new version; a version is never changed after its upload. 3. **Upload links last 15 minutes.** `expires_at` is 15 minutes after `start`; the expiry is checked when a `PUT` starts, so a large file begun before it may finish after it. If the links expire before every file is up, call `start` again and upload every file to the new version. A version that is never committed is deleted on its own about 30 minutes after its `start`, and a file that lands in it after that is deleted by the next daily sweep. Committing it after that answers `410 bundle_upload_expired`: call `start` again. 4. **Nothing about the app is validated.** `start` checks only three things: every path stays inside the bundle (no leading `/`, no `.`, `..` or empty segment, no backslash, no control character, no path listed twice: `400 bundle_path_invalid`), at most 1024 files (`400 bundle_too_many_files`), and the declared total fits the owner's remaining storage (`402 storage_exceeded`; nothing is held, so two uploads started at once may together go over). Nothing checks a missing `index.html` (the app then answers `404`), a wrong build base, a forgotten file or a wrong file type, and `commit` does not check that the listed files arrived: a listed file that was never uploaded answers like a missing file. A `README.md` in the bundle is an ordinary file, never the app's manual (`### Serving frontend apps`, item 2). If the app is broken, fix the build and publish again; open the app in a browser after every publish. 5. **Storage is counted on what arrived.** `start` bills nothing. About 30 minutes after `start` (at most about 35), the platform counts the bytes that actually arrived toward the owner's storage and charges each file that arrived as one upload, whether or not the version was committed; files listed but never uploaded cost nothing, and a version never committed stops counting when it is deleted. A public app's bundle is stored once, on the public CDN only. After a new `commit` the replaced version keeps serving pages already loading it for 24 hours, then it is deleted and stops counting. Prices: `https://pam.pilely.app/pricing/service_cost.md` (Storage). 6. **A public app's stylesheets are rewritten at `commit`.** Every root-absolute `url(/…)` in a `.css` file the version lists, declared at `bundle/start` at 4 MiB (4194304 bytes) or less, becomes the equivalent relative path, in place, so fonts and images referenced from CSS load from the same version folder on the CDN. A `.css` file declared bigger than 4 MiB is not rewritten: it is left exactly as uploaded, its root-absolute `url(/…)` do not resolve on the CDN, and `commit` lists its path in `stylesheets_skipped` (usually `[]`; `stylesheets_rewritten` counts the files rewritten). In a stylesheet that big use relative URLs, or split it into files of 4 MiB or less. No other file and no other byte is touched; a protected or private app's files are never rewritten. If the rewrite fails, `commit` answers `500 stylesheet_rewrite_failed` with the version already live: commit the same `version_ms` again. ### Serving frontend apps 1. **How frontend bundles are served.** A serving-shaped request (a `GET` or `HEAD` with no upgrade) to `.pilely.app/` on a frontend app is answered by root's serving surface, in this order: the access gate, the owner's quota probe (traffic balance and storage allowance), the shell gate, the no-bundle check, the quota threshold, then file-or-shell. File-or-shell is decided by the live version's file list, the paths it was uploaded with at `bundle/start` (`### Publishing frontend apps`, item 2): a `` that exactly matches one of them (case-sensitive, as uploaded) is that file, and every other path is the shell. It is never decided by the file extension or a folder prefix, and root never asks storage whether a file exists. On a protected or private app a file path (every path that is not the root URL or `index.html`, `icon.svg`/`icon.png` included) first passes the file gate, before any file decision: it goes on only when the request carries an admitted asset cookie (`### The browser runtime`, item 4), one whose session is bound to this host and this app and whose user the app's current owner and allow list still admit, so a user removed from the allow list is refused from then on. The cookie counts only when `Sec-Fetch-Site` is `same-origin` or `none`, or the header is absent; on `same-site` or `cross-site` it is ignored, so another app's page cannot load this app's files with the visitor's cookie. Every other caller gets the uniform bootstrap page (`200`, byte-identical to a nonexistent app's answer and to a missing path's at the same URL, item 3), whatever the filename and whether or not the file exists. The cookie never releases the shell: the root URL, `index.html` and routes stay ticket-only (item 2). A listed file of a public app answers `302` with `Cache-Control: max-age=60` to the unsigned, never-expiring `https://pilely-public-cdn.com//spa//`, and the browser fetches the bytes from the public CDN, which Cloudflare answers mostly from its cache; there every uploaded file answers `GET`/`HEAD` `200` with the Content-Type its upload link set and `Access-Control-Allow-Origin: *`, and any other path answers `404`. A public app's bundle lives only there, so its files are served from the CDN as soon as `bundle/commit` returns, and the root-absolute `url(/…)` in its stylesheets of 4 MiB or less were rewritten at commit (`### Publishing frontend apps`, item 6). After a new `bundle/commit` the replaced version's files keep answering for 24 hours, then `404`. Deleting the app deletes its files and purges its CDN prefix, so its CDN URLs answer `404` within seconds (a CDN redirect cached on the app host may last its 60 seconds). A listed file of a protected or private app answers `302` to a presigned R2 GET URL into the private bucket, and the browser fetches the bytes straight from R2; that `302` carries `Cache-Control: private, max-age=60` plus `Vary: cookie, sec-fetch-site`; the presign timestamp is pinned to a window (`R2_PRESIGN_WINDOW_SECS`, default 3600) with a longer expiry (`R2_PRESIGN_EXPIRY_SECS`, default 7200), so repeat requests within the window get a byte-identical URL and hit the browser cache. A listed file that never arrived redirects to a URL that answers `404`. Any path the live version does not list gets the shell: root serves the version's cached `index.html` (the SPA shell: `200`, `text/html; charset=utf-8`, `Cache-Control: no-store`, metered against the owner), and the client-side router renders the route; a version with no `index.html` answers `404`. An R2 transport failure is `500`. Two paths always take the shell branch: the app's root URL and `index.html` itself (it is the shell object, so it is routed through the shell gate rather than presigned). A path with an empty segment (a `//` or a trailing slash) also falls through to the shell. A path with a `.` or `..` segment in any spelling (`%2e`, `.%2E`), a `\`, or an encoded `%2F` / `%5C` is never served at all: root answers it `404 pile_not_found` before it looks up the app (item 2). This is about whole segments, so dots inside a filename are unaffected. Consequences: fingerprinted files can sit anywhere in the bundle (`_assets/index-abc.js`, `_chunks/lazy.js`, `favicon.svg` at the root); a client-side route may contain dots (`/posts/123.json` is not a listed file, so it gets the shell); a real file at a path shadows a route of the same name; a request for a route or a random path never touches storage. The fixed icon names `icon.svg`/`icon.png` are the exception: they map to the unversioned `/meta_data/` folder, are decided before the file list (so a bundle file of that name never answers), live only in the private bucket (a public app's icon is always the presigned `302`), and, past the file gate, answer `404 icon not found` rather than the shell when missing. A path ending in `.md` (`/orders.md`, `/index.md`) is an ordinary path of the app like any other: the bundle's file at that path if the version lists one, otherwise the shell; a bundle's `index.md` is not the app's manual. The one exception is `/README.md`, which is never a serving request (item 2). Every shell answer, the bootstrap page included, carries the `x-pilely-agent` advisory header, one fixed string for every app: `agents start at https://pilely.app/README.md`. 2. **An app host owns its whole path space.** On an app subdomain `.pilely.app`, and on a custom domain bound to the app, every path belongs to the app: `/~`, `/@`, `/-`, `/skill`, `/about` and `/healthz` included. None is refused by prefix and none rides an exception; root resolves the host to the app and the app receives the caller's path exactly as sent. The one exception holds on every host root serves: a path a standard URL parser would change before sending it on (a `\`, a `.` or `..` segment in any spelling, a character it would percent-encode such as a raw `"`, `{`, `}` or non-ASCII byte) or one carrying `%2F` / `%5C` reaches no app. Root answers it `404 pile_not_found` in the JSON envelope before it even looks up the app, so the answer is the same whether or not the app exists: a frontend app serves no shell or file for it and a backend app never receives it. On a user-owned app the host reserves exactly two things: the `/.well-known/` prefix and the path `/README.md`. `/.well-known/` (RFC 8615) today holds exactly one route, `/.well-known/pilely/spa_ticket` (a lone trailing `/` is tolerated), which root's host shell answers itself — `POST` mints; every other method is root's plain `404 not found` — without ever forwarding to the app. Any other `/.well-known/...` path is root's plain `404 not found`, never forwarded, so an app can never claim a well-known path. `client.js` calls the spa_ticket route itself, same-origin with the Bearer app token, on the bootstrap page: it gets a single-use ticket valid about 10 seconds and re-enters the page with `location.replace(...?pilely_spa_ticket=)`; the app never calls it. `/README.md` is the app's one agent manual, for frontend and backend apps alike: `https://.pilely.app/README.md`. The owner uploads it to root — `readme_md` is required by `POST /~/apps/register` and `POST /~/apps/{pile_id}/update_readme` replaces it (`https://pilely.app/README.md`) — and a bundle never carries it: a `README.md` uploaded in a bundle is an ordinary file that `/README.md` never answers, and no `index.md` is required. The match is exact and case-sensitive: `/README`, `/readme.md` and `/docs/README.md` stay the app's own paths. Root answers `/README.md` itself, for every method, never through the serving surface and never forwarded to a backend, after the same access gate, owner's limiter policies (`429 rate_limited`), traffic quota (`503 out_of_traffic_credits`) and storage standing (`503 storage_over_quota`) as any other request to the app. A caller the access gate refuses gets exactly the answer a nonexistent app gives, for every method. To an admitted caller: `GET` answers `200`, `Content-Type: text/markdown; charset=utf-8`, the stored bytes verbatim, and an `ETag` naming the live README version, or `304` when `If-None-Match` names it; `Cache-Control` is `public, no-cache` on a public app and `private, no-cache` on a protected or private one; `HEAD` answers GET's headers with no body; any other method answers `405` with `Allow: GET, HEAD`; an app with no README answers `404 no_readme`. A new upload is seen on the next request. A bound custom domain answers `/README.md` exactly as the app's subdomain does. An app owned by a platform account keeps its own `/README.md`, answered by its own backend. 3. **Before its first bundle.** Register uploads no bundle, so a frontend app has nothing to serve until its first `bundle/commit`; its `/README.md` answers from the moment it is registered (item 2). A public app answers a `GET` with a plain-text `404` whose body is `pile has no bundle`. A non-public (protected or private) app answers every caller without a valid shell ticket with the uniform bootstrap page (`200`, unmetered, `Cache-Control: public, max-age=60`, byte-identical to a nonexistent app's answer). A caller who does hold a valid ticket — an authorized visitor — gets the same plain-text `404 pile has no bundle` a public app gives. A backend app's host has nothing but its `/README.md` to answer until `server/add` on `@simple_server` launches its server; there is no placeholder page. (corrected from /skill) ### Cost and abuse 1. **Pilely sets no rate or budget limit on an app's traffic.** The owner pays for every request to the app, signed-out visitors' included. Nothing on the platform caps that traffic on the owner's behalf. 2. **To cap traffic, the owner adds `@simple_limiter` policies and watches the traffic balance.** A policy can sit on any route of the owner's own app host, and, per app, on the app's `simple-db` and `simple-email` routes (hosts `simple-db.pilely.app` and `simple-email.pilely.app`: a table's record routes, its file upload and download links, email sends). Root enforces every active policy on the requests it forwards and answers `429 rate_limited` with `Retry-After`. On the owner's own app host a policy counts every caller but the owner, signed-out visitors included; on the `simple-*` hosts it counts only requests made through the policy's app, signed-out visitors included, and never the owner, whatever credential the owner uses. A frontend app's page and asset loads (item 1 of `### Serving frontend apps`) are answered before that gate, so no policy caps them; its data and email calls are where a policy applies. How to create one: `https://simple-limiter.pilely.app/README.md` → `### POST /policies/create`, `### Who is counted`, `### Limiting a simple_db table` and `### Limiting simple_email sends`. The owner tops the balance up with `POST https://pilely.pilely.app/subscription/buy_traffic` (`https://pilely.pilely.app/README.md`). 3. **When the balance reaches zero the app stops serving until topped up.** While the owner's balance is at or below zero, root answers requests to the owner's apps `503 out_of_traffic_credits` (`https://pam.pilely.app/specs/accounts_and_tokens` → `### @pilely verification and billing answers`). The app also stops serving, to everyone, the owner included, while the owner is over their storage allowance: once the daily check finds the account over, root answers `503 storage_over_quota` until it is back within it (a protected or private app answers the uniform bootstrap page instead, as at a zero balance; files a public app already has on the public CDN may still be served from there). `https://pam.pilely.app/pricing.md` → `### Over the allowance`.