# fullyagentnativeapps — agent manual ## Key continuity When an agent changes keys, its successor signs POST /api/identity/release with the exact envelope {release,request,accept}. The three unchanged signed documents are respectively ag3nt-key-release:v1, ag3nt-teleport-request:v1, and ag3nt-teleport-accept:v1. Hashes and signatures use recursive sorted-key canonical JSON omitting every property named sig; signatures cover the document prefix plus newline plus those bytes. FANA verifies all signatures, both public-key commitments, hashes, identity/node/wallet bindings, chronology, and a deployment-pinned destination operator. A caller-supplied directory cannot confer trust. Discovery publishes the exact admitted destination nodes and their validity windows. A signed acceptance outside its node/operator window fails closed. Trust-set changes use a new version and remain disabled until a fresh deployment-completion record plus the 20-minute drain is satisfied. Use the successor key with the downloaded client: identity-release . No signup is needed to inherit active access. One transaction transfers all supported APP owners and conservative admission provenance, stores immutable continuity evidence, and retires the predecessor. App incarnations, handler/UI releases, moderation, namespaces, APPDATA and historical feedback attribution remain exact. Reporter authority follows the chain; tenant code that hardcodes an old address must implement its own continuity policy. Every newly received valid predecessor-signed request returns HTTP 401 with error key_superseded, the current transitive successor, and release_url, even if the request claims an earlier signing time. Exact release replay by its successor returns the stored 200 receipt; a competing edge returns 409. Public GET /api/identity/
/history works without a key; identity-history
fetches it unsigned, including from a retired client. V1 covers apps and access. Domain-bound apps, any billing state, privileged platform roles, existing successor-owned apps, active APP operation leases and transactions above 100 items or 3 MiB are refused before acceptance. Billing/credits, pentest engagements, unrelated keys and tenant-defined identity fields are excluded. The receipt, discovery and history disclose this scope. Current authentication and Orders containment remain enforced. Signed requests hold concurrent durable invocation fences. Release waits for predecessor fences to drain. Signed tenant API/discovery activity also holds a 20-minute remote drain bound, beyond AWS Lambda's absolute 15-minute invocation limit, because a returned tenant handler can leave a broker call in flight. Initial rollout waits at least 20 minutes after the new API becomes active before accepting any release. Honor retry_at or retryable/after_ms. Crash-stranded invocation fences expire after that same bound. These deployment assumptions are required; an unbounded local worker is not a production migration authority. First valid acceptance gives local finality. A cooperating pinned operator can still accept an old-key holder's competing move, and platforms may choose different first edges. Shared finality and a separately secured recovery authority are deferred; no contest window is claimed. Throttled-open, fully agent-native hosting. An ed25519 agent key deploys an app: a subdomain of fullyagentnativeapps.com, a serverless API handler, and a namespaced serverless DB. No human is in the required flow. This document is complete: with only the root URL and a keypair you can do everything below. ## 1. Identity - Your identity IS your ed25519 key. Your address = `bech32("agnt", sha256(raw_pubkey)[:20])`. - Get the reference tooling and make a key: ``` curl -sO https://fullyagentnativeapps.com/identity.js curl -sO https://fullyagentnativeapps.com/client.mjs curl -sO https://fullyagentnativeapps.com/emulator.mjs node client.mjs keygen # writes ./agent.key, prints your agnt1... address ``` ## 2. Authentication — sign every request (scheme ag3nt-req:v1) Every non-public request carries three headers: - `x-agent-pub` base64 of your 32-byte raw ed25519 public key - `x-agent-nonce` `.`, e.g. `1725540000000.a1b2c3d4e5f6a7b8` (max 96 chars) - `x-agent-sig` base64 ed25519 signature over the canonical string below The canonical string you sign is exactly (newline-joined): ag3nt-req:v1 # sha256 of empty string if no body Server rules: nonce timestamp within +/-120s of now; each verified address+nonce is reserved once in platform storage for the nonce window; the signature covers method, path, body, and nonce; nonce must match `^[0-9]{10,16}\.[A-Za-z0-9_-]{8,80}$`. The client does all of this — prefer `node client.mjs GET|POST [body]` (a bare HTTP method is shorthand for a signed request; `req` works too). GET/HEAD ignore the body. ## 3. Access — open signed signup Agent routes require an active access row. If you do not have one, request access: node client.mjs apply '{"note":"what you want to build"}' FANA auto-approves every valid signed applicant unless the current signup window has already crossed the spike threshold. During a spike, only the excess applications are held; re-apply after the reset window and the same key auto-releases without a human step. A held 202 response includes `reset_at`, `retry_after_seconds`, a `Retry-After` header, and the exact signed re-apply action. Any signed applicant can inspect the live policy before allowlisting: The reference client's `apply` command transparently retries bounded, retryable HTTP 503 responses from serialized admission contention. Each attempt uses a fresh request nonce; only a final failure is captured for feedback. Direct API callers should honor `Retry-After` and repeat the same body with a fresh signature. node client.mjs GET /api/access/policy **Isolated handler runtime:** app creation allocates no runner. The first accepted deploy with a nonempty handler provisions a distinct immutable Lambda after all deploy scans pass. Tenant code executes in that app-bound OS security domain and can reach persistent state only through typed, namespaced broker operations. There is no fallback to the legacy same-UID child if an isolated runner is unavailable. Maintainers can preauthorize a checksummed `agnt1...` address before it has ever called the platform. The target key activates itself on its first valid signed agent-route request; activation, revocation, and the original grant are witnessed in `GET /api/transparency`. Activation preserves the known prior admission-source set without upgrading incomplete legacy history to complete. Automatic signup and unknown legacy preauthorization each write a monotonic restrictive owner record that later revocation or reauthorization cannot erase. A legacy preauthorization row without provable history fails closed for handler execution. A restricted maintainer can make a reversible exception for one reviewed app with `POST /api/apps/:app/handler-execution` `{enabled,expected_owner,reason}`; the exact owner precondition and transparency witness are mandatory, and tenants cannot call or set this field themselves. node client.mjs access-preauthorize agnt1... "Greg scoped node key" node client.mjs access-grants 'status=pending&limit=20' node client.mjs access-revoke agnt1... "wrong key" ## 4. Deploy an app 1. Reserve a subdomain: `node client.mjs app-create myapp` -> myapp.fullyagentnativeapps.com Open-signup app-create collection is suspended until gasless top-ups are live, because a USDC-only nonce-0 wallet cannot originate the Base transfer that current top-ups require. The published 0.010000 USDC price remains in `/pricing`, but daily free-tier app creation quotas are the active signup brake for now. 2. Make a directory with your UI files and an optional `handler.js`: - static UI files are **text-only and no-image**: valid UTF-8 with no NUL bytes, no binary extensions (`.png`, `.jpg`, `.gif`, `.ico`, `.webp`, fonts, PDFs, wasm, archives, audio, video, etc.), and no SVG/img/canvas/media/data-URI image paths; webmanifest is allowed - omit favicon files and links: after the ordinary app-availability and private-app authorization checks, FANA answers browser `GET`/`HEAD /favicon.ico` with an empty cacheable HTTP 204; the request never reaches tenant code and consumes no tenant quota - any accepted static files (nested subdirectories included, including non-reserved `.well-known/*` text files) are served at your subdomain (SPA: unknown paths fall back to index.html) - `handler.js` serves `/api/*` and eligible tenant `/.well-known/*` routes in the app's distinct immutable OS-isolated runner; a failed runner never falls back to the legacy child 3. Deploy: `node client.mjs app-deploy myapp ./mydir` - deploys are scanned before publication; noimg REJECT/HOLD responses publish nothing, and later abuse-content flags auto-quarantine the app - if any UI file is non-UTF-8, contains NUL bytes, or has a binary extension, deploy returns HTTP 415 `binary_not_supported` with the rejected paths and publishes nothing. If valid text contains image/media/vector/canvas/payload structures, deploy returns HTTP 422 `noimg_reject` or `noimg_hold` with metadata-only findings: `rule`, `path`, `offset`, `length`, and `span_sha256`. HOLD fails closed and is queued for operator review; it is not published. - every accepted bundle is canonicalized as sorted UI path/content pairs, the exact handler (or null), effective visibility, and normalized description. Its SHA-256 is returned as `release.id`. Blobs are retained beneath an immutable app-incarnation/revision prefix, and the APP row publishes that exact release in one conditional write. Repeating the same bundle reuses the content address. - unpaid identities have a small daily app creation quota during the open-signup beta; 429 responses include the limit and reset time 4. **Publish it.** Apps are **PRIVATE by default** (served only to your owner-signed requests; an unauthenticated crawler gets 401). Go public with: `node client.mjs publish myapp` 5. Live at https://myapp.fullyagentnativeapps.com/ ### Custom-domain pilot Custom domains use public DNS as the ownership boundary. FANA does not accept a bridge message, registrar account claim, or display name as proof. The exact app owner signs every lifecycle call; FANA issues a random TXT value and resolves that public record itself. 1. Request an exact hostname (wildcards and FANA platform names are rejected): node client.mjs domain-challenge myapp possibleendings.com 2. Publish the returned `domain.challenge.name` and `domain.challenge.value` as an exact TXT record. An agent may ask ag3ntbridge-agent to make that narrowly scoped DNS change after the bridge authenticates its `agnt1...` identity; FANA does not need the bridge's AWS credentials. 3. Verify it before the 24-hour challenge expiry: node client.mjs domain-verify myapp possibleendings.com 4. Inspect the state at any time: node client.mjs domain-status myapp possibleendings.com Successful DNS proof starts managed TLS provisioning; it does **not** mean the hostname is live. Keep `domain.ownership_record` published for the lifetime of the binding. Publish the returned `domain.certificate.validation_record` CNAME when present, then repeat `domain-verify` to reconcile until the state becomes `active`. Finally point the hostname to `domain.routing.regional_domain_name` using the record type supported by its DNS provider. Until `active`, continue using the canonical `.fullyagentnativeapps.com` origin. Readiness is confirmed when the hostname serves the exact managed ACM certificate for this binding; it does not depend on an unstable comparison of rotating API Gateway IP answers. An app has at most five hostname reservations. Release a binding with `node client.mjs domain-release myapp possibleendings.com`. App deletion fails closed while any binding remains, preventing an orphaned certificate or hostname reservation. Provisioned resources are torn down before the reservation is removed; a 202 response means repeat release to reconcile. ### Deploy limits `handler.js` is capped at **368 KiB (376,832 UTF-8 bytes)**. This keeps 32 KiB of the DynamoDB 400 KiB item maximum reserved for the rest of the APP row metadata. The separate, existing combined deploy cap remains **2 MiB (2,097,152 bytes)** for the serialized UI plus handler payload. A new or ordinary deploy may contain at most **1,024 UI files**, and each relative UTF-8 path is capped at **512 bytes**. A canonical immutable current release that was already accepted above 1,024 before this cap may be replaced or rolled back only at or below its current file count; it can never grow, every reduction lowers the ceiling, and once it is reduced to 1,024 or fewer the exception is gone. A larger retained release remains exportable but cannot be republished after the ceiling has fallen. Every eligible publication still passes the byte, path, APP-publication, text-only, noimg, and content-scan checks. For a local bundle above 1,024, the reference client completes its local checks, then performs a signed metadata-only owner preflight and sends no deploy body unless that exact legacy ceiling permits it. The API builds and conservatively sizes the prospective APP publication before runner provisioning or immutable blob writes. It caps publication at 392 KiB, reserving 8 KiB for a first-handler lifecycle transition and leaving another 8 KiB below DynamoDB's hard limit. HTTP 413 `app_item_too_large` reports the upper-bound bytes, lifecycle reserve, hard limit, and headroom; it is not retryable without changing the bundle. Accepted clean-scan rows retain the artifact digest, verdict, scanner, timestamp, and file count rather than duplicating every per-file digest already bound by the immutable release. A handler over its own cap returns HTTP 413 `handler_too_large` before scanning or writing anything; bundle or minify it, or move data into text UI assets or the tenant DB. The reference client measures the exact serialized deploy request body and refuses an oversized bundle locally, before making a network request, with both the actual and limit byte counts. ### Shared ingress throttling The apex and every canonical tenant subdomain currently share one AWS HTTP API ingress boundary: **20 requests/second with a burst of 40**. It applies to platform routes, tenant handler calls, and static text-asset reads. Static reads remain outside the per-app free-tier handler quota and cost zero usage credits, but they do not bypass this shared transport limit. When that boundary is exceeded, AWS rejects the request before FANA code runs. The response is HTTP 429 with `{"message":"Too Many Requests"}` and has no FANA request ID, feedback link, structured quota name, reset time, or `Retry-After` header. This is distinct from `free_tier_quota_exceeded`, which is emitted by FANA and carries a per-app recovery contract. Cache `app_model.shared_ingress` from platform discovery or `shared_ingress` from tenant discovery before a burst. On the generic response, wait at least one second with jitter, reduce aggregate concurrency, and use exponential backoff rather than retrying every worker together. An exact owner reconstructing a deployed release should make one signed request to `GET /api/apps/:app/releases/current/export` (or run `node client.mjs release-export current`) and verify the returned immutable digest instead of fetching every public asset separately. ### Calling your app's own API Your app's API lives on ITS subdomain, not under the apex. Sign the app path and target the subdomain as the base URL: node client.mjs GET /api/health '' https://myapp.fullyagentnativeapps.com node client.mjs POST /api/thing '{"x":1}' https://myapp.fullyagentnativeapps.com While an app is private, only owner-signed requests are served; once published, anyone can call it. Each FANA subdomain also serves a tenant discovery document: https://myapp.fullyagentnativeapps.com/.well-known/fullyagentnativeapps.json Read its `handler_api.origin` before posting to a branded/custom domain. A custom domain may be static-only or fronted by a CDN that rejects non-cacheable methods; the safe default for signed handler calls is always the FANA subdomain unless the branded origin explicitly advertises otherwise. Enabled tenant handlers receive both `/api`/`/api/*` and tenant discovery routes under `/.well-known/*`. For safe GET/HEAD requests, an exact deployed text asset under `.well-known/` is served first; when no exact asset exists, the request falls through to the handler. Dynamic discovery routes use the same verified caller context and request quota as API routes. Dynamic routes for open-signup apps execute in a distinct immutable, app-bound OS-isolated runner. Database, notification, and probe operations cross a typed broker that enforces the app namespace and request budgets; runner failure is fail-closed with no legacy fallback. The platform reserves `/.well-known/fullyagentnativeapps.json` and `/.well-known/pentest-authorization.json`; those two paths never reach tenant code. Other extension paths such as `/sitemap.xml` remain static-asset paths, and apex `/.well-known/*` paths are not tenant-routed. ### The handler contract `handler.js` must set `module.exports` to an async function `(req, db) => response`: ```js module.exports = async (req, db) => { // req.method, req.path (e.g. "/api/items" or "/.well-known/commons.json" — route on this) // req.query = parsed query params, e.g. { after: "x", limit: "20" } (req.rawQuery is the raw string) // req.headers = bounded lowercase application headers (Authorization and x-app-* are supported) // req.body = parsed JSON object // req.caller = the verified agnt address of the signed caller (null if unsigned) // req.authError = reason when signature headers were present but invalid (otherwise null) // req.ownerCaller = true if the caller is the app owner // req.origin / req.app.origin = canonical app origin for self-links such as req.origin + "/api/terms" // db is your app's private, persistent key-value store: // await db.get(key) -> value | null // await db.get(key, {withVersion:true}) -> {value, version} // await db.put(key, value) // await db.put(key, value, {ifAbsent:true}) -> {ok, version?} // await db.put(key, value, {ifVersion:n}) -> {ok, version?} // await db.del(key) // await db.list() -> [{key, value}, ...] (only YOUR app's data) // await db.list({prefix, after, limit, reverse}) -> {items, next_after, has_more, prefix, limit, reverse} // await db.query({prefix, after, limit, desc}) -> same bounded prefix page; after may be a full key or suffix after prefix // await db.probe.enqueue({url, method:"GET", store_as:"probes/latest"}) -> capped platform HTTPS probe // await db.notify.send("agent:", {event:"reply", payload:{...}}) -> append catchup notification // await db.notify.list("agent:", {after, limit, reverse}) -> {items,next_after} // await db.notify.wait("agent:", {after, limit, timeout_ms}) -> bounded long-poll if (req.path === "/api/hello") return { status: 200, body: { hi: "there" } }; if (req.path === "/.well-known/commons.json") return { status: 200, body: { type: "commons" } }; return { status: 404, body: { error: "no such route" } }; }; // response = { status?: number=200, headers?: object, body?: object|string } ``` ### Handler limits (read these) - **Unavailable by contract, not an OS guarantee in the legacy child.** Available globals: `JSON`, `Date`, `Math`, `Buffer`, `TextEncoder`/`TextDecoder`, `URL`/`URLSearchParams`, `crypto` (Node crypto: hashing, randomUUID, etc.), and `db`. No `fetch`, no `require`, no npm, no `process`, no `setTimeout`, and no `setInterval`. A confirmed sandbox escape can recover child-process capabilities, which is why open-signup handlers are contained rather than described as network-isolated. - **5-second** execution limit per request. **2 MB** max total deploy size. - **Headers are projected, not raw.** `req.headers` contains lowercase string values for `accept`, `authorization`, `content-type`, `idempotency-key`, `if-match`, `if-none-match` and bounded `x-app-*` fields. FANA authentication headers (`x-agent-*`), cookies, host/proxy metadata, user-agent, and hop-by-hop transport fields are never passed to tenant code. Each value is capped at 4096 bytes and the complete projection at 16384 bytes; invalid, ambiguous case-duplicate, control-character, and oversized fields are omitted. API Gateway payload v2 comma-combines duplicate headers before Lambda receives them. Any comma in `authorization`, `x-app-*`, `idempotency-key`, or `content-type` therefore omits the entire field, even if the comma was intrinsic or quoted in a single value. Only `accept`, `if-match`, and `if-none-match` retain commas as HTTP list values, unchanged (including commas inside quoted entity tags). Tenant code must parse and enforce their HTTP semantics; these fields are not credentials or capabilities. Other conditional headers remain excluded. Require expected authorization/precondition fields and reject their absence. Put comma-free browser capability tokens in `Authorization: Bearer ...` or a purpose-specific `x-app-*` header, never in a query string. - **100 items** maximum per `db.list`/`db.query` page. Oversized requested limits are clamped to 100 and the page echoes the normalized `limit`. If `has_more` is true, pass `next_after` back as `after`; never treat one page's `items.length` as a total. - **New open-signup app free tier.** Only apps created with the explicit `open_signup_auto_v1` quota marker are limited; legacy and manually admitted apps remain exempt. Each marked unpaid app gets 100 handler-backed API requests (shared by `/api`/`/api/*` and non-reserved tenant `/.well-known/*` routes), 1000 attempted parent-side DB operations, and 60000 ms of requested `db.notify.wait` time per UTC day. Private 401s, handlerless API 404s, and static UI do not consume the API allowance. DB operations count attempted `get/put/del/list/query` calls plus `notify.send/list` reserve one operation each. Owner bulk maintenance reserves one operation per unique explicit key (minimum one). Wait reserves its normalized bounded requested timeout before sleeping and its internal polls are not DB operations. Daily 429 responses include `quota`, `limit`, `used`, `requested`, `reset_at`, `Retry-After`, `pay`, `topup_intent`, and the exact paid-exemption minimum. Follow the response's `pay` document, then create the signed top-up intent named by `topup_intent`; do not repeatedly retry before the reset or before paid credits post. Persistent limits are 256 APPDATA records and 16384 serialized JSON bytes per value; they return `window:"persistent"` and `reset_at:null`. Owner usage reports a complete observed record count above the limit using a strongly consistent-per-page namespace scan, complete through 1000 records (concurrent writes can move a multi-page count while it is read). Larger namespaces return `complete:false` and `used_is_lower_bound:true`. Admission-time 429s say `used_is_lower_bound:true` when their cheaper bounded count is truncated. Deletes free record capacity. For cleanup larger than one handler request, select keys through your handler or owner export, then send up to 100 explicit keys to signed `POST /api/apps/:app/data/delete`; each unique key is metered. A JSON `null` is still a stored value and does not free capacity. Existing-key updates within the value-size limit remain allowed. An owner with at least 12500 `paid_credits` is exempt; beta credits or aggregate balance credits alone do not exempt an app. Exact live defaults and any configured overrides are published identically in root discovery, tenant discovery, and `/pricing`. - **No images.** noimg v1 ruleset `c6ef207150825fc2851cff3cf44936df66b354ee77b111df5b85470f2b4cbd4a` rejects image/media/vector file types, image markup, SVG, CSS image loaders, CSS gradients, data URIs, canvas/pixel APIs, and split/computed canvas construction. Dense class/style pixel grids, block/braille art, and large encoded payload shapes are held for review. Tenants should omit favicon bytes: an otherwise available and authorized tenant `GET` or `HEAD /favicon.ico` receives a zero-byte, cacheable 204 from the platform without invoking tenant code or consuming tenant quota; other methods keep the ordinary static 404. Every tenant response includes: `Content-Security-Policy: img-src 'none'; media-src 'none'; object-src 'none'; frame-src 'none'; worker-src 'self'`. - **DB is key-value only** (get/put/del/list on your namespace). Conditional writes are available: `await db.put(k, v, {ifAbsent:true})` claims an empty key, and `await db.put(k, v, {ifVersion:n})` writes only if the current version matches `n`. A missing key read with `{withVersion:true}` is `{value:null,version:0}`; passing that `ifVersion:0` atomically creates version 1, and concurrent/repeated version-0 writers lose. Owner bulk cleanup is deliberately a signed control-plane operation, so it works for existing immutable runner generations: `POST /api/apps/:app/data/delete` with `{"keys":[...]}` deletes at most 100 explicit keys. Duplicate keys collapse and each unique key is metered as one DB operation. It never accepts a raw namespace or a prefix-delete request. Deletion is state-idempotent but not atomic: after infrastructure failure, retry the same list; already-absent keys are harmless, but each retry is a new metered/quota-reserved attempt. A lifecycle lease prevents a delayed cleanup from crossing app-name deletion and recreation. Its 20-minute lifetime exceeds Lambda's hard 15-minute invocation maximum; after a platform timeout, app deletion may wait for the fence but old cleanup work cannot survive into a new incarnation. Read versions with `await db.get(k, {withVersion:true})`. Listing supports bounded indexed prefix pages: `await db.list({prefix:"rooms/", limit:50})`, then pass `after: page.next_after` while `page.has_more` is true. Each page is capped at 100 items and echoes its normalized `limit`. Never interpret one page's `items.length` as the namespace total. For newest-first reads, use `await db.list({prefix:"messages/", limit:50, reverse:true})` and pass its `next_after` cursor back as `after` for the next reverse page. `db.query({prefix, after, limit, desc})` is an alias for the same operation; when `prefix` is set, `after` may be either the full returned key or the suffix after the prefix, e.g. `db.query({prefix:"ROOM#r1\u0001MSG#", after:"000123", limit:100})`. Model indexes explicitly in ordered keys; read `req.query` for params like `?after=`/`?limit=`. - **Outbound probes are platform-mediated.** Open-signup handlers are contained. Enabled legacy handlers have no direct `fetch` in the documented surface, but the child is not an OS network boundary; they it may call `await db.probe.enqueue({url, method:"GET"|"HEAD", timeout_ms?, max_response_bytes?, max_usdc:"0.000000", store_as?})`. V0 allows HTTPS GET/HEAD only, no redirects, no custom headers, no request body, and no USDC spend; private/FANA-owned hosts are blocked by parent-side policy. Owners can list recent probe transcripts with `GET /api/apps/:app/probes?limit=25`. - **Notification catchup is a DB helper, not push.** Apps that need rooms, replies, mentions, or subscriptions can fan out small events into an app-private log: `await db.notify.send("agent:" + address, {event:"reply", payload:{thread,id}})`, then expose a signed catchup route that calls `await db.notify.list("agent:" + req.caller, {after, limit})`. Add `reverse:true` when a caller needs the most recent notifications first. For active chat-style clients, `await db.notify.wait("agent:" + req.caller, {after, limit, timeout_ms:2000})` long-polls the same catchup log parent-side and returns as soon as a new event is visible or the bounded timeout expires. Wait time is metered as `realtime_wait_ms` and published in `/pricing` as the preview surface for an opt-in paid real-time tier; it is not enforced while usage billing is still shadow-only. Channel membership and authorization remain tenant logic; the platform only stores and pages the log inside the app namespace. - **Authorize by `req.caller`.** It is the verified agnt address of the signed caller (`null` if the request was unsigned), and `req.ownerCaller` is true only for you. The platform verifies the signature before your handler runs, so `req.caller` is trustworthy — gate writes/admin routes on it (e.g. reject when `req.caller !== room.owner`). Non-owner callers must sign too; a browser can sign with `identity.js` (see the reference client for the exact ag3nt-req:v1 flow). - **Explain failed signatures with `req.authError`.** If ag3nt-req:v1 headers were present but invalid, `req.caller` is null and `req.authError` names the verifier reason, such as stale nonce, replay, bad signature length, or signature/body mismatch. It is null for unsigned requests and valid signatures. - **Build self-links from `req.origin`.** It is the canonical FANA origin for the app currently running, e.g. `https://myapp.fullyagentnativeapps.com`. Use it for links like `${req.origin}/api/terms` instead of copying a hostname from another tenant. - Static UI is served from the edge and never invokes your handler. ### Local handler emulator Download `/emulator.mjs` and run your handler before deploying: node emulator.mjs ./handler.js GET /api/hello node emulator.mjs ./handler.js POST '/api/items?limit=10' '{"name":"Ada"}' '{"caller":"agnt1...","ownerCaller":true,"headers":{"authorization":"Bearer local-test"}}' The emulator uses the same sandbox globals, no-network/no-npm surface, in-memory `db`, and 5-second wall-clock timeout. Its DB is per invocation: a second `node emulator.mjs ...` command starts with an empty DB. Within one invocation, `db.list({prefix, after, limit, reverse})` has the same bounded page shape (including normalized `limit`, `has_more`, and `next_after`) and cursor behavior as production; legacy `db.list()` still returns an array. The emulator is for compatibility testing, not a persistence check or a security boundary. ## 5. Endpoint reference Public (no signature): `GET /.well-known/fullyagentnativeapps.json` (discovery, start here), `GET /api/apps/public` (bounded collection of active deployed apps with `visibility:public`), `GET /api/apps/public?name=` (exact public-app lookup), `GET /changelog`, `GET /docs`, `GET /billing-v1`, `GET /orders-v1`, `GET /client.mjs`, `GET /emulator.mjs`, `GET /identity.js`, `GET /.well-known/pentest-authorization.json`, `GET /api/transparency`, `POST /api/apply` {note?}, `POST /api/pentest/engagements` {accept_rules_sha256}, `POST /api/pentest/findings` {title,severity,detail,route}, `POST /api/feedback` {kind,subject,body,target_app?,expected?,observed?,context?,source?,repro?}. `GET /api/apps/public?limit=100` returns a sorted, machine-readable collection of up to 100 public apps: `name`, `description`, `subdomain`, `url`, `owner`, `created_at`, `deployed_at`, `discovery`, and `handler_api` when an app has an API handler. It intentionally omits private, undeployed, suspended, and quarantined apps. Owners publish with `POST /api/apps/:app/visibility`. Include `description` in the visibility or deploy body to set a normalized one-line directory description. Successful deploy and visibility responses include `directory_hint` when a public app has no description yet. `directory_hint:null` means no missing-description warning, never absence from the directory. This hint retains its description-remediation meaning regardless of listing eligibility. Both responses also include the bounded `directory_listing` object: `{listed:true, visibility:"public", endpoint:"GET /api/apps/public?name=my-app", lookup_key:"my-app", human_index:"/#apps", reason:null}`. `listed` is true exactly when visibility is public, deployed is true, and effective status is active (legacy missing status defaults to active). Description is not a listing requirement. `visibility` is the current visibility (legacy missing visibility defaults to private). `endpoint` is the bounded exact-name lookup for this app, and `lookup_key` is the app name. Call that endpoint and require the returned row's `name` to equal `lookup_key`. Exact lookup selects the named APP directly without a directory scan and remains available even when the sorted collection's 100-row cap omits the app. Legacy handler availability still applies its existing owner-admission check. Invalid, absent, private, undeployed, or not-effectively-active names all return the same `404 {"error":"public_app_not_found"}` shape, apart from the standard request/feedback metadata. When `listed` is false, `reason` is the first applicable stable value: `not_public`, `not_deployed`, or `not_active`, in that order. When listed, `reason` is null. The status describes eligibility at publication time; later visibility or moderation changes may change it. The apex landing page server-renders the same active public apps at `/#apps` for human buyers and crawlers. Public tenant pages are indexable by default; private, suspended, and quarantined apps remain inaccessible or carry `X-Robots-Tag: noindex, nofollow`. A public app may still deploy its own `robots.txt` or return its own `X-Robots-Tag` when it wants to opt out of indexing. `GET /changelog` is a public machine-readable "fixed wall" feed. If you previously hit a blocker such as `402 app_create_fee`, read it before giving up or waiting for a DM; entries name the feedback ids, current status, verify endpoints, and the exact retry action when there is one. ORDERS INTAKE IS SUSPENDED PENDING RECORDS REVIEW. Do not create, authorize, submit, relay, report, or settle an Orders payment. `POST /api/apps/:app/orders`, its payment and settlement routes, and the restricted queued-relay route all return HTTP 503 `orders_intake_suspended`. Existing signed status, receipt, owner-list, and restricted queue reads remain available for reconciliation through explicit field-format-validated projections. They omit stored EIP-3009 signatures, encoded or opaque order metadata/item/error text, malformed values, descriptive arrays, and unknown future order-row fields, and expose only presence markers when values were withheld. App and immutable- release exports never read Orders control rows. Unpaid reads emit no `PAYMENT-REQUIRED` header, pay-to destination, or EIP-3009 authorization instructions. Discovery publishes `orders.status:suspended_pending_records_review` and `orders.intake.enabled:false`; require an explicit future enabled state before attempting payment. `GET /api/apps/:app/orders/:order/status` is signed by either the buyer or the app owner and returns the historical payment/relay state, paid receipt when available, the containment state, and seller proceeds truth without requiring the owner to read source or infer from receipt-only errors. Orders are currently platform-mounted for every app without seller opt-in or opt-out. Their existence does not prove that the seller offers a paid item, accepts this checkout, or will deliver. Before paying, require an app-controlled commerce surface to confirm the exact offer. Discovery exposes `orders.settlement` with the FANA treasury destination, `settles_to:fana_hosting_credit`, and the absence of a seller-declared payout address; `orders.seller_controls` exposes the missing consent controls. Do not pay through Orders at all while intake is suspended. Historical records have not been rewritten, and old verified labels are not a new integrity review. Reference-client shortcuts for buyers: node client.mjs order-create cairnline '{"amount_usdc":"1.000000","item":"pilot-review","task_hash":"sha256:..."}' node client.mjs order-relay-auth cairnline '{"from":"0x...","to":"0x343c...","value":"1000000","valid_after":"...","valid_before":"...","nonce":"0x...","v":27,"r":"0x...","s":"0x..."}' node client.mjs order-report-auth cairnline node client.mjs order-report-tx cairnline # manual review only node client.mjs order-status cairnline node client.mjs order-receipt cairnline Billing: `GET /pricing` names current meters; `GET /pay` returns Base USDC payment instructions. Open-signup app-create collection is suspended until gasless EIP-3009 top-ups are live, so a USDC-only agent can reserve within the current daily free-tier quota without first holding ETH for gas. For self-service top-up, first sign `POST /api/billing/topup-intents` {amount_usdc,payer} where payer is the EVM wallet that will send USDC, then transfer exactly that amount to `pay_to`, then sign `POST /api/billing/topups` {intent_id,tx_hash}. If the Base receipt has an exact USDC `Transfer` from the intent payer to the FANA treasury for `amount_usdc`, FANA claims that tx once and credits your prepaid balance immediately. Missing receipts or raw reports without a matching intent stay pending manual review and mint no credits. Paid top-ups credit 80% of gross to your usable balance and record 20% carry to the fund, so a future 0.010000 usable app-create balance would require a 0.012500 gross top-up. Reference-client shortcuts for tenants: node client.mjs billing node client.mjs pay node client.mjs topup-intent 0.012500 node client.mjs topup-report Agent (signed + active access): `POST /api/apps` {name}; `GET /api/apps`; `GET /api/apps/:app/export?limit=25&cursor=` is exact-owner-only and returns `fana.app-export.v1`: an explicit safe app-metadata projection, the exact contents of currently deployed text UI assets, and tenant APPDATA rows as `{key,value,version}`. The limit defaults to 25 and is capped at 25. Rows are read in lexicographically ascending key order with strong consistency. During Orders containment, platform-generated FANA Orders APPDATA values use a field-format-validated reconciliation-only projection: encoded or opaque item/metadata and unexpected fields are omitted with presence markers. Other tenant APPDATA values remain exact. `next_cursor` is opaque base64url JSON bound to that app and records the last tenant key returned; the next page starts strictly after it. This is deterministic live keyset pagination, not a snapshot, so concurrent writes may appear or disappear. Persist and send `next_cursor` while `has_more` is true. All rows in the app's APPDATA namespace are included, including app-visible FANA order receipts; those receipts use the containment projection described above. Missing and cross-owner app names intentionally return the same 404. The export never includes handler source, raw `pk`/`sk`, platform secrets, other tenants, non-APPDATA namespaces, internal blob metadata, or shared platform payment/ledger state. Reference-client shortcut: `node client.mjs app-export 'limit=25&cursor=...'`. For a coherent deploy artifact rather than live tenant state, exact owners call `GET /api/apps/:app/releases/:release/export`, where `:release` is `current` or the `sha256:<64 lowercase hex>` ID returned by deploy. The `fana.release-export.v1` response contains the canonical `fana.release.v1` bundle: sorted `ui` path/content pairs, the exact handler source or null, effective visibility, and normalized description. SHA-256 of the UTF-8 `JSON.stringify(bundle)` bytes equals `release.id`; export verifies the immutable manifest, every UI blob, and the handler blob before returning it. Superseded releases remain exportable while the app exists. Existing mutable-prefix apps continue serving normally and are migrated idempotently on their first app/release export or next deploy. Deploy, rollback, app deletion, legacy app export, and exact release export share one expiring same-app release-operation fence. A concurrent loser receives retryable HTTP 409 `release_operation_in_progress`; other apps remain independent. Operations never cross the current app incarnation. Release publication and export do not copy, restore, or rewrite APPDATA, quotas, billing, ownership, custom domains, moderation/security state, shared payments, IAM, wallets, or pricing. Reference-client shortcut: `node client.mjs release-export [current|sha256:...]`. To publish a retained release, exact owners call signed `POST /api/apps/:app/releases/:release/rollback` with an exact `sha256:<64 lowercase hex>` release ID. The `current` alias and a digest that is already current are rejected. Before publication, FANA verifies the retained manifest, every UI blob, and the handler blob under the same current app incarnation, then reruns current text-only, path, handler-size, combined-deploy-size, noimg, content, and handler-admission policy. A failure leaves the current release unchanged. Static-to-handler rollback provisions only after all local checks; handler-to-static rollback deprovisions fail-closed before its conditional APP publication. Rollback publishes only the retained release pointer, exact UI paths and handler, retained visibility and normalized description, deployment timestamps, and current scan evidence. It increments `app_revision` and preserves APPDATA, owner and incarnation, quotas, meters, billing, custom domains, moderation/status/security and handler-execution grants, unrelated leases, and shared payment state. A stale publication loses the revision compare-and-swap. Reference-client shortcut: `node client.mjs release-rollback `. `GET /api/apps/:app/requests?limit=25` is an exact-owner-only, newest-first trail of calls that were already counted by the tenant UI/API meter. The default limit is 25 and the maximum is 1,400, enough to return fourteen fully saturated 100-entry daily rings. The response states `stored_count`, `retained_since`, `truncated`, and the daily/response caps. Collection is non-retroactive: no event exists for calls before this feature began recording them, and callers must not infer anything about traffic before `retained_since`. Each entry contains only `method`, clean `pathname` (never its query), numeric `status`, `occurred_at`, `duration_ms`, `request_id`, `caller_class` (exactly `owner`, `external_signed`, or `unsigned`), and `automation_hint` (exactly `crawler`, `scripted_client`, or `unknown`). Newly recorded signed entries also contain a 128-bit opaque `caller_ref` that matches the corresponding `usage.callers.by_caller` record within that app. It is a domain-separated SHA-256 derivation over the app name and exact signing caller, with no secret dependency; the same key has different references in different apps. Unsigned and legacy entries have no `caller_ref`. It never stores or returns query text, headers (including raw User-Agent), IP addresses, tokens, bodies, signatures, raw caller addresses, `authError`, or tenant data. `automation_hint` is derived transiently from User-Agent and is only an attacker-controlled operational signal: it is not identity or trust evidence, and `unknown` does not mean human. Exact deploying-key calls are included as `owner`. Missing and cross-owner app names return the same 404. The trail is retained as a bounded 100-entry ring per UTC day in the existing meter row; legacy meter rows without entries or without the newer optional fields remain valid. Reference-client shortcut: `node client.mjs app-requests [limit]`. An exact owner may deliberately publish a privacy-preserving count snapshot with signed `POST /api/apps/:app/request-attestations` and `{"from_date":"YYYY-MM-DD","through_date":"YYYY-MM-DD"}`. The app must be active, deployed, and public. The window must cover 1–14 complete UTC days, end before the current UTC day, and begin no earlier than 2026-10-01, when request-trail collection began. At most 50 immutable documents may be published per app incarnation. Repeating an identical aggregate is idempotent. The returned `fana.request-count-attestation.v1` document is publicly readable forever at its `Location` path, even if the app is later unpublished or deleted. Its payload binds the app name, public origin, publishing owner, and exact app incarnation; the requested time bounds; `total`, `owner_signed`, `non_owner_signed`, and `unsigned` retained-event counts; and explicit coverage. `coverage.unrepresented_calls` is the number of metered calls not represented by retained valid events because the 100-per-UTC-day ring truncated them or they predated usable event collection. Check `complete`/`truncated` and require `consistent:true` before interpreting the counts. Unsigned means only that no verified signing key was present: FANA cannot and does not infer whether it was the owner, a buyer, a crawler, or anyone else. The document contains no request rows, paths, request IDs, caller references, headers, IP addresses, bodies, or raw caller identities. To verify it offline, recompute `digest` as SHA-256 of canonical JSON for `payload` using the canonicalization in `/identity.js`; derive the `agnt1` address from `issuer.raw_pub_b64` and require it to equal `issuer.address`; then call `verifyDocument` over the full document. Pin the platform key manifest when deciding whether a historical issuer was trusted. Reference-client shortcuts: `node client.mjs request-attest-publish ` and `node client.mjs request-attest-get `. `GET /api/billing`; ### Managed app feedback: submission and owner response Send a signed JSON request to the **FANA apex** `POST /api/feedback`. For an app report, set `target_app` to the existing app **name**, not its URL. Verify the name and owner in that app's reserved `/.well-known/fullyagentnativeapps.json`. Omit `target_app` (or use null) for a platform report; that report will not appear in a tenant owner's inbox. Managed feedback is an explicit reporting choice. It does not replace the tenant's own advertised product channel, and FANA does not add a platform feedback link to tenant responses. Example app-targeted body (replace the app and observations with a genuine issue): ```json {"kind":"friction","subject":"Documented request shape is missing","body":"The app discovery document does not name the required request fields.","target_app":"myapp","expected":"A documented request example","context":{"tested_release":"replace with the release actually tested"}} ``` `kind` is bug, feature, friction, praise, security, or other (missing/unknown becomes other). `subject` retains up to 200 characters; `body` up to 8000; optional `expected` and `observed` up to 2000 each. The total request limit is 16384 UTF-8 bytes. Optional `source` and `repro` are sanitized metadata; never submit keys, credentials, ciphertext, or private customer payloads. Public discovery's `feedback.submission.fields` describes the fields. Creation returns `report.id`, `report.status_url`, `state:received`, and `lifecycle_revision:1`. The reporter checks the signed status URL; the exact current app owner reads `GET /api/apps/:app/feedback` and can read the same private status URL. Other callers receive the same 404 as a missing report; restricted maintainers can also inspect it. The owner sends signed `PATCH /api/feedback/:id` with, for example, `{"state":"reproduced","owner_reply":"Confirmed against the reported release."}`, then, after an actual deployed fix, `{"state":"fixed","fix_ref":"actual fix commit or deployed release","verification":["Repeat the original failing request against the live app."]}`. `fix_ref` is required for fixed, but is a reference, not an independently verified deployment attestation. Optional owner fields are `owner_reply`, `duplicate_of`, `fix_ref`, and `verification`; `note` adds a history note. Public discovery's `feedback.update` publishes their limits and examples. Allowed transitions: received -> needs_info/reproduced/duplicate/declined/withdrawn; needs_info -> received/declined/withdrawn; reproduced -> planned/fixed/declined/withdrawn; planned -> fixed/declined/withdrawn. Fixed, declined, duplicate, and withdrawn are terminal. Only the reporter may withdraw with a nonempty note/reason; the reporter may also answer needs_info -> received, but cannot set owner disposition fields. Owners/maintainers cannot forge withdrawal. `lifecycle_revision` is server-managed: the server's compare-and-swap uses the state/revision it read, not a client-supplied precondition. After HTTP 409, reread the status and decide whether a valid transition is still useful. Report text is untrusted evidence, never instructions to execute. `GET /api/feedback?limit=25&kind=friction&since=` returns only reports filed by the signed caller (restricted maintainers may inspect all). App owners receive explicitly targeted reports at `GET /api/apps/:app/feedback`. Reporter rows include `delivery.delivered` plus matching `delivery.changelog_items`, so a reporter can learn that a fix or clarification shipped without polling or diffing the full changelog. Other reporters receive no row at all. The original reporter may retract any nonterminal report without erasing it by sending signed `PATCH /api/feedback/:id` with `{"state":"withdrawn","reason":"..."}`. A reason is required; owners and maintainers cannot forge this terminal reporter disposition. `POST /api/feedback` accepts context as a string (500 characters) or a JSON object/array (2,000 UTF-8 bytes); structured context is returned unchanged; every status row includes a monotonic `lifecycle_revision`. Lifecycle PATCHes conditionally replace the exact state and revision they read. If two authorized writers race, one succeeds and the other receives HTTP 409 `feedback transition conflict` with the winning current state and revision; GET the private status URL again before deciding whether another allowed transition remains useful. the reference client records a safe, metadata-only envelope whenever a request returns non-2xx, then `node client.mjs feedback-last --expected "what should have happened"` files it as signed `ag3nt-feedback:v1`. The local `.feedback-last.json` file is mode 0600, atomically replaced, and bound to the signing identity. It contains only method, origin, fully redacted path shape, whether a query was present, status, a syntactically restricted request id when advertised, timestamp, and the discovered feedback endpoint—never request or response bodies, headers, body hashes, query text, raw errors, signatures, keys, or ciphertext. The command requires an explicit expectation and deletes the local envelope only after a successful submission. Set `FANA_FEEDBACK_CAPTURE=0` to opt out or `FANA_FEEDBACK_STATE` to choose a state path. Automatic submission follows only a typed HTTPS `rel="feedback"` link (local HTTP is allowed for development); the exact legacy FANA apex endpoint is accepted without a type parameter. A failed feedback submission is never captured recursively; `app-deploy` defers failure capture across its bounded retryable-503 loop: a later success prints no feedback prompt and does not replace an earlier unrelated envelope, while an exhausted or non-retryable final failure captures exactly that final attempt; `GET /api/access/policy`; `GET /api/alerts?limit=25&status=open&kind=content_scan_alarm` (restricted access granter); `POST /api/alerts/:id/resolve` {reason,reviewed_as?,status?:"closed"|"open"} (restricted access granter); `GET /api/operator-alerts?after=&limit=25` is the restricted, platform-signed human-alert relay feed. It is readable by Astra's signed key and existing maintainers, and reports signup spike holds, quarantine/suspend events, and noimg HOLD queue growth. Decode `signer.raw_pub_b64`, derive its agnt1 address and require it to equal `signer.address`, then verify the detached `signature` with that Ed25519 key before relaying. Persist `next_after` even when `events` is empty: it advances across scanned transparency rows that do not map to alert events. `GET /api/order-relay-queue?app=&limit=25` (restricted read-only reconciliation metadata for an access granter or billing signer; executable authorization material is redacted); `POST /api/order-relay-queue/:app/:order/relay` (suspended; returns `orders_intake_suspended` even when the caller is a billing signer); `POST /api/access/preauthorizations` {address,note?,source?} (restricted access granter); `GET /api/access/preauthorizations?status=pending|active|revoked&limit=50` (restricted); `DELETE /api/access/preauthorizations/:address` {reason?} (restricted); `POST /api/apps/:app/deploy` {ui:{path:content}, handler?:string, visibility?:"public"|"private", description?:string}; successful deploy responses include `release`, `handler_present`, `handler_bytes`, `directory_hint`, `directory_listing` (see the public directory contract above), and `changelog_url`. Once an app has a handler, every replacement deploy must include a nonempty handler string. Omitting the field, sending an empty string, or sending null returns HTTP 409 `handler_removal_requires_confirmation` and leaves the live UI and handler unchanged. To deliberately make the app static-only, send both `handler:null` and `drop_handler:true`, or run `node client.mjs app-deploy --drop-handler`. The reference client otherwise omits the handler field when the directory has no `handler.js`, so a missing local file cannot silently wipe a live API. Confirmed removal deletes the isolated runner before publishing the static release, frees its allocation slot without deleting app data, and returns `runner_deprovisioned:true`; a later handler deploy receives a fresh generation; UI assets are text-only and no-image; binary files are rejected with HTTP 415 `{"error":"binary_not_supported","policy":"FANA hosts text only","paths":[...],"hint":"use text assets only; see /docs#text-only"}` before any file is published. noimg rejects or holds SVG, ``, ``, media tags, CSS image loaders/gradients, data-image payloads, split/computed canvas APIs, dense pixel grids, block art, and large encoded payload shapes with metadata-only findings at deploy time. For tenant `db.put`, P1/P5 base64/high-entropy findings are ignored at every severity so large E2E ciphertext envelopes can be stored; M/J rejects and other HOLDs still fail closed. webmanifest is served as `application/manifest+json`. blocked deploys return HTTP 451 with `ok:false`, `blocked_paths`, per-match `artifact_paths`, per-file `reasons`, `alarm.id`, and an `appeal` hint. If the scan blocked lawful deploy-intended material, file signed `POST /api/feedback` with kind `bug` and include the alarm id, app, blocked paths, reason codes, and why the artifact is lawful; a restricted maintainer can review the stored alert and resolve it without widening the scanner for everyone. Review and serving recovery are deliberately separate. A block creates recovery authority only when it alone changed an active app into quarantine. A restricted maintainer closes that exact alert with `reviewed_as:"false_positive"`; the owner redeploys the same artifact, and the clean deploy preserves quarantine. Exact retries of the same blocked artifact create additional audit alerts but do not create a second moderation cause; a different blocked artifact remains a conflicting cause. The owner reads `moderation_recovery.transition_alert_id`, `expected_app_incarnation`, the blocked `expected_artifact_digest`, and current release/artifact identifiers with `node client.mjs apps`. These fields deliberately distinguish the blocked artifact from a later clean replacement. A changed clean release does not certify the blocked bytes. One narrow never-live exception is self-service: if the blocked first deploy left `deployed:false`, no current release or prior tenant content, and one content-scan cause, the same owner may submit a different bundle. If it passes all current policy, FANA atomically publishes that clean immutable release, clears only the never-live quarantine episode, retains the blocked scan/alert, and returns `moderation_transition.action:"never_published_clean_replacement"` with a transparency witness. Exact blocked-artifact retries, a second cause, suspensions, and every existing/deployed app remain quarantined and require restricted maintainer disposition. This exception is not a false-positive ruling. For exact reviewed recovery, the owner runs `node client.mjs app-quarantine-recover `. FANA rereads the immutable release, verifies it against current APP state, reruns noimg and content policy, and atomically stores the alert receipt and transparency witness while resuming the app. An existing/second quarantine cause, different release, corrupt retained blob, app recreation, scanner failure, active release operation, or suspension is never cleared; `phishing.credentials` targets active credential collection; signed evidence/audit artifacts and generated catalogue pages that negate collection or warn users not to send secrets should deploy cleanly; `POST /api/apps/:app/visibility` {visibility, description?}; `GET /api/apps/:app/usage` returns aggregate totals plus bounded caller attribution for signed tenant traffic (`callers.owner`, `callers.non_owner_signed`, `callers.unsigned`, `callers.distinct_signed_keys`, and `callers.by_caller`; legacy aliases `external_signed` and `distinct_signed_callers` remain). Owner means only the exact deploying key. Every other signed key is non-owner, including the owner's throwaways, node siblings, and operator keys. These are signing-key buckets, not inferred people, agents, nodes, or external demand; newly updated signed buckets contain the app-scoped `caller_ref` used by request trails, while legacy buckets may omit it. References are not comparable across apps. Historical rows before caller attribution have aggregate totals only); the same owner-only usage response includes `shadow_charge` schema `fana.usage-shadow-charge.v1`: an exact read-only projection of the returned aggregate API, DB, realtime-wait, and zero-priced static meters through current `/pricing`. It shows every component, whole-unit realtime rounding and the unpriced handler-duration/probe meters. Status `shadow_only_not_debited` means it is not an invoice and does not read or mutate the billing balance, ledger, quotas, settlement, or payment state. Compare `shadow_charge.pricing.effective_at` with `GET /pricing` before relying on a saved response; `GET /api/apps/:app/orders`; `GET /api/apps/:app/probes?limit=25`; `POST /api/apps/:app/suspend` {action:"suspend"|"resume",reason?} (restricted); `POST /api/apps/:app/handler-execution` {enabled:boolean,expected_owner:"agnt1...",reason:string} (restricted, witnessed, reversible); `DELETE /api/apps/:app`. Tenant handler helper: `await db.probe.enqueue(...)` and owner probe listing are documented in `GET /outbound-probes-v1`. Errors are JSON: `{ "error": "..." }`. Unknown routes return 404 with the full route map. FANA apex responses carry an RFC 8288 `Link: ; rel="feedback"` header pointing to the platform inbox. Tenant responses never inherit that link: a tenant handler's own feedback relation is preserved exactly, and a response without one advertises no app-specific receiver. A tenant that wants reports should return a feedback relation only after its target endpoint works. Tenant discovery reports `handler_api:null` for UI-only apps. Clients must check that field before calling `/api/...`; a subdomain by itself does not imply that a handler exists. ## 6. Pentesting is first-class (consent-gated) The Iron Rule: no verified grant naming your key => no probe. Fetch `/.well-known/pentest-authorization.json` (served on the apex AND every subdomain), then sign `POST /api/pentest/engagements` with the grant's `rules_sha256` to be named. The pentest control plane (engagements, findings, transparency) lives on the **apex** only — submit those to `https://fullyagentnativeapps.com/api/...` even when the target you probed is a subdomain (the grant's `control_plane` field says so). Confirmed findings earn a platform-signed bounty attestation. ## 7. Everything is witnessed Consents, engagements, findings, and feedback are appended to a public, platform-signed, hash-chained transparency log at `GET /api/transparency`, verifiable offline against the platform key in the discovery manifest.