@sproutboat/runtime 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # @sproutboat/runtime
 
+## 0.4.0
+
+### Minor Changes
+
+- `crypto.subtle` subset (baronunread/sproutboat#133): `digest` (SHA-256 / SHA-384
+  / SHA-512) and HMAC `importKey` / `sign` / `verify` over a raw key. Enough for
+  JWTs and hand-rolled sessions; no ECDSA, AES or key wrapping.
+  
+  Backed by ~300 lines of reference SHA-2 as inline C rather than BearSSL —
+  BearSSL links only in `--standalone` builds and the prelude C is shared with the
+  broker transport, so a link dependency would break non-standalone builds. Pure C
+  is transport-independent and lets a handler drop a vendored pure-JS SHA-256.
+  Verified against NIST vectors on both transports; surface is exactly standard so
+  it deletes cleanly when Porffor ships Web Crypto (CanadaHonk/porffor#347).
+- Rate Limiting binding (baronunread/sproutboat#69): `env.<NAME>.limit({ key }) ->
+  { success }`.
+  
+  - Config: `ratelimiters: [{ binding, limit, period }]` in `sproutboat.jsonc` —
+    at most `limit` calls per `period` seconds, per key.
+  - A fixed-window counter (`ratelimit` table) on **both** transports: the
+    embedded one for standalone binaries, and the broker (`ratelimit.check` op,
+    in the replay-dedup set) for deployed sprouts. `limit` / `period` travel in
+    the message so the op stays stateless.
+  - `ponytail`: fixed window, so a burst across the boundary can briefly reach
+    ~2x; swap for a two-window weighted count if that matters.
+- `crypto.scryptVerify(password, salt, expected, { N, r, p })` (baronunread/sproutboat#153):
+  a scrypt (RFC 7914) implementation as inline C — PBKDF2-HMAC-SHA256 (reusing
+  #133's HMAC) + Salsa20/8 + BlockMix + ROMix.
+  
+  Deliberately verify-only (re-derive and constant-time compare, no exposed raw
+  `scrypt()`): a migration path for password hashes made by Node/Bun `scrypt`
+  (e.g. `N=32768 r=8 p=3`), not a KDF blessed for new credentials — those should
+  use HMAC/PBKDF2 via `crypto.subtle`. Verified against the RFC 7914 §12 vector.
+  `N*r` is capped so a bad config cannot ask for gigabytes of scratch.
+
+### Patch Changes
+
+- Embedded transport: set `PRAGMA busy_timeout=5000` on every connection. Within
+  one binary all binding ops are serial so there is no self-contention, but when
+  several copies of a standalone binary share a data dir behind `SO_REUSEPORT`
+  (the #154 scaling recipe) a writer now waits for the WAL lock instead of
+  failing `SQLITE_BUSY`.
+
+## 0.3.0
+
+### Minor Changes
+
+- Standalone runtime: client IP, D1 online backup, and a prepared-statement cache.
+  
+  - `request.cf.clientIp` is populated from the connection's remote address
+    (`x-sb-remote-addr`, appended by the server and stripped from client input),
+    with `SB_TRUSTED_PROXIES` resolving `X-Forwarded-For` behind a reverse proxy.
+    IPv4-mapped IPv6 peers are folded to dotted form. (baronunread/sproutboat#163)
+  - `env.<D1>.backup(name?)` — a Sproutboat extension: an online, integrity-checked
+    single-file snapshot via `VACUUM INTO`, on both the embedded and broker
+    transports. New `d1.backup` op. (baronunread/sproutboat#164)
+  - The embedded transport caches prepared statements per database (FIFO, 32/db)
+    instead of recompiling the SQL on every binding op. (baronunread/sproutboat#155)
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,33 @@
 # `@sproutboat/runtime`
 
-Single source of truth for the sprout runtime: the binding/trigger wrapper,
-handler source validation, both transports (broker and embedded), and the
+The sprout runtime as a unit: the binding and trigger wrapper, handler
+source validation, both transports (broker and embedded), and the
 native-fetch prelude. These move as one because `wrap.ts` locates the
 prelude and transports by file URL beside itself.
+
+```sh
+bun add @sproutboat/runtime
+```
+
+```ts
+import { preludePath, transportPath, wrapNativeFetchHandler } from "@sproutboat/runtime";
+import { validateHttpSyncSource } from "@sproutboat/runtime";
+```
+
+## API
+
+- `wrapNativeFetchHandler(...)` turns a user's `export default { fetch }`
+  into a native-fetch module with bindings, triggers, and env installed.
+  `Bindings`, `EMPTY_BINDINGS`, `readVarsFromEnv`, `readBindingsFromEnv`,
+  and `neutraliseExports` travel with it.
+- `preludePath` / `transportPath(transport)` locate the prelude and the
+  `broker` / `embedded` transports on disk. The prelude is read as text
+  and prepended before compilation, never imported.
+- `TRANSPORT_MARKER`, `BASELINE_COMPATIBILITY_DATE`, `Transport` type.
+- `validateHttpSyncSource(source)` checks a bundled handler module
+  (`SourceValidation`), used by project checks on both sides.
+
+The prelude shims the Web API surface handlers expect (URL, Response,
+crypto random values, binding shims, trigger dispatch) and is identical
+for both transports, which is what lets one conformance suite hold them
+honest.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutboat/runtime",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "license": "MIT",
   "type": "module",
   "main": "./src/index.ts",

package/src/client-ip.test.js

@@ -0,0 +1,66 @@
+// #163 — the client-IP resolution helpers live inline in native-fetch-prelude.js
+// (the prelude is prepended as text and cannot import), so this test lifts that
+// one pure-JS block out and exercises it directly. If the block moves or its
+// boundary markers change, this fails loudly rather than silently testing nothing.
+import { expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const src = readFileSync(fileURLToPath(new URL("./native-fetch-prelude.js", import.meta.url)), "utf8");
+const start = src.indexOf("function __sbParseHex(");
+const end = src.indexOf("globalThis.__sbEntry");
+if (start === -1 || end === -1 || end < start) throw new Error("client-ip helper block not found in prelude");
+
+let env = {};
+// oxlint-disable-next-line no-function-constructor -- lifting a pure block out of the text-only prelude for test
+const load = new Function(
+  "__envMap",
+  `${src.slice(start, end)}
+   const __sbEnv = (k) => __envMap[k];
+   return { __sbNormalizeIp, __sbIpInCidr, __sbIpTrusted, __sbClientIp, __sbSplitList };`,
+);
+const H = load(new Proxy({}, { get: (_, k) => env[k] }));
+
+const req = (headers) => ({ headers: { get: (k) => headers[k.toLowerCase()] ?? null } });
+
+test("__sbNormalizeIp folds IPv4-mapped IPv6 to dotted quad", () => {
+  expect(H.__sbNormalizeIp("0000:0000:0000:0000:0000:ffff:7f00:0001")).toBe("127.0.0.1");
+  expect(H.__sbNormalizeIp("::ffff:198.51.100.9")).toBe("198.51.100.9");
+  expect(H.__sbNormalizeIp("203.0.113.7")).toBe("203.0.113.7");
+  expect(H.__sbNormalizeIp("2001:db8::1")).toBe("2001:db8::1"); // real IPv6 untouched
+  expect(H.__sbNormalizeIp("")).toBe("");
+});
+
+test("__sbIpInCidr does IPv4 range math without sign errors above 2^31", () => {
+  expect(H.__sbIpInCidr("10.1.2.3", "10.0.0.0/8")).toBe(true);
+  expect(H.__sbIpInCidr("11.0.0.1", "10.0.0.0/8")).toBe(false);
+  expect(H.__sbIpInCidr("203.0.113.7", "203.0.113.7")).toBe(true); // bare IP
+  expect(H.__sbIpInCidr("192.168.1.1", "0.0.0.0/0")).toBe(true);
+  // 224.x is > 2^31 as a uint32 — the divide-not-mask path.
+  expect(H.__sbIpInCidr("224.0.0.5", "224.0.0.0/24")).toBe(true);
+  expect(H.__sbIpInCidr("224.0.1.5", "224.0.0.0/24")).toBe(false);
+});
+
+test("__sbClientIp: no trusted proxies means the peer wins, XFF ignored", () => {
+  env = {};
+  const r = req({ "x-sb-remote-addr": "::ffff:203.0.113.7", "x-forwarded-for": "1.2.3.4" });
+  expect(H.__sbClientIp(r)).toBe("203.0.113.7");
+});
+
+test("__sbClientIp: a trusted peer resolves the rightmost untrusted XFF hop", () => {
+  env = { SB_TRUSTED_PROXIES: "127.0.0.0/8, 10.0.0.0/8" };
+  expect(H.__sbClientIp(req({ "x-sb-remote-addr": "127.0.0.1", "x-forwarded-for": "203.0.113.7, 10.1.2.3" }))).toBe(
+    "203.0.113.7",
+  );
+  // every hop trusted → fall back to the peer
+  expect(H.__sbClientIp(req({ "x-sb-remote-addr": "127.0.0.1", "x-forwarded-for": "10.9.9.9" }))).toBe("127.0.0.1");
+  // mapped-v6 entry in the chain is normalised
+  expect(
+    H.__sbClientIp(req({ "x-sb-remote-addr": "10.0.0.1", "x-forwarded-for": "::ffff:198.51.100.9, 10.1.2.3" })),
+  ).toBe("198.51.100.9");
+});
+
+test("__sbClientIp: an untrusted peer cannot use XFF even if it sends one", () => {
+  env = { SB_TRUSTED_PROXIES: "10.0.0.0/8" };
+  expect(H.__sbClientIp(req({ "x-sb-remote-addr": "198.51.100.9", "x-forwarded-for": "1.1.1.1" }))).toBe("198.51.100.9");
+});

package/src/native-fetch-prelude.js

@@ -4,8 +4,10 @@
 // json(). This adds, additively, the rest of the WHATWG surface Worker code
 // expects: URLSearchParams (read + write), URL.prototype.searchParams and the
 // protocol/host/hostname/port/hash accessors, static Response.json,
-// crypto.randomUUID / crypto.getRandomValues, and structuredClone. Each is
-// feature-detected; delete a block once Porffor ships that global.
+// crypto.randomUUID / crypto.getRandomValues, crypto.subtle (digest + HMAC
+// sign/verify, #133), and structuredClone. Each is feature-detected; delete a
+// block once Porffor ships that global. crypto.scryptVerify (#153) is a
+// Sproutboat extension, not WHATWG, and stays.
 // Tracked upstream in patches/UPSTREAM.md.
 //
 // Declared before it is referenced: a getter body that names a later top-level
@@ -276,6 +278,141 @@ if (globalThis.crypto.randomUUID == null) {
   };
 }
 
+// #133 — a WebCrypto subset: crypto.subtle.digest (SHA-256/384/512) and HMAC
+// sign/verify over a raw key. Enough for JWTs and hand-rolled sessions; not a
+// complete SubtleCrypto (no ECDSA, no AES, no key wrapping). The surface is
+// exactly standard so it can be deleted when Porffor ships Web Crypto
+// (CanadaHonk/porffor#347). Backed by the inline-C SHA-2 above, not a link
+// dependency, so it works on the broker transport too.
+function __sbHashBits(algo) {
+  const n = String((algo && algo.name) || algo || "").toUpperCase();
+  if (n === "SHA-256" || n === "SHA256") return "256";
+  if (n === "SHA-384" || n === "SHA384") return "384";
+  if (n === "SHA-512" || n === "SHA512") return "512";
+  return "";
+}
+// -> a latin1 string, one char per byte. Strings are UTF-8 encoded (matching
+// TextEncoder); ArrayBuffer / typed-array input is copied byte for byte.
+function __sbToBytes(input) {
+  if (input == null) return "";
+  if (__sbIsStr(input)) {
+    let s = "";
+    for (let i = 0; i < input.length; i++) {
+      const c = input.charCodeAt(i);
+      if (c < 0x80) s += String.fromCharCode(c);
+      else if (c < 0x800) s += String.fromCharCode(0xc0 | (c >> 6)) + String.fromCharCode(0x80 | (c & 0x3f));
+      else if (c >= 0xd800 && c < 0xdc00 && i + 1 < input.length) {
+        const cp = 0x10000 + ((c - 0xd800) << 10) + (input.charCodeAt(++i) - 0xdc00);
+        s +=
+          String.fromCharCode(0xf0 | (cp >> 18)) +
+          String.fromCharCode(0x80 | ((cp >> 12) & 0x3f)) +
+          String.fromCharCode(0x80 | ((cp >> 6) & 0x3f)) +
+          String.fromCharCode(0x80 | (cp & 0x3f));
+      } else
+        s +=
+          String.fromCharCode(0xe0 | (c >> 12)) +
+          String.fromCharCode(0x80 | ((c >> 6) & 0x3f)) +
+          String.fromCharCode(0x80 | (c & 0x3f));
+    }
+    return s;
+  }
+  const view = input.length !== undefined && input.buffer !== undefined ? input : new Uint8Array(input);
+  let s = "";
+  for (let i = 0; i < view.length; i++) s += String.fromCharCode(view[i] & 0xff);
+  return s;
+}
+function __sbBufFrom(latin1) {
+  const b = new Uint8Array(latin1.length);
+  for (let i = 0; i < latin1.length; i++) b[i] = latin1.charCodeAt(i) & 0xff;
+  return b.buffer;
+}
+// Constant-time compare of two latin1 byte strings.
+function __sbEqCt(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+// An even-length all-hex string -> its bytes; anything else -> its raw bytes.
+function __sbHexOrBytes(value) {
+  if (__sbIsStr(value) && value.length > 0 && value.length % 2 === 0) {
+    let out = "";
+    for (let i = 0; i < value.length; i++) {
+      const c = value.charCodeAt(i);
+      const d = c >= 48 && c <= 57 ? c - 48 : c >= 97 && c <= 102 ? c - 87 : c >= 65 && c <= 70 ? c - 55 : -1;
+      if (d < 0) return __sbToBytes(value);
+      if (i % 2 === 0) out += String.fromCharCode(d << 4);
+      else out = out.slice(0, -1) + String.fromCharCode(out.charCodeAt(out.length - 1) | d);
+    }
+    return out;
+  }
+  return __sbToBytes(value);
+}
+
+if (globalThis.crypto.subtle == null) {
+  globalThis.crypto.subtle = {
+    async digest(algo, data) {
+      const bits = __sbHashBits(algo);
+      if (!bits) throw new Error("crypto.subtle.digest: unsupported algorithm");
+      const out = __sbDigestRaw(bits, __sbToBytes(data));
+      if (!out) throw new Error("crypto.subtle.digest failed");
+      return __sbBufFrom(out);
+    },
+    async importKey(format, keyData, algo, extractable, usages) {
+      if (format !== "raw") throw new Error("crypto.subtle.importKey: only format 'raw' is supported");
+      const name = String((algo && algo.name) || algo || "").toUpperCase();
+      if (name !== "HMAC") throw new Error("crypto.subtle.importKey: only HMAC keys are supported");
+      const bits = __sbHashBits((algo && algo.hash) || "SHA-256");
+      if (!bits) throw new Error("crypto.subtle.importKey: unsupported hash");
+      return {
+        type: "secret",
+        extractable: !!extractable,
+        algorithm: { name: "HMAC", hash: { name: "SHA-" + bits } },
+        usages: usages || [],
+        __sbKey: __sbToBytes(keyData),
+        __sbBits: bits,
+      };
+    },
+    async sign(algo, key, data) {
+      if (!key || key.__sbKey == null) throw new Error("crypto.subtle.sign: only HMAC keys from importKey are supported");
+      const out = __sbHmacRaw(key.__sbBits, key.__sbKey, __sbToBytes(data));
+      if (!out) throw new Error("crypto.subtle.sign failed");
+      return __sbBufFrom(out);
+    },
+    async verify(algo, key, signature, data) {
+      if (!key || key.__sbKey == null) throw new Error("crypto.subtle.verify: only HMAC keys are supported");
+      const mac = __sbHmacRaw(key.__sbBits, key.__sbKey, __sbToBytes(data));
+      if (!mac) return false;
+      return __sbEqCt(mac, __sbToBytes(signature));
+    },
+  };
+}
+
+// #153 — scrypt verification, for migrating password hashes made elsewhere
+// (Node/Bun `scrypt`, N/r/p). Not on WebCrypto; deliberately verify-only, so it
+// is a migration tool rather than a KDF blessed for new credentials — new
+// credentials should use HMAC/PBKDF2 via crypto.subtle. `expected` is the stored
+// hash: a hex string, or bytes (ArrayBuffer / Uint8Array).
+if (globalThis.crypto.scryptVerify == null) {
+  globalThis.crypto.scryptVerify = function (password, salt, expected, params) {
+    const p = params || {};
+    const N = p.N || p.cost || 16384;
+    const r = p.r || p.blockSize || 8;
+    const par = p.p || p.parallelization || 1;
+    const want = __sbHexOrBytes(expected);
+    if (want.length === 0) return false;
+    const dk = __sbScryptRaw(
+      __sbToBytes(password),
+      __sbToBytes(salt),
+      String(N),
+      String(r),
+      String(par),
+      String(want.length),
+    );
+    return dk.length === want.length && __sbEqCt(dk, want);
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Bindings: env.<KV>, env.<SECRET>, env.<D1>, env.<R2>, and globalThis.fetch,
 // backed by a Bun broker on a loopback TCP port. The transport is inline C —
@@ -300,10 +437,291 @@ Porffor.c`
 #include <fcntl.h>
 #include <errno.h>
 #include <time.h>
+#include <stdint.h>
 
 u32 porf_native_fetch_alloc_bytestring(const char* input, size_t len);
 int porf_native_fetch_read_value(jsval value, const char** out_buf, size_t* out_len, char** out_owned);
 
+// --- #133: SHA-2 + HMAC ---------------------------------------------------
+// Standalone links BearSSL, but a deployed sprout does not, and this inline C
+// is shared by both transports — so a plain reference SHA-2 rather than a link
+// dependency. It also lets a handler drop a vendored pure-JS SHA-256. Exposed
+// as crypto.subtle.digest / sign / verify (HMAC), which deletes cleanly when
+// Porffor ships Web Crypto (CanadaHonk/porffor#347).
+#define SB_ROR32(x, n) (((x) >> (n)) | ((x) << (32 - (n))))
+#define SB_ROR64(x, n) (((x) >> (n)) | ((x) << (64 - (n))))
+
+typedef struct { uint32_t h[8]; uint64_t len; unsigned char buf[64]; size_t n; } sb_sha256_ctx;
+static const uint32_t sb_k256[64] = {
+  0x428a2f98,0x71374491,0xb5c0fbcf,0xe9b5dba5,0x3956c25b,0x59f111f1,0x923f82a4,0xab1c5ed5,
+  0xd807aa98,0x12835b01,0x243185be,0x550c7dc3,0x72be5d74,0x80deb1fe,0x9bdc06a7,0xc19bf174,
+  0xe49b69c1,0xefbe4786,0x0fc19dc6,0x240ca1cc,0x2de92c6f,0x4a7484aa,0x5cb0a9dc,0x76f988da,
+  0x983e5152,0xa831c66d,0xb00327c8,0xbf597fc7,0xc6e00bf3,0xd5a79147,0x06ca6351,0x14292967,
+  0x27b70a85,0x2e1b2138,0x4d2c6dfc,0x53380d13,0x650a7354,0x766a0abb,0x81c2c92e,0x92722c85,
+  0xa2bfe8a1,0xa81a664b,0xc24b8b70,0xc76c51a3,0xd192e819,0xd6990624,0xf40e3585,0x106aa070,
+  0x19a4c116,0x1e376c08,0x2748774c,0x34b0bcb5,0x391c0cb3,0x4ed8aa4a,0x5b9cca4f,0x682e6ff3,
+  0x748f82ee,0x78a5636f,0x84c87814,0x8cc70208,0x90befffa,0xa4506ceb,0xbef9a3f7,0xc67178f2 };
+static void sb_sha256_block(sb_sha256_ctx* c, const unsigned char* p) {
+  uint32_t w[64], a,b,cc,d,e,f,g,h,t1,t2;
+  for (int i = 0; i < 16; i++)
+    w[i] = ((uint32_t)p[i*4]<<24)|((uint32_t)p[i*4+1]<<16)|((uint32_t)p[i*4+2]<<8)|((uint32_t)p[i*4+3]);
+  for (int i = 16; i < 64; i++) {
+    uint32_t s0 = SB_ROR32(w[i-15],7) ^ SB_ROR32(w[i-15],18) ^ (w[i-15]>>3);
+    uint32_t s1 = SB_ROR32(w[i-2],17) ^ SB_ROR32(w[i-2],19) ^ (w[i-2]>>10);
+    w[i] = w[i-16] + s0 + w[i-7] + s1;
+  }
+  a=c->h[0];b=c->h[1];cc=c->h[2];d=c->h[3];e=c->h[4];f=c->h[5];g=c->h[6];h=c->h[7];
+  for (int i = 0; i < 64; i++) {
+    uint32_t S1 = SB_ROR32(e,6) ^ SB_ROR32(e,11) ^ SB_ROR32(e,25);
+    uint32_t ch = (e & f) ^ (~e & g);
+    t1 = h + S1 + ch + sb_k256[i] + w[i];
+    uint32_t S0 = SB_ROR32(a,2) ^ SB_ROR32(a,13) ^ SB_ROR32(a,22);
+    uint32_t maj = (a & b) ^ (a & cc) ^ (b & cc);
+    t2 = S0 + maj;
+    h=g;g=f;f=e;e=d+t1;d=cc;cc=b;b=a;a=t1+t2;
+  }
+  c->h[0]+=a;c->h[1]+=b;c->h[2]+=cc;c->h[3]+=d;c->h[4]+=e;c->h[5]+=f;c->h[6]+=g;c->h[7]+=h;
+}
+static void sb_sha256_init(sb_sha256_ctx* c) {
+  c->h[0]=0x6a09e667;c->h[1]=0xbb67ae85;c->h[2]=0x3c6ef372;c->h[3]=0xa54ff53a;
+  c->h[4]=0x510e527f;c->h[5]=0x9b05688c;c->h[6]=0x1f83d9ab;c->h[7]=0x5be0cd19;c->len=0;c->n=0;
+}
+static void sb_sha256_update(sb_sha256_ctx* c, const unsigned char* p, size_t n) {
+  c->len += n;
+  while (n) {
+    size_t k = 64 - c->n; if (k > n) k = n;
+    memcpy(c->buf + c->n, p, k); c->n += k; p += k; n -= k;
+    if (c->n == 64) { sb_sha256_block(c, c->buf); c->n = 0; }
+  }
+}
+static void sb_sha256_final(sb_sha256_ctx* c, unsigned char out[32]) {
+  uint64_t bits = c->len * 8;
+  unsigned char pad = 0x80;
+  sb_sha256_update(c, &pad, 1);
+  unsigned char z = 0;
+  while (c->n != 56) sb_sha256_update(c, &z, 1);
+  unsigned char lb[8];
+  for (int i = 0; i < 8; i++) lb[i] = (unsigned char)(bits >> (56 - i*8));
+  sb_sha256_update(c, lb, 8);
+  for (int i = 0; i < 8; i++) {
+    out[i*4]=(unsigned char)(c->h[i]>>24);out[i*4+1]=(unsigned char)(c->h[i]>>16);
+    out[i*4+2]=(unsigned char)(c->h[i]>>8);out[i*4+3]=(unsigned char)c->h[i];
+  }
+}
+
+typedef struct { uint64_t h[8]; uint64_t lenhi, lenlo; unsigned char buf[128]; size_t n; } sb_sha512_ctx;
+static const uint64_t sb_k512[80] = {
+  0x428a2f98d728ae22ULL,0x7137449123ef65cdULL,0xb5c0fbcfec4d3b2fULL,0xe9b5dba58189dbbcULL,
+  0x3956c25bf348b538ULL,0x59f111f1b605d019ULL,0x923f82a4af194f9bULL,0xab1c5ed5da6d8118ULL,
+  0xd807aa98a3030242ULL,0x12835b0145706fbeULL,0x243185be4ee4b28cULL,0x550c7dc3d5ffb4e2ULL,
+  0x72be5d74f27b896fULL,0x80deb1fe3b1696b1ULL,0x9bdc06a725c71235ULL,0xc19bf174cf692694ULL,
+  0xe49b69c19ef14ad2ULL,0xefbe4786384f25e3ULL,0x0fc19dc68b8cd5b5ULL,0x240ca1cc77ac9c65ULL,
+  0x2de92c6f592b0275ULL,0x4a7484aa6ea6e483ULL,0x5cb0a9dcbd41fbd4ULL,0x76f988da831153b5ULL,
+  0x983e5152ee66dfabULL,0xa831c66d2db43210ULL,0xb00327c898fb213fULL,0xbf597fc7beef0ee4ULL,
+  0xc6e00bf33da88fc2ULL,0xd5a79147930aa725ULL,0x06ca6351e003826fULL,0x142929670a0e6e70ULL,
+  0x27b70a8546d22ffcULL,0x2e1b21385c26c926ULL,0x4d2c6dfc5ac42aedULL,0x53380d139d95b3dfULL,
+  0x650a73548baf63deULL,0x766a0abb3c77b2a8ULL,0x81c2c92e47edaee6ULL,0x92722c851482353bULL,
+  0xa2bfe8a14cf10364ULL,0xa81a664bbc423001ULL,0xc24b8b70d0f89791ULL,0xc76c51a30654be30ULL,
+  0xd192e819d6ef5218ULL,0xd69906245565a910ULL,0xf40e35855771202aULL,0x106aa07032bbd1b8ULL,
+  0x19a4c116b8d2d0c8ULL,0x1e376c085141ab53ULL,0x2748774cdf8eeb99ULL,0x34b0bcb5e19b48a8ULL,
+  0x391c0cb3c5c95a63ULL,0x4ed8aa4ae3418acbULL,0x5b9cca4f7763e373ULL,0x682e6ff3d6b2b8a3ULL,
+  0x748f82ee5defb2fcULL,0x78a5636f43172f60ULL,0x84c87814a1f0ab72ULL,0x8cc702081a6439ecULL,
+  0x90befffa23631e28ULL,0xa4506cebde82bde9ULL,0xbef9a3f7b2c67915ULL,0xc67178f2e372532bULL,
+  0xca273eceea26619cULL,0xd186b8c721c0c207ULL,0xeada7dd6cde0eb1eULL,0xf57d4f7fee6ed178ULL,
+  0x06f067aa72176fbaULL,0x0a637dc5a2c898a6ULL,0x113f9804bef90daeULL,0x1b710b35131c471bULL,
+  0x28db77f523047d84ULL,0x32caab7b40c72493ULL,0x3c9ebe0a15c9bebcULL,0x431d67c49c100d4cULL,
+  0x4cc5d4becb3e42b6ULL,0x597f299cfc657e2aULL,0x5fcb6fab3ad6faecULL,0x6c44198c4a475817ULL };
+static void sb_sha512_block(sb_sha512_ctx* c, const unsigned char* p) {
+  uint64_t w[80], a,b,cc,d,e,f,g,h,t1,t2;
+  for (int i = 0; i < 16; i++) {
+    w[i] = 0; for (int j = 0; j < 8; j++) w[i] = (w[i]<<8) | p[i*8+j];
+  }
+  for (int i = 16; i < 80; i++) {
+    uint64_t s0 = SB_ROR64(w[i-15],1) ^ SB_ROR64(w[i-15],8) ^ (w[i-15]>>7);
+    uint64_t s1 = SB_ROR64(w[i-2],19) ^ SB_ROR64(w[i-2],61) ^ (w[i-2]>>6);
+    w[i] = w[i-16] + s0 + w[i-7] + s1;
+  }
+  a=c->h[0];b=c->h[1];cc=c->h[2];d=c->h[3];e=c->h[4];f=c->h[5];g=c->h[6];h=c->h[7];
+  for (int i = 0; i < 80; i++) {
+    uint64_t S1 = SB_ROR64(e,14) ^ SB_ROR64(e,18) ^ SB_ROR64(e,41);
+    uint64_t ch = (e & f) ^ (~e & g);
+    t1 = h + S1 + ch + sb_k512[i] + w[i];
+    uint64_t S0 = SB_ROR64(a,28) ^ SB_ROR64(a,34) ^ SB_ROR64(a,39);
+    uint64_t maj = (a & b) ^ (a & cc) ^ (b & cc);
+    t2 = S0 + maj;
+    h=g;g=f;f=e;e=d+t1;d=cc;cc=b;b=a;a=t1+t2;
+  }
+  c->h[0]+=a;c->h[1]+=b;c->h[2]+=cc;c->h[3]+=d;c->h[4]+=e;c->h[5]+=f;c->h[6]+=g;c->h[7]+=h;
+}
+static void sb_sha512_init(sb_sha512_ctx* c, int is384) {
+  if (is384) {
+    c->h[0]=0xcbbb9d5dc1059ed8ULL;c->h[1]=0x629a292a367cd507ULL;c->h[2]=0x9159015a3070dd17ULL;c->h[3]=0x152fecd8f70e5939ULL;
+    c->h[4]=0x67332667ffc00b31ULL;c->h[5]=0x8eb44a8768581511ULL;c->h[6]=0xdb0c2e0d64f98fa7ULL;c->h[7]=0x47b5481dbefa4fa4ULL;
+  } else {
+    c->h[0]=0x6a09e667f3bcc908ULL;c->h[1]=0xbb67ae8584caa73bULL;c->h[2]=0x3c6ef372fe94f82bULL;c->h[3]=0xa54ff53a5f1d36f1ULL;
+    c->h[4]=0x510e527fade682d1ULL;c->h[5]=0x9b05688c2b3e6c1fULL;c->h[6]=0x1f83d9abfb41bd6bULL;c->h[7]=0x5be0cd19137e2179ULL;
+  }
+  c->lenhi=0;c->lenlo=0;c->n=0;
+}
+static void sb_sha512_update(sb_sha512_ctx* c, const unsigned char* p, size_t n) {
+  uint64_t add = n; if ((c->lenlo += add) < add) c->lenhi++;
+  while (n) {
+    size_t k = 128 - c->n; if (k > n) k = n;
+    memcpy(c->buf + c->n, p, k); c->n += k; p += k; n -= k;
+    if (c->n == 128) { sb_sha512_block(c, c->buf); c->n = 0; }
+  }
+}
+static void sb_sha512_final(sb_sha512_ctx* c, unsigned char* out, int is384) {
+  uint64_t bhi = (c->lenhi << 3) | (c->lenlo >> 61), blo = c->lenlo << 3;
+  unsigned char pad = 0x80;
+  sb_sha512_update(c, &pad, 1);
+  unsigned char z = 0;
+  while (c->n != 112) sb_sha512_update(c, &z, 1);
+  unsigned char lb[16];
+  for (int i = 0; i < 8; i++) lb[i] = (unsigned char)(bhi >> (56 - i*8));
+  for (int i = 0; i < 8; i++) lb[8+i] = (unsigned char)(blo >> (56 - i*8));
+  sb_sha512_update(c, lb, 16);
+  int words = is384 ? 6 : 8;
+  for (int i = 0; i < words; i++)
+    for (int j = 0; j < 8; j++) out[i*8+j] = (unsigned char)(c->h[i] >> (56 - j*8));
+}
+
+// One-shot digest. algo: 256 | 384 | 512. out must hold 32/48/64 bytes.
+// Returns the digest length, or 0 for an unknown algo.
+static size_t sb_digest(int algo, const unsigned char* msg, size_t mlen, unsigned char* out) {
+  if (algo == 256) { sb_sha256_ctx c; sb_sha256_init(&c); sb_sha256_update(&c, msg, mlen); sb_sha256_final(&c, out); return 32; }
+  if (algo == 384) { sb_sha512_ctx c; sb_sha512_init(&c, 1); sb_sha512_update(&c, msg, mlen); sb_sha512_final(&c, out, 1); return 48; }
+  if (algo == 512) { sb_sha512_ctx c; sb_sha512_init(&c, 0); sb_sha512_update(&c, msg, mlen); sb_sha512_final(&c, out, 0); return 64; }
+  return 0;
+}
+
+// HMAC(algo) per RFC 2104. Block size is 64 for SHA-256, 128 for SHA-384/512.
+static size_t sb_hmac(int algo, const unsigned char* key, size_t klen,
+                      const unsigned char* msg, size_t mlen, unsigned char* out) {
+  size_t bs = algo == 256 ? 64 : 128;
+  unsigned char k[128], ipad[128], opad[128], inner[64];
+  memset(k, 0, sizeof(k));
+  if (klen > bs) { sb_digest(algo, key, klen, k); }
+  else memcpy(k, key, klen);
+  for (size_t i = 0; i < bs; i++) { ipad[i] = k[i] ^ 0x36; opad[i] = k[i] ^ 0x5c; }
+  size_t dl;
+  if (algo == 256) {
+    sb_sha256_ctx c; sb_sha256_init(&c);
+    sb_sha256_update(&c, ipad, bs); sb_sha256_update(&c, msg, mlen); sb_sha256_final(&c, inner);
+    sb_sha256_ctx o; sb_sha256_init(&o);
+    sb_sha256_update(&o, opad, bs); sb_sha256_update(&o, inner, 32); sb_sha256_final(&o, out);
+    dl = 32;
+  } else {
+    int is384 = algo == 384; dl = is384 ? 48 : 64;
+    sb_sha512_ctx c; sb_sha512_init(&c, is384);
+    sb_sha512_update(&c, ipad, bs); sb_sha512_update(&c, msg, mlen); sb_sha512_final(&c, inner, is384);
+    sb_sha512_ctx o; sb_sha512_init(&o, is384);
+    sb_sha512_update(&o, opad, bs); sb_sha512_update(&o, inner, dl); sb_sha512_final(&o, out, is384);
+  }
+  return dl;
+}
+
+// --- #153: scrypt (RFC 7914), for verifying pre-existing password hashes ----
+// PBKDF2-HMAC-SHA256 (reuses sb_hmac) + Salsa20/8 + BlockMix + ROMix. Exposed
+// only as crypto.scryptVerify: a migration path for hashes made elsewhere
+// (Node/Bun scrypt), not a blessed KDF for new credentials.
+static void sb_pbkdf2_hmac256(const unsigned char* pw, size_t pwlen,
+                              const unsigned char* salt, size_t saltlen,
+                              uint32_t iters, unsigned char* out, size_t dklen) {
+  unsigned char block[64], u[32], t[32];
+  uint32_t i = 1;
+  size_t done = 0;
+  while (done < dklen) {
+    unsigned char* s2 = (unsigned char*)malloc(saltlen + 4);
+    memcpy(s2, salt, saltlen);
+    s2[saltlen] = (unsigned char)(i >> 24); s2[saltlen+1] = (unsigned char)(i >> 16);
+    s2[saltlen+2] = (unsigned char)(i >> 8); s2[saltlen+3] = (unsigned char)i;
+    sb_hmac(256, pw, pwlen, s2, saltlen + 4, u);
+    free(s2);
+    memcpy(t, u, 32);
+    // iters is 1 for scrypt's use of PBKDF2, but support the general case.
+    for (uint32_t j = 1; j < iters; j++) {
+      sb_hmac(256, pw, pwlen, u, 32, u);
+      for (int k = 0; k < 32; k++) t[k] ^= u[k];
+    }
+    memcpy(block, t, 32);
+    size_t take = dklen - done; if (take > 32) take = 32;
+    memcpy(out + done, block, take);
+    done += take; i++;
+  }
+}
+static void sb_salsa20_8(uint32_t out[16], const uint32_t in[16]) {
+  uint32_t x[16];
+  for (int i = 0; i < 16; i++) x[i] = in[i];
+  for (int i = 0; i < 4; i++) {
+    x[ 4] ^= SB_ROR32(x[ 0] + x[12], 32 - 7);  x[ 8] ^= SB_ROR32(x[ 4] + x[ 0], 32 - 9);
+    x[12] ^= SB_ROR32(x[ 8] + x[ 4], 32 - 13); x[ 0] ^= SB_ROR32(x[12] + x[ 8], 32 - 18);
+    x[ 9] ^= SB_ROR32(x[ 5] + x[ 1], 32 - 7);  x[13] ^= SB_ROR32(x[ 9] + x[ 5], 32 - 9);
+    x[ 1] ^= SB_ROR32(x[13] + x[ 9], 32 - 13); x[ 5] ^= SB_ROR32(x[ 1] + x[13], 32 - 18);
+    x[14] ^= SB_ROR32(x[10] + x[ 6], 32 - 7);  x[ 2] ^= SB_ROR32(x[14] + x[10], 32 - 9);
+    x[ 6] ^= SB_ROR32(x[ 2] + x[14], 32 - 13); x[10] ^= SB_ROR32(x[ 6] + x[ 2], 32 - 18);
+    x[ 3] ^= SB_ROR32(x[15] + x[11], 32 - 7);  x[ 7] ^= SB_ROR32(x[ 3] + x[15], 32 - 9);
+    x[11] ^= SB_ROR32(x[ 7] + x[ 3], 32 - 13); x[15] ^= SB_ROR32(x[11] + x[ 7], 32 - 18);
+    x[ 1] ^= SB_ROR32(x[ 0] + x[ 3], 32 - 7);  x[ 2] ^= SB_ROR32(x[ 1] + x[ 0], 32 - 9);
+    x[ 3] ^= SB_ROR32(x[ 2] + x[ 1], 32 - 13); x[ 0] ^= SB_ROR32(x[ 3] + x[ 2], 32 - 18);
+    x[ 6] ^= SB_ROR32(x[ 5] + x[ 4], 32 - 7);  x[ 7] ^= SB_ROR32(x[ 6] + x[ 5], 32 - 9);
+    x[ 4] ^= SB_ROR32(x[ 7] + x[ 6], 32 - 13); x[ 5] ^= SB_ROR32(x[ 4] + x[ 7], 32 - 18);
+    x[11] ^= SB_ROR32(x[10] + x[ 9], 32 - 7);  x[ 8] ^= SB_ROR32(x[11] + x[10], 32 - 9);
+    x[ 9] ^= SB_ROR32(x[ 8] + x[11], 32 - 13); x[10] ^= SB_ROR32(x[ 9] + x[ 8], 32 - 18);
+    x[12] ^= SB_ROR32(x[15] + x[14], 32 - 7);  x[13] ^= SB_ROR32(x[12] + x[15], 32 - 9);
+    x[14] ^= SB_ROR32(x[13] + x[12], 32 - 13); x[15] ^= SB_ROR32(x[14] + x[13], 32 - 18);
+  }
+  for (int i = 0; i < 16; i++) out[i] = x[i] + in[i];
+}
+// BlockMix: B is 2r 64-byte blocks (as uint32 words). Result into out.
+static void sb_blockmix(const uint32_t* b, uint32_t* out, size_t r) {
+  uint32_t x[16], y[16];
+  memcpy(x, b + (2*r - 1) * 16, 64);
+  for (size_t i = 0; i < 2*r; i++) {
+    for (int k = 0; k < 16; k++) x[k] ^= b[i*16 + k];
+    sb_salsa20_8(y, x);
+    memcpy(x, y, 64);
+    size_t dst = (i % 2 == 0) ? (i/2) : (r + (i-1)/2);
+    memcpy(out + dst*16, x, 64);
+  }
+}
+static uint64_t sb_integerify(const uint32_t* b, size_t r) {
+  const uint32_t* p = b + (2*r - 1) * 16;
+  return ((uint64_t)p[0]) | (((uint64_t)p[1]) << 32);
+}
+// scrypt(pw, salt, N, r, p) -> dk[dklen]. Returns 0 on success, -1 on bad
+// params or allocation failure. Caps N*r so a bad config cannot ask for GB.
+static int sb_scrypt(const unsigned char* pw, size_t pwlen, const unsigned char* salt, size_t saltlen,
+                     uint64_t N, uint32_t r, uint32_t p, unsigned char* dk, size_t dklen) {
+  if (r == 0 || p == 0 || N < 2 || (N & (N - 1)) != 0) return -1;
+  if ((uint64_t)r * N > (1ULL << 20)) return -1; // <= 128 MiB of V
+  size_t blk = 128 * (size_t)r;                  // one B block, bytes
+  unsigned char* b = (unsigned char*)malloc(blk * p);
+  uint32_t* v = (uint32_t*)malloc(blk * (size_t)N);
+  uint32_t* xy = (uint32_t*)malloc(blk * 2);
+  if (!b || !v || !xy) { free(b); free(v); free(xy); return -1; }
+  sb_pbkdf2_hmac256(pw, pwlen, salt, saltlen, 1, b, blk * p);
+  for (uint32_t i = 0; i < p; i++) {
+    uint32_t* x = (uint32_t*)(b + (size_t)i * blk);
+    uint32_t* y = xy;
+    for (uint64_t j = 0; j < N; j++) {
+      memcpy(v + j * (blk / 4), x, blk);
+      sb_blockmix(x, y, r);
+      memcpy(x, y, blk);
+    }
+    for (uint64_t j = 0; j < N; j++) {
+      uint64_t k = sb_integerify(x, r) & (N - 1);
+      const uint32_t* vk = v + k * (blk / 4);
+      for (size_t w = 0; w < blk / 4; w++) x[w] ^= vk[w];
+      sb_blockmix(x, y, r);
+      memcpy(x, y, blk);
+    }
+  }
+  sb_pbkdf2_hmac256(pw, pwlen, b, blk * p, 1, dk, dklen);
+  free(b); free(v); free(xy);
+  return 0;
+}
+
 // Fill buf with n bytes from the OS CSPRNG. /dev/urandom is present on Linux and
 // macOS and inside the bubblewrap sandbox; blocking is not a concern after the
 // pool is seeded. Returns 0, or -1 if the source could not be read in full.
@@ -354,6 +772,101 @@ function __sbRandomBytes(nStr) {
   return out;
 }
 
+// #133 — one-shot SHA-2 digest. `algoStr` is "256"|"384"|"512"; `data` is a
+// latin1 string (one char per byte). Returns the raw digest as a bytestring.
+// oxlint-disable-next-line no-unused-vars -- read inside the RawC block, not by JS.
+function __sbDigestRaw(algoStr, data) {
+  let out = "";
+  // oxlint-disable-next-line no-unused-expressions -- Porffor.c`...` is inline C the compiler consumes, not a JS expression.
+  Porffor.c`
+    const char* __as; size_t __asl; char* __aso = 0;
+    porf_native_fetch_read_value(algoStr, &__as, &__asl, &__aso);
+    char __ab[8]; size_t __ak = __asl < 7 ? __asl : 7;
+    memcpy(__ab, __as, __ak); __ab[__ak] = 0;
+    if (__aso) free(__aso);
+    int __algo = atoi(__ab);
+
+    const char* __d; size_t __dl; char* __do = 0;
+    porf_native_fetch_read_value(data, &__d, &__dl, &__do);
+    unsigned char __out[64];
+    size_t __n = sb_digest(__algo, (const unsigned char*)__d, __dl, __out);
+    if (__do) free(__do);
+    if (__n) out = porf_box((f64)porf_native_fetch_alloc_bytestring((const char*)__out, __n), 195);
+  `;
+  return out;
+}
+
+// #133 — HMAC-SHA-2. `algoStr` "256"|"384"|"512"; `key` and `data` latin1.
+// Returns the raw MAC as a bytestring.
+// oxlint-disable-next-line no-unused-vars -- read inside the RawC block, not by JS.
+function __sbHmacRaw(algoStr, key, data) {
+  let out = "";
+  // oxlint-disable-next-line no-unused-expressions -- Porffor.c`...` is inline C the compiler consumes, not a JS expression.
+  Porffor.c`
+    const char* __as; size_t __asl; char* __aso = 0;
+    porf_native_fetch_read_value(algoStr, &__as, &__asl, &__aso);
+    char __ab[8]; size_t __ak = __asl < 7 ? __asl : 7;
+    memcpy(__ab, __as, __ak); __ab[__ak] = 0;
+    if (__aso) free(__aso);
+    int __algo = atoi(__ab);
+
+    const char* __k; size_t __kl; char* __ko = 0;
+    porf_native_fetch_read_value(key, &__k, &__kl, &__ko);
+    unsigned char* __kc = (unsigned char*)malloc(__kl ? __kl : 1);
+    if (__kc) memcpy(__kc, __k, __kl);
+    if (__ko) free(__ko);
+
+    const char* __d; size_t __dl; char* __do = 0;
+    porf_native_fetch_read_value(data, &__d, &__dl, &__do);
+    unsigned char __out[64];
+    size_t __n = __kc ? sb_hmac(__algo, __kc, __kl, (const unsigned char*)__d, __dl, __out) : 0;
+    if (__do) free(__do);
+    if (__kc) free(__kc);
+    if (__n) out = porf_box((f64)porf_native_fetch_alloc_bytestring((const char*)__out, __n), 195);
+  `;
+  return out;
+}
+
+// #153 — scrypt derivation. All params are decimal strings. Returns the derived
+// key as a bytestring, or '' on bad params / allocation failure.
+// oxlint-disable-next-line no-unused-vars -- read inside the RawC block, not by JS.
+function __sbScryptRaw(pw, salt, nStr, rStr, pStr, dkLenStr) {
+  let out = "";
+  // oxlint-disable-next-line no-unused-expressions -- Porffor.c`...` is inline C the compiler consumes, not a JS expression.
+  Porffor.c`
+    const char* __p; size_t __pl; char* __po = 0;
+    porf_native_fetch_read_value(pw, &__p, &__pl, &__po);
+    unsigned char* __pc = (unsigned char*)malloc(__pl ? __pl : 1);
+    if (__pc) memcpy(__pc, __p, __pl);
+    if (__po) free(__po);
+
+    const char* __s; size_t __sl; char* __so = 0;
+    porf_native_fetch_read_value(salt, &__s, &__sl, &__so);
+    unsigned char* __sc = (unsigned char*)malloc(__sl ? __sl : 1);
+    if (__sc) memcpy(__sc, __s, __sl);
+    if (__so) free(__so);
+
+    long __N = 0, __r = 0, __pp = 0, __dk = 0;
+    { const char* q; size_t ql; char* qo = 0; char nb[24];
+      porf_native_fetch_read_value(nStr, &q, &ql, &qo); { size_t k = ql < 23 ? ql : 23; memcpy(nb, q, k); nb[k] = 0; } if (qo) free(qo); __N = atol(nb);
+      porf_native_fetch_read_value(rStr, &q, &ql, &qo); { size_t k = ql < 23 ? ql : 23; memcpy(nb, q, k); nb[k] = 0; } if (qo) free(qo); __r = atol(nb);
+      porf_native_fetch_read_value(pStr, &q, &ql, &qo); { size_t k = ql < 23 ? ql : 23; memcpy(nb, q, k); nb[k] = 0; } if (qo) free(qo); __pp = atol(nb);
+      porf_native_fetch_read_value(dkLenStr, &q, &ql, &qo); { size_t k = ql < 23 ? ql : 23; memcpy(nb, q, k); nb[k] = 0; } if (qo) free(qo); __dk = atol(nb);
+    }
+    if (__pc && __sc && __dk > 0 && __dk <= 1024) {
+      unsigned char* __d = (unsigned char*)malloc((size_t)__dk);
+      if (__d) {
+        if (sb_scrypt(__pc, __pl, __sc, __sl, (uint64_t)__N, (uint32_t)__r, (uint32_t)__pp, __d, (size_t)__dk) == 0)
+          out = porf_box((f64)porf_native_fetch_alloc_bytestring((const char*)__d, (size_t)__dk), 195);
+        free(__d);
+      }
+    }
+    if (__pc) free(__pc);
+    if (__sc) free(__sc);
+  `;
+  return out;
+}
+
 // #63 — every request carries the protocol version it was built against and an
 // id unique to this process. The id is what makes a resend safe: the transport
 // retries the *same bytes*, so a broker that already applied the request can
@@ -421,6 +934,14 @@ function __sbMakeD1(dbName) {
       __sbRpc("d1.exec", { db: dbName, sql: String(sql) });
       return { count: (String(sql).match(/;/g) || []).length, duration: 0 };
     },
+    // Sproutboat extension (not in CF Workers D1): an online, integrity-checked
+    // snapshot of this database. Standalone only for now — the broker transport
+    // returns an error until hosted backup (#139) covers it. `name` lands under
+    // `<data-dir>/backups/`; omit it for a timestamped default. See #164.
+    backup(name) {
+      const r = __sbRpc("d1.backup", { db: dbName, name: name == null ? "" : String(name) });
+      return { path: r.path, bytes: r.bytes };
+    },
   };
 }
 
