chore: bump version (#3461)

* fix: centralize module methods in parent class

* fix: performance degradations in app fetching

.github/workflows/backend-tests.yaml

@@ -1,10 +1,19 @@
 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'
+      - '.github/workflows/backend-tests.yaml'
 
 permissions:
   contents: read

.github/workflows/puterjs-tests.yaml

@@ -0,0 +1,145 @@
+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:
+  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,8 @@ 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/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,70 +18,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 before inventing them.** Search for an existing type first; extend it if close. Only define a new type when nothing fits.
-- **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.
-
-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
 
@@ -94,6 +47,106 @@ 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.js`, `ai/`, …), shared plumbing in [src/puter-js/src/lib/](src/puter-js/src/lib/), hand-maintained type declarations in [src/puter-js/types/](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. Reference the hand-maintained declarations in [src/puter-js/types/](src/puter-js/types/) with `import(...)` types rather than re-declaring shapes:
+
+```js
+/** @typedef {import('../../types/modules/ai').ChatOptions} ChatOptions */
+
+/** @type {ChatOptions} */
+const options = { model: 'gpt-5-nano' };
+```
+
+When a shape only exists locally, declare it as an inline object literal — not the `@typedef {Object}` + `@property` list form — and use `unknown` over `*`:
+
+```js
+/** @typedef {{ key: string, value: unknown }} KVEntry */
+```
+
+Public (exposed) methods must carry JSDoc types — parameters and return value, matching the `.d.ts` declarations exactly. Unexposed/private helpers are typed at the contributor's discretion: annotate where it helps the next reader, and either way keep them clean.
+
+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.** Update [src/puter-js/types/modules/](src/puter-js/types/modules/)`<module>.d.ts` and re-export new types through `index.d.ts` / `types/puter.d.ts`. 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.

CLAUDE.md

@@ -0,0 +1 @@
+FOLLOW ./AGENTS.md

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
 

config.default.json

@@ -23,6 +23,7 @@
     "default_user_group": "78b1b1dd-c959-44d2-b02c-8735671f9997",
     "default_temp_group": "b7220104-7905-4985-b996-649fdcdb3c8f",
     "storage_capacity": 104857600,
+    "disable_user_signup": false,
     "strict_email_verification_required": false,
     "gui_assets_root": "./src/gui",
     "puterjs_root": "./src/puter-js/dist",

config.template.jsonc

@@ -16,6 +16,12 @@
     // `dev` opens a browser on boot, skips blocked-email checks, and runs the
     // dev-time webpack watcher; `prod` serves pre-built bundles.
     "env": "dev",
+    // Console output format. `json` replaces the global console so every call
+    // emits one structured JSON line (level, timestamp, msg, and the active
+    // request's trace id) — one event per call, so a line-oriented log
+    // collector can't split stack traces across events and level filtering
+    // works. Unset (the default) leaves console output human-readable.
+    "log_format": "text",
     "version": "0.0.0",
     // Stable identity for this server node — used by pager alerts and
     // graceful-shutdown coordination.
@@ -75,6 +81,9 @@
     "url_signature_secret": "change-me",
     "cookie_name": "puter_auth_token",
     "min_pass_length": 6,
+    // When true, anonymous users must log in instead of creating temp or
+    // permanent accounts.
+    "disable_user_signup": false,
     "allow_system_login": false,
     "strict_email_verification_required": false,
     "captcha": {
@@ -278,6 +287,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
@@ -316,6 +329,7 @@
             "secret_key": "",
             "region": "us-west-2"
         },
+        "speechify": { "apiKey": "" },
         "aws-textract": {
             "access_key": "",
             "secret_key": "",

doc/contributing-apis.md

@@ -0,0 +1,108 @@
+# 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.
+
+### 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
+
+- Add or extend the declaration in [src/puter-js/types/modules/](../src/puter-js/types/modules/)`<module>.d.ts` and re-export new types through `index.d.ts`. Declarations must match the runtime exactly — optionality, defaults, and return types included.
+
+### 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

@@ -135,7 +135,7 @@ 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.
-- `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.
+- `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.
@@ -379,6 +379,15 @@ Built-in proof-of-work captcha — no external service needed.
 
 `difficulty` is one of `easy` / `medium` / `hard`.
 
+### Disable new signups
+
+Force visitors to log in with an existing account instead of creating a
+temporary or permanent one.
+
+```json
+"disable_user_signup": true
+```
+
 ### Block disposable email TLDs
 
 Only enforced when `env: "prod"`.

extensions/appTelemetry.test.ts

@@ -1,75 +1,92 @@
-import type { Request, Response } from 'express';
 import { v4 as uuidv4 } from 'uuid';
-import {
-    afterAll,
-    beforeAll,
-    describe,
-    expect,
-    it,
-    vi,
-} from 'vitest';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import { runWithContext } from '../src/backend/core/context.ts';
 import { PuterServer } from '../src/backend/server.ts';
 import { setupTestServer } from '../src/backend/testUtil.ts';
-import {
-    handleAppTelemetryUserCount,
-    handleAppTelemetryUsers,
-} from './appTelemetry.ts';
-
-interface CapturedResponse {
-    body: unknown;
-}
-
-const makeReq = (query: Record<string, unknown> = {}): Request =>
-    ({ query }) as unknown as Request;
-
-const makeRes = () => {
-    const captured: CapturedResponse = { body: undefined };
-    const res = {
-        json: vi.fn((value: unknown) => {
-            captured.body = value;
-            return res;
-        }),
-        status: vi.fn(() => res),
-    };
-    return { res: res as unknown as Response, captured };
-};
-
-// `handleAppTelemetryUsers` calls `Context.get('actor')` for the permission
-// gate. Wrap test calls in `runWithContext` so the ALS lookup resolves.
-const callWithActor = async (
-    actor: { user: { uuid: string; id?: number }; app?: null } | undefined,
-    fn: () => Promise<void>,
-) => runWithContext({ actor }, fn);
+// Importing the module registers the `appTelemetry` driver into the shared
+// extensionStore, so `setupTestServer` instantiates it on `server.drivers`.
+import { AppTelemetryDriver } from './appTelemetry.ts';
 
 let server: PuterServer;
+let driver: AppTelemetryDriver;
+
+// `get_users` reads `Context.get('actor')` for the ownership gate. Wrap
+// actor-dependent calls in `runWithContext` so the ALS lookup resolves.
+const callWithActor = <T>(
+    actor: { user: { uuid: string; id?: number } } | undefined,
+    fn: () => Promise<T>,
+) => runWithContext({ actor }, fn);
 
 beforeAll(async () => {
     server = await setupTestServer();
+    driver = (server.drivers as unknown as Record<string, AppTelemetryDriver>)
+        .appTelemetry;
+    // Guard: the driver must have been wired onto the server. If this is
+    // undefined the extension didn't register, and every test below would
+    // fail with a confusing "cannot read property of undefined".
+    expect(driver).toBeInstanceOf(AppTelemetryDriver);
 });
 
 afterAll(async () => {
-    await server.shutdown();
+    await server?.shutdown();
 });
 
-describe('appTelemetry extension — handleAppTelemetryUsers', () => {
+const seedOwnedApp = async (prefix: string) => {
+    const owner = await server.stores.user.create({
+        username: `${prefix}_${Math.random().toString(36).slice(2, 8)}`,
+        uuid: uuidv4(),
+        password: 'x',
+        email: null,
+    });
+    const slug = Math.random().toString(36).slice(2, 8);
+    const app = await server.stores.app.create(
+        {
+            name: `${prefix}_${slug}`,
+            title: `${prefix} ${slug}`,
+            index_url: `https://example.com/${slug}`,
+        },
+        { ownerUserId: owner.id as number },
+    );
+    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 () => {
-        const { res } = makeRes();
-        await expect(
-            handleAppTelemetryUsers(makeReq({}), res),
-        ).rejects.toMatchObject({
+        await expect(driver.get_users({})).rejects.toMatchObject({
             statusCode: 400,
             message: expect.stringContaining('app_uuid'),
         });
     });
 
     it('throws HttpError(400) for a non-numeric limit', async () => {
-        const { res } = makeRes();
         await expect(
-            handleAppTelemetryUsers(
-                makeReq({ app_uuid: 'app-anything', limit: 'banana' }),
-                res,
-            ),
+            driver.get_users({ app_uuid: 'app-anything', limit: 'banana' }),
         ).rejects.toMatchObject({
             statusCode: 400,
             message: expect.stringContaining('limit'),
@@ -77,22 +94,14 @@ describe('appTelemetry extension — handleAppTelemetryUsers', () => {
     });
 
     it('throws HttpError(400) when offset exceeds the allowed maximum', async () => {
-        const { res } = makeRes();
         await expect(
-            handleAppTelemetryUsers(
-                makeReq({ app_uuid: 'app-anything', offset: 1_000_001 }),
-                res,
-            ),
+            driver.get_users({ app_uuid: 'app-anything', offset: 1_000_001 }),
         ).rejects.toMatchObject({ statusCode: 400 });
     });
 
     it('throws HttpError(404) when the app cannot be found', async () => {
-        const { res } = makeRes();
         await expect(
-            handleAppTelemetryUsers(
-                makeReq({ app_uuid: 'app-does-not-exist' }),
-                res,
-            ),
+            driver.get_users({ app_uuid: 'app-does-not-exist' }),
         ).rejects.toMatchObject({
             statusCode: 404,
             message: 'App not found',
@@ -100,25 +109,10 @@ describe('appTelemetry extension — handleAppTelemetryUsers', () => {
     });
 
     it('throws HttpError(403) when the caller does not own the app', async () => {
-        // Seed an owner user + an app belonging to them, then call the
-        // handler as a *different* user. The real permission service should
-        // reject since the caller has no `apps-of-user:<owner>:write` perm.
-        const owner = await server.stores.user.create({
-            username: `owner_${Math.random().toString(36).slice(2, 8)}`,
-            uuid: uuidv4(),
-            password: 'x',
-            email: null,
-        });
-        const slug = Math.random().toString(36).slice(2, 8);
-        const app = await server.stores.app.create(
-            {
-                name: `app_${slug}`,
-                title: `App ${slug}`,
-                index_url: `https://example.com/${slug}`,
-            },
-            { ownerUserId: owner.id as number },
-        );
-
+        // Seed an owner + their app, then call as a *different* user. The
+        // real permission service should reject: the caller has no
+        // `apps-of-user:<owner>:write`.
+        const { app } = await seedOwnedApp('owner');
         const intruder = await server.stores.user.create({
             username: `intruder_${Math.random().toString(36).slice(2, 8)}`,
             uuid: uuidv4(),
@@ -126,15 +120,11 @@ describe('appTelemetry extension — handleAppTelemetryUsers', () => {
             email: null,
         });
 
-        const { res } = makeRes();
         await callWithActor(
             { user: { uuid: intruder.uuid, id: intruder.id as number } },
             async () => {
                 await expect(
-                    handleAppTelemetryUsers(
-                        makeReq({ app_uuid: app!.uid }),
-                        res,
-                    ),
+                    driver.get_users({ app_uuid: app.uid }),
                 ).rejects.toMatchObject({
                     statusCode: 403,
                     message: 'Permission denied',
@@ -144,78 +134,92 @@ describe('appTelemetry extension — handleAppTelemetryUsers', () => {
     });
 
     it('returns an empty list for an owned app with no authenticated users', async () => {
-        const owner = await server.stores.user.create({
-            username: `owner2_${Math.random().toString(36).slice(2, 8)}`,
-            uuid: uuidv4(),
-            password: 'x',
-            email: null,
-        });
-        const slug = Math.random().toString(36).slice(2, 8);
-        const app = await server.stores.app.create(
-            {
-                name: `app2_${slug}`,
-                title: `App2 ${slug}`,
-                index_url: `https://example.com/${slug}`,
-            },
-            { ownerUserId: owner.id as number },
-        );
+        const { owner, app } = await seedOwnedApp('owner2');
 
-        const { res, captured } = makeRes();
-        await callWithActor(
+        const result = await callWithActor(
             { user: { uuid: owner.uuid, id: owner.id as number } },
-            async () => {
-                await handleAppTelemetryUsers(
-                    makeReq({ app_uuid: app!.uid }),
-                    res,
-                );
-            },
+            () => driver.get_users({ app_uuid: app.uid }),
         );
 
-        expect(captured.body).toEqual([]);
+        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 extension — handleAppTelemetryUserCount', () => {
+describe('appTelemetry driver — user_count', () => {
     it('throws HttpError(400) when app_uuid is missing', async () => {
-        const { res } = makeRes();
-        await expect(
-            handleAppTelemetryUserCount(makeReq({}), res),
-        ).rejects.toMatchObject({ statusCode: 400 });
+        await expect(driver.user_count({})).rejects.toMatchObject({
+            statusCode: 400,
+        });
     });
 
     it('throws HttpError(404) for an unknown app_uuid', async () => {
-        const { res } = makeRes();
         await expect(
-            handleAppTelemetryUserCount(
-                makeReq({ app_uuid: 'app-not-here' }),
-                res,
-            ),
+            driver.user_count({ app_uuid: 'app-not-here' }),
         ).rejects.toMatchObject({ statusCode: 404 });
     });
 
-    it('returns { count: 0 } for an app with no authenticated users', async () => {
-        const owner = await server.stores.user.create({
-            username: `counto_${Math.random().toString(36).slice(2, 8)}`,
-            uuid: uuidv4(),
-            password: 'x',
-            email: null,
-        });
-        const slug = Math.random().toString(36).slice(2, 8);
-        const app = await server.stores.app.create(
-            {
-                name: `appcount_${slug}`,
-                title: `AppCount ${slug}`,
-                index_url: `https://example.com/${slug}`,
-            },
-            { ownerUserId: owner.id as number },
-        );
-
-        const { res, captured } = makeRes();
-        await handleAppTelemetryUserCount(
-            makeReq({ app_uuid: app!.uid }),
-            res,
-        );
-
-        expect(captured.body).toEqual({ count: 0 });
+    it('returns 0 for an app with no authenticated users', async () => {
+        const { app } = await seedOwnedApp('appcount');
+        await expect(driver.user_count({ app_uuid: app.uid })).resolves.toBe(0);
     });
 });

extensions/appTelemetry.ts

@@ -1,11 +1,16 @@
-import type { Request, Response } from 'express';
 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 { extension } from '@heyputer/backend/src/extensions';
 
-const clients = extension.import('client');
-const stores = extension.import('store');
-const services = extension.import('service');
+// App-telemetry lets an app owner enumerate the users who have
+// authenticated into their app. v1 shipped this as a driver on the
+// `app-telemetry` interface (methods `get_users` / `user_count`) and
+// puter-js's `puter.apps(...).getUsers()` still calls it that way
+// (`puter.drivers.call('app-telemetry', 'app-telemetry', 'get_users', …)`).
+// This is the v2 port of that driver — same interface/method/return shapes
+// so existing puter-js callers work unchanged.
 
 const DEFAULT_LIMIT = 100;
 const MAX_LIMIT = 1000;
@@ -41,91 +46,125 @@ const parseIntParam = (
     return parsed;
 };
 
-export const handleAppTelemetryUsers = async (
-    req: Request,
-    res: Response,
-): Promise<void> => {
-    const { app_uuid } = req.query as Record<string, string>;
-    if (!app_uuid) throw new HttpError(400, 'Missing `app_uuid`');
+/**
+ * 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 +
+ * `default_implicit_user_app_permissions`). The real authorization — "is the
+ * 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;
 
-    const safeLimit = parseIntParam(req.query.limit, {
-        key: 'limit',
-        min: 1,
-        max: MAX_LIMIT,
-        fallback: DEFAULT_LIMIT,
-    });
-    const safeOffset = parseIntParam(req.query.offset, {
-        key: 'offset',
-        min: 0,
-        max: MAX_OFFSET,
-        fallback: 0,
-    });
+    /** Users who have authenticated into the given app (owner-only). */
+    async get_users({
+        app_uuid,
+        limit,
+        offset,
+    }: {
+        app_uuid?: string;
+        limit?: unknown;
+        offset?: unknown;
+    } = {}): Promise<
+        Array<{ user: string; user_uuid: string; user_email?: string | null }>
+    > {
+        if (!app_uuid) throw new HttpError(400, 'Missing `app_uuid`');
 
-    const app = await stores.app.getByUid(app_uuid);
-    if (!app) throw new HttpError(404, 'App not found');
+        const safeLimit = parseIntParam(limit, {
+            key: 'limit',
+            min: 1,
+            max: MAX_LIMIT,
+            fallback: DEFAULT_LIMIT,
+        });
+        const safeOffset = parseIntParam(offset, {
+            key: 'offset',
+            min: 0,
+            max: MAX_OFFSET,
+            fallback: 0,
+        });
 
-    // `apps-of-user:<uuid>:write` — the implicator keys on the owner's
-    // UUID, not the numeric id. Look up the owner explicitly. v1 got
-    // this for free because its entity-storage layer eager-joined the
-    // owner row; v2's AppStore.getByUid returns the raw row with only
-    // `owner_user_id` populated.
-    const ownerId = (app as { owner_user_id?: number }).owner_user_id;
-    if (!ownerId) throw new HttpError(404, 'App owner not found');
-    const owner = (await stores.user.getById(ownerId)) as {
-        uuid?: string;
-    } | null;
-    if (!owner?.uuid) throw new HttpError(404, 'App owner not found');
+        const app = await this.stores.app.getByUid(app_uuid);
+        if (!app) throw new HttpError(404, 'App not found');
 
-    const actor = Context.get('actor');
-    const ownsApp = await services.permission
-        .check(actor!, `apps-of-user:${owner.uuid}:write`)
-        .catch(() => false);
-    if (!ownsApp) throw new HttpError(403, 'Permission denied');
+        // The `apps-of-user:<uuid>:write` implicator keys on the owner's
+        // UUID, not the numeric id. Look up the owner explicitly — the raw
+        // app row only carries `owner_user_id`. (v1 got the owner for free
+        // because its entity-storage layer eager-joined the owner row.)
+        const ownerId = (app as { owner_user_id?: number }).owner_user_id;
+        if (!ownerId) throw new HttpError(404, 'App owner not found');
+        const owner = await this.stores.user.getById(ownerId);
+        if (!owner?.uuid) throw new HttpError(404, 'App owner not found');
 
-    const users = await clients.db.read(
-        `SELECT u.username, u.uuid FROM user_to_app_permissions p
-         INNER JOIN ${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 Record<string, unknown>).id, safeLimit, safeOffset],
-    );
+        const actor = Context.get('actor');
+        if (!actor) throw new HttpError(401, 'Authentication required');
+        const ownsApp = await this.services.permission
+            .check(actor as Actor, `apps-of-user:${owner.uuid}:write`)
+            .catch(() => false);
+        if (!ownsApp) throw new HttpError(403, 'Permission denied');
 
-    res.json(
-        (users as Array<{ username: string; uuid: string }>).map((e) => ({
-            user: e.username,
-            user_uuid: e.uuid,
-        })),
-    );
-};
+        const appId = (app as { id: number }).id;
 
-export const handleAppTelemetryUserCount = async (
-    req: Request,
-    res: Response,
-): Promise<void> => {
-    const { app_uuid } = req.query as Record<string, string>;
-    if (!app_uuid) throw new HttpError(400, 'Missing `app_uuid`');
+        const users = (await this.clients.db.read(
+            `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 ?`,
+            [appId, safeLimit, safeOffset],
+        )) as Array<{
+            id: number;
+            username: string;
+            uuid: string;
+            email: string | null;
+        }>;
 
-    const app = await stores.app.getByUid(app_uuid);
-    if (!app) throw new HttpError(404, 'App not found');
+        // 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);
+        }
 
-    const [row] = (await clients.db.read(
-        `SELECT COUNT(*) AS n FROM user_to_app_permissions
-         WHERE permission = 'flag:app-is-authenticated' AND app_id = ?`,
-        [(app as Record<string, unknown>).id],
-    )) as Array<{ n: number }>;
+        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 },
+        );
+    }
 
-    res.json({ count: row?.n ?? 0 });
-};
+    /** Count of users who have authenticated into the given app. */
+    async user_count({
+        app_uuid,
+    }: { app_uuid?: string } = {}): Promise<number> {
+        if (!app_uuid) throw new HttpError(400, 'Missing `app_uuid`');
 
-extension.get(
-    '/app-telemetry/users',
-    { subdomain: 'api', requireAuth: true },
-    handleAppTelemetryUsers,
-);
+        const app = await this.stores.app.getByUid(app_uuid);
+        if (!app) throw new HttpError(404, 'App not found');
 
-extension.get(
-    '/app-telemetry/user-count',
-    { subdomain: 'api', requireAuth: true },
-    handleAppTelemetryUserCount,
-);
+        const [row] = (await this.clients.db.read(
+            `SELECT COUNT(*) AS n FROM user_to_app_permissions
+             WHERE permission = 'flag:app-is-authenticated' AND app_id = ?`,
+            [(app as { id: number }).id],
+        )) as Array<{ n: number }>;
+
+        return row?.n ?? 0;
+    }
+}
+
+extension.registerDriver('appTelemetry', AppTelemetryDriver);

extensions/installedApps.test.ts

@@ -38,7 +38,7 @@ beforeAll(async () => {
 });
 
 afterAll(async () => {
-    await server.shutdown();
+    await server?.shutdown();
 });
 
 const seedUser = async () => {
@@ -132,9 +132,41 @@ describe('installedApps extension — handleInstalledApps', () => {
         expect(list[0].uid).toBe(app!.uid);
         expect(list[0].name).toBe(app!.name);
         expect(list[0].title).toBe(app!.title);
+        // index_url is required so the dashboard can derive a hostname title
+        // for anonymous (app-…) apps.
+        expect(list[0].index_url).toBe(app!.index_url);
         expect(Object.prototype.hasOwnProperty.call(list[0], 'iconUrl')).toBe(
             true,
         );
+        // An owned app is not external, and the raw owner id must not leak.
+        expect(list[0].external).toBe(false);
+        expect(
+            Object.prototype.hasOwnProperty.call(list[0], 'owner_user_id'),
+        ).toBe(false);
+    });
+
+    it('flags apps with no owner_user_id as external', async () => {
+        const user = await seedUser();
+        const slug = Math.random().toString(36).slice(2, 8);
+        // createFromOrigin bootstraps an app with owner_user_id = null.
+        const app = await server.stores.app.createFromOrigin(
+            `app-${slug}`,
+            `https://external-${slug}.example.com`,
+        );
+        await grantInstalled(app!.id as number, user.id as number);
+
+        const { res, captured } = makeRes();
+        await runWithContext(
+            { actor: { user: { uuid: user.uuid, id: user.id as number } } },
+            () => handleInstalledApps(makeReq({}), res),
+        );
+
+        const list = captured.body as Array<Record<string, unknown>>;
+        expect(list).toHaveLength(1);
+        expect(list[0].external).toBe(true);
+        expect(
+            Object.prototype.hasOwnProperty.call(list[0], 'owner_user_id'),
+        ).toBe(false);
     });
 
     it('clamps page/limit to safe ranges (page>=1, 1<=limit<=100)', async () => {

extensions/installedApps.ts

@@ -49,6 +49,8 @@ export const handleInstalledApps = async (
             apps.title,
             apps.description,
             apps.icon,
+            apps.index_url,
+            apps.owner_user_id,
             MIN(perm.dt) AS installed_at
         FROM apps
         LEFT JOIN user_to_app_permissions AS perm ON apps.id = perm.app_id
@@ -62,10 +64,18 @@ export const handleInstalledApps = async (
 
     const apiBaseUrl = extension.config.api_base_url as string | undefined;
     res.json(
-        installedApps.map((app) => ({
-            ...app,
-            iconUrl: getAppIconUrl(app, { apiBaseUrl }),
-        })),
+        installedApps.map((app) => {
+            // An app with no owner_user_id (null/empty) isn't owned by a Puter
+            // user — it's an "external" app. Derive a flag and don't leak the
+            // raw owner id to the client.
+            const { owner_user_id, ...rest } = app;
+            const external = owner_user_id == null || owner_user_id === '';
+            return {
+                ...rest,
+                iconUrl: getAppIconUrl(app, { apiBaseUrl }),
+                external,
+            };
+        }),
     );
 };
 

extensions/metering.test.ts

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

extensions/thumbnails.test.ts

@@ -41,7 +41,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 +108,7 @@ describe('thumbnails extension — handleThumbnailUploadPrepare', () => {
     });
 
     afterAll(async () => {
-        await server.shutdown();
+        await server?.shutdown();
     });
 
     it('returns early when event has no items array', async () => {
@@ -188,7 +188,7 @@ describe('thumbnails extension — handleThumbnailRead', () => {
     });
 
     afterAll(async () => {
-        await server.shutdown();
+        await server?.shutdown();
     });
 
     it('rewrites an s3:// thumbnail into a presigned https URL', async () => {
@@ -281,7 +281,7 @@ describe('thumbnails extension — handleFsRemoveNodeThumbnail', () => {
     });
 
     afterAll(async () => {
-        await server.shutdown();
+        await server?.shutdown();
     });
 
     it('deletes the S3 object referenced by an s3:// thumbnail URL', async () => {

extensions/whoami.test.ts

@@ -51,7 +51,7 @@ beforeAll(async () => {
 });
 
 afterAll(async () => {
-    await server.shutdown();
+    await server?.shutdown();
 });
 
 const seedUser = async () => {
@@ -107,6 +107,8 @@ describe('whoami extension — handleWhoami', () => {
         expect(body.email).toBe(user.email);
         expect(body.is_temp).toBe(false);
         expect(body.oidc_only).toBe(false);
+        // is_user_token is present (true) for user actors.
+        expect(body.is_user_token).toBe(true);
         // `directories` is only sent to user actors — confirm it’s present.
         expect(body.directories).toBeDefined();
         // taskbar_items is only sent to user actors.
@@ -146,6 +148,8 @@ describe('whoami extension — handleWhoami', () => {
 
         const body = captured.body as Record<string, unknown>;
         expect(body.app_name).toBe('app-test-actor');
+        // is_user_token is stripped for app actors.
+        expect(body.is_user_token).toBeUndefined();
         expect(body.desktop_bg_url).toBeUndefined();
         expect(body.desktop_bg_color).toBeUndefined();
         expect(body.desktop_bg_fit).toBeUndefined();
@@ -154,6 +158,49 @@ describe('whoami extension — handleWhoami', () => {
         expect(body.directories).toBeUndefined();
     });
 
+    it('redacts tmp_password from metadata for user actors', async () => {
+        const user = await seedUser();
+        await server.stores.user.updateMetadata(user.id as number, {
+            tmp_password: 'bootstrap-secret',
+            hasDevAccountAccess: true,
+        });
+
+        const { res, captured } = makeRes();
+        await runWithContext(
+            { actor: { user: { uuid: user.uuid, id: user.id as number } } },
+            () => handleWhoami(makeReq(), res),
+        );
+
+        const body = captured.body as Record<string, unknown>;
+        const metadata = body.metadata as Record<string, unknown>;
+        expect(metadata.tmp_password).toBeUndefined();
+        // Other metadata keys still reach the user's own client.
+        expect(metadata.hasDevAccountAccess).toBe(true);
+        expect(body.hasDevAccountAccess).toBe(true);
+    });
+
+    it('never sends user metadata to app actors', async () => {
+        const user = await seedUser();
+        await server.stores.user.updateMetadata(user.id as number, {
+            tmp_password: 'bootstrap-secret',
+        });
+
+        const { res, captured } = makeRes();
+        await runWithContext(
+            {
+                actor: {
+                    user: { uuid: user.uuid, id: user.id as number },
+                    app: { uid: 'app-test-actor' },
+                },
+            },
+            () => handleWhoami(makeReq(), res),
+        );
+
+        const body = captured.body as Record<string, unknown>;
+        expect(body.metadata).toBeUndefined();
+        expect(JSON.stringify(body)).not.toContain('bootstrap-secret');
+    });
+
     it('marks the user as oidc_only when password is null', async () => {
         const slug = Math.random().toString(36).slice(2, 8);
         const oidcUser = await server.stores.user.create({

extensions/whoami.ts

@@ -65,6 +65,9 @@ export const handleWhoami = async (
         }
     }
 
+    const metadata = user.metadata ? { ...user.metadata } : user.metadata;
+    if (metadata) delete metadata.tmp_password;
+
     const details: Record<string, unknown> = {
         username: user.username,
         uuid: user.uuid,
@@ -79,6 +82,7 @@ export const handleWhoami = async (
         desktop_bg_color: user.desktop_bg_color,
         desktop_bg_fit: user.desktop_bg_fit,
         is_temp: user.password === null && user.email === null,
+        is_user_token: true,
         oidc_only: oidcOnly,
         taskbar_items: isUser
             ? await getTaskbarItems(
@@ -97,7 +101,7 @@ export const handleWhoami = async (
         human_readable_age: user.timestamp
             ? timeago.format(new Date(user.timestamp as string))
             : null,
-        metadata: user.metadata,
+        metadata,
         hasDevAccountAccess: !!user.metadata?.hasDevAccountAccess,
     };
 
@@ -160,6 +164,8 @@ export const handleWhoami = async (
         delete details.desktop_bg_color;
         delete details.desktop_bg_fit;
         delete details.human_readable_age;
+        delete details.is_user_token;
+        delete details.metadata;
     }
 
     if (actor.app) {

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",
@@ -46,7 +53,13 @@
   "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 ",
-    "start=gui": "nodemon --exec \"node dev-server.js\" ",
+    "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",
     "dev": "npm start",
@@ -78,15 +91,20 @@
     "dedent": "^1.5.3",
     "javascript-time-ago": "^2.5.11",
     "libphonenumber-js": "1.13.6",
+    "miniflare": "^4.20260617.1",
     "open": "^10.1.0"
   },
   "engines": {
     "node": ">=24.0.0"
   },
   "allowScripts": {
-    "[email protected]": true,
-    "[email protected]": true,
     "@google/genai": false,
-    "[email protected].1": true
+    "[email protected].1": true,
+    "[email protected]": true,
+    "[email protected]": true,
+    "[email protected]": true,
+    "[email protected]": true,
+    "[email protected]": true,
+    "[email protected]": true
   }
 }

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

@@ -17,8 +17,12 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import { describe, expect, it } from 'vitest';
-import { compareMigrationFilenames } from './MySQLDatabaseClient.js';
+import { describe, expect, it, vi } from 'vitest';
+import type { IConfig } from '../../types';
+import {
+    MySQLDatabaseClient,
+    compareMigrationFilenames,
+} from './MySQLDatabaseClient.js';
 
 describe('compareMigrationFilenames', () => {
     it('orders numbered migrations numerically, not lexically', () => {
@@ -93,3 +97,76 @@ 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();
+    });
+});

src/backend/clients/database/MySQLDatabaseClient.ts

@@ -19,31 +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 };
 
@@ -85,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);
@@ -96,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();
     }
@@ -135,15 +128,36 @@ export class MySQLDatabaseClient extends AbstractDatabaseClient {
     // Query interface
     // ------------------------------------------------------------------
 
+    // The db.* spans measure the logical query, including time queued in
+    // the SQLBatcher — the mysql2 auto-instrumentation only sees the
+    // coalesced multi-statement flush, so per-query latency lives here.
+    @Span('db.read', (query: string) => ({ 'db.statement': query }))
     override async read(
         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>[]) ?? [];
     }
 
+    @Span('db.pread', (query: string) => ({ 'db.statement': query }))
     override async pread(
         query: string,
         params: unknown[] = [],
@@ -153,6 +167,7 @@ export class MySQLDatabaseClient extends AbstractDatabaseClient {
         return (result[0] as Record<string, unknown>[]) ?? [];
     }
 
+    @Span('db.write', (query: string) => ({ 'db.statement': query }))
     override async write(
         query: string,
         params: unknown[] = [],
@@ -170,6 +185,9 @@ export class MySQLDatabaseClient extends AbstractDatabaseClient {
         };
     }
 
+    @Span('db.batchWrite', (entries: unknown[]) => ({
+        'db.batch_size': entries.length,
+    }))
     override async batchWrite(
         entries: { statement: string; values: unknown[] }[],
     ): Promise<void> {
@@ -195,6 +213,7 @@ export class MySQLDatabaseClient extends AbstractDatabaseClient {
         }
     }
 
+    @Span('db.tryHardRead', (query: string) => ({ 'db.statement': query }))
     override async tryHardRead(
         query: string,
         params: unknown[] = [],
@@ -296,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). */
@@ -317,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) {
@@ -335,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 &&
@@ -351,11 +411,14 @@ 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.ts

@@ -20,6 +20,7 @@
 import { readdirSync, readFileSync } from 'fs';
 import { isAbsolute, resolve as resolvePath } from 'path';
 import { Pool, type PoolConfig, type QueryResult } from 'pg';
+import { Span } from '../../util/span.js';
 import {
     AbstractDatabaseClient,
     type BatchEntry,
@@ -214,6 +215,7 @@ export class PostgresDatabaseClient extends AbstractDatabaseClient {
         return value;
     }
 
+    @Span('db.read', (query: string) => ({ 'db.statement': query }))
     override async read(
         query: string,
         params: unknown[] = [],
@@ -222,6 +224,7 @@ export class PostgresDatabaseClient extends AbstractDatabaseClient {
         return normalizePostgresRows(result);
     }
 
+    @Span('db.pread', (query: string) => ({ 'db.statement': query }))
     override async pread(
         query: string,
         params: unknown[] = [],
@@ -230,6 +233,7 @@ export class PostgresDatabaseClient extends AbstractDatabaseClient {
         return normalizePostgresRows(result);
     }
 
+    @Span('db.write', (query: string) => ({ 'db.statement': query }))
     override async write(
         query: string,
         params: unknown[] = [],
@@ -238,6 +242,9 @@ export class PostgresDatabaseClient extends AbstractDatabaseClient {
         return mapPostgresWriteResult(result);
     }
 
+    @Span('db.batchWrite', (entries: unknown[]) => ({
+        'db.batch_size': entries.length,
+    }))
     override async batchWrite(entries: BatchEntry[]): Promise<void> {
         if (entries.length === 0) return;
 
@@ -258,6 +265,7 @@ export class PostgresDatabaseClient extends AbstractDatabaseClient {
         }
     }
 
+    @Span('db.tryHardRead', (query: string) => ({ 'db.statement': query }))
     override async tryHardRead(
         query: string,
         params: unknown[] = [],

src/backend/clients/database/SQLBatcher.js

@@ -18,10 +18,19 @@
  */
 
 import { metrics } from '@opentelemetry/api';
+import {
+    POOL_ACQUIRE_TIMEOUT,
+    isNeverSentError,
+    isRetriableError,
+} 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 +62,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 +79,43 @@ 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 +123,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 +137,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 +157,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 +168,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 +193,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 +260,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 +312,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 +322,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 +342,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 +355,39 @@ 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
+    // never reached the server — a write that died mid-flight may have
+    // committed, and re-running it would double-apply.
+    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)
+                    : isNeverSentError(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,239 @@
+/**
+ * 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('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.ts

@@ -21,6 +21,7 @@ import { existsSync, mkdirSync, readFileSync } from 'fs';
 import { basename, dirname, extname, join, resolve } from 'path';
 import { createContext, runInContext } from 'vm';
 import type { IConfig } from '../../types';
+import { Span } from '../../util/span.js';
 import { AbstractDatabaseClient, type WriteResult } from './DatabaseClient';
 
 const MIGRATIONS_DIR = resolve(__dirname, './migrations/sqlite');
@@ -88,6 +89,11 @@ const AVAILABLE_MIGRATIONS: [number, string[]][] = [
     [52, ['0057_add_user_reputation.sql']],
     [53, ['0058_add_phone_verification.sql']],
     [54, ['0059_add_card_verification.sql']],
+    [55, ['0060_add_card_fingerprint.sql']],
+    [56, ['0061_add_suspended_at.sql']],
+    [57, ['0062_blocked-app-origins.sql']],
+    [58, ['0063_add_suspended_reason.sql']],
+    [59, ['0064_abuse-moderation-events.sql']],
 ];
 
 export class SqliteDatabaseClient extends AbstractDatabaseClient {
@@ -131,6 +137,7 @@ export class SqliteDatabaseClient extends AbstractDatabaseClient {
     // Query interface
     // ------------------------------------------------------------------
 
+    @Span('db.read', (query: string) => ({ 'db.statement': query }))
     override async read(
         query: string,
         params: unknown[] = [],
@@ -151,6 +158,7 @@ export class SqliteDatabaseClient extends AbstractDatabaseClient {
         return this.read(query, params);
     }
 
+    @Span('db.write', (query: string) => ({ 'db.statement': query }))
     override async write(
         query: string,
         params: unknown[] = [],
@@ -167,6 +175,9 @@ export class SqliteDatabaseClient extends AbstractDatabaseClient {
         };
     }
 
+    @Span('db.batchWrite', (entries: unknown[]) => ({
+        'db.batch_size': entries.length,
+    }))
     override async batchWrite(
         entries: { statement: string; values: unknown[] }[],
     ): Promise<void> {

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

@@ -0,0 +1,46 @@
+-- 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/>.
+
+-- Suspended-at column. Mirrors SQLite migration 0061. `suspended_at` is when
+-- the account was suspended, as unix seconds (NULL while not suspended) — the
+-- timestamp sibling of the boolean `suspended` flag, indexed so the
+-- signup-abuse harness can count an IP's recently-suspended accounts.
+--
+-- Idempotent: the column add uses _puter_add_col (defined in mig_1, which
+-- leaves it resident for later migrations); the index add is guarded against
+-- INFORMATION_SCHEMA.STATISTICS so the directory replays safely.
+
+CALL _puter_add_col('user', 'suspended_at', '`suspended_at` bigint DEFAULT NULL');
+
+DROP PROCEDURE IF EXISTS _puter_add_user_suspended_at_index;
+DELIMITER //
+CREATE PROCEDURE _puter_add_user_suspended_at_index()
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.STATISTICS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'user'
+      AND INDEX_NAME = 'idx_user_suspended_at'
+  ) THEN
+    ALTER TABLE `user` ADD INDEX `idx_user_suspended_at` (`suspended_at`);
+  END IF;
+END//
+DELIMITER ;
+
+CALL _puter_add_user_suspended_at_index();
+
+DROP PROCEDURE IF EXISTS _puter_add_user_suspended_at_index;

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

@@ -0,0 +1,36 @@
+-- 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/>.
+
+-- Admin-managed blocklist of app origins. Mirrors SQLite migration 0062.
+-- An app whose `index_url` host (or a request origin) matches an entry is
+-- denied access to Puter resources: it cannot obtain an app token and
+-- already-issued app tokens are rejected on each request. `include_subdomains
+-- = 1` also blocks every subdomain of `domain`. Enforced in AuthService via
+-- AppOriginBlocklistService.
+--
+-- Idempotent: `CREATE TABLE IF NOT EXISTS` lets the directory replay safely.
+
+CREATE TABLE IF NOT EXISTS `blocked_app_origins` (
+    `id` INT NOT NULL AUTO_INCREMENT,
+    `domain` VARCHAR(255) NOT NULL,
+    `include_subdomains` TINYINT(1) NOT NULL DEFAULT 0,
+    `reason` TEXT DEFAULT NULL,
+    `created_by` VARCHAR(255) DEFAULT NULL,
+    `created_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `idx_blocked_app_origins_domain` (`domain`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

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

@@ -0,0 +1,26 @@
+-- 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/>.
+
+-- Suspension reason column. Mirrors SQLite migration 0063. Why an account was
+-- suspended (NULL while not suspended) — companion to the boolean `suspended`
+-- flag and `suspended_at` timestamp. Constrained at the application layer to a
+-- fixed set of reasons (see extensions/admin suspension_reasons.js).
+--
+-- Idempotent: the column add uses _puter_add_col (defined in mig_1, which
+-- leaves it resident for later migrations).
+
+CALL _puter_add_col('user', 'suspended_reason', '`suspended_reason` VARCHAR(64) DEFAULT NULL');

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

@@ -0,0 +1,38 @@
+-- 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/>.
+
+-- Append-only log of admin moderation actions. Mirrors SQLite migration 0064.
+-- Used to measure the abuse system's false-positive rate: `unsuspend` (admin
+-- unblock) and `admin_create_user` are the false-positive signals; `suspend`
+-- gives the denominator. Preserves history the `user` suspension columns lose
+-- on unsuspend. `created_at` is unix seconds (matching `user.suspended_at`).
+--
+-- Idempotent: `CREATE TABLE IF NOT EXISTS` lets the directory replay safely.
+
+CREATE TABLE IF NOT EXISTS `abuse_moderation_events` (
+    `id` INT NOT NULL AUTO_INCREMENT,
+    `action` VARCHAR(32) NOT NULL,
+    `target_user_id` BIGINT DEFAULT NULL,
+    `target_username` VARCHAR(255) DEFAULT NULL,
+    `admin_username` VARCHAR(255) DEFAULT NULL,
+    `reason` TEXT DEFAULT NULL,
+    `source` VARCHAR(64) DEFAULT NULL,
+    `created_at` BIGINT NOT NULL,
+    PRIMARY KEY (`id`),
+    KEY `idx_abuse_moderation_events_created_at` (`created_at`),
+    KEY `idx_abuse_moderation_events_action` (`action`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

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

@@ -0,0 +1,25 @@
+-- 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/>.
+
+-- Suspended-at column. Mirrors SQLite migration 0061. `suspended_at` is when
+-- the account was suspended, as unix seconds (NULL while not suspended) — the
+-- timestamp sibling of the boolean `suspended` flag, indexed so the
+-- signup-abuse harness can count an IP's recently-suspended accounts.
+-- Idempotent via IF NOT EXISTS.
+
+ALTER TABLE "user" ADD COLUMN IF NOT EXISTS suspended_at bigint;
+CREATE INDEX IF NOT EXISTS idx_user_suspended_at ON "user" (suspended_at);

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

@@ -0,0 +1,36 @@
+-- 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/>.
+
+-- Admin-managed blocklist of app origins. Mirrors SQLite migration 0062 /
+-- MySQL mysql_mig_17 (which Postgres was originally missed for). An app whose
+-- `index_url` host (or a request origin) matches an entry is denied access to
+-- Puter resources. `include_subdomains = 1` also blocks every subdomain of
+-- `domain`. Enforced in AuthService via AppOriginBlocklistService.
+--
+-- Idempotent via IF NOT EXISTS.
+
+CREATE TABLE IF NOT EXISTS blocked_app_origins (
+    id SERIAL PRIMARY KEY,
+    domain VARCHAR(255) NOT NULL,
+    include_subdomains SMALLINT NOT NULL DEFAULT 0,
+    reason TEXT DEFAULT NULL,
+    created_by VARCHAR(255) DEFAULT NULL,
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_blocked_app_origins_domain
+    ON blocked_app_origins (domain);

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

@@ -0,0 +1,24 @@
+-- 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/>.
+
+-- Suspension reason column. Mirrors SQLite migration 0063. Why an account was
+-- suspended (NULL while not suspended) — companion to the boolean `suspended`
+-- flag and `suspended_at` timestamp. Constrained at the application layer to a
+-- fixed set of reasons (see extensions/admin suspension_reasons.js).
+-- Idempotent via IF NOT EXISTS.
+
+ALTER TABLE "user" ADD COLUMN IF NOT EXISTS suspended_reason text;

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

@@ -0,0 +1,40 @@
+-- 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/>.
+
+-- Append-only log of admin moderation actions. Mirrors SQLite migration 0064 /
+-- MySQL mysql_mig_19. Used to measure the abuse system's false-positive rate:
+-- `unsuspend` (admin unblock) and `admin_create_user` are the false-positive
+-- signals; `suspend` gives the denominator. Preserves history the `user`
+-- suspension columns lose on unsuspend. `created_at` is unix seconds.
+--
+-- Idempotent via IF NOT EXISTS.
+
+CREATE TABLE IF NOT EXISTS abuse_moderation_events (
+    id BIGSERIAL PRIMARY KEY,
+    action VARCHAR(32) NOT NULL,
+    target_user_id BIGINT DEFAULT NULL,
+    target_username VARCHAR(255) DEFAULT NULL,
+    admin_username VARCHAR(255) DEFAULT NULL,
+    reason TEXT DEFAULT NULL,
+    source VARCHAR(64) DEFAULT NULL,
+    created_at BIGINT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_abuse_moderation_events_created_at
+    ON abuse_moderation_events (created_at);
+CREATE INDEX IF NOT EXISTS idx_abuse_moderation_events_action
+    ON abuse_moderation_events (action);

src/backend/clients/database/migrations/sqlite/0061_add_suspended_at.sql

@@ -0,0 +1,23 @@
+-- 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/>.
+
+-- When the account was suspended, as unix seconds; NULL while not suspended.
+-- The timestamp sibling of the existing boolean `suspended` flag, stamped by
+-- every suspension site. Indexed so the signup-abuse harness can count an IP's
+-- recently-suspended accounts (see extensions/abuse/v2 suspendedAccountsByIp).
+ALTER TABLE `user` ADD COLUMN `suspended_at` INTEGER DEFAULT NULL;
+CREATE INDEX IF NOT EXISTS idx_user_suspended_at ON `user` (`suspended_at`);

src/backend/clients/database/migrations/sqlite/0062_blocked-app-origins.sql

@@ -0,0 +1,34 @@
+-- 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/>.
+
+-- Admin-managed blocklist of app origins. An app whose `index_url` host (or
+-- a request origin) matches an entry is denied access to Puter resources:
+-- it cannot obtain an app token and already-issued app tokens are rejected
+-- on each request. `include_subdomains = 1` also blocks every subdomain of
+-- `domain`. Enforced in AuthService via AppOriginBlocklistService.
+
+CREATE TABLE IF NOT EXISTS `blocked_app_origins` (
+    "id" INTEGER PRIMARY KEY AUTOINCREMENT,
+    "domain" TEXT NOT NULL,
+    "include_subdomains" INTEGER NOT NULL DEFAULT 0,
+    "reason" TEXT DEFAULT NULL,
+    "created_by" TEXT DEFAULT NULL,
+    "created_at" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS `idx_blocked_app_origins_domain`
+    ON `blocked_app_origins` (`domain`);

src/backend/clients/database/migrations/sqlite/0063_add_suspended_reason.sql

@@ -0,0 +1,23 @@
+-- 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/>.
+
+-- Why an account was suspended, NULL while not suspended. Companion to the
+-- boolean `suspended` flag and `suspended_at` timestamp. Constrained at the
+-- application layer to a fixed set of reasons (see extensions/admin
+-- suspension_reasons.js) — kept as free TEXT here so adding a reason later
+-- needs no migration.
+ALTER TABLE `user` ADD COLUMN `suspended_reason` TEXT DEFAULT NULL;

src/backend/clients/database/migrations/sqlite/0064_abuse-moderation-events.sql

@@ -0,0 +1,43 @@
+-- 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/>.
+
+-- Append-only log of admin moderation actions, used to measure the abuse
+-- system's false-positive rate: `unsuspend` (admin unblock) and
+-- `admin_create_user` (an account minted by an admin, typically to recover a
+-- legitimately-blocked signup) are the false-positive signals; `suspend` gives
+-- the denominator. Unlike the `suspended`/`suspended_at`/`suspended_reason`
+-- columns on `user` — which are cleared on unsuspend and so keep no history —
+-- this table preserves every event. `created_at` is unix seconds (matching
+-- `user.suspended_at`), stamped by the recorder in
+-- extensions/admin/moderation_events.js. Written best-effort at the admin
+-- suspend/unsuspend/create-user sites; surfaced on the /admin/abuse dashboard.
+
+CREATE TABLE IF NOT EXISTS `abuse_moderation_events` (
+    "id" INTEGER PRIMARY KEY AUTOINCREMENT,
+    "action" TEXT NOT NULL,             -- 'suspend' | 'unsuspend' | 'admin_create_user'
+    "target_user_id" INTEGER DEFAULT NULL,
+    "target_username" TEXT DEFAULT NULL,
+    "admin_username" TEXT DEFAULT NULL, -- the acting admin (req.actor.user.username)
+    "reason" TEXT DEFAULT NULL,
+    "source" TEXT DEFAULT NULL,         -- 'user_page' | 'email_hostname_blacklist' | 'create_user'
+    "created_at" INTEGER NOT NULL       -- unix seconds
+);
+
+CREATE INDEX IF NOT EXISTS idx_abuse_moderation_events_created_at
+    ON `abuse_moderation_events` (`created_at`);
+CREATE INDEX IF NOT EXISTS idx_abuse_moderation_events_action
+    ON `abuse_moderation_events` (`action`);

src/backend/clients/database/retriableErrors.ts

@@ -0,0 +1,78 @@
+/**
+ * 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,
+]);
+
+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));
+};

src/backend/clients/dynamodb/DDBClient.ts

@@ -3,18 +3,19 @@
  *
  * 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.
+ * 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.
+ * 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/>.
+ * along with this program. If not, see
+ * [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
  */
 
 import {
@@ -43,6 +44,7 @@ import { once } from 'node:events';
 import { Agent as httpsAgent } from 'node:https';
 import { HttpError } from '../../core/http';
 import type { IConfig, IDynamoConfig } from '../../types';
+import { Span } from '../../util/span.js';
 import { PuterClient } from '../types';
 
 const LOCAL_DYNAMO_MEMORY_PREFIX = ':memory:';
@@ -151,6 +153,7 @@ export class DDBClient extends PuterClient {
         await this.#localInitPromise;
     }
 
+    @Span('ddb.get', (table: string) => ({ 'db.table': table }))
     async get<T extends Record<string, unknown>>(
         table: string,
         key: T,
@@ -167,6 +170,7 @@ export class DDBClient extends PuterClient {
         return client.send(command);
     }
 
+    @Span('ddb.put', (table: string) => ({ 'db.table': table }))
     async put<T extends Record<string, unknown>>(table: string, item: T) {
         const command = new PutCommand({
             TableName: table,
@@ -178,6 +182,9 @@ export class DDBClient extends PuterClient {
         return client.send(command);
     }
 
+    @Span('ddb.batchGet', (params: unknown[]) => ({
+        'db.batch_size': params.length,
+    }))
     async batchGet(
         params: { table: string; items: Record<string, unknown> }[],
         consistentRead = false,
@@ -212,6 +219,9 @@ export class DDBClient extends PuterClient {
         return client.send(command);
     }
 
+    @Span('ddb.batchPut', (params: unknown[]) => ({
+        'db.batch_size': params.length,
+    }))
     async batchPut(params: { table: string; item: Record<string, unknown> }[]) {
         const consumedCapacityByTable = new Map<string, number>();
         if (params.length === 0) {
@@ -318,6 +328,7 @@ export class DDBClient extends PuterClient {
         };
     }
 
+    @Span('ddb.del', (table: string) => ({ 'db.table': table }))
     async del<T extends Record<string, unknown>>(table: string, key: T) {
         const command = new DeleteCommand({
             TableName: table,
@@ -329,6 +340,7 @@ export class DDBClient extends PuterClient {
         return client.send(command);
     }
 
+    @Span('ddb.query', (table: string) => ({ 'db.table': table }))
     async query<T extends Record<string, unknown>>(
         table: string,
         keys: T,
@@ -336,7 +348,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}`,
@@ -367,6 +387,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 }),
@@ -376,6 +401,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',
         });
 
@@ -383,6 +412,7 @@ export class DDBClient extends PuterClient {
         return client.send(command);
     }
 
+    @Span('ddb.update', (table: string) => ({ 'db.table': table }))
     async update<T extends Record<string, unknown>>(
         table: string,
         key: T,
@@ -424,6 +454,7 @@ export class DDBClient extends PuterClient {
             return;
         }
 
+        let alreadyExisted = false;
         try {
             const client = await this.#getDocumentClient();
             await client.send(new CreateTableCommand(params));
@@ -431,14 +462,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.ts

@@ -24,12 +24,20 @@ import type { IConfig } from '../../types';
 import { PuterClient } from '../types';
 import { EMAIL_TEMPLATES, type EmailTemplateName } from './templates';
 
-// -- Types ------------------------------------------------------------
+/** Attachment shape passed through to the underlying transport. */
+export interface EmailAttachment {
+    filename: string;
+    content: Buffer | string;
+    contentType?: string;
+    encoding?: string;
+}
 
-// nodemailer doesn't ship TS types, so declare the subset we use.
-interface NodemailerTransport {
-    sendMail: (options: SendMailOptions) => Promise<unknown>;
-    close?: () => void;
+/** Subset of the transport's send result callers may care about. */
+export interface SentMessageInfo {
+    messageId?: string;
+    accepted?: string[];
+    rejected?: string[];
+    [key: string]: unknown;
 }
 
 export interface SendMailOptions {
@@ -37,10 +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;
@@ -100,7 +116,8 @@ const DOMAIN_ALIASES: Record<string, string> = {
  *   - Policy + extensible validation (via `validate`)
  */
 export class EmailClient extends PuterClient {
-    private transport: NodemailerTransport | null = null;
+    private transport: ReturnType<typeof nodemailer.createTransport> | null =
+        null;
     private compiledTemplates: Partial<
         Record<EmailTemplateName, CompiledTemplate>
     > = {};
@@ -123,8 +140,7 @@ export class EmailClient extends PuterClient {
             return;
         }
 
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        this.transport = nodemailer.createTransport(emailConf as any);
+        this.transport = nodemailer.createTransport(emailConf);
         console.log('[email] transport configured');
     }
 
@@ -159,21 +175,30 @@ export class EmailClient extends PuterClient {
     /**
      * 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).
      */
-    async sendRaw(options: SendMailOptions): Promise<void> {
+    async sendRaw(options: SendMailOptions) {
         if (!this.transport) {
             console.warn(
                 '[email] attempted to send email without transport. If you need to send email, configure an SMTP transport in your config file (see docs for details). Email content:',
                 options,
             );
-            return;
+            return null;
         }
-        await this.transport.sendMail({
-            from: options.from ?? this.defaultFrom(),
+        return await this.transport.sendMail({
             ...options,
+            from: options.from ?? this.defaultFrom(),
         });
     }
 
+    /** Whether an SMTP transport is configured (sends are no-ops otherwise). */
+    get isConfigured(): boolean {
+        return this.transport !== null;
+    }
+
     // -- Public API: clean / validate ---------------------------------
 
     /**

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

@@ -21,7 +21,7 @@ describe('EventClient', () => {
     });
 
     afterAll(async () => {
-        await server.shutdown();
+        await server?.shutdown();
     });
 
     // Each test gets a fresh key so listeners registered by earlier tests

src/backend/clients/event/EventClient.ts

@@ -18,6 +18,7 @@
  */
 
 import { extensionStore } from '../../extensions';
+import { withSpan } from '../../util/span.js';
 import { PuterClient } from '../types';
 import {
     EventListener,
@@ -99,26 +100,34 @@ export class EventClient extends PuterClient {
         data: EventMap[T],
         meta: EventMetadata,
     ) {
-        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;
-            const extensionListeners = extensionStore.events[matchKey];
-            const listeners = (this.#eventListeners[matchKey] || []).concat(
-                extensionListeners || [],
-            );
-            if (!listeners) continue;
-            for (const listener of listeners) {
-                try {
-                    await listener(key, data, meta);
-                } catch (e) {
-                    console.error('Error in event listener for event', key, e);
+        // Spanned because callers block on listeners — this is where time
+        // spent in extension hooks (e.g. `ip.validate`) gets attributed.
+        return withSpan('event.emitAndWait', { 'event.key': key }, async () => {
+            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;
+                const extensionListeners = extensionStore.events[matchKey];
+                const listeners = (this.#eventListeners[matchKey] || []).concat(
+                    extensionListeners || [],
+                );
+                if (!listeners) continue;
+                for (const listener of listeners) {
+                    try {
+                        await listener(key, data, meta);
+                    } catch (e) {
+                        console.error(
+                            'Error in event listener for event',
+                            key,
+                            e,
+                        );
+                    }
                 }
             }
-        }
+        });
     }
 
     /**
@@ -146,6 +155,19 @@ export class EventClient extends PuterClient {
             this.#eventListeners[key] ?? (this.#eventListeners[key] = []);
         listeners.push(callback as EventListener);
     }
+    off<P extends ListenKey>(
+        key: P,
+        callback: (
+            key: MatchingEvents<P>,
+            data: EventMap[MatchingEvents<P>],
+            meta: EventMetadata,
+        ) => Promise<void> | void,
+    ) {
+        const listeners = this.#eventListeners[key];
+        if (!listeners) return;
+        const idx = listeners.indexOf(callback as EventListener);
+        if (idx !== -1) listeners.splice(idx, 1);
+    }
     async #emitEvent<T extends keyof EventMap>(
         listener: EventListener,
         key: T,

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 {
@@ -120,6 +121,21 @@ export type EventMap = {
         actor: unknown;
         result: { allowed: boolean; reason?: string; error?: string };
     };
+    // Emitted after an app token is granted (get-user-app-token). The app-side
+    // analogue of `site.htmlServed` — the external-app abuse scanner
+    // (extensions/subdomainAbuse/appScan.ts) listens to screenshot + classify
+    // external `index_url`s that Puter never serves itself.
+    'puter.app.authenticated': {
+        app_uid?: string;
+        user_id?: number | null;
+        app?: {
+            id?: number;
+            uid?: string;
+            index_url?: string | null;
+            owner_user_id?: number | null;
+            name?: string | null;
+        };
+    };
 
     // ---- Auth / signup ----
     'puter.signup.validate': {
@@ -133,14 +149,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 signals forwarded verbatim from the signup request body. */
+        /** Device signal forwarded verbatim from the signup request body. */
         fingerprint?: string | null;
-        dfp_telemetry_id?: 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;
@@ -237,6 +255,7 @@ export type EventMap = {
         fingerprint: string | null;
         funding: string | null;
         country: string | null;
+        customer_id: string | null;
         [key: string]: unknown;
     };
     'user.card-verified': {
@@ -245,6 +264,7 @@ export type EventMap = {
         fingerprint: string | null;
         funding: string | null;
         country: string | null;
+        customer_id: string | null;
     };
     'user.username-changed': {
         user_id: number;
@@ -318,9 +338,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 };
@@ -376,6 +400,8 @@ export type EventMap = {
     // normalized path: `route.<method>.<path>.before|after|error|reject`. Same
     // wildcard + veto semantics as the driver lifecycle above.
     [K in `route.${string}`]: RouteLifecycleEvent;
+} & {
+    [K in `pubsub.login.${string}`]: { authtoken: string };
 };
 
 /**
@@ -388,9 +414,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;
@@ -456,11 +482,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/prelude/PreludeClient.test.ts

@@ -79,12 +79,28 @@ describe('PreludeClient', () => {
         expect(init.headers.Authorization).toBe('Bearer sk_test');
         expect(JSON.parse(init.body)).toEqual({
             target: { type: 'phone_number', value: '+14155550123' },
-            // Defaults to RCS (cheaper); Prelude falls back to SMS.
-            options: { code_size: 6, preferred_channel: 'rcs' },
+            // Defaults to RCS (cheaper); Prelude falls back to SMS. locale is
+            // hardcoded to en-US so the message text is always English.
+            options: { code_size: 6, preferred_channel: 'rcs', locale: 'en-US' },
             signals: { ip: '203.0.113.7' },
         });
     });
 
+    it('returns the delivery channel sequence Prelude reports', async () => {
+        fetchMock.mockResolvedValue(
+            okJson({
+                id: 'vrf_1',
+                status: 'success',
+                channels: ['whatsapp', 'sms'],
+            }),
+        );
+        const client = makeClient('sk_test');
+
+        const res = await client.createVerification('+14155550123');
+
+        expect(res.channels).toEqual(['whatsapp', 'sms']);
+    });
+
     it('forwards device_id and user_agent signals when supplied', async () => {
         fetchMock.mockResolvedValue(okJson({ id: 'v', status: 'success' }));
         const client = makeClient('sk_test');
@@ -114,6 +130,32 @@ describe('PreludeClient', () => {
         );
     });
 
+    it('forwards dispatch_id as a top-level field, not inside signals', async () => {
+        fetchMock.mockResolvedValue(okJson({ id: 'v', status: 'success' }));
+        const client = makeClient('sk_test');
+
+        await client.createVerification('+14155550123', {
+            ip: '203.0.113.7',
+            dispatch_id: 'd1f5e9a0-0000-4000-8000-000000000000',
+        });
+
+        const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+        expect(body.dispatch_id).toBe('d1f5e9a0-0000-4000-8000-000000000000');
+        expect(body.signals).toEqual({ ip: '203.0.113.7' });
+        expect(body.signals).not.toHaveProperty('dispatch_id');
+    });
+
+    it('omits dispatch_id when not supplied', async () => {
+        fetchMock.mockResolvedValue(okJson({ id: 'v', status: 'success' }));
+        const client = makeClient('sk_test');
+
+        await client.createVerification('+14155550123', { ip: '203.0.113.7' });
+
+        expect(JSON.parse(fetchMock.mock.calls[0][1].body)).not.toHaveProperty(
+            'dispatch_id',
+        );
+    });
+
     it('includes a configured template_id + sender_id + preferred channel', async () => {
         fetchMock.mockResolvedValue(okJson({ id: 'v', status: 'success' }));
         const client = new PreludeClient({
@@ -131,6 +173,7 @@ describe('PreludeClient', () => {
         expect(JSON.parse(init.body).options).toEqual({
             code_size: 6,
             preferred_channel: 'sms', // config override beats the rcs default
+            locale: 'en-US',
             template_id: 'tmpl_puter',
             sender_id: 'Puter',
         });

src/backend/clients/prelude/PreludeClient.ts

@@ -42,6 +42,12 @@ export type PreludeChannel =
     | 'viber'
     | 'zalo'
     | 'telegram';
+/**
+ * Channels Prelude reports in a verification's `channels` array — the ordered
+ * delivery sequence, first entry first. Superset of `PreludeChannel`: 'silent'
+ * and 'voice' can appear as delivery methods but can't be preferred.
+ */
+export type PreludeDeliveryChannel = PreludeChannel | 'silent' | 'voice';
 /**
  * Default per-SMS cost ceiling (EUR). Countries whose Prelude SMS rate exceeds
  * this — or that have no SMS channel — are not offered phone verification. The
@@ -117,25 +123,19 @@ export class PreludeClient extends PuterClient {
         return price.sms <= this.maxSmsCostEur;
     }
 
-    /**
-     * Create (or retry) a verification: Prelude sends an OTP to `target`.
-     * @param target E.164 phone number, e.g. "+14155550123".
-     * @param signals Optional anti-fraud signals. The more we forward, the
-     *   better Prelude's fraud model scores the attempt (per their docs IP +
-     *   device + platform are the highest-value). We pass what the backend
-     *   already has: the request `ip`, the client `device_id` (ThumbmarkJS
-     *   hash), and the `user_agent` (Prelude infers platform/model/OS from it).
-     *   Richer client-collected signals require Prelude's frontend SDK, which
-     *   produces a `dispatch_id` the backend would forward here.
-     */
     async createVerification(
         target: string,
         signals: {
             ip?: string;
             device_id?: string;
             user_agent?: string;
+            dispatch_id?: string;
         } = {},
-    ): Promise<{ id?: string; status: PreludeCreateStatus }> {
+    ): Promise<{
+        id?: string;
+        status: PreludeCreateStatus;
+        channels?: PreludeDeliveryChannel[];
+    }> {
         // Match the 6-box code UI (UIWindowPhoneVerificationRequired). Without
         // code_size Prelude uses the dashboard default (4). preferred_channel
         // prioritizes RCS (cheaper); Prelude falls back to SMS when unavailable.
@@ -144,6 +144,7 @@ export class PreludeClient extends PuterClient {
             preferred_channel:
                 this.config.prelude?.preferredChannel ??
                 DEFAULT_PREFERRED_CHANNEL,
+            locale: 'en-US',
         };
         // Branding lives in the Prelude dashboard (the message text is a
         // template); these just select a Puter-branded template / sender when
@@ -163,9 +164,12 @@ export class PreludeClient extends PuterClient {
         if (signals.device_id) sig.device_id = signals.device_id;
         if (signals.user_agent) sig.user_agent = signals.user_agent;
         if (Object.keys(sig).length > 0) body.signals = sig;
+        // dispatch_id is a top-level field, not a member of `signals`.
+        if (signals.dispatch_id) body.dispatch_id = signals.dispatch_id;
         return this.#post('/verification', body) as Promise<{
             id?: string;
             status: PreludeCreateStatus;
+            channels?: PreludeDeliveryChannel[];
         }>;
     }
 

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

@@ -19,6 +19,12 @@
 
 import { Readable } from 'node:stream';
 import type { Request, RequestHandler, Response } from 'express';
+import { trace } from '@opentelemetry/api';
+import {
+    BasicTracerProvider,
+    InMemorySpanExporter,
+    SimpleSpanProcessor,
+} from '@opentelemetry/sdk-trace-base';
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
 import { v4 as uuidv4 } from 'uuid';
 import { actorUid, type Actor } from '../../core/actor.js';
@@ -289,6 +295,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.
@@ -615,4 +772,65 @@ describe('DriverController.registerRoutes', () => {
     });
 });
 
+describe('DriverController.#handleCall tracing', () => {
+    let routes: Captured;
+    const exporter = new InMemorySpanExporter();
+    const provider = new BasicTracerProvider({
+        spanProcessors: [new SimpleSpanProcessor(exporter)],
+    });
+
+    beforeAll(() => {
+        routes = captureRoutes(controller);
+        trace.setGlobalTracerProvider(provider);
+    });
+
+    afterAll(async () => {
+        await provider.shutdown();
+        trace.disable();
+    });
+
+    it('emits driver + downstream spans around a successful call', async () => {
+        const actor = await makeUserActor();
+        await server.stores.permission.setFlatUserPerm(
+            actor.user!.id!,
+            'service:puter-kvstore:ii:puter-kvstore',
+            {
+                permission: 'service:puter-kvstore:ii:puter-kvstore',
+                deleted: false,
+                issuer_user_id: actor.user!.id!,
+            } as never,
+        );
+        exporter.reset();
+
+        const res = makeRes();
+        const req = makeReq(
+            {
+                interface: 'puter-kvstore',
+                method: 'set',
+                args: { key: `k-${uuidv4()}`, value: 'v' },
+            },
+            actor,
+        );
+        await runWithContext({ actor }, () =>
+            routes['POST /call'](req, res as unknown as Response, () => {}),
+        );
+        expect((res.body as { success: boolean }).success).toBe(true);
+
+        const names = exporter.getFinishedSpans().map((s) => s.name);
+        const driverSpan = exporter
+            .getFinishedSpans()
+            .find((s) => s.name === 'driver.puter-kvstore.set');
+        expect(driverSpan).toBeDefined();
+        expect(driverSpan!.attributes).toMatchObject({
+            driver: 'puter-kvstore',
+            'driver.method': 'set',
+            'driver.name': 'puter-kvstore',
+        });
+        // The call path exercises the permission gate and the KV store's
+        // dynamo writes — both should have produced spans of their own.
+        expect(names).toContain('permission.scan');
+        expect(names.some((n) => n.startsWith('ddb.'))).toBe(true);
+    });
+});
+
 void vi; // unused but reserved for future expansion

src/backend/controllers/drivers/DriverController.ts

@@ -3,18 +3,19 @@
  *
  * 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.
+ * 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.
+ * 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/>.
+ * along with this program. If not, see
+ * [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
  */
 
 import type { Request, Response } from 'express';
@@ -22,6 +23,7 @@ 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,
@@ -37,6 +40,7 @@ import {
 import type { PermissionService } from '../../services/permission/PermissionService.js';
 import { PermissionUtil } from '../../services/permission/permissionUtil.js';
 import type { WithLifecycle } from '../../types';
+import { withSpan } from '../../util/span.js';
 import { PuterController } from '../types.js';
 
 type DriverInstance = WithLifecycle & Record<string, unknown>;
@@ -113,15 +117,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);
@@ -200,14 +212,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.
@@ -218,6 +235,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
@@ -256,7 +287,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,
@@ -382,11 +412,22 @@ export class DriverController extends PuterController {
         }
 
         // Drivers read actor/context via the Context API — no drilled args.
+        // The span ends when the method returns; for streamed results that
+        // is stream start, not stream drain (same window the lifecycle
+        // events below report as durationMs).
         const startedAt = Date.now();
         let result;
         try {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            result = await (fn as (...x: unknown[]) => any).call(driver, args);
+            result = await withSpan(
+                `driver.${ifaceName}.${method}`,
+                {
+                    driver: ifaceName,
+                    'driver.method': method,
+                    'driver.name': resolved,
+                },
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                () => (fn as (...x: unknown[]) => any).call(driver, args),
+            );
         } catch (e) {
             this.clients.event?.emit(
                 `driver.${ifaceName}.${method}.error`,
@@ -487,10 +528,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/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

@@ -3,24 +3,25 @@
  *
  * 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.
+ * 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.
+ * 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/>.
+ * along with this program. If not, see
+ * [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
  */
 
 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 { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
 import type { Actor } from '../../core/actor.js';
 import { runWithContext } from '../../core/context.js';
 import { PuterServer } from '../../server.js';
@@ -28,9 +29,9 @@ 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 +92,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 +170,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 +211,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 +337,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 +361,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 +414,7 @@ describe('FSController.completeBatchWrites', () => {
             ),
         );
         const [firstResponse] = firstStart.captured
-            .body as SignedWriteResponse[];
+            .body as ClientSignedWriteResponse[];
         const firstComplete = makeRes();
         await withActor(actor, () =>
             controller.completeBatchWrites(
@@ -424,7 +446,7 @@ describe('FSController.completeBatchWrites', () => {
             ),
         );
         const [secondResponse] = secondStart.captured
-            .body as SignedWriteResponse[];
+            .body as ClientSignedWriteResponse[];
 
         const secondComplete = makeRes();
         await withActor(actor, () =>
@@ -464,20 +486,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 +545,7 @@ describe('FSController.completeBatchWrites', () => {
             ),
         );
         const [firstResponse] = firstStart.captured
-            .body as SignedWriteResponse[];
+            .body as ClientSignedWriteResponse[];
         await withActor(actor, () =>
             controller.completeBatchWrites(
                 makeReq<CompleteWriteRequest[]>({
@@ -555,7 +582,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 +662,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 +723,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 +875,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',
+        });
     });
 });
 
@@ -1510,6 +1576,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: Actor = {
+            ...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', () => {
@@ -1992,3 +2598,112 @@ describe('FSController metadata.objectKey injection', () => {
         expect(await streamToString(read.body)).toBe(attackerDecoy);
     });
 });
+
+// ── associatedAppId entitlement gate ────────────────────────────────
+//
+// `associatedAppId` is client-supplied write metadata that's echoed back in
+// legacy FS responses. Binding a file to another tenant's private app would
+// turn `/stat` into an app-row enumeration oracle, so the write path drops
+// any association the actor isn't entitled to make.
+
+describe('FSController associatedAppId entitlement gate', () => {
+    // Seed an app row with a direct insert. `create` treats is_private as a
+    // read-only column, and going through the store would prime the cache —
+    // a raw insert leaves nothing cached so the gate's getById reads the DB.
+    const makeApp = async (
+        ownerUserId: number,
+        opts: { is_private?: boolean } = {},
+    ): Promise<{ id: number }> => {
+        const uid = `app-${uuidv4()}`;
+        await server.clients.db.write(
+            `INSERT INTO \`apps\` (\`uid\`, \`name\`, \`title\`, \`index_url\`, \`owner_user_id\`, \`is_private\`)
+             VALUES (?, ?, ?, ?, ?, ?)`,
+            [
+                uid,
+                uid,
+                'Gate App',
+                'https://gate-app.puter.site/',
+                ownerUserId,
+                opts.is_private ? 1 : 0,
+            ],
+        );
+        const row = (
+            await server.clients.db.read('SELECT id FROM apps WHERE uid = ?', [
+                uid,
+            ])
+        )[0] as { id: number };
+        return { id: row.id };
+    };
+
+    // Write a file via the signed-write flow with the given associatedAppId
+    // and return the committed entry's stored associatedAppId.
+    const writeWithAssociation = async (
+        actor: Actor,
+        path: string,
+        associatedAppId: number,
+    ): Promise<number | null> => {
+        const startRes = makeRes();
+        await withActor(actor, () =>
+            controller.startBatchWrites(
+                makeReq<SignedWriteRequest[]>({
+                    body: [
+                        { fileMetadata: { path, size: 3, associatedAppId } },
+                    ],
+                    actor,
+                }),
+                startRes.res,
+            ),
+        );
+        const [started] = startRes.captured.body as ClientSignedWriteResponse[];
+        const completeRes = makeRes();
+        await withActor(actor, () =>
+            controller.completeBatchWrites(
+                makeReq<CompleteWriteRequest[]>({
+                    body: [{ uploadId: started.sessionId }],
+                    actor,
+                }),
+                completeRes.res,
+            ),
+        );
+        const entry = await server.stores.fsEntry.getEntryByPath(path);
+        return entry?.associatedAppId ?? null;
+    };
+
+    it("drops an association to another tenant's private app", async () => {
+        const victim = await makeUser();
+        const attacker = await makeUser();
+        const victimApp = await makeApp(victim.userId, { is_private: true });
+
+        const stored = await writeWithAssociation(
+            attacker.actor,
+            `/${attacker.actor.user!.username}/Documents/probe.txt`,
+            victimApp.id,
+        );
+        expect(stored).toBeNull();
+    });
+
+    it('keeps an association to a public app the actor does not own', async () => {
+        const owner = await makeUser();
+        const other = await makeUser();
+        const publicApp = await makeApp(owner.userId, { is_private: false });
+
+        const stored = await writeWithAssociation(
+            other.actor,
+            `/${other.actor.user!.username}/Documents/public-assoc.txt`,
+            publicApp.id,
+        );
+        expect(stored).toBe(publicApp.id);
+    });
+
+    it('keeps an association to the actor’s own private app', async () => {
+        const owner = await makeUser();
+        const ownApp = await makeApp(owner.userId, { is_private: true });
+
+        const stored = await writeWithAssociation(
+            owner.actor,
+            `/${owner.actor.user!.username}/Documents/own-assoc.txt`,
+            ownApp.id,
+        );
+        expect(stored).toBe(ownApp.id);
+    });
+});

src/backend/controllers/fs/FSController.ts

@@ -3,18 +3,19 @@
  *
  * 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.
+ * 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.
+ * 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/>.
+ * along with this program. If not, see
+ * [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
  */
 
 import Busboy from 'busboy';
@@ -40,13 +41,24 @@ import {
 import { applyInlineContentSecurity } from '../../util/inlineContentSecurity.js';
 import { PuterController } from '../types.js';
 import { FS_COSTS } from './costs.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 +72,6 @@ import type {
     ThumbnailUploadPrepareItem,
     ThumbnailUploadPreparePayload,
 } from './types.js';
-import { toLegacyEntry } from './legacyFsHelpers.js';
 class UploadProgressTracker implements UploadProgressTrackerLike {
     total = 0;
     progress = 0;
@@ -89,6 +100,8 @@ 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;
 
@@ -106,7 +119,7 @@ export class FSController extends PuterController {
     @Post('/startWrite', { subdomain: 'api', requireVerified: true })
     async startWrite(
         req: Request<RouteParams, null, SignedWriteRequest>,
-        res: Response<SignedWriteResponse>,
+        res: Response<ClientSignedWriteResponse>,
     ) {
         const userId = this.#getActorUserId(req);
         const storageAllowanceMax = this.#getStorageAllowanceMaxOverride(req);
@@ -119,6 +132,8 @@ export class FSController extends PuterController {
         requestBody.fileMetadata = await this.#resolveAssociatedAppMetadata(
             requestBody.fileMetadata,
             requestBody,
+            undefined,
+            userId,
         );
         await this.#assertWriteAccess(req, requestBody.fileMetadata, {
             pathAlreadyNormalized: true,
@@ -154,13 +169,15 @@ export class FSController extends PuterController {
                 }
             }, 'emitStartWriteDirectoryEvents');
         }
-        res.json(response);
+        res.json(
+            this.#withoutStorageInternals(this.#withClientFsEntry(response)),
+        );
     }
 
     @Post('/startBatchWrite', { subdomain: 'api', requireVerified: true })
     async startBatchWrites(
         req: Request<RouteParams, null, SignedWriteRequest[]>,
-        res: Response<SignedWriteResponse[]>,
+        res: Response<ClientSignedWriteResponse[]>,
     ) {
         const userId = this.#getActorUserId(req);
         const storageAllowanceMax = this.#getStorageAllowanceMaxOverride(req);
@@ -183,6 +200,7 @@ export class FSController extends PuterController {
                               normalizedRequestBody.fileMetadata,
                               normalizedRequestBody,
                               appUidLookupCache,
+                              userId,
                           );
                       return normalizedRequestBody;
                   }),
@@ -249,13 +267,17 @@ 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 })
     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);
@@ -275,13 +297,18 @@ 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 })
     async completeBatchWrites(
         req: Request<RouteParams, null, CompleteWriteRequest[]>,
-        res: Response<CompleteWriteResponse[]>,
+        res: Response<ClientCompleteWriteResponse[]>,
     ) {
         const userId = this.#getActorUserId(req);
         const requests = Array.isArray(req.body)
@@ -316,7 +343,9 @@ 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 })
@@ -338,20 +367,20 @@ export class FSController extends PuterController {
     @Post('/signMultipartParts', { subdomain: 'api', requireVerified: true })
     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 })
     async write(
         req: Request<RouteParams, null, WriteRequest>,
-        res: Response<WriteResponse>,
+        res: Response<ClientWriteResponse>,
     ) {
         const userId = this.#getActorUserId(req);
         const storageAllowanceMax = this.#getStorageAllowanceMaxOverride(req);
@@ -364,6 +393,8 @@ export class FSController extends PuterController {
         requestBody.fileMetadata = await this.#resolveAssociatedAppMetadata(
             requestBody.fileMetadata,
             requestBody,
+            undefined,
+            userId,
         );
         await this.#assertWriteAccess(req, requestBody.fileMetadata, {
             pathAlreadyNormalized: true,
@@ -389,13 +420,13 @@ export class FSController extends PuterController {
             response,
             requestBody.guiMetadata,
         );
-        res.json(updatedResponse);
+        res.json(this.#withRequiredClientFsEntry(updatedResponse));
     }
 
     @Post('/batchWrite', { subdomain: 'api', requireVerified: true })
     async batchWrites(
         req: Request<RouteParams, null, WriteRequest[]>,
-        res: Response<WriteResponse[]>,
+        res: Response<ClientWriteResponse[]>,
     ) {
         const userId = this.#getActorUserId(req);
         const storageAllowanceMax = this.#getStorageAllowanceMaxOverride(req);
@@ -497,6 +528,7 @@ export class FSController extends PuterController {
                                                 item.fileMetadata,
                                                 item,
                                                 appUidLookupCache,
+                                                userId,
                                             ),
                                     })),
                                 ),
@@ -696,7 +728,9 @@ export class FSController extends PuterController {
                     );
                 },
             );
-            res.json(updatedResponses);
+            res.json(
+                updatedResponses.map((r) => this.#withRequiredClientFsEntry(r)),
+            );
             return;
         }
 
@@ -718,6 +752,7 @@ export class FSController extends PuterController {
                               normalizedRequestBody.fileMetadata,
                               normalizedRequestBody,
                               appUidLookupCache,
+                              userId,
                           );
                       return normalizedRequestBody;
                   }),
@@ -815,7 +850,9 @@ export class FSController extends PuterController {
                 );
             },
         );
-        res.json(updatedResponses);
+        res.json(
+            updatedResponses.map((r) => this.#withRequiredClientFsEntry(r)),
+        );
     }
 
     // -- Read-side routes ------------------------------------------------
@@ -838,17 +875,135 @@ export class FSController extends PuterController {
             await this.services.suggestedApps.getSuggestedApps(entry);
 
         res.json({
-            ...entry,
+            ...this.#toClientEntry(entry),
             ...(subtreeSize !== undefined ? { size: subtreeSize } : {}),
         });
     }
 
+    /**
+     * 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 })
+    async readdirEntriesViaGet(req: Request, res: Response) {
+        return this.readdirEntries(req, res);
+    }
+
     @Post('/readdir', { subdomain: 'api', requireVerified: true })
     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(
@@ -866,54 +1021,155 @@ 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 })
@@ -1061,7 +1317,7 @@ export class FSController extends PuterController {
                 ) ?? false,
         });
         this.#emitGuiItemAdded(entry);
-        res.json(entry);
+        res.json(this.#toClientEntry(entry));
     }
 
     @Post('/touch', { subdomain: 'api', requireVerified: true })
@@ -1097,7 +1353,7 @@ 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 })
@@ -1115,7 +1371,7 @@ 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 })
@@ -1161,7 +1417,7 @@ 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 })
@@ -1189,7 +1445,7 @@ export class FSController extends PuterController {
                 this.#toBoolean(body.dedupe_name ?? body.change_name) ?? true,
         });
         this.#emitGuiItemAdded(copy);
-        res.json(copy);
+        res.json(this.#toClientEntry(copy));
     }
 
     @Post('/mkshortcut', { subdomain: 'api', requireVerified: true })
@@ -1218,7 +1474,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 -----------------------------------------------
@@ -1273,12 +1529,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);
@@ -1695,6 +1951,7 @@ export class FSController extends PuterController {
         fileMetadata: FSEntryWriteInput,
         fallbackSource?: unknown,
         appUidLookupCache?: Map<string, Promise<number | null>>,
+        actorUserId?: number,
     ): Promise<FSEntryWriteInput> {
         const metadataRecord = this.#toObjectRecord(fileMetadata);
         const fallbackRecord = this.#toObjectRecord(fallbackSource);
@@ -1708,10 +1965,11 @@ export class FSController extends PuterController {
             ),
         );
         if (associatedAppId !== undefined) {
-            return {
-                ...fileMetadata,
+            return this.#withAssociatedAppId(
+                fileMetadata,
                 associatedAppId,
-            };
+                actorUserId,
+            );
         }
 
         const appUid = this.#firstDefined(
@@ -1745,9 +2003,46 @@ export class FSController extends PuterController {
         if (resolvedAppId === null) {
             return fileMetadata;
         }
+        return this.#withAssociatedAppId(
+            fileMetadata,
+            resolvedAppId,
+            actorUserId,
+        );
+    }
+
+    /**
+     * 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.
+     *
+     * `#resolveWriteFileMetadata` has already copied the raw client value onto
+     * `fileMetadata`, so a dropped association must be actively stripped — not
+     * merely left unset.
+     */
+    async #withAssociatedAppId(
+        fileMetadata: FSEntryWriteInput,
+        appId: number,
+        actorUserId?: number,
+    ): Promise<FSEntryWriteInput> {
+        const app = await this.stores.app.getById(appId);
+        const isPrivate =
+            !!app && (Boolean(app.is_private) || Boolean(app.protected));
+        const isOwner =
+            actorUserId !== undefined &&
+            this.#toNumber(app?.owner_user_id) === actorUserId;
+        if (!app || (isPrivate && !isOwner)) {
+            const { associatedAppId: _dropped, ...rest } =
+                fileMetadata as unknown as Record<string, unknown>;
+            return rest as unknown as FSEntryWriteInput;
+        }
         return {
             ...fileMetadata,
-            associatedAppId: resolvedAppId,
+            associatedAppId: appId,
         };
     }
 
@@ -1764,8 +2059,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),

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

@@ -18,12 +18,15 @@
  */
 
 import type { Request, Response } from 'express';
+import { 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 { runWithContext } from '../../core/context.js';
+import { PuterRouter } from '../../core/http/PuterRouter.js';
 import { PuterServer } from '../../server.js';
 import { setupTestServer } from '../../testUtil.js';
+import { signFile } from '../../util/fileSigning.js';
 import { generateDefaultFsentries } from '../../util/userProvisioning.js';
 import type { LegacyFSController } from './LegacyFSController.js';
 
@@ -688,6 +691,59 @@ describe('LegacyFSController.readdir', () => {
             ),
         ).rejects.toMatchObject({ statusCode: 400 });
     });
+
+    it('pages children with cursors and reports totals', async () => {
+        const { actor } = await makeUser();
+        const username = actor.user!.username!;
+        for (const name of ['p1', 'p2', 'p3']) {
+            await withActor(actor, () =>
+                controller.mkdir(
+                    makeReq({
+                        body: { path: `/${username}/Documents/${name}` },
+                        actor,
+                    }),
+                    makeRes().res,
+                ),
+            );
+        }
+
+        const readdir = async (body: Record<string, unknown>) => {
+            const { res, captured } = makeRes();
+            await withActor(actor, () =>
+                controller.readdir(makeReq({ body, actor }), res),
+            );
+            return captured.body;
+        };
+
+        const seen: string[] = [];
+        let cursor: string | null | undefined = null;
+        let total: number | undefined;
+        do {
+            const page = (await readdir({
+                path: `/${username}/Documents`,
+                limit: 2,
+                cursor,
+                includeTotal: true,
+            })) as {
+                items: Array<{ name: string }>;
+                cursor?: string;
+                total?: number;
+            };
+            seen.push(...page.items.map((e) => e.name));
+            total = page.total;
+            cursor = page.cursor;
+        } while (cursor);
+        expect(seen).toEqual(['p1', 'p2', 'p3']);
+        expect(total).toBe(3);
+
+        // Legacy limit-only requests keep the bare array response.
+        const bare = await readdir({
+            path: `/${username}/Documents`,
+            limit: 2,
+        });
+        expect(Array.isArray(bare)).toBe(true);
+        expect((bare as unknown[]).length).toBe(2);
+    });
 });
 
 // ── copy ────────────────────────────────────────────────────────────
@@ -720,13 +776,9 @@ describe('LegacyFSController.copy', () => {
             copied: { path: string; name: string };
         }>;
         expect(body).toHaveLength(1);
-        expect(body[0].copied.path).toBe(
-            `/${username}/Pictures/src-folder`,
-        );
+        expect(body[0].copied.path).toBe(`/${username}/Pictures/src-folder`);
         // The original still exists; the copy lives under Pictures.
-        expect(
-            await server.stores.fsEntry.getEntryByPath(src),
-        ).not.toBeNull();
+        expect(await server.stores.fsEntry.getEntryByPath(src)).not.toBeNull();
         expect(
             await server.stores.fsEntry.getEntryByPath(
                 `/${username}/Pictures/src-folder`,
@@ -761,9 +813,120 @@ describe('LegacyFSController.copy', () => {
         );
 
         const body = captured.body as Array<{ copied: { path: string } }>;
-        expect(body[0].copied.path).toBe(
-            `/${username}/Pictures/renamed-copy`,
+        expect(body[0].copied.path).toBe(`/${username}/Pictures/renamed-copy`);
+    });
+
+    it('copies an empty file (no backing S3 object) without erroring', async () => {
+        // Empty files created via /touch have size 0 and no S3 object —
+        // bucket is null. Copy must clone them as empty-file entries rather
+        // than issuing a CopyObject, which would throw S3 NoSuchKey.
+        const { actor } = await makeUser();
+        const username = actor.user!.username!;
+        const src = `/${username}/Documents/empty.txt`;
+        await withActor(actor, () =>
+            controller.touch(
+                makeReq({ body: { path: src }, actor }),
+                makeRes().res,
+            ),
         );
+
+        const { res, captured } = makeRes();
+        await withActor(actor, () =>
+            controller.copy(
+                makeReq({
+                    body: { source: src, destination: `/${username}/Pictures` },
+                    actor,
+                }),
+                res,
+            ),
+        );
+
+        const body = captured.body as Array<{ copied: { path: string } }>;
+        expect(body[0].copied.path).toBe(`/${username}/Pictures/empty.txt`);
+        const copied = await server.stores.fsEntry.getEntryByPath(
+            `/${username}/Pictures/empty.txt`,
+        );
+        expect(copied).not.toBeNull();
+        expect(copied!.size).toBe(0);
+        // Original is untouched.
+        expect(await server.stores.fsEntry.getEntryByPath(src)).not.toBeNull();
+    });
+
+    it('copying a ghost file (S3 object missing) 404s and cleans up the orphan', async () => {
+        // A real file whose backing S3 object has vanished keeps a non-null
+        // bucket, so it isn't an empty file. CopyObject would throw S3
+        // NoSuchKey; copy must surface a clean 404 and remove the orphan row
+        // rather than bubbling a 500. Mirrors readContent's ghost handling.
+        const { actor, userId } = await makeUser();
+        const username = actor.user!.username!;
+        const src = `/${username}/Documents/ghost.txt`;
+        const content = Buffer.from('i will be deleted from s3');
+        await server.services.fs.write(userId, {
+            fileMetadata: {
+                path: src,
+                size: content.byteLength,
+                contentType: 'text/plain',
+            },
+            fileContent: content,
+        });
+
+        // Delete the backing S3 object directly, leaving the DB row behind.
+        const entry = (await server.stores.fsEntry.getEntryByPath(src))!;
+        await server.stores.s3Object.deleteObject(
+            server.stores.s3Object.resolveBucket(entry.bucket),
+            entry.uuid,
+            server.stores.s3Object.resolveRegion(entry.bucketRegion),
+        );
+
+        const { res } = makeRes();
+        await expect(
+            withActor(actor, () =>
+                controller.copy(
+                    makeReq({
+                        body: {
+                            source: src,
+                            destination: `/${username}/Pictures`,
+                        },
+                        actor,
+                    }),
+                    res,
+                ),
+            ),
+        ).rejects.toMatchObject({ statusCode: 404 });
+
+        // The ghost handler removed the orphaned source row.
+        expect(await server.stores.fsEntry.getEntryByPath(src)).toBeNull();
+        // No partial copy was left behind.
+        expect(
+            await server.stores.fsEntry.getEntryByPath(
+                `/${username}/Pictures/ghost.txt`,
+            ),
+        ).toBeNull();
+    });
+
+    it('reads an empty file as empty content without deleting it', async () => {
+        // Reading an empty file (no S3 object) must not throw NoSuchKey nor
+        // trip the ghost-file cleanup, which would delete the entry.
+        const { actor } = await makeUser();
+        const username = actor.user!.username!;
+        const src = `/${username}/Documents/readme-empty.txt`;
+        await withActor(actor, () =>
+            controller.touch(
+                makeReq({ body: { path: src }, actor }),
+                makeRes().res,
+            ),
+        );
+        const entry = (await server.stores.fsEntry.getEntryByPath(src))!;
+
+        const download = await server.services.fs.readContent(entry);
+        const chunks: Buffer[] = [];
+        for await (const chunk of download.body) {
+            chunks.push(Buffer.from(chunk as Uint8Array));
+        }
+        expect(Buffer.concat(chunks).byteLength).toBe(0);
+        expect(download.contentLength).toBe(0);
+        // The entry must still exist — the ghost handler must NOT have run.
+        expect(await server.stores.fsEntry.getEntryByPath(src)).not.toBeNull();
     });
 });
 
@@ -876,10 +1039,7 @@ describe('LegacyFSController.search', () => {
 
         const { res, captured } = makeRes();
         await withActor(actor, () =>
-            controller.search(
-                makeReq({ body: { query: needle }, actor }),
-                res,
-            ),
+            controller.search(makeReq({ body: { query: needle }, actor }), res),
         );
         const results = captured.body as Array<{ name: string }>;
         expect(Array.isArray(results)).toBe(true);
@@ -931,9 +1091,7 @@ describe('LegacyFSController.search', () => {
             ).toBe(true);
         }
         expect(
-            results.some(
-                (r) => r.path === `/${username}/Documents/${needle}`,
-            ),
+            results.some((r) => r.path === `/${username}/Documents/${needle}`),
         ).toBe(false);
     });
 });
@@ -1013,10 +1171,7 @@ describe('LegacyFSController.sign', () => {
         const { res } = makeRes();
         await expect(
             withActor(actor, () =>
-                controller.sign(
-                    makeReq({ body: { items: [] }, actor }),
-                    res,
-                ),
+                controller.sign(makeReq({ body: { items: [] }, actor }), res),
             ),
         ).rejects.toMatchObject({ statusCode: 400 });
     });
@@ -1171,6 +1326,113 @@ describe('LegacyFSController.writeFile', () => {
     });
 });
 
+// ── writeFile (write IDOR: authorized subject must equal write target) ─
+//
+// Holding a write signature + write ACL on a single file must not let the
+// caller redirect the upload to an attacker-named sibling via the `name`
+// field. The write has to land on the signed file itself.
+
+describe('LegacyFSController.writeFile (write IDOR)', () => {
+    const signingCfgOf = () => {
+        const cfg = (
+            controller as unknown as {
+                config: {
+                    api_base_url?: string;
+                    url_signature_secret?: string;
+                };
+            }
+        ).config;
+        cfg.api_base_url = cfg.api_base_url ?? 'http://api.test.local';
+        cfg.url_signature_secret =
+            cfg.url_signature_secret ?? 'test-signing-secret';
+        return {
+            secret: cfg.url_signature_secret,
+            apiBaseUrl: cfg.api_base_url,
+        };
+    };
+
+    const multipartWriteReq = (opts: {
+        actor: Actor;
+        uid: string;
+        expires: string;
+        signature: string;
+        name?: string;
+        content: string;
+    }): Request => {
+        const boundary = '----lfsWriteIdorBoundary';
+        const payload =
+            `--${boundary}\r\n` +
+            'Content-Disposition: form-data; name="file"; ' +
+            'filename="upload.bin"\r\n' +
+            'Content-Type: application/octet-stream\r\n\r\n' +
+            `${opts.content}\r\n` +
+            `--${boundary}--\r\n`;
+        const req = Readable.from([Buffer.from(payload)]) as unknown as Request;
+        Object.assign(req, {
+            headers: {
+                'content-type': `multipart/form-data; boundary=${boundary}`,
+            },
+            query: {
+                uid: opts.uid,
+                expires: opts.expires,
+                signature: opts.signature,
+                operation: 'write',
+            },
+            body: opts.name !== undefined ? { name: opts.name } : {},
+            actor: opts.actor,
+        });
+        return req;
+    };
+
+    it('writes to the signed file, not an attacker-named sibling', async () => {
+        const victim = await makeUser();
+        const attacker = await makeUser();
+        const dir = `/${victim.actor.user!.username}/Documents`;
+        const target = `${dir}/secret.txt`;
+        const sibling = `${dir}/passwords.txt`;
+
+        // Victim owns a single file; attacker gets write on just that file.
+        await withActor(victim.actor, () =>
+            controller.touch(
+                makeReq({ body: { path: target }, actor: victim.actor }),
+                makeRes().res,
+            ),
+        );
+        const entry = await server.stores.fsEntry.getEntryByPath(target);
+        expect(entry).toBeTruthy();
+        await server.services.permission.grantUserUserPermission(
+            victim.actor,
+            attacker.actor.user!.username!,
+            `fs:${entry!.uuid}:write`,
+            {},
+        );
+
+        const writeUrl = new URL(signFile(entry!, signingCfgOf()).write_url!);
+
+        const { res, captured } = makeRes();
+        await withActor(attacker.actor, () =>
+            controller.writeFile(
+                multipartWriteReq({
+                    actor: attacker.actor,
+                    uid: writeUrl.searchParams.get('uid')!,
+                    expires: writeUrl.searchParams.get('expires')!,
+                    signature: writeUrl.searchParams.get('signature')!,
+                    name: 'passwords.txt',
+                    content: 'attacker-bytes',
+                }),
+                res,
+            ),
+        );
+
+        // The write landed on the signed file …
+        expect((captured.body as { path?: string }).path).toBe(target);
+        // … and never created the attacker-named sibling.
+        const siblingEntry =
+            await server.stores.fsEntry.getEntryByPath(sibling);
+        expect(siblingEntry).toBeFalsy();
+    });
+});
+
 // ── file (validation paths) ─────────────────────────────────────────
 
 describe('LegacyFSController.file', () => {
@@ -1318,10 +1580,7 @@ describe('LegacyFSController.requestAppRootDir', () => {
         const { res } = makeRes();
         await expect(
             withActor(actor, () =>
-                controller.requestAppRootDir(
-                    makeReq({ body: {}, actor }),
-                    res,
-                ),
+                controller.requestAppRootDir(makeReq({ body: {}, actor }), res),
             ),
         ).rejects.toMatchObject({ statusCode: 400 });
     });
@@ -1497,10 +1756,7 @@ describe('LegacyFSController.down', () => {
         const { res } = makeRes();
         await expect(
             withActor(actor, () =>
-                controller.down(
-                    makeReq({ query: { path: '/' }, actor }),
-                    res,
-                ),
+                controller.down(makeReq({ query: { path: '/' }, actor }), res),
             ),
         ).rejects.toMatchObject({ statusCode: 400 });
     });
@@ -1557,9 +1813,9 @@ describe('LegacyFSController.mkdir additional branches', () => {
             }),
             actor: undefined,
         } as unknown as Request;
-        await expect(
-            controller.mkdir(req, res),
-        ).rejects.toMatchObject({ statusCode: 401 });
+        await expect(controller.mkdir(req, res)).rejects.toMatchObject({
+            statusCode: 401,
+        });
     });
 });
 
@@ -1579,17 +1835,12 @@ describe('LegacyFSController.delete additional branches', () => {
 
         const { res, captured } = makeRes();
         await withActor(actor, () =>
-            controller.delete(
-                makeReq({ body: { path: target }, actor }),
-                res,
-            ),
+            controller.delete(makeReq({ body: { path: target }, actor }), res),
         );
         const body = captured.body as { ok: boolean; uid: string };
         expect(body.ok).toBe(true);
         expect(typeof body.uid).toBe('string');
-        expect(
-            await server.stores.fsEntry.getEntryByPath(target),
-        ).toBeNull();
+        expect(await server.stores.fsEntry.getEntryByPath(target)).toBeNull();
     });
 
     it('forwards descendants_only into fs.remove', async () => {
@@ -1720,9 +1971,9 @@ describe('LegacyFSController.df actor gate', () => {
             ...makeReq({ body: {}, actor }),
             actor: undefined,
         } as unknown as Request;
-        await expect(
-            controller.df(req, makeRes().res),
-        ).rejects.toMatchObject({ statusCode: 401 });
+        await expect(controller.df(req, makeRes().res)).rejects.toMatchObject({
+            statusCode: 401,
+        });
     });
 });
 
@@ -1739,7 +1990,8 @@ describe('LegacyFSController.down file streaming', () => {
             ended: false,
         };
         // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const { Writable } = require('node:stream') as typeof import('node:stream');
+        const { Writable } =
+            require('node:stream') as typeof import('node:stream');
         const writable = new Writable({
             write(chunk: Buffer, _enc, cb) {
                 captured.bodyChunks.push(chunk);
@@ -1785,18 +2037,19 @@ describe('LegacyFSController.down file streaming', () => {
 
         const { res, captured } = makeStreamingRes();
         await withActor(actor, () =>
-            controller.down(
-                makeReq({ query: { path: target }, actor }),
-                res,
-            ),
+            controller.down(makeReq({ query: { path: target }, actor }), res),
         );
         await new Promise<void>((resolve) => setImmediate(resolve));
 
         expect(captured.statusCode).toBe(200);
         // /down forces octet-stream regardless of the entry's true type.
-        expect(captured.headers['Content-Type']).toBe('application/octet-stream');
+        expect(captured.headers['Content-Type']).toBe(
+            'application/octet-stream',
+        );
         expect(captured.headers['Content-Disposition']).toMatch(/^attachment;/);
-        expect(captured.headers['Content-Length']).toBe(String(body.byteLength));
+        expect(captured.headers['Content-Length']).toBe(
+            String(body.byteLength),
+        );
         // The piped bytes match the file contents.
         await new Promise<void>((resolve) => setImmediate(resolve));
         if (captured.bodyChunks.length > 0) {
@@ -1843,7 +2096,8 @@ describe('LegacyFSController.read file streaming', () => {
             bodyChunks: [] as Buffer[],
         };
         // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const { Writable } = require('node:stream') as typeof import('node:stream');
+        const { Writable } =
+            require('node:stream') as typeof import('node:stream');
         const writable = new Writable({
             write(chunk: Buffer, _enc, cb) {
                 captured.bodyChunks.push(chunk);
@@ -1886,18 +2140,19 @@ describe('LegacyFSController.read file streaming', () => {
 
         const { res, captured } = makeStreamingRes();
         await withActor(actor, () =>
-            controller.read(
-                makeReq({ query: { file: target }, actor }),
-                res,
-            ),
+            controller.read(makeReq({ query: { file: target }, actor }), res),
         );
         await new Promise<void>((resolve) => setImmediate(resolve));
 
         expect(captured.statusCode).toBe(200);
         // The v1 contract is octet-stream regardless of real mime; /fs/read
         // (v2) is the type-aware variant. This is documented in the controller.
-        expect(captured.headers['Content-Type']).toBe('application/octet-stream');
-        expect(captured.headers['Content-Length']).toBe(String(body.byteLength));
+        expect(captured.headers['Content-Type']).toBe(
+            'application/octet-stream',
+        );
+        expect(captured.headers['Content-Length']).toBe(
+            String(body.byteLength),
+        );
     });
 
     it('honors options.realMime by forwarding the real content-type from mime-types', async () => {
@@ -1921,7 +2176,10 @@ describe('LegacyFSController.read file streaming', () => {
             controller.read(
                 makeReq({ query: { file: target }, actor }),
                 res,
-                { realMime: true } as never,
+                undefined,
+                {
+                    realMime: true,
+                },
             ),
         );
         expect(captured.headers['Content-Type']).toMatch(/text\/html/);
@@ -2027,10 +2285,7 @@ describe('LegacyFSController.search fallback fields', () => {
         );
         const { res, captured } = makeRes();
         await withActor(actor, () =>
-            controller.search(
-                makeReq({ body: { text: needle }, actor }),
-                res,
-            ),
+            controller.search(makeReq({ body: { text: needle }, actor }), res),
         );
         const results = captured.body as Array<{ name: string }>;
         expect(results.some((r) => r.name === needle)).toBe(true);
@@ -2145,7 +2400,9 @@ describe('LegacyFSController.batch additional operations', () => {
             ),
         );
         expect(captured.statusCode).toBe(200);
-        const body = captured.body as { results: Array<Record<string, unknown>> };
+        const body = captured.body as {
+            results: Array<Record<string, unknown>>;
+        };
         expect(body.results).toHaveLength(1);
     });
 
@@ -2173,12 +2430,10 @@ describe('LegacyFSController.batch additional operations', () => {
             ),
         );
         expect(captured.statusCode).toBe(200);
-        expect(
-            await server.stores.fsEntry.getEntryByPath(target),
-        ).toBeNull();
+        expect(await server.stores.fsEntry.getEntryByPath(target)).toBeNull();
     });
 
-    it("runs a `shortcut` op pointing at an existing target uid", async () => {
+    it('runs a `shortcut` op pointing at an existing target uid', async () => {
         const { actor } = await makeUser();
         const username = actor.user!.username!;
         const target = `/${username}/Documents/batch-sc-target`;
@@ -2326,10 +2581,7 @@ describe('LegacyFSController.suggestApps', () => {
             ),
         );
 
-        const spy = vi.spyOn(
-            server.services.suggestedApps,
-            'getSuggestedApps',
-        );
+        const spy = vi.spyOn(server.services.suggestedApps, 'getSuggestedApps');
         try {
             const { res } = makeRes();
             await withActor(appActor, () =>
@@ -2361,10 +2613,7 @@ describe('LegacyFSController.suggestApps', () => {
             ),
         );
 
-        const spy = vi.spyOn(
-            server.services.suggestedApps,
-            'getSuggestedApps',
-        );
+        const spy = vi.spyOn(server.services.suggestedApps, 'getSuggestedApps');
         try {
             const { res } = makeRes();
             await withActor(actor, () =>
@@ -2417,10 +2666,7 @@ describe('LegacyFSController.readdirSubdomains', () => {
 
         const { res, captured } = makeRes();
         await withActor(actor, () =>
-            controller.readdirSubdomains(
-                makeReq({ body: {}, actor }),
-                res,
-            ),
+            controller.readdirSubdomains(makeReq({ body: {}, actor }), res),
         );
         const rows = captured.body as Array<{ subdomain: string }>;
         expect(rows.some((r) => r.subdomain === sd)).toBe(true);
@@ -2498,3 +2744,190 @@ describe('LegacyFSController.updateFsentryThumbnail', () => {
         expect(typeof body.thumbnail).toBe('string');
     });
 });
+
+// ── GET /get-launch-apps ────────────────────────────────────────────
+//
+// `recent` is a launch-metadata producer: it returns `index_url` for
+// apps the user has opened before. The taskbar happens to launch these
+// by name (so AppDriver's hosted-backing guard applies), but the field
+// is served regardless, so the guard is applied here too.
+
+describe('LegacyFSController GET /get-launch-apps', () => {
+    const hostedUrl = (sub: string) => `https://${sub}.site.puter.localhost/`;
+
+    // The route is an inline lambda in `registerRoutes`, so pull it off a
+    // freshly-registered router rather than calling a named method.
+    const getLaunchAppsHandler = () => {
+        const router = new PuterRouter();
+        (
+            controller as unknown as {
+                registerRoutes: (r: PuterRouter) => void;
+            }
+        ).registerRoutes(router);
+        const route = router.routes.find(
+            (r) => r.method === 'get' && r.path === '/get-launch-apps',
+        );
+        if (!route) throw new Error('No GET /get-launch-apps route');
+        return route.handler;
+    };
+
+    const recordOpen = async (userId: number, appUid: string) => {
+        await server.clients.db.write(
+            'INSERT INTO `app_opens` (`app_uid`, `user_id`, `ts`) VALUES (?, ?, ?)',
+            [appUid, userId, Math.floor(Date.now() / 1000)],
+        );
+    };
+
+    const fetchRecent = async (
+        actor: Actor,
+    ): Promise<Array<Record<string, unknown>>> => {
+        const { res, captured } = makeRes();
+        await withActor(actor, async () => {
+            await getLaunchAppsHandler()(makeReq({ actor }), res, () => {
+                throw new Error('handler called next() unexpectedly');
+            });
+        });
+        return (captured.body as { recent: Array<Record<string, unknown>> })
+            .recent;
+    };
+
+    const makeHostedApp = async (userId: number, sub: string) => {
+        const name = `launch-${Math.random().toString(36).slice(2, 10)}`;
+        const app = await server.stores.app.create(
+            { name, title: 'Launchable', index_url: hostedUrl(sub) },
+            { ownerUserId: userId },
+        );
+        return app as { uid: string };
+    };
+
+    it('returns index_url while the hosted subdomain is owned', async () => {
+        const { actor, userId } = await makeUser();
+        const sub = `live-${Math.random().toString(36).slice(2, 10)}`;
+        await server.stores.subdomain.create({ userId, subdomain: sub });
+        const app = await makeHostedApp(userId, sub);
+        await recordOpen(userId, app.uid);
+
+        const entry = (await fetchRecent(actor)).find(
+            (a) => a.uuid === app.uid,
+        );
+        expect(entry).toBeDefined();
+        expect(String(entry?.index_url)).toContain(sub);
+        expect(entry?.privateAccess).toBeUndefined();
+    });
+
+    it('nulls index_url and denies launch once the subdomain is deleted', async () => {
+        const { actor, userId } = await makeUser();
+        const sub = `gone-${Math.random().toString(36).slice(2, 10)}`;
+        const row = await server.stores.subdomain.create({
+            userId,
+            subdomain: sub,
+        });
+        const app = await makeHostedApp(userId, sub);
+        await recordOpen(userId, app.uid);
+
+        await server.stores.subdomain.deleteByUuid(
+            String((row as { uuid: string }).uuid),
+            { userId },
+        );
+
+        const entry = (await fetchRecent(actor)).find(
+            (a) => a.uuid === app.uid,
+        );
+        expect(entry).toBeDefined();
+        expect(entry?.index_url).toBeNull();
+        expect(entry?.privateAccess).toMatchObject({
+            hasAccess: false,
+            reason: 'hosted_backing_unavailable',
+        });
+    });
+
+    it('nulls index_url once the subdomain is reclaimed by another user', async () => {
+        const owner = await makeUser();
+        const attacker = await makeUser();
+        const sub = `reclaim-${Math.random().toString(36).slice(2, 10)}`;
+        const row = await server.stores.subdomain.create({
+            userId: owner.userId,
+            subdomain: sub,
+        });
+        const app = await makeHostedApp(owner.userId, sub);
+        await recordOpen(owner.userId, app.uid);
+
+        await server.stores.subdomain.deleteByUuid(
+            String((row as { uuid: string }).uuid),
+            { userId: owner.userId },
+        );
+        await server.stores.subdomain.create({
+            userId: attacker.userId,
+            subdomain: sub,
+        });
+
+        const entry = (await fetchRecent(owner.actor)).find(
+            (a) => a.uuid === app.uid,
+        );
+        expect(entry?.index_url).toBeNull();
+        expect(entry?.privateAccess).toMatchObject({
+            hasAccess: false,
+            reason: 'hosted_backing_unavailable',
+        });
+    });
+
+    it('fails closed when the subdomain lookup errors', async () => {
+        const { actor, userId } = await makeUser();
+        const sub = `flaky-${Math.random().toString(36).slice(2, 10)}`;
+        await server.stores.subdomain.create({ userId, subdomain: sub });
+        const app = await makeHostedApp(userId, sub);
+        await recordOpen(userId, app.uid);
+
+        const spy = vi
+            .spyOn(server.stores.subdomain, 'getBySubdomain')
+            .mockRejectedValue(new Error('db down'));
+        try {
+            const entry = (await fetchRecent(actor)).find(
+                (a) => a.uuid === app.uid,
+            );
+            expect(entry?.index_url).toBeNull();
+        } finally {
+            spy.mockRestore();
+        }
+    });
+
+    it('leaves non-hosted index_urls untouched', async () => {
+        const { actor, userId } = await makeUser();
+        const name = `ext-${Math.random().toString(36).slice(2, 10)}`;
+        const app = (await server.stores.app.create(
+            {
+                name,
+                title: 'External',
+                index_url: 'https://dev-owned-domain.example/',
+            },
+            { ownerUserId: userId },
+        )) as { uid: string };
+        await recordOpen(userId, app.uid);
+
+        const entry = (await fetchRecent(actor)).find(
+            (a) => a.uuid === app.uid,
+        );
+        expect(entry?.index_url).toBe('https://dev-owned-domain.example/');
+        expect(entry?.privateAccess).toBeUndefined();
+    });
+
+    // The rows are fetched in one batched lookup, which returns a map — the
+    // handler has to re-impose the recency order the uid list carries.
+    it('preserves the most-recent-first order of the underlying uid list', async () => {
+        const { actor, userId } = await makeUser();
+        const first = await makeHostedApp(userId, 'unregistered-a');
+        const second = await makeHostedApp(userId, 'unregistered-b');
+        const third = await makeHostedApp(userId, 'unregistered-c');
+
+        await recordOpen(userId, first.uid);
+        await recordOpen(userId, second.uid);
+        await recordOpen(userId, third.uid);
+
+        const recentUids = await server.stores.app.getRecentAppOpens(userId, {
+            limit: 10,
+        });
+        const returned = (await fetchRecent(actor)).map((a) => a.uuid);
+
+        expect(returned).toEqual(recentUids);
+    });
+});

src/backend/controllers/fs/LegacyFSController.ts

@@ -3,32 +3,42 @@
  *
  * 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.
+ * 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.
+ * 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/>.
+ * along with this program. If not, see
+ * [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
  */
 
 import Busboy from 'busboy';
-import type { Request, RequestHandler, Response } from 'express';
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
 import { contentType as contentTypeFromMime } from 'mime-types';
 import { posix as pathPosix } from 'node:path';
 import type { Actor } from '../../core/actor.js';
 import { effectiveActorApp, isAccessTokenActor } from '../../core/actor.js';
 import { Context } from '../../core/context.js';
 import { HttpError } from '../../core/http/HttpError.js';
+import {
+    assertNotSuspended,
+    assertVerifiedAccount,
+} from '../../core/http/middleware/gates.js';
+import { RouteOptions } from '../../core/http/index.js';
 import type { PuterRouter } from '../../core/http/PuterRouter.js';
 import type { ACLService } from '../../services/acl/ACLService.js';
 import type { SignedFile } from '../../util/fileSigning.js';
 import { verifySignature } from '../../util/fileSigning.js';
+import {
+    buildHostedBackingDenial,
+    hostedIndexUrlBackingIsUnavailable,
+} from '../../util/hostedAppBacking.js';
 import { applyInlineContentSecurity } from '../../util/inlineContentSecurity.js';
 import { PuterController } from '../types.js';
 import { FS_COSTS } from './costs.js';
@@ -44,7 +54,6 @@ import {
     signingConfigFromAppConfig,
     toLegacyEntry,
 } from './legacyFsHelpers.js';
-import { RouteOptions } from '../../core/http/index.js';
 
 type RouterCache = Map<string, RequestHandler | null>;
 
@@ -176,28 +185,60 @@ export class LegacyFSController extends PuterController {
                             ) => Promise<string[]>;
                         }
                     ).getRecentAppOpens?.(userId, { limit: 10 })) ?? [];
-                const apps: unknown[] = [];
-                for (const uid of recentUids) {
-                    const app = await (
-                        this.stores.app as unknown as {
-                            getByUid: (
-                                uid: string,
-                            ) => Promise<Record<string, unknown> | null>;
-                        }
-                    ).getByUid(uid);
-                    if (app) {
-                        apps.push({
-                            uuid: app.uid,
-                            name: app.name,
-                            title: app.title,
-                            icon: app.icon ?? null,
-                            godmode: Boolean(app.godmode),
-                            maximize_on_start: Boolean(app.maximize_on_start),
-                            index_url: app.index_url,
-                        });
+                // One batched read for the rows, then the backing checks
+                // concurrently. Serially awaiting a lookup per uid put ~2
+                // round trips of latency on every desktop boot.
+                const appsByUid = await (
+                    this.stores.app as unknown as {
+                        getByUids: (
+                            uids: string[],
+                        ) => Promise<Map<string, Record<string, unknown>>>;
                     }
-                }
-                recent = apps;
+                ).getByUids(recentUids);
+
+                // `recentUids` is ordered most-recent-first; preserve it.
+                const orderedApps = recentUids
+                    .map((uid) => appsByUid.get(uid))
+                    .filter((app): app is Record<string, unknown> =>
+                        Boolean(app),
+                    );
+
+                // Don't hand out an index_url whose puter-hosted backing is
+                // gone or reclaimed. The taskbar launches recents by name (so
+                // AppDriver's guard applies), but this list is a
+                // launch-metadata producer like any other — a future consumer
+                // reading index_url straight off it shouldn't inherit a stale
+                // origin.
+                const backingGoneFlags = await Promise.all(
+                    orderedApps.map((app) =>
+                        hostedIndexUrlBackingIsUnavailable({
+                            app,
+                            subdomainStore: this.stores.subdomain,
+                            config: this.config,
+                        }).catch(() => true),
+                    ),
+                );
+
+                recent = orderedApps.map((app, index) => {
+                    const backingGone = backingGoneFlags[index];
+                    return {
+                        uuid: app.uid,
+                        name: app.name,
+                        title: app.title,
+                        icon: app.icon ?? null,
+                        godmode: Boolean(app.godmode),
+                        maximize_on_start: Boolean(app.maximize_on_start),
+                        index_url: backingGone ? null : app.index_url,
+                        ...(backingGone
+                            ? { privateAccess: buildHostedBackingDenial() }
+                            : {}),
+                        // An app with no owner isn't owned by a Puter user —
+                        // it's an "external" (origin-bootstrapped) app.
+                        external:
+                            app.owner_user_id == null ||
+                            app.owner_user_id === '',
+                    };
+                });
             }
 
             res.json({ recommended, recent });
@@ -308,6 +349,13 @@ export class LegacyFSController extends PuterController {
         const actor = this.#requireActor(req);
         const body = asRecord(req.body);
 
+        // Presence of `cursor` (null means "first page") or `includeTotal`
+        // opts into the paginated `{items, cursor?, total?}` envelope.
+        // Requests without pagination params keep the bare-array response.
+        const paginated =
+            Object.prototype.hasOwnProperty.call(body, 'cursor') ||
+            body.includeTotal === true;
+
         if (this.#isRootPathRef(body)) {
             const { listRootEntries } =
                 await import('../../services/fs/rootListing.js');
@@ -337,6 +385,15 @@ export class LegacyFSController extends PuterController {
                     }),
                 ),
             );
+            if (paginated) {
+                res.json({
+                    items: shaped,
+                    ...(body.includeTotal === true
+                        ? { total: shaped.length }
+                        : {}),
+                });
+                return;
+            }
             res.json(shaped);
             return;
         }
@@ -355,10 +412,37 @@ export class LegacyFSController extends PuterController {
             'list',
         );
 
-        const children = await this.services.fs.listDirectory(parent.uuid, {
-            sortBy: this.#parseSortBy(body),
-            sortOrder: this.#parseSortOrder(body),
-        });
+        const sortBy = this.#parseSortBy(body);
+        const sortOrder = this.#parseSortOrder(body);
+        const limit =
+            typeof body.limit === 'number' || typeof body.limit === 'string'
+                ? Number(body.limit)
+                : undefined;
+        const offset =
+            typeof body.offset === 'number' || typeof body.offset === 'string'
+                ? Number(body.offset)
+                : undefined;
+
+        let children;
+        let cursor: string | undefined;
+        if (paginated) {
+            const page = await this.services.fs.listDirectoryPage(parent.uuid, {
+                limit,
+                cursor:
+                    typeof body.cursor === 'string' ? body.cursor : undefined,
+                sortBy,
+                sortOrder,
+            });
+            children = page.entries;
+            cursor = page.cursor;
+        } else {
+            children = await this.services.fs.listDirectory(parent.uuid, {
+                limit: Number.isFinite(limit) ? limit : undefined,
+                offset: Number.isFinite(offset) ? offset : undefined,
+                sortBy,
+                sortOrder,
+            });
+        }
 
         const suggestions =
             await this.services.suggestedApps.getSuggestedAppsForEntries(
@@ -381,6 +465,19 @@ export class LegacyFSController extends PuterController {
                 toLegacyEntry(this.clients.event, c, { appsById }),
             ),
         );
+
+        if (paginated) {
+            const total =
+                body.includeTotal === true
+                    ? await this.services.fs.countDirectory(parent.uuid)
+                    : undefined;
+            res.json({
+                items: shaped,
+                ...(cursor ? { cursor } : {}),
+                ...(total !== undefined ? { total } : {}),
+            });
+            return;
+        }
         res.json(shaped);
     };
 
@@ -824,7 +921,12 @@ export class LegacyFSController extends PuterController {
         res.json(shaped);
     };
 
-    read = async (req: Request, res: Response, options = {}): Promise<void> => {
+    read = async (
+        req: Request,
+        res: Response,
+        _next?: NextFunction,
+        options: { realMime?: boolean } = {},
+    ) => {
         const actor = this.#requireActor(req);
         const query = asRecord(req.query);
 
@@ -865,7 +967,10 @@ export class LegacyFSController extends PuterController {
         // GUI) expect the raw-Blob shape. Use `/fs/read` for type-aware
         // streaming.
         if (options.realMime) {
-            res.setHeader('Content-Type', contentTypeFromMime(entry.name));
+            res.setHeader(
+                'Content-Type',
+                contentTypeFromMime(entry.name) as string,
+            );
         } else {
             res.setHeader('Content-Type', 'application/octet-stream');
         }
@@ -932,20 +1037,25 @@ export class LegacyFSController extends PuterController {
             });
         }
 
-        req.actor = actor;
+        // This endpoint authenticates the token by hand and never runs the
+        // route gate chain, so the suspension and pending-verification checks
+        // that guard every other authenticated FS route have to run here.
+        assertNotSuspended(actor!.user);
+        assertVerifiedAccount(actor!.user);
+
+        req.actor = actor!;
         Context.set('actor', actor);
 
         // Forward back to regular read after setting actor
-        return this.read(req, res, { realMime: true });
+        return this.read(req, res, undefined, { realMime: true });
     };
 
     // -- Signed-URL + meta routes ----------------------------------------
 
     /**
-     * POST /sign
-     * Body: `{ items: [{ uid?, path?, action }], app_uid? }`. Returns
-     * `{ signatures: [...], token? }`. Apps may only sign files under their
-     * own AppData subtree.
+     * POST /sign Body: `{ items: [{ uid?, path?, action }], app_uid? }`.
+     * Returns `{ signatures: [...], token? }`. Apps may only sign files under
+     * their own AppData subtree.
      */
     sign = async (req: Request, res: Response): Promise<void> => {
         const actor = this.#requireActor(req);
@@ -1071,10 +1181,10 @@ export class LegacyFSController extends PuterController {
     };
 
     /**
-     * POST /writeFile?uid=<uid>&operation=<op>
-     * Signature-authenticated multipart upload. `operation` dispatches to one
-     * of write/copy/move/mkdir/delete/rename/trash. Signature must be valid
-     * for `write` action on `uid`.
+     * POST /writeFile?uid=<uid>&operation=<op> Signature-authenticated
+     * multipart upload. `operation` dispatches to one of
+     * write/copy/move/mkdir/delete/rename/trash. Signature must be valid for
+     * `write` action on `uid`.
      */
     writeFile = async (req: Request, res: Response): Promise<void> => {
         const query = asRecord(req.query);
@@ -1125,35 +1235,35 @@ export class LegacyFSController extends PuterController {
             );
         }
 
-        // ACL re-check: require an authenticated actor with write
-        // permission. A valid write signature alone is not sufficient —
-        // the caller must also pass ACL, preventing exploitation of
-        // leaked write URLs by read-only share recipients.
         const callerActor = this.#requireActor(req);
-        if (operation === 'write') {
-            await assertAccess(
-                this.services.acl,
-                this.services.fs,
-                callerActor,
-                targetEntry.path,
-                'write',
-            );
-        }
         if (operation === 'write') {
             const body = asRecord(req.body);
-            const parentEntry = targetEntry.isDir
-                ? targetEntry
-                : await this.#resolveParentOfEntry(targetEntry);
-            const name =
-                typeof body.name === 'string'
-                    ? body.name
-                    : targetEntry.isDir
-                      ? `upload-${Date.now()}`
-                      : targetEntry.name;
-            const targetPath =
-                parentEntry.path === '/'
-                    ? `/${name}`
-                    : `${parentEntry.path}/${name}`;
+            let targetPath: string;
+            if (targetEntry.isDir) {
+                const name =
+                    typeof body.name === 'string'
+                        ? body.name
+                        : `upload-${Date.now()}`;
+                targetPath =
+                    targetEntry.path === '/'
+                        ? `/${name}`
+                        : `${targetEntry.path}/${name}`;
+                await assertCanCreate(
+                    this.services.acl,
+                    this.services.fs,
+                    callerActor,
+                    targetPath,
+                );
+            } else {
+                targetPath = targetEntry.path;
+                await assertAccess(
+                    this.services.acl,
+                    this.services.fs,
+                    callerActor,
+                    targetPath,
+                    'write',
+                );
+            }
 
             // Parse multipart and pipe the first `file` part into fsService.write.
             const uploadResult = await this.#multipartWrite(
@@ -1293,10 +1403,9 @@ export class LegacyFSController extends PuterController {
     };
 
     /**
-     * GET /file?uid=<uid>&signature=...&expires=...
-     * Signature-authenticated file read. Directories return a signed listing
-     * of children; files stream bytes (with Range support when `download`
-     * isn't requested).
+     * GET /file?uid=<uid>&signature=...&expires=... Signature-authenticated
+     * file read. Directories return a signed listing of children; files stream
+     * bytes (with Range support when `download` isn't requested).
      */
     file = async (req: Request, res: Response): Promise<void> => {
         const query = asRecord(req.query);
@@ -1391,9 +1500,9 @@ export class LegacyFSController extends PuterController {
     };
 
     /**
-     * POST /open_item — resolve an entry, grant the default suggested app
-     * write access to it, and return a signed URL + user-app token so the
-     * launched app can read/write the file via its app-under-user token.
+     * POST /open_item — resolve an entry, grant the default suggested app write
+     * access to it, and return a signed URL + user-app token so the launched
+     * app can read/write the file via its app-under-user token.
      *
      * Matches v1 semantics: permission is always granted as `write` — the
      * underlying user's permission check still caps the effective access
@@ -1467,8 +1576,8 @@ export class LegacyFSController extends PuterController {
     };
 
     /**
-     * POST /auth/request-app-root-dir — an app-under-user requests stat on
-     * its own app root directory. The app must own itself.
+     * POST /auth/request-app-root-dir — an app-under-user requests stat on its
+     * own app root directory. The app must own itself.
      */
     requestAppRootDir = async (req: Request, res: Response): Promise<void> => {
         const actor = this.#requireActor(req);
@@ -1656,14 +1765,6 @@ export class LegacyFSController extends PuterController {
         }
     }
 
-    async #resolveParentOfEntry(entry: { path: string; userId: number }) {
-        const parentPath = pathPosix.dirname(entry.path);
-        const parent = await resolveV1Selector(this.stores.fsEntry, {
-            path: parentPath,
-        });
-        return parent;
-    }
-
     async #multipartWrite(
         req: Request,
         userId: number,
@@ -2182,12 +2283,21 @@ export class LegacyFSController extends PuterController {
 
     #serializeBatchError(err: unknown): Record<string, unknown> {
         if (err instanceof HttpError) {
-            return {
+            const payload: Record<string, unknown> = {
                 error: true,
                 status: err.statusCode,
                 message: err.message,
                 code: err.legacyCode ?? err.code,
             };
+            // Same as the terminal errorHandler: extra fields (e.g.
+            // `entry_name` on item_with_same_name_exists) ride along
+            // without clobbering the canonical slots.
+            if (err.fields) {
+                for (const [k, v] of Object.entries(err.fields)) {
+                    if (!(k in payload)) payload[k] = v;
+                }
+            }
+            return payload;
         }
         if (err instanceof Error) {
             return { error: true, status: 500, message: err.message };
@@ -2196,120 +2306,6 @@ export class LegacyFSController extends PuterController {
     }
 
     // -- Helpers ---------------------------------------------------------
-
-    #parsePositiveIntegerQuery(
-        query: Record<string, unknown>,
-        key: string,
-        message: string,
-    ): number | undefined {
-        const value = query[key];
-        if (value === undefined || value === null || value === '') {
-            return undefined;
-        }
-        const parsed = Number.parseInt(String(value), 10);
-        if (!Number.isInteger(parsed) || parsed < 1) {
-            throw new HttpError(400, message, { legacyCode: 'bad_request' });
-        }
-        return parsed;
-    }
-
-    #parseNonNegativeIntegerQuery(
-        query: Record<string, unknown>,
-        key: string,
-        message: string,
-    ): number | undefined {
-        const value = query[key];
-        if (value === undefined || value === null || value === '') {
-            return undefined;
-        }
-        const parsed = Number.parseInt(String(value), 10);
-        if (!Number.isInteger(parsed) || parsed < 0) {
-            throw new HttpError(400, message, { legacyCode: 'bad_request' });
-        }
-        return parsed;
-    }
-
-    #normalizeRangeHeader(rangeHeader: string): string | undefined {
-        const firstRange = rangeHeader.includes(',')
-            ? rangeHeader.split(',')[0]?.trim()
-            : rangeHeader.trim();
-        if (!firstRange) return undefined;
-
-        const matches = firstRange.match(/^bytes=(\d+)-(\d*)$/);
-        if (!matches) return undefined;
-
-        const [, start, end] = matches;
-        return end ? `bytes=${start}-${end}` : `bytes=${start}-`;
-    }
-
-    #pipeLimitedLines(
-        source: NodeJS.ReadableStream,
-        res: Response,
-        lineCount: number,
-    ): void {
-        let remainingLines = lineCount;
-        let isClosed = false;
-
-        const closeSource = () => {
-            if (isClosed) return;
-            isClosed = true;
-            if ('destroy' in source && typeof source.destroy === 'function') {
-                source.destroy();
-            }
-        };
-
-        source.on('error', (err) => {
-            if (!isClosed) {
-                isClosed = true;
-                res.destroy(err);
-            }
-        });
-
-        res.on('close', () => {
-            closeSource();
-        });
-
-        source.on('data', (chunk: Buffer | string) => {
-            if (isClosed) return;
-
-            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-            let endIndex = buffer.length;
-
-            for (let index = 0; index < buffer.length; index++) {
-                if (buffer[index] !== 0x0a) continue;
-                remainingLines -= 1;
-                if (remainingLines === 0) {
-                    endIndex = index + 1;
-                    break;
-                }
-            }
-
-            if (endIndex > 0) {
-                const canContinue = res.write(buffer.subarray(0, endIndex));
-                if (!canContinue) {
-                    source.pause();
-                    res.once('drain', () => {
-                        if (!isClosed) {
-                            source.resume();
-                        }
-                    });
-                }
-            }
-
-            if (endIndex !== buffer.length) {
-                res.end();
-                closeSource();
-            }
-        });
-
-        source.on('end', () => {
-            if (!isClosed) {
-                isClosed = true;
-                res.end();
-            }
-        });
-    }
-
     #requireActor(req: Request) {
         const actor = req.actor;
         if (!actor) {
@@ -2349,7 +2345,7 @@ export class LegacyFSController extends PuterController {
     #parseSortBy(
         body: Record<string, unknown>,
     ): 'name' | 'modified' | 'type' | 'size' | null {
-        const raw = getString(body, 'sort_by');
+        const raw = getString(body, 'sortBy') || getString(body, 'sort_by');
         if (!raw) return null;
         const normalized = raw.toLowerCase();
         return (
@@ -2360,7 +2356,8 @@ export class LegacyFSController extends PuterController {
     }
 
     #parseSortOrder(body: Record<string, unknown>): 'asc' | 'desc' | null {
-        const raw = getString(body, 'sort_order');
+        const raw =
+            getString(body, 'sortOrder') || getString(body, 'sort_order');
         if (!raw) return null;
         const normalized = raw.toLowerCase();
         return (['asc', 'desc'] as const).find((v) => v === normalized) ?? null;

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

@@ -0,0 +1,102 @@
+/**
+ * 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 { loadLegacyAssociatedApps } from './legacyFsHelpers.js';
+import type { FSEntry } from '../../stores/fs/FSEntry.js';
+
+const entryWithApp = (associatedAppId: number): FSEntry =>
+    ({ associatedAppId }) as unknown as FSEntry;
+
+const appRow = (overrides: Record<string, unknown>): Record<string, unknown> => ({
+    id: 1,
+    uid: 'app-1',
+    owner_user_id: 99,
+    app_owner: 99,
+    icon: 'icon',
+    name: 'an-app',
+    title: 'An App',
+    description: 'desc',
+    godmode: 1,
+    maximize_on_start: 1,
+    index_url: 'https://an-app.puter.site/',
+    background: 1,
+    metadata: { secret: true },
+    is_private: 0,
+    protected: 0,
+    ...overrides,
+});
+
+const fakeStore = (row: Record<string, unknown>) => ({
+    getByIds: async (ids: number[]) =>
+        new Map(ids.map((id) => [id, { ...row, id }])),
+});
+
+describe('loadLegacyAssociatedApps associated_app redaction', () => {
+    it('never leaks owner identifiers, even for public apps', async () => {
+        const out = await loadLegacyAssociatedApps(
+            fakeStore(appRow({ is_private: 0, protected: 0 })),
+            [entryWithApp(1)],
+        );
+        const app = out.get(1)!;
+        expect(app).not.toHaveProperty('owner_user_id');
+        expect(app).not.toHaveProperty('app_owner');
+    });
+
+    it('passes through hosting + capability fields for public apps', async () => {
+        const out = await loadLegacyAssociatedApps(
+            fakeStore(appRow({ is_private: 0, protected: 0, godmode: 1 })),
+            [entryWithApp(1)],
+        );
+        const app = out.get(1)!;
+        expect(app.index_url).toBe('https://an-app.puter.site/');
+        expect(app.godmode).toBe(1);
+        expect(app.maximize_on_start).toBe(1);
+    });
+
+    it('redacts hosting + capability fields for private apps', async () => {
+        const out = await loadLegacyAssociatedApps(
+            fakeStore(appRow({ is_private: 1, godmode: 1 })),
+            [entryWithApp(1)],
+        );
+        const app = out.get(1)!;
+        // Existence + display fields still surface...
+        expect(app.uid).toBe('app-1');
+        expect(app.name).toBe('an-app');
+        expect(app.is_private).toBe(1);
+        // ...but the sensitive bits are stripped.
+        expect(app.index_url).toBeNull();
+        expect(app.godmode).toBe(0);
+        expect(app.maximize_on_start).toBe(0);
+        expect(app.background).toBe(0);
+        expect(app.metadata).toBeNull();
+        expect(app).not.toHaveProperty('owner_user_id');
+    });
+
+    it('redacts the same fields for protected apps', async () => {
+        const out = await loadLegacyAssociatedApps(
+            fakeStore(appRow({ is_private: 0, protected: 1, godmode: 1 })),
+            [entryWithApp(1)],
+        );
+        const app = out.get(1)!;
+        expect(app.protected).toBe(1);
+        expect(app.index_url).toBeNull();
+        expect(app.godmode).toBe(0);
+    });
+});

src/backend/controllers/fs/legacyFsHelpers.ts

@@ -3,18 +3,19 @@
  *
  * 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.
+ * 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.
+ * 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/>.
+ * along with this program. If not, see
+ * [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
  */
 
 import { posix as pathPosix } from 'node:path';
@@ -43,9 +44,8 @@ import type { IConfig } from '../../types.js';
 /**
  * Shared helpers used by the legacy FS route shims (LegacyFSController).
  *
- * Legacy clients speak snake_case and expect specific response shapes —
- * these helpers encapsulate that translation so the route handlers stay
- * terse.
+ * Legacy clients speak snake_case and expect specific response shapes — these
+ * helpers encapsulate that translation so the route handlers stay terse.
  */
 
 // -- Body parsing -----------------------------------------------------
@@ -220,15 +220,15 @@ export async function assertAccess(
 }
 
 /**
- * Authorize creation of a new entry at `targetPath`. The standard rule is
- * write on the parent, but we also allow it when the actor has explicit
- * write on the target itself — this covers an app creating 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
- * shares granted directly on a not-yet-created path.
+ * Authorize creation of a new entry at `targetPath`. The standard rule is write
+ * on the parent, but we also allow it when the actor has explicit write on the
+ * target itself — this covers an app creating 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 shares
+ * granted directly on a not-yet-created path.
  *
- * On failure, delegates to `assertAccess` on the parent so the error
- * shape stays identical to the previous parent-only check.
+ * On failure, delegates to `assertAccess` on the parent so the error shape
+ * stays identical to the previous parent-only check.
  */
 export async function assertCanCreate(
     aclService: ACLService,
@@ -272,23 +272,36 @@ const toIntBool = (v: unknown): number => (v ? 1 : 0);
 /**
  * Convert an AppStore-normalized app row into the v1 `associated_app` shape
  * embedded in legacy FS entries. Booleans round-trip back to integers (0/1)
- * because the v1 wire contract emits them that way and existing clients key
- * off it. Other columns pass through as-is — `metadata` is already parsed.
+ * because the v1 wire contract emits them that way and existing clients key off
+ * it. Other columns pass through as-is — `metadata` is already parsed.
+ *
+ * Two redactions, because `associatedAppId` can name an app the actor does not
+ * own (the column is client-writable display metadata, never trusted for authz
+ * — see FSController) and may point cross-tenant:
+ *
+ * - Owner identifiers (`owner_user_id`, `app_owner`) are never emitted — they're
+ *   internal user references with no client-side display use.
+ * - For private or protected apps, the direct hosting URL and launch capability
+ *   flags (`index_url`, `godmode`, `maximize_on_start`, `background`,
+ *   `metadata`) are dropped. This mirrors AppDriver, which withholds
+ *   `index_url` from callers without read entitlement. Display fields (name,
+ *   icon, title) still pass through so the GUI can label the file's associated
+ *   app.
  */
 function mapAppForLegacyAssociatedApp(
     app: Record<string, unknown>,
 ): Record<string, unknown> {
+    const gated = Boolean(app.is_private) || Boolean(app.protected);
     return {
         id: app.id,
         uid: app.uid,
-        owner_user_id: app.owner_user_id,
         icon: app.icon,
         name: app.name,
         title: app.title,
         description: app.description,
-        godmode: toIntBool(app.godmode),
-        maximize_on_start: toIntBool(app.maximize_on_start),
-        index_url: app.index_url,
+        godmode: gated ? 0 : toIntBool(app.godmode),
+        maximize_on_start: gated ? 0 : toIntBool(app.maximize_on_start),
+        index_url: gated ? null : app.index_url,
         approved_for_listing: toIntBool(app.approved_for_listing),
         approved_for_opening_items: toIntBool(app.approved_for_opening_items),
         approved_for_incentive_program: toIntBool(
@@ -297,9 +310,8 @@ function mapAppForLegacyAssociatedApp(
         timestamp: app.timestamp ?? null,
         last_review: app.last_review ?? null,
         tags: app.tags ?? null,
-        app_owner: app.app_owner ?? null,
-        background: toIntBool(app.background),
-        metadata: app.metadata ?? null,
+        background: gated ? 0 : toIntBool(app.background),
+        metadata: gated ? null : (app.metadata ?? null),
         protected: toIntBool(app.protected),
         is_private: toIntBool(app.is_private),
     };
@@ -308,13 +320,15 @@ function mapAppForLegacyAssociatedApp(
 /**
  * Batch-load `associated_app` payloads for a set of entries. Dedupes app ids
  * across the input, hands them to `AppStore.getByIds` (one pipelined Redis
- * MGET + a single `id IN (…)` query for any cache misses), and returns a map
- * keyed by app id holding the v1-shaped embed. Callers pass the result to
- * `toLegacyEntry` via `opts.appsById` so each entry hydrates without a
- * second round-trip.
+ * MGET
  *
- * Empty input short-circuits — readdir on a directory of plain files makes
- * zero extra calls.
+ * - A single `id IN (…)` query for any cache misses), and returns a map keyed by
+ *   app id holding the v1-shaped embed. Callers pass the result to
+ *   `toLegacyEntry` via `opts.appsById` so each entry hydrates without a second
+ *   round-trip.
+ *
+ * Empty input short-circuits — readdir on a directory of plain files makes zero
+ * extra calls.
  */
 export async function loadLegacyAssociatedApps(
     appStore: AppRowLookup,
@@ -337,12 +351,55 @@ export async function loadLegacyAssociatedApps(
 }
 
 /**
- * Produce the snake_case entry shape legacy clients expect. If `thumbnail`
- * is set, asks the thumbnail extension (via `thumbnail.read` event) to swap
- * an S3 URL for a signed one. Pass `fsEntryStore`/`userStore` to hydrate
- * `is_empty` (directories) and `owner` — both are required fields per
- * the legacy stat contract but need extra DB lookups. Pass `appsById`
- * (built via `loadLegacyAssociatedApps`) to populate `associated_app`.
+ * The v1 `type` field: a MIME content-type (e.g. "image/png; charset=utf-8")
+ * for files, or "folder" for directories. The GUI's icon lookup keys off
+ * `type.startsWith('image/')`, so a bare extension breaks icon selection.
+ */
+export function fsEntryMimeType(entry: {
+    isDir: boolean;
+    name: string;
+}): string | null {
+    return entry.isDir ? 'folder' : contentTypeFromMime(entry.name) || null;
+}
+
+/**
+ * Swap an S3 thumbnail key for a signed URL via the thumbnail extension
+ * (`thumbnail.read` event). Returns the input unchanged when there's no
+ * thumbnail or no event client; returns null if signing yields nothing.
+ */
+export async function signEntryThumbnail(
+    eventClient: EventClient | undefined,
+    uuid: string,
+    thumbnail: string | null,
+): Promise<string | null> {
+    if (
+        typeof thumbnail !== 'string' ||
+        thumbnail.length === 0 ||
+        !eventClient
+    ) {
+        return thumbnail ?? null;
+    }
+    const thumbnailEntry = { uuid, thumbnail };
+    try {
+        // emitAndWait — listener mutates `thumbnail` on the payload; plain
+        // `emit` is fire-and-forget and would drop the rewrite.
+        await eventClient.emitAndWait('thumbnail.read', thumbnailEntry, {});
+    } catch {
+        // ignore — non-critical.
+    }
+    return typeof thumbnailEntry.thumbnail === 'string' &&
+        thumbnailEntry.thumbnail.length > 0
+        ? thumbnailEntry.thumbnail
+        : null;
+}
+
+/**
+ * Produce the snake_case entry shape legacy clients expect. If `thumbnail` is
+ * set, asks the thumbnail extension (via `thumbnail.read` event) to swap an S3
+ * URL for a signed one. Pass `fsEntryStore`/`userStore` to hydrate `is_empty`
+ * (directories) and `owner` — both are required fields per the legacy stat
+ * contract but need extra DB lookups. Pass `appsById` (built via
+ * `loadLegacyAssociatedApps`) to populate `associated_app`.
  */
 export async function toLegacyEntry(
     eventClient: EventClient | undefined,
@@ -356,13 +413,7 @@ export async function toLegacyEntry(
     } = {},
 ): Promise<Record<string, unknown>> {
     const dirname = pathPosix.dirname(entry.path);
-    // v1 contract: `type` is a MIME content-type (e.g. "image/png; charset=utf-8")
-    // for files, or "folder" for directories. The GUI's icon lookup does
-    // `type.startsWith('image/')` etc., so a bare extension breaks every
-    // banner that falls through the name-extension ladder in item_icon.js.
-    const mimeType = entry.isDir
-        ? 'folder'
-        : contentTypeFromMime(entry.name) || null;
+    const mimeType = fsEntryMimeType(entry);
 
     const pathComponents = entry.path.split('/');
     const appdata_app =
@@ -433,28 +484,11 @@ export async function toLegacyEntry(
     }
 
     // Let the thumbnail extension swap an s3:// key for a signed URL.
-    if (
-        typeof response.thumbnail === 'string' &&
-        (response.thumbnail as string).length > 0 &&
-        eventClient
-    ) {
-        const thumbnailEntry = {
-            uuid: entry.uuid,
-            thumbnail: response.thumbnail as string,
-        };
-        try {
-            // emitAndWait — listener mutates `thumbnail` on the payload;
-            // plain `emit` is fire-and-forget and would drop the rewrite.
-            await eventClient.emitAndWait('thumbnail.read', thumbnailEntry, {});
-        } catch {
-            // ignore — non-critical.
-        }
-        response.thumbnail =
-            typeof thumbnailEntry.thumbnail === 'string' &&
-            thumbnailEntry.thumbnail.length > 0
-                ? thumbnailEntry.thumbnail
-                : null;
-    }
+    response.thumbnail = await signEntryThumbnail(
+        eventClient,
+        entry.uuid,
+        response.thumbnail as string | null,
+    );
 
     return response;
 }
@@ -464,8 +498,8 @@ export { normalizeAbsolutePath };
 // -- Signing ---------------------------------------------------------
 
 /**
- * Pull the signing config off the app config. Throws if either value is
- * missing — these are required for signed URL routes to function.
+ * Pull the signing config off the app config. Throws if either value is missing
+ * — these are required for signed URL routes to function.
  */
 export function signingConfigFromAppConfig(config: IConfig): SigningConfig {
     const secret = config.url_signature_secret;
@@ -487,9 +521,7 @@ export function signingConfigFromAppConfig(config: IConfig): SigningConfig {
     return { secret, apiBaseUrl };
 }
 
-/**
- * Convenience wrapper: turn an FSEntry into a signed-file response object.
- */
+/** Convenience wrapper: turn an FSEntry into a signed-file response object. */
 export function signEntry(
     entry: {
         uuid: string;

src/backend/controllers/fs/requestTypes.ts

@@ -3,22 +3,27 @@
  *
  * 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.
+ * 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.
+ * 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/>.
+ * along with this program. If not, see
+ * [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
  */
 
-import type { FSEntry, FSEntryWriteInput } from '../../stores/fs/FSEntry.js';
 import type { Readable } from 'node:stream';
+import type {
+    FSEntry,
+    FSEntrySubdomain,
+    FSEntryWriteInput,
+} from '../../stores/fs/FSEntry.js';
 
 export type UploadMode = 'single' | 'multipart';
 
@@ -129,3 +134,100 @@ export interface WriteResponse {
     requestedThumbnail?: string | null;
     contentHashSha256?: string | null;
 }
+
+/**
+ * An `FSEntry` as it is safe to hand to a client. Built by an allowlist, so the
+ * `fsentries` primary key (`id`) and its `parentId`/`associatedAppId`
+ * references, the storage columns (`bucket`, `bucketRegion`), the owning
+ * `userId`, and the `publicToken`/`fileRequestToken` capability tokens never
+ * reach the wire. Entries are addressed by `uuid`.
+ *
+ * `shortcutTo` is the one numeric row reference that stays: the v1 contract has
+ * always exposed it as `shortcut_to` and the desktop resolves shortcuts through
+ * it, so dropping it would break them.
+ *
+ * The `?: never` members below are guards, not fields: they make a raw
+ * `FSEntry` fail to typecheck wherever a `ClientFSEntry` is expected. Without
+ * them this type is just a structural subset of `FSEntry`, so an unsanitized
+ * row would be silently assignable and the distinction would buy nothing.
+ *
+ * Checked by `tsc -p tsconfig.json` (the strict config). Note that
+ * `tsconfig.build.json` sets `noCheck: true` — it only transpiles, so it will
+ * not catch a violation here.
+ */
+export interface ClientFSEntry {
+    uuid: string;
+    uid: string;
+    parentUid: string | null;
+    path: string;
+    name: string;
+    isDir: boolean;
+    isShortcut: boolean;
+    shortcutTo: number | null;
+    isSymlink: boolean;
+    symlinkPath: string | null;
+    isPublic: boolean | null;
+    immutable: boolean;
+    metadata: string | null;
+    modified: number;
+    created: number | null;
+    accessed: number | null;
+    size: number | null;
+    layout: string | null;
+    subdomains: FSEntrySubdomain[];
+    workers: FSEntrySubdomain[];
+    hasWebsite: boolean;
+    suggestedApps: unknown[];
+
+    id?: never;
+    userId?: never;
+    parentId?: never;
+    associatedAppId?: never;
+    bucket?: never;
+    bucketRegion?: never;
+    publicToken?: never;
+    fileRequestToken?: never;
+}
+
+/**
+ * Wire counterparts of the write responses. The bare `…Response` types describe
+ * what the service produces internally (a real `FSEntry`); these describe what
+ * the controller sends after sanitizing. Keeping them distinct is what makes
+ * "did this response get sanitized?" a question the compiler answers.
+ */
+/**
+ * The presigned-upload envelope minus the storage internals. A client uploads
+ * to the presigned `url` / `multipartPartUrls`, which already carry everything
+ * S3 needs, so `bucket`, `bucketRegion`, and `objectKey` are ours to keep —
+ * they name where a user's bytes physically live.
+ */
+export type ClientSignedWriteResponse = Omit<
+    SignedWriteResponse,
+    'fsEntry' | 'bucket' | 'bucketRegion' | 'objectKey'
+> & { fsEntry?: ClientFSEntry };
+
+export type ClientSignMultipartPartsResponse = Omit<
+    SignMultipartPartsResponse,
+    'bucket' | 'bucketRegion' | 'objectKey'
+>;
+
+export type ClientCompleteWriteResponse = Omit<
+    CompleteWriteResponse,
+    'fsEntry'
+> & { fsEntry: ClientFSEntry };
+
+export type ClientWriteResponse = Omit<WriteResponse, 'fsEntry'> & {
+    fsEntry: ClientFSEntry;
+};
+
+/**
+ * A directory-listing entry: a sanitized entry plus the three fields a client
+ * cannot derive on its own — the MIME `type`, a _signed_ `thumbnail` URL (the
+ * stored value is an S3 key, which is useless to a client), and the resolved
+ * `associatedApp`.
+ */
+export type ClientReaddirEntry = ClientFSEntry & {
+    type: string | null;
+    thumbnail: string | null;
+    associatedApp: Record<string, unknown> | null;
+};

src/backend/controllers/homepage/HomepageController.test.ts

@@ -165,6 +165,43 @@ describe('HomepageController shell routes', () => {
         expect(html).toContain('Puter');
     });
 
+    it('exposes disable_temp_users to the GUI when signups are disabled', async () => {
+        const homepageConfig = server.controllers.homepage.config as {
+            disable_user_signup?: boolean;
+        };
+        const prev = homepageConfig.disable_user_signup;
+        homepageConfig.disable_user_signup = true;
+        const { res, captured } = makeRes();
+        try {
+            await callRoute('get', '/', makeReq({ path: '/' }), res);
+        } finally {
+            homepageConfig.disable_user_signup = prev;
+        }
+        expect(String(captured.body)).toContain('"disable_temp_users":true');
+    });
+
+    it('keeps an operator-set gui_params.disable_temp_users when the flag is off', async () => {
+        const homepageConfig = server.controllers.homepage.config as {
+            disable_user_signup?: boolean;
+            gui_params?: Record<string, unknown>;
+        };
+        const prevFlag = homepageConfig.disable_user_signup;
+        const prevGuiParams = homepageConfig.gui_params;
+        homepageConfig.disable_user_signup = false;
+        homepageConfig.gui_params = {
+            ...prevGuiParams,
+            disable_temp_users: true,
+        };
+        const { res, captured } = makeRes();
+        try {
+            await callRoute('get', '/', makeReq({ path: '/' }), res);
+        } finally {
+            homepageConfig.disable_user_signup = prevFlag;
+            homepageConfig.gui_params = prevGuiParams;
+        }
+        expect(String(captured.body)).toContain('"disable_temp_users":true');
+    });
+
     it('still serves the shell when an authenticated actor is present', async () => {
         const { actor } = await makeUser();
         const { res, captured } = makeRes();
@@ -173,12 +210,14 @@ describe('HomepageController shell routes', () => {
         expect(String(captured.body)).toMatch(/<!DOCTYPE html>/i);
     });
 
-    it('serves the shell on /settings, /dashboard, /action, /@:username', async () => {
+    it('serves the shell on /settings, /dashboard, /desktop, /action, /@:username', async () => {
         for (const path of [
             '/settings',
             '/settings/*splat',
             '/dashboard',
             '/dashboard/',
+            '/desktop',
+            '/desktop/',
             '/action/*splat',
             '/@:username',
         ]) {
@@ -238,6 +277,70 @@ describe('HomepageController GET /app/:name', () => {
         expect(html).toMatch(/<!DOCTYPE html>/i);
         expect(html).toContain('Cool App');
     });
+
+    it('does not leak a private app index_url or owner id to an anonymous visitor', async () => {
+        const { userId } = await makeUser();
+        const name = `priv-${Math.random().toString(36).slice(2, 10)}`;
+        const secretUrl = `https://secret-${name}.example.com/`;
+        // `is_private` is a READ_ONLY_COLUMN, so it can't be set through the
+        // store's create/update allow-list — insert the private row directly.
+        await server.clients.db.write(
+            `INSERT INTO \`apps\` (\`uid\`, \`name\`, \`title\`, \`description\`, \`index_url\`, \`owner_user_id\`, \`is_private\`)
+             VALUES (?, ?, ?, ?, ?, ?, ?)`,
+            [
+                `app-${uuidv4()}`,
+                name,
+                'Private App',
+                'a private app row',
+                secretUrl,
+                userId,
+                1,
+            ],
+        );
+
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/app/:name',
+            makeReq({ params: { name }, path: `/app/${name}` }),
+            res,
+        );
+
+        expect(captured.statusCode).toBe(200);
+        const html = String(captured.body);
+        // Public meta (title) is fine to render...
+        expect(html).toContain('Private App');
+        // ...but the private hosting URL and owner id must be redacted.
+        expect(html).not.toContain(secretUrl);
+        expect(html).not.toContain('owner_user_id');
+    });
+
+    it('omits index_url even for a public app — the shell is not the launch authority', async () => {
+        const { userId } = await makeUser();
+        const name = `pub-${Math.random().toString(36).slice(2, 10)}`;
+        const indexUrl = `https://public-${name}.example.com/`;
+        await server.stores.app.create(
+            { name, title: 'Public App', index_url: indexUrl },
+            { ownerUserId: userId },
+        );
+
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/app/:name',
+            makeReq({ params: { name }, path: `/app/${name}` }),
+            res,
+        );
+
+        expect(captured.statusCode).toBe(200);
+        const html = String(captured.body);
+        expect(html).toContain('Public App');
+        // The GUI re-reads the app through the driver before launching, which
+        // is where the entitlement gate and hosted-backing guard run. Baking
+        // a launch URL into server-rendered HTML buys nothing and costs the
+        // lookups those guards require.
+        expect(html).not.toContain(indexUrl);
+    });
 });
 
 // ── /show/* ─────────────────────────────────────────────────────────

src/backend/controllers/homepage/HomepageController.ts

@@ -3,23 +3,25 @@
  *
  * 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.
+ * 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.
+ * 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/>.
+ * along with this program. If not, see
+ * [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
  */
 
 import express from 'express';
 import path from 'node:path';
 import { PuterController } from '../types.js';
+import { toAppShellView } from '../../util/appShellView.js';
 import type { PuterRouter } from '../../core/http/PuterRouter';
 import type {
     PuterHomepageService,
@@ -32,8 +34,8 @@ import type {
  * under `<gui_assets_root>/src` for non-dist/src paths (images, fonts, lib
  * files referenced from the shell).
  *
- * All root-subdomain-only. Registered last in the controller list so the
- * static catch-all doesn't shadow specific API routes.
+ * All root-subdomain-only. Registered last in the controller list so the static
+ * catch-all doesn't shadow specific API routes.
  */
 export class HomepageController extends PuterController {
     registerRoutes(router: PuterRouter) {
@@ -82,6 +84,9 @@ export class HomepageController extends PuterController {
         router.get('/dashboard', {}, (req, res) => sendShell(req, res));
         router.get('/dashboard/', {}, (req, res) => sendShell(req, res));
 
+        router.get('/desktop', {}, (req, res) => sendShell(req, res));
+        router.get('/desktop/', {}, (req, res) => sendShell(req, res));
+
         router.get('/action/*splat', {}, (req, res) => sendShell(req, res));
 
         router.get('/@:username', {}, (req, res) => sendShell(req, res));
@@ -98,6 +103,12 @@ export class HomepageController extends PuterController {
                         ? safeJsonParse(app.metadata)
                         : (app.metadata as Record<string, unknown> | null)) ??
                     {};
+                // Never bake the raw store row into the shell — it exposes
+                // `index_url`, `owner_user_id`, and moderation flags. The
+                // shell only needs a preview; the GUI re-reads the app
+                // through the apps driver before launching, and that read is
+                // where the entitlement gate and hosted-backing guard run.
+                const clientApp = toAppShellView(app);
                 await sendShell(req, res, {
                     title: String(app.title ?? name),
                     description: String(app.description ?? ''),
@@ -107,7 +118,7 @@ export class HomepageController extends PuterController {
                         typeof metadata.social_image === 'string'
                             ? metadata.social_image
                             : undefined,
-                    app: app as Record<string, unknown>,
+                    app: clientApp as Record<string, unknown>,
                 });
                 return;
             }

src/backend/controllers/oidc/OIDCController.test.ts

@@ -52,6 +52,12 @@ const TEST_ORIGIN = 'http://test.local';
 let server: PuterServer;
 let router: PuterRouter;
 
+// Stand-in for the abuse extension's signup veto. EventClient has no off(),
+// so one shared listener is installed in beforeAll and tests swap the
+// override in and out (same pattern as AuthController.test.ts).
+type SignupValidateOverride = (data: Record<string, unknown>) => void;
+let signupValidateOverride: SignupValidateOverride | null = null;
+
 beforeAll(async () => {
     server = await setupTestServer({
         origin: TEST_ORIGIN,
@@ -75,6 +81,14 @@ beforeAll(async () => {
     } as never);
     router = new PuterRouter();
     server.controllers.oidc.registerRoutes(router);
+    server.clients.event.on(
+        'puter.signup.validate',
+        (_k: unknown, data: unknown) => {
+            if (signupValidateOverride) {
+                signupValidateOverride(data as Record<string, unknown>);
+            }
+        },
+    );
 });
 
 afterAll(async () => {
@@ -83,6 +97,7 @@ afterAll(async () => {
 
 afterEach(() => {
     vi.restoreAllMocks();
+    signupValidateOverride = null;
 });
 
 interface CapturedResponse {
@@ -92,6 +107,7 @@ interface CapturedResponse {
     redirectUrl?: string;
     headers: Record<string, string>;
     cookies: Array<{ name: string; value: string; opts?: unknown }>;
+    clearedCookies: Array<{ name: string; opts?: unknown }>;
     contentType?: string;
 }
 
@@ -100,6 +116,7 @@ const makeReq = (init: {
     query?: Record<string, unknown>;
     params?: Record<string, unknown>;
     headers?: Record<string, string>;
+    cookies?: Record<string, string>;
     method?: string;
 }): Request => {
     return {
@@ -107,6 +124,7 @@ const makeReq = (init: {
         query: init.query ?? {},
         params: init.params ?? {},
         headers: init.headers ?? {},
+        cookies: init.cookies ?? {},
         method: init.method ?? 'GET',
     } as unknown as Request;
 };
@@ -117,6 +135,7 @@ const makeRes = () => {
         body: undefined,
         headers: {},
         cookies: [],
+        clearedCookies: [],
     };
     const res = {
         json: vi.fn((value: unknown) => {
@@ -155,6 +174,10 @@ const makeRes = () => {
             captured.cookies.push({ name, value, opts });
             return res;
         }),
+        clearCookie: vi.fn((name: string, opts?: unknown) => {
+            captured.clearedCookies.push({ name, opts });
+            return res;
+        }),
         type: vi.fn(() => res),
     };
     return { res: res as unknown as Response, captured };
@@ -306,6 +329,54 @@ describe('OIDCController GET /auth/oidc/:provider/start', () => {
         expect(decoded).toMatchObject({ referrer: 'http://ref.test' });
     });
 
+    it('bakes a whitelisted return_to (/app/<name>) into the state redirect_uri', async () => {
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/auth/oidc/:provider/start',
+            makeReq({
+                params: { provider: 'custom' },
+                query: { return_to: '/app/my-App_2' },
+            }),
+            res,
+        );
+        const state = new URL(captured.redirectUrl ?? '').searchParams.get(
+            'state',
+        );
+        const decoded = oidc().verifyState(state!);
+        expect(String(decoded?.redirect_uri)).toBe(
+            `${TEST_ORIGIN}/app/my-App_2`,
+        );
+    });
+
+    it('ignores a non-whitelisted return_to', async () => {
+        const bad_values = [
+            '/app/evil/extra',
+            '/app/',
+            '/app/name?x=1',
+            '//evil.test',
+            '/settings',
+            `/app/${'a'.repeat(101)}`,
+        ];
+        for (const return_to of bad_values) {
+            const { res, captured } = makeRes();
+            await callRoute(
+                'get',
+                '/auth/oidc/:provider/start',
+                makeReq({
+                    params: { provider: 'custom' },
+                    query: { return_to },
+                }),
+                res,
+            );
+            const state = new URL(
+                captured.redirectUrl ?? '',
+            ).searchParams.get('state');
+            const decoded = oidc().verifyState(state!);
+            expect(String(decoded?.redirect_uri)).toBe(TEST_ORIGIN);
+        }
+    });
+
     it('signs revalidate-flow state with user_uuid + flow=revalidate', async () => {
         const userUuid = uuidv4();
         const { res, captured } = makeRes();
@@ -593,10 +664,81 @@ describe('OIDCController login callback', () => {
         );
         expect(captured.redirectStatus).toBe(302);
         expect(captured.redirectUrl).toContain('auth_error=1');
+        expect(captured.redirectUrl).toContain('message=account_suspended');
         // No session cookie issued for suspended accounts.
         expect(captured.cookies).toHaveLength(0);
     });
 
+    it('redirects back to an /app/<name> landing after sign-in', async () => {
+        const state = oidc().signState({
+            provider: 'custom',
+            redirect_uri: `${TEST_ORIGIN}/app/some-app`,
+        });
+        vi.spyOn(oidc(), 'exchangeCodeForTokens').mockResolvedValue({
+            access_token: 'access',
+            id_token: 'id',
+        } as never);
+        vi.spyOn(oidc(), 'getUserInfo').mockResolvedValue({
+            sub: `sub-${Math.random().toString(36).slice(2, 8)}`,
+            email: `oidc-${Math.random().toString(36).slice(2, 8)}@test.local`,
+            email_verified: true,
+        } as never);
+
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/auth/oidc/callback/login',
+            makeReq({ query: { code: 'c', state } }),
+            res,
+        );
+        expect(captured.cookies).toHaveLength(1);
+        expect(captured.redirectUrl).toBe(`${TEST_ORIGIN}/app/some-app`);
+    });
+
+    it('keeps an /app/<name> landing in the error redirect (suspended user)', async () => {
+        const sub = `sub-${Math.random().toString(36).slice(2, 8)}`;
+        const email = `sus-app-${Math.random().toString(36).slice(2, 8)}@test.local`;
+        const created = await runWithContext(
+            { req: makeReq({}) },
+            () =>
+                oidc().createUserFromOIDC('custom', {
+                    sub,
+                    email,
+                    email_verified: true,
+                }),
+        );
+        expect(created.success).toBe(true);
+        await server.stores.user.update(created.user!.id, { suspended: 1 });
+
+        const state = oidc().signState({
+            provider: 'custom',
+            redirect_uri: `${TEST_ORIGIN}/app/some-app`,
+        });
+        vi.spyOn(oidc(), 'exchangeCodeForTokens').mockResolvedValue({
+            access_token: 'access',
+            id_token: 'id',
+        } as never);
+        vi.spyOn(oidc(), 'getUserInfo').mockResolvedValue({
+            sub,
+            email,
+            email_verified: true,
+        } as never);
+
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/auth/oidc/callback/login',
+            makeReq({ query: { code: 'c', state } }),
+            res,
+        );
+        expect(captured.redirectStatus).toBe(302);
+        const url = new URL(captured.redirectUrl ?? '');
+        expect(url.pathname).toBe('/app/some-app');
+        expect(url.searchParams.get('auth_error')).toBe('1');
+        expect(url.searchParams.get('action')).toBe('login');
+        expect(captured.cookies).toHaveLength(0);
+    });
+
     it('appends oidc_login=true and uses popup-style URL when state is from a popup flow', async () => {
         const sub = `sub-${Math.random().toString(36).slice(2, 8)}`;
         const email = `oidc-${Math.random().toString(36).slice(2, 8)}@test.local`;
@@ -674,9 +816,7 @@ describe('OIDCController login callback', () => {
         expect(captured.redirectUrl).toContain('embedded_in_popup=true');
         expect(captured.redirectUrl).toContain('msg_id=msg-99');
         expect(captured.redirectUrl).toContain('auth_error=1');
-        // 'This account is suspended.' is not in ALLOWED_ERRORS, so the
-        // builder falls back to 'unauthorized'.
-        expect(captured.redirectUrl).toContain('message=unauthorized');
+        expect(captured.redirectUrl).toContain('message=account_suspended');
         expect(captured.redirectUrl).toContain(
             `opener_origin=${encodeURIComponent('http://opener.test')}`,
         );
@@ -767,6 +907,291 @@ describe('OIDCController login callback', () => {
     });
 });
 
+// -- Browser binding / login-CSRF --------------------------------------
+
+describe('OIDCController signup veto (abuse harness)', () => {
+    const vetoWithTrail = (email: string, trailId: string) => {
+        signupValidateOverride = (data) => {
+            if (data.email !== email) return;
+            data.allow = false;
+            data.trail_id = trailId;
+        };
+    };
+
+    const stubIdp = (sub: string, email: string) => {
+        vi.spyOn(oidc(), 'exchangeCodeForTokens').mockResolvedValue({
+            access_token: 'access',
+            id_token: 'id',
+        } as never);
+        vi.spyOn(oidc(), 'getUserInfo').mockResolvedValue({
+            sub,
+            email,
+            email_verified: true,
+        } as never);
+    };
+
+    it('createUserFromOIDC returns signup_blocked and the trail id as requestCode', async () => {
+        const email = `veto-${Math.random().toString(36).slice(2, 8)}@test.local`;
+        vetoWithTrail(email, 'trail-svc-1');
+
+        const created = await runWithContext(
+            { req: makeReq({}) },
+            () =>
+                oidc().createUserFromOIDC('custom', {
+                    sub: `sub-${Math.random().toString(36).slice(2, 8)}`,
+                    email,
+                    email_verified: true,
+                }),
+        );
+        expect(created.success).toBe(false);
+        expect(created.code).toBe('signup_blocked');
+        expect(created.requestCode).toBe('trail-svc-1');
+    });
+
+    it('login callback redirects with signup_blocked + request_code when first sign-in is vetoed', async () => {
+        const email = `veto-${Math.random().toString(36).slice(2, 8)}@test.local`;
+        vetoWithTrail(email, 'trail-login-1');
+        stubIdp(`sub-${Math.random().toString(36).slice(2, 8)}`, email);
+
+        const state = oidc().signState({
+            provider: 'custom',
+            redirect_uri: TEST_ORIGIN + '/',
+        });
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/auth/oidc/callback/login',
+            makeReq({ query: { code: 'c', state } }),
+            res,
+        );
+
+        expect(captured.redirectStatus).toBe(302);
+        expect(captured.redirectUrl).toContain('auth_error=1');
+        expect(captured.redirectUrl).toContain('action=login');
+        expect(captured.redirectUrl).toContain('message=signup_blocked');
+        expect(captured.redirectUrl).toContain('request_code=trail-login-1');
+        expect(captured.cookies).toHaveLength(0);
+    });
+
+    it('signup callback redirects with signup_blocked + request_code when vetoed', async () => {
+        const email = `veto-${Math.random().toString(36).slice(2, 8)}@test.local`;
+        vetoWithTrail(email, 'trail-signup-1');
+        stubIdp(`sub-${Math.random().toString(36).slice(2, 8)}`, email);
+
+        const state = oidc().signState({
+            provider: 'custom',
+            redirect_uri: TEST_ORIGIN + '/',
+        });
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/auth/oidc/callback/signup',
+            makeReq({ query: { code: 'c', state } }),
+            res,
+        );
+
+        expect(captured.redirectStatus).toBe(302);
+        expect(captured.redirectUrl).toContain('auth_error=1');
+        expect(captured.redirectUrl).toContain('action=signup');
+        expect(captured.redirectUrl).toContain('message=signup_blocked');
+        expect(captured.redirectUrl).toContain('request_code=trail-signup-1');
+        expect(captured.cookies).toHaveLength(0);
+    });
+
+    it('a veto with no trail id still redirects with signup_blocked and no request_code', async () => {
+        const email = `veto-${Math.random().toString(36).slice(2, 8)}@test.local`;
+        signupValidateOverride = (data) => {
+            if (data.email !== email) return;
+            data.allow = false;
+        };
+        stubIdp(`sub-${Math.random().toString(36).slice(2, 8)}`, email);
+
+        const state = oidc().signState({
+            provider: 'custom',
+            redirect_uri: TEST_ORIGIN + '/',
+        });
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/auth/oidc/callback/signup',
+            makeReq({ query: { code: 'c', state } }),
+            res,
+        );
+
+        expect(captured.redirectUrl).toContain('message=signup_blocked');
+        expect(captured.redirectUrl).not.toContain('request_code');
+    });
+});
+
+describe('OIDCController browser binding', () => {
+    const NONCE_COOKIE = 'puter_oidc_nonce';
+
+    const stubIdP = (sub: string, email: string) => {
+        vi.spyOn(oidc(), 'exchangeCodeForTokens').mockResolvedValue({
+            access_token: 'access',
+            id_token: 'id',
+        } as never);
+        vi.spyOn(oidc(), 'getUserInfo').mockResolvedValue({
+            sub,
+            email,
+            email_verified: true,
+        } as never);
+    };
+
+    it('/start sets an HttpOnly nonce cookie matching the nonce embedded in state', async () => {
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/auth/oidc/:provider/start',
+            makeReq({ params: { provider: 'custom' } }),
+            res,
+        );
+
+        const nonceCookie = captured.cookies.find(
+            (c) => c.name === NONCE_COOKIE,
+        );
+        expect(nonceCookie).toBeTruthy();
+        expect(nonceCookie?.value).toBeTruthy();
+        expect((nonceCookie?.opts as { httpOnly?: boolean })?.httpOnly).toBe(
+            true,
+        );
+
+        // The cookie value must equal the nonce baked into the signed state.
+        const state = new URL(captured.redirectUrl ?? '').searchParams.get(
+            'state',
+        );
+        const decoded = oidc().verifyState(state!);
+        expect(decoded?.nonce).toBe(nonceCookie?.value);
+    });
+
+    it('completes login when the nonce cookie matches the state nonce', async () => {
+        const sub = `sub-${Math.random().toString(36).slice(2, 8)}`;
+        const email = `bind-${Math.random().toString(36).slice(2, 8)}@test.local`;
+        const nonce = 'browser-nonce-match';
+        const state = oidc().signState({
+            provider: 'custom',
+            redirect_uri: TEST_ORIGIN + '/',
+            nonce,
+        });
+        stubIdP(sub, email);
+
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/auth/oidc/callback/login',
+            makeReq({
+                query: { code: 'c', state },
+                cookies: { [NONCE_COOKIE]: nonce },
+            }),
+            res,
+        );
+
+        // Session cookie issued; single-use nonce cookie cleared.
+        expect(captured.cookies).toHaveLength(1);
+        expect(captured.redirectUrl).toBe(TEST_ORIGIN + '/');
+        expect(
+            captured.clearedCookies.some((c) => c.name === NONCE_COOKIE),
+        ).toBe(true);
+    });
+
+    it('rejects login (no session cookie) when the nonce cookie is absent — the login-CSRF case', async () => {
+        const state = oidc().signState({
+            provider: 'custom',
+            redirect_uri: TEST_ORIGIN + '/',
+            nonce: 'attacker-flow-nonce',
+        });
+        // If enforcement were missing, this would resolve a user and set a
+        // session cookie for the victim's browser. It must not get that far.
+        const exchangeSpy = vi.spyOn(oidc(), 'exchangeCodeForTokens');
+
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/auth/oidc/callback/login',
+            // Victim's browser has no nonce cookie for the attacker's flow.
+            makeReq({ query: { code: 'c', state }, cookies: {} }),
+            res,
+        );
+
+        expect(captured.redirectStatus).toBe(302);
+        expect(captured.redirectUrl).toContain('auth_error=1');
+        expect(captured.cookies).toHaveLength(0);
+        // We bail before ever exchanging the code.
+        expect(exchangeSpy).not.toHaveBeenCalled();
+    });
+
+    it('rejects login when the nonce cookie does not match the state nonce', async () => {
+        const state = oidc().signState({
+            provider: 'custom',
+            redirect_uri: TEST_ORIGIN + '/',
+            nonce: 'expected-nonce',
+        });
+        const exchangeSpy = vi.spyOn(oidc(), 'exchangeCodeForTokens');
+
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/auth/oidc/callback/login',
+            makeReq({
+                query: { code: 'c', state },
+                cookies: { [NONCE_COOKIE]: 'a-different-nonce' },
+            }),
+            res,
+        );
+
+        expect(captured.redirectUrl).toContain('auth_error=1');
+        expect(captured.cookies).toHaveLength(0);
+        expect(exchangeSpy).not.toHaveBeenCalled();
+    });
+
+    it('rejects the revalidate callback (400) when the nonce cookie is missing', async () => {
+        const state = oidc().signState({
+            provider: 'custom',
+            flow: 'revalidate',
+            user_uuid: uuidv4(),
+            nonce: 'reval-nonce',
+        });
+        const exchangeSpy = vi.spyOn(oidc(), 'exchangeCodeForTokens');
+
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/auth/oidc/callback/revalidate',
+            makeReq({ query: { code: 'c', state }, cookies: {} }),
+            res,
+        );
+
+        expect(captured.statusCode).toBe(400);
+        expect(exchangeSpy).not.toHaveBeenCalled();
+    });
+
+    it('lets legacy nonce-less state through (deploy grace) without touching the nonce cookie', async () => {
+        const sub = `sub-${Math.random().toString(36).slice(2, 8)}`;
+        const email = `legacy-${Math.random().toString(36).slice(2, 8)}@test.local`;
+        // No `nonce` field — mimics a state signed before this shipped.
+        const state = oidc().signState({
+            provider: 'custom',
+            redirect_uri: TEST_ORIGIN + '/',
+        });
+        stubIdP(sub, email);
+
+        const { res, captured } = makeRes();
+        await callRoute(
+            'get',
+            '/auth/oidc/callback/login',
+            makeReq({ query: { code: 'c', state }, cookies: {} }),
+            res,
+        );
+
+        // Proceeds as before; no nonce cookie is cleared for legacy states.
+        expect(captured.cookies).toHaveLength(1);
+        expect(captured.redirectUrl).toBe(TEST_ORIGIN + '/');
+        expect(
+            captured.clearedCookies.some((c) => c.name === NONCE_COOKIE),
+        ).toBe(false);
+    });
+});
+
 // ── /auth/oidc/callback/signup ──────────────────────────────────────
 
 describe('OIDCController signup callback', () => {

src/backend/controllers/oidc/OIDCController.ts

@@ -3,20 +3,22 @@
  *
  * 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.
+ * 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.
+ * 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/>.
+ * along with this program. If not, see
+ * [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
  */
 
+import crypto from 'node:crypto';
 import type { Request, Response } from 'express';
 import { HttpError } from '../../core/http/HttpError.js';
 import type { PuterRouter } from '../../core/http/PuterRouter.js';
@@ -26,46 +28,89 @@ import { sessionCookieFlags } from '../../util/cookieFlags.js';
 const REVALIDATION_COOKIE_NAME = 'puter_revalidation';
 const REVALIDATION_EXPIRY_SEC = 300;
 
+// Companion cookie that binds an OIDC flow to the browser that started it.
+// Expiry mirrors STATE_EXPIRY_SEC in OIDCService — the state and its
+// browser-binding cookie must expire together.
+const OIDC_NONCE_COOKIE_NAME = 'puter_oidc_nonce';
+const OIDC_NONCE_EXPIRY_SEC = 600;
+
 const OIDC_ERROR_REDIRECT_MAP: Record<string, Record<string, string>> = {
     login: { account_not_found: 'signup', other: 'login' },
     signup: { account_already_exists: 'login', other: 'signup' },
 };
 
-const ALLOWED_ERRORS = ['account_suspended', 'unauthorized'] as const;
+// The `message` query param is clamped to these codes — the GUI maps them to
+// display text. Free-text errors (which may describe internals or, for vetoed
+// signups, the block reason) never reach the redirect URL.
+const ALLOWED_ERRORS = [
+    'account_suspended',
+    'unauthorized',
+    'signup_blocked',
+] as const;
+
+// GUI pages an OIDC flow may return to: /desktop, /dashboard, and direct app
+// landings (/app/<name>, mirroring APP_NAME_REGEX in AppDriver). Strict
+// whitelist — never a client-supplied URL (no open redirect).
+function isWhitelistedReturnPath(path: string): boolean {
+    return (
+        path === '/desktop' ||
+        path === '/dashboard' ||
+        /^\/app\/[a-zA-Z0-9_-]{1,100}$/.test(path)
+    );
+}
 
 function buildErrorRedirectUrl(
     origin: string,
     sourceFlow: string,
     errorCondition: string,
-    message: (typeof ALLOWED_ERRORS)[number],
+    message: string,
     stateDecoded?: Record<string, unknown>,
+    requestCode?: string,
 ): string {
     const targetFlow =
         OIDC_ERROR_REDIRECT_MAP[sourceFlow]?.[errorCondition] ?? sourceFlow;
     const base = origin.replace(/\/$/, '') || '/';
+    const clamped = (ALLOWED_ERRORS as readonly string[]).includes(message)
+        ? message
+        : 'unauthorized';
 
+    // Land back on the whitelisted page the flow started from (e.g. an
+    // /app/<name> landing) so the retry — and the eventual success — keeps
+    // the user's destination. redirect_uri comes from the signed state and
+    // was built server-side, but re-check the path against the whitelist.
+    let pagePath = '/';
+    if (typeof stateDecoded?.redirect_uri === 'string') {
+        try {
+            const statePath = new URL(stateDecoded.redirect_uri).pathname;
+            if (isWhitelistedReturnPath(statePath)) pagePath = statePath;
+        } catch {
+            // unparsable redirect_uri: fall back to the root page
+        }
+    }
+
+    let params: URLSearchParams;
     if (stateDecoded?.embedded_in_popup && stateDecoded?.msg_id != null) {
-        const params = new URLSearchParams({
+        params = new URLSearchParams({
             embedded_in_popup: 'true',
             msg_id: String(stateDecoded.msg_id),
             auth_error: '1',
-            message: ALLOWED_ERRORS.includes(message)
-                ? message
-                : 'unauthorized',
+            message: clamped,
             action: targetFlow,
         });
         if (stateDecoded?.opener_origin) {
             params.set('opener_origin', String(stateDecoded.opener_origin));
         }
-        return `${base}/?${params.toString()}`;
+    } else {
+        params = new URLSearchParams({
+            action: targetFlow,
+            auth_error: '1',
+            message: clamped,
+        });
     }
-
-    const params = new URLSearchParams({
-        action: targetFlow,
-        auth_error: '1',
-        message: ALLOWED_ERRORS.includes(message) ? message : 'unauthorized',
-    });
-    return `${base}/?${params.toString()}`;
+    if (requestCode) {
+        params.set('request_code', requestCode);
+    }
+    return `${base}${pagePath}?${params.toString()}`;
 }
 
 function appendQueryParam(url: string, key: string, value: string): string {
@@ -73,9 +118,17 @@ function appendQueryParam(url: string, key: string, value: string): string {
     return `${url}${sep}${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
 }
 
+/** Length-safe constant-time string compare (never throws on mismatch). */
+function constantTimeEqual(a: string, b: string): boolean {
+    const ba = Buffer.from(a);
+    const bb = Buffer.from(b);
+    if (ba.length !== bb.length) return false;
+    return crypto.timingSafeEqual(ba, bb);
+}
+
 /**
- * True iff `target` parses as a URL whose origin equals `origin`. Used to
- * clamp OIDC redirect targets — `startsWith` would accept
+ * True iff `target` parses as a URL whose origin equals `origin`. Used to clamp
+ * OIDC redirect targets — `startsWith` would accept
  * `https://puter.com.evil.com` against `https://puter.com`.
  */
 function isSameOrigin(target: string, origin: string): boolean {
@@ -139,6 +192,19 @@ export class OIDCController extends PuterController {
 
                 let appRedirectUri = flowRedirects[flow] ?? (origin || '/');
 
+                // Optional GUI return path so login started from /desktop,
+                // /dashboard, or an /app/<name> landing lands back there.
+                const rawReturnTo = Array.isArray(req.query.return_to)
+                    ? req.query.return_to[0]
+                    : req.query.return_to;
+                if (
+                    (flow === 'login' || flow === 'signup') &&
+                    typeof rawReturnTo === 'string' &&
+                    isWhitelistedReturnPath(rawReturnTo)
+                ) {
+                    appRedirectUri = `${origin}${rawReturnTo}`;
+                }
+
                 // Popup support
                 const rawPopup = Array.isArray(req.query.embedded_in_popup)
                     ? req.query.embedded_in_popup[0]
@@ -198,6 +264,17 @@ export class OIDCController extends PuterController {
                     statePayload.flow = 'revalidate';
                 }
 
+                // Bind this flow to the initiating browser: a single-use
+                // nonce lives both in the signed `state` and in an HttpOnly
+                // companion cookie. The callback requires them to match, so a
+                // `state` captured from an attacker's own flow can't be
+                // replayed in a victim's browser (login-CSRF / session
+                // fixation).
+                const browserNonce = crypto
+                    .randomBytes(32)
+                    .toString('base64url');
+                statePayload.nonce = browserNonce;
+
                 const state = this.services.oidc.signState(statePayload);
                 const url = await this.services.oidc.getAuthorizationUrl(
                     provider,
@@ -211,6 +288,15 @@ export class OIDCController extends PuterController {
                         { legacyCode: 'internal_error' },
                     );
 
+                res.cookie(OIDC_NONCE_COOKIE_NAME, browserNonce, {
+                    // Same flags as the session cookie: SameSite=None;Secure
+                    // on HTTPS so the cookie survives Apple's cross-site
+                    // form_post callback; Lax on plain-HTTP self-host.
+                    ...sessionCookieFlags(this.config),
+                    httpOnly: true,
+                    maxAge: OIDC_NONCE_EXPIRY_SEC * 1000,
+                    path: '/',
+                });
                 res.redirect(302, url);
             },
         );
@@ -224,7 +310,7 @@ export class OIDCController extends PuterController {
 
         const loginCb = async (req: Request, res: Response) => {
             const origin = this.config.origin ?? '';
-            const result = await this.#processCallback(req, 'login');
+            const result = await this.#processCallback(req, res, 'login');
             if ('error' in result) {
                 console.warn(`OIDC login callback error: ${result.error}`);
                 return res.redirect(
@@ -255,8 +341,9 @@ export class OIDCController extends PuterController {
                         origin,
                         'login',
                         'other',
-                        resolved.error,
+                        resolved.code ?? 'unauthorized',
                         stateDecoded,
+                        resolved.requestCode,
                     ),
                 );
             }
@@ -272,7 +359,7 @@ export class OIDCController extends PuterController {
                         origin,
                         'login',
                         'other',
-                        'This account is suspended.',
+                        'account_suspended',
                         stateDecoded,
                     ),
                 );
@@ -287,7 +374,7 @@ export class OIDCController extends PuterController {
 
         const signupCb = async (req: Request, res: Response) => {
             const origin = this.config.origin ?? '';
-            const result = await this.#processCallback(req, 'signup');
+            const result = await this.#processCallback(req, res, 'signup');
             if ('error' in result) {
                 return res.redirect(
                     302,
@@ -308,14 +395,18 @@ export class OIDCController extends PuterController {
                 (stateDecoded.referrer as string) ?? null,
             );
             if ('error' in resolved) {
+                console.warn(
+                    `OIDC signup user resolution error: ${resolved.error}`,
+                );
                 return res.redirect(
                     302,
                     buildErrorRedirectUrl(
                         origin,
                         'signup',
                         'other',
-                        'unauthorized',
+                        resolved.code ?? 'unauthorized',
                         stateDecoded,
+                        resolved.requestCode,
                     ),
                 );
             }
@@ -352,7 +443,7 @@ export class OIDCController extends PuterController {
             req: Request,
             res: Response,
         ): Promise<void> => {
-            const result = await this.#processCallback(req, 'revalidate');
+            const result = await this.#processCallback(req, res, 'revalidate');
             if ('error' in result) {
                 res.status(400).send(result.error);
                 return;
@@ -432,13 +523,14 @@ if (window.opener) {
 
     /**
      * Resolve an OIDC callback to a Puter user. In order:
-     *   1. Existing link on (provider, sub) → that user.
-     *   2. Email matches an existing account whose email is CONFIRMED →
-     *      link (provider, sub) to that user.
-     *   3. Email matches an account whose email is UNCONFIRMED → refuse.
-     *      We don't know who owns an unconfirmed address, so linking would
-     *      let whoever controls the OIDC identity hijack a pending signup.
-     *   4. Otherwise create a new user and link.
+     *
+     * 1. Existing link on (provider, sub) → that user.
+     * 2. Email matches an existing account whose email is CONFIRMED → link
+     *    (provider, sub) to that user.
+     * 3. Email matches an account whose email is UNCONFIRMED → refuse. We don't
+     *    know who owns an unconfirmed address, so linking would let whoever
+     *    controls the OIDC identity hijack a pending signup.
+     * 4. Otherwise create a new user and link.
      *
      * Step 2 also requires `email_verified !== false` on the OIDC side,
      * otherwise a malicious IdP could claim someone else's email.
@@ -451,7 +543,7 @@ if (window.opener) {
         userinfo: { sub: string; email?: unknown; [k: string]: unknown },
         referrer?: string | null,
     ): Promise<
-        | { error: string }
+        | { error: string; code?: string; requestCode?: string }
         | {
               user: import('../../stores/user/UserStore.js').UserRow;
               origin: 'linked-sub' | 'linked-email' | 'created';
@@ -497,13 +589,18 @@ if (window.opener) {
             referrer,
         );
         if (!outcome.success || !outcome.user) {
-            return { error: outcome.error ?? 'Account creation failed.' };
+            return {
+                error: outcome.error ?? 'Account creation failed.',
+                code: outcome.code,
+                requestCode: outcome.requestCode,
+            };
         }
         return { user: outcome.user, origin: 'created' };
     }
 
     async #processCallback(
         req: Request,
+        res: Response,
         flow: string,
     ): Promise<
         | { error: string }
@@ -527,6 +624,28 @@ if (window.opener) {
         if (!stateDecoded || !stateDecoded.provider)
             return { error: 'Invalid or expired state.' };
 
+        // Enforce the browser binding set at /start. Every state minted by
+        // the current /start carries a nonce, so this covers all live flows.
+        // States signed before this shipped have no nonce and pass through
+        // until they expire (STATE_EXPIRY, 10 min) so in-flight logins don't
+        // break on deploy — a caller can't forge a nonce-less state because
+        // /start always adds one and the state is server-signed.
+        const expectedNonce =
+            typeof stateDecoded.nonce === 'string' ? stateDecoded.nonce : '';
+        if (expectedNonce) {
+            const cookieNonce = req.cookies?.[OIDC_NONCE_COOKIE_NAME];
+            // Single-use: drop the cookie regardless of the outcome.
+            res.clearCookie(OIDC_NONCE_COOKIE_NAME, { path: '/' });
+            if (
+                typeof cookieNonce !== 'string' ||
+                !constantTimeEqual(cookieNonce, expectedNonce)
+            ) {
+                return {
+                    error: 'This sign-in could not be verified for your browser. Please start again.',
+                };
+            }
+        }
+
         const provider = String(stateDecoded.provider);
         const callbackUrl = this.services.oidc.getCallbackUrl(flow);
         if (!callbackUrl) return { error: 'Invalid flow.' };

src/backend/controllers/puterai/PuterAIController.test.ts

@@ -44,7 +44,9 @@ import {
 } from 'vitest';
 
 import type { Actor } from '../../core/actor.js';
+import type { RouteOptions } from '../../core/http/index.js';
 import type { ChatCompletionDriver } from '../../drivers/ai-chat/ChatCompletionDriver.js';
+import { AI_CONCURRENT, AI_RATE_LIMIT } from '../../drivers/util/aiLimits.js';
 import { PuterServer } from '../../server.js';
 import { setupTestServer } from '../../testUtil.js';
 import { PuterAIController } from './PuterAIController.js';
@@ -188,11 +190,16 @@ describe('PuterAIController.registerRoutes', () => {
             ]),
         );
 
-        // The four upstream-proxy routes reject third-party apps (they must
-        // call puter-chat-completion directly), but admit the user's own
-        // full-access personal access token: `requireUserActor` keeps apps out
-        // and `allowFullAccessToken` opens the gate to a full-access PAT. Each
-        // proxy route carries both flags.
+        // The four upstream-proxy routes accept exactly one credential
+        // shape — a full-access API token minted from the dashboard:
+        // `requireUserActor` keeps apps out, `allowFullAccessToken` admits
+        // the PAT, and `noUserSession` rejects the account session ("root")
+        // token. Each route also carries `requireVerified` (fresh accounts
+        // must confirm their email before using the AI wire surface) and
+        // the shared per-tier AI rate-limit / concurrency policy — these
+        // routes bypass the `/drivers/call` dispatch (where the
+        // driver-declared limits are enforced), so without the route gates
+        // they'd be unthrottled.
         const userOnlyPaths = [
             '/puterai/openai/v1/chat/completions',
             '/puterai/openai/v1/completions',
@@ -205,6 +212,18 @@ describe('PuterAIController.registerRoutes', () => {
                 subdomain: 'api',
                 requireUserActor: true,
                 allowFullAccessToken: true,
+                noUserSession: true,
+                requireVerified: true,
+                rateLimit: {
+                    ...AI_RATE_LIMIT.default,
+                    scope: 'driver:puter-chat-completion:complete',
+                    key: expect.any(Function),
+                },
+                concurrent: {
+                    ...AI_CONCURRENT.default,
+                    scope: 'driver:puter-chat-completion:complete',
+                    key: expect.any(Function),
+                },
             });
         }
         const modelsRoute = calls.find(
@@ -215,6 +234,46 @@ describe('PuterAIController.registerRoutes', () => {
             requireAuth: false,
         });
     });
+
+    it('keys the proxy-route AI limits by user uuid so they share the /drivers/call buckets', () => {
+        const calls: Array<{ path: string; opts: RouteOptions }> = [];
+        const router = {
+            post: vi.fn((path: string, opts: RouteOptions) => {
+                calls.push({ path, opts });
+                return router;
+            }),
+            get: vi.fn(() => router),
+        };
+
+        controller.registerRoutes(router as never);
+
+        const route = calls.find(
+            (c) => c.path === '/puterai/openai/v1/chat/completions',
+        );
+        const rateLimit = route?.opts.rateLimit as {
+            key: (req: Request) => string;
+            scope: string;
+        };
+        const concurrent = route?.opts.concurrent as {
+            key: (req: Request) => string;
+            scope: string;
+        };
+
+        // The dispatch buckets requests as `driver:<iface>:<method>:<uid>`
+        // where uid is the actor's user uuid; scope + key must compose to the
+        // identical string or wire traffic mints a second per-user budget.
+        const req = makeReq({ actor: makeUserActor() });
+        expect(rateLimit.key(req)).toBe('u-7');
+        expect(concurrent.key(req)).toBe('u-7');
+        expect(rateLimit.scope).toBe('driver:puter-chat-completion:complete');
+        expect(concurrent.scope).toBe('driver:puter-chat-completion:complete');
+
+        // No-actor fallback still yields a usable (fingerprint) key rather
+        // than throwing or bucketing everyone together under undefined.
+        const anonKey = rateLimit.key(makeReq({}));
+        expect(typeof anonKey).toBe('string');
+        expect(anonKey.length).toBeGreaterThan(0);
+    });
 });
 
 // ── /openai/v1/chat/completions ─────────────────────────────────────

src/backend/controllers/puterai/PuterAIController.ts

@@ -22,6 +22,7 @@ import crypto from 'node:crypto';
 import { Readable } from 'node:stream';
 import { HttpError } from '../../core/http/HttpError.js';
 import { RouteOptions } from '../../core/http/index.js';
+import { computeNetworkFingerprint } from '../../core/http/middleware/rateLimit.js';
 import type { PuterRouter } from '../../core/http/PuterRouter.js';
 import type { ChatCompletionDriver } from '../../drivers/ai-chat/ChatCompletionDriver.js';
 import type {
@@ -29,6 +30,7 @@ import type {
     ICompleteArguments,
 } from '../../drivers/ai-chat/types.js';
 import { isDriverStreamResult } from '../../drivers/meta.js';
+import { AI_CONCURRENT, AI_RATE_LIMIT } from '../../drivers/util/aiLimits.js';
 import { PuterController } from '../types.js';
 
 const GEMINI_DOWNLOAD_BASE =
@@ -44,20 +46,49 @@ const GEMINI_DOWNLOAD_BASE =
  * ChatCompletionDriver, and translate the result (or NDJSON stream) back
  * into the vendor's response / SSE shape.
  *
- * All routes live on `subdomain: 'api'` and reject app-under-user actors —
- * only user actors may proxy.
+ * All routes live on `subdomain: 'api'` and require a full-access API
+ * token minted from the dashboard (user-scoped worker tokens also pass —
+ * workers are never treated as root tokens). Apps, scoped tokens, and
+ * account session ("root") tokens are rejected.
  */
 export class PuterAIController extends PuterController {
     registerRoutes(router: PuterRouter): void {
+        /**
+         * The wire routes call the chat driver directly instead of going
+         * through the `/drivers/call` dispatch, so the shared per-tier AI
+         * rate-limit / concurrency policy must be declared as route gates
+         * here. `scope` + `key` reproduce the dispatch's bucket key
+         * (`driver:<iface>:<method>:<uid>`) exactly, so wire traffic and
+         * `/drivers/call` traffic draw from one per-user budget rather than
+         * each surface minting its own.
+         */
+        const aiPolicyScope = 'driver:puter-chat-completion:complete';
+        const aiPolicyKey = (req: Request): string =>
+            req.actor?.user?.uuid || computeNetworkFingerprint(req);
         const apiAuthOpts = {
             subdomain: 'api',
+            // The wire routes want a delegated credential — a full-access
+            // API token minted from the dashboard (or a user-scoped worker
+            // token, which is never treated as a root token).
+            // `requireUserActor` keeps apps out, `allowFullAccessToken`
+            // admits the PAT, and `noUserSession` rejects the account's
+            // session ("root") token — a copied session credential
+            // shouldn't double as an AI API key. `requireVerified` keeps
+            // fresh/unconfirmed accounts out, same as FS writes.
             requireUserActor: true,
-            // These are the user's own programmatic AI surface (OpenAI/Anthropic
-            // wire). `requireUserActor` here exists to keep third-party apps
-            // out, not to block the user's own credential — so admit full-access
-            // personal access tokens (CLI/MCP/scripts). Apps and scoped tokens
-            // stay blocked.
             allowFullAccessToken: true,
+            noUserSession: true,
+            requireVerified: true,
+            rateLimit: {
+                ...AI_RATE_LIMIT.default!,
+                scope: aiPolicyScope,
+                key: aiPolicyKey,
+            },
+            concurrent: {
+                ...AI_CONCURRENT.default!,
+                scope: aiPolicyScope,
+                key: aiPolicyKey,
+            },
         } as RouteOptions;
         const publicOpts = { subdomain: 'api', requireAuth: false } as const;
 

src/backend/controllers/system/SystemController.js

@@ -37,17 +37,33 @@ export class SystemController extends PuterController {
     ) {
         // -- Healthcheck ---------------------------------------------
         // Delegates to ServerHealthService for the real check-based
-        // status. Returns `{ ok: true }` when all registered checks pass,
-        // or `{ ok: false, failed: [...] }` + 503 when any fail or the
+        // status. Returns `{ ok: true }` + 200 when all registered checks
+        // pass, or `{ ok: false, failed: [...] }` + 503 when any fail or the
         // server is draining.
-        router.get('/healthcheck', { subdomain: '*' }, async (_req, res) => {
+        //
+        // `?ignore=a,b` disregards the named checks for this request only.
+        // `?marked-degraded=a,b` demotes the named checks to a non-fatal
+        // `degraded` list: `ok` stays true but the response is 207 so the
+        // caller can tell the node is running in a degraded state.
+        const parseNames = (value) =>
+            typeof value === 'string'
+                ? value
+                      .split(',')
+                      .map((name) => name.trim())
+                      .filter(Boolean)
+                : [];
+        router.get('/healthcheck', { subdomain: '*' }, async (req, res) => {
             const health = this.services.health;
             if (!health || typeof health.getStatus !== 'function') {
                 // Fallback for boot ordering / missing service.
                 return res.send('ok');
             }
-            const status = await health.getStatus();
+            const status = await health.getStatus({
+                ignore: parseNames(req.query.ignore),
+                degrade: parseNames(req.query['marked-degraded']),
+            });
             if (!status.ok) return res.status(503).json(status);
+            if (status.degraded?.length) return res.status(207).json(status);
             return res.json(status);
         });
 
@@ -137,31 +153,31 @@ export class SystemController extends PuterController {
                 name: 'Puter',
                 version: this.config.version ?? null,
                 environment: this.config.env ?? 'prod',
+                disable_user_signup: Boolean(this.config.disable_user_signup),
             });
         });
 
-        // -- GET /lsmod ----------------------------------------------
-        // Enumerates driver interfaces and their implementors.
+        // -- GET|POST /lsmod -----------------------------------------
+        // Enumerates driver interfaces and their implementors. POST is
+        // also routed because puter.js `drivers.list()` sends POST.
 
-        router.get(
-            '/lsmod',
-            { subdomain: 'api', requireAuth: true },
-            (_req, res) => {
-                const interfaces = {};
-                for (const [key, driver] of Object.entries(this.drivers)) {
-                    const ifaceName = driver?.driverInterface;
-                    if (!ifaceName) continue;
-                    const driverName = driver.driverName ?? key;
-                    if (!interfaces[ifaceName]) {
-                        interfaces[ifaceName] = { implementors: {} };
-                    }
-                    interfaces[ifaceName].implementors[driverName] = {
-                        isDefault: Boolean(driver.isDefault),
-                    };
+        const lsmod = (_req, res) => {
+            const interfaces = {};
+            for (const [key, driver] of Object.entries(this.drivers)) {
+                const ifaceName = driver?.driverInterface;
+                if (!ifaceName) continue;
+                const driverName = driver.driverName ?? key;
+                if (!interfaces[ifaceName]) {
+                    interfaces[ifaceName] = { implementors: {} };
                 }
-                res.json({ interfaces });
-            },
-        );
+                interfaces[ifaceName].implementors[driverName] = {
+                    isDefault: Boolean(driver.isDefault),
+                };
+            }
+            res.json({ interfaces });
+        };
+        router.get('/lsmod', { subdomain: 'api', requireAuth: true }, lsmod);
+        router.post('/lsmod', { subdomain: 'api', requireAuth: true }, lsmod);
     }
 
     onServerStart() {}

src/backend/controllers/system/SystemController.test.ts

@@ -18,9 +18,10 @@
  */
 
 import type { Request, RequestHandler, Response } from 'express';
-import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
 import { v4 as uuidv4 } from 'uuid';
 import type { Actor } from '../../core/actor.js';
+import { kv } from '../../util/kvSingleton.js';
 import { PuterRouter } from '../../core/http/PuterRouter.js';
 import { PuterServer } from '../../server.js';
 import { setupTestServer } from '../../testUtil.js';
@@ -79,10 +80,11 @@ interface CapturedResponse {
 const makeReq = (init: {
     body?: unknown;
     actor?: Actor;
+    query?: Record<string, unknown>;
 }): Request => {
     return {
         body: init.body ?? {},
-        query: {},
+        query: init.query ?? {},
         headers: {},
         actor: init.actor,
     } as unknown as Request;
@@ -139,6 +141,191 @@ describe('SystemController GET /healthcheck', () => {
         expect(captured.body).toMatchObject({ ok: true });
         expect(captured.statusCode).toBe(200);
     });
+
+    it('parses ?ignore and ?marked-degraded into trimmed name lists', async () => {
+        const spy = vi
+            .spyOn(server.services.health, 'getStatus')
+            .mockResolvedValue({ ok: true });
+        try {
+            const { res } = makeRes();
+            await callRoute(
+                'get',
+                '/healthcheck',
+                makeReq({
+                    query: {
+                        ignore: 'database-liveness, thumbnailer',
+                        'marked-degraded': ' socket-initialized ',
+                    },
+                }),
+                res,
+            );
+            expect(spy).toHaveBeenCalledWith({
+                ignore: ['database-liveness', 'thumbnailer'],
+                degrade: ['socket-initialized'],
+            });
+        } finally {
+            spy.mockRestore();
+        }
+    });
+
+    it('returns ok:true + 200 when the only failures are ignored', async () => {
+        const spy = vi
+            .spyOn(server.services.health, 'getStatus')
+            .mockImplementation(async ({ ignore = [] } = {}) => {
+                const failed = ['database-liveness'].filter(
+                    (name) => !ignore.includes(name),
+                );
+                return failed.length === 0
+                    ? { ok: true }
+                    : { ok: false, failed };
+            });
+        try {
+            const { res, captured } = makeRes();
+            await callRoute(
+                'get',
+                '/healthcheck',
+                makeReq({ query: { ignore: 'database-liveness' } }),
+                res,
+            );
+            expect(captured.body).toEqual({ ok: true });
+            expect(captured.statusCode).toBe(200);
+        } finally {
+            spy.mockRestore();
+        }
+    });
+
+    it('returns ok:true + 207 when the only failures are marked degraded', async () => {
+        const spy = vi
+            .spyOn(server.services.health, 'getStatus')
+            .mockResolvedValue({ ok: true, degraded: ['database-liveness'] });
+        try {
+            const { res, captured } = makeRes();
+            await callRoute(
+                'get',
+                '/healthcheck',
+                makeReq({ query: { 'marked-degraded': 'database-liveness' } }),
+                res,
+            );
+            expect(captured.body).toEqual({
+                ok: true,
+                degraded: ['database-liveness'],
+            });
+            expect(captured.statusCode).toBe(207);
+        } finally {
+            spy.mockRestore();
+        }
+    });
+
+    it('still 503s when a non-ignored failure remains', async () => {
+        const spy = vi
+            .spyOn(server.services.health, 'getStatus')
+            .mockImplementation(async ({ ignore = [] } = {}) => {
+                const failed = ['database-liveness', 'socket-initialized'].filter(
+                    (name) => !ignore.includes(name),
+                );
+                return failed.length === 0
+                    ? { ok: true }
+                    : { ok: false, failed };
+            });
+        try {
+            const { res, captured } = makeRes();
+            await callRoute(
+                'get',
+                '/healthcheck',
+                makeReq({ query: { ignore: 'database-liveness' } }),
+                res,
+            );
+            expect(captured.statusCode).toBe(503);
+            expect(captured.body).toEqual({
+                ok: false,
+                failed: ['socket-initialized'],
+            });
+        } finally {
+            spy.mockRestore();
+        }
+    });
+});
+
+// ── ServerHealthService.getStatus ignore / degrade filtering ────────
+//
+// Exercises the real service by seeding the in-process status cache
+// (the kv.js singleton) it reads from, so the actual per-request
+// classification runs — not a stubbed getStatus.
+
+describe('ServerHealthService.getStatus ignore/degrade filtering', () => {
+    const STATUS_CACHE_KEY = 'server-health:status';
+
+    const seedStatus = (status: unknown) => {
+        kv.set(STATUS_CACHE_KEY, status, { EX: 5 });
+    };
+
+    afterEach(() => {
+        kv.del(STATUS_CACHE_KEY);
+    });
+
+    it('collapses to ok:true when every failure is ignored', async () => {
+        seedStatus({ ok: false, failed: ['database-liveness', 'thumbnailer'] });
+        const status = await server.services.health.getStatus({
+            ignore: ['database-liveness', 'thumbnailer'],
+        });
+        expect(status).toEqual({ ok: true });
+    });
+
+    it('keeps the non-ignored failures', async () => {
+        seedStatus({ ok: false, failed: ['database-liveness', 'thumbnailer'] });
+        const status = await server.services.health.getStatus({
+            ignore: ['database-liveness'],
+        });
+        expect(status).toEqual({ ok: false, failed: ['thumbnailer'] });
+    });
+
+    it('is a no-op for a healthy status', async () => {
+        seedStatus({ ok: true });
+        const status = await server.services.health.getStatus({
+            ignore: ['database-liveness'],
+        });
+        expect(status).toEqual({ ok: true });
+    });
+
+    it('ignores unknown names without affecting real failures', async () => {
+        seedStatus({ ok: false, failed: ['database-liveness'] });
+        const status = await server.services.health.getStatus({
+            ignore: ['not-a-check'],
+        });
+        expect(status).toEqual({ ok: false, failed: ['database-liveness'] });
+    });
+
+    it('demotes marked failures to degraded and stays ok:true', async () => {
+        seedStatus({ ok: false, failed: ['database-liveness'] });
+        const status = await server.services.health.getStatus({
+            degrade: ['database-liveness'],
+        });
+        expect(status).toEqual({ ok: true, degraded: ['database-liveness'] });
+    });
+
+    it('reports degraded alongside remaining hard failures (ok:false)', async () => {
+        seedStatus({
+            ok: false,
+            failed: ['database-liveness', 'socket-initialized'],
+        });
+        const status = await server.services.health.getStatus({
+            degrade: ['database-liveness'],
+        });
+        expect(status).toEqual({
+            ok: false,
+            failed: ['socket-initialized'],
+            degraded: ['database-liveness'],
+        });
+    });
+
+    it('lets ignore take precedence over degrade for the same name', async () => {
+        seedStatus({ ok: false, failed: ['database-liveness'] });
+        const status = await server.services.health.getStatus({
+            ignore: ['database-liveness'],
+            degrade: ['database-liveness'],
+        });
+        expect(status).toEqual({ ok: true });
+    });
 });
 
 // ── /version ────────────────────────────────────────────────────────
@@ -233,6 +420,7 @@ describe('SystemController GET /whoarewe', () => {
         expect(captured.body).toMatchObject({
             name: 'Puter',
             environment: 'dev',
+            disable_user_signup: false,
         });
     });
 });

src/backend/controllers/webdav/WebDAVController.test.ts

@@ -335,6 +335,63 @@ describe('WebDAVController', () => {
         });
     });
 
+    describe('suspension gate', () => {
+        // WebDAV must also enforce the suspension gate every other authenticated
+        // route gets from requireAuthGate. Same single-use() dispatch means that
+        // middleware is never wired in, so #dispatch calls assertNotSuspended
+        // itself. Without it, a suspended account could read/write/delete its
+        // whole filesystem over the `dav` subdomain.
+        it('rejects a suspended session actor with 403', async () => {
+            const { res, captured } = makeRes();
+            await dispatchMiddleware(
+                makeReq({
+                    method: 'PROPFIND',
+                    actor: {
+                        user: {
+                            id: 1,
+                            uuid: 'suspended-uuid',
+                            username: 'suspended',
+                            suspended: true,
+                        },
+                    },
+                }),
+                res,
+                noop,
+            );
+            expect(captured.statusCode).toBe(403);
+        });
+
+        it('rejects a suspended user on the Basic-auth path with 403', async () => {
+            const username = `webdav-suspended-${Math.random()
+                .toString(36)
+                .slice(2, 10)}`;
+            const created = await server.stores.user.create({
+                username,
+                uuid: uuidv4(),
+                password: await bcryptHash('correct-horse', 4),
+                email: `${username}@test.local`,
+                free_storage: 100 * 1024 * 1024,
+                requires_email_confirmation: false,
+            });
+            await server.stores.user.update(created.id, {
+                suspended: 1,
+            });
+
+            const { res, captured } = makeRes();
+            await dispatchMiddleware(
+                makeReq({
+                    method: 'PROPFIND',
+                    headers: {
+                        authorization: basicAuth(username, 'correct-horse'),
+                    },
+                }),
+                res,
+                noop,
+            );
+            expect(captured.statusCode).toBe(403);
+        });
+    });
+
     describe('unsupported methods', () => {
         it('returns 405 for unknown HTTP methods', async () => {
             const { res, captured } = makeRes();

src/backend/controllers/webdav/WebDAVController.ts

@@ -23,7 +23,10 @@ import { posix as pathPosix } from 'node:path';
 import { EventMap } from '../../clients/event/types.js';
 import type { Actor } from '../../core/actor.js';
 import { HttpError } from '../../core/http/HttpError.js';
-import { assertVerifiedAccount } from '../../core/http/middleware/gates.js';
+import {
+    assertNotSuspended,
+    assertVerifiedAccount,
+} from '../../core/http/middleware/gates.js';
 import type { PuterRouter } from '../../core/http/PuterRouter.js';
 import { verify as verifyOtp } from '../../services/auth/OTPUtil.js';
 import { expandTildePath } from '../../services/fs/resolveNode.js';
@@ -90,14 +93,15 @@ export class WebDAVController extends PuterController {
         const actor = await this.#resolveActor(req, res);
         if (!actor) return; // 401 already sent
 
-        // Apply the same pending-verification gate every other authenticated
-        // route gets from `requireVerifiedAccount`. WebDAV dispatches every
-        // method off a single `router.use` with no route options, so that
-        // middleware is never inserted into its chain — without this call an
-        // account still pending email / phone / card verification could read,
-        // write, and delete its entire filesystem over the `dav` subdomain,
-        // bypassing the gate. Throws a 403 HttpError, surfaced by the catch in
-        // registerRoutes.
+        // Apply the same suspension + pending-verification gates every other
+        // authenticated route gets from `requireAuthGate` / `requireVerifiedAccount`.
+        // WebDAV dispatches every method off a single `router.use` with no route
+        // options, so that middleware is never inserted into its chain — without
+        // these calls a suspended account (or one still pending email / phone /
+        // card verification) could read, write, and delete its entire filesystem
+        // over the `dav` subdomain, bypassing the gates. Both throw a 403
+        // HttpError, surfaced by the catch in registerRoutes.
+        assertNotSuspended(actor.user);
         assertVerifiedAccount(actor.user);
 
         // Expand `~`/`~/...` against the authenticated actor's username.

src/backend/core/actor.ts

@@ -54,9 +54,11 @@ export interface Actor {
      * Session reference when authenticated via a session token (user actors)
      * or an app-under-user token that carries a session. Absent for system,
      * raw-app, and pure access-token actors. Used for session introspection
-     * and targeted logout.
+     * and targeted logout. `kind` mirrors the session row's kind (e.g.
+     * 'web', 'app', 'worker') so callers can gate on how the credential
+     * was minted without an extra session lookup.
      */
-    session?: { uid: string } | null;
+    session?: { uid: string; kind?: string | null } | null;
 }
 
 /** UUID of the baked-in system user (see 0025 seed migration). */

src/backend/core/http/HttpError.ts

@@ -53,7 +53,8 @@ export type LegacyErrorCodes =
     | 'password_required'
     | 'password_mismatch'
     | 'field_not_allowed_for_create'
-    | 'account_is_not_verified';
+    | 'account_is_not_verified'
+    | 'app_or_api_token_required';
 
 /**
  * Copyright (C) 2024-present Puter Technologies Inc.

src/backend/core/http/expressAugmentation.ts

@@ -3,32 +3,34 @@
  *
  * 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.
+ * 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.
+ * 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/>.
+ * along with this program. If not, see
+ * [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
  */
 
 import type { Actor } from '../actor';
+import type { TokenSource } from './types';
 
 /**
  * Global Express.Request augmentation for v2.
  *
- * Every field declared here is populated by *global* middleware installed by
- * `PuterServer` (auth probe, body parser, etc.). Per-route fields stay local
- * to their handlers via `TypedRequest<O>` instead.
+ * Every field declared here is populated by _global_ middleware installed by
+ * `PuterServer` (auth probe, body parser, etc.). Per-route fields stay local to
+ * their handlers via `TypedRequest<O>` instead.
  *
  * This module is import-only — it has no runtime exports. Files that consume
- * the augmented `Request` should `import './expressAugmentation'` (or any
- * file that imports it transitively) so TypeScript loads the declaration.
+ * the augmented `Request` should `import './expressAugmentation'` (or any file
+ * that imports it transitively) so TypeScript loads the declaration.
  */
 
 declare global {
@@ -40,15 +42,28 @@ declare global {
             /** The raw token string, if one was presented and parsed. */
             token?: string;
 
+            /**
+             * Which request slot `token` came out of. Set alongside `token`;
+             * routes that mint browser credentials gate on it.
+             */
+            tokenSource?: TokenSource;
+
             tokenAuthFailed?: boolean;
 
+            /**
+             * Set when a token authenticated but its app is on the origin
+             * blocklist. The auth probe leaves `actor` unset; gates translate
+             * this into a 403 `app_blocked`.
+             */
+            appBlocked?: { reason?: string };
+
             requiresReauth?: {
                 reason: 'token_v1' | 'session_revoked' | 'session_expired';
                 auth_id?: string;
                 /**
                  * Short-lived server-signed JWT that proves the bearer was
-                 * identified as `auth_id` by the rejected session. The GUI
-                 * must echo this back (not the raw `auth_id`) on the next
+                 * identified as `auth_id` by the rejected session. The GUI must
+                 * echo this back (not the raw `auth_id`) on the next
                  * login/signup so the controller can rebind to the same user.
                  */
                 reauth_token?: string;
@@ -63,7 +78,10 @@ declare global {
                 device: { vendor?: string; model?: string; type?: string };
             };
 
-            /** True when the request's Host is a custom domain (not one of the configured Puter domains). */
+            /**
+             * True when the request's Host is a custom domain (not one of the
+             * configured Puter domains).
+             */
             is_custom_domain?: boolean;
 
             /**
@@ -76,12 +94,15 @@ declare global {
             /**
              * Client-supplied device fingerprint (ThumbmarkJS hash) from the
              * body or `x-puter-device-fingerprint` header, populated by the
-             * global fingerprint middleware. Present only when the client sent a
-             * well-shaped value; spoofable but stable per device across IPs.
+             * global fingerprint middleware. Present only when the client sent
+             * a well-shaped value; spoofable but stable per device across IPs.
              */
             deviceFingerprint?: string;
 
-            /** Parsed cookies, populated by the global `cookie-parser` middleware. */
+            /**
+             * Parsed cookies, populated by the global `cookie-parser`
+             * middleware.
+             */
             cookies?: Record<string, string>;
         }
     }

src/backend/core/http/index.ts

@@ -46,6 +46,16 @@ export {
     subdomainGate,
 } from './middleware/gates';
 export { createNotFoundHandler } from './middleware/notFoundHandler';
+export {
+    createStepUpGate,
+    signStepUpToken,
+    STEP_UP_COOKIE_NAME,
+    STEP_UP_PURPOSE,
+    STEP_UP_SCOPE,
+    STEP_UP_TTL_SECONDS,
+    stepUpCookieOptions,
+    verifyStepUpSession,
+} from './middleware/stepUpSession';
 export { PuterRouter } from './PuterRouter';
 export {
     PREFIX_METADATA_KEY,

src/backend/core/http/middleware/authProbe.test.ts

@@ -262,6 +262,46 @@ describe('createAuthProbe — token extraction precedence', () => {
     });
 });
 
+describe('createAuthProbe — tokenSource', () => {
+    const cases: Array<[string, Parameters<typeof makeReq>[0]]> = [
+        ['body', { body: { auth_token: 'tok' } }],
+        ['header', { headers: { authorization: 'Bearer tok' } }],
+        ['x-api-key', { headers: { 'x-api-key': 'tok' } }],
+        ['cookie', { cookieHeader: 'puter_token=tok' }],
+        ['query', { query: { auth_token: 'tok' } }],
+        ['handshake', { handshakeQuery: { auth_token: 'tok' } }],
+    ];
+
+    const actor: Actor = { user: { uuid: 'u-1' } };
+
+    it.each(cases)('records %s', async (expected, init) => {
+        const stub = makeStubAuth(actor);
+        const probe = createAuthProbe({
+            authService: stub.service,
+            cookieName: 'puter_token',
+        });
+        const { req } = await runProbe(probe, makeReq(init));
+        expect(req.tokenSource).toBe(expected);
+    });
+
+    it('is left unset when no token is presented', async () => {
+        const stub = makeStubAuth(actor);
+        const probe = createAuthProbe({ authService: stub.service });
+        const { req } = await runProbe(probe, makeReq({}));
+        expect(req.tokenSource).toBeUndefined();
+    });
+
+    it('is left unset when the token fails to authenticate', async () => {
+        const stub = makeStubAuth(null);
+        const probe = createAuthProbe({ authService: stub.service });
+        const { req } = await runProbe(
+            probe,
+            makeReq({ headers: { authorization: 'Bearer tok' } }),
+        );
+        expect(req.tokenSource).toBeUndefined();
+    });
+});
+
 describe('createAuthProbe — header parsing', () => {
     it("strips 'Bearer ' (case-insensitive) from the Authorization value", async () => {
         const stub = makeStubAuth();
@@ -545,30 +585,10 @@ describe('createAuthProbe — actor attachment + failure tracking', () => {
     });
 });
 
-// ── Reauth signal + KV counters ─────────────────────────────────────
+// ── Reauth signal ───────────────────────────────────────────────────
 
 describe('createAuthProbe — reauth signal', () => {
-    /** Capture KV increments without a real store. */
-    const makeKvStub = () => {
-        const calls: Array<{
-            key: string;
-            pathAndAmountMap: Record<string, number>;
-        }> = [];
-        return {
-            calls,
-            store: {
-                incr: async (args: {
-                    key: string;
-                    pathAndAmountMap: Record<string, number>;
-                }) => {
-                    calls.push(args);
-                    return { res: {} as Record<string, number>, usage: 0 };
-                },
-            },
-        };
-    };
-
-    it('sets requiresReauth and counts v1 + reauth.token_v1 for a legacy v1 token', async () => {
+    it('sets requiresReauth with a signed token for a legacy v1 token', async () => {
         const stub = makeStubAuth();
         stub.setNextResult({
             reauth: { reason: 'token_v1', auth_id: 'u-legacy' },
@@ -576,11 +596,7 @@ describe('createAuthProbe — reauth signal', () => {
             // The probe must still set requiresReauth; gate emits 401.
             actor: { user: { uuid: 'u-legacy' } },
         } as never);
-        const kv = makeKvStub();
-        const probe = createAuthProbe({
-            authService: stub.service,
-            kvStore: kv.store,
-        });
+        const probe = createAuthProbe({ authService: stub.service });
         const { req } = await runProbe(
             probe,
             makeReq({ headers: { authorization: 'Bearer v1-tok' } }),
@@ -590,109 +606,36 @@ describe('createAuthProbe — reauth signal', () => {
             auth_id: 'u-legacy',
             reauth_token: 'reauth-jwt:u-legacy',
         });
-        // Both increments fire under the same day-bucketed key.
-        expect(kv.calls).toHaveLength(1);
-        expect(kv.calls[0].key).toMatch(/^auth-v2:metrics:\d{4}-\d{2}-\d{2}$/);
-        expect(kv.calls[0].pathAndAmountMap).toEqual({
-            v1: 1,
-            'reauth.token_v1': 1,
-        });
     });
 
-    it('sets requiresReauth and counts reauth.session_revoked', async () => {
+    it('sets requiresReauth for a revoked session', async () => {
         const stub = makeStubAuth();
         stub.setNextResult({
             reauth: { reason: 'session_revoked', auth_id: 'u-1' },
         });
-        const kv = makeKvStub();
-        const probe = createAuthProbe({
-            authService: stub.service,
-            kvStore: kv.store,
-        });
+        const probe = createAuthProbe({ authService: stub.service });
         const { req } = await runProbe(
             probe,
             makeReq({ headers: { authorization: 'Bearer tok' } }),
         );
         expect(req.requiresReauth?.reason).toBe('session_revoked');
-        expect(kv.calls[0].pathAndAmountMap).toEqual({
-            v1: 1,
-            'reauth.session_revoked': 1,
-        });
     });
 
-    it('sets requiresReauth and counts reauth.session_expired', async () => {
+    it('sets requiresReauth for an expired session', async () => {
         const stub = makeStubAuth();
         stub.setNextResult({
             reauth: { reason: 'session_expired', auth_id: 'u-1' },
         });
-        const kv = makeKvStub();
-        const probe = createAuthProbe({
-            authService: stub.service,
-            kvStore: kv.store,
-        });
+        const probe = createAuthProbe({ authService: stub.service });
         const { req } = await runProbe(
             probe,
             makeReq({ headers: { authorization: 'Bearer tok' } }),
         );
         expect(req.requiresReauth?.reason).toBe('session_expired');
-        expect(kv.calls[0].pathAndAmountMap).toEqual({
-            v1: 1,
-            'reauth.session_expired': 1,
-        });
     });
 
-    it('counts v2 verify (no reauth) for a healthy token', async () => {
+    it('attaches an actor and no reauth for a healthy v2 token', async () => {
         const stub = makeStubAuth({ user: { uuid: 'u-1' } });
-        const kv = makeKvStub();
-        const probe = createAuthProbe({
-            authService: stub.service,
-            kvStore: kv.store,
-        });
-        const { req } = await runProbe(
-            probe,
-            makeReq({ headers: { authorization: 'Bearer good-tok' } }),
-        );
-        expect(req.actor).toBeTruthy();
-        expect(req.requiresReauth).toBeUndefined();
-        expect(kv.calls[0].pathAndAmountMap).toEqual({ v2: 1 });
-    });
-
-    it('does not increment counters when no token is presented', async () => {
-        const stub = makeStubAuth();
-        const kv = makeKvStub();
-        const probe = createAuthProbe({
-            authService: stub.service,
-            kvStore: kv.store,
-        });
-        await runProbe(probe, makeReq({}));
-        // Anonymous-OK routes pay no metrics cost.
-        expect(kv.calls).toHaveLength(0);
-    });
-
-    it('absorbs KV failures — never rejects on the hot path', async () => {
-        const stub = makeStubAuth({ user: { uuid: 'u-1' } });
-        // Failing KV: increments throw. Probe must still succeed.
-        const failingKv = {
-            incr: async () => {
-                throw new Error('kv unavailable');
-            },
-        };
-        const probe = createAuthProbe({
-            authService: stub.service,
-            kvStore: failingKv,
-        });
-        const { req, next } = await runProbe(
-            probe,
-            makeReq({ headers: { authorization: 'Bearer good-tok' } }),
-        );
-        expect(next).toHaveBeenCalledWith();
-        expect(req.actor).toBeTruthy();
-    });
-
-    it('works without a kvStore (counters become no-ops)', async () => {
-        const stub = makeStubAuth({ user: { uuid: 'u-1' } });
-        // Production may not always pass a KV — fresh installs without
-        // dynamo wired still need a functioning probe.
         const probe = createAuthProbe({ authService: stub.service });
         const { req } = await runProbe(
             probe,
@@ -702,6 +645,17 @@ describe('createAuthProbe — reauth signal', () => {
         expect(req.requiresReauth).toBeUndefined();
     });
 
+    it('never rejects on the hot path', async () => {
+        const stub = makeStubAuth({ user: { uuid: 'u-1' } });
+        const probe = createAuthProbe({ authService: stub.service });
+        const { req, next } = await runProbe(
+            probe,
+            makeReq({ headers: { authorization: 'Bearer good-tok' } }),
+        );
+        expect(next).toHaveBeenCalledWith();
+        expect(req.actor).toBeTruthy();
+    });
+
     it('logs `[auth-v2] reauth reason=<r> auth_id=<id>` per event', async () => {
         // The log line is the human-facing forensic counterpart to the
         // KV counter. Asserting the exact shape so ops can `grep

src/backend/core/http/middleware/authProbe.ts

@@ -3,18 +3,19 @@
  *
  * 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.
+ * 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.
+ * 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/>.
+ * along with this program. If not, see
+ * [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
  */
 
 import type { Request, RequestHandler } from 'express';
@@ -22,7 +23,7 @@ import type {
     AuthService,
     ReauthReason,
 } from '../../../services/auth/AuthService';
-import type { SystemKVStore } from '../../../stores/systemKv/SystemKVStore';
+import type { TokenSource } from '../types';
 
 // Ensure the `Request.actor` / `Request.token` augmentation is in scope
 // wherever this middleware is imported.
@@ -30,47 +31,34 @@ import '../expressAugmentation';
 
 interface AuthProbeOptions {
     authService: AuthService;
-    /** Name of the session cookie to inspect. Falls back to `config.cookie_name`. */
+    /**
+     * Name of the session cookie to inspect. Falls back to
+     * `config.cookie_name`.
+     */
     cookieName?: string;
-    kvStore?: SystemKVStore;
 }
 
-const authV2MetricsKey = (): string => {
-    const now = new Date();
-    const yyyy = now.getUTCFullYear();
-    const mm = String(now.getUTCMonth() + 1).padStart(2, '0');
-    const dd = String(now.getUTCDate()).padStart(2, '0');
-    return `auth-v2:metrics:${yyyy}-${mm}-${dd}`;
-};
-
-const bumpCounter = (
-    kv: Pick<SystemKVStore, 'incr'> | undefined,
-    pathAndAmountMap: Record<string, number>,
-): void => {
-    if (!kv) return;
-    kv.incr({ key: authV2MetricsKey(), pathAndAmountMap }).catch(() => {});
-};
-
 /**
- * Non-enforcing auth probe. Runs globally (installed by `PuterServer`) on
- * every request, tries to locate a token in the usual places, and — if one
- * is present and valid — attaches an `Actor` to `req.actor`.
+ * Non-enforcing auth probe. Runs globally (installed by `PuterServer`) on every
+ * request, tries to locate a token in the usual places, and — if one is present
+ * and valid — attaches an `Actor` to `req.actor`.
  *
  * Key property: this middleware **never rejects**. Missing tokens, malformed
  * tokens, expired tokens, tokens pointing at deleted users — all result in
- * `req.actor` being left undefined. Per-route gates decide whether absence
- * is acceptable.
+ * `req.actor` being left undefined. Per-route gates decide whether absence is
+ * acceptable.
  *
  * Token lookup order:
- *   1. `req.body.auth_token`
- *   2. `Authorization: Bearer <token>` header
- *   3. `x-api-key` header — third-party SDK convention (Anthropic etc.)
- *   4. Session cookie, only when the browser request is same-origin
- *   5. `?auth_token=...` query param
- *   6. Socket handshake query (for ws upgrades that pass through HTTP first)
+ *
+ * 1. `req.body.auth_token`
+ * 2. `Authorization: Bearer <token>` header
+ * 3. `x-api-key` header — third-party SDK convention (Anthropic etc.)
+ * 4. Session cookie, only when the browser request is same-origin
+ * 5. `?auth_token=...` query param
+ * 6. Socket handshake query (for ws upgrades that pass through HTTP first)
  */
 export const createAuthProbe = (opts: AuthProbeOptions): RequestHandler => {
-    const { authService, cookieName, kvStore } = opts;
+    const { authService, cookieName } = opts;
     return async (req, _res, next): Promise<void> => {
         // If something upstream already attached an actor, respect it.
         if (req.actor) {
@@ -78,11 +66,12 @@ export const createAuthProbe = (opts: AuthProbeOptions): RequestHandler => {
             return;
         }
 
-        const token = extractToken(req, cookieName);
-        if (!token) {
+        const extracted = extractToken(req, cookieName);
+        if (!extracted) {
             next();
             return;
         }
+        const { token, source } = extracted;
 
         try {
             // Thread the request IP and User-Agent into authenticate so
@@ -94,10 +83,6 @@ export const createAuthProbe = (opts: AuthProbeOptions): RequestHandler => {
             });
 
             if (result.reauth) {
-                bumpCounter(kvStore, {
-                    v1: 1,
-                    [`reauth.${result.reauth.reason}`]: 1,
-                });
                 // Bind a short-lived JWT proving the rejected session
                 // identified this auth_id. The GUI echoes this back on
                 // /login or /signup; the raw auth_id is informational
@@ -113,13 +98,19 @@ export const createAuthProbe = (opts: AuthProbeOptions): RequestHandler => {
                 console.info(
                     `[auth-v2] reauth reason=${result.reauth.reason} auth_id=${result.reauth.auth_id ?? '-'}`,
                 );
-            } else if (result.actor) {
-                bumpCounter(kvStore, { v2: 1 });
+            }
+
+            if (result.blocked) {
+                // App is on the origin blocklist: leave `actor` unset so gates
+                // reject. `appBlocked` lets the gate emit a clear 403 instead
+                // of the generic "token failed" 401.
+                req.appBlocked = { reason: result.blocked.reason };
             }
 
             if (result.actor) {
                 req.actor = result.actor;
                 req.token = token;
+                req.tokenSource = source;
             } else if (result.invalid) {
                 req.tokenAuthFailed = true;
             }
@@ -134,12 +125,15 @@ export const createAuthProbe = (opts: AuthProbeOptions): RequestHandler => {
  * Token extraction logic covering the request sources clients use to
  * authenticate.
  */
-const extractToken = (req: Request, cookieName?: string): string | null => {
+const extractToken = (
+    req: Request,
+    cookieName?: string,
+): { token: string; source: TokenSource } | null => {
     // 1. Body (`{ "auth_token": "..." }`)
     const bodyToken = (req.body as { auth_token?: unknown } | undefined)
         ?.auth_token;
     if (typeof bodyToken === 'string' && bodyToken.length > 0) {
-        return stripBearer(bodyToken);
+        return { token: stripBearer(bodyToken), source: 'body' };
     }
 
     // 2. Authorization header. Reject `Basic ...` (not our scheme) and
@@ -155,7 +149,7 @@ const extractToken = (req: Request, cookieName?: string): string | null => {
     ) {
         const stripped = authHeader.replace(/^Bearer\s+/i, '').trim();
         if (stripped.length > 0 && stripped !== 'undefined') {
-            return stripped;
+            return { token: stripped, source: 'header' };
         }
     }
 
@@ -165,7 +159,7 @@ const extractToken = (req: Request, cookieName?: string): string | null => {
     const xApiKey =
         typeof req.header === 'function' ? req.header('x-api-key') : undefined;
     if (typeof xApiKey === 'string' && xApiKey.length > 0) {
-        return stripBearer(xApiKey);
+        return { token: stripBearer(xApiKey), source: 'x-api-key' };
     }
 
     // 4. Cookie (set by login flow for session tokens). Do not let an
@@ -182,12 +176,12 @@ const extractToken = (req: Request, cookieName?: string): string | null => {
         if (cookieName) {
             const cookieToken = req.cookies?.[cookieName];
             if (typeof cookieToken === 'string' && cookieToken.length > 0) {
-                return stripBearer(cookieToken);
+                return { token: stripBearer(cookieToken), source: 'cookie' };
             }
         }
         const v2Token = req.cookies?.puter_token_v2;
         if (typeof v2Token === 'string' && v2Token.length > 0) {
-            return stripBearer(v2Token);
+            return { token: stripBearer(v2Token), source: 'cookie' };
         }
     }
 
@@ -195,7 +189,7 @@ const extractToken = (req: Request, cookieName?: string): string | null => {
     const queryToken = (req.query as { auth_token?: unknown } | undefined)
         ?.auth_token;
     if (typeof queryToken === 'string' && queryToken.length > 0) {
-        return stripBearer(queryToken);
+        return { token: stripBearer(queryToken), source: 'query' };
     }
 
     // 6. Socket handshake (for websocket upgrades that pass through HTTP).
@@ -204,7 +198,7 @@ const extractToken = (req: Request, cookieName?: string): string | null => {
     ).handshake;
     const handshakeToken = handshake?.query?.auth_token;
     if (typeof handshakeToken === 'string' && handshakeToken.length > 0) {
-        return stripBearer(handshakeToken);
+        return { token: stripBearer(handshakeToken), source: 'handshake' };
     }
 
     return null;

src/backend/core/http/middleware/errorHandler.test.ts

@@ -232,3 +232,50 @@ describe('createErrorHandler — when the response has already started streaming
         expect(onError).toHaveBeenCalledTimes(1);
     });
 });
+
+// ── Database load-shed translation ──────────────────────────────────
+
+describe('createErrorHandler — dbBatchFailed load-shed errors', () => {
+    const makeDbBatchError = (reason: string) => {
+        const err = new Error('Database operation failed') as Error & {
+            code: string;
+            reason: string;
+        };
+        err.code = 'dbBatchFailed';
+        err.reason = reason;
+        return err;
+    };
+
+    it('maps to 503 + Retry-After instead of a generic 500', () => {
+        const onUnhandled = vi.fn();
+        const handler = createErrorHandler({ onUnhandled });
+        const { out } = runHandler(handler, makeDbBatchError('breakerOpen'));
+
+        expect(out.statusCode).toBe(503);
+        expect(out.headers['Retry-After']).toBe(5);
+        expect(out.body).toMatchObject({
+            code: 'db_unavailable',
+            error: 'Service temporarily unavailable',
+        });
+        // Translated errors are expected degradation, not unhandled bugs.
+        expect(onUnhandled).not.toHaveBeenCalled();
+    });
+
+    it('translates every load-shed reason the batcher emits', () => {
+        const handler = createErrorHandler({ onUnhandled: () => {} });
+        for (const reason of ['breakerOpen', 'queueOverflow', 'connAcquire']) {
+            const { out } = runHandler(handler, makeDbBatchError(reason));
+            expect(out.statusCode).toBe(503);
+        }
+    });
+
+    it('leaves unrelated coded errors on the generic 500 path', () => {
+        const onUnhandled = vi.fn();
+        const handler = createErrorHandler({ onUnhandled });
+        const err = new Error('boom') as Error & { code: string };
+        err.code = 'somethingElse';
+        const { out } = runHandler(handler, err);
+        expect(out.statusCode).toBe(500);
+        expect(onUnhandled).toHaveBeenCalledTimes(1);
+    });
+});

src/backend/core/http/middleware/errorHandler.ts

@@ -85,6 +85,17 @@ export const createErrorHandler = (
             err = translated;
         }
 
+        // Database-batcher load-shed (circuit open, queue overflow, or no
+        // connection available): the persistence layer is temporarily
+        // degraded, not a programming bug. Surface as 503 so clients back
+        // off and retry instead of treating it as a hard failure.
+        if ((err as { code?: string } | null)?.code === 'dbBatchFailed') {
+            res.setHeader('Retry-After', 5);
+            err = new HttpError(503, 'Service temporarily unavailable', {
+                code: 'db_unavailable',
+            });
+        }
+
         if (isHttpError(err)) {
             opts.onError?.(err, req);
             if (err.statusCode === 402 || err.statusCode === 413) {

src/backend/core/http/middleware/fingerprint.ts

@@ -55,13 +55,15 @@ function readDeviceFingerprint(req: {
  * Stamp request-scoped fingerprints onto `req` so any downstream gate, handler,
  * or service (via the ALS `Context.get('req')`) can read them without recomputing:
  *
- *   - `req.networkFingerprint` — always set; a coarse IP+headers hash (the same
- *     value the rate limiter keys on). Server-derived, so it can't be forged
- *     away, but it's coarse (shared behind NAT/VPN, rotates with UA).
+ *   - `req.networkFingerprint` — always set; a coarse IP+headers hash (the
+ *     anchor of the rate limiter's default key). Server-derived, so it can't be
+ *     forged away, but it's coarse (shared behind NAT/VPN, rotates with UA).
  *   - `req.deviceFingerprint` — set only when the client supplied a well-shaped
  *     device fingerprint (ThumbmarkJS hash) in the body or the
  *     `x-puter-device-fingerprint` header; `undefined` otherwise. Client-supplied
- *     and spoofable, but stable per real device across IP rotation.
+ *     and spoofable, but stable per real device across IP rotation. The rate
+ *     limiter's 'fingerprint' strategy appends it to the network hash so each
+ *     device behind a shared network gets its own bucket.
  *
  * Install AFTER the body parsers (so the body fingerprint is readable) and
  * before `requestContext` (so the snapshot into ALS already carries them).

src/backend/core/http/middleware/gates.test.ts

@@ -24,6 +24,8 @@ import {
     DEFAULT_ADMIN_USERNAMES,
     adminOnlyGate,
     allowedAppIdsGate,
+    assertNotUserSession,
+    noUserSessionGate,
     requireAuthGate,
     requireVerifiedAccount,
     requireNonAccessTokenGate,
@@ -331,6 +333,103 @@ describe('requireNonAccessTokenGate', () => {
     });
 });
 
+// ── noUserSessionGate ───────────────────────────────────────────────
+
+describe('noUserSessionGate', () => {
+    it('rejects a bare user-session ("root" token) actor with 403', () => {
+        const got = runGate(noUserSessionGate(), {
+            actor: { user: { uuid: 'u-1' } },
+        });
+        expectHttpError(got, 403, 'app_or_api_token_required');
+    });
+
+    it('passes through for app-under-user actors (app/worker tokens)', () => {
+        const got = runGate(noUserSessionGate(), {
+            actor: { user: { uuid: 'u-1' }, app: { uid: 'app-1' } },
+        });
+        expect(got).toBeUndefined();
+    });
+
+    it('passes through for user-scoped worker sessions (kind="worker")', () => {
+        const got = runGate(noUserSessionGate(), {
+            actor: {
+                user: { uuid: 'u-1' },
+                session: { uid: 'sess-1', kind: 'worker' },
+            },
+        });
+        expect(got).toBeUndefined();
+    });
+
+    it('passes through for access-token actors (which access tokens are OK is decided by the other gates)', () => {
+        const got = runGate(noUserSessionGate(), {
+            actor: {
+                user: { uuid: 'u-1' },
+                accessToken: {
+                    uid: 'tok-1',
+                    issuer: { user: { uuid: 'u-1' } },
+                    fullAccess: true,
+                },
+            },
+        });
+        expect(got).toBeUndefined();
+    });
+
+    it("falls back to 401 if there's no actor at all (defensive)", () => {
+        const got = runGate(noUserSessionGate(), {});
+        expectHttpError(got, 401, 'token_missing');
+    });
+});
+
+describe('assertNotUserSession', () => {
+    it('is a no-op for a missing actor (anonymous is the auth gate’s job)', () => {
+        expect(() => assertNotUserSession(undefined)).not.toThrow();
+        expect(() => assertNotUserSession(null)).not.toThrow();
+    });
+
+    it('always admits a user-scoped worker session — workers are never root tokens', () => {
+        // Workers deployed with no app binding hold a session-TYPE token
+        // whose row is kind='worker' (see AuthService.createWorkerSessionToken)
+        // — a bare user actor plus that session ref. The gate is an
+        // annoyance for sign-up-and-scrape abuse; a deployed worker is
+        // already a delegated, revocable credential.
+        expect(() =>
+            assertNotUserSession({
+                app: null,
+                accessToken: null,
+                session: { uid: 'sess-1', kind: 'worker' },
+            }),
+        ).not.toThrow();
+    });
+
+    it('still rejects web sessions', () => {
+        expect(() =>
+            assertNotUserSession({
+                app: null,
+                accessToken: null,
+                session: { uid: 'sess-1', kind: 'web' },
+            }),
+        ).toThrow();
+    });
+
+    it('throws 403 app_or_api_token_required for a bare session actor', () => {
+        try {
+            assertNotUserSession({ app: null, accessToken: null });
+            expect.unreachable('expected assertNotUserSession to throw');
+        } catch (err) {
+            expect(isHttpError(err)).toBe(true);
+            expect((err as HttpError).statusCode).toBe(403);
+            expect((err as HttpError).legacyCode).toBe(
+                'app_or_api_token_required',
+            );
+            // The user asked for a helpful message: it must point at the
+            // credentials that DO work and where to get one.
+            expect((err as HttpError).message).toMatch(/app or worker token/i);
+            expect((err as HttpError).message).toMatch(/API token/);
+            expect((err as HttpError).message).toMatch(/dashboard/i);
+        }
+    });
+});
+
 // ── adminOnlyGate ───────────────────────────────────────────────────
 
 describe('adminOnlyGate', () => {
@@ -407,6 +506,113 @@ describe('adminOnlyGate', () => {
             }),
         ).toBeUndefined();
     });
+
+    // -- Root-token requirement --
+    //
+    // Admin endpoints require a root token (an actor with no app anywhere
+    // in its token chain), so a third-party app an admin authorized can't
+    // reach them on the admin's behalf.
+
+    it('admits an admin acting via a session (root token)', () => {
+        const got = runGate(adminOnlyGate(), {
+            actor: { user: { uuid: 'u-1', username: 'admin' } },
+        });
+        expect(got).toBeUndefined();
+    });
+
+    it("admits an admin's full-access PAT (still a root token — no app)", () => {
+        const got = runGate(adminOnlyGate(), {
+            actor: {
+                user: { uuid: 'u-1', username: 'admin' },
+                accessToken: {
+                    uid: 'tok-1',
+                    issuer: { user: { uuid: 'u-1', username: 'admin' } },
+                    fullAccess: true,
+                },
+            },
+        });
+        expect(got).toBeUndefined();
+    });
+
+    it('rejects an admin acting through an app with 403 (not a root token)', () => {
+        const got = runGate(adminOnlyGate(), {
+            actor: {
+                user: { uuid: 'u-1', username: 'admin' },
+                app: { uid: 'app-1' },
+            },
+        });
+        expectHttpError(got, 403, 'forbidden');
+    });
+
+    it('rejects an admin access token issued through an app (app in the token chain)', () => {
+        // Access-token actors carry their app on `accessToken.issuer.app`,
+        // not top-level `actor.app` — the root-token check must walk the
+        // chain, not just the top level.
+        const got = runGate(adminOnlyGate(), {
+            actor: {
+                user: { uuid: 'u-1', username: 'admin' },
+                accessToken: {
+                    uid: 'tok-1',
+                    issuer: {
+                        user: { uuid: 'u-1', username: 'admin' },
+                        app: { uid: 'app-1' },
+                    },
+                },
+            },
+        });
+        expectHttpError(got, 403, 'forbidden');
+    });
+
+    it('rejects an app-issued access token even when appGated', () => {
+        // The appGated deferral only applies to direct app-under-user
+        // actors: `allowedAppIdsGate` reads top-level `actor.app` and would
+        // pass a chain-only app straight through, so it must not be
+        // deferred to.
+        const got = runGate(adminOnlyGate([], { appGated: true }), {
+            actor: {
+                user: { uuid: 'u-1', username: 'admin' },
+                accessToken: {
+                    uid: 'tok-1',
+                    issuer: {
+                        user: { uuid: 'u-1', username: 'admin' },
+                        app: { uid: 'app-1' },
+                    },
+                },
+            },
+        });
+        expectHttpError(got, 403, 'forbidden');
+    });
+
+    it('admits an admin acting through an app when appGated (allowedAppIdsGate then decides)', () => {
+        // On an appId-gated route the root-token check is deferred to
+        // `allowedAppIdsGate`; this gate must let the app actor through.
+        const got = runGate(adminOnlyGate([], { appGated: true }), {
+            actor: {
+                user: { uuid: 'u-1', username: 'admin' },
+                app: { uid: 'app-1' },
+            },
+        });
+        expect(got).toBeUndefined();
+    });
+
+    it('still admits a root token when appGated', () => {
+        const got = runGate(adminOnlyGate([], { appGated: true }), {
+            actor: { user: { uuid: 'u-1', username: 'admin' } },
+        });
+        expect(got).toBeUndefined();
+    });
+
+    it('applies the username check before the root-token check', () => {
+        // A non-admin acting through an app is rejected for being non-admin,
+        // regardless of the app scope.
+        const got = runGate(adminOnlyGate(), {
+            actor: {
+                user: { uuid: 'u-1', username: 'random-user' },
+                app: { uid: 'app-1' },
+            },
+        });
+        expectHttpError(got, 403, 'forbidden');
+    });
 });
 
 // ── requireVerifiedGate ─────────────────────────────────────────────

src/backend/core/http/middleware/gates.ts

@@ -18,6 +18,8 @@
  */
 
 import type { Request, RequestHandler } from 'express';
+import { effectiveActorApp } from '../../actor';
+import type { Actor } from '../../actor';
 import { HttpError } from '../HttpError';
 import { assertVerifiedEmail } from '../verifiedEmail';
 
@@ -79,16 +81,24 @@ export const subdomainGate = (allowed: string | string[]): RequestHandler => {
  */
 export const requireAuthGate = (): RequestHandler => {
     return (req, _res, next) => {
+        if (req.appBlocked) {
+            next(
+                new HttpError(
+                    403,
+                    'This app is not allowed to access Puter resources',
+                    { legacyCode: 'app_blocked' },
+                ),
+            );
+            return;
+        }
         if (!req.actor) {
             next(rejectAuth(req));
             return;
         }
-        if (req.actor.user.suspended) {
-            next(
-                new HttpError(403, 'Account suspended', {
-                    legacyCode: 'forbidden',
-                }),
-            );
+        try {
+            assertNotSuspended(req.actor.user);
+        } catch (err) {
+            next(err);
             return;
         }
         next();
@@ -139,6 +149,59 @@ export const requireUserActorGate = (
     };
 };
 
+/**
+ * Reject bare user-session actors — the "root" credential a browser session
+ * (or `/login`) holds, with no app and no access token in play. Use on API
+ * surfaces that must only be driven by a delegated credential: an app or
+ * worker token, or an API token minted from the dashboard. The point is that
+ * a leaked-or-copied session token (full account control) shouldn't double
+ * as an AI/API credential; users are pushed to mint a revocable token
+ * instead.
+ *
+ * This gate only rejects the bare-session shape. Which delegated credentials
+ * are acceptable is decided by the gates it composes with (`requireUserActor`
+ * + `allowFullAccessToken` to also keep apps out, `requireNonAccessTokenGate`
+ * for scoped tokens, etc.).
+ */
+export const assertNotUserSession = (
+    actor: Pick<Actor, 'app' | 'accessToken' | 'session'> | null | undefined,
+): void => {
+    if (!actor) return; // anonymous requests are the auth gate's problem
+    if (actor.app || actor.accessToken) return;
+    // User-scoped workers (deployed with no app binding) authenticate with
+    // a session-TYPE token whose session row is `kind='worker'` — a managed,
+    // revocable deployment credential, not a browser sign-in. Workers are
+    // never treated as root tokens: this gate is an annoyance for
+    // sign-up-and-scrape abuse, and someone who deploys a worker to reach
+    // an API has already left that path.
+    if (actor.session?.kind === 'worker') return;
+    throw new HttpError(
+        403,
+        'This API cannot be called with an account session token. ' +
+            'Use an app or worker token, or create an API token from the ' +
+            'dashboard (Account → API Token).',
+        { legacyCode: 'app_or_api_token_required' },
+    );
+};
+
+/** Route-option form of {@link assertNotUserSession} (`noUserSession: true`). */
+export const noUserSessionGate = (): RequestHandler => {
+    return (req, _res, next) => {
+        const actor = req.actor;
+        if (!actor) {
+            next(rejectAuth(req));
+            return;
+        }
+        try {
+            assertNotUserSession(actor);
+        } catch (err) {
+            next(err);
+            return;
+        }
+        next();
+    };
+};
+
 export const requireNonAccessTokenGate = (): RequestHandler => {
     return (req, _res, next) => {
         const actor = req.actor;
@@ -174,13 +237,24 @@ export const DEFAULT_ADMIN_USERNAMES = ['admin', 'system'] as const;
  * the supplied extras. Extras are *additional* allowed users on top of the
  * built-in pair, not a replacement for it.
  *
- * Implies `requireAuth`. Does *not* imply `requireUserActor` — admin
- * endpoints are callable via an admin's access token or app-under-user
- * actor; combine with `requireUserActor` explicitly if a route must be
- * restricted to browser sessions.
+ * Also requires a *root token* — an actor with no app anywhere in its token
+ * chain (see `effectiveActorApp`) — so a third-party app an admin has
+ * authorized can't reach admin endpoints on the admin's behalf. The one
+ * exception is `appGated`: on a route that is also appId-gated
+ * (`allowedAppIds`), a direct app-under-user actor is deferred to
+ * `allowedAppIdsGate`, so the net effect there is "a root token OR a token
+ * scoped to an allowed app". Access tokens issued through an app are
+ * rejected even then — `allowedAppIdsGate` only sees top-level `actor.app`
+ * and would otherwise wave them through.
+ *
+ * Implies `requireAuth`. Does *not* imply `requireUserActor` — a root token
+ * still includes an admin's full-access personal access token, not only
+ * browser sessions; combine with `requireUserActor` explicitly if a route
+ * must be restricted to browser sessions.
  */
 export const adminOnlyGate = (
     extras: readonly string[] = [],
+    opts: { appGated?: boolean } = {},
 ): RequestHandler => {
     // Match the case-insensitivity guarantee of the username column
     // (MySQL: ascii_general_ci; SQLite: idx_user_username_nocase). Comparing
@@ -199,6 +273,20 @@ export const adminOnlyGate = (
             );
             return;
         }
+        // Root-token requirement: reject actors carrying an app anywhere in
+        // their token chain — app-under-user, or an access token issued
+        // through an app. A direct app-under-user actor is deferred to
+        // `allowedAppIdsGate` when the route is appId-gated; chain-only apps
+        // are rejected even then, since that gate can't see them.
+        const chainApp = req.actor ? effectiveActorApp(req.actor) : null;
+        if (chainApp && !(opts.appGated && req.actor?.app?.uid)) {
+            next(
+                new HttpError(403, 'Only admins may request this resource', {
+                    legacyCode: 'forbidden',
+                }),
+            );
+            return;
+        }
         next();
     };
 };
@@ -302,6 +390,16 @@ export const assertVerifiedAccount = (
     }
 };
 
+export const assertNotSuspended = (
+    user: { suspended?: unknown } | undefined,
+): void => {
+    if (user?.suspended) {
+        throw new HttpError(403, 'Account suspended', {
+            legacyCode: 'forbidden',
+        });
+    }
+};
+
 /**
  * Reject unless the actor is acting through one of the named apps.
  * App-under-user actors are permitted iff `actor.app.uid` is in the allowList;

src/backend/core/http/middleware/localWorkerProxy.ts

@@ -0,0 +1,150 @@
+/**
+ * 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 { RequestHandler } from 'express';
+import { Readable } from 'node:stream';
+import type { puterClients } from '../../../clients';
+import type { puterServices } from '../../../services';
+import type { puterStores } from '../../../stores';
+import type { IConfig, LayerInstances } from '../../../types';
+
+interface Layers {
+    clients: LayerInstances<typeof puterClients>;
+    stores: LayerInstances<typeof puterStores>;
+    services: LayerInstances<typeof puterServices>;
+}
+
+// Local analogue of the production `<name>.puter.work` worker domain. Requests
+// to `<name>.workers.puter.localhost` are dispatched into a Miniflare instance
+// by `LocalWorkerService`, which mirrors the real Cloudflare dispatch path.
+const WORKER_HOST_SUFFIX = 'workers.puter.localhost';
+
+// Minimal WHATWG-Response shape we consume from Miniflare's `dispatchFetch`.
+// It isn't the Node global `Response`, so we type it structurally rather than
+// importing Miniflare's classes into the HTTP layer.
+interface FetchResponse {
+    status: number;
+    headers: { forEach(cb: (value: string, key: string) => void): void };
+    body: ReadableStream<Uint8Array> | null;
+}
+
+function normalizeHost(value: string | undefined | null): string | null {
+    if (typeof value !== 'string') return null;
+    const trimmed = value.trim().toLowerCase().replace(/^\./, '');
+    if (!trimmed) return null;
+    return trimmed.split(':')[0] || null;
+}
+
+// `<name>.workers.puter.localhost` → `name`. Returns null for the bare zone or
+// any host outside it. Flip this if your dev DNS puts the name elsewhere.
+function workerNameFromHost(host: string): string | null {
+    if (host === WORKER_HOST_SUFFIX) return null;
+    if (!host.endsWith(`.${WORKER_HOST_SUFFIX}`)) return null;
+    const prefix = host.slice(0, host.length - WORKER_HOST_SUFFIX.length - 1);
+    return prefix.split('.')[0] || null;
+}
+
+// Express (Node) request → WHATWG Request the Worker's `fetch(request)` sees.
+// Must run BEFORE any body-parsing middleware so `req` is still an unconsumed
+// stream; otherwise the Worker gets an empty body on POST/PUT.
+function toFetchRequest(req: Parameters<RequestHandler>[0]): Request {
+    const url = `http://${req.headers.host ?? WORKER_HOST_SUFFIX}${req.originalUrl}`;
+
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (Array.isArray(value)) {
+            for (const v of value) headers.append(key, v);
+        } else if (value != null) {
+            headers.set(key, value);
+        }
+    }
+
+    const method = (req.method ?? 'GET').toUpperCase();
+    const hasBody = method !== 'GET' && method !== 'HEAD';
+
+    return new Request(url, {
+        method,
+        headers,
+        // `duplex: 'half'` is required by undici whenever a stream body is set.
+        body: hasBody ? (Readable.toWeb(req) as ReadableStream) : undefined,
+        ...(hasBody ? { duplex: 'half' } : {}),
+    } as RequestInit);
+}
+
+// WHATWG Response from the Worker → Express response.
+function sendFetchResponse(
+    res: Parameters<RequestHandler>[1],
+    response: FetchResponse,
+): void {
+    res.status(response.status);
+    response.headers.forEach((value, key) => {
+        // Node manages framing headers itself; forwarding them corrupts the
+        // response (double content-length, stale transfer-encoding).
+        const lower = key.toLowerCase();
+        if (lower === 'content-length' || lower === 'transfer-encoding') return;
+        res.setHeader(key, value);
+    });
+
+    if (!response.body) {
+        res.end();
+        return;
+    }
+
+    const nodeStream = Readable.fromWeb(response.body as never);
+    nodeStream.on('error', () => res.destroy());
+    nodeStream.pipe(res);
+}
+
+/**
+ * Serves local Workers on `*.workers.puter.localhost` by dispatching into
+ * Miniflare via `LocalWorkerService`. No-op unless `config.workers.localServer`
+ * is set — production keeps hitting real Cloudflare through `WorkerDriver`.
+ *
+ * Mount this BEFORE the body-parsing middleware in `server.ts` so the Worker
+ * receives the raw request stream.
+ */
+export const createLocalWorkerProxyMiddleware = (
+    config: IConfig,
+    layers: Layers,
+): RequestHandler => {
+    if (!config.workers?.localServer) {
+        return (_req, _res, next) => next();
+    }
+
+    const localWorkerService = layers.services.localworkerservice;
+
+    return async (req, res, next) => {
+        const host = normalizeHost(req.hostname);
+        if (!host) return next();
+
+        const workerName = workerNameFromHost(host);
+        if (!workerName) return next();
+
+        try {
+            const fetchRequest = toFetchRequest(req);
+            const response = (await localWorkerService.cfCallLocal(
+                workerName,
+                fetchRequest,
+            )) as unknown as FetchResponse;
+            sendFetchResponse(res, response);
+        } catch (err) {
+            next(err);
+        }
+    };
+};

src/backend/core/http/middleware/notFoundHandler.test.ts

@@ -22,25 +22,102 @@ import { describe, expect, it, vi } from 'vitest';
 import { isHttpError } from '../HttpError';
 import { createNotFoundHandler } from './notFoundHandler';
 
+const makeReq = (over: Partial<Request> = {}): Request =>
+    ({
+        method: 'GET',
+        hostname: 'puter.example',
+        path: '/no-such-page',
+        ...over,
+    }) as Request;
+
+const makeRes = () => ({
+    status: vi.fn(),
+    json: vi.fn(),
+    redirect: vi.fn(),
+});
+
+const expect404 = (next: ReturnType<typeof vi.fn>) => {
+    expect(next).toHaveBeenCalledTimes(1);
+    const err = next.mock.calls[0][0];
+    expect(isHttpError(err)).toBe(true);
+    expect(err.statusCode).toBe(404);
+    expect(err.legacyCode).toBe('not_found');
+};
+
 describe('createNotFoundHandler', () => {
     it("forwards an HttpError(404, 'not_found') to next() — does not write the response itself", () => {
         // The handler must NOT call res.json/status — that's the error
         // handler's job, so every failure goes through the same serializer.
         const handler = createNotFoundHandler();
         const next = vi.fn();
-        const res = {
-            status: vi.fn(),
-            json: vi.fn(),
-        } as unknown as Response;
-        handler({} as Request, res, next);
+        const res = makeRes();
+        handler(makeReq(), res as unknown as Response, next);
 
-        expect(next).toHaveBeenCalledTimes(1);
-        const err = next.mock.calls[0][0];
-        expect(isHttpError(err)).toBe(true);
-        expect(err.statusCode).toBe(404);
-        expect(err.legacyCode).toBe('not_found');
+        expect404(next);
         // Never wrote a response directly.
-        expect((res.status as ReturnType<typeof vi.fn>)).not.toHaveBeenCalled();
-        expect((res.json as ReturnType<typeof vi.fn>)).not.toHaveBeenCalled();
+        expect(res.status).not.toHaveBeenCalled();
+        expect(res.json).not.toHaveBeenCalled();
+        expect(res.redirect).not.toHaveBeenCalled();
+    });
+
+    describe('with guiDomain set', () => {
+        const handler = createNotFoundHandler({ guiDomain: 'puter.example' });
+
+        it('redirects an unmatched GET on the GUI domain to /', () => {
+            const next = vi.fn();
+            const res = makeRes();
+            handler(makeReq(), res as unknown as Response, next);
+
+            expect(res.redirect).toHaveBeenCalledWith('/');
+            expect(next).not.toHaveBeenCalled();
+        });
+
+        it('redirects HEAD like GET', () => {
+            const next = vi.fn();
+            const res = makeRes();
+            handler(
+                makeReq({ method: 'HEAD' }),
+                res as unknown as Response,
+                next,
+            );
+
+            expect(res.redirect).toHaveBeenCalledWith('/');
+            expect(next).not.toHaveBeenCalled();
+        });
+
+        it('still 404s non-GET methods on the GUI domain', () => {
+            const next = vi.fn();
+            const res = makeRes();
+            handler(
+                makeReq({ method: 'POST' }),
+                res as unknown as Response,
+                next,
+            );
+
+            expect404(next);
+            expect(res.redirect).not.toHaveBeenCalled();
+        });
+
+        it('still 404s on subdomains (api., etc.)', () => {
+            const next = vi.fn();
+            const res = makeRes();
+            handler(
+                makeReq({ hostname: 'api.puter.example' }),
+                res as unknown as Response,
+                next,
+            );
+
+            expect404(next);
+            expect(res.redirect).not.toHaveBeenCalled();
+        });
+
+        it('never redirects / to itself', () => {
+            const next = vi.fn();
+            const res = makeRes();
+            handler(makeReq({ path: '/' }), res as unknown as Response, next);
+
+            expect404(next);
+            expect(res.redirect).not.toHaveBeenCalled();
+        });
     });
 });

src/backend/core/http/middleware/notFoundHandler.ts

@@ -20,6 +20,16 @@
 import type { RequestHandler } from 'express';
 import { HttpError } from '../HttpError';
 
+export interface NotFoundHandlerOptions {
+    /**
+     * The bare GUI domain (`config.domain`). When set, unmatched GET/HEAD
+     * requests whose host is exactly this domain redirect to `/` instead of
+     * 404ing, so a typo'd or stale URL lands back on the desktop. Subdomains
+     * (api., etc.) and custom domains are unaffected and still 404.
+     */
+    guiDomain?: string;
+}
+
 /**
  * Catch-all 404 middleware. Install last (just before the error handler);
  * any request that didn't match a route lands here.
@@ -28,8 +38,22 @@ import { HttpError } from '../HttpError';
  * the same error-handler pipeline serializes the body — keeps the wire shape
  * consistent with every other failure (`{ error: '...', code: 'not_found' }`).
  */
-export const createNotFoundHandler = (): RequestHandler => {
-    return (_req, _res, next): void => {
+export const createNotFoundHandler = (
+    opts: NotFoundHandlerOptions = {},
+): RequestHandler => {
+    const guiDomain = opts.guiDomain?.trim().toLowerCase() || null;
+    return (req, res, next): void => {
+        if (
+            guiDomain &&
+            (req.method === 'GET' || req.method === 'HEAD') &&
+            req.hostname?.toLowerCase() === guiDomain &&
+            // '/' always matches the shell route; the guard just makes a
+            // misconfigured deployment 404 instead of redirect-looping.
+            req.path !== '/'
+        ) {
+            res.redirect('/');
+            return;
+        }
         next(new HttpError(404, 'Not Found', { legacyCode: 'not_found' }));
     };
 };

src/backend/core/http/middleware/privateAppGate.test.ts

@@ -331,6 +331,27 @@ describe('buildPrivateHostRedirect', () => {
         expect(url).toBe('http://beans.app.puter.localhost:4100/');
     });
 
+    it('collapses a scheme-relative path so it cannot escape the host (open redirect)', () => {
+        for (const evil of [
+            '//evil.com/',
+            '///evil.com/',
+            '/\\evil.com/',
+            '/\\/evil.com/',
+        ]) {
+            const url = buildPrivateHostRedirect(
+                reqOf({
+                    hostname: 'beans.site.puter.localhost',
+                    originalUrl: evil,
+                }),
+                { name: 'beans' },
+                cfg,
+            );
+            expect(url).toBe(
+                'http://beans.app.puter.localhost:4100/evil.com/',
+            );
+        }
+    });
+
     it('returns null when no private hosting domain is configured', () => {
         const noPrivate = {
             ...cfg,
@@ -400,6 +421,26 @@ describe('buildPublicHostRedirect', () => {
         expect(url).toBe('http://beans.site.puter.localhost:4100/');
     });
 
+    it('collapses a scheme-relative path so it cannot escape the host (open redirect)', () => {
+        for (const evil of [
+            '//evil.com/',
+            '///evil.com/',
+            '/\\evil.com/',
+            '/\\/evil.com/',
+        ]) {
+            const url = buildPublicHostRedirect(
+                reqOf({
+                    hostname: 'beans.app.puter.localhost',
+                    originalUrl: evil,
+                }),
+                cfg,
+            );
+            expect(url).toBe(
+                'http://beans.site.puter.localhost:4100/evil.com/',
+            );
+        }
+    });
+
     it('returns null when no public hosting domain is configured', () => {
         const noPublic = {
             ...cfg,

src/backend/core/http/middleware/privateAppGate.ts

@@ -584,6 +584,17 @@ export async function resolvePublicHostedIdentity(opts: {
 
 // -- Redirect helpers ------------------------------------------------
 
+/**
+ * Turn a request path into a safe reference for `new URL(path, base)`.
+ * Collapses any run of leading slashes/backslashes into a single `/` so a
+ * scheme-relative path (`//evil.com`, `/\evil.com`, which the URL parser
+ * folds to `//`) can't override the base authority and turn the redirect
+ * into an open redirect. Guarantees exactly one leading slash.
+ */
+function normalizeRedirectPath(originalUrl: string | undefined): string {
+    return '/' + (originalUrl || '/').replace(/^[/\\]+/, '');
+}
+
 /** Build the URL to redirect a private-app request to its private host. */
 export function buildPrivateHostRedirect(
     req: Request,
@@ -605,9 +616,7 @@ export function buildPrivateHostRedirect(
     try {
         const protocol = config.protocol || req.protocol || 'https';
         const base = `${protocol}://${subdomain}.${privateDomain}`;
-        const reqPath = (req.originalUrl || '/').startsWith('/')
-            ? req.originalUrl || '/'
-            : `/${req.originalUrl}`;
+        const reqPath = normalizeRedirectPath(req.originalUrl);
         return new URL(reqPath, base).toString();
     } catch {
         return null;
@@ -638,9 +647,7 @@ export function buildPublicHostRedirect(
     try {
         const protocol = config.protocol || req.protocol || 'https';
         const base = `${protocol}://${subdomain}.${publicDomain}`;
-        const reqPath = (req.originalUrl || '/').startsWith('/')
-            ? req.originalUrl || '/'
-            : `/${req.originalUrl}`;
+        const reqPath = normalizeRedirectPath(req.originalUrl);
         return new URL(reqPath, base).toString();
     } catch {
         return null;

src/backend/core/http/middleware/rateLimit.js

@@ -18,6 +18,7 @@
  */
 
 import crypto from 'node:crypto';
+import { withSpan } from '../../../util/span.js';
 import { HttpError } from '../HttpError.js';
 
 /**
@@ -256,8 +257,32 @@ async function acquireKvConcurrent(kv, key, limit) {
 // limiting — so route / driver code never has to reason about which
 // backend is wired for which mode.
 
+/**
+ * Wrap a backend pair so every rate / acquire call runs inside a span
+ * tagged with the backend name. Applied at registration, so all gates
+ * (route middleware, driver helpers, imperative checks) are covered.
+ */
+function instrumentBackendPair(name, pair) {
+    const attrs = { 'rate_limit.backend': name };
+    return {
+        rate: (key, limit, windowMs) =>
+            withSpan('rate_limit.check', attrs, () =>
+                pair.rate(key, limit, windowMs),
+            ),
+        acquire: (key, limit) =>
+            withSpan('rate_limit.acquire', attrs, () =>
+                pair.acquire(key, limit),
+            ),
+    };
+}
+
+const memoryBackendPair = instrumentBackendPair('memory', {
+    rate: checkMemory,
+    acquire: acquireMemoryConcurrent,
+});
+
 const backends = {
-    memory: { rate: checkMemory, acquire: acquireMemoryConcurrent },
+    memory: memoryBackendPair,
 };
 let defaultBackendName = 'memory';
 
@@ -295,19 +320,19 @@ export function configureRateLimit({
 } = {}) {
     // Reset (test reconfigure clears stale wiring).
     for (const name of Object.keys(backends)) delete backends[name];
-    backends.memory = { rate: checkMemory, acquire: acquireMemoryConcurrent };
+    backends.memory = memoryBackendPair;
     if (redis) {
-        backends.redis = {
+        backends.redis = instrumentBackendPair('redis', {
             rate: (key, limit, windowMs) =>
                 checkRedis(redis, key, limit, windowMs),
             acquire: (key, limit) => acquireRedisConcurrent(redis, key, limit),
-        };
+        });
     }
     if (kv) {
-        backends.kv = {
+        backends.kv = instrumentBackendPair('kv', {
             rate: (key, limit, windowMs) => checkKv(kv, key, limit, windowMs),
             acquire: (key, limit) => acquireKvConcurrent(kv, key, limit),
-        };
+        });
     }
 
     meteringService = metering ?? null;
@@ -351,9 +376,10 @@ function resolveBackend(name) {
  * Build a rate-limit key from the request.
  *
  * Strategies:
- *   'fingerprint' — IP + User-Agent hash (default). Good for
- *                    unauthenticated endpoints where the same IP may
- *                    serve many users (offices, VPNs).
+ *   'fingerprint' — network hash (IP + headers), refined by the client's
+ *                    device fingerprint when one was supplied (default).
+ *                    Good for unauthenticated endpoints where the same
+ *                    IP may serve many users (offices, VPNs).
  *   'ip'          — bare IP. Simpler but coarser.
  *   'user'        — actor UUID. Use for authenticated endpoints where
  *                    you want per-account limits regardless of IP.
@@ -395,7 +421,7 @@ function ip(req) {
 /**
  * A coarse network fingerprint for a request: a short hash of the (proxy-aware)
  * IP plus the headers a client can't trivially vary per-request without also
- * changing how the request looks. Used as the default rate-limit key here, and
+ * changing how the request looks. Anchors the default rate-limit key here, and
  * exported so the global fingerprint middleware can stamp the identical value
  * on `req.networkFingerprint` (one key space shared by both).
  */
@@ -413,8 +439,19 @@ export function computeNetworkFingerprint(req) {
         .slice(0, 16);
 }
 
+/**
+ * The device fingerprint (validated and stamped by the fingerprint middleware)
+ * refines the bucket so devices behind one NAT don't crowd each other's limit.
+ * It stays anchored to the network hash because the value is client-supplied:
+ * alone it could be spoofed to drain another device's bucket, and rotating it
+ * to mint fresh buckets is caught by the same stacked 'ip' backstop that
+ * catches User-Agent rotation.
+ */
 function fingerprint(req) {
-    return computeNetworkFingerprint(req);
+    const network = req.networkFingerprint ?? computeNetworkFingerprint(req);
+    return req.deviceFingerprint
+        ? `${network}:${req.deviceFingerprint}`
+        : network;
 }
 
 // -- Route middleware ------------------------------------------------

src/backend/core/http/middleware/rateLimit.test.js

@@ -67,6 +67,7 @@ describe('rateLimitGate — memory backend (default)', () => {
         actor: init.actor,
         route: init.route,
         socket: init.socket ?? { remoteAddress: '1.2.3.4' },
+        deviceFingerprint: init.deviceFingerprint,
     });
 
     it('admits up to `limit` hits and rejects the next one with 429', async () => {
@@ -140,6 +141,62 @@ describe('rateLimitGate — memory backend (default)', () => {
         expect(isHttpError(re)).toBe(true);
     });
 
+    it("'fingerprint' (default) gives each device behind one network its own bucket", async () => {
+        // Same IP and identical headers (a NAT'd office of look-alike
+        // machines) but distinct device fingerprints (stamped by the
+        // fingerprint middleware) → independent buckets, so one device
+        // hitting its limit doesn't block the whole network.
+        const opts = { limit: 1, window: 60_000, scope: 'mem-fp-device' };
+        const shared = {
+            ip: '5.6.7.8',
+            headers: { 'user-agent': 'shared-browser' },
+        };
+        expect(
+            await runGate(
+                opts,
+                makeReq({ ...shared, deviceFingerprint: 'device-alice-01' }),
+            ),
+        ).toBeUndefined();
+        expect(
+            await runGate(
+                opts,
+                makeReq({ ...shared, deviceFingerprint: 'device-bob-02' }),
+            ),
+        ).toBeUndefined();
+        // Same device again → its own bucket is full.
+        const re = await runGate(
+            opts,
+            makeReq({ ...shared, deviceFingerprint: 'device-alice-01' }),
+        );
+        expect(isHttpError(re)).toBe(true);
+    });
+
+    it('device fingerprint stays anchored to the network — spoofing a value from another IP cannot drain its bucket', async () => {
+        const opts = { limit: 1, window: 60_000, scope: 'mem-fp-anchor' };
+        const fp = 'device-victim-01';
+        // Victim exhausts their bucket from their own network.
+        expect(
+            await runGate(
+                opts,
+                makeReq({ ip: '10.0.0.1', deviceFingerprint: fp }),
+            ),
+        ).toBeUndefined();
+        const re = await runGate(
+            opts,
+            makeReq({ ip: '10.0.0.1', deviceFingerprint: fp }),
+        );
+        expect(isHttpError(re)).toBe(true);
+        // Attacker replays the same device fingerprint from elsewhere:
+        // different network hash → different bucket, and the victim's
+        // bucket is untouched.
+        expect(
+            await runGate(
+                opts,
+                makeReq({ ip: '99.99.99.99', deviceFingerprint: fp }),
+            ),
+        ).toBeUndefined();
+    });
+
     // Stacked gates, mirroring the materializer's handling of a
     // `rateLimit: [...]` array (each entry is its own gate; a rejection
     // short-circuits the chain). This is the credential-endpoint pattern:

src/backend/core/http/middleware/stepUpSession.test.ts

@@ -0,0 +1,263 @@
+/**
+ * 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 { describe, expect, it, vi } from 'vitest';
+import { TokenService } from '../../../services/auth/TokenService.js';
+import {
+    createStepUpGate,
+    signStepUpToken,
+    STEP_UP_COOKIE_NAME,
+    verifyStepUpSession,
+} from './stepUpSession.js';
+
+const V2_SECRET = 'test-v2-secret';
+const USER_UUID = 'a1111111-1111-1111-1111-111111111111';
+
+function tokenService(): TokenService {
+    const config = {
+        jwt_secret: 'test-v1-secret',
+        jwt_secret_v2: V2_SECRET,
+        allow_v1_tokens: true,
+    } as ConstructorParameters<typeof TokenService>[0];
+    const svc = new TokenService(
+        config,
+        {} as ConstructorParameters<typeof TokenService>[1],
+        {} as ConstructorParameters<typeof TokenService>[2],
+        {} as ConstructorParameters<typeof TokenService>[3],
+    );
+    svc.onServerStart();
+    return svc;
+}
+
+function reqWith(
+    cookie: string | undefined,
+    actorUuid: string | undefined,
+    extra: Partial<Request> = {},
+): Request {
+    return {
+        cookies: cookie ? { [STEP_UP_COOKIE_NAME]: cookie } : {},
+        actor: actorUuid ? { user: { uuid: actorUuid } } : undefined,
+        ...extra,
+    } as unknown as Request;
+}
+
+describe('verifyStepUpSession', () => {
+    it('accepts a token bound to the acting user', () => {
+        const ts = tokenService();
+        const token = signStepUpToken(ts, { uuid: USER_UUID });
+        expect(
+            verifyStepUpSession(reqWith(token, USER_UUID), { tokenService: ts }),
+        ).toBe(true);
+    });
+
+    it('rejects a token bound to a different user (cookie alone is useless)', () => {
+        const ts = tokenService();
+        const token = signStepUpToken(ts, { uuid: USER_UUID });
+        expect(
+            verifyStepUpSession(
+                reqWith(token, 'b2222222-2222-2222-2222-222222222222'),
+                { tokenService: ts },
+            ),
+        ).toBe(false);
+    });
+
+    it('rejects when there is no actor (no live session)', () => {
+        const ts = tokenService();
+        const token = signStepUpToken(ts, { uuid: USER_UUID });
+        expect(
+            verifyStepUpSession(reqWith(token, undefined), {
+                tokenService: ts,
+            }),
+        ).toBe(false);
+    });
+
+    it('rejects when the cookie is missing', () => {
+        const ts = tokenService();
+        expect(
+            verifyStepUpSession(reqWith(undefined, USER_UUID), {
+                tokenService: ts,
+            }),
+        ).toBe(false);
+    });
+
+    it('rejects an expired token', () => {
+        const ts = tokenService();
+        // Sign with a lifetime past the verifier's 30s clock tolerance.
+        const expired = ts.sign(
+            'step-up',
+            { user_uuid: USER_UUID, purpose: 'elevation' },
+            { expiresIn: -60 },
+        );
+        expect(
+            verifyStepUpSession(reqWith(expired, USER_UUID), {
+                tokenService: ts,
+            }),
+        ).toBe(false);
+    });
+
+    it('rejects a token minted under a different scope/purpose (no cross-use)', () => {
+        const ts = tokenService();
+        // A well-formed session-style token must not satisfy the gate.
+        const authToken = ts.sign('auth', {
+            type: 'session',
+            version: '2',
+            user_uid: USER_UUID,
+        });
+        expect(
+            verifyStepUpSession(reqWith(authToken, USER_UUID), {
+                tokenService: ts,
+            }),
+        ).toBe(false);
+    });
+});
+
+describe('createStepUpGate', () => {
+    it('passes a session with a valid elevation cookie', () => {
+        const ts = tokenService();
+        const gate = createStepUpGate({ tokenService: ts });
+        const token = signStepUpToken(ts, { uuid: USER_UUID });
+        const next = vi.fn();
+        gate(reqWith(token, USER_UUID), {} as Response, next);
+        expect(next).toHaveBeenCalledWith();
+    });
+
+    it('rejects a session without an elevation cookie, hinting the factor', () => {
+        const ts = tokenService();
+        const gate = createStepUpGate({ tokenService: ts });
+        const next = vi.fn();
+        const req = reqWith(undefined, USER_UUID, {
+            actor: { user: { uuid: USER_UUID, otp_enabled: true } },
+        } as never);
+        gate(req, {} as Response, next);
+        const err = next.mock.calls[0][0];
+        expect(err.statusCode).toBe(403);
+        expect(err.legacyCode).toBe('elevation_required');
+        expect(err.fields.factor).toBe('otp');
+    });
+
+    it('hints the password factor when 2FA is off', () => {
+        const ts = tokenService();
+        const gate = createStepUpGate({ tokenService: ts });
+        const next = vi.fn();
+        gate(reqWith(undefined, USER_UUID), {} as Response, next);
+        expect(next.mock.calls[0][0].fields.factor).toBe('password');
+    });
+
+    // A stolen session can mint a full-access token via
+    // /auth/create-access-token without re-proving identity, so exempting one
+    // here would be a way around the gate rather than an exception to it.
+    it('does NOT exempt full-access personal access tokens', () => {
+        const ts = tokenService();
+        const gate = createStepUpGate({ tokenService: ts });
+        const next = vi.fn();
+        const req = reqWith(undefined, USER_UUID, {
+            actor: {
+                user: { uuid: USER_UUID },
+                accessToken: { fullAccess: true },
+            },
+        } as never);
+        gate(req, {} as Response, next);
+        expect(next.mock.calls[0][0]?.statusCode).toBe(403);
+    });
+
+    // App-gated routes (adminOnly + allowedAppIds): an admin acting through an
+    // allowlisted app can't elevate — apps have no password/TOTP and are blocked
+    // from /auth/elevate. The exemption keys off the token carrying an allowed
+    // app id, not the route flag.
+    it('exempts a token that carries an allowlisted app id', () => {
+        const ts = tokenService();
+        const gate = createStepUpGate({
+            tokenService: ts,
+            allowedAppUids: ['app-xyz'],
+        });
+        const next = vi.fn();
+        const req = reqWith(undefined, USER_UUID, {
+            actor: { user: { uuid: USER_UUID }, app: { uid: 'app-xyz' } },
+        } as never);
+        gate(req, {} as Response, next);
+        expect(next).toHaveBeenCalledWith();
+    });
+
+    it('still requires step-up for an app id NOT in the allowlist', () => {
+        const ts = tokenService();
+        const gate = createStepUpGate({
+            tokenService: ts,
+            allowedAppUids: ['other-app'],
+        });
+        const next = vi.fn();
+        const req = reqWith(undefined, USER_UUID, {
+            actor: { user: { uuid: USER_UUID }, app: { uid: 'app-xyz' } },
+        } as never);
+        gate(req, {} as Response, next);
+        expect(next.mock.calls[0][0]?.statusCode).toBe(403);
+    });
+
+    it('still requires step-up when the route has no allowedAppIds', () => {
+        const ts = tokenService();
+        const gate = createStepUpGate({ tokenService: ts });
+        const next = vi.fn();
+        const req = reqWith(undefined, USER_UUID, {
+            actor: { user: { uuid: USER_UUID }, app: { uid: 'app-xyz' } },
+        } as never);
+        gate(req, {} as Response, next);
+        expect(next.mock.calls[0][0]?.statusCode).toBe(403);
+    });
+
+    it('still requires step-up on the human/root-token path (no app id in token)', () => {
+        const ts = tokenService();
+        const gate = createStepUpGate({
+            tokenService: ts,
+            allowedAppUids: ['app-xyz'],
+        });
+        const next = vi.fn();
+        gate(reqWith(undefined, USER_UUID), {} as Response, next);
+        expect(next.mock.calls[0][0]?.statusCode).toBe(403);
+    });
+
+    it('accepts the elevation via the x-puter-elevation header (API clients)', () => {
+        const ts = tokenService();
+        const gate = createStepUpGate({ tokenService: ts });
+        const token = signStepUpToken(ts, { uuid: USER_UUID });
+        const next = vi.fn();
+        const req = {
+            cookies: {},
+            headers: { 'x-puter-elevation': token },
+            actor: { user: { uuid: USER_UUID } },
+        } as never;
+        gate(req, {} as Response, next);
+        expect(next).toHaveBeenCalledWith();
+    });
+
+    it('rejects a header elevation bound to a different user', () => {
+        const ts = tokenService();
+        const gate = createStepUpGate({ tokenService: ts });
+        const token = signStepUpToken(ts, {
+            uuid: 'b2222222-2222-2222-2222-222222222222',
+        });
+        const next = vi.fn();
+        const req = {
+            cookies: {},
+            headers: { 'x-puter-elevation': token },
+            actor: { user: { uuid: USER_UUID } },
+        } as never;
+        gate(req, {} as Response, next);
+        expect(next.mock.calls[0][0]?.statusCode).toBe(403);
+    });
+});

src/backend/core/http/middleware/stepUpSession.ts

@@ -0,0 +1,191 @@
+/**
+ * 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 } from 'express';
+import type { IConfig } from '../../../types';
+import type { UserRow } from '../../../stores/user/UserStore';
+import type { TokenService } from '../../../services/auth/TokenService';
+import { sessionCookieFlags } from '../../../util/cookieFlags';
+import { HttpError } from '../HttpError';
+
+// Make sure the `Express.Request.actor` augmentation is in scope.
+import '../expressAugmentation';
+
+/**
+ * Step-up ("elevation") sessions — a second factor layered on top of an
+ * ordinary session for privileged endpoints (`adminOnly` routes).
+ *
+ * An ordinary session cookie proves only that someone holds the credential; for
+ * privileged endpoints that isn't enough, since a leaked session would inherit
+ * the privilege. Elevation makes the caller re-prove identity — a fresh TOTP
+ * code when 2FA is enabled, otherwise the account password — via
+ * `POST /auth/elevate`, which mints the cookie below.
+ *
+ * Both halves are required and neither is sufficient: gates demand a live
+ * session actor AND this proof, and the proof is bound to that actor's
+ * `user_uuid`. So a stolen session can't elevate itself, and a stolen elevation
+ * proof is inert without the session.
+ *
+ * The proof travels as an httpOnly cookie for browsers, or as the
+ * `x-puter-elevation` header for API clients (which have no cookie jar). The
+ * two are equivalent — both are the same signed token, and obtaining either
+ * requires the password/TOTP. Nothing is exempt from the requirement: there is
+ * deliberately no carve-out for any credential kind, because any credential a
+ * stolen session can obtain *without* re-proving identity would be a way around
+ * this control rather than an exception to it.
+ *
+ * The token has its own scope and `purpose` claim and carries no auth `type`
+ * claim, so `AuthService.authenticate` rejects it — it can never be spent as a
+ * main auth token even though every scope shares `jwt_secret_v2`.
+ */
+
+export const STEP_UP_COOKIE_NAME = 'puter_elevated';
+export const STEP_UP_HEADER_NAME = 'x-puter-elevation';
+export const STEP_UP_SCOPE = 'step-up';
+export const STEP_UP_PURPOSE = 'elevation';
+export const STEP_UP_TTL_SECONDS = 7 * 24 * 60 * 60;
+
+interface StepUpPayload {
+    user_uuid: string;
+    purpose: string;
+}
+
+/** Sign an elevation token bound to the user's uuid. */
+export function signStepUpToken(
+    tokenService: TokenService,
+    user: Pick<UserRow, 'uuid'>,
+): string {
+    return tokenService.sign(
+        STEP_UP_SCOPE,
+        { user_uuid: user.uuid, purpose: STEP_UP_PURPOSE },
+        { expiresIn: STEP_UP_TTL_SECONDS },
+    );
+}
+
+/**
+ * Cookie flags for the elevation cookie. `domain` and `maxAge` are what
+ * `sessionCookieFlags` doesn't set: the domain keeps the cookie readable across
+ * the site's subdomains (privileged endpoints aren't all on one origin), and
+ * `maxAge` gives the elevation its lifetime.
+ */
+export function stepUpCookieOptions(config: IConfig): {
+    httpOnly: true;
+    sameSite: 'none' | 'lax';
+    secure: boolean;
+    maxAge: number;
+    domain?: string;
+} {
+    return {
+        ...sessionCookieFlags(config),
+        httpOnly: true,
+        maxAge: STEP_UP_TTL_SECONDS * 1000,
+        ...(config.domain ? { domain: config.domain } : {}),
+    };
+}
+
+/**
+ * True iff a valid elevation proof (cookie or `x-puter-elevation` header) is
+ * present AND bound to the acting user. Never throws — a missing/expired/
+ * mismatched proof returns false so callers can prompt for the second factor
+ * instead of erroring.
+ */
+export function verifyStepUpSession(
+    req: Request,
+    deps: { tokenService: TokenService },
+): boolean {
+    const header = req.headers?.[STEP_UP_HEADER_NAME];
+    const token =
+        req.cookies?.[STEP_UP_COOKIE_NAME] ??
+        (typeof header === 'string' ? header : undefined);
+    const actorUuid = req.actor?.user?.uuid;
+    if (!token || !actorUuid) return false;
+    try {
+        const payload = deps.tokenService.verify<StepUpPayload>(
+            STEP_UP_SCOPE,
+            token,
+        );
+        return (
+            payload?.purpose === STEP_UP_PURPOSE &&
+            payload.user_uuid === actorUuid
+        );
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Require an elevated session. Runs after the privilege gate it supplements
+ * (`adminOnlyGate`), so it only adds the re-authentication requirement.
+ *
+ * Narrow by design — the only exemption is the app-gated path:
+ *
+ *   - Not env-conditional, so the flow exercised locally is the one that ships.
+ *   - No carve-out for full-access tokens. That looks safe (a deliberately
+ *     minted, header-borne credential) but isn't: `/auth/create-access-token`
+ *     needs only a session, so a stolen session can mint a full-access token
+ *     without ever re-proving identity and walk straight around this gate.
+ *   - No carve-out based on how the credential arrived (cookie vs bearer). The
+ *     holder of a token chooses which header to put it in, so that distinction
+ *     is attacker-controlled and worthless as a gate.
+ *   - `allowedAppUids`: the exemption is keyed off the *token*, not the route.
+ *     An actor whose token carries one of these allowlisted app ids (an admin
+ *     acting through an allowlisted app) is exempt — that actor can't elevate at
+ *     all (apps have no password/TOTP and are blocked from `/auth/elevate`), so
+ *     step-up is unsatisfiable for it. A token WITHOUT an allowlisted app id — a
+ *     root/human session — still requires step-up, exactly as it would on a
+ *     route with no `allowedAppIds`. So this is not a session or token-kind
+ *     carve-out: reaching the exempt path needs an admin's OAuth grant to a
+ *     specific allowlisted app.
+ *
+ * The invariant for the human path: reaching a privileged endpoint requires
+ * proving the password or a TOTP code within the elevation's lifetime.
+ *
+ * A caller without a valid elevation proof is rejected with
+ * `elevation_required`; `factor` tells the client which credential to collect.
+ */
+export function createStepUpGate(deps: {
+    tokenService: TokenService;
+    allowedAppUids?: readonly string[];
+}): RequestHandler {
+    return (req, _res, next) => {
+        // Exempt only an actor whose token carries one of the route's
+        // allowlisted app ids: an admin acting through an allowlisted app can't
+        // elevate, so step-up is unsatisfiable for it. Any other actor — most
+        // importantly a root/human session with no app id in its token — falls
+        // through and must present the elevation proof.
+        const appUid = req.actor?.app?.uid;
+        if (appUid && deps.allowedAppUids?.includes(appUid)) {
+            next();
+            return;
+        }
+        if (verifyStepUpSession(req, deps)) {
+            next();
+            return;
+        }
+        next(
+            new HttpError(403, 'Re-authentication required', {
+                legacyCode: 'elevation_required',
+                fields: {
+                    code: 'elevation_required',
+                    factor: req.actor?.user?.otp_enabled ? 'otp' : 'password',
+                },
+            }),
+        );
+    };
+}

src/backend/core/http/types.ts

@@ -3,23 +3,37 @@
  *
  * 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.
+ * 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.
+ * 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/>.
+ * along with this program. If not, see
+ * [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
  */
 
 import type { NextFunction, Request, RequestHandler, Response } from 'express';
 import type { Actor } from '../actor';
 
+/**
+ * Which request slot the auth probe found its token in, recorded on
+ * `req.tokenSource`. Routes that hand the browser durable credentials assert on
+ * it instead of accepting any token that authenticates.
+ */
+export type TokenSource =
+    | 'body'
+    | 'header'
+    | 'x-api-key'
+    | 'cookie'
+    | 'query'
+    | 'handshake';
+
 /**
  * Every route method PuterRouter exposes. Mirrors the express router surface
  * plus WebDAV verbs that some endpoints still use.
@@ -47,7 +61,8 @@ export type RouteMethod =
 
 /**
  * Path shape accepted by express route methods. Kept permissive rather than
- * re-exporting express's internal `PathParams` (which isn't stable public API).
+ * re-exporting express's internal `PathParams` (which isn't stable public
+ * API).
  */
 export type RoutePath = string | RegExp | Array<string | RegExp>;
 
@@ -61,20 +76,20 @@ export type RoutePath = string | RegExp | Array<string | RegExp>;
  *     requireUserActor → adminOnly → allowedAppIds →
  *     caller `middleware: []` → handler
  *
- * `requireUserActor`, `adminOnly`, and `allowedAppIds` all imply
- * `requireAuth`; the materializer dedupes so only one auth gate ends up
- * in the chain. Commented-out slots are reserved for the next chunks
- * (body parsing, post-auth gates, timing).
+ * `requireUserActor`, `adminOnly`, and `allowedAppIds` all imply `requireAuth`;
+ * the materializer dedupes so only one auth gate ends up in the chain.
+ * Commented-out slots are reserved for the next chunks (body parsing, post-auth
+ * gates, timing).
  */
 /** One rate-limit window. See `RouteOptions.rateLimit` for semantics. */
 export interface RouteRateLimit {
     limit: number;
     window: number;
     /**
-     * Per-subscription overrides for `limit` (`SubscriptionPolicy.id`
-     * → cap). Same mechanic as `concurrent.bySubscription`: resolved
-     * via the metering service per request; falls back to the base
-     * `limit` when there's no actor / no metering / no match.
+     * Per-subscription overrides for `limit` (`SubscriptionPolicy.id` → cap).
+     * Same mechanic as `concurrent.bySubscription`: resolved via the metering
+     * service per request; falls back to the base `limit` when there's no actor
+     * / no metering / no match.
      */
     bySubscription?: Record<string, number>;
     key?: 'fingerprint' | 'ip' | 'user' | ((req: Request) => string);
@@ -83,20 +98,26 @@ export interface RouteRateLimit {
 }
 
 export interface RouteOptions {
-    /** Extra per-route middleware. Applied after built-in gates, before the handler. */
+    /**
+     * Extra per-route middleware. Applied after built-in gates, before the
+     * handler.
+     */
     middleware?: RequestHandler[];
 
     /**
-     * Subdomain routing. If set, the route only matches requests whose
-     * leftmost subdomain is in this list (via `next('route')` skip).
+     * Subdomain routing. If set, the route only matches requests whose leftmost
+     * subdomain is in this list (via `next('route')` skip).
      *
-     * If omitted, verb-routes (get/post/etc.) are restricted to the root
-     * origin only (no subdomain). Pass `'*'` to explicitly match ANY
-     * subdomain/root. `use()` middleware is not gated by default.
+     * If omitted, verb-routes (get/post/etc.) are restricted to the root origin
+     * only (no subdomain). Pass `'*'` to explicitly match ANY subdomain/root.
+     * `use()` middleware is not gated by default.
      */
     subdomain?: string | string[];
 
-    /** Reject anonymous + suspended-user requests with 401/403. Only allows user and app actors */
+    /**
+     * Reject anonymous + suspended-user requests with 401/403. Only allows user
+     * and app actors
+     */
     requireAuth?: boolean;
 
     /** Reject app/access-token actors. Implies `requireAuth`. */
@@ -116,27 +137,49 @@ export interface RouteOptions {
     /** Allows access-tokens */
     allowAccessToken?: boolean;
 
+    /**
+     * Reject bare user-session actors ("root" tokens — no app, no access token)
+     * with 403 `app_or_api_token_required`. Implies `requireAuth`. Use on API
+     * surfaces that must only be driven by a delegated credential (app/worker
+     * token or a dashboard-minted API token), so a copied session token can't
+     * double as an API credential. Compose with `requireUserActor` +
+     * `allowFullAccessToken` to further narrow to API tokens only (apps stay
+     * out too). Worker sessions (`session.kind === 'worker'`) always pass — a
+     * deployed worker is a delegated, revocable credential, never a root
+     * token.
+     */
+    noUserSession?: boolean;
+
     /**
      * Reject unless the actor's username is `admin`, `system`, or one of the
      * extras in this array. `true` means just `admin`/`system`; an array adds
      * to that pair (does not replace it). Implies `requireAuth`.
      *
-     * Does NOT imply `requireUserActor` — admin endpoints accept an admin's
-     * access-token or app-under-user actor. Combine with `requireUserActor`
-     * to restrict to browser sessions.
+     * Also requires a _root token_ (an actor with no app anywhere in its token
+     * chain), so an admin acting through a third-party app can't reach the
+     * route. Pair with `allowedAppIds` to make an admin route reachable by
+     * specific apps: the combination admits a root token OR a token scoped to
+     * an allowed app.
+     *
+     * Does NOT imply `requireUserActor` — a root token still includes an
+     * admin's full-access personal access token, not only browser sessions.
+     * Combine with `requireUserActor` to restrict to browser sessions.
      */
     adminOnly?: boolean | string[];
 
-    /** Reject unless the actor is acting through one of these apps. Implies `requireAuth`. */
+    /**
+     * Reject unless the actor is acting through one of these apps. Implies
+     * `requireAuth`.
+     */
     allowedAppIds?: string[];
 
     /**
-     * Allow users whose account is pending email confirmation to access
-     * this route. By default, any authenticated route rejects users where
-     * `requires_email_confirmation && !email_confirmed` with 403. Set
-     * this to `true` on essential flows that must remain accessible
-     * before confirmation: logout, email-confirm, whoami, save-account,
-     * anti-CSRF token, etc.
+     * Allow users whose account is pending email confirmation to access this
+     * route. By default, any authenticated route rejects users where
+     * `requires_email_confirmation && !email_confirmed` with 403. Set this to
+     * `true` on essential flows that must remain accessible before
+     * confirmation: logout, email-confirm, whoami, save-account, anti-CSRF
+     * token, etc.
      *
      * Only meaningful when the route also requires authentication (via
      * `requireAuth`, `requireUserActor`, `adminOnly`, or `allowedAppIds`).
@@ -149,8 +192,8 @@ export interface RouteOptions {
      * `config.strict_email_verification_required` is falsy, so self-hosted
      * deployments can opt in via config. Implies `requireAuth` but NOT
      * `requireUserActor` — app-under-user actors also carry a `.user`, so
-     * verification applies uniformly whether the user acts directly or
-     * through an app.
+     * verification applies uniformly whether the user acts directly or through
+     * an app.
      */
     requireVerified?: boolean;
 
@@ -160,14 +203,15 @@ export interface RouteOptions {
      * the raw bytes on `req.rawBody` for signature-verification use cases.
      *
      * Use this option only when a route needs different parser settings:
-     *   - `false` — opt out of parsing entirely (rare; the route reads the
-     *     raw stream itself, e.g. some webhook proxies). The global parser
-     *     will still have already run if the content-type was JSON, so this
-     *     is mostly useful for routes that accept *non*-JSON body shapes
-     *     and want to ensure no further parsers attach.
-     *   - `{ limit, type }` — override the limit (e.g., for ML endpoints
-     *     that legitimately need 100mb) or the matched content-type list
-     *     (e.g., to ALSO accept `application/x-ndjson`).
+     *
+     * - `false` — opt out of parsing entirely (rare; the route reads the raw
+     *   stream itself, e.g. some webhook proxies). The global parser will still
+     *   have already run if the content-type was JSON, so this is mostly useful
+     *   for routes that accept _non_-JSON body shapes and want to ensure no
+     *   further parsers attach.
+     * - `{ limit, type }` — override the limit (e.g., for ML endpoints that
+     *   legitimately need 100mb) or the matched content-type list (e.g., to
+     *   ALSO accept `application/x-ndjson`).
      */
     bodyJson?: false | { limit?: string; type?: string | string[] };
 
@@ -192,64 +236,64 @@ export interface RouteOptions {
     bodyUrlencoded?: boolean | { limit?: string; extended?: boolean };
 
     /**
-     * Require captcha verification. When `true`, the route rejects
-     * requests that don't carry valid `captchaToken` + `captchaAnswer`
-     * fields in the body. No-op when captcha is disabled in config.
+     * Require captcha verification. When `true`, the route rejects requests
+     * that don't carry valid `captchaToken` + `captchaAnswer` fields in the
+     * body. No-op when captcha is disabled in config.
      */
     captcha?: boolean;
 
     /**
-     * Require a valid one-time anti-CSRF token in `req.body.anti_csrf`.
-     * The token is consumed on use. Requires authentication (keyed by
-     * user uuid).
+     * Require a valid one-time anti-CSRF token in `req.body.anti_csrf`. The
+     * token is consumed on use. Requires authentication (keyed by user uuid).
      */
     antiCsrf?: boolean;
 
     /**
-     * Per-route rate limiting. In-memory sliding window keyed by
-     * request identity.
+     * Per-route rate limiting. In-memory sliding window keyed by request
+     * identity.
      *
      * `key` controls how requests are bucketed:
-     *   - `'fingerprint'` (default) — IP + User-Agent hash. Safe for
-     *     shared IPs (offices, VPNs).
-     *   - `'ip'` — bare IP address.
-     *   - `'user'` — actor's user ID. Use for authenticated routes
-     *     where you want per-account limits.
-     *   - `(req) => string` — custom key function.
      *
-     * `scope` is an optional namespace prefix to isolate counters
-     * between routes that share the same key strategy. Defaults to
-     * the route path.
+     * - `'fingerprint'` (default) — network hash (IP + headers), refined by the
+     *   client's device fingerprint when one was supplied. Safe for shared IPs
+     *   (offices, VPNs): each device gets its own bucket instead of the whole
+     *   network sharing one.
+     * - `'ip'` — bare IP address.
+     * - `'user'` — actor's user ID. Use for authenticated routes where you want
+     *   per-account limits.
+     * - `(req) => string` — custom key function.
      *
-     * `backend` selects the storage backend ('memory' / 'redis' / 'kv').
-     * All registered backends stay co-resident at runtime, so different
-     * routes can pick whichever fits their access pattern. Omitting
-     * `backend` uses the server-wide default (`config.rate_limit.backend`).
+     * `scope` is an optional namespace prefix to isolate counters between
+     * routes that share the same key strategy. Defaults to the route path.
      *
-     * An array applies every limit independently (a request must pass all
-     * of them). Use this to pair a per-client budget with a coarser
-     * backstop on a different key — e.g. per-fingerprint for fairness on
-     * shared IPs, plus per-IP so rotating headers can't mint fresh
-     * fingerprint buckets indefinitely. Give each entry its own `scope`
-     * so the counters don't collide.
+     * `backend` selects the storage backend ('memory' / 'redis' / 'kv'). All
+     * registered backends stay co-resident at runtime, so different routes can
+     * pick whichever fits their access pattern. Omitting `backend` uses the
+     * server-wide default (`config.rate_limit.backend`).
+     *
+     * An array applies every limit independently (a request must pass all of
+     * them). Use this to pair a per-client budget with a coarser backstop on a
+     * different key — e.g. per-fingerprint for fairness on shared IPs, plus
+     * per-IP so rotating headers can't mint fresh fingerprint buckets
+     * indefinitely. Give each entry its own `scope` so the counters don't
+     * collide.
      */
     rateLimit?: RouteRateLimit | RouteRateLimit[];
 
     /**
-     * Concurrent in-flight limiting. Caps how many requests for this
-     * key are simultaneously in flight, rather than how many fire per
-     * window. A slot is acquired before the handler runs and released
-     * on `res.finish` / `res.close` — aborted requests still give their
-     * slot back.
+     * Concurrent in-flight limiting. Caps how many requests for this key are
+     * simultaneously in flight, rather than how many fire per window. A slot is
+     * acquired before the handler runs and released on `res.finish` /
+     * `res.close` — aborted requests still give their slot back.
      *
-     *   { concurrent: { limit: 5, key: 'user' } }
-     *   { concurrent: { limit: 5, bySubscription: { user_free: 2 } } }
+     * { concurrent: { limit: 5, key: 'user' } } { concurrent: { limit: 5,
+     * bySubscription: { user_free: 2 } } }
      *
      * `bySubscription` overrides the base `limit` per subscription tier
-     * (`SubscriptionPolicy.id`) — `user_free`, `temp_free`, `unlimited`
-     * out of the box. Requires the metering service to be wired into
-     * the rate-limit module (`configureRateLimit({ metering: ... })`)
-     * and an authenticated actor; otherwise the base `limit` applies.
+     * (`SubscriptionPolicy.id`) — `user_free`, `temp_free`, `unlimited` out of
+     * the box. Requires the metering service to be wired into the rate-limit
+     * module (`configureRateLimit({ metering: ... })`) and an authenticated
+     * actor; otherwise the base `limit` applies.
      *
      * `key`, `scope`, `backend` parallel the `rateLimit` option exactly;
      * there's no `window` — that's the whole point of the second gate.
@@ -265,11 +309,14 @@ export interface RouteOptions {
     // Reserved — wire as the corresponding features/services land:
     // bodyFiles?: string[];      // multer-style multipart fields
     // responseTimeout?: number;
+
+    realMime?: boolean; // for legacy FS controller, see `LegacyFSController#serveFile`
 }
 
 /**
  * Normalized route record produced by PuterRouter (and the class/method
- * decorators). `path` is omitted only for `router.use(handler)` / `use(options, handler)`.
+ * decorators). `path` is omitted only for `router.use(handler)` / `use(options,
+ * handler)`.
  */
 export interface RouteDescriptor {
     method: RouteMethod;
@@ -280,8 +327,8 @@ export interface RouteDescriptor {
 
 /**
  * Shape stored on decorated controller prototypes by `@Get` / `@Post` / etc.
- * `handler` is the method reference — still unbound at decoration time;
- * the installed `registerRoutes` binds it to the instance at walk time.
+ * `handler` is the method reference — still unbound at decoration time; the
+ * installed `registerRoutes` binds it to the instance at walk time.
  */
 export interface CollectedRoute {
     method: RouteMethod;
@@ -309,8 +356,8 @@ export const PREFIX_METADATA_KEY = '__puterControllerPrefix' as const;
 
 /**
  * `true` iff the materializer will run an auth gate before the handler.
- * Branches match readonly *and* mutable arrays so callers don't need
- * `as const` on every options literal.
+ * Branches match readonly _and_ mutable arrays so callers don't need `as const`
+ * on every options literal.
  */
 export type AuthRequired<O extends RouteOptions> = O extends {
     requireAuth: true;
@@ -322,7 +369,9 @@ export type AuthRequired<O extends RouteOptions> = O extends {
         ? true
         : O extends { allowedAppIds: readonly string[] | string[] }
           ? true
-          : false;
+          : O extends { noUserSession: true }
+            ? true
+            : false;
 
 /** Express `Request` with `actor` narrowed based on the route's options. */
 export type TypedRequest<O extends RouteOptions> = Omit<Request, 'actor'> & {

src/backend/drivers/ai-chat/ChatCompletionDriver.ts

@@ -3,18 +3,19 @@
  *
  * 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.
+ * 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.
+ * 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/>.
+ * along with this program. If not, see
+ * [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
  */
 
 import crypto from 'node:crypto';
@@ -37,6 +38,7 @@ import { DeepSeekProvider } from './providers/deepseek/DeepSeekProvider.js';
 import { FakeChatProvider } from './providers/FakeChatProvider.js';
 import { GeminiChatProvider } from './providers/gemini/GeminiChatProvider.js';
 import { GroqAIProvider } from './providers/groq/GroqAIProvider.js';
+import { InfronProvider } from './providers/infron/InfronProvider.js';
 import { MiniMaxProvider } from './providers/minimax/MiniMaxProvider.js';
 import { MistralAIProvider } from './providers/mistral/MistralAiProvider.js';
 import { MoonshotProvider } from './providers/moonshot/MoonshotProvider.js';
@@ -72,13 +74,13 @@ type ProviderAttempt = {
 };
 
 /**
- * Capture what an upstream provider gave us so the classifier downstream
- * can decide a user-facing status code instead of always returning 500.
+ * Capture what an upstream provider gave us so the classifier downstream can
+ * decide a user-facing status code instead of always returning 500.
  *
- * OpenAI-SDK-based providers throw `APIError` with `.status` and a
- * structured `.error` body — pull both. For arbitrary errors we fall
- * back to the message and a status sniff so providers that throw plain
- * `Error("... 503 ...")` strings still classify correctly.
+ * OpenAI-SDK-based providers throw `APIError` with `.status` and a structured
+ * `.error` body — pull both. For arbitrary errors we fall back to the message
+ * and a status sniff so providers that throw plain `Error("... 503 ...")`
+ * strings still classify correctly.
  */
 const toAttempt = (
     modelId: string,
@@ -126,11 +128,12 @@ const isUpstream5xx = (a: ProviderAttempt) =>
  * Map an exhausted fallback chain to a single user-facing HttpError.
  *
  * Per-class rules (see also alarm gate in server.ts):
- *  - all rate-limited → 429 `upstream_rate_limited` (paged: forced alert)
- *  - all auth failures → 500 `upstream_auth_failed` (paged: our config)
- *  - all upstream 5xx → 400 `upstream_provider_unavailable` (no page)
- *  - all upstream 4xx (other) → 400 `upstream_bad_request` (no page)
- *  - mixed → 400 `upstream_failed` (no page)
+ *
+ * - All rate-limited → 429 `upstream_rate_limited` (paged: forced alert)
+ * - All auth failures → 500 `upstream_auth_failed` (paged: our config)
+ * - All upstream 5xx → 400 `upstream_provider_unavailable` (no page)
+ * - All upstream 4xx (other) → 400 `upstream_bad_request` (no page)
+ * - Mixed → 400 `upstream_failed` (no page)
  */
 const classifyAttempts = (attempts: ProviderAttempt[]): HttpError => {
     const fields = { attempts };
@@ -196,10 +199,10 @@ const classifyAttempts = (attempts: ProviderAttempt[]): HttpError => {
 /**
  * Driver implementing the `puter-chat-completion` interface.
  *
- * Manages multiple upstream providers (Claude, OpenAI, …) and handles
- * model resolution, provider routing, fallback on failure, and message
- * normalisation. Each provider is a plain `IChatProvider` — the driver
- * instantiates them from config on boot.
+ * Manages multiple upstream providers (Claude, OpenAI, …) and handles model
+ * resolution, provider routing, fallback on failure, and message normalisation.
+ * Each provider is a plain `IChatProvider` — the driver instantiates them from
+ * config on boot.
  *
  * Providers handle their own metering internally.
  */
@@ -985,6 +988,18 @@ export class ChatCompletionDriver extends PuterDriver {
             );
         }
 
+        const infron = providers['infron'];
+        const infronKey = readKey(infron);
+        if (infronKey) {
+            this.#providers['infron'] = new InfronProvider(
+                {
+                    apiKey: infronKey,
+                    apiBaseUrl: infron?.apiBaseUrl as string | undefined,
+                },
+                metering,
+            );
+        }
+
         // Fake provider — always available for testing
         this.#providers['fake-chat'] = new FakeChatProvider();
     }
@@ -992,7 +1007,7 @@ export class ChatCompletionDriver extends PuterDriver {
     // -- Model map ---------------------------------------------------
 
     async #buildModelMap() {
-        const AGGREGATORS = new Set(['together-ai', 'openrouter']);
+        const AGGREGATORS = new Set(['together-ai', 'openrouter', 'infron']);
 
         for (const providerName in this.#providers) {
             const provider = this.#providers[providerName];

src/backend/drivers/ai-chat/providers/claude/ClaudeProvider.ts

@@ -3,18 +3,19 @@
  *
  * 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.
+ * 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.
+ * 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/>.
+ * along with this program. If not, see
+ * [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
  */
 
 import Anthropic from '@anthropic-ai/sdk';
@@ -268,8 +269,10 @@ export class ClaudeProvider implements IChatProvider {
         // Other models require temperature=1 when thinking is enabled.
         const omitsTemperature = [
             'claude-fable-5',
+            'claude-sonnet-5',
             'claude-opus-4-7',
             'claude-opus-4-8',
+            'claude-opus-5',
         ].includes(modelUsed.id);
         const resolvedTemperature = omitsTemperature
             ? undefined
@@ -278,6 +281,8 @@ export class ClaudeProvider implements IChatProvider {
               : (temperature ?? 0);
         const supportsEffort = [
             'claude-fable-5',
+            'claude-sonnet-5',
+            'claude-opus-5',
             'claude-opus-4-8',
             'claude-opus-4-7',
             'claude-opus-4-6',
@@ -680,6 +685,7 @@ export class ClaudeProvider implements IChatProvider {
         // the stream.
         if (
             modelId === 'claude-fable-5' ||
+            modelId === 'claude-opus-5' ||
             modelId === 'claude-opus-4-8' ||
             modelId === 'claude-opus-4-7'
         ) {

src/backend/drivers/ai-chat/providers/claude/models.ts

@@ -3,18 +3,19 @@
  *
  * 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.
+ * 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.
+ * 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/>.
+ * along with this program. If not, see
+ * [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
  */
 
 import type { IChatModel } from '../../types.js';
@@ -50,6 +51,65 @@ export const CLAUDE_MODELS: IChatModel[] = [
         context: 1000000,
         max_tokens: 128000,
     },
+    {
+        puterId: 'anthropic:anthropic/claude-sonnet-5',
+        id: 'claude-sonnet-5',
+        modalities: { input: ['text', 'image', 'pdf'], output: ['text'] },
+        open_weights: false,
+        tool_call: true,
+        release_date: '2026-06-30',
+        aliases: [
+            'claude-sonnet',
+            'claude-sonnet-latest',
+            'claude-sonnet-5-latest',
+            'claude-sonnet-5',
+            'anthropic/claude-sonnet-5',
+        ],
+        name: 'Claude Sonnet 5',
+        costs_currency: 'usd-cents',
+        input_cost_key: 'input_tokens',
+        output_cost_key: 'output_tokens',
+        costs: {
+            tokens: 1_000_000,
+            input_tokens: 300,
+            ephemeral_5m_input_tokens: 300 * 1.25,
+            ephemeral_1h_input_tokens: 300 * 2,
+            cache_read_input_tokens: 300 * 0.1,
+            output_tokens: 1500,
+        },
+        context: 1000000,
+        max_tokens: 64000,
+    },
+    {
+        puterId: 'anthropic:anthropic/claude-opus-5',
+        id: 'claude-opus-5',
+        modalities: { input: ['text', 'image', 'pdf'], output: ['text'] },
+        open_weights: false,
+        tool_call: true,
+        knowledge: '2026-05',
+        release_date: '2026-07-24',
+        aliases: [
+            'claude-opus',
+            'claude-opus-latest',
+            'claude-opus-5-latest',
+            'claude-opus-5',
+            'anthropic/claude-opus-5',
+        ],
+        name: 'Claude Opus 5',
+        costs_currency: 'usd-cents',
+        input_cost_key: 'input_tokens',
+        output_cost_key: 'output_tokens',
+        costs: {
+            tokens: 1_000_000,
+            input_tokens: 500,
+            ephemeral_5m_input_tokens: 500 * 1.25,
+            ephemeral_1h_input_tokens: 500 * 2,
+            cache_read_input_tokens: 500 * 0.1,
+            output_tokens: 2500,
+        },
+        context: 1000000,
+        max_tokens: 128000,
+    },
     {
         puterId: 'anthropic:anthropic/claude-opus-4-8',
         id: 'claude-opus-4-8',
@@ -59,8 +119,6 @@ export const CLAUDE_MODELS: IChatModel[] = [
         knowledge: '2026-01',
         release_date: '2026-05-28',
         aliases: [
-            'claude-opus',
-            'claude-opus-latest',
             'claude-opus-4-8-latest',
             'claude-opus-4.8',
             'claude-opus-4-8',
@@ -119,8 +177,6 @@ export const CLAUDE_MODELS: IChatModel[] = [
         knowledge: '2025-08',
         release_date: '2026-02-17',
         aliases: [
-            'claude-sonnet-latest',
-            'claude-sonnet',
             'claude-sonnet-4-6-latest',
             'claude-sonnet-4.6',
             'claude-sonnet-4-6',
@@ -311,127 +367,4 @@ export const CLAUDE_MODELS: IChatModel[] = [
         context: 200000,
         max_tokens: 32000,
     },
-    {
-        puterId: 'anthropic:anthropic/claude-sonnet-4',
-        id: 'claude-sonnet-4-20250514',
-        modalities: { input: ['text', 'image', 'pdf'], output: ['text'] },
-        open_weights: false,
-        tool_call: true,
-        knowledge: '2025-03-31',
-        release_date: '2025-05-22',
-        aliases: [
-            'claude-sonnet-4',
-            'claude-sonnet-4-latest',
-            'anthropic/claude-sonnet-4',
-        ],
-        name: 'Claude Sonnet 4',
-        costs_currency: 'usd-cents',
-        input_cost_key: 'input_tokens',
-        output_cost_key: 'output_tokens',
-        costs: {
-            tokens: 1_000_000,
-            input_tokens: 300,
-            ephemeral_5m_input_tokens: 300 * 1.25,
-            ephemeral_1h_input_tokens: 300 * 2,
-            cache_read_input_tokens: 300 * 0.1,
-            output_tokens: 1500,
-        },
-        context: 200000,
-        max_tokens: 64000,
-    },
-    {
-        puterId: 'anthropic:anthropic/claude-3-7-sonnet',
-        id: 'claude-3-7-sonnet-20250219',
-        modalities: { input: ['text', 'image', 'pdf'], output: ['text'] },
-        open_weights: false,
-        tool_call: true,
-        knowledge: '2024-10-31',
-        release_date: '2025-02-19',
-        aliases: ['claude-3-7-sonnet-latest', 'anthropic/claude-3-7-sonnet'],
-        succeeded_by: 'claude-sonnet-4-20250514',
-        costs_currency: 'usd-cents',
-        input_cost_key: 'input_tokens',
-        output_cost_key: 'output_tokens',
-        costs: {
-            tokens: 1_000_000,
-            input_tokens: 300,
-            ephemeral_5m_input_tokens: 300 * 1.25,
-            ephemeral_1h_input_tokens: 300 * 2,
-            cache_read_input_tokens: 300 * 0.1,
-            output_tokens: 1500,
-        },
-        context: 200000,
-        max_tokens: 8192,
-    },
-    {
-        puterId: 'anthropic:anthropic/claude-3-5-sonnet',
-        id: 'claude-3-5-sonnet-20241022',
-        modalities: { input: ['text', 'image', 'pdf'], output: ['text'] },
-        open_weights: false,
-        tool_call: true,
-        knowledge: '2024-04-30',
-        release_date: '2024-10-22',
-        name: 'Claude 3.5 Sonnet',
-        aliases: ['claude-3-5-sonnet-latest', 'anthropic/claude-3-5-sonnet'],
-        costs_currency: 'usd-cents',
-        input_cost_key: 'input_tokens',
-        output_cost_key: 'output_tokens',
-        costs: {
-            tokens: 1_000_000,
-            input_tokens: 300,
-            ephemeral_5m_input_tokens: 300 * 1.25,
-            ephemeral_1h_input_tokens: 300 * 2,
-            cache_read_input_tokens: 300 * 0.1,
-            output_tokens: 1500,
-        },
-        context: 200000,
-        max_tokens: 8192,
-    },
-    {
-        puterId: 'anthropic:anthropic/claude-3-5-sonnet-20240620',
-        id: 'claude-3-5-sonnet-20240620',
-        modalities: { input: ['text', 'image', 'pdf'], output: ['text'] },
-        open_weights: false,
-        tool_call: true,
-        knowledge: '2024-04-30',
-        release_date: '2024-06-20',
-        succeeded_by: 'claude-3-5-sonnet-20241022',
-        aliases: ['anthropic/claude-3-5-sonnet-20240620'],
-        costs_currency: 'usd-cents',
-        input_cost_key: 'input_tokens',
-        output_cost_key: 'output_tokens',
-        costs: {
-            tokens: 1_000_000,
-            input_tokens: 300,
-            ephemeral_5m_input_tokens: 300 * 1.25,
-            ephemeral_1h_input_tokens: 300 * 2,
-            cache_read_input_tokens: 300 * 0.1,
-            output_tokens: 1500,
-        },
-        context: 200000,
-        max_tokens: 8192,
-    },
-    {
-        puterId: 'anthropic:anthropic/claude-3-haiku',
-        id: 'claude-3-haiku-20240307',
-        modalities: { input: ['text', 'image', 'pdf'], output: ['text'] },
-        open_weights: false,
-        tool_call: true,
-        knowledge: '2023-08-31',
-        release_date: '2024-03-13',
-        aliases: ['anthropic/claude-3-haiku'],
-        costs_currency: 'usd-cents',
-        input_cost_key: 'input_tokens',
-        output_cost_key: 'output_tokens',
-        costs: {
-            tokens: 1_000_000,
-            input_tokens: 25,
-            ephemeral_5m_input_tokens: 25 * 1.25,
-            ephemeral_1h_input_tokens: 25 * 2,
-            cache_read_input_tokens: 25 * 0.1,
-            output_tokens: 125,
-        },
-        context: 200000,
-        max_tokens: 4096,
-    },
 ];

src/backend/drivers/ai-chat/providers/infron/InfronProvider.integration.test.ts

@@ -0,0 +1,59 @@
+/**
+ * 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/>.
+ */
+
+/**
+ * Integration test for the Infron aggregator.
+ *
+ * Routes through Infron to a tiny upstream model
+ * (`deepseek/deepseek-v4-flash`). Skipped when
+ * `PUTER_TEST_AI_INFRON_API_KEY` is unset.
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+    INTEGRATION_TEST_TIMEOUT_MS,
+    makeMeteringStub,
+    optionalEnv,
+    skipUnlessEnv,
+    withTestActor,
+} from '../../../integrationTestUtil.js';
+import { InfronProvider } from './InfronProvider.js';
+
+const ENV_VAR = 'PUTER_TEST_AI_INFRON_API_KEY';
+
+describe.skipIf(skipUnlessEnv(ENV_VAR))('InfronProvider (integration)', () => {
+    it('returns a non-empty completion via Infron', { timeout: INTEGRATION_TEST_TIMEOUT_MS }, async () => {
+        const provider = new InfronProvider(
+            { apiKey: optionalEnv(ENV_VAR)! },
+            makeMeteringStub(),
+        );
+
+        const result = await withTestActor(() =>
+            provider.complete({
+                model: 'infron:deepseek/deepseek-v4-flash',
+                messages: [{ role: 'user', content: 'Say hi in one word.' }],
+                max_tokens: 16,
+            }),
+        );
+
+        const text = (result as { message?: { content?: string } }).message
+            ?.content;
+        expect(typeof text === 'string' && text.length > 0).toBe(true);
+    });
+});

src/backend/drivers/ai-chat/providers/infron/InfronProvider.test.ts

@@ -0,0 +1,483 @@
+/*
+ * 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/>.
+ */
+
+/**
+ * Offline unit tests for InfronProvider.
+ *
+ * Boots a real PuterServer (in-memory sqlite + dynamo + s3 + mock
+ * redis) and constructs InfronProvider directly against the live
+ * wired `MeteringService` so the recording side is exercised end-to-
+ * end. Infron is OpenAI-compatible, so the OpenAI SDK is mocked at
+ * the module boundary; the model catalog is fetched via `axios`
+ * which is mocked at its module boundary too. Both are the real
+ * network egress points. Each test clears the kv-cached model list.
+ * The companion integration test (InfronProvider.integration.test.ts)
+ * exercises the real Infron endpoint.
+ */
+
+import { Writable } from 'node:stream';
+import {
+    afterAll,
+    afterEach,
+    beforeAll,
+    beforeEach,
+    describe,
+    expect,
+    it,
+    vi,
+    type MockInstance,
+} from 'vitest';
+
+import type { MeteringService } from '../../../../services/metering/MeteringService.js';
+import { PuterServer } from '../../../../server.js';
+import { setupTestServer } from '../../../../testUtil.js';
+import { kv } from '../../../../util/kvSingleton.js';
+import { withTestActor } from '../../../integrationTestUtil.js';
+import { AIChatStream } from '../../utils/Streaming.js';
+import { InfronProvider } from './InfronProvider.js';
+
+// ── OpenAI SDK mock ─────────────────────────────────────────────────
+
+const { createMock, openAICtor } = vi.hoisted(() => ({
+    createMock: vi.fn(),
+    openAICtor: vi.fn(),
+}));
+
+vi.mock('openai', () => {
+    const OpenAICtor = vi.fn().mockImplementation(function (
+        this: Record<string, unknown>,
+        opts: unknown,
+    ) {
+        openAICtor(opts);
+        this.chat = { completions: { create: createMock } };
+    });
+    return { OpenAI: OpenAICtor, default: { OpenAI: OpenAICtor } };
+});
+
+// ── axios mock (model catalog endpoint) ─────────────────────────────
+
+const { axiosRequestMock } = vi.hoisted(() => ({
+    axiosRequestMock: vi.fn(),
+}));
+
+vi.mock('axios', () => ({
+    default: { request: axiosRequestMock },
+    request: axiosRequestMock,
+}));
+
+// ── Test harness ────────────────────────────────────────────────────
+
+let server: PuterServer;
+let recordSpy: MockInstance<MeteringService['utilRecordUsageObject']>;
+
+const KV_KEY = 'infronChat:models';
+
+// Prices are USD per million tokens (Infron catalog convention).
+const SAMPLE_API_MODELS = [
+    {
+        id: 'deepseek/deepseek-v4-flash',
+        display_name: 'DeepSeek: DeepSeek V4 Flash',
+        category_type: 'LLM',
+        supported_endpoint_types: ['openai'],
+        context_length: 1000000,
+        max_output_tokens: 384000,
+        min_prompt_price: 10,
+        min_completion_price: 30,
+    },
+    {
+        id: 'anthropic/claude-haiku-4.5',
+        display_name: 'Anthropic: Claude Haiku 4.5',
+        category_type: 'LLM',
+        supported_endpoint_types: ['openai'],
+        context_length: 200000,
+        max_output_tokens: 8192,
+        min_prompt_price: 2,
+        min_completion_price: 10,
+    },
+    {
+        // Non-chat modality — filtered out.
+        id: 'black-forest-labs/flux-2.1',
+        display_name: 'FLUX 2.1',
+        category_type: 'Text to Image',
+        supported_endpoint_types: ['openai'],
+        min_request_price: 0.04,
+    },
+    {
+        // Display-only entries are not callable — filtered out.
+        id: 'example/display-only-model',
+        display_name: 'Display Only',
+        category_type: 'LLM',
+        is_display_only: true,
+        supported_endpoint_types: ['openai'],
+    },
+];
+
+const seedModelsCache = () =>
+    axiosRequestMock.mockResolvedValue({ data: { data: SAMPLE_API_MODELS } });
+
+beforeAll(async () => {
+    server = await setupTestServer();
+});
+
+afterAll(async () => {
+    await server?.shutdown();
+});
+
+const makeProvider = () => {
+    const provider = new InfronProvider(
+        { apiKey: 'test-key' },
+        server.services.metering,
+    );
+    return { provider };
+};
+
+const asAsyncIterable = <T>(items: T[]): AsyncIterable<T> => ({
+    async *[Symbol.asyncIterator]() {
+        for (const item of items) {
+            yield item;
+        }
+    },
+});
+
+const makeCapturingChatStream = () => {
+    const chunks: string[] = [];
+    const sink = new Writable({
+        write(chunk, _enc, cb) {
+            chunks.push(chunk.toString('utf8'));
+            cb();
+        },
+    });
+    const chatStream = new AIChatStream({ stream: sink });
+    return {
+        chatStream,
+        events: () =>
+            chunks
+                .join('')
+                .split('\n')
+                .filter(Boolean)
+                .map((line) => JSON.parse(line)),
+    };
+};
+
+beforeEach(() => {
+    createMock.mockReset();
+    openAICtor.mockReset();
+    axiosRequestMock.mockReset();
+    seedModelsCache();
+    kv.del(KV_KEY);
+    recordSpy = vi.spyOn(server.services.metering, 'utilRecordUsageObject');
+});
+
+afterEach(() => {
+    vi.restoreAllMocks();
+    kv.del(KV_KEY);
+});
+
+// ── Construction ────────────────────────────────────────────────────
+
+describe('InfronProvider construction', () => {
+    it('points the OpenAI SDK at the Infron base URL with the configured key', () => {
+        makeProvider();
+        expect(openAICtor).toHaveBeenCalledTimes(1);
+        expect(openAICtor).toHaveBeenCalledWith({
+            apiKey: 'test-key',
+            baseURL: 'https://llm.onerouter.pro/v1',
+        });
+    });
+
+    it('honours an apiBaseUrl override', () => {
+        new InfronProvider(
+            {
+                apiKey: 'test-key',
+                apiBaseUrl: 'https://custom.infron.example/v1',
+            },
+            server.services.metering,
+        );
+        expect(openAICtor).toHaveBeenLastCalledWith({
+            apiKey: 'test-key',
+            baseURL: 'https://custom.infron.example/v1',
+        });
+    });
+});
+
+// ── Model catalog ───────────────────────────────────────────────────
+
+describe('InfronProvider model catalog', () => {
+    it('returns the infron-prefixed default model id', () => {
+        const { provider } = makeProvider();
+        expect(provider.getDefaultModel()).toBe(
+            'infron:deepseek/deepseek-v4-flash',
+        );
+    });
+
+    it('sends the API key as a bearer token on the catalog fetch', async () => {
+        const { provider } = makeProvider();
+        await provider.models();
+        const [args] = axiosRequestMock.mock.calls[0]!;
+        expect(args.url).toBe('https://llm.onerouter.pro/v1/models');
+        expect(args.headers).toMatchObject({
+            Authorization: 'Bearer test-key',
+        });
+    });
+
+    it('list() prefixes ids with infron: and filters non-chat and display-only entries', async () => {
+        const { provider } = makeProvider();
+        const ids = await provider.list();
+        expect(ids).toContain('infron:deepseek/deepseek-v4-flash');
+        expect(ids).toContain('infron:anthropic/claude-haiku-4.5');
+        expect(ids).not.toContain('infron:black-forest-labs/flux-2.1');
+        expect(ids).not.toContain('infron:example/display-only-model');
+    });
+
+    it('caches the model list in kv after the first axios round-trip', async () => {
+        const { provider } = makeProvider();
+        await provider.models();
+        await provider.models();
+        // Second call should be a cache hit, not a second axios request.
+        expect(axiosRequestMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('converts USD-per-million-token prices to microcents per token', async () => {
+        const { provider } = makeProvider();
+        const models = await provider.models();
+        // $10/M tokens → 10 * 100 = 1000 microcents per token.
+        expect(models).toEqual(
+            expect.arrayContaining([
+                expect.objectContaining({
+                    id: 'infron:deepseek/deepseek-v4-flash',
+                    costs: expect.objectContaining({
+                        tokens: 1_000_000,
+                        prompt: 1000,
+                        completion: 3000,
+                    }),
+                }),
+            ]),
+        );
+    });
+});
+
+// ── Request shape ──────────────────────────────────────────────────
+
+describe('InfronProvider.complete request shape', () => {
+    const baseCompletion = {
+        choices: [
+            {
+                message: { content: 'hi', role: 'assistant' },
+                finish_reason: 'stop',
+            },
+        ],
+        usage: { prompt_tokens: 1, completion_tokens: 1 },
+        cost: 0,
+    };
+
+    it('strips the infron: prefix from the wire model id', async () => {
+        const { provider } = makeProvider();
+        createMock.mockResolvedValueOnce(baseCompletion);
+
+        await withTestActor(() =>
+            provider.complete({
+                model: 'infron:deepseek/deepseek-v4-flash',
+                messages: [{ role: 'user', content: 'hello' }],
+            }),
+        );
+
+        const [args] = createMock.mock.calls[0]!;
+        // infron: prefix is dropped before the SDK call.
+        expect(args.model).toBe('deepseek/deepseek-v4-flash');
+        // Infron requires `usage: { include: true }` to surface the
+        // cost field — the provider always sets this.
+        expect(args.usage).toEqual({ include: true });
+    });
+
+    it('only sets stream_options.include_usage when streaming', async () => {
+        const { provider } = makeProvider();
+
+        createMock.mockResolvedValueOnce(baseCompletion);
+        await withTestActor(() =>
+            provider.complete({
+                model: 'infron:deepseek/deepseek-v4-flash',
+                messages: [{ role: 'user', content: 'hi' }],
+                stream: false,
+            }),
+        );
+        expect(createMock.mock.calls[0]![0].stream).toBe(false);
+        expect('stream_options' in createMock.mock.calls[0]![0]).toBe(false);
+
+        createMock.mockReturnValueOnce(asAsyncIterable([]));
+        await withTestActor(() =>
+            provider.complete({
+                model: 'infron:deepseek/deepseek-v4-flash',
+                messages: [{ role: 'user', content: 'hi' }],
+                stream: true,
+            }),
+        );
+        expect(createMock.mock.calls[1]![0].stream_options).toEqual({
+            include_usage: true,
+        });
+    });
+});
+
+// ── Non-stream completion: cost calculator branches ─────────────────
+
+describe('InfronProvider.complete non-stream output', () => {
+    it('uses the cost-bearing branch when the top-level cost is present', async () => {
+        const { provider } = makeProvider();
+        createMock.mockResolvedValueOnce({
+            choices: [
+                {
+                    message: { content: 'hi there', role: 'assistant' },
+                    finish_reason: 'stop',
+                },
+            ],
+            usage: {
+                prompt_tokens: 100,
+                completion_tokens: 50,
+                prompt_tokens_details: { cached_tokens: 10 },
+            },
+            // Infron reports cost at the top level of the completion,
+            // not inside `usage`.
+            cost: 0.0001,
+        });
+
+        const result = (await withTestActor(() =>
+            provider.complete({
+                model: 'infron:deepseek/deepseek-v4-flash',
+                messages: [{ role: 'user', content: 'hi' }],
+            }),
+        )) as { usage: Record<string, number> };
+
+        // The cost-bearing branch zeroes per-token costs and bills via a
+        // single `billedUsage` line item priced at cost * 1e8.
+        expect(recordSpy).toHaveBeenCalledTimes(1);
+        const [usage, , prefix, overrides] = recordSpy.mock.calls[0]!;
+        expect(prefix).toBe('infron:deepseek/deepseek-v4-flash');
+        expect(usage).toMatchObject({
+            prompt: 100 - 10, // prompt_tokens - cached
+            completion: 50,
+            input_cache_read: 10,
+            billedUsage: 1,
+        });
+        // All per-token costs are zeroed so Infron's authoritative
+        // cost is the only thing that bills.
+        expect(overrides.prompt).toBe(0);
+        expect(overrides.completion).toBe(0);
+        expect(overrides.input_cache_read).toBe(0);
+        expect(overrides.billedUsage).toBe(0.0001 * 100_000_000);
+        // The returned usage exposes usd_cents derived from cost.
+        expect(result.usage.usd_cents).toBe(0.0001 * 100);
+    });
+
+    it('falls back to per-token pricing when cost is absent', async () => {
+        const { provider } = makeProvider();
+        createMock.mockResolvedValueOnce({
+            choices: [
+                {
+                    message: { content: 'ok', role: 'assistant' },
+                    finish_reason: 'stop',
+                },
+            ],
+            // No top-level `cost` → fallback branch.
+            usage: {
+                prompt_tokens: 100,
+                completion_tokens: 50,
+                prompt_tokens_details: { cached_tokens: 10 },
+            },
+        });
+
+        await withTestActor(() =>
+            provider.complete({
+                model: 'infron:deepseek/deepseek-v4-flash',
+                messages: [{ role: 'user', content: 'hi' }],
+            }),
+        );
+
+        // deepseek-v4-flash catalog pricing converted to microcents per
+        // token: prompt=$10/M → 1000, completion=$30/M → 3000; cache
+        // reads fall back to the full prompt rate.
+        const [usage, , , overrides] = recordSpy.mock.calls[0]!;
+        expect(usage).toMatchObject({
+            prompt: 90,
+            completion: 50,
+            input_cache_read: 10,
+        });
+        expect(overrides.prompt).toBe(90 * 1000);
+        expect(overrides.completion).toBe(50 * 3000);
+        expect(overrides.input_cache_read).toBe(10 * 1000);
+    });
+});
+
+// ── Streaming deltas ────────────────────────────────────────────────
+
+describe('InfronProvider.complete streaming', () => {
+    it('streams text deltas through to text events and meters the final-chunk cost', async () => {
+        const { provider } = makeProvider();
+        createMock.mockReturnValueOnce(
+            asAsyncIterable([
+                { choices: [{ delta: { content: 'hel' } }] },
+                { choices: [{ delta: { content: 'lo' } }] },
+                {
+                    choices: [{ delta: {} }],
+                    usage: {
+                        prompt_tokens: 4,
+                        completion_tokens: 2,
+                    },
+                    // Cost rides at the top level of the final chunk.
+                    cost: 0.00005,
+                },
+            ]),
+        );
+
+        const result = await withTestActor(() =>
+            provider.complete({
+                model: 'infron:deepseek/deepseek-v4-flash',
+                messages: [{ role: 'user', content: 'say hi' }],
+                stream: true,
+            }),
+        );
+        expect((result as { stream: boolean }).stream).toBe(true);
+
+        const harness = makeCapturingChatStream();
+        await (
+            result as {
+                init_chat_stream: (p: { chatStream: unknown }) => Promise<void>;
+            }
+        ).init_chat_stream({ chatStream: harness.chatStream });
+
+        const events = harness.events();
+        const textEvents = events.filter((e) => e.type === 'text');
+        expect(textEvents.map((e) => e.text)).toEqual(['hel', 'lo']);
+
+        // Cost-branch metering on the final chunk.
+        expect(recordSpy).toHaveBeenCalledTimes(1);
+        const [, , prefix, overrides] = recordSpy.mock.calls[0]!;
+        expect(prefix).toBe('infron:deepseek/deepseek-v4-flash');
+        expect(overrides.billedUsage).toBe(0.00005 * 100_000_000);
+    });
+});
+
+// ── Moderation ──────────────────────────────────────────────────────
+
+describe('InfronProvider.checkModeration', () => {
+    it('throws — Infron provider does not implement moderation', () => {
+        const { provider } = makeProvider();
+        expect(() => provider.checkModeration('anything')).toThrow(
+            /not implemented/i,
+        );
+    });
+});

src/backend/drivers/ai-chat/providers/infron/InfronProvider.ts

@@ -0,0 +1,291 @@
+/*
+ * 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 axios from 'axios';
+import { OpenAI } from 'openai';
+import { ChatCompletionCreateParams } from 'openai/resources';
+import { Context } from '../../../../core/context.js';
+import type { MeteringService } from '../../../../services/metering/MeteringService.js';
+import { kv } from '../../../../util/kvSingleton.js';
+import * as OpenAIUtil from '../../utils/OpenAIUtil.js';
+import type {
+    IChatModel,
+    IChatProvider,
+    IChatCompleteResult,
+    ICompleteArguments,
+} from '../../types.js';
+
+/**
+ * Shape of one entry in Infron's `GET /v1/models` catalog. Unlike OpenRouter
+ * there is no `pricing` object; prices are USD per million tokens in
+ * `min_prompt_price` / `min_completion_price`, and the catalog mixes non-chat
+ * modalities (image, video, embeddings) that this provider filters out via
+ * `category_type`.
+ */
+type InfronApiModel = {
+    id: string;
+    display_name?: string;
+    category_type?: string;
+    is_display_only?: boolean;
+    supported_endpoint_types?: string[];
+    context_length?: number;
+    max_output_tokens?: number;
+    min_prompt_price?: number;
+    min_completion_price?: number;
+    min_request_price?: number;
+};
+
+type InfronUsage = OpenAI.Completions.CompletionUsage & {
+    cost?: number;
+};
+
+const KV_MODELS_KEY = 'infronChat:models';
+
+export class InfronProvider implements IChatProvider {
+    #meteringService: MeteringService;
+
+    #openai: OpenAI;
+
+    #apiKey: string;
+
+    #apiBaseUrl: string = 'https://llm.onerouter.pro/v1';
+
+    constructor(
+        config: { apiBaseUrl?: string; apiKey: string },
+        meteringService: MeteringService,
+    ) {
+        this.#apiBaseUrl = config.apiBaseUrl || 'https://llm.onerouter.pro/v1';
+        this.#apiKey = config.apiKey;
+        this.#openai = new OpenAI({
+            apiKey: config.apiKey,
+            baseURL: this.#apiBaseUrl,
+        });
+        this.#meteringService = meteringService;
+    }
+
+    getDefaultModel() {
+        return 'infron:deepseek/deepseek-v4-flash';
+    }
+
+    /**
+     * Returns a list of available model names
+     *
+     * @returns {Promise<string[]>} Array of model identifiers
+     */
+    async list() {
+        const models = await this.models();
+        const model_names: string[] = [];
+        for (const model of models) {
+            model_names.push(model.id);
+        }
+        return model_names;
+    }
+
+    /** AI Chat completion method. See AIChatService for more details. */
+    async complete({
+        messages,
+        stream,
+        model,
+        tools,
+        max_tokens,
+        temperature,
+    }: ICompleteArguments): Promise<IChatCompleteResult> {
+        const availableModels = await this.models();
+        const modelUsed =
+            availableModels.find((m) =>
+                [m.id, ...(m.aliases || [])].includes(model),
+            ) || availableModels.find((m) => m.id === this.getDefaultModel())!;
+
+        const modelIdForParams = modelUsed.id.startsWith('infron:')
+            ? modelUsed.id.slice('infron:'.length)
+            : modelUsed.id;
+
+        const actor = Context.get('actor');
+
+        messages = await OpenAIUtil.process_input_messages(messages);
+
+        const completionParams = {
+            messages,
+            model: modelIdForParams,
+            ...(tools ? { tools } : {}),
+            max_tokens,
+            temperature,
+            stream,
+            ...(stream
+                ? {
+                      stream_options: { include_usage: true },
+                  }
+                : {}),
+            // Surfaces the authoritative `cost` field (USD) on the
+            // response so metering doesn't depend on catalog prices.
+            usage: { include: true },
+        } as ChatCompletionCreateParams;
+
+        const completion =
+            await this.#openai.chat.completions.create(completionParams);
+
+        const usage_calculator = ({
+            usage,
+            cost,
+        }: {
+            usage: InfronUsage;
+            cost?: number;
+        }) => {
+            // Infron reports `cost` at the top level of the response, not
+            // inside `usage`. Non-streaming calls get it via the spread
+            // completion below; streaming injects it into `usage` via the
+            // `index_usage_from_stream_chunk` deviation.
+            const authoritativeCost =
+                typeof cost === 'number' ? cost : usage.cost;
+            const trackedUsage = {
+                prompt:
+                    (usage.prompt_tokens ?? 0) -
+                    (usage.prompt_tokens_details?.cached_tokens ?? 0),
+                completion: usage.completion_tokens ?? 0,
+                input_cache_read:
+                    usage.prompt_tokens_details?.cached_tokens ?? 0,
+                request: 1,
+            };
+            if (typeof authoritativeCost === 'number') {
+                // Bill the gateway-reported cost as a single line item and
+                // zero the per-token costs so nothing double-bills.
+                const billedTrackedUsage = { ...trackedUsage, billedUsage: 1 };
+                const costOverwrites = Object.fromEntries(
+                    Object.keys(billedTrackedUsage).map((k) => [k, 0]),
+                );
+                costOverwrites.billedUsage =
+                    authoritativeCost * 100_000_000 || 1;
+                this.#meteringService.utilRecordUsageObject(
+                    billedTrackedUsage,
+                    actor,
+                    modelUsed.id,
+                    costOverwrites,
+                );
+                (billedTrackedUsage as Record<string, number>).usd_cents =
+                    authoritativeCost * 100;
+                return billedTrackedUsage;
+            }
+            // Fallback: per-token pricing from the model catalog.
+            const costOverwrites = Object.fromEntries(
+                Object.keys(trackedUsage).map((k) => {
+                    return [
+                        k,
+                        (modelUsed.costs[k] ?? 0) *
+                            trackedUsage[k as keyof typeof trackedUsage],
+                    ];
+                }),
+            );
+            this.#meteringService.utilRecordUsageObject(
+                trackedUsage,
+                actor,
+                modelUsed.id,
+                costOverwrites,
+            );
+            return trackedUsage;
+        };
+
+        return OpenAIUtil.handle_completion_output({
+            deviations: {
+                index_usage_from_stream_chunk: (chunk: {
+                    usage?: InfronUsage;
+                    cost?: number;
+                }) =>
+                    chunk.usage
+                        ? { ...chunk.usage, cost: chunk.cost }
+                        : chunk.usage,
+            },
+            usage_calculator,
+            stream,
+            completion,
+        });
+    }
+
+    async models() {
+        let models = kv.get(KV_MODELS_KEY) as InfronApiModel[] | undefined;
+        if (!models) {
+            try {
+                const resp = await axios.request({
+                    method: 'GET',
+                    url: `${this.#apiBaseUrl}/models`,
+                    // Infron requires authentication on the catalog endpoint.
+                    headers: {
+                        Authorization: `Bearer ${this.#apiKey}`,
+                    },
+                });
+
+                models = resp.data.data;
+                kv.set(KV_MODELS_KEY, models, { EX: 15 * 60 }); // cache for 15 minutes
+            } catch (e) {
+                console.log(e);
+            }
+        }
+        if (!models) return [];
+        const coerced_models: IChatModel[] = [];
+        for (const model of models) {
+            // The catalog mixes chat with image/video/embedding/search
+            // models — only chat-completion-capable models belong here.
+            if (model.category_type !== 'LLM') continue;
+            if (model.is_display_only) continue;
+            if (!(model.supported_endpoint_types ?? []).includes('openai')) {
+                continue;
+            }
+            // Catalog prices are USD per million tokens; costs are
+            // microcents per token, so the conversion is ×100.
+            const promptCost = Math.round((model.min_prompt_price ?? 0) * 100);
+            coerced_models.push({
+                id: `infron:${model.id}`,
+                name: `${model.display_name || model.id} (Infron)`,
+                aliases: [
+                    model.id,
+                    ...(model.display_name ? [model.display_name] : []),
+                    `infron/${model.id}`,
+                    model.id.split('/').slice(1).join('/'),
+                ],
+                context: model.context_length,
+                max_tokens: model.max_output_tokens ?? 0,
+                costs_currency: 'usd-cents',
+                input_cost_key: 'prompt',
+                output_cost_key: 'completion',
+                costs: {
+                    tokens: 1_000_000,
+                    prompt: promptCost,
+                    completion: Math.round(
+                        (model.min_completion_price ?? 0) * 100,
+                    ),
+                    // The catalog carries no cache-read price; charge the
+                    // full prompt rate in the fallback path so cached
+                    // tokens are never billed below list. The normal path
+                    // bills the gateway-reported cost instead.
+                    input_cache_read: promptCost,
+                    // USD per request → microcents per request.
+                    request: Math.round(
+                        (model.min_request_price ?? 0) * 1_000_000 * 100,
+                    ),
+                },
+            });
+        }
+        return coerced_models;
+    }
+
+    checkModeration(
+        _text: string,
+    ): ReturnType<IChatProvider['checkModeration']> {
+        throw new Error('Method not implemented.');
+    }
+}

src/backend/drivers/ai-chat/providers/moonshot/MoonshotProvider.test.ts

@@ -202,7 +202,25 @@ describe('MoonshotProvider.complete request shape', () => {
         usage: { prompt_tokens: 1, completion_tokens: 1 },
     };
 
-    it('forwards model + messages and locks max_tokens=1000', async () => {
+    it('forwards model + messages and passes max_tokens through unchanged', async () => {
+        const { provider } = makeProvider();
+        createMock.mockResolvedValueOnce(baseCompletion);
+
+        await withTestActor(() =>
+            provider.complete({
+                model: 'kimi-k2.6',
+                messages: [{ role: 'user', content: 'hello' }],
+                max_tokens: 2048,
+            }),
+        );
+
+        const [args] = createMock.mock.calls[0]!;
+        expect(args.model).toBe('kimi-k2.6');
+        expect(args.messages).toEqual([{ role: 'user', content: 'hello' }]);
+        expect(args.max_tokens).toBe(2048);
+    });
+
+    it('forwards max_tokens as undefined when not supplied', async () => {
         const { provider } = makeProvider();
         createMock.mockResolvedValueOnce(baseCompletion);
 
@@ -214,11 +232,7 @@ describe('MoonshotProvider.complete request shape', () => {
         );
 
         const [args] = createMock.mock.calls[0]!;
-        expect(args.model).toBe('kimi-k2.6');
-        expect(args.messages).toEqual([{ role: 'user', content: 'hello' }]);
-        // max_tokens is hardcoded by the provider — the call to Moonshot
-        // should always cap at 1000 tokens of completion.
-        expect(args.max_tokens).toBe(1000);
+        expect(args.max_tokens).toBeUndefined();
     });
 
     it('omits the `tools` key entirely when no tools are supplied', async () => {

src/backend/drivers/ai-chat/providers/moonshot/MoonshotProvider.ts

@@ -21,12 +21,12 @@ import { OpenAI } from 'openai';
 import { ChatCompletionCreateParams } from 'openai/resources/index.js';
 import { Context } from '../../../../core/context.js';
 import type { MeteringService } from '../../../../services/metering/MeteringService.js';
-import * as OpenAIUtil from '../../utils/OpenAIUtil.js';
 import type {
+    IChatCompleteResult,
     IChatProvider,
     ICompleteArguments,
-    IChatCompleteResult,
 } from '../../types.js';
+import * as OpenAIUtil from '../../utils/OpenAIUtil.js';
 import { inlineHttpImageUrls } from './imageHandling.js';
 import { MOONSHOT_MODELS } from './models.js';
 
@@ -68,6 +68,7 @@ export class MoonshotProvider implements IChatProvider {
         stream,
         model,
         tools,
+        max_tokens,
     }: ICompleteArguments): Promise<IChatCompleteResult> {
         const actor = Context.get('actor');
         const availableModels = this.models();
@@ -89,7 +90,7 @@ export class MoonshotProvider implements IChatProvider {
                 messages,
                 model: modelUsed.id,
                 ...(tools ? { tools } : {}),
-                max_tokens: 1000,
+                max_tokens,
                 stream,
                 ...(stream
                     ? {

src/backend/drivers/ai-chat/providers/moonshot/models.ts

@@ -21,6 +21,27 @@ import type { IChatModel } from '../../types.js';
 
 export const MOONSHOT_MODELS: IChatModel[] = [
     // -- Flagship ----------------------------------------------------
+    {
+        puterId: 'moonshotai:moonshotai/kimi-k3',
+        id: 'kimi-k3',
+        name: 'Kimi K3',
+        aliases: ['moonshotai/kimi-k3', 'moonshot/kimi-k3'],
+        modalities: { input: ['text', 'image', 'video'], output: ['text'] },
+        costs_currency: 'usd-cents',
+        input_cost_key: 'prompt_tokens',
+        output_cost_key: 'completion_tokens',
+        costs: {
+            tokens: 1_000_000,
+            prompt_tokens: 300, // $3.00 per 1M
+            completion_tokens: 1500, // $15.00 per 1M
+            cached_tokens: 30, // $0.30 per 1M
+        },
+        context: 1_048_576,
+        max_tokens: 1_048_576,
+        tool_call: true,
+    },
+
+    // -- Kimi K2.6 --------------------------------------------------
     {
         puterId: 'moonshotai:moonshotai/kimi-k2.6',
         id: 'kimi-k2.6',

src/backend/drivers/ai-chat/providers/openai/models.ts

@@ -23,6 +23,74 @@ import type { IChatModel } from '../../types.js';
 
 // Hardcoded from https://models.dev/api.json
 export const OPEN_AI_MODELS: IChatModel[] = [
+    {
+        puterId: 'openai:openai/gpt-5.6-sol',
+        id: 'gpt-5.6-sol',
+        modalities: { input: ['text', 'image'], output: ['text'] },
+        open_weights: false,
+        tool_call: true,
+        knowledge: '2026-02-16',
+        aliases: [
+            'gpt-5.6',
+            'gpt-5.6-sol',
+            'openai/gpt-5.6',
+            'openai/gpt-5.6-sol',
+        ],
+        costs_currency: 'usd-cents',
+        input_cost_key: 'prompt_tokens',
+        output_cost_key: 'completion_tokens',
+        costs: {
+            tokens: 1_000_000,
+            prompt_tokens: 500,
+            cached_tokens: 50,
+            completion_tokens: 3000,
+        },
+        context: 1_050_000,
+        max_tokens: 128_000,
+        responses_api_only: true,
+    },
+    {
+        puterId: 'openai:openai/gpt-5.6-terra',
+        id: 'gpt-5.6-terra',
+        modalities: { input: ['text', 'image'], output: ['text'] },
+        open_weights: false,
+        tool_call: true,
+        knowledge: '2026-02-16',
+        aliases: ['gpt-5.6-terra', 'openai/gpt-5.6-terra'],
+        costs_currency: 'usd-cents',
+        input_cost_key: 'prompt_tokens',
+        output_cost_key: 'completion_tokens',
+        costs: {
+            tokens: 1_000_000,
+            prompt_tokens: 250,
+            cached_tokens: 25,
+            completion_tokens: 1500,
+        },
+        context: 1_050_000,
+        max_tokens: 128_000,
+        responses_api_only: true,
+    },
+    {
+        puterId: 'openai:openai/gpt-5.6-luna',
+        id: 'gpt-5.6-luna',
+        modalities: { input: ['text', 'image'], output: ['text'] },
+        open_weights: false,
+        tool_call: true,
+        knowledge: '2026-02-16',
+        aliases: ['gpt-5.6-luna', 'openai/gpt-5.6-luna'],
+        costs_currency: 'usd-cents',
+        input_cost_key: 'prompt_tokens',
+        output_cost_key: 'completion_tokens',
+        costs: {
+            tokens: 1_000_000,
+            prompt_tokens: 100,
+            cached_tokens: 10,
+            completion_tokens: 600,
+        },
+        context: 1_050_000,
+        max_tokens: 128_000,
+        responses_api_only: true,
+    },
     {
         puterId: 'openai:openai/gpt-5.5',
         id: 'gpt-5.5-2026-04-23',