fix: kv max number value (#3629)

* docs: remove Discord and Reddit links

Drops both links from the docs README (header row and Support list) and
from the footer generated on every built docs page.

* docs: remove Mastodon link

.env.example

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

.github/workflows/backend-tests.yaml

@@ -13,6 +13,9 @@ on:
       - 'tools/**'
       - 'package.json'
       - 'package-lock.json'
+      # The type-check job below reads these.
+      - 'tsconfig.json'
+      - 'tsconfig.build.json'
       - '.github/workflows/backend-tests.yaml'
 
 permissions:
@@ -20,6 +23,35 @@ permissions:
   pull-requests: write
 
 jobs:
+  # `tsconfig.build.json` builds with `noCheck: true`, so nothing else in CI
+  # runs the type checker and a missing export compiles to `undefined`,
+  # surfacing only when the call is finally reached at runtime. This diffs
+  # against tools/typecheck-baseline.json and fails only on *new* errors.
+  #
+  # The consuming repo runs an equivalent gate, but only once someone bumps the
+  # submodule pointer — too late to keep the error off this repo's default
+  # branch. Hence a gate here, on this repo's own pull requests.
+  #
+  # Its own job rather than a step in `test`: that one runs a base/PR matrix for
+  # coverage comparison, and the check only needs the PR ref, once.
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check (new errors only)
+        run: npm run typecheck
+
   test:
     runs-on: ubuntu-latest
     strategy:

.github/workflows/docker-image.yaml

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

.github/workflows/puterjs-tests.yaml

@@ -23,6 +23,33 @@ permissions:
   pull-requests: write
 
 jobs:
+  # The JSDoc in src/puter-js/src is the source of truth for the SDK's public
+  # types. The declarations shipped to npm are generated from it at build time
+  # and never committed, so what needs guarding is the JSDoc itself: this
+  # generates the declarations and type-checks the published surface without
+  # skipLibCheck, which is how broken re-exports used to go unnoticed.
+  #
+  # Its own job rather than a step in `test`: that one builds bundles and
+  # installs a browser, and this needs neither.
+  types:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check the puter.js JSDoc produces declarations that type-check
+        run: npm run check:puterjs:types
+
   test:
     runs-on: ubuntu-latest
 

AGENTS.md

@@ -10,6 +10,7 @@ Use these as the source of truth before exploring further:
 - [doc/architecture.md](doc/architecture.md) — backend layered stack (controllers → drivers → services → stores → clients), `PuterServer` wiring, `Context` (ALS), and extensions.
 - [doc/contributing-apis.md](doc/contributing-apis.md) — adding and maintaining public APIs end to end (backend surface → puter.js → types → docs → tests). Follow it for any API work.
 - [doc/pagination.md](doc/pagination.md) — the one pagination convention for list APIs (limit/cursor/offset/includeTotal, envelope shape, cursor semantics).
+- [doc/alarms.md](doc/alarms.md) — raising alarms and picking a severity (what pages, what only gets recorded), plus the config that routes them.
 - [doc/self-hosting.md](doc/self-hosting.md) — running Puter outside hosted infra.
 - [CONTRIBUTING.md](CONTRIBUTING.md) — testing, security, AI-assisted code, PR conventions, Boy Scout Rule.
 - [SECURITY.md](SECURITY.md) — how to report vulnerabilities (do not file them publicly).
@@ -51,6 +52,7 @@ When in doubt, return less. Auth-, permission-, or data-export-related changes d
 - **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.
+- **A limit change is not done until the docs change with it.** Every rate limit, concurrency cap, quota, and allowance in the code is published in [src/docs/src/rate-limits-and-quotas.md](src/docs/src/rate-limits-and-quotas.md) — an undisclosed limit is one developers discover as a service failure. If a PR moves any of these numbers, the same PR updates that page. The numbers live in `src/backend/controllers/fs/limits.ts` (filesystem), `src/backend/drivers/util/aiLimits.ts` (all AI drivers), per-driver `rateLimit`/`concurrent` configs, and `src/backend/data/subPolicies/` (free-tier allowances).
 
 ---
 
@@ -97,24 +99,23 @@ Follow the same layered structure inside an extension — unless it only needs a
 
 [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/).
+Layout: SDK modules in [src/puter-js/src/modules/](src/puter-js/src/modules/) (one file or directory per area — `FileSystem/`, `kv/`, `ai/`, …), shared plumbing in [src/puter-js/src/lib/](src/puter-js/src/lib/), generated (gitignored) type declarations in `src/puter-js/types/`, API tests in [src/puter-js/tests/api/](src/puter-js/tests/api/), UI e2e tests in [src/puter-js/tests/e2e/](src/puter-js/tests/e2e/), developer docs in [src/docs/](src/docs/).
 
-Language & typing: puter.js source is plain JavaScript — never TypeScript files — typed via JSDoc. Reference the hand-maintained declarations in [src/puter-js/types/](src/puter-js/types/) with `import(...)` types rather than re-declaring shapes:
+Language & typing: puter.js source is plain JavaScript — never TypeScript files — typed via JSDoc. **The JSDoc is the source of truth for the SDK's types.** `src/puter-js/types/` is `tsc --emitDeclarationOnly` output: the SDK build (`npm run build` in `src/puter-js`) generates it, the npm tarball ships it so TypeScript consumers get declarations, and git ignores it — it is never committed and never edited by hand. `npm run check:puterjs:types` generates it in CI and type-checks the result without `skipLibCheck`. The one hand-written declaration file is [src/puter-js/index.d.ts](src/puter-js/index.d.ts), which decides what is public and re-exports the generated names.
+
+Declare a shape where it belongs, and reference it with an `import(...)` type from elsewhere. A shape more than one file needs lives in the module's `types.js`; a shape shared across modules lives in [src/puter-js/src/lib/types.js](src/puter-js/src/lib/types.js); a shape with one consumer can stay next to it:
 
 ```js
-/** @typedef {import('../../types/modules/ai').ChatOptions} ChatOptions */
-
-/** @type {ChatOptions} */
-const options = { model: 'gpt-5-nano' };
+/** @typedef {import('./types.js').KVOptConfig} KVOptConfig */
 ```
 
-When a shape only exists locally, declare it as an inline object literal — not the `@typedef {Object}` + `@property` list form — and use `unknown` over `*`:
+Use `@typedef {Object}` + `@property` for any shape whose fields need documenting — it is the only JSDoc form that carries a doc comment per field into the generated declaration. Keep the inline object-literal form for small internal shapes with nothing to say about each field, and prefer `unknown` over `*`:
 
 ```js
 /** @typedef {{ key: string, value: unknown }} KVEntry */
 ```
 
-Public (exposed) methods must carry JSDoc types — parameters and return value, 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.
+Public (exposed) methods must carry JSDoc types — parameters and return value — with one `@overload` block per accepted call form, since those overloads *are* the published signature. Unexposed/private helpers are typed at the contributor's discretion: annotate where it helps the next reader, and either way keep them clean. Members tagged `@internal` are stripped from the generated declarations, so use that tag rather than `@private` to keep something off the public surface.
 
 Typing in JS files is encouraged: annotate with JSDoc `@type`/`@param`/`@returns` using the TypeScript type system, and define shared shapes with `@typedef`. API types must not be `unknown` or untyped `...args` — spell out the real parameter and return shapes; the only exception is values passed through transparently to an upstream layer that owns their type. For example:
 
@@ -132,7 +133,7 @@ Every SDK change carries all five of the following — a puter.js PR missing one
 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.
+4. **Types.** Type the change in JSDoc on the implementation, then run `npm run check:puterjs:types` to confirm it still produces declarations that type-check. Name any new type in [src/puter-js/index.d.ts](src/puter-js/index.d.ts) if consumers should be able to import it. Declarations must match runtime behavior exactly — a wrong type is worse than a missing one.
 5. **Error handling.** Reject/throw `{ message, code }` objects with stable `snake_case` codes, matching the existing modules (see `KV.js`). Validate cheap preconditions client-side before making the network call; pass backend errors through unchanged rather than swallowing or re-wrapping them. Error codes are API surface — changing one is a breaking change.
 
 [doc/contributing-apis.md](doc/contributing-apis.md) walks the full lifecycle of adding an API across backend + SDK.

BUG-BOUNTY.md

@@ -6,33 +6,33 @@ We at **Puter** are committed to maintaining a secure experience for our users a
 
 The following are in scope for this program:
 
-* **The Puter open-source project** (available at [github.com/HeyPuter/puter](https://github.com/HeyPuter/puter))
-* **`puter.com`**
-* **`api.puter.com`**
+- **The Puter open-source project** (available at [github.com/HeyPuter/puter](https://github.com/HeyPuter/puter))
+- **`puter.com`**
+- **`api.puter.com`**
 
 Out-of-scope:
 
-* Third-party services, applications, or libraries not maintained by Puter.
-* Social engineering attacks (e.g., phishing against staff).
-* Denial of Service (DoS), spam, or volumetric attacks.
-* Physical security issues.
+- Third-party services, applications, or libraries not maintained by Puter.
+- Social engineering attacks (e.g., phishing against staff).
+- Denial of Service (DoS), spam, or volumetric attacks.
+- Physical security issues.
 
 ## Known Non-Issues (Please Check Before Submitting)
 
 The following have already been reviewed and determined **not to be vulnerabilities**. Reports that only re-describe one of these are **not eligible for a reward** and will be closed as non-issues — even if they include new code references. Please review this list before submitting:
 
-* **XSS / CORS / token issues scoped to `api.puter.com`.** The primary user session cookie lives on `puter.com`, not on the API origin, so reflected/stored XSS, CORS, or token handling on `api.puter.com` is generally out of scope. Two exceptions we *do* evaluate on their merits — please report these: (a) attacker-controlled content served **inline** (e.g. an HTML `Content-Type`) from API file/response endpoints, and (b) anything that abuses the app-scoped `puter_token_v2` companion cookie set on the API host.
-* **SSRF via `secureFetch`.** Production routes outbound requests through an isolated proxy that has no access to internal/SSRF-sensitive resources.
-* **Attacks that depend on guessing an `appInstanceID` or app UID.** These are random 128-bit secret values and are not considered guessable.
-* **Apps invoking drivers, creating workers, or using KV.** Applications are intended to do this; worker permissions are scoped to the owning app. This is by design.
-* **App metadata or app user-count "leaks".** This information is currently public by design.
-* **General "token in a URL" / token-lifetime designs** — signed directory URLs exposing children, a write signature implying read, or app tokens outliving a web session. These are current intended behaviors.
-* **Missing PKCE, unverified `id_token` signatures, or other OIDC hardening.** Provider tokens are obtained through a server-to-server authorization-code exchange with the provider's token endpoint over TLS, so the resulting `id_token` / userinfo claims are trusted from that channel rather than from local JWKS signature verification — the callback never accepts a caller-supplied `id_token`. Adding local signature / `aud` / `iss` / `exp` checks is welcome defense-in-depth (please open a GitHub issue/PR), but their absence is not an account-takeover vector on its own.
-* **JWT "algorithm confusion" / unpinned `algorithms` in `jwt.verify`.** Puter's session tokens are HMAC-signed (HS256) with a server-side secret, and there is no asymmetric public key anywhere in the verification path, so `alg`-substitution attacks do not apply. Explicitly pinning `algorithms` is a fine hardening PR, but it is not a vulnerability.
-* **Static-source "SQL injection" in internal pagination.** Findings such as `LIMIT ${limit}` in list/notification queries: the limit is numerically coerced and clamped before it reaches the query, so it is not reachable with attacker-controlled string input. Hardening PRs to the internal stores are welcome, but these are not exploitable as reported.
-* **Deprecated `saveTo*` GUI app messages.** The legacy `saveToDesktop` / `saveToDocuments` / etc. app-IPC handlers can create — never overwrite — new files in standard user folders. The behavior is non-destructive, path-traversal-safe, and deprecated (slated for removal); it is not treated as a sandbox escape.
-* **Best-practice suggestions** such as login/registration username enumeration (kept intentionally for UX) or unauthenticated unsubscribe links (industry norm).
-* **Rate-limiting suggestions for TURN credential issuance** (intentional; not billed per tunnel).
+- **XSS / CORS / token issues scoped to `api.puter.com`.** The primary user session cookie lives on `puter.com`, not on the API origin, so reflected/stored XSS, CORS, or token handling on `api.puter.com` is generally out of scope. Two exceptions we _do_ evaluate on their merits — please report these: (a) attacker-controlled content served **inline** (e.g. an HTML `Content-Type`) from API file/response endpoints, and (b) anything that abuses the app-scoped `puter_token_v2` companion cookie set on the API host.
+- **SSRF via `secureFetch`.** Production routes outbound requests through an isolated proxy that has no access to internal/SSRF-sensitive resources.
+- **Attacks that depend on guessing an `appInstanceID` or app UID.** These are random 128-bit secret values and are not considered guessable.
+- **Apps invoking drivers, creating workers, or using KV.** Applications are intended to do this; worker permissions are scoped to the owning app. This is by design.
+- **App metadata or app user-count "leaks".** This information is currently public by design.
+- **General "token in a URL" / token-lifetime designs** — signed directory URLs exposing children, a write signature implying read, or app tokens outliving a web session. These are current intended behaviors.
+- **Missing PKCE, unverified `id_token` signatures, or other OIDC hardening.** Provider tokens are obtained through a server-to-server authorization-code exchange with the provider's token endpoint over TLS, so the resulting `id_token` / userinfo claims are trusted from that channel rather than from local JWKS signature verification — the callback never accepts a caller-supplied `id_token`. Adding local signature / `aud` / `iss` / `exp` checks is welcome defense-in-depth (please open a GitHub issue/PR), but their absence is not an account-takeover vector on its own.
+- **JWT "algorithm confusion" / unpinned `algorithms` in `jwt.verify`.** Puter's session tokens are HMAC-signed (HS256) with a server-side secret, and there is no asymmetric public key anywhere in the verification path, so `alg`-substitution attacks do not apply. Explicitly pinning `algorithms` is a fine hardening PR, but it is not a vulnerability.
+- **Static-source "SQL injection" in internal pagination.** Findings such as `LIMIT ${limit}` in list/notification queries: the limit is numerically coerced and clamped before it reaches the query, so it is not reachable with attacker-controlled string input. Hardening PRs to the internal stores are welcome, but these are not exploitable as reported.
+- **Deprecated `saveTo*` GUI app messages.** The legacy `saveToDesktop` / `saveToDocuments` / etc. app-IPC handlers can create — never overwrite — new files in standard user folders. The behavior is non-destructive, path-traversal-safe, and deprecated (slated for removal); it is not treated as a sandbox escape.
+- **Best-practice suggestions** such as login/registration username enumeration (kept intentionally for UX) or unauthenticated unsubscribe links (industry norm).
+- **Rate-limiting suggestions for TURN credential issuance** (intentional; not billed per tunnel).
 
 If you believe you have a **genuinely new** exploit chain that defeats one of these rationales (for example, demonstrating a sensitive credential that really is reachable on `api.puter.com`), say so explicitly and show why the reasoning above does not apply.
 
@@ -40,7 +40,7 @@ If you believe you have a **genuinely new** exploit chain that defeats one of th
 
 To participate, you must:
 
-1. **Report responsibly**: Provide detailed steps to reproduce the issue, including proof-of-concept code, screenshots, or a screen recording (see *Proof of Reproduction* below).
+1. **Report responsibly**: Provide detailed steps to reproduce the issue, including proof-of-concept code, screenshots, or a screen recording (see _Proof of Reproduction_ below).
 2. **Do no harm**: Do not exfiltrate, modify, or delete data. Only access your own account or test data.
 3. **Respect availability**: Do not perform denial-of-service attacks or automated scans that degrade service.
 4. **Follow disclosure policy**: Do not publicly disclose vulnerabilities until we have confirmed and patched the issue.
@@ -51,26 +51,30 @@ Reports that do not meet these guidelines may not be eligible for a reward.
 
 ## Proof of Reproduction
 
-Reports must demonstrate a **working, reproducible exploit with real impact** — not a theoretical or static-source-review finding. Please include:
+Reports **MUST** demonstrate a **working, reproducible exploit with real impact** — not a theoretical or static-source-review finding. Please include:
 
-* Exact steps to reproduce, the relevant request/response or code path, and the commit or version you tested.
-* The **observed** result versus the **expected** result.
-* For client-side, UI, or authentication-flow bugs: a short screen recording (≤ 2 minutes) showing the exploit working end-to-end on a real Puter instance.
-* For server-side bugs: a runnable proof-of-concept.
+- Exact steps to reproduce, the relevant request/response or code path, and the commit or version you tested.
+- The **observed** result versus the **expected** result.
+- For client-side, UI, or authentication-flow bugs: a short screen recording (≤ 2 minutes) showing the exploit working end-to-end on a real Puter instance.
+- For server-side bugs: a runnable proof-of-concept and screenshot or video showing the attack process.
 
-Reports based solely on reading the source ("source review only, not tested") or unverified AI/LLM-generated reports are the **lowest triage priority and are generally not eligible**. If you used an AI tool to help find an issue, you must personally verify that it actually reproduces before submitting.
+Reports based solely on reading the source ("source review only, not tested") or unverified AI/LLM-generated reports are the **lowest triage priority and not eligible for bounty**.
+If you used an AI tool to help find an issue, you must personally verify that it actually reproduces before submitting.
 
-Please submit **one issue per report**. Bundled "audit packs" of many speculative findings will be declined; send each confirmed issue separately.
+Please submit **one issue per report**.
+Bundled "audit packs" of many speculative findings will not be elligible for bounty; send each confirmed issue separately.
+Additionally please **DO NOT** submit too many issues at once; these will be treated as a bundled report, and will not be elligible for bounty.
 
 ## Reporting Process
 
 To report a vulnerability, email us at: **[[email protected]](mailto:[email protected])**.
 Include:
 
-* A description of the vulnerability
-* Steps to reproduce
-* Potential impact
-* Suggested remediation (if available)
+- A description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested remediation (if available)
+- Paypal id where we can send the bounty (if eligible)
 
 We aim to acknowledge receipt within **72 hours** and provide a resolution timeline.
 
@@ -78,10 +82,10 @@ We aim to acknowledge receipt within **72 hours** and provide a resolution timel
 
 We offer monetary rewards based on the severity of the vulnerability, as determined by our internal assessment (using CVSS as a guide).
 
-* **Critical: \$1,000 – \$2,000**
-* **High: \$500 – \$1,000**
-* **Medium: \$200 – \$500**
-* **Low: \$50 – \$100**
+- **Critical: \$1,000 – \$2,000**
+- **High: \$500 – \$1,000**
+- **Medium: \$200 – \$500**
+- **Low: \$50 – \$100**
 
 Non-security issues, suggestions, and best practices feedback are always welcome, but may not qualify for a reward.
 If multiple researchers report the same issue, the bounty will be awarded to the first eligible report we receive.

CONTRIBUTING.md

@@ -32,6 +32,8 @@ Don't commit code you couldn't have written, debugged, or defended yourself. Rea
 
 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.
 
+The same rule applies to limits: rate limits, concurrency caps, quotas, and allowances are published in [src/docs/src/rate-limits-and-quotas.md](src/docs/src/rate-limits-and-quotas.md), and a PR that changes one of those numbers updates that page in the same PR. A limit nobody published is a limit developers only discover as a service failure.
+
 ## 6. Boy Scout Rule — leave it 1% better
 
 ![Boy Scout Rule](https://imgs.search.brave.com/DMmIWl5-NuZVtrR9kXBb06AKF8kturkgSW9UMb2-6m4/rs:fit:860:0:0:0/g:ce/aHR0cHM6Ly9sYXdz/b2Zzb2Z0d2FyZWVu/Z2luZWVyaW5nLmNv/bS9pbWFnZXMvbGF3/cy9ib3ktc2NvdXQt/cnVsZS5wbmc)

README.md

@@ -12,10 +12,6 @@
     ·
     <a href="https://developer.puter.com" target="_blank">Developers</a>
     ·
-    <a href="https://discord.com/invite/PQcx7Teh8u">Discord</a>
-    ·
-    <a href="https://reddit.com/r/puter">Reddit</a>
-    ·
     <a href="https://twitter.com/HeyPuter">X</a>
 </p>
 
@@ -82,10 +78,7 @@ Puter is available as a hosted service at [**puter.com**](https://puter.com).
 Connect with the maintainers and community through these channels:
 
 - Bug report or feature request? Please [open an issue](https://github.com/HeyPuter/puter/issues/new/choose).
-- Discord: [discord.com/invite/PQcx7Teh8u](https://discord.com/invite/PQcx7Teh8u)
 - X (Twitter): [x.com/HeyPuter](https://x.com/HeyPuter)
-- Reddit: [reddit.com/r/puter/](https://www.reddit.com/r/puter/)
-- Mastodon: [mastodon.social/@puter](https://mastodon.social/@puter)
 - Security issues or abuse reports? [[email protected]](mailto:[email protected])
 - Email maintainers at [[email protected]](mailto:[email protected])
 

caddy/Caddyfile

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

config.default.json

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

config.template.jsonc

@@ -73,11 +73,7 @@
 
     // ── Auth / session ──────────────────────────────────────────────────
     // ALWAYS replace these for any public install — `openssl rand -hex 64`.
-    // `jwt_secret` is legacy verify-only; new tokens sign with `jwt_secret_v2`.
-    "jwt_secret": "change-me",
     "jwt_secret_v2": "change-me",
-    // Set false to retire v1 tokens entirely (ROLLOUT-1).
-    "allow_v1_tokens": true,
     "url_signature_secret": "change-me",
     "cookie_name": "puter_auth_token",
     "min_pass_length": 6,
@@ -255,6 +251,82 @@
         }
     },
 
+    // ── Sharing ─────────────────────────────────────────────────────────
+    // Email a recipient who already has an account about a new share. On
+    // unless set to false; they opt out via the unsubscribe link, or by
+    // blocking a sender. An invite to an address with no account always goes.
+    // "share_email_notifications": false,
+    //
+    // New shares one account may create per UTC day. Default 200.
+    // "share_daily_limit": 200,
+    //
+    // How often a share may interrupt its recipient — the notification pushed
+    // to their screen and the email with it. Over budget the share still
+    // succeeds and their notification is still brought up to date; only the
+    // interruption is dropped. The recipient bounds are what stop many senders
+    // burying one person between them. A non-positive value removes a bound.
+    // "share_notify_limits": {
+    //     "pairWindowSeconds": 900,
+    //     "pairDaily": 20,
+    //     "recipientHourly": 10,
+    //     "recipientDaily": 50,
+    //     "emailBatchSeconds": 90
+    // },
+
+    // ── Alarms / alerting ───────────────────────────────────────────────
+    // Where system alarms go. Severity is the routing decision — each
+    // transport takes everything at or above its own `minSeverity`:
+    //
+    //   critical — an unhandled server error; pages on-call.
+    //   error    — pages as well; prefer critical or warning.
+    //   warning  — look at it today; no page.
+    //   info     — a record in the chat channel only.
+    //
+    // Both transports are off unless enabled, so a self-hosted node just
+    // logs its alarms to the console.
+    "pager": {
+        // Severity for call sites that don't pick one. Default "critical".
+        "defaultSeverity": "critical",
+
+        // Retier or silence an alarm without a deploy. Keys are alarm ids,
+        // or a prefix ending in `*`; the exact id wins over a pattern, and
+        // the longest matching pattern wins among patterns. Values are a
+        // severity or "mute". This is applied last, so it overrides both the
+        // call site and any known-error rule.
+        "severityOverrides": {
+            // "cronMonitor:*": "info",
+            // "http_500:GET:/some/flapping/route:*": "mute"
+        },
+
+        "pagerduty": {
+            "enabled": false,
+            "routingKey": "",
+            // Lowest severity that reaches PagerDuty. Default "warning",
+            // which keeps `info` out of the paging system entirely.
+            "minSeverity": "warning"
+        },
+
+        // Slack incoming webhook — the low-noise destination for everything
+        // that shouldn't page.
+        "slack": {
+            "enabled": false,
+            "webhookUrl": "",
+            // Optional; defaults to the channel the webhook was created for.
+            "channel": "#alerts",
+            "username": "puter-alarms",
+            // Severity window posted to Slack. The ceiling defaults to
+            // "info" when PagerDuty is configured — what pages belongs in
+            // the pager, not in chat — and to "critical" when Slack is the
+            // only transport.
+            "minSeverity": "info",
+            "maxSeverity": "info",
+            // Don't repost the same alarm id within this window. The first
+            // occurrence always posts; the next post that gets through
+            // reports how many occurrences piled up. 0 disables throttling.
+            "repeatThrottleMs": 900000
+        }
+    },
+
     // ── Rate limiting ───────────────────────────────────────────────────
     // `memory` for single-node, `redis` for multi-node (default), `kv` for
     // dynamo-backed counters.
@@ -274,6 +346,10 @@
             "apiURL": ""
         },
         "gemini": { "apiKey": "" },
+        // Meta Model API (Muse Spark). `muse-spark-1.2-contributor`
+        // trades a ~12x discount for Meta training on its prompts and
+        // completions, so it is only served to callers that name it.
+        "meta": { "apiKey": "" },
         "groq": { "apiKey": "" },
         "deepseek": { "apiKey": "" },
         "mistral": { "apiKey": "" },
@@ -291,6 +367,16 @@
             "apiKey": "",
             "apiBaseUrl": "https://llm.onerouter.pro/v1"
         },
+        // BytePlus ModelArk. One key powers chat (Seed/GLM/DeepSeek), image
+        // generation (Seedream) and video generation (Seedance); `apiBaseUrl`
+        // selects the region; see
+        // https://docs.byteplus.com/en/docs/ModelArk/1330310 for options.
+        "byteplus": {
+            "apiKey": "",
+            "apiBaseUrl": "https://ark.ap-southeast.bytepluses.com/api/v3"
+        },
+        "zai": { "apiKey": "" },
+        "alibaba": { "apiKey": "" },
         "together-ai": { "apiKey": "" },
         // Local Ollama. `enabled: false` skips the auto-probe at startup
         // (otherwise Puter logs ECONNREFUSED on every boot when no Ollama
@@ -387,6 +473,27 @@
     ],
 
     // ── Metering ────────────────────────────────────────────────────────
-    // When true, all metering checks pass — no per-actor limits enforced.
-    "unlimitedMetering": false
+    // When true, every account resolves to an unlimited policy: usage is still
+    // recorded, but nothing is ever refused for lack of budget. This is the
+    // setting for a deployment with no way to buy more — without it, accounts
+    // are held to the free monthly allowance and start getting 402s from the AI
+    // surfaces, file transfers and KV once they pass it.
+    "unlimitedMetering": false,
+
+    // Whether an account that has spent its whole allowance is refused the
+    // operations that spend it — file transfers, KV calls. Recording is
+    // unaffected either way. `workers` extends the same refusal to
+    // worker-driven calls, which are exempt by default because a deployed
+    // worker has nowhere to surface a payment prompt. `subscriptions` covers
+    // the separate question of surfaces reserved for paid plans (the
+    // vendor-compatible AI endpoints): turn it off on a deployment with no
+    // paid plans, or every account is refused them.
+    // "meteringEnforcement": { "enabled": true, "workers": false, "subscriptions": true },
+
+    // Fleet-wide spend rate, in micro-cents per minute, past which metering
+    // raises the `metering:excessiveGlobalUsageRate` alarm. Omit it (the
+    // default) to leave the check off: the only useful value is a multiple of
+    // what this deployment's normal traffic costs, so it has to be measured
+    // rather than guessed, and a stale number here alarms on healthy growth.
+    // "maxGlobalUsagePerMinute": 200000000
 }

doc/alarms.md

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

doc/contributing-apis.md

@@ -53,7 +53,10 @@ Both are supported ways to define an API. **Prefer a controller when you need fi
 #### 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.
+- **Driver methods** get their policies from the `@Driver` options: per-method `rateLimit` (limit/window/backend), `concurrent` in-flight caps (optionally `bySubscription`), `requireSubscription`, and `noUserSession`. The `/drivers/call` surface enforces them.
+- **A surface only paying accounts should reach** declares `requireSubscription` — the route option on a controller endpoint, the per-method `@Driver({ requireSubscription })` block on a driver (`/drivers/call` is one shared route, so a driver's requirement can't live in route options). `true` accepts any plan that isn't free, so a plan registered by an extension counts without core naming it; an array of policy ids (`['business', 'pro']`) accepts only those; `false` is "no requirement", the same as leaving it out. An empty array is a boot error rather than a silent no-op — it reads as subscribers-only while admitting everyone. Off unless asked for, and answered from the metering service's cached per-actor subscription, so it costs a map lookup. Distinct from `requireCredits`: this asks which plan the account is on, not whether it has budget left. Deployments with no paid plans (self-hosted installs) turn the whole thing off with `meteringEnforcement.subscriptions: false`.
+- **An account must have verified a specific factor** — `requireVerified` (email, and only under `strict_email_verification_required`), `requirePhoneVerified`, `requireCardVerified`. These are opt-in and require the factor to have actually been verified, unlike the default-on gate that turns away accounts still carrying a pending verification the abuse harness asked for.
+- **An endpoint that spends metered resources** on the caller's behalf — moving file content, making object-store requests, anything else the account is billed for — also declares `requireCredits: true`, which turns an account with nothing left of its budget away with a 402 before the handler runs. Endpoints that only describe or delete things deliberately don't: an account that has run out still has to be able to see what it has, clear it, and reach its billing pages. Drivers have no route options to declare this on, so they call `assertActorHasCredits` themselves ([src/backend/services/metering/enforcement.ts](../src/backend/services/metering/enforcement.ts)) — see `KVStoreDriver`, which does it once for every method.
 
 ### 3. puter.js
 
@@ -62,7 +65,10 @@ Both are supported ways to define an API. **Prefer a controller when you need fi
 
 ### 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.
+- Type the method where you wrote it, in JSDoc: `@param`/`@returns` on the implementation, one `@overload` block per accepted call form, and `@typedef {Object}` + `@property` for any new shape. The JSDoc is the source of truth — declarations are generated from it, so there is nothing to keep in sync by hand.
+- Put a shape more than one file needs in the module's `types.js` (e.g. [src/puter-js/src/modules/kv/types.js](../src/puter-js/src/modules/kv/types.js)); anything shared across modules goes in [src/puter-js/src/lib/types.js](../src/puter-js/src/lib/types.js). A shape with one consumer can stay next to it.
+- Run `npm run check:puterjs:types` — it generates the declarations and type-checks the published surface without `skipLibCheck`. **Never edit anything under `src/puter-js/types/`**: it is gitignored build output, produced by the SDK build and shipped in the npm tarball, and the next build overwrites it.
+- Name the new type in [src/puter-js/index.d.ts](../src/puter-js/index.d.ts) if consumers should be able to import it. That file is the one hand-written declaration in the package: it decides what is public and re-exports nothing else.
 
 ### 5. Docs
 

doc/self-hosting.md

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

docker-compose.yml

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

extensions/appTelemetry.ts

@@ -2,6 +2,14 @@ import { Context } from '@heyputer/backend/src/core';
 import type { Actor } from '@heyputer/backend/src/core/actor';
 import { HttpError } from '@heyputer/backend/src/core/http';
 import { PuterDriver } from '@heyputer/backend/src/drivers/types';
+import type {
+    DriverConcurrentConfig,
+    DriverRateLimitConfig,
+} from '@heyputer/backend/src/drivers/meta';
+import {
+    DEFAULT_FREE_SUBSCRIPTION,
+    DEFAULT_TEMP_SUBSCRIPTION,
+} from '@heyputer/backend/src/services/metering/consts';
 import { extension } from '@heyputer/backend/src/extensions';
 
 // App-telemetry lets an app owner enumerate the users who have
@@ -50,17 +58,42 @@ const parseIntParam = (
  * Driver exposing the `app-telemetry` interface.
  *
  * The `/drivers/call` permission gate checks
- * `service:app-telemetry:ii:app-telemetry`, which every actor already holds
- * via the blanket `service` grant (hardcoded-permissions.js +
+ * `service:app-telemetry:ii:app-telemetry`, which every actor already holds via
+ * the blanket `service` grant (hardcoded-permissions.js +
  * `default_implicit_user_app_permissions`). The real authorization — "is the
- * caller the app owner?" — is enforced inside `get_users` below, exactly as
- * v1 did.
+ * caller the app owner?" — is enforced inside `get_users` below, exactly as v1
+ * did.
  */
 export class AppTelemetryDriver extends PuterDriver {
     readonly driverInterface = 'app-telemetry';
     readonly driverName = 'app-telemetry';
     readonly isDefault = true;
 
+    // Declaring nothing here would leave both methods on the generic
+    // 600/minute driver default, which does not fit a paginated scan that
+    // can ask for MAX_LIMIT rows at MAX_OFFSET. This is a dashboard read —
+    // nobody calls it in a loop.
+    readonly rateLimit: DriverRateLimitConfig = {
+        default: {
+            limit: 60,
+            window: 60_000,
+            bySubscription: {
+                [DEFAULT_FREE_SUBSCRIPTION]: 30,
+                [DEFAULT_TEMP_SUBSCRIPTION]: 10,
+            },
+        },
+    };
+
+    readonly concurrent: DriverConcurrentConfig = {
+        default: {
+            limit: 5,
+            bySubscription: {
+                [DEFAULT_FREE_SUBSCRIPTION]: 2,
+                [DEFAULT_TEMP_SUBSCRIPTION]: 2,
+            },
+        },
+    };
+
     /** Users who have authenticated into the given app (owner-only). */
     async get_users({
         app_uuid,

extensions/devWatcher.test.ts

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

extensions/installedApps.ts

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

extensions/metering.ts

@@ -3,8 +3,13 @@ import { HttpError } from '@heyputer/backend/src/core/http';
 import {
     controllersContainers,
     driversContainers,
+    servicesContainers,
 } from '@heyputer/backend/src/exports';
 import { extension } from '@heyputer/backend/src/extensions';
+import {
+    creditMultiplierFrom,
+    toCredits,
+} from '@heyputer/backend/src/services/metering/utils';
 import type { Request, Response } from 'express';
 
 const services = extension.import('service');
@@ -18,7 +23,7 @@ function collectAllCosts(): Record<string, unknown>[] {
     const all: Record<string, unknown>[] = [];
     const collect = (
         source: Record<string, unknown>,
-        kind: 'driver' | 'controller',
+        kind: 'driver' | 'controller' | 'service',
     ) => {
         for (const [name, instance] of Object.entries(source)) {
             const fn = (
@@ -43,9 +48,48 @@ function collectAllCosts(): Record<string, unknown>[] {
     };
     collect(driversContainers as Record<string, unknown>, 'driver');
     collect(controllersContainers as Record<string, unknown>, 'controller');
+    // Services report the costs that aren't tied to one endpoint — egress,
+    // which is metered for every response there is.
+    collect(servicesContainers as Record<string, unknown>, 'service');
     return all;
 }
 
+// -- Credits scaling ---------------------------------------------------
+//
+// When the deployment configures a credit multiplier, every monetary amount
+// is scaled to display credits BEFORE it leaves the server — raw metered
+// amounts are never reported. Counts, units, and byte figures pass through
+// untouched. A response that was scaled says so (`unit: 'credits'`); without
+// a configured multiplier amounts pass through raw and clients render them
+// as dollars.
+
+/** The per-usage-type records of a UsageByType map, costs scaled. */
+const scaleUsageByType = (
+    usage: Record<string, unknown>,
+    multiplier: number,
+): Record<string, unknown> => {
+    const out: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(usage)) {
+        // `allowanceUsed` is the month's allowance-charged spend — monetary,
+        // scalar, scaled like the total.
+        if (key === 'total' || key === 'allowanceUsed') {
+            out[key] = toCredits(Number(value) || 0, multiplier);
+        } else if (
+            value &&
+            typeof value === 'object' &&
+            typeof (value as { cost?: unknown }).cost === 'number'
+        ) {
+            out[key] = {
+                ...(value as Record<string, unknown>),
+                cost: toCredits((value as { cost: number }).cost, multiplier),
+            };
+        } else {
+            out[key] = value;
+        }
+    }
+    return out;
+};
+
 export const handleMeteringUsage = async (
     _req: Request,
     res: Response,
@@ -57,7 +101,44 @@ export const handleMeteringUsage = async (
         services.metering.getActorCurrentMonthUsageDetails(actor),
         services.metering.getAllowedUsage(actor),
     ]);
-    res.json({ ...actorUsage, allowanceInfo });
+    const multiplier = creditMultiplierFrom(extension.config);
+    if (!multiplier) {
+        res.json({ ...actorUsage, allowanceInfo });
+        return;
+    }
+    res.json({
+        usage: scaleUsageByType(
+            actorUsage.usage as unknown as Record<string, unknown>,
+            multiplier,
+        ),
+        appTotals: Object.fromEntries(
+            Object.entries(actorUsage.appTotals).map(([appId, totals]) => [
+                appId,
+                { ...totals, total: toCredits(totals.total, multiplier) },
+            ]),
+        ),
+        allowanceInfo: {
+            ...allowanceInfo,
+            remaining: toCredits(allowanceInfo.remaining, multiplier),
+            monthUsageAllowance: toCredits(
+                allowanceInfo.monthUsageAllowance,
+                multiplier,
+            ),
+            // Monetary addon fields scale; absent ones stay absent rather
+            // than materializing as NaN/null. purchasedStorage is bytes.
+            addons: Object.fromEntries(
+                Object.entries(allowanceInfo.addons ?? {}).map(([k, v]) => [
+                    k,
+                    (k === 'purchasedCredits' ||
+                        k === 'consumedPurchaseCredits') &&
+                    typeof v === 'number'
+                        ? toCredits(v, multiplier)
+                        : v,
+                ]),
+            ),
+            unit: 'credits',
+        },
+    });
 };
 
 export const handleMeteringUsageForApp = async (
@@ -88,7 +169,18 @@ export const handleMeteringUsageForApp = async (
             actor,
             appId,
         );
-    res.json(appUsage);
+    const multiplier = creditMultiplierFrom(extension.config);
+    if (!multiplier) {
+        res.json(appUsage);
+        return;
+    }
+    res.json({
+        ...scaleUsageByType(
+            appUsage as unknown as Record<string, unknown>,
+            multiplier,
+        ),
+        unit: 'credits',
+    });
 };
 
 export const handleMeteringGlobalUsage = async (
@@ -105,31 +197,67 @@ export const handleMeteringAllCosts = async (
     res: Response,
 ): Promise<void> => {
     if (!cachedAllCosts) {
-        cachedAllCosts = collectAllCosts();
+        const raw = collectAllCosts();
+        const multiplier = creditMultiplierFrom(extension.config);
+        // Price the catalogue in the same unit the usage endpoints report:
+        // per-unit credits when a multiplier is configured, raw otherwise.
+        cachedAllCosts = multiplier
+            ? raw.map(({ ucentsPerUnit, costs_currency: _cc, ...rest }) =>
+                  typeof ucentsPerUnit === 'number'
+                      ? {
+                            ...rest,
+                            creditsPerUnit: toCredits(
+                                ucentsPerUnit,
+                                multiplier,
+                            ),
+                        }
+                      : rest,
+              )
+            : raw;
     }
     res.json({ costs: cachedAllCosts });
 };
 
+/** Dashboard reads over the per-actor KV aggregates. */
+const USAGE_READ_LIMIT = {
+    scope: 'metering-usage',
+    limit: 120,
+    window: 60_000,
+    key: 'user' as const,
+};
+
 extension.get(
     '/metering/usage',
-    { subdomain: 'api', requireAuth: true },
+    { subdomain: 'api', requireAuth: true, rateLimit: USAGE_READ_LIMIT },
     handleMeteringUsage,
 );
 
 extension.get(
     '/metering/usage/:appIdOrName',
-    { subdomain: 'api', requireAuth: true },
+    { subdomain: 'api', requireAuth: true, rateLimit: USAGE_READ_LIMIT },
     handleMeteringUsageForApp,
 );
 
 extension.get(
     '/metering/globalUsage',
-    { subdomain: 'api', adminOnly: true },
+    {
+        subdomain: 'api',
+        adminOnly: true,
+        // Sums across every shard of the global aggregate. Admin-gated, so
+        // this is loop protection — but one accidental poll is an
+        // expensive minute.
+        rateLimit: {
+            scope: 'metering-global-usage',
+            limit: 10,
+            window: 60_000,
+            key: 'user',
+        },
+    },
     handleMeteringGlobalUsage,
 );
 
 extension.get(
     '/metering/allCosts',
-    { subdomain: 'api', requireAuth: true },
+    { subdomain: 'api', requireAuth: true, rateLimit: USAGE_READ_LIMIT },
     handleMeteringAllCosts,
 );

extensions/serverInfo.test.ts

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

extensions/thumbnails.test.ts

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

extensions/thumbnails.ts

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

extensions/whoami.test.ts

@@ -109,6 +109,9 @@ describe('whoami extension — handleWhoami', () => {
         expect(body.oidc_only).toBe(false);
         // is_user_token is present (true) for user actors.
         expect(body.is_user_token).toBe(true);
+        // Account creation time, in unix seconds.
+        expect(typeof body.created_ts).toBe('number');
+        expect(body.created_ts).toBeGreaterThan(0);
         // `directories` is only sent to user actors — confirm it’s present.
         expect(body.directories).toBeDefined();
         // taskbar_items is only sent to user actors.
@@ -132,7 +135,7 @@ describe('whoami extension — handleWhoami', () => {
         expect(flags.payment_bypass).toBeUndefined();
     });
 
-    it('strips desktop_bg_* and human_readable_age fields for app actors', async () => {
+    it('strips desktop_bg_*, created_ts and human_readable_age fields for app actors', async () => {
         const user = await seedUser();
         const { res, captured } = makeRes();
 
@@ -154,6 +157,8 @@ describe('whoami extension — handleWhoami', () => {
         expect(body.desktop_bg_color).toBeUndefined();
         expect(body.desktop_bg_fit).toBeUndefined();
         expect(body.human_readable_age).toBeUndefined();
+        // Account age, in either form, is not exposed to apps.
+        expect(body.created_ts).toBeUndefined();
         // Directories are user-only.
         expect(body.directories).toBeUndefined();
     });
@@ -201,6 +206,84 @@ describe('whoami extension — handleWhoami', () => {
         expect(JSON.stringify(body)).not.toContain('bootstrap-secret');
     });
 
+    it('never exposes phone, card fingerprint or signup identity', async () => {
+        const user = await seedUser();
+        await server.stores.user.update(user.id as number, {
+            phone: '+15551234567',
+            card_fingerprint: 'fp_ABC123',
+            requires_phone_verification: false,
+            requires_card_verification: false,
+        });
+        // Guard against a vacuous assertion below: the columns really do hold
+        // the values we then expect never to see on the wire.
+        const stored = await server.stores.user.getById(user.id as number, {
+            cached: false,
+            force: true,
+        });
+        expect(stored?.phone).toBe('+15551234567');
+        expect(stored?.card_fingerprint).toBe('fp_ABC123');
+
+        for (const actor of [
+            { user: { uuid: user.uuid, id: user.id as number } },
+            {
+                user: { uuid: user.uuid, id: user.id as number },
+                app: { uid: 'app-test-actor' },
+            },
+        ]) {
+            const { res, captured } = makeRes();
+            await runWithContext({ actor }, () =>
+                handleWhoami(makeReq(), res),
+            );
+
+            const body = captured.body as Record<string, unknown>;
+            expect(body.phone).toBeUndefined();
+            expect(body.card_fingerprint).toBeUndefined();
+            expect(body.password).toBeUndefined();
+            expect(body.otp_secret).toBeUndefined();
+            expect(body.signup_ip).toBeUndefined();
+            // Not just absent as a key — the values must not appear anywhere
+            // in the payload (nested under metadata, taskbar items, …).
+            const serialized = JSON.stringify(body);
+            expect(serialized).not.toContain('5551234567');
+            expect(serialized).not.toContain('fp_ABC123');
+            // The verification flags, which the GUI acts on, still ship.
+            expect(body).toHaveProperty('requires_phone_verification');
+            expect(body).toHaveProperty('requires_card_verification');
+        }
+    });
+
+    it('scrubs sensitive keys added to metadata, and leaves the cached row intact', async () => {
+        const user = await seedUser();
+        await server.stores.user.updateMetadata(user.id as number, {
+            tmp_password: 'bootstrap-secret',
+            billing: { card_fingerprint: 'fp_NESTED', tier: 'pro' },
+        });
+
+        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();
+        // Nested sensitive keys are removed too; siblings survive.
+        expect(metadata.billing).toEqual({ tier: 'pro' });
+        expect(JSON.stringify(body)).not.toContain('fp_NESTED');
+
+        // The scrub works on a copy — server-side state is untouched.
+        const fresh = await server.stores.user.getById(user.id as number, {
+            cached: false,
+            force: true,
+        });
+        expect(fresh?.metadata?.tmp_password).toBe('bootstrap-secret');
+        expect(
+            (fresh?.metadata?.billing as Record<string, unknown>)
+                ?.card_fingerprint,
+        ).toBe('fp_NESTED');
+    });
+
     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

@@ -14,6 +14,15 @@ const timeago = (() => {
     return new TimeAgo('en-US');
 })();
 
+// User timestamps come off the DB as SQL datetime strings; the wire format
+// for all of them is unix seconds. Unparseable values are dropped rather
+// than sent as NaN.
+const toUnixSeconds = (value: unknown): number | undefined => {
+    if (!value) return undefined;
+    const ms = new Date(value as string | number | Date).getTime();
+    return Number.isNaN(ms) ? undefined : Math.round(ms / 1000);
+};
+
 // Allowlist of `config.feature_flags` keys safe to surface via /whoami.
 // Anything not listed here stays server-side, so internal flags
 // (payment_bypass, staff_only_*, etc.) cannot leak by accident. Add a
@@ -24,6 +33,68 @@ const CLIENT_VISIBLE_FEATURE_FLAGS: ReadonlySet<string> = new Set([
     'prompt_user_when_navigation_away_from_puter',
 ]);
 
+// Keys that must never leave the server, whoever put them on the response.
+// `details` is an explicit pick, but the `whoami.details` event hands
+// listeners the full UserRow next to the object they may write to, and
+// `metadata` is a free-form blob — so any of these can arrive on the
+// response without an edit to the pick above. The scrub runs last, over the
+// whole payload, and is the one place that decides what "sensitive" means.
+//
+// Credentials and single-use tokens, the payment/phone identifiers used for
+// verification (`card_fingerprint` is the Stripe fingerprint, stable per
+// card number), the network identity recorded at signup, and internal
+// anti-abuse bookkeeping. `requires_phone_verification` /
+// `requires_card_verification` stay: they are the flags the GUI acts on, and
+// they carry no identifier.
+const SENSITIVE_KEYS: ReadonlySet<string> = new Set([
+    'password',
+    'tmp_password',
+    'pass_recovery_token',
+    'email_confirm_code',
+    'email_confirm_token',
+    'change_email_confirm_token',
+    'otp_secret',
+    'otp_recovery_codes',
+    'card_fingerprint',
+    'phone',
+    'clean_email',
+    'signup_ip',
+    'signup_ip_forwarded',
+    'signup_user_agent',
+    'signup_origin',
+    'signup_server',
+    'audit_metadata',
+]);
+
+// Depth-limited, cycle-safe walk deleting every SENSITIVE_KEYS entry it finds
+// at any level (`metadata` and `taskbar_items` are both nested structures).
+const scrubSensitive = (
+    value: unknown,
+    seen: Set<object> = new Set(),
+    depth = 0,
+): void => {
+    if (depth > 8 || value === null || typeof value !== 'object') return;
+    if (seen.has(value as object)) return;
+    seen.add(value as object);
+
+    if (Array.isArray(value)) {
+        for (const entry of value) scrubSensitive(entry, seen, depth + 1);
+        return;
+    }
+
+    for (const key of Object.keys(value as Record<string, unknown>)) {
+        if (SENSITIVE_KEYS.has(key)) {
+            delete (value as Record<string, unknown>)[key];
+            continue;
+        }
+        scrubSensitive(
+            (value as Record<string, unknown>)[key],
+            seen,
+            depth + 1,
+        );
+    }
+};
+
 export const handleWhoami = async (
     req: Request,
     res: Response,
@@ -65,8 +136,12 @@ export const handleWhoami = async (
         }
     }
 
-    const metadata = user.metadata ? { ...user.metadata } : user.metadata;
-    if (metadata) delete metadata.tmp_password;
+    // Deep-copied (it is decoded JSON) so the scrub below edits the response
+    // and not the cached UserRow. Sensitive keys inside it — tmp_password and
+    // anything else on the denylist — are removed by scrubSensitive.
+    const metadata = user.metadata
+        ? structuredClone(user.metadata)
+        : user.metadata;
 
     const details: Record<string, unknown> = {
         username: user.username,
@@ -75,7 +150,9 @@ export const handleWhoami = async (
         unconfirmed_email: user.email,
         email_confirmed: user.email_confirmed || user.username === 'admin',
         requires_email_confirmation: user.requires_email_confirmation,
-        phone: user.phone,
+        // The phone number itself is deliberately absent: nothing on the
+        // client reads it, and it is PII that would otherwise be handed to
+        // every app actor. Only the verification flag ships.
         requires_phone_verification: user.requires_phone_verification,
         requires_card_verification: user.requires_card_verification,
         desktop_bg_url: user.desktop_bg_url,
@@ -83,6 +160,10 @@ export const handleWhoami = async (
         desktop_bg_fit: user.desktop_bg_fit,
         is_temp: user.password === null && user.email === null,
         is_user_token: true,
+        // Present only once the account has actually asked for a code (see the
+        // referral extension) — null until then, and never minted from here:
+        // this endpoint is polled, and a mint is a write.
+        referral_code: user.referral_code,
         oidc_only: oidcOnly,
         taskbar_items: isUser
             ? await getTaskbarItems(
@@ -98,6 +179,7 @@ export const handleWhoami = async (
             : undefined,
         otp: !!user.otp_enabled,
         feature_flags,
+        created_ts: toUnixSeconds(user.timestamp),
         human_readable_age: user.timestamp
             ? timeago.format(new Date(user.timestamp as string))
             : null,
@@ -141,14 +223,9 @@ export const handleWhoami = async (
     }
 
     // Last activity
-    if (user.last_activity_ts) {
-        try {
-            details.last_activity_ts = Math.round(
-                new Date(user.last_activity_ts as string).getTime() / 1000,
-            );
-        } catch {
-            /* ignore parse error */
-        }
+    const lastActivityTs = toUnixSeconds(user.last_activity_ts);
+    if (lastActivityTs !== undefined) {
+        details.last_activity_ts = lastActivityTs;
     }
 
     // Strip sensitive fields for app actors
@@ -164,8 +241,11 @@ export const handleWhoami = async (
         delete details.desktop_bg_color;
         delete details.desktop_bg_fit;
         delete details.human_readable_age;
+        delete details.created_ts;
         delete details.is_user_token;
         delete details.metadata;
+        // An app has no business reading the code its user earns credit with.
+        delete details.referral_code;
     }
 
     if (actor.app) {
@@ -183,19 +263,38 @@ export const handleWhoami = async (
     }
 
     const subscription = details.subscription as
-        | { offering?: Record<string, unknown> }
-        | undefined;
+        { offering?: Record<string, unknown> } | undefined;
     if (subscription?.offering) {
         delete subscription.offering.group;
         delete subscription.offering.benefits;
         delete subscription.offering.price_id;
     }
 
+    // Last word on what ships, after every listener has had its say.
+    scrubSensitive(details);
+
     res.json(details);
 };
 
 extension.get(
     '/whoami',
-    { subdomain: 'api', requireAuth: true, allowUnconfirmed: true },
+    {
+        subdomain: 'api',
+        requireAuth: true,
+        allowUnconfirmed: true,
+        // The GUI polls this, and each call fans out to every `whoami`
+        // event listener — so it costs more than the response suggests.
+        //
+        // It is also the call everything else leans on to find out who it is
+        // talking to, so it rides along with unrelated work rather than
+        // arriving at its own pace: the ceiling has to clear whatever the
+        // busiest session is doing, not what a person clicks.
+        rateLimit: {
+            scope: 'whoami',
+            limit: 1_800,
+            window: 60_000,
+            key: 'user',
+        },
+    },
     handleWhoami,
 );

install.ps1

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

install.sh

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

nginx/nginx.conf

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

package.json

@@ -13,14 +13,9 @@
     "@babel/core": "^7.29.7",
     "@eslint/js": "^9.35.0",
     "@playwright/test": "^1.56.1",
-    "@stylistic/eslint-plugin": "^5.3.1",
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/express": "^5.0.0",
-    "@types/mime-types": "^3.0.1",
     "@typescript-eslint/eslint-plugin": "^8.46.1",
     "@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",
@@ -30,29 +25,23 @@
     "eslint": "^9.35.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",
-    "eslint-rule-composer": "^0.3.0",
     "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",
-    "vite-plugin-static-copy": "^3.3.0",
     "vitest": "^4.1.5",
     "webpack": "^5.88.2",
-    "webpack-cli": "^5.1.1",
-    "yaml": "^2.8.1"
+    "webpack-cli": "^5.1.1"
   },
   "scripts": {
-    "test:backend": "npm run setupExtensions && vitest run --config src/backend/vitest.config.ts ",
-    "test:backend:postgres": "npm run setupExtensions && PUTER_TEST_DB_ENGINE=postgres vitest run --config src/backend/vitest.config.ts ",
+    "test:backend": "npm run setupExtensions && npm run build:workerLib && vitest run --config src/backend/vitest.config.ts ",
+    "test:backend:postgres": "npm run setupExtensions && npm run build:workerLib && PUTER_TEST_DB_ENGINE=postgres vitest run --config src/backend/vitest.config.ts ",
     "test:puterjs": "npm run setupExtensions && vitest run --config src/puter-js/tests/api/vitest.config.ts",
     "test:puterjs:node": "npm run test:puterjs -- src/puter-js/tests/api/runners/node.test.ts",
     "test:puterjs:browser": "npm run test:puterjs -- src/puter-js/tests/api/runners/browser.test.ts",
@@ -60,20 +49,20 @@
     "test:puterjs:coverage": "npm run build:workerLib:coverage && npm run setupExtensions && rm -rf src/puter-js/coverage && PUTER_COVERAGE=1 vitest run --config src/puter-js/tests/api/vitest.config.ts && node ./tools/puterjsCoverageReport.mjs",
     "build:workerLib:coverage": "cd src/puter-js && npm run build:coverage && cd ../worker && npm run build",
     "start:gui": "nodemon --exec \"node dev-server.js\" ",
-    "start": "node --enable-source-maps -r ./dist/src/backend/telemetry.js ./dist/src/backend/index.js",
-    "prestart": "npm run setupExtensions && npm run build:ts",
+    "start": "node ./tools/start.mjs",
     "dev": "npm start",
     "build": "npm run setupExtensions && npm run build:ts && cd src/gui && node ./build.js && cd ../puter-js && npm run build",
     "build:workerLib": "cd src/puter-js && npm run build && cd ../worker && npm run build",
     "check-translations": "node tools/check-translations.js",
     "prepare": "husky",
     "build:ts": "tsc -p tsconfig.build.json && node ./tools/write-dist-package-json.mjs",
+    "check:puterjs:types": "node tools/checkPuterjsTypes.mjs",
+    "typecheck": "node tools/typecheck.mjs",
+    "typecheck:update": "node tools/typecheck.mjs --update",
     "setupExtensions": "node ./tools/extensionSetup.mjs"
   },
   "workspaces": [
-    "src/*",
-    "tools/*",
-    "experiments/js-parse-and-output"
+    "src/*"
   ],
   "nodemonConfig": {
     "ext": "js, json, mjs, jsx, svg, css",
@@ -83,11 +72,8 @@
     ]
   },
   "dependencies": {
-    "@ai-sdk/openai": "^3.0.25",
     "@aws-sdk/client-s3": "^3.1020.0",
     "@aws-sdk/s3-request-presigner": "^3.1028.0",
-    "@heyputer/putility": "^1.0.2",
-    "ai": "^6.0.73",
     "dedent": "^1.5.3",
     "javascript-time-ago": "^2.5.11",
     "libphonenumber-js": "1.13.6",
@@ -99,12 +85,17 @@
   },
   "allowScripts": {
     "@google/genai": false,
-    "bcrypt@5.1.1": true,
-    "better-sqlite3@12.11.1": true,
-    "browser-tabs-lock@1.3.0": true,
-    "classic-level@3.0.0": true,
-    "[email protected]": true,
-    "[email protected]": true,
-    "[email protected]": true
+    "bcrypt": true,
+    "better-sqlite3": true,
+    "browser-tabs-lock": true,
+    "classic-level": true,
+    "esbuild": true,
+    "fsevents": true,
+    "protobufjs": true,
+    "sharp": true,
+    "workerd": true
+  },
+  "overrides": {
+    "undici": "^7.29.0"
   }
 }

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

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

src/backend/clients/alarm/AlarmClient.ts

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

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

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

src/backend/clients/alarm/severity.ts

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

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

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

src/backend/clients/alarm/slack.ts

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

src/backend/clients/alarm/types.ts

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

src/backend/clients/clickhouse/ClickhouseClient.ts

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

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

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

src/backend/clients/database/DatabaseClient.ts

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

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

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

src/backend/clients/database/MySQLDatabaseClient.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -248,9 +248,9 @@ export class MySQLDatabaseClient extends AbstractDatabaseClient {
 
     /**
      * Apply `.sql` files from each configured migration directory in order.
-     * Files within a directory are sorted lexically. Files MUST be
-     * idempotent — there is no per-file applied-state tracking. Failures
-     * abort startup so operators see schema problems loud.
+     * Files within a directory are sorted lexically. Files MUST be idempotent —
+     * there is no per-file applied-state tracking. Failures abort startup so
+     * operators see schema problems loud.
      */
     private async runMigrations(): Promise<void> {
         const paths = this.config.database?.migrationPaths;
@@ -414,8 +414,10 @@ export class MySQLDatabaseClient extends AbstractDatabaseClient {
         return isRetriableError(error);
     }
 
-    /** Replica failures worth retrying on the primary: batcher load-shed
-     *  or transient connection errors — never deterministic SQL errors. */
+    /**
+     * 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);

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

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

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

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

src/backend/clients/database/PostgresDatabaseClient.ts

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

src/backend/clients/database/SQLBatcher.js

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -22,6 +22,7 @@ import {
     POOL_ACQUIRE_TIMEOUT,
     isNeverSentError,
     isRetriableError,
+    isRolledBackError,
 } from './retriableErrors.js';
 
 const DEFAULT_MAX_QUEUE_SIZE = 1000;
@@ -89,20 +90,22 @@ export class SQLBatcher {
     #metricAttrs;
 
     /**
-     * @param {object} dbPool mysql2 pool
+     * @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
+     * @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,
+     * @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
+     * @param {number} [opts.acquireTimeoutMs] Max wait for a pooled connection;
+     *   0 disables the bound
      */
     constructor(
         dbPool,
@@ -359,8 +362,14 @@ export class SQLBatcher {
     // 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.
+    // did not apply — either it never reached the server, or the server
+    // rolled it back itself. A write that died mid-flight may have
+    // committed, and re-running that one would double-apply.
+    //
+    // Lock contention lands in the second group and is worth retrying rather
+    // than surfacing: an item is a single statement, so a deadlock victim has
+    // been fully undone, and the caller sees an unhandled 500 for what the
+    // database is telling us to just run again.
     async #runFallbackItem(b) {
         let attempt = 0;
         while (true) {
@@ -377,8 +386,8 @@ export class SQLBatcher {
                 };
             } catch (error) {
                 const canRetry = this.readOnly
-                    ? isRetriableError(error)
-                    : isNeverSentError(error);
+                    ? isRetriableError(error) || isRolledBackError(error)
+                    : isNeverSentError(error) || isRolledBackError(error);
                 if (!canRetry || attempt >= ITEM_RETRY_ATTEMPTS) {
                     return { ok: false, error };
                 }

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

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -208,6 +208,36 @@ describe('SQLBatcher', () => {
         expect(fallbackAttempts).toBe(2);
     });
 
+    it('retries a deadlocked write instead of surfacing it', async () => {
+        let fallbackAttempts = 0;
+        const conn = makeConnection((sql) => {
+            if (isBatchQuery(sql)) throw makeError('ER_LOCK_DEADLOCK');
+            fallbackAttempts++;
+            if (fallbackAttempts === 1) throw makeError('ER_LOCK_DEADLOCK');
+            return [[{ ok: 1 }], undefined];
+        });
+        const { pool } = makePool(conn);
+        const batcher = new SQLBatcher(pool, { maxTimeInQueue: 5 });
+
+        // The victim statement was rolled back by the server, so re-running it
+        // can't double-apply — the caller should never see the deadlock.
+        const result = await batcher.query('UPDATE notification SET x', []);
+        expect(result[0]).toEqual([{ ok: 1 }]);
+        expect(fallbackAttempts).toBe(2);
+    });
+
+    it('gives up on a write that deadlocks past the retry budget', async () => {
+        const conn = makeConnection(() => {
+            throw makeError('ER_LOCK_DEADLOCK');
+        });
+        const { pool } = makePool(conn);
+        const batcher = new SQLBatcher(pool, { maxTimeInQueue: 5 });
+
+        await expect(batcher.query('UPDATE hot SET x', [])).rejects.toMatchObject(
+            { code: 'ER_LOCK_DEADLOCK' },
+        );
+    });
+
     it('never retries deterministic row-level errors and does not escalate the breaker', async () => {
         let fallbackAttempts = 0;
         const conn = makeConnection((sql) => {

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

@@ -0,0 +1,547 @@
+/**
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import Database from 'better-sqlite3';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { IConfig } from '../../types';
+import { DatabaseClientFactory } from './index.js';
+import { SqliteDatabaseClient } from './SqliteDatabaseClient.js';
+
+/** Highest schema version the migration table can reach. */
+const CURRENT_SCHEMA_VERSION = 66;
+
+/**
+ * These suites migrate real files on disk. Idle they finish in well under a
+ * second, but the whole migration chain runs against the filesystem — enough
+ * that a loaded runner blows the 5s default and reports a timeout where there
+ * is no fault.
+ */
+const DISK_MIGRATION_TIMEOUT_MS = 30_000;
+const SYSTEM_USER_UUID = '5d4adce0-a381-4982-9c02-6e2540026238';
+
+const sqliteConfig = (
+    database: Partial<NonNullable<IConfig['database']>> = {},
+): IConfig =>
+    ({
+        port: 0,
+        extensions: [],
+        database: { engine: 'sqlite', inMemory: true, ...database },
+    }) as IConfig;
+
+const bootClient = async (
+    database: Partial<NonNullable<IConfig['database']>> = {},
+): Promise<SqliteDatabaseClient> => {
+    const client = new SqliteDatabaseClient(sqliteConfig(database));
+    await client.onServerStart();
+    return client;
+};
+
+const userVersionOf = async (client: SqliteDatabaseClient): Promise<number> => {
+    const [row] = await client.read('PRAGMA user_version');
+    return row.user_version as number;
+};
+
+describe('SqliteDatabaseClient — boot and migrations', { timeout: DISK_MIGRATION_TIMEOUT_MS }, () => {
+    let client: SqliteDatabaseClient;
+
+    beforeEach(async () => {
+        client = await bootClient();
+    });
+
+    afterEach(() => {
+        client.onServerShutdown();
+    });
+
+    it('is what the factory picks for the sqlite engine', () => {
+        expect(new DatabaseClientFactory(sqliteConfig())).toBeInstanceOf(
+            SqliteDatabaseClient,
+        );
+    });
+
+    it('migrates a fresh database all the way to the current version', async () => {
+        expect(await userVersionOf(client)).toBe(CURRENT_SCHEMA_VERSION);
+    });
+
+    it('runs the javascript migrations, not just the .sql ones', async () => {
+        // The `system` user only exists because 0025 (a .dbmig.js file) ran
+        // inside the migration VM.
+        const rows = await client.read(
+            'SELECT `username` FROM `user` WHERE `uuid` = ?',
+            [SYSTEM_USER_UUID],
+        );
+        expect(rows).toEqual([{ username: 'system' }]);
+    });
+
+    // 0070 sweeps three by-hand groups no code reads. Both tables it can reach
+    // cascade on delete, so the guard is the point: a group that still carries
+    // permissions or members has to survive, or the sweep silently revokes
+    // them. Re-running the statement is safe — it is a plain conditional DELETE.
+    describe('0070 drop-orphaned-default-groups', () => {
+        const MIGRATION = readFileSync(
+            new URL(
+                './migrations/sqlite/0070_drop-orphaned-default-groups.sql',
+                import.meta.url,
+            ),
+            'utf8',
+        );
+
+        const seedGroup = async (name: string): Promise<number> => {
+            const [system] = await client.read(
+                'SELECT `id` FROM `user` WHERE `uuid` = ?',
+                [SYSTEM_USER_UUID],
+            );
+            const uid = `grp-${name}-${Math.random().toString(36).slice(2, 10)}`;
+            await client.write(
+                'INSERT INTO `group` (`uid`, `owner_user_id`, `extra`, `metadata`) ' +
+                    'VALUES (?, ?, ?, ?)',
+                [uid, system.id, JSON.stringify({ name }), '{}'],
+            );
+            const [row] = await client.read(
+                'SELECT `id` FROM `group` WHERE `uid` = ?',
+                [uid],
+            );
+            return Number(row.id);
+        };
+
+        const stillThere = async (id: number): Promise<boolean> => {
+            const rows = await client.read(
+                'SELECT `id` FROM `group` WHERE `id` = ?',
+                [id],
+            );
+            return rows.length > 0;
+        };
+
+        it('drops an orphaned freeai/experimental/dangerous group', async () => {
+            const ids = await Promise.all(
+                ['freeai', 'experimental', 'dangerous'].map(seedGroup),
+            );
+            await client.write(MIGRATION);
+            for (const id of ids) expect(await stillThere(id)).toBe(false);
+        });
+
+        it('spares one that still carries a permission row', async () => {
+            const id = await seedGroup('freeai');
+            const [system] = await client.read(
+                'SELECT `id` FROM `user` WHERE `uuid` = ?',
+                [SYSTEM_USER_UUID],
+            );
+            await client.write(
+                'INSERT INTO `user_to_group_permissions` ' +
+                    '(`user_id`, `group_id`, `permission`, `extra`) VALUES (?, ?, ?, ?)',
+                [system.id, id, 'service:some-paid-thing', '{}'],
+            );
+
+            await client.write(MIGRATION);
+
+            expect(await stillThere(id)).toBe(true);
+            // And the grant it carries is still intact, not cascaded away.
+            const perms = await client.read(
+                'SELECT `permission` FROM `user_to_group_permissions` WHERE `group_id` = ?',
+                [id],
+            );
+            expect(perms).toEqual([{ permission: 'service:some-paid-thing' }]);
+        });
+
+        it('spares one that still has members', async () => {
+            const id = await seedGroup('experimental');
+            const [system] = await client.read(
+                'SELECT `id` FROM `user` WHERE `uuid` = ?',
+                [SYSTEM_USER_UUID],
+            );
+            await client.write(
+                'INSERT INTO `jct_user_group` (`user_id`, `group_id`) VALUES (?, ?)',
+                [system.id, id],
+            );
+
+            await client.write(MIGRATION);
+
+            expect(await stillThere(id)).toBe(true);
+        });
+
+        it('leaves the groups the platform actually depends on alone', async () => {
+            // system, admin, user and temp are named by config or code.
+            await client.write(MIGRATION);
+            const rows = await client.read(
+                "SELECT json_extract(`extra`, '$.name') AS name FROM `group`",
+            );
+            const names = rows.map((r) => String(r.name));
+            for (const name of ['system', 'admin', 'user']) {
+                expect(names).toContain(name);
+            }
+        });
+    });
+
+    it('leaves an already-migrated database untouched on a second boot', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'puter-sqlite-'));
+        const path = join(dir, 'nested', 'puter.sqlite');
+        try {
+            const first = new SqliteDatabaseClient(
+                sqliteConfig({ inMemory: false, path }),
+            );
+            await first.onServerStart();
+            await first.write(
+                'INSERT INTO `kv` (`user_id`, `kkey_hash`, `kkey`, `value`) ' +
+                    'VALUES (?, ?, ?, ?)',
+                [1, 1, 'boot-marker', '"kept"'],
+            );
+            first.onServerShutdown();
+
+            expect(existsSync(path)).toBe(true);
+
+            const second = new SqliteDatabaseClient(
+                sqliteConfig({ inMemory: false, path }),
+            );
+            await second.onServerStart();
+            await expect(
+                second.read('SELECT `value` FROM `kv` WHERE `kkey` = ?', [
+                    'boot-marker',
+                ]),
+            ).resolves.toEqual([{ value: '"kept"' }]);
+            expect(await userVersionOf(second)).toBe(CURRENT_SCHEMA_VERSION);
+            second.onServerShutdown();
+        } finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+
+    it('stops early at a configured target version', async () => {
+        const partial = await bootClient({ targetVersion: 5 });
+        try {
+            expect(await userVersionOf(partial)).toBe(5);
+            // 0005 landed (apps.background); 0011 (notification) did not.
+            await expect(
+                partial.read(
+                    "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'notification'",
+                ),
+            ).resolves.toEqual([]);
+            await expect(
+                partial.read(
+                    "SELECT 1 FROM pragma_table_info('apps') WHERE name = 'background'",
+                ),
+            ).resolves.toHaveLength(1);
+        } finally {
+            partial.onServerShutdown();
+        }
+    });
+});
+
+describe(
+    'SqliteDatabaseClient — legacy version inference',
+    { timeout: DISK_MIGRATION_TIMEOUT_MS },
+    () => {
+    let dir: string;
+
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), 'puter-sqlite-legacy-'));
+    });
+
+    afterEach(() => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+
+    it('treats user_version=0 with no bootstrap tables as uninitialized', async () => {
+        const path = join(dir, 'blank.sqlite');
+        new Database(path).close();
+
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const client = new SqliteDatabaseClient(
+            sqliteConfig({ inMemory: false, path }),
+        );
+        try {
+            await client.onServerStart();
+            expect(warn).toHaveBeenCalledWith(
+                expect.stringContaining('bootstrap tables are missing'),
+            );
+            // A full migration run followed, so the schema is current.
+            expect(await userVersionOf(client)).toBe(CURRENT_SCHEMA_VERSION);
+        } finally {
+            client.onServerShutdown();
+            warn.mockRestore();
+        }
+    });
+
+    it('infers the schema version from table and column markers', async () => {
+        const path = join(dir, 'legacy.sqlite');
+        const seed = new Database(path);
+        seed.exec(`
+            CREATE TABLE user (
+                id INTEGER PRIMARY KEY,
+                username TEXT,
+                otp_secret TEXT,
+                otp_enabled INTEGER,
+                otp_recovery_codes TEXT
+            );
+            CREATE TABLE apps (
+                id INTEGER PRIMARY KEY,
+                uid TEXT,
+                background INTEGER,
+                metadata TEXT
+            );
+            CREATE TABLE user_to_user_permissions (id INTEGER PRIMARY KEY);
+            CREATE TABLE audit_user_to_user_permissions (
+                id INTEGER PRIMARY KEY,
+                issuer_user_id INTEGER,
+                holder_user_id INTEGER
+            );
+            CREATE TABLE sessions (
+                id INTEGER PRIMARY KEY,
+                created_at INTEGER,
+                last_activity INTEGER
+            );
+            CREATE TABLE kv (id INTEGER PRIMARY KEY, value JSON);
+            INSERT INTO apps (uid)
+                VALUES ('app-e3ac5486-da8c-42ad-8377-8728086e0980');
+        `);
+        seed.close();
+
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        // targetVersion just past the inferred version keeps the run a
+        // no-op, so the assertion is about inference alone.
+        const client = new SqliteDatabaseClient(
+            sqliteConfig({ inMemory: false, path, targetVersion: 22 }),
+        );
+        try {
+            await client.onServerStart();
+            expect(warn).toHaveBeenCalledWith(
+                '[sqlite] user_version=0; inferred legacy schema version 21',
+            );
+            // Nothing was applied, so user_version stays where it was.
+            expect(await userVersionOf(client)).toBe(0);
+        } finally {
+            client.onServerShutdown();
+            warn.mockRestore();
+        }
+    });
+
+    it('reports version 0 when only the bootstrap tables exist', async () => {
+        const path = join(dir, 'bootstrap-only.sqlite');
+        const seed = new Database(path);
+        seed.exec(`
+            CREATE TABLE user (id INTEGER PRIMARY KEY);
+            CREATE TABLE apps (id INTEGER PRIMARY KEY);
+        `);
+        seed.close();
+
+        const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const client = new SqliteDatabaseClient(
+            sqliteConfig({ inMemory: false, path, targetVersion: 1 }),
+        );
+        try {
+            await client.onServerStart();
+            expect(log).toHaveBeenCalledWith('[sqlite] database version: 0');
+        } finally {
+            client.onServerShutdown();
+            log.mockRestore();
+        }
+    });
+});
+
+describe('SqliteDatabaseClient — query interface', () => {
+    let client: SqliteDatabaseClient;
+
+    beforeEach(async () => {
+        client = await bootClient();
+        await client.write(
+            'CREATE TABLE `widget` (`id` INTEGER PRIMARY KEY, ' +
+                '`name` TEXT, `enabled` INTEGER, `seen_at` TEXT)',
+        );
+    });
+
+    afterEach(() => {
+        client.onServerShutdown();
+    });
+
+    it('reports lastInsertRowid and change counts on write', async () => {
+        const inserted = await client.write(
+            'INSERT INTO `widget` (`name`) VALUES (?)',
+            ['spanner'],
+        );
+        expect(inserted).toEqual({
+            insertId: 1,
+            affectedRows: 1,
+            anyRowsAffected: true,
+        });
+
+        const missed = await client.write(
+            'UPDATE `widget` SET `name` = ? WHERE `id` = ?',
+            ['nope', 999],
+        );
+        expect(missed).toMatchObject({
+            affectedRows: 0,
+            anyRowsAffected: false,
+        });
+    });
+
+    it('binds booleans as sqlite integers', async () => {
+        await client.write(
+            'INSERT INTO `widget` (`name`, `enabled`) VALUES (?, ?)',
+            ['toggled', true],
+        );
+        await client.write(
+            'INSERT INTO `widget` (`name`, `enabled`) VALUES (?, ?)',
+            ['untoggled', false],
+        );
+
+        await expect(
+            client.read('SELECT `name`, `enabled` FROM `widget` ORDER BY `id`'),
+        ).resolves.toEqual([
+            { name: 'toggled', enabled: 1 },
+            { name: 'untoggled', enabled: 0 },
+        ]);
+    });
+
+    it('rewrites now() into the sqlite equivalent', async () => {
+        await client.write(
+            'INSERT INTO `widget` (`name`, `seen_at`) VALUES (?, NOW())',
+            ['stamped'],
+        );
+        const [row] = await client.read(
+            'SELECT `seen_at` FROM `widget` WHERE `name` = ?',
+            ['stamped'],
+        );
+        expect(row.seen_at).toMatch(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/);
+    });
+
+    it('generates an INSERT from a data object', async () => {
+        await client.insert('widget', { name: 'generated', enabled: true });
+        await expect(
+            client.read('SELECT `name`, `enabled` FROM `widget`'),
+        ).resolves.toEqual([{ name: 'generated', enabled: 1 }]);
+    });
+
+    it('primary-reads through the same single-node connection', async () => {
+        await client.write('INSERT INTO `widget` (`name`) VALUES (?)', ['p']);
+        await expect(
+            client.pread('SELECT `name` FROM `widget`'),
+        ).resolves.toEqual([{ name: 'p' }]);
+    });
+
+    it('applies a batch write atomically', async () => {
+        await client.batchWrite([
+            {
+                statement:
+                    'INSERT INTO `widget` (`name`, `enabled`) VALUES (?, ?)',
+                values: ['one', true],
+            },
+            {
+                statement: 'INSERT INTO `widget` (`name`) VALUES (?)',
+                values: ['two'],
+            },
+        ]);
+
+        await expect(
+            client.read('SELECT `name` FROM `widget` ORDER BY `id`'),
+        ).resolves.toEqual([{ name: 'one' }, { name: 'two' }]);
+    });
+
+    it('rolls the whole batch back when one statement fails', async () => {
+        await expect(
+            client.batchWrite([
+                {
+                    statement: 'INSERT INTO `widget` (`name`) VALUES (?)',
+                    values: ['kept-if-broken'],
+                },
+                {
+                    statement: 'INSERT INTO `nonexistent` (`name`) VALUES (?)',
+                    values: ['boom'],
+                },
+            ]),
+        ).rejects.toThrow(/no such table/i);
+
+        await expect(
+            client.read('SELECT `name` FROM `widget`'),
+        ).resolves.toEqual([]);
+    });
+
+    it('surfaces sqlite errors for malformed SQL', async () => {
+        await expect(client.read('SELEC oops')).rejects.toThrow(
+            /syntax error/i,
+        );
+    });
+
+    it('closes the database on shutdown', async () => {
+        const closable = await bootClient();
+        closable.onServerShutdown();
+        await expect(closable.read('SELECT 1')).rejects.toThrow(
+            'The database connection is not open',
+        );
+    });
+});
+
+// Single-node engines have no replica to race, so `tryHardRead` must not
+// issue the query twice — the base-class default fires `pread()` and
+// `read()` in parallel, which on sqlite is the same connection.
+describe('SqliteDatabaseClient — tryHardRead', () => {
+    let client: SqliteDatabaseClient;
+
+    beforeEach(async () => {
+        client = await bootClient();
+        await client.write(
+            'CREATE TABLE `widget` (`id` INTEGER PRIMARY KEY, `name` TEXT)',
+        );
+    });
+
+    afterEach(() => {
+        client.onServerShutdown();
+    });
+
+    it('executes the statement exactly once', async () => {
+        await client.write('INSERT INTO `widget` (`name`) VALUES (?)', ['one']);
+        const readSpy = vi.spyOn(client, 'read');
+        const preadSpy = vi.spyOn(client, 'pread');
+
+        await expect(
+            client.tryHardRead('SELECT `name` FROM `widget`'),
+        ).resolves.toEqual([{ name: 'one' }]);
+
+        expect(readSpy).toHaveBeenCalledTimes(1);
+        expect(preadSpy).not.toHaveBeenCalled();
+    });
+
+    it('executes the statement exactly once when it matches no rows', async () => {
+        const readSpy = vi.spyOn(client, 'read');
+        const preadSpy = vi.spyOn(client, 'pread');
+
+        await expect(
+            client.tryHardRead('SELECT `name` FROM `widget`'),
+        ).resolves.toEqual([]);
+
+        expect(readSpy).toHaveBeenCalledTimes(1);
+        expect(preadSpy).not.toHaveBeenCalled();
+    });
+
+    it('throws from requireRead when nothing matches', async () => {
+        await expect(
+            client.requireRead(
+                'SELECT `name` FROM `widget` WHERE `id` = ?',
+                [42],
+            ),
+        ).rejects.toThrow('required read returned no rows');
+    });
+
+    it('returns the rows from requireRead when something matches', async () => {
+        await client.write('INSERT INTO `widget` (`name`) VALUES (?)', ['ok']);
+        await expect(
+            client.requireRead('SELECT `name` FROM `widget`'),
+        ).resolves.toEqual([{ name: 'ok' }]);
+    });
+});

src/backend/clients/database/SqliteDatabaseClient.ts

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

src/backend/clients/database/index.ts

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

src/backend/clients/database/migrationFilenames.ts

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

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

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

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

@@ -0,0 +1,128 @@
+-- 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/>.
+
+-- Enforce "at most one account owns an email address". Mirrors SQLite
+-- migration 0066.
+--
+-- `user.email` is deliberately not UNIQUE: several rows may legitimately hold
+-- the same address while unconfirmed (admin-provisioned placeholders, signups
+-- that were never confirmed, temp accounts on their way to becoming real). What
+-- must never happen is two rows both *owning* an address — owning meaning the
+-- row is confirmed, or holds a password and so can drive password recovery for
+-- that inbox.
+--
+-- Signup, save-account, change-email, OIDC and admin provisioning each check for
+-- an owner before writing, but a check and an insert are not one operation: two
+-- requests can both read "free" and both write. This index is what actually
+-- holds the invariant; the application checks just produce a nicer error most of
+-- the time.
+--
+-- SQLite expresses that with a partial index. MySQL has none, so the predicate
+-- lives in a generated column that evaluates to NULL for every row that does not
+-- own its address — and NULLs do not collide in an InnoDB unique index, which is
+-- exactly the "unlimited unconfirmed placeholders" behaviour we need.
+--
+-- The column is VIRTUAL, not STORED, on purpose: adding a stored generated
+-- column rebuilds the table, while a virtual one is a metadata-only change and
+-- the index that follows builds INPLACE. On a `user` table of any size with
+-- read replicas attached, that is the difference between a routine change and an
+-- outage. The ALGORITHM/LOCK clauses are spelled out so a server that cannot
+-- honour them refuses the statement instead of quietly copying the table.
+--
+-- Matching is on the canonical address so provider aliases
+-- (`[email protected]` vs `[email protected]`) collide. `clean_email` is
+-- written on every modern write path; the COALESCE covers rows old enough to
+-- predate the column. Run the `clean_email` backfill before this migration or
+-- alias collisions among those rows go unnoticed.
+--
+-- Idempotent: both steps are guarded on INFORMATION_SCHEMA so the directory
+-- replays safely.
+--
+-- If the index creation fails with ER_DUP_ENTRY, the DB already contains
+-- duplicate owners. Collapse them first (admin → One-off Jobs → Collapse
+-- Duplicate Emails) — there is no safe automatic merge of two accounts.
+
+DROP PROCEDURE IF EXISTS _puter_add_owned_email;
+DELIMITER //
+CREATE PROCEDURE _puter_add_owned_email()
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.COLUMNS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'user'
+      AND COLUMN_NAME = 'owned_email'
+  ) THEN
+    ALTER TABLE `user`
+      ADD COLUMN `owned_email` VARCHAR(256)
+        CHARACTER SET latin1 COLLATE latin1_swedish_ci
+        GENERATED ALWAYS AS (
+          CASE
+            WHEN `email` IS NOT NULL
+                 AND (`email_confirmed` = 1 OR `password` IS NOT NULL)
+            THEN COALESCE(`clean_email`, LOWER(`email`))
+            ELSE NULL
+          END
+        ) VIRTUAL,
+      ALGORITHM=INSTANT;
+  END IF;
+
+  IF NOT EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.STATISTICS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'user'
+      AND INDEX_NAME = 'idx_user_owned_email'
+  ) THEN
+    ALTER TABLE `user`
+      ADD UNIQUE KEY `idx_user_owned_email` (`owned_email`),
+      ALGORITHM=INPLACE, LOCK=NONE;
+  END IF;
+END//
+DELIMITER ;
+
+CALL _puter_add_owned_email();
+
+DROP PROCEDURE IF EXISTS _puter_add_owned_email;
+
+-- One Puter account per external identity. OIDCStore.link already assumes this
+-- constraint exists — it catches the unique violation to tell "re-linking the
+-- same account" apart from "this sub belongs to someone else" — but the table
+-- never actually had it, so two concurrent first-time logins could each create
+-- an account and each link the same sub. Subsequent logins then resolved to
+-- whichever row came back first.
+--
+-- Dedupe `user_oidc_providers` before applying this: keep the lowest `id` per
+-- (provider, provider_sub) and point it at the account the collapse job kept.
+
+DROP PROCEDURE IF EXISTS _puter_add_oidc_sub_unique;
+DELIMITER //
+CREATE PROCEDURE _puter_add_oidc_sub_unique()
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.STATISTICS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'user_oidc_providers'
+      AND INDEX_NAME = 'idx_user_oidc_provider_sub'
+  ) THEN
+    ALTER TABLE `user_oidc_providers`
+      ADD UNIQUE KEY `idx_user_oidc_provider_sub` (`provider`, `provider_sub`);
+  END IF;
+END//
+DELIMITER ;
+
+CALL _puter_add_oidc_sub_unique();
+
+DROP PROCEDURE IF EXISTS _puter_add_oidc_sub_unique;

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

@@ -0,0 +1,106 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- Grow `share` from a pending-email-invite table into the index of active
+-- shares. See sqlite/0067_share_entries.sql for the column rationale.
+--
+-- Idempotent: columns go through _puter_add_col (from mig_1), indexes and
+-- foreign keys through the guarded procedure below. There is no per-file
+-- applied-state tracking, so every statement must tolerate a re-run.
+
+CALL _puter_add_col('share', 'holder_user_id', '`holder_user_id` int unsigned DEFAULT NULL');
+CALL _puter_add_col('share', 'fsentry_id', '`fsentry_id` int unsigned DEFAULT NULL');
+CALL _puter_add_col('share', 'mode', '`mode` varchar(20) DEFAULT NULL');
+CALL _puter_add_col('share', 'applied_at', '`applied_at` timestamp NULL DEFAULT NULL');
+
+DROP PROCEDURE IF EXISTS _puter_add_share_index_constraints;
+DELIMITER //
+CREATE PROCEDURE _puter_add_share_index_constraints()
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.STATISTICS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'share'
+      AND INDEX_NAME = 'idx_share_holder'
+  ) THEN
+    ALTER TABLE `share` ADD INDEX `idx_share_holder` (`holder_user_id`, `id`);
+  END IF;
+
+  IF NOT EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.STATISTICS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'share'
+      AND INDEX_NAME = 'idx_share_fsentry'
+  ) THEN
+    ALTER TABLE `share` ADD INDEX `idx_share_fsentry` (`fsentry_id`);
+  END IF;
+
+  IF NOT EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.STATISTICS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'share'
+      AND INDEX_NAME = 'idx_share_holder_entry_issuer'
+  ) THEN
+    ALTER TABLE `share` ADD UNIQUE INDEX `idx_share_holder_entry_issuer`
+      (`holder_user_id`, `fsentry_id`, `issuer_user_id`);
+  END IF;
+
+  -- Retiring a deleted node's grants looks them up by permission text
+  -- (`fs:<uuid>` and `fs:<uuid>:%`); the subject lives in that text rather
+  -- than a column, so no foreign key can cascade it. The primary key is
+  -- (issuer, holder, permission), which never puts `permission` first, so
+  -- without this both the equality and the left-anchored LIKE degrade to a
+  -- full scan on the delete path. The column is ascii varchar(255), well
+  -- inside InnoDB's key limit, so it is indexed whole.
+  IF NOT EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.STATISTICS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'user_to_user_permissions'
+      AND INDEX_NAME = 'idx_user_to_user_permissions_permission'
+  ) THEN
+    ALTER TABLE `user_to_user_permissions`
+      ADD INDEX `idx_user_to_user_permissions_permission` (`permission`);
+  END IF;
+
+  IF NOT EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.TABLE_CONSTRAINTS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'share'
+      AND CONSTRAINT_NAME = 'share_holder_user_fk'
+  ) THEN
+    ALTER TABLE `share` ADD CONSTRAINT `share_holder_user_fk`
+      FOREIGN KEY (`holder_user_id`) REFERENCES `user` (`id`)
+      ON DELETE CASCADE ON UPDATE CASCADE;
+  END IF;
+
+  -- The cascade that retires a share with its file.
+  IF NOT EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.TABLE_CONSTRAINTS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'share'
+      AND CONSTRAINT_NAME = 'share_fsentry_fk'
+  ) THEN
+    ALTER TABLE `share` ADD CONSTRAINT `share_fsentry_fk`
+      FOREIGN KEY (`fsentry_id`) REFERENCES `fsentries` (`id`)
+      ON DELETE CASCADE ON UPDATE CASCADE;
+  END IF;
+END//
+DELIMITER ;
+
+CALL _puter_add_share_index_constraints();
+
+DROP PROCEDURE IF EXISTS _puter_add_share_index_constraints;

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

@@ -0,0 +1,35 @@
+-- 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/>.
+
+-- One user refusing contact from another. See sqlite/0068_user-block.sql for
+-- the rationale. `created_at` is unix seconds.
+--
+-- Idempotent: `CREATE TABLE IF NOT EXISTS` with the indexes declared inline,
+-- so the directory can replay safely.
+
+CREATE TABLE IF NOT EXISTS `user_block` (
+    `id` INT NOT NULL AUTO_INCREMENT,
+    `blocker_user_id` INT UNSIGNED NOT NULL,
+    `blocked_user_id` INT UNSIGNED NOT NULL,
+    `created_at` BIGINT NOT NULL,
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `idx_user_block_pair` (`blocker_user_id`, `blocked_user_id`),
+    CONSTRAINT `fk_user_block_blocker` FOREIGN KEY (`blocker_user_id`)
+        REFERENCES `user` (`id`) ON DELETE CASCADE ON UPDATE CASCADE,
+    CONSTRAINT `fk_user_block_blocked` FOREIGN KEY (`blocked_user_id`)
+        REFERENCES `user` (`id`) ON DELETE CASCADE ON UPDATE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

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

@@ -0,0 +1,61 @@
+-- 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/>.
+
+-- Widen `notification.shown` and `notification.acknowledged` to hold the unix
+-- second the store has been writing to them since the backend rework.
+--
+-- Both arrived from the v1 schema as `tinyint(1)`, where they were flags. The
+-- rework changed the writes to timestamps and sqlite (`INTEGER`) and postgres
+-- (`bigint`) took them; only mysql was left too narrow, so every `markShown`
+-- and `markAcknowledged` there fails with ER_WARN_DATA_OUT_OF_RANGE and the
+-- column stays NULL. Dismissing a notification therefore never sticks, and one
+-- already delivered is re-sent on every reconnect.
+--
+-- No backfill: every reader tests `IS NULL` / `IS NOT NULL` only, so a legacy
+-- `1` keeps meaning "yes" once widened.
+--
+-- Guarded on the current type rather than run unconditionally. Changing a
+-- column type copies the table, and this one grows without bound — a migration
+-- directory that replays on every boot must not rebuild it every time.
+
+DROP PROCEDURE IF EXISTS _puter_widen_notification_stamps;
+DELIMITER //
+CREATE PROCEDURE _puter_widen_notification_stamps()
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.COLUMNS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'notification'
+      AND COLUMN_NAME = 'shown'
+      AND DATA_TYPE = 'tinyint'
+  ) THEN
+    ALTER TABLE `notification` MODIFY `shown` BIGINT DEFAULT NULL;
+  END IF;
+
+  IF EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.COLUMNS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'notification'
+      AND COLUMN_NAME = 'acknowledged'
+      AND DATA_TYPE = 'tinyint'
+  ) THEN
+    ALTER TABLE `notification` MODIFY `acknowledged` BIGINT DEFAULT NULL;
+  END IF;
+END //
+DELIMITER ;
+CALL _puter_widen_notification_stamps();
+DROP PROCEDURE IF EXISTS _puter_widen_notification_stamps;

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

@@ -0,0 +1,22 @@
+-- Drops three groups that no code has ever read: `freeai`, `experimental` and
+-- `dangerous`. No migration creates them — they were added by hand back when
+-- hardcoded permissions were keyed by group name. That map is now a flat
+-- per-user floor (`default_user_permissions` in data/hardcoded-permissions.js),
+-- so a group nothing looks up grants nothing, and the rows are dead weight.
+--
+-- Guarded, and deliberately so: `user_to_group_permissions.group_id` and
+-- `jct_user_group.group_id` both cascade on delete, so removing a group that
+-- still carries permissions or members would silently revoke them from every
+-- member. Only a group with neither is dropped. A group that survives this
+-- migration has dependents and needs a deliberate decision, not a sweep --
+-- query `user_to_group_permissions` by `group_id` to see what it holds.
+--
+-- The joins rather than `NOT IN` subqueries: MySQL will not read from the table
+-- it is deleting from inside a subquery on the same statement.
+DELETE g FROM `group` g
+LEFT JOIN `user_to_group_permissions` p ON p.`group_id` = g.`id`
+LEFT JOIN `jct_user_group` j ON j.`group_id` = g.`id`
+WHERE JSON_UNQUOTE(JSON_EXTRACT(g.`extra`, '$.name'))
+        IN ('freeai', 'experimental', 'dangerous')
+  AND p.`group_id` IS NULL
+  AND j.`group_id` IS NULL;

src/backend/clients/database/migrations/postgres/postgres_mig_10.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/>.
+
+-- Enforce "at most one account owns an email address". Mirrors SQLite
+-- migration 0066 and MySQL migration 21; see those for the full rationale.
+--
+-- In short: `user.email` is deliberately not UNIQUE because several rows may
+-- hold the same address while unconfirmed. What must not happen is two rows
+-- both owning it — confirmed, or holding a password and so able to drive
+-- password recovery for that inbox. The application checks for an owner before
+-- every write, but a check and a write are not one operation.
+--
+-- If this fails, the DB already contains duplicate owners; collapse them first
+-- (admin → One-off Jobs → Collapse Duplicate Emails).
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_user_owned_email
+    ON "user" (COALESCE(clean_email, LOWER(email)))
+    WHERE email IS NOT NULL
+      AND (email_confirmed = TRUE OR password IS NOT NULL);
+
+-- One Puter account per external identity. OIDCStore.link already assumes this
+-- constraint exists — it catches the unique violation to tell "re-linking the
+-- same account" apart from "this sub belongs to someone else" — but the table
+-- never actually had it.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_user_oidc_provider_sub
+    ON user_oidc_providers (provider, provider_sub);

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

@@ -0,0 +1,42 @@
+-- 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/>.
+
+-- Grow share from a pending-email-invite table into the index of active
+-- shares. See sqlite/0067_share_entries.sql for the column rationale.
+
+ALTER TABLE share
+  ADD COLUMN IF NOT EXISTS holder_user_id integer
+      REFERENCES "user" (id) ON DELETE CASCADE ON UPDATE CASCADE,
+  ADD COLUMN IF NOT EXISTS fsentry_id integer
+      REFERENCES fsentries (id) ON DELETE CASCADE ON UPDATE CASCADE,
+  ADD COLUMN IF NOT EXISTS mode varchar(20),
+  ADD COLUMN IF NOT EXISTS applied_at timestamp;
+
+CREATE INDEX IF NOT EXISTS idx_share_holder
+    ON share (holder_user_id, id);
+CREATE INDEX IF NOT EXISTS idx_share_fsentry
+    ON share (fsentry_id);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_share_holder_entry_issuer
+    ON share (holder_user_id, fsentry_id, issuer_user_id);
+
+-- Retiring a deleted node's grants looks them up by permission text, and the
+-- primary key is (issuer, holder, permission) — `permission` is never the
+-- leading column, so the delete path would otherwise scan the table. The
+-- text_pattern_ops class is what makes the left-anchored LIKE a range scan
+-- under a non-C collation; plain equality still uses it.
+CREATE INDEX IF NOT EXISTS idx_user_to_user_permissions_permission
+    ON user_to_user_permissions (permission text_pattern_ops);

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

@@ -0,0 +1,33 @@
+-- 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/>.
+
+-- One user refusing contact from another. See sqlite/0068_user-block.sql for
+-- the rationale. `created_at` is unix seconds.
+--
+-- Idempotent via IF NOT EXISTS.
+
+CREATE TABLE IF NOT EXISTS user_block (
+    id BIGSERIAL PRIMARY KEY,
+    blocker_user_id integer NOT NULL
+        REFERENCES "user" (id) ON DELETE CASCADE ON UPDATE CASCADE,
+    blocked_user_id integer NOT NULL
+        REFERENCES "user" (id) ON DELETE CASCADE ON UPDATE CASCADE,
+    created_at BIGINT NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_user_block_pair
+    ON user_block (blocker_user_id, blocked_user_id);

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

@@ -0,0 +1,20 @@
+-- Drops three groups that no code has ever read: `freeai`, `experimental` and
+-- `dangerous`. No migration creates them — they were added by hand back when
+-- hardcoded permissions were keyed by group name. That map is now a flat
+-- per-user floor (`default_user_permissions` in data/hardcoded-permissions.js),
+-- so a group nothing looks up grants nothing, and the rows are dead weight.
+--
+-- Guarded, and deliberately so: user_to_group_permissions.group_id and
+-- jct_user_group.group_id both cascade on delete, so removing a group that
+-- still carries permissions or members would silently revoke them from every
+-- member. Only a group with neither is dropped. A group that survives this
+-- migration has dependents and needs a deliberate decision, not a sweep --
+-- query user_to_group_permissions by group_id to see what it holds.
+DELETE FROM "group" g
+WHERE g.extra ->> 'name' IN ('freeai', 'experimental', 'dangerous')
+  AND NOT EXISTS (
+      SELECT 1 FROM user_to_group_permissions p WHERE p.group_id = g.id
+  )
+  AND NOT EXISTS (
+      SELECT 1 FROM jct_user_group j WHERE j.group_id = g.id
+  );

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

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

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

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

src/backend/clients/database/migrations/sqlite/0066_owned-email-unique.sql

@@ -0,0 +1,53 @@
+-- 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/>.
+
+-- Enforce "at most one account owns an email address".
+--
+-- `user.email` is deliberately not UNIQUE: several rows may legitimately hold
+-- the same address while unconfirmed (admin-provisioned placeholders, signups
+-- that were never confirmed, temp accounts on their way to becoming real). What
+-- must never happen is two rows both *owning* an address — owning meaning the
+-- row is confirmed, or holds a password and so can drive password recovery for
+-- that inbox.
+--
+-- Signup, save-account, change-email, OIDC and admin provisioning each check for
+-- an owner before writing, but a check and an insert are not one operation: two
+-- requests can both read "free" and both write. This index is what actually
+-- holds the invariant; the application checks just produce a nicer error most of
+-- the time.
+--
+-- Matching is on the canonical address so provider aliases
+-- (`[email protected]` vs `[email protected]`) collide. `clean_email` is
+-- written on every modern write path; the COALESCE covers rows old enough to
+-- predate the column.
+--
+-- If this CREATE fails, the DB already contains duplicate owners. Collapse them
+-- first (admin → One-off Jobs → Collapse Duplicate Emails) — there is no safe
+-- automatic merge of two accounts.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_user_owned_email
+    ON user(COALESCE(clean_email, lower(email)))
+    WHERE email IS NOT NULL
+      AND (email_confirmed = 1 OR password IS NOT NULL);
+
+-- One Puter account per external identity. OIDCStore.link already assumes this
+-- constraint exists — it catches the unique violation to tell "re-linking the
+-- same account" apart from "this sub belongs to someone else" — but the table
+-- never actually had it, so two concurrent first-time logins could each create
+-- an account and each link the same sub. Subsequent logins then resolved to
+-- whichever row came back first.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_user_oidc_provider_sub
+    ON user_oidc_providers(provider, provider_sub);

src/backend/clients/database/migrations/sqlite/0067_share_entries.sql

@@ -0,0 +1,60 @@
+-- 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/>.
+
+-- Grow `share` from a pending-email-invite table into the index of active
+-- shares. Permissions stay the source of truth for access; this is what makes
+-- shares listable and gives them a lifecycle.
+--
+--   - `holder_user_id` : NULL while an invite awaits signup.
+--   - `fsentry_id`     : the shared node. ON DELETE CASCADE retires the share
+--                        with the file, which permissions alone don't do.
+--   - `mode`           : see|list|read|write|manage. Unconstrained on purpose —
+--                        ACLService owns the mode set and adding one shouldn't
+--                        need a three-dialect migration.
+--   - `applied_at`     : set when an invite is claimed. Claiming updates the
+--                        row rather than deleting it, so the share stays
+--                        queryable.
+
+ALTER TABLE `share` ADD COLUMN `holder_user_id` INTEGER DEFAULT NULL
+    REFERENCES `user` (`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE `share` ADD COLUMN `fsentry_id` INTEGER DEFAULT NULL
+    REFERENCES `fsentries` (`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE `share` ADD COLUMN `mode` TEXT DEFAULT NULL;
+ALTER TABLE `share` ADD COLUMN `applied_at` TIMESTAMP DEFAULT NULL;
+
+-- "Shared with me", keyset-paginated: ORDER BY ends in `id` as the tiebreaker.
+CREATE INDEX IF NOT EXISTS `idx_share_holder`
+    ON `share` (`holder_user_id`, `id`);
+
+-- Who has access to one node — also how an owner sees a manage-delegate's
+-- re-grants, which the issuer/holder permission tables can't answer.
+CREATE INDEX IF NOT EXISTS `idx_share_fsentry` ON `share` (`fsentry_id`);
+
+-- One row per (holder, node, issuer). Pending invites have a NULL
+-- holder_user_id and so aren't covered here; dedup for those belongs with the
+-- invite flow.
+CREATE UNIQUE INDEX IF NOT EXISTS `idx_share_holder_entry_issuer`
+    ON `share` (`holder_user_id`, `fsentry_id`, `issuer_user_id`);
+
+-- Retiring a deleted node's grants looks them up by permission text
+-- (`fs:<uuid>` and `fs:<uuid>:%`), and the subject only lives in that text —
+-- no column, so no foreign key can cascade it. The table's primary key is
+-- (issuer, holder, permission), which never puts `permission` first, so
+-- without this the equality and the left-anchored LIKE both degrade to a full
+-- scan on the delete path. With it, each is a range scan.
+CREATE INDEX IF NOT EXISTS `idx_user_to_user_permissions_permission`
+    ON `user_to_user_permissions` (`permission`);

src/backend/clients/database/migrations/sqlite/0068_referral-code-unique.sql

@@ -0,0 +1,32 @@
+-- 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/>.
+
+-- One referral code, one account. The mysql and postgres baselines have
+-- declared `user.referral_code` UNIQUE since the column was introduced; the
+-- sqlite baseline only declared the column, so the invariant held on hosted
+-- deployments and not on self-hosted ones.
+--
+-- Codes are minted by picking at random and writing, so this index is not a
+-- nicety: it is what makes "did anyone already take this code" a decision the
+-- database makes once, instead of a read the next mint can race. A caller that
+-- loses the race sees a unique violation and picks again.
+--
+-- NULL is distinct from NULL in a sqlite unique index, so accounts that have
+-- never asked for a code (the majority) are unaffected.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_user_referral_code
+    ON user(referral_code)
+    WHERE referral_code IS NOT NULL;

src/backend/clients/database/migrations/sqlite/0069_user-block.sql

@@ -0,0 +1,39 @@
+-- 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/>.
+
+-- One user refusing contact from another. Sharing is what reads it today —
+-- a blocked sender's share is refused outright, and their pending invite is
+-- dropped when the blocker confirms the address it was aimed at — but the
+-- table is deliberately not share-specific: the same answer serves anything
+-- else one person can push at another.
+--
+-- Rows are read on the share path by exact (blocker, blocked) pair, which the
+-- unique index answers as a point lookup; the same index's leading column
+-- serves "who have I blocked". `created_at` is unix seconds, matching
+-- `app_feedback`.
+
+CREATE TABLE IF NOT EXISTS `user_block` (
+    "id" INTEGER PRIMARY KEY AUTOINCREMENT,
+    "blocker_user_id" INTEGER NOT NULL
+        REFERENCES `user` ("id") ON DELETE CASCADE ON UPDATE CASCADE,
+    "blocked_user_id" INTEGER NOT NULL
+        REFERENCES `user` ("id") ON DELETE CASCADE ON UPDATE CASCADE,
+    "created_at" INTEGER NOT NULL       -- unix seconds
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS `idx_user_block_pair`
+    ON `user_block` (`blocker_user_id`, `blocked_user_id`);

src/backend/clients/database/migrations/sqlite/0070_drop-orphaned-default-groups.sql

@@ -0,0 +1,33 @@
+-- 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/>.
+
+-- Drops three groups that no code has ever read: `freeai`, `experimental` and
+-- `dangerous`. No migration creates them — they were added by hand back when
+-- hardcoded permissions were keyed by group name. That map is now a flat
+-- per-user floor (`default_user_permissions` in data/hardcoded-permissions.js),
+-- so a group nothing looks up grants nothing, and the rows are dead weight.
+--
+-- Guarded, and deliberately so: `user_to_group_permissions.group_id` and
+-- `jct_user_group.group_id` both cascade on delete, so removing a group that
+-- still carries permissions or members would silently revoke them from every
+-- member. Only a group with neither is dropped. A group that survives this
+-- migration has dependents and needs a deliberate decision, not a sweep --
+-- query `user_to_group_permissions` by `group_id` to see what it holds.
+DELETE FROM `group`
+WHERE json_extract(`extra`, '$.name') IN ('freeai', 'experimental', 'dangerous')
+  AND `id` NOT IN (SELECT `group_id` FROM `user_to_group_permissions`)
+  AND `id` NOT IN (SELECT `group_id` FROM `jct_user_group`);

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

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

src/backend/clients/database/preparePostgresSql.ts

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

src/backend/clients/database/retriableErrors.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -41,11 +41,10 @@ const RETRIABLE_ERROR_MESSAGES = [
 ];
 
 /**
- * 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.
+ * 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',
@@ -55,14 +54,33 @@ const NEVER_SENT_ERROR_CODES = new Set([
     POOL_ACQUIRE_TIMEOUT,
 ]);
 
+/**
+ * Failures the server itself rolled back before returning. The statement did
+ * reach the database, so this is not `NEVER_SENT`, but InnoDB guarantees it
+ * left no effect — which makes a retry just as safe for writes.
+ *
+ * Only true for a _single_ statement: under autocommit each statement is its
+ * own transaction, so "the transaction was rolled back" means "this statement
+ * was rolled back". Retrying a multi-statement string on one of these would
+ * re-run the statements that already committed ahead of the failure.
+ */
+const ROLLED_BACK_ERROR_CODES = new Set([
+    // Deadlock — InnoDB picked this transaction as the victim and undid it.
+    // MySQL's own message for it is "try restarting transaction".
+    'ER_LOCK_DEADLOCK',
+    // Lock wait timeout. Rolls back the statement rather than the transaction
+    // unless innodb_rollback_on_timeout is set — the same thing when the
+    // transaction is one statement.
+    'ER_LOCK_WAIT_TIMEOUT',
+]);
+
 const errorCode = (error: unknown): string | undefined =>
     (error as { code?: string } | null)?.code;
 
 /**
- * Transient connection-level failures worth retrying — but only for
- * statements that are safe to run twice (reads). Row-level errors
- * (duplicate key, constraint violations) are deterministic and never
- * match.
+ * 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);
@@ -76,3 +94,13 @@ export const isNeverSentError = (error: unknown): boolean => {
     const code = errorCode(error);
     return Boolean(code && NEVER_SENT_ERROR_CODES.has(code));
 };
+
+/**
+ * Lock-contention failures the server rolled back on its own. Safe to retry a
+ * single statement on, writes included — see `ROLLED_BACK_ERROR_CODES` for the
+ * one-statement precondition.
+ */
+export const isRolledBackError = (error: unknown): boolean => {
+    const code = errorCode(error);
+    return Boolean(code && ROLLED_BACK_ERROR_CODES.has(code));
+};

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

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

src/backend/clients/database/splitMysqlStatements.ts

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

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

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

src/backend/clients/database/splitPostgresStatements.ts

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

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

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

src/backend/clients/dynamodb/DDBClient.ts

@@ -1,21 +1,20 @@
-/**
+/*
  * 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.
+ * 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/](https://www.gnu.org/licenses/).
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
 import {
@@ -46,6 +45,11 @@ import { HttpError } from '../../core/http';
 import type { IConfig, IDynamoConfig } from '../../types';
 import { Span } from '../../util/span.js';
 import { PuterClient } from '../types';
+import {
+    clampStoredNumber,
+    isRepairableMarshallError,
+    repairForMarshall,
+} from './marshallRepair.js';
 
 const LOCAL_DYNAMO_MEMORY_PREFIX = ':memory:';
 const localDynaliteEndpointPromises = new Map<string, Promise<string>>();
@@ -115,6 +119,49 @@ const sleep = async (ms: number) => {
     await new Promise((resolve) => setTimeout(resolve, ms));
 };
 
+// One caller writing an out-of-range number usually keeps doing it, so the
+// warning is per-target and throttled rather than one line per write.
+const REPAIR_WARNING_INTERVAL_MS = 60_000;
+const lastRepairWarningAt = new Map<string, number>();
+
+const warnRepaired = (target: string, message: string): void => {
+    const now = Date.now();
+    const lastWarnedAt = lastRepairWarningAt.get(target) ?? 0;
+    if (now - lastWarnedAt < REPAIR_WARNING_INTERVAL_MS) return;
+
+    lastRepairWarningAt.set(target, now);
+    console.warn(
+        `[ddb] clamped an out-of-range value in ${target}: ${message}`,
+    );
+};
+
+/**
+ * Send a write, and if the payload was rejected while being encoded for a value
+ * the store cannot represent, clamp it and send it once more.
+ *
+ * Nothing is inspected on the way in: the payload of a successful write is
+ * never walked, so this costs one `try` on the hot path. The repair only runs
+ * on the failure, and only retries when it actually changed something —
+ * otherwise the original error stands.
+ */
+const sendRepairingValues = async <TPayload, TResult>(
+    payload: TPayload,
+    send: (payload: TPayload) => Promise<TResult>,
+    describe: () => string,
+): Promise<TResult> => {
+    try {
+        return await send(payload);
+    } catch (error) {
+        if (!isRepairableMarshallError(error)) throw error;
+
+        const repaired = repairForMarshall(payload);
+        if (!repaired.changed) throw error;
+
+        warnRepaired(describe(), (error as Error).message);
+        return send(repaired.value as TPayload);
+    }
+};
+
 export class DDBClient extends PuterClient {
     #documentClient: DynamoDBDocumentClient | null = null;
     #localInitPromise: Promise<void> | null = null;
@@ -172,14 +219,19 @@ export class DDBClient extends PuterClient {
 
     @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,
-            Item: item,
-            ReturnConsumedCapacity: 'TOTAL',
-        });
-
         const client = await this.#getDocumentClient();
-        return client.send(command);
+        return sendRepairingValues(
+            item,
+            (itemToWrite) =>
+                client.send(
+                    new PutCommand({
+                        TableName: table,
+                        Item: itemToWrite,
+                        ReturnConsumedCapacity: 'TOTAL',
+                    }),
+                ),
+            () => `a put to ${table}`,
+        );
     }
 
     @Span('ddb.batchGet', (params: unknown[]) => ({
@@ -223,6 +275,37 @@ export class DDBClient extends PuterClient {
         'db.batch_size': params.length,
     }))
     async batchPut(params: { table: string; item: Record<string, unknown> }[]) {
+        return this.#batchWrite(
+            params.map(({ table, item }) => ({
+                table,
+                request: { PutRequest: { Item: item } },
+            })),
+        );
+    }
+
+    @Span('ddb.batchDel', (params: unknown[]) => ({
+        'db.batch_size': params.length,
+    }))
+    async batchDel(params: { table: string; key: Record<string, unknown> }[]) {
+        return this.#batchWrite(
+            params.map(({ table, key }) => ({
+                table,
+                request: { DeleteRequest: { Key: key } },
+            })),
+        );
+    }
+
+    // Shared BatchWriteItem plumbing for batchPut/batchDel: 25-item chunks,
+    // UnprocessedItems retried with capped exponential backoff, consumed
+    // capacity accumulated per table across every request.
+    async #batchWrite(
+        params: {
+            table: string;
+            request: NonNullable<
+                BatchWriteCommandInput['RequestItems']
+            >[string][number];
+        }[],
+    ) {
         const consumedCapacityByTable = new Map<string, number>();
         if (params.length === 0) {
             return { ConsumedCapacity: [] };
@@ -259,11 +342,7 @@ export class DDBClient extends PuterClient {
             let requestItems = chunk.reduce(
                 (acc, curr) => {
                     const tableRequests = acc[curr.table] ?? [];
-                    tableRequests.push({
-                        PutRequest: {
-                            Item: curr.item,
-                        },
-                    });
+                    tableRequests.push(curr.request);
                     acc[curr.table] = tableRequests;
                     return acc;
                 },
@@ -279,11 +358,17 @@ export class DDBClient extends PuterClient {
                     break;
                 }
 
-                const response = await client.send(
-                    new BatchWriteCommand({
-                        RequestItems: requestItems,
-                        ReturnConsumedCapacity: 'TOTAL',
-                    }),
+                const response = await sendRepairingValues(
+                    requestItems,
+                    (itemsToWrite) =>
+                        client.send(
+                            new BatchWriteCommand({
+                                RequestItems: itemsToWrite,
+                                ReturnConsumedCapacity: 'TOTAL',
+                            }),
+                        ),
+                    () =>
+                        `a batch write to ${Object.keys(requestItems).join(', ')}`,
                 );
                 accumulateConsumedCapacity(
                     response.ConsumedCapacity as
@@ -329,11 +414,18 @@ export class DDBClient extends PuterClient {
     }
 
     @Span('ddb.del', (table: string) => ({ 'db.table': table }))
-    async del<T extends Record<string, unknown>>(table: string, key: T) {
+    async del<T extends Record<string, unknown>>(
+        table: string,
+        key: T,
+        opts?: { returnOld?: boolean },
+    ) {
         const command = new DeleteCommand({
             TableName: table,
             Key: key,
             ReturnConsumedCapacity: 'TOTAL',
+            // ALL_OLD makes the delete an atomic claim: exactly one caller
+            // gets the attributes back.
+            ...(opts?.returnOld ? { ReturnValues: 'ALL_OLD' as const } : {}),
         });
 
         const client = await this.#getDocumentClient();
@@ -424,20 +516,27 @@ export class DDBClient extends PuterClient {
             !!expressionValues && Object.keys(expressionValues).length > 0;
         const hasNames =
             !!expressionNames && Object.keys(expressionNames).length > 0;
-        const command = new UpdateCommand({
-            TableName: table,
-            Key: key,
-            UpdateExpression: expression,
-            ...(hasValues
-                ? { ExpressionAttributeValues: expressionValues }
-                : {}),
-            ...(hasNames ? { ExpressionAttributeNames: expressionNames } : {}),
-            ReturnValues: 'ALL_NEW',
-            ReturnConsumedCapacity: 'TOTAL',
-        });
-
         const client = await this.#getDocumentClient();
-        return client.send(command);
+        return sendRepairingValues(
+            expressionValues,
+            (valuesToWrite) =>
+                client.send(
+                    new UpdateCommand({
+                        TableName: table,
+                        Key: key,
+                        UpdateExpression: expression,
+                        ...(hasValues
+                            ? { ExpressionAttributeValues: valuesToWrite }
+                            : {}),
+                        ...(hasNames
+                            ? { ExpressionAttributeNames: expressionNames }
+                            : {}),
+                        ReturnValues: 'ALL_NEW',
+                        ReturnConsumedCapacity: 'TOTAL',
+                    }),
+                ),
+            () => `an update to ${table}`,
+        );
     }
 
     async createTableIfNotExists(
@@ -539,6 +638,9 @@ export class DDBClient extends PuterClient {
             marshallOptions: {
                 removeUndefinedValues: true,
             },
+            unmarshallOptions: {
+                wrapNumbers: clampStoredNumber,
+            },
         });
     }
 
@@ -566,6 +668,9 @@ export class DDBClient extends PuterClient {
             marshallOptions: {
                 removeUndefinedValues: true,
             },
+            unmarshallOptions: {
+                wrapNumbers: clampStoredNumber,
+            },
         });
     }
 

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

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest';
+import {
+    clampStoredNumber,
+    isRepairableMarshallError,
+    MAX_STORED_NUMBER,
+    MIN_STORED_NUMBER,
+    repairForMarshall,
+} from './marshallRepair.ts';
+
+describe('isRepairableMarshallError', () => {
+    it('recognizes the out-of-range and special-value failures', () => {
+        for (const message of [
+            'Number 1.6515584833071455e+55 is greater than Number.MAX_SAFE_INTEGER. Use NumberValue from @aws-sdk/lib-dynamodb.',
+            'Number -1e+55 is lesser than Number.MIN_SAFE_INTEGER. Use NumberValue from @aws-sdk/lib-dynamodb.',
+            'Special numeric value NaN is not allowed',
+            'Special numeric value Infinity is not allowed',
+        ]) {
+            expect(isRepairableMarshallError(new Error(message))).toBe(true);
+        }
+    });
+
+    it('leaves every other failure alone', () => {
+        for (const error of [
+            new Error('Unsupported type passed: [object Symbol].'),
+            new Error('ValidationException'),
+            new Error(''),
+            undefined,
+            'not an error',
+        ]) {
+            expect(isRepairableMarshallError(error)).toBe(false);
+        }
+    });
+});
+
+describe('repairForMarshall', () => {
+    it('clamps a number past the safe range in both directions', () => {
+        expect(repairForMarshall(1.6515584833071455e55)).toEqual({
+            value: MAX_STORED_NUMBER,
+            changed: true,
+        });
+        expect(repairForMarshall(-1e55)).toEqual({
+            value: MIN_STORED_NUMBER,
+            changed: true,
+        });
+    });
+
+    it('clamps infinities and nulls NaN', () => {
+        expect(repairForMarshall(Infinity).value).toBe(MAX_STORED_NUMBER);
+        expect(repairForMarshall(-Infinity).value).toBe(MIN_STORED_NUMBER);
+        expect(repairForMarshall(NaN)).toEqual({ value: null, changed: true });
+    });
+
+    it('repairs numbers nested in objects and arrays', () => {
+        const repaired = repairForMarshall({
+            profile: { netWorth: 1e55, level: 29 },
+            scores: [1, [2, -1e55]],
+        });
+
+        expect(repaired.changed).toBe(true);
+        expect(repaired.value).toEqual({
+            profile: { netWorth: MAX_STORED_NUMBER, level: 29 },
+            scores: [1, [2, MIN_STORED_NUMBER]],
+        });
+    });
+
+    it('returns the original payload untouched when nothing is out of range', () => {
+        const payload = {
+            a: MAX_STORED_NUMBER,
+            b: [1, 2, { c: 'three' }],
+            d: null,
+        };
+
+        const repaired = repairForMarshall(payload);
+        expect(repaired.changed).toBe(false);
+        expect(repaired.value).toBe(payload);
+    });
+
+    it('does not mutate the payload it repairs', () => {
+        const nested = { netWorth: 1e55 };
+        const payload = { nested };
+
+        repairForMarshall(payload);
+
+        expect(nested.netWorth).toBe(1e55);
+    });
+
+    it('keeps a `__proto__` key as data', () => {
+        const payload = JSON.parse('{"__proto__":{"big":1e55}}');
+
+        const repaired = repairForMarshall(payload) as {
+            value: Record<string, unknown>;
+            changed: boolean;
+        };
+
+        expect(repaired.changed).toBe(true);
+        expect(Object.getPrototypeOf(repaired.value)).toBe(Object.prototype);
+        expect(
+            Object.getOwnPropertyDescriptor(repaired.value, '__proto__')?.value,
+        ).toEqual({ big: MAX_STORED_NUMBER });
+    });
+
+    it('leaves values it does not own alone', () => {
+        const date = new Date(0);
+        expect(repairForMarshall(date).value).toBe(date);
+        expect(repairForMarshall('str')).toEqual({
+            value: 'str',
+            changed: false,
+        });
+    });
+});
+
+describe('clampStoredNumber', () => {
+    it('decodes a number inside the range unchanged', () => {
+        expect(clampStoredNumber('42')).toBe(42);
+        expect(clampStoredNumber('-0.5')).toBe(-0.5);
+        expect(clampStoredNumber(String(MAX_STORED_NUMBER))).toBe(
+            MAX_STORED_NUMBER,
+        );
+    });
+
+    it('clamps a stored number past the range instead of decoding a BigInt', () => {
+        expect(clampStoredNumber('18014398509481982')).toBe(MAX_STORED_NUMBER);
+        expect(clampStoredNumber('-18014398509481982')).toBe(MIN_STORED_NUMBER);
+        expect(clampStoredNumber('1e400')).toBe(MAX_STORED_NUMBER);
+    });
+});

src/backend/clients/dynamodb/marshallRepair.ts

@@ -0,0 +1,129 @@
+/*
+ * 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/>.
+ */
+
+/**
+ * A stored number keeps its exact value only within the IEEE-754 safe integer
+ * range; a magnitude past this cannot round-trip, and the document client
+ * refuses to marshall one rather than write a value that reads back wrong.
+ */
+export const MAX_STORED_NUMBER = Number.MAX_SAFE_INTEGER;
+export const MIN_STORED_NUMBER = Number.MIN_SAFE_INTEGER;
+
+/**
+ * Marshalling failures a retry can fix by clamping: an out-of-range number, or
+ * a special numeric value (`NaN`, `±Infinity`) that has no representation at
+ * all. Matched on the message because they are plain `Error`s thrown while
+ * encoding the payload — no error name or code separates them from anything
+ * else, and they never reach the wire, so there is no response to inspect.
+ */
+const REPAIRABLE_MARSHALL_ERRORS = [
+    /is greater than Number\.MAX_SAFE_INTEGER/,
+    /is lesser than Number\.MIN_SAFE_INTEGER/,
+    /^Special numeric value /,
+];
+
+export const isRepairableMarshallError = (error: unknown): boolean => {
+    const message = (error as Error | undefined)?.message;
+    if (typeof message !== 'string') return false;
+    return REPAIRABLE_MARSHALL_ERRORS.some((pattern) => pattern.test(message));
+};
+
+/**
+ * The same bound, applied to what comes back. A stored number past the safe
+ * range — left by an older write, or reached by a counter incremented up to it
+ * — is otherwise decoded as a `BigInt`, which no JSON response can carry. This
+ * hands back the same kind of value a write accepts, and does less work per
+ * number than the default decoding it replaces.
+ */
+export const clampStoredNumber = (stored: string): number => {
+    const num = Number(stored);
+    if (num > MAX_STORED_NUMBER) return MAX_STORED_NUMBER;
+    if (num < MIN_STORED_NUMBER) return MIN_STORED_NUMBER;
+    return num;
+};
+
+export interface MarshallRepair {
+    value: unknown;
+    /** False when nothing in the payload was out of range — nothing to retry. */
+    changed: boolean;
+}
+
+const unchanged = (value: unknown): MarshallRepair => ({
+    value,
+    changed: false,
+});
+
+// Matches the shapes the marshaller walks into as a map: object literals and
+// null-prototype objects, but not class instances (Date, Buffer, Set, …),
+// which it encodes by their own rules.
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+    typeof value === 'object' &&
+    value !== null &&
+    (value.constructor === Object || value.constructor === undefined);
+
+const repairNumber = (num: number): MarshallRepair => {
+    // No representation for these; JSON already turns them into null, so a
+    // caller that got one this far did not send it as JSON.
+    if (Number.isNaN(num)) return { value: null, changed: true };
+    if (num > MAX_STORED_NUMBER)
+        return { value: MAX_STORED_NUMBER, changed: true };
+    if (num < MIN_STORED_NUMBER)
+        return { value: MIN_STORED_NUMBER, changed: true };
+    return unchanged(num);
+};
+
+/**
+ * Clamp every number a payload holds into the range the store accepts,
+ * returning the original object untouched when nothing needed it — callers hold
+ * on to the values they pass (caches, retries), so a repair copies rather than
+ * mutating in place.
+ *
+ * Only run after a marshalling failure. Walking a payload this way costs as
+ * much as marshalling it, which is exactly why writes are not checked up
+ * front.
+ */
+export const repairForMarshall = (value: unknown): MarshallRepair => {
+    if (typeof value === 'number') return repairNumber(value);
+
+    if (Array.isArray(value)) {
+        let changed = false;
+        const repairedEntries = value.map((entry) => {
+            const repaired = repairForMarshall(entry);
+            changed = changed || repaired.changed;
+            return repaired.value;
+        });
+        return changed ? { value: repairedEntries, changed } : unchanged(value);
+    }
+
+    if (isPlainObject(value)) {
+        let changed = false;
+        const repairedEntries = Object.entries(value).map(([key, entry]) => {
+            const repaired = repairForMarshall(entry);
+            changed = changed || repaired.changed;
+            return [key, repaired.value] as const;
+        });
+        // `fromEntries` defines each property rather than assigning it, so a
+        // `__proto__` key in the payload stays data here.
+        return changed
+            ? { value: Object.fromEntries(repairedEntries), changed }
+            : unchanged(value);
+    }
+
+    return unchanged(value);
+};

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

@@ -0,0 +1,462 @@
+/**
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import type { IConfig } from '../../types';
+import { EmailClient } from './EmailClient';
+
+const FROM = '"Puter" <[email protected]>';
+
+/**
+ * Nodemailer's JSON transport is a real transport that serializes the message
+ * instead of talking SMTP — the send path stays genuine while the wire stays
+ * local.
+ */
+const jsonTransportConfig = (overrides: Partial<IConfig> = {}): IConfig =>
+    ({
+        port: 0,
+        extensions: [],
+        env: 'prod',
+        email: { jsonTransport: true, from: FROM },
+        ...overrides,
+    }) as unknown as IConfig;
+
+const startClient = (overrides: Partial<IConfig> = {}): EmailClient => {
+    const client = new EmailClient(jsonTransportConfig(overrides));
+    client.onServerStart();
+    return client;
+};
+
+/** The JSON transport reports the serialized message on `.message`. */
+const sentMessage = (info: unknown) =>
+    JSON.parse((info as { message: string }).message) as {
+        from: { address: string; name: string };
+        to: { address: string }[];
+        subject: string;
+        html?: string;
+        headers?: Record<string, string>;
+    };
+
+describe('EmailClient — transport lifecycle', () => {
+    it('stops sending once the transport is shut down', async () => {
+        const client = startClient();
+        expect(
+            await client.sendRaw({ to: '[email protected]', subject: 'up', text: 'x' }),
+        ).not.toBeNull();
+
+        client.onServerShutdown();
+
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        expect(
+            await client.sendRaw({ to: '[email protected]', subject: 'down', text: 'x' }),
+        ).toBeNull();
+        warn.mockRestore();
+    });
+
+    it('warns at boot when no transport is set', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const client = new EmailClient({
+            port: 0,
+            extensions: [],
+        } as unknown as IConfig);
+        client.onServerStart();
+
+        expect(warn).toHaveBeenCalledWith(
+            expect.stringContaining('no email transport configured'),
+        );
+        warn.mockRestore();
+    });
+
+    it('drops the send and returns null when no transport exists', async () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const client = new EmailClient({
+            port: 0,
+            extensions: [],
+        } as unknown as IConfig);
+        client.onServerStart();
+
+        await expect(
+            client.sendRaw({ to: '[email protected]', subject: 'hi', text: 'hi' }),
+        ).resolves.toBeNull();
+        expect(warn).toHaveBeenCalledWith(
+            expect.stringContaining('without transport'),
+            expect.objectContaining({ to: '[email protected]' }),
+        );
+        warn.mockRestore();
+    });
+});
+
+describe('EmailClient — sending', () => {
+    it('sends a rendered template through the transport', async () => {
+        const client = startClient();
+        const info = await client.sendRaw({
+            to: '[email protected]',
+            subject: 'raw subject',
+            html: '<p>hello</p>',
+            headers: { 'List-Unsubscribe': '<https://puter.test/u>' },
+        });
+
+        const message = sentMessage(info);
+        expect(message.subject).toBe('raw subject');
+        expect(message.to[0].address).toBe('[email protected]');
+        expect(message.from.address).toBe('[email protected]');
+        expect(message.headers?.['List-Unsubscribe']).toBe(
+            '<https://puter.test/u>',
+        );
+    });
+
+    it('lets the caller override the from address', async () => {
+        const client = startClient();
+        const info = await client.sendRaw({
+            from: '[email protected]',
+            to: '[email protected]',
+            subject: 's',
+            text: 't',
+        });
+        expect(sentMessage(info).from.address).toBe('[email protected]');
+    });
+
+    it('falls back to the built-in sender when config has none', async () => {
+        const client = startClient({
+            email: { jsonTransport: true },
+        } as unknown as Partial<IConfig>);
+        const info = await client.sendRaw({
+            to: '[email protected]',
+            subject: 's',
+            text: 't',
+        });
+        expect(sentMessage(info).from.address).toBe('[email protected]');
+    });
+
+    it('refuses an unknown template name', async () => {
+        const client = startClient();
+        await expect(
+            client.send('[email protected]', 'not-a-template' as never),
+        ).rejects.toThrow('Unknown email template: not-a-template');
+    });
+
+    it('surfaces transport failures to the caller', async () => {
+        // Port 1 on loopback is never listening, so the send really fails.
+        const client = startClient({
+            email: { host: '127.0.0.1', port: 1, from: FROM },
+        } as unknown as Partial<IConfig>);
+
+        await expect(
+            client.sendRaw({
+                to: '[email protected]',
+                subject: 's',
+                text: 't',
+            }),
+        ).rejects.toThrow();
+    });
+});
+
+describe('EmailClient — template rendering', () => {
+    it('renders the code into both subject and body', async () => {
+        const client = startClient();
+        const captured: { subject?: string; html?: string } = {};
+        const original = client.sendRaw.bind(client);
+        vi.spyOn(client, 'sendRaw').mockImplementation(async (options) => {
+            captured.subject = options.subject;
+            captured.html = options.html;
+            return original(options);
+        });
+
+        await client.send('[email protected]', 'email_verification_code', {
+            code: '424242',
+        });
+
+        expect(captured.subject).toBe('424242 is your confirmation code');
+        expect(captured.html).toContain('<strong>424242</strong>');
+    });
+
+    it('does not HTML-escape values in the plain-text subject header', async () => {
+        const client = startClient();
+        const captured: { subject?: string } = {};
+        vi.spyOn(client, 'sendRaw').mockImplementation(async (options) => {
+            captured.subject = options.subject;
+            return null;
+        });
+
+        await client.send('[email protected]', 'app-user-feedback', {
+            owner_username: 'dev',
+            sender_username: 'user',
+            sender_email: null,
+            app_title: "Bob's App & Games",
+            app_name: 'bobs-app',
+            app_link: 'https://puter.example/app/bobs-app',
+            message: 'hi',
+        });
+
+        // A subject is not HTML — entities would render literally in the
+        // recipient's mail client.
+        expect(captured.subject).toBe("New user feedback for Bob's App & Games");
+    });
+
+    it('escapes html and converts newlines in nl2br values', async () => {
+        const client = startClient();
+        let html = '';
+        vi.spyOn(client, 'sendRaw').mockImplementation(async (options) => {
+            html = options.html ?? '';
+            return null;
+        });
+
+        await client.send('[email protected]', 'listing-rejected', {
+            app_name: 'demo',
+            app_title: 'Demo',
+            reason: 'first & "only"\n<b>line</b>',
+        });
+
+        expect(html).toContain(
+            'first &amp; &quot;only&quot;<br />&lt;b&gt;line&lt;/b&gt;',
+        );
+    });
+
+    it('renders an empty string for a missing nl2br value', async () => {
+        const client = startClient();
+        let html = '';
+        vi.spyOn(client, 'sendRaw').mockImplementation(async (options) => {
+            html = options.html ?? '';
+            return null;
+        });
+
+        await client.send('[email protected]', 'listing-rejected', {
+            app_name: 'demo',
+            app_title: 'Demo',
+        });
+
+        expect(html).toContain('<blockquote></blockquote>');
+    });
+});
+
+describe('EmailClient — share notification templates', () => {
+    /** Captures both parts of a send without touching the transport. */
+    const renderShare = async (
+        template: 'file_shared_with_you' | 'file_shared_invite',
+        values: Record<string, unknown>,
+    ) => {
+        const client = startClient();
+        const captured: { html: string; text: string } = { html: '', text: '' };
+        vi.spyOn(client, 'sendRaw').mockImplementation(async (options) => {
+            captured.html = options.html ?? '';
+            captured.text = options.text ?? '';
+            return null;
+        });
+        await client.send('[email protected]', template, values);
+        return captured;
+    };
+
+    const HOLDER = {
+        recipient: 'alice',
+        subject_line: 'bob shared notes.md with you',
+        shares: [
+            { sender: 'bob', what: 'notes.md' },
+            { sender: 'carol', what: '3 items — a.txt, b.txt, +1 more' },
+        ],
+        link: 'https://puter.test',
+        unsubscribe_uuid: null,
+    };
+
+    it('sends a plain-text alternative beside the html', async () => {
+        const { html, text } = await renderShare(
+            'file_shared_with_you',
+            HOLDER,
+        );
+
+        expect(html).toContain('<!DOCTYPE html>');
+        // Every sender reaches both parts, so a text-only client loses nothing.
+        for (const part of [html, text]) {
+            expect(part).toContain('bob');
+            expect(part).toContain('notes.md');
+            expect(part).toContain('carol');
+            expect(part).toContain('+1 more');
+        }
+        expect(text).not.toContain('<');
+    });
+
+    it('escapes item names in the html and leaves them raw in the text', async () => {
+        const { html, text } = await renderShare('file_shared_with_you', {
+            ...HOLDER,
+            shares: [{ sender: 'bob', what: 'r&d "notes".md' }],
+        });
+
+        expect(html).toContain('r&amp;d &quot;notes&quot;.md');
+        expect(text).toContain('r&d "notes".md');
+    });
+
+    it('renders as a responsive single column with no remote assets', async () => {
+        const { html } = await renderShare('file_shared_with_you', HOLDER);
+
+        expect(html).toContain(
+            '<meta name="viewport" content="width=device-width, initial-scale=1" />',
+        );
+        expect(html).toContain('@media only screen and (max-width: 600px)');
+        expect(html).toContain('@media (prefers-color-scheme: dark)');
+        expect(html).toContain('max-width: 600px');
+        // Images are the one thing a client can refuse to load, so the design
+        // does without them — the layout can't depend on a blocked asset.
+        expect(html).not.toContain('<img');
+        // The colors have to survive a client that drops the stylesheet.
+        expect(html).toContain('style="background-color: #ffffff;');
+    });
+
+    it('opens with a preview line that is hidden in the body', async () => {
+        const { html } = await renderShare('file_shared_with_you', HOLDER);
+
+        const preheader = html.indexOf('Waiting for you under Shared with me.');
+        expect(preheader).toBeGreaterThan(-1);
+        expect(html.slice(0, preheader)).toContain('mso-hide: all');
+        expect(preheader).toBeLessThan(html.indexOf('Hi alice,'));
+    });
+
+    it('points the call to action at the app and nowhere else', async () => {
+        const { html, text } = await renderShare(
+            'file_shared_with_you',
+            HOLDER,
+        );
+
+        expect(html).toContain('href="https://puter.test"');
+        expect(html).toContain('>Open Puter</a>');
+        expect(text).toContain('Open Puter: https://puter.test');
+    });
+
+    it('separates senders without a rule above the first', async () => {
+        const { html } = await renderShare('file_shared_with_you', HOLDER);
+
+        // One rule between two senders, none leading the list.
+        expect(html.split('border-top: 1px solid').length - 1).toBe(1);
+    });
+
+    it('offers the unsubscribe link only to a recipient who has an account', async () => {
+        const withAccount = await renderShare('file_shared_with_you', {
+            ...HOLDER,
+            unsubscribe_uuid: 'a-uuid',
+        });
+        expect(withAccount.html).toContain(
+            'href="https://puter.test/unsubscribe?user_uuid=a-uuid"',
+        );
+        expect(withAccount.text).toContain(
+            'https://puter.test/unsubscribe?user_uuid=a-uuid',
+        );
+
+        const anonymous = await renderShare('file_shared_with_you', HOLDER);
+        expect(anonymous.html).not.toContain('/unsubscribe');
+        expect(anonymous.text).not.toContain('/unsubscribe');
+    });
+
+    it('tells an invited address what to do with it', async () => {
+        const { html, text } = await renderShare('file_shared_invite', {
+            email: '[email protected]',
+            subject_line: 'bob shared notes.md with you on Puter',
+            shares: [{ sender: 'bob', what: 'notes.md' }],
+            link: 'https://puter.test',
+        });
+
+        for (const part of [html, text]) {
+            expect(part).toContain('[email protected]');
+            expect(part).toContain('Create your free account');
+            // An invite has no account to unsubscribe from.
+            expect(part).not.toContain('/unsubscribe');
+        }
+        expect(html).toContain('href="https://puter.test"');
+    });
+});
+
+describe('EmailClient.clean', () => {
+    const clean = (email: string) => startClient().clean(email);
+
+    it('strips subaddressing on ordinary domains', () => {
+        expect(clean('[email protected]')).toBe('[email protected]');
+    });
+
+    it('ignores dots and subaddressing for gmail', () => {
+        expect(clean('[email protected]')).toBe('[email protected]');
+    });
+
+    it('canonicalizes googlemail onto gmail', () => {
+        expect(clean('[email protected]')).toBe('[email protected]');
+    });
+
+    it('keeps yahoo subaddressing, which yahoo treats as distinct', () => {
+        expect(clean('[email protected]')).toBe('[email protected]');
+    });
+
+    it('ignores dots for icloud aliases', () => {
+        expect(clean('[email protected]')).toBe('[email protected]');
+    });
+
+    it('returns anything that is not an address unchanged', () => {
+        expect(clean('not-an-email')).toBe('not-an-email');
+        expect(clean('@nolocal.test')).toBe('@nolocal.test');
+    });
+});
+
+describe('EmailClient.validate', () => {
+    it('waves everything through in a dev environment', async () => {
+        const client = startClient({ env: 'dev' } as Partial<IConfig>);
+        await expect(client.validate('[email protected]')).resolves.toBe(
+            true,
+        );
+    });
+
+    it('rejects a blocked domain suffix', async () => {
+        const client = startClient({
+            blockedEmailDomains: ['blocked.test'],
+        } as unknown as Partial<IConfig>);
+
+        await expect(client.validate('[email protected]')).resolves.toBe(
+            false,
+        );
+        await expect(client.validate('[email protected]')).resolves.toBe(
+            true,
+        );
+    });
+
+    it('matches the blocklist against the cleaned address', async () => {
+        const client = startClient({
+            blockedEmailDomains: ['@gmail.com'],
+        } as unknown as Partial<IConfig>);
+        await expect(
+            client.validate('[email protected]'),
+        ).resolves.toBe(false);
+    });
+
+    it('lets a registered validator veto an address', async () => {
+        const client = startClient();
+        const seen: string[] = [];
+        client.addValidator((email) => {
+            seen.push(email);
+            return !email.startsWith('spam');
+        });
+
+        await expect(client.validate('[email protected]')).resolves.toBe(
+            false,
+        );
+        await expect(client.validate('[email protected]')).resolves.toBe(true);
+        // Validators always see the canonical form.
+        expect(seen).toEqual(['[email protected]', '[email protected]']);
+    });
+
+    it('supports asynchronous validators', async () => {
+        const client = startClient();
+        client.addValidator(async (email) => email !== '[email protected]');
+        await expect(client.validate('[email protected]')).resolves.toBe(false);
+        await expect(client.validate('[email protected]')).resolves.toBe(true);
+    });
+});

src/backend/clients/email/EmailClient.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -22,7 +22,11 @@ import handlebars, { template } from 'handlebars';
 import nodemailer from 'nodemailer';
 import type { IConfig } from '../../types';
 import { PuterClient } from '../types';
-import { EMAIL_TEMPLATES, type EmailTemplateName } from './templates';
+import {
+    EMAIL_TEMPLATES,
+    type EmailTemplate,
+    type EmailTemplateName,
+} from './templates';
 
 /** Attachment shape passed through to the underlying transport. */
 export interface EmailAttachment {
@@ -64,6 +68,7 @@ export type EmailValidator = (email: string) => Promise<boolean> | boolean;
 interface CompiledTemplate {
     subject: ReturnType<typeof template>;
     html: ReturnType<typeof template>;
+    text?: ReturnType<typeof template>;
 }
 
 // -- Clean-email rules ------------------------------------------------
@@ -110,10 +115,11 @@ const DOMAIN_ALIASES: Record<string, string> = {
 
 /**
  * Unified email client. Handles:
- *   - Template-based outbound mail (via `send`)
- *   - Raw nodemailer passthrough (via `sendRaw`)
- *   - Canonical-form normalization for dedup (via `clean`)
- *   - Policy + extensible validation (via `validate`)
+ *
+ * - Template-based outbound mail (via `send`)
+ * - Raw nodemailer passthrough (via `sendRaw`)
+ * - Canonical-form normalization for dedup (via `clean`)
+ * - Policy + extensible validation (via `validate`)
  */
 export class EmailClient extends PuterClient {
     private transport: ReturnType<typeof nodemailer.createTransport> | null =
@@ -152,12 +158,15 @@ export class EmailClient extends PuterClient {
     // -- Public API: sending ------------------------------------------
 
     /**
-     * Render a template and send it to `to`.
+     * Render a template and send it to `to`. `options.replyTo` sets the
+     * Reply-To header (e.g. so a recipient can respond to the originator of the
+     * message rather than the no-reply From address).
      */
     async send<T extends EmailTemplateName>(
         to: string,
         template: T,
         values: Record<string, unknown> = {},
+        options: { replyTo?: string } = {},
     ): Promise<void> {
         const compiled = this.compiledTemplates[template];
         if (!compiled) {
@@ -169,16 +178,19 @@ export class EmailClient extends PuterClient {
             to,
             subject: compiled.subject(values),
             html: compiled.html(values),
+            ...(compiled.text ? { text: compiled.text(values) } : {}),
+            ...(options.replyTo ? { replyTo: options.replyTo } : {}),
         });
     }
 
     /**
-     * Raw send — bypasses the template system. Useful for one-off
-     * admin emails that don't warrant a named template.
+     * Raw send — bypasses the template system. Useful for one-off admin emails
+     * that don't warrant a named template.
      *
-     * Returns the transport's send result, or `null` when no transport
-     * is configured (the send is a no-op in that case — callers that
-     * must not silently drop mail should check `isConfigured` first).
+     * Returns the transport's send result, or `null` when no transport is
+     * configured (the send is a no-op in that case — callers that must not
+     * silently drop mail should check `config.email` before composing, or the
+     * `null` return after).
      */
     async sendRaw(options: SendMailOptions) {
         if (!this.transport) {
@@ -194,17 +206,12 @@ export class EmailClient extends PuterClient {
         });
     }
 
-    /** Whether an SMTP transport is configured (sends are no-ops otherwise). */
-    get isConfigured(): boolean {
-        return this.transport !== null;
-    }
-
     // -- Public API: clean / validate ---------------------------------
 
     /**
-     * Normalize an email to its canonical form for dedup comparisons.
-     * Applies provider-specific rules (e.g. Gmail ignores dots in
-     * the local part) plus generic subaddressing removal.
+     * Normalize an email to its canonical form for dedup comparisons. Applies
+     * provider-specific rules (e.g. Gmail ignores dots in the local part) plus
+     * generic subaddressing removal.
      */
     clean(email: string): string {
         let [local, domain] = email.split('@');
@@ -233,9 +240,9 @@ export class EmailClient extends PuterClient {
     }
 
     /**
-     * Check whether an email is allowed to be used. Checks domain
-     * blocklist plus any registered validators (services can call
-     * `addValidator()` to register custom policy hooks).
+     * Check whether an email is allowed to be used. Checks domain blocklist
+     * plus any registered validators (services can call `addValidator()` to
+     * register custom policy hooks).
      */
     async validate(email: string): Promise<boolean> {
         if (this.config.env === 'dev') return true;
@@ -258,9 +265,8 @@ export class EmailClient extends PuterClient {
     }
 
     /**
-     * Register a custom validation hook. Services can call this
-     * during their startup to veto specific emails (e.g. a
-     * disposable-email service).
+     * Register a custom validation hook. Services can call this during their
+     * startup to veto specific emails (e.g. a disposable-email service).
      */
     addValidator(fn: EmailValidator): void {
         this.validators.push(fn);
@@ -285,10 +291,30 @@ export class EmailClient extends PuterClient {
     }
 
     private compileTemplates(): void {
-        for (const [name, template] of Object.entries(EMAIL_TEMPLATES)) {
+        // Widened to the interface: the literal map keeps a distinct type per
+        // template, and only some of them carry a `text` part.
+        const templates: Record<EmailTemplateName, EmailTemplate> =
+            EMAIL_TEMPLATES;
+        for (const [name, template] of Object.entries(templates)) {
             this.compiledTemplates[name as EmailTemplateName] = {
-                subject: handlebars.compile(template.subject),
+                // Subjects are plain-text headers: HTML-escaping would put
+                // literal entities in front of the recipient (&amp; etc.).
+                // Header safety is handled elsewhere — the transport encodes
+                // newlines, and free-form values (e.g. app_title) collapse
+                // whitespace upstream.
+                subject: handlebars.compile(template.subject, {
+                    noEscape: true,
+                }),
                 html: handlebars.compile(dedent(template.html)),
+                // Same reasoning as the subject: a text part is not HTML, so
+                // escaping would show entities to the reader.
+                ...(template.text
+                    ? {
+                          text: handlebars.compile(dedent(template.text), {
+                              noEscape: true,
+                          }),
+                      }
+                    : {}),
             };
         }
     }

src/backend/clients/email/templates.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -18,19 +18,195 @@
  */
 
 /**
- * Email template definitions. Keys are the template names; values are
- * the Handlebars-compilable `subject` and `html` strings.
+ * Email template definitions. Keys are the template names; values are the
+ * Handlebars-compilable `subject` and `html` strings.
  *
- * Rendered values are supplied by callers of `EmailClient.send()`.
- * Variables use standard Handlebars syntax: `{{var}}`, `{{#if cond}}…{{/if}}`,
- * and the custom helper `{{{nl2br text}}}` for HTML-safe newline conversion.
+ * Rendered values are supplied by callers of `EmailClient.send()`. Variables
+ * use standard Handlebars syntax: `{{var}}`, `{{#if cond}}…{{/if}}`, and the
+ * custom helper `{{{nl2br text}}}` for HTML-safe newline conversion.
  */
 
 export interface EmailTemplate {
     subject: string;
     html: string;
+    /**
+     * Optional plain-text alternative. Where a template has one it goes out
+     * beside the HTML as multipart/alternative, which is what plain-text
+     * clients, screen readers and spam scoring all prefer to a machine
+     * down-conversion of the markup.
+     */
+    text?: string;
 }
 
+// -- Shared layout ----------------------------------------------------
+
+/**
+ * Colors, in one place so the two share templates can't drift apart. Every one
+ * of them is also written inline further down: clients that drop `<style>`
+ * (Gmail reading a non-Gmail account, Outlook.com) would otherwise render an
+ * unstyled page, so the stylesheet only carries what inline CSS can't express —
+ * the small-screen and dark-mode overrides.
+ *
+ * `ACCENT` is the GUI's primary blue darkened until white text on it clears
+ * 4.5:1, since a button label is small text however bold it is.
+ */
+const INK = '#101828';
+const INK_SOFT = '#5b6472';
+const INK_FAINT = '#667085';
+const PAGE_BG = '#f2f4f7';
+const CARD_BG = '#ffffff';
+const CARD_BORDER = '#e4e7ec';
+const RULE = '#e6e9ee';
+const PANEL_BG = '#f8f9fb';
+const PANEL_BORDER = '#eceff3';
+const ACCENT = '#0a76cc';
+
+const FONT =
+    "-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif";
+
+/** Pads the preview line so body text can't leak into it. */
+const PREHEADER_FILL = '&#847;&zwnj;&nbsp;'.repeat(60);
+
+/**
+ * The document both share notifications render into: one 600px column that goes
+ * full width on a phone, laid out with tables and `bgcolor` because Outlook
+ * renders through Word and ignores anything more modern.
+ *
+ * `preheader` is the line the inbox shows beside the subject — it should add to
+ * the subject, not repeat it. `content` is the card's rows; `footer` sits below
+ * the card, where the reason-for-receiving and unsubscribe belong.
+ */
+const shareEmailLayout = (parts: {
+    preheader: string;
+    content: string;
+    footer: string;
+}): string => `
+<!DOCTYPE html>
+<html lang="en" dir="ltr" xmlns:o="urn:schemas-microsoft-com:office:office">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="x-apple-disable-message-reformatting" />
+<meta name="color-scheme" content="light dark" />
+<meta name="supported-color-schemes" content="light dark" />
+<title>{{subject_line}}</title>
+<!--[if mso]>
+<noscript><xml><o:OfficeDocumentSettings><o:PixelsPerInch>96</o:PixelsPerInch></o:OfficeDocumentSettings></xml></noscript>
+<![endif]-->
+<style>
+    body { margin: 0; padding: 0; width: 100% !important; -webkit-text-size-adjust: 100%; -ms-text-size-adjust: 100%; }
+    table { border-spacing: 0; mso-table-lspace: 0pt; mso-table-rspace: 0pt; }
+    td { mso-line-height-rule: exactly; }
+    a[x-apple-data-detectors] { color: inherit !important; text-decoration: none !important; font-size: inherit !important; font-family: inherit !important; font-weight: inherit !important; line-height: inherit !important; }
+    @media only screen and (max-width: 600px) {
+        .col { width: 100% !important; }
+        .pad { padding-left: 24px !important; padding-right: 24px !important; }
+        .pad-y { padding-top: 28px !important; padding-bottom: 28px !important; }
+        .h1 { font-size: 22px !important; line-height: 30px !important; }
+        .btn { width: 100% !important; }
+    }
+    @media (prefers-color-scheme: dark) {
+        .page { background-color: #0e1116 !important; }
+        .card { background-color: #171b22 !important; border-color: #272d38 !important; }
+        .ink { color: #e9ebef !important; }
+        .ink-soft { color: #9aa3b2 !important; }
+        .ink-soft a { color: #9aa3b2 !important; }
+        .rule { border-color: #272d38 !important; }
+        .panel { background-color: #1d222a !important; border-color: #2b323d !important; }
+        .mark { color: #4da3f2 !important; }
+    }
+</style>
+</head>
+<body class="page" style="margin: 0; padding: 0; width: 100%; background-color: ${PAGE_BG};">
+<div style="display: none; font-size: 1px; line-height: 1px; max-height: 0; max-width: 0; opacity: 0; overflow: hidden; mso-hide: all;">${parts.preheader}${PREHEADER_FILL}</div>
+<div role="article" aria-roledescription="email" lang="en">
+<table role="presentation" class="page" width="100%" cellpadding="0" cellspacing="0" border="0" style="width: 100%; background-color: ${PAGE_BG};">
+<tr>
+<td align="center" style="padding: 32px 12px;">
+<!--[if mso]><table role="presentation" width="600" cellpadding="0" cellspacing="0" border="0"><tr><td><![endif]-->
+<table role="presentation" class="col" width="600" cellpadding="0" cellspacing="0" border="0" style="width: 100%; max-width: 600px; text-align: left;">
+    <tr>
+        <td class="pad mark" style="padding: 0 4px 14px; font-family: ${FONT}; font-size: 15px; line-height: 20px; font-weight: 700; letter-spacing: 0.01em; color: ${ACCENT};">Puter</td>
+    </tr>
+    <tr>
+        <td class="card" style="background-color: ${CARD_BG}; border: 1px solid ${CARD_BORDER}; border-radius: 14px;">
+            <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="width: 100%;">
+                <tr>
+                    <td class="pad pad-y" style="padding: 36px 36px 34px;">
+                        <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="width: 100%;">${parts.content}
+                        </table>
+                    </td>
+                </tr>
+            </table>
+        </td>
+    </tr>
+    <tr>
+        <td class="pad ink-soft" style="padding: 20px 4px 0; font-family: ${FONT}; font-size: 13px; line-height: 20px; color: ${INK_FAINT};">${parts.footer}
+        </td>
+    </tr>
+</table>
+<!--[if mso]></td></tr></table><![endif]-->
+</td>
+</tr>
+</table>
+</div>
+</body>
+</html>
+`;
+
+/** The greeting line above the heading. */
+const greetingRow = (text: string): string => `
+                            <tr>
+                                <td class="ink-soft" style="padding: 0 0 6px; font-family: ${FONT}; font-size: 15px; line-height: 22px; color: ${INK_SOFT};">${text}</td>
+                            </tr>`;
+
+const headingRow = (text: string): string => `
+                            <tr>
+                                <td class="ink h1" style="padding: 0 0 18px; font-family: ${FONT}; font-size: 24px; line-height: 32px; font-weight: 700; letter-spacing: -0.01em; color: ${INK};">${text}</td>
+                            </tr>`;
+
+/**
+ * One row per sender, hairline-separated. The wording comes pre-composed from
+ * the digest (`digestLines`), so the list stays a list however many senders and
+ * items fold into it.
+ */
+const SHARE_LIST_ROW = `
+                            <tr>
+                                <td class="panel" style="padding: 6px 18px; background-color: ${PANEL_BG}; border: 1px solid ${PANEL_BORDER}; border-radius: 10px;">
+                                    <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="width: 100%;">
+                                        {{#each shares}}
+                                        <tr>
+                                            <td class="ink rule" style="padding: 12px 0;{{#unless @first}} border-top: 1px solid ${RULE};{{/unless}} font-family: ${FONT}; font-size: 16px; line-height: 24px; color: ${INK};"><strong style="font-weight: 600;">{{this.sender}}</strong> shared {{this.what}}</td>
+                                        </tr>
+                                        {{/each}}
+                                    </table>
+                                </td>
+                            </tr>`;
+
+/** A body paragraph. `padding` lets a caller tune the rhythm around it. */
+const textRow = (text: string, padding = '18px 0 0'): string => `
+                            <tr>
+                                <td class="ink-soft" style="padding: ${padding}; font-family: ${FONT}; font-size: 15px; line-height: 23px; color: ${INK_SOFT};">${text}</td>
+                            </tr>`;
+
+/**
+ * The call to action. Padding sits on the cell and the color on `bgcolor` so
+ * Outlook still draws a real button (square-cornered, which is fine); the table
+ * goes full width under 600px so the tap target spans the card.
+ */
+const buttonRow = (label: string): string => `
+                            <tr>
+                                <td style="padding: 26px 0 0;">
+                                    <table role="presentation" class="btn" cellpadding="0" cellspacing="0" border="0" style="border-collapse: separate;">
+                                        <tr>
+                                            <td align="center" bgcolor="${ACCENT}" style="background-color: ${ACCENT}; border-radius: 10px; padding: 14px 26px;">
+                                                <a href="{{link}}" style="display: inline-block; font-family: ${FONT}; font-size: 16px; line-height: 20px; font-weight: 600; color: #ffffff; text-decoration: none;">${label}</a>
+                                            </td>
+                                        </tr>
+                                    </table>
+                                </td>
+                            </tr>`;
+
 export const EMAIL_TEMPLATES = {
     'approved-for-listing': {
         subject: '🎉 Your app has been approved for listing!',
@@ -75,6 +251,25 @@ Please update <a href="https://puter.com/app/{{app_name}}">{{app_title}}</a>.
 <blockquote>{{nl2br message}}</blockquote>
 <p>Best,<br />
 The Puter Team
+</p>
+        `,
+    },
+    'app-user-feedback': {
+        subject: 'New user feedback for {{app_title}}',
+        html: `
+<p>Hi{{#if owner_username}} {{owner_username}}{{/if}},</p>
+<p>
+<strong>{{sender_username}}</strong>{{#if sender_email}} (<a href="mailto:{{sender_email}}">{{sender_email}}</a>){{/if}} sent feedback about <a href="{{app_link}}">{{app_title}}</a>:
+</p>
+<blockquote>{{{nl2br message}}}</blockquote>
+{{#if sender_email}}<p>Just reply to this email to respond to them directly.</p>{{/if}}
+<p>
+You're receiving this because feedback is enabled for
+<a href="{{app_link}}">{{app_title}}</a> — manage it in the
+<a href="{{dev_center_link}}">Dev Center</a> under your app's settings.
+</p>
+<p>Best,<br />
+The Puter Team
 </p>
         `,
     },
@@ -164,32 +359,85 @@ immediately</p>
 <p>Puter</p>
         `,
     },
-    share_by_username: {
-        subject: 'Puter share from {{susername}}',
-        html: `
-<p>Hi there {{rusername}},</p>
-<p>You've received a share from {{susername}} on Puter.</p>
-<p>Go to puter.com to check it out.</p>
-{{#if message}}
-    <p>The following message was included:</p>
-    <blockquote>{{message}}</blockquote>
-{{/if}}
-<p>Sincerely,</p>
-<p>Puter</p>
+    /**
+     * A digest: shares to one recipient are held briefly and merged, so
+     * `shares` may carry several senders. The subject is composed by the
+     * service (see `digestSubject`), which owns the grouped wording.
+     */
+    file_shared_with_you: {
+        subject: '{{subject_line}}',
+        html: shareEmailLayout({
+            preheader: 'Waiting for you under Shared with me.',
+            content:
+                greetingRow('Hi{{#if recipient}} {{recipient}}{{/if}},') +
+                headingRow('Shared with you') +
+                SHARE_LIST_ROW +
+                buttonRow('Open Puter') +
+                textRow(
+                    'Shared items live under <span style="font-weight: 600;">Shared</span> in your files.',
+                    '24px 0 0',
+                ),
+            footer: `You're receiving this because someone shared with your Puter account.{{#if unsubscribe_uuid}}
+            <br /><a href="{{link}}/unsubscribe?user_uuid={{unsubscribe_uuid}}" style="color: inherit; text-decoration: underline;">Unsubscribe from notification emails</a>{{/if}}`,
+        }),
+        text: `
+            Hi{{#if recipient}} {{recipient}}{{/if}},
+
+            Shared with you on Puter:
+            {{#each shares}}
+            - {{this.sender}} shared {{this.what}}
+            {{/each}}
+
+            Open Puter: {{link}}
+
+            Shared items live under "Shared" in your files.
+
+            --
+            You're receiving this because someone shared with your Puter account.
+            {{#if unsubscribe_uuid}}Unsubscribe from notification emails:
+            {{link}}/unsubscribe?user_uuid={{unsubscribe_uuid}}{{/if}}
         `,
     },
-    share_by_email: {
-        subject: 'share by email',
-        html: `
-<p>Hi there,</p>
-<p>You've received a share from {{sender_name}} on Puter:</p>
-<p><a href="{{link}}">{{link}}</a></p>
-{{#if message}}
-    <p>The following message was included:</p>
-    <blockquote>{{message}}</blockquote>
-{{/if}}
-<p>Sincerely,</p>
-<p>Puter</p>
+    // The only way to reach someone with no account. Same digest shape.
+    file_shared_invite: {
+        subject: '{{subject_line}}',
+        html: shareEmailLayout({
+            preheader: 'Claim it with a free Puter account.',
+            content:
+                greetingRow('Hi there,') +
+                headingRow('Shared with you on Puter') +
+                SHARE_LIST_ROW +
+                textRow(
+                    'There\'s no Puter account for <span style="font-weight: 600;">{{email}}</span> yet. Create one with this address, confirm it, and everything above will be waiting for you. It\'s free and takes about a minute.',
+                ) +
+                buttonRow('Create your free account') +
+                textRow(
+                    'Already on Puter? Add {{email}} to your account and confirm it to get the same access.',
+                    '24px 0 0',
+                ),
+            footer: `You're receiving this because someone shared with {{email}}. Nothing is shared until the address is confirmed, so you can ignore this email and nothing happens.`,
+        }),
+        text: `
+            Hi there,
+
+            Shared with you on Puter:
+            {{#each shares}}
+            - {{this.sender}} shared {{this.what}}
+            {{/each}}
+
+            There's no Puter account for {{email}} yet. Create one with this
+            address, confirm it, and everything above will be waiting for you.
+            It's free and takes about a minute.
+
+            Create your free account: {{link}}
+
+            Already on Puter? Add {{email}} to your account and confirm it to get
+            the same access.
+
+            --
+            You're receiving this because someone shared with {{email}}. Nothing is
+            shared until the address is confirmed, so you can ignore this email
+            and nothing happens.
         `,
     },
 } satisfies Record<string, EmailTemplate>;

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

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

src/backend/clients/event/EventClient.ts

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

src/backend/clients/event/types.ts

@@ -20,6 +20,7 @@ import type {
     Response as ExpressResponse,
 } from 'express';
 import { Actor } from '../../core';
+import type { UsageInput } from '../../services/metering/types';
 import { FSEntry } from '../../stores/fs/FSEntry';
 
 // GUI write events spread an entry plus per-event metadata into `response`.
@@ -31,6 +32,24 @@ type GuiEvent<R = Record<string, unknown>> = {
     response: R;
 };
 
+/**
+ * Extension-augmentable half of {@link EventMap}. Extensions that emit their own
+ * events declare the payload here by declaration merging, so both the emitter
+ * and every listener are typed against the same shape:
+ *
+ *     declare module '@heyputer/backend/clients/event/types' {
+ *         interface IExtensionEventMap {
+ *             'my.thing.happened': { thingId: string };
+ *         }
+ *     }
+ *
+ * Deliberately member-less and index-signature-free: an index signature here
+ * would widen `keyof EventMap` to `string` and silently disable key checking on
+ * every `emit` in the tree.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface IExtensionEventMap {}
+
 export type EventMap = {
     // ---- Server lifecycle ----
     serverStart: Record<string, never>;
@@ -141,6 +160,19 @@ export type EventMap = {
     'puter.signup.validate': {
         allow: boolean;
         email?: string;
+        /**
+         * The address in the same canonical form the `email.validate` hook was
+         * given (`cleanEmail`), so a handler can correlate the two hooks on one
+         * key. Aliases (`[email protected]`, `[email protected]`) differ from
+         * `email` here.
+         */
+        clean_email?: string;
+        /**
+         * True for a temp (frictionless, no-password) signup. Those carry a
+         * synthetic `<username>@gmail.com` and never reach email validation, so
+         * a handler must not draw conclusions from `email`.
+         */
+        is_temp?: boolean;
         ip?: string | null;
         source?: 'oidc';
         req?: unknown;
@@ -289,7 +321,17 @@ export type EventMap = {
         sourceObjectKey: string;
         copyObjectKey: string;
     };
-    'fs.move.node': { node: FSEntry; fromPath: string; toPath: string };
+    /**
+     * `fromUserId` is the owner the node had before the move. A move into
+     * someone else's tree re-owns the row, and `node` already carries the new
+     * owner — listeners that care about the hand-over need the old one.
+     */
+    'fs.move.node': {
+        node: FSEntry;
+        fromPath: string;
+        toPath: string;
+        fromUserId?: number;
+    };
     'fs.remove.node': { node: FSEntry; entry: FSEntry; target: FSEntry };
     'fs.write.file': { node: FSEntry; entry: FSEntry; target: FSEntry };
     'fs.storage.upload-progress': {
@@ -305,13 +347,81 @@ export type EventMap = {
     };
     'storage.quota.bonus': { userId: number; extra: number };
 
+    // ---- Metering ----
+    // Recurring charges are pure mechanism here: the metering service knows
+    // when to ask (once per user per month, the first time that month's usage
+    // record is touched) and how to record the answer, and an extension
+    // decides what the account owes. Listeners push onto `charges`; the
+    // service applies them as ordinary usage once every listener has run.
+    // Nothing listening → no charges and no claim is ever taken.
+    //
+    // Emitted after the claim is settled, so a listener that calls back into
+    // metering can't re-trigger it.
+    'metering.monthly.charges': {
+        /**
+         * User-scoped, with no app on it: the account is what recurs, and the
+         * app that happened to trigger the month's first call has nothing to do
+         * with what is owed. Price against what the user owns.
+         */
+        actor: Actor;
+        /** The month being charged for, `YYYY-MM` in UTC. */
+        month: string;
+        /**
+         * Push what the user owes here. Every listener's charges are merged
+         * into one amount map and recorded as a single increment.
+         */
+        charges: UsageInput[];
+    };
+
+    // ---- Workers ----
+    // Only a genuinely new worker. Redeploying an existing name updates its
+    // row instead, and never reaches here — so a listener that prices this
+    // is pricing workers that came into existence, not deploys.
+    'worker.create': { actor: Actor; workerName: string };
+
+    // The same announcement for worker code that lives inside a hosted site
+    // and is deployed on demand rather than by an explicit call. Such a worker
+    // has no row of ours to key on, so what stands in for "genuinely new" is
+    // the absence of any prior record that it ran — which is why it is
+    // announced separately, and identified by where its source lives rather
+    // than by a worker name.
+    'worker.dynamic.create': {
+        actor: Actor;
+        subdomain: string;
+        worker: string;
+    };
+
     // ---- Outer / GUI broadcast ----
     'outer.cacheUpdate': {
         cacheKey: string[];
         data?: unknown;
         ttlSeconds?: number;
     };
+    /**
+     * Permission cache generations were bumped, so peer regions must bump their
+     * own — the counter is per-cluster, so a local bump says nothing to them.
+     * Carries the actors, not the values: the numbers only have to change.
+     */
+    'outer.permission.generationBumped': { actorUids: string[] };
+    /**
+     * Flat permission entries were deleted. Grant-path flat entries carry no
+     * expiry, so without this a revoke never lands in a peer region whose KV
+     * table isn't replicated. Revoke-only: a grant that fails to replicate just
+     * denies there, which is the safe direction.
+     */
+    'outer.permission.flatInvalidated': {
+        entries: Array<{ holderUserId: number; permission: string }>;
+    };
     'outer.fs.write-hash': { hash: string; uuid: string };
+    /**
+     * Cache keys the KV read cache must stop serving, because the entries
+     * behind them were just written somewhere else.
+     *
+     * `outer.*` rather than `outer.pubsub.*` on purpose: the cache lives in the
+     * Redis a cluster shares, so one node applying the invalidation covers the
+     * whole cluster — fanning it out to siblings would just repeat the write.
+     */
+    'outer.kv.cacheInvalidated': { cacheKeys: string[] };
     'outer.gui.item.added': GuiEvent;
     'outer.gui.item.updated': GuiEvent;
     'outer.gui.item.moved': GuiEvent;
@@ -325,8 +435,10 @@ export type EventMap = {
     }>;
 
     // ---- Subdomains ----
-    'subdomain.delete': { subdomain: string };
-    'subdomain.update': { subdomain: string };
+    // `uid` is the row uuid — for `delete` it is the only surviving handle a
+    // listener can use to find state keyed to the row after it is gone.
+    'subdomain.delete': { subdomain: string; uid?: string };
+    'subdomain.update': { subdomain: string; uid?: string };
     'site.htmlServed': {
         subdomain: string;
         entry: unknown;
@@ -402,7 +514,23 @@ export type EventMap = {
     [K in `route.${string}`]: RouteLifecycleEvent;
 } & {
     [K in `pubsub.login.${string}`]: { authtoken: string };
-};
+} & {
+    /**
+     * A user's subscription now resolves to a different policy. Carried on the
+     * `outer.pubsub.*` channel so it reaches sibling nodes and peer clusters,
+     * not just the one that handled the change — every node caches the resolved
+     * policy, so a purchase is only live once they have all dropped theirs.
+     */
+    'outer.pubsub.metering.subscription-changed': { userUuid: string };
+    /**
+     * A user's purchased credit balance changed. Separate from a policy change
+     * because it moves the other half of the same budget, and carried on the
+     * `outer.pubsub.*` channel for the same reason: every node caches whether
+     * an account has budget left, so a top-up only lifts enforcement once they
+     * have all dropped that answer.
+     */
+    'outer.pubsub.metering.credits-changed': { userUuid: string };
+} & IExtensionEventMap;
 
 /**
  * Phase of a request/method lifecycle. `reject` is emitted when a `before`
@@ -482,10 +610,11 @@ export type EventKey = keyof EventMap & string;
 // Generates a wildcard for every non-final dot-separated prefix of K.
 export type WildcardPrefixes<K extends string> =
     K extends `${infer Head}.${infer Tail}`
-        ? | `${Head}.*`
-          | (Tail extends `${string}.${string}`
-                ? `${Head}.${WildcardPrefixes<Tail>}`
-                : never)
+        ?
+              | `${Head}.*`
+              | (Tail extends `${string}.${string}`
+                    ? `${Head}.${WildcardPrefixes<Tail>}`
+                    : never)
         : never;
 
 export type ListenKey = EventKey | WildcardPrefixes<EventKey>;

src/backend/clients/index.ts

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

src/backend/clients/prelude/PreludeClient.test.ts

@@ -30,7 +30,7 @@ describe('PreludeClient', () => {
         expect(makeClient().isConfigured()).toBe(false);
     });
 
-    describe('isCountrySupported (€0.07 cap)', () => {
+    describe('isCountrySupported (€0.20 cap)', () => {
         const client = makeClient('sk_test');
 
         it('allows revenue markets up to the cap (incl. the priciest)', () => {
@@ -40,6 +40,17 @@ describe('PreludeClient', () => {
             expect(client.isCountrySupported('us')).toBe(true); // case-insensitive
         });
 
+        it('allows the markets the old €0.07 cap excluded', () => {
+            // Raising the cap to €0.20 brought ~89 countries into the phone
+            // gate. These pin the new range so a future change to the default
+            // has to say so out loud.
+            expect(client.isCountrySupported('UA')).toBe(true); // €0.0940
+            expect(client.isCountrySupported('PH')).toBe(true); // €0.1237
+            expect(client.isCountrySupported('EG')).toBe(true); // €0.1561
+            expect(client.isCountrySupported('NG')).toBe(true); // €0.1980
+            expect(client.isCountrySupported('WS')).toBe(true); // €0.2000, at the cap
+        });
+
         it('rejects countries above the cap, with no SMS, or unknown', () => {
             expect(client.isCountrySupported('PK')).toBe(false); // €0.3548
             expect(client.isCountrySupported('ID')).toBe(false); // €0.2430
@@ -63,9 +74,7 @@ describe('PreludeClient', () => {
     });
 
     it('createVerification POSTs the phone target + ip signal with bearer auth', async () => {
-        fetchMock.mockResolvedValue(
-            okJson({ id: 'vrf_1', status: 'success' }),
-        );
+        fetchMock.mockResolvedValue(okJson({ id: 'vrf_1', status: 'success' }));
         const client = makeClient('sk_test');
 
         const res = await client.createVerification('+14155550123', {
@@ -81,7 +90,11 @@ describe('PreludeClient', () => {
             target: { type: 'phone_number', value: '+14155550123' },
             // 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' },
+            options: {
+                code_size: 6,
+                preferred_channel: 'rcs',
+                locale: 'en-US',
+            },
             signals: { ip: '203.0.113.7' },
         });
     });
@@ -196,9 +209,9 @@ describe('PreludeClient', () => {
 
     it('throws (does not call fetch) when not configured', async () => {
         const client = makeClient();
-        await expect(
-            client.createVerification('+14155550123'),
-        ).rejects.toThrow(/not configured/i);
+        await expect(client.createVerification('+14155550123')).rejects.toThrow(
+            /not configured/i,
+        );
         expect(fetchMock).not.toHaveBeenCalled();
     });
 

src/backend/clients/prelude/PreludeClient.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (C) 2024-present Puter Technologies Inc.
  *
  * This file is part of Puter.
@@ -50,12 +50,15 @@ export type PreludeChannel =
 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
- * cap covers every realistic revenue market (priciest are Germany €0.0598 and
- * Saudi Arabia €0.0638) while excluding the expensive, high-fraud long tail.
- * Override per-deployment with `config.prelude.maxSmsCostEur`.
+ * this — or that have no SMS channel — are not offered phone verification.
+ * Raised from €0.07 to €0.20: the old cap sat only marginally above the
+ * priciest revenue markets (Germany €0.0598, Saudi Arabia €0.0638), so any rate
+ * drift silently withdrew the phone gate from a real market — and the abuse
+ * harness now routes far more legitimate signups into the SMS band, where an
+ * unavailable gate is a dead end rather than a mild inconvenience. Override
+ * per-deployment with `config.prelude.maxSmsCostEur`.
  */
-const DEFAULT_MAX_SMS_COST_EUR = 0.07;
+const DEFAULT_MAX_SMS_COST_EUR = 0.2;
 
 /** Status returned by Prelude when creating/retrying a verification. */
 export type PreludeCreateStatus =
@@ -74,11 +77,11 @@ export type PreludeCheckStatus =
     | 'transaction_mismatch';
 
 /**
- * Prelude Verify v2 client (https://docs.prelude.so/verify/v2). Sends and checks
- * SMS one-time codes — Prelude generates, delivers, and validates the code, so
- * we never store one ourselves. No-ops with a warning when no API key is
- * configured (so dev environments don't crash); `isConfigured()` lets callers
- * surface a clean "phone verification unavailable" error instead.
+ * Prelude Verify v2 client (https://docs.prelude.so/verify/v2). Sends and
+ * checks SMS one-time codes — Prelude generates, delivers, and validates the
+ * code, so we never store one ourselves. No-ops with a warning when no API key
+ * is configured (so dev environments don't crash); `isConfigured()` lets
+ * callers surface a clean "phone verification unavailable" error instead.
  */
 export class PreludeClient extends PuterClient {
     private apiKey: string | null = null;
@@ -113,7 +116,9 @@ export class PreludeClient extends PuterClient {
 
     /**
      * Whether SMS verification should be offered for a country. False when the
-     * country is unknown, has no SMS channel, or its rate exceeds the cost cap.
+     * country is unknown, has no SMS channel, or its rate exceeds the cost
+     * cap.
+     *
      * @param iso ISO-3166 alpha-2 (e.g. 'US') — from the parsed phone number.
      */
     isCountrySupported(iso: string | undefined): boolean {
@@ -174,7 +179,9 @@ export class PreludeClient extends PuterClient {
     }
 
     /**
-     * Check a code the user entered against the active verification for `target`.
+     * Check a code the user entered against the active verification for
+     * `target`.
+     *
      * @returns `{ status }` — `'success'` means verified.
      */
     async checkVerification(

src/backend/clients/prelude/countries.ts

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

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

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

src/backend/clients/redis/RedisClient.ts

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

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

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

src/backend/clients/s3/S3Client.ts

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

src/backend/clients/types.ts

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

src/backend/controllers/apps/AppController.js

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

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

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

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

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

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

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

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

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