@amritk/nish 0.13.0 → 0.14.0

package/runtime/shim.mjs

@@ -42,6 +42,7 @@
  * The rewrite rules that call these helpers are listed in docs/wp13-differential.md.
  */
 import child_process from "node:child_process";
+import { webcrypto } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 
@@ -91,6 +92,37 @@ export function bitsToF64(b) {
   return BITS.getFloat64(0);
 }
 
+/**
+ * `ctSelect` / `ctEq` (WP34 N6). A `u32` is a `number` here and a `u64` a
+ * BigInt, so the operands' kind picks the width, and a mix of the two — which
+ * the native checker refuses, and which a `u64` written as a bare literal is
+ * under an unrewritten run — throws the `TypeError` BigInt arithmetic throws
+ * rather than comparing a number with a BigInt and answering zero. JavaScript's
+ * `&` reads a `number` as a signed 32-bit integer, so each answer is put back in
+ * range with `>>> 0` or `asUintN(64, ...)`. These branch: only the native
+ * lowering promises constant time.
+ */
+function ctWide(name, first, second, third) {
+  const wide = typeof first === "bigint";
+  if ((typeof second === "bigint") !== wide || (typeof third === "bigint") !== wide) {
+    throw new TypeError(`${name}: cannot mix a u64 (BigInt) with a u32 (number)`);
+  }
+  return wide;
+}
+
+const U64_ONES = (1n << 64n) - 1n;
+
+export function ctSelect(mask, a, b) {
+  if (ctWide("ctSelect", mask, a, b)) return wrapU64((a & mask) | (b & ~mask));
+  return ((a & mask) | (b & ~mask)) >>> 0;
+}
+
+export function ctEq(a, b) {
+  // `ctEq` has two operands, so the second one stands in for the third.
+  if (ctWide("ctEq", a, b, b)) return wrapU64(a ^ b) === 0n ? U64_ONES : 0n;
+  return (a ^ b) === 0 ? 0xffffffff : 0;
+}
+
 /** Wrap a BigInt to the i64 range: every i64 `+ - * /` and unary minus goes through here. */
 export function wrapI64(x) {
   return BigInt.asIntN(64, x);
@@ -401,6 +433,28 @@ export function updIdx(a, i, f) {
   return v;
 }
 
+/**
+ * `dst.set(src, offset)` (WP34 N2): `TypedArray.prototype.set`'s copy on the
+ * plain array a `u8[]` is here. The source is copied first, so a self-copy or
+ * an overlapping one reads what was there before, as `memmove` does natively;
+ * a range past the end fails with the native panic and its words, where a
+ * typed array would throw a `RangeError` for the same offsets.
+ */
+export function arraySet(dst, src, offset) {
+  // `ToIntegerOrInfinity`: NaN is 0, as `llvm.fptosi.sat` makes it natively.
+  // `Math.trunc` rather than `toIndex`, which converts a bigint: an `i64` or
+  // `u64` offset is a bigint here, and it throws the `TypeError` the typed
+  // array and `Array.prototype.fill` throw for one, instead of being rounded
+  // to the nearest double past 2^53 (docs/RUN_UNDER_NODE.md).
+  const at = offset === undefined ? 0 : Math.trunc(offset) || 0;
+  const end = at + src.length;
+  if (!(at >= 0 && end <= dst.length)) panicSlice(at, end, dst.length);
+  // Two plain arrays overlap only when they are one array, which is the one
+  // case that must read the source before writing it.
+  const from = src === dst ? src.slice() : src;
+  for (let i = 0; i < from.length; i++) dst[at + i] = from[i];
+}
+
 /** `new Array<T>(n)`: `n` zero-filled elements (`0`, `0n`, or `false`). */
 export function newArray(n, zero) {
   return new Array(toIndex(n)).fill(zero);
@@ -434,6 +488,15 @@ export function readFileSyncOrNull(path) {
   }
 }
 
+/** `readFileBytesSync(path)` (WP34 N2): the bytes as a plain array of numbers, or null. */
+export function readFileBytesSync(path) {
+  try {
+    return Array.from(fs.readFileSync(path));
+  } catch {
+    return null;
+  }
+}
+
 export function writeFileSync(path, data) {
   try {
     fs.writeFileSync(path, data, "utf8");
@@ -618,6 +681,65 @@ export function monotonicNanos() {
   return process.hrtime.bigint();
 }
 
+// ---- The host (WP34 N3) ------------------------------------------------------
+
+/**
+ * `statMtimeSync(path)`: Node's `mtimeMs` for the path, or NaN when it cannot
+ * be stat'd, which is the native answer too. `mtimeMs` is the same arithmetic
+ * `runtime-host.c` does, so the two print the same digits, fraction and all.
+ */
+export function statMtimeSync(path) {
+  const st = fs.statSync(path, { throwIfNoEntry: false });
+  if (st === undefined) {
+    return Number.NaN;
+  }
+  return st.mtimeMs;
+}
+
+/**
+ * Node's own fill, taken before `runtime/nish.mjs` puts the one below in its
+ * place on the same object: `webcrypto` is the global `crypto`.
+ */
+const webRandom = webcrypto.getRandomValues.bind(webcrypto);
+
+/**
+ * `crypto.getRandomValues(bytes)` for the plain array a `u8[]` is here. Node's
+ * own takes only a typed array, so the bytes are drawn into one and copied
+ * across. More than 65,536 fails with the native panic and its words, where
+ * Node would throw a `QuotaExceededError`: the exit status is 1 either way. A
+ * typed array goes straight through.
+ */
+export function getRandomValues(bytes) {
+  if (!Array.isArray(bytes)) {
+    return webRandom(bytes);
+  }
+  if (bytes.length > 65536) {
+    panic(`crypto.getRandomValues: ${bytes.length} bytes asked for, and one call fills at most 65536`);
+  }
+  const drawn = webRandom(new Uint8Array(bytes.length));
+  for (let i = 0; i < drawn.length; i++) {
+    bytes[i] = drawn[i];
+  }
+  return bytes;
+}
+
+/**
+ * `signalFd()` and `readSignal(fd)` have no faithful reading under Node, and
+ * these say so rather than answer something else. Node delivers a signal to
+ * its event loop (`process.on("SIGTERM")`), and a blocking read keeps the loop
+ * from ever running, so no synchronous function here can learn that one
+ * arrived. docs/wp33-round-trip.md §3.5 has the row and the translation.
+ */
+export function signalFd() {
+  throw new Error(
+    "signalFd has no synchronous reading under Node: a signal reaches the event loop, which a blocking readSignal never returns to (docs/wp33-round-trip.md)"
+  );
+}
+
+export function readSignal() {
+  return signalFd();
+}
+
 /** `process.argv`: index 0 is the program (the script here, the executable natively), then the arguments. */
 export function argv() {
   return process.argv.slice(1);

package/scripts/build.sh

@@ -3,11 +3,12 @@
 #
 #   scripts/build.sh <module.ll> [more .ll/.c files...] -o <out> [--profile debug|speed|size|wasm]
 #
-# The C runtime is three translation units and is named as one: an input
+# The C runtime is four translation units and is named as one: an input
 # <dir>/runtime.c also compiles <dir>/runtime-os.c, the half that wraps the
 # system calls (files, directories, subprocesses, the environment, the clock),
-# and <dir>/runtime-parallel.c, the half that divides a range of work across
-# threads. Each of those files says why they are compiled and measured apart.
+# <dir>/runtime-parallel.c, the half that divides a range of work across
+# threads, and <dir>/runtime-host.c, the wall clock, entropy, file times and
+# signals. Each of those files says why they are compiled and measured apart.
 #
 # Profiles:
 #   debug  clang defaults: no optimisation, symbols kept. The "before" number.
@@ -83,9 +84,9 @@ done
 [ ${#inputs[@]} -gt 0 ] || { echo "error: no input files" >&2; exit 2; }
 [ -n "$out" ] || { echo "error: -o <out> is required" >&2; exit 2; }
 
-# The runtime is three translation units, and a caller names one: whoever passes
-# <dir>/runtime.c gets <dir>/runtime-os.c and <dir>/runtime-parallel.c compiled
-# beside it. They were one file until the operating-system half was split out
+# The runtime is four translation units, and a caller names one: whoever passes
+# <dir>/runtime.c gets <dir>/runtime-os.c, <dir>/runtime-parallel.c and
+# <dir>/runtime-host.c compiled beside it. They were one file until the operating-system half was split out
 # for its own size budget, and the parallel half followed for the same reason
 # (each file's header comment says why), and a link line is where those splits
 # would otherwise leak: `nish --link` builds its command line in
@@ -97,7 +98,7 @@ done
 for i in ${inputs[@]+"${inputs[@]}"}; do
   case "$i" in
     */runtime.c|runtime.c)
-      for half in runtime-os.c runtime-parallel.c; do
+      for half in runtime-os.c runtime-parallel.c runtime-host.c; do
         side="${i%runtime.c}$half"
         have=0
         for j in "${inputs[@]}"; do

package/scripts/gen-diagnostic-codes.mjs

@@ -25,10 +25,12 @@
  *
  *   - **Every number is well-formed and in its band.** `NL1xxx` Phase 0,
  *     `NL2xxx` the checker, `NL3xxx` the driver, `NL4xxx` the interop
- *     sidecars, `NL9xxx` a WP15 section 8 performance warning. Band 0 is not
- *     in the tables: `NL0000` (no rule matched), `NL0001` (a syntax error),
- *     `NL0002` (the toolchain) and `NL0003` (an internal error) are constants.
- *     A performance fragment is in `performanceRules` and nowhere else.
+ *     sidecars, `NL8xxx` a WP33 portability warning, `NL9xxx` a WP15 section
+ *     8 performance warning. Band 0 is not in the tables: `NL0000` (no rule
+ *     matched), `NL0001` (a syntax error), `NL0002` (the toolchain) and
+ *     `NL0003` (an internal error) are constants. A performance fragment is in
+ *     `performanceRules` and nowhere else, and a portability fragment is in
+ *     `portabilityRules` and nowhere else.
  *   - **Nothing is used twice.** A number handed out once is never handed to a
  *     different rule, and a retired rule keeps its entry -- it matches nothing,
  *     so carrying it costs a string -- precisely so that its number stays
@@ -48,7 +50,8 @@
  *     simply not a match. So each table's strings are counted on their own
  *     and have to come to twice its pairs ([#107](https://github.com/amritk/nish/issues/107)).
  *   - **The `NL9xxx` codes run from `NL9001` with no gap**, one per WP15
- *     section 8 rule, so a missing number is a rule that lost its code.
+ *     section 8 rule, so a missing number is a rule that lost its code; and
+ *     the `NL8xxx` codes run from `NL8001` the same way, one per WP33 row.
  *   - **`RULE_COUNT` is the number of entries.**
  *
  * A fragment is the longest literal run of its message's template -- the rule
@@ -68,11 +71,24 @@ const REGISTRY =
   process.argv.slice(2).find((arg) => !arg.startsWith("--")) ?? path.join(ROOT, "src", "codes.ts")
 
 /** The bands a table entry may use. Band 0 is constants, never a table row. */
-const BANDS = new Set(["1", "2", "3", "4", "9"])
+const BANDS = new Set(["1", "2", "3", "4", "8", "9"])
 
 /** Shorter than this, a fragment would match half the suite. */
 const MIN_FRAGMENT = 10
 
+/**
+ * The three tables, the band each warning table owns alone, and that warning
+ * class's name: a warning table holds only its band's codes and its band's
+ * codes live only there, because `codeFor` matches a warning's message against
+ * its own table and nothing else. `null` is the table of errors, which takes
+ * every other band.
+ */
+const TABLES = [
+  ["diagnosticRules", null, null],
+  ["portabilityRules", "8", "portability"],
+  ["performanceRules", "9", "performance"],
+]
+
 /**
  * The text of one table in `src/codes.ts`: from its `name = (): string[] => [`
  * to the `];` that closes it. Parsed per table, because the table a fragment
@@ -104,10 +120,7 @@ const inOrder = (a, b) => b.fragment.length - a.fragment.length || a.fragment.lo
 const problems = (text) => {
   const found = []
   const tables = []
-  for (const [name, perf] of [
-    ["diagnosticRules", false],
-    ["performanceRules", true],
-  ]) {
+  for (const [name, owns, kind] of TABLES) {
     const body = tableText(text, name)
     if (body === null) {
       found.push(`src/codes.ts has no \`${name}\` table`)
@@ -122,7 +135,7 @@ const problems = (text) => {
             "without its other half shifts every later pairing `codeFor` makes"
         )
       }
-      tables.push({ name, perf, pairs })
+      tables.push({ name, owns, kind, pairs })
     } catch (err) {
       found.push(err.message)
     }
@@ -139,18 +152,22 @@ const problems = (text) => {
     found.push(err.message)
   }
   if (whole.length !== all.length) {
-    found.push(`src/codes.ts holds ${whole.length} pairs, ${all.length} of them inside the two tables`)
+    found.push(`src/codes.ts holds ${whole.length} pairs, ${all.length} of them inside the three tables`)
   }
 
-  for (const { name, perf, pairs } of tables) {
+  const warningBands = TABLES.map(([, owns]) => owns).filter((band) => band !== null)
+  for (const { name, owns, pairs } of tables) {
     for (let i = 0; i < pairs.length; i++) {
       const { fragment, code } = pairs[i]
       const band = code[2]
       if (!BANDS.has(band)) {
-        found.push(`${code} is not in a table band (1, 2, 3, 4 or 9): ${JSON.stringify(fragment)}`)
+        found.push(`${code} is not in a table band (1, 2, 3, 4, 8 or 9): ${JSON.stringify(fragment)}`)
+      }
+      if (owns !== null && band !== owns) {
+        found.push(`${code} is in \`${name}\`, which holds only NL${owns}xxx codes`)
       }
-      if (perf !== (band === "9")) {
-        found.push(`${code} is in \`${name}\`, which holds ${perf ? "only" : "no"} NL9xxx codes`)
+      if (owns === null && warningBands.includes(band)) {
+        found.push(`${code} is in \`${name}\`, which holds no NL${band}xxx codes`)
       }
       if (fragment.trim().length < MIN_FRAGMENT) {
         found.push(`${code}'s fragment ${JSON.stringify(fragment)} is under ${MIN_FRAGMENT} characters`)
@@ -161,15 +178,20 @@ const problems = (text) => {
     }
   }
 
-  const perfCodes = tables
-    .filter((t) => t.perf)
-    .flatMap((t) => t.pairs.map((p) => Number(p.code.slice(3))))
-    .sort((a, b) => a - b)
-  const gap = perfCodes.findIndex((n, i) => n !== i + 1)
-  if (gap >= 0) {
-    found.push(
-      `\`performanceRules\` has no NL${9000 + gap + 1} in its place: its codes run from NL9001 with no gap`
-    )
+  // A warning band is gap-free from its first number, so a missing one is a
+  // rule that lost its code rather than a number nobody took yet.
+  for (const { name, owns, kind, pairs } of tables) {
+    if (owns === null) {
+      continue
+    }
+    const numbers = pairs.map((p) => Number(p.code.slice(3))).sort((a, b) => a - b)
+    const gap = numbers.findIndex((n, i) => n !== i + 1)
+    if (gap >= 0) {
+      const base = Number(owns) * 1000
+      found.push(
+        `\`${name}\` has no NL${base + gap + 1} in its place: its ${kind} codes run from NL${base + 1} with no gap`
+      )
+    }
   }
 
   const seen = (key) => {

package/std/README.md

@@ -16,6 +16,46 @@ whatever program imports it, and subject to the same rules as `examples/` or
 | [`map.ts`](./map.ts) | `reserve(m, n)` and `getOrInsert(m, k, v)` for the global `Map`. Their bodies are the meaning, and what runs under Node: `reserve` does nothing, and `getOrInsert` is a `get`, and a `set` of `v` when the key was missing. Natively the compiler lowers every call in place — `reserve` to the table's `reserveSlots`, which grows the buckets once so that `n` entries fit without a rebuild, and `getOrInsert` to one `probe` and a `valueAt` or an `insertAt` through its answer — so, like `collections.ts`, it writes no `.ll` of its own ([`docs/wp32-map.md`](../docs/wp32-map.md) §9.2, [`docs/LANGUAGE.md`](../docs/LANGUAGE.md#map-and-set)) |
 | [`threads.ts`](./threads.ts) | `parallelMapInto(src, dst, f)` and `parallelReduce(src, f, identity)`: a function over every element of an array, on as many threads as the length is worth. Its bodies are the sequential meaning, which is what runs under Node; the compiler recognises the two templates by module and name, lowers the one loop in each onto `nish_parallel_range`, holds the function to the rules that make that safe, and compiles an importing program with `--threads` ([`docs/LANGUAGE.md`](../docs/LANGUAGE.md#data-parallelism-nishthreads)). `tests/link/par_*` are its programs |
 
+## `nish/crypto` — the primitives under TLS 1.3
+
+The first lanes of [WP34](../docs/wp34-hosting-cs.md) §5: K1's hashes, MACs and
+key derivation, and K4's key exchange, in pure Nish (decision S1), each module
+imported by its own specifier. Every one is written from its specification
+rather than ported, and reproduces that specification's published vectors in
+its `tests/link/crypto_*` programs. The performance gate compiles every module
+with no diagnostics under both `--number-mode i32` and `f64`, and the hashes,
+HMAC, HKDF and X25519 also run their vectors in `f64` (`crypto_*_f64`).
+
+| Module | What it is | Reproduces |
+| --- | --- | --- |
+| [`crypto/sha256.ts`](./crypto/sha256.ts) | `sha256(data)`, and `Sha256`, a streaming hasher: `update(buf, off, len)` over a window of a `u8[]`, `copy()` for the hash of a prefix while the original keeps going, and `digest()`, a fresh 32-byte array. `SHA256_SIZE` and `SHA256_BLOCK` | FIPS 180-4 §6.2 |
+| [`crypto/sha512.ts`](./crypto/sha512.ts) | SHA-512 and SHA-384 on one compression function: `sha512` and `sha384`, and the streaming `Sha512` and `Sha384` with `Sha256`'s three methods; digests of 64 and 48 bytes. `SHA512_SIZE`, `SHA384_SIZE` and `SHA512_BLOCK` | FIPS 180-4 §6.4, §6.5 |
+| [`crypto/hmac.ts`](./crypto/hmac.ts) | `hmacSha256` and `hmacSha384`, the streaming `HmacSha256` and `HmacSha384` (keyed in the constructor, then `update` and `digest`), and `hmacSha256Verify` / `hmacSha384Verify`, which compare a received tag with `timingSafeEqual` | RFC 2104, RFC 4231 §4 |
+| [`crypto/hkdf.ts`](./crypto/hkdf.ts) | `hkdfExtractSha256` / `hkdfExtractSha384` (an empty salt is HashLen zeros) and `hkdfExpandSha256` / `hkdfExpandSha384`, which answer `null` for a length below zero or above 255 × HashLen. TLS 1.3's HKDF-Expand-Label is not here; it belongs with TLS | RFC 5869 §2, Appendix A |
+| [`crypto/ct.ts`](./crypto/ct.ts) | `timingSafeEqual(a, b)`, which reads every byte whatever it holds, and `timingSafeEqualAt(a, aOff, b, bOff, len)` over two windows, which answers `false` for a window outside its array. Two lengths that differ answer `false` at once, because a length is public | — |
+| [`crypto/base64url.ts`](./crypto/base64url.ts) | `base64urlEncode(data)` and `base64urlDecode(text)`, unpadded. Decoding is strict, so every byte string has one spelling: a `=`, a character outside the alphabet, a length of 1 mod 4 or nonzero unused low bits answer `null` | RFC 4648 §5, §10 |
+| [`crypto/x25519.ts`](./crypto/x25519.ts) | `x25519(scalar, u)` and `x25519Base(scalar)`, on ten 25.5-bit limbs in `i64`. Either answers `null` unless its arguments are `X25519_SIZE` (32) bytes; the scalar is clamped on a copy | RFC 7748 §5.2, §6.1 |
+
+Three rules hold across the modules:
+
+- **A digest ends the computation.** After `digest()` on a hasher or an HMAC, a
+  further `update` or `digest` panics rather than answering a hash over the
+  padding, and so does a window outside its buffer. `Sha256.copy()` on a
+  digested hasher panics too; `Sha512.copy()` and `Sha384.copy()` answer a copy
+  that is itself spent, so any `update` or `digest` on it panics. Either way,
+  copy *before* `digest` when the computation has to go on.
+- **An all-zero X25519 result is returned, not refused.** It is what a
+  low-order `u` gives, and RFC 7748 §6.1 leaves the check to the protocol; TLS
+  1.3 (WP34 T1) makes it. A key exchange outside TLS has to make it itself.
+- **Constant time by construction, not yet by proof.** No module branches on,
+  or indexes by, a secret: comparisons OR the differences into one word and
+  test it once, the ladder swaps with a mask and always runs 255 steps, and
+  base64url maps characters by arithmetic on range masks rather than a table.
+  Every branch is on a length, a loop counter or a bit position. What checks
+  that the machine code kept that shape is WP34 N6 — the `ctSelect` / `ctEq`
+  builtins behind an optimisation barrier, and a disassembly check — and it is
+  not built yet, so this is the discipline and not a verified property.
+
 ## How a program imports it
 
 By its package specifier:

package/std/crypto/base64url.ts

@@ -0,0 +1,145 @@
+/**
+ * `nish/crypto/base64url` — RFC 4648 §5 base64url, unpadded, as JWS and the
+ * relay's grants spell a key or a tag inside a URL or a header.
+ *
+ * The alphabet is `A-Z a-z 0-9 - _`, and there is no `=`: the length of the
+ * text already says how many bytes the last group holds (RFC 4648 §3.2 lets a
+ * specification that knows its lengths drop the padding, and RFC 7515 §2 does).
+ *
+ * **Decoding is strict, so that each byte string has exactly one spelling.**
+ * `base64urlDecode` answers `null` for a `=` anywhere, for any character outside
+ * the alphabet (whitespace included), for a length of 1 mod 4 — six bits, not a
+ * byte — and for a final character whose unused low bits are not zero (RFC 4648
+ * §3.5). A lenient decoder would let `AB` and `AA` both mean `00`, and a token
+ * compared or cached by its text would then have two identities.
+ *
+ * **Neither direction indexes or branches on the data.** What is encoded here
+ * is usually a key, a nonce or a MAC, and a lookup table indexed by a secret
+ * sextet leaves its trace in the cache. So a sextet becomes a character, and a
+ * character a sextet, by arithmetic on range masks: `(lo - 1 - c) & (c - hi - 1)`
+ * is negative exactly when `lo <= c <= hi`, and an arithmetic shift by 31 turns
+ * that sign into an all-ones or all-zeros mask. A malformed character is not
+ * refused where it is found either: the verdict is ORed into one word and read
+ * once, after the whole text. The text's length is public and is tested first.
+ *
+ * Private helpers share the importing program's flat symbol namespace
+ * (`docs/wp26-stdlib.md` §3e), which is why each one carries the module's name.
+ */
+
+/**
+ * All ones when `lo <= c <= hi`, else zero, without a branch. `c` is a byte or
+ * a sextet, so neither subtraction can overflow.
+ */
+const base64urlRangeMask = (c: i32, lo: i32, hi: i32): i32 => ((lo - 1 - c) & (c - hi - 1)) >> 31
+
+/**
+ * The URL-alphabet character for the sextet `v` (`0 <= v <= 63`).
+ *
+ * It starts from `'A' + v` and adds, for each range `v` has passed, the step
+ * from the previous range's first character to this one's: 26 lands on `a`, 52
+ * on `0`, 62 on `-` and 63 on `_`.
+ */
+const base64urlCharOf = (v: i32): i32 =>
+  65 +
+  v +
+  (base64urlRangeMask(v, 26, 63) & 6) -
+  (base64urlRangeMask(v, 52, 63) & 75) -
+  (base64urlRangeMask(v, 62, 63) & 13) +
+  (base64urlRangeMask(v, 63, 63) & 49)
+
+/**
+ * The sextet the byte `c` stands for, or `-1` when `c` is not in the alphabet.
+ * Each range contributes its value under its own mask, and a byte in none of
+ * them has every bit set by the final OR.
+ */
+const base64urlSextetOf = (c: i32): i32 => {
+  const upper: i32 = base64urlRangeMask(c, 65, 90)
+  const lower: i32 = base64urlRangeMask(c, 97, 122)
+  const digit: i32 = base64urlRangeMask(c, 48, 57)
+  const dash: i32 = base64urlRangeMask(c, 45, 45)
+  const underscore: i32 = base64urlRangeMask(c, 95, 95)
+  const value: i32 =
+    (upper & (c - 65)) | (lower & (c - 71)) | (digit & (c + 4)) | (dash & 62) | (underscore & 63)
+  return value | ~(upper | lower | digit | dash | underscore)
+}
+
+/**
+ * `data` as unpadded base64url: four characters per three bytes, and two or
+ * three for a short final group.
+ *
+ * Bytes go into a bit accumulator eight at a time and come out six at a time,
+ * so one index walks the input and the only branches are on how many bits are
+ * waiting — which depends on the position, never on the bytes.
+ */
+export const base64urlEncode = (data: u8[]): string => {
+  const parts: string[] = []
+  let acc: i32 = 0
+  let bits: i32 = 0
+  for (let k: i32 = 0; k < toI32(data.length); k++) {
+    // At most four bits wait from the bytes before, so twelve are live here;
+    // the mask keeps the accumulator from growing without bound.
+    acc = ((acc << 8) | toI32(data[k])) & 0xfff
+    bits += 8
+    while (bits >= 6) {
+      bits -= 6
+      parts.push(String.fromCharCode(base64urlCharOf((acc >> bits) & 63)))
+    }
+  }
+  // Two or four bits of a final byte are left: they go out as the high bits of
+  // one more sextet, filled out with zeros.
+  if (bits > 0) {
+    parts.push(String.fromCharCode(base64urlCharOf((acc << (6 - bits)) & 63)))
+  }
+  return parts.join("")
+}
+
+/**
+ * The bytes `text` spells in unpadded base64url, or `null` when it is not the
+ * one canonical spelling of any byte string — see the module comment for the
+ * four refusals.
+ *
+ * The same accumulator as `base64urlEncode`, run the other way: six bits in per
+ * character, eight out per byte.
+ */
+export const base64urlDecode = (text: string): u8[] | null => {
+  const n: i32 = toI32(text.length)
+  const tail: i32 = n & 3
+  // Six bits cannot finish a byte, so a single character after the last full
+  // group spells nothing.
+  if (tail === 1) {
+    return null
+  }
+  // Three bytes per full group of four, and one fewer than the characters in a
+  // short final group; `n * 3 / 4` would overflow for a text over 700 MB.
+  const out: u8[] = new Array<u8>((n >> 2) * 3 + (tail === 0 ? 0 : tail - 1))
+  const outLen: i32 = toI32(out.length)
+  // All ones once any character is outside the alphabet (its sextet of `-1`
+  // shifted right by 31), and non-zero once the text ends on a bit that
+  // encodes no byte.
+  let bad: i32 = 0
+  let acc: i32 = 0
+  let bits: i32 = 0
+  let j: i32 = 0
+  for (let k: i32 = 0; k < n; k++) {
+    const v: i32 = base64urlSextetOf(toI32(text.charCodeAt(k)))
+    bad = bad | (v >> 31)
+    acc = ((acc << 6) | (v & 63)) & 0xfff
+    bits += 6
+    if (bits >= 8) {
+      bits -= 8
+      // Always true — `out` was sized from the same length — but written out
+      // so that the store keeps no bounds check.
+      if (j >= 0 && j < outLen) {
+        out[j] = toU8((acc >> bits) & 255)
+      }
+      j++
+    }
+  }
+  // The two or four bits left over belong to no byte, and must be zero so that
+  // `AA` is the only spelling of a zero byte and `AB` is refused (RFC 4648 §3.5).
+  bad = bad | (acc & ((1 << bits) - 1))
+  if (bad !== 0) {
+    return null
+  }
+  return out
+}

package/std/crypto/ct.ts

@@ -0,0 +1,64 @@
+/**
+ * `nish/crypto/ct` — comparing secrets without telling the clock where they differ.
+ *
+ * An `===` loop over two MACs stops at the first differing byte, so the time it
+ * takes says how many leading bytes an attacker already guessed right, and a
+ * tag can be recovered one byte at a time. These functions read every byte of
+ * the window whatever it holds: each pair is XORed, the differences are ORed
+ * into one accumulator, and that accumulator is tested once, after the loop.
+ *
+ * What is *not* secret is checked first and may branch: the two lengths, and
+ * whether a window lies inside its array. A caller comparing a received tag
+ * against an expected one already knows both lengths, so refusing a mismatch
+ * early leaks nothing the attacker did not send.
+ *
+ * The names are `timingSafeEqual*`, after Node's `crypto.timingSafeEqual`,
+ * rather than `ctEq`: that one is reserved for the builtin WP34 N6 will add,
+ * together with the disassembly check that proves the loop stays branch-free
+ * after LLVM has seen it. Until then this is the discipline and not a proof.
+ */
+
+/**
+ * Whether `a` and `b` hold the same bytes, reading all of them.
+ *
+ * Arrays of different lengths answer `false` at once, because a length is
+ * public; arrays of one length are compared in full, with no early exit.
+ */
+export const timingSafeEqual = (a: u8[], b: u8[]): boolean => {
+  const n: i32 = toI32(a.length)
+  if (n !== toI32(b.length)) {
+    return false
+  }
+  let diff: i32 = 0
+  // Bounded by both lengths, which are equal here, so the prover drops both
+  // bounds checks rather than trusting the comparison above.
+  for (let i: i32 = 0; i < n && i < toI32(b.length); i++) {
+    diff = diff | toI32(a[i] ^ b[i])
+  }
+  return diff === 0
+}
+
+/**
+ * Whether the `len` bytes of `a` from `aOff` equal the `len` bytes of `b` from
+ * `bOff`, reading all of them.
+ *
+ * A window that does not lie inside its array — a negative offset or length,
+ * or `off + len` past the end — answers `false` instead of panicking on the
+ * first out-of-range read. That is a decision about the caller's position: a
+ * verifier handed a truncated record should say "not equal", not take the
+ * process down, and the bounds are public, so testing them first is safe.
+ */
+export const timingSafeEqualAt = (a: u8[], aOff: i32, b: u8[], bOff: i32, len: i32): boolean => {
+  const aLen: i32 = toI32(a.length)
+  const bLen: i32 = toI32(b.length)
+  // Written as `off > length - len` rather than `off + len > length`, so that
+  // a huge offset cannot wrap round to a small sum and pass.
+  if (aOff < 0 || bOff < 0 || len < 0 || aOff > aLen - len || bOff > bLen - len) {
+    return false
+  }
+  let diff: i32 = 0
+  for (let k: i32 = 0; k < len; k++) {
+    diff = diff | toI32(a[aOff + k] ^ b[bOff + k])
+  }
+  return diff === 0
+}