@sproutboat/runtime 0.37.1 → 0.38.0

package/src/subtle/README.md

@@ -0,0 +1,62 @@
+# crypto.subtle, native half
+
+`crypto.subtle` follows workerd's surface from compatibility date `__SB_SUBTLE_DATE` (a
+placeholder constant at the top of the new block in `native-fetch-prelude.js`). The JavaScript
+side (key objects, algorithm and usage checks, JWK, DOMException names) lives in the prelude;
+this directory is the C it calls.
+
+## Where the primitives come from
+
+Nothing here implements a primitive. The rule is that anything with a vetted C implementation
+uses it.
+
+| Need | Source | Licence |
+| --- | --- | --- |
+| SHA-1/256/384/512, HMAC, HKDF | BearSSL 0.6 | MIT |
+| RSA (private and public operations, key generation, PKCS#1 v1.5 padding), RSA-OAEP | BearSSL 0.6 | MIT |
+| ECDSA and ECDH on P-256, P-384, P-521, EC key generation | BearSSL 0.6 | MIT |
+| AES (constant-time), CBC, CTR, GCM | BearSSL 0.6 | MIT |
+| Ed25519, X25519 | Monocypher 4.0.2, vendored in `vendor/` | BSD-2-Clause or CC0-1.0 |
+
+BearSSL is already linked into every embedded sprout (standalone binaries and sproutd) for
+TLS, so this adds no dependency there. It has no Ed25519 or X25519 signing, which is why
+Monocypher is vendored: one small library, audited (Cure53, 2017), written for constant time,
+public domain or BSD. The two `.c` files and two headers are verbatim from the 4.0.2 release
+(sha256 of the tarball `38d07179738c0c90677dba3ceb7a7b8496bcfea758ba1a53e803fed30ae0879c`);
+`assemble.ts` wraps each in preprocessor aliases so none of its short names (`u8`, `fe`, `FOR`,
+`MIN`) leak into the shared translation unit.
+
+What is written here is composition and checking, each of it tested against BoringSSL (Bun's
+WebCrypto) in `subtle.test.ts`:
+
+- RSASSA-PSS encoding and verification (EMSA-PSS with MGF1), since BearSSL has the RSA
+  primitive but no PSS.
+- PBKDF2 (RFC 8018) over BearSSL's HMAC.
+- The DER for SPKI and PKCS#8, and the PKCS#8 RSA reader. BearSSL's own PKCS#8 decoder
+  recomputes the public exponent and fails for primes that are 1 mod 4, which OpenSSL and
+  BoringSSL keys often have, so the structure is read directly and BearSSL gets the CRT parts.
+- Argument and point validation (an EC public point is accepted only if it is on the curve).
+
+## Constant time
+
+Secret-dependent work is BearSSL's (RSA private exponentiation, ECDSA signing, AES) and
+Monocypher's (Ed25519 signing, X25519), which are written for constant time. Comparisons of
+MACs and signatures use a constant-time compare. Verification of public data (RSA, ECDSA,
+PSS check) is not secret-dependent. ECDSA signatures are deterministic (RFC 6979, BearSSL's
+HMAC-DRBG), which WebCrypto permits.
+
+## Layout
+
+- `subtle.c`: the C; one entry point, `sbc_op`.
+- `vendor/`: Monocypher, verbatim, with its licence.
+- `assemble.ts`: builds the block that is spliced into `transport-embedded.js` between the
+  `SUBTLE:BEGIN` and `SUBTLE:END` markers. Run `bun run gen:subtle` in `packages/runtime` after
+  editing `subtle.c`.
+- `driver.c`, `subtle.test.ts`: compile the same C with the host `cc` and BearSSL from the CLI
+  cache, and compare with Bun's WebCrypto.
+
+## Transports
+
+Only the embedded transport has BearSSL and Monocypher. On the broker transport
+`__sbSubtleRaw` returns an empty string and the prelude throws `NotSupportedError` for
+anything that needs the native half (HMAC and digest never do).

package/src/subtle/assemble.ts

@@ -0,0 +1,152 @@
+// Builds the C that crypto.subtle compiles into an embedded sprout: Monocypher (vendored verbatim in
+// vendor/) plus subtle.c, adapted for the one place it is compiled.
+//
+// Porffor splits inline C into a shared header and per-unit implementation files, and the splitter
+// is a small scanner, not a C parser. Three things follow, and this file handles each:
+//   - A comment that opens a top-level chunk makes the chunk look like a variable and breaks the
+//     split, so every comment is removed (the licence travels in vendor/ and the README).
+//   - A top-level non-const static function becomes a global symbol in its unit, so every file-scope
+//     name Monocypher declares static is aliased to a prefixed one by the preprocessor, for the span
+//     of the file. Its short typedef names (u8, fe) and macros (FOR, MIN) are aliased or undefined
+//     the same way, so none of them reaches the rest of the translation unit, which also holds
+//     Porffor's generated code and SQLite glue.
+//   - Preprocessor lines are copied to both halves in order, so the aliases hold on both sides.
+import { readFileSync, writeFileSync } from "node:fs";
+
+const here = (name: string) => new URL(name, import.meta.url);
+const read = (name: string) => readFileSync(here(name), "utf8");
+
+/** Monocypher's internal typedef names. Each is aliased by the preprocessor across the whole block. */
+const INTERNAL_NAMES = ["i8", "u8", "i16", "u32", "i32", "i64", "u64", "fe", "ge", "ge_cached", "ge_precomp", "blk"];
+
+export const SUBTLE_BEGIN =
+  "// SUBTLE:BEGIN (generated by `bun run gen:subtle`; edit src/subtle/subtle.c, not this block)";
+export const SUBTLE_END = "// SUBTLE:END";
+
+/** Removes C comments, leaving strings and character constants alone. */
+export function stripComments(source: string): string {
+  let out = "";
+  for (let i = 0; i < source.length;) {
+    const c = source[i];
+    if (c === '"' || c === "'") {
+      let j = i + 1;
+      while (source[j] !== c) j += source[j] === "\\" ? 2 : 1;
+      out += source.slice(i, j + 1);
+      i = j + 1;
+    } else if (c === "/" && source[i + 1] === "/") {
+      while (i < source.length && source[i] !== "\n") i++;
+    } else if (c === "/" && source[i + 1] === "*") {
+      i = source.indexOf("*/", i + 2) + 2;
+      out += " ";
+    } else {
+      out += c;
+      i++;
+    }
+  }
+  return out;
+}
+
+const tidy = (source: string) =>
+  stripComments(source)
+    .split("\n")
+    .map((line) => line.replace(/\s+$/, ""))
+    .filter((line, index, all) => line !== "" || (index > 0 && all[index - 1] !== ""))
+    .join("\n");
+
+export function assembleSubtleC(): string {
+  // The C++ guards (a namespace, extern "C") would swallow the rest of the block in the splitter.
+  const strip = (name: string) =>
+    tidy(read(name))
+      .replace(/^#include "monocypher[^"]*"\s*$/gm, "")
+      .replace(/^#ifdef (?:MONOCYPHER_CPP_NAMESPACE|__cplusplus)\n[\s\S]*?^#endif\n/gm, "");
+  // Each vendored .c file was written to be its own translation unit: its macros end with it, and
+  // its static names get a prefix of their own (both define `hash_reduce`, differently).
+  const unit = (name: string, index: number) => {
+    const body = strip(name);
+    const macros = [...new Set([...body.matchAll(/^#define\s+(\w+)/gm)].map((m) => m[1]))];
+    const statics = [
+      ...new Set([...body.matchAll(/^static\b([^;{(=]*?)\b(\w+)\s*(?:\(|\[|=|;)/gm)].map((m) => m[2])),
+    ].filter((n) => !INTERNAL_NAMES.includes(n));
+    return [
+      ...statics.map((n) => `#define ${n} sbm${index}_${n}`),
+      body,
+      ...macros.map((n) => `#undef ${n}`),
+      ...statics.map((n) => `#undef ${n}`),
+    ].join("\n");
+  };
+  const headers = ["vendor/monocypher.h", "vendor/monocypher-ed25519.h"].map(strip).join("\n");
+  const alias = INTERNAL_NAMES.map((n) => `#define ${n} sbm_${n}`).join("\n");
+  const unalias = INTERNAL_NAMES.map((n) => `#undef ${n}`).join("\n");
+  return [
+    "#include <bearssl.h>",
+    "// Monocypher 4.0.2 (BSD-2-Clause OR CC0-1.0), Loup Vaillant: vendor/monocypher*.[ch] without comments.",
+    alias,
+    headers,
+    unit("vendor/monocypher.c", 1),
+    unit("vendor/monocypher-ed25519.c", 2),
+    unalias,
+    "// End of Monocypher.",
+    tidy(read("subtle.c")),
+  ].join("\n");
+}
+
+/**
+ * One call into sbc_op. `op` is a decimal string; a, b, c, d are byte strings (latin1, one char per
+ * byte). Returns a byte string whose first byte is the status (0 ok, 1 DataError, 2 OperationError,
+ * 3 NotSupportedError) and whose rest is the result. Sits inside the markers so that pruning the
+ * block (wrap.ts, for a handler that never touches crypto.subtle) removes it with the C it calls.
+ */
+const SUBTLE_RAW = `// oxlint-disable-next-line no-unused-vars -- read inside the RawC block below, not by JS.
+function __sbSubtleRaw(op, a, b, c, d) {
+  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* __os; size_t __osl; char* __oso = 0;
+    porf_native_fetch_read_value(op, &__os, &__osl, &__oso);
+    char __ob[8]; size_t __ok = __osl < 7 ? __osl : 7;
+    memcpy(__ob, __os, __ok); __ob[__ok] = 0;
+    if (__oso) free(__oso);
+    int __op = atoi(__ob);
+
+    const char* __pa = ""; size_t __pal = 0; porf_native_fetch_read_raw_bytes(a, &__pa, &__pal);
+    const char* __pb = ""; size_t __pbl = 0; porf_native_fetch_read_raw_bytes(b, &__pb, &__pbl);
+    const char* __pc = ""; size_t __pcl = 0; porf_native_fetch_read_raw_bytes(c, &__pc, &__pcl);
+    const char* __pd = ""; size_t __pdl = 0; porf_native_fetch_read_raw_bytes(d, &__pd, &__pdl);
+    unsigned char* __res = 0; size_t __resl = 0;
+    int __rc = sbc_op(__op, (const unsigned char*)__pa, __pal, (const unsigned char*)__pb, __pbl,
+                      (const unsigned char*)__pc, __pcl, (const unsigned char*)__pd, __pdl, &__res, &__resl);
+    unsigned char* __w = (unsigned char*)malloc(__resl + 1);
+    if (__w) {
+      __w[0] = (unsigned char)__rc;
+      if (__resl) memcpy(__w + 1, __res, __resl);
+      out = porf_box((f64)porf_native_fetch_alloc_bytestring((const char*)__w, __resl + 1), 195);
+      free(__w);
+    }
+    free(__res);
+  \`;
+  return out;
+}
+`;
+
+/** The prelude with the generated block (re)written between its markers. */
+export function spliceSubtle(prelude: string): string {
+  const start = prelude.indexOf(SUBTLE_BEGIN);
+  const end = prelude.indexOf(SUBTLE_END);
+  if (start < 0 || end < start) throw new Error("native-fetch-prelude.js has no SUBTLE markers");
+  const block = assembleSubtleC();
+  if (/`|\$\{/.test(block)) throw new Error("subtle C contains a backtick or ${: it is spliced into a JS template");
+  return (
+    prelude.slice(0, start) +
+    SUBTLE_BEGIN +
+    "\n// oxlint-disable-next-line no-unused-expressions -- Porffor.c`...` is inline C the compiler consumes, not a JS expression.\nPorffor.c`\n" +
+    block +
+    "\n`;\n" +
+    SUBTLE_RAW +
+    prelude.slice(end)
+  );
+}
+
+if (import.meta.main) {
+  const path = new URL("../native-fetch-prelude.js", import.meta.url);
+  writeFileSync(path, spliceSubtle(readFileSync(path, "utf8")));
+}

package/src/subtle/driver.c

@@ -0,0 +1,33 @@
+/* Test driver for subtle.c: reads "op a b c d" lines (hex, "-" for empty), prints "rc hex". */
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <fcntl.h>
+#include <unistd.h>
+#include <stdint.h>
+#include <bearssl.h>
+#include "assembled.c"
+
+static unsigned char* unhex(const char* s, size_t* n) {
+  if (!strcmp(s, "-")) { *n = 0; return (unsigned char*)calloc(1, 1); }
+  size_t l = strlen(s) / 2; unsigned char* o = (unsigned char*)malloc(l + 1);
+  for (size_t i = 0; i < l; i++) { unsigned v; sscanf(s + 2 * i, "%2x", &v); o[i] = (unsigned char)v; }
+  *n = l; return o;
+}
+int main(void) {
+  static char line[1 << 20];
+  while (fgets(line, sizeof line, stdin)) {
+    char* t[5]; int k = 0;
+    for (char* p = strtok(line, " \n"); p && k < 5; p = strtok(0, " \n")) t[k++] = p;
+    if (k < 5) continue;
+    size_t l[4]; unsigned char* a[4];
+    for (int i = 0; i < 4; i++) a[i] = unhex(t[i + 1], &l[i]);
+    unsigned char* out; size_t ol;
+    int rc = sbc_op(atoi(t[0]), a[0], l[0], a[1], l[1], a[2], l[2], a[3], l[3], &out, &ol);
+    printf("%d ", rc);
+    for (size_t i = 0; i < ol; i++) printf("%02x", out[i]);
+    printf("\n"); fflush(stdout);
+    free(out); for (int i = 0; i < 4; i++) free(a[i]);
+  }
+  return 0;
+}

package/src/subtle/prune.test.ts

@@ -0,0 +1,53 @@
+import { expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { preludePath, pruneSubtle, wrapNativeFetchHandler } from "../wrap";
+
+const prelude = readFileSync(preludePath, "utf8");
+const handler = (body: string) => `export default { async fetch() { ${body} return new Response("x"); } };`;
+
+test("pruning removes the workerd-style crypto.subtle, its C and its glue, and nothing else", () => {
+  const pruned = pruneSubtle(prelude);
+  for (const gone of [
+    "__sbSubtleNext",
+    "__sbSubtleLegacy",
+    "SUBTLE:",
+    "const __SB_SUBTLE_DATE",
+    "sbc_op",
+    "crypto_ed25519_sign",
+    "__sbSubtleRaw",
+    "class DigestStream",
+  ])
+    expect(pruned).not.toContain(gone);
+  for (const kept of ["globalThis.crypto.subtle = {", "sb_sha256_block", "__sbHmacRaw"]) expect(pruned).toContain(kept);
+  expect(pruned.length).toBeLessThan(prelude.length - 150_000);
+  // What is left is still JavaScript.
+  new Bun.Transpiler().transformSync(pruned);
+});
+
+test("auto keeps the code for a handler that names crypto.subtle, DigestStream or CryptoKey", () => {
+  const wrap = (source: string, mode: "auto" | "always") =>
+    wrapNativeFetchHandler(
+      source,
+      prelude,
+      {},
+      undefined,
+      undefined,
+      "2026-11-06",
+      "app",
+      undefined,
+      "embedded",
+      undefined,
+      mode,
+    );
+  expect(wrap(handler("await crypto.subtle.digest('SHA-256', new Uint8Array(1));"), "auto")).toContain(
+    "__sbSubtleNext",
+  );
+  expect(wrap(handler("new crypto.DigestStream('SHA-1');"), "auto")).toContain("__sbSubtleNext");
+  expect(wrap(handler("if (k instanceof CryptoKey) {}"), "auto")).toContain("__sbSubtleNext");
+  expect(wrap(handler(""), "auto")).not.toContain("__sbSubtleNext");
+  expect(wrap(handler(""), "always")).toContain("__sbSubtleNext");
+});
+
+test("a prelude without the markers is an error, not a silent no-op", () => {
+  expect(() => pruneSubtle("function f() {}")).toThrow(/no \/\/ SUBTLE-JS:BEGIN/);
+});