@@ -585,6 +1106,21 @@ globalThis.__sbInstallBindings = function (target, bindings) {
     target[b.binding] = __sbMakeDONamespace(b.binding, b.className);
   }
 
+  // #69 — env.<NAME>.limit({ key }) -> { success }. Fixed window: at most
+  // `limit` calls per `period` seconds for a given key. limit/period travel in
+  // the message so the op stays stateless (the transport has no config).
+  // Returns sync like the other shims (CF's is a Promise; the runtime is sync).
+  for (let i = 0; i < (bindings.ratelimiters || []).length; i++) {
+    const rl = bindings.ratelimiters[i];
+    target[rl.binding] = {
+      limit(options) {
+        const key = options && options.key != null ? String(options.key) : "";
+        const r = __sbRpc("ratelimit.check", { name: rl.binding, key, limit: rl.limit, period: rl.period });
+        return { success: !!r.success };
+      },
+    };
+  }
+
   // Static assets: env.<ASSETS>.fetch(request) -> broker `assets.get`. The edge
   // already serves matching files directly; the sprout only calls this for paths
   // it wants to own (SPA fallback, auth-gated files). The transport keeps the
@@ -844,9 +1380,119 @@ function __sbTriggerAuthed(request) {
   return request.headers.get("x-sb-token") === want;
 }
 
