hyperpolymath · hyperpolymath · May 27, 2026
diff --git a/lib/codegen_deno.ml b/lib/codegen_deno.ml
@@ -206,6 +206,92 @@ const __as_httpFetch = async (url, method, headers, bodyOpt) => {
     body: text,
   };
 };
+// ---- Crypto (stdlib/Crypto.affine — HMAC-SHA256, RS256, base64url) ----
+// All shims go through `globalThis.crypto.subtle` so they run unmodified
+// on Deno, Node 18+, and browser ESM. The hex/base64url helpers are
+// pure JS (no crypto.subtle dependency); harnesses can stub them
+// independently of the SubtleCrypto surface.
+const __as_hexToBytes = (hex) => {
+  if (typeof hex !== "string" || hex.length % 2 !== 0) return null;
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    const b = parseInt(hex.substr(i * 2, 2), 16);
+    if (Number.isNaN(b)) return null;
+    out[i] = b;
+  }
+  return out;
+};
+const __as_b64uFromBytes = (bytes) => {
+  let s = "";
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+  return btoa(s).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+};
+const __as_b64uToBytes = (s) => {
+  const padded = s.replaceAll("-", "+").replaceAll("_", "/") +
+    "==".slice(0, (4 - (s.length % 4)) % 4);
+  const bin = atob(padded);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+};
+const __as_b64uEncodeString = (s) => __as_b64uFromBytes(
+  new TextEncoder().encode(String(s))
+);
+const __as_hmacSha256Verify = async (secret, body, sigHex) => {
+  const sig = __as_hexToBytes(sigHex);
+  if (sig === null) return false;
+  const enc = new TextEncoder();
+  const key = await globalThis.crypto.subtle.importKey(
+    "raw",
+    enc.encode(String(secret)),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"],
+  );
+  return await globalThis.crypto.subtle.verify(
+    "HMAC",
+    key,
+    sig,
+    enc.encode(String(body)),
+  );
+};
+// PEM -> Uint8Array (strip header/footer + base64 body decode). Accepts
+// `-----BEGIN PRIVATE KEY-----` (PKCS#8); a PKCS#1 key (`BEGIN RSA
+// PRIVATE KEY`) is rejected here so the failure is loud at the boundary
+// rather than as an opaque "unsupported key" deep inside subtle.importKey.
+const __as_pkcs8PemToBytes = (pem) => {
+  const s = String(pem);
+  if (!s.includes("-----BEGIN PRIVATE KEY-----")) {
+    throw new Error(
+      "rs256_sign: expected PKCS#8 PEM (-----BEGIN PRIVATE KEY-----). " +
+        "Convert PKCS#1 with `openssl pkcs8 -topk8 -nocrypt`.",
+    );
+  }
+  const body = s
+    .replace(/-----BEGIN PRIVATE KEY-----/g, "")
+    .replace(/-----END PRIVATE KEY-----/g, "")
+    .replace(/\s+/g, "");
+  const bin = atob(body);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+};
+const __as_rs256Sign = async (pkcs8Pem, payload) => {
+  const keyBytes = __as_pkcs8PemToBytes(pkcs8Pem);
+  const key = await globalThis.crypto.subtle.importKey(
+    "pkcs8",
+    keyBytes,
+    { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await globalThis.crypto.subtle.sign(
+    "RSASSA-PKCS1-v1_5",
+    key,
+    new TextEncoder().encode(String(payload)),
+  );
+  return new Uint8Array(sig);
+};
 // ---- end runtime ----
 
 |}
@@ -299,7 +385,23 @@ let () =
      (see {!fd_is_async}). *)
   b "http_request" (fun a ->
     Printf.sprintf "(await __as_httpFetch(%s, %s, %s, %s))"
-      (arg 0 a) (arg 1 a) (arg 2 a) (arg 3 a))
+      (arg 0 a) (arg 1 a) (arg 2 a) (arg 3 a));
+  (* ---- Crypto (stdlib/Crypto.affine) ----
+     `hmac_sha256_verify` / `rs256_sign` are `/ Async` so the emitted
+     call is wrapped in `await` (same shape as `http_request`). The
+     base64url helpers are pure (no effect) so they lower as plain
+     expressions. *)
+  b "hmac_sha256_verify" (fun a ->
+    Printf.sprintf "(await __as_hmacSha256Verify(%s, %s, %s))"
+      (arg 0 a) (arg 1 a) (arg 2 a));
+  b "rs256_sign" (fun a ->
+    Printf.sprintf "(await __as_rs256Sign(%s, %s))" (arg 0 a) (arg 1 a));
+  b "base64url_encode_string" (fun a ->
+    Printf.sprintf "__as_b64uEncodeString(%s)" (arg 0 a));
+  b "base64url_encode_bytes" (fun a ->
+    Printf.sprintf "__as_b64uFromBytes(%s)" (arg 0 a));
+  b "base64url_decode" (fun a ->
+    Printf.sprintf "__as_b64uToBytes(%s)" (arg 0 a))
 
 (* ============================================================================
    Identifier sanitisation (JS reserved words -> trailing underscore)

diff --git a/stdlib/Crypto.affine b/stdlib/Crypto.affine
@@ -1,11 +1,59 @@
 // SPDX-License-Identifier: MPL-2.0
 // Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
 //
-// Crypto.affine — extern bindings for crypto primitives and wall-clock time.
-// The Node-CJS shim wraps Node's built-in node:crypto and Date.now().
+// Crypto.affine — host bindings for crypto primitives and wall-clock time.
+//
+// Lowered by lib/codegen_deno.ml. The Web Crypto SubtleCrypto surface is
+// async, so the HMAC verify and RS256 sign primitives carry the `Async`
+// effect; callers compile to `async function` and the call site receives
+// an awaited result (mirroring the Http.affine pattern, ADR-013).
+//
+// `hmac_sha256_verify` uses `crypto.subtle.verify`, which is implemented
+// in constant time by spec — do not replace with a `compare(hex_a, hex_b)`
+// shape, as constant-time hex compare is the user's responsibility and is
+// easy to get wrong. The signature input is the lowercase-hex digest as
+// GitHub delivers it in `X-Hub-Signature-256` (after the `sha256=` prefix
+// is stripped by the caller).
+//
+// `rs256_sign` takes a PEM-encoded PKCS#8 private key — the format
+// produced by `openssl pkcs8 -topk8 -nocrypt`. GitHub Apps download keys
+// in PKCS#1; the conversion is documented in
+// `oikos/docs/GITHUB_APP_SETUP.md`. Returns the raw signature bytes;
+// callers typically pass it through `base64url_encode_bytes` for JWT
+// assembly.
 
 module Crypto;
 
+use Deno::{Bytes};
+
+// ── Existing (pre-2026-05) ──────────────────────────────────────────
 pub extern fn random_string(n: Int) -> String;
 pub extern fn random_f64() -> Float;
 pub extern fn time_ms() -> Int;
+
+// ── HMAC-SHA256 ─────────────────────────────────────────────────────
+//
+// Constant-time verification of an HMAC-SHA256 signature.
+// `signature_hex` is the lowercase-hex digest. Returns false on any
+// error (malformed hex, length mismatch, signature mismatch) —
+// fail-closed.
+pub extern fn hmac_sha256_verify(secret: String,
+                                  body: String,
+                                  signature_hex: String) -> Bool / Async;
+
+// ── RS256 / RSASSA-PKCS1-v1_5 over SHA-256 ──────────────────────────
+//
+// Sign `payload` (UTF-8 bytes) with the PKCS#8 RSA private key in
+// `pkcs8_pem`. Returns the raw signature bytes. Throws (via Web
+// Crypto's own surface) on a malformed key — defensible behaviour, the
+// bot should not be running with a broken key.
+pub extern fn rs256_sign(pkcs8_pem: String,
+                          payload: String) -> Bytes / Async;
+
+// ── Base64URL (RFC 4648 §5, no padding) ──────────────────────────────
+//
+// JWT and OAuth2 token formats are base64url, not base64. These match
+// the JOSE base64url-encode (`=` stripped, `+` -> `-`, `/` -> `_`).
+pub extern fn base64url_encode_string(s: String) -> String;
+pub extern fn base64url_encode_bytes(b: Bytes) -> String;
+pub extern fn base64url_decode(s: String) -> Bytes;
diff --git a/tests/codegen-deno/crypto_primitives.affine b/tests/codegen-deno/crypto_primitives.affine
@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: MPL-2.0
+// crypto-stdlib-2026-05 — HMAC-SHA256, RS256, base64url end-to-end on the
+// Deno-ESM backend. Exercises stdlib/Crypto.affine + the lowering rules
+// added to lib/codegen_deno.ml.
+//
+// The harness (crypto_primitives.harness.mjs) stubs `globalThis.crypto`
+// so the assertions are deterministic and the test stays offline.
+
+use Crypto::{hmac_sha256_verify, rs256_sign, base64url_encode_string, base64url_encode_bytes, base64url_decode};
+
+// HMAC-SHA256 verify — both the happy path and the fail-closed return.
+pub fn verify_ok(secret: String, body: String, sig: String) -> Bool / Async {
+  hmac_sha256_verify(secret, body, sig)
+}
+
+// RS256 sign returns Bytes; we round-trip through base64url so the harness
+// can assert on a string (Bytes cross the boundary as Uint8Array, but the
+// harness side checks the b64u-encoded shape — easier to read).
+pub fn sign_b64u(pem: String, payload: String) -> String / Async {
+  base64url_encode_bytes(rs256_sign(pem, payload))
+}
+
+// Pure (no Async, no Net) — base64url encode/decode round-trip.
+pub fn b64u_encode(s: String) -> String {
+  base64url_encode_string(s)
+}
+
+pub fn b64u_decode_roundtrip(s: String) -> String / Async {
+  // decode -> bytes -> re-encode through bytes path, to exercise both
+  // string and bytes encoders. The .harness asserts the round-trip.
+  base64url_encode_bytes(base64url_decode(s))
+}
diff --git a/tests/codegen-deno/crypto_primitives.harness.mjs b/tests/codegen-deno/crypto_primitives.harness.mjs
@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: MPL-2.0
+// crypto-stdlib-2026-05 — Node-ESM harness for crypto_primitives.affine.
+//
+// Strategy: stub `globalThis.crypto.subtle.{importKey,verify,sign}` so the
+// HMAC + RS256 lowerings have a deterministic surface, then assert that
+// the AffineScript-side calls thread arguments through correctly and
+// observe both the happy path and the fail-closed return.
+
+import assert from "node:assert/strict";
+
+// ── crypto.subtle stub ──────────────────────────────────────────────
+let importedKeys = [];
+let lastVerify = null;
+let lastSign = null;
+
+// Node 20 exposes `globalThis.crypto` as a read-only getter, so we
+// install our stub via `defineProperty` rather than direct assignment.
+Object.defineProperty(globalThis, "crypto", {
+  value: {
+    subtle: {
+      importKey: async (format, keyData, algorithm, extractable, usages) => {
+        const handle = {
+          _id: importedKeys.length,
+          format,
+          keyData,
+          algorithm,
+          extractable,
+          usages,
+        };
+        importedKeys.push(handle);
+        return handle;
+      },
+      // HMAC verify — the AffineScript-level `hmac_sha256_verify` shim
+      // converts hex -> Uint8Array before calling us, so what arrives
+      // here is bytes. Decide truth by a sentinel byte at the head.
+      verify: async (algorithm, key, signature, data) => {
+        lastVerify = {
+          algorithm,
+          key,
+          signatureBytes: Array.from(signature),
+          dataText: new TextDecoder().decode(data),
+        };
+        // Sentinel: a signature whose first byte is 0xAA verifies true.
+        return signature[0] === 0xaa;
+      },
+      // RS256 sign — return a deterministic 256-byte buffer so we can
+      // assert on the base64url encoding length.
+      sign: async (algorithm, key, data) => {
+        lastSign = {
+          algorithm,
+          key,
+          dataText: new TextDecoder().decode(data),
+        };
+        const out = new Uint8Array(256);
+        out[0] = 0x42;
+        out[255] = 0xbe;
+        return out.buffer;
+      },
+    },
+  },
+  writable: true,
+  configurable: true,
+});
+
+// ── Load the compiled module ────────────────────────────────────────
+const {
+  verify_ok,
+  sign_b64u,
+  b64u_encode,
+  b64u_decode_roundtrip,
+} = await import("./crypto_primitives.deno.js");
+
+// ── HMAC-SHA256 verify ──────────────────────────────────────────────
+// Happy path: signature hex starting with `aa` -> stub returns true.
+assert.equal(
+  await verify_ok("topsecret", "the body", "aa".repeat(32)),
+  true,
+  "hmac verify happy path returns true",
+);
+assert.equal(lastVerify.algorithm, "HMAC", "verify algorithm = HMAC");
+assert.equal(lastVerify.dataText, "the body", "verify body threaded through");
+assert.equal(
+  lastVerify.signatureBytes.length,
+  32,
+  "signature decoded to 32 bytes (64 hex chars)",
+);
+assert.equal(lastVerify.signatureBytes[0], 0xaa, "first byte is 0xAA");
+
+// Wrong-key path: stub returns false because first byte is 0xBB.
+assert.equal(
+  await verify_ok("topsecret", "the body", "bb".repeat(32)),
+  false,
+  "hmac verify wrong-key path returns false",
+);
+
+// Fail-closed on malformed hex (odd length).
+assert.equal(
+  await verify_ok("topsecret", "the body", "abc"),
+  false,
+  "hmac verify rejects malformed hex without calling subtle",
+);
+
+// Fail-closed on non-hex characters.
+assert.equal(
+  await verify_ok("topsecret", "the body", "g".repeat(64)),
+  false,
+  "hmac verify rejects non-hex characters",
+);
+
+// ── RS256 sign ──────────────────────────────────────────────────────
+// Build a minimal PKCS#8 PEM. The shim only checks the header marker
+// and base64-decodes the body; it does NOT validate the DER, so a
+// trivial 1-byte body is sufficient for the test.
+const fakePem = [
+  "-----BEGIN PRIVATE KEY-----",
+  "AA==",
+  "-----END PRIVATE KEY-----",
+].join("\n");
+
+const sigB64u = await sign_b64u(fakePem, "header.payload");
+assert.equal(
+  typeof sigB64u,
+  "string",
+  "rs256_sign returns a string via base64url_encode_bytes",
+);
+// 256 bytes -> 342 chars base64url (no padding).
+assert.equal(sigB64u.length, 342, "256-byte signature encodes to 342 b64u chars");
+assert.equal(sigB64u.startsWith("Qg"), true, "first byte 0x42 -> b64u 'Qg'");
+assert.equal(
+  lastSign.algorithm,
+  "RSASSA-PKCS1-v1_5",
+  "rs256_sign algorithm threaded",
+);
+assert.equal(lastSign.dataText, "header.payload", "rs256_sign payload threaded");
+
+// Loud failure on PKCS#1 (rejected at the boundary).
+await assert.rejects(
+  () =>
+    sign_b64u(
+      ["-----BEGIN RSA PRIVATE KEY-----", "AA==", "-----END RSA PRIVATE KEY-----"]
+        .join("\n"),
+      "x",
+    ),
+  /PKCS#8/,
+  "rs256_sign rejects PKCS#1 with a clear message",
+);
+
+// ── base64url ───────────────────────────────────────────────────────
+// JWT header example — known fixture, easy to verify by eye.
+assert.equal(
+  b64u_encode(`{"alg":"RS256","typ":"JWT"}`),
+  "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9",
+  "b64u_encode matches the canonical JWT header encoding",
+);
+
+// `+` / `/` => `-` / `_`. The string ">>>>" encodes to "Pj4+Pg==" in
+// stock base64 — verify the b64u rewrites and strip padding.
+assert.equal(b64u_encode(">>>>"), "Pj4-Pg", "b64u uses '-'/'_' and strips padding");
+
+// Round-trip a non-aligned-length input.
+assert.equal(
+  await b64u_decode_roundtrip("SGVsbG8"),
+  "SGVsbG8",
+  "b64u decode/encode round-trips a 7-char string",
+);
+
+console.log("crypto_primitives.harness.mjs OK");