Merge branch 'feat/app-user-feedback' of https://github.com/HeyPuter/puter into feat/app-user-feedback

Add `requireVerified: true` to both app feedback routes (`GET /target` and `POST /`) in `AppFeedbackController`. This tightens access control so only verified user accounts can fetch feedback targets or submit app feedback.

.env.example

@@ -2,9 +2,9 @@
 # docker-compose.full.yml up -d`. None of the defaults below are safe for
 # anything beyond a local laptop test.
 
-# ── Public-facing ports (nginx) ---------------------------------------
+# ── Public-facing ports (Caddy) ---------------------------------------
 HTTP_PORT=80
-# HTTPS_PORT=443     # uncomment after you enable TLS in nginx/nginx.conf
+# HTTPS_PORT=443     # uncomment after you enable TLS in caddy/Caddyfile
 
 # ── MariaDB ------------------------------------------------------------
 MARIADB_ROOT_PASSWORD=replace-with-strong-password

.github/workflows/backend-tests.yaml

@@ -1,16 +1,57 @@
 name: Backend Tests
 
+# Runs on backend and extension changes. Tests are co-located with the
+# code (src/backend/**/*.test.ts, extensions/**/*.test.ts), so test-only
+# changes match the same globs. puter.js SDK changes are covered by
+# puterjs-tests.yaml instead.
 on:
   pull_request:
     types: [opened, synchronize, reopened]
-    paths-ignore:
-      - 'src/docs/**'
+    paths:
+      - 'src/backend/**'
+      - 'extensions/**'
+      - 'tools/**'
+      - 'package.json'
+      - 'package-lock.json'
+      # The type-check job below reads these.
+      - 'tsconfig.json'
+      - 'tsconfig.build.json'
+      - '.github/workflows/backend-tests.yaml'
 
 permissions:
   contents: read
   pull-requests: write
 
 jobs:
+  # `tsconfig.build.json` builds with `noCheck: true`, so nothing else in CI
+  # runs the type checker and a missing export compiles to `undefined`,
+  # surfacing only when the call is finally reached at runtime. This diffs
+  # against tools/typecheck-baseline.json and fails only on *new* errors.
+  #
+  # The consuming repo runs an equivalent gate, but only once someone bumps the
+  # submodule pointer — too late to keep the error off this repo's default
+  # branch. Hence a gate here, on this repo's own pull requests.
+  #
+  # Its own job rather than a step in `test`: that one runs a base/PR matrix for
+  # coverage comparison, and the check only needs the PR ref, once.
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check (new errors only)
+        run: npm run typecheck
+
   test:
     runs-on: ubuntu-latest
     strategy:

.github/workflows/docker-image.yaml

@@ -87,6 +87,8 @@ jobs:
                   platforms: linux/amd64,linux/arm64
                   context: .
                   push: true
+                  provenance: mode=max
+                  sbom: true
                   tags: ${{ steps.meta.outputs.tags }}
                   labels: ${{ steps.meta.outputs.labels }}
                   cache-from: type=gha

.github/workflows/puterjs-tests.yaml

@@ -0,0 +1,172 @@
+name: Puter.js API Tests
+
+# Runs on puter.js SDK changes — the suites live in src/puter-js/tests,
+# so test changes are covered by the same glob — plus the pieces the
+# runners depend on: the worker preamble, the in-memory test env in
+# testUtil, and the backend vitest config the API-tests config extends.
+# Backend and extension changes run backend-tests.yaml instead.
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - 'src/puter-js/**'
+      - 'src/worker/**'
+      - 'src/backend/testUtil.ts'
+      - 'src/backend/vitest.config.ts'
+      - 'tools/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - '.github/workflows/puterjs-tests.yaml'
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  # The JSDoc in src/puter-js/src is the source of truth for the SDK's public
+  # types. The declarations shipped to npm are generated from it at build time
+  # and never committed, so what needs guarding is the JSDoc itself: this
+  # generates the declarations and type-checks the published surface without
+  # skipLibCheck, which is how broken re-exports used to go unnoticed.
+  #
+  # Its own job rather than a step in `test`: that one builds bundles and
+  # installs a browser, and this needs neither.
+  types:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check the puter.js JSDoc produces declarations that type-check
+        run: npm run check:puterjs:types
+
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      # The runners exercise the built artifacts: the SDK bundle
+      # (src/puter-js/dist) for node + browser, and the worker preamble
+      # (src/worker/dist) for workerd.
+      - name: Build puter.js SDK and worker preamble
+        run: npm run build:workerLib
+
+      - name: Install Playwright chromium
+        run: npx playwright install --with-deps chromium
+
+      - name: Run puter.js API tests (node, browser, workerd)
+        run: npm run test:puterjs
+        env:
+          CI: 'true'
+
+  # SDK coverage on both refs, reported as a PR comment — same shape as
+  # backend-tests.yaml. This run uses the istanbul-instrumented bundle
+  # (the `test` job above keeps exercising the production build).
+  coverage:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - ref: ${{ github.base_ref }}
+            artifact: base
+          - ref: ${{ github.head_ref }}
+            artifact: pr
+
+    steps:
+      - name: Checkout ${{ matrix.ref }}
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ matrix.ref }}
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright chromium
+        run: npx playwright install --with-deps chromium
+
+      # The base leg is best-effort — it only enriches the PR comment with
+      # a comparison, and the base ref may predate the coverage script.
+      - name: Run puter.js API tests with coverage
+        continue-on-error: ${{ matrix.artifact == 'base' }}
+        run: npm run test:puterjs:coverage
+        env:
+          CI: 'true'
+
+      - name: Upload coverage artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: puterjs-coverage-${{ matrix.artifact }}
+          path: src/puter-js/coverage/coverage-*.json
+          retention-days: 14
+          if-no-files-found: ignore
+
+  report-coverage:
+    needs: coverage
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Download PR coverage
+        uses: actions/download-artifact@v4
+        with:
+          name: puterjs-coverage-pr
+          path: src/puter-js/coverage
+
+      # May not exist (base ref without the coverage script, or a failed
+      # base run) — then report without the comparison column.
+      - name: Download base coverage
+        id: base-coverage
+        continue-on-error: true
+        uses: actions/download-artifact@v4
+        with:
+          name: puterjs-coverage-base
+          path: coverage-base
+
+      - name: Report coverage on PR
+        if: steps.base-coverage.outcome == 'success'
+        uses: davelosert/vitest-coverage-report-action@v2
+        with:
+          name: puter.js SDK
+          json-summary-path: src/puter-js/coverage/coverage-summary.json
+          json-final-path: src/puter-js/coverage/coverage-final.json
+          json-summary-compare-path: coverage-base/coverage-summary.json
+
+      - name: Report coverage on PR (no base comparison)
+        if: steps.base-coverage.outcome != 'success'
+        uses: davelosert/vitest-coverage-report-action@v2
+        with:
+          name: puter.js SDK
+          json-summary-path: src/puter-js/coverage/coverage-summary.json
+          json-final-path: src/puter-js/coverage/coverage-final.json

.prettierrc.json

@@ -1,4 +1,5 @@
 {
     "tabWidth": 4,
-    "singleQuote": true
+    "singleQuote": true,
+    "plugins": ["prettier-plugin-jsdoc"]
 }

AGENTS.md

@@ -8,6 +8,9 @@ Use these as the source of truth before exploring further:
 
 - [README.md](README.md) — project overview and quickstart.
 - [doc/architecture.md](doc/architecture.md) — backend layered stack (controllers → drivers → services → stores → clients), `PuterServer` wiring, `Context` (ALS), and extensions.
+- [doc/contributing-apis.md](doc/contributing-apis.md) — adding and maintaining public APIs end to end (backend surface → puter.js → types → docs → tests). Follow it for any API work.
+- [doc/pagination.md](doc/pagination.md) — the one pagination convention for list APIs (limit/cursor/offset/includeTotal, envelope shape, cursor semantics).
+- [doc/alarms.md](doc/alarms.md) — raising alarms and picking a severity (what pages, what only gets recorded), plus the config that routes them.
 - [doc/self-hosting.md](doc/self-hosting.md) — running Puter outside hosted infra.
 - [CONTRIBUTING.md](CONTRIBUTING.md) — testing, security, AI-assisted code, PR conventions, Boy Scout Rule.
 - [SECURITY.md](SECURITY.md) — how to report vulnerabilities (do not file them publicly).
@@ -16,72 +19,21 @@ Use these as the source of truth before exploring further:
 
 ---
 
-## Backend
+## Repo-wide conventions
 
-The backend is organized as a layered stack inspired by Controller–Service–Repository with dependency injection. Every layer only depends on the layers beneath it, and `PuterServer` ([src/backend/server.ts](src/backend/server.ts)) wires the whole thing together.
+These apply everywhere — backend, puter.js, and GUI.
 
-### Layers (top → bottom)
+### Language & files
 
-| Layer           | Lives in                                             | Responsibility                                                                                                                                                 |
-| --------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Controllers** | [src/backend/controllers/](src/backend/controllers/) | Route handlers. Parse + validate input, apply per-route gates (auth, subdomain, rate limit, body parsers via `RouteOptions`), call services, format responses. |
-| **Drivers**     | [src/backend/drivers/](src/backend/drivers/)         | Optional. RPC-style handlers exposed over `/drivers/*`. Thin shells that validate RPC inputs and call into services/stores.                                    |
-| **Services**    | [src/backend/services/](src/backend/services/)       | Business logic. Assume the caller is already authenticated/authorized — services do not run auth gates themselves.                                             |
-| **Stores**      | [src/backend/stores/](src/backend/stores/)           | Persistence. Wraps clients with the domain shape services consume (rows, entities, KV namespaces).                                                             |
-| **Clients**     | [src/backend/clients/](src/backend/clients/)         | Adapters for external/internal services (sql, redis, s3, dynamo, email, event bus). Knows protocols, not domain concepts.                                      |
-| **Config**      | `config.*.json` → `IConfig`                          | Flat, typed config object every layer receives at construction.                                                                                                |
-
-Each layer receives the layers beneath it through its constructor. Dependencies are explicit and traceable from `PuterServer`.
-
-### Cross-layer rules
-
-- **Don't reach across layers.** Controllers do not poke clients directly; services do not register routes. If you want to, the abstraction is wrong — fix the abstraction.
-- **Don't call sideways within a layer for code reuse.** If two services need the same logic, lift it into a util/helper. Services should not depend on other services for shared code.
-- **Prefer explicit arguments over `Context` (ALS).** Reach for [Context](src/backend/core/context.ts) only when the value is genuinely request-scoped and would otherwise thread through many layers. Today it's used sparingly — mostly for `actor` and `req`.
-
-### Extensions
-
-Extensions live in [extensions/](extensions/) and parallel the layered stack. They are for **non-crucial parts of the system** — things Puter still works without if removed. If a feature is load-bearing for clients, it belongs in core, not in an extension (see [whoami](extensions/whoami.ts) as the cautionary example).
-
-The `extension` global ([src/backend/extensions.ts](src/backend/extensions.ts)) exposes:
-
-- `extension.registerClient/Store/Service/Driver/Controller(name, Class)` for first-class additions.
-- `extension.on(event, handler)` and `extension.get/post/put/delete/patch/use(path, opts?, handler)` for the lightweight common case. `opts` is the same `RouteOptions` controllers use.
-- `extension.import('client' | 'store' | 'service' | 'controller' | 'driver')` returns a lazy proxy to instantiated objects. `extension.config` exposes live config.
-
-### Language & file conventions
-
-- **Modules:** We transpile and build as needed — write ES modules, not CommonJS.
-- **TypeScript preferred for new files.** Existing JS is fine; convert opportunistically when you're already touching a file.
-- **Reuse types and code before adding duplicates.** Before defining a type, search for an existing one; extend it if close. Before writing a helper or repeating logic, search for an existing utility, helper, or implementation and reuse or extend it. Only add a new type or helper when nothing suitable exists.
-- **Make new types findable.** Co-locate them with the layer/module that owns them, export from the obvious entry point, and use a descriptive `PascalCase` name. Don't hide types in random files where future readers won't grep them.
-- **Naming:** `camelCase` for variables/functions, `PascalCase` for classes and for files containing a class (`AuthService.ts`, `KVStoreDriver.ts`).
+- Write ES modules, not CommonJS — we transpile and build as needed.
+- TypeScript preferred for new files in the backend and extensions; convert existing JS there opportunistically when you're already touching a file. The GUI and puter.js are plain JavaScript — don't introduce TypeScript files in them. In puter.js, type with JSDoc instead (see the puter.js section for what must be typed).
+- **Reuse before adding.** Search for an existing type, helper, or implementation and extend it; only add a new one when nothing suitable exists.
+- Make new types findable: descriptive `PascalCase` names, exported from the obvious entry point. A type used from many places belongs in the owning module's `types.ts` (e.g. [src/backend/controllers/types.ts](src/backend/controllers/types.ts)) rather than bloating a logic file; a type with a single consumer can stay next to it.
+- Naming: `camelCase` for variables/functions, `PascalCase` for classes and files containing a class (`AuthService.ts`). **Prefer `camelCase` for all new code** — new local variables, parameters, functions, and internal object properties. `snake_case` is reserved for identifiers that are part of an external contract: wire/JSON keys sent to or received from the backend, stable API error codes, public option names that already ship as `snake_case`, and established `puter_*` namespaced fields. Don't rename those (it's a breaking change), but don't introduce new `snake_case` alongside them either — a camelCase local can carry a value into a `snake_case` wire key (`{ operation_id: operationId }`).
 
 ### Comments
 
-Keep comments light. Prefer self-documenting code — clear names, small functions, obvious flow. Add a comment **only** when:
-
-- The _why_ is non-obvious (a hidden constraint, a workaround, a subtle invariant).
-- A non-trivial usage detail would otherwise trip the next reader.
-
-If comments need to be more than a line, its probably too long, and when it does need multiline comments, use multiline `/** ... */` JSDoc style for consistency. Use `//` for single-line comments.
-
-Don't restate what the code already says. Don't write comments that reference the current task or PR or version of something — those rot.
-
-**No ticket references in code or test comments.** Don't write `PUT-1234`, `AUTH-3`, `GUI-2`, `// fix for FOO-99`, `// per ROLLOUT-1`, or section headers like `// -- PUT-1020: ... --`. The ticket exists in git history and the issue tracker; the code should describe the _why_ in domain terms ("logout cascade transparently invalidates...") not project-management terms ("the cascade from AUTH-3..."). Same rule for test-block names and section dividers — describe what's being tested, not which ticket asked for it.
-
-**Use plain ASCII `-` in comment section dividers, not box-drawing characters.** Write `// -- Section name --`, not `// ── Section name ──`. The `─` (U+2500) character renders inconsistently in some editors and diff tools and adds nothing over `-`.
-
-### Tests
-
-When adding new behavior (function, endpoint, driver method, branch of logic), add a test for it.
-
-- Use Vitest for unit and integration tests. Test files go next to the code they test, named `*.test.ts` or `*.test.js`.
-- **Mock data, not methods.** Stub the inputs (fixtures, fake rows, sample payloads) rather than mocking the function under test or the layer beneath it. Over-mocking produces tests that pass while production breaks. If you must mock, mock at a real boundary (a client/external service), not within the same layer you're testing.
-- Prefer test server over mocking deps. We have existing test utilities for running full test server to boot deps based on config. (see [src/backend/testUtil.ts](src/backend/testUtil.ts)).
-- **Hit a real database / real client where reasonable.** Integration shapes catch the things unit tests with mocks miss.
-- **Regression tests for bug fixes.** A test that fails before your fix and passes after is the cheapest insurance against the bug coming back.
-- If something is genuinely hard to test (UI animation, third-party glue), skip it but say so in the PR.
+Keep comments light; prefer self-documenting code. Comment only when the _why_ is non-obvious or a usage detail would trip the next reader. Use `//` for single lines and `/** ... */` JSDoc when it genuinely needs more — if a comment runs long, it's probably too long. Don't restate the code and don't reference the current task, PR, or version — those rot. **No ticket references** (`PUT-1234`, `// fix for FOO-99`) in code, comments, or test names; describe the why in domain terms, not project-management terms. Use plain ASCII `-` in comment section dividers (`// -- Section --`), never box-drawing characters.
 
 ### Security & privacy
 
@@ -96,6 +48,105 @@ When in doubt, return less. Auth-, permission-, or data-export-related changes d
 ### Working rules of thumb
 
 - **Run it, don't just compile it.** "It type-checks" is not "it works." Exercise the code path end-to-end at least once.
-- **Read the neighbors before writing.** Match the shape of similar things already in the tree. If you genuinely think the existing pattern is wrong, raise it — don't quietly diverge.
-- **Boy Scout Rule, proportional to the change.** Fix the obvious typo, dead import, or missing typehint in files you're already touching. Don't ride a refactor along with a bug fix — that just makes review harder.
+- **Read the neighbors before writing.** Match the shape of similar things already in the tree. If you think the existing pattern is wrong, raise it — don't quietly diverge.
+- **Test new behavior.** Every new function, endpoint, driver method, or logic branch gets a test; every bug fix gets a regression test that fails before the fix. If something is genuinely hard to test, skip it but say so in the PR.
+- **Boy Scout Rule, proportional to the change.** Fix the obvious typo or dead import in files you're already touching; don't ride a refactor along with a bug fix.
 - **Understand what you commit.** AI assistance is fine; shipping code you couldn't defend in review is not.
+
+---
+
+## Backend
+
+A layered stack with explicit dependency injection: each layer depends only on the layers beneath it, receives them through its constructor, and `PuterServer` ([src/backend/server.ts](src/backend/server.ts)) wires the whole thing together. [doc/architecture.md](doc/architecture.md) is the full reference.
+
+| Layer (top → bottom) | Lives in                                             | Responsibility                                                                                                                                         |
+| -------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Controllers**      | [src/backend/controllers/](src/backend/controllers/) | Route handlers: parse/validate input, per-route gates via `RouteOptions` (auth, subdomain, rate limit, body parsers), call services, format responses. |
+| **Drivers**          | [src/backend/drivers/](src/backend/drivers/)         | Optional RPC-style handlers on `/drivers/*`; thin shells that validate inputs and call services/stores.                                                |
+| **Services**         | [src/backend/services/](src/backend/services/)       | Business logic. Assume the caller is already authenticated/authorized.                                                                                 |
+| **Stores**           | [src/backend/stores/](src/backend/stores/)           | Persistence; wraps clients in the domain shapes services consume.                                                                                      |
+| **Clients**          | [src/backend/clients/](src/backend/clients/)         | Adapters for external/internal services (sql, redis, s3, email, event bus). Protocols, not domain concepts.                                            |
+| **Config**           | `config.*.json` → `IConfig`                          | Flat, typed config object every layer receives at construction.                                                                                        |
+
+A public API can be exposed through either a controller or a driver — both are supported; prefer a controller when you need fine-grained control over routes and gates. [doc/contributing-apis.md](doc/contributing-apis.md) has the decision guide with links to the decorators and middleware for each.
+
+Cross-layer rules:
+
+- **Don't reach across layers.** Controllers don't poke clients; services don't register routes. If you want to, the abstraction is wrong — fix the abstraction.
+- **Don't call sideways within a layer for code reuse.** Two services needing the same logic means a util/helper, not a service-to-service dependency.
+- **Prefer explicit arguments over `Context` (ALS).** Reach for [Context](src/backend/core/context.ts) only for genuinely request-scoped values that would otherwise thread through many layers — today mostly `actor` and `req`.
+
+### Extensions
+
+[extensions/](extensions/) parallels the layered stack and is for **non-crucial parts of the system** — Puter still works with the extension removed. If core needs to call it, it belongs in core, not an extension (see [whoami](extensions/whoami.ts) as the cautionary example). The `extension` global ([src/backend/extensions.ts](src/backend/extensions.ts)) exposes:
+
+- `extension.registerClient/Store/Service/Driver/Controller(name, Class)` for first-class additions.
+- `extension.on(event, handler)` and `extension.get/post/put/delete/patch/use(path, opts?, handler)` for the lightweight common case. `opts` is the same `RouteOptions` controllers use.
+- `extension.import('client' | 'store' | 'service' | 'controller' | 'driver')` — lazy proxy to instantiated core objects. `extension.config` exposes live config.
+
+Follow the same layered structure inside an extension — unless it only needs a few route handlers, in which case the lightweight helpers are enough on their own.
+
+### Backend tests
+
+- Vitest; test files sit next to the code they test (`*.test.ts` / `*.test.js`). Run with `npm run test:backend`.
+- **Mock data, not methods.** Stub inputs (fixtures, fake rows, payloads), not the function under test or the layer beneath it — over-mocking produces tests that pass while production breaks. If you must mock, mock at a real boundary (a client/external service).
+- **Prefer the test server over mocking deps.** `setupPuterTestEnv()` in [src/backend/testUtil.ts](src/backend/testUtil.ts) boots a fully in-memory backend; hit a real database/client shape where reasonable — integration shapes catch what mocked unit tests miss.
+
+---
+
+## puter.js (the SDK)
+
+[src/puter-js/](src/puter-js/) is the public SDK. It ships live from `https://js.puter.com/v2/` with no version pinning — every existing app picks up changes immediately. Treat every observable behavior (signatures, response fields, error codes) as something a production app depends on.
+
+Layout: SDK modules in [src/puter-js/src/modules/](src/puter-js/src/modules/) (one file or directory per area — `FileSystem/`, `kv/`, `ai/`, …), shared plumbing in [src/puter-js/src/lib/](src/puter-js/src/lib/), generated (gitignored) type declarations in `src/puter-js/types/`, API tests in [src/puter-js/tests/api/](src/puter-js/tests/api/), UI e2e tests in [src/puter-js/tests/e2e/](src/puter-js/tests/e2e/), developer docs in [src/docs/](src/docs/).
+
+Language & typing: puter.js source is plain JavaScript — never TypeScript files — typed via JSDoc. **The JSDoc is the source of truth for the SDK's types.** `src/puter-js/types/` is `tsc --emitDeclarationOnly` output: the SDK build (`npm run build` in `src/puter-js`) generates it, the npm tarball ships it so TypeScript consumers get declarations, and git ignores it — it is never committed and never edited by hand. `npm run check:puterjs:types` generates it in CI and type-checks the result without `skipLibCheck`. The one hand-written declaration file is [src/puter-js/index.d.ts](src/puter-js/index.d.ts), which decides what is public and re-exports the generated names.
+
+Declare a shape where it belongs, and reference it with an `import(...)` type from elsewhere. A shape more than one file needs lives in the module's `types.js`; a shape shared across modules lives in [src/puter-js/src/lib/types.js](src/puter-js/src/lib/types.js); a shape with one consumer can stay next to it:
+
+```js
+/** @typedef {import('./types.js').KVOptConfig} KVOptConfig */
+```
+
+Use `@typedef {Object}` + `@property` for any shape whose fields need documenting — it is the only JSDoc form that carries a doc comment per field into the generated declaration. Keep the inline object-literal form for small internal shapes with nothing to say about each field, and prefer `unknown` over `*`:
+
+```js
+/** @typedef {{ key: string, value: unknown }} KVEntry */
+```
+
+Public (exposed) methods must carry JSDoc types — parameters and return value — with one `@overload` block per accepted call form, since those overloads *are* the published signature. Unexposed/private helpers are typed at the contributor's discretion: annotate where it helps the next reader, and either way keep them clean. Members tagged `@internal` are stripped from the generated declarations, so use that tag rather than `@private` to keep something off the public surface.
+
+Typing in JS files is encouraged: annotate with JSDoc `@type`/`@param`/`@returns` using the TypeScript type system, and define shared shapes with `@typedef`. API types must not be `unknown` or untyped `...args` — spell out the real parameter and return shapes; the only exception is values passed through transparently to an upstream layer that owns their type. For example:
+
+```js
+/**
+ * @typedef {{key:string, value: unknown}} KVEntry
+ */
+
+/** @type {KVEntry[]} */
+let entries = [];
+```
+
+Every SDK change carries all five of the following — a puter.js PR missing one is incomplete:
+
+1. **Backward compatibility.** Mandatory unless a maintainer explicitly signs off on a break. Existing call signatures keep working (including both positional and options-object forms where a method supports them); new parameters are optional with defaults that preserve old behavior; never rename or repurpose existing params, response fields, or error codes. New parameter names are `camelCase` (existing `snake_case` stays for compatibility). Say in the PR how existing callers are unaffected.
+2. **Tests.** Add or extend a suite in [tests/api/suites/](src/puter-js/tests/api/suites/) (`<area>.suite.ts`; register new suites in `suites/index.ts` — no globbing). One suite runs unchanged on node, browser, and workerd via `npm run test:puterjs`; never write a per-platform test. The runners execute the **built** bundle — run `npm run build:workerLib` after SDK changes or the suite silently tests stale code. For `puter.ui.*` methods rendered by the desktop, use the Playwright e2e harness instead — see [src/puter-js/TESTING.md](src/puter-js/TESTING.md).
+3. **Docs.** New or changed APIs update [src/docs/src/](src/docs/src/): the method page (`<Area>/<method>.md`, with frontmatter and a runnable example) and the area overview when the surface changes. Docs are the contract users code against — signatures, defaults, and return shapes must match the implementation exactly.
+4. **Types.** Type the change in JSDoc on the implementation, then run `npm run check:puterjs:types` to confirm it still produces declarations that type-check. Name any new type in [src/puter-js/index.d.ts](src/puter-js/index.d.ts) if consumers should be able to import it. Declarations must match runtime behavior exactly — a wrong type is worse than a missing one.
+5. **Error handling.** Reject/throw `{ message, code }` objects with stable `snake_case` codes, matching the existing modules (see `KV.js`). Validate cheap preconditions client-side before making the network call; pass backend errors through unchanged rather than swallowing or re-wrapping them. Error codes are API surface — changing one is a breaking change.
+
+[doc/contributing-apis.md](doc/contributing-apis.md) walks the full lifecycle of adding an API across backend + SDK.
+
+---
+
+## GUI
+
+[src/gui/](src/gui/) is the Puter desktop: deliberately plain JavaScript + jQuery with HTML-string templates. Don't introduce a UI framework or a new rendering pattern.
+
+The guiding rule here is **conformity over novelty** — match the existing design and code structure even where you'd personally choose differently. A visually or structurally divergent addition is a defect even when it works.
+
+- **Reuse existing UI primitives before writing new ones.** Windows and dialogs are `UIWindow*` functions in [src/gui/src/UI/](src/gui/src/UI/); generic pieces already exist (`UIAlert`, `UIPrompt`, `UIContextMenu`, `UINotification`, `UIPopover`, widgets in [UI/Components/](src/gui/src/UI/Components/)). A new window should read like its neighbors: an async function taking an options object, composing an HTML string, wiring behavior with jQuery, delegating to `UIWindow(...)`.
+- **Match the visual language.** Use existing CSS classes (`button`, `button-primary`, window chrome, form styles) and copy the layout patterns of neighboring windows; new styles go in [src/gui/src/css/](src/gui/src/css/) following existing conventions. Verify anything positional (menus, overlays, z-index) on both desktop and mobile viewports.
+- **i18n every user-facing string.** No hardcoded UI text — use `i18n('key')` and add the key to [src/gui/src/i18n/translations/en.js](src/gui/src/i18n/translations/en.js). Run `npm run check-translations` before opening the PR.
+- **Shared logic goes in helpers/services.** Reusable non-UI logic belongs in [src/gui/src/helpers/](src/gui/src/helpers/) or [src/gui/src/services/](src/gui/src/services/), not copy-pasted between windows.
+- **Tests.** Vitest is wired for the GUI (`src/**/*.test.js`; see [appOrder.test.js](src/gui/src/UI/Dashboard/appOrder.test.js) for the shape). Extract pure logic into functions and test those. Desktop behavior driven through puter.js (`puter.ui.*`) is covered by the Playwright harness in [src/puter-js/tests/e2e/](src/puter-js/tests/e2e/) — add a spec there when you change how the desktop renders SDK-driven UI.

CONTRIBUTING.md

@@ -16,6 +16,8 @@ Add tests for new behavior, endpoints, or bug fixes. If something's genuinely ha
 
 Match the shape of similar code already in the repo. [doc/architecture.md](doc/architecture.md) is the source of truth for layers, wiring, and naming. If you think a pattern is wrong, raise it — don't quietly diverge.
 
+In plain-JS files, typing is encouraged via JSDoc `@type` annotations using the TypeScript type system, with `@typedef` for shared shapes. Don't type API surfaces as `unknown` or untyped `...args` unless the values are passed through transparently to an upstream layer that owns their type.
+
 ## 3. Don't expose system or user information
 
 Scan your diff for stray logs, debug routes, internal paths, secrets, tokens, or user data in errors/responses. When in doubt, return less. Flag any auth, permission, or data-export changes in the PR description.
@@ -26,9 +28,9 @@ For private security reports, see [SECURITY.md](SECURITY.md).
 
 Don't commit code you couldn't have written, debugged, or defended yourself. Read the diff, run it, and be ready to explain it in review.
 
-## 5. Update docs for API changes
+## 5. Adding or changing APIs
 
-If you change puter-js APIs (drivers or endpoints used by puter-js), update [developer docs](src/docs/). puter-js itself may also need updating.
+If you add or change a public API (an endpoint, driver method, or puter-js method), follow [doc/contributing-apis.md](doc/contributing-apis.md) — backward compatibility, [developer docs](src/docs/), types, and tests all move in the same PR.
 
 ## 6. Boy Scout Rule — leave it 1% better
 

caddy/Caddyfile

@@ -0,0 +1,73 @@
+# Reverse proxy in front of Puter — mirrors what the prod ALB does:
+# accepts every Host header, forwards to the Puter container, and lets
+# the Puter app handle subdomain-based routing internally (api.*,
+# site.*, app.*, dev.*, plus the per-user subdomains under those).
+#
+# To enable TLS:
+#   1. Drop a wildcard fullchain.pem + privkey.pem into ./puter/tls/
+#      (see "Step 3 — TLS" in doc/self-hosting.md).
+#   2. Uncomment the `:443` block at the bottom of this file, and swap the
+#      `:80` block for the redirect shown alongside it.
+#   3. Uncomment the `443:443` port mapping under the `caddy` service in
+#      docker-compose.yml, and HTTPS_PORT in .env.
+#   4. Set `"protocol": "https"` and `"pub_port": 443` in config.json.
+{
+	# Certs are supplied by the operator, not issued by Caddy. Puter serves
+	# per-user sites and apps on dynamic subdomains (<name>.site.<domain>,
+	# <name>.app.<domain>) — only a DNS-01 wildcard cert covers those, and
+	# DNS-01 needs a provider plugin that isn't in the stock caddy image.
+	# `off` stops Caddy attempting ACME on boot (it would fail and leave the
+	# site unreachable) and stops it inventing its own http→https redirects.
+	auto_https off
+}
+
+# Shared handling, imported by the HTTP and HTTPS site blocks below so the
+# two can't drift apart.
+(puter_routes) {
+	# Rough size cap that mirrors prod ALB defaults; tune for your uploads.
+	# Puter chunks large uploads, so 1 GiB per request is plenty.
+	request_body {
+		max_size 1024MiB
+	}
+
+	# RustFS — see the `s3` service in docker-compose.yml. Browsers PUT/GET
+	# here for presigned-URL uploads / downloads. Matched on the `s3.`
+	# subdomain of whatever the install domain is, so signature verification
+	# works (Caddy preserves the original Host end-to-end) and HTTPS stays
+	# clean — no mixed content from a port-9000 host publish.
+	@s3 header_regexp Host ^s3\.
+	handle @s3 {
+		reverse_proxy s3:9000
+	}
+
+	# Everything else, on every Host, goes to Puter — which routes on that
+	# Host internally. Caddy forwards it unchanged and adds X-Forwarded-For
+	# / -Proto / -Host, which is what `trust_proxy` in config.json counts.
+	handle {
+		reverse_proxy puter:4100 {
+			# Stream responses through unbuffered — Puter uses SSE and
+			# socket.io. WebSocket upgrades need no config of their own;
+			# Caddy proxies them by default.
+			flush_interval -1
+		}
+	}
+}
+
+# ── HTTP (port 80) ─────────────────────────────────────────────────────
+# A site address with no hostname is the catch-all: it answers for every
+# Host, which is what Puter's subdomain routing requires.
+:80 {
+	import puter_routes
+}
+
+# ── HTTPS (port 443) — uncomment after dropping certs in ./puter/tls/ ──
+# Replace the `:80` block above with a redirect to force HTTPS everywhere:
+#
+# :80 {
+# 	redir https://{host}{uri} permanent
+# }
+#
+# :443 {
+# 	tls /etc/caddy/tls/fullchain.pem /etc/caddy/tls/privkey.pem
+# 	import puter_routes
+# }

config.default.json

@@ -5,9 +5,7 @@
     "protocol": "http",
     "domain": "puter.localhost",
     "cookie_name": "puter_auth_token",
-    "jwt_secret": "dev-jwt-secret-change-me",
     "jwt_secret_v2": "dev-jwt-secret-v2-change-me",
-    "allow_v1_tokens": true,
     "url_signature_secret": "dev-url-signature-secret-change-me",
     "allow_all_host_values": true,
     "allow_no_host_header": true,

config.template.jsonc

@@ -73,11 +73,7 @@
 
     // ── Auth / session ──────────────────────────────────────────────────
     // ALWAYS replace these for any public install — `openssl rand -hex 64`.
-    // `jwt_secret` is legacy verify-only; new tokens sign with `jwt_secret_v2`.
-    "jwt_secret": "change-me",
     "jwt_secret_v2": "change-me",
-    // Set false to retire v1 tokens entirely (ROLLOUT-1).
-    "allow_v1_tokens": true,
     "url_signature_secret": "change-me",
     "cookie_name": "puter_auth_token",
     "min_pass_length": 6,
@@ -255,6 +251,60 @@
         }
     },
 
+    // ── Alarms / alerting ───────────────────────────────────────────────
+    // Where system alarms go. Severity is the routing decision — each
+    // transport takes everything at or above its own `minSeverity`:
+    //
+    //   critical — an unhandled server error; pages on-call.
+    //   error    — pages as well; prefer critical or warning.
+    //   warning  — look at it today; no page.
+    //   info     — a record in the chat channel only.
+    //
+    // Both transports are off unless enabled, so a self-hosted node just
+    // logs its alarms to the console.
+    "pager": {
+        // Severity for call sites that don't pick one. Default "critical".
+        "defaultSeverity": "critical",
+
+        // Retier or silence an alarm without a deploy. Keys are alarm ids,
+        // or a prefix ending in `*`; the exact id wins over a pattern, and
+        // the longest matching pattern wins among patterns. Values are a
+        // severity or "mute". This is applied last, so it overrides both the
+        // call site and any known-error rule.
+        "severityOverrides": {
+            // "cronMonitor:*": "info",
+            // "http_500:GET:/some/flapping/route:*": "mute"
+        },
+
+        "pagerduty": {
+            "enabled": false,
+            "routingKey": "",
+            // Lowest severity that reaches PagerDuty. Default "warning",
+            // which keeps `info` out of the paging system entirely.
+            "minSeverity": "warning"
+        },
+
+        // Slack incoming webhook — the low-noise destination for everything
+        // that shouldn't page.
+        "slack": {
+            "enabled": false,
+            "webhookUrl": "",
+            // Optional; defaults to the channel the webhook was created for.
+            "channel": "#alerts",
+            "username": "puter-alarms",
+            // Severity window posted to Slack. The ceiling defaults to
+            // "info" when PagerDuty is configured — what pages belongs in
+            // the pager, not in chat — and to "critical" when Slack is the
+            // only transport.
+            "minSeverity": "info",
+            "maxSeverity": "info",
+            // Don't repost the same alarm id within this window. The first
+            // occurrence always posts; the next post that gets through
+            // reports how many occurrences piled up. 0 disables throttling.
+            "repeatThrottleMs": 900000
+        }
+    },
+
     // ── Rate limiting ───────────────────────────────────────────────────
     // `memory` for single-node, `redis` for multi-node (default), `kv` for
     // dynamo-backed counters.
@@ -287,6 +337,10 @@
             "apiKey": "",
             "apiBaseUrl": "https://openrouter.ai/api/v1"
         },
+        "infron": {
+            "apiKey": "",
+            "apiBaseUrl": "https://llm.onerouter.pro/v1"
+        },
         "together-ai": { "apiKey": "" },
         // Local Ollama. `enabled: false` skips the auto-probe at startup
         // (otherwise Puter logs ECONNREFUSED on every boot when no Ollama
@@ -325,6 +379,7 @@
             "secret_key": "",
             "region": "us-west-2"
         },
+        "speechify": { "apiKey": "" },
         "aws-textract": {
             "access_key": "",
             "secret_key": "",
@@ -382,6 +437,24 @@
     ],
 
     // ── Metering ────────────────────────────────────────────────────────
-    // When true, all metering checks pass — no per-actor limits enforced.
-    "unlimitedMetering": false
+    // When true, every account resolves to an unlimited policy: usage is still
+    // recorded, but nothing is ever refused for lack of budget. This is the
+    // setting for a deployment with no way to buy more — without it, accounts
+    // are held to the free monthly allowance and start getting 402s from the AI
+    // surfaces, file transfers and KV once they pass it.
+    "unlimitedMetering": false,
+
+    // Whether an account that has spent its whole allowance is refused the
+    // operations that spend it — file transfers, KV calls. Recording is
+    // unaffected either way. `workers` extends the same refusal to
+    // worker-driven calls, which are exempt by default because a deployed
+    // worker has nowhere to surface a payment prompt.
+    // "meteringEnforcement": { "enabled": true, "workers": false },
+
+    // Fleet-wide spend rate, in micro-cents per minute, past which metering
+    // raises the `metering:excessiveGlobalUsageRate` alarm. Omit it (the
+    // default) to leave the check off: the only useful value is a multiple of
+    // what this deployment's normal traffic costs, so it has to be measured
+    // rather than guessed, and a stale number here alarms on healthy growth.
+    // "maxGlobalUsagePerMinute": 200000000
 }

doc/alarms.md

@@ -0,0 +1,119 @@
+# Alarms
+
+`clients.alarm` is the one way code reports that something is wrong. It
+de-dupes by alarm id, counts occurrences, and routes each alarm to alert
+transports by **severity**.
+
+```ts
+this.clients.alarm.create(
+    `metering_write_failed:${userUuid}`, // de-dupe key
+    'Metering write failed', // what a human reads
+    { userUuid, appId, error }, // context fields
+    'info', // severity
+);
+```
+
+## Severity is the routing decision
+
+| Severity   | Meaning                                                | Goes to     |
+| ---------- | ------------------------------------------------------ | ----------- |
+| `critical` | An unhandled server error. Someone gets woken up.      | Pager       |
+| `error`    | Same urgency as critical; prefer one of the other two. | Pager       |
+| `warning`  | Worth a look today. Nobody is paged.                   | Pager (low) |
+| `info`     | A record of something expected-but-notable.            | Chat        |
+
+Each transport declares the severity window it accepts, so the value a call
+site passes is what decides where the alarm lands. The two windows don't
+overlap by default: anything that pages lives in the paging system, and chat
+is the record of what didn't. The bar for `critical` is
+deliberately high: an unhandled 5xx out of the HTTP error handler is the main
+thing that still pages. Anything a human can look at tomorrow is `warning`,
+and anything that's just worth recording is `info`.
+
+Omitting the severity takes `pager.defaultSeverity` (itself `critical`), so
+pass one explicitly unless you really mean "page someone".
+
+### Choosing one
+
+- Did the server fail to do its job in a way nobody expected? → `critical`
+- Is a background job, rate, or dependency degraded? → `warning`
+- Is this a user doing something notable (tripping an abuse heuristic,
+  overspending)? → `info`
+- Did one of *our own* limits reject a caller — a rate limit, a concurrency
+  cap, a quota? → don't alarm at all. The limit doing its job is not an
+  event; the 429 is the whole signal, and alarming on it only produces noise
+  proportional to traffic. An *upstream provider* rate-limiting us is the
+  opposite case and still alarms (`upstream_rate_limited`, `info`) — that one
+  is not something we chose.
+
+An extension whose signals are all one tier can default its own local
+`raiseAlarm` helper to that tier instead of repeating it at every call site —
+see [extensions/cronMonitor](../../../extensions/cronMonitor/index.js).
+
+## One incident per occurrence, unless you say otherwise
+
+Alarms always de-dupe *in process* — repeats of an id bump its occurrence
+count rather than creating a second alarm. What that means for the pager is a
+separate decision, and by default every occurrence opens its own PagerDuty
+incident: two failed scans an hour apart are two things that happened, and
+closing one shouldn't hide the other.
+
+Pass `{ dedup: true }` as a fifth argument when repeats of the id really are
+one recurring fault, and they collapse onto a single incident carrying the
+occurrence count:
+
+```ts
+this.clients.alarm.create(alarmId, message, fields, 'critical', {
+    dedup: true,
+});
+```
+
+The HTTP error handler uses it: its id is route + error signature, so a hot
+loop of the same crash is one incident with N occurrences instead of N pages.
+Reach for it anywhere else only when the id is that specific — otherwise a
+per-request alarm can flood the pager.
+
+## Configuration
+
+Everything lives under `pager` in config (see
+[config.template.jsonc](../config.template.jsonc) for the annotated version).
+Both transports are off unless enabled, so a self-hosted node just logs
+alarms to the console.
+
+```jsonc
+"pager": {
+    "defaultSeverity": "critical",
+    "severityOverrides": { "cronMonitor:*": "info" },
+    "pagerduty": { "enabled": true, "routingKey": "…", "minSeverity": "warning" },
+    "slack": {
+        "enabled": true,
+        "webhookUrl": "…",
+        "channel": "#alerts",
+        "minSeverity": "info",
+        "maxSeverity": "info",
+        "repeatThrottleMs": 900000,
+    },
+}
+```
+
+Slack's `maxSeverity` defaults to `info` whenever PagerDuty is configured, and
+to `critical` when it isn't — a node with only a webhook still sees
+everything. Raise it to have chat mirror the paging tiers as well.
+
+### Retiering without a deploy
+
+`severityOverrides` is the escape hatch for an alarm that turns out to be
+noisier or more serious than its call site assumed. Keys are alarm ids or a
+prefix ending in `*`; the exact id beats a pattern, and the longest matching
+prefix wins among patterns. Values are a severity, or `mute` to drop the
+alarm before any transport sees it.
+
+It is applied *after* the call site's severity and any known-error rule, so
+config always has the last word.
+
+### Repeat throttling
+
+The chat transport won't repost the same alarm id within
+`repeatThrottleMs` (default 15 minutes). The first occurrence always posts,
+and the next one that gets through reports how many piled up in between —
+so a hot loop reads as one message with a count, not a wall of them.

doc/contributing-apis.md

@@ -0,0 +1,112 @@
+# Contributing APIs
+
+How to add a new public API to Puter, and how to maintain one that already exists. "Public API" means anything applications can call: HTTP endpoints, `/drivers/*` methods, and the puter.js methods that wrap them. This guide is written for human contributors and AI agents alike — [AGENTS.md](../AGENTS.md) defers to it for API work.
+
+Companion docs: [architecture.md](architecture.md) (backend layering), [pagination.md](pagination.md) (list APIs), [src/puter-js/tests/api/README.md](../src/puter-js/tests/api/README.md) (SDK test environment).
+
+## Rule zero: don't break callers
+
+puter.js is served live from `https://js.puter.com/v2/` with no version pinning — every app in existence picks up your change the moment it deploys, and the backend endpoints underneath have the same property. Assume every observable behavior (parameter handling, response fields, error codes, ordering) has someone depending on it.
+
+Every change is backward compatible unless a maintainer has explicitly agreed to a break beforehand.
+
+## Core or extension?
+
+The first decision is where the API lives.
+
+If the API is **not crucial to core functionality — nothing in core will call it — prefer an extension** over wiring it into core. Extensions live in [extensions/](../extensions/), parallel the core layered stack, and reach core through `extension.import(...)`:
+
+```js
+const services = extension.import('service');
+const stores = extension.import('store');
+
+extension.registerDriver('myFeature', MyFeatureDriver);  // first-class driver
+extension.post('/my-feature/frobnicate', opts, handler); // or plain routes
+```
+
+Follow the same layered structure inside the extension (driver/controller → service → store) unless it genuinely only needs a couple of route handlers — then the lightweight `extension.get/post/...` helpers are enough on their own.
+
+The test is the direction of dependency: Puter must still work with the extension removed. The moment core needs to call your API, it belongs in core — see [whoami](../extensions/whoami.ts) for the cautionary example of a load-bearing "extension".
+
+## Adding a new API
+
+Work through all seven steps; the PR is complete when every one is.
+
+### 1. Design the surface first
+
+- Sketch the signature, options, return shape, and error cases before writing code. Find the two or three most similar existing APIs and match their conventions.
+- New parameter and field names are `camelCase`. (Existing `snake_case` names stay where they already exist.)
+- Anything returning a list follows the [pagination convention](pagination.md): `limit`/`cursor` in, `{ items, cursor, total }` envelope out.
+- Prefer an options object over a growing list of positional parameters, but keep the common case callable with a single argument where siblings do.
+
+### 2. Backend
+
+Follow the layered stack ([architecture.md](architecture.md)): a controller or driver at the edge, business logic in a service, persistence in a store. The edge parses and validates input and applies gates; services assume the caller is already authorized. Return exactly what the caller needs and no more — every response field you ship is permanent — and use stable `snake_case` error codes.
+
+#### Controller or driver?
+
+Both are supported ways to define an API. **Prefer a controller when you need fine-grained control** — URL shape, HTTP verbs, per-route gates, response and streaming formats. A **driver** fits when the API is a set of RPC methods implementing one of the named interfaces on `/drivers/*` (`puter-kvstore`, `puter-chat-completion`, …) and the generic driver plumbing — one call envelope, interchangeable implementations, per-method policies — covers what you need.
+
+- **Controller:** extend `PuterController` ([src/backend/controllers/types.ts](../src/backend/controllers/types.ts)) and declare routes with the `@Controller(prefix)` class decorator plus `@Get`/`@Post`/… method decorators ([src/backend/core/http/decorators.ts](../src/backend/core/http/decorators.ts)), each taking `(path, routeOptions)` — or override `registerRoutes(router)` imperatively. Core controllers register in [src/backend/controllers/index.ts](../src/backend/controllers/index.ts); extensions use `extension.registerController(...)` or the plain route helpers.
+- **Driver:** extend `PuterDriver` ([src/backend/drivers/types.ts](../src/backend/drivers/types.ts)) and mark it with the `@Driver(interfaceName, opts)` decorator ([src/backend/drivers/decorators.ts](../src/backend/drivers/decorators.ts)), which also declares its policies. Core drivers register in [src/backend/drivers/index.ts](../src/backend/drivers/index.ts); extensions use `extension.registerDriver(...)`.
+
+#### Middleware and gates
+
+- **Controller routes** (and extension routes — same options) take [`RouteOptions`](../src/backend/core/http/types.ts): auth gates (`requireAuth`, `requireUserActor`, `noUserSession`, `adminOnly`, `allowedAppIds`, and the access-token controls), `subdomain` routing, per-route `rateLimit`, body parsers, and arbitrary extra `middleware`. The auth flavors are subtle and default-deny — read the JSDoc on each field before picking.
+- **Driver methods** get their policies from the `@Driver` options: per-method `rateLimit` (limit/window/backend), `concurrent` in-flight caps (optionally `bySubscription`), and `noUserSession`. The `/drivers/call` surface enforces them.
+- **An endpoint that spends metered resources** on the caller's behalf — moving file content, making object-store requests, anything else the account is billed for — also declares `requireCredits: true`, which turns an account with nothing left of its budget away with a 402 before the handler runs. Endpoints that only describe or delete things deliberately don't: an account that has run out still has to be able to see what it has, clear it, and reach its billing pages. Drivers have no route options to declare this on, so they call `assertActorHasCredits` themselves ([src/backend/services/metering/enforcement.ts](../src/backend/services/metering/enforcement.ts)) — see `KVStoreDriver`, which does it once for every method.
+
+### 3. puter.js
+
+- Add the method to the matching module in [src/puter-js/src/modules/](../src/puter-js/src/modules/), matching the calling conventions of its siblings (promise-returning; positional shortcut plus options form where that's the local pattern).
+- Validate cheap preconditions client-side and throw `{ message, code }` objects; pass backend errors through unchanged rather than swallowing or re-wrapping them.
+
+### 4. Types
+
+- Type the method where you wrote it, in JSDoc: `@param`/`@returns` on the implementation, one `@overload` block per accepted call form, and `@typedef {Object}` + `@property` for any new shape. The JSDoc is the source of truth — declarations are generated from it, so there is nothing to keep in sync by hand.
+- Put a shape more than one file needs in the module's `types.js` (e.g. [src/puter-js/src/modules/kv/types.js](../src/puter-js/src/modules/kv/types.js)); anything shared across modules goes in [src/puter-js/src/lib/types.js](../src/puter-js/src/lib/types.js). A shape with one consumer can stay next to it.
+- Run `npm run check:puterjs:types` — it generates the declarations and type-checks the published surface without `skipLibCheck`. **Never edit anything under `src/puter-js/types/`**: it is gitignored build output, produced by the SDK build and shipped in the npm tarball, and the next build overwrites it.
+- Name the new type in [src/puter-js/index.d.ts](../src/puter-js/index.d.ts) if consumers should be able to import it. That file is the one hand-written declaration in the package: it decides what is public and re-exports nothing else.
+
+### 5. Docs
+
+- Add the method page at [src/docs/src/](../src/docs/src/)`<Area>/<method>.md` — frontmatter (`title`, `description`, `platforms`), syntax, parameters, return value, and at least one runnable example — and update the area overview (`<Area>.md`). Copy the structure of an existing page.
+
+### 6. Tests
+
+- **Backend:** colocated Vitest tests; prefer the in-memory test server (`setupPuterTestEnv` in [src/backend/testUtil.ts](../src/backend/testUtil.ts)) over mocking.
+- **SDK:** add cases to [src/puter-js/tests/api/suites/](../src/puter-js/tests/api/suites/)`<area>.suite.ts` (register new suites in `suites/index.ts`). One suite runs on node, browser, and workerd via `npm run test:puterjs` — never write per-platform tests, and rebuild first with `npm run build:workerLib` since the runners execute the built bundle.
+- **Desktop-rendered UI** (`puter.ui.*`): add a Playwright spec per [src/puter-js/TESTING.md](../src/puter-js/TESTING.md).
+
+### 7. Security pass
+
+Scan the diff before opening the PR: no internals leaked in errors or logs, no over-broad responses, auth gates present. Flag anything auth-, permission-, or data-export-related in the PR description.
+
+## Maintaining an existing API
+
+Changes are **additive by default**:
+
+- New parameters are optional, with defaults that reproduce the old behavior exactly.
+- Never rename, repurpose, or remove existing parameters, response fields, or error codes. Don't change types, ordering guarantees, or which fields are present when.
+- New behavior that could surprise existing callers goes behind an opt-in flag.
+- Docs, types, and tests move in the same PR as the behavior. A signature change with stale docs is a bug — the docs are the contract users code against.
+- Bug fixes come with a regression test that fails before the fix. Be suspicious of fixes that change observable behavior: someone may depend on the bug. When in doubt, ask a maintainer.
+
+### Breaking changes
+
+Rare and deliberate. In order: explicit maintainer sign-off, a documented migration path, and a rollout plan — typically new surface added first, old surface deprecated, old surface removed much later, if ever. Never break as a side effect of a refactor.
+
+### Deprecating
+
+The old surface keeps working. Mark it `@deprecated` in the type declarations, note the replacement on its docs page, and stop using it in examples. Removal is a separate, maintainer-approved decision.
+
+## Definition of done
+
+- [ ] Backward compatible (or the break was explicitly approved)
+- [ ] Right home: extension if core never calls it; layered structure either way
+- [ ] puter.js method matches sibling conventions; errors are `{ message, code }` with stable codes
+- [ ] Types updated and matching runtime behavior
+- [ ] Docs page + area overview updated, with a runnable example
+- [ ] Tests: backend + three-platform SDK suite (+ e2e for desktop-rendered UI)
+- [ ] Security pass on the diff
+- [ ] You ran it end to end

doc/pagination.md

@@ -0,0 +1,100 @@
+# Pagination convention for list APIs
+
+Every list endpoint follows one wire contract. This document is the source of
+truth for adding pagination to a new or existing list surface.
+
+## Wire contract
+
+Requests accept:
+
+| Param | Type | Meaning |
+| --- | --- | --- |
+| `limit` | number | Maximum items per page. Each endpoint documents its cap and default. |
+| `cursor` | string \| null | Opaque continuation token. `null` (or any presence of the key) requests the first page. |
+| `offset` | number | Skip N items. Legacy/discouraged — see below. Cannot be combined with `cursor`. |
+| `includeTotal` | boolean | Adds `total` to the response. |
+
+Paginated responses are an envelope:
+
+```json
+{ "items": [...], "cursor": "…", "total": 123 }
+```
+
+- `cursor` is present only while more pages exist. Clients iterate until it
+  is absent.
+- `total` is present only when the request set `includeTotal`.
+- **Pages may be short.** Post-query filtering (TTL expiry, permission
+  checks) can shrink a page below `limit` — or even to zero — while a
+  `cursor` is still returned. Never use `items.length < limit` as an
+  end-of-list signal.
+
+New request params are camelCase (`includeTotal`, `fetchUntilFull`).
+Pre-existing snake_case params stay for compatibility.
+
+## Backward compatibility
+
+Requests without pagination params keep returning the full result in the
+legacy shape (bare array) forever — old clients never break.
+
+The envelope trigger depends on the endpoint's history:
+
+- Endpoints where `limit` pre-dates the convention (readdir, subdomain
+  `select`) return the envelope only when the request contains `cursor`
+  (including `null`) or `includeTotal`; `limit`/`offset`-only requests keep
+  the bare array.
+- Endpoints where every pagination param is new (kv `list`, workers
+  `getFilePaths`) return the envelope when any pagination param is present.
+
+## Cursors
+
+Cursors are opaque base64-encoded JSON, produced and consumed only by the
+backend (`src/backend/util/pagination.ts`). What a cursor wraps is an
+implementation detail per store:
+
+- DynamoDB-backed lists wrap `LastEvaluatedKey`.
+- SQL-backed lists wrap a keyset position — `(sortValue, id)` of the last
+  row — and the query seeks past it (`WHERE (col, id) > (?, ?) ORDER BY col,
+  id`). Any SQL list gaining a cursor must have a deterministic `ORDER BY`
+  ending in a unique tiebreaker (`id`).
+
+Cursors that carry a sort also pin it: a request that passes a cursor plus a
+conflicting sort is rejected with 400.
+
+## Offset
+
+SQL-backed endpoints support `offset` natively. DynamoDB-backed endpoints
+(kv) emulate it by advancing past skipped items with `Select: COUNT` queries
+— no item data is transferred, but read capacity is still consumed for
+everything skipped, and the caller is metered for it. **Offset is supported
+for parity, not recommended** — cost grows linearly with the offset, so it is
+capped (kv: 5000). Use cursors.
+
+## Totals (`includeTotal`)
+
+- SQL: `SELECT COUNT(*)` with the same WHERE clause as the listing.
+- DynamoDB: a `Select: COUNT` loop over the query (TTL-filtered), metered to
+  the caller. Cost is proportional to the total item count — request the
+  total on the first page only, not every page.
+- Where visibility is decided per-actor after the query (protected apps in
+  the catalog listing), `total` approximates the visible set: it counts
+  non-protected plus caller-owned rows, and misses rows visible only through
+  explicit permission grants.
+
+## fetchUntilFull (kv only)
+
+DynamoDB applies `Limit` before its filter expression, so TTL-filtered pages
+are structurally short. `fetchUntilFull: true` makes the backend keep
+fetching (bounded number of continuation queries) until the page holds
+`limit` items or the keyset is exhausted. Requires `limit`. If the bound is
+hit, the response simply carries a cursor — still convention-legal.
+
+## Adding pagination to a new endpoint
+
+1. Use `encodeCursor`/`decodeCursor`/`normalizeLimit`/`normalizeOffset` from
+   `src/backend/util/pagination.ts`.
+2. Push equality filters into the query so pages and counts operate on the
+   true result set; only genuinely per-actor filtering may remain post-query
+   (short-pages rule covers it).
+3. Fetch `limit + 1` rows to detect whether a next page exists (SQL), or use
+   `LastEvaluatedKey` (DynamoDB).
+4. Keep the no-params request returning the legacy full result.

doc/self-hosting.md

@@ -1,6 +1,6 @@
 # Self-Hosting Puter
 
-`docker-compose.yml` brings up Puter **plus every external service it needs** — MariaDB, Valkey, DynamoDB-local, RustFS S3, nginx — wired together. Closest thing to a production deployment you can self-manage on a single host.
+`docker-compose.yml` brings up Puter **plus every external service it needs** — MariaDB, Valkey, DynamoDB-local, RustFS S3, Caddy — wired together. Closest thing to a production deployment you can self-manage on a single host.
 
 ## One-line installer (recommended)
 
@@ -8,7 +8,7 @@
 curl -fsSL https://raw.githubusercontent.com/HeyPuter/puter/main/install.sh | sh
 ```
 
-Generates secrets, writes `.env` + `puter/config/config.json`, downloads `docker-compose.yml` from the OSS repo, and runs `docker compose up -d`. Re-running is safe — it won't overwrite existing config (set `PUTER_FORCE=1` to rotate). Use the manual steps below if you want to inspect or tweak each step yourself.
+Generates secrets, writes `.env` + `puter/config/config.json`, downloads `docker-compose.yml` + `caddy/Caddyfile` from the OSS repo, and runs `docker compose up -d`. Re-running is safe — it won't overwrite existing config (set `PUTER_FORCE=1` to rotate). Use the manual steps below if you want to inspect or tweak each step yourself.
 
 ## Requirements
 
@@ -20,7 +20,7 @@ Generates secrets, writes `.env` + `puter/config/config.json`, downloads `docker
 
 | Container       | Image                    | Role                                                       |
 | --------------- | ------------------------ | ---------------------------------------------------------- |
-| `puter-nginx`   | `nginx:1.27-alpine`      | Reverse proxy on 80 (and 443 if TLS); forwards to Puter    |
+| `puter-caddy`   | `caddy:2.11-alpine`      | Reverse proxy on 80 (and 443 if TLS); forwards to Puter    |
 | `puter`         | `ghcr.io/heyputer/puter` | The app                                                    |
 | `puter-mariadb` | `mariadb:11`             | SQL database — schema applied automatically on first boot  |
 | `puter-valkey`  | `valkey/valkey:8-alpine` | Redis-compatible cache + rate-limiter                      |
@@ -47,7 +47,6 @@ State lives under `./puter/data/<service>/`.
 MARIADB_ROOT_PASSWORD=$(openssl rand -hex 32)
 MARIADB_PASSWORD=$(openssl rand -hex 32)
 S3_SECRET_KEY=$(openssl rand -hex 32)
-JWT_SECRET=$(openssl rand -hex 64)
 JWT_SECRET_V2=$(openssl rand -hex 64)
 URL_SIGNATURE_SECRET=$(openssl rand -hex 64)
 
@@ -65,7 +64,7 @@ S3_SECRET_KEY=$S3_SECRET_KEY
 S3_BUCKET=puter-local
 EOF
 
-mkdir -p puter/config puter/data puter/tls
+mkdir -p puter/config puter/data puter/data/caddy puter/tls
 cat > puter/config/config.json <<EOF
 {
     "domain": "puter.localhost",
@@ -78,9 +77,7 @@ cat > puter/config/config.json <<EOF
     "private_app_hosting_domain": "app.puter.localhost",
     "private_app_hosting_domain_alt": "dev.puter.localhost",
 
-    "jwt_secret": "$JWT_SECRET",
     "jwt_secret_v2": "$JWT_SECRET_V2",
-    "allow_v1_tokens": true,
     "url_signature_secret": "$URL_SIGNATURE_SECRET",
 
     "database": {
@@ -134,21 +131,21 @@ Replace `puter.localhost`, `site.puter.localhost`, `host.puter.localhost`, `dev.
 
 Why these knobs:
 
-- `jwt_secret` + `jwt_secret_v2` — Puter signs new auth tokens with `jwt_secret_v2` (v2 token format, `kid: 'v2'` JWT header). `jwt_secret` is verify-only and lets tokens minted before this version (cookies still in users' browsers, stored API tokens) keep working. `allow_v1_tokens: true` keeps that fallback enabled. Fresh installs can leave it as-is; future versions will flip the flag to `false` and retire `jwt_secret` entirely once legacy tokens have drained.
+- `jwt_secret_v2` — the HMAC secret Puter signs and verifies auth tokens with (`kid: 'v2'` JWT header). The pre-v2 token format is retired: a token signed with the old `jwt_secret` no longer verifies, and holders are asked to sign in again. If you are upgrading from a release that had `jwt_secret`, drop it from your config — it is ignored.
 - `env: "prod"` — the bundled `config.default.json` ships with `env: "dev"` (matches the source-tree `npm run start:gui` workflow, which expects webpack-dev-server emitting a CSS manifest). Self-host runs against pre-built static bundles, so `env: "prod"` makes the homepage emit the `/dist/bundle.min.css` `<link>` tag instead of waiting on a manifest that doesn't exist.
 - `database.migrationPaths` — Puter applies the bundled MySQL/MariaDB schema on boot. The migration files are idempotent, so it is safe to leave this configured across restarts.
 - `dynamo.bootstrapTables: true` — Puter creates its KV table on boot. **Only set against a local emulator**, never real AWS.
 - `dynamo.aws` keys are dummies; DynamoDB-local doesn't validate them but the AWS SDK requires _something_. **Note:** DynamoDB uses `access_key` / `secret_key` (snake_case); S3 below uses `accessKeyId` / `secretAccessKey` (camelCase). Not interchangeable.
 - `providers.ollama.enabled: false` — Puter auto-probes a local Ollama at `127.0.0.1:11434` by default; without one running you'd see `ECONNREFUSED` on every boot. To run a bundled Ollama, see [Optional: local LLM (Ollama)](#optional-local-llm-ollama) below.
 - `s3.s3Config.forcePathStyle: true` — RustFS / MinIO / fauxqs need path-style URLs (`<endpoint>/<bucket>`). Real AWS S3 wants virtual-hosted (`<bucket>.<endpoint>`) — drop this flag (or set `false`) when you swap to real S3.
-- `s3.s3Config.publicEndpoint` — `endpoint` (`http://s3:9000`) only resolves inside the docker network; presigned upload/download URLs handed to the browser need a host-reachable URL. nginx routes the `s3.<domain>` subdomain to RustFS internally and preserves the Host header end-to-end (required for S3 signature validation), so the browser hits the same port/protocol as the rest of the app — no separate published port, no mixed-content surprises when you turn on TLS. Switch to `https://s3.<your-domain>` once you enable TLS in Step 3. Real AWS S3 doesn't need this — its endpoint is already public; drop the field entirely.
-- `trust_proxy: 1` — nginx terminates TLS and forwards `X-Forwarded-For`. Without this, `req.ip` is the docker-network address of the nginx container instead of the real client IP, which breaks rate limiting and IP-based audit logs. `1` = one trusted hop (nginx). Bump to `2` if you put Cloudflare in front of nginx; never set `true` (it trusts every hop and makes XFF forgeable).
+- `s3.s3Config.publicEndpoint` — `endpoint` (`http://s3:9000`) only resolves inside the docker network; presigned upload/download URLs handed to the browser need a host-reachable URL. Caddy routes the `s3.<domain>` subdomain to RustFS internally and preserves the Host header end-to-end (required for S3 signature validation), so the browser hits the same port/protocol as the rest of the app — no separate published port, no mixed-content surprises when you turn on TLS. Switch to `https://s3.<your-domain>` once you enable TLS in Step 3. Real AWS S3 doesn't need this — its endpoint is already public; drop the field entirely.
+- `trust_proxy: 1` — Caddy terminates TLS and forwards `X-Forwarded-For`. Without this, `req.ip` is the docker-network address of the Caddy container instead of the real client IP, which breaks rate limiting and IP-based audit logs. `1` = one trusted hop (Caddy). Bump to `2` if you put Cloudflare in front of Caddy; never set `true` (it trusts every hop and makes XFF forgeable).
 
 > If you ever change `MARIADB_PASSWORD` after first boot, `.env` alone won't update MariaDB — its credentials are baked into `./puter/data/mariadb/` on first init. Either rotate the password inside MariaDB by hand or `docker compose down && rm -rf ./puter/data/mariadb` to start fresh.
 
 ## Step 2 — Point DNS at the server \[Optional\]
 
-In your DNS provider, add records for the main domain plus the subdomains Puter and nginx route on (`api.*`, `site.*`, `app.*`, `s3.*`):
+In your DNS provider, add records for the main domain plus the subdomains Puter and Caddy route on (`api.*`, `site.*`, `app.*`, `s3.*`):
 
 ```
 A      puter.localhost          → <your server's public IP>
@@ -163,7 +160,7 @@ A      dev.puter.localhost      → <your server's public IP>
 A      *.dev.puter.localhost    → <your server's public IP>
 ```
 
-The wildcards are required — Puter routes via subdomains (`api.*`, `app.*`, etc.) and nginx routes browser S3 traffic via `s3.*` to RustFS.
+The wildcards are required — Puter routes via subdomains (`api.*`, `app.*`, etc.) and Caddy routes browser S3 traffic via `s3.*` to RustFS.
 
 ## Step 3 — TLS (recommended for public installs) \[Optional\]
 
@@ -182,13 +179,15 @@ sudo certbot certonly --manual --preferred-challenges dns \
 
 The cert needs to cover `*.puter.localhost` so that `s3.puter.localhost` (browser S3 endpoint), plus Puter's own `api.*` / `app.*` subdomains, all validate.
 
+> **Why not Caddy's automatic HTTPS?** Caddy issues certs over ACME by itself, but only for hostnames it knows up front, and only over HTTP-01 with the stock image. Puter serves every user's site and app on a subdomain it invents at runtime (`<name>.site.<domain>`, `<name>.app.<domain>`), which needs a **wildcard** cert — and wildcards require DNS-01, which requires a DNS-provider plugin that isn't in `caddy:2.11-alpine`. So `caddy/Caddyfile` sets `auto_https off` and reads the cert you supply below. If you'd rather have Caddy manage certs, build an image with the plugin for your DNS provider (`xcaddy build --with github.com/caddy-dns/<provider>`) and swap the `tls` line for a `tls { dns <provider> … }` block.
+
 Drop the resulting `fullchain.pem` and `privkey.pem` into `./puter/tls/`.
 
-**Wire nginx to use them:**
+**Wire Caddy to use them:**
 
-1. Open [nginx/nginx.conf](../nginx/nginx.conf), uncomment **both** `# server { listen 443 ssl … }` blocks (one for `s3.*`, one for the catch-all).
-2. (Optional) Replace the body of the port-80 blocks with `return 301 https://$host$request_uri;` to force HTTPS everywhere.
-3. In [docker-compose.yml](../docker-compose.yml), uncomment the `443:443` port mapping under the `nginx` service.
+1. Open [caddy/Caddyfile](../caddy/Caddyfile) and uncomment the `# :443 { … }` block at the bottom.
+2. (Optional but recommended) Replace the plain `:80 { import puter_routes }` block with the `redir` version shown alongside it, to force HTTPS everywhere.
+3. In [docker-compose.yml](../docker-compose.yml), uncomment the `443:443` port mapping under the `caddy` service.
 4. In `.env`, uncomment `HTTPS_PORT=443`.
 5. In `config.json`, switch:
     ```json
@@ -201,9 +200,9 @@ Drop the resulting `fullchain.pem` and `privkey.pem` into `./puter/tls/`.
 
 ## Running behind your own reverse proxy
 
-The bundled `puter-nginx` mirrors production and is the supported default — it terminates TLS (Step 3) and forwards every Host to Puter. But plenty of self-hosters already run their own edge proxy (Caddy, Traefik, HAProxy, a cloud load balancer, another nginx). You can put Puter behind it instead; Puter doesn't terminate TLS itself in any setup, so "your proxy does TLS" is just a matter of pointing it at the Puter container and getting a handful of details right.
+The bundled `puter-caddy` mirrors production and is the supported default — it terminates TLS (Step 3) and forwards every Host to Puter. But plenty of self-hosters already run their own edge proxy (Traefik, nginx, HAProxy, a cloud load balancer, another Caddy). You can put Puter behind it instead; Puter doesn't terminate TLS itself in any setup, so "your proxy does TLS" is just a matter of pointing it at the Puter container and getting a handful of details right.
 
-You can keep the bundled nginx as the single hop your proxy talks to, or bypass it and forward straight to the Puter container on port `4100` (uncomment the `4100:4100` mapping under the `puter` service in [docker-compose.yml](../docker-compose.yml), or attach your proxy to the compose network). Either works — what matters is the rules below.
+You can keep the bundled Caddy as the single hop your proxy talks to, or bypass it and forward straight to the Puter container on port `4100` (uncomment the `4100:4100` mapping under the `puter` service in [docker-compose.yml](../docker-compose.yml), or attach your proxy to the compose network). Either works — what matters is the rules below.
 
 **The rules that actually matter** (getting any of these wrong is what causes the redirect loops and "Invalid Host header" failures people hit):
 
@@ -219,7 +218,7 @@ You can keep the bundled nginx as the single hop your proxy talks to, or bypass
     - `X-Forwarded-For` — the real client IP (rate limiting + audit logs).
     - `Upgrade` / `Connection` — passed through for WebSocket / socket.io upgrades, or the realtime connection silently fails.
 
-5. **Set `trust_proxy` to the number of hops in front of Puter.** One external proxy talking directly to Puter → `"trust_proxy": 1` (installer: `PUTER_TRUST_PROXY=1`). A second proxy in front (e.g. Cloudflare → your proxy → Puter) → `2`. This is the count of proxies between the client and Puter, **including** the bundled nginx if you keep it. Too low and `req.ip` becomes a proxy address (breaks rate limiting); never set `true` (it trusts every hop and makes `X-Forwarded-For` forgeable).
+5. **Set `trust_proxy` to the number of hops in front of Puter.** One external proxy talking directly to Puter → `"trust_proxy": 1` (installer: `PUTER_TRUST_PROXY=1`). A second proxy in front (e.g. Cloudflare → your proxy → Puter) → `2`. This is the count of proxies between the client and Puter, **including** the bundled Caddy if you keep it. Too low and `req.ip` becomes a proxy address (breaks rate limiting); never set `true` (it trusts every hop and makes `X-Forwarded-For` forgeable).
 
 6. **Route the wildcard to Puter.** Your proxy must forward `*.<domain>` (covering `api.*`, `app.*`, and `s3.<domain>`) and `*.site.<domain>` (and any other hosting domains) to Puter — same wildcard DNS as Step 2. Puter does the per-subdomain routing internally; the proxy just needs to hand it the traffic with the Host intact.
 
@@ -227,6 +226,8 @@ With those in place the rest of the stack is unchanged — `docker compose up -d
 
 ## Step 4 — Bring it up
 
+Both [docker-compose.yml](../docker-compose.yml) and [caddy/Caddyfile](../caddy/Caddyfile) need to sit next to your `.env` — clone the repo, or copy those two paths out of it. The Caddyfile is bind-mounted read-only; if it's missing, Docker creates a *directory* at that path and `puter-caddy` dies with "not a directory".
+
 ```bash
 docker compose up -d
 ```
@@ -369,6 +370,37 @@ Default is 100 MB per user.
 
 Set `is_storage_limited: false` for unlimited (bounded by host disk).
 
+### Usage metering and budgets
+
+Puter meters what an account costs to serve — bytes sent back, object-store
+requests, KV capacity, AI tokens — against a monthly budget, and refuses the
+operations that spend it once that budget is gone. The refusal is a `402` with
+code `insufficient_funds`; reads that only describe things, and every kind of
+deletion, stay available so an account can always see what it has and clear it.
+
+On a self-hosted install this is almost certainly not what you want. There is
+nowhere to buy more, so accounts are held to the free monthly allowance
+(US$0.25 of measured cost — roughly 2 GiB of downloads) and start being refused
+after that. Turn it off:
+
+```json
+"unlimitedMetering": true
+```
+
+Every account then resolves to an unlimited policy. Usage is still recorded, so
+the dashboard still shows what is being consumed; nothing is ever refused for
+lack of budget.
+
+To keep the budgets but stop them blocking anything — recording only:
+
+```json
+"meteringEnforcement": { "enabled": false }
+```
+
+Calls driven by a deployed worker are exempt from enforcement by default,
+because a worker has no prompt to show and nobody watching it fail. Set
+`"meteringEnforcement": { "workers": true }` to include them.
+
 ### Captcha on signup / login
 
 Built-in proof-of-work captcha — no external service needed.
@@ -469,7 +501,7 @@ Migrations re-apply idempotently across pulls. Volumes are preserved.
 
 ## Troubleshooting
 
-**Site loads but I get "Bad Gateway" / nginx errors.**
+**Site loads but I get a 502 / "Bad Gateway" from Caddy.**
 The puter container failed to come up. `docker compose logs puter` will tell you which dependency rejected it (most often DB password mismatch between `.env` and `config.json`).
 
 **Login screen says "admin password not set".**

docker-compose.yml

@@ -2,7 +2,7 @@
 # Self-hosted Puter — full stack.
 #
 # Brings up Puter + every external service it needs:
-#   - nginx    : reverse proxy (mirrors prod ALB; handles TLS + Host fan-out)
+#   - caddy    : reverse proxy (mirrors prod ALB; handles TLS + Host fan-out)
 #   - valkey   : redis-compatible cache / rate-limiter backend
 #   - mariadb  : SQL database (Puter applies its schema on first boot)
 #   - dynamo   : DynamoDB-local (KV store; Puter creates the table itself)
@@ -23,7 +23,8 @@
 #
 # Production:
 #   - Always replace the default passwords / S3 keys / Puter secrets.
-#   - Front Puter with TLS-terminating reverse proxy (Caddy / nginx).
+#   - Enable TLS on the bundled Caddy (see caddy/Caddyfile) or front the
+#     stack with your own TLS-terminating proxy.
 #   - Move state-bearing volumes to a backed-up location.
 
 services:
@@ -118,7 +119,7 @@ services:
       RUSTFS_SECRET_KEY: ${S3_SECRET_KEY:-puter-secret-change-me}
     volumes:
       - ./puter/data/s3:/data:z
-    # Internal-only — browsers reach RustFS via nginx (`s3.<domain>`),
+    # Internal-only — browsers reach RustFS via Caddy (`s3.<domain>`),
     # which preserves the Host header for S3 signature validation and
     # rides the same TLS termination as Puter. Uncomment to also expose
     # 9000 directly on the host for `aws-cli` / debugging.
@@ -249,7 +250,7 @@ services:
         condition: service_started
       s3-init:
         condition: service_completed_successfully
-    # Internal-only: nginx reaches it on the compose network. Uncomment
+    # Internal-only: Caddy reaches it on the compose network. Uncomment
     # to also expose port 4100 directly on the host (useful for debugging).
     # ports:
     #   - "4100:4100"
@@ -270,23 +271,32 @@ services:
       retries: 3
       start_period: 30s
 
-  nginx:
-    image: nginx:1.27-alpine
-    container_name: puter-nginx
+  caddy:
+    image: caddy:2.11-alpine
+    container_name: puter-caddy
     restart: unless-stopped
     depends_on:
       puter:
         condition: service_started
     ports:
       - "${HTTP_PORT:-80}:80"
-      # Uncomment when you enable TLS in nginx/nginx.conf:
+      # Uncomment when you enable TLS in caddy/Caddyfile:
       # - "${HTTPS_PORT:-443}:443"
     volumes:
-      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro,z
-      # TLS certs (fullchain.pem + privkey.pem). Read-only inside.
-      - ./puter/tls:/etc/nginx/tls:ro,z
+      - ./caddy/Caddyfile:/etc/caddy/Caddyfile:ro,z
+      # TLS certs (wildcard fullchain.pem + privkey.pem). Read-only inside.
+      - ./puter/tls:/etc/caddy/tls:ro,z
+      # Caddy's own state — the cert store it would use if you swap this
+      # config over to ACME. Kept under ./puter/data with everything else
+      # so one directory is the whole backup.
+      - ./puter/data/caddy:/data:z
     healthcheck:
-      test: ["CMD-SHELL", "wget -qO- --tries=1 --timeout=2 http://localhost/ || exit 1"]
+      # Hits Caddy's local-only admin API rather than proxying through to
+      # Puter: this reports whether the proxy itself is up and configured,
+      # and keeps working once the `:80` block becomes an HTTPS redirect.
+      # 127.0.0.1, not localhost — the admin endpoint is IPv4-only and
+      # busybox wget tries ::1 first.
+      test: ["CMD-SHELL", "wget -qO- --tries=1 --timeout=2 http://127.0.0.1:2019/config/ >/dev/null || exit 1"]
       interval: 10s
       timeout: 3s
       retries: 5

extensions/appTelemetry.test.ts

@@ -28,7 +28,7 @@ beforeAll(async () => {
 });
 
 afterAll(async () => {
-    await server.shutdown();
+    await server?.shutdown();
 });
 
 const seedOwnedApp = async (prefix: string) => {
@@ -50,6 +50,32 @@ const seedOwnedApp = async (prefix: string) => {
     return { owner, app: app! };
 };
 
+const seedUser = async (prefix: string, email: string | null = null) =>
+    server.stores.user.create({
+        username: `${prefix}_${Math.random().toString(36).slice(2, 8)}`,
+        uuid: uuidv4(),
+        password: 'x',
+        email,
+    });
+
+const grantAuthenticated = async (appId: number, userId: number) => {
+    await server.clients.db.write(
+        `INSERT INTO user_to_app_permissions (user_id, app_id, permission, extra) VALUES (?, ?, ?, ?)`,
+        [userId, appId, 'flag:app-is-authenticated', null],
+    );
+};
+
+const grantEmailRead = async (
+    appId: number,
+    userId: number,
+    userUuid: string,
+) => {
+    await server.clients.db.write(
+        `INSERT INTO user_to_app_permissions (user_id, app_id, permission, extra) VALUES (?, ?, ?, ?)`,
+        [userId, appId, `user:${userUuid}:email:read`, null],
+    );
+};
+
 describe('appTelemetry driver — get_users', () => {
     it('throws HttpError(400) when app_uuid is missing', async () => {
         await expect(driver.get_users({})).rejects.toMatchObject({
@@ -117,6 +143,66 @@ describe('appTelemetry driver — get_users', () => {
 
         expect(result).toEqual([]);
     });
+
+    it('omits user_email for a user who did not grant email:read', async () => {
+        const { owner, app } = await seedOwnedApp('noemail');
+        const member = await seedUser('member', '[email protected]');
+        await grantAuthenticated(app.id as number, member.id as number);
+
+        const [row] = (await callWithActor(
+            { user: { uuid: owner.uuid, id: owner.id as number } },
+            () => driver.get_users({ app_uuid: app.uid }),
+        )) as Array<Record<string, unknown>>;
+
+        expect(row.user).toBe(member.username);
+        expect(row.user_uuid).toBe(member.uuid);
+        // No grant → the field must be absent (not just null), so the email
+        // never leaks to the app owner.
+        expect(Object.prototype.hasOwnProperty.call(row, 'user_email')).toBe(
+            false,
+        );
+    });
+
+    it('returns user_email when the user granted email:read to the app', async () => {
+        const { owner, app } = await seedOwnedApp('withemail');
+        const member = await seedUser('member', '[email protected]');
+        await grantAuthenticated(app.id as number, member.id as number);
+        await grantEmailRead(
+            app.id as number,
+            member.id as number,
+            member.uuid,
+        );
+
+        const [row] = (await callWithActor(
+            { user: { uuid: owner.uuid, id: owner.id as number } },
+            () => driver.get_users({ app_uuid: app.uid }),
+        )) as Array<Record<string, unknown>>;
+
+        expect(row.user_uuid).toBe(member.uuid);
+        expect(row.user_email).toBe('[email protected]');
+    });
+
+    it('does not leak email granted to a *different* app', async () => {
+        const { owner, app } = await seedOwnedApp('appA');
+        const { app: otherApp } = await seedOwnedApp('appB');
+        const member = await seedUser('member', '[email protected]');
+        await grantAuthenticated(app.id as number, member.id as number);
+        // Grant email:read against the OTHER app only.
+        await grantEmailRead(
+            otherApp.id as number,
+            member.id as number,
+            member.uuid,
+        );
+
+        const [row] = (await callWithActor(
+            { user: { uuid: owner.uuid, id: owner.id as number } },
+            () => driver.get_users({ app_uuid: app.uid }),
+        )) as Array<Record<string, unknown>>;
+
+        expect(Object.prototype.hasOwnProperty.call(row, 'user_email')).toBe(
+            false,
+        );
+    });
 });
 
 describe('appTelemetry driver — user_count', () => {

extensions/appTelemetry.ts

@@ -2,6 +2,14 @@ import { Context } from '@heyputer/backend/src/core';
 import type { Actor } from '@heyputer/backend/src/core/actor';
 import { HttpError } from '@heyputer/backend/src/core/http';
 import { PuterDriver } from '@heyputer/backend/src/drivers/types';
+import type {
+    DriverConcurrentConfig,
+    DriverRateLimitConfig,
+} from '@heyputer/backend/src/drivers/meta';
+import {
+    DEFAULT_FREE_SUBSCRIPTION,
+    DEFAULT_TEMP_SUBSCRIPTION,
+} from '@heyputer/backend/src/services/metering/consts';
 import { extension } from '@heyputer/backend/src/extensions';
 
 // App-telemetry lets an app owner enumerate the users who have
@@ -50,17 +58,42 @@ const parseIntParam = (
  * Driver exposing the `app-telemetry` interface.
  *
  * The `/drivers/call` permission gate checks
- * `service:app-telemetry:ii:app-telemetry`, which every actor already holds
- * via the blanket `service` grant (hardcoded-permissions.js +
+ * `service:app-telemetry:ii:app-telemetry`, which every actor already holds via
+ * the blanket `service` grant (hardcoded-permissions.js +
  * `default_implicit_user_app_permissions`). The real authorization — "is the
- * caller the app owner?" — is enforced inside `get_users` below, exactly as
- * v1 did.
+ * caller the app owner?" — is enforced inside `get_users` below, exactly as v1
+ * did.
  */
 export class AppTelemetryDriver extends PuterDriver {
     readonly driverInterface = 'app-telemetry';
     readonly driverName = 'app-telemetry';
     readonly isDefault = true;
 
+    // Declaring nothing here would leave both methods on the generic
+    // 600/minute driver default, which does not fit a paginated scan that
+    // can ask for MAX_LIMIT rows at MAX_OFFSET. This is a dashboard read —
+    // nobody calls it in a loop.
+    readonly rateLimit: DriverRateLimitConfig = {
+        default: {
+            limit: 60,
+            window: 60_000,
+            bySubscription: {
+                [DEFAULT_FREE_SUBSCRIPTION]: 30,
+                [DEFAULT_TEMP_SUBSCRIPTION]: 10,
+            },
+        },
+    };
+
+    readonly concurrent: DriverConcurrentConfig = {
+        default: {
+            limit: 5,
+            bySubscription: {
+                [DEFAULT_FREE_SUBSCRIPTION]: 2,
+                [DEFAULT_TEMP_SUBSCRIPTION]: 2,
+            },
+        },
+    };
+
     /** Users who have authenticated into the given app (owner-only). */
     async get_users({
         app_uuid,
@@ -70,7 +103,9 @@ export class AppTelemetryDriver extends PuterDriver {
         app_uuid?: string;
         limit?: unknown;
         offset?: unknown;
-    } = {}): Promise<Array<{ user: string; user_uuid: string }>> {
+    } = {}): Promise<
+        Array<{ user: string; user_uuid: string; user_email?: string | null }>
+    > {
         if (!app_uuid) throw new HttpError(400, 'Missing `app_uuid`');
 
         const safeLimit = parseIntParam(limit, {
@@ -105,16 +140,45 @@ export class AppTelemetryDriver extends PuterDriver {
             .catch(() => false);
         if (!ownsApp) throw new HttpError(403, 'Permission denied');
 
+        const appId = (app as { id: number }).id;
+
         const users = (await this.clients.db.read(
-            `SELECT u.username, u.uuid FROM user_to_app_permissions p
+            `SELECT u.id, u.username, u.uuid, u.email FROM user_to_app_permissions p
              INNER JOIN ${this.clients.db.quoteIdentifier('user')} u ON p.user_id = u.id
              WHERE p.permission = 'flag:app-is-authenticated' AND p.app_id = ?
              ORDER BY (p.dt IS NOT NULL), p.dt, p.user_id
              LIMIT ? OFFSET ?`,
-            [(app as { id: number }).id, safeLimit, safeOffset],
-        )) as Array<{ username: string; uuid: string }>;
+            [appId, safeLimit, safeOffset],
+        )) as Array<{
+            id: number;
+            username: string;
+            uuid: string;
+            email: string | null;
+        }>;
 
-        return users.map((e) => ({ user: e.username, user_uuid: e.uuid }));
+        // Only surface a user's email if *that user* granted this app the
+        // `user:<their-uuid>:email:read` permission — the same grant
+        // `puter.perms.requestEmail()` obtains and `whoami` honours. This is a
+        // per-user check keyed on the app (not the calling owner-actor): a
+        // user may have authenticated into the app without sharing their
+        // email. Resolve the whole page in one query.
+        const emailPermitted = new Set<number>();
+        if (users.length > 0) {
+            const permStrings = users.map((u) => `user:${u.uuid}:email:read`);
+            const placeholders = permStrings.map(() => '?').join(', ');
+            const grants = (await this.clients.db.read(
+                `SELECT user_id FROM user_to_app_permissions
+                 WHERE app_id = ? AND permission IN (${placeholders})`,
+                [appId, ...permStrings],
+            )) as Array<{ user_id: number }>;
+            for (const g of grants) emailPermitted.add(g.user_id);
+        }
+
+        return users.map((e) =>
+            emailPermitted.has(e.id)
+                ? { user: e.username, user_uuid: e.uuid, user_email: e.email }
+                : { user: e.username, user_uuid: e.uuid },
+        );
     }
 
     /** Count of users who have authenticated into the given app. */

extensions/devWatcher.test.ts

@@ -0,0 +1,555 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import {
+    afterAll,
+    afterEach,
+    beforeAll,
+    beforeEach,
+    describe,
+    expect,
+    it,
+    vi,
+} from 'vitest';
+import { extensionStore } from '../src/backend/extensions.ts';
+import type { IConfig } from '../src/backend/types';
+import './devWatcher.ts';
+
+type Lifecycle = {
+    onServerStart: () => Promise<void>;
+    onServerShutdown: () => Promise<void>;
+};
+
+// The extension registers itself on import; that registry entry is the
+// only handle on the service class.
+const DevWatcherService = extensionStore.services.devWatcher as unknown as new (
+    config: IConfig,
+    clients: unknown,
+    stores: unknown,
+    services: unknown,
+) => Lifecycle;
+
+const makeService = (config: Record<string, unknown>): Lifecycle =>
+    new DevWatcherService(config as unknown as IConfig, {}, {}, {});
+
+let workdir: string;
+
+const write = (relative: string, contents: string): string => {
+    const abs = path.join(workdir, relative);
+    writeFileSync(abs, contents);
+    return abs;
+};
+
+/** Poll until `predicate` holds or the budget runs out. */
+const waitFor = async (
+    predicate: () => boolean,
+    label: string,
+    timeoutMs = 15_000,
+): Promise<void> => {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        if (predicate()) return;
+        await new Promise((r) => setTimeout(r, 20));
+    }
+    throw new Error(`timed out waiting for ${label}`);
+};
+
+const logLines = (spy: { mock: { calls: unknown[][] } }): string[] =>
+    spy.mock.calls.map((call) => call.map(String).join(' '));
+
+describe('devWatcher extension', () => {
+    let log: ReturnType<typeof vi.spyOn>;
+    let warn: ReturnType<typeof vi.spyOn>;
+    let error: ReturnType<typeof vi.spyOn>;
+
+    beforeAll(() => {
+        workdir = mkdtempSync(path.join(tmpdir(), 'devwatch-test-'));
+    });
+
+    afterAll(() => {
+        rmSync(workdir, { recursive: true, force: true });
+        delete (extensionStore.services as Record<string, unknown>).devWatcher;
+    });
+
+    beforeEach(() => {
+        log = vi.spyOn(console, 'log').mockImplementation(() => {});
+        warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        error = vi.spyOn(console, 'error').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        log.mockRestore();
+        warn.mockRestore();
+        error.mockRestore();
+    });
+
+    const started = () =>
+        logLines(log).some((line) =>
+            line.startsWith('[devwatch] starting watchers from'),
+        );
+
+    // -- start gating -------------------------------------------------
+
+    it('does nothing when the server is not running in dev', async () => {
+        await makeService({ env: 'production' }).onServerStart();
+        expect(started()).toBe(false);
+    });
+
+    it('does nothing when devwatch is explicitly disabled', async () => {
+        await makeService({
+            env: 'dev',
+            devwatch: { enabled: false },
+        }).onServerStart();
+        expect(started()).toBe(false);
+    });
+
+    it('does nothing when the server opts out with no_devwatch', async () => {
+        await makeService({
+            env: 'dev',
+            no_devwatch: true,
+            devwatch: { enabled: true },
+        }).onServerStart();
+        expect(started()).toBe(false);
+    });
+
+    it('starts in dev even with no explicit devwatch block', async () => {
+        const service = makeService({
+            env: 'dev',
+            devwatch: {
+                root: workdir,
+                commands: [],
+                webpack: [],
+                ready_delay_ms: 0,
+            },
+        });
+        await service.onServerStart();
+        expect(started()).toBe(true);
+        await service.onServerShutdown();
+    });
+
+    it('starts outside dev when devwatch is explicitly enabled', async () => {
+        const service = makeService({
+            env: 'production',
+            devwatch: {
+                enabled: true,
+                root: workdir,
+                commands: [],
+                webpack: [],
+                ready_delay_ms: 0,
+            },
+        });
+        await service.onServerStart();
+        expect(started()).toBe(true);
+        await service.onServerShutdown();
+    });
+
+    it('ignores a devwatch config that is not an object', async () => {
+        // Falls back to `{}`, so the dev-env rule decides — and the
+        // default webpack entries would be used, so pin it off instead.
+        await makeService({
+            env: 'production',
+            devwatch: 'yes',
+        }).onServerStart();
+        expect(started()).toBe(false);
+    });
+
+    it('only starts once even if the lifecycle hook fires again', async () => {
+        const service = makeService({
+            env: 'dev',
+            devwatch: {
+                root: workdir,
+                commands: [],
+                webpack: [],
+                ready_delay_ms: 0,
+            },
+        });
+        await service.onServerStart();
+        await service.onServerStart();
+        expect(
+            logLines(log).filter((line) =>
+                line.startsWith('[devwatch] starting watchers from'),
+            ),
+        ).toHaveLength(1);
+        await service.onServerShutdown();
+    });
+
+    it('waits out the configured ready delay before resolving', async () => {
+        const service = makeService({
+            env: 'dev',
+            devwatch: {
+                root: workdir,
+                commands: [],
+                webpack: [],
+                ready_delay_ms: 60,
+            },
+        });
+        const start = Date.now();
+        await service.onServerStart();
+        expect(Date.now() - start).toBeGreaterThanOrEqual(50);
+        await service.onServerShutdown();
+    });
+
+    // -- child commands -----------------------------------------------
+
+    it('spawns a command, line-buffers its output and flushes the tail', async () => {
+        write(
+            'chatty.js',
+            [
+                "process.stdout.write('one\\ntwo\\n');",
+                "process.stderr.write('bad thing\\n');",
+                // No trailing newline: only the stream `end` flushes it.
+                "process.stdout.write('tail-no-newline');",
+            ].join('\n'),
+        );
+
+        const service = makeService({
+            env: 'dev',
+            devwatch: {
+                root: workdir,
+                commands: [
+                    {
+                        name: 'chatty',
+                        directory: '.',
+                        command: 'node',
+                        args: ['chatty.js'],
+                    },
+                ],
+                webpack: [],
+                ready_delay_ms: 0,
+            },
+        });
+        await service.onServerStart();
+
+        await waitFor(
+            () =>
+                logLines(log).some((l) =>
+                    l.includes('[devwatch:chatty:1] tail-no-newline'),
+                ),
+            'child stdout',
+        );
+
+        const lines = logLines(log);
+        expect(lines).toContain('[devwatch:chatty:1] one');
+        expect(lines).toContain('[devwatch:chatty:1] two');
+        expect(logLines(warn)).toContain('[devwatch:chatty:2] bad thing');
+
+        await waitFor(
+            () =>
+                logLines(log).some((l) =>
+                    l.includes('[devwatch:chatty:exit] process exited'),
+                ),
+            'child exit',
+        );
+        await service.onServerShutdown();
+    });
+
+    it('passes literal and computed env values to the child', async () => {
+        write(
+            'env.js',
+            'process.stdout.write(`STATIC=${process.env.STATIC_VALUE} ORIGIN=${process.env.FROM_CONFIG} MISSING=${process.env.BLOWS_UP}\\n`);',
+        );
+
+        const service = makeService({
+            env: 'dev',
+            origin: 'http://puter.localhost:4100',
+            devwatch: {
+                root: workdir,
+                commands: [
+                    {
+                        name: 'envtest',
+                        directory: '.',
+                        command: 'node',
+                        args: ['env.js'],
+                        env: {
+                            STATIC_VALUE: 'literal',
+                            FROM_CONFIG: ({
+                                global_config,
+                            }: {
+                                global_config: Record<string, unknown> | null;
+                            }) => String(global_config?.origin ?? ''),
+                            // Reading through a null is the "config not
+                            // loaded yet" shape the extension deliberately
+                            // stays quiet about.
+                            BLOWS_UP: () => {
+                                const nothing = null as unknown as {
+                                    x: string;
+                                };
+                                return nothing.x;
+                            },
+                            NOISY: () => {
+                                throw new Error('unexpected failure');
+                            },
+                        },
+                    },
+                ],
+                webpack: [],
+                ready_delay_ms: 0,
+            },
+        });
+        await service.onServerStart();
+
+        await waitFor(
+            () => logLines(log).some((l) => l.includes('STATIC=literal')),
+            'env output',
+        );
+        const line = logLines(log).find((l) => l.includes('STATIC=literal'))!;
+        expect(line).toContain('ORIGIN=http://puter.localhost:4100');
+        expect(line).toContain('MISSING=undefined');
+
+        // A null-property read is expected noise and stays silent; any
+        // other failure is reported.
+        const warnings = logLines(warn);
+        expect(
+            warnings.some((w) => w.includes('could not evaluate env function')),
+        ).toBe(true);
+        expect(warnings.some((w) => w.includes('for BLOWS_UP'))).toBe(false);
+        expect(warnings.some((w) => w.includes('for NOISY'))).toBe(true);
+
+        await service.onServerShutdown();
+    });
+
+    it('kills a still-running child on shutdown', async () => {
+        write('forever.js', 'setInterval(() => {}, 1000);');
+
+        const service = makeService({
+            env: 'dev',
+            devwatch: {
+                root: workdir,
+                commands: [
+                    {
+                        name: 'forever',
+                        directory: '.',
+                        command: 'node',
+                        args: ['forever.js'],
+                    },
+                ],
+                webpack: [],
+                ready_delay_ms: 0,
+            },
+        });
+        await service.onServerStart();
+        await service.onServerShutdown();
+
+        expect(logLines(log)).toContain('[devwatch:forever] stopping process');
+        await waitFor(
+            () =>
+                logLines(log).some((l) =>
+                    l.includes('[devwatch:forever:exit] process exited'),
+                ),
+            'child killed',
+        );
+    });
+
+    // -- webpack watchers ---------------------------------------------
+
+    const makeWebpackProject = (
+        name: string,
+        configFile: string,
+        contents: string,
+        packageJson?: string,
+    ): string => {
+        const dir = path.join(workdir, name);
+        rmSync(dir, { recursive: true, force: true });
+        writeFileSync(
+            path.join(
+                (() => {
+                    const { mkdirSync } =
+                        require('node:fs') as typeof import('node:fs');
+                    mkdirSync(path.join(dir, 'src'), { recursive: true });
+                    return dir;
+                })(),
+                'src/entry.js',
+            ),
+            "console.log('hello');\n",
+        );
+        writeFileSync(path.join(dir, configFile), contents);
+        if (packageJson) {
+            writeFileSync(path.join(dir, 'package.json'), packageJson);
+        }
+        return name;
+    };
+
+    it('compiles a CommonJS webpack config and reports later rebuilds', async () => {
+        const dir = makeWebpackProject(
+            'cjs-project',
+            'webpack.config.cjs',
+            `module.exports = {
+                mode: 'development',
+                entry: './src/entry.js',
+                output: { path: __dirname + '/out', filename: 'bundle.js' },
+            };`,
+        );
+
+        let onConfigSaw: Record<string, unknown> | undefined;
+        const service = makeService({
+            env: 'dev',
+            devwatch: {
+                root: workdir,
+                commands: [],
+                webpack: [
+                    {
+                        name: 'cjs',
+                        directory: dir,
+                        onConfig: (cfg: Record<string, unknown>) => {
+                            onConfigSaw = cfg;
+                        },
+                    },
+                ],
+                ready_delay_ms: 0,
+            },
+        });
+
+        await service.onServerStart();
+        expect(onConfigSaw).toBeDefined();
+        // The watcher context is anchored at <root>/<directory> so relative
+        // entries resolve regardless of the server's cwd.
+        expect(onConfigSaw!.context).toBe(path.join(workdir, dir));
+
+        // First build is silent by design; force a rebuild and assert the
+        // update line shows up.
+        await new Promise((r) => setTimeout(r, 500));
+        writeFileSync(
+            path.join(workdir, dir, 'src/entry.js'),
+            "console.log('hello again');\n",
+        );
+        await waitFor(
+            () =>
+                logLines(log).some((l) =>
+                    l.includes('[devwatch] updated cjs using Webpack'),
+                ),
+            'webpack rebuild',
+        );
+
+        await service.onServerShutdown();
+    });
+
+    it('resolves an ESM webpack config declared through package.json type', async () => {
+        const dir = makeWebpackProject(
+            'esm-project',
+            'webpack.config.js',
+            `export default {
+                mode: 'development',
+                entry: './src/entry.js',
+                output: { filename: 'bundle.js' },
+            };`,
+            JSON.stringify({ name: 'esm-project', type: 'module' }),
+        );
+
+        const service = makeService({
+            env: 'dev',
+            devwatch: {
+                root: workdir,
+                commands: [],
+                webpack: [{ directory: dir }],
+                ready_delay_ms: 0,
+            },
+        });
+
+        await service.onServerStart();
+        await service.onServerShutdown();
+        // Falling back to the directory as the display name is the
+        // documented behaviour when `name` is omitted.
+        expect(error).not.toHaveBeenCalled();
+    });
+
+    it('calls a config exported as a function and honours an explicit context', async () => {
+        const dir = makeWebpackProject(
+            'fn-project',
+            'webpack.config.cjs',
+            `module.exports = () => ({
+                mode: 'development',
+                context: 'src',
+                entry: './entry.js',
+                name: process.env.WEBPACK_MARKER,
+                output: { path: __dirname + '/out', filename: 'bundle.js' },
+            });`,
+        );
+
+        let seen: Record<string, unknown> | undefined;
+        const service = makeService({
+            env: 'dev',
+            devwatch: {
+                root: workdir,
+                commands: [],
+                webpack: [
+                    {
+                        name: 'fn',
+                        directory: dir,
+                        env: { WEBPACK_MARKER: 'set-during-load' },
+                        onConfig: (cfg: Record<string, unknown>) => {
+                            seen = cfg;
+                        },
+                    },
+                ],
+                ready_delay_ms: 0,
+            },
+        });
+
+        await service.onServerStart();
+        // Relative `context` resolves against <root>/<directory>.
+        expect(seen!.context).toBe(path.join(workdir, dir, 'src'));
+        // The entry's env map is applied while the config module runs, and
+        // restored afterwards.
+        expect(seen!.name).toBe('set-during-load');
+        expect(process.env.WEBPACK_MARKER).toBeUndefined();
+        await service.onServerShutdown();
+    });
+
+    it('reports a failing compilation instead of crashing the server', async () => {
+        const dir = makeWebpackProject(
+            'broken-project',
+            'webpack.config.cjs',
+            `module.exports = {
+                mode: 'development',
+                entry: './src/does-not-exist.js',
+                output: { path: __dirname + '/out', filename: 'bundle.js' },
+            };`,
+        );
+
+        const service = makeService({
+            env: 'dev',
+            devwatch: {
+                root: workdir,
+                commands: [],
+                webpack: [{ name: 'broken', directory: dir }],
+                ready_delay_ms: 0,
+            },
+        });
+
+        await service.onServerStart();
+        await waitFor(
+            () =>
+                logLines(error).some((l) =>
+                    l.includes('[devwatch] failed to update broken'),
+                ),
+            'webpack failure',
+        );
+        expect(
+            logLines(error).some((l) =>
+                l.includes('[devwatch] error information: broken'),
+            ),
+        ).toBe(true);
+        await service.onServerShutdown();
+    });
+
+    it('fails loudly when a directory has no webpack config at all', async () => {
+        const dir = path.join('no-config');
+        const { mkdirSync } = await import('node:fs');
+        mkdirSync(path.join(workdir, dir), { recursive: true });
+
+        const service = makeService({
+            env: 'dev',
+            devwatch: {
+                root: workdir,
+                commands: [],
+                webpack: [{ name: 'missing', directory: dir }],
+                ready_delay_ms: 0,
+            },
+        });
+
+        await expect(service.onServerStart()).rejects.toThrow(
+            'could not find webpack config for: no-config',
+        );
+        await service.onServerShutdown();
+    });
+});

extensions/installedApps.test.ts

@@ -38,7 +38,7 @@ beforeAll(async () => {
 });
 
 afterAll(async () => {
-    await server.shutdown();
+    await server?.shutdown();
 });
 
 const seedUser = async () => {

extensions/installedApps.ts

@@ -81,6 +81,16 @@ export const handleInstalledApps = async (
 
 extension.get(
     '/installedApps',
-    { subdomain: 'api', requireUserActor: true, allowFullAccessToken: true },
+    {
+        subdomain: 'api',
+        requireUserActor: true,
+        allowFullAccessToken: true,
+        rateLimit: {
+            scope: 'installed-apps',
+            limit: 120,
+            window: 60_000,
+            key: 'user',
+        },
+    },
     handleInstalledApps,
 );

extensions/metering.test.ts

@@ -48,7 +48,7 @@ beforeAll(async () => {
 });
 
 afterAll(async () => {
-    await server.shutdown();
+    await server?.shutdown();
 });
 
 const seedUser = async () => {

extensions/metering.ts

@@ -3,6 +3,7 @@ import { HttpError } from '@heyputer/backend/src/core/http';
 import {
     controllersContainers,
     driversContainers,
+    servicesContainers,
 } from '@heyputer/backend/src/exports';
 import { extension } from '@heyputer/backend/src/extensions';
 import type { Request, Response } from 'express';
@@ -18,7 +19,7 @@ function collectAllCosts(): Record<string, unknown>[] {
     const all: Record<string, unknown>[] = [];
     const collect = (
         source: Record<string, unknown>,
-        kind: 'driver' | 'controller',
+        kind: 'driver' | 'controller' | 'service',
     ) => {
         for (const [name, instance] of Object.entries(source)) {
             const fn = (
@@ -43,6 +44,9 @@ function collectAllCosts(): Record<string, unknown>[] {
     };
     collect(driversContainers as Record<string, unknown>, 'driver');
     collect(controllersContainers as Record<string, unknown>, 'controller');
+    // Services report the costs that aren't tied to one endpoint — egress,
+    // which is metered for every response there is.
+    collect(servicesContainers as Record<string, unknown>, 'service');
     return all;
 }
 
@@ -110,26 +114,46 @@ export const handleMeteringAllCosts = async (
     res.json({ costs: cachedAllCosts });
 };
 
+/** Dashboard reads over the per-actor KV aggregates. */
+const USAGE_READ_LIMIT = {
+    scope: 'metering-usage',
+    limit: 120,
+    window: 60_000,
+    key: 'user' as const,
+};
+
 extension.get(
     '/metering/usage',
-    { subdomain: 'api', requireAuth: true },
+    { subdomain: 'api', requireAuth: true, rateLimit: USAGE_READ_LIMIT },
     handleMeteringUsage,
 );
 
 extension.get(
     '/metering/usage/:appIdOrName',
-    { subdomain: 'api', requireAuth: true },
+    { subdomain: 'api', requireAuth: true, rateLimit: USAGE_READ_LIMIT },
     handleMeteringUsageForApp,
 );
 
 extension.get(
     '/metering/globalUsage',
-    { subdomain: 'api', adminOnly: true },
+    {
+        subdomain: 'api',
+        adminOnly: true,
+        // Sums across every shard of the global aggregate. Admin-gated, so
+        // this is loop protection — but one accidental poll is an
+        // expensive minute.
+        rateLimit: {
+            scope: 'metering-global-usage',
+            limit: 10,
+            window: 60_000,
+            key: 'user',
+        },
+    },
     handleMeteringGlobalUsage,
 );
 
 extension.get(
     '/metering/allCosts',
-    { subdomain: 'api', requireAuth: true },
+    { subdomain: 'api', requireAuth: true, rateLimit: USAGE_READ_LIMIT },
     handleMeteringAllCosts,
 );

extensions/serverInfo.test.ts

@@ -71,9 +71,7 @@ describe('serverInfo extension — handleServerInfo', () => {
         const statfsSpy = vi
             .spyOn(fs.default, 'statfs')
             .mockRejectedValue(new Error('statfs unsupported'));
-        const errSpy = vi
-            .spyOn(console, 'error')
-            .mockImplementation(() => {});
+        const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
 
         const { res, captured } = makeRes();
         await handleServerInfo({} as Request, res);
@@ -88,4 +86,18 @@ describe('serverInfo extension — handleServerInfo', () => {
         statfsSpy.mockRestore();
         errSpy.mockRestore();
     });
+
+    it('reports an unknown CPU model when os.cpus() comes back empty', async () => {
+        const os = await import('node:os');
+        const cpusSpy = vi.spyOn(os.default, 'cpus').mockReturnValue([]);
+
+        const { res, captured } = makeRes();
+        await handleServerInfo({} as Request, res);
+
+        const cpu = captured.body!.cpu as Record<string, unknown>;
+        expect(cpu.model).toBe('Unknown');
+        expect(cpu.cores).toBe(0);
+
+        cpusSpy.mockRestore();
+    });
 });

extensions/thumbnails.test.ts

@@ -3,6 +3,7 @@ import {
     PutObjectCommand,
     type S3Client,
 } from '@aws-sdk/client-s3';
+import crypto from 'node:crypto';
 import {
     afterAll,
     beforeAll,
@@ -14,6 +15,7 @@ import {
 import { PuterServer } from '../src/backend/server.ts';
 import { setupTestServer } from '../src/backend/testUtil.ts';
 import {
+    handleFsCopyNodeThumbnail,
     handleFsRemoveNodeThumbnail,
     handleThumbnailCreated,
     handleThumbnailRead,
@@ -26,6 +28,9 @@ const TINY_PNG_BASE64 =
 
 const BUCKET = 'puter-local';
 
+// Keys the extension will accept back: its own `thumbnails/<uuid>` namespace.
+const mintedKey = () => `thumbnails/${crypto.randomUUID()}`;
+
 const streamToBuffer = async (
     body: { transformToByteArray: () => Promise<Uint8Array> } | undefined,
 ): Promise<Buffer> => {
@@ -41,7 +46,7 @@ describe('thumbnails extension — handleThumbnailCreated', () => {
     });
 
     afterAll(async () => {
-        await server.shutdown();
+        await server?.shutdown();
     });
 
     it('uploads a valid data: URL thumbnail to S3 and rewrites event.url to an s3:// pointer', async () => {
@@ -108,7 +113,7 @@ describe('thumbnails extension — handleThumbnailUploadPrepare', () => {
     });
 
     afterAll(async () => {
-        await server.shutdown();
+        await server?.shutdown();
     });
 
     it('returns early when event has no items array', async () => {
@@ -188,14 +193,14 @@ describe('thumbnails extension — handleThumbnailRead', () => {
     });
 
     afterAll(async () => {
-        await server.shutdown();
+        await server?.shutdown();
     });
 
     it('rewrites an s3:// thumbnail into a presigned https URL', async () => {
         // Seed an object so the presigned URL points at something real
         // (the signer itself doesn't validate existence, but this keeps
         // the test honest).
-        const key = 'thumb-read-test';
+        const key = mintedKey();
         await s3.send(
             new PutObjectCommand({
                 Bucket: BUCKET,
@@ -220,6 +225,57 @@ describe('thumbnails extension — handleThumbnailRead', () => {
         expect((entry.thumbnail as string).startsWith('http')).toBe(true);
     });
 
+    // `fsentries.thumbnail` is writable through the FS API, so a stored
+    // pointer is attacker input. Signing one the extension didn't mint would
+    // hand out a presigned read of an arbitrary object — including another
+    // user's file, whose key is its fsentry uuid in this same bucket.
+    it.each([
+        // Shaped exactly like an fs object key (and like a legacy thumbnail
+        // row) — indistinguishable from a planted pointer, so it fails closed.
+        [
+            "another user's file object",
+            `s3://${BUCKET}/${crypto.randomUUID()}`,
+        ],
+        [
+            'a key outside the thumbnails namespace',
+            `s3://${BUCKET}/secrets/dump`,
+        ],
+        [
+            'a namespace-lookalike key',
+            `s3://${BUCKET}/thumbnails/../${crypto.randomUUID()}`,
+        ],
+        ['a non-uuid inside the namespace', `s3://${BUCKET}/thumbnails/etc`],
+    ])('refuses to presign a pointer naming %s', async (_label, thumbnail) => {
+        const entry: Record<string, unknown> = { thumbnail };
+        await handleThumbnailRead(entry, {
+            s3,
+            s3Presign,
+            bucketName: BUCKET,
+            bucketEndpoint: 'http://127.0.0.1:4566/puter-local/',
+            db: stubDb,
+        });
+        expect(entry.thumbnail).toBeNull();
+    });
+
+    it('signs against its own bucket, ignoring the one in the pointer', async () => {
+        const key = mintedKey();
+        const entry: Record<string, unknown> = {
+            thumbnail: `s3://attacker-named-bucket/${key}`,
+        };
+        await handleThumbnailRead(entry, {
+            s3,
+            s3Presign,
+            bucketName: BUCKET,
+            bucketEndpoint: 'http://127.0.0.1:4566/puter-local/',
+            db: stubDb,
+        });
+        // Signed for OUR bucket; `attacker-named-bucket` never reached S3.
+        const signed = entry.thumbnail as string;
+        expect(signed.startsWith('http')).toBe(true);
+        expect(signed).not.toContain('attacker-named-bucket');
+        expect(signed).toContain(BUCKET);
+    });
+
     it('leaves the thumbnail untouched when not s3/https/data', async () => {
         const entry: Record<string, unknown> = { thumbnail: 'about:blank' };
         await handleThumbnailRead(entry, {
@@ -281,11 +337,11 @@ describe('thumbnails extension — handleFsRemoveNodeThumbnail', () => {
     });
 
     afterAll(async () => {
-        await server.shutdown();
+        await server?.shutdown();
     });
 
     it('deletes the S3 object referenced by an s3:// thumbnail URL', async () => {
-        const key = 'thumb-remove-test';
+        const key = mintedKey();
         await s3.send(
             new PutObjectCommand({
                 Bucket: BUCKET,
@@ -297,7 +353,7 @@ describe('thumbnails extension — handleFsRemoveNodeThumbnail', () => {
 
         await handleFsRemoveNodeThumbnail(
             { target: { thumbnail: `s3://${BUCKET}/${key}` } },
-            { s3 },
+            { s3, bucketName: BUCKET },
         );
 
         // GetObject should now error because the key was deleted.
@@ -306,15 +362,147 @@ describe('thumbnails extension — handleFsRemoveNodeThumbnail', () => {
         ).rejects.toThrow();
     });
 
+    // The destructive half of the same confused deputy: the stored pointer
+    // decides which object is deleted, so a key the extension didn't mint
+    // must never reach DeleteObject.
+    it('does not delete an object the pointer names but we did not mint', async () => {
+        const victimKey = crypto.randomUUID(); // shaped like an fs object key
+        await s3.send(
+            new PutObjectCommand({
+                Bucket: BUCKET,
+                Key: victimKey,
+                Body: Buffer.from(TINY_PNG_BASE64, 'base64'),
+                ContentType: 'image/png',
+            }),
+        );
+
+        await handleFsRemoveNodeThumbnail(
+            { target: { thumbnail: `s3://${BUCKET}/${victimKey}` } },
+            { s3, bucketName: BUCKET },
+        );
+
+        const survivor = await s3.send(
+            new GetObjectCommand({ Bucket: BUCKET, Key: victimKey }),
+        );
+        expect(survivor.ContentType).toBe('image/png');
+    });
+
     it('is a no-op when the target has no thumbnail', async () => {
         // Should not throw or attempt a delete.
-        await handleFsRemoveNodeThumbnail({ target: {} }, { s3 });
+        await handleFsRemoveNodeThumbnail(
+            { target: {} },
+            { s3, bucketName: BUCKET },
+        );
     });
 
     it('is a no-op when the thumbnail URL is not an s3:// pointer', async () => {
         await handleFsRemoveNodeThumbnail(
             { target: { thumbnail: 'https://cdn.example.com/x.png' } },
-            { s3 },
+            { s3, bucketName: BUCKET },
         );
     });
 });
+
+describe('thumbnails extension — handleFsCopyNodeThumbnail', () => {
+    let server: PuterServer;
+    let s3: S3Client;
+
+    beforeAll(async () => {
+        server = await setupTestServer();
+        s3 = server.clients.s3.get();
+    });
+
+    afterAll(async () => {
+        await server?.shutdown();
+    });
+
+    it('duplicates the shared thumbnail object and repoints the copied row', async () => {
+        const sourceKey = mintedKey();
+        const body = Buffer.from(TINY_PNG_BASE64, 'base64');
+        await s3.send(
+            new PutObjectCommand({
+                Bucket: BUCKET,
+                Key: sourceKey,
+                Body: body,
+                ContentType: 'image/png',
+            }),
+        );
+
+        const copyUuid = crypto.randomUUID();
+        const db = { write: vi.fn().mockResolvedValue(undefined) };
+        await handleFsCopyNodeThumbnail(
+            {
+                copy: {
+                    thumbnail: `s3://${BUCKET}/${sourceKey}`,
+                    uuid: copyUuid,
+                },
+            },
+            { s3, bucketName: BUCKET, db },
+        );
+
+        // The copied row was repointed at a fresh object...
+        expect(db.write).toHaveBeenCalledTimes(1);
+        const [, params] = db.write.mock.calls[0] as [string, [string, string]];
+        const [newPointer, updatedUuid] = params;
+        expect(updatedUuid).toBe(copyUuid);
+        expect(newPointer.startsWith(`s3://${BUCKET}/thumbnails/`)).toBe(true);
+        expect(newPointer).not.toBe(`s3://${BUCKET}/${sourceKey}`);
+
+        // ...whose content matches, while the source object survives — so
+        // deleting either entry can no longer break the other's thumbnail.
+        const newKey = newPointer.slice(`s3://${BUCKET}/`.length);
+        const duplicated = await s3.send(
+            new GetObjectCommand({ Bucket: BUCKET, Key: newKey }),
+        );
+        expect(
+            (await streamToBuffer(duplicated.Body as never)).equals(body),
+        ).toBe(true);
+        const original = await s3.send(
+            new GetObjectCommand({ Bucket: BUCKET, Key: sourceKey }),
+        );
+        expect(original.ContentType).toBe('image/png');
+    });
+
+    it('drops the pointer when the shared object is already gone', async () => {
+        const copyUuid = crypto.randomUUID();
+        const db = { write: vi.fn().mockResolvedValue(undefined) };
+        await handleFsCopyNodeThumbnail(
+            {
+                copy: {
+                    thumbnail: `s3://${BUCKET}/${mintedKey()}`, // never uploaded
+                    uuid: copyUuid,
+                },
+            },
+            { s3, bucketName: BUCKET, db },
+        );
+
+        expect(db.write).toHaveBeenCalledTimes(1);
+        const [sql, params] = db.write.mock.calls[0] as [string, [string]];
+        expect(sql).toContain('NULL');
+        expect(params).toEqual([copyUuid]);
+    });
+
+    it('does not duplicate an object the pointer names but we did not mint', async () => {
+        const foreignKey = crypto.randomUUID(); // shaped like an fs object key
+        const db = { write: vi.fn().mockResolvedValue(undefined) };
+        await handleFsCopyNodeThumbnail(
+            {
+                copy: {
+                    thumbnail: `s3://${BUCKET}/${foreignKey}`,
+                    uuid: crypto.randomUUID(),
+                },
+            },
+            { s3, bucketName: BUCKET, db },
+        );
+        expect(db.write).not.toHaveBeenCalled();
+    });
+
+    it('is a no-op when the copy has no thumbnail', async () => {
+        const db = { write: vi.fn().mockResolvedValue(undefined) };
+        await handleFsCopyNodeThumbnail(
+            { copy: { thumbnail: null, uuid: crypto.randomUUID() } },
+            { s3, bucketName: BUCKET, db },
+        );
+        expect(db.write).not.toHaveBeenCalled();
+    });
+});

extensions/thumbnails.ts

@@ -1,4 +1,5 @@
 import {
+    CopyObjectCommand,
     DeleteObjectCommand,
     GetObjectCommand,
     PutObjectCommand,
@@ -13,6 +14,54 @@ const clients = extension.import('client');
 const MAX_THUMBNAIL_BYTES = 2 * 1024 * 1024;
 const MAX_THUMBNAIL_PIXELS = 64e6;
 
+// Namespace every object this extension writes. An fs object's key is its
+// bare fsentry uuid and the default config points `thumbnailStore.name` at
+// the same bucket as `s3_bucket`, so without a prefix of our own there is no
+// way to tell a thumbnail we minted from any other object in the deployment.
+const THUMBNAIL_KEY_PREFIX = 'thumbnails/';
+const UUID_PATTERN =
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+const mintThumbnailKey = (): string =>
+    `${THUMBNAIL_KEY_PREFIX}${crypto.randomUUID()}`;
+
+/**
+ * Extract the object key from a stored thumbnail pointer, or null when the
+ * pointer isn't one this extension minted.
+ *
+ * `fsentries.thumbnail` is writable through the FS API, so neither half of the
+ * stored string is trusted: the bucket is discarded (callers always pass their
+ * own) and the key must sit under {@link THUMBNAIL_KEY_PREFIX} with a random
+ * uuid. Honouring an arbitrary key would lend this extension's storage
+ * credentials to whatever object the caller named — in the shared-bucket layout
+ * that is every user's file, since an fs object's key is its fsentry uuid.
+ * Legacy bare-uuid thumbnails fail the check and are treated as absent; they
+ * are indistinguishable from a planted pointer, so there is nothing safer to do
+ * with them than stop signing them.
+ */
+const resolveThumbnailKey = (pointer: string): string | null => {
+    let key: string;
+    if (pointer.startsWith('s3://')) {
+        const rest = pointer.slice('s3://'.length);
+        const slash = rest.indexOf('/');
+        if (slash === -1) return null;
+        key = rest.slice(slash + 1);
+    } else {
+        let pathname: string;
+        try {
+            pathname = new URL(pointer).pathname;
+        } catch {
+            return null;
+        }
+        const segments = pathname.replace(/^\/+/, '').split('/');
+        segments.shift(); // bucket
+        key = segments.join('/');
+    }
+    if (!key.startsWith(THUMBNAIL_KEY_PREFIX)) return null;
+    const id = key.slice(THUMBNAIL_KEY_PREFIX.length);
+    return UUID_PATTERN.test(id) ? key : null;
+};
+
 // S3 client + bucket config — lazily resolved after boot from config.
 let s3Client: S3Client | null = null;
 let s3PresignClient: S3Client | null = null;
@@ -112,7 +161,7 @@ export async function handleThumbnailCreated(
         return;
     }
 
-    const key = crypto.randomUUID();
+    const key = mintThumbnailKey();
     event.url = `s3://${deps.bucketName}/${key}`;
 
     await deps.s3.send(
@@ -151,7 +200,7 @@ export const handleThumbnailUploadPrepare = async (
                 continue;
         }
 
-        const key = crypto.randomUUID();
+        const key = mintThumbnailKey();
         const command = new PutObjectCommand({
             Bucket: deps.bucketName,
             Key: key,
@@ -178,27 +227,27 @@ export const handleThumbnailRead = async (
     if (typeof thumb !== 'string' || !thumb) return;
     const presignClient = deps.s3Presign;
 
-    if (thumb.startsWith('s3://')) {
-        const [bucket, key] = thumb.slice(5).split('/');
-        entry.thumbnail = await getSignedUrl(
-            presignClient,
-            new GetObjectCommand({ Bucket: bucket, Key: key }),
-            { expiresIn: 604800 },
-        );
-    } else if (
-        thumb.startsWith('https') &&
-        thumb.includes(new URL(deps.bucketEndpoint).hostname)
-    ) {
+    if (
+        thumb.startsWith('s3://') ||
         // Legacy format — remove after full migration
-        const [bucket, key] = new URL(thumb).pathname.slice(1).split('/');
+        (thumb.startsWith('https') &&
+            thumb.includes(new URL(deps.bucketEndpoint).hostname))
+    ) {
+        const key = resolveThumbnailKey(thumb);
+        if (!key) {
+            // Not a pointer we minted — refuse to sign it rather than hand
+            // out a presigned read of whatever object it names.
+            entry.thumbnail = null;
+            return;
+        }
         entry.thumbnail = await getSignedUrl(
             presignClient,
-            new GetObjectCommand({ Bucket: bucket, Key: key }),
+            new GetObjectCommand({ Bucket: deps.bucketName, Key: key }),
             { expiresIn: 604800 },
         );
     } else if (thumb.startsWith('data')) {
         // Inline data-URL migration: upload to S3 and update the DB entry.
-        const key = crypto.randomUUID();
+        const key = mintThumbnailKey();
         const { mimeType, data } = base64ParseDataUrl(thumb);
         const newUrl = `s3://${deps.bucketName}/${key}`;
 
@@ -232,15 +281,72 @@ export const handleThumbnailRead = async (
     }
 };
 
-export const handleFsRemoveNodeThumbnail = async (
-    payload: { target: Record<string, unknown> },
-    deps: { s3: S3Client },
+export const handleFsCopyNodeThumbnail = async (
+    payload: { copy?: { thumbnail?: string | null; uuid?: string } | null },
+    deps: {
+        s3: S3Client;
+        bucketName: string;
+        db: { write: (sql: string, params: unknown[]) => Promise<unknown> };
+    },
 ): Promise<void> => {
-    const thumbnailUrl = payload.target.thumbnail as string | undefined;
-    if (!thumbnailUrl || !thumbnailUrl.startsWith('s3://')) return;
+    const copy = payload.copy;
+    const thumbnailUrl = copy?.thumbnail;
+    if (!copy || !copy.uuid || typeof thumbnailUrl !== 'string') return;
 
-    const [bucket, key] = thumbnailUrl.slice(5).split('/');
-    await deps.s3.send(new DeleteObjectCommand({ Bucket: bucket, Key: key }));
+    // Same trust rule as the read and remove paths: only touch objects this
+    // extension minted.
+    const sourceKey = resolveThumbnailKey(thumbnailUrl);
+    if (!sourceKey) return;
+
+    // The copied row points at the SAME S3 object as its source, and
+    // fs.remove.node deletes the pointed-to object — so the first removal
+    // among the sharers (an overwrite, a trash purge) would break every
+    // other sharer's thumbnail. Give the copy an object of its own.
+    const newKey = mintThumbnailKey();
+    try {
+        await deps.s3.send(
+            new CopyObjectCommand({
+                Bucket: deps.bucketName,
+                CopySource: `${deps.bucketName}/${sourceKey}`,
+                Key: newKey,
+            }),
+        );
+    } catch (err) {
+        // The shared object is already gone (e.g. a sharer was removed
+        // before this fix existed) — the pointer is dead either way, so
+        // drop it rather than leave the row advertising a thumbnail it
+        // doesn't have.
+        await deps.db.write(
+            'UPDATE `fsentries` SET `thumbnail` = NULL WHERE `uuid` = ?',
+            [copy.uuid],
+        );
+        console.warn('[thumbnails] failed to duplicate thumbnail on copy', err);
+        return;
+    }
+
+    await deps.db.write(
+        'UPDATE `fsentries` SET `thumbnail` = ? WHERE `uuid` = ?',
+        [`s3://${deps.bucketName}/${newKey}`, copy.uuid],
+    );
+};
+
+export const handleFsRemoveNodeThumbnail = async (
+    payload: { target: { thumbnail?: string | null } },
+    deps: { s3: S3Client; bucketName: string },
+): Promise<void> => {
+    const thumbnailUrl = payload.target.thumbnail;
+    if (!thumbnailUrl) return;
+
+    // Same trust rule as the read path, and load-bearing for the same reason:
+    // the pointer decides which object gets deleted, so a key we didn't mint
+    // would let the owner of one file destroy an object belonging to someone
+    // else just by naming it here.
+    const key = resolveThumbnailKey(thumbnailUrl);
+    if (!key) return;
+
+    await deps.s3.send(
+        new DeleteObjectCommand({ Bucket: deps.bucketName, Key: key }),
+    );
 };
 
 extension.on(
@@ -279,12 +385,29 @@ extension.on('thumbnail.read', async (_key, entry: Record<string, unknown>) => {
     });
 });
 
+// -- fs.copy.node ----------------------------------------------------
+// A copied entry initially shares its source's thumbnail object; duplicate
+// it so removing either entry can't break the other's thumbnail.
+
+extension.on('fs.copy.node', async (_key, payload) => {
+    await handleFsCopyNodeThumbnail(
+        payload as {
+            copy?: { thumbnail?: string | null; uuid?: string } | null;
+        },
+        {
+            s3: getClient(),
+            bucketName: thumbnailBucketName,
+            db: clients.db,
+        },
+    );
+});
+
 // -- fs.remove.node --------------------------------------------------
 // Delete S3 thumbnail when the file is removed.
 
-extension.on(
-    'fs.remove.node',
-    async (_key, payload: { target: Record<string, unknown> }) => {
-        await handleFsRemoveNodeThumbnail(payload, { s3: getClient() });
-    },
-);
+extension.on('fs.remove.node', async (_key, payload) => {
+    await handleFsRemoveNodeThumbnail(payload, {
+        s3: getClient(),
+        bucketName: thumbnailBucketName,
+    });
+});

extensions/whoami.test.ts

@@ -51,7 +51,7 @@ beforeAll(async () => {
 });
 
 afterAll(async () => {
-    await server.shutdown();
+    await server?.shutdown();
 });
 
 const seedUser = async () => {
@@ -109,6 +109,9 @@ describe('whoami extension — handleWhoami', () => {
         expect(body.oidc_only).toBe(false);
         // is_user_token is present (true) for user actors.
         expect(body.is_user_token).toBe(true);
+        // Account creation time, in unix seconds.
+        expect(typeof body.created_ts).toBe('number');
+        expect(body.created_ts).toBeGreaterThan(0);
         // `directories` is only sent to user actors — confirm it’s present.
         expect(body.directories).toBeDefined();
         // taskbar_items is only sent to user actors.
@@ -132,7 +135,7 @@ describe('whoami extension — handleWhoami', () => {
         expect(flags.payment_bypass).toBeUndefined();
     });
 
-    it('strips desktop_bg_* and human_readable_age fields for app actors', async () => {
+    it('strips desktop_bg_*, created_ts and human_readable_age fields for app actors', async () => {
         const user = await seedUser();
         const { res, captured } = makeRes();
 
@@ -154,6 +157,8 @@ describe('whoami extension — handleWhoami', () => {
         expect(body.desktop_bg_color).toBeUndefined();
         expect(body.desktop_bg_fit).toBeUndefined();
         expect(body.human_readable_age).toBeUndefined();
+        // Account age, in either form, is not exposed to apps.
+        expect(body.created_ts).toBeUndefined();
         // Directories are user-only.
         expect(body.directories).toBeUndefined();
     });

extensions/whoami.ts

@@ -14,6 +14,15 @@ const timeago = (() => {
     return new TimeAgo('en-US');
 })();
 
+// User timestamps come off the DB as SQL datetime strings; the wire format
+// for all of them is unix seconds. Unparseable values are dropped rather
+// than sent as NaN.
+const toUnixSeconds = (value: unknown): number | undefined => {
+    if (!value) return undefined;
+    const ms = new Date(value as string | number | Date).getTime();
+    return Number.isNaN(ms) ? undefined : Math.round(ms / 1000);
+};
+
 // Allowlist of `config.feature_flags` keys safe to surface via /whoami.
 // Anything not listed here stays server-side, so internal flags
 // (payment_bypass, staff_only_*, etc.) cannot leak by accident. Add a
@@ -98,6 +107,7 @@ export const handleWhoami = async (
             : undefined,
         otp: !!user.otp_enabled,
         feature_flags,
+        created_ts: toUnixSeconds(user.timestamp),
         human_readable_age: user.timestamp
             ? timeago.format(new Date(user.timestamp as string))
             : null,
@@ -141,14 +151,9 @@ export const handleWhoami = async (
     }
 
     // Last activity
-    if (user.last_activity_ts) {
-        try {
-            details.last_activity_ts = Math.round(
-                new Date(user.last_activity_ts as string).getTime() / 1000,
-            );
-        } catch {
-            /* ignore parse error */
-        }
+    const lastActivityTs = toUnixSeconds(user.last_activity_ts);
+    if (lastActivityTs !== undefined) {
+        details.last_activity_ts = lastActivityTs;
     }
 
     // Strip sensitive fields for app actors
@@ -164,6 +169,7 @@ export const handleWhoami = async (
         delete details.desktop_bg_color;
         delete details.desktop_bg_fit;
         delete details.human_readable_age;
+        delete details.created_ts;
         delete details.is_user_token;
         delete details.metadata;
     }
@@ -183,8 +189,7 @@ export const handleWhoami = async (
     }
 
     const subscription = details.subscription as
-        | { offering?: Record<string, unknown> }
-        | undefined;
+        { offering?: Record<string, unknown> } | undefined;
     if (subscription?.offering) {
         delete subscription.offering.group;
         delete subscription.offering.benefits;
@@ -196,6 +201,23 @@ export const handleWhoami = async (
 
 extension.get(
     '/whoami',
-    { subdomain: 'api', requireAuth: true, allowUnconfirmed: true },
+    {
+        subdomain: 'api',
+        requireAuth: true,
+        allowUnconfirmed: true,
+        // The GUI polls this, and each call fans out to every `whoami`
+        // event listener — so it costs more than the response suggests.
+        //
+        // It is also the call everything else leans on to find out who it is
+        // talking to, so it rides along with unrelated work rather than
+        // arriving at its own pace: the ceiling has to clear whatever the
+        // busiest session is doing, not what a person clicks.
+        rateLimit: {
+            scope: 'whoami',
+            limit: 1_800,
+            window: 60_000,
+            key: 'user',
+        },
+    },
     handleWhoami,
 );

install.ps1

@@ -11,7 +11,7 @@
 # What this does, in order:
 #   1. Checks that docker (with the compose plugin) exists.
 #   2. Creates ./puter-selfhosted/ (override with $env:PUTER_DIR).
-#   3. Downloads docker-compose.yml + nginx.conf from the OSS repo.
+#   3. Downloads docker-compose.yml + caddy/Caddyfile from the OSS repo.
 #   4. Generates fresh secrets and writes .env + puter/config/config.json.
 #   5. Runs `docker compose up -d` and prints how to find the admin password.
 #
@@ -23,7 +23,7 @@
 #   PUTER_DIR     install directory                       (default: ./puter-selfhosted)
 #   PUTER_URL     base URL to fetch docker-compose.yml    (default: GitHub raw, main branch)
 #   PUTER_DOMAIN  domain Puter will serve on              (default: puter.localhost)
-#   PUTER_PORT    HTTP port for nginx                     (default: 80)
+#   PUTER_PORT    HTTP port for Caddy                     (default: 80)
 #   PUTER_FORCE   set to 1 to overwrite existing .env / config.json
 
 [CmdletBinding()]
@@ -77,10 +77,10 @@ if ($LASTEXITCODE -ne 0) {
 # ── Step 2: install dir ─────────────────────────────────────────────
 $null = New-Item -ItemType Directory -Force -Path $PuterDir
 Set-Location $PuterDir
-$null = New-Item -ItemType Directory -Force -Path 'puter/config', 'puter/data', 'puter/tls'
+$null = New-Item -ItemType Directory -Force -Path 'puter/config', 'puter/data', 'puter/data/caddy', 'puter/tls'
 Write-Log "install dir: $((Get-Location).Path)"
 
-# ── Step 3: docker-compose.yml + nginx config ──────────────────────
+# ── Step 3: docker-compose.yml + Caddy config ──────────────────────
 Write-Log "downloading docker-compose.yml from $PuterUrl"
 try {
     Invoke-WebRequest -Uri "$PuterUrl/docker-compose.yml" -OutFile 'docker-compose.yml' -UseBasicParsing
@@ -88,17 +88,19 @@ try {
     Die "could not fetch $PuterUrl/docker-compose.yml — $_"
 }
 
-Write-Log "downloading nginx/nginx.conf from $PuterUrl"
-$null = New-Item -ItemType Directory -Force -Path 'nginx'
+# The Caddyfile is domain-agnostic — it answers on every Host and leaves
+# the subdomain routing to Puter — so there's nothing to template in.
+Write-Log "downloading caddy/Caddyfile from $PuterUrl"
+$null = New-Item -ItemType Directory -Force -Path 'caddy'
 # If the path was previously auto-created as a directory by a failed
 # `compose up`, remove it so we can write the file there.
-if (Test-Path 'nginx/nginx.conf' -PathType Container) {
-    Remove-Item 'nginx/nginx.conf' -Recurse -Force
+if (Test-Path 'caddy/Caddyfile' -PathType Container) {
+    Remove-Item 'caddy/Caddyfile' -Recurse -Force
 }
 try {
-    Invoke-WebRequest -Uri "$PuterUrl/nginx/nginx.conf" -OutFile 'nginx/nginx.conf' -UseBasicParsing
+    Invoke-WebRequest -Uri "$PuterUrl/caddy/Caddyfile" -OutFile 'caddy/Caddyfile' -UseBasicParsing
 } catch {
-    Die "could not fetch $PuterUrl/nginx/nginx.conf — $_"
+    Die "could not fetch $PuterUrl/caddy/Caddyfile — $_"
 }
 
 # ── Step 4: secrets, .env, config.json ──────────────────────────────
@@ -121,7 +123,8 @@ if ($writeConfig) {
 
     $envContent = @"
 HTTP_PORT=$PuterPort
-# HTTPS_PORT=443     # uncomment after enabling TLS (see doc/selfhosting/full-stack.md)
+# HTTPS_PORT=443     # uncomment after enabling TLS in caddy/Caddyfile
+#                    # (see "Step 3 — TLS" in doc/self-hosting.md)
 
 MARIADB_ROOT_PASSWORD=$mariadbRootPw
 MARIADB_DATABASE=puter
@@ -205,4 +208,4 @@ Write-Log "    cd $PuterDir; docker compose logs -f puter"
 Write-Log ''
 Write-Log "open http://${PuterDomain}:${PuterPort} once the puter container is healthy."
 Write-Log 'first-boot admin password is logged once — grab it with:'
-Write-Log "    cd $PuterDir; docker compose logs puter | Select-String password"
+Write-Log "    cd $PuterDir; docker compose logs puter | Select-String password"

install.sh

@@ -7,7 +7,8 @@
 # What this does, in order:
 #   1. Checks that docker (with the compose plugin), curl, and openssl exist.
 #   2. Creates ./puter-selfhosted/ (override with PUTER_DIR=...).
-#   3. Downloads docker-compose.yml from the OSS repo (raw.githubusercontent.com).
+#   3. Downloads docker-compose.yml + caddy/Caddyfile from the OSS repo
+#      (raw.githubusercontent.com).
 #   4. Generates fresh secrets and writes .env + puter/config/config.json.
 #   5. Runs `docker compose up -d` and prints the first-boot admin password.
 #
@@ -19,15 +20,17 @@
 #   PUTER_DIR         install directory                   (default: ./puter-selfhosted)
 #   PUTER_URL         base URL to fetch docker-compose.yml (default: GitHub raw, main branch)
 #   PUTER_DOMAIN      domain Puter will serve on           (default: puter.localhost)
-#   PUTER_PORT        HTTP port for nginx                  (default: 80)
+#   PUTER_PORT        HTTP port for Caddy                  (default: 80)
 #   PUTER_PROTOCOL    public scheme: http | https          (default: http)
-#                     Set https when a TLS-terminating reverse proxy (Caddy,
-#                     Traefik, nginx, a cloud LB) sits in front — Puter then
-#                     builds https:// origins, S3 URLs, and redirects. See
-#                     "Running behind your own reverse proxy" in doc/self-hosting.md.
+#                     Set https once TLS is terminating in front of Puter —
+#                     either the bundled Caddy with your certs (see "Step 3 —
+#                     TLS" in doc/self-hosting.md) or your own proxy (Traefik,
+#                     a cloud LB). Puter then builds https:// origins, S3
+#                     URLs, and redirects. Leave it http and the installer
+#                     serves plain HTTP on PUTER_PORT.
 #   PUTER_TRUST_PROXY number of reverse-proxy hops in front (default: 1)
-#                     1 = the bundled nginx (or a single external proxy);
-#                     2 = two hops (e.g. Cloudflare → your proxy → Puter).
+#                     1 = the bundled Caddy (or a single external proxy);
+#                     2 = two hops (e.g. Cloudflare → Caddy → Puter).
 #   PUTER_ENV         prod | dev                            (default: prod)
 #   PUTER_FORCE       set to 1 to overwrite existing .env / config.json
 
@@ -72,25 +75,27 @@ mkdir -p puter/config puter/data puter/tls
 # bind-mount roots sidesteps the mismatch without guessing each image's
 # internal UID. (Docker Desktop on macOS/Windows papers over this with
 # its VM layer; native Linux docker on Debian/Alpine doesn't.)
-mkdir -p puter/data/valkey puter/data/mariadb puter/data/dynamo puter/data/s3 puter/data/puter
-chmod 0777 puter/data/valkey puter/data/mariadb puter/data/dynamo puter/data/s3 puter/data/puter
+mkdir -p puter/data/valkey puter/data/mariadb puter/data/dynamo puter/data/s3 puter/data/puter puter/data/caddy
+chmod 0777 puter/data/valkey puter/data/mariadb puter/data/dynamo puter/data/s3 puter/data/puter puter/data/caddy
 log "install dir: $(pwd)"
 
-# ── Step 3: docker-compose.yml + nginx config ──────────────────────
+# ── Step 3: docker-compose.yml + Caddy config ──────────────────────
 log "downloading docker-compose.yml from $PUTER_URL"
 curl -fsSL "$PUTER_URL/docker-compose.yml" -o docker-compose.yml \
     || die "could not fetch $PUTER_URL/docker-compose.yml"
 
-# nginx is mounted as `./nginx/nginx.conf:/etc/nginx/nginx.conf:ro` — if
+# Caddy is mounted as `./caddy/Caddyfile:/etc/caddy/Caddyfile:ro,z` — if
 # the host file is missing, docker silently creates a directory at that
 # path and the mount fails with "not a directory" at container start.
-log "downloading nginx/nginx.conf from $PUTER_URL"
-mkdir -p nginx
+# The Caddyfile is domain-agnostic — it answers on every Host and leaves
+# the subdomain routing to Puter — so there's nothing to template in.
+log "downloading caddy/Caddyfile from $PUTER_URL"
+mkdir -p caddy
 # If the path was previously auto-created as a dir by a failed `compose up`,
 # remove it so curl can write the file.
-[ -d nginx/nginx.conf ] && rmdir nginx/nginx.conf 2>/dev/null || true
-curl -fsSL "$PUTER_URL/nginx/nginx.conf" -o nginx/nginx.conf \
-    || die "could not fetch $PUTER_URL/nginx/nginx.conf"
+[ -d caddy/Caddyfile ] && rmdir caddy/Caddyfile 2>/dev/null || true
+curl -fsSL "$PUTER_URL/caddy/Caddyfile" -o caddy/Caddyfile \
+    || die "could not fetch $PUTER_URL/caddy/Caddyfile"
 
 # ── Step 4: secrets, .env, config.json ──────────────────────────────
 write_config=1
@@ -113,7 +118,8 @@ if [ "$write_config" = "1" ]; then
 
     cat > .env <<EOF
 HTTP_PORT=$PUTER_PORT
-# HTTPS_PORT=443     # uncomment after enabling TLS (see doc/selfhosting/full-stack.md)
+# HTTPS_PORT=443     # uncomment after enabling TLS in caddy/Caddyfile
+#                    # (see "Step 3 — TLS" in doc/self-hosting.md)
 
 MARIADB_ROOT_PASSWORD=$MARIADB_ROOT_PASSWORD
 MARIADB_DATABASE=puter
@@ -190,6 +196,18 @@ EOF
 EOF
 fi
 
+# `https` only works if something in front is actually terminating it. The
+# bundled Caddy does that from ./puter/tls once you enable its `:443` block
+# (see "Step 3 — TLS" in doc/self-hosting.md); your own edge proxy is fine
+# too. Neither in place means Puter hands out https:// URLs for an endpoint
+# that only speaks HTTP — broken logins and mixed content.
+if [ "$PUTER_PROTOCOL" = "https" ] && [ ! -f puter/tls/fullchain.pem ]; then
+    warn "PUTER_PROTOCOL=https but ./puter/tls/fullchain.pem is missing."
+    warn "The bundled Caddy is still serving plain HTTP on port $PUTER_PORT."
+    warn "Either drop a wildcard cert into ./puter/tls and uncomment the :443"
+    warn "block in caddy/Caddyfile, or terminate TLS in your own proxy."
+fi
+
 # ── Step 5: bring it up ─────────────────────────────────────────────
 log "docker compose up -d"
 docker compose up -d

nginx/nginx.conf

@@ -1,135 +0,0 @@
-# Reverse proxy in front of Puter — mirrors what the prod ALB does:
-# accepts every Host header, forwards to the Puter container, and lets
-# the Puter app handle subdomain-based routing internally (api.*,
-# site.*, app.*, etc).
-#
-# To enable TLS:
-#   1. Drop your fullchain.pem + privkey.pem into ./puter/tls/.
-#   2. Uncomment the 443 server{} block below.
-#   3. Update server_name to your domain (and wildcard subdomains).
-
-worker_processes auto;
-events {
-    worker_connections 4096;
-}
-
-http {
-    # Required for Puter's WebSocket / socket.io upgrades.
-    map $http_upgrade $connection_upgrade {
-        default upgrade;
-        '' close;
-    }
-
-    # Rough size cap that mirrors prod ALB defaults; tune for your
-    # uploads. Puter chunks large uploads, so 1 GiB per request is plenty.
-    client_max_body_size 1024m;
-    proxy_read_timeout 600s;
-    proxy_send_timeout 600s;
-    proxy_buffering off;
-    server_tokens off;
-
-    upstream puter_backend {
-        server puter:4100;
-        keepalive 32;
-    }
-
-    upstream s3_backend {
-        # RustFS — see `s3` service in docker-compose.full.yml. Browsers
-        # PUT/GET here for presigned-URL uploads / downloads. Routed via
-        # the `s3.<domain>` subdomain so signature verification works
-        # (Host header preserved end-to-end) and so HTTPS stays clean
-        # (no mixed-content from a port-9000 host publish).
-        server s3:9000;
-        keepalive 32;
-    }
-
-    # ── HTTP (port 80) ─────────────────────────────────────────────
-    server {
-        listen 80;
-        listen [::]:80;
-        server_name ~^s3\.;
-
-        location / {
-            proxy_pass http://s3_backend;
-            proxy_http_version 1.1;
-            # Critical: preserve the original Host so RustFS validates
-            # the request against the same host the URL was signed for.
-            proxy_set_header Host $host;
-            proxy_set_header X-Real-IP $remote_addr;
-            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-            proxy_set_header X-Forwarded-Proto $scheme;
-        }
-    }
-
-    server {
-        listen 80 default_server;
-        listen [::]:80 default_server;
-        server_name _;
-
-        # Note: when you enable TLS, replace this block with a redirect:
-        #   return 301 https://$host$request_uri;
-        location / {
-            proxy_pass http://puter_backend;
-            proxy_http_version 1.1;
-            proxy_set_header Host $host;
-            proxy_set_header X-Real-IP $remote_addr;
-            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-            proxy_set_header X-Forwarded-Proto $scheme;
-            proxy_set_header X-Forwarded-Host $host;
-            proxy_set_header X-Forwarded-Port $server_port;
-            proxy_set_header Upgrade $http_upgrade;
-            proxy_set_header Connection $connection_upgrade;
-        }
-    }
-
-    # ── HTTPS (port 443) — uncomment after dropping certs in ./puter/tls/ ─
-    # server {
-    #     listen 443 ssl;
-    #     listen [::]:443 ssl;
-    #     http2 on;
-    #     server_name ~^s3\.;
-    #
-    #     ssl_certificate     /etc/nginx/tls/fullchain.pem;
-    #     ssl_certificate_key /etc/nginx/tls/privkey.pem;
-    #     ssl_protocols       TLSv1.2 TLSv1.3;
-    #     ssl_ciphers         HIGH:!aNULL:!MD5;
-    #     ssl_session_cache   shared:SSL:10m;
-    #     ssl_session_timeout 10m;
-    #
-    #     location / {
-    #         proxy_pass http://s3_backend;
-    #         proxy_http_version 1.1;
-    #         proxy_set_header Host $host;
-    #         proxy_set_header X-Real-IP $remote_addr;
-    #         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    #         proxy_set_header X-Forwarded-Proto $scheme;
-    #     }
-    # }
-    #
-    # server {
-    #     listen 443 ssl default_server;
-    #     listen [::]:443 ssl default_server;
-    #     http2 on;
-    #     server_name _;
-    #
-    #     ssl_certificate     /etc/nginx/tls/fullchain.pem;
-    #     ssl_certificate_key /etc/nginx/tls/privkey.pem;
-    #     ssl_protocols       TLSv1.2 TLSv1.3;
-    #     ssl_ciphers         HIGH:!aNULL:!MD5;
-    #     ssl_session_cache   shared:SSL:10m;
-    #     ssl_session_timeout 10m;
-    #
-    #     location / {
-    #         proxy_pass http://puter_backend;
-    #         proxy_http_version 1.1;
-    #         proxy_set_header Host $host;
-    #         proxy_set_header X-Real-IP $remote_addr;
-    #         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    #         proxy_set_header X-Forwarded-Proto $scheme;
-    #         proxy_set_header X-Forwarded-Host $host;
-    #         proxy_set_header X-Forwarded-Port $server_port;
-    #         proxy_set_header Upgrade $http_upgrade;
-    #         proxy_set_header Connection $connection_upgrade;
-    #     }
-    # }
-}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "puter.com",
-  "version": "2.5.1",
+  "version": "26.07",
   "author": "Puter Technologies Inc.",
   "license": "AGPL-3.0-only",
   "description": "Desktop environment in the browser!",
@@ -10,6 +10,7 @@
     "lib": "lib"
   },
   "devDependencies": {
+    "@babel/core": "^7.29.7",
     "@eslint/js": "^9.35.0",
     "@playwright/test": "^1.56.1",
     "@stylistic/eslint-plugin": "^5.3.1",
@@ -20,6 +21,8 @@
     "@typescript-eslint/parser": "^8.46.1",
     "@vitest/coverage-v8": "^4.0.14",
     "@vitest/ui": "^4.0.14",
+    "babel-loader": "^10.1.1",
+    "babel-plugin-istanbul": "^8.0.0",
     "chalk": "^4.1.0",
     "clean-css": "^5.3.2",
     "dotenv": "^16.4.5",
@@ -31,9 +34,13 @@
     "globals": "^15.15.0",
     "html-webpack-plugin": "^5.6.0",
     "husky": "^9.1.7",
+    "istanbul-lib-coverage": "^3.2.2",
+    "istanbul-lib-report": "^3.0.1",
+    "istanbul-reports": "^3.2.0",
     "license-check-and-add": "^4.0.5",
     "nodemon": "^3.1.0",
     "prettier": "^3.8.3",
+    "prettier-plugin-jsdoc": "^1.8.1",
     "simple-git": "^3.32.3",
     "typescript": "^5.4.5",
     "uglify-js": "^3.17.4",
@@ -44,17 +51,25 @@
     "yaml": "^2.8.1"
   },
   "scripts": {
-    "test:backend": "npm run setupExtensions && vitest run --config src/backend/vitest.config.ts ",
-    "test:backend:postgres": "npm run setupExtensions && PUTER_TEST_DB_ENGINE=postgres vitest run --config src/backend/vitest.config.ts ",
+    "test:backend": "npm run setupExtensions && npm run build:workerLib && vitest run --config src/backend/vitest.config.ts ",
+    "test:backend:postgres": "npm run setupExtensions && npm run build:workerLib && PUTER_TEST_DB_ENGINE=postgres vitest run --config src/backend/vitest.config.ts ",
+    "test:puterjs": "npm run setupExtensions && vitest run --config src/puter-js/tests/api/vitest.config.ts",
+    "test:puterjs:node": "npm run test:puterjs -- src/puter-js/tests/api/runners/node.test.ts",
+    "test:puterjs:browser": "npm run test:puterjs -- src/puter-js/tests/api/runners/browser.test.ts",
+    "test:puterjs:workerd": "npm run test:puterjs -- src/puter-js/tests/api/runners/workerd.test.ts",
+    "test:puterjs:coverage": "npm run build:workerLib:coverage && npm run setupExtensions && rm -rf src/puter-js/coverage && PUTER_COVERAGE=1 vitest run --config src/puter-js/tests/api/vitest.config.ts && node ./tools/puterjsCoverageReport.mjs",
+    "build:workerLib:coverage": "cd src/puter-js && npm run build:coverage && cd ../worker && npm run build",
     "start:gui": "nodemon --exec \"node dev-server.js\" ",
-    "start": "node --enable-source-maps -r ./dist/src/backend/telemetry.js ./dist/src/backend/index.js",
-    "prestart": "npm run setupExtensions && npm run build:ts",
+    "start": "node ./tools/start.mjs",
     "dev": "npm start",
     "build": "npm run setupExtensions && npm run build:ts && cd src/gui && node ./build.js && cd ../puter-js && npm run build",
     "build:workerLib": "cd src/puter-js && npm run build && cd ../worker && npm run build",
     "check-translations": "node tools/check-translations.js",
     "prepare": "husky",
     "build:ts": "tsc -p tsconfig.build.json && node ./tools/write-dist-package-json.mjs",
+    "check:puterjs:types": "node tools/checkPuterjsTypes.mjs",
+    "typecheck": "node tools/typecheck.mjs",
+    "typecheck:update": "node tools/typecheck.mjs --update",
     "setupExtensions": "node ./tools/extensionSetup.mjs"
   },
   "workspaces": [

src/backend/clients/alarm/AlarmClient.test.ts

@@ -0,0 +1,521 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { AlarmClient } from './AlarmClient';
+import type { IConfig, IPagerConfig } from '../../types';
+import type { AlertPayload } from './types';
+
+const pdEvent = vi.hoisted(() => vi.fn(async () => ({})));
+vi.mock('@pagerduty/pdjs', () => ({ event: pdEvent }));
+
+const makeClient = (pager: IPagerConfig = {}) =>
+    new AlarmClient({ serverId: 'test-node', pager } as unknown as IConfig);
+
+/** Register a capturing handler in place of a real transport. */
+const capture = (
+    client: AlarmClient,
+    minSeverity?: 'critical' | 'error' | 'warning' | 'info',
+    maxSeverity?: 'critical' | 'error' | 'warning' | 'info',
+) => {
+    const seen: AlertPayload[] = [];
+    client.addAlertHandler(
+        async (alert) => {
+            seen.push(alert);
+        },
+        { name: 'capture', minSeverity, maxSeverity },
+    );
+    return seen;
+};
+
+describe('AlarmClient severity routing', () => {
+    beforeEach(() => {
+        vi.spyOn(console, 'error').mockImplementation(() => {});
+        vi.spyOn(console, 'warn').mockImplementation(() => {});
+        vi.spyOn(console, 'log').mockImplementation(() => {});
+        pdEvent.mockClear();
+    });
+
+    it('defaults to critical when the call site says nothing', () => {
+        const client = makeClient();
+        const seen = capture(client);
+
+        client.create('boom', 'everything is on fire');
+
+        expect(seen).toHaveLength(1);
+        expect(seen[0].severity).toBe('critical');
+    });
+
+    it('honours a configured default severity', () => {
+        const client = makeClient({ defaultSeverity: 'info' });
+        const seen = capture(client);
+
+        client.create('boom', 'everything is on fire');
+
+        expect(seen[0].severity).toBe('info');
+    });
+
+    it('skips handlers whose floor the alarm does not reach', () => {
+        const client = makeClient();
+        const paging = capture(client, 'warning');
+        const chat = capture(client, 'info');
+
+        client.create('rate-limit', 'a user hit a limit', {}, 'info');
+
+        expect(paging).toHaveLength(0);
+        expect(chat).toHaveLength(1);
+    });
+
+    it('skips handlers whose ceiling the alarm exceeds', () => {
+        const client = makeClient();
+        const chat = capture(client, 'info', 'info');
+
+        client.create('rate-limit', 'a user hit a limit', {}, 'info');
+        client.create('outage', 'everything is on fire', {}, 'critical');
+
+        expect(chat.map((alert) => alert.id)).toEqual(['rate-limit']);
+    });
+
+    it('retiers an alarm from config', () => {
+        const client = makeClient({
+            severityOverrides: { 'noisy:*': 'info' },
+        });
+        const paging = capture(client, 'warning');
+        const chat = capture(client, 'info');
+
+        client.create('noisy:thing', 'used to page', {}, 'critical');
+
+        expect(paging).toHaveLength(0);
+        expect(chat[0].severity).toBe('info');
+    });
+
+    it('mutes an alarm from config', () => {
+        const client = makeClient({
+            severityOverrides: { 'noisy:thing': 'mute' },
+        });
+        const chat = capture(client, 'info');
+
+        client.create('noisy:thing', 'not worth reporting');
+        client.create('noisy:thing', 'still not worth reporting');
+
+        expect(chat).toHaveLength(0);
+    });
+
+    it('lets config override a known-error rule', () => {
+        const client = makeClient({
+            severityOverrides: { 'known:thing': 'critical' },
+        });
+        client.setKnownErrors([
+            {
+                match: { id: 'known:thing' },
+                action: { type: 'severity', value: 'info' },
+            },
+        ]);
+        const paging = capture(client, 'warning');
+
+        client.create('known:thing', 'known but escalated');
+
+        expect(paging[0].severity).toBe('critical');
+    });
+
+    it('still respects a no-alert known-error rule', () => {
+        const client = makeClient();
+        client.setKnownErrors([
+            { match: { id: 'known:quiet' }, action: { type: 'no-alert' } },
+        ]);
+        const chat = capture(client, 'info');
+
+        client.create('known:quiet', 'suppressed');
+
+        expect(chat).toHaveLength(0);
+    });
+});
+
+describe('AlarmClient alert payload', () => {
+    beforeEach(() => {
+        vi.spyOn(console, 'error').mockImplementation(() => {});
+        vi.spyOn(console, 'warn').mockImplementation(() => {});
+    });
+
+    it('reports occurrence counts across repeats', () => {
+        const client = makeClient();
+        const seen = capture(client);
+
+        client.create('flap', 'first');
+        client.create('flap', 'second');
+
+        expect(seen[0]).toMatchObject({ repeatCount: 1, isRepeat: false });
+        expect(seen[1]).toMatchObject({ repeatCount: 2, isRepeat: true });
+    });
+
+    it('renders fields as strings and lifts the stack out of the error', () => {
+        const client = makeClient();
+        const seen = capture(client);
+        const error = new Error('kaboom');
+
+        client.create('boom', 'failed', { error, status: 500 }, 'critical');
+
+        expect(seen[0].fields.status).toBe('500');
+        expect(seen[0].trace).toBe(error.stack);
+        expect(seen[0].shortId).toMatch(/^[a-z]+-[a-z]+-[a-z]+$/);
+    });
+
+    it('keeps one failing handler from starving the others', async () => {
+        const client = makeClient();
+        client.addAlertHandler(
+            async () => {
+                throw new Error('transport down');
+            },
+            { name: 'broken' },
+        );
+        const seen = capture(client);
+
+        client.create('boom', 'failed');
+        await Promise.resolve();
+
+        expect(seen).toHaveLength(1);
+    });
+
+    it('suppresses alarms once draining', () => {
+        const client = makeClient();
+        const seen = capture(client);
+
+        client.onServerPrepareShutdown();
+        client.create('boom', 'too late');
+
+        expect(seen).toHaveLength(0);
+    });
+});
+
+describe('AlarmClient transport registration', () => {
+    beforeEach(() => {
+        vi.spyOn(console, 'error').mockImplementation(() => {});
+        vi.spyOn(console, 'warn').mockImplementation(() => {});
+        vi.spyOn(console, 'log').mockImplementation(() => {});
+        pdEvent.mockClear();
+    });
+
+    it('splits info to Slack and everything above it to PagerDuty', async () => {
+        const fetchMock = vi.fn(async () => ({ ok: true, status: 200 }));
+        vi.stubGlobal('fetch', fetchMock);
+
+        const client = makeClient({
+            pagerduty: { enabled: true, routingKey: 'rk' },
+            slack: { enabled: true, webhookUrl: 'https://hooks.example/abc' },
+        });
+        await client.onServerStart();
+
+        client.create('quiet:thing', 'informational', {}, 'info');
+        await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1));
+        expect(pdEvent).not.toHaveBeenCalled();
+
+        client.create('loud:thing', 'paging', {}, 'critical');
+        await vi.waitFor(() => expect(pdEvent).toHaveBeenCalledTimes(1));
+        // The pager has it; chat doesn't repeat it.
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+
+        vi.unstubAllGlobals();
+    });
+
+    it('sends every severity to Slack when there is no pager', async () => {
+        const fetchMock = vi.fn(async () => ({ ok: true, status: 200 }));
+        vi.stubGlobal('fetch', fetchMock);
+
+        const client = makeClient({
+            slack: { enabled: true, webhookUrl: 'https://hooks.example/abc' },
+        });
+        await client.onServerStart();
+
+        client.create(
+            'loud:thing',
+            'nowhere else to send this',
+            {},
+            'critical',
+        );
+        await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1));
+
+        vi.unstubAllGlobals();
+    });
+
+    it('lets config widen the Slack ceiling back out', async () => {
+        const fetchMock = vi.fn(async () => ({ ok: true, status: 200 }));
+        vi.stubGlobal('fetch', fetchMock);
+
+        const client = makeClient({
+            pagerduty: { enabled: true, routingKey: 'rk' },
+            slack: {
+                enabled: true,
+                webhookUrl: 'https://hooks.example/abc',
+                maxSeverity: 'critical',
+            },
+        });
+        await client.onServerStart();
+
+        client.create('loud:thing', 'paging', {}, 'critical');
+        await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1));
+
+        vi.unstubAllGlobals();
+    });
+
+    it('gives each occurrence its own PagerDuty incident by default', async () => {
+        const client = makeClient({
+            pagerduty: { enabled: true, routingKey: 'rk' },
+        });
+        await client.onServerStart();
+
+        client.create('scan:failed', 'first', {}, 'warning');
+        client.create('scan:failed', 'second', {}, 'warning');
+        await vi.waitFor(() => expect(pdEvent).toHaveBeenCalledTimes(2));
+
+        const keys = pdEvent.mock.calls.map(
+            ([arg]: [{ data: { dedup_key: string } }]) => arg.data.dedup_key,
+        );
+        expect(keys[0]).not.toBe(keys[1]);
+    });
+
+    it('collapses repeats of a dedup alarm onto one incident', async () => {
+        const client = makeClient({
+            pagerduty: { enabled: true, routingKey: 'rk' },
+        });
+        await client.onServerStart();
+
+        const raise = () =>
+            client.create(
+                'http_500:POST:/notif/mark-ack:deadlock',
+                'HTTP 500 on POST /notif/mark-ack: deadlock',
+                {},
+                'critical',
+                { dedup: true },
+            );
+        raise();
+        raise();
+        await vi.waitFor(() => expect(pdEvent).toHaveBeenCalledTimes(2));
+
+        const keys = pdEvent.mock.calls.map(
+            ([arg]: [{ data: { dedup_key: string } }]) => arg.data.dedup_key,
+        );
+        expect(keys[0]).toBe('http_500:POST:/notif/mark-ack:deadlock');
+        expect(keys[1]).toBe(keys[0]);
+    });
+
+    it('skips transports that are enabled but not configured', async () => {
+        const client = makeClient({
+            pagerduty: { enabled: true },
+            slack: { enabled: true },
+        });
+        await client.onServerStart();
+
+        const seen = capture(client);
+        client.create('boom', 'nowhere to send this');
+
+        // Only the capturing handler is registered.
+        expect(seen).toHaveLength(1);
+        expect(pdEvent).not.toHaveBeenCalled();
+    });
+});
+
+describe('AlarmClient alarm registry', () => {
+    beforeEach(() => {
+        vi.spyOn(console, 'error').mockImplementation(() => {});
+        vi.spyOn(console, 'warn').mockImplementation(() => {});
+        vi.spyOn(console, 'log').mockImplementation(() => {});
+    });
+
+    it('finds an alarm by its full id or its short id', () => {
+        const client = makeClient();
+        client.create('disk-pressure', 'nearly full');
+
+        const alarm = client.get('disk-pressure');
+        expect(alarm?.message).toBe('nearly full');
+        expect(client.get(alarm!.shortId)).toBe(alarm);
+    });
+
+    it('returns nothing for an id it has never seen', () => {
+        expect(makeClient().get('never-raised')).toBeUndefined();
+    });
+
+    it('forgets an alarm once cleared, under both ids', () => {
+        const client = makeClient();
+        client.create('disk-pressure', 'nearly full');
+        const shortId = client.get('disk-pressure')!.shortId;
+
+        client.clear('disk-pressure');
+
+        expect(client.get('disk-pressure')).toBeUndefined();
+        expect(client.get(shortId)).toBeUndefined();
+    });
+
+    it('ignores a clear for an alarm that is not active', () => {
+        const client = makeClient();
+        expect(() => client.clear('never-raised')).not.toThrow();
+    });
+
+    it('abbreviates long ids in the log line but keeps the short id usable', () => {
+        const log = vi.spyOn(console, 'error').mockImplementation(() => {});
+        const client = makeClient();
+        const longId = 'a-very-long-alarm-identifier-that-wraps';
+
+        client.create(longId, 'noisy');
+
+        const shortId = client.get(longId)!.shortId;
+        expect(log).toHaveBeenCalledWith(
+            `[alarm] ACTIVE ${shortId} (${longId.slice(0, 20)}...) :: noisy`,
+        );
+    });
+
+    it('accumulates fields across repeats of the same alarm', () => {
+        const client = makeClient();
+        const seen = capture(client);
+
+        client.create('flap', 'first', { a: 1 });
+        client.create('flap', 'second', { b: 2 });
+
+        expect(seen[1].fields).toEqual({ a: '1', b: '2' });
+        expect(client.get('flap')?.occurrences).toHaveLength(2);
+    });
+
+    it('caps retained occurrences while still counting every repeat', () => {
+        const client = makeClient();
+        const seen = capture(client);
+
+        for (let i = 0; i < 50; i++) {
+            client.create('hot', `occurrence ${i}`, { i });
+        }
+
+        const alarm = client.get('hot')!;
+        expect(alarm.count).toBe(50);
+        expect(alarm.occurrences).toHaveLength(20);
+        expect(alarm.timestamps).toHaveLength(20);
+        // The window kept is the most recent one, not the oldest.
+        expect(alarm.occurrences[19].message).toBe('occurrence 49');
+        // Trimming history must not rewind what the transports are told.
+        expect(seen[49]).toMatchObject({ repeatCount: 50, isRepeat: true });
+    });
+
+    it('names anonymous handlers by their registration order', () => {
+        const client = makeClient();
+        client.addAlertHandler(async () => {
+            throw new Error('down');
+        });
+        expect(() => client.create('boom', 'x')).not.toThrow();
+    });
+
+    it('only logs the drain notice once', () => {
+        const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+        log.mockClear();
+        const client = makeClient();
+
+        client.onServerPrepareShutdown();
+        // A second prepare must not restart the drain.
+        client.onServerPrepareShutdown();
+        client.create('a', 'x');
+        client.create('b', 'y');
+
+        const drainLogs = log.mock.calls.filter(
+            ([message]) =>
+                message === '[alarm] suppressing alarm while draining',
+        );
+        expect(drainLogs).toHaveLength(1);
+    });
+
+    it('substitutes placeholders for an empty id and message', () => {
+        const client = makeClient();
+        const seen = capture(client);
+
+        client.create('', '');
+
+        expect(seen[0]).toMatchObject({
+            id: 'something-bad',
+            message: 'something bad happened',
+        });
+    });
+});
+
+describe('AlarmClient known-error rules', () => {
+    beforeEach(() => {
+        vi.spyOn(console, 'error').mockImplementation(() => {});
+        vi.spyOn(console, 'warn').mockImplementation(() => {});
+        vi.spyOn(console, 'log').mockImplementation(() => {});
+    });
+
+    it('suppresses alerts for a matching rule', () => {
+        const client = makeClient();
+        const seen = capture(client);
+        client.setKnownErrors([
+            { match: { id: 'noisy' }, action: { type: 'no-alert' } },
+        ]);
+
+        client.create('noisy', 'ignore me');
+        client.create('noisy', 'ignore me again');
+
+        expect(seen).toHaveLength(0);
+    });
+
+    it('leaves alarms with a different id alone', () => {
+        const client = makeClient();
+        const seen = capture(client);
+        client.setKnownErrors([
+            { match: { id: 'noisy' }, action: { type: 'no-alert' } },
+        ]);
+
+        client.create('real', 'page me');
+
+        expect(seen).toHaveLength(1);
+    });
+
+    it('only matches when the message matches too', () => {
+        const rules = [
+            {
+                match: { id: 'timeout', message: 'upstream timed out' },
+                action: { type: 'no-alert' as const },
+            },
+        ];
+
+        // Separate clients: suppression is recorded on the alarm, so a
+        // second occurrence of the same id would inherit it.
+        const matching = makeClient();
+        const matchingSeen = capture(matching);
+        matching.setKnownErrors(rules);
+        matching.create('timeout', 'upstream timed out');
+        expect(matchingSeen).toHaveLength(0);
+
+        const differing = makeClient();
+        const differingSeen = capture(differing);
+        differing.setKnownErrors(rules);
+        differing.create('timeout', 'something else entirely');
+        expect(differingSeen.map((alert) => alert.message)).toEqual([
+            'something else entirely',
+        ]);
+    });
+
+    it('only matches when every named field matches', () => {
+        const client = makeClient();
+        const seen = capture(client);
+        client.setKnownErrors([
+            {
+                match: { id: 'http', fields: { status: 404 } },
+                action: { type: 'no-alert' },
+            },
+        ]);
+
+        client.create('http', 'not found', { status: 404 });
+        client.create('http-2', 'server error', { status: 500 });
+
+        expect(seen.map((alert) => alert.id)).toEqual(['http-2']);
+    });
+
+    it('retiers a matching alarm to a lower severity', () => {
+        const client = makeClient();
+        const paging = capture(client, 'error');
+        const chat = capture(client, 'info');
+        client.setKnownErrors([
+            {
+                match: { id: 'flaky' },
+                action: { type: 'severity', value: 'info' },
+            },
+        ]);
+
+        client.create('flaky', 'transient', {}, 'critical');
+
+        expect(paging).toHaveLength(0);
+        expect(chat).toHaveLength(1);
+        expect(chat[0].severity).toBe('info');
+    });
+});

src/backend/clients/alarm/AlarmClient.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -20,64 +20,65 @@
 import { event as pdEvent } from '@pagerduty/pdjs';
 import { inspect } from 'node:util';
 import { createHash } from 'node:crypto';
-import type { IConfig } from '../../types';
+import type { IConfig, PagerSeverity, SeverityRule } from '../../types';
 import { PuterClient } from '../types';
+import {
+    meetsMinSeverity,
+    resolveSeverityOverride,
+    withinMaxSeverity,
+} from './severity';
+import { createSlackAlertHandler } from './slack';
+import type {
+    Alarm,
+    AlarmFields,
+    AlarmOptions,
+    AlertHandler,
+    AlertPayload,
+    KnownErrorRule,
+} from './types';
+
+export type {
+    Alarm,
+    AlarmFields,
+    AlarmOptions,
+    AlertHandler,
+    AlertPayload,
+    KnownErrorRule,
+} from './types';
+export type { PagerSeverity } from '../../types';
 
 // -- Types ------------------------------------------------------------
 
-export interface AlarmFields {
-    error?: Error;
-    [key: string]: unknown;
+interface RegisteredHandler {
+    name: string;
+    /** Lowest severity this transport accepts. */
+    minSeverity: PagerSeverity;
+    /** Highest severity this transport accepts. */
+    maxSeverity: PagerSeverity;
+    handler: AlertHandler;
 }
 
-interface AlarmOccurrence {
-    message: string;
-    fields: AlarmFields;
-    timestamp: number;
-}
-
-interface Alarm {
-    id: string;
-    shortId: string;
-    message: string;
-    fields: AlarmFields;
-    error?: Error;
-    started: number;
-    timestamps: number[];
-    occurrences: AlarmOccurrence[];
-    severity?: PagerSeverity;
-    noAlert?: boolean;
-}
-
-export type PagerSeverity = 'critical' | 'error' | 'warning' | 'info';
-
-export interface AlertPayload {
-    id: string;
-    message: string;
-    source: string;
-    severity: PagerSeverity;
-    custom?: Record<string, unknown>;
-}
-
-type AlertHandler = (alert: AlertPayload) => Promise<void>;
-
-interface KnownErrorRule {
-    match: {
-        id: string;
-        message?: string;
-        fields?: Record<string, unknown>;
-    };
-    action: {
-        type: 'no-alert' | 'severity';
-        value?: PagerSeverity;
-    };
-}
+/** Severity used when neither the call site nor config picks one. */
+const FALLBACK_SEVERITY: PagerSeverity = 'critical';
+/**
+ * How many recent occurrences an alarm keeps. An alarm is never cleared unless
+ * something calls `clear`, and a hot one repeats for as long as the fault lasts
+ * — so retaining every occurrence means retaining every message and field set
+ * it was ever raised with, request bodies and actors included, for the life of
+ * the process. The last few are what a human reads; the rest is only a count,
+ * and `count` keeps that.
+ */
+const OCCURRENCE_HISTORY_LIMIT = 20;
+/** Keeps `info` alarms out of the paging system unless config says otherwise. */
+const DEFAULT_PAGERDUTY_MIN_SEVERITY: PagerSeverity = 'warning';
+/** Slack's ceiling once a pager exists: chat gets what doesn't page. */
+const DEFAULT_SLACK_MAX_SEVERITY_WITH_PAGER: PagerSeverity = 'info';
 
 // -- Helpers ----------------------------------------------------------
 
 /**
- * Deterministic short identifier derived from an alarm ID.
- * Produces a readable 3-word slug like "amber-delta-fox".
+ * Deterministic short identifier derived from an alarm ID. Produces a readable
+ * 3-word slug like "amber-delta-fox".
  */
 const WORD_POOL = [
     'alpha',
@@ -169,13 +170,17 @@ function cleanFields(fields: AlarmFields): Record<string, string> {
 // -- AlarmClient ------------------------------------------------------
 
 /**
- * Manages system alarms and dispatches alerts to external paging
- * services (PagerDuty, or any registered handler).
+ * Manages system alarms and routes them to alert transports by severity.
+ *
+ * Severity is the routing decision: each transport declares the severity window
+ * it accepts, so `critical` pages on-call while `info` only reaches the chat
+ * channel. Config can retier or mute any alarm id after the fact — see
+ * `pager.severityOverrides` in {@link IConfig}.
  */
 export class AlarmClient extends PuterClient {
     private alarms = new Map<string, Alarm>();
     private aliases = new Map<string, Alarm>();
-    private alertHandlers: AlertHandler[] = [];
+    private alertHandlers: RegisteredHandler[] = [];
     private knownErrors: KnownErrorRule[] = [];
     private draining = false;
     private drainLogged = false;
@@ -187,39 +192,8 @@ export class AlarmClient extends PuterClient {
     // -- Lifecycle ----------------------------------------------------
 
     override async onServerStart(): Promise<void> {
-        const pagerConf = this.config.pager;
-        if (!pagerConf?.pagerduty?.enabled) return;
-
-        const routingKey = pagerConf.pagerduty.routingKey;
-        if (!routingKey) {
-            console.warn(
-                '[alarm] PagerDuty enabled but no routingKey configured',
-            );
-            return;
-        }
-
-        const serverId = this.config.serverId;
-
-        this.alertHandlers.push(async (alert) => {
-            await pdEvent({
-                data: {
-                    routing_key: routingKey,
-                    event_action: 'trigger',
-                    dedup_key: alert.id,
-                    payload: {
-                        summary: alert.message,
-                        source: alert.source,
-                        severity: alert.severity,
-                        custom_details: {
-                            ...alert.custom,
-                            server_id: serverId,
-                        },
-                    },
-                },
-            });
-        });
-
-        console.log('[alarm] PagerDuty handler registered');
+        const paging = this.registerPagerDuty();
+        this.registerSlack({ paging });
     }
 
     override onServerPrepareShutdown(): void {
@@ -228,22 +202,107 @@ export class AlarmClient extends PuterClient {
         console.log('[alarm] entering drain mode — suppressing new alarms');
     }
 
+    /** @returns Whether a working PagerDuty transport was registered. */
+    private registerPagerDuty(): boolean {
+        const pagerDutyConf = this.config.pager?.pagerduty;
+        if (!pagerDutyConf?.enabled) return false;
+
+        const routingKey = pagerDutyConf.routingKey;
+        if (!routingKey) {
+            console.warn(
+                '[alarm] PagerDuty enabled but no routingKey configured',
+            );
+            return false;
+        }
+
+        const serverId = this.config.serverId;
+        const minSeverity =
+            pagerDutyConf.minSeverity ?? DEFAULT_PAGERDUTY_MIN_SEVERITY;
+
+        this.addAlertHandler(
+            async (alert) => {
+                await pdEvent({
+                    data: {
+                        routing_key: routingKey,
+                        event_action: 'trigger',
+                        dedup_key: alert.dedupKey,
+                        payload: {
+                            summary: alert.message,
+                            source: alert.source,
+                            severity: alert.severity,
+                            custom_details: {
+                                ...alert.custom,
+                                server_id: serverId,
+                            },
+                        },
+                    },
+                });
+            },
+            { name: 'pagerduty', minSeverity },
+        );
+
+        console.log(
+            `[alarm] PagerDuty handler registered (min severity: ${minSeverity})`,
+        );
+        return true;
+    }
+
+    private registerSlack({ paging }: { paging: boolean }): void {
+        const slackConf = this.config.pager?.slack;
+        if (!slackConf?.enabled) return;
+
+        if (!slackConf.webhookUrl) {
+            console.warn('[alarm] Slack enabled but no webhookUrl configured');
+            return;
+        }
+
+        const minSeverity = slackConf.minSeverity ?? 'info';
+        // With a pager taking everything from `warning` up, chat is where the
+        // rest is recorded — reposting the paging tiers there only trains
+        // people to skim the channel. Without one, Slack is the only place an
+        // alarm can land, so it takes all of them.
+        const maxSeverity =
+            slackConf.maxSeverity ??
+            (paging ? DEFAULT_SLACK_MAX_SEVERITY_WITH_PAGER : 'critical');
+
+        this.addAlertHandler(
+            createSlackAlertHandler(slackConf, {
+                serverId: this.config.serverId,
+            }),
+            { name: 'slack', minSeverity, maxSeverity },
+        );
+
+        console.log(
+            `[alarm] Slack handler registered (severity ${minSeverity}..${maxSeverity})`,
+        );
+    }
+
     // -- Public API ---------------------------------------------------
 
     /**
-     * Create or update an alarm. If the alarm ID already exists, the
-     * occurrence count is incremented and a repeat alert is dispatched.
+     * Create or update an alarm. If the alarm ID already exists, the occurrence
+     * count is incremented and a repeat alert is dispatched.
      *
-     * `severity` is the PagerDuty severity for this alarm; omit for the
-     * default 'critical'. Use 'info' / 'warning' for expected-but-worth-
-     * tracking signals (e.g. a user hitting a rate limit) so they record
-     * and de-dupe like any other alarm but don't page on-call.
+     * `severity` decides where the alarm lands:
+     *
+     * Critical — a real outage; pages on-call. Reserve it for unhandled server
+     * errors. error — pages on-call as well; prefer `critical` or `warning`.
+     * warning — worth a look soon, but nobody gets woken up. info — a record in
+     * the chat channel; never pages.
+     *
+     * Omit it to take `pager.defaultSeverity` (itself defaulting to
+     * 'critical'). Operators can retier or mute any alarm id from config
+     * afterwards, so the value here is the starting point, not the last word.
+     *
+     * Pass `{ dedup: true }` when repeats of this id are one recurring fault
+     * that should collapse into a single incident — see {@link AlarmOptions}.
      */
     create(
         id: string,
         message: string,
         fields: AlarmFields = {},
         severity?: PagerSeverity,
+        opts: AlarmOptions = {},
     ): void {
         if (this.draining) {
             if (!this.drainLogged) {
@@ -267,8 +326,12 @@ export class AlarmClient extends PuterClient {
             message,
             fields,
             severity,
+            dedup: opts.dedup,
             started: Date.now(),
-            timestamps: [Date.now()],
+            // `recordOccurrence` below stamps the first occurrence; seeding one
+            // here too would report every alarm as one occurrence ahead.
+            count: 0,
+            timestamps: [],
             occurrences: [],
         };
         if (fields.error) alarm.error = fields.error;
@@ -295,16 +358,28 @@ export class AlarmClient extends PuterClient {
     }
 
     /**
-     * Register an additional alert handler. Handlers are called for
-     * every alarm that isn't suppressed by a known-error rule.
+     * Register an additional alert handler. Handlers are called for every alarm
+     * that isn't suppressed by a known-error rule or muted by config, and whose
+     * severity falls inside the handler's own `minSeverity`..`maxSeverity`
+     * window (default: everything).
      */
-    addAlertHandler(handler: AlertHandler): void {
-        this.alertHandlers.push(handler);
+    addAlertHandler(
+        handler: AlertHandler,
+        opts: {
+            name?: string;
+            minSeverity?: PagerSeverity;
+            maxSeverity?: PagerSeverity;
+        } = {},
+    ): void {
+        this.alertHandlers.push({
+            name: opts.name ?? `handler-${this.alertHandlers.length}`,
+            minSeverity: opts.minSeverity ?? 'info',
+            maxSeverity: opts.maxSeverity ?? 'critical',
+            handler,
+        });
     }
 
-    /**
-     * Add rules that can suppress or adjust severity of known errors.
-     */
+    /** Add rules that can suppress or adjust severity of known errors. */
     setKnownErrors(rules: KnownErrorRule[]): void {
         this.knownErrors = rules;
     }
@@ -316,16 +391,25 @@ export class AlarmClient extends PuterClient {
         message: string,
         fields: AlarmFields,
     ): void {
+        const now = Date.now();
         alarm.message = message;
         alarm.fields = { ...alarm.fields, ...fields };
-        alarm.timestamps.push(Date.now());
+        alarm.count++;
         if (fields.error) alarm.error = fields.error;
 
-        alarm.occurrences.push({
-            message,
-            fields,
-            timestamp: Date.now(),
-        });
+        alarm.timestamps.push(now);
+        alarm.occurrences.push({ message, fields, timestamp: now });
+
+        if (alarm.timestamps.length > OCCURRENCE_HISTORY_LIMIT) {
+            alarm.timestamps.splice(
+                0,
+                alarm.timestamps.length - OCCURRENCE_HISTORY_LIMIT,
+            );
+            alarm.occurrences.splice(
+                0,
+                alarm.occurrences.length - OCCURRENCE_HISTORY_LIMIT,
+            );
+        }
     }
 
     private applyKnownErrors(alarm: Alarm): void {
@@ -373,7 +457,7 @@ export class AlarmClient extends PuterClient {
         this.applyKnownErrors(alarm);
 
         console.warn(
-            `[alarm] REPEAT ${displayId(alarm)} :: ${alarm.message} (${alarm.timestamps.length})`,
+            `[alarm] REPEAT ${displayId(alarm)} :: ${alarm.message} (${alarm.count})`,
         );
 
         if (alarm.noAlert) return;
@@ -381,25 +465,72 @@ export class AlarmClient extends PuterClient {
         this.dispatchAlert(alarm);
     }
 
+    /**
+     * Call-site severity, then any known-error rule (both already on the
+     * alarm), then the config override — so an operator always has the last
+     * word over what the code asked for.
+     */
+    private resolveSeverity(alarm: Alarm): SeverityRule {
+        const base =
+            alarm.severity ??
+            this.config.pager?.defaultSeverity ??
+            FALLBACK_SEVERITY;
+        return (
+            resolveSeverityOverride(
+                alarm.id,
+                this.config.pager?.severityOverrides,
+            ) ?? base
+        );
+    }
+
     private dispatchAlert(alarm: Alarm): void {
-        const severity = alarm.severity ?? 'critical';
+        const resolved = this.resolveSeverity(alarm);
+        if (resolved === 'mute') {
+            if (!alarm.muteLogged) {
+                alarm.muteLogged = true;
+                console.log(`[alarm] MUTED by config ${displayId(alarm)}`);
+            }
+            return;
+        }
+        alarm.severity = resolved;
+
         const fieldsClean = cleanFields(alarm.fields);
+        const repeatCount = alarm.count;
+
+        const id = alarm.id || 'something-bad';
 
         const payload: AlertPayload = {
-            id: alarm.id || 'something-bad',
+            id,
+            // A de-duplicating transport should fold repeats of a recurring
+            // fault into one incident, but everything else is a fresh event
+            // each time it fires — the start time keeps occurrence numbering
+            // from colliding with an incident left open by an earlier boot.
+            dedupKey: alarm.dedup
+                ? id
+                : `${id}#${alarm.started}.${repeatCount}`,
+            shortId: alarm.shortId,
             message: alarm.message || alarm.id || 'something bad happened',
             source: 'alarm',
-            severity,
+            severity: resolved,
+            fields: fieldsClean,
+            trace: alarm.error?.stack,
+            repeatCount,
+            isRepeat: repeatCount > 1,
             custom: {
                 fields: fieldsClean,
                 trace: alarm.error?.stack,
-                repeat_count: alarm.timestamps.length,
+                repeat_count: repeatCount,
             },
         };
 
-        for (const handler of this.alertHandlers) {
+        for (const { name, minSeverity, maxSeverity, handler } of this
+            .alertHandlers) {
+            if (!meetsMinSeverity(resolved, minSeverity)) continue;
+            if (!withinMaxSeverity(resolved, maxSeverity)) continue;
             handler(payload).catch((err) => {
-                console.error(`[alarm] alert handler failed: ${err?.message}`);
+                console.error(
+                    `[alarm] ${name} alert handler failed: ${err?.message}`,
+                );
             });
         }
     }

src/backend/clients/alarm/severity.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it, vi } from 'vitest';
+import { meetsMinSeverity, resolveSeverityOverride } from './severity';
+
+describe('meetsMinSeverity', () => {
+    it('accepts everything at or above the floor', () => {
+        expect(meetsMinSeverity('critical', 'warning')).toBe(true);
+        expect(meetsMinSeverity('error', 'warning')).toBe(true);
+        expect(meetsMinSeverity('warning', 'warning')).toBe(true);
+        expect(meetsMinSeverity('info', 'warning')).toBe(false);
+    });
+
+    it('lets an info floor take every severity', () => {
+        for (const severity of [
+            'critical',
+            'error',
+            'warning',
+            'info',
+        ] as const) {
+            expect(meetsMinSeverity(severity, 'info')).toBe(true);
+        }
+    });
+});
+
+describe('resolveSeverityOverride', () => {
+    it('returns undefined without overrides or on no match', () => {
+        expect(resolveSeverityOverride('a:b', undefined)).toBeUndefined();
+        expect(
+            resolveSeverityOverride('a:b', { 'c:*': 'info' }),
+        ).toBeUndefined();
+    });
+
+    it('matches an exact id', () => {
+        expect(
+            resolveSeverityOverride('cronMonitor:lowSignupRate', {
+                'cronMonitor:lowSignupRate': 'info',
+            }),
+        ).toBe('info');
+    });
+
+    it('matches a prefix pattern', () => {
+        expect(
+            resolveSeverityOverride('cronMonitor:high_aiLogEntries', {
+                'cronMonitor:*': 'warning',
+            }),
+        ).toBe('warning');
+    });
+
+    it('prefers the exact id over a prefix pattern', () => {
+        expect(
+            resolveSeverityOverride('cronMonitor:lowSignupRate', {
+                'cronMonitor:*': 'warning',
+                'cronMonitor:lowSignupRate': 'mute',
+            }),
+        ).toBe('mute');
+    });
+
+    it('prefers the longest matching prefix', () => {
+        expect(
+            resolveSeverityOverride('abuse:card-verification:setup-failed', {
+                'abuse:*': 'info',
+                'abuse:card-verification:*': 'mute',
+            }),
+        ).toBe('mute');
+    });
+
+    it('drops an unrecognized rule rather than guessing', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        expect(
+            resolveSeverityOverride('a:b', {
+                'a:b': 'silent' as unknown as 'mute',
+            }),
+        ).toBeUndefined();
+        expect(warn).toHaveBeenCalled();
+        warn.mockRestore();
+    });
+});

src/backend/clients/alarm/severity.ts

@@ -0,0 +1,94 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import type { PagerSeverity, SeverityRule } from '../../types';
+
+/** Ascending urgency. A transport takes everything at or above its floor. */
+const RANK: Record<PagerSeverity, number> = {
+    info: 0,
+    warning: 1,
+    error: 2,
+    critical: 3,
+};
+
+const SEVERITIES = Object.keys(RANK) as PagerSeverity[];
+
+export function isPagerSeverity(value: unknown): value is PagerSeverity {
+    return typeof value === 'string' && value in RANK;
+}
+
+/** True when `severity` is urgent enough for a transport whose floor is `min`. */
+export function meetsMinSeverity(
+    severity: PagerSeverity,
+    min: PagerSeverity,
+): boolean {
+    return RANK[severity] >= RANK[min];
+}
+
+/**
+ * True when `severity` is quiet enough for a transport whose ceiling is `max`.
+ * A ceiling is what keeps a chat transport from repeating everything the pager
+ * already delivered.
+ */
+export function withinMaxSeverity(
+    severity: PagerSeverity,
+    max: PagerSeverity,
+): boolean {
+    return RANK[severity] <= RANK[max];
+}
+
+/**
+ * Look up the operator override for an alarm id. Exact ids win over prefix
+ * patterns (`cronMonitor:*`); among patterns the longest prefix wins, so a
+ * specific rule can carve an exception out of a broad one.
+ */
+export function resolveSeverityOverride(
+    id: string,
+    overrides: Record<string, SeverityRule> | undefined,
+): SeverityRule | undefined {
+    if (!overrides) return undefined;
+
+    const exact = overrides[id];
+    if (exact !== undefined) return validRule(id, exact);
+
+    let bestLength = -1;
+    let best: SeverityRule | undefined;
+    for (const [pattern, rule] of Object.entries(overrides)) {
+        if (!pattern.endsWith('*')) continue;
+        const prefix = pattern.slice(0, -1);
+        if (!id.startsWith(prefix)) continue;
+        if (prefix.length <= bestLength) continue;
+        bestLength = prefix.length;
+        best = rule;
+    }
+    return best === undefined ? undefined : validRule(id, best);
+}
+
+/**
+ * A typo in the override map would otherwise silently mute or escalate an
+ * alarm, so an unrecognized value is dropped with a warning instead.
+ */
+function validRule(id: string, rule: SeverityRule): SeverityRule | undefined {
+    if (rule === 'mute' || isPagerSeverity(rule)) return rule;
+    console.warn(
+        `[alarm] ignoring invalid severity override "${rule}" for ${id} ` +
+            `(expected mute or one of ${SEVERITIES.join(', ')})`,
+    );
+    return undefined;
+}

src/backend/clients/alarm/slack.test.ts

@@ -0,0 +1,206 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { buildSlackMessage, createSlackAlertHandler } from './slack';
+import type { AlertPayload } from './types';
+
+const alert = (over: Partial<AlertPayload> = {}): AlertPayload => ({
+    id: 'cronMonitor:high_aiLogEntries',
+    dedupKey: 'cronMonitor:high_aiLogEntries#1.1',
+    shortId: 'amber-delta-fox',
+    message: 'High AI log entries: 1200 in the last 10 minutes',
+    source: 'alarm',
+    severity: 'warning',
+    fields: { count: '1200', threshold: '1000' },
+    repeatCount: 1,
+    isRepeat: false,
+    ...over,
+});
+
+describe('buildSlackMessage', () => {
+    it('renders severity, message and fields', () => {
+        const msg = buildSlackMessage(alert(), {
+            channel: '#alerts',
+            username: 'puter-alarms',
+            serverId: 'oregon',
+        });
+
+        expect(msg.text).toContain('[WARNING]');
+        expect(msg.text).toContain('High AI log entries');
+        expect(msg.channel).toBe('#alerts');
+        expect(msg.username).toBe('puter-alarms');
+        expect(msg.attachments[0].fields).toEqual([
+            { title: 'count', value: '1200', short: true },
+            { title: 'threshold', value: '1000', short: true },
+        ]);
+        expect(msg.attachments[0].footer).toBe(
+            'amber-delta-fox • cronMonitor:high_aiLogEntries • oregon',
+        );
+    });
+
+    it('marks repeats with an occurrence count', () => {
+        const msg = buildSlackMessage(
+            alert({ repeatCount: 7, isRepeat: true }),
+        );
+        expect(msg.text).toContain('(x7)');
+    });
+
+    it('colours each severity differently', () => {
+        const colors = (['critical', 'error', 'warning', 'info'] as const).map(
+            (severity) =>
+                buildSlackMessage(alert({ severity })).attachments[0].color,
+        );
+        expect(new Set(colors).size).toBe(4);
+    });
+
+    it('puts the stack in a code block and keeps it out of the fields', () => {
+        const msg = buildSlackMessage(
+            alert({
+                fields: { error: 'Error: boom', path: '/api/x' },
+                trace: 'Error: boom\n    at handler',
+            }),
+        );
+        expect(msg.attachments[0].text).toBe(
+            '```Error: boom\n    at handler```',
+        );
+        expect(msg.attachments[0].fields.map((f) => f.title)).toEqual(['path']);
+    });
+
+    it('truncates long values and caps the field count', () => {
+        const fields: Record<string, string> = { long: 'x'.repeat(1000) };
+        for (let i = 0; i < 30; i++) fields[`f${i}`] = String(i);
+
+        const msg = buildSlackMessage(alert({ fields }));
+        expect(msg.attachments[0].fields.length).toBe(12);
+        expect(msg.attachments[0].fields[0].value).toHaveLength(400);
+        expect(msg.attachments[0].fields[0].value.endsWith('…')).toBe(true);
+    });
+
+    it('omits channel and username when unset', () => {
+        const msg = buildSlackMessage(alert());
+        expect(msg.channel).toBeUndefined();
+        expect(msg.username).toBeUndefined();
+    });
+});
+
+describe('createSlackAlertHandler', () => {
+    let fetchMock: ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+        vi.useFakeTimers();
+        fetchMock = vi.fn(async () => ({ ok: true, status: 200 }));
+        vi.stubGlobal('fetch', fetchMock);
+    });
+
+    afterEach(() => {
+        vi.useRealTimers();
+        vi.unstubAllGlobals();
+    });
+
+    it('posts the payload to the webhook', async () => {
+        const handler = createSlackAlertHandler({
+            webhookUrl: 'https://hooks.example/abc',
+            channel: '#alerts',
+        });
+        await handler(alert());
+
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        const [url, init] = fetchMock.mock.calls[0];
+        expect(url).toBe('https://hooks.example/abc');
+        expect(init.method).toBe('POST');
+        expect(JSON.parse(init.body).channel).toBe('#alerts');
+    });
+
+    it('throttles repeats of the same alarm and lets other ids through', async () => {
+        const handler = createSlackAlertHandler({
+            webhookUrl: 'https://hooks.example/abc',
+            repeatThrottleMs: 60_000,
+        });
+
+        await handler(alert());
+        await handler(alert({ repeatCount: 2, isRepeat: true }));
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+
+        await handler(alert({ id: 'other:alarm' }));
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+
+        vi.advanceTimersByTime(60_000);
+        await handler(alert({ repeatCount: 3, isRepeat: true }));
+        expect(fetchMock).toHaveBeenCalledTimes(3);
+    });
+
+    it('posts every occurrence when throttling is disabled', async () => {
+        const handler = createSlackAlertHandler({
+            webhookUrl: 'https://hooks.example/abc',
+            repeatThrottleMs: 0,
+        });
+
+        await handler(alert());
+        await handler(alert({ repeatCount: 2, isRepeat: true }));
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+
+    it('does not let a failed post consume the throttle slot', async () => {
+        fetchMock.mockResolvedValueOnce({ ok: false, status: 500 });
+        const handler = createSlackAlertHandler({
+            webhookUrl: 'https://hooks.example/abc',
+            repeatThrottleMs: 60_000,
+        });
+
+        await expect(handler(alert())).rejects.toThrow('500');
+        await handler(alert());
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+
+    it('releases the throttle slot when the post itself errors', async () => {
+        fetchMock.mockRejectedValueOnce(new Error('socket hang up'));
+        const handler = createSlackAlertHandler({
+            webhookUrl: 'https://hooks.example/abc',
+            repeatThrottleMs: 60_000,
+        });
+
+        await expect(handler(alert())).rejects.toThrow('socket hang up');
+        await handler(alert());
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+
+    it('evicts throttle entries that have aged out once the map fills', async () => {
+        const throttleMs = 60_000;
+        const handler = createSlackAlertHandler({
+            webhookUrl: 'https://hooks.example/abc',
+            repeatThrottleMs: throttleMs,
+        });
+
+        // Fill to the high-water mark, then age every entry past the window.
+        for (let i = 0; i < 5000; i++) {
+            await handler(alert({ id: `aged:${i}` }));
+        }
+        vi.advanceTimersByTime(throttleMs);
+
+        await handler(alert({ id: 'fresh' }));
+        expect(fetchMock).toHaveBeenCalledTimes(5001);
+
+        // The aged ids were pruned, so they post again immediately.
+        await handler(alert({ id: 'aged:0' }));
+        expect(fetchMock).toHaveBeenCalledTimes(5002);
+    });
+
+    it('drops the oldest entry when the map is full of live ones', async () => {
+        const handler = createSlackAlertHandler({
+            webhookUrl: 'https://hooks.example/abc',
+            repeatThrottleMs: 60_000,
+        });
+
+        for (let i = 0; i < 5000; i++) {
+            await handler(alert({ id: `live:${i}` }));
+        }
+
+        // Nothing has aged out, so the oldest id makes room for the new one.
+        await handler(alert({ id: 'newcomer' }));
+        expect(fetchMock).toHaveBeenCalledTimes(5001);
+
+        await handler(alert({ id: 'live:0' }));
+        expect(fetchMock).toHaveBeenCalledTimes(5002);
+        // The newcomer is still throttled.
+        await handler(alert({ id: 'newcomer' }));
+        expect(fetchMock).toHaveBeenCalledTimes(5002);
+    });
+});

src/backend/clients/alarm/slack.ts

@@ -0,0 +1,178 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import type { ISlackAlertConfig, PagerSeverity } from '../../types';
+import type { AlertHandler, AlertPayload } from './types';
+
+const REQUEST_TIMEOUT_MS = 5000;
+export const DEFAULT_REPEAT_THROTTLE_MS = 15 * 60 * 1000;
+
+/** Beyond this many tracked alarm ids, throttle state is pruned. */
+const MAX_THROTTLE_ENTRIES = 5000;
+
+const MAX_FIELDS = 12;
+const MAX_FIELD_VALUE = 400;
+const MAX_TRACE = 1500;
+/** Values under this length sit two-per-row in the Slack attachment. */
+const SHORT_FIELD_LENGTH = 40;
+
+const STYLE: Record<PagerSeverity, { emoji: string; color: string }> = {
+    critical: { emoji: ':rotating_light:', color: '#d64545' },
+    error: { emoji: ':red_circle:', color: '#e08d4c' },
+    warning: { emoji: ':warning:', color: '#e0b84c' },
+    info: { emoji: ':information_source:', color: '#4c8de0' },
+};
+
+interface SlackField {
+    title: string;
+    value: string;
+    short: boolean;
+}
+
+export interface SlackMessage {
+    text: string;
+    channel?: string;
+    username?: string;
+    icon_emoji?: string;
+    attachments: Array<{
+        color: string;
+        fallback: string;
+        fields: SlackField[];
+        footer: string;
+        mrkdwn_in: string[];
+        text?: string;
+    }>;
+}
+
+function truncate(value: string, max: number): string {
+    return value.length <= max ? value : `${value.slice(0, max - 1)}…`;
+}
+
+/**
+ * Render an alert as an incoming-webhook payload: severity-coloured attachment,
+ * the alarm's fields as a table, and the stack (when there is one) as a code
+ * block. Split out from the handler so the formatting is testable on its own.
+ */
+export function buildSlackMessage(
+    alert: AlertPayload,
+    opts: { channel?: string; username?: string; serverId?: string } = {},
+): SlackMessage {
+    const style = STYLE[alert.severity] ?? STYLE.info;
+    const repeat = alert.isRepeat ? ` (x${alert.repeatCount})` : '';
+    const headline = `${style.emoji} *[${alert.severity.toUpperCase()}]* ${alert.message}${repeat}`;
+
+    const fields: SlackField[] = [];
+    for (const [key, value] of Object.entries(alert.fields)) {
+        if (fields.length >= MAX_FIELDS) break;
+        // `error` is already rendered as the trace block below.
+        if (key === 'error') continue;
+        const rendered = truncate(value, MAX_FIELD_VALUE);
+        fields.push({
+            title: key,
+            value: rendered,
+            short: rendered.length <= SHORT_FIELD_LENGTH,
+        });
+    }
+
+    const footerParts = [alert.shortId, alert.id];
+    if (opts.serverId) footerParts.push(opts.serverId);
+
+    return {
+        text: headline,
+        ...(opts.channel ? { channel: opts.channel } : {}),
+        ...(opts.username ? { username: opts.username } : {}),
+        attachments: [
+            {
+                color: style.color,
+                fallback: `[${alert.severity}] ${alert.message}`,
+                fields,
+                footer: footerParts.join(' • '),
+                mrkdwn_in: ['text'],
+                ...(alert.trace
+                    ? { text: '```' + truncate(alert.trace, MAX_TRACE) + '```' }
+                    : {}),
+            },
+        ],
+    };
+}
+
+/**
+ * Post alerts to a Slack incoming webhook. Repeats of the same alarm id are
+ * throttled so a hot loop doesn't flood the channel — the occurrence count on
+ * the next post that gets through tells the reader what they missed.
+ */
+export function createSlackAlertHandler(
+    conf: ISlackAlertConfig,
+    opts: { serverId?: string } = {},
+): AlertHandler {
+    const webhookUrl = conf.webhookUrl as string;
+    const throttleMs = conf.repeatThrottleMs ?? DEFAULT_REPEAT_THROTTLE_MS;
+    const lastPosted = new Map<string, number>();
+
+    const shouldPost = (alert: AlertPayload): boolean => {
+        if (throttleMs <= 0) return true;
+        const now = Date.now();
+        const previous = lastPosted.get(alert.id);
+        if (previous !== undefined && now - previous < throttleMs) return false;
+
+        if (lastPosted.size >= MAX_THROTTLE_ENTRIES) {
+            for (const [id, at] of lastPosted) {
+                if (now - at >= throttleMs) lastPosted.delete(id);
+            }
+            // Still full of live entries — drop the oldest to stay bounded.
+            if (lastPosted.size >= MAX_THROTTLE_ENTRIES) {
+                const oldest = lastPosted.keys().next().value;
+                if (oldest !== undefined) lastPosted.delete(oldest);
+            }
+        }
+        lastPosted.set(alert.id, now);
+        return true;
+    };
+
+    return async (alert) => {
+        if (!shouldPost(alert)) return;
+
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        try {
+            const res = await fetch(webhookUrl, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(
+                    buildSlackMessage(alert, {
+                        channel: conf.channel,
+                        username: conf.username,
+                        serverId: opts.serverId,
+                    }),
+                ),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                // A rejected post shouldn't leave the id marked as delivered.
+                lastPosted.delete(alert.id);
+                throw new Error(`Slack webhook returned ${res.status}`);
+            }
+        } catch (err) {
+            lastPosted.delete(alert.id);
+            throw err;
+        } finally {
+            clearTimeout(timer);
+        }
+    };
+}

src/backend/clients/alarm/types.ts

@@ -0,0 +1,105 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import type { PagerSeverity } from '../../types';
+
+export interface AlarmFields {
+    error?: Error;
+    [key: string]: unknown;
+}
+
+export interface AlarmOccurrence {
+    message: string;
+    fields: AlarmFields;
+    timestamp: number;
+}
+
+export interface AlarmOptions {
+    /**
+     * Collapse repeats of this alarm id into a single incident on transports
+     * that de-duplicate (PagerDuty). Only right when the id already pins down
+     * one recurring fault — an uncaught error on a route, say — so that N
+     * occurrences really are one thing to fix. Off by default: every other
+     * alarm raises its own incident per occurrence.
+     */
+    dedup?: boolean;
+}
+
+export interface Alarm extends AlarmOptions {
+    id: string;
+    shortId: string;
+    message: string;
+    fields: AlarmFields;
+    error?: Error;
+    started: number;
+    /**
+     * Every occurrence ever counted, including those aged out of the two lists
+     * below.
+     */
+    count: number;
+    /**
+     * Timestamps of the most recent occurrences only — see
+     * `OCCURRENCE_HISTORY_LIMIT`.
+     */
+    timestamps: number[];
+    /** The most recent occurrences only — see `OCCURRENCE_HISTORY_LIMIT`. */
+    occurrences: AlarmOccurrence[];
+    severity?: PagerSeverity;
+    noAlert?: boolean;
+    /** Set once a config mute has been logged, so it's reported only once. */
+    muteLogged?: boolean;
+}
+
+export interface AlertPayload {
+    id: string;
+    /**
+     * Key a de-duplicating transport groups by. Equal to `id` for alarms raised
+     * with `dedup`, and unique per occurrence for everything else.
+     */
+    dedupKey: string;
+    /** Readable slug for the same alarm, for humans quoting it back. */
+    shortId: string;
+    message: string;
+    source: string;
+    severity: PagerSeverity;
+    /** Field values rendered as strings, ready to display. */
+    fields: Record<string, string>;
+    /** Stack of the attached error, when the alarm carried one. */
+    trace?: string;
+    /** Total occurrences of this alarm so far, including this one. */
+    repeatCount: number;
+    /** False for the first occurrence of an alarm id. */
+    isRepeat: boolean;
+    /** PagerDuty `custom_details` payload. */
+    custom?: Record<string, unknown>;
+}
+
+export type AlertHandler = (alert: AlertPayload) => Promise<void>;
+
+export interface KnownErrorRule {
+    match: {
+        id: string;
+        message?: string;
+        fields?: Record<string, unknown>;
+    };
+    action: {
+        type: 'no-alert' | 'severity';
+        value?: PagerSeverity;
+    };
+}

src/backend/clients/clickhouse/ClickhouseClient.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.

src/backend/clients/database/DatabaseClient.test.ts

@@ -0,0 +1,247 @@
+/**
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { describe, expect, it } from 'vitest';
+import type { IConfig } from '../../types';
+import { AbstractDatabaseClient, type WriteResult } from './DatabaseClient';
+import { DatabaseClientFactory } from './index.js';
+import { MySQLDatabaseClient } from './MySQLDatabaseClient.js';
+import { PostgresDatabaseClient } from './PostgresDatabaseClient.js';
+import { SqliteDatabaseClient } from './SqliteDatabaseClient.js';
+
+const config = (engine: string): IConfig =>
+    ({ port: 0, extensions: [], database: { engine } }) as IConfig;
+
+const sqlite = () => new SqliteDatabaseClient(config('sqlite'));
+const mysql = () => new MySQLDatabaseClient(config('mysql'));
+const postgres = () => new PostgresDatabaseClient(config('postgres'));
+
+/**
+ * Minimal concrete client backed by fixture rows — exercises the shared helpers
+ * on `AbstractDatabaseClient` that the real engines inherit.
+ */
+class FixtureDatabaseClient extends AbstractDatabaseClient {
+    override readonly engineName = 'fixture';
+    readonly reads: string[] = [];
+    readonly preads: string[] = [];
+    readonly writes: { query: string; params: unknown[] }[] = [];
+
+    constructor(
+        private readonly replicaRows: Record<string, unknown>[] | Error,
+        private readonly primaryRows: Record<string, unknown>[] = [],
+    ) {
+        super(config('fixture'));
+    }
+
+    override async read(query: string): Promise<Record<string, unknown>[]> {
+        this.reads.push(query);
+        if (this.replicaRows instanceof Error) throw this.replicaRows;
+        return this.replicaRows;
+    }
+
+    override async pread(query: string): Promise<Record<string, unknown>[]> {
+        this.preads.push(query);
+        return this.primaryRows;
+    }
+
+    override async write(
+        query: string,
+        params: unknown[] = [],
+    ): Promise<WriteResult> {
+        this.writes.push({ query, params });
+        return { insertId: 1, affectedRows: 1, anyRowsAffected: true };
+    }
+}
+
+describe('DatabaseClientFactory', () => {
+    it('picks sqlite when no engine is configured', () => {
+        expect(
+            new DatabaseClientFactory({ port: 0, extensions: [] } as IConfig),
+        ).toBeInstanceOf(SqliteDatabaseClient);
+    });
+
+    it('refuses an unknown engine name', () => {
+        expect(() => new DatabaseClientFactory(config('cassandra'))).toThrow(
+            'Unknown database engine: cassandra',
+        );
+    });
+});
+
+describe('AbstractDatabaseClient — unimplemented surface', () => {
+    const bare = () => new AbstractDatabaseClient(config('none'));
+
+    it('refuses to run queries until a subclass implements them', async () => {
+        await expect(bare().read('SELECT 1')).rejects.toThrow(
+            'DatabaseClient.read() not implemented',
+        );
+        await expect(bare().pread('SELECT 1')).rejects.toThrow(
+            'DatabaseClient.pread() not implemented',
+        );
+        await expect(bare().write('DELETE FROM x')).rejects.toThrow(
+            'DatabaseClient.write() not implemented',
+        );
+        await expect(bare().batchWrite([])).rejects.toThrow(
+            'DatabaseClient.batchWrite() not implemented',
+        );
+    });
+});
+
+describe('AbstractDatabaseClient — replica-aware reads', () => {
+    it('returns replica rows without waiting on the primary', async () => {
+        const client = new FixtureDatabaseClient([{ id: 1 }], [{ id: 2 }]);
+        await expect(client.tryHardRead('SELECT 1')).resolves.toEqual([
+            { id: 1 },
+        ]);
+    });
+
+    it('falls back to the primary when the replica has not caught up', async () => {
+        const client = new FixtureDatabaseClient([], [{ id: 2 }]);
+        await expect(client.tryHardRead('SELECT 1')).resolves.toEqual([
+            { id: 2 },
+        ]);
+    });
+
+    it('falls back to the primary when the replica read throws', async () => {
+        const client = new FixtureDatabaseClient(
+            new Error('replica unavailable'),
+            [{ id: 3 }],
+        );
+        await expect(client.tryHardRead('SELECT 1')).resolves.toEqual([
+            { id: 3 },
+        ]);
+    });
+
+    it('names the failing query when a required read finds nothing', async () => {
+        const client = new FixtureDatabaseClient([], []);
+        await expect(
+            client.requireRead('SELECT * FROM `user` WHERE `id` = ?'),
+        ).rejects.toThrow(
+            'required read returned no rows: SELECT * FROM `user` WHERE `id` = ?',
+        );
+    });
+});
+
+describe('AbstractDatabaseClient — SQL generation', () => {
+    it('generates an INSERT with quoted columns and placeholders', async () => {
+        const client = new FixtureDatabaseClient([]);
+        await client.insert('user', { username: 'ada', email: null });
+
+        expect(client.writes).toEqual([
+            {
+                query: 'INSERT INTO `user` (`username`, `email`) VALUES (?, ?)',
+                params: ['ada', null],
+            },
+        ]);
+    });
+
+    it('quotes each dotted segment and escapes embedded backticks', () => {
+        const client = sqlite();
+        expect(client.quoteIdentifier('user')).toBe('`user`');
+        expect(client.quoteIdentifier('db.user.id')).toBe('`db`.`user`.`id`');
+        expect(client.quoteIdentifier('user.*')).toBe('`user`.*');
+        expect(client.quoteIdentifier('we`ird')).toBe('`we``ird`');
+    });
+
+    it('quotes postgres identifiers with double quotes', () => {
+        const client = postgres();
+        expect(client.quoteIdentifier('db.user')).toBe('"db"."user"');
+        expect(client.quoteIdentifier('we"ird')).toBe('"we""ird"');
+        expect(client.quoteIdentifier('user.*')).toBe('"user".*');
+    });
+
+    it('renders booleans the way each engine expects', () => {
+        expect(sqlite().booleanLiteral(true)).toBe('1');
+        expect(sqlite().booleanValue(false)).toBe(0);
+        expect(postgres().booleanLiteral(true)).toBe('TRUE');
+        expect(postgres().booleanLiteral(false)).toBe('FALSE');
+        expect(postgres().booleanValue(true)).toBe(true);
+    });
+
+    it('picks the engine-specific ignore-conflict syntax', () => {
+        expect(sqlite().insertIgnoreInto('kv')).toBe(
+            'INSERT OR IGNORE INTO `kv`',
+        );
+        expect(sqlite().insertIgnoreSuffix()).toBe('');
+        expect(postgres().insertIgnoreInto('kv')).toBe('INSERT INTO "kv"');
+        expect(postgres().insertIgnoreSuffix()).toBe(' ON CONFLICT DO NOTHING');
+        expect(mysql().insertIgnoreInto('kv')).toBe('INSERT IGNORE INTO `kv`');
+        expect(mysql().insertIgnoreSuffix()).toBe('');
+    });
+
+    it('builds an upsert clause per engine', () => {
+        expect(mysql().upsertClause(['user_id'], ['value', 'dt'])).toBe(
+            'ON DUPLICATE KEY UPDATE `value` = ?, `dt` = ?',
+        );
+        expect(sqlite().upsertClause(['user_id', 'app'], ['value'])).toBe(
+            'ON CONFLICT(`user_id`, `app`) DO UPDATE SET `value` = ?',
+        );
+        expect(postgres().upsertClause(['user_id'], ['value'])).toBe(
+            'ON CONFLICT("user_id") DO UPDATE SET "value" = ?',
+        );
+    });
+
+    it('rejects an upsert with nothing to update', () => {
+        expect(() => sqlite().upsertClause(['user_id'], [])).toThrow(
+            'upsertClause requires at least one update column',
+        );
+    });
+
+    it('extracts JSON text using each engine dialect', () => {
+        expect(sqlite().jsonTextExtract('`metadata`', ['a', 'b'])).toBe(
+            "json_extract(`metadata`, '$.a.b')",
+        );
+        expect(mysql().jsonTextExtract('`metadata`', ['a'])).toBe(
+            "JSON_UNQUOTE(JSON_EXTRACT(`metadata`, '$.a'))",
+        );
+        expect(postgres().jsonTextExtract('"metadata"', ['a', 'b'])).toBe(
+            `"metadata" #>> ARRAY['a', 'b']`,
+        );
+    });
+
+    it('escapes quotes inside JSON path segments', () => {
+        expect(sqlite().jsonTextExtract('`m`', ["it's"])).toBe(
+            "json_extract(`m`, '$.it''s')",
+        );
+    });
+
+    it('coalesces expressions and rejects an empty list', () => {
+        expect(sqlite().nullCoalesce('`a`', '`b`', '0')).toBe(
+            'COALESCE(`a`, `b`, 0)',
+        );
+        expect(() => sqlite().nullCoalesce()).toThrow(
+            'nullCoalesce requires at least one expression',
+        );
+    });
+
+    it('only postgres needs a RETURNING clause to learn the insert id', () => {
+        expect(postgres().returningIdClause()).toBe(' RETURNING id');
+        expect(sqlite().returningIdClause()).toBe('');
+        expect(mysql().returningIdClause()).toBe('');
+    });
+
+    it('falls back to `otherwise` for an engine with no explicit choice', () => {
+        const client = new FixtureDatabaseClient([]);
+        expect(
+            client.case({ sqlite: 'a', mysql: 'b', otherwise: 'fallback' }),
+        ).toBe('fallback');
+        expect(client.case({ fixture: 'exact', otherwise: 'fallback' })).toBe(
+            'exact',
+        );
+    });
+});

src/backend/clients/database/DatabaseClient.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -37,8 +37,8 @@ type SqlJsonPath = readonly [string, ...string[]];
  * Base database client. Subclasses must override every method that throws here.
  *
  * Do not instantiate directly — use the factory exported from
- * `clients/database/index.ts` which picks the right implementation
- * based on `config.database.engine`.
+ * `clients/database/index.ts` which picks the right implementation based on
+ * `config.database.engine`.
  */
 export class AbstractDatabaseClient extends PuterClient {
     /** Short name used by `case()` to pick engine-specific values. */
@@ -52,9 +52,7 @@ export class AbstractDatabaseClient extends PuterClient {
     // Abstract interface — subclasses MUST override
     // ------------------------------------------------------------------
 
-    /**
-     * Execute a read query. Returns an array of row objects.
-     */
+    /** Execute a read query. Returns an array of row objects. */
     async read(
         _query: string,
         _params: unknown[] = [],
@@ -63,9 +61,9 @@ export class AbstractDatabaseClient extends PuterClient {
     }
 
     /**
-     * Read that prefers the primary database (useful when read-replicas
-     * may have replication lag). In single-node setups this is identical
-     * to `read()`.
+     * Read that prefers the primary database (useful when read-replicas may
+     * have replication lag). In single-node setups this is identical to
+     * `read()`.
      */
     async pread(
         _query: string,
@@ -74,16 +72,12 @@ export class AbstractDatabaseClient extends PuterClient {
         throw new Error('DatabaseClient.pread() not implemented');
     }
 
-    /**
-     * Execute a write query (INSERT / UPDATE / DELETE).
-     */
+    /** Execute a write query (INSERT / UPDATE / DELETE). */
     async write(_query: string, _params: unknown[] = []): Promise<WriteResult> {
         throw new Error('DatabaseClient.write() not implemented');
     }
 
-    /**
-     * Execute multiple write statements in a single transaction.
-     */
+    /** Execute multiple write statements in a single transaction. */
     async batchWrite(_entries: BatchEntry[]): Promise<void> {
         throw new Error('DatabaseClient.batchWrite() not implemented');
     }
@@ -111,9 +105,9 @@ export class AbstractDatabaseClient extends PuterClient {
     }
 
     /**
-     * Like `read()` but falls back to the primary when read-replicas are
-     * in use. Subclasses may override with replica-aware logic; the
-     * default delegates to `pread()`.
+     * Like `read()` but falls back to the primary when read-replicas are in
+     * use. Subclasses may override with replica-aware logic; the default
+     * delegates to `pread()`.
      */
     async tryHardRead(
         query: string,
@@ -133,9 +127,7 @@ export class AbstractDatabaseClient extends PuterClient {
         return primary;
     }
 
-    /**
-     * Like `tryHardRead()` but throws when the result set is empty.
-     */
+    /** Like `tryHardRead()` but throws when the result set is empty. */
     async requireRead(
         query: string,
         params: unknown[] = [],
@@ -151,9 +143,12 @@ export class AbstractDatabaseClient extends PuterClient {
      * Return the value from `choices` that matches the current engine.
      *
      * Usage:
-     * ```
-     * db.case({ sqlite: "datetime('now')", mysql: 'NOW()', otherwise: 'NOW()' })
-     * ```
+     *
+     *     db.case({
+     *         sqlite: "datetime('now')",
+     *         mysql: 'NOW()',
+     *         otherwise: 'NOW()',
+     *     });
      *
      * If the engine name isn't present in `choices`, falls back to
      * `choices.otherwise`.

src/backend/clients/database/MySQLDatabaseClient.test.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -17,8 +17,94 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import { describe, expect, it } from 'vitest';
-import { compareMigrationFilenames } from './MySQLDatabaseClient.js';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { IConfig } from '../../types';
+import {
+    MySQLDatabaseClient,
+    compareMigrationFilenames,
+} from './MySQLDatabaseClient.js';
+
+interface FakeConnection {
+    query: ReturnType<typeof vi.fn>;
+    execute: ReturnType<typeof vi.fn>;
+    beginTransaction: ReturnType<typeof vi.fn>;
+    commit: ReturnType<typeof vi.fn>;
+    rollback: ReturnType<typeof vi.fn>;
+    release: ReturnType<typeof vi.fn>;
+}
+
+interface FakePool {
+    poolConfig: Record<string, unknown>;
+    connectionHandlers: ((conn: unknown) => void)[];
+    connections: FakeConnection[];
+    calls: { sql: string; values?: unknown[] }[];
+    ended: boolean;
+    endError: unknown;
+    endThrows: unknown;
+    respond: (sql: string, values?: unknown[]) => unknown;
+    on: (event: string, handler: (conn: unknown) => void) => FakePool;
+    promise: () => { getConnection: () => Promise<FakeConnection> };
+    end: (cb: (err?: unknown) => void) => void;
+}
+
+// mysql2 is the wire boundary: stub the driver's pool so we can assert on
+// the exact SQL, parameters and connection choreography the adapter emits.
+const { createPoolMock, createdPools } = vi.hoisted(() => {
+    const createdPools: FakePool[] = [];
+
+    const createPoolMock = vi.fn((poolConfig: Record<string, unknown>) => {
+        const pool: FakePool = {
+            poolConfig,
+            connectionHandlers: [],
+            connections: [],
+            calls: [],
+            ended: false,
+            endError: null,
+            endThrows: null,
+            respond: () => [[], undefined],
+            on(event, handler) {
+                if (event === 'connection') {
+                    pool.connectionHandlers.push(handler);
+                }
+                return pool;
+            },
+            promise() {
+                return {
+                    getConnection: async () => {
+                        const run = async (sql: string, values?: unknown[]) => {
+                            pool.calls.push({ sql, values });
+                            return pool.respond(sql, values);
+                        };
+                        const conn: FakeConnection = {
+                            query: vi.fn(run),
+                            execute: vi.fn(run),
+                            beginTransaction: vi.fn(async () => {}),
+                            commit: vi.fn(async () => {}),
+                            rollback: vi.fn(async () => {}),
+                            release: vi.fn(),
+                        };
+                        pool.connections.push(conn);
+                        return conn;
+                    },
+                };
+            },
+            end(cb) {
+                if (pool.endThrows) throw pool.endThrows;
+                pool.ended = true;
+                cb(pool.endError ?? undefined);
+            },
+        };
+        createdPools.push(pool);
+        return pool;
+    });
+
+    return { createPoolMock, createdPools };
+});
+
+vi.mock('mysql2', () => ({ createPool: createPoolMock }));
 
 describe('compareMigrationFilenames', () => {
     it('orders numbered migrations numerically, not lexically', () => {
@@ -93,3 +179,669 @@ describe('compareMigrationFilenames', () => {
         expect([...sorted].sort(compareMigrationFilenames)).toEqual(sorted);
     });
 });
+
+// ── Replica read failover ───────────────────────────────────────────
+//
+// `read()` normally goes to the replica batcher; when the replica side is
+// degraded (batcher load-shed or a transient connection error) and a real
+// replica is configured, the read retries once on the primary batcher.
+
+type Batcher = { execute: ReturnType<typeof vi.fn> };
+
+const makeClient = (opts: {
+    replica: Batcher;
+    primary: Batcher;
+    multiNode?: boolean;
+}) => {
+    const client = new MySQLDatabaseClient({
+        database: { engine: 'mysql' },
+    } as IConfig);
+    // Bypass onServerStart (which would connect to a real database) and
+    // inject the batchers directly. Configuration enum: SINGLE=0, REPLICA=1.
+    Object.assign(client as unknown as Record<string, unknown>, {
+        dbReplica: opts.replica,
+        db: opts.primary,
+        configuration: opts.multiNode === false ? 0 : 1,
+    });
+    return client;
+};
+
+const codedError = (code: string) => {
+    const err = new Error(code) as Error & { code: string };
+    err.code = code;
+    return err;
+};
+
+describe('MySQLDatabaseClient.read — replica failover', () => {
+    it('fails over to the primary on batcher load-shed errors', async () => {
+        const replica = {
+            execute: vi.fn().mockRejectedValue(codedError('dbBatchFailed')),
+        };
+        const primary = { execute: vi.fn().mockResolvedValue([[{ ok: 1 }]]) };
+        const client = makeClient({ replica, primary });
+
+        await expect(client.read('SELECT 1')).resolves.toEqual([{ ok: 1 }]);
+        expect(primary.execute).toHaveBeenCalledTimes(1);
+    });
+
+    it('fails over on transient connection errors', async () => {
+        const replica = {
+            execute: vi.fn().mockRejectedValue(codedError('ECONNRESET')),
+        };
+        const primary = { execute: vi.fn().mockResolvedValue([[{ ok: 1 }]]) };
+        const client = makeClient({ replica, primary });
+
+        await expect(client.read('SELECT 1')).resolves.toEqual([{ ok: 1 }]);
+    });
+
+    it('rethrows deterministic SQL errors without touching the primary', async () => {
+        const replica = {
+            execute: vi.fn().mockRejectedValue(codedError('ER_PARSE_ERROR')),
+        };
+        const primary = { execute: vi.fn() };
+        const client = makeClient({ replica, primary });
+
+        await expect(client.read('SELEC oops')).rejects.toMatchObject({
+            code: 'ER_PARSE_ERROR',
+        });
+        expect(primary.execute).not.toHaveBeenCalled();
+    });
+
+    it('does not fail over in single-node configuration', async () => {
+        const replica = {
+            execute: vi.fn().mockRejectedValue(codedError('dbBatchFailed')),
+        };
+        const primary = { execute: vi.fn() };
+        const client = makeClient({ replica, primary, multiNode: false });
+
+        await expect(client.read('SELECT 1')).rejects.toMatchObject({
+            code: 'dbBatchFailed',
+        });
+        expect(primary.execute).not.toHaveBeenCalled();
+    });
+});
+
+// -- Driver-level behaviour (stubbed mysql2 pool) ---------------------
+
+const mysqlConfig = (
+    database: Partial<NonNullable<IConfig['database']>> = {},
+): IConfig =>
+    ({
+        port: 0,
+        extensions: [],
+        database: { engine: 'mysql', ...database },
+    }) as IConfig;
+
+const startClient = async (
+    database: Partial<NonNullable<IConfig['database']>> = {},
+): Promise<MySQLDatabaseClient> => {
+    const client = new MySQLDatabaseClient(mysqlConfig(database));
+    await client.onServerStart();
+    return client;
+};
+
+// The batcher coalesces a batch into `stmt1;stmt2; SELECT 1`, so the driver
+// must answer with one row-set per statement plus one for the SELECT 1.
+const rowSets = (...sets: unknown[][]) => [[...sets, [{ 1: 1 }]], undefined];
+
+beforeEach(() => {
+    createdPools.length = 0;
+    createPoolMock.mockClear();
+});
+
+describe('MySQLDatabaseClient — pool construction', () => {
+    it('builds the primary pool from config with multi-statement support', async () => {
+        await startClient({
+            host: 'db.internal',
+            port: 3307,
+            user: 'puter',
+            password: 'hunter2',
+            database: 'puterdb',
+        });
+
+        expect(createPoolMock).toHaveBeenCalledTimes(1);
+        expect(createdPools[0].poolConfig).toEqual({
+            maxPreparedStatements: 900,
+            connectionLimit: 30,
+            enableKeepAlive: true,
+            host: 'db.internal',
+            port: 3307,
+            user: 'puter',
+            password: 'hunter2',
+            database: 'puterdb',
+            multipleStatements: true,
+        });
+    });
+
+    it('falls back to loopback defaults when the endpoint is unspecified', async () => {
+        await startClient();
+
+        expect(createdPools[0].poolConfig).toMatchObject({
+            host: '127.0.0.1',
+            port: 3306,
+            user: 'root',
+            password: '',
+            database: 'puter',
+        });
+    });
+
+    it('arms a server-side statement timeout on every new connection', async () => {
+        await startClient({ selectTimeoutMs: 12_000 });
+
+        const pool = createdPools[0];
+        expect(pool.connectionHandlers).toHaveLength(1);
+
+        const conn = { query: vi.fn() };
+        pool.connectionHandlers[0](conn);
+        expect(conn.query).toHaveBeenCalledWith(
+            'SET SESSION max_execution_time = 12000',
+        );
+    });
+
+    it('omits the statement timeout when configured to 0', async () => {
+        await startClient({ selectTimeoutMs: 0 });
+        expect(createdPools[0].connectionHandlers).toHaveLength(0);
+    });
+
+    it('shares one pool between reads and writes without a replica', async () => {
+        await startClient();
+        expect(createPoolMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('creates a second pool when a read-replica is configured', async () => {
+        await startClient({
+            replica: { host: 'replica.internal', port: 3306 },
+        });
+
+        expect(createPoolMock).toHaveBeenCalledTimes(2);
+        expect(createdPools[1].poolConfig).toMatchObject({
+            host: 'replica.internal',
+            multipleStatements: true,
+        });
+    });
+});
+
+describe('MySQLDatabaseClient — query interface', () => {
+    it('sends the query and its parameters through to the driver', async () => {
+        const client = await startClient();
+        const pool = createdPools[0];
+        pool.respond = () => rowSets([{ id: 1, username: 'ada' }]);
+
+        await expect(
+            client.read('SELECT * FROM `user` WHERE `id` = ?', [1]),
+        ).resolves.toEqual([{ id: 1, username: 'ada' }]);
+
+        expect(pool.calls).toEqual([
+            {
+                sql: 'SELECT * FROM `user` WHERE `id` = ?; SELECT 1',
+                values: [1],
+            },
+        ]);
+    });
+
+    it('returns an empty array when the driver yields no row-set', async () => {
+        const client = await startClient();
+        createdPools[0].respond = () => [[], undefined];
+
+        await expect(client.read('SELECT 1')).resolves.toEqual([]);
+        await expect(client.pread('SELECT 1')).resolves.toEqual([]);
+    });
+
+    it('reads from the replica pool and primary-reads from the primary', async () => {
+        const client = await startClient({ replica: { host: 'replica' } });
+        const [primary, replica] = createdPools;
+        primary.respond = () => rowSets([{ from: 'primary' }]);
+        replica.respond = () => rowSets([{ from: 'replica' }]);
+
+        await expect(client.read('SELECT 1')).resolves.toEqual([
+            { from: 'replica' },
+        ]);
+        await expect(client.pread('SELECT 1')).resolves.toEqual([
+            { from: 'primary' },
+        ]);
+    });
+
+    it('maps the mysql result header onto the shared write result', async () => {
+        const client = await startClient();
+        createdPools[0].respond = () =>
+            rowSets({ insertId: 42, affectedRows: 2 } as unknown as unknown[]);
+
+        await expect(
+            client.write('UPDATE `user` SET `username` = ? WHERE `id` = ?', [
+                'ada',
+                1,
+            ]),
+        ).resolves.toEqual({
+            insertId: 42,
+            affectedRows: 2,
+            anyRowsAffected: true,
+        });
+    });
+
+    it('reports no rows affected when the header omits the counters', async () => {
+        const client = await startClient();
+        createdPools[0].respond = () => rowSets({} as unknown as unknown[]);
+
+        await expect(client.write('DELETE FROM `user`')).resolves.toEqual({
+            insertId: 0,
+            affectedRows: 0,
+            anyRowsAffected: false,
+        });
+    });
+
+    it('builds an INSERT with quoted identifiers and positional params', async () => {
+        const client = await startClient();
+        const pool = createdPools[0];
+        pool.respond = () =>
+            rowSets({ insertId: 7, affectedRows: 1 } as unknown as unknown[]);
+
+        await expect(
+            client.insert('user', { username: 'ada', email: null }),
+        ).resolves.toMatchObject({ insertId: 7 });
+
+        expect(pool.calls[0]).toEqual({
+            sql:
+                'INSERT INTO `user` (`username`, `email`) VALUES (?, ?); ' +
+                'SELECT 1',
+            values: ['ada', null],
+        });
+    });
+});
+
+describe('MySQLDatabaseClient — batchWrite transactions', () => {
+    it('runs every statement on one connection inside a transaction', async () => {
+        const client = await startClient();
+        const pool = createdPools[0];
+
+        await client.batchWrite([
+            { statement: 'UPDATE `user` SET `x` = ?', values: [1] },
+            {
+                statement: 'DELETE FROM `sessions` WHERE `uuid` = ?',
+                values: ['s'],
+            },
+        ]);
+
+        expect(pool.connections).toHaveLength(1);
+        const conn = pool.connections[0];
+        expect(conn.beginTransaction).toHaveBeenCalledTimes(1);
+        expect(conn.execute.mock.calls).toEqual([
+            ['UPDATE `user` SET `x` = ?', [1]],
+            ['DELETE FROM `sessions` WHERE `uuid` = ?', ['s']],
+        ]);
+        expect(conn.commit).toHaveBeenCalledTimes(1);
+        expect(conn.rollback).not.toHaveBeenCalled();
+        expect(conn.release).toHaveBeenCalledTimes(1);
+    });
+
+    it('rolls back and releases the connection when a statement fails', async () => {
+        const client = await startClient();
+        const pool = createdPools[0];
+        pool.respond = (sql) => {
+            if (sql.startsWith('DELETE')) throw new Error('constraint blew up');
+            return [[], undefined];
+        };
+
+        await expect(
+            client.batchWrite([
+                { statement: 'UPDATE `user` SET `x` = ?', values: [1] },
+                { statement: 'DELETE FROM `user`', values: [] },
+            ]),
+        ).rejects.toThrow('constraint blew up');
+
+        const conn = pool.connections[0];
+        expect(conn.commit).not.toHaveBeenCalled();
+        expect(conn.rollback).toHaveBeenCalledTimes(1);
+        expect(conn.release).toHaveBeenCalledTimes(1);
+    });
+
+    it('still rethrows the original failure when the rollback also fails', async () => {
+        const client = await startClient();
+        const pool = createdPools[0];
+        pool.respond = () => {
+            throw new Error('statement blew up');
+        };
+
+        const original = client.batchWrite([
+            { statement: 'UPDATE `user` SET `x` = ?', values: [1] },
+        ]);
+        // The rollback is attached after the connection is handed out, so
+        // patch it once the adapter has acquired one.
+        await Promise.resolve();
+        pool.connections[0]?.rollback.mockRejectedValue(
+            new Error('rollback blew up'),
+        );
+
+        await expect(original).rejects.toThrow('statement blew up');
+        expect(pool.connections[0].release).toHaveBeenCalledTimes(1);
+    });
+
+    it('never acquires a connection for an empty batch', async () => {
+        const client = await startClient();
+        await client.batchWrite([]);
+        expect(createdPools[0].connections).toHaveLength(0);
+    });
+});
+
+describe('MySQLDatabaseClient — tryHardRead', () => {
+    it('issues exactly one query in single-node configuration', async () => {
+        const client = await startClient();
+        const pool = createdPools[0];
+        pool.respond = () => rowSets([{ id: 1 }]);
+
+        await expect(client.tryHardRead('SELECT 1')).resolves.toEqual([
+            { id: 1 },
+        ]);
+        expect(pool.calls).toHaveLength(1);
+    });
+
+    it('prefers replica rows when the replica has them', async () => {
+        const client = await startClient({ replica: { host: 'replica' } });
+        const [primary, replica] = createdPools;
+        primary.respond = () => rowSets([{ from: 'primary' }]);
+        replica.respond = () => rowSets([{ from: 'replica' }]);
+
+        await expect(client.tryHardRead('SELECT 1')).resolves.toEqual([
+            { from: 'replica' },
+        ]);
+    });
+
+    it('falls back to the primary when the replica is behind', async () => {
+        const client = await startClient({ replica: { host: 'replica' } });
+        const [primary, replica] = createdPools;
+        primary.respond = () => rowSets([{ from: 'primary' }]);
+        replica.respond = () => rowSets([]);
+
+        await expect(client.tryHardRead('SELECT 1')).resolves.toEqual([
+            { from: 'primary' },
+        ]);
+    });
+
+    it('falls back to the primary when the replica query throws', async () => {
+        const client = await startClient({ replica: { host: 'replica' } });
+        const [primary, replica] = createdPools;
+        primary.respond = () => rowSets([{ from: 'primary' }]);
+        replica.respond = () => {
+            throw new Error('replica down');
+        };
+
+        await expect(client.tryHardRead('SELECT 1')).resolves.toEqual([
+            { from: 'primary' },
+        ]);
+    });
+});
+
+describe('MySQLDatabaseClient — migrations', () => {
+    let dir: string;
+
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), 'puter-mysql-mig-'));
+    });
+
+    afterEach(() => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+
+    it('applies mysql migrations in numeric order, one statement at a time', async () => {
+        writeFileSync(
+            join(dir, 'mysql_mig_2.sql'),
+            'CREATE TABLE b (id INT);\nCREATE TABLE c (id INT);\n',
+        );
+        writeFileSync(
+            join(dir, 'mysql_mig_10.sql'),
+            'CREATE TABLE d (id INT);',
+        );
+        // Other engines' files and non-SQL noise must be ignored.
+        writeFileSync(join(dir, 'postgres_mig_1.sql'), 'CREATE TABLE nope ();');
+        writeFileSync(join(dir, 'mysql_notes.txt'), 'not sql');
+
+        await startClient({ migrationPaths: [dir] });
+
+        const pool = createdPools[0];
+        expect(pool.calls.map((c) => c.sql)).toEqual([
+            'CREATE TABLE b (id INT)',
+            'CREATE TABLE c (id INT)',
+            'CREATE TABLE d (id INT)',
+        ]);
+        expect(pool.connections[0].release).toHaveBeenCalledTimes(1);
+    });
+
+    it('reports which file and statement index failed', async () => {
+        writeFileSync(
+            join(dir, 'mysql_mig_1.sql'),
+            'CREATE TABLE ok (id INT);\nCREATE TABLE bad (id INT);',
+        );
+
+        const client = new MySQLDatabaseClient(
+            mysqlConfig({ migrationPaths: [dir] }),
+        );
+        const cause = new Error('ER_PARSE_ERROR');
+        // The pool only exists once onServerStart runs, so arm the failure
+        // through the factory.
+        createPoolMock.mockImplementationOnce((poolConfig) => {
+            const pool = createPoolMock.getMockImplementation()!(poolConfig);
+            pool.respond = (sql: string) => {
+                if (sql.includes('bad')) throw cause;
+                return [[], undefined];
+            };
+            return pool;
+        });
+
+        await expect(client.onServerStart()).rejects.toThrow(
+            '[mysql] failed to apply mysql_mig_1.sql at statement 1',
+        );
+    });
+
+    it('fails loudly when a configured migration path is unreadable', async () => {
+        await expect(
+            startClient({ migrationPaths: [join(dir, 'does-not-exist')] }),
+        ).rejects.toThrow('[mysql] migration path is unreadable');
+    });
+
+    it('skips a configured directory that holds no mysql migrations', async () => {
+        writeFileSync(join(dir, 'readme.md'), '# nothing here');
+        await startClient({ migrationPaths: [dir] });
+        expect(createdPools[0].calls).toEqual([]);
+    });
+});
+
+describe('MySQLDatabaseClient — pool lifecycle', () => {
+    it('replaces and closes the previous primary pool on reinit', async () => {
+        const client = await startClient();
+        const original = createdPools[0];
+
+        client.reinitPrimary();
+
+        expect(createdPools).toHaveLength(2);
+        expect(original.ended).toBe(true);
+        // Single-node: the replica batcher must follow the new primary.
+        createdPools[1].respond = () => rowSets([{ from: 'new-primary' }]);
+        await expect(client.read('SELECT 1')).resolves.toEqual([
+            { from: 'new-primary' },
+        ]);
+    });
+
+    it('replaces only the replica pool on replica reinit', async () => {
+        const client = await startClient({ replica: { host: 'replica' } });
+        const [primary, originalReplica] = createdPools;
+
+        client.reinitReplica();
+
+        expect(createdPools).toHaveLength(3);
+        expect(originalReplica.ended).toBe(true);
+        expect(primary.ended).toBe(false);
+    });
+
+    it('ignores a replica reinit when no replica is configured', async () => {
+        const client = await startClient();
+        client.reinitReplica();
+        expect(createdPools).toHaveLength(1);
+    });
+
+    it('ignores reinit once shutdown has started', async () => {
+        const client = await startClient();
+        await client.onServerPrepareShutdown();
+        client.reinitPrimary();
+        expect(createdPools).toHaveLength(1);
+        await client.onServerShutdown();
+    });
+
+    it('closes both pools on shutdown when a replica is configured', async () => {
+        const client = await startClient({ replica: { host: 'replica' } });
+        await client.onServerShutdown();
+
+        expect(createdPools[0].ended).toBe(true);
+        expect(createdPools[1].ended).toBe(true);
+    });
+
+    it('closes the pools once the drain window elapses', async () => {
+        vi.useFakeTimers();
+        try {
+            const client = await startClient();
+            await client.onServerPrepareShutdown();
+            expect(createdPools[0].ended).toBe(false);
+
+            await vi.advanceTimersByTimeAsync(60_000);
+            expect(createdPools[0].ended).toBe(true);
+        } finally {
+            vi.useRealTimers();
+        }
+    });
+
+    it('cancels the drain timer when shutdown arrives first', async () => {
+        vi.useFakeTimers();
+        try {
+            const client = await startClient();
+            await client.onServerPrepareShutdown();
+            // A second prepare is a no-op — only one drain timer may exist.
+            await client.onServerPrepareShutdown();
+            expect(vi.getTimerCount()).toBe(1);
+
+            await client.onServerShutdown();
+            expect(vi.getTimerCount()).toBe(0);
+            expect(createdPools[0].ended).toBe(true);
+        } finally {
+            vi.useRealTimers();
+        }
+    });
+
+    it('surfaces a driver error raised while closing the pool', async () => {
+        const client = await startClient();
+        createdPools[0].endError = new Error('pool refused to close');
+
+        await expect(client.onServerShutdown()).rejects.toThrow(
+            'pool refused to close',
+        );
+    });
+
+    it('surfaces a driver error thrown synchronously by end()', async () => {
+        const client = await startClient();
+        createdPools[0].endThrows = new Error('end exploded');
+
+        await expect(client.onServerShutdown()).rejects.toThrow('end exploded');
+    });
+});
+
+describe('MySQLDatabaseClient.readWithRetry', () => {
+    const codedFailure = (code: string) => {
+        const err = new Error(code) as Error & { code: string };
+        err.code = code;
+        return err;
+    };
+
+    it('classifies transient connection failures as retriable', () => {
+        expect(
+            MySQLDatabaseClient.isRetriableError(codedFailure('ECONNRESET')),
+        ).toBe(true);
+        expect(
+            MySQLDatabaseClient.isRetriableError(codedFailure('ER_DUP_ENTRY')),
+        ).toBe(false);
+        expect(
+            MySQLDatabaseClient.isRetriableError(new Error('Connection lost')),
+        ).toBe(true);
+    });
+
+    it('retries a transient failure and returns the eventual result', async () => {
+        const client = await startClient();
+        let attempts = 0;
+        const operation = vi.fn(async () => {
+            attempts += 1;
+            if (attempts < 3) throw codedFailure('PROTOCOL_CONNECTION_LOST');
+            return [{ ok: 1 }];
+        });
+
+        await expect(
+            client.readWithRetry('health', operation, { baseBackoffMs: 0 }),
+        ).resolves.toEqual([{ ok: 1 }]);
+        expect(operation).toHaveBeenCalledTimes(3);
+    });
+
+    it('gives up after the attempt budget is spent', async () => {
+        const client = await startClient();
+        const operation = vi.fn(async () => {
+            throw codedFailure('ETIMEDOUT');
+        });
+
+        await expect(
+            client.readWithRetry('health', operation, {
+                maxAttempts: 2,
+                baseBackoffMs: 0,
+            }),
+        ).rejects.toMatchObject({ code: 'ETIMEDOUT' });
+        expect(operation).toHaveBeenCalledTimes(2);
+    });
+
+    it('never retries a deterministic SQL error', async () => {
+        const client = await startClient();
+        const operation = vi.fn(async () => {
+            throw codedFailure('ER_PARSE_ERROR');
+        });
+
+        await expect(
+            client.readWithRetry('health', operation, { baseBackoffMs: 0 }),
+        ).rejects.toMatchObject({ code: 'ER_PARSE_ERROR' });
+        expect(operation).toHaveBeenCalledTimes(1);
+    });
+
+    it('stops retrying once shutdown has started', async () => {
+        const client = await startClient();
+        await client.onServerPrepareShutdown();
+        const operation = vi.fn(async () => {
+            throw codedFailure('ECONNRESET');
+        });
+
+        await expect(
+            client.readWithRetry('health', operation, { baseBackoffMs: 0 }),
+        ).rejects.toMatchObject({ code: 'ECONNRESET' });
+        expect(operation).toHaveBeenCalledTimes(1);
+        await client.onServerShutdown();
+    });
+
+    it('applies jittered exponential backoff capped at maxBackoffMs', async () => {
+        const client = await startClient();
+        const delays: number[] = [];
+        const realSetTimeout = globalThis.setTimeout;
+        const timeoutSpy = vi
+            .spyOn(globalThis, 'setTimeout')
+            .mockImplementation(((fn: () => void, ms?: number) => {
+                delays.push(ms ?? 0);
+                return realSetTimeout(fn, 0);
+            }) as typeof setTimeout);
+
+        try {
+            const operation = vi.fn(async () => {
+                throw codedFailure('ECONNRESET');
+            });
+            await expect(
+                client.readWithRetry('health', operation, {
+                    maxAttempts: 4,
+                    baseBackoffMs: 100,
+                    maxBackoffMs: 150,
+                    jitterRatio: 0,
+                }),
+            ).rejects.toMatchObject({ code: 'ECONNRESET' });
+            expect(delays).toEqual([100, 150, 150]);
+        } finally {
+            timeoutSpy.mockRestore();
+        }
+    });
+});

src/backend/clients/database/MySQLDatabaseClient.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -19,32 +19,24 @@
 
 import { readdirSync, readFileSync } from 'fs';
 import { isAbsolute, resolve as resolvePath } from 'path';
+import { metrics } from '@opentelemetry/api';
 import { createPool, type Pool } from 'mysql2';
 import { Span } from '../../util/span.js';
 import { AbstractDatabaseClient, type WriteResult } from './DatabaseClient';
 import { SQLBatcher } from './SQLBatcher.js';
+import { isRetriableError } from './retriableErrors.js';
 import { splitMysqlStatements } from './splitMysqlStatements.js';
 import { compareMigrationFilenames } from './migrationFilenames.js';
 import type { IConfig } from '../../types';
 
-const RETRIABLE_ERROR_CODES = new Set([
-    'PROTOCOL_CONNECTION_LOST',
-    'PROTOCOL_SEQUENCE_TIMEOUT',
-    'PROTOCOL_ENQUEUE_AFTER_FATAL_ERROR',
-    'ECONNRESET',
-    'ETIMEDOUT',
-    'EPIPE',
-    'ECONNREFUSED',
-    'EHOSTUNREACH',
-    'ENETUNREACH',
-    'EAI_AGAIN',
-]);
+const DEFAULT_SELECT_TIMEOUT_MS = 30_000;
 
-const RETRIABLE_ERROR_MESSAGES = [
-    'Connection lost',
-    'read ECONNRESET',
-    'ETIMEDOUT',
-];
+const replicaFailoverCounter = metrics
+    .getMeter('puter-backend')
+    .createCounter('db.read.replica_failover', {
+        description:
+            'Reads that failed on the replica batcher and were retried on the primary',
+    });
 
 export { compareMigrationFilenames };
 
@@ -86,7 +78,7 @@ export class MySQLDatabaseClient extends AbstractDatabaseClient {
         });
         console.log('[mysql] connected to primary');
 
-        this.db = new SQLBatcher(this.primaryPool, 30, 5);
+        this.db = this.createPrimaryBatcher(this.primaryPool);
 
         if (dbConf.replica) {
             this.replicaPool = this.createPool(dbConf.replica);
@@ -97,7 +89,7 @@ export class MySQLDatabaseClient extends AbstractDatabaseClient {
             this.configuration = Configuration.SINGLE;
         }
 
-        this.dbReplica = new SQLBatcher(this.replicaPool, 10, 5);
+        this.dbReplica = this.createReplicaBatcher(this.replicaPool);
 
         await this.runMigrations();
     }
@@ -144,7 +136,23 @@ export class MySQLDatabaseClient extends AbstractDatabaseClient {
         query: string,
         params: unknown[] = [],
     ): Promise<Record<string, unknown>[]> {
-        const result = await this.dbReplica.execute(query, params);
+        let result;
+        try {
+            result = await this.dbReplica.execute(query, params);
+        } catch (error) {
+            // Replica-side degradation (batcher load-shed or a transient
+            // connection failure) shouldn't fail reads while the primary is
+            // healthy. Deterministic errors (bad SQL) are rethrown — they
+            // would fail identically on the primary.
+            if (
+                this.configuration !== Configuration.REPLICA ||
+                !MySQLDatabaseClient.isFailoverWorthy(error)
+            ) {
+                throw error;
+            }
+            replicaFailoverCounter.add(1);
+            result = await this.db.execute(query, params);
+        }
         if (!result) return [];
         return (result[0] as Record<string, unknown>[]) ?? [];
     }
@@ -240,9 +248,9 @@ export class MySQLDatabaseClient extends AbstractDatabaseClient {
 
     /**
      * Apply `.sql` files from each configured migration directory in order.
-     * Files within a directory are sorted lexically. Files MUST be
-     * idempotent — there is no per-file applied-state tracking. Failures
-     * abort startup so operators see schema problems loud.
+     * Files within a directory are sorted lexically. Files MUST be idempotent —
+     * there is no per-file applied-state tracking. Failures abort startup so
+     * operators see schema problems loud.
      */
     private async runMigrations(): Promise<void> {
         const paths = this.config.database?.migrationPaths;
@@ -307,12 +315,53 @@ export class MySQLDatabaseClient extends AbstractDatabaseClient {
     // ------------------------------------------------------------------
 
     private createPool(poolConfig: PoolConfig): Pool {
-        return createPool({
+        const pool = createPool({
             maxPreparedStatements: 900,
             connectionLimit: 30,
+            enableKeepAlive: true,
             ...poolConfig,
             multipleStatements: true,
         } as PoolConfig);
+
+        // Server-side kill switch for runaway reads: MySQL applies
+        // max_execution_time to SELECT statements only, so this is
+        // write-safe. Without it, a stalled database turns reads into
+        // indefinite hangs that no client-side timeout ever converts
+        // into a failure. 0 disables.
+        const selectTimeoutMs = Math.floor(
+            Number(
+                this.config.database?.selectTimeoutMs ??
+                    DEFAULT_SELECT_TIMEOUT_MS,
+            ),
+        );
+        if (selectTimeoutMs > 0) {
+            pool.on('connection', (conn) => {
+                conn.query(
+                    `SET SESSION max_execution_time = ${selectTimeoutMs}`,
+                );
+            });
+        }
+
+        return pool;
+    }
+
+    private createPrimaryBatcher(pool: Pool): SQLBatcher {
+        return new SQLBatcher(pool, {
+            maxTimeInQueue: 30,
+            maxBatchSize: 5,
+            poolLabel: 'primary',
+            acquireTimeoutMs: this.config.database?.acquireTimeoutMs,
+        });
+    }
+
+    private createReplicaBatcher(pool: Pool): SQLBatcher {
+        return new SQLBatcher(pool, {
+            maxTimeInQueue: 10,
+            maxBatchSize: 5,
+            poolLabel: 'replica',
+            readOnly: true,
+            acquireTimeoutMs: this.config.database?.acquireTimeoutMs,
+        });
     }
 
     /** Reinitialize the primary pool (e.g. after a health-check failure). */
@@ -328,11 +377,11 @@ export class MySQLDatabaseClient extends AbstractDatabaseClient {
             password: dbConf.password ?? '',
             database: dbConf.database ?? 'puter',
         });
-        this.db = new SQLBatcher(this.primaryPool, 30, 5);
+        this.db = this.createPrimaryBatcher(this.primaryPool);
 
         if (this.configuration === Configuration.SINGLE) {
             this.replicaPool = this.primaryPool;
-            this.dbReplica = new SQLBatcher(this.primaryPool, 10, 5);
+            this.dbReplica = this.createReplicaBatcher(this.primaryPool);
         }
 
         if (previous && previous !== this.primaryPool) {
@@ -346,7 +395,7 @@ export class MySQLDatabaseClient extends AbstractDatabaseClient {
 
         const previous = this.replicaPool;
         this.replicaPool = this.createPool(this.config.database.replica);
-        this.dbReplica = new SQLBatcher(this.replicaPool, 10, 5);
+        this.dbReplica = this.createReplicaBatcher(this.replicaPool);
 
         if (
             previous &&
@@ -362,11 +411,16 @@ export class MySQLDatabaseClient extends AbstractDatabaseClient {
     // ------------------------------------------------------------------
 
     static isRetriableError(error: unknown): boolean {
-        const code = (error as { code?: string })?.code;
-        if (code && RETRIABLE_ERROR_CODES.has(code)) return true;
+        return isRetriableError(error);
+    }
 
-        const msg = String((error as Error)?.message ?? '');
-        return RETRIABLE_ERROR_MESSAGES.some((m) => msg.includes(m));
+    /**
+     * Replica failures worth retrying on the primary: batcher load-shed or
+     * transient connection errors — never deterministic SQL errors.
+     */
+    private static isFailoverWorthy(error: unknown): boolean {
+        const code = (error as { code?: string })?.code;
+        return code === 'dbBatchFailed' || isRetriableError(error);
     }
 
     async readWithRetry(

src/backend/clients/database/PostgresDatabaseClient.integration.test.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.

src/backend/clients/database/PostgresDatabaseClient.test.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.

src/backend/clients/database/PostgresDatabaseClient.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.

src/backend/clients/database/SQLBatcher.js

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -18,10 +18,20 @@
  */
 
 import { metrics } from '@opentelemetry/api';
+import {
+    POOL_ACQUIRE_TIMEOUT,
+    isNeverSentError,
+    isRetriableError,
+    isRolledBackError,
+} from './retriableErrors.js';
 
 const DEFAULT_MAX_QUEUE_SIZE = 1000;
 const DEFAULT_FAILURE_THRESHOLD = 5;
 const DEFAULT_COOLDOWN_MS = 5_000;
+const DEFAULT_ACQUIRE_TIMEOUT_MS = 5_000;
+const ACQUIRE_ATTEMPTS = 3;
+const ITEM_RETRY_ATTEMPTS = 2;
+const RETRY_BASE_BACKOFF_MS = 100;
 const FALLBACK_RETRY_CONCURRENCY = 8;
 
 const meter = metrics.getMeter('puter-backend');
@@ -53,6 +63,15 @@ const fallbackItemFailuresCounter = meter.createCounter(
             'Per-item failures observed during SQLBatcher per-item retry',
     },
 );
+const fallbackItemRetriesCounter = meter.createCounter(
+    'sql_batcher.fallback.item_retries',
+    {
+        description:
+            'Transient per-item failures retried during SQLBatcher fallback',
+    },
+);
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 export class SQLBatcher {
     dbPool;
@@ -61,18 +80,45 @@ export class SQLBatcher {
     maxQueueSize;
     failureThreshold;
     cooldownMs;
+    poolLabel;
+    readOnly;
+    acquireTimeoutMs;
     queue = [];
     timeouts = [];
     #consecutiveFailures = 0;
     #lastFailureAt = 0;
+    #metricAttrs;
 
+    /**
+     * @param {object} dbPool Mysql2 pool
+     * @param {object} [opts]
+     * @param {number} [opts.maxTimeInQueue] Ms an item may wait before flush
+     * @param {number} [opts.maxBatchSize] Items coalesced per flush
+     * @param {number} [opts.maxQueueSize] Drop-oldest high-water mark
+     * @param {number} [opts.failureThreshold] Consecutive failures to open the
+     *   breaker
+     * @param {number} [opts.cooldownMs] Breaker open duration after last
+     *   failure
+     * @param {'primary' | 'replica'} [opts.poolLabel] Role label on metrics; in
+     *   single-node setups the 'replica' batcher shares the primary pool, so
+     *   this reflects the read/write role rather than a physical instance
+     * @param {boolean} [opts.readOnly] This batcher only ever carries SELECTs,
+     *   so any transient failure is safe to retry
+     * @param {number} [opts.acquireTimeoutMs] Max wait for a pooled connection;
+     *   0 disables the bound
+     */
     constructor(
         dbPool,
-        maxTimeInQueue = 20,
-        maxBatchSize = 50,
-        maxQueueSize = DEFAULT_MAX_QUEUE_SIZE,
-        failureThreshold = DEFAULT_FAILURE_THRESHOLD,
-        cooldownMs = DEFAULT_COOLDOWN_MS,
+        {
+            maxTimeInQueue = 20,
+            maxBatchSize = 50,
+            maxQueueSize = DEFAULT_MAX_QUEUE_SIZE,
+            failureThreshold = DEFAULT_FAILURE_THRESHOLD,
+            cooldownMs = DEFAULT_COOLDOWN_MS,
+            poolLabel = 'primary',
+            readOnly = false,
+            acquireTimeoutMs = DEFAULT_ACQUIRE_TIMEOUT_MS,
+        } = {},
     ) {
         this.dbPool = dbPool;
         this.maxTimeInQueue = maxTimeInQueue;
@@ -80,6 +126,10 @@ export class SQLBatcher {
         this.maxQueueSize = maxQueueSize;
         this.failureThreshold = failureThreshold;
         this.cooldownMs = cooldownMs;
+        this.poolLabel = poolLabel;
+        this.readOnly = readOnly;
+        this.acquireTimeoutMs = acquireTimeoutMs;
+        this.#metricAttrs = { pool: poolLabel };
     }
 
     async execute(sql, values) {
@@ -90,9 +140,13 @@ export class SQLBatcher {
         return this;
     }
 
-    #createPublicBatchError() {
+    // The public error is deliberately opaque (no SQL, no internals), but
+    // `reason` distinguishes the load-shed path for logs and callers:
+    // breakerOpen | queueOverflow | connAcquire.
+    #createPublicBatchError(reason) {
         const error = new Error('Database operation failed');
         error.code = 'dbBatchFailed';
+        error.reason = reason;
         return error;
     }
 
@@ -106,8 +160,8 @@ export class SQLBatcher {
 
     async query(sql, values) {
         if (this.#isBreakerOpen()) {
-            enqueueRejectedCounter.add(1);
-            throw this.#createPublicBatchError();
+            enqueueRejectedCounter.add(1, this.#metricAttrs);
+            throw this.#createPublicBatchError('breakerOpen');
         }
 
         const { promise, resolve, reject } = Promise.withResolvers();
@@ -117,8 +171,8 @@ export class SQLBatcher {
         // to have already exceeded any caller-side timeout anyway.
         while (this.queue.length >= this.maxQueueSize) {
             const dropped = this.queue.shift();
-            dropped.reject(this.#createPublicBatchError());
-            enqueueDroppedCounter.add(1);
+            dropped.reject(this.#createPublicBatchError('queueOverflow'));
+            enqueueDroppedCounter.add(1, this.#metricAttrs);
         }
 
         this.queue.push({
@@ -142,6 +196,61 @@ export class SQLBatcher {
         return promise;
     }
 
+    // Bounded wait for a pooled connection. Without a bound, a stalled
+    // database turns every flush into an indefinite hang — nothing fails,
+    // so neither the breaker nor callers' own timeouts ever engage.
+    #getConnectionWithTimeout() {
+        const acquire = this.dbPool.promise().getConnection();
+        if (!this.acquireTimeoutMs) return acquire;
+
+        return new Promise((resolve, reject) => {
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                // A connection that arrives late must go back to the pool.
+                acquire.then(
+                    (conn) => conn.release(),
+                    () => {},
+                );
+                const error = new Error(
+                    'Timed out acquiring database connection',
+                );
+                error.code = POOL_ACQUIRE_TIMEOUT;
+                reject(error);
+            }, this.acquireTimeoutMs);
+
+            acquire.then(
+                (conn) => {
+                    if (timedOut) return;
+                    clearTimeout(timer);
+                    resolve(conn);
+                },
+                (err) => {
+                    if (timedOut) return;
+                    clearTimeout(timer);
+                    reject(err);
+                },
+            );
+        });
+    }
+
+    // Acquisition failures never sent a statement, so retrying is always
+    // safe regardless of what the batch contains.
+    async #acquireConnection() {
+        let lastError;
+        for (let attempt = 1; attempt <= ACQUIRE_ATTEMPTS; attempt++) {
+            try {
+                return await this.#getConnectionWithTimeout();
+            } catch (error) {
+                lastError = error;
+                if (attempt < ACQUIRE_ATTEMPTS) {
+                    await sleep(RETRY_BASE_BACKOFF_MS * attempt);
+                }
+            }
+        }
+        throw lastError;
+    }
+
     async flush(batch) {
         const timeout = this.timeouts.shift();
         if (timeout && !timeout._destroyed) {
@@ -154,17 +263,17 @@ export class SQLBatcher {
 
         let connection;
         try {
-            connection = await this.dbPool.promise().getConnection();
+            connection = await this.#acquireConnection();
         } catch (error) {
             this.#consecutiveFailures++;
             this.#lastFailureAt = Date.now();
-            flushFailureCounter.add(1);
+            flushFailureCounter.add(1, this.#metricAttrs);
             console.warn(
                 'SQLBatcher could not acquire connection for flush:',
                 error,
             );
             for (const b of batch) {
-                b.reject(this.#createPublicBatchError());
+                b.reject(this.#createPublicBatchError('connAcquire'));
             }
             return;
         }
@@ -206,8 +315,8 @@ export class SQLBatcher {
         // committed; re-running each item independently produces clean
         // success/failure outcomes for each caller. Concurrency is capped to
         // avoid briefly saturating the pool when a large batch fails.
-        flushFailureCounter.add(1);
-        fallbackInvocationsCounter.add(1);
+        flushFailureCounter.add(1, this.#metricAttrs);
+        fallbackInvocationsCounter.add(1, this.#metricAttrs);
 
         const settled = new Array(batch.length);
         let cursor = 0;
@@ -216,17 +325,7 @@ export class SQLBatcher {
             async () => {
                 while (cursor < batch.length) {
                     const i = cursor++;
-                    const b = batch[i];
-                    try {
-                        settled[i] = {
-                            ok: true,
-                            value: await this.dbPool
-                                .promise()
-                                .query(b.sql, b.values ?? []),
-                        };
-                    } catch (error) {
-                        settled[i] = { ok: false, error };
-                    }
+                    settled[i] = await this.#runFallbackItem(batch[i]);
                 }
             },
         );
@@ -246,7 +345,7 @@ export class SQLBatcher {
             }
         }
         if (failureCount > 0) {
-            fallbackItemFailuresCounter.add(failureCount);
+            fallbackItemFailuresCounter.add(failureCount, this.#metricAttrs);
         }
 
         // Only escalate the breaker when the database itself looks unhealthy
@@ -259,4 +358,45 @@ export class SQLBatcher {
             this.#consecutiveFailures++;
         }
     }
+
+    // Run one fallback item, retrying transient failures with backoff.
+    // A read-only batcher may retry anything transient; a batcher that
+    // carries writes only retries failures where the statement provably
+    // did not apply — either it never reached the server, or the server
+    // rolled it back itself. A write that died mid-flight may have
+    // committed, and re-running that one would double-apply.
+    //
+    // Lock contention lands in the second group and is worth retrying rather
+    // than surfacing: an item is a single statement, so a deadlock victim has
+    // been fully undone, and the caller sees an unhandled 500 for what the
+    // database is telling us to just run again.
+    async #runFallbackItem(b) {
+        let attempt = 0;
+        while (true) {
+            let connection;
+            try {
+                connection = await this.#acquireConnection();
+            } catch (error) {
+                return { ok: false, error };
+            }
+            try {
+                return {
+                    ok: true,
+                    value: await connection.query(b.sql, b.values ?? []),
+                };
+            } catch (error) {
+                const canRetry = this.readOnly
+                    ? isRetriableError(error) || isRolledBackError(error)
+                    : isNeverSentError(error) || isRolledBackError(error);
+                if (!canRetry || attempt >= ITEM_RETRY_ATTEMPTS) {
+                    return { ok: false, error };
+                }
+                attempt++;
+                fallbackItemRetriesCounter.add(1, this.#metricAttrs);
+                await sleep(RETRY_BASE_BACKOFF_MS * attempt);
+            } finally {
+                connection.release();
+            }
+        }
+    }
 }

src/backend/clients/database/SQLBatcher.test.ts

@@ -0,0 +1,269 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { SQLBatcher } from './SQLBatcher.js';
+
+const makeError = (code: string, message = code): Error & { code: string } => {
+    const error = new Error(message) as Error & { code: string };
+    error.code = code;
+    return error;
+};
+
+interface FakeConnection {
+    beginTransaction: ReturnType<typeof vi.fn>;
+    query: ReturnType<typeof vi.fn>;
+    commit: ReturnType<typeof vi.fn>;
+    rollback: ReturnType<typeof vi.fn>;
+    release: ReturnType<typeof vi.fn>;
+}
+
+// The batch flush sends one coalesced multi-statement (always suffixed
+// `; SELECT 1`); fallback items send their original single statement.
+const isBatchQuery = (sql: string) => sql.endsWith('; SELECT 1');
+
+const makeConnection = (
+    onQuery: (sql: string, values: unknown[]) => unknown,
+): FakeConnection => ({
+    beginTransaction: vi.fn(async () => {}),
+    query: vi.fn(async (sql: string, values: unknown[]) => onQuery(sql, values)),
+    commit: vi.fn(async () => {}),
+    rollback: vi.fn(async () => {}),
+    release: vi.fn(),
+});
+
+const makePool = (connection: FakeConnection | (() => Promise<FakeConnection>)) => {
+    const getConnection = vi.fn(async () =>
+        typeof connection === 'function' ? connection() : connection,
+    );
+    return {
+        pool: { promise: () => ({ getConnection }) },
+        getConnection,
+    };
+};
+
+// Happy-path onQuery: batch returns one result row-set per statement plus
+// the trailing SELECT 1 row-set.
+const happyBatch = (sql: string) => {
+    if (!isBatchQuery(sql)) throw new Error('unexpected fallback query');
+    const statements = sql.split(';').length - 1;
+    return [
+        Array.from({ length: statements + 1 }, (_, i) => [{ n: i }]),
+        undefined,
+    ];
+};
+
+describe('SQLBatcher', () => {
+    it('resolves each batched item with its own result', async () => {
+        const conn = makeConnection(happyBatch);
+        const { pool } = makePool(conn);
+        const batcher = new SQLBatcher(pool, { maxTimeInQueue: 5 });
+
+        const [a, b] = await Promise.all([
+            batcher.query('SELECT a', []),
+            batcher.query('SELECT b', []),
+        ]);
+        expect(a[0]).toEqual([{ n: 0 }]);
+        expect(b[0]).toEqual([{ n: 1 }]);
+        expect(conn.beginTransaction).toHaveBeenCalledTimes(1);
+        expect(conn.commit).toHaveBeenCalledTimes(1);
+        expect(conn.release).toHaveBeenCalledTimes(1);
+    });
+
+    it('drops the oldest item with reason queueOverflow at the high-water mark', async () => {
+        const conn = makeConnection(happyBatch);
+        const { pool } = makePool(conn);
+        const batcher = new SQLBatcher(pool, {
+            maxTimeInQueue: 5,
+            maxQueueSize: 1,
+        });
+
+        const first = batcher.query('SELECT a', []);
+        const second = batcher.query('SELECT b', []);
+
+        await expect(first).rejects.toMatchObject({
+            code: 'dbBatchFailed',
+            reason: 'queueOverflow',
+        });
+        await expect(second).resolves.toBeTruthy();
+    });
+
+    it('rejects with reason connAcquire after exhausting acquisition retries', async () => {
+        const getConnection = vi.fn(async () => {
+            throw makeError('ECONNREFUSED');
+        });
+        const pool = { promise: () => ({ getConnection }) };
+        const batcher = new SQLBatcher(pool, { maxTimeInQueue: 5 });
+
+        await expect(batcher.query('SELECT a', [])).rejects.toMatchObject({
+            code: 'dbBatchFailed',
+            reason: 'connAcquire',
+        });
+        expect(getConnection).toHaveBeenCalledTimes(3);
+    });
+
+    it('bounds connection acquisition and rejects when the pool never answers', async () => {
+        const getConnection = vi.fn(
+            () => new Promise(() => {}), // pool never yields a connection
+        );
+        const pool = { promise: () => ({ getConnection }) };
+        const batcher = new SQLBatcher(pool, {
+            maxTimeInQueue: 5,
+            acquireTimeoutMs: 30,
+        });
+
+        await expect(batcher.query('SELECT a', [])).rejects.toMatchObject({
+            code: 'dbBatchFailed',
+            reason: 'connAcquire',
+        });
+        expect(getConnection).toHaveBeenCalledTimes(3);
+    });
+
+    it('opens the breaker after consecutive failures and rejects with reason breakerOpen', async () => {
+        // Batch and fallback both fail with an ambiguous (non-retriable for
+        // writes) connection error, so no item gets through.
+        const conn = makeConnection(() => {
+            throw makeError('ECONNRESET');
+        });
+        const { pool } = makePool(conn);
+        const batcher = new SQLBatcher(pool, {
+            maxTimeInQueue: 5,
+            failureThreshold: 1,
+            cooldownMs: 60_000,
+        });
+
+        await expect(batcher.query('INSERT x', [])).rejects.toMatchObject({
+            code: 'ECONNRESET',
+        });
+        await expect(batcher.query('INSERT y', [])).rejects.toMatchObject({
+            code: 'dbBatchFailed',
+            reason: 'breakerOpen',
+        });
+    });
+
+    it('retries transient fallback failures when readOnly', async () => {
+        let fallbackAttempts = 0;
+        const conn = makeConnection((sql) => {
+            if (isBatchQuery(sql)) throw makeError('ECONNRESET');
+            fallbackAttempts++;
+            if (fallbackAttempts === 1) throw makeError('ECONNRESET');
+            return [[{ ok: 1 }], undefined];
+        });
+        const { pool } = makePool(conn);
+        const batcher = new SQLBatcher(pool, {
+            maxTimeInQueue: 5,
+            readOnly: true,
+        });
+
+        const result = await batcher.query('SELECT a', []);
+        expect(result[0]).toEqual([{ ok: 1 }]);
+        expect(fallbackAttempts).toBe(2);
+    });
+
+    it('does not retry ambiguous failures on a batcher that carries writes', async () => {
+        let fallbackAttempts = 0;
+        const conn = makeConnection((sql) => {
+            if (isBatchQuery(sql)) throw makeError('ECONNRESET');
+            fallbackAttempts++;
+            throw makeError('ECONNRESET');
+        });
+        const { pool } = makePool(conn);
+        const batcher = new SQLBatcher(pool, { maxTimeInQueue: 5 });
+
+        await expect(batcher.query('INSERT x', [])).rejects.toMatchObject({
+            code: 'ECONNRESET',
+        });
+        expect(fallbackAttempts).toBe(1);
+    });
+
+    it('retries never-sent failures even on a batcher that carries writes', async () => {
+        let fallbackAttempts = 0;
+        const conn = makeConnection((sql) => {
+            if (isBatchQuery(sql)) throw makeError('ECONNRESET');
+            fallbackAttempts++;
+            if (fallbackAttempts === 1) throw makeError('ECONNREFUSED');
+            return [[{ ok: 1 }], undefined];
+        });
+        const { pool } = makePool(conn);
+        const batcher = new SQLBatcher(pool, { maxTimeInQueue: 5 });
+
+        const result = await batcher.query('INSERT x', []);
+        expect(result[0]).toEqual([{ ok: 1 }]);
+        expect(fallbackAttempts).toBe(2);
+    });
+
+    it('retries a deadlocked write instead of surfacing it', async () => {
+        let fallbackAttempts = 0;
+        const conn = makeConnection((sql) => {
+            if (isBatchQuery(sql)) throw makeError('ER_LOCK_DEADLOCK');
+            fallbackAttempts++;
+            if (fallbackAttempts === 1) throw makeError('ER_LOCK_DEADLOCK');
+            return [[{ ok: 1 }], undefined];
+        });
+        const { pool } = makePool(conn);
+        const batcher = new SQLBatcher(pool, { maxTimeInQueue: 5 });
+
+        // The victim statement was rolled back by the server, so re-running it
+        // can't double-apply — the caller should never see the deadlock.
+        const result = await batcher.query('UPDATE notification SET x', []);
+        expect(result[0]).toEqual([{ ok: 1 }]);
+        expect(fallbackAttempts).toBe(2);
+    });
+
+    it('gives up on a write that deadlocks past the retry budget', async () => {
+        const conn = makeConnection(() => {
+            throw makeError('ER_LOCK_DEADLOCK');
+        });
+        const { pool } = makePool(conn);
+        const batcher = new SQLBatcher(pool, { maxTimeInQueue: 5 });
+
+        await expect(batcher.query('UPDATE hot SET x', [])).rejects.toMatchObject(
+            { code: 'ER_LOCK_DEADLOCK' },
+        );
+    });
+
+    it('never retries deterministic row-level errors and does not escalate the breaker', async () => {
+        let fallbackAttempts = 0;
+        const conn = makeConnection((sql) => {
+            if (isBatchQuery(sql)) throw makeError('ER_DUP_ENTRY');
+            fallbackAttempts++;
+            if (sql === 'INSERT dup') throw makeError('ER_DUP_ENTRY');
+            return [[{ ok: 1 }], undefined];
+        });
+        const { pool } = makePool(conn);
+        const batcher = new SQLBatcher(pool, {
+            maxTimeInQueue: 5,
+            failureThreshold: 1,
+            cooldownMs: 60_000,
+            readOnly: true,
+        });
+
+        const dup = batcher.query('INSERT dup', []);
+        const fine = batcher.query('INSERT fine', []);
+        await expect(dup).rejects.toMatchObject({ code: 'ER_DUP_ENTRY' });
+        await expect(fine).resolves.toBeTruthy();
+        expect(fallbackAttempts).toBe(2);
+
+        // One fallback item succeeded, so the breaker must stay closed.
+        const conn2 = makeConnection(happyBatch);
+        // reuse same batcher/pool: next query must not be rejected upfront
+        conn.query.mockImplementation(conn2.query.getMockImplementation()!);
+        await expect(batcher.query('SELECT a', [])).resolves.toBeTruthy();
+    });
+});

src/backend/clients/database/SqliteDatabaseClient.test.ts

@@ -0,0 +1,437 @@
+/**
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import Database from 'better-sqlite3';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { IConfig } from '../../types';
+import { DatabaseClientFactory } from './index.js';
+import { SqliteDatabaseClient } from './SqliteDatabaseClient.js';
+
+/** Highest schema version the migration table can reach. */
+const CURRENT_SCHEMA_VERSION = 61;
+const SYSTEM_USER_UUID = '5d4adce0-a381-4982-9c02-6e2540026238';
+
+const sqliteConfig = (
+    database: Partial<NonNullable<IConfig['database']>> = {},
+): IConfig =>
+    ({
+        port: 0,
+        extensions: [],
+        database: { engine: 'sqlite', inMemory: true, ...database },
+    }) as IConfig;
+
+const bootClient = async (
+    database: Partial<NonNullable<IConfig['database']>> = {},
+): Promise<SqliteDatabaseClient> => {
+    const client = new SqliteDatabaseClient(sqliteConfig(database));
+    await client.onServerStart();
+    return client;
+};
+
+const userVersionOf = async (client: SqliteDatabaseClient): Promise<number> => {
+    const [row] = await client.read('PRAGMA user_version');
+    return row.user_version as number;
+};
+
+describe('SqliteDatabaseClient — boot and migrations', () => {
+    let client: SqliteDatabaseClient;
+
+    beforeEach(async () => {
+        client = await bootClient();
+    });
+
+    afterEach(() => {
+        client.onServerShutdown();
+    });
+
+    it('is what the factory picks for the sqlite engine', () => {
+        expect(new DatabaseClientFactory(sqliteConfig())).toBeInstanceOf(
+            SqliteDatabaseClient,
+        );
+    });
+
+    it('migrates a fresh database all the way to the current version', async () => {
+        expect(await userVersionOf(client)).toBe(CURRENT_SCHEMA_VERSION);
+    });
+
+    it('runs the javascript migrations, not just the .sql ones', async () => {
+        // The `system` user only exists because 0025 (a .dbmig.js file) ran
+        // inside the migration VM.
+        const rows = await client.read(
+            'SELECT `username` FROM `user` WHERE `uuid` = ?',
+            [SYSTEM_USER_UUID],
+        );
+        expect(rows).toEqual([{ username: 'system' }]);
+    });
+
+    it('leaves an already-migrated database untouched on a second boot', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'puter-sqlite-'));
+        const path = join(dir, 'nested', 'puter.sqlite');
+        try {
+            const first = new SqliteDatabaseClient(
+                sqliteConfig({ inMemory: false, path }),
+            );
+            await first.onServerStart();
+            await first.write(
+                'INSERT INTO `kv` (`user_id`, `kkey_hash`, `kkey`, `value`) ' +
+                    'VALUES (?, ?, ?, ?)',
+                [1, 1, 'boot-marker', '"kept"'],
+            );
+            first.onServerShutdown();
+
+            expect(existsSync(path)).toBe(true);
+
+            const second = new SqliteDatabaseClient(
+                sqliteConfig({ inMemory: false, path }),
+            );
+            await second.onServerStart();
+            await expect(
+                second.read('SELECT `value` FROM `kv` WHERE `kkey` = ?', [
+                    'boot-marker',
+                ]),
+            ).resolves.toEqual([{ value: '"kept"' }]);
+            expect(await userVersionOf(second)).toBe(CURRENT_SCHEMA_VERSION);
+            second.onServerShutdown();
+        } finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+
+    it('stops early at a configured target version', async () => {
+        const partial = await bootClient({ targetVersion: 5 });
+        try {
+            expect(await userVersionOf(partial)).toBe(5);
+            // 0005 landed (apps.background); 0011 (notification) did not.
+            await expect(
+                partial.read(
+                    "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'notification'",
+                ),
+            ).resolves.toEqual([]);
+            await expect(
+                partial.read(
+                    "SELECT 1 FROM pragma_table_info('apps') WHERE name = 'background'",
+                ),
+            ).resolves.toHaveLength(1);
+        } finally {
+            partial.onServerShutdown();
+        }
+    });
+});
+
+describe('SqliteDatabaseClient — legacy version inference', () => {
+    let dir: string;
+
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), 'puter-sqlite-legacy-'));
+    });
+
+    afterEach(() => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+
+    it('treats user_version=0 with no bootstrap tables as uninitialized', async () => {
+        const path = join(dir, 'blank.sqlite');
+        new Database(path).close();
+
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const client = new SqliteDatabaseClient(
+            sqliteConfig({ inMemory: false, path }),
+        );
+        try {
+            await client.onServerStart();
+            expect(warn).toHaveBeenCalledWith(
+                expect.stringContaining('bootstrap tables are missing'),
+            );
+            // A full migration run followed, so the schema is current.
+            expect(await userVersionOf(client)).toBe(CURRENT_SCHEMA_VERSION);
+        } finally {
+            client.onServerShutdown();
+            warn.mockRestore();
+        }
+    });
+
+    it('infers the schema version from table and column markers', async () => {
+        const path = join(dir, 'legacy.sqlite');
+        const seed = new Database(path);
+        seed.exec(`
+            CREATE TABLE user (
+                id INTEGER PRIMARY KEY,
+                username TEXT,
+                otp_secret TEXT,
+                otp_enabled INTEGER,
+                otp_recovery_codes TEXT
+            );
+            CREATE TABLE apps (
+                id INTEGER PRIMARY KEY,
+                uid TEXT,
+                background INTEGER,
+                metadata TEXT
+            );
+            CREATE TABLE user_to_user_permissions (id INTEGER PRIMARY KEY);
+            CREATE TABLE audit_user_to_user_permissions (
+                id INTEGER PRIMARY KEY,
+                issuer_user_id INTEGER,
+                holder_user_id INTEGER
+            );
+            CREATE TABLE sessions (
+                id INTEGER PRIMARY KEY,
+                created_at INTEGER,
+                last_activity INTEGER
+            );
+            CREATE TABLE kv (id INTEGER PRIMARY KEY, value JSON);
+            INSERT INTO apps (uid)
+                VALUES ('app-e3ac5486-da8c-42ad-8377-8728086e0980');
+        `);
+        seed.close();
+
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        // targetVersion just past the inferred version keeps the run a
+        // no-op, so the assertion is about inference alone.
+        const client = new SqliteDatabaseClient(
+            sqliteConfig({ inMemory: false, path, targetVersion: 22 }),
+        );
+        try {
+            await client.onServerStart();
+            expect(warn).toHaveBeenCalledWith(
+                '[sqlite] user_version=0; inferred legacy schema version 21',
+            );
+            // Nothing was applied, so user_version stays where it was.
+            expect(await userVersionOf(client)).toBe(0);
+        } finally {
+            client.onServerShutdown();
+            warn.mockRestore();
+        }
+    });
+
+    it('reports version 0 when only the bootstrap tables exist', async () => {
+        const path = join(dir, 'bootstrap-only.sqlite');
+        const seed = new Database(path);
+        seed.exec(`
+            CREATE TABLE user (id INTEGER PRIMARY KEY);
+            CREATE TABLE apps (id INTEGER PRIMARY KEY);
+        `);
+        seed.close();
+
+        const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const client = new SqliteDatabaseClient(
+            sqliteConfig({ inMemory: false, path, targetVersion: 1 }),
+        );
+        try {
+            await client.onServerStart();
+            expect(log).toHaveBeenCalledWith('[sqlite] database version: 0');
+        } finally {
+            client.onServerShutdown();
+            log.mockRestore();
+        }
+    });
+});
+
+describe('SqliteDatabaseClient — query interface', () => {
+    let client: SqliteDatabaseClient;
+
+    beforeEach(async () => {
+        client = await bootClient();
+        await client.write(
+            'CREATE TABLE `widget` (`id` INTEGER PRIMARY KEY, ' +
+                '`name` TEXT, `enabled` INTEGER, `seen_at` TEXT)',
+        );
+    });
+
+    afterEach(() => {
+        client.onServerShutdown();
+    });
+
+    it('reports lastInsertRowid and change counts on write', async () => {
+        const inserted = await client.write(
+            'INSERT INTO `widget` (`name`) VALUES (?)',
+            ['spanner'],
+        );
+        expect(inserted).toEqual({
+            insertId: 1,
+            affectedRows: 1,
+            anyRowsAffected: true,
+        });
+
+        const missed = await client.write(
+            'UPDATE `widget` SET `name` = ? WHERE `id` = ?',
+            ['nope', 999],
+        );
+        expect(missed).toMatchObject({
+            affectedRows: 0,
+            anyRowsAffected: false,
+        });
+    });
+
+    it('binds booleans as sqlite integers', async () => {
+        await client.write(
+            'INSERT INTO `widget` (`name`, `enabled`) VALUES (?, ?)',
+            ['toggled', true],
+        );
+        await client.write(
+            'INSERT INTO `widget` (`name`, `enabled`) VALUES (?, ?)',
+            ['untoggled', false],
+        );
+
+        await expect(
+            client.read('SELECT `name`, `enabled` FROM `widget` ORDER BY `id`'),
+        ).resolves.toEqual([
+            { name: 'toggled', enabled: 1 },
+            { name: 'untoggled', enabled: 0 },
+        ]);
+    });
+
+    it('rewrites now() into the sqlite equivalent', async () => {
+        await client.write(
+            'INSERT INTO `widget` (`name`, `seen_at`) VALUES (?, NOW())',
+            ['stamped'],
+        );
+        const [row] = await client.read(
+            'SELECT `seen_at` FROM `widget` WHERE `name` = ?',
+            ['stamped'],
+        );
+        expect(row.seen_at).toMatch(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/);
+    });
+
+    it('generates an INSERT from a data object', async () => {
+        await client.insert('widget', { name: 'generated', enabled: true });
+        await expect(
+            client.read('SELECT `name`, `enabled` FROM `widget`'),
+        ).resolves.toEqual([{ name: 'generated', enabled: 1 }]);
+    });
+
+    it('primary-reads through the same single-node connection', async () => {
+        await client.write('INSERT INTO `widget` (`name`) VALUES (?)', ['p']);
+        await expect(
+            client.pread('SELECT `name` FROM `widget`'),
+        ).resolves.toEqual([{ name: 'p' }]);
+    });
+
+    it('applies a batch write atomically', async () => {
+        await client.batchWrite([
+            {
+                statement:
+                    'INSERT INTO `widget` (`name`, `enabled`) VALUES (?, ?)',
+                values: ['one', true],
+            },
+            {
+                statement: 'INSERT INTO `widget` (`name`) VALUES (?)',
+                values: ['two'],
+            },
+        ]);
+
+        await expect(
+            client.read('SELECT `name` FROM `widget` ORDER BY `id`'),
+        ).resolves.toEqual([{ name: 'one' }, { name: 'two' }]);
+    });
+
+    it('rolls the whole batch back when one statement fails', async () => {
+        await expect(
+            client.batchWrite([
+                {
+                    statement: 'INSERT INTO `widget` (`name`) VALUES (?)',
+                    values: ['kept-if-broken'],
+                },
+                {
+                    statement: 'INSERT INTO `nonexistent` (`name`) VALUES (?)',
+                    values: ['boom'],
+                },
+            ]),
+        ).rejects.toThrow(/no such table/i);
+
+        await expect(
+            client.read('SELECT `name` FROM `widget`'),
+        ).resolves.toEqual([]);
+    });
+
+    it('surfaces sqlite errors for malformed SQL', async () => {
+        await expect(client.read('SELEC oops')).rejects.toThrow(
+            /syntax error/i,
+        );
+    });
+
+    it('closes the database on shutdown', async () => {
+        const closable = await bootClient();
+        closable.onServerShutdown();
+        await expect(closable.read('SELECT 1')).rejects.toThrow(
+            'The database connection is not open',
+        );
+    });
+});
+
+// Single-node engines have no replica to race, so `tryHardRead` must not
+// issue the query twice — the base-class default fires `pread()` and
+// `read()` in parallel, which on sqlite is the same connection.
+describe('SqliteDatabaseClient — tryHardRead', () => {
+    let client: SqliteDatabaseClient;
+
+    beforeEach(async () => {
+        client = await bootClient();
+        await client.write(
+            'CREATE TABLE `widget` (`id` INTEGER PRIMARY KEY, `name` TEXT)',
+        );
+    });
+
+    afterEach(() => {
+        client.onServerShutdown();
+    });
+
+    it('executes the statement exactly once', async () => {
+        await client.write('INSERT INTO `widget` (`name`) VALUES (?)', ['one']);
+        const readSpy = vi.spyOn(client, 'read');
+        const preadSpy = vi.spyOn(client, 'pread');
+
+        await expect(
+            client.tryHardRead('SELECT `name` FROM `widget`'),
+        ).resolves.toEqual([{ name: 'one' }]);
+
+        expect(readSpy).toHaveBeenCalledTimes(1);
+        expect(preadSpy).not.toHaveBeenCalled();
+    });
+
+    it('executes the statement exactly once when it matches no rows', async () => {
+        const readSpy = vi.spyOn(client, 'read');
+        const preadSpy = vi.spyOn(client, 'pread');
+
+        await expect(
+            client.tryHardRead('SELECT `name` FROM `widget`'),
+        ).resolves.toEqual([]);
+
+        expect(readSpy).toHaveBeenCalledTimes(1);
+        expect(preadSpy).not.toHaveBeenCalled();
+    });
+
+    it('throws from requireRead when nothing matches', async () => {
+        await expect(
+            client.requireRead(
+                'SELECT `name` FROM `widget` WHERE `id` = ?',
+                [42],
+            ),
+        ).rejects.toThrow('required read returned no rows');
+    });
+
+    it('returns the rows from requireRead when something matches', async () => {
+        await client.write('INSERT INTO `widget` (`name`) VALUES (?)', ['ok']);
+        await expect(
+            client.requireRead('SELECT `name` FROM `widget`'),
+        ).resolves.toEqual([{ name: 'ok' }]);
+    });
+});

src/backend/clients/database/SqliteDatabaseClient.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -27,9 +27,9 @@ import { AbstractDatabaseClient, type WriteResult } from './DatabaseClient';
 const MIGRATIONS_DIR = resolve(__dirname, './migrations/sqlite');
 
 /**
- * Ordered list of [threshold_version, files[]] pairs.
- * A database whose `user_version` is <= threshold_version will have
- * the corresponding files applied.
+ * Ordered list of [threshold_version, files[]] pairs. A database whose
+ * `user_version` is <= threshold_version will have the corresponding files
+ * applied.
  */
 const AVAILABLE_MIGRATIONS: [number, string[]][] = [
     [-1, ['0001_create-tables.sql', '0002_add-default-apps.sql']],
@@ -94,6 +94,7 @@ const AVAILABLE_MIGRATIONS: [number, string[]][] = [
     [57, ['0062_blocked-app-origins.sql']],
     [58, ['0063_add_suspended_reason.sql']],
     [59, ['0064_abuse-moderation-events.sql']],
+    [60, ['0065_app-feedback.sql']],
 ];
 
 export class SqliteDatabaseClient extends AbstractDatabaseClient {
@@ -158,6 +159,16 @@ export class SqliteDatabaseClient extends AbstractDatabaseClient {
         return this.read(query, params);
     }
 
+    override async tryHardRead(
+        query: string,
+        params: unknown[] = [],
+    ): Promise<Record<string, unknown>[]> {
+        // No replica to race, so the base class's parallel
+        // primary-plus-replica read would run the same statement twice on
+        // the one connection.
+        return this.read(query, params);
+    }
+
     @Span('db.write', (query: string) => ({ 'db.statement': query }))
     override async write(
         query: string,

src/backend/clients/database/index.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -33,9 +33,9 @@ import { PostgresDatabaseClient } from './PostgresDatabaseClient';
 import { SqliteDatabaseClient } from './SqliteDatabaseClient';
 
 /**
- * Factory class registered in `puterClients`. PuterServer calls
- * `new DatabaseClientFactory(config)` — the constructor returns the
- * concrete subclass selected by `config.database.engine`.
+ * Factory class registered in `puterClients`. PuterServer calls `new
+ * DatabaseClientFactory(config)` — the constructor returns the concrete
+ * subclass selected by `config.database.engine`.
  */
 export const DatabaseClientFactory = class DatabaseClientFactory {
     constructor(config: IConfig) {

src/backend/clients/database/migrationFilenames.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.

src/backend/clients/database/migrations/mysql/mysql_mig_20.sql

@@ -0,0 +1,48 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- User-to-developer feedback for apps that opt in. Mirrors SQLite migration
+-- 0065. Opt-in is the new `apps.feedback_enabled` column (developer-writable
+-- through the regular `puter.apps.update` path). Each row of `app_feedback`
+-- is one message a signed-in user submitted through the GUI feedback dialog;
+-- a copy is emailed to the app owner unless the per-app daily email cap
+-- suppressed it (`email_sent` records which). `app_uid` is denormalized
+-- alongside `app_id` so rows stay attributable after an app is deleted.
+-- `created_at` is unix seconds.
+--
+-- Idempotent: the column add uses _puter_add_col (defined in mig_1, which
+-- always runs first) and the table uses `CREATE TABLE IF NOT EXISTS`, so the
+-- directory can replay safely.
+
+CALL _puter_add_col('apps', 'feedback_enabled', '`feedback_enabled` tinyint(1) DEFAULT ''0''');
+
+CREATE TABLE IF NOT EXISTS `app_feedback` (
+    `id` INT NOT NULL AUTO_INCREMENT,
+    `uid` CHAR(36) NOT NULL,
+    `app_id` INT NOT NULL,
+    `app_uid` CHAR(40) NOT NULL,
+    `user_id` INT NOT NULL,
+    `message` TEXT NOT NULL,
+    `source_env` VARCHAR(16) DEFAULT NULL,
+    `source_origin` VARCHAR(2048) DEFAULT NULL,
+    `email_sent` TINYINT(1) NOT NULL DEFAULT 0,
+    `created_at` BIGINT NOT NULL,
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uq_app_feedback_uid` (`uid`),
+    KEY `idx_app_feedback_app_created` (`app_id`, `created_at`),
+    KEY `idx_app_feedback_user_created` (`user_id`, `created_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

src/backend/clients/database/migrations/postgres/postgres_mig_9.sql

@@ -0,0 +1,47 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- User-to-developer feedback for apps that opt in. Mirrors SQLite migration
+-- 0065 / MySQL mysql_mig_20. Opt-in is the new `apps.feedback_enabled` column
+-- (developer-writable through the regular `puter.apps.update` path). Each row
+-- of `app_feedback` is one message a signed-in user submitted through the GUI
+-- feedback dialog; a copy is emailed to the app owner unless the per-app
+-- daily email cap suppressed it (`email_sent` records which). `app_uid` is
+-- denormalized alongside `app_id` so rows stay attributable after an app is
+-- deleted. `created_at` is unix seconds.
+--
+-- Idempotent via IF NOT EXISTS.
+
+ALTER TABLE apps ADD COLUMN IF NOT EXISTS feedback_enabled boolean NOT NULL DEFAULT FALSE;
+
+CREATE TABLE IF NOT EXISTS app_feedback (
+    id BIGSERIAL PRIMARY KEY,
+    uid CHAR(36) NOT NULL UNIQUE,
+    app_id BIGINT NOT NULL,
+    app_uid VARCHAR(40) NOT NULL,
+    user_id BIGINT NOT NULL,
+    message TEXT NOT NULL,
+    source_env VARCHAR(16) DEFAULT NULL,
+    source_origin VARCHAR(2048) DEFAULT NULL,
+    email_sent BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at BIGINT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_app_feedback_app_created
+    ON app_feedback (app_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_app_feedback_user_created
+    ON app_feedback (user_id, created_at);

src/backend/clients/database/migrations/sqlite/0065_app-feedback.sql

@@ -0,0 +1,51 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- User-to-developer feedback for apps that opt in. Opt-in is the new
+-- `apps.feedback_enabled` column (developer-writable through the regular
+-- `puter.apps.update` path; a dedicated column rather than a `metadata` key
+-- because Dev Center saves replace the whole metadata blob and would erase
+-- it). Each row of `app_feedback` is one message a signed-in user submitted
+-- through the GUI feedback dialog; a copy is emailed to the app owner unless
+-- the per-app daily email cap suppressed it (`email_sent` records which).
+-- `app_uid` is denormalized alongside `app_id` so rows stay attributable
+-- after an app is deleted (abuse forensics). `source_env` is 'app' (desktop
+-- dialog) or 'web' (puter.com popup opened from an external site);
+-- `source_origin` is the popup opener's browser-attested origin, null for
+-- desktop submissions. `created_at` is unix seconds. The (user_id,
+-- created_at) and (app_id, created_at) indexes serve the sliding-window
+-- rate-limit counts in AppFeedbackStore.
+
+ALTER TABLE apps ADD COLUMN "feedback_enabled" tinyint(1) DEFAULT '0';
+
+CREATE TABLE IF NOT EXISTS `app_feedback` (
+    "id" INTEGER PRIMARY KEY AUTOINCREMENT,
+    "uid" TEXT NOT NULL UNIQUE,
+    "app_id" INTEGER NOT NULL,
+    "app_uid" TEXT NOT NULL,
+    "user_id" INTEGER NOT NULL,
+    "message" TEXT NOT NULL,
+    "source_env" TEXT DEFAULT NULL,     -- 'app' | 'web'
+    "source_origin" TEXT DEFAULT NULL,  -- attested opener origin (web popups)
+    "email_sent" INTEGER NOT NULL DEFAULT 0,
+    "created_at" INTEGER NOT NULL       -- unix seconds
+);
+
+CREATE INDEX IF NOT EXISTS idx_app_feedback_app_created
+    ON `app_feedback` (`app_id`, `created_at`);
+CREATE INDEX IF NOT EXISTS idx_app_feedback_user_created
+    ON `app_feedback` (`user_id`, `created_at`);

src/backend/clients/database/preparePostgresSql.test.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.

src/backend/clients/database/preparePostgresSql.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.

src/backend/clients/database/retriableErrors.ts

@@ -0,0 +1,106 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/** Error code set by the pool-acquisition timeout in SQLBatcher. */
+export const POOL_ACQUIRE_TIMEOUT = 'POOL_ACQUIRE_TIMEOUT';
+
+const RETRIABLE_ERROR_CODES = new Set([
+    'PROTOCOL_CONNECTION_LOST',
+    'PROTOCOL_SEQUENCE_TIMEOUT',
+    'PROTOCOL_ENQUEUE_AFTER_FATAL_ERROR',
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'EPIPE',
+    'ECONNREFUSED',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'EAI_AGAIN',
+    POOL_ACQUIRE_TIMEOUT,
+]);
+
+const RETRIABLE_ERROR_MESSAGES = [
+    'Connection lost',
+    'read ECONNRESET',
+    'ETIMEDOUT',
+];
+
+/**
+ * Failures where the statement provably never reached the server, so a retry
+ * can never double-apply it — safe even for writes. Anything that can occur
+ * after the statement was sent (resets, protocol drops) is deliberately
+ * excluded: the server may have committed before the connection died.
+ */
+const NEVER_SENT_ERROR_CODES = new Set([
+    'ECONNREFUSED',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'EAI_AGAIN',
+    POOL_ACQUIRE_TIMEOUT,
+]);
+
+/**
+ * Failures the server itself rolled back before returning. The statement did
+ * reach the database, so this is not `NEVER_SENT`, but InnoDB guarantees it
+ * left no effect — which makes a retry just as safe for writes.
+ *
+ * Only true for a _single_ statement: under autocommit each statement is its
+ * own transaction, so "the transaction was rolled back" means "this statement
+ * was rolled back". Retrying a multi-statement string on one of these would
+ * re-run the statements that already committed ahead of the failure.
+ */
+const ROLLED_BACK_ERROR_CODES = new Set([
+    // Deadlock — InnoDB picked this transaction as the victim and undid it.
+    // MySQL's own message for it is "try restarting transaction".
+    'ER_LOCK_DEADLOCK',
+    // Lock wait timeout. Rolls back the statement rather than the transaction
+    // unless innodb_rollback_on_timeout is set — the same thing when the
+    // transaction is one statement.
+    'ER_LOCK_WAIT_TIMEOUT',
+]);
+
+const errorCode = (error: unknown): string | undefined =>
+    (error as { code?: string } | null)?.code;
+
+/**
+ * Transient connection-level failures worth retrying — but only for statements
+ * that are safe to run twice (reads). Row-level errors (duplicate key,
+ * constraint violations) are deterministic and never match.
+ */
+export const isRetriableError = (error: unknown): boolean => {
+    const code = errorCode(error);
+    if (code && RETRIABLE_ERROR_CODES.has(code)) return true;
+
+    const msg = String((error as Error)?.message ?? '');
+    return RETRIABLE_ERROR_MESSAGES.some((m) => msg.includes(m));
+};
+
+export const isNeverSentError = (error: unknown): boolean => {
+    const code = errorCode(error);
+    return Boolean(code && NEVER_SENT_ERROR_CODES.has(code));
+};
+
+/**
+ * Lock-contention failures the server rolled back on its own. Safe to retry a
+ * single statement on, writes included — see `ROLLED_BACK_ERROR_CODES` for the
+ * one-statement precondition.
+ */
+export const isRolledBackError = (error: unknown): boolean => {
+    const code = errorCode(error);
+    return Boolean(code && ROLLED_BACK_ERROR_CODES.has(code));
+};

src/backend/clients/database/splitMysqlStatements.test.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.

src/backend/clients/database/splitMysqlStatements.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -20,12 +20,11 @@
 /**
  * DELIMITER-aware splitter for MySQL dump / migration files.
  *
- * Splits `sql` into individual statements using the active statement
- * delimiter (default `;`). Recognises `DELIMITER X` lines, single-quoted
- * strings, double-quoted strings, backtick-quoted identifiers, line
- * comments (`-- `, `#`) and block comments (`/* ... *\/`). DELIMITER
- * directives are stripped from the output (they're a client-side concept,
- * not server SQL).
+ * Splits `sql` into individual statements using the active statement delimiter
+ * (default `;`). Recognises `DELIMITER X` lines, single-quoted strings,
+ * double-quoted strings, backtick-quoted identifiers, line comments (`-- `,
+ * `#`) and block comments (`/* ... *\/`). DELIMITER directives are stripped
+ * from the output (they're a client-side concept, not server SQL).
  *
  * Returns trimmed, non-empty statements without the trailing delimiter.
  */

src/backend/clients/database/splitPostgresStatements.test.ts

@@ -0,0 +1,116 @@
+/**
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { splitPostgresStatements } from './splitPostgresStatements';
+
+describe('splitPostgresStatements', () => {
+    it('splits on semicolons and trims each statement', () => {
+        expect(
+            splitPostgresStatements('SELECT 1;\n  SELECT 2 ;\nSELECT 3'),
+        ).toEqual(['SELECT 1', 'SELECT 2', 'SELECT 3']);
+    });
+
+    it('drops empty statements from stray semicolons', () => {
+        expect(splitPostgresStatements(';;SELECT 1;;')).toEqual(['SELECT 1']);
+    });
+
+    it('returns nothing for whitespace-only input', () => {
+        expect(splitPostgresStatements('   \n\t ')).toEqual([]);
+    });
+
+    it('keeps semicolons inside single-quoted literals', () => {
+        expect(
+            splitPostgresStatements("INSERT INTO t VALUES ('a;b'); SELECT 1"),
+        ).toEqual(["INSERT INTO t VALUES ('a;b')", 'SELECT 1']);
+    });
+
+    it('handles doubled and backslash-escaped quotes in literals', () => {
+        expect(
+            splitPostgresStatements("SELECT 'it''s; fine'; SELECT 2"),
+        ).toEqual(["SELECT 'it''s; fine'", 'SELECT 2']);
+        expect(splitPostgresStatements("SELECT E'a\\'; b'; SELECT 2")).toEqual([
+            "SELECT E'a\\'; b'",
+            'SELECT 2',
+        ]);
+    });
+
+    it('keeps semicolons inside quoted identifiers', () => {
+        expect(
+            splitPostgresStatements('SELECT "we;ird" FROM t; SELECT 2'),
+        ).toEqual(['SELECT "we;ird" FROM t', 'SELECT 2']);
+    });
+
+    it('handles a doubled quote inside a quoted identifier', () => {
+        expect(
+            splitPostgresStatements('SELECT "we""ird;x" FROM t; SELECT 2'),
+        ).toEqual(['SELECT "we""ird;x" FROM t', 'SELECT 2']);
+    });
+
+    it('ignores semicolons inside line comments', () => {
+        expect(
+            splitPostgresStatements('SELECT 1 -- trailing; note\n; SELECT 2'),
+        ).toEqual(['SELECT 1 -- trailing; note', 'SELECT 2']);
+    });
+
+    it('ignores semicolons inside block comments', () => {
+        expect(
+            splitPostgresStatements('SELECT /* a; b */ 1; SELECT 2'),
+        ).toEqual(['SELECT /* a; b */ 1', 'SELECT 2']);
+    });
+
+    it('keeps a whole dollar-quoted function body together', () => {
+        const sql = [
+            'CREATE FUNCTION bump() RETURNS trigger AS $$',
+            'BEGIN',
+            '  NEW.updated_at := now();',
+            '  RETURN NEW;',
+            'END;',
+            '$$ LANGUAGE plpgsql;',
+            'SELECT 1',
+        ].join('\n');
+
+        const statements = splitPostgresStatements(sql);
+        expect(statements).toHaveLength(2);
+        expect(statements[0]).toContain('RETURN NEW;');
+        expect(statements[0].endsWith('$$ LANGUAGE plpgsql')).toBe(true);
+        expect(statements[1]).toBe('SELECT 1');
+    });
+
+    it('respects a tagged dollar quote and its nested untagged pair', () => {
+        const sql = 'SELECT $body$ inner $$ still; inside $body$; SELECT 2';
+        expect(splitPostgresStatements(sql)).toEqual([
+            'SELECT $body$ inner $$ still; inside $body$',
+            'SELECT 2',
+        ]);
+    });
+
+    it('treats a bare dollar sign as ordinary text', () => {
+        expect(splitPostgresStatements('SELECT 1 $ 2; SELECT 3')).toEqual([
+            'SELECT 1 $ 2',
+            'SELECT 3',
+        ]);
+    });
+
+    it('emits an unterminated final statement', () => {
+        expect(
+            splitPostgresStatements('SELECT 1; SELECT 2 -- no newline'),
+        ).toEqual(['SELECT 1', 'SELECT 2 -- no newline']);
+    });
+});

src/backend/clients/database/splitPostgresStatements.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.

src/backend/clients/dynamodb/DDBClient.test.ts

@@ -0,0 +1,531 @@
+/**
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { createServer, type Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import type { IConfig } from '../../types';
+import { DDBClient } from './DDBClient';
+
+const TABLE = 'kv-items';
+const GSI = 'by-kind';
+
+const localConfig = (): IConfig =>
+    ({
+        port: 0,
+        extensions: [],
+        dynamo: { inMemory: true, bootstrapTables: true },
+    }) as unknown as IConfig;
+
+/**
+ * The emulator reports a table as CREATING for a tick after `CreateTable`
+ * returns, so wait until it actually answers a read before using it.
+ */
+const awaitTable = async (
+    client: DDBClient,
+    table: string,
+    key: Record<string, unknown>,
+): Promise<void> => {
+    for (let attempt = 0; attempt < 100; attempt++) {
+        try {
+            await client.get(table, key);
+            return;
+        } catch (error) {
+            if ((error as Error).name !== 'ResourceNotFoundException')
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, 20));
+        }
+    }
+    throw new Error(`table ${table} never became queryable`);
+};
+
+const tableSchema = {
+    TableName: TABLE,
+    KeySchema: [
+        { AttributeName: 'pk', KeyType: 'HASH' as const },
+        { AttributeName: 'sk', KeyType: 'RANGE' as const },
+    ],
+    AttributeDefinitions: [
+        { AttributeName: 'pk', AttributeType: 'S' as const },
+        { AttributeName: 'sk', AttributeType: 'S' as const },
+        { AttributeName: 'kind', AttributeType: 'S' as const },
+    ],
+    GlobalSecondaryIndexes: [
+        {
+            IndexName: GSI,
+            KeySchema: [{ AttributeName: 'kind', KeyType: 'HASH' as const }],
+            Projection: { ProjectionType: 'ALL' as const },
+            ProvisionedThroughput: {
+                ReadCapacityUnits: 5,
+                WriteCapacityUnits: 5,
+            },
+        },
+    ],
+    ProvisionedThroughput: { ReadCapacityUnits: 5, WriteCapacityUnits: 5 },
+};
+
+describe('DDBClient — item operations', () => {
+    let client: DDBClient;
+
+    beforeAll(async () => {
+        client = new DDBClient(localConfig());
+        await client.createTableIfNotExists(tableSchema);
+        await awaitTable(client, TABLE, { pk: 'ready', sk: 'ready' });
+    });
+
+    it('round-trips an item and reports consumed capacity', async () => {
+        await client.put(TABLE, { pk: 'u1', sk: 'profile', name: 'ada' });
+
+        const result = await client.get(TABLE, { pk: 'u1', sk: 'profile' });
+        expect(result.Item).toEqual({ pk: 'u1', sk: 'profile', name: 'ada' });
+        expect(result.ConsumedCapacity?.TableName).toBe(TABLE);
+    });
+
+    it('returns no Item for a key that does not exist', async () => {
+        const result = await client.get(TABLE, { pk: 'nobody', sk: 'here' });
+        expect(result.Item).toBeUndefined();
+    });
+
+    it('honours a strongly consistent read', async () => {
+        await client.put(TABLE, { pk: 'u2', sk: 'profile', name: 'grace' });
+        const result = await client.get(
+            TABLE,
+            { pk: 'u2', sk: 'profile' },
+            true,
+        );
+        expect(result.Item?.name).toBe('grace');
+    });
+
+    it('applies an update expression and returns the new item', async () => {
+        await client.put(TABLE, { pk: 'u3', sk: 'counter', hits: 1 });
+        const updated = await client.update(
+            TABLE,
+            { pk: 'u3', sk: 'counter' },
+            'SET #h = :next',
+            { ':next': 5 },
+            { '#h': 'hits' },
+        );
+        expect(updated.Attributes).toMatchObject({ hits: 5 });
+    });
+
+    it('supports an update expression with no values or names', async () => {
+        await client.put(TABLE, { pk: 'u4', sk: 'doc', stale: true });
+        const updated = await client.update(
+            TABLE,
+            { pk: 'u4', sk: 'doc' },
+            'REMOVE stale',
+        );
+        expect(updated.Attributes).toEqual({ pk: 'u4', sk: 'doc' });
+    });
+
+    it('deletes an item', async () => {
+        await client.put(TABLE, { pk: 'u5', sk: 'temp' });
+        await client.del(TABLE, { pk: 'u5', sk: 'temp' });
+        const result = await client.get(TABLE, { pk: 'u5', sk: 'temp' });
+        expect(result.Item).toBeUndefined();
+    });
+
+    it('fetches keys from several tables in one batch', async () => {
+        await client.put(TABLE, { pk: 'b1', sk: 'a', v: 1 });
+        await client.put(TABLE, { pk: 'b1', sk: 'b', v: 2 });
+
+        const result = await client.batchGet([
+            { table: TABLE, items: { pk: 'b1', sk: 'a' } },
+            { table: TABLE, items: { pk: 'b1', sk: 'b' } },
+        ]);
+
+        const values = (result.Responses?.[TABLE] ?? [])
+            .map((item) => item.v as number)
+            .sort();
+        expect(values).toEqual([1, 2]);
+    });
+});
+
+describe('DDBClient — queries', () => {
+    let client: DDBClient;
+
+    beforeAll(async () => {
+        client = new DDBClient(localConfig());
+        await client.createTableIfNotExists(tableSchema);
+        await awaitTable(client, TABLE, { pk: 'ready', sk: 'ready' });
+        for (const sk of ['post#1', 'post#2', 'post#3', 'note#1']) {
+            await client.put(TABLE, {
+                pk: 'q1',
+                sk,
+                kind: sk.split('#')[0],
+                size: sk === 'post#2' ? 10 : 1,
+            });
+        }
+    });
+
+    it('queries by partition key', async () => {
+        const result = await client.query(TABLE, { pk: 'q1' });
+        expect(result.Items).toHaveLength(4);
+        expect(result.ConsumedCapacity?.TableName).toBe(TABLE);
+    });
+
+    it('narrows the sort key with begins_with', async () => {
+        const result = await client.query(
+            TABLE,
+            { pk: 'q1' },
+            0,
+            undefined,
+            '',
+            false,
+            { beginsWith: { key: 'sk', value: 'post#' } },
+        );
+        expect(result.Items?.map((item) => item.sk)).toEqual([
+            'post#1',
+            'post#2',
+            'post#3',
+        ]);
+    });
+
+    it('ignores an empty begins_with value', async () => {
+        const result = await client.query(
+            TABLE,
+            { pk: 'q1' },
+            0,
+            undefined,
+            '',
+            false,
+            { beginsWith: { key: 'sk', value: '' } },
+        );
+        expect(result.Items).toHaveLength(4);
+    });
+
+    it('applies a filter expression with its own names and values', async () => {
+        const result = await client.query(
+            TABLE,
+            { pk: 'q1' },
+            0,
+            undefined,
+            '',
+            false,
+            {
+                filter: {
+                    expression: '#s > :min',
+                    names: { '#s': 'size' },
+                    values: { ':min': 5 },
+                },
+            },
+        );
+        expect(result.Items?.map((item) => item.sk)).toEqual(['post#2']);
+    });
+
+    it('counts without returning items', async () => {
+        const result = await client.query(
+            TABLE,
+            { pk: 'q1' },
+            0,
+            undefined,
+            '',
+            false,
+            { select: 'COUNT' },
+        );
+        expect(result.Count).toBe(4);
+        expect(result.Items).toBeUndefined();
+    });
+
+    it('pages through results with the last evaluated key', async () => {
+        const seen: string[] = [];
+        let pageKey: Record<string, unknown> | undefined;
+        let pages = 0;
+
+        do {
+            const page = await client.query(TABLE, { pk: 'q1' }, 2, pageKey);
+            pages += 1;
+            expect(page.Items?.length).toBeLessThanOrEqual(2);
+            for (const item of page.Items ?? []) seen.push(item.sk as string);
+            pageKey = page.LastEvaluatedKey;
+        } while (pageKey && pages < 10);
+
+        expect(pages).toBeGreaterThan(1);
+        expect(new Set(seen).size).toBe(4);
+    });
+
+    it('queries a secondary index', async () => {
+        const result = await client.query(
+            TABLE,
+            { kind: 'note' },
+            0,
+            undefined,
+            GSI,
+        );
+        expect(result.Items?.map((item) => item.sk)).toEqual(['note#1']);
+    });
+});
+
+describe('DDBClient — batch writes', () => {
+    let client: DDBClient;
+
+    beforeAll(async () => {
+        client = new DDBClient(localConfig());
+        await client.createTableIfNotExists(tableSchema);
+        await awaitTable(client, TABLE, { pk: 'ready', sk: 'ready' });
+    });
+
+    it('reports no consumed capacity for an empty batch', async () => {
+        await expect(client.batchPut([])).resolves.toEqual({
+            ConsumedCapacity: [],
+        });
+    });
+
+    it('splits a batch larger than the service limit into chunks', async () => {
+        const params = Array.from({ length: 60 }, (_, index) => ({
+            table: TABLE,
+            item: { pk: 'bulk', sk: `item-${index}`, index },
+        }));
+
+        const result = await client.batchPut(params);
+
+        expect(result.ConsumedCapacity).toHaveLength(1);
+        expect(result.ConsumedCapacity[0].TableName).toBe(TABLE);
+        expect(result.ConsumedCapacity[0].CapacityUnits).toBeGreaterThan(0);
+
+        const stored = await client.query(TABLE, { pk: 'bulk' });
+        expect(stored.Items).toHaveLength(60);
+    });
+});
+
+describe('DDBClient — expired item sweep', () => {
+    it('deletes only the items past their ttl when the table already existed', async () => {
+        const client = new DDBClient(localConfig());
+        const table = 'ttl-items';
+        const schema = {
+            TableName: table,
+            KeySchema: [{ AttributeName: 'pk', KeyType: 'HASH' as const }],
+            AttributeDefinitions: [
+                { AttributeName: 'pk', AttributeType: 'S' as const },
+            ],
+            ProvisionedThroughput: {
+                ReadCapacityUnits: 5,
+                WriteCapacityUnits: 5,
+            },
+        };
+
+        await client.createTableIfNotExists(schema, 'expireAt');
+        await awaitTable(client, table, { pk: 'ready' });
+        const now = Math.floor(Date.now() / 1000);
+        await client.put(table, { pk: 'stale', expireAt: now - 60 });
+        await client.put(table, { pk: 'fresh', expireAt: now + 3600 });
+        await client.put(table, { pk: 'eternal' });
+
+        // Second call finds the table in use, so the sweep runs.
+        await client.createTableIfNotExists(schema, 'expireAt');
+
+        expect((await client.get(table, { pk: 'stale' })).Item).toBeUndefined();
+        expect((await client.get(table, { pk: 'fresh' })).Item).toBeDefined();
+        expect((await client.get(table, { pk: 'eternal' })).Item).toBeDefined();
+    });
+});
+
+describe('DDBClient — expired item sweep on an empty table', () => {
+    it('completes without deleting anything', async () => {
+        const client = new DDBClient(localConfig());
+        const table = 'ttl-empty';
+        const schema = {
+            TableName: table,
+            KeySchema: [{ AttributeName: 'pk', KeyType: 'HASH' as const }],
+            AttributeDefinitions: [
+                { AttributeName: 'pk', AttributeType: 'S' as const },
+            ],
+            ProvisionedThroughput: {
+                ReadCapacityUnits: 5,
+                WriteCapacityUnits: 5,
+            },
+        };
+
+        await client.createTableIfNotExists(schema, 'expireAt');
+        await awaitTable(client, table, { pk: 'ready' });
+        await expect(
+            client.createTableIfNotExists(schema, 'expireAt'),
+        ).resolves.toBeUndefined();
+    });
+});
+
+describe('DDBClient — credentialled configuration', () => {
+    it('refuses an aws config that is missing a key', () => {
+        expect(
+            () =>
+                new DDBClient({
+                    port: 0,
+                    extensions: [],
+                    dynamo: { aws: { access_key: 'only-one' } },
+                } as unknown as IConfig),
+        ).toThrow('requires both `access_key` and `secret_key`');
+    });
+
+    it('skips table creation on a managed deployment', async () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const client = new DDBClient({
+            port: 0,
+            extensions: [],
+            dynamo: {
+                aws: { access_key: 'a', secret_key: 'b', region: 'us-west-2' },
+                endpoint: 'http://127.0.0.1:1',
+            },
+        } as unknown as IConfig);
+
+        // Would fail against the unreachable endpoint if it actually tried.
+        await client.createTableIfNotExists(tableSchema);
+        expect(warn).toHaveBeenCalledWith(
+            expect.stringContaining(
+                'Creating DynamoDB tables is disabled by default',
+            ),
+        );
+        warn.mockRestore();
+    });
+
+    it('rebinds an aws-credentialled client on recreate', async () => {
+        const client = new DDBClient({
+            port: 0,
+            extensions: [],
+            dynamo: {
+                aws: { access_key: 'a', secret_key: 'b' },
+                endpoint: 'http://127.0.0.1:1',
+            },
+        } as unknown as IConfig);
+
+        await expect(client.recreateClient()).resolves.toBeUndefined();
+    });
+
+    it('rebinds the underlying client on recreate', async () => {
+        const client = new DDBClient(localConfig());
+        await client.createTableIfNotExists(tableSchema);
+        await awaitTable(client, TABLE, { pk: 'ready', sk: 'ready' });
+        await client.put(TABLE, { pk: 'recreate', sk: 'a', v: 1 });
+
+        await client.recreateClient();
+
+        // Same in-memory store: the recreated client sees earlier writes.
+        const result = await client.get(TABLE, { pk: 'recreate', sk: 'a' });
+        expect(result.Item?.v).toBe(1);
+    });
+});
+
+// Unprocessed items are a throttling signal the emulator never produces, so
+// the retry loop is driven against a stub speaking the DynamoDB wire format.
+describe('DDBClient — unprocessed batch items', () => {
+    let server: Server;
+    let endpoint: string;
+    let responses: unknown[];
+    let requestCount = 0;
+
+    beforeAll(async () => {
+        server = createServer((req, res) => {
+            let body = '';
+            req.on('data', (chunk) => {
+                body += chunk;
+            });
+            req.on('end', () => {
+                const next = responses.shift() ?? {};
+                requestCount += 1;
+                res.writeHead(200, {
+                    'content-type': 'application/x-amz-json-1.0',
+                });
+                res.end(JSON.stringify(next));
+            });
+        });
+        await new Promise<void>((resolve) =>
+            server.listen(0, '127.0.0.1', resolve),
+        );
+        endpoint = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+    });
+
+    afterAll(async () => {
+        await new Promise<void>((resolve) => server.close(() => resolve()));
+    });
+
+    const stubClient = () =>
+        new DDBClient({
+            port: 0,
+            extensions: [],
+            dynamo: {
+                aws: { access_key: 'a', secret_key: 'b', region: 'us-west-2' },
+                endpoint,
+            },
+        } as unknown as IConfig);
+
+    const unprocessed = (pk: string) => ({
+        UnprocessedItems: {
+            [TABLE]: [{ PutRequest: { Item: { pk: { S: pk } } } }],
+        },
+        ConsumedCapacity: [{ TableName: TABLE, CapacityUnits: 1 }],
+    });
+
+    it('retries the leftover items and sums capacity across attempts', async () => {
+        requestCount = 0;
+        responses = [
+            unprocessed('retry-me'),
+            {
+                UnprocessedItems: {},
+                ConsumedCapacity: [{ TableName: TABLE, CapacityUnits: 2 }],
+            },
+        ];
+
+        const result = await stubClient().batchPut([
+            { table: TABLE, item: { pk: 'retry-me' } },
+        ]);
+
+        expect(requestCount).toBe(2);
+        expect(result.ConsumedCapacity).toEqual([
+            { TableName: TABLE, CapacityUnits: 3 },
+        ]);
+    });
+
+    it('gives up with a bad-request error when items never drain', async () => {
+        requestCount = 0;
+        responses = Array.from({ length: 12 }, () => unprocessed('stuck'));
+
+        await expect(
+            stubClient().batchPut([{ table: TABLE, item: { pk: 'stuck' } }]),
+        ).rejects.toMatchObject({
+            statusCode: 400,
+            legacyCode: 'bad_request',
+            message: 'Failed to batch write all items to DynamoDB',
+        });
+        // One initial attempt plus the full retry budget.
+        expect(requestCount).toBe(9);
+    }, 30_000);
+
+    it('tolerates a response that reports no capacity at all', async () => {
+        requestCount = 0;
+        responses = [{ UnprocessedItems: {} }];
+
+        await expect(
+            stubClient().batchPut([{ table: TABLE, item: { pk: 'quiet' } }]),
+        ).resolves.toEqual({ ConsumedCapacity: [] });
+        expect(requestCount).toBe(1);
+    });
+
+    it('ignores capacity entries with no table name', async () => {
+        requestCount = 0;
+        responses = [
+            {
+                UnprocessedItems: {},
+                ConsumedCapacity: [{ CapacityUnits: 7 }],
+            },
+        ];
+
+        await expect(
+            stubClient().batchPut([{ table: TABLE, item: { pk: 'anon' } }]),
+        ).resolves.toEqual({ ConsumedCapacity: [] });
+    });
+});

src/backend/clients/dynamodb/DDBClient.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -347,7 +347,15 @@ export class DDBClient extends PuterClient {
         pageKey?: Record<string, unknown>,
         index = '',
         consistentRead = false,
-        options?: { beginsWith?: { key: string; value: string } },
+        options?: {
+            beginsWith?: { key: string; value: string };
+            select?: 'COUNT';
+            filter?: {
+                expression: string;
+                values?: Record<string, unknown>;
+                names?: Record<string, string>;
+            };
+        },
     ) {
         const keyExpressionParts = Object.keys(keys).map(
             (key) => `#${key} = :${key}`,
@@ -378,6 +386,11 @@ export class DDBClient extends PuterClient {
             expressionAttributeNames[`#${beginsKey}`] = beginsKey;
         }
 
+        if (options?.filter) {
+            Object.assign(expressionAttributeValues, options.filter.values);
+            Object.assign(expressionAttributeNames, options.filter.names);
+        }
+
         const command = new QueryCommand({
             TableName: table,
             ...(!index ? {} : { IndexName: index }),
@@ -387,6 +400,10 @@ export class DDBClient extends PuterClient {
             ConsistentRead: consistentRead,
             ...(!pageKey ? {} : { ExclusiveStartKey: pageKey }),
             ...(!limit ? {} : { Limit: limit }),
+            ...(options?.filter
+                ? { FilterExpression: options.filter.expression }
+                : {}),
+            ...(options?.select ? { Select: options.select } : {}),
             ReturnConsumedCapacity: 'TOTAL',
         });
 
@@ -436,6 +453,7 @@ export class DDBClient extends PuterClient {
             return;
         }
 
+        let alreadyExisted = false;
         try {
             const client = await this.#getDocumentClient();
             await client.send(new CreateTableCommand(params));
@@ -443,14 +461,33 @@ export class DDBClient extends PuterClient {
             if ((error as Error)?.name !== 'ResourceInUseException') {
                 throw error;
             }
+            alreadyExisted = true;
         }
 
-        if (ttlAttribute) {
-            await this.#deleteExpiredItems(
-                params.TableName!,
-                params.KeySchema!,
-                ttlAttribute,
-            );
+        // Only sweep a table that was already there. `CreateTable` returns
+        // while the table is still CREATING, so scanning it right away races
+        // its transition to ACTIVE and intermittently throws
+        // `ResourceNotFoundException` — and a table we just created holds no
+        // items to expire anyway.
+        if (ttlAttribute && alreadyExisted) {
+            try {
+                await this.#deleteExpiredItems(
+                    params.TableName!,
+                    params.KeySchema!,
+                    ttlAttribute,
+                );
+            } catch (error) {
+                // The sweep is opportunistic cleanup, so a table that isn't
+                // queryable yet must never fail boot. Emulators differ on
+                // whether `CreateTable` reports an existing table as in-use,
+                // which can still land us here on a CREATING table.
+                if ((error as Error)?.name !== 'ResourceNotFoundException') {
+                    throw error;
+                }
+                console.warn(
+                    `[ddb] skipped TTL sweep for ${params.TableName}: table not queryable yet`,
+                );
+            }
         }
     }
 

src/backend/clients/email/EmailClient.test.ts

@@ -0,0 +1,322 @@
+/**
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import type { IConfig } from '../../types';
+import { EmailClient } from './EmailClient';
+
+const FROM = '"Puter" <[email protected]>';
+
+/**
+ * Nodemailer's JSON transport is a real transport that serializes the message
+ * instead of talking SMTP — the send path stays genuine while the wire stays
+ * local.
+ */
+const jsonTransportConfig = (overrides: Partial<IConfig> = {}): IConfig =>
+    ({
+        port: 0,
+        extensions: [],
+        env: 'prod',
+        email: { jsonTransport: true, from: FROM },
+        ...overrides,
+    }) as unknown as IConfig;
+
+const startClient = (overrides: Partial<IConfig> = {}): EmailClient => {
+    const client = new EmailClient(jsonTransportConfig(overrides));
+    client.onServerStart();
+    return client;
+};
+
+/** The JSON transport reports the serialized message on `.message`. */
+const sentMessage = (info: unknown) =>
+    JSON.parse((info as { message: string }).message) as {
+        from: { address: string; name: string };
+        to: { address: string }[];
+        subject: string;
+        html?: string;
+        headers?: Record<string, string>;
+    };
+
+describe('EmailClient — transport lifecycle', () => {
+    it('reports as configured once a transport is wired up', () => {
+        const client = startClient();
+        expect(client.isConfigured).toBe(true);
+        client.onServerShutdown();
+        expect(client.isConfigured).toBe(false);
+    });
+
+    it('warns and stays unconfigured when no transport is set', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const client = new EmailClient({
+            port: 0,
+            extensions: [],
+        } as unknown as IConfig);
+        client.onServerStart();
+
+        expect(client.isConfigured).toBe(false);
+        expect(warn).toHaveBeenCalledWith(
+            expect.stringContaining('no email transport configured'),
+        );
+        warn.mockRestore();
+    });
+
+    it('drops the send and returns null when no transport exists', async () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const client = new EmailClient({
+            port: 0,
+            extensions: [],
+        } as unknown as IConfig);
+        client.onServerStart();
+
+        await expect(
+            client.sendRaw({ to: '[email protected]', subject: 'hi', text: 'hi' }),
+        ).resolves.toBeNull();
+        expect(warn).toHaveBeenCalledWith(
+            expect.stringContaining('without transport'),
+            expect.objectContaining({ to: '[email protected]' }),
+        );
+        warn.mockRestore();
+    });
+});
+
+describe('EmailClient — sending', () => {
+    it('sends a rendered template through the transport', async () => {
+        const client = startClient();
+        const info = await client.sendRaw({
+            to: '[email protected]',
+            subject: 'raw subject',
+            html: '<p>hello</p>',
+            headers: { 'List-Unsubscribe': '<https://puter.test/u>' },
+        });
+
+        const message = sentMessage(info);
+        expect(message.subject).toBe('raw subject');
+        expect(message.to[0].address).toBe('[email protected]');
+        expect(message.from.address).toBe('[email protected]');
+        expect(message.headers?.['List-Unsubscribe']).toBe(
+            '<https://puter.test/u>',
+        );
+    });
+
+    it('lets the caller override the from address', async () => {
+        const client = startClient();
+        const info = await client.sendRaw({
+            from: '[email protected]',
+            to: '[email protected]',
+            subject: 's',
+            text: 't',
+        });
+        expect(sentMessage(info).from.address).toBe('[email protected]');
+    });
+
+    it('falls back to the built-in sender when config has none', async () => {
+        const client = startClient({
+            email: { jsonTransport: true },
+        } as unknown as Partial<IConfig>);
+        const info = await client.sendRaw({
+            to: '[email protected]',
+            subject: 's',
+            text: 't',
+        });
+        expect(sentMessage(info).from.address).toBe('[email protected]');
+    });
+
+    it('refuses an unknown template name', async () => {
+        const client = startClient();
+        await expect(
+            client.send('[email protected]', 'not-a-template' as never),
+        ).rejects.toThrow('Unknown email template: not-a-template');
+    });
+
+    it('surfaces transport failures to the caller', async () => {
+        // Port 1 on loopback is never listening, so the send really fails.
+        const client = startClient({
+            email: { host: '127.0.0.1', port: 1, from: FROM },
+        } as unknown as Partial<IConfig>);
+
+        await expect(
+            client.sendRaw({
+                to: '[email protected]',
+                subject: 's',
+                text: 't',
+            }),
+        ).rejects.toThrow();
+    });
+});
+
+describe('EmailClient — template rendering', () => {
+    it('renders the code into both subject and body', async () => {
+        const client = startClient();
+        const captured: { subject?: string; html?: string } = {};
+        const original = client.sendRaw.bind(client);
+        vi.spyOn(client, 'sendRaw').mockImplementation(async (options) => {
+            captured.subject = options.subject;
+            captured.html = options.html;
+            return original(options);
+        });
+
+        await client.send('[email protected]', 'email_verification_code', {
+            code: '424242',
+        });
+
+        expect(captured.subject).toBe('424242 is your confirmation code');
+        expect(captured.html).toContain('<strong>424242</strong>');
+    });
+
+    it('does not HTML-escape values in the plain-text subject header', async () => {
+        const client = startClient();
+        const captured: { subject?: string } = {};
+        vi.spyOn(client, 'sendRaw').mockImplementation(async (options) => {
+            captured.subject = options.subject;
+            return null;
+        });
+
+        await client.send('[email protected]', 'app-user-feedback', {
+            owner_username: 'dev',
+            sender_username: 'user',
+            sender_email: null,
+            app_title: "Bob's App & Games",
+            app_name: 'bobs-app',
+            app_link: 'https://puter.example/app/bobs-app',
+            message: 'hi',
+        });
+
+        // A subject is not HTML — entities would render literally in the
+        // recipient's mail client.
+        expect(captured.subject).toBe("New user feedback for Bob's App & Games");
+    });
+
+    it('escapes html and converts newlines in nl2br values', async () => {
+        const client = startClient();
+        let html = '';
+        vi.spyOn(client, 'sendRaw').mockImplementation(async (options) => {
+            html = options.html ?? '';
+            return null;
+        });
+
+        await client.send('[email protected]', 'listing-rejected', {
+            app_name: 'demo',
+            app_title: 'Demo',
+            reason: 'first & "only"\n<b>line</b>',
+        });
+
+        expect(html).toContain(
+            'first &amp; &quot;only&quot;<br />&lt;b&gt;line&lt;/b&gt;',
+        );
+    });
+
+    it('renders an empty string for a missing nl2br value', async () => {
+        const client = startClient();
+        let html = '';
+        vi.spyOn(client, 'sendRaw').mockImplementation(async (options) => {
+            html = options.html ?? '';
+            return null;
+        });
+
+        await client.send('[email protected]', 'listing-rejected', {
+            app_name: 'demo',
+            app_title: 'Demo',
+        });
+
+        expect(html).toContain('<blockquote></blockquote>');
+    });
+});
+
+describe('EmailClient.clean', () => {
+    const clean = (email: string) => startClient().clean(email);
+
+    it('strips subaddressing on ordinary domains', () => {
+        expect(clean('[email protected]')).toBe('[email protected]');
+    });
+
+    it('ignores dots and subaddressing for gmail', () => {
+        expect(clean('[email protected]')).toBe('[email protected]');
+    });
+
+    it('canonicalizes googlemail onto gmail', () => {
+        expect(clean('[email protected]')).toBe('[email protected]');
+    });
+
+    it('keeps yahoo subaddressing, which yahoo treats as distinct', () => {
+        expect(clean('[email protected]')).toBe('[email protected]');
+    });
+
+    it('ignores dots for icloud aliases', () => {
+        expect(clean('[email protected]')).toBe('[email protected]');
+    });
+
+    it('returns anything that is not an address unchanged', () => {
+        expect(clean('not-an-email')).toBe('not-an-email');
+        expect(clean('@nolocal.test')).toBe('@nolocal.test');
+    });
+});
+
+describe('EmailClient.validate', () => {
+    it('waves everything through in a dev environment', async () => {
+        const client = startClient({ env: 'dev' } as Partial<IConfig>);
+        await expect(client.validate('[email protected]')).resolves.toBe(
+            true,
+        );
+    });
+
+    it('rejects a blocked domain suffix', async () => {
+        const client = startClient({
+            blockedEmailDomains: ['blocked.test'],
+        } as unknown as Partial<IConfig>);
+
+        await expect(client.validate('[email protected]')).resolves.toBe(
+            false,
+        );
+        await expect(client.validate('[email protected]')).resolves.toBe(
+            true,
+        );
+    });
+
+    it('matches the blocklist against the cleaned address', async () => {
+        const client = startClient({
+            blockedEmailDomains: ['@gmail.com'],
+        } as unknown as Partial<IConfig>);
+        await expect(
+            client.validate('[email protected]'),
+        ).resolves.toBe(false);
+    });
+
+    it('lets a registered validator veto an address', async () => {
+        const client = startClient();
+        const seen: string[] = [];
+        client.addValidator((email) => {
+            seen.push(email);
+            return !email.startsWith('spam');
+        });
+
+        await expect(client.validate('[email protected]')).resolves.toBe(
+            false,
+        );
+        await expect(client.validate('[email protected]')).resolves.toBe(true);
+        // Validators always see the canonical form.
+        expect(seen).toEqual(['[email protected]', '[email protected]']);
+    });
+
+    it('supports asynchronous validators', async () => {
+        const client = startClient();
+        client.addValidator(async (email) => email !== '[email protected]');
+        await expect(client.validate('[email protected]')).resolves.toBe(false);
+        await expect(client.validate('[email protected]')).resolves.toBe(true);
+    });
+});

src/backend/clients/email/EmailClient.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -45,11 +45,18 @@ export interface SendMailOptions {
     to: string;
     cc?: string;
     bcc?: string;
+    /** Optional transport recipients when they differ from visible headers. */
+    envelope?: {
+        from?: string;
+        to: string;
+    };
     subject: string;
     html?: string;
     text?: string;
     replyTo?: string;
     attachments?: EmailAttachment[];
+    /** Extra message headers (e.g. List-Unsubscribe), passed to the transport. */
+    headers?: Record<string, string>;
 }
 
 export type EmailValidator = (email: string) => Promise<boolean> | boolean;
@@ -103,10 +110,11 @@ const DOMAIN_ALIASES: Record<string, string> = {
 
 /**
  * Unified email client. Handles:
- *   - Template-based outbound mail (via `send`)
- *   - Raw nodemailer passthrough (via `sendRaw`)
- *   - Canonical-form normalization for dedup (via `clean`)
- *   - Policy + extensible validation (via `validate`)
+ *
+ * - Template-based outbound mail (via `send`)
+ * - Raw nodemailer passthrough (via `sendRaw`)
+ * - Canonical-form normalization for dedup (via `clean`)
+ * - Policy + extensible validation (via `validate`)
  */
 export class EmailClient extends PuterClient {
     private transport: ReturnType<typeof nodemailer.createTransport> | null =
@@ -145,12 +153,15 @@ export class EmailClient extends PuterClient {
     // -- Public API: sending ------------------------------------------
 
     /**
-     * Render a template and send it to `to`.
+     * Render a template and send it to `to`. `options.replyTo` sets the
+     * Reply-To header (e.g. so a recipient can respond to the originator of the
+     * message rather than the no-reply From address).
      */
     async send<T extends EmailTemplateName>(
         to: string,
         template: T,
         values: Record<string, unknown> = {},
+        options: { replyTo?: string } = {},
     ): Promise<void> {
         const compiled = this.compiledTemplates[template];
         if (!compiled) {
@@ -162,16 +173,17 @@ export class EmailClient extends PuterClient {
             to,
             subject: compiled.subject(values),
             html: compiled.html(values),
+            ...(options.replyTo ? { replyTo: options.replyTo } : {}),
         });
     }
 
     /**
-     * Raw send — bypasses the template system. Useful for one-off
-     * admin emails that don't warrant a named template.
+     * Raw send — bypasses the template system. Useful for one-off admin emails
+     * that don't warrant a named template.
      *
-     * Returns the transport's send result, or `null` when no transport
-     * is configured (the send is a no-op in that case — callers that
-     * must not silently drop mail should check `isConfigured` first).
+     * Returns the transport's send result, or `null` when no transport is
+     * configured (the send is a no-op in that case — callers that must not
+     * silently drop mail should check `isConfigured` first).
      */
     async sendRaw(options: SendMailOptions) {
         if (!this.transport) {
@@ -195,9 +207,9 @@ export class EmailClient extends PuterClient {
     // -- Public API: clean / validate ---------------------------------
 
     /**
-     * Normalize an email to its canonical form for dedup comparisons.
-     * Applies provider-specific rules (e.g. Gmail ignores dots in
-     * the local part) plus generic subaddressing removal.
+     * Normalize an email to its canonical form for dedup comparisons. Applies
+     * provider-specific rules (e.g. Gmail ignores dots in the local part) plus
+     * generic subaddressing removal.
      */
     clean(email: string): string {
         let [local, domain] = email.split('@');
@@ -226,9 +238,9 @@ export class EmailClient extends PuterClient {
     }
 
     /**
-     * Check whether an email is allowed to be used. Checks domain
-     * blocklist plus any registered validators (services can call
-     * `addValidator()` to register custom policy hooks).
+     * Check whether an email is allowed to be used. Checks domain blocklist
+     * plus any registered validators (services can call `addValidator()` to
+     * register custom policy hooks).
      */
     async validate(email: string): Promise<boolean> {
         if (this.config.env === 'dev') return true;
@@ -251,9 +263,8 @@ export class EmailClient extends PuterClient {
     }
 
     /**
-     * Register a custom validation hook. Services can call this
-     * during their startup to veto specific emails (e.g. a
-     * disposable-email service).
+     * Register a custom validation hook. Services can call this during their
+     * startup to veto specific emails (e.g. a disposable-email service).
      */
     addValidator(fn: EmailValidator): void {
         this.validators.push(fn);
@@ -280,7 +291,14 @@ export class EmailClient extends PuterClient {
     private compileTemplates(): void {
         for (const [name, template] of Object.entries(EMAIL_TEMPLATES)) {
             this.compiledTemplates[name as EmailTemplateName] = {
-                subject: handlebars.compile(template.subject),
+                // Subjects are plain-text headers: HTML-escaping would put
+                // literal entities in front of the recipient (&amp; etc.).
+                // Header safety is handled elsewhere — the transport encodes
+                // newlines, and free-form values (e.g. app_title) collapse
+                // whitespace upstream.
+                subject: handlebars.compile(template.subject, {
+                    noEscape: true,
+                }),
                 html: handlebars.compile(dedent(template.html)),
             };
         }

src/backend/clients/email/templates.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -18,12 +18,12 @@
  */
 
 /**
- * Email template definitions. Keys are the template names; values are
- * the Handlebars-compilable `subject` and `html` strings.
+ * Email template definitions. Keys are the template names; values are the
+ * Handlebars-compilable `subject` and `html` strings.
  *
- * Rendered values are supplied by callers of `EmailClient.send()`.
- * Variables use standard Handlebars syntax: `{{var}}`, `{{#if cond}}…{{/if}}`,
- * and the custom helper `{{{nl2br text}}}` for HTML-safe newline conversion.
+ * Rendered values are supplied by callers of `EmailClient.send()`. Variables
+ * use standard Handlebars syntax: `{{var}}`, `{{#if cond}}…{{/if}}`, and the
+ * custom helper `{{{nl2br text}}}` for HTML-safe newline conversion.
  */
 
 export interface EmailTemplate {
@@ -75,6 +75,25 @@ Please update <a href="https://puter.com/app/{{app_name}}">{{app_title}}</a>.
 <blockquote>{{nl2br message}}</blockquote>
 <p>Best,<br />
 The Puter Team
+</p>
+        `,
+    },
+    'app-user-feedback': {
+        subject: 'New user feedback for {{app_title}}',
+        html: `
+<p>Hi{{#if owner_username}} {{owner_username}}{{/if}},</p>
+<p>
+<strong>{{sender_username}}</strong>{{#if sender_email}} (<a href="mailto:{{sender_email}}">{{sender_email}}</a>){{/if}} sent feedback about <a href="{{app_link}}">{{app_title}}</a>:
+</p>
+<blockquote>{{{nl2br message}}}</blockquote>
+{{#if sender_email}}<p>Just reply to this email to respond to them directly.</p>{{/if}}
+<p>
+You're receiving this because feedback is enabled for
+<a href="{{app_link}}">{{app_title}}</a> — manage it in the
+<a href="{{dev_center_link}}">Dev Center</a> under your app's settings.
+</p>
+<p>Best,<br />
+The Puter Team
 </p>
         `,
     },

src/backend/clients/event/EventClient.test.ts

@@ -1,5 +1,6 @@
 import {
     afterAll,
+    afterEach,
     beforeAll,
     beforeEach,
     describe,
@@ -7,6 +8,7 @@ import {
     it,
     vi,
 } from 'vitest';
+import { extensionStore } from '../../extensions.ts';
 import { PuterServer } from '../../server.ts';
 import { setupTestServer } from '../../testUtil.ts';
 import type { EventClient } from './EventClient.js';
@@ -21,12 +23,11 @@ describe('EventClient', () => {
     });
 
     afterAll(async () => {
-        await server.shutdown();
+        await server?.shutdown();
     });
 
     // Each test gets a fresh key so listeners registered by earlier tests
-    // never collide with later ones (the client has no public way to
-    // unsubscribe).
+    // never collide with later ones.
     let key: string;
     beforeEach(() => {
         key = `test.${Math.random().toString(36).slice(2)}`;
@@ -184,6 +185,106 @@ describe('EventClient', () => {
         });
     });
 
+    describe('off', () => {
+        it('stops delivering to a removed listener', () => {
+            const kept = vi.fn();
+            const removed = vi.fn();
+            target.on(key, kept);
+            target.on(key, removed);
+
+            target.off(key, removed);
+            target.emit(key, {}, {});
+
+            expect(kept).toHaveBeenCalledTimes(1);
+            expect(removed).not.toHaveBeenCalled();
+        });
+
+        it('ignores a key nobody ever subscribed to', () => {
+            expect(() => target.off(key, vi.fn())).not.toThrow();
+        });
+
+        it('leaves the list alone when the listener was never registered', () => {
+            const listener = vi.fn();
+            target.on(key, listener);
+
+            target.off(key, vi.fn());
+            target.emit(key, {}, {});
+
+            expect(listener).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    describe('hasListeners', () => {
+        it('is false for a key nobody subscribed to', () => {
+            expect(target.hasListeners(key)).toBe(false);
+        });
+
+        it('is true for an exact subscriber', () => {
+            target.on(key, vi.fn());
+            expect(target.hasListeners(key)).toBe(true);
+        });
+
+        it('is true when only a wildcard prefix matches', () => {
+            target.on(`${key}.*`, vi.fn());
+            expect(target.hasListeners(`${key}.child.deep`)).toBe(true);
+        });
+
+        it('is true for an extension-registered listener', () => {
+            extensionStore.events[key] = [vi.fn()];
+            try {
+                expect(target.hasListeners(key)).toBe(true);
+            } finally {
+                delete extensionStore.events[key];
+            }
+        });
+
+        it('goes back to false once the last listener is removed', () => {
+            const listener = vi.fn();
+            target.on(key, listener);
+            target.off(key, listener);
+            expect(target.hasListeners(key)).toBe(false);
+        });
+    });
+
+    describe('extension-registered listeners', () => {
+        afterEach(() => {
+            delete extensionStore.events[key];
+        });
+
+        it('fires alongside listeners registered on the client', () => {
+            const fromExtension = vi.fn();
+            const fromClient = vi.fn();
+            extensionStore.events[key] = [fromExtension];
+            target.on(key, fromClient);
+
+            target.emit(key, { n: 1 }, { source: 'test' });
+
+            expect(fromExtension).toHaveBeenCalledWith(
+                key,
+                { n: 1 },
+                { source: 'test' },
+            );
+            expect(fromClient).toHaveBeenCalledTimes(1);
+        });
+
+        it('is awaited by emitAndWait', async () => {
+            const order: string[] = [];
+            extensionStore.events[key] = [
+                async () => {
+                    await new Promise((resolve) => setTimeout(resolve, 5));
+                    order.push('extension');
+                },
+            ];
+            target.on(key, () => {
+                order.push('client');
+            });
+
+            await target.emitAndWait(key, {}, {});
+
+            expect(order).toEqual(['client', 'extension']);
+        });
+    });
+
     describe('lifecycle hooks', () => {
         it('onServerStart emits a serverStart event', () => {
             const listener = vi.fn();

src/backend/clients/event/EventClient.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -44,20 +44,19 @@ export class EventClient extends PuterClient {
     /**
      * Dispatch an event to every matching subscriber.
      *
-     * Match semantics: emit walks every dot-separated prefix of `key`,
-     * looking up `<prefix>.*` listeners for prefixes shorter than the full
-     * key, and exact-key listeners on the final iteration. So emitting
+     * Match semantics: emit walks every dot-separated prefix of `key`, looking
+     * up `<prefix>.*` listeners for prefixes shorter than the full key, and
+     * exact-key listeners on the final iteration. So emitting
      * `outer.gui.item.removed` fires subscribers on:
      *
-     *   - `outer.*`
-     *   - `outer.gui.*`
-     *   - `outer.gui.item.*`
-     *   - `outer.gui.item.removed`
-     *
-     * Subscribers are still keyed in a single map — wildcards just live
-     * under their literal `<prefix>.*` string. No regex, no per-emit
-     * scan of every listener.
+     * - `outer.*`
+     * - `outer.gui.*`
+     * - `outer.gui.item.*`
+     * - `outer.gui.item.removed`
      *
+     * Subscribers are still keyed in a single map — wildcards just live under
+     * their literal `<prefix>.*` string. No regex, no per-emit scan of every
+     * listener.
      */
     emit<T extends keyof EventMap>(
         key: T,
@@ -85,15 +84,15 @@ export class EventClient extends PuterClient {
     /**
      * Like `emit`, but awaits every matched listener before resolving.
      *
-     * Use this when the emitter needs to act on mutations the handlers made
-     * to `data` — e.g. validation hooks where a listener can set
-     * `data.allow = false` to reject, or pre-commit pipelines where every
-     * stage must complete before the next step runs. Regular `emit` is
-     * fire-and-forget and can't observe handler state changes.
+     * Use this when the emitter needs to act on mutations the handlers made to
+     * `data` — e.g. validation hooks where a listener can set `data.allow =
+     * false` to reject, or pre-commit pipelines where every stage must complete
+     * before the next step runs. Regular `emit` is fire-and-forget and can't
+     * observe handler state changes.
      *
-     * Listeners run sequentially in the order they're registered so an
-     * earlier handler's mutation is visible to later ones. A listener that
-     * throws is logged (same as `emit`) and the chain continues.
+     * Listeners run sequentially in the order they're registered so an earlier
+     * handler's mutation is visible to later ones. A listener that throws is
+     * logged (same as `emit`) and the chain continues.
      */
     async emitAndWait<T extends keyof EventMap>(
         key: T,
@@ -130,18 +129,37 @@ export class EventClient extends PuterClient {
         });
     }
 
+    /**
+     * Whether anything would run if `key` were emitted, wildcards included.
+     *
+     * For emitters whose work is only worth doing when someone is listening —
+     * gathering the payload costs a round trip, say. Emitting into the void is
+     * otherwise perfectly cheap and doesn't need this.
+     */
+    hasListeners<T extends keyof EventMap>(key: T): boolean {
+        const parts = key.split('.');
+        for (let i = 0; i < parts.length; i++) {
+            const matchKey = (
+                i === parts.length - 1
+                    ? key
+                    : `${parts.slice(0, i + 1).join('.')}.*`
+            ) as ListenKey;
+            if (this.#eventListeners[matchKey]?.length) return true;
+            if (extensionStore.events[matchKey]?.length) return true;
+        }
+        return false;
+    }
+
     /**
      * Subscribe to an event by exact key OR a wildcard prefix.
      *
-     * Wildcards: a key ending in `.*` matches every event whose name
-     * starts with the prefix. `outer.*` matches `outer.gui.item.removed`,
-     * `outer.fs.write-hash`, and any other dot-extended descendant.
-     * Exact keys still match exactly. See `emit()` for the dispatch order.
-     *
-     * Callback receives the full `(key, data, meta)` tuple as passed
-     * to `emit()` — wildcard subscribers can branch on the triggering
-     * event name.
+     * Wildcards: a key ending in `.*` matches every event whose name starts
+     * with the prefix. `outer.*` matches `outer.gui.item.removed`,
+     * `outer.fs.write-hash`, and any other dot-extended descendant. Exact keys
+     * still match exactly. See `emit()` for the dispatch order.
      *
+     * Callback receives the full `(key, data, meta)` tuple as passed to
+     * `emit()` — wildcard subscribers can branch on the triggering event name.
      */
     on<P extends ListenKey>(
         key: P,

src/backend/clients/event/types.ts

@@ -3,15 +3,16 @@
  *
  * Domain objects (User, Actor, FSEntry, Socket, ...) are typed as `unknown`
  * here on purpose — pulling their real types in would couple this module to
- * most of the backend and risk import cycles. Refine at the listener if
- * you need narrowed access.
+ * most of the backend and risk import cycles. Refine at the listener if you
+ * need narrowed access.
  *
  * Conventions:
- * - `*.validate` events carry an `allow` flag listeners flip to reject;
- *   they tend to grow listener-specific fields, so they accept extras via
- *   an index signature.
- * - `outer.gui.*` events ride the `{ user_id_list, response }` envelope
- *   the SocketService fans out to user-scoped channels.
+ *
+ * - `*.validate` events carry an `allow` flag listeners flip to reject; they tend
+ *   to grow listener-specific fields, so they accept extras via an index
+ *   signature.
+ * - `outer.gui.*` events ride the `{ user_id_list, response }` envelope the
+ *   SocketService fans out to user-scoped channels.
  */
 
 import type {
@@ -19,6 +20,7 @@ import type {
     Response as ExpressResponse,
 } from 'express';
 import { Actor } from '../../core';
+import type { UsageInput } from '../../services/metering/types';
 import { FSEntry } from '../../stores/fs/FSEntry';
 
 // GUI write events spread an entry plus per-event metadata into `response`.
@@ -148,13 +150,16 @@ export type EventMap = {
         trail?: Array<string>;
         /**
          * Set by the abuse harness for flagged signups — the id under which the
-         * decision trail is persisted to KV (`abuse:trail:<id>`), shared back on
-         * the request for log / support correlation.
+         * decision trail is persisted to KV (`abuse:trail:<id>`), shared back
+         * on the request for log / support correlation.
          */
         trail_id?: string;
         /** Device signal forwarded verbatim from the signup request body. */
         fingerprint?: string | null;
-        /** Set by the abuse harness — require SMS phone verification post-signup. */
+        /**
+         * Set by the abuse harness — require SMS phone verification
+         * post-signup.
+         */
         requires_phone_verification?: boolean;
         /** Set by the abuse harness — require card verification post-signup. */
         requires_card_verification?: boolean;
@@ -301,6 +306,38 @@ export type EventMap = {
     };
     'storage.quota.bonus': { userId: number; extra: number };
 
+    // ---- Metering ----
+    // Recurring charges are pure mechanism here: the metering service knows
+    // when to ask (once per user per month, the first time that month's usage
+    // record is touched) and how to record the answer, and an extension
+    // decides what the account owes. Listeners push onto `charges`; the
+    // service applies them as ordinary usage once every listener has run.
+    // Nothing listening → no charges and no claim is ever taken.
+    //
+    // Emitted after the claim is settled, so a listener that calls back into
+    // metering can't re-trigger it.
+    'metering.monthly.charges': {
+        /**
+         * User-scoped, with no app on it: the account is what recurs, and the
+         * app that happened to trigger the month's first call has nothing to do
+         * with what is owed. Price against what the user owns.
+         */
+        actor: Actor;
+        /** The month being charged for, `YYYY-MM` in UTC. */
+        month: string;
+        /**
+         * Push what the user owes here. Every listener's charges are merged
+         * into one amount map and recorded as a single increment.
+         */
+        charges: UsageInput[];
+    };
+
+    // ---- Workers ----
+    // Only a genuinely new worker. Redeploying an existing name updates its
+    // row instead, and never reaches here — so a listener that prices this
+    // is pricing workers that came into existence, not deploys.
+    'worker.create': { actor: Actor; workerName: string };
+
     // ---- Outer / GUI broadcast ----
     'outer.cacheUpdate': {
         cacheKey: string[];
@@ -308,6 +345,15 @@ export type EventMap = {
         ttlSeconds?: number;
     };
     'outer.fs.write-hash': { hash: string; uuid: string };
+    /**
+     * Cache keys the KV read cache must stop serving, because the entries
+     * behind them were just written somewhere else.
+     *
+     * `outer.*` rather than `outer.pubsub.*` on purpose: the cache lives in the
+     * Redis a cluster shares, so one node applying the invalidation covers the
+     * whole cluster — fanning it out to siblings would just repeat the write.
+     */
+    'outer.kv.cacheInvalidated': { cacheKeys: string[] };
     'outer.gui.item.added': GuiEvent;
     'outer.gui.item.updated': GuiEvent;
     'outer.gui.item.moved': GuiEvent;
@@ -334,9 +380,13 @@ export type EventMap = {
     };
 
     // ---- Thumbnails ----
+    // The listener rewrites `thumbnail` in place (an s3:// key or legacy
+    // https:// URL becomes a signed URL) and falls back to `uuid`/`uid` to
+    // migrate inline data-URL thumbnails. Declared to match: the previous
+    // `uri` member was never emitted nor read.
     'thumbnail.read': {
-        uri: string;
-        size?: string;
+        uuid?: string;
+        uid?: string;
         thumbnail?: string | null;
     };
     'thumbnail.created': { url: string };
@@ -394,6 +444,22 @@ export type EventMap = {
     [K in `route.${string}`]: RouteLifecycleEvent;
 } & {
     [K in `pubsub.login.${string}`]: { authtoken: string };
+} & {
+    /**
+     * A user's subscription now resolves to a different policy. Carried on the
+     * `outer.pubsub.*` channel so it reaches sibling nodes and peer clusters,
+     * not just the one that handled the change — every node caches the resolved
+     * policy, so a purchase is only live once they have all dropped theirs.
+     */
+    'outer.pubsub.metering.subscription-changed': { userUuid: string };
+    /**
+     * A user's purchased credit balance changed. Separate from a policy change
+     * because it moves the other half of the same budget, and carried on the
+     * `outer.pubsub.*` channel for the same reason: every node caches whether
+     * an account has budget left, so a top-up only lifts enforcement once they
+     * have all dropped that answer.
+     */
+    'outer.pubsub.metering.credits-changed': { userUuid: string };
 };
 
 /**
@@ -406,9 +472,9 @@ export type LifecyclePhase = 'before' | 'after' | 'error' | 'reject';
 /**
  * Payload for `driver.<iface>.<method>.<phase>` events.
  *
- * One shape across all phases; read `phase` (or the key suffix) to
- * branch. `allow`/`rejectReason` are only meaningful on the `before` phase
- * (emitted via `emitAndWait`).
+ * One shape across all phases; read `phase` (or the key suffix) to branch.
+ * `allow`/`rejectReason` are only meaningful on the `before` phase (emitted via
+ * `emitAndWait`).
  */
 export type DriverMethodLifecycleEvent = {
     phase: LifecyclePhase;
@@ -474,11 +540,10 @@ export type EventKey = keyof EventMap & string;
 // Generates a wildcard for every non-final dot-separated prefix of K.
 export type WildcardPrefixes<K extends string> =
     K extends `${infer Head}.${infer Tail}`
-        ?
-              | `${Head}.*`
-              | (Tail extends `${string}.${string}`
-                    ? `${Head}.${WildcardPrefixes<Tail>}`
-                    : never)
+        ? | `${Head}.*`
+          | (Tail extends `${string}.${string}`
+                ? `${Head}.${WildcardPrefixes<Tail>}`
+                : never)
         : never;
 
 export type ListenKey = EventKey | WildcardPrefixes<EventKey>;

src/backend/clients/index.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.

src/backend/clients/prelude/PreludeClient.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -74,11 +74,11 @@ export type PreludeCheckStatus =
     | 'transaction_mismatch';
 
 /**
- * Prelude Verify v2 client (https://docs.prelude.so/verify/v2). Sends and checks
- * SMS one-time codes — Prelude generates, delivers, and validates the code, so
- * we never store one ourselves. No-ops with a warning when no API key is
- * configured (so dev environments don't crash); `isConfigured()` lets callers
- * surface a clean "phone verification unavailable" error instead.
+ * Prelude Verify v2 client (https://docs.prelude.so/verify/v2). Sends and
+ * checks SMS one-time codes — Prelude generates, delivers, and validates the
+ * code, so we never store one ourselves. No-ops with a warning when no API key
+ * is configured (so dev environments don't crash); `isConfigured()` lets
+ * callers surface a clean "phone verification unavailable" error instead.
  */
 export class PreludeClient extends PuterClient {
     private apiKey: string | null = null;
@@ -113,7 +113,9 @@ export class PreludeClient extends PuterClient {
 
     /**
      * Whether SMS verification should be offered for a country. False when the
-     * country is unknown, has no SMS channel, or its rate exceeds the cost cap.
+     * country is unknown, has no SMS channel, or its rate exceeds the cost
+     * cap.
+     *
      * @param iso ISO-3166 alpha-2 (e.g. 'US') — from the parsed phone number.
      */
     isCountrySupported(iso: string | undefined): boolean {
@@ -174,7 +176,9 @@ export class PreludeClient extends PuterClient {
     }
 
     /**
-     * Check a code the user entered against the active verification for `target`.
+     * Check a code the user entered against the active verification for
+     * `target`.
+     *
      * @returns `{ status }` — `'success'` means verified.
      */
     async checkVerification(

src/backend/clients/prelude/countries.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -17,11 +17,13 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-/** Per-country Prelude SMS pricing, hardcoded from the Prelude global price
+/**
+ * Per-country Prelude SMS pricing, hardcoded from the Prelude global price
  * sheet. `sms` is the average cost in EUR, or null when SMS is unavailable
  * there. Used to cap phone verification to affordable countries (see
  * PreludeClient.isCountrySupported). Regenerate from the price sheet when
- * Prelude updates rates. */
+ * Prelude updates rates.
+ */
 export interface CountryPrice {
     name: string;
     /** Prelude SMS average in EUR, or null when SMS is not available. */

src/backend/clients/redis/RedisClient.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { IConfig } from '../../types';
+import { RedisClient } from './RedisClient';
+
+const config = (redis: Record<string, unknown>): IConfig =>
+    ({ port: 0, extensions: [], redis }) as unknown as IConfig;
+
+type ClusterOptions = {
+    redisOptions?: { tls?: unknown; connectTimeout?: number };
+    clusterRetryStrategy?: (attempts: number) => number;
+};
+
+const optionsOf = (client: RedisClient): ClusterOptions =>
+    (client as unknown as { options: ClusterOptions }).options;
+
+describe('RedisClient — in-process mock', () => {
+    let client: RedisClient | null = null;
+
+    afterEach(async () => {
+        if (client) await client.onServerShutdown();
+        client = null;
+    });
+
+    it('falls back to the mock when no startup nodes are configured', async () => {
+        client = new RedisClient(config({}));
+        await client.set('greeting', 'hello');
+        await expect(client.get('greeting')).resolves.toBe('hello');
+    });
+
+    it('honours an explicit mock request even with startup nodes present', async () => {
+        client = new RedisClient(
+            config({
+                useMock: true,
+                startupNodes: [{ host: 'redis.internal', port: 6379 }],
+            }),
+        );
+        await client.set('k', 'v');
+        await expect(client.get('k')).resolves.toBe('v');
+    });
+
+    it('exposes the shutdown hook directly on the cluster instance', () => {
+        client = new RedisClient(config({}));
+        expect(typeof client.onServerShutdown).toBe('function');
+    });
+
+    it('disconnects when a clean quit fails', async () => {
+        const instance = new RedisClient(config({}));
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        vi.spyOn(instance, 'quit').mockRejectedValue(new Error('quit refused'));
+        const disconnect = vi.spyOn(instance, 'disconnect');
+
+        await instance.onServerShutdown();
+
+        expect(disconnect).toHaveBeenCalledTimes(1);
+        expect(warn).toHaveBeenCalledWith(
+            '[redis] failed to quit redis client cleanly',
+            expect.any(Error),
+        );
+        warn.mockRestore();
+    });
+});
+
+describe('RedisClient — real cluster wiring', () => {
+    let client: RedisClient | null = null;
+
+    afterEach(() => {
+        client?.disconnect();
+        client = null;
+    });
+
+    const startupNodes = [{ host: '127.0.0.1', port: 7001 }];
+
+    it('enables TLS by default and bounds the connect timeout', () => {
+        client = new RedisClient(config({ startupNodes }));
+        expect(optionsOf(client).redisOptions?.tls).toEqual({});
+        expect(optionsOf(client).redisOptions?.connectTimeout).toBe(10000);
+    });
+
+    it('lets a plain-TCP deployment opt out of TLS', () => {
+        client = new RedisClient(config({ startupNodes, tls: false }));
+        expect(optionsOf(client).redisOptions?.tls).toBeUndefined();
+    });
+
+    it('backs off on cluster retries up to a ceiling', () => {
+        client = new RedisClient(config({ startupNodes, tls: false }));
+        const retry = optionsOf(client).clusterRetryStrategy!;
+        expect(retry(0)).toBe(100);
+        expect(retry(5)).toBe(600);
+        expect(retry(100)).toBe(2000);
+    });
+
+    it('treats startup churn as a warning and everything else as an error', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+        client = new RedisClient(config({ startupNodes, tls: false }));
+
+        client.emit('error', new Error('None of startup nodes is available'));
+        expect(warn).toHaveBeenCalledWith(
+            expect.stringContaining('startup issue while connecting'),
+        );
+
+        const fatal = new Error('WRONGPASS invalid credentials');
+        client.emit('error', fatal);
+        expect(error).toHaveBeenCalledWith('[redis] cluster error', fatal);
+
+        warn.mockRestore();
+        error.mockRestore();
+    });
+
+    it('applies the same triage to per-node errors', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+        client = new RedisClient(config({ startupNodes, tls: false }));
+
+        const transient = new Error('boom');
+        transient.name = 'ClusterAllFailedError';
+        client.emit('node error', transient, '127.0.0.1:7001');
+        expect(warn).toHaveBeenCalledWith(
+            expect.stringContaining(
+                'startup issue for cluster node 127.0.0.1:7001',
+            ),
+        );
+
+        const fatal = new Error('node exploded');
+        client.emit('node error', fatal, '127.0.0.1:7002');
+        expect(error).toHaveBeenCalledWith(
+            '[redis] cluster node error (127.0.0.1:7002)',
+            fatal,
+        );
+
+        // Non-Error payloads are stringified rather than crashing the handler.
+        client.emit('node error', 'None of startup nodes is available', 'n3');
+        expect(warn).toHaveBeenCalledWith(
+            expect.stringContaining('startup issue for cluster node n3'),
+        );
+
+        warn.mockRestore();
+        error.mockRestore();
+    });
+
+    it('logs the transport lifecycle once each', () => {
+        const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+        client = new RedisClient(config({ startupNodes, tls: false }));
+
+        client.emit('connect');
+        client.emit('ready');
+
+        expect(log).toHaveBeenCalledWith('[redis] cluster transport connected');
+        expect(log).toHaveBeenCalledWith('[redis] cluster ready');
+        log.mockRestore();
+    });
+});

src/backend/clients/redis/RedisClient.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -108,13 +108,13 @@ const buildCluster = (config: IConfig): Cluster => {
 
 /**
  * `RedisClient` IS the ioredis `Cluster` instance — consumers call
- * `this.clients.redis.get(...)` / `.set(...)` directly rather than
- * going through an inner `.client` field. Lifecycle methods
- * (`onServerShutdown`) are attached onto the cluster instance itself.
+ * `this.clients.redis.get(...)` / `.set(...)` directly rather than going
+ * through an inner `.client` field. Lifecycle methods (`onServerShutdown`) are
+ * attached onto the cluster instance itself.
  *
- * Type-wise, `RedisClient` is `Cluster & WithLifecycle`; the registry-
- * facing value below is a constructor that returns that shape. Mirrors
- * the `DatabaseClientFactory` pattern.
+ * Type-wise, `RedisClient` is `Cluster & WithLifecycle`; the registry- facing
+ * value below is a constructor that returns that shape. Mirrors the
+ * `DatabaseClientFactory` pattern.
  */
 export type RedisClient = Cluster & WithLifecycle;
 

src/backend/clients/s3/S3Client.test.ts

@@ -0,0 +1,489 @@
+/**
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { GetObjectCommand } from '@aws-sdk/client-s3';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { IConfig } from '../../types';
+import { S3Client } from './S3Client';
+
+const LOCAL_BUCKET = 'puter-local';
+
+/**
+ * The multipart helper takes its command sender as a parameter, so the failure
+ * paths can be driven without a live endpoint.
+ */
+type S3Internals = {
+    awsConfig: { endpoint?: string };
+    migrateLegacyStorage(opts?: {
+        bucket?: string;
+        legacyPath?: string;
+    }): Promise<{ migratedFileCount: number; scannedEntryCount: number }>;
+    uploadMultipart(args: {
+        bucket: string;
+        client: { send: (command: unknown) => Promise<unknown> };
+        filePath: string;
+        fileSize: number;
+        key: string;
+    }): Promise<void>;
+};
+
+const internals = (client: S3Client) => client as unknown as S3Internals;
+
+const localConfig = (): IConfig =>
+    ({
+        port: 0,
+        extensions: [],
+        s3: { localConfig: { inMemory: true } },
+    }) as unknown as IConfig;
+
+const startLocal = async (): Promise<S3Client> => {
+    const client = new S3Client(localConfig());
+    await client.onServerStart();
+    return client;
+};
+
+const objectBody = async (
+    client: S3Client,
+    key: string,
+): Promise<string | undefined> => {
+    const result = await client
+        .get()
+        .send(new GetObjectCommand({ Bucket: LOCAL_BUCKET, Key: key }));
+    return result.Body?.transformToString();
+};
+
+describe('S3Client — local development endpoint', () => {
+    let client: S3Client;
+
+    beforeEach(async () => {
+        client = await startLocal();
+    });
+
+    afterEach(async () => {
+        await client.onServerShutdown();
+    });
+
+    it('points clients at the in-process object store', async () => {
+        await client
+            .get()
+            .send(
+                new GetObjectCommand({
+                    Bucket: LOCAL_BUCKET,
+                    Key: 'definitely-absent',
+                }),
+            )
+            .then(
+                () => {
+                    throw new Error('expected a missing-key failure');
+                },
+                (error: { name?: string }) => {
+                    expect(error.name).toBe('NoSuchKey');
+                },
+            );
+    });
+
+    it('reuses one client per region and mints a new one per region', () => {
+        const first = client.get('us-west-2');
+        expect(client.get('us-west-2')).toBe(first);
+        expect(client.get('eu-central-1')).not.toBe(first);
+    });
+
+    it('serves presigning from the same client when no public endpoint is set', () => {
+        expect(client.getForPresign('us-west-2')).toBe(client.get('us-west-2'));
+    });
+
+    it('keeps modest upload thresholds so the local store is not overwhelmed', () => {
+        expect(client.maxSingleUploadSize).toBe(10 * 1024 * 1024);
+        expect(client.partSize).toBe(5 * 1024 * 1024);
+    });
+});
+
+describe('S3Client — remote endpoint configuration', () => {
+    let local: S3Client;
+    let remote: S3Client | null = null;
+
+    beforeEach(async () => {
+        local = await startLocal();
+    });
+
+    afterEach(async () => {
+        if (remote) await remote.onServerShutdown();
+        remote = null;
+        await local.onServerShutdown();
+    });
+
+    const remoteConfig = (extra: Record<string, unknown>): IConfig =>
+        ({
+            port: 0,
+            extensions: [],
+            s3: {
+                s3Config: {
+                    endpoint: internals(local).awsConfig.endpoint,
+                    accessKeyId: 'fakeAccessKeyId',
+                    secretAccessKey: 'fakeSecretAccessKey',
+                    region: 'us-west-2',
+                    forcePathStyle: true,
+                    ...extra,
+                },
+            },
+        }) as unknown as IConfig;
+
+    it('talks to a configured S3-compatible endpoint', async () => {
+        remote = new S3Client(remoteConfig({}));
+        await remote.onServerStart();
+
+        await remote
+            .get()
+            .send(new GetObjectCommand({ Bucket: LOCAL_BUCKET, Key: 'nope' }))
+            .then(
+                () => {
+                    throw new Error('expected a missing-key failure');
+                },
+                (error: { name?: string }) => {
+                    expect(error.name).toBe('NoSuchKey');
+                },
+            );
+    });
+
+    it('signs browser-facing URLs against the public endpoint', async () => {
+        remote = new S3Client(
+            remoteConfig({ publicEndpoint: 'https://cdn.example.test' }),
+        );
+        await remote.onServerStart();
+
+        const presign = remote.getForPresign('us-west-2');
+        expect(presign).not.toBe(remote.get('us-west-2'));
+        // Cached per region like the regular client map.
+        expect(remote.getForPresign('us-west-2')).toBe(presign);
+        expect(remote.getForPresign('eu-central-1')).not.toBe(presign);
+    });
+
+    it('shares one client when the public endpoint matches the private one', async () => {
+        const endpoint = internals(local).awsConfig.endpoint;
+        remote = new S3Client(remoteConfig({ publicEndpoint: endpoint }));
+        await remote.onServerStart();
+
+        expect(remote.getForPresign('us-west-2')).toBe(remote.get('us-west-2'));
+    });
+
+    it('raises the upload thresholds when using the ambient credential chain', async () => {
+        remote = new S3Client({
+            port: 0,
+            extensions: [],
+            s3: { s3Config: { useCredentialChain: true } },
+        } as unknown as IConfig);
+        await remote.onServerStart();
+
+        expect(remote.partSize).toBe(64 * 1024 * 1024);
+        expect(remote.maxSingleUploadSize).toBe(128 * 1024 * 1024);
+    });
+});
+
+describe('S3Client — legacy storage migration', () => {
+    let client: S3Client;
+    let dir: string;
+
+    beforeEach(async () => {
+        client = await startLocal();
+        dir = mkdtempSync(join(tmpdir(), 'puter-s3-legacy-'));
+    });
+
+    afterEach(async () => {
+        rmSync(dir, { recursive: true, force: true });
+        await client.onServerShutdown();
+    });
+
+    it('does nothing when there is no legacy directory', async () => {
+        await expect(
+            internals(client).migrateLegacyStorage({
+                legacyPath: join(dir, 'absent'),
+            }),
+        ).resolves.toEqual({ migratedFileCount: 0, scannedEntryCount: 0 });
+    });
+
+    it('uploads each legacy file, skips directories, then removes the tree', async () => {
+        const small = 'small-file-contents';
+        writeFileSync(join(dir, 'small.txt'), small);
+        writeFileSync(join(dir, 'other.txt'), 'other');
+        mkdirSync(join(dir, 'a-subdirectory'));
+
+        await expect(
+            internals(client).migrateLegacyStorage({ legacyPath: dir }),
+        ).resolves.toEqual({ migratedFileCount: 2, scannedEntryCount: 3 });
+
+        await expect(objectBody(client, 'small.txt')).resolves.toBe(small);
+        await expect(objectBody(client, 'other.txt')).resolves.toBe('other');
+        expect(existsSync(dir)).toBe(false);
+    });
+
+    it('switches to a multipart upload for a file over the single-put limit', async () => {
+        // S3 requires every part but the last to be at least 5 MiB, so the
+        // fixture has to straddle that for real.
+        client.maxSingleUploadSize = 1024 * 1024;
+        client.partSize = 5 * 1024 * 1024;
+        const body = 'X'.repeat(6 * 1024 * 1024);
+        writeFileSync(join(dir, 'large.bin'), body);
+
+        await expect(
+            internals(client).migrateLegacyStorage({ legacyPath: dir }),
+        ).resolves.toEqual({ migratedFileCount: 1, scannedEntryCount: 1 });
+        await expect(objectBody(client, 'large.bin')).resolves.toBe(body);
+    });
+});
+
+describe('S3Client — multipart failure handling', () => {
+    let client: S3Client;
+    let dir: string;
+    let filePath: string;
+
+    beforeEach(async () => {
+        client = await startLocal();
+        dir = mkdtempSync(join(tmpdir(), 'puter-s3-multipart-'));
+        filePath = join(dir, 'part-source.bin');
+        writeFileSync(filePath, 'Y'.repeat(30));
+        client.partSize = 10;
+    });
+
+    afterEach(async () => {
+        rmSync(dir, { recursive: true, force: true });
+        await client.onServerShutdown();
+    });
+
+    const commandName = (command: unknown) =>
+        (command as { constructor: { name: string } }).constructor.name;
+
+    it('fails when the store will not open a multipart upload', async () => {
+        const send = vi.fn(async () => ({}));
+
+        await expect(
+            internals(client).uploadMultipart({
+                bucket: LOCAL_BUCKET,
+                client: { send },
+                filePath,
+                fileSize: 30,
+                key: 'no-upload-id',
+            }),
+        ).rejects.toThrow('Failed to start multipart upload');
+    });
+
+    it('aborts the upload when a part comes back without an ETag', async () => {
+        const sent: string[] = [];
+        const send = vi.fn(async (command: unknown) => {
+            const name = commandName(command);
+            sent.push(name);
+            if (name === 'CreateMultipartUploadCommand') {
+                return { UploadId: 'upload-1' };
+            }
+            if (name === 'UploadPartCommand') return {};
+            return {};
+        });
+
+        await expect(
+            internals(client).uploadMultipart({
+                bucket: LOCAL_BUCKET,
+                client: { send },
+                filePath,
+                fileSize: 30,
+                key: 'etag-less',
+            }),
+        ).rejects.toMatchObject({ statusCode: 400, legacyCode: 'bad_request' });
+
+        expect(sent).toEqual([
+            'CreateMultipartUploadCommand',
+            'UploadPartCommand',
+            'AbortMultipartUploadCommand',
+        ]);
+    });
+
+    it('sends one part per chunk and completes with every ETag', async () => {
+        const parts: { PartNumber: number; ContentLength: number }[] = [];
+        let completed: { ETag: string; PartNumber: number }[] | undefined;
+        const send = vi.fn(async (command: unknown) => {
+            const name = commandName(command);
+            const input = (command as { input: Record<string, unknown> }).input;
+            if (name === 'CreateMultipartUploadCommand') {
+                return { UploadId: 'upload-1' };
+            }
+            if (name === 'UploadPartCommand') {
+                parts.push({
+                    PartNumber: input.PartNumber as number,
+                    ContentLength: input.ContentLength as number,
+                });
+                return { ETag: `etag-${input.PartNumber}` };
+            }
+            if (name === 'CompleteMultipartUploadCommand') {
+                completed = (
+                    input.MultipartUpload as {
+                        Parts: { ETag: string; PartNumber: number }[];
+                    }
+                ).Parts;
+            }
+            return {};
+        });
+
+        client.partSize = 12;
+        await internals(client).uploadMultipart({
+            bucket: LOCAL_BUCKET,
+            client: { send },
+            filePath,
+            fileSize: 30,
+            key: 'chunked',
+        });
+
+        expect(parts).toEqual([
+            { PartNumber: 1, ContentLength: 12 },
+            { PartNumber: 2, ContentLength: 12 },
+            { PartNumber: 3, ContentLength: 6 },
+        ]);
+        expect(completed).toEqual([
+            { ETag: 'etag-1', PartNumber: 1 },
+            { ETag: 'etag-2', PartNumber: 2 },
+            { ETag: 'etag-3', PartNumber: 3 },
+        ]);
+    });
+
+    it('aborts and rethrows when completing the upload fails', async () => {
+        const sent: string[] = [];
+        const send = vi.fn(async (command: unknown) => {
+            const name = commandName(command);
+            sent.push(name);
+            if (name === 'CreateMultipartUploadCommand') {
+                return { UploadId: 'upload-1' };
+            }
+            if (name === 'UploadPartCommand') return { ETag: 'etag' };
+            if (name === 'CompleteMultipartUploadCommand') {
+                throw new Error('complete rejected');
+            }
+            return {};
+        });
+
+        await expect(
+            internals(client).uploadMultipart({
+                bucket: LOCAL_BUCKET,
+                client: { send },
+                filePath,
+                fileSize: 30,
+                key: 'incomplete',
+            }),
+        ).rejects.toThrow('complete rejected');
+
+        expect(sent.at(-1)).toBe('AbortMultipartUploadCommand');
+    });
+});
+
+describe('S3Client — disk-backed local store', () => {
+    let cwd: string;
+    let dir: string;
+    let client: S3Client | null = null;
+
+    beforeEach(() => {
+        cwd = process.cwd();
+        dir = mkdtempSync(join(tmpdir(), 'puter-s3-disk-'));
+    });
+
+    afterEach(async () => {
+        if (client) await client.onServerShutdown();
+        client = null;
+        process.chdir(cwd);
+        rmSync(dir, { recursive: true, force: true });
+    });
+
+    it('persists to the configured directories and drains legacy storage', async () => {
+        // The legacy sweep resolves `storage/` against the working
+        // directory, so the whole fixture lives in a throwaway cwd.
+        process.chdir(dir);
+        mkdirSync(join(dir, 'storage'));
+        writeFileSync(join(dir, 'storage', 'legacy.txt'), 'from-disk');
+
+        const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+        client = new S3Client({
+            port: 0,
+            extensions: [],
+            s3: {
+                localConfig: {
+                    host: '127.0.0.1',
+                    port: 0,
+                    dataDir: join(dir, 'fauxqs-data'),
+                    s3StorageDir: join(dir, 'fauxqs-s3'),
+                },
+            },
+        } as unknown as IConfig);
+        await client.onServerStart();
+
+        expect(log).toHaveBeenCalledWith(
+            '[s3] migrated 1 file(s) from legacy storage',
+        );
+        await expect(objectBody(client, 'legacy.txt')).resolves.toBe(
+            'from-disk',
+        );
+        expect(existsSync(join(dir, 'storage'))).toBe(false);
+        log.mockRestore();
+    });
+});
+
+describe('S3Client — short reads during multipart', () => {
+    let client: S3Client;
+    let dir: string;
+
+    beforeEach(async () => {
+        client = await startLocal();
+        dir = mkdtempSync(join(tmpdir(), 'puter-s3-short-'));
+    });
+
+    afterEach(async () => {
+        rmSync(dir, { recursive: true, force: true });
+        await client.onServerShutdown();
+    });
+
+    it('stops uploading parts once the file runs out early', async () => {
+        const filePath = join(dir, 'truncated.bin');
+        writeFileSync(filePath, 'Z'.repeat(20));
+        client.partSize = 10;
+
+        const parts: number[] = [];
+        const send = vi.fn(async (command: unknown) => {
+            const name = (command as { constructor: { name: string } })
+                .constructor.name;
+            const input = (command as { input: Record<string, unknown> }).input;
+            if (name === 'CreateMultipartUploadCommand') {
+                return { UploadId: 'upload-1' };
+            }
+            if (name === 'UploadPartCommand') {
+                parts.push(input.ContentLength as number);
+                return { ETag: `etag-${input.PartNumber}` };
+            }
+            return {};
+        });
+
+        // The caller's size is stale — the file is shorter than advertised.
+        await internals(client).uploadMultipart({
+            bucket: LOCAL_BUCKET,
+            client: { send },
+            filePath,
+            fileSize: 50,
+            key: 'truncated',
+        });
+
+        expect(parts).toEqual([10, 10]);
+    });
+});

src/backend/clients/s3/S3Client.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -21,6 +21,7 @@ import {
     AbortMultipartUploadCommand,
     CompleteMultipartUploadCommand,
     CreateMultipartUploadCommand,
+    HeadBucketCommand,
     PutObjectCommand,
     S3Client as AwsS3Client,
     type S3ClientConfig,
@@ -184,8 +185,8 @@ export class S3Client extends PuterClient {
     // ------------------------------------------------------------------
 
     /**
-     * Get (or create) an S3Client for the given region.
-     * Clients are cached per-region for connection reuse.
+     * Get (or create) an S3Client for the given region. Clients are cached
+     * per-region for connection reuse.
      */
     get(
         region = this.config.s3_region || this.config.region || 'us-west-2',
@@ -213,10 +214,10 @@ export class S3Client extends PuterClient {
 
     /**
      * Client used to generate browser-facing presigned URLs. When
-     * `s3Config.publicEndpoint` is set, this returns a client bound to
-     * that endpoint — its signatures resolve against the public host
-     * the browser will actually hit. When unset, falls back to the
-     * regular client (prod behavior: one public endpoint everywhere).
+     * `s3Config.publicEndpoint` is set, this returns a client bound to that
+     * endpoint — its signatures resolve against the public host the browser
+     * will actually hit. When unset, falls back to the regular client (prod
+     * behavior: one public endpoint everywhere).
      */
     getForPresign(
         region = this.config.s3_region || this.config.region || 'us-west-2',
@@ -244,6 +245,19 @@ export class S3Client extends PuterClient {
         return client;
     }
 
+    /**
+     * Cheapest round-trip that proves the object store answers for a bucket: no
+     * object data, no listing, just a HEAD. Throws on any failure (missing
+     * bucket, bad credentials, unreachable endpoint) so callers can treat it as
+     * a liveness probe. Reuses the pooled per-region client.
+     */
+    async headBucket(
+        bucket = this.config.s3_bucket || LEGACY_STORAGE_BUCKET,
+        region?: string,
+    ): Promise<void> {
+        await this.get(region).send(new HeadBucketCommand({ Bucket: bucket }));
+    }
+
     // ------------------------------------------------------------------
     // Legacy storage migration
     // ------------------------------------------------------------------

src/backend/clients/types.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -45,8 +45,8 @@ export interface IExtensionClientInstances {
     /**
      * Optional ClickHouse analytics client. Absent by default — a production
      * deployment registers it via an extension to speed up the app-stats path
-     * at scale (see {@link ClickhouseClient}). Always branch on its presence
-     * and fall back to SQL.
+     * at scale (see {@link ClickhouseClient}). Always branch on its presence and
+     * fall back to SQL.
      */
     clickhouse?: ClickhouseClient;
 }

src/backend/controllers/apps/AppController.js

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -31,15 +31,99 @@ import DEFAULT_APP_ICON from './default-app-icon.js';
 /**
  * REST endpoints for app management.
  *
- * Delegates to AppDriver for the actual CRUD + permission logic —
- * these routes are just thin shape adapters that translate REST
- * conventions into driver calls.
+ * Delegates to AppDriver for the actual CRUD + permission logic — these routes
+ * are just thin shape adapters that translate REST conventions into driver
+ * calls.
  */
+/**
+ * Desktop boot reads the app list and individual app records repeatedly, so the
+ * ceiling is set well above normal boot traffic and exists to catch a runaway
+ * client rather than to pace one.
+ *
+ * "Repeatedly" is the operative word: an app record is read on launch, on
+ * permission checks, and again by anything resolving an app by name, so these
+ * accumulate against whatever else a session is doing rather than arriving on
+ * their own. Sized for a session working hard, not for a person clicking.
+ */
+const APP_READ_LIMIT = {
+    scope: 'app-read',
+    limit: 1_800,
+    window: 60_000,
+    key: 'user',
+};
+
+/**
+ * Unauthenticated icon serving; no actor to key on, so the bucket is the
+ * address — and an address is a NAT, a campus or a carrier gateway that can
+ * hold hundreds of desktops. Each desktop boot pulls the taskbar's icons at
+ * once, so a single burst from one network is already thousands of requests.
+ * Responses are publicly cacheable and usually a redirect, so the ceiling is
+ * not protecting bandwidth; it is there so a client looping on a broken icon
+ * can't spin unbounded.
+ */
+const APP_ICON_LIMIT = {
+    scope: 'app-icon',
+    limit: 12_000,
+    window: 60_000,
+    key: 'ip',
+};
+
 export class AppController extends PuterController {
     get appStore() {
         return this.stores.app;
     }
 
+    // In-flight background app-open writes. Tracked only so tests and
+    // shutdown can wait for them — the request path never does.
+    #pendingOpenWrites = new Set();
+
+    /**
+     * Record an app open. `app_opens` is analytics: it backs the recent-apps
+     * list and the open counters, and no response field is derived from it. The
+     * client posts this without awaiting and updates its own recent list
+     * optimistically, so holding a response open for a primary write only added
+     * latency to the launch that write is measuring.
+     *
+     * Failures are logged, never surfaced — a dropped stat must not turn into a
+     * failed app open.
+     *
+     * @param {string} appUid
+     * @param {number} userId
+     * @returns {Promise<void>} Settles when the write and event emit finish
+     */
+    #recordAppOpen(appUid, userId) {
+        const ts = Math.floor(Date.now() / 1000);
+        const work = (async () => {
+            try {
+                await this.clients.db.write(
+                    'INSERT INTO `app_opens` (`app_uid`, `user_id`, `ts`) VALUES (?, ?, ?)',
+                    [appUid, userId, ts],
+                );
+            } catch (e) {
+                console.warn('[rao] insert failed:', e);
+            }
+
+            try {
+                this.clients.event?.emitAndWait(
+                    'app.opened',
+                    { app_uid: appUid, user_id: userId, ts },
+                    {},
+                );
+            } catch {
+                // event emission best-effort
+            }
+        })();
+
+        this.#pendingOpenWrites.add(work);
+        work.finally(() => this.#pendingOpenWrites.delete(work));
+        return work;
+    }
+
+    /** Await every in-flight app-open write. */
+    async drainPendingAppOpens() {
+        await Promise.allSettled([...this.#pendingOpenWrites]);
+    }
+
     get appDriver() {
         // Drivers are wired into the shared driversContainers export by
         // PuterServer at boot. Controllers get them lazily via this getter
@@ -49,7 +133,9 @@ export class AppController extends PuterController {
         return d;
     }
 
-    registerRoutes(router) {
+    registerRoutes(
+        /** @type {import('../../core/http/PuterRouter').PuterRouter} */ router,
+    ) {
         // GET /apps — list apps owned by the current user
         router.get(
             '/apps',
@@ -57,6 +143,7 @@ export class AppController extends PuterController {
                 subdomain: 'api',
                 requireUserActor: true,
                 allowFullAccessToken: true,
+                rateLimit: APP_READ_LIMIT,
             },
             async (req, res) => {
                 const apps = await this.appDriver.select({
@@ -71,8 +158,16 @@ export class AppController extends PuterController {
             '/apps/nameAvailable',
             {
                 subdomain: 'api',
-                requireUserActor: true,
-                allowFullAccessToken: true,
+                requireAuth: true,
+                // Answers "does this name exist?" for any name, so it is a
+                // name-enumeration oracle however cheap it is to serve.
+                // Mirrors the `isNameAvailable` budget on AppDriver.
+                rateLimit: {
+                    scope: 'app-name-available',
+                    limit: 60,
+                    window: 60_000,
+                    key: 'user',
+                },
             },
             async (req, res) => {
                 const name = req.query?.name;
@@ -107,6 +202,7 @@ export class AppController extends PuterController {
             {
                 subdomain: 'api',
                 requireAuth: true,
+                rateLimit: APP_READ_LIMIT,
             },
             async (req, res) => {
                 const actor = req.actor;
@@ -148,33 +244,10 @@ export class AppController extends PuterController {
                         legacyCode: 'not_found',
                     });
 
-                // Persist open record
-                try {
-                    await this.clients.db.write(
-                        'INSERT INTO `app_opens` (`app_uid`, `user_id`, `ts`) VALUES (?, ?, ?)',
-                        [
-                            app_uid,
-                            req.actor.user.id,
-                            Math.floor(Date.now() / 1000),
-                        ],
-                    );
-                } catch (e) {
-                    console.warn('[rao] insert failed:', e);
-                }
-
-                try {
-                    this.clients.event?.emitAndWait(
-                        'app.opened',
-                        {
-                            app_uid,
-                            user_id: req.actor.user.id,
-                            ts: Math.floor(Date.now() / 1000),
-                        },
-                        {},
-                    );
-                } catch {
-                    // event emission best-effort
-                }
+                // Validation and authorization are settled by this point, so
+                // the caller learns the outcome now and the stats write lands
+                // on its own. See `#recordAppOpen`.
+                this.#recordAppOpen(app_uid, req.actor.user.id);
 
                 res.json({});
             },
@@ -188,6 +261,7 @@ export class AppController extends PuterController {
                 subdomain: 'api',
                 requireUserActor: true,
                 allowFullAccessToken: true,
+                rateLimit: APP_READ_LIMIT,
             },
             async (req, res) => {
                 const raw = req.params.name;
@@ -214,7 +288,13 @@ export class AppController extends PuterController {
                             source: 'appsRoute',
                             args: req.query ?? {},
                         });
-                        return { ...shaped, privateAccess };
+                        return {
+                            ...shaped,
+                            privateAccess:
+                                shaped.privateAccess?.hasAccess === false
+                                    ? shaped.privateAccess
+                                    : privateAccess,
+                        };
                     }),
                 );
 
@@ -255,6 +335,7 @@ export class AppController extends PuterController {
             {
                 subdomain: 'api',
                 requireAuth: true,
+                rateLimit: APP_READ_LIMIT,
             },
             async (req, res) => {
                 const appList = Array.isArray(req.body) ? req.body : [];
@@ -437,7 +518,11 @@ export class AppController extends PuterController {
                 }
                 setIconSecurityHeaders(res);
                 res.set('Content-Type', mime);
-                res.set('Cache-Control', 'public, max-age=60');
+                // Same freshness as the redirect path above — this is the
+                // same resource, just served inline because no CDN file
+                // exists yet. A 60s TTL made every app launch re-fetch the
+                // icon over a connection the launch itself is competing for.
+                res.set('Cache-Control', 'public, max-age=900');
                 res.send(Buffer.from(icon.slice(commaIdx + 1), 'base64'));
 
                 // Trigger background generation so next request hits the CDN
@@ -459,15 +544,27 @@ export class AppController extends PuterController {
         // Icons are <img src> targets from the GUI (root) AND resolved via
         // api_base_url in taskbar payloads. Register on both so either origin
         // works without a cross-subdomain redirect.
-        router.get('/app-icon/:app_uid', { subdomain: ['api', ''] }, serveIcon);
+        router.get(
+            '/app-icon/:app_uid',
+            { subdomain: ['api', ''], rateLimit: APP_ICON_LIMIT },
+            serveIcon,
+        );
         router.get(
             '/app-icon/:app_uid/:size',
-            { subdomain: ['api', ''] },
+            { subdomain: ['api', ''], rateLimit: APP_ICON_LIMIT },
             serveIcon,
         );
     }
 
     onServerStart() {}
-    onServerPrepareShutdown() {}
+    /**
+     * Let outstanding stats writes finish before the process goes away —
+     * otherwise a deploy silently drops every open recorded in the seconds
+     * before it.
+     */
+    async onServerPrepareShutdown() {
+        await this.drainPendingAppOpens();
+    }
+
     onServerShutdown() {}
 }

src/backend/controllers/apps/AppController.test.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -91,6 +91,11 @@ const uniqueName = (prefix: string) =>
 const uniqueIndexUrl = () =>
     `https://example-${Math.random().toString(36).slice(2, 10)}.test/`;
 
+// 1x1 transparent PNG. The `icon` write path validates the decoded payload,
+// not just the declared MIME, so icon fixtures must be real images.
+const MINIMAL_PNG_BASE64 =
+    'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=';
+
 const createApp = async (
     actor: Actor,
     overrides: Record<string, unknown> = {},
@@ -285,12 +290,7 @@ describe('AppController POST /rao', () => {
         const { res } = makeRes();
         await expect(
             withActor(actor, () =>
-                callRoute(
-                    'post',
-                    '/rao',
-                    makeReq({ body: {}, actor }),
-                    res,
-                ),
+                callRoute('post', '/rao', makeReq({ body: {}, actor }), res),
             ),
         ).rejects.toMatchObject({ statusCode: 400 });
     });
@@ -328,6 +328,9 @@ describe('AppController POST /rao', () => {
         );
         expect(captured.body).toEqual({});
 
+        // The stats write is deliberately not awaited by the request.
+        await server.controllers.apps.drainPendingAppOpens();
+
         const rows = (await server.clients.db.read(
             'SELECT `app_uid`, `user_id` FROM `app_opens` WHERE `app_uid` = ? AND `user_id` = ?',
             [app.uid, owner.userId],
@@ -335,6 +338,74 @@ describe('AppController POST /rao', () => {
         expect(rows).toHaveLength(1);
     });
 
+    // `app_opens` is analytics: the response carries nothing derived from it
+    // and the client never awaits the post. Holding the response open for a
+    // primary write put that write's latency inside the app launch it was
+    // measuring, on a connection the launch was competing for.
+    it('responds without waiting for the stats write', async () => {
+        const owner = await makeUser();
+        const app = await createApp(owner.actor);
+
+        let releaseWrite = () => {};
+        const writeSpy = vi
+            .spyOn(server.clients.db, 'write')
+            .mockImplementation(
+                () =>
+                    new Promise((resolve) => {
+                        releaseWrite = () => resolve(undefined as never);
+                    }),
+            );
+
+        try {
+            const { res, captured } = makeRes();
+            await withActor(owner.actor, () =>
+                callRoute(
+                    'post',
+                    '/rao',
+                    makeReq({ body: { app_uid: app.uid }, actor: owner.actor }),
+                    res,
+                ),
+            );
+
+            // The handler returned while the INSERT is still outstanding.
+            expect(captured.body).toEqual({});
+            expect(writeSpy).toHaveBeenCalled();
+        } finally {
+            releaseWrite();
+            await server.controllers.apps.drainPendingAppOpens();
+            writeSpy.mockRestore();
+        }
+    });
+
+    // A stats failure must never turn into a failed app open — and since the
+    // write is now unawaited, it must not surface as an unhandled rejection.
+    it('swallows a failing stats write without rejecting the request', async () => {
+        const owner = await makeUser();
+        const app = await createApp(owner.actor);
+
+        const writeSpy = vi
+            .spyOn(server.clients.db, 'write')
+            .mockRejectedValue(new Error('primary is down'));
+
+        try {
+            const { res, captured } = makeRes();
+            await withActor(owner.actor, () =>
+                callRoute(
+                    'post',
+                    '/rao',
+                    makeReq({ body: { app_uid: app.uid }, actor: owner.actor }),
+                    res,
+                ),
+            );
+            expect(captured.body).toEqual({});
+            await expect(
+                server.controllers.apps.drainPendingAppOpens(),
+            ).resolves.toBeUndefined();
+        } finally {
+            writeSpy.mockRestore();
+        }
+    });
+
     it('falls back to actor.app.uid when the body omits app_uid', async () => {
         const owner = await makeUser();
         const app = await createApp(owner.actor);
@@ -354,6 +425,8 @@ describe('AppController POST /rao', () => {
         );
         expect(captured.body).toEqual({});
 
+        await server.controllers.apps.drainPendingAppOpens();
+
         const rows = (await server.clients.db.read(
             'SELECT `app_uid` FROM `app_opens` WHERE `app_uid` = ? AND `user_id` = ?',
             [app.uid, owner.userId],
@@ -427,6 +500,73 @@ describe('AppController GET /apps/:name', () => {
         expect((arr[0] as Record<string, unknown>).uid).toBe(app.uid);
         expect(arr[1]).toBeNull();
     });
+
+    // The driver is the authoritative producer of launch metadata: it runs
+    // the hosted-subdomain guard, which this route knows nothing about. The
+    // route's own entitlement re-check must never turn that denial into an
+    // affirmative verdict — the GUI launcher appends `puter.auth.token` to
+    // whatever `index_url` it is handed.
+
+    it('preserves the hosted-backing denial for the app owner', async () => {
+        const owner = await makeUser();
+        const sub = uniqueName('gone');
+        const row = await server.stores.subdomain.create({
+            userId: owner.userId,
+            subdomain: sub,
+        });
+        const app = await createApp(owner.actor, {
+            index_url: `https://${sub}.site.puter.localhost/`,
+        });
+        await server.stores.subdomain.deleteByUuid(
+            String((row as { uuid: string }).uuid),
+            { userId: owner.userId },
+        );
+
+        const { res, captured } = makeRes();
+        await withActor(owner.actor, () =>
+            callRoute(
+                'get',
+                '/apps/:name',
+                makeReq({ params: { name: app.name }, actor: owner.actor }),
+                res,
+            ),
+        );
+        const body = captured.body as Record<string, unknown>;
+        expect(body.privateAccess).toMatchObject({
+            hasAccess: false,
+            reason: 'hosted_backing_unavailable',
+        });
+    });
+
+    it('omits the stale index_url for a non-owner', async () => {
+        const owner = await makeUser();
+        const stranger = await makeUser();
+        const sub = uniqueName('gone');
+        const row = await server.stores.subdomain.create({
+            userId: owner.userId,
+            subdomain: sub,
+        });
+        const app = await createApp(owner.actor, {
+            index_url: `https://${sub}.site.puter.localhost/`,
+        });
+        await server.stores.subdomain.deleteByUuid(
+            String((row as { uuid: string }).uuid),
+            { userId: owner.userId },
+        );
+
+        const { res, captured } = makeRes();
+        await withActor(stranger.actor, () =>
+            callRoute(
+                'get',
+                '/apps/:name',
+                makeReq({ params: { name: app.name }, actor: stranger.actor }),
+                res,
+            ),
+        );
+        const body = captured.body as Record<string, unknown>;
+        expect(body.index_url).toBeUndefined();
+        expect(body.privateAccess).toMatchObject({ hasAccess: false });
+    });
 });
 
 // ── POST /query/app ─────────────────────────────────────────────────
@@ -649,7 +789,9 @@ describe('AppController GET /app-icon/:app_uid', () => {
 
     it('decodes a data URL icon and serves the declared MIME', async () => {
         const owner = await makeUser();
-        const png = Buffer.from('mock-png-bytes');
+        // Real PNG bytes: the write path sniffs the decoded payload and
+        // rejects anything that isn't the image type it claims to be.
+        const png = Buffer.from(MINIMAL_PNG_BASE64, 'base64');
         const dataUrl = `data:image/png;base64,${png.toString('base64')}`;
         const app = await createApp(owner.actor, { icon: dataUrl });
 
@@ -666,6 +808,25 @@ describe('AppController GET /app-icon/:app_uid', () => {
         expect((captured.body as Buffer).equals(png)).toBe(true);
     });
 
+    // Icons are fetched on every app launch, over a connection the launch is
+    // already competing for. The inline path must not be cached more briefly
+    // than the redirect path that serves the same resource.
+    it('caches an inline data-URL icon as long as the redirect path', async () => {
+        const owner = await makeUser();
+        const dataUrl = `data:image/png;base64,${MINIMAL_PNG_BASE64}`;
+        const app = await createApp(owner.actor, { icon: dataUrl });
+
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/app-icon/:app_uid',
+            makeReq({ params: { app_uid: app.uid } }),
+            res,
+        );
+
+        expect(captured.headers['cache-control']).toBe('public, max-age=900');
+    });
+
     it('falls back to the default icon when the data-URL MIME is not allowlisted', async () => {
         const owner = await makeUser();
         // text/html is NOT in the icon allowlist — must NOT be echoed back.
@@ -707,3 +868,175 @@ describe('AppController GET /app-icon/:app_uid', () => {
         expect(captured.statusCode).toBe(200);
     });
 });
+
+// ── /rao actor gating ───────────────────────────────────────────────
+
+describe('AppController POST /rao actor gating', () => {
+    it('refuses to record an open for a scoped access token', async () => {
+        const { actor } = await makeUser();
+        const app = await createApp(actor);
+        // Shared / scoped credentials must not drive analytics counters.
+        const tokenActor = {
+            ...actor,
+            accessToken: { uuid: uuidv4(), permissions: [] },
+        } as unknown as Actor;
+
+        const { res } = makeRes();
+        await expect(
+            withActor(tokenActor, () =>
+                callRoute(
+                    'post',
+                    '/rao',
+                    makeReq({
+                        body: { app_uid: app.uid },
+                        actor: tokenActor,
+                    }),
+                    res,
+                ),
+            ),
+        ).rejects.toMatchObject({ statusCode: 403, legacyCode: 'forbidden' });
+    });
+
+    it("refuses to let an app actor record another app's open", async () => {
+        const { actor } = await makeUser();
+        const own = await createApp(actor);
+        const other = await createApp(actor);
+        const appActor = {
+            ...actor,
+            app: { uid: own.uid as string },
+        } as unknown as Actor;
+
+        const { res } = makeRes();
+        await expect(
+            withActor(appActor, () =>
+                callRoute(
+                    'post',
+                    '/rao',
+                    makeReq({
+                        body: { app_uid: other.uid },
+                        actor: appActor,
+                    }),
+                    res,
+                ),
+            ),
+        ).rejects.toMatchObject({ statusCode: 403, legacyCode: 'forbidden' });
+    });
+});
+
+// ── app-icon redirect + fallback paths ──────────────────────────────
+
+describe('AppController GET /app-icon remote icons', () => {
+    // AppDriver.create validates the `icon` column, so these fixtures write
+    // it straight to the row. AppStore caches by uid — drop that entry or the
+    // handler reads the pre-update app back.
+    const setIcon = async (uid: string, icon: string) => {
+        await server.clients.db.write(
+            'UPDATE `apps` SET `icon` = ? WHERE `uid` = ?',
+            [icon, uid],
+        );
+        await server.stores.app.invalidateByUid(uid);
+    };
+
+    it('redirects to an icon hosted on a trusted host', async () => {
+        const owner = await makeUser();
+        const app = await createApp(owner.actor);
+        const { static_hosting_domain: hostingDomain } = (
+            server.controllers.apps as unknown as {
+                config: { static_hosting_domain: string };
+            }
+        ).config;
+        const trusted = `https://puter-app-icons.${hostingDomain}/${app.uid}-128.png`;
+        await setIcon(String(app.uid), trusted);
+
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/app-icon/:app_uid',
+            makeReq({ params: { app_uid: app.uid } }),
+            res,
+        );
+        expect(captured.redirectStatus).toBe(302);
+        expect(captured.redirectUrl).toBe(trusted);
+        expect(captured.headers['cache-control']).toBe('public, max-age=900');
+    });
+
+    it('never redirects to an icon URL on an untrusted host', async () => {
+        const owner = await makeUser();
+        const app = await createApp(owner.actor);
+        // An open redirect here would let an app row point browsers anywhere.
+        await setIcon(String(app.uid), 'https://evil.example.com/icon.png');
+
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/app-icon/:app_uid',
+            makeReq({ params: { app_uid: app.uid } }),
+            res,
+        );
+        expect(captured.redirectUrl).toBeUndefined();
+        expect(captured.headers['content-type']).toContain('image/svg+xml');
+    });
+
+    it('serves the default icon for a malformed data URL with no comma', async () => {
+        const owner = await makeUser();
+        const app = await createApp(owner.actor);
+        await setIcon(String(app.uid), 'data:image/png;base64');
+
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/app-icon/:app_uid',
+            makeReq({ params: { app_uid: app.uid } }),
+            res,
+        );
+        expect(captured.headers['content-type']).toContain('image/svg+xml');
+    });
+
+    it('serves the default icon for an unknown app uid', async () => {
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/app-icon/:app_uid',
+            makeReq({ params: { app_uid: `app-${uuidv4()}` } }),
+            res,
+        );
+        expect(captured.headers['content-type']).toContain('image/svg+xml');
+    });
+
+    it('serves the default icon for a bare (non-URL, non-data) icon value', async () => {
+        const owner = await makeUser();
+        const app = await createApp(owner.actor);
+        await setIcon(String(app.uid), 'legacy-icon-name.png');
+
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/app-icon/:app_uid/:size',
+            makeReq({ params: { app_uid: app.uid, size: '64' } }),
+            res,
+        );
+        expect(captured.headers['content-type']).toContain('image/svg+xml');
+    });
+});
+
+// ── app-icon rate limit ─────────────────────────────────────────────
+
+describe('AppController app-icon rate limit', () => {
+    it('sizes the icon bucket for a whole network rather than one desktop', () => {
+        // Icons are unauthenticated `<img src>` targets, so the only key is
+        // the address — which one NAT shares across every desktop behind it,
+        // and each boot pulls the taskbar's icons in a burst.
+        for (const path of ['/app-icon/:app_uid', '/app-icon/:app_uid/:size']) {
+            const route = router.routes.find(
+                (r) => r.method === 'get' && r.path === path,
+            );
+            if (!route) throw new Error(`No GET ${path} route`);
+            expect(route.options.rateLimit).toEqual({
+                scope: 'app-icon',
+                limit: 12_000,
+                window: 60_000,
+                key: 'ip',
+            });
+        }
+    });
+});

src/backend/controllers/apps/default-app-icon.js

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.

src/backend/controllers/auth/authOriginGating.test.ts

@@ -0,0 +1,103 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/**
+ * Wiring test for `guiOriginOnly`.
+ *
+ * `originGate.test.ts` covers what the gate decides. This covers that the
+ * routes which hand a session credential back to the caller actually opt into
+ * it — a correct gate wired to nothing protects nothing, and the failure is
+ * invisible (the route keeps working, just for everybody).
+ */
+
+import { describe, expect, it } from 'vitest';
+import { AuthController } from './AuthController.js';
+import {
+    ROUTES_METADATA_KEY,
+    type CollectedRoute,
+} from '../../core/http/types.js';
+
+// The decorators register on the prototype via `addInitializer`, which only
+// runs once an instance exists. We never start this one — constructing it is
+// enough to populate the route metadata.
+const collectRoutes = (): CollectedRoute[] => {
+    const proto = AuthController.prototype as unknown as Record<
+        string,
+        CollectedRoute[] | undefined
+    >;
+    if (!proto[ROUTES_METADATA_KEY]) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        new (AuthController as any)({}, {}, {}, {}, {});
+    }
+    return proto[ROUTES_METADATA_KEY] ?? [];
+};
+
+/**
+ * Every route that answers with a usable session credential. Adding one here
+ * without `guiOriginOnly` is the mistake this test exists to catch: reflected
+ * CORS would let any page read the credential out of the response.
+ */
+const CREDENTIAL_ROUTES: Array<[method: string, path: string]> = [
+    ['post', '/login'],
+    ['post', '/login/otp'],
+    ['post', '/login/recovery-code'],
+    ['post', '/signup'],
+    ['get', '/session/sync-cookie'],
+];
+
+describe('guiOriginOnly wiring on AuthController', () => {
+    const routes = collectRoutes();
+
+    it('registers the routes under test at all (guards against a rename)', () => {
+        for (const [method, path] of CREDENTIAL_ROUTES) {
+            const found = routes.find(
+                (r) => r.method === method && r.path === path,
+            );
+            expect(found, `${method.toUpperCase()} ${path} not registered`)
+                .toBeDefined();
+        }
+    });
+
+    it.each(CREDENTIAL_ROUTES)(
+        'gates %s %s to the GUI origin',
+        (method, path) => {
+            const route = routes.find(
+                (r) => r.method === method && r.path === path,
+            );
+            expect(route?.options.guiOriginOnly).toBe(true);
+        },
+    );
+
+    // The popup relay is the third-party sign-in path: `puter.auth.signIn()`
+    // polls `/login/wait` from whatever origin the app is served from, and
+    // `/login/set` is posted by the popup. Gating either to our own origin
+    // would break every third-party app, and neither needs it — the token
+    // they move is app-scoped, not a session.
+    it.each([
+        ['post', '/login/wait'],
+        ['post', '/login/set'],
+    ])('leaves %s %s open cross-origin', (method, path) => {
+        const route = routes.find(
+            (r) => r.method === method && r.path === path,
+        );
+        expect(route, `${method.toUpperCase()} ${path} not registered`)
+            .toBeDefined();
+        expect(route?.options.guiOriginOnly).toBeUndefined();
+    });
+});

src/backend/controllers/broadcast/BroadcastController.test.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.

src/backend/controllers/broadcast/BroadcastController.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -27,20 +27,19 @@ import { PuterController } from '../types.js';
  *
  * The route is intentionally a thin shell: parse the four custom
  * `X-Broadcast-*` headers, hand the raw body + parsed body off to
- * `BroadcastService.verifyAndEmit()`, and translate its structured
- * result into HTTP. All the cryptography, replay protection, and
- * event-bus dispatch live in the service so they're reusable from
- * tests / direct callers.
+ * `BroadcastService.verifyAndEmit()`, and translate its structured result into
+ * HTTP. All the cryptography, replay protection, and event-bus dispatch live in
+ * the service so they're reusable from tests / direct callers.
  *
- * Mounted with `subdomain: '*'` (any host) because peers reach the
- * webhook through the ALB DNS, not the public `api.<domain>` subdomain,
- * so the host header can be an internal ALB hostname rather than
- * `api.<domain>` or `<domain>`. Authentication is via the HMAC +
- * peer-id + nonce triple, not the host.
+ * Mounted with `subdomain: '*'` (any host) because peers reach the webhook
+ * through the ALB DNS, not the public `api.<domain>` subdomain, so the host
+ * header can be an internal ALB hostname rather than `api.<domain>` or
+ * `<domain>`. Authentication is via the HMAC + peer-id + nonce triple, not the
+ * host.
  *
- * `req.rawBody` is captured by the global JSON parser and is what the
- * HMAC verifies against — do NOT switch this route to a custom body
- * parser without preserving the raw bytes.
+ * `req.rawBody` is captured by the global JSON parser and is what the HMAC
+ * verifies against — do NOT switch this route to a custom body parser without
+ * preserving the raw bytes.
  */
 @Controller('/broadcast')
 export class BroadcastController extends PuterController {

src/backend/controllers/desktop/DesktopController.js

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -28,9 +28,23 @@ const ALLOWED_SORT_ORDER = ['asc', 'desc'];
  * Desktop/UI preference routes.
  *
  * Two categories:
- *   - User-level: desktop background, taskbar items (UserStore)
- *   - Folder-level: layout, sort_by/sort_order (fsentries table)
+ *
+ * - User-level: desktop background, taskbar items (UserStore)
+ * - Folder-level: layout, sort_by/sort_order (fsentries table)
  */
+/**
+ * Desktop preference writes — background, taskbar, layout, sort order. All four
+ * persist to the user row on every call, and the GUI fires them on direct user
+ * action, so a per-minute ceiling well above human speed is enough to catch a
+ * stuck client.
+ */
+const PREFERENCE_WRITE_LIMIT = {
+    scope: 'desktop-preference',
+    limit: 120,
+    window: 60_000,
+    key: 'user',
+};
+
 export class DesktopController extends PuterController {
     constructor(config, clients, stores, services) {
         super(config, clients, stores, services);
@@ -52,6 +66,7 @@ export class DesktopController extends PuterController {
                 subdomain: 'api',
                 requireUserActor: true,
                 allowFullAccessToken: true,
+                rateLimit: PREFERENCE_WRITE_LIMIT,
             },
             async (req, res) => {
                 const { url, color, fit } = req.body ?? {};
@@ -107,6 +122,7 @@ export class DesktopController extends PuterController {
                 subdomain: 'api',
                 requireUserActor: true,
                 allowFullAccessToken: true,
+                rateLimit: PREFERENCE_WRITE_LIMIT,
             },
             async (req, res) => {
                 const { items } = req.body ?? {};
@@ -133,6 +149,7 @@ export class DesktopController extends PuterController {
                 subdomain: 'api',
                 requireUserActor: true,
                 allowFullAccessToken: true,
+                rateLimit: PREFERENCE_WRITE_LIMIT,
             },
             async (req, res) => {
                 const { item_uid, item_path, layout } = req.body ?? {};
@@ -160,6 +177,7 @@ export class DesktopController extends PuterController {
                 subdomain: 'api',
                 requireUserActor: true,
                 allowFullAccessToken: true,
+                rateLimit: PREFERENCE_WRITE_LIMIT,
             },
             async (req, res) => {
                 const { item_uid, item_path, sort_by, sort_order } =
@@ -195,16 +213,15 @@ export class DesktopController extends PuterController {
     // -- Helpers ------------------------------------------------------
 
     /**
-     * Update columns on an actor-owned fsentry. Accepts either `item_uid`
-     * (fast path) or `item_path` (path lookups in FSEntryStore now have
-     * a recursive-CTE fallback for legacy rows with a NULL `path` column,
-     * so this works for old accounts too).
+     * Update columns on an actor-owned fsentry. Accepts either `item_uid` (fast
+     * path) or `item_path` (path lookups in FSEntryStore now have a
+     * recursive-CTE fallback for legacy rows with a NULL `path` column, so this
+     * works for old accounts too).
      *
-     * Ownership: `entry.user_id === actor.user.id`. Kept as added
-     * validation against bad paths — the previous "drop user_id entirely"
-     * theory turned out to be wrong (the actual legacy issue was NULL
-     * paths, not user_id drift), so this filter doesn't lock out old
-     * accounts in practice.
+     * Ownership: `entry.user_id === actor.user.id`. Kept as added validation
+     * against bad paths — the previous "drop user_id entirely" theory turned
+     * out to be wrong (the actual legacy issue was NULL paths, not user_id
+     * drift), so this filter doesn't lock out old accounts in practice.
      */
     async #updateFSEntry(actor, { item_uid, item_path }, patch) {
         if (!item_uid && !item_path) {

src/backend/controllers/desktop/DesktopController.test.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.

src/backend/controllers/drivers/DriverController.concurrent.test.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -124,9 +124,9 @@ const makeSyntheticDriver = () => ({
 
 const buildController = (driver: ReturnType<typeof makeSyntheticDriver>) => {
     // The controller reads `this.services?.permission` only when an actor
-    // is on the request; otherwise the services bag is unused. The
-    // alarm client is invoked on the rate-limit / concurrency rejection
-    // paths, so stub a no-op `create`.
+    // is on the request; otherwise the services bag is unused. The rejection
+    // paths no longer alarm, but other paths still reach the client, so keep
+    // a no-op `create` stubbed.
     const clients = { alarm: { create: () => {} } };
     return new DriverController(
         {} as any,

src/backend/controllers/drivers/DriverController.errors.test.ts

@@ -0,0 +1,437 @@
+/**
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/**
+ * Upstream-error translation and rate-limit rejection in `/drivers/call`.
+ *
+ * When a driver's upstream provider fails, the caller must see a stable Puter
+ * error code rather than a raw vendor payload. Each SDK reports its status
+ * differently (`status`, `response.status`, an AWS `$metadata` block, or only a
+ * message), so the controller sniffs all four — this suite pins the mapping for
+ * every shape and asserts the resulting `legacyCode` / `statusCode`, plus the
+ * `upstreamStatus` / `upstreamCode` diagnostic fields.
+ *
+ * The synthetic driver stands in for a provider-backed one: it is the input to
+ * the translation under test, and it lets a single controller instance cover
+ * every failure shape without real provider credentials.
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Readable, Writable } from 'node:stream';
+import type { Request, RequestHandler, Response } from 'express';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { DriverMethodLifecycleEvent } from '../../clients/event/types.js';
+import { runWithContext } from '../../core/context.js';
+import { configureRateLimit } from '../../core/http/middleware/rateLimit.js';
+import { DriverController } from './DriverController.js';
+
+// -- Harness ---------------------------------------------------------
+
+const captureCallHandler = (controller: DriverController): RequestHandler => {
+    let handler: RequestHandler | undefined;
+    const fakeRouter = {
+        post: (path: string, _opts: unknown, h: RequestHandler) => {
+            if (path === '/call') handler = h;
+            return fakeRouter;
+        },
+        get: () => fakeRouter,
+        use: () => fakeRouter,
+    };
+    controller.registerRoutes(fakeRouter as any);
+    if (!handler) throw new Error('failed to capture POST /call handler');
+    return handler;
+};
+
+// A real Writable so `result.stream.pipe(res)` behaves like the express
+// response it stands in for.
+class MockRes extends Writable {
+    statusCode = 200;
+    body: unknown;
+    headers: Record<string, string> = {};
+    chunks: Buffer[] = [];
+    override _write(
+        chunk: Buffer,
+        _enc: BufferEncoding,
+        cb: (e?: Error) => void,
+    ) {
+        this.chunks.push(Buffer.from(chunk));
+        cb();
+    }
+    status(code: number) {
+        this.statusCode = code;
+        return this;
+    }
+    json(body: unknown) {
+        this.body = body;
+        return this;
+    }
+    setHeader(k: string, v: string) {
+        this.headers[k.toLowerCase()] = v;
+        return this;
+    }
+}
+
+const makeReq = (body: Record<string, unknown>): Request =>
+    ({
+        body,
+        headers: {},
+        query: {},
+        ip: '127.0.0.1',
+        socket: { remoteAddress: '127.0.0.1' },
+    }) as unknown as Request;
+
+interface BuildOptions {
+    run?: () => unknown;
+    rateLimit?: unknown;
+    /**
+     * Rate-limit buckets are keyed by iface+method, so give tests that exercise
+     * limits their own namespace.
+     */
+    iface?: string;
+}
+
+/**
+ * Build a controller around one synthetic driver. No actor is attached, so the
+ * permission scan is skipped and the call reaches the driver method.
+ */
+const build = (opts: BuildOptions = {}) => {
+    const events: DriverMethodLifecycleEvent[] = [];
+    const eventClient = {
+        emitAndWait: vi.fn(async () => {}),
+        emit: vi.fn((_key: string, payload: unknown) => {
+            events.push(payload as DriverMethodLifecycleEvent);
+        }),
+        on: vi.fn(),
+    };
+    const alarms: Array<{ id: string; severity: string }> = [];
+    const iface = opts.iface ?? 'test-iface';
+    const driver = {
+        driverInterface: iface,
+        driverName: 'test-driver',
+        isDefault: true,
+        ...(opts.rateLimit ? { rateLimit: opts.rateLimit } : {}),
+        run:
+            opts.run ??
+            (() => {
+                throw new Error('no run configured');
+            }),
+    };
+    const controller = new DriverController(
+        {} as any,
+        {
+            event: eventClient,
+            alarm: {
+                create: (id: string, _t: string, _f: unknown, sev: string) => {
+                    alarms.push({ id, severity: sev });
+                },
+            },
+        } as any,
+        {} as any,
+        {} as any,
+        { testDriver: driver } as any,
+    );
+    return {
+        handler: captureCallHandler(controller),
+        events,
+        alarms,
+        driver,
+        iface,
+    };
+};
+
+const callWith = async (run: () => unknown) => {
+    const { handler, events } = build({ run });
+    const res = new MockRes();
+    const err = await runWithContext({}, () =>
+        handler(
+            makeReq({ interface: 'test-iface', method: 'run' }),
+            res as unknown as Response,
+            () => {},
+        ),
+    ).then(
+        () => null,
+        (e: unknown) => e,
+    );
+    return { err, res, events };
+};
+
+const throwing = (payload: unknown) => () => {
+    throw payload;
+};
+
+// -- Upstream status extraction --------------------------------------
+
+describe('DriverController upstream error translation', () => {
+    it('maps an upstream 429 to a Puter 429 with upstream_rate_limited', async () => {
+        const { err } = await callWith(
+            throwing(
+                Object.assign(new Error('slow down'), {
+                    status: 429,
+                    code: 'rate_limit_exceeded',
+                }),
+            ),
+        );
+        expect(err).toMatchObject({
+            statusCode: 429,
+            legacyCode: 'upstream_rate_limited',
+            message: 'slow down',
+            fields: {
+                upstreamStatus: 429,
+                upstreamCode: 'rate_limit_exceeded',
+            },
+        });
+    });
+
+    it('maps upstream 401 and 403 to a 500 upstream_auth_failed — never leaking auth state to the caller', async () => {
+        for (const status of [401, 403]) {
+            const { err } = await callWith(
+                throwing(Object.assign(new Error('bad key'), { status })),
+            );
+            expect(err).toMatchObject({
+                statusCode: 500,
+                legacyCode: 'upstream_auth_failed',
+                fields: { upstreamStatus: status },
+            });
+        }
+    });
+
+    it('maps any upstream 5xx to a 400 upstream_provider_unavailable with a generic message', async () => {
+        const { err } = await callWith(
+            throwing(
+                Object.assign(new Error('internal provider stack trace'), {
+                    status: 503,
+                }),
+            ),
+        );
+        expect(err).toMatchObject({
+            statusCode: 400,
+            legacyCode: 'upstream_provider_unavailable',
+            message: 'AI provider unavailable',
+            fields: { upstreamStatus: 503 },
+        });
+    });
+
+    it('maps a generic upstream 4xx to a 400 upstream_bad_request', async () => {
+        const { err } = await callWith(
+            throwing(
+                Object.assign(new Error('unsupported parameter'), {
+                    status: 422,
+                }),
+            ),
+        );
+        expect(err).toMatchObject({
+            statusCode: 400,
+            legacyCode: 'upstream_bad_request',
+            message: 'unsupported parameter',
+            fields: { upstreamStatus: 422 },
+        });
+    });
+
+    it('prefers the nested error.message and error.code over the top-level ones', async () => {
+        const { err } = await callWith(
+            throwing({
+                status: 400,
+                message: 'outer',
+                code: 'outer_code',
+                error: { message: 'inner detail', code: 'inner_code' },
+            }),
+        );
+        expect(err).toMatchObject({
+            legacyCode: 'upstream_bad_request',
+            message: 'inner detail',
+            fields: { upstreamStatus: 400, upstreamCode: 'inner_code' },
+        });
+    });
+
+    it('reads the status from statusCode when `status` is absent', async () => {
+        const { err } = await callWith(throwing({ statusCode: 429 }));
+        expect(err).toMatchObject({
+            statusCode: 429,
+            legacyCode: 'upstream_rate_limited',
+        });
+    });
+
+    it('reads the status from a nested response object (axios-style)', async () => {
+        const { err } = await callWith(
+            throwing({ response: { status: 429 }, message: 'axios rejected' }),
+        );
+        expect(err).toMatchObject({
+            statusCode: 429,
+            legacyCode: 'upstream_rate_limited',
+            fields: { upstreamStatus: 429 },
+        });
+    });
+
+    it('reads the status from an AWS $metadata block', async () => {
+        const { err } = await callWith(
+            throwing({
+                $metadata: { httpStatusCode: 400 },
+                message: 'ValidationException',
+            }),
+        );
+        expect(err).toMatchObject({
+            statusCode: 400,
+            legacyCode: 'upstream_bad_request',
+            fields: { upstreamStatus: 400 },
+        });
+    });
+
+    it('sniffs a status out of the message when nothing else carries one', async () => {
+        const { err } = await callWith(
+            throwing(new Error('Request failed with status code 422')),
+        );
+        expect(err).toMatchObject({
+            statusCode: 400,
+            legacyCode: 'upstream_bad_request',
+            fields: { upstreamStatus: 422 },
+        });
+    });
+
+    it('does not treat a bare 4xx-looking number in the message as a status', async () => {
+        const raw = new Error('the answer contained 404 rows');
+        const { err } = await callWith(throwing(raw));
+        // No status could be derived, so the original error passes through
+        // untranslated rather than being mislabelled.
+        expect(err).toBe(raw);
+    });
+
+    it('passes an HttpError from the driver straight through', async () => {
+        const { HttpError } = await import('../../core/http/HttpError.js');
+        const raw = new HttpError(404, 'no such key', {
+            legacyCode: 'not_found',
+        });
+        const { err } = await callWith(throwing(raw));
+        expect(err).toBe(raw);
+    });
+
+    it('passes non-object throwables through untouched', async () => {
+        const { err } = await callWith(throwing('a bare string'));
+        expect(err).toBe('a bare string');
+    });
+
+    it('passes an error with a sub-400 status through untranslated', async () => {
+        const raw = { status: 302, message: 'redirected' };
+        const { err } = await callWith(throwing(raw));
+        expect(err).toBe(raw);
+    });
+
+    it('emits the error lifecycle event with the original (untranslated) error', async () => {
+        const raw = Object.assign(new Error('provider down'), { status: 500 });
+        const { events, err } = await callWith(throwing(raw));
+
+        const errorEvent = events.find(
+            (e) => (e as { phase?: string }).phase === 'error',
+        ) as unknown as Record<string, unknown>;
+        expect(errorEvent).toBeDefined();
+        expect(errorEvent.iface).toBe('test-iface');
+        expect(errorEvent.method).toBe('run');
+        expect(errorEvent.driver).toBe('test-driver');
+        expect(errorEvent.error).toBe(raw);
+        expect(typeof errorEvent.durationMs).toBe('number');
+        // The caller still sees the translated error.
+        expect(err).toMatchObject({
+            legacyCode: 'upstream_provider_unavailable',
+        });
+    });
+});
+
+// -- Stream results --------------------------------------------------
+
+describe('DriverController stream responses', () => {
+    it('sets Transfer-Encoding: chunked for a chunked stream result', async () => {
+        const { handler } = build({
+            run: () => ({
+                dataType: 'stream',
+                content_type: 'audio/mpeg',
+                chunked: true,
+                stream: Readable.from(['a', 'b']),
+            }),
+        });
+        const res = new MockRes();
+
+        await runWithContext({}, () =>
+            handler(
+                makeReq({ interface: 'test-iface', method: 'run' }),
+                res as unknown as Response,
+                () => {},
+            ),
+        );
+
+        expect(res.headers['content-type']).toBe('audio/mpeg');
+        expect(res.headers['transfer-encoding']).toBe('chunked');
+        // A piped stream never produces a JSON body.
+        expect(res.body).toBeUndefined();
+    });
+
+    it('omits Transfer-Encoding for a non-chunked stream result', async () => {
+        const { handler } = build({
+            run: () => ({
+                dataType: 'stream',
+                content_type: 'audio/mpeg',
+                stream: Readable.from(['a']),
+            }),
+        });
+        const res = new MockRes();
+
+        await runWithContext({}, () =>
+            handler(
+                makeReq({ interface: 'test-iface', method: 'run' }),
+                res as unknown as Response,
+                () => {},
+            ),
+        );
+
+        expect(res.headers['content-type']).toBe('audio/mpeg');
+        expect('transfer-encoding' in res.headers).toBe(false);
+    });
+});
+
+// -- Rate limiting ---------------------------------------------------
+
+describe('DriverController per-method rate limiting', () => {
+    beforeEach(() => {
+        configureRateLimit({ disabled: false } as never);
+    });
+
+    it('answers 429 without alarming once the per-method budget is spent', async () => {
+        const { handler, alarms, iface } = build({
+            run: () => ({ ok: true }),
+            rateLimit: { default: { limit: 1, window: 60_000 } },
+            iface: 'rate-limited-iface',
+        });
+        const call = () =>
+            runWithContext({}, () =>
+                handler(
+                    makeReq({ interface: iface, method: 'run' }),
+                    new MockRes() as unknown as Response,
+                    () => {},
+                ),
+            );
+
+        await call();
+        await expect(call()).rejects.toMatchObject({
+            statusCode: 429,
+            legacyCode: 'too_many_requests',
+        });
+
+        // Spending your own budget is the limit working as designed, so it
+        // must not raise anything — the 429 is the whole signal.
+        expect(alarms).toEqual([]);
+    });
+});

src/backend/controllers/drivers/DriverController.test.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -158,11 +158,14 @@ interface MockRes {
     sentBody: string | undefined;
     contentType: string | undefined;
     pipedFrom: Readable | undefined;
+    listeners: Record<string, Array<() => void>>;
     status(code: number): MockRes;
     json(body: unknown): MockRes;
     setHeader(key: string, value: string): MockRes;
     type(t: string): MockRes;
     send(body: string): MockRes;
+    once(event: string, fn: () => void): MockRes;
+    emit(event: string): void;
 }
 const makeRes = (): MockRes => {
     const res: MockRes = {
@@ -172,6 +175,19 @@ const makeRes = (): MockRes => {
         sentBody: undefined,
         contentType: undefined,
         pipedFrom: undefined,
+        // `#handleCall` releases a driver's concurrency slot on `finish` /
+        // `close`, so the stub has to behave like an emitter for any driver
+        // that declares a `concurrent` policy.
+        listeners: {},
+        once(event: string, fn: () => void) {
+            (this.listeners[event] ??= []).push(fn);
+            return this;
+        },
+        emit(event: string) {
+            const fns = this.listeners[event] ?? [];
+            this.listeners[event] = [];
+            for (const fn of fns) fn();
+        },
         status(code: number) {
             this.statusCode = code;
             return this;
@@ -295,6 +311,157 @@ describe('DriverController.#handleCall (via captured router)', () => {
         ).rejects.toMatchObject({ statusCode: 404 });
     });
 
+    // A lifecycle hook *exists* on every driver (inherited from PuterDriver),
+    // so the old `typeof driver[method] === 'function'` dispatch would have
+    // invoked it. It must not be reachable over /drivers/call.
+    it.each([
+        'onServerStart',
+        'onServerShutdown',
+        'onServerPrepareShutdown',
+        'getReportedCosts',
+        'constructor',
+        'toString',
+    ])('rejects the framework method %s with 404', async (method) => {
+        const actor = await makeUserActor();
+        const req = makeReq({ interface: 'puter-kvstore', method }, actor);
+        await expect(
+            runWithContext({ actor }, () =>
+                routes['POST /call'](
+                    req,
+                    makeRes() as unknown as Response,
+                    () => {},
+                ),
+            ),
+        ).rejects.toMatchObject({ statusCode: 404 });
+    });
+
+    it('admits a bare session ("root" token) actor on the AI drivers', async () => {
+        // Privileged ("godmode") apps call AI with the user's own session
+        // token, so the AI drivers no longer set `noUserSession`: the
+        // session actor reaches the permission scan (403 forbidden — no
+        // perms granted) instead of the credential-shape rejection.
+        const actor = await makeUserActor();
+        const req = makeReq(
+            {
+                interface: 'puter-chat-completion',
+                method: 'complete',
+                args: { messages: [] },
+            },
+            actor,
+        );
+        await expect(
+            runWithContext({ actor }, () =>
+                routes['POST /call'](
+                    req,
+                    makeRes() as unknown as Response,
+                    () => {},
+                ),
+            ),
+        ).rejects.toMatchObject({
+            statusCode: 403,
+            legacyCode: 'forbidden',
+        });
+    });
+
+    it('admits app and access-token actors on the AI drivers (they fail later on permission, not credential shape)', async () => {
+        const base = await makeUserActor();
+        const delegatedActors: Actor[] = [
+            { ...base, app: { uid: `app-${uuidv4()}` } },
+            {
+                ...base,
+                accessToken: {
+                    uid: `tok-${uuidv4()}`,
+                    issuer: base,
+                    fullAccess: true,
+                },
+            },
+        ];
+        for (const actor of delegatedActors) {
+            const req = makeReq(
+                {
+                    interface: 'puter-chat-completion',
+                    method: 'complete',
+                    args: { messages: [] },
+                },
+                actor,
+            );
+            await expect(
+                runWithContext({ actor }, () =>
+                    routes['POST /call'](
+                        req,
+                        makeRes() as unknown as Response,
+                        () => {},
+                    ),
+                ),
+            ).rejects.toMatchObject({
+                statusCode: 403,
+                // Fresh actors hold no service:* perms, so the call still
+                // 403s — but at the permission scan, proving the
+                // credential-shape gate let the delegated actor through.
+                legacyCode: 'forbidden',
+            });
+        }
+    });
+
+    it('admits a user-scoped worker session on the AI drivers', async () => {
+        // Workers deployed without an app binding authenticate as a user
+        // actor whose session row is kind='worker' — they must keep their
+        // AI access (they fail later on permission here, not on
+        // credential shape).
+        const base = await makeUserActor();
+        const actor: Actor = {
+            ...base,
+            session: { uid: `sess-${uuidv4()}`, kind: 'worker' },
+        };
+        const req = makeReq(
+            {
+                interface: 'puter-chat-completion',
+                method: 'complete',
+                args: { messages: [] },
+            },
+            actor,
+        );
+        await expect(
+            runWithContext({ actor }, () =>
+                routes['POST /call'](
+                    req,
+                    makeRes() as unknown as Response,
+                    () => {},
+                ),
+            ),
+        ).rejects.toMatchObject({
+            statusCode: 403,
+            legacyCode: 'forbidden',
+        });
+    });
+
+    it('still allows bare session actors on drivers without the noUserSession flag', async () => {
+        // puter-kvstore doesn't set the flag; the session actor reaches
+        // the permission scan (403 forbidden — no perms granted) instead
+        // of being rejected for its credential shape.
+        const actor = await makeUserActor();
+        const req = makeReq(
+            {
+                interface: 'puter-kvstore',
+                method: 'set',
+                args: { key: 'x', value: 'y' },
+            },
+            actor,
+        );
+        await expect(
+            runWithContext({ actor }, () =>
+                routes['POST /call'](
+                    req,
+                    makeRes() as unknown as Response,
+                    () => {},
+                ),
+            ),
+        ).rejects.toMatchObject({
+            statusCode: 403,
+            legacyCode: 'forbidden',
+        });
+    });
+
     it('rejects with 403 when the actor lacks the service permission', async () => {
         // A fresh user has no service:* perms → permission.check returns
         // false → 403.

src/backend/controllers/drivers/DriverController.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -17,11 +17,13 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+import { metrics } from '@opentelemetry/api';
 import type { Request, Response } from 'express';
 import { actorUid } from '../../core/actor.js';
 import { Context } from '../../core/context.js';
 import { Controller } from '../../core/http/decorators.js';
 import { HttpError, isHttpError } from '../../core/http/HttpError.js';
+import { assertNotUserSession } from '../../core/http/middleware/gates.js';
 import {
     acquireDriverConcurrent,
     checkDriverRateLimit,
@@ -30,6 +32,7 @@ import type { PuterRouter } from '../../core/http/PuterRouter.js';
 import type { DriverMeta } from '../../drivers/meta.js';
 import {
     isDriverStreamResult,
+    resolveCallableMethods,
     resolveDriverMeta,
     resolveDriverMethodConcurrent,
     resolveDriverMethodRateLimit,
@@ -42,6 +45,38 @@ import { PuterController } from '../types.js';
 
 type DriverInstance = WithLifecycle & Record<string, unknown>;
 
+/**
+ * Coarse envelope over the whole `/call` surface, so that spreading calls
+ * across many interfaces can't dodge every individual bucket. Per-driver limits
+ * are what actually shape traffic.
+ *
+ * "Coarse" is a constraint, not a description: for this to be an envelope it
+ * has to sit _above_ every per-driver budget, or it silently becomes the real
+ * limit for the widest ones and overrides the tier policy they declare.
+ * `driverPolicies.test.ts` asserts that ordering against every registered
+ * driver, so raising a driver's budget past this number fails there rather than
+ * in production. The headroom above the widest driver (notifications, at
+ * 3000/30s) is what leaves room for one caller to be busy on two interfaces at
+ * once.
+ */
+export const DRIVERS_CALL_LIMIT = {
+    scope: 'drivers-call',
+    limit: 8000,
+    window: 60_000,
+    key: 'user' as const,
+};
+
+// Every driver call is timed here already, for the lifecycle events below.
+// Recording the same number as a histogram makes the per-interface latency
+// distribution available downstream; which interfaces are worth keeping is a
+// collector-side decision, not one made here, so this deliberately records
+// everything and lets the export pipeline drop what it doesn't want.
+const meter = metrics.getMeter('puter-backend');
+const driverCallDuration = meter.createHistogram('driver.call.duration', {
+    description: 'Wall time of a driver method call',
+    unit: 'ms',
+});
+
 const extractUpstreamStatus = (e: {
     status?: number;
     statusCode?: number;
@@ -114,15 +149,23 @@ const translateProviderError = (err: unknown): unknown => {
 
 @Controller('/drivers')
 export class DriverController extends PuterController {
-    /** iface → Map<driverName, driverInstance> */
+    /** Iface → Map<driverName, driverInstance> */
     #drivers = new Map<string, Map<string, DriverInstance>>();
-    /** iface → default driver name */
+    /** Iface → default driver name */
     #defaults = new Map<string, string>();
     /**
-     * driver instance → resolved meta. Cached so the per-call rate-limit
-     * lookup doesn't have to walk prototype chains on every request.
+     * Driver instance → resolved meta. Cached so the per-call rate-limit lookup
+     * doesn't have to walk prototype chains on every request.
      */
     #meta = new WeakMap<DriverInstance, DriverMeta>();
+    /**
+     * Driver instance → the set of method names callable via `/drivers/call`.
+     * Resolved once at registration (server startup) via
+     * `resolveCallableMethods`; the request path only does a `Set.has` lookup.
+     * This is what stops framework/lifecycle methods (`onServerStart`, etc.)
+     * and `Object.prototype` members from being invoked by remote callers.
+     */
+    #callableMethods = new WeakMap<DriverInstance, Set<string>>();
 
     constructor(...args: ConstructorParameters<typeof PuterController>) {
         super(...args);
@@ -158,12 +201,26 @@ export class DriverController extends PuterController {
     registerRoutes(router: PuterRouter): void {
         router.post(
             '/call',
-            { subdomain: 'api', requireAuth: true },
+            {
+                subdomain: 'api',
+                requireAuth: true,
+                rateLimit: DRIVERS_CALL_LIMIT,
+            },
             this.#handleCall,
         );
         router.get(
             '/list-interfaces',
-            { subdomain: 'api', requireAuth: true },
+            {
+                subdomain: 'api',
+                requireAuth: true,
+                // Static introspection output, read once at boot.
+                rateLimit: {
+                    scope: 'drivers-list-interfaces',
+                    limit: 60,
+                    window: 60_000,
+                    key: 'user',
+                },
+            },
             this.#handleListInterfaces,
         );
     }
@@ -201,14 +258,19 @@ export class DriverController extends PuterController {
             );
         }
 
-        const fn = driver[method];
-        if (typeof fn !== 'function') {
+        // Only methods in the pre-resolved callable set are dispatchable.
+        // This excludes framework/lifecycle hooks (onServerStart, etc.),
+        // inherited base methods, and Object.prototype members, none of
+        // which are part of any interface's RPC contract.
+        const callable = this.#callableMethods.get(driver);
+        if (!callable?.has(method)) {
             throw new HttpError(
                 404,
                 `Method '${method}' not found on driver '${ifaceName}'`,
                 { legacyCode: 'not_found' },
             );
         }
+        const fn = driver[method];
 
         // Resolve the concrete driver name for permission keys, falling
         // back through prototype metadata → instance field → requested name.
@@ -219,6 +281,20 @@ export class DriverController extends PuterController {
             requestedDriver ??
             'unknown';
 
+        const driverMeta = this.#meta.get(driver);
+
+        // Drivers flagged `noUserSession` refuse the bare
+        // account-session ("root") token: callers must present an app or
+        // worker token, or an API token minted from the dashboard. This is
+        // the per-driver counterpart of the `noUserSession` route option —
+        // `/drivers/call` is one shared route, so the flag has to live on
+        // the driver rather than in `RouteOptions`. Checked before the
+        // permission scan so a session-token caller always gets the
+        // credential-shape message, not a permission error.
+        if (driverMeta?.noUserSession) {
+            assertNotUserSession(req.actor);
+        }
+
         if (req.actor) {
             const permService = this.services.permission as unknown as
                 | PermissionService
@@ -257,7 +333,6 @@ export class DriverController extends PuterController {
         // — we hook `res.finish` / `res.close` for that so streamed
         // responses hold their slot until the stream drains, and aborted
         // requests still give the slot back.
-        const driverMeta = this.#meta.get(driver);
         const rateLimitSpec = resolveDriverMethodRateLimit(
             driverMeta?.rateLimit,
             method,
@@ -265,19 +340,8 @@ export class DriverController extends PuterController {
         if (
             !(await checkDriverRateLimit(req, ifaceName, method, rateLimitSpec))
         ) {
-            // De-dupe on (iface, method) so a hot loop across many users
-            // aggregates as occurrences on a single low-severity alarm
-            // instead of fanning out one per user.
-            this.clients.alarm.create(
-                `driver_rate_limit_hit:${ifaceName}:${method}`,
-                `Driver rate limit hit on ${ifaceName}:${method}`,
-                {
-                    iface: ifaceName,
-                    method,
-                    userUuid: req.actor?.user?.uuid,
-                },
-                'info',
-            );
+            // Deliberately unalarmed: a caller spending its own budget is
+            // the limit working, not an incident. The 429 is the signal.
             throw new HttpError(429, 'Too many requests.', {
                 legacyCode: 'too_many_requests',
             });
@@ -300,16 +364,8 @@ export class DriverController extends PuterController {
                 concurrentSpec,
             );
             if (!handle.ok) {
-                this.clients.alarm.create(
-                    `driver_concurrent_limit_hit:${ifaceName}:${method}`,
-                    `Driver concurrency limit hit on ${ifaceName}:${method}`,
-                    {
-                        iface: ifaceName,
-                        method,
-                        userUuid: req.actor?.user?.uuid,
-                    },
-                    'info',
-                );
+                // Unalarmed for the same reason as the rate-limit rejection
+                // above: hitting a declared cap is the cap doing its job.
                 throw new HttpError(429, 'Too many concurrent requests.', {
                     legacyCode: 'too_many_requests',
                 });
@@ -400,6 +456,11 @@ export class DriverController extends PuterController {
                 () => (fn as (...x: unknown[]) => any).call(driver, args),
             );
         } catch (e) {
+            driverCallDuration.record(Date.now() - startedAt, {
+                driver: ifaceName,
+                'driver.method': method,
+                outcome: 'error',
+            });
             this.clients.event?.emit(
                 `driver.${ifaceName}.${method}.error`,
                 {
@@ -417,6 +478,15 @@ export class DriverController extends PuterController {
             );
             throw translateProviderError(e);
         }
+
+        // Same window the span and the lifecycle events measure: for streamed
+        // results this is stream start, not stream drain. Worth remembering
+        // when reading AI latency — it is time-to-first-token, not total.
+        driverCallDuration.record(Date.now() - startedAt, {
+            driver: ifaceName,
+            'driver.method': method,
+            outcome: 'ok',
+        });
         this.clients.event?.emit(
             `driver.${ifaceName}.${method}.after`,
             {
@@ -499,10 +569,15 @@ export class DriverController extends PuterController {
         // Cache the resolved meta so the request hot-path can read the
         // per-method rate-limit spec without re-walking the prototype.
         this.#meta.set(instance, meta);
-        // Register each alias pointing at the same instance. Legacy puter-js
-        // calls that pass a provider id in the `driver` slot (e.g. the TTS
-        // module sends `aws-polly` / `openai-tts` / `elevenlabs-tts` instead
-        // of the unified `ai-tts`) resolve here; the handler sets
+        // Resolve the callable RPC surface once, at startup. The request
+        // path checks membership against this set instead of reflecting on
+        // the live instance, so lifecycle hooks / inherited framework
+        // methods can never be dispatched.
+        this.#callableMethods.set(instance, resolveCallableMethods(instance));
+        // Register each alias pointing at the same instance. Calls that pass
+        // a provider id in the `driver` slot (e.g. `aws-polly` or
+        // `openai-tts` instead of the unified `ai-tts`, as SDK bundles
+        // predating the unified drivers do) resolve here; the handler sets
         // Context.driverName to the alias so the method can route to the
         // right internal provider.
         for (const alias of meta.aliases) {

src/backend/controllers/feedback/AppFeedbackController.test.ts

@@ -0,0 +1,594 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import type { Request, RequestHandler, Response } from 'express';
+import {
+    afterAll,
+    afterEach,
+    beforeAll,
+    describe,
+    expect,
+    it,
+    vi,
+} from 'vitest';
+import { v4 as uuidv4 } from 'uuid';
+import type { Actor } from '../../core/actor.js';
+import { PuterRouter } from '../../core/http/PuterRouter.js';
+import { PuterServer } from '../../server.js';
+import { AppFeedbackService } from '../../services/feedback/AppFeedbackService.js';
+import { setupTestServer } from '../../testUtil.js';
+
+// Boots one real PuterServer (in-memory sqlite + mocked externals) and
+// registers AppFeedbackController's decorated routes onto a fresh
+// PuterRouter. Tests drive the captured handlers with stub req/res; the
+// stores/services underneath are the live wired ones, so rows land in the
+// real `app_feedback` table.
+
+let server: PuterServer;
+let router: PuterRouter;
+
+beforeAll(async () => {
+    server = await setupTestServer();
+    router = new PuterRouter();
+    server.controllers.appFeedback.registerRoutes(router);
+});
+
+afterAll(async () => {
+    await server?.shutdown();
+});
+
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+
+const makeUser = async (): Promise<{ actor: Actor; userId: number }> => {
+    const username = `fdbk-${Math.random().toString(36).slice(2, 10)}`;
+    const created = await server.stores.user.create({
+        username,
+        uuid: uuidv4(),
+        password: null,
+        email: `${username}@test.local`,
+        free_storage: 100 * 1024 * 1024,
+        requires_email_confirmation: false,
+    });
+    const refreshed = (await server.stores.user.getById(created.id))!;
+    return {
+        userId: refreshed.id,
+        actor: {
+            user: {
+                id: refreshed.id,
+                uuid: refreshed.uuid,
+                username: refreshed.username,
+                email: refreshed.email ?? null,
+                email_confirmed: true,
+            } as Actor['user'],
+        },
+    };
+};
+
+const makeApp = async (
+    ownerUserId: number,
+    opts: { feedbackEnabled?: boolean; indexUrl?: string; name?: string } = {},
+) => {
+    const name =
+        opts.name ?? `fdbk-app-${Math.random().toString(36).slice(2, 10)}`;
+    return await server.stores.app.create(
+        {
+            name,
+            title: `Feedback Test ${name}`,
+            index_url: opts.indexUrl ?? `https://${name}.example.com`,
+            ...(opts.feedbackEnabled ? { feedback_enabled: 1 } : {}),
+        },
+        { ownerUserId },
+    );
+};
+
+// Feedback is only offered when the deployment can deliver it (email
+// transport configured); most tests want that baseline without asserting
+// anything about the mail itself.
+const mockEmailConfigured = () =>
+    vi.spyOn(server.clients.email, 'isConfigured', 'get').mockReturnValue(
+        true,
+    );
+
+const confirmOwnerEmail = async (userId: number) => {
+    await server.clients.db.write(
+        'UPDATE `user` SET `email_confirmed` = ? WHERE `id` = ?',
+        [server.clients.db.booleanValue(true), userId],
+    );
+    const user = await server.stores.user.getById(userId);
+    if (user) await server.stores.user.invalidate(user);
+};
+
+const makeReq = (init: {
+    body?: unknown;
+    actor?: Actor;
+    query?: Record<string, unknown>;
+}): Request => {
+    return {
+        body: init.body ?? {},
+        query: init.query ?? {},
+        headers: {},
+        actor: init.actor,
+    } as unknown as Request;
+};
+
+const makeRes = () => {
+    const captured: { statusCode: number; body: unknown } = {
+        statusCode: 200,
+        body: undefined,
+    };
+    const res = {
+        json: vi.fn((value: unknown) => {
+            captured.body = value;
+            return res;
+        }),
+        status: vi.fn((code: number) => {
+            captured.statusCode = code;
+            return res;
+        }),
+    };
+    return { res: res as unknown as Response, captured };
+};
+
+const findRoute = (method: string, path: string) => {
+    const route = router.routes.find(
+        (r) => r.method === method && r.path === path,
+    );
+    if (!route) throw new Error(`No ${method.toUpperCase()} ${path} route`);
+    return route;
+};
+
+const callRoute = async (
+    method: string,
+    path: string,
+    req: Request,
+    res: Response,
+) => {
+    const handler: RequestHandler = findRoute(method, path).handler;
+    await handler(req, res, () => {
+        throw new Error('handler called next() unexpectedly');
+    });
+};
+
+const submit = (actor: Actor, body: unknown) => {
+    const { res, captured } = makeRes();
+    return callRoute('post', '/', makeReq({ body, actor }), res).then(
+        () => captured,
+    );
+};
+
+// ── Route gates ─────────────────────────────────────────────────────
+
+describe('AppFeedbackController route options', () => {
+    it('rejects app actors and cross-origin pages on submit', () => {
+        const { options } = findRoute('post', '/');
+        // requireUserActor is what makes feedback impossible to submit
+        // programmatically with an app token; guiOriginOnly keeps
+        // cross-origin browser pages out even with a leaked user token.
+        expect(options.requireUserActor).toBe(true);
+        expect(options.guiOriginOnly).toBe(true);
+    });
+
+    it('stacks a per-user budget with a per-IP backstop', () => {
+        const { options } = findRoute('post', '/');
+        const limits = options.rateLimit;
+        expect(Array.isArray(limits)).toBe(true);
+        const keys = (limits as Array<{ key?: unknown }>).map((l) => l.key);
+        expect(keys).toContain('user');
+        expect(keys).toContain('ip');
+    });
+
+    it('requires a user actor on the target pre-flight too', () => {
+        const { options } = findRoute('get', '/target');
+        expect(options.requireUserActor).toBe(true);
+    });
+});
+
+// ── GET /app-feedback/target ────────────────────────────────────────
+
+describe('AppFeedbackController GET /target', () => {
+    it('throws 400 when neither or both of app/origin are given', async () => {
+        const { actor } = await makeUser();
+        for (const query of [
+            {},
+            { app: 'x', origin: 'https://x.example.com' },
+        ]) {
+            const { res } = makeRes();
+            await expect(
+                callRoute('get', '/target', makeReq({ query, actor }), res),
+            ).rejects.toMatchObject({ statusCode: 400 });
+        }
+    });
+
+    it('reports enabled:false for an unknown app', async () => {
+        const { actor } = await makeUser();
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/target',
+            makeReq({ query: { app: 'no-such-app-xyz' }, actor }),
+            res,
+        );
+        expect(captured.body).toEqual({ enabled: false, app: null });
+    });
+
+    it('reports enabled:false for an app that has not opted in', async () => {
+        mockEmailConfigured();
+        const { userId: ownerId } = await makeUser();
+        const app = await makeApp(ownerId);
+        const { actor } = await makeUser();
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/target',
+            makeReq({ query: { app: app.name }, actor }),
+            res,
+        );
+        expect(captured.body).toMatchObject({ enabled: false });
+    });
+
+    it('reports enabled:true with canonical title/name for an opted-in app', async () => {
+        mockEmailConfigured();
+        const { userId: ownerId } = await makeUser();
+        const app = await makeApp(ownerId, { feedbackEnabled: true });
+        const { actor } = await makeUser();
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/target',
+            makeReq({ query: { app: app.uid }, actor }),
+            res,
+        );
+        expect(captured.body).toEqual({
+            enabled: true,
+            app: { name: app.name, title: app.title },
+        });
+    });
+
+    it('resolves an opted-in app whose name starts with "app-"', async () => {
+        mockEmailConfigured();
+        const { userId: ownerId } = await makeUser();
+        const name = `app-fdbk-${Math.random().toString(36).slice(2, 10)}`;
+        const app = await makeApp(ownerId, { feedbackEnabled: true, name });
+        const { actor } = await makeUser();
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/target',
+            makeReq({ query: { app: name }, actor }),
+            res,
+        );
+        expect(captured.body).toEqual({
+            enabled: true,
+            app: { name: app.name, title: app.title },
+        });
+    });
+
+    it('resolves an origin to the app whose index_url it matches', async () => {
+        mockEmailConfigured();
+        const { userId: ownerId } = await makeUser();
+        const app = await makeApp(ownerId, { feedbackEnabled: true });
+        const origin = new URL(app.index_url).origin;
+        const { actor } = await makeUser();
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/target',
+            makeReq({ query: { origin }, actor }),
+            res,
+        );
+        expect(captured.body).toEqual({
+            enabled: true,
+            app: { name: app.name, title: app.title },
+        });
+    });
+
+    it('reports enabled:false when the email transport is unconfigured', async () => {
+        // No mockEmailConfigured(): this is the self-hosted no-SMTP default.
+        // Feedback that can never be delivered must not be solicited.
+        const { userId: ownerId } = await makeUser();
+        const app = await makeApp(ownerId, { feedbackEnabled: true });
+        const { actor } = await makeUser();
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/target',
+            makeReq({ query: { app: app.name }, actor }),
+            res,
+        );
+        expect(captured.body).toMatchObject({ enabled: false });
+    });
+
+    it('reports enabled:false for an origin with no registered app', async () => {
+        const { actor } = await makeUser();
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/target',
+            makeReq({
+                query: { origin: 'https://nobody-registered.example.com' },
+                actor,
+            }),
+            res,
+        );
+        expect(captured.body).toEqual({ enabled: false, app: null });
+    });
+});
+
+// ── POST /app-feedback ──────────────────────────────────────────────
+
+describe('AppFeedbackController POST /', () => {
+    it('throws 400 when message is missing or not a string', async () => {
+        const { userId: ownerId } = await makeUser();
+        const app = await makeApp(ownerId, { feedbackEnabled: true });
+        const { actor } = await makeUser();
+        for (const message of [undefined, 12345, '']) {
+            await expect(
+                submit(actor, { app: app.name, message }),
+            ).rejects.toMatchObject({ statusCode: 400 });
+        }
+    });
+
+    it('throws 400 when both app and origin are given', async () => {
+        const { actor } = await makeUser();
+        await expect(
+            submit(actor, {
+                app: 'x',
+                origin: 'https://x.example.com',
+                message: 'hi',
+            }),
+        ).rejects.toMatchObject({ statusCode: 400 });
+    });
+
+    it('throws 400 when the origin exceeds the stored column size', async () => {
+        // source_origin is VARCHAR(2048) on MySQL/Postgres; a longer origin
+        // must be rejected up front, not fail (or silently truncate) at the
+        // INSERT after passing every other validation.
+        mockEmailConfigured();
+        const { userId: ownerId } = await makeUser();
+        const app = await makeApp(ownerId, { feedbackEnabled: true });
+        const origin = `${new URL(app.index_url).origin}/${'x'.repeat(2500)}`;
+        const { actor } = await makeUser();
+        await expect(
+            submit(actor, { origin, message: 'hi' }),
+        ).rejects.toMatchObject({ statusCode: 400 });
+    });
+
+    it('throws 403 feedback_not_enabled when the app has not opted in', async () => {
+        mockEmailConfigured();
+        const { userId: ownerId } = await makeUser();
+        const app = await makeApp(ownerId);
+        const { actor } = await makeUser();
+        await expect(
+            submit(actor, { app: app.name, message: 'hi there' }),
+        ).rejects.toMatchObject({
+            statusCode: 403,
+            legacyCode: 'feedback_not_enabled',
+        });
+    });
+
+    it('throws 403 for an unknown app and an unknown origin alike', async () => {
+        const { actor } = await makeUser();
+        await expect(
+            submit(actor, { app: 'no-such-app-xyz', message: 'hi' }),
+        ).rejects.toMatchObject({ statusCode: 403 });
+        await expect(
+            submit(actor, {
+                origin: 'https://nobody-registered.example.com',
+                message: 'hi',
+            }),
+        ).rejects.toMatchObject({ statusCode: 403 });
+    });
+
+    it('throws 403 feedback_not_enabled when the email transport is unconfigured', async () => {
+        // No mockEmailConfigured(): the opted-in app must still refuse — a
+        // stored row nothing can read, sold to the sender as delivered, is
+        // worse than an honest refusal.
+        const { userId: ownerId } = await makeUser();
+        const app = await makeApp(ownerId, { feedbackEnabled: true });
+        const { actor } = await makeUser();
+        await expect(
+            submit(actor, { app: app.name, message: 'into the void' }),
+        ).rejects.toMatchObject({
+            statusCode: 403,
+            legacyCode: 'feedback_not_enabled',
+        });
+    });
+
+    it('throws 400 when the message exceeds the length limit', async () => {
+        mockEmailConfigured();
+        const { userId: ownerId } = await makeUser();
+        const app = await makeApp(ownerId, { feedbackEnabled: true });
+        const { actor } = await makeUser();
+        await expect(
+            submit(actor, {
+                app: app.name,
+                message: 'x'.repeat(
+                    AppFeedbackService.MESSAGE_MAX_LENGTH + 1,
+                ),
+            }),
+        ).rejects.toMatchObject({ statusCode: 400 });
+    });
+
+    it('stores a normalized row and responds with an empty object', async () => {
+        mockEmailConfigured();
+        const { userId: ownerId } = await makeUser();
+        const app = await makeApp(ownerId, { feedbackEnabled: true });
+        const { actor, userId } = await makeUser();
+        const captured = await submit(actor, {
+            app: app.uid,
+            message: '  Great\r\napp!  ',
+            context: 'app',
+        });
+        expect(captured.body).toEqual({});
+
+        const rows = (await server.clients.db.read(
+            'SELECT * FROM `app_feedback` WHERE `user_id` = ?',
+            [userId],
+        )) as Array<Record<string, unknown>>;
+        expect(rows).toHaveLength(1);
+        expect(rows[0]).toMatchObject({
+            app_uid: app.uid,
+            message: 'Great\napp!',
+            source_env: 'app',
+            source_origin: null,
+        });
+        // Engine-agnostic reads: pg returns BIGINT as string and BOOLEAN as
+        // boolean, sqlite returns numbers for both.
+        expect(Number(rows[0].app_id)).toBe(app.id);
+        expect(Boolean(rows[0].email_sent)).toBe(false);
+        expect(typeof rows[0].uid).toBe('string');
+        expect(Number.isFinite(Number(rows[0].created_at))).toBe(true);
+    });
+
+    it('records the attested origin on web submissions', async () => {
+        mockEmailConfigured();
+        const { userId: ownerId } = await makeUser();
+        const app = await makeApp(ownerId, { feedbackEnabled: true });
+        const origin = new URL(app.index_url).origin;
+        const { actor, userId } = await makeUser();
+        await submit(actor, { origin, message: 'from the web', context: 'web' });
+
+        const rows = (await server.clients.db.read(
+            'SELECT `source_env`, `source_origin` FROM `app_feedback` WHERE `user_id` = ?',
+            [userId],
+        )) as Array<Record<string, unknown>>;
+        expect(rows).toHaveLength(1);
+        expect(rows[0]).toMatchObject({
+            source_env: 'web',
+            source_origin: origin,
+        });
+    });
+
+    it('enforces the per-user-per-app daily cap with 429', async () => {
+        mockEmailConfigured();
+        const { userId: ownerId } = await makeUser();
+        const app = await makeApp(ownerId, { feedbackEnabled: true });
+        const { actor, userId } = await makeUser();
+        const since = Math.floor(Date.now() / 1000);
+        for (let i = 0; i < AppFeedbackService.PER_USER_APP_DAILY_LIMIT; i++) {
+            await server.stores.appFeedback.create({
+                appId: app.id,
+                appUid: app.uid,
+                userId,
+                message: `seed ${i}`,
+            });
+        }
+        expect(
+            await server.stores.appFeedback.countByUserAndAppSince(
+                userId,
+                app.id,
+                since - 60,
+            ),
+        ).toBe(AppFeedbackService.PER_USER_APP_DAILY_LIMIT);
+        await expect(
+            submit(actor, { app: app.name, message: 'one too many' }),
+        ).rejects.toMatchObject({
+            statusCode: 429,
+            legacyCode: 'too_many_requests',
+        });
+    });
+
+    it('rolls back the stored row when a concurrent burst breaches the cap', async () => {
+        mockEmailConfigured();
+        const { userId: ownerId } = await makeUser();
+        const app = await makeApp(ownerId, { feedbackEnabled: true });
+        const { actor, userId } = await makeUser();
+        for (let i = 0; i < AppFeedbackService.PER_USER_APP_DAILY_LIMIT; i++) {
+            await server.stores.appFeedback.create({
+                appId: app.id,
+                appUid: app.uid,
+                userId,
+                message: `seed ${i}`,
+            });
+        }
+        // Simulate the losing side of the check-then-insert race: the
+        // pre-insert check reads a stale under-cap count; the post-insert
+        // recount (real implementation) sees the truth.
+        vi.spyOn(
+            server.stores.appFeedback,
+            'countByUserAndAppSince',
+        ).mockResolvedValueOnce(0);
+
+        await expect(
+            submit(actor, { app: app.name, message: 'raced past the cap' }),
+        ).rejects.toMatchObject({
+            statusCode: 429,
+            legacyCode: 'too_many_requests',
+        });
+
+        const rows = (await server.clients.db.read(
+            'SELECT COUNT(*) AS n FROM `app_feedback` WHERE `user_id` = ?',
+            [userId],
+        )) as Array<{ n: unknown }>;
+        expect(Number(rows[0]?.n)).toBe(
+            AppFeedbackService.PER_USER_APP_DAILY_LIMIT,
+        );
+    });
+
+    it('enforces the per-user daily cap across apps with 429', async () => {
+        mockEmailConfigured();
+        const { userId: ownerId } = await makeUser();
+        const target = await makeApp(ownerId, { feedbackEnabled: true });
+        const other = await makeApp(ownerId, { feedbackEnabled: true });
+        const { actor, userId } = await makeUser();
+        for (let i = 0; i < AppFeedbackService.PER_USER_DAILY_LIMIT; i++) {
+            await server.stores.appFeedback.create({
+                appId: other.id,
+                appUid: other.uid,
+                userId,
+                message: `seed ${i}`,
+            });
+        }
+        await expect(
+            submit(actor, { app: target.name, message: 'over the limit' }),
+        ).rejects.toMatchObject({ statusCode: 429 });
+    });
+});
+
+// ── Owner email delivery ────────────────────────────────────────────
+
+// Which submissions get emailed, and what the mail contains, is service
+// logic covered in AppFeedbackService.test.ts. What the controller owes the
+// caller is that mail trouble never becomes the sender's problem.
+describe('AppFeedbackController owner email', () => {
+    it('a failing email send never fails the request', async () => {
+        mockEmailConfigured();
+        vi.spyOn(server.clients.email, 'send').mockRejectedValue(
+            new Error('smtp down'),
+        );
+        const { userId: ownerId } = await makeUser();
+        await confirmOwnerEmail(ownerId);
+        const app = await makeApp(ownerId, { feedbackEnabled: true });
+        const { actor, userId } = await makeUser();
+
+        const captured = await submit(actor, {
+            app: app.name,
+            message: 'still stored',
+        });
+        expect(captured.body).toEqual({});
+        const rows = (await server.clients.db.read(
+            'SELECT `email_sent` FROM `app_feedback` WHERE `user_id` = ?',
+            [userId],
+        )) as Array<{ email_sent: unknown }>;
+        expect(rows).toHaveLength(1);
+        expect(Boolean(rows[0]?.email_sent)).toBe(false);
+    });
+});

src/backend/controllers/feedback/AppFeedbackController.ts

@@ -0,0 +1,169 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import type { Request, Response } from 'express';
+import { Controller, Get, Post } from '../../core/http/decorators.js';
+import { HttpError } from '../../core/http/HttpError.js';
+import { AppFeedbackService } from '../../services/feedback/AppFeedbackService.js';
+import { PuterController } from '../types.js';
+
+/**
+ * Endpoints behind the "send feedback to this app's developer" dialog
+ * (`puter.ui.showFeedbackDialog()`). Only the GUI (desktop dialog or the
+ * puter.com popup) calls these; apps cannot — both routes reject app actors,
+ * which is what makes feedback impossible to submit programmatically on a
+ * user's behalf.
+ *
+ * The target may be named either by `app` (uid or name — the desktop knows
+ * which app asked) or by `origin` (external site — the popup passes its
+ * browser-attested opener origin). Exactly one must be provided.
+ */
+
+/** Sanity cap on the raw body field; the service enforces the real limit. */
+const RAW_MESSAGE_CAP = 50_000;
+
+// Upper bound on the `app`/`origin` target params. Must not exceed the
+// `source_origin` column (VARCHAR(2048) on MySQL/Postgres): the raw origin is
+// stored verbatim, and a longer value would fail the INSERT after passing
+// every validation — or be silently truncated on non-strict MySQL.
+const TARGET_PARAM_MAX_LENGTH = 2048;
+
+const readTargetParam = (value: unknown): string | undefined => {
+    return typeof value === 'string' &&
+        value.length > 0 &&
+        value.length <= TARGET_PARAM_MAX_LENGTH
+        ? value
+        : undefined;
+};
+
+@Controller('/app-feedback')
+export class AppFeedbackController extends PuterController {
+    /**
+     * GET /app-feedback/target — pre-flight for the dialog: whether the target
+     * app accepts feedback, plus its canonical title/name for display. Reveals
+     * nothing that `puter.apps.get` doesn't already.
+     */
+    @Get('/target', {
+        subdomain: 'api',
+        requireUserActor: true,
+        requireVerified: true,
+        rateLimit: {
+            scope: 'app-feedback-target',
+            limit: 60,
+            window: 60_000,
+            key: 'user',
+        },
+    })
+    async target(req: Request, res: Response): Promise<void> {
+        const app = readTargetParam(req.query.app);
+        const origin = readTargetParam(req.query.origin);
+        if (!app === !origin) {
+            throw new HttpError(
+                400,
+                'Exactly one of `app` and `origin` is required',
+                { legacyCode: 'bad_request' },
+            );
+        }
+
+        const service = this.services.appFeedback as AppFeedbackService;
+        res.json(await service.getTarget({ app, origin }));
+    }
+
+    /**
+     * POST /app-feedback — store one feedback message and email the app's
+     * developer. Strict limits: the route limits below are the cheap first
+     * line; AppFeedbackService enforces durable per-user/per-app daily caps
+     * from the database (the route limiter fails open, the DB caps don't).
+     */
+    @Post('/', {
+        subdomain: 'api',
+        requireUserActor: true,
+        requireVerified: true,
+        // Submissions only ever originate from our own GUI pages (desktop
+        // dialog / popup). Cross-origin browser pages get stopped here even
+        // if they somehow hold a user token; non-browser clients still pass
+        // and are handled by the caps.
+        guiOriginOnly: true,
+        rateLimit: [
+            {
+                scope: 'app-feedback-user',
+                limit: 5,
+                window: 30 * 60_000,
+                key: 'user',
+            },
+            // IP backstop so freshly minted accounts can't stack per-user
+            // budgets from one machine.
+            {
+                scope: 'app-feedback-ip',
+                limit: 30,
+                window: 24 * 60 * 60_000,
+                key: 'ip',
+            },
+        ],
+    })
+    async submit(req: Request, res: Response): Promise<void> {
+        const body = req.body ?? {};
+        const app = readTargetParam(body.app);
+        const origin = readTargetParam(body.origin);
+        if (!app === !origin) {
+            throw new HttpError(
+                400,
+                'Exactly one of `app` and `origin` is required',
+                { legacyCode: 'bad_request' },
+            );
+        }
+
+        const message = body.message;
+        if (typeof message !== 'string' || message.length === 0) {
+            throw new HttpError(400, '`message` is required', {
+                legacyCode: 'bad_request',
+            });
+        }
+        if (message.length > RAW_MESSAGE_CAP) {
+            throw new HttpError(
+                400,
+                `\`message\` is too long (max ${AppFeedbackService.MESSAGE_MAX_LENGTH} characters)`,
+                { legacyCode: 'bad_request' },
+            );
+        }
+
+        const sourceEnv =
+            body.context === 'app' || body.context === 'web'
+                ? body.context
+                : undefined;
+
+        const userId = req.actor?.user?.id;
+        if (!userId) {
+            throw new HttpError(401, 'Unauthorized', {
+                legacyCode: 'unauthorized',
+            });
+        }
+
+        const service = this.services.appFeedback as AppFeedbackService;
+        await service.submit({
+            userId,
+            app,
+            origin,
+            message,
+            sourceEnv,
+            sourceOrigin: origin ?? null,
+        });
+        res.json({});
+    }
+}

src/backend/controllers/fs/FSController.http.test.ts

@@ -0,0 +1,229 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { setupPuterTestEnv, type PuterTestEnv } from '../../testUtil.js';
+
+/**
+ * Route-level coverage for `GET /fs/readdir`. The unit tests call the handler
+ * directly, which cannot catch a route that was never registered or a gate that
+ * rejects the request — so this suite drives real HTTP over a listening server,
+ * and authenticates purely through `?auth_token=` (no request headers), which is
+ * the whole point of offering the read as a GET.
+ */
+describe('GET /fs/readdir over HTTP', () => {
+    let env: PuterTestEnv;
+
+    beforeAll(async () => {
+        env = await setupPuterTestEnv();
+    }, 120_000);
+
+    afterAll(async () => {
+        await env?.shutdown();
+    });
+
+    const readdirUrl = (params: Record<string, string>) => {
+        const url = new URL('/fs/readdir', env.apiOrigin);
+        for (const [key, value] of Object.entries(params)) {
+            url.searchParams.set(key, value);
+        }
+        return url;
+    };
+
+    it('lists a directory authenticated only by a query token', async () => {
+        const { username, token } = env.users.user;
+        const response = await fetch(
+            readdirUrl({ path: `/${username}`, auth_token: token }),
+        );
+        expect(response.status).toBe(200);
+        const body = (await response.json()) as Array<{
+            name: string;
+            uuid: string;
+        }>;
+        expect(Array.isArray(body)).toBe(true);
+        // Default provisioned home directories.
+        expect(body.map((e) => e.name)).toContain('Documents');
+        for (const entry of body) {
+            expect(entry.uuid).toEqual(expect.any(String));
+        }
+    });
+
+    it('paginates via query params', async () => {
+        const { username, token } = env.users.user;
+        const response = await fetch(
+            readdirUrl({
+                path: `/${username}`,
+                auth_token: token,
+                limit: '2',
+                cursor: '',
+                includeTotal: 'true',
+            }),
+        );
+        expect(response.status).toBe(200);
+        const page = (await response.json()) as {
+            items: unknown[];
+            cursor?: string;
+            total?: number;
+        };
+        expect(page.items.length).toBe(2);
+        expect(typeof page.total).toBe('number');
+        expect(page.cursor).toEqual(expect.any(String));
+    });
+
+    it('rejects an unauthenticated request', async () => {
+        const { username } = env.users.user;
+        const response = await fetch(readdirUrl({ path: `/${username}` }));
+        expect(response.status).toBeGreaterThanOrEqual(400);
+        expect(response.status).toBeLessThan(500);
+    });
+
+    it('does not leak internal ids or storage columns over the wire', async () => {
+        const { username, token } = env.users.user;
+        const response = await fetch(
+            readdirUrl({ path: `/${username}`, auth_token: token }),
+        );
+        const raw = await response.text();
+        const body = JSON.parse(raw) as Array<Record<string, unknown>>;
+        expect(body.length).toBeGreaterThan(0);
+        // Checked per-entry rather than by scanning the raw body: the nested
+        // `associatedApp` payload legitimately carries its own `id` (v1 has
+        // always exposed it), so a substring scan would false-alarm.
+        for (const entry of body) {
+            for (const field of [
+                'id',
+                'parentId',
+                'userId',
+                'associatedAppId',
+                'bucket',
+                'bucketRegion',
+                'publicToken',
+                'fileRequestToken',
+            ]) {
+                expect(entry).not.toHaveProperty(field);
+            }
+        }
+        // No user-identifying data (emails, owner records) anywhere.
+        expect(raw).not.toContain('@');
+        expect(raw).not.toMatch(/"(email|owner|user_id|userId)"/);
+    });
+
+    it('lists a nested subtree recursively over GET', async () => {
+        const { username, token } = env.users.user;
+        const base = `/${username}/Documents/http-recursive-${Date.now()}`;
+        for (const path of [base, `${base}/a`, `${base}/a/b`]) {
+            const created = await fetch(new URL('/fs/mkdir', env.apiOrigin), {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ path, auth_token: token }),
+            });
+            expect(created.status).toBe(200);
+        }
+
+        const response = await fetch(
+            readdirUrl({
+                path: base,
+                auth_token: token,
+                recursive: 'true',
+                depth: '5',
+            }),
+        );
+        expect(response.status).toBe(200);
+        const page = (await response.json()) as {
+            items: Array<{ path: string }>;
+        };
+        expect(
+            page.items.map((e) => e.path.slice(base.length + 1)).sort(),
+        ).toEqual(['a', 'a/b']);
+    });
+
+    it('mkdir does not return internal ids, storage columns or tokens', async () => {
+        const { username, token } = env.users.user;
+        const response = await fetch(new URL('/fs/mkdir', env.apiOrigin), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                path: `/${username}/Documents/http-mkdir-${Date.now()}`,
+                auth_token: token,
+            }),
+        });
+        expect(response.status).toBe(200);
+        const entry = (await response.json()) as Record<string, unknown>;
+        expect(entry.uuid).toEqual(expect.any(String));
+        expect(entry.isDir).toBe(true);
+        for (const field of [
+            'id',
+            'parentId',
+            'userId',
+            'associatedAppId',
+            'bucket',
+            'bucketRegion',
+            'publicToken',
+            'fileRequestToken',
+        ]) {
+            expect(entry).not.toHaveProperty(field);
+        }
+    });
+
+    it('startBatchWrite does not expose storage internals', async () => {
+        const { username, token } = env.users.user;
+        const response = await fetch(
+            new URL('/fs/startBatchWrite', env.apiOrigin),
+            {
+                method: 'POST',
+                // Array body, so there is no `auth_token` field for the auth
+                // probe to read — authenticate via the header instead.
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${token}`,
+                },
+                body: JSON.stringify([
+                    {
+                        fileMetadata: {
+                            path: `/${username}/Documents/http-signed-${Date.now()}.bin`,
+                            size: 4,
+                        },
+                    },
+                ]),
+            },
+        );
+        expect(response.status).toBe(200);
+        const [target] = (await response.json()) as Array<
+            Record<string, unknown>
+        >;
+        // What a client actually needs to upload.
+        expect(target!.sessionId).toEqual(expect.any(String));
+        expect(typeof target!.url).toBe('string');
+        // What it does not: where the bytes physically live.
+        for (const field of ['bucket', 'bucketRegion', 'objectKey']) {
+            expect(target).not.toHaveProperty(field);
+        }
+    });
+
+    it('still serves the POST form for existing callers', async () => {
+        const { username, token } = env.users.user;
+        const response = await fetch(new URL('/fs/readdir', env.apiOrigin), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ path: `/${username}`, auth_token: token }),
+        });
+        expect(response.status).toBe(200);
+        const body = (await response.json()) as Array<{ name: string }>;
+        expect(body.map((e) => e.name)).toContain('Documents');
+    });
+});

src/backend/controllers/fs/FSController.test.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -19,18 +19,18 @@
 
 import type { Request, Response } from 'express';
 import type { Readable } from 'node:stream';
-import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
 import { v4 as uuidv4 } from 'uuid';
-import type { Actor } from '../../core/actor.js';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { makeActor, type Actor } from '../../core/actor.js';
 import { runWithContext } from '../../core/context.js';
 import { PuterServer } from '../../server.js';
 import { setupTestServer } from '../../testUtil.js';
 import { generateDefaultFsentries } from '../../util/userProvisioning.js';
 import type { FSController } from './FSController.js';
 import type {
+    ClientSignedWriteResponse,
     CompleteWriteRequest,
     SignedWriteRequest,
-    SignedWriteResponse,
 } from './requestTypes.js';
 
 // ── Test harness ────────────────────────────────────────────────────
@@ -91,11 +91,15 @@ const makeReq = <B>(init: {
     headers?: Record<string, string>;
     actor: Actor;
     user?: { id: number; username: string };
+    method?: string;
 }): Request => {
     return {
         body: init.body ?? ({} as B),
         query: init.query ?? {},
         headers: init.headers ?? {},
+        // Handlers that serve both verbs (readdir) read params from `query` on
+        // GET and `body` otherwise.
+        ...(init.method ? { method: init.method } : {}),
         actor: init.actor,
         // Some controller helpers fall back to `req.user` (set by the
         // session middleware) for id / username before reading `req.actor`.
@@ -165,13 +169,16 @@ describe('FSController.startBatchWrites', () => {
         const req = makeReq<SignedWriteRequest[]>({ body, actor });
         await withActor(actor, () => controller.startBatchWrites(req, res));
 
-        const responses = captured.body as SignedWriteResponse[];
+        const responses = captured.body as ClientSignedWriteResponse[];
         expect(responses).toHaveLength(2);
         for (const r of responses) {
             expect(r.sessionId).toEqual(expect.any(String));
-            expect(r.objectKey).toEqual(expect.any(String));
-            expect(r.bucket).toEqual(expect.any(String));
             expect(r.uploadMode).toBe('single');
+            // Storage internals stay server-side: the presigned `url` already
+            // encodes bucket and key.
+            for (const field of ['bucket', 'bucketRegion', 'objectKey']) {
+                expect(r).not.toHaveProperty(field);
+            }
             // In-memory mock S3 still returns a presigned-URL string for
             // single-mode uploads — verify it's there but don't assert
             // shape (varies by region/host config).
@@ -203,7 +210,7 @@ describe('FSController.startBatchWrites', () => {
         const { res, captured } = makeRes();
         const req = makeReq<SignedWriteRequest[]>({ body, actor });
         await withActor(actor, () => controller.startBatchWrites(req, res));
-        const [response] = captured.body as SignedWriteResponse[];
+        const [response] = captured.body as ClientSignedWriteResponse[];
         const session = await server.stores.fsEntry.getPendingEntryBySessionId(
             response!.sessionId,
         );
@@ -329,7 +336,8 @@ describe('FSController.completeBatchWrites', () => {
                 startRes.res,
             ),
         );
-        const startResponses = startRes.captured.body as SignedWriteResponse[];
+        const startResponses = startRes.captured
+            .body as ClientSignedWriteResponse[];
         expect(startResponses).toHaveLength(2);
 
         // 2) Complete via the controller. Single-mode completion only
@@ -352,16 +360,29 @@ describe('FSController.completeBatchWrites', () => {
         const responses = captured.body as Array<{
             sessionId: string;
             wasOverwrite: boolean;
-            fsEntry: { path: string; userId: number; isDir: boolean };
+            fsEntry: Record<string, unknown>;
         }>;
-        expect(responses.map((r) => r.fsEntry.path).sort()).toEqual([
+        expect(responses.map((r) => r.fsEntry.path as string).sort()).toEqual([
             `/${username}/Documents/c.txt`,
             `/${username}/Documents/d.txt`,
         ]);
         for (const response of responses) {
             expect(response.wasOverwrite).toBe(false);
-            expect(response.fsEntry.userId).toBe(userId);
             expect(response.fsEntry.isDir).toBe(false);
+            // Ownership is asserted against the store below — the response
+            // itself must not carry the owner, storage columns, or the
+            // capability tokens.
+            for (const field of [
+                'userId',
+                'id',
+                'parentId',
+                'bucket',
+                'bucketRegion',
+                'publicToken',
+                'fileRequestToken',
+            ]) {
+                expect(response.fsEntry).not.toHaveProperty(field);
+            }
         }
 
         // The real fsentries were committed and are now resolvable.
@@ -392,7 +413,7 @@ describe('FSController.completeBatchWrites', () => {
             ),
         );
         const [firstResponse] = firstStart.captured
-            .body as SignedWriteResponse[];
+            .body as ClientSignedWriteResponse[];
         const firstComplete = makeRes();
         await withActor(actor, () =>
             controller.completeBatchWrites(
@@ -424,7 +445,7 @@ describe('FSController.completeBatchWrites', () => {
             ),
         );
         const [secondResponse] = secondStart.captured
-            .body as SignedWriteResponse[];
+            .body as ClientSignedWriteResponse[];
 
         const secondComplete = makeRes();
         await withActor(actor, () =>
@@ -464,20 +485,25 @@ describe('FSController.completeBatchWrites', () => {
                 start.res,
             ),
         );
-        const [started] = start.captured.body as SignedWriteResponse[];
+        const [started] = start.captured.body as ClientSignedWriteResponse[];
 
         // Actually upload 4096 bytes to the session's object key (simulating
-        // a client that PUTs more than it declared via the signed URL).
+        // a client that PUTs more than it declared via the signed URL). The
+        // storage location isn't in the response any more, so read it off the
+        // upload session — a real client just PUTs to the presigned URL.
+        const session = await server.stores.fsEntry.getPendingEntryBySessionId(
+            started!.sessionId,
+        );
         const realBytes = Buffer.alloc(4096, 0x41);
         await server.stores.s3Object.uploadFromServer(
             {
-                bucket: started!.bucket,
-                objectKey: started!.objectKey,
+                bucket: session!.bucket!,
+                objectKey: session!.objectKey,
                 contentType: 'application/octet-stream',
                 body: realBytes,
                 contentLength: realBytes.byteLength,
             },
-            started!.bucketRegion,
+            session!.bucketRegion!,
         );
 
         const complete = makeRes();
@@ -518,7 +544,7 @@ describe('FSController.completeBatchWrites', () => {
             ),
         );
         const [firstResponse] = firstStart.captured
-            .body as SignedWriteResponse[];
+            .body as ClientSignedWriteResponse[];
         await withActor(actor, () =>
             controller.completeBatchWrites(
                 makeReq<CompleteWriteRequest[]>({
@@ -555,7 +581,7 @@ describe('FSController.completeBatchWrites', () => {
             ),
         );
         const [secondResponse] = secondStart.captured
-            .body as SignedWriteResponse[];
+            .body as ClientSignedWriteResponse[];
 
         const emitSpy = vi.spyOn(server.clients.event, 'emit');
         let updatedCall: (typeof emitSpy.mock.calls)[number] | undefined;
@@ -635,7 +661,7 @@ describe('FSController.completeBatchWrites', () => {
                 startA.res,
             ),
         );
-        const [aResponse] = startA.captured.body as SignedWriteResponse[];
+        const [aResponse] = startA.captured.body as ClientSignedWriteResponse[];
 
         const err = await withActor(b.actor, () =>
             controller
@@ -696,6 +722,41 @@ describe('FSController.statEntry', () => {
         expect(body.name).toBe('stat-me');
     });
 
+    it('does not leak backend-internal fields to the client', async () => {
+        const { actor } = await makeUser();
+        const username = actor.user!.username!;
+        await withActor(actor, () =>
+            controller.mkdirEntry(
+                makeReq({
+                    body: { path: `/${username}/Documents/no-leak` },
+                    actor,
+                }),
+                makeRes().res,
+            ),
+        );
+
+        const { res, captured } = makeRes();
+        await withActor(actor, () =>
+            controller.statEntry(
+                makeReq({
+                    body: { path: `/${username}/Documents/no-leak` },
+                    actor,
+                }),
+                res,
+            ),
+        );
+        const body = captured.body as Record<string, unknown>;
+        for (const field of [
+            'bucket',
+            'bucketRegion',
+            'userId',
+            'publicToken',
+            'fileRequestToken',
+        ]) {
+            expect(body).not.toHaveProperty(field);
+        }
+    });
+
     it('includes the subtree size when return_size is set on a directory', async () => {
         const { actor } = await makeUser();
         const username = actor.user!.username!;
@@ -813,7 +874,11 @@ describe('FSController.readdirEntries', () => {
                     makeRes().res,
                 ),
             ),
-        ).rejects.toMatchObject({ statusCode: 400 });
+        ).rejects.toMatchObject({
+            statusCode: 400,
+            // Matches the legacy `/readdir` code the SDK moved off of.
+            legacyCode: 'dest_is_not_a_directory',
+        });
     });
 });
 
@@ -862,7 +927,7 @@ describe('FSController.searchEntries', () => {
         const { actor: userActor } = await makeUser();
         const username = userActor.user!.username!;
         const appUid = `app-search-${uuidv4()}`;
-        const appActor: Actor = { ...userActor, app: { uid: appUid } };
+        const appActor = makeActor({ ...userActor, app: { uid: appUid } });
         const needle = `appneedle-${Math.random().toString(36).slice(2, 8)}`;
 
         // User-owned entry outside AppData — must NOT appear for the app.
@@ -913,7 +978,7 @@ describe('FSController.searchEntries', () => {
         const { actor: userActor } = await makeUser();
         const username = userActor.user!.username!;
         const appUid = `app-search-${uuidv4()}`;
-        const appActor: Actor = { ...userActor, app: { uid: appUid } };
+        const appActor = makeActor({ ...userActor, app: { uid: appUid } });
         const needle = `appneedle-${Math.random().toString(36).slice(2, 8)}`;
 
         // Only seed outside AppData — the app must not be able to find it.
@@ -1062,7 +1127,7 @@ describe('FSController.mkdirEntry', () => {
         const { actor: userActor } = await makeUser();
         const username = userActor.user!.username!;
         const appUid = `app-mkdir-${uuidv4()}`;
-        const appActor: Actor = { ...userActor, app: { uid: appUid } };
+        const appActor = makeActor({ ...userActor, app: { uid: appUid } });
         const target = `/${username}/AppData/${appUid}`;
 
         await withActor(userActor, () =>
@@ -1510,6 +1575,546 @@ describe('FSController.readdirEntries sort + limit', () => {
     });
 });
 
+// -- /readdir pagination envelope --
+
+describe('FSController.readdirEntries pagination', () => {
+    const makeDocs = async (names: string[]) => {
+        const { actor } = await makeUser();
+        const username = actor.user!.username!;
+        for (const name of names) {
+            await withActor(actor, () =>
+                controller.mkdirEntry(
+                    makeReq({
+                        body: { path: `/${username}/Documents/${name}` },
+                        actor,
+                    }),
+                    makeRes().res,
+                ),
+            );
+        }
+        return { actor, path: `/${username}/Documents` };
+    };
+
+    const readdir = async (
+        actor: Awaited<ReturnType<typeof makeUser>>['actor'],
+        body: Record<string, unknown>,
+    ) => {
+        const { res, captured } = makeRes();
+        await withActor(actor, () =>
+            controller.readdirEntries(makeReq({ body, actor }), res),
+        );
+        return captured.body;
+    };
+
+    it('keeps the bare array response for limit/offset requests', async () => {
+        const { actor, path } = await makeDocs(['a', 'b', 'c']);
+        const body = await readdir(actor, { path, limit: 2, offset: 1 });
+        expect(Array.isArray(body)).toBe(true);
+        expect((body as unknown[]).length).toBe(2);
+    });
+
+    it('returns the envelope when cursor is present (null = first page)', async () => {
+        const { actor, path } = await makeDocs(['a', 'b', 'c']);
+        const page = (await readdir(actor, { path, cursor: null })) as {
+            items: Array<{ name: string }>;
+            cursor?: string;
+        };
+        expect(page.items.map((e) => e.name)).toEqual(['a', 'b', 'c']);
+        expect(page.cursor).toBeUndefined();
+    });
+
+    it('pages through children with cursors in sort order', async () => {
+        const { actor, path } = await makeDocs(['d1', 'd2', 'd3', 'd4', 'd5']);
+        const names: string[] = [];
+        let cursor: string | null | undefined = null;
+        do {
+            const page = (await readdir(actor, {
+                path,
+                limit: 2,
+                cursor,
+            })) as { items: Array<{ name: string }>; cursor?: string };
+            names.push(...page.items.map((e) => e.name));
+            cursor = page.cursor;
+        } while (cursor);
+        expect(names).toEqual(['d1', 'd2', 'd3', 'd4', 'd5']);
+    });
+
+    it('respects descending sort across pages', async () => {
+        const { actor, path } = await makeDocs(['a', 'b', 'c', 'd']);
+        const first = (await readdir(actor, {
+            path,
+            limit: 2,
+            cursor: null,
+            sortBy: 'name',
+            sortOrder: 'desc',
+        })) as { items: Array<{ name: string }>; cursor?: string };
+        expect(first.items.map((e) => e.name)).toEqual(['d', 'c']);
+        const second = (await readdir(actor, {
+            path,
+            limit: 2,
+            cursor: first.cursor,
+        })) as { items: Array<{ name: string }>; cursor?: string };
+        expect(second.items.map((e) => e.name)).toEqual(['b', 'a']);
+    });
+
+    it('rejects a cursor that conflicts with the requested sort', async () => {
+        const { actor, path } = await makeDocs(['a', 'b', 'c']);
+        const first = (await readdir(actor, {
+            path,
+            limit: 1,
+            cursor: null,
+            sortBy: 'name',
+        })) as { cursor?: string };
+        await expect(
+            withActor(actor, () =>
+                controller.readdirEntries(
+                    makeReq({
+                        body: {
+                            path,
+                            limit: 1,
+                            cursor: first.cursor,
+                            sortBy: 'size',
+                        },
+                        actor,
+                    }),
+                    makeRes().res,
+                ),
+            ),
+        ).rejects.toMatchObject({ statusCode: 400 });
+    });
+
+    it('reports total with includeTotal', async () => {
+        const { actor, path } = await makeDocs(['a', 'b', 'c']);
+        const page = (await readdir(actor, {
+            path,
+            limit: 1,
+            cursor: null,
+            includeTotal: true,
+        })) as { items: unknown[]; total?: number };
+        expect(page.items.length).toBe(1);
+        expect(page.total).toBe(3);
+    });
+
+    it('wraps the root listing in an envelope when asked', async () => {
+        const { actor } = await makeUser();
+        const page = (await readdir(actor, {
+            path: '/',
+            cursor: null,
+            includeTotal: true,
+        })) as { items: unknown[]; total?: number; cursor?: string };
+        expect(Array.isArray(page.items)).toBe(true);
+        expect(page.total).toBe(page.items.length);
+        expect(page.cursor).toBeUndefined();
+    });
+});
+
+// -- /readdir recursive (nested listing) --
+
+describe('FSController.readdirEntries recursive', () => {
+    // Seed a nested tree under Documents/tree and return its base path.
+    // Relative depths: l1a/l1b = 1, l2a = 2, l3a = 3, l4a = 4.
+    const makeTree = async () => {
+        const { actor, userId } = await makeUser();
+        const username = actor.user!.username!;
+        const base = `/${username}/Documents/tree`;
+        const dirs = [
+            base,
+            `${base}/l1a`,
+            `${base}/l1b`,
+            `${base}/l1a/l2a`,
+            `${base}/l1a/l2a/l3a`,
+            `${base}/l1a/l2a/l3a/l4a`,
+        ];
+        for (const path of dirs) {
+            await withActor(actor, () =>
+                controller.mkdirEntry(
+                    makeReq({ body: { path }, actor }),
+                    makeRes().res,
+                ),
+            );
+        }
+        return { actor, userId, base };
+    };
+
+    const readdir = async (
+        actor: Awaited<ReturnType<typeof makeUser>>['actor'],
+        body: Record<string, unknown>,
+    ) => {
+        const { res, captured } = makeRes();
+        await withActor(actor, () =>
+            controller.readdirEntries(makeReq({ body, actor }), res),
+        );
+        return captured.body;
+    };
+
+    const rel = (base: string, items: Array<{ path: string }>) =>
+        items.map((e) => e.path.slice(base.length + 1)).sort();
+
+    it('depth 1 returns only direct children (like a normal readdir)', async () => {
+        const { actor, base } = await makeTree();
+        const page = (await readdir(actor, {
+            path: base,
+            recursive: true,
+            depth: 1,
+        })) as { items: Array<{ path: string }>; cursor?: string };
+        expect(rel(base, page.items)).toEqual(['l1a', 'l1b']);
+    });
+
+    it('deeper levels appear as depth grows', async () => {
+        const { actor, base } = await makeTree();
+        const d2 = (await readdir(actor, {
+            path: base,
+            recursive: true,
+            depth: 2,
+        })) as { items: Array<{ path: string }> };
+        expect(rel(base, d2.items)).toEqual(['l1a', 'l1a/l2a', 'l1b']);
+
+        const d3 = (await readdir(actor, {
+            path: base,
+            recursive: true,
+            depth: 3,
+        })) as { items: Array<{ path: string }> };
+        expect(rel(base, d3.items)).toEqual([
+            'l1a',
+            'l1a/l2a',
+            'l1a/l2a/l3a',
+            'l1b',
+        ]);
+    });
+
+    it('caps depth at 10 so a huge depth returns the whole subtree', async () => {
+        const { actor, base } = await makeTree();
+        const page = (await readdir(actor, {
+            path: base,
+            recursive: true,
+            depth: 9999,
+        })) as { items: Array<{ path: string }> };
+        expect(rel(base, page.items)).toEqual([
+            'l1a',
+            'l1a/l2a',
+            'l1a/l2a/l3a',
+            'l1a/l2a/l3a/l4a',
+            'l1b',
+        ]);
+    });
+
+    it('pages through the whole subtree with cursors, no dupes or gaps', async () => {
+        const { actor, base } = await makeTree();
+        const seen: string[] = [];
+        let cursor: string | null | undefined = null;
+        do {
+            const page = (await readdir(actor, {
+                path: base,
+                recursive: true,
+                depth: 10,
+                limit: 2,
+                cursor,
+            })) as { items: Array<{ path: string }>; cursor?: string };
+            expect(page.items.length).toBeLessThanOrEqual(2);
+            seen.push(...page.items.map((e) => e.path));
+            cursor = page.cursor;
+        } while (cursor);
+        expect(
+            rel(
+                base,
+                seen.map((path) => ({ path })),
+            ),
+        ).toEqual(['l1a', 'l1a/l2a', 'l1a/l2a/l3a', 'l1a/l2a/l3a/l4a', 'l1b']);
+    });
+
+    it('counts the subtree with includeTotal', async () => {
+        const { actor, base } = await makeTree();
+        const page = (await readdir(actor, {
+            path: base,
+            recursive: true,
+            depth: 2,
+            cursor: null,
+            includeTotal: true,
+        })) as { items: unknown[]; total?: number };
+        expect(page.total).toBe(3); // l1a, l1b, l2a
+    });
+
+    it('enriches entries with type, thumbnail and associatedApp', async () => {
+        const { actor, base } = await makeTree();
+        const page = (await readdir(actor, {
+            path: base,
+            recursive: true,
+            depth: 1,
+        })) as {
+            items: Array<{
+                type?: unknown;
+                thumbnail?: unknown;
+                associatedApp?: unknown;
+            }>;
+        };
+        for (const item of page.items) {
+            expect(item.type).toBe('folder');
+            expect(item.thumbnail ?? null).toBeNull();
+            expect('associatedApp' in item).toBe(true);
+        }
+    });
+
+    it('gives files a MIME type and an associatedApp field', async () => {
+        const { actor } = await makeUser();
+        const username = actor.user!.username!;
+        const dir = `/${username}/Documents/files`;
+        await withActor(actor, () =>
+            controller.mkdirEntry(
+                makeReq({ body: { path: dir }, actor }),
+                makeRes().res,
+            ),
+        );
+        await withActor(actor, () =>
+            controller.touchEntry(
+                makeReq({ body: { path: `${dir}/pic.png` }, actor }),
+                makeRes().res,
+            ),
+        );
+        const page = (await readdir(actor, {
+            path: dir,
+            recursive: true,
+            depth: 1,
+        })) as {
+            items: Array<{
+                name: string;
+                type?: unknown;
+                associatedApp?: unknown;
+            }>;
+        };
+        const file = page.items.find((e) => e.name === 'pic.png')!;
+        expect(String(file.type)).toContain('image/png');
+        expect('associatedApp' in file).toBe(true);
+    });
+
+    it('masks denials for app-under-user actors as a 404 (legacy parity)', async () => {
+        const { actor: userActor } = await makeUser();
+        const username = userActor.user!.username!;
+        const appActor = makeActor({
+            ...userActor,
+            app: { uid: `app-readdir-${uuidv4()}` },
+        });
+        // The user's Documents is outside the app's AppData subtree, so the
+        // app can't list it. Legacy `/readdir` masks this as a 404
+        // subject_does_not_exist rather than leaking a 403.
+        await expect(
+            withActor(appActor, () =>
+                controller.readdirEntries(
+                    makeReq({
+                        body: { path: `/${username}/Documents` },
+                        actor: appActor,
+                    }),
+                    makeRes().res,
+                ),
+            ),
+        ).rejects.toMatchObject({
+            statusCode: 404,
+            legacyCode: 'subject_does_not_exist',
+        });
+    });
+
+    it('rejects recursive listing at the root', async () => {
+        const { actor } = await makeUser();
+        await expect(
+            withActor(actor, () =>
+                controller.readdirEntries(
+                    makeReq({
+                        body: { path: '/', recursive: true },
+                        actor,
+                    }),
+                    makeRes().res,
+                ),
+            ),
+        ).rejects.toMatchObject({ statusCode: 400 });
+    });
+
+    it('does not leak another users identically-named subtree', async () => {
+        const { actor, base } = await makeTree();
+        // A second user with the same relative tree must not appear.
+        await makeTree();
+        const page = (await readdir(actor, {
+            path: base,
+            recursive: true,
+            depth: 10,
+        })) as { items: Array<{ path: string }> };
+        for (const item of page.items) {
+            expect(item.path.startsWith(`${base}/`)).toBe(true);
+        }
+        expect(page.items).toHaveLength(5);
+    });
+});
+
+// -- /readdir over GET (query params) --
+
+describe('FSController.readdirEntriesViaGet', () => {
+    const seed = async (names: string[]) => {
+        const { actor } = await makeUser();
+        const username = actor.user!.username!;
+        const dir = `/${username}/Documents/get-readdir`;
+        await withActor(actor, () =>
+            controller.mkdirEntry(
+                makeReq({ body: { path: dir }, actor }),
+                makeRes().res,
+            ),
+        );
+        for (const name of names) {
+            await withActor(actor, () =>
+                controller.mkdirEntry(
+                    makeReq({ body: { path: `${dir}/${name}` }, actor }),
+                    makeRes().res,
+                ),
+            );
+        }
+        return { actor, dir };
+    };
+
+    // Query strings carry every value as a string — that is the whole risk
+    // surface of this route, so tests pass strings the way a real URL would.
+    const getReaddir = async (
+        actor: Awaited<ReturnType<typeof makeUser>>['actor'],
+        query: Record<string, unknown>,
+    ) => {
+        const { res, captured } = makeRes();
+        await withActor(actor, () =>
+            controller.readdirEntriesViaGet(
+                makeReq({ query, actor, method: 'GET' }),
+                res,
+            ),
+        );
+        return captured.body;
+    };
+
+    it('lists a directory from query params', async () => {
+        const { actor, dir } = await seed(['a', 'b', 'c']);
+        const body = await getReaddir(actor, { path: dir });
+        expect(Array.isArray(body)).toBe(true);
+        expect((body as Array<{ name: string }>).map((e) => e.name)).toEqual([
+            'a',
+            'b',
+            'c',
+        ]);
+    });
+
+    it('honors string limit/offset like the POST form', async () => {
+        const { actor, dir } = await seed(['a', 'b', 'c']);
+        const body = (await getReaddir(actor, {
+            path: dir,
+            limit: '2',
+            offset: '1',
+        })) as Array<{ name: string }>;
+        expect(body.map((e) => e.name)).toEqual(['b', 'c']);
+    });
+
+    it('treats an empty cursor as the first page and returns the envelope', async () => {
+        const { actor, dir } = await seed(['a', 'b', 'c']);
+        const page = (await getReaddir(actor, { path: dir, cursor: '' })) as {
+            items: Array<{ name: string }>;
+            cursor?: string;
+        };
+        expect(page.items.map((e) => e.name)).toEqual(['a', 'b', 'c']);
+        expect(page.cursor).toBeUndefined();
+    });
+
+    it('pages through with a string cursor', async () => {
+        const { actor, dir } = await seed(['d1', 'd2', 'd3', 'd4', 'd5']);
+        const names: string[] = [];
+        let cursor: string | undefined = '';
+        do {
+            const page = (await getReaddir(actor, {
+                path: dir,
+                limit: '2',
+                cursor,
+            })) as { items: Array<{ name: string }>; cursor?: string };
+            names.push(...page.items.map((e) => e.name));
+            cursor = page.cursor;
+        } while (cursor);
+        expect(names).toEqual(['d1', 'd2', 'd3', 'd4', 'd5']);
+    });
+
+    it('coerces string includeTotal=true', async () => {
+        const { actor, dir } = await seed(['a', 'b', 'c']);
+        const page = (await getReaddir(actor, {
+            path: dir,
+            limit: '1',
+            cursor: '',
+            includeTotal: 'true',
+        })) as { items: unknown[]; total?: number };
+        expect(page.items.length).toBe(1);
+        expect(page.total).toBe(3);
+    });
+
+    it('coerces string recursive/depth and lists nested entries', async () => {
+        const { actor } = await makeUser();
+        const username = actor.user!.username!;
+        const base = `/${username}/Documents/get-tree`;
+        for (const path of [base, `${base}/a`, `${base}/a/b`]) {
+            await withActor(actor, () =>
+                controller.mkdirEntry(
+                    makeReq({ body: { path }, actor }),
+                    makeRes().res,
+                ),
+            );
+        }
+        const page = (await getReaddir(actor, {
+            path: base,
+            recursive: 'true',
+            depth: '2',
+        })) as { items: Array<{ path: string }> };
+        expect(
+            page.items.map((e) => e.path.slice(base.length + 1)).sort(),
+        ).toEqual(['a', 'a/b']);
+    });
+
+    it('rejects a non-directory target with the legacy code', async () => {
+        const { actor } = await makeUser();
+        const username = actor.user!.username!;
+        const file = `/${username}/Documents/get-file.txt`;
+        await withActor(actor, () =>
+            controller.touchEntry(
+                makeReq({ body: { path: file }, actor }),
+                makeRes().res,
+            ),
+        );
+        await expect(
+            withActor(actor, () =>
+                controller.readdirEntriesViaGet(
+                    makeReq({ query: { path: file }, actor, method: 'GET' }),
+                    makeRes().res,
+                ),
+            ),
+        ).rejects.toMatchObject({
+            statusCode: 400,
+            legacyCode: 'dest_is_not_a_directory',
+        });
+    });
+
+    it('does not expose internal ids, storage columns or tokens', async () => {
+        const { actor, dir } = await seed(['a']);
+        const body = (await getReaddir(actor, { path: dir })) as Array<
+            Record<string, unknown>
+        >;
+        const entry = body[0]!;
+        // Numeric primary keys and storage/token columns must never ship in a
+        // listing — entries are addressed by uuid.
+        for (const field of [
+            'id',
+            'parentId',
+            'userId',
+            'associatedAppId',
+            'bucket',
+            'bucketRegion',
+            'publicToken',
+            'fileRequestToken',
+        ]) {
+            expect(entry).not.toHaveProperty(field);
+        }
+        expect(entry.uuid).toEqual(expect.any(String));
+        // No user-identifying data anywhere in the serialized payload.
+        const serialized = JSON.stringify(body);
+        expect(serialized).not.toContain('@');
+        expect(serialized).not.toMatch(/"(email|owner|user_id|userId)"/);
+    });
+});
+
 // ── /touch additional branches ──────────────────────────────────────
 
 describe('FSController.touchEntry additional branches', () => {
@@ -1767,15 +2372,18 @@ describe('FSController.statEntry additional branches', () => {
 // ── #getReportedCosts ───────────────────────────────────────────────
 
 describe('FSController.getReportedCosts', () => {
-    it('mirrors every FS_COSTS entry as a per-byte line item', async () => {
-        const { FS_COSTS } = await import('./costs.js');
+    it('mirrors every storage-operation price as a per-operation line item', async () => {
+        const { STORAGE_OP_COSTS } =
+            await import('../../services/metering/costs.js');
         const reported = controller.getReportedCosts();
-        expect(reported.length).toBe(Object.keys(FS_COSTS).length);
-        for (const [usageType, ucentsPerUnit] of Object.entries(FS_COSTS)) {
+        expect(reported.length).toBe(Object.keys(STORAGE_OP_COSTS).length);
+        for (const [usageType, ucentsPerUnit] of Object.entries(
+            STORAGE_OP_COSTS,
+        )) {
             expect(reported).toContainEqual({
                 usageType,
                 ucentsPerUnit,
-                unit: 'byte',
+                unit: 'operation',
                 source: 'controller:fs',
             });
         }
@@ -2022,10 +2630,9 @@ describe('FSController associatedAppId entitlement gate', () => {
             ],
         );
         const row = (
-            await server.clients.db.read(
-                'SELECT id FROM apps WHERE uid = ?',
-                [uid],
-            )
+            await server.clients.db.read('SELECT id FROM apps WHERE uid = ?', [
+                uid,
+            ])
         )[0] as { id: number };
         return { id: row.id };
     };
@@ -2041,13 +2648,15 @@ describe('FSController associatedAppId entitlement gate', () => {
         await withActor(actor, () =>
             controller.startBatchWrites(
                 makeReq<SignedWriteRequest[]>({
-                    body: [{ fileMetadata: { path, size: 3, associatedAppId } }],
+                    body: [
+                        { fileMetadata: { path, size: 3, associatedAppId } },
+                    ],
                     actor,
                 }),
                 startRes.res,
             ),
         );
-        const [started] = startRes.captured.body as SignedWriteResponse[];
+        const [started] = startRes.captured.body as ClientSignedWriteResponse[];
         const completeRes = makeRes();
         await withActor(actor, () =>
             controller.completeBatchWrites(

src/backend/controllers/fs/FSController.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -22,7 +22,6 @@ import type { Request, Response } from 'express';
 import { posix as pathPosix } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import type { Actor } from '../../core/actor.js';
-import { effectiveActorApp } from '../../core/actor.js';
 import { Context } from '../../core/context.js';
 import { HttpError } from '../../core/http/HttpError.js';
 import { Controller, Get, Post } from '../../core/http/decorators.js';
@@ -39,14 +38,37 @@ import {
 } from '../../util/concurrency.js';
 import { applyInlineContentSecurity } from '../../util/inlineContentSecurity.js';
 import { PuterController } from '../types.js';
-import { FS_COSTS } from './costs.js';
+import { STORAGE_OP_COSTS } from '../../services/metering/costs.js';
+import {
+    FS_MULTIPART_LIMIT,
+    FS_MUTATE_LIMIT,
+    FS_READ_CONCURRENT,
+    FS_READ_LIMIT,
+    FS_READDIR_LIMIT,
+    FS_SEARCH_CONCURRENT,
+    FS_SEARCH_LIMIT,
+    FS_STAT_LIMIT,
+    FS_WRITE_CONCURRENT,
+    FS_WRITE_LIMIT,
+} from './limits.js';
+import {
+    assertAccess as assertLegacyAccess,
+    fsEntryMimeType,
+    loadLegacyAssociatedApps,
+    signEntryThumbnail,
+    toLegacyEntry,
+} from './legacyFsHelpers.js';
 import type {
+    ClientCompleteWriteResponse,
+    ClientFSEntry,
+    ClientReaddirEntry,
+    ClientSignedWriteResponse,
+    ClientSignMultipartPartsResponse,
+    ClientWriteResponse,
     CompleteWriteRequest,
-    CompleteWriteResponse,
     SignedWriteRequest,
     SignedWriteResponse,
     SignMultipartPartsRequest,
-    SignMultipartPartsResponse,
     WriteGuiMetadata,
     WriteRequest,
     WriteResponse,
@@ -60,7 +82,6 @@ import type {
     ThumbnailUploadPrepareItem,
     ThumbnailUploadPreparePayload,
 } from './types.js';
-import { toLegacyEntry } from './legacyFsHelpers.js';
 class UploadProgressTracker implements UploadProgressTrackerLike {
     total = 0;
     progress = 0;
@@ -89,24 +110,36 @@ class UploadProgressTracker implements UploadProgressTrackerLike {
 }
 
 const MAX_THUMBNAIL_BYTES = 2 * 1024 * 1024;
+// Hard cap on how many levels below the target a recursive readdir descends.
+const MAX_READDIR_DEPTH = 10;
 const DEFAULT_BATCH_ACL_CHECK_CONCURRENCY = 32;
 const DEFAULT_BATCH_WRITE_SIDE_EFFECT_CONCURRENCY = 8;
 
 @Controller('/fs')
 export class FSController extends PuterController {
+    // Object-store requests are reported here because the filesystem is what
+    // makes them. Bytes leaving the server are not: they are metered for every
+    // response, so `MeteringService` prices them.
     override getReportedCosts() {
-        return Object.entries(FS_COSTS).map(([usageType, ucentsPerUnit]) => ({
-            usageType,
-            ucentsPerUnit,
-            unit: 'byte',
-            source: 'controller:fs',
-        }));
+        return Object.entries(STORAGE_OP_COSTS).map(
+            ([usageType, ucentsPerUnit]) => ({
+                usageType,
+                ucentsPerUnit,
+                unit: 'operation',
+                source: 'controller:fs',
+            }),
+        );
     }
 
-    @Post('/startWrite', { subdomain: 'api', requireVerified: true })
+    @Post('/startWrite', {
+        subdomain: 'api',
+        requireVerified: true,
+        requireCredits: true,
+        rateLimit: FS_MULTIPART_LIMIT,
+    })
     async startWrite(
         req: Request<RouteParams, null, SignedWriteRequest>,
-        res: Response<SignedWriteResponse>,
+        res: Response<ClientSignedWriteResponse>,
     ) {
         const userId = this.#getActorUserId(req);
         const storageAllowanceMax = this.#getStorageAllowanceMaxOverride(req);
@@ -156,13 +189,20 @@ export class FSController extends PuterController {
                 }
             }, 'emitStartWriteDirectoryEvents');
         }
-        res.json(response);
+        res.json(
+            this.#withoutStorageInternals(this.#withClientFsEntry(response)),
+        );
     }
 
-    @Post('/startBatchWrite', { subdomain: 'api', requireVerified: true })
+    @Post('/startBatchWrite', {
+        subdomain: 'api',
+        requireVerified: true,
+        requireCredits: true,
+        rateLimit: FS_MULTIPART_LIMIT,
+    })
     async startBatchWrites(
         req: Request<RouteParams, null, SignedWriteRequest[]>,
-        res: Response<SignedWriteResponse[]>,
+        res: Response<ClientSignedWriteResponse[]>,
     ) {
         const userId = this.#getActorUserId(req);
         const storageAllowanceMax = this.#getStorageAllowanceMaxOverride(req);
@@ -252,13 +292,22 @@ export class FSController extends PuterController {
                 }
             }, 'emitStartBatchWriteDirectoryEvents');
         }
-        res.json(responses);
+        res.json(
+            responses.map((r) =>
+                this.#withoutStorageInternals(this.#withClientFsEntry(r)),
+            ),
+        );
     }
 
-    @Post('/completeWrite', { subdomain: 'api', requireVerified: true })
+    @Post('/completeWrite', {
+        subdomain: 'api',
+        requireVerified: true,
+        requireCredits: true,
+        rateLimit: FS_MULTIPART_LIMIT,
+    })
     async completeWrite(
         req: Request<RouteParams, null, CompleteWriteRequest>,
-        res: Response<CompleteWriteResponse>,
+        res: Response<ClientCompleteWriteResponse>,
     ) {
         const userId = this.#getActorUserId(req);
         const requestBody = this.#withGuiMetadata(req.body, req.body);
@@ -278,13 +327,23 @@ export class FSController extends PuterController {
             },
             requestBody.guiMetadata,
         );
-        res.json({ ...response, fsEntry: writeResponse.fsEntry });
+        res.json(
+            this.#withRequiredClientFsEntry({
+                ...response,
+                fsEntry: writeResponse.fsEntry,
+            }),
+        );
     }
 
-    @Post('/completeBatchWrite', { subdomain: 'api', requireVerified: true })
+    @Post('/completeBatchWrite', {
+        subdomain: 'api',
+        requireVerified: true,
+        requireCredits: true,
+        rateLimit: FS_MULTIPART_LIMIT,
+    })
     async completeBatchWrites(
         req: Request<RouteParams, null, CompleteWriteRequest[]>,
-        res: Response<CompleteWriteResponse[]>,
+        res: Response<ClientCompleteWriteResponse[]>,
     ) {
         const userId = this.#getActorUserId(req);
         const requests = Array.isArray(req.body)
@@ -319,10 +378,16 @@ export class FSController extends PuterController {
                 return { ...writeResponse, fsEntry: withSideEffects.fsEntry };
             },
         );
-        res.json(updatedResponse);
+        res.json(
+            updatedResponse.map((r) => this.#withRequiredClientFsEntry(r)),
+        );
     }
 
-    @Post('/abortWrite', { subdomain: 'api', requireVerified: true })
+    @Post('/abortWrite', {
+        subdomain: 'api',
+        requireVerified: true,
+        rateLimit: FS_MULTIPART_LIMIT,
+    })
     async abortWrite(
         req: Request<RouteParams, null, AbortWriteRequest>,
         res: Response<{ ok: true }>,
@@ -338,23 +403,34 @@ export class FSController extends PuterController {
         res.json({ ok: true });
     }
 
-    @Post('/signMultipartParts', { subdomain: 'api', requireVerified: true })
+    @Post('/signMultipartParts', {
+        subdomain: 'api',
+        requireVerified: true,
+        requireCredits: true,
+        rateLimit: FS_MULTIPART_LIMIT,
+    })
     async signMultipartParts(
         req: Request<RouteParams, null, SignMultipartPartsRequest>,
-        res: Response<SignMultipartPartsResponse>,
+        res: Response<ClientSignMultipartPartsResponse>,
     ) {
         const userId = this.#getActorUserId(req);
         const response = await this.services.fs.signMultipartParts(
             userId,
             req.body,
         );
-        res.json(response);
+        res.json(this.#withoutStorageInternals(response));
     }
 
-    @Post('/write', { subdomain: 'api', requireVerified: true })
+    @Post('/write', {
+        subdomain: 'api',
+        requireVerified: true,
+        requireCredits: true,
+        rateLimit: FS_WRITE_LIMIT,
+        concurrent: FS_WRITE_CONCURRENT,
+    })
     async write(
         req: Request<RouteParams, null, WriteRequest>,
-        res: Response<WriteResponse>,
+        res: Response<ClientWriteResponse>,
     ) {
         const userId = this.#getActorUserId(req);
         const storageAllowanceMax = this.#getStorageAllowanceMaxOverride(req);
@@ -394,13 +470,19 @@ export class FSController extends PuterController {
             response,
             requestBody.guiMetadata,
         );
-        res.json(updatedResponse);
+        res.json(this.#withRequiredClientFsEntry(updatedResponse));
     }
 
-    @Post('/batchWrite', { subdomain: 'api', requireVerified: true })
+    @Post('/batchWrite', {
+        subdomain: 'api',
+        requireVerified: true,
+        requireCredits: true,
+        rateLimit: FS_WRITE_LIMIT,
+        concurrent: FS_WRITE_CONCURRENT,
+    })
     async batchWrites(
         req: Request<RouteParams, null, WriteRequest[]>,
-        res: Response<WriteResponse[]>,
+        res: Response<ClientWriteResponse[]>,
     ) {
         const userId = this.#getActorUserId(req);
         const storageAllowanceMax = this.#getStorageAllowanceMaxOverride(req);
@@ -413,6 +495,11 @@ export class FSController extends PuterController {
             let parseFailure: Error | null = null;
             const uploadPromises: Promise<UploadedBatchWriteItem | null>[] = [];
             const uploadedIndexes = new Set<number>();
+            // Manifest indexes are client-chosen and may skip values (an
+            // ignored `.DS_Store`, or a sparse numbering). `prepareBatchWrites`
+            // re-indexes by array position, so the two spaces have to be
+            // bridged explicitly or file parts get paired with the wrong item.
+            const preparedIndexByManifestIndex = new Map<number, number>();
             let fileOrderIndex = 0;
 
             const failParse = (error: unknown) => {
@@ -523,6 +610,12 @@ export class FSController extends PuterController {
                                 { pathAlreadyNormalized: true },
                             );
 
+                            activeManifestItems.forEach((item, position) => {
+                                preparedIndexByManifestIndex.set(
+                                    item.index,
+                                    position,
+                                );
+                            });
                             preparedBatch =
                                 await this.services.fs.prepareBatchWrites(
                                     userId,
@@ -595,9 +688,13 @@ export class FSController extends PuterController {
                         }
                         uploadedIndexes.add(itemIndex);
 
+                        const preparedIndex =
+                            preparedIndexByManifestIndex.get(itemIndex);
                         const preparedItem =
-                            preparedBatch.itemsByIndex.get(itemIndex);
-                        if (!preparedItem) {
+                            preparedIndex === undefined
+                                ? undefined
+                                : preparedBatch.itemsByIndex.get(preparedIndex);
+                        if (preparedIndex === undefined || !preparedItem) {
                             throw new HttpError(
                                 400,
                                 `Batch write metadata was not found for index ${itemIndex}`,
@@ -615,7 +712,7 @@ export class FSController extends PuterController {
 
                         return await this.services.fs.uploadPreparedBatchItem({
                             preparedBatch,
-                            itemIndex,
+                            itemIndex: preparedIndex,
                             fileContent: stream,
                             uploadTracker,
                         });
@@ -627,6 +724,12 @@ export class FSController extends PuterController {
                     }
                 })();
                 uploadPromises.push(uploadPromise);
+                // Failures are collected with `Promise.allSettled` once
+                // parsing finishes, which is many ticks away — attach an
+                // inert handler now so an immediate rejection (e.g. a file
+                // part arriving before the manifest) isn't reported as an
+                // unhandled rejection in the meantime.
+                void uploadPromise.catch(() => undefined);
             });
 
             const parsingComplete = new Promise<void>((resolve, reject) => {
@@ -636,6 +739,18 @@ export class FSController extends PuterController {
 
             req.pipe(busboy);
             await parsingComplete;
+            // A manifest that failed to parse never sets
+            // `manifestPreparationPromise`, so surface the real reason
+            // (invalid JSON, bad item index, duplicate index → 409) before
+            // falling back to "no manifest was sent at all". Scoped to that
+            // case on purpose: with no prepared batch nothing can have been
+            // uploaded, so there is nothing to clean up. A parse failure that
+            // arrives *after* a manifest was accepted has to fall through to
+            // the cleanup path below, which sweeps objects already in storage.
+            if (parseFailure && !manifestPreparationPromise) {
+                await Promise.allSettled(uploadPromises);
+                throw parseFailure;
+            }
             if (!manifestPreparationPromise) {
                 await Promise.allSettled(uploadPromises);
                 throw new HttpError(400, 'Batch write manifest is required', {
@@ -702,7 +817,9 @@ export class FSController extends PuterController {
                     );
                 },
             );
-            res.json(updatedResponses);
+            res.json(
+                updatedResponses.map((r) => this.#withRequiredClientFsEntry(r)),
+            );
             return;
         }
 
@@ -822,12 +939,18 @@ export class FSController extends PuterController {
                 );
             },
         );
-        res.json(updatedResponses);
+        res.json(
+            updatedResponses.map((r) => this.#withRequiredClientFsEntry(r)),
+        );
     }
 
     // -- Read-side routes ------------------------------------------------
 
-    @Post('/stat', { subdomain: 'api', requireVerified: true })
+    @Post('/stat', {
+        subdomain: 'api',
+        requireVerified: true,
+        rateLimit: FS_STAT_LIMIT,
+    })
     async statEntry(req: Request, res: Response) {
         const actor = this.#requireActor(req);
         const userId = this.#getActorUserId(req);
@@ -845,17 +968,143 @@ export class FSController extends PuterController {
             await this.services.suggestedApps.getSuggestedApps(entry);
 
         res.json({
-            ...entry,
+            ...this.#toClientEntry(entry),
             ...(subtreeSize !== undefined ? { size: subtreeSize } : {}),
         });
     }
 
-    @Post('/readdir', { subdomain: 'api', requireVerified: true })
+    /**
+     * Strip backend-internal fields before returning an entry to a client.
+     * Storage location (bucket/region), the owner's numeric id, and the
+     * capability-token columns are never used by clients and must not leak to
+     * callers who only hold `see`/`list` on the entry — a share recipient, or
+     * (with public folders enabled) any authenticated user. The legacy read
+     * path already curates its output; this does the same for the v2 routes.
+     */
+    #toClientEntry(entry: FSEntry): ClientFSEntry {
+        // Allowlist, not a denylist: a denylist silently ships every column
+        // added to `fsentries` later. Omits the numeric primary keys (`id`,
+        // `parentId`, `associatedAppId`), the storage columns, the owning
+        // `userId`, and the `publicToken`/`fileRequestToken` capability tokens.
+        //
+        // Tolerant of partially-hydrated entries: write/mkdir paths return a
+        // freshly-built entry that hasn't been through a subdomain join.
+        const subdomains = entry.subdomains ?? [];
+        return {
+            uuid: entry.uuid,
+            uid: entry.uid ?? entry.uuid,
+            parentUid: entry.parentUid ?? null,
+            path: entry.path,
+            name: entry.name,
+            isDir: entry.isDir,
+            isShortcut: entry.isShortcut,
+            shortcutTo: entry.shortcutTo ?? null,
+            isSymlink: entry.isSymlink,
+            symlinkPath: entry.symlinkPath ?? null,
+            isPublic: entry.isPublic ?? null,
+            immutable: entry.immutable,
+            metadata: entry.metadata ?? null,
+            modified: entry.modified,
+            created: entry.created ?? null,
+            accessed: entry.accessed ?? null,
+            size: entry.size ?? null,
+            layout: entry.layout ?? null,
+            subdomains,
+            workers: entry.workers ?? [],
+            hasWebsite: entry.hasWebsite ?? subdomains.length > 0,
+            suggestedApps: entry.suggestedApps ?? [],
+        };
+    }
+
+    /**
+     * Sanitize the `fsEntry` a write response carries, leaving the rest of the
+     * envelope (session id, presigned upload targets) untouched — those fields
+     * are the point of the response. Applied at every `res.json` on the write
+     * paths, which previously serialized the raw database row.
+     *
+     * The return type is the sanitized counterpart, so a caller cannot keep
+     * treating the result as though it still held a full `FSEntry`.
+     */
+    #withClientFsEntry<T extends { fsEntry?: FSEntry }>(
+        response: T,
+    ): Omit<T, 'fsEntry'> & { fsEntry?: ClientFSEntry } {
+        const { fsEntry, ...rest } = response;
+        return {
+            ...rest,
+            ...(fsEntry ? { fsEntry: this.#toClientEntry(fsEntry) } : {}),
+        };
+    }
+
+    /**
+     * Drop the storage internals from a presigned-upload envelope. The client
+     * uploads to the presigned URLs, which already encode bucket and key, so
+     * naming the physical location of a user's bytes buys the caller nothing.
+     */
+    #withoutStorageInternals<
+        T extends { bucket: string; bucketRegion: string; objectKey: string },
+    >(response: T): Omit<T, 'bucket' | 'bucketRegion' | 'objectKey'> {
+        const { bucket, bucketRegion, objectKey, ...rest } = response;
+        return rest;
+    }
+
+    /** Same, for the responses whose `fsEntry` is always present. */
+    #withRequiredClientFsEntry<T extends { fsEntry: FSEntry }>(
+        response: T,
+    ): Omit<T, 'fsEntry'> & { fsEntry: ClientFSEntry } {
+        return {
+            ...response,
+            fsEntry: this.#toClientEntry(response.fsEntry),
+        };
+    }
+
+    /**
+     * `GET /fs/readdir` — same contract as the POST form, with parameters in
+     * the query string instead of the body. A read as a GET is cacheable and
+     * can authenticate via `?auth_token=`, which lets callers fetch a listing
+     * without a JSON body. Every value arrives as a string, so parameter
+     * parsing goes through the same coercion helpers the POST path uses.
+     */
+    @Get('/readdir', {
+        subdomain: 'api',
+        requireVerified: true,
+        rateLimit: FS_READDIR_LIMIT,
+    })
+    async readdirEntriesViaGet(req: Request, res: Response) {
+        return this.readdirEntries(req, res);
+    }
+
+    @Post('/readdir', {
+        subdomain: 'api',
+        requireVerified: true,
+        rateLimit: FS_READDIR_LIMIT,
+    })
     async readdirEntries(req: Request, res: Response) {
         const actor = this.#requireActor(req);
-        const body = this.#toObjectRecord(req.body);
+        // GET carries its parameters in the query string; POST in the body.
+        const body = this.#toObjectRecord(
+            req.method === 'GET' ? req.query : req.body,
+        );
+
+        // Presence of `cursor` (null/empty means "first page") or
+        // `includeTotal` opts into the paginated `{items, cursor?, total?}`
+        // envelope. Legacy limit/offset requests keep the bare-array response.
+        const includeTotal = this.#toBoolean(body.includeTotal) === true;
+        const paginated =
+            Object.prototype.hasOwnProperty.call(body, 'cursor') ||
+            includeTotal;
+
+        // Undocumented: `recursive` lists descendants (prefix scan) up to
+        // `depth` levels below the target. Always paginated; sorts by path.
+        const recursive = this.#toBoolean(body.recursive) === true;
 
         if (this.#isRootPathRef(body)) {
+            if (recursive) {
+                throw new HttpError(
+                    400,
+                    'recursive listing is not supported at the root',
+                    { legacyCode: 'bad_request' },
+                );
+            }
             const { listRootEntries } =
                 await import('../../services/fs/rootListing.js');
             const rootChildren = await listRootEntries(
@@ -873,57 +1122,163 @@ export class FSController extends PuterController {
                     child.suggestedApps = rootSuggestions[index] ?? [];
                 }
             }
-            res.json(rootChildren);
+            const rootItems = await this.#toReaddirEntries(rootChildren);
+            if (paginated) {
+                res.json({
+                    items: rootItems,
+                    ...(includeTotal ? { total: rootItems.length } : {}),
+                });
+                return;
+            }
+            res.json(rootItems);
             return;
         }
 
         const parent = await this.#resolveEntryForRequest(body);
         if (!parent.isDir) {
             throw new HttpError(400, 'Target is not a directory', {
-                legacyCode: 'bad_request',
+                legacyCode: 'dest_is_not_a_directory',
             });
         }
-        await this.#assertAccess(actor, parent.path, 'list');
+        // Use the legacy access assertion so this endpoint stays behaviorally
+        // identical to the `/readdir` route the SDK moved off of — same error
+        // codes and the same app-actor 404 masking on denial.
+        await assertLegacyAccess(
+            this.services.acl,
+            this.services.fs,
+            actor,
+            parent.path,
+            'list',
+        );
 
         const limit = this.#toNumberOrUndefined(body.limit);
         const offset = this.#toNumberOrUndefined(body.offset);
         const sortByRaw =
-            typeof body.sort_by === 'string'
-                ? body.sort_by.toLowerCase()
+            typeof (body.sortBy ?? body.sort_by) === 'string'
+                ? String(body.sortBy ?? body.sort_by).toLowerCase()
                 : undefined;
         const sortBy =
             (['name', 'modified', 'type', 'size'] as const).find(
                 (v) => v === sortByRaw,
             ) ?? null;
         const sortOrderRaw =
-            typeof body.sort_order === 'string'
-                ? body.sort_order.toLowerCase()
+            typeof (body.sortOrder ?? body.sort_order) === 'string'
+                ? String(body.sortOrder ?? body.sort_order).toLowerCase()
                 : undefined;
         const sortOrder =
             (['asc', 'desc'] as const).find((v) => v === sortOrderRaw) ?? null;
 
+        if (recursive) {
+            const requestedDepth = this.#toNumberOrUndefined(body.depth);
+            const maxDepth = Math.min(
+                MAX_READDIR_DEPTH,
+                Math.max(1, Math.floor(requestedDepth ?? MAX_READDIR_DEPTH)),
+            );
+            const page = await this.services.fs.listDirectoryTreePage(
+                parent.userId,
+                parent.path,
+                {
+                    limit,
+                    cursor:
+                        typeof body.cursor === 'string'
+                            ? body.cursor
+                            : undefined,
+                    maxDepth,
+                },
+            );
+            await this.#attachSuggestedApps(page.entries);
+            const total = includeTotal
+                ? await this.services.fs.countDirectoryTree(
+                      parent.userId,
+                      parent.path,
+                      maxDepth,
+                  )
+                : undefined;
+            res.json({
+                items: await this.#toReaddirEntries(page.entries),
+                ...(page.cursor ? { cursor: page.cursor } : {}),
+                ...(total !== undefined ? { total } : {}),
+            });
+            return;
+        }
+
+        if (paginated) {
+            const page = await this.services.fs.listDirectoryPage(parent.uuid, {
+                limit,
+                cursor:
+                    typeof body.cursor === 'string' ? body.cursor : undefined,
+                sortBy,
+                sortOrder,
+            });
+            await this.#attachSuggestedApps(page.entries);
+            const total = includeTotal
+                ? await this.services.fs.countDirectory(parent.uuid)
+                : undefined;
+            res.json({
+                items: await this.#toReaddirEntries(page.entries),
+                ...(page.cursor ? { cursor: page.cursor } : {}),
+                ...(total !== undefined ? { total } : {}),
+            });
+            return;
+        }
+
         const children = await this.services.fs.listDirectory(parent.uuid, {
             limit,
             offset,
             sortBy,
             sortOrder,
         });
+        await this.#attachSuggestedApps(children);
+        res.json(await this.#toReaddirEntries(children));
+    }
 
+    /**
+     * Shape readdir entries in the v2 (camelCase) response shape, enriched with
+     * the three fields the SDK cannot reconstruct on its own so it can rebuild
+     * the v1 shape: `type` (MIME), a signed `thumbnail`, and `associatedApp`.
+     */
+    async #toReaddirEntries(entries: FSEntry[]): Promise<ClientReaddirEntry[]> {
+        const appsById = await loadLegacyAssociatedApps(
+            this.stores.app,
+            entries,
+        );
+        return Promise.all(
+            entries.map(async (entry) => ({
+                ...this.#toClientEntry(entry),
+                // Fields the client cannot derive on its own.
+                type: fsEntryMimeType(entry),
+                thumbnail: await signEntryThumbnail(
+                    this.clients.event,
+                    entry.uuid,
+                    entry.thumbnail,
+                ),
+                associatedApp:
+                    entry.associatedAppId !== null
+                        ? (appsById.get(entry.associatedAppId) ?? null)
+                        : null,
+            })),
+        );
+    }
+
+    async #attachSuggestedApps(entries: FSEntry[]): Promise<void> {
         const suggestions =
             await this.services.suggestedApps.getSuggestedAppsForEntries(
-                children,
+                entries,
             );
-        for (let index = 0; index < children.length; index++) {
-            const child = children[index];
+        for (let index = 0; index < entries.length; index++) {
+            const child = entries[index];
             if (child) {
                 child.suggestedApps = suggestions[index] ?? [];
             }
         }
-
-        res.json(children);
     }
 
-    @Post('/search', { subdomain: 'api', requireVerified: true })
+    @Post('/search', {
+        subdomain: 'api',
+        requireVerified: true,
+        rateLimit: FS_SEARCH_LIMIT,
+        concurrent: FS_SEARCH_CONCURRENT,
+    })
     async searchEntries(req: Request, res: Response) {
         const actor = this.#requireActor(req);
         const userId = this.#getActorUserId(req);
@@ -949,7 +1304,13 @@ export class FSController extends PuterController {
         res.json(results);
     }
 
-    @Get('/read', { subdomain: 'api', requireVerified: true })
+    @Get('/read', {
+        subdomain: 'api',
+        requireVerified: true,
+        requireCredits: true,
+        rateLimit: FS_READ_LIMIT,
+        concurrent: FS_READ_CONCURRENT,
+    })
     async readEntry(req: Request, res: Response) {
         const actor = this.#requireActor(req);
         const query = this.#toObjectRecord(req.query);
@@ -993,15 +1354,6 @@ export class FSController extends PuterController {
         );
         res.status(range ? 206 : 200);
 
-        const metering = this.services.metering as
-            | {
-                  batchIncrementUsages?: (
-                      actor: unknown,
-                      entries: unknown[],
-                  ) => void;
-              }
-            | undefined;
-
         try {
             await pipeline(download.body, res);
         } catch {
@@ -1009,28 +1361,15 @@ export class FSController extends PuterController {
             // tore down both ends. Response is partially sent; nothing to do.
             return;
         }
-
-        // Meter egress only on successful completion.
-        if (metering?.batchIncrementUsages && download.contentLength) {
-            try {
-                const bytes = download.contentLength;
-                metering.batchIncrementUsages(actor, [
-                    {
-                        usageType: 'filesystem:egress:bytes',
-                        usageAmount: bytes,
-                        costOverride:
-                            FS_COSTS['filesystem:egress:bytes'] * bytes,
-                    },
-                ]);
-            } catch {
-                // ignore — metering is non-critical.
-            }
-        }
     }
 
     // -- Mutation routes ------------------------------------------------
 
-    @Post('/mkdir', { subdomain: 'api', requireVerified: true })
+    @Post('/mkdir', {
+        subdomain: 'api',
+        requireVerified: true,
+        rateLimit: FS_MUTATE_LIMIT,
+    })
     async mkdirEntry(req: Request, res: Response) {
         const actor = this.#requireActor(req);
         const userId = this.#getActorUserId(req);
@@ -1068,10 +1407,14 @@ export class FSController extends PuterController {
                 ) ?? false,
         });
         this.#emitGuiItemAdded(entry);
-        res.json(entry);
+        res.json(this.#toClientEntry(entry));
     }
 
-    @Post('/touch', { subdomain: 'api', requireVerified: true })
+    @Post('/touch', {
+        subdomain: 'api',
+        requireVerified: true,
+        rateLimit: FS_MUTATE_LIMIT,
+    })
     async touchEntry(req: Request, res: Response) {
         const actor = this.#requireActor(req);
         const userId = this.#getActorUserId(req);
@@ -1104,10 +1447,14 @@ export class FSController extends PuterController {
             createMissingParents:
                 this.#toBoolean(body.create_missing_parents) ?? false,
         });
-        res.json(entry);
+        res.json(this.#toClientEntry(entry));
     }
 
-    @Post('/rename', { subdomain: 'api', requireVerified: true })
+    @Post('/rename', {
+        subdomain: 'api',
+        requireVerified: true,
+        rateLimit: FS_MUTATE_LIMIT,
+    })
     async renameEntry(req: Request, res: Response) {
         const actor = this.#requireActor(req);
         const body = this.#toObjectRecord(req.body);
@@ -1122,10 +1469,14 @@ export class FSController extends PuterController {
 
         const renamed = await this.services.fs.rename(entry, newName);
         this.#emitGuiItemUpdated(renamed);
-        res.json(renamed);
+        res.json(this.#toClientEntry(renamed));
     }
 
-    @Post('/delete', { subdomain: 'api', requireVerified: true })
+    @Post('/delete', {
+        subdomain: 'api',
+        requireVerified: true,
+        rateLimit: FS_MUTATE_LIMIT,
+    })
     async deleteEntry(req: Request, res: Response) {
         const actor = this.#requireActor(req);
         const userId = this.#getActorUserId(req);
@@ -1143,7 +1494,11 @@ export class FSController extends PuterController {
         res.json({ ok: true });
     }
 
-    @Post('/move', { subdomain: 'api', requireVerified: true })
+    @Post('/move', {
+        subdomain: 'api',
+        requireVerified: true,
+        rateLimit: FS_MUTATE_LIMIT,
+    })
     async moveEntry(req: Request, res: Response) {
         const actor = this.#requireActor(req);
         const userId = this.#getActorUserId(req);
@@ -1168,10 +1523,15 @@ export class FSController extends PuterController {
                 this.#toBoolean(body.dedupe_name ?? body.change_name) ?? false,
         });
         this.#emitGuiItemMoved(source, moved);
-        res.json(moved);
+        res.json(this.#toClientEntry(moved));
     }
 
-    @Post('/copy', { subdomain: 'api', requireVerified: true })
+    @Post('/copy', {
+        subdomain: 'api',
+        requireVerified: true,
+        requireCredits: true,
+        rateLimit: FS_MUTATE_LIMIT,
+    })
     async copyEntry(req: Request, res: Response) {
         const actor = this.#requireActor(req);
         const userId = this.#getActorUserId(req);
@@ -1186,6 +1546,7 @@ export class FSController extends PuterController {
         await this.#assertAccess(actor, source.path, 'read');
         await this.#assertAccess(actor, destinationParent.path, 'write');
 
+        const storageAllowanceMax = this.#getStorageAllowanceMaxOverride(req);
         const copy = await this.services.fs.copy(userId, {
             source,
             destinationParent,
@@ -1194,12 +1555,19 @@ export class FSController extends PuterController {
             overwrite: this.#toBoolean(body.overwrite) ?? false,
             dedupeName:
                 this.#toBoolean(body.dedupe_name ?? body.change_name) ?? true,
+            ...(storageAllowanceMax !== undefined
+                ? { storageAllowanceMax }
+                : {}),
         });
         this.#emitGuiItemAdded(copy);
-        res.json(copy);
+        res.json(this.#toClientEntry(copy));
     }
 
-    @Post('/mkshortcut', { subdomain: 'api', requireVerified: true })
+    @Post('/mkshortcut', {
+        subdomain: 'api',
+        requireVerified: true,
+        rateLimit: FS_MUTATE_LIMIT,
+    })
     async mkshortcutEntry(req: Request, res: Response) {
         const actor = this.#requireActor(req);
         const userId = this.#getActorUserId(req);
@@ -1225,7 +1593,7 @@ export class FSController extends PuterController {
             dedupeName: this.#toBoolean(body.dedupe_name) ?? true,
         });
         this.#emitGuiItemAdded(shortcut);
-        res.json(shortcut);
+        res.json(this.#toClientEntry(shortcut));
     }
 
     // -- Read-side helpers -----------------------------------------------
@@ -1280,12 +1648,12 @@ export class FSController extends PuterController {
     }
 
     /**
-     * Authorize creation of a new entry at `targetPath`. The standard rule
-     * is write on the parent, but we also accept write on the target itself
-     * — this lets an app create its own `/<user>/AppData/<app_uid>` folder
-     * (parent `AppData` is off-limits, but the target is the app's own
-     * subtree per ACLService's short-circuit) and lets recipients of a
-     * direct share on a not-yet-existent path materialize it.
+     * Authorize creation of a new entry at `targetPath`. The standard rule is
+     * write on the parent, but we also accept write on the target itself — this
+     * lets an app create its own `/<user>/AppData/<app_uid>` folder (parent
+     * `AppData` is off-limits, but the target is the app's own subtree per
+     * ACLService's short-circuit) and lets recipients of a direct share on a
+     * not-yet-existent path materialize it.
      */
     async #assertCanCreate(actor: Actor, targetPath: string) {
         const parent = pathPosix.dirname(targetPath);
@@ -1763,13 +2131,13 @@ export class FSController extends PuterController {
 
     /**
      * Bind `associatedAppId` onto the write input only when the actor is
-     * entitled to reference that app. `associatedAppId` is client-supplied
-     * and never trusted for authz, but it's echoed back in legacy FS
-     * responses — so an attacker could plant another tenant's private app id
-     * to confirm the row exists (an enumeration oracle) and harvest its
-     * metadata. Allow binding to public apps (their existence isn't secret)
-     * or to apps the actor owns; drop the association otherwise so the file
-     * simply carries no associated app.
+     * entitled to reference that app. `associatedAppId` is client-supplied and
+     * never trusted for authz, but it's echoed back in legacy FS responses — so
+     * an attacker could plant another tenant's private app id to confirm the
+     * row exists (an enumeration oracle) and harvest its metadata. Allow
+     * binding to public apps (their existence isn't secret) or to apps the
+     * actor owns; drop the association otherwise so the file simply carries no
+     * associated app.
      *
      * `#resolveWriteFileMetadata` has already copied the raw client value onto
      * `fileMetadata`, so a dropped association must be actively stripped — not
@@ -1810,8 +2178,7 @@ export class FSController extends PuterController {
         // the ActorUser type. Access via the escape hatch until a proper
         // storage-quota mechanism is in place.
         const actorUser = req.actor?.user as
-            | Record<string, unknown>
-            | undefined;
+            Record<string, unknown> | undefined;
 
         const candidates = [
             this.#toStorageCapacityCandidate(actorUser?.free_storage),
@@ -2156,7 +2523,7 @@ export class FSController extends PuterController {
     // search results to this path so app actors can't see entries outside
     // their AppData via `/fs/search`.
     #appDataScopeForActor(actor: Actor): string | undefined {
-        const app = effectiveActorApp(actor);
+        const app = actor.effectiveApp;
         if (!app) return undefined;
         const username = actor.user?.username;
         if (typeof username !== 'string' || username.length === 0)