+// #163 — the connection's remote address, for `request.cf.clientIp`.
+//
+// `x-sb-remote-addr` is the TCP peer, appended by the server (see
+// patches/UPSTREAM.md #163) and stripped from anything a client sends, so it
+// cannot be forged. With no proxy in front, that is the client. Behind one, set
+// `SB_TRUSTED_PROXIES` to a comma-separated list of trusted CIDRs (or bare IPs):
+// when the peer is trusted, the client is the rightmost `x-forwarded-for` entry
+// that is not itself a trusted hop.
+//
+// ponytail: IPv4 CIDR ranges + exact-string match (which covers a bare IPv6).
+// An IPv6 *prefix* in SB_TRUSTED_PROXIES matches nothing — widen __sbIpInCidr if
+// a deployment ever fronts its sprout with an IPv6 proxy range.
+function __sbParseHex(s) {
+  let n = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    let d = -1;
+    if (c >= 48 && c <= 57) d = c - 48;
+    else if (c >= 97 && c <= 102) d = c - 87;
+    else if (c >= 65 && c <= 70) d = c - 55;
+    if (d < 0) return -1;
+    n = n * 16 + d;
+  }
+  return n;
+}
+// uWS hands back IPv4-mapped IPv6 for IPv4 clients on a dual-stack socket
+// (`::ffff:1.2.3.4`, or fully expanded `0:0:0:0:0:ffff:0102:0304`). Fold those
+// to the dotted IPv4 so CIDR matching and `clientIp` see a plain address.
+function __sbNormalizeIp(ip) {
+  const s = String(ip || "");
+  if (s.indexOf(":") === -1) return s;
+  const low = s.toLowerCase();
+  const dotted = low.indexOf("::ffff:");
+  if (dotted === 0 && low.indexOf(".") !== -1) return low.slice(7);
+  const g = low.split(":");
+  if (g.length === 8) {
+    let mapped = __sbParseHex(g[5]) === 0xffff;
+    for (let i = 0; i < 5; i++) if (__sbParseHex(g[i] || "0") !== 0) mapped = false;
+    if (mapped) {
+      const hi = __sbParseHex(g[6] || "0");
+      const lo = __sbParseHex(g[7] || "0");
+      if (hi >= 0 && lo >= 0) {
+        return ((hi / 256) | 0) + "." + (hi & 0xff) + "." + ((lo / 256) | 0) + "." + (lo & 0xff);
+      }
+    }
+  }
+  return s;
+}
+function __sbTrim(s) {
+  let a = 0;
+  let b = s.length;
+  while (a < b && (s.charCodeAt(a) === 32 || s.charCodeAt(a) === 9)) a++;
+  while (b > a && (s.charCodeAt(b - 1) === 32 || s.charCodeAt(b - 1) === 9)) b--;
+  return s.slice(a, b);
+}
+function __sbSplitList(raw) {
+  const out = [];
+  const parts = String(raw || "").split(",");
+  for (let i = 0; i < parts.length; i++) {
+    const v = __sbTrim(parts[i]);
+    if (v) out.push(v);
+  }
+  return out;
+}
+function __sbIpToLong(ip) {
+  const p = String(ip).split(".");
+  if (p.length !== 4) return -1;
+  let n = 0;
+  for (let i = 0; i < 4; i++) {
+    if (p[i] === "" || p[i].length > 3) return -1;
+    const o = Number(p[i]);
+    if (!(o >= 0 && o <= 255) || o !== (o | 0)) return -1;
+    n = n * 256 + o;
+  }
+  return n;
+}
+function __sbIpInCidr(ip, cidr) {
+  const slash = cidr.indexOf("/");
+  if (slash === -1) return ip === cidr; // bare IP: exact match, covers IPv6
+  const addr = __sbIpToLong(ip);
+  const base = __sbIpToLong(cidr.slice(0, slash));
+  const bits = Number(cidr.slice(slash + 1));
+  if (addr < 0 || base < 0 || !(bits >= 0 && bits <= 32)) return false;
+  if (bits === 0) return true;
+  if (bits === 32) return addr === base;
+  // Divide rather than mask: a 32-bit `&` in JS is signed and would miscompare
+  // addresses above 2^31.
+  const size = Math.pow(2, 32 - bits);
+  return Math.floor(addr / size) === Math.floor(base / size);
+}
+function __sbIpTrusted(ip, list) {
+  for (let i = 0; i < list.length; i++) if (__sbIpInCidr(ip, list[i])) return true;
+  return false;
+}
+function __sbClientIp(request) {
+  const peer = __sbNormalizeIp(request.headers.get("x-sb-remote-addr") || "");
+  const trusted = __sbSplitList(__sbEnv("SB_TRUSTED_PROXIES"));
+  if (!trusted.length || !__sbIpTrusted(peer, trusted)) return peer;
+  const xff = __sbSplitList(request.headers.get("x-forwarded-for"));
+  for (let i = xff.length - 1; i >= 0; i--) {
+    const hop = __sbNormalizeIp(xff[i]);
+    if (!__sbIpTrusted(hop, trusted)) return hop;
+  }
+  return peer;
+}
+
 globalThis.__sbEntry = function (handlers, request) {
   const trigger = request.headers.get("x-sb-trigger");
   if (!trigger) {
+    // #163 — expose the resolved client IP the Workers way, before the handler runs.
+    const __cf = request.cf || {};
+    __cf.clientIp = __sbClientIp(request);
+    request.cf = __cf;
     // #28 — per-invocation CPU time. One fetch turn per process (serial), so the
     // process CPU delta across the handler is this invocation's CPU.
     // ponytail: serial-turn assumption; revisit if the profile ever allows

package/src/transport-embedded.js

@@ -35,6 +35,7 @@ extern int sqlite3_prepare_v2(sqlite3*, const char*, int, sqlite3_stmt**, const
 extern int sqlite3_step(sqlite3_stmt*);
 extern int sqlite3_finalize(sqlite3_stmt*);
 extern int sqlite3_reset(sqlite3_stmt*);
+extern int sqlite3_clear_bindings(sqlite3_stmt*);
 extern int sqlite3_column_count(sqlite3_stmt*);
 extern int sqlite3_column_type(sqlite3_stmt*, int);
 extern const unsigned char* sqlite3_column_text(sqlite3_stmt*, int);
@@ -50,6 +51,7 @@ extern const void* sqlite3_column_blob(sqlite3_stmt*, int);
 extern int sqlite3_changes(sqlite3*);
 extern int64_t sqlite3_last_insert_rowid(sqlite3*);
 extern const char* sqlite3_errmsg(sqlite3*);
+extern int sqlite3_close(sqlite3*);
 
 #define SB_SQLITE_ROW 100
 #define SB_SQLITE_DONE 101
@@ -94,8 +96,13 @@ static int sb_db_for(const char* path) {
   // copy it saves once the file holds a few large objects. The page cache is
   // capped instead, and journal_size_limit stops the WAL staying huge after one
   // big write.
+  // busy_timeout: within one binary every binding op is serial, so there is no
+  // self-contention. It matters when the same data dir is served by several
+  // copies of the binary behind SO_REUSEPORT (#154 scaling recipe): WAL takes
+  // concurrent readers plus one writer across processes, and this makes a
+  // writer wait for the lock instead of failing SQLITE_BUSY.
   sqlite3_exec(db,
-    "PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL;"
+    "PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL; PRAGMA busy_timeout=5000;"
     "PRAGMA cache_size=-2000; PRAGMA journal_size_limit=16777216;",
     0, 0, 0);
   sb_dbs[sb_db_count] = db;
@@ -103,6 +110,42 @@ static int sb_db_for(const char* path) {
   return sb_db_count++;
 }
 
+// #155 — a prepared-statement cache per database. Every binding op (KV, D1, DO
+// storage, queue, AE) funnels through sb_sql_run, which used to prepare and
+// finalize on every call — measured at ~0.6 ms/op, that compile step was most
+// of an op's cost. Keyed by exact SQL text; reset and re-bound on reuse.
+//
+// ponytail: FIFO eviction over 32 slots, linear scan, no lock (the runtime
+// serves one turn at a time). Move to LRU + a hash if a real app keeps >32 hot
+// statements per db, or if execution ever overlaps. Entries are never finalized
+// on shutdown — sb_db_for never closes a handle, the process owns it for life.
+#define SB_STMT_CACHE 32
+typedef struct { char* sql; sqlite3_stmt* st; } sb_cached_stmt;
+static sb_cached_stmt sb_stmt_cache[SB_MAX_DB][SB_STMT_CACHE];
+static int sb_stmt_fifo[SB_MAX_DB];
+
+static sqlite3_stmt* sb_stmt_get(int idx, sqlite3* db, const char* sql) {
+  sb_cached_stmt* slots = sb_stmt_cache[idx];
+  for (int i = 0; i < SB_STMT_CACHE; i++) {
+    if (slots[i].sql && strcmp(slots[i].sql, sql) == 0) {
+      sqlite3_reset(slots[i].st);
+      sqlite3_clear_bindings(slots[i].st);
+      return slots[i].st;
+    }
+  }
+  sqlite3_stmt* st = 0;
+  if (sqlite3_prepare_v2(db, sql, -1, &st, 0) != 0 || !st) return 0;
+  int slot = sb_stmt_fifo[idx];
+  sb_stmt_fifo[idx] = (slot + 1) % SB_STMT_CACHE;
+  if (slots[slot].st) sqlite3_finalize(slots[slot].st);
+  free(slots[slot].sql);
+  size_t n = strlen(sql);
+  slots[slot].sql = (char*)malloc(n + 1);
+  if (slots[slot].sql) memcpy(slots[slot].sql, sql, n + 1);
+  slots[slot].st = st;
+  return st;
+}
+
 // --- a growable output buffer, for building the reply JSON ------------------
 typedef struct { char* p; size_t len; size_t cap; } sb_buf;
 static void sb_buf_need(sb_buf* b, size_t extra) {
@@ -319,8 +362,8 @@ static char* sb_sql_run(const char* path, const char* sql, const char* params) {
   int idx = sb_db_for(path);
   if (idx < 0) { sb_puts(&b, "{\"ok\":false,\"error\":\"cannot open database\"}"); return b.p; }
   sqlite3* db = sb_dbs[idx];
-  sqlite3_stmt* st = 0;
-  if (sqlite3_prepare_v2(db, sql, -1, &st, 0) != 0 || !st) {
+  sqlite3_stmt* st = sb_stmt_get(idx, db, sql);
+  if (!st) {
     sb_puts(&b, "{\"ok\":false,\"error\":");
     const char* m = sqlite3_errmsg(db);
     sb_putjson(&b, m, strlen(m));
@@ -361,7 +404,9 @@ static char* sb_sql_run(const char* path, const char* sql, const char* params) {
   char tail[96];
   int k = snprintf(tail, 96, "],\"changes\":%d,\"rowid\":%lld}", sqlite3_changes(db), (long long)sqlite3_last_insert_rowid(db));
   sb_put(&b, tail, (size_t)k);
-  sqlite3_finalize(st);
+  // Reset, don't finalize: the statement stays compiled in sb_stmt_cache. Reset
+  // now (not just on next reuse) so a SELECT stops holding its read transaction.
+  sqlite3_reset(st);
   if (rc != SB_SQLITE_DONE && rc != SB_SQLITE_ROW) {
     free(b.p);
     sb_buf e = { 0, 0, 0 };
@@ -374,6 +419,67 @@ static char* sb_sql_run(const char* path, const char* sql, const char* params) {
   return b.p;
 }
 
+// #164 — an online, consistent single-file snapshot of a database, via
+// VACUUM INTO. Runs against the live db with no downtime (SQLite holds a read
+// transaction for the copy) and writes a fresh, defragmented file with no WAL
+// sidecars — exactly what you copy off the box. The copy is then reopened and
+// PRAGMA integrity_check'd, so a bad backup fails here, not on restore.
+// Returns {"ok":true,"bytes":n} or {"ok":false,"error":"..."}.
+static char* sb_sql_backup(const char* src_path, const char* dest_path) {
+  sb_buf b = { 0, 0, 0 };
+  int idx = sb_db_for(src_path);
+  if (idx < 0) { sb_puts(&b, "{\"ok\":false,\"error\":\"cannot open database\"}"); return b.p; }
+  sqlite3* db = sb_dbs[idx];
+
+  sb_mkdirs(dest_path);
+  unlink(dest_path); // VACUUM INTO refuses to overwrite an existing file
+
+  sqlite3_stmt* st = 0;
+  if (sqlite3_prepare_v2(db, "VACUUM INTO ?1", -1, &st, 0) != 0 || !st) {
+    sb_puts(&b, "{\"ok\":false,\"error\":");
+    const char* m = sqlite3_errmsg(db);
+    sb_putjson(&b, m, strlen(m));
+    sb_puts(&b, "}");
+    return b.p;
+  }
+  sqlite3_bind_text(st, 1, dest_path, -1, SB_SQLITE_TRANSIENT);
+  int rc = sqlite3_step(st);
+  sqlite3_finalize(st);
+  if (rc != SB_SQLITE_DONE) {
+    sb_puts(&b, "{\"ok\":false,\"error\":");
+    const char* m = sqlite3_errmsg(db);
+    sb_putjson(&b, m, strlen(m));
+    sb_puts(&b, "}");
+    return b.p;
+  }
+
+  sqlite3* chk = 0;
+  int ok = 0;
+  if (sqlite3_open(dest_path, &chk) == 0 && chk) {
+    sqlite3_stmt* cs = 0;
+    if (sqlite3_prepare_v2(chk, "PRAGMA integrity_check", -1, &cs, 0) == 0 && cs) {
+      if (sqlite3_step(cs) == SB_SQLITE_ROW) {
+        const unsigned char* r = sqlite3_column_text(cs, 0);
+        ok = r && strcmp((const char*)r, "ok") == 0;
+      }
+      sqlite3_finalize(cs);
+    }
+  }
+  if (chk) sqlite3_close(chk);
+  if (!ok) {
+    unlink(dest_path);
+    sb_puts(&b, "{\"ok\":false,\"error\":\"integrity check failed on the backup\"}");
+    return b.p;
+  }
+
+  struct stat sbuf;
+  long long bytes = stat(dest_path, &sbuf) == 0 ? (long long)sbuf.st_size : -1;
+  char head[64];
+  int k = snprintf(head, sizeof(head), "{\"ok\":true,\"bytes\":%lld}", bytes);
+  sb_put(&b, head, (size_t)k);
+  return b.p;
+}
+
 // --- outbound HTTP + HTTPS ---------------------------------------------------
 // Plain sockets for http, BearSSL for https, with the Mozilla root set compiled
 // in (see src/bearssl.ts). Both directions share the request builder and the
@@ -894,6 +1000,33 @@ function __sbSqlScriptRaw(path, sql) {
   return res;
 }
 
+// #164 — VACUUM INTO a fresh file. Two strings in, JSON out. Same pattern as
+// __sbSqlScriptRaw.
+// oxlint-disable-next-line no-unused-vars -- read inside the RawC block below, not by JS.
+function __sbD1BackupRaw(src, dest) {
+  let res = "";
+  // oxlint-disable-next-line no-unused-expressions -- Porffor.c`...` is inline C the compiler consumes, not a JS expression.
+  Porffor.c`
+    const char* __s; size_t __sl; char* __so = 0;
+    porf_native_fetch_read_value(src, &__s, &__sl, &__so);
+    char* __src = (char*)malloc(__sl + 1); memcpy(__src, __s, __sl); __src[__sl] = 0;
+    if (__so) free(__so);
+
+    const char* __d; size_t __dl; char* __do = 0;
+    porf_native_fetch_read_value(dest, &__d, &__dl, &__do);
+    char* __dest = (char*)malloc(__dl + 1); memcpy(__dest, __d, __dl); __dest[__dl] = 0;
+    if (__do) free(__do);
+
+    char* __out = sb_sql_backup(__src, __dest);
+    free(__src); free(__dest);
+    if (__out) {
+      res = porf_box((f64)porf_native_fetch_alloc_bytestring(__out, strlen(__out)), 195);
+      free(__out);
+    }
+  `;
+  return res;
+}
+
 // Outbound HTTP. String params so C can read each directly; the JS side has
 // already split the URL and enforced the allowlist. `tlsFlag` is "1" or "0" —
 // a string like the rest, so the marshalling stays uniform.
@@ -1051,6 +1184,10 @@ function __sbEnsureSchema() {
     s,
     "CREATE TABLE IF NOT EXISTS ae (dataset TEXT NOT NULL, ts INTEGER NOT NULL, indexes_json TEXT NOT NULL, blobs_json TEXT NOT NULL, doubles_json TEXT NOT NULL)",
   );
+  __sbSql(
+    s,
+    "CREATE TABLE IF NOT EXISTS ratelimit (name TEXT NOT NULL, key TEXT NOT NULL, window_start INTEGER NOT NULL, count INTEGER NOT NULL, PRIMARY KEY (name, key))",
+  );
 }
 
 function __sbHex(n) {
@@ -1199,6 +1336,20 @@ function __sbEmbeddedDispatch(msg) {
     return { ok: true, results: one.results, meta: one.meta, success: true };
   }
 
+  if (op === "d1.backup") {
+    const src = __sbD1Path(String(msg.db));
+    // A caller-supplied name must be a plain basename; anything else falls back
+    // to the timestamped default, so nothing can climb out of backups/.
+    const given = String(msg.name || "");
+    const name = /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(given)
+      ? given
+      : String(msg.db) + "-" + new Date().toISOString().replace(/[:.]/g, "-") + ".sqlite";
+    const dest = __sbDir() + "/backups/" + name;
+    const reply = JSON.parse(__sbD1BackupRaw(src, dest));
+    if (reply.ok === false) throw new Error("d1 backup: " + reply.error);
+    return { ok: true, path: dest, bytes: reply.bytes };
+  }
+
   if (op === "r2.put") {
     const body = String(msg.body == null ? "" : msg.body);
     const etag = __sbHex(16);
@@ -1371,6 +1522,26 @@ function __sbEmbeddedDispatch(msg) {
     return { ok: true, count: total.rows.length ? Number(total.rows[0][0]) : 0, rows };
   }
 
+  if (op === "ratelimit.check") {
+    // #69 — fixed window. limit/period come in the message (the transport holds
+    // no config). One upsert: same window -> count+1, new window -> reset to 1.
+    // ponytail: fixed window, so a burst straddling the boundary can briefly
+    // reach ~2x limit. Swap for a two-window weighted count if that matters.
+    const limit = Math.max(Number(msg.limit) || 1, 1);
+    const period = Math.max(Number(msg.period) || 60, 1);
+    const now = Math.floor(Date.now() / 1000);
+    const windowStart = now - (now % period);
+    const r = __sbSql(
+      store,
+      "INSERT INTO ratelimit (name, key, window_start, count) VALUES (?1, ?2, ?3, 1) " +
+        "ON CONFLICT (name, key) DO UPDATE SET count = CASE WHEN window_start = ?3 THEN count + 1 ELSE 1 END, " +
+        "window_start = ?3 RETURNING count",
+      [String(msg.name), String(msg.key == null ? "" : msg.key), windowStart],
+    );
+    const count = r.rows.length ? Number(r.rows[0][0]) : 1;
+    return { ok: true, success: count <= limit };
+  }
+
   throw new Error("unknown op: " + op);
 }
 

package/src/wrap.ts

@@ -65,6 +65,9 @@ export type Bindings = {
    *  it resolves to is a runtime input, not part of the artifact. */
   services: Array<{ binding: string; service: string }>;
   crons: string[];
+  /** #69 — rate limiters: `env.<binding>.limit({ key }) -> { success }`, a
+   *  fixed window of `limit` calls per `period` seconds, per key. */
+  ratelimiters: Array<{ binding: string; limit: number; period: number }>;
   /** Static-asset binding name for `env.<NAME>.fetch(request)`; `""` when assets are edge-only. */
   assets: string;
 };
@@ -80,6 +83,7 @@ export const EMPTY_BINDINGS: Bindings = {
   do: [],
   services: [],
   crons: [],
+  ratelimiters: [],
   assets: "",
 };
 
@@ -94,6 +98,7 @@ function hasBindings(b: Bindings): boolean {
     b.analytics.length > 0 ||
     b.do.length > 0 ||
     b.services.length > 0 ||
+    b.ratelimiters.length > 0 ||
     b.assets !== ""
   );
 }
@@ -251,6 +256,15 @@ export function readBindingsFromEnv(): Bindings {
       }
     }
   }
+  const isCount = (v: VarsJson): v is number => Number(v) === v && Number.isInteger(v) && v >= 1;
+  const ratelimiters: Array<{ binding: string; limit: number; period: number }> = [];
+  if (Array.isArray(parsed.ratelimiters)) {
+    for (const entry of parsed.ratelimiters) {
+      if (isVarsObject(entry) && isVarsString(entry.binding) && isCount(entry.limit) && isCount(entry.period)) {
+        ratelimiters.push({ binding: entry.binding, limit: entry.limit, period: entry.period });
+      }
+    }
+  }
   return {
     kv: strings(parsed.kv),
     secrets: strings(parsed.secrets),
@@ -262,6 +276,7 @@ export function readBindingsFromEnv(): Bindings {
     do: dos,
     services,
     crons: strings(parsed.crons),
+    ratelimiters,
     assets: isVarsString(parsed.assets) ? parsed.assets : "",
   };
 }