@amritk/nish 0.12.0 → 0.14.0

package/scripts/platform-package.mjs

@@ -22,41 +22,41 @@
  * say so when none was installed; two packages claiming one command name would
  * leave which binary wins up to npm's link order.
  */
-import fs from "node:fs";
-import path from "node:path";
-import { targetForAsset } from "../bin/packaging.js";
+import fs from "node:fs"
+import path from "node:path"
+import { targetForAsset } from "../bin/packaging.js"
 
-const args = process.argv.slice(2);
+const args = process.argv.slice(2)
 const flag = (name) => {
-  const i = args.indexOf(name);
-  return i < 0 ? null : args[i + 1];
-};
-const positional = args.filter((a, i) => !a.startsWith("--") && !(args[i - 1] ?? "").startsWith("--"));
-const [stageDir, asset] = positional;
+  const i = args.indexOf(name)
+  return i < 0 ? null : args[i + 1]
+}
+const positional = args.filter((a, i) => !a.startsWith("--") && !(args[i - 1] ?? "").startsWith("--"))
+const [stageDir, asset] = positional
 
 if (stageDir === undefined || asset === undefined) {
-  console.error("usage: platform-package.mjs <stage-dir> <asset> [--version <v>]");
-  process.exit(2);
+  console.error("usage: platform-package.mjs <stage-dir> <asset> [--version <v>]")
+  process.exit(2)
 }
 
-const root = path.resolve(import.meta.dirname, "..");
-const main = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
-const version = flag("--version") ?? main.version;
+const root = path.resolve(import.meta.dirname, "..")
+const main = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"))
+const version = flag("--version") ?? main.version
 
-const target = targetForAsset(asset);
+const target = targetForAsset(asset)
 if (target === null) {
-  console.error(`platform-package.mjs: ${asset} is not a platform this project builds for`);
-  process.exit(1);
+  console.error(`platform-package.mjs: ${asset} is not a platform this project builds for`)
+  process.exit(1)
 }
 
-const binary = path.join(stageDir, "bin", "nish");
+const binary = path.join(stageDir, "bin", "nish")
 if (!fs.existsSync(binary)) {
-  console.error(`platform-package.mjs: ${binary} does not exist; stage the binary before packaging it`);
-  process.exit(1);
+  console.error(`platform-package.mjs: ${binary} does not exist; stage the binary before packaging it`)
+  process.exit(1)
 }
 
-const pretty = { linux: "Linux", darwin: "macOS" }[target.os] ?? target.os;
-const chip = { x64: "x86_64", arm64: "ARM64" }[target.cpu] ?? target.cpu;
+const pretty = { linux: "Linux", darwin: "macOS" }[target.os] ?? target.os
+const chip = { x64: "x86_64", arm64: "ARM64" }[target.cpu] ?? target.cpu
 
 const manifest = {
   name: `${main.name}-${asset}`,
@@ -84,8 +84,8 @@ const manifest = {
   repository: main.repository,
   bugs: main.bugs,
   homepage: main.homepage,
-};
+}
 
-const out = path.join(stageDir, "package.json");
-fs.writeFileSync(out, `${JSON.stringify(manifest, null, 2)}\n`);
-console.log(`${manifest.name}@${version} (os ${target.os}, cpu ${target.cpu}) -> ${out}`);
+const out = path.join(stageDir, "package.json")
+fs.writeFileSync(out, `${JSON.stringify(manifest, null, 2)}\n`)
+console.log(`${manifest.name}@${version} (os ${target.os}, cpu ${target.cpu}) -> ${out}`)

package/scripts/postinstall.mjs

@@ -28,7 +28,7 @@
  *
  * **The compiler resolves the link itself as of 0.6.0** -- the real path of
  * whatever `argv[0]` named is a candidate for the package root
- * ([wp19 §5a](../docs/wp19-stage0-retirement.md) item 4, in `self/`) -- so this
+ * ([wp19 §5a](../docs/wp19-stage0-retirement.md) item 4, in `src/`) -- so this
  * `exec` is no longer what makes a copy work, and the reason it is still here is
  * the 91 ms above rather than the defect. It also still carries whoever never
  * ran this script: a shim npm linked and nothing swapped now finds its own
@@ -45,44 +45,54 @@
  * postinstall that can break `npm ci` is a worse bug than the startup cost it
  * exists to remove.
  */
-import fs from "node:fs";
-import path from "node:path";
-import { createRequire } from "node:module";
-import { pathToFileURL } from "node:url";
+import fs from "node:fs"
+import path from "node:path"
+import { createRequire } from "node:module"
+import { pathToFileURL } from "node:url"
 
-const root = path.resolve(import.meta.dirname, "..");
+const root = path.resolve(import.meta.dirname, "..")
 
 const swap = async () => {
   // A checkout, not an install. The repository is its own package, so `npm ci`
   // here installs this package's own optionalDependencies -- and without this
   // guard, the first `npm ci` after they are published would overwrite the
   // tracked `bin/nish` with a binary and leave the working tree dirty. The
-  // landmark is `self/compile.ts`, which is the check `scripts/bootstrap.sh`
-  // makes and is not in `files`; it used to be `src/launcher.ts`, which stopped
+  // landmark is `src/compile.ts`, which is the check `scripts/bootstrap.sh`
+  // makes and is not in `files`; it used to be stage0's `src/launcher.ts`, which stopped
   // being a landmark when the launcher moved into `bin/` and ships.
-  if (fs.existsSync(path.join(root, "self", "compile.ts"))) return "a checkout, so the shim stays";
+  if (fs.existsSync(path.join(root, "src", "compile.ts"))) {
+    return "a checkout, so the shim stays"
+  }
 
-  const shim = path.join(root, "bin", "nish");
-  if (!fs.existsSync(shim)) return "no bin/nish to replace";
+  const shim = path.join(root, "bin", "nish")
+  if (!fs.existsSync(shim)) {
+    return "no bin/nish to replace"
+  }
 
-  const packaging = path.join(root, "bin", "packaging.js");
-  if (!fs.existsSync(packaging)) return "bin/packaging.js is missing";
-  const { assetFor, platformPackageName } = await import(pathToFileURL(packaging).href);
-  const asset = assetFor(process.platform, process.arch);
-  if (asset === null) return `no prebuilt binary for ${process.platform}/${process.arch}`;
+  const packaging = path.join(root, "bin", "packaging.js")
+  if (!fs.existsSync(packaging)) {
+    return "bin/packaging.js is missing"
+  }
+  const { assetFor, platformPackageName } = await import(pathToFileURL(packaging).href)
+  const asset = assetFor(process.platform, process.arch)
+  if (asset === null) {
+    return `no prebuilt binary for ${process.platform}/${process.arch}`
+  }
 
   const name = platformPackageName(
     JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).name,
     asset
-  );
-  let binary;
+  )
+  let binary
   try {
-    const manifest = createRequire(import.meta.url).resolve(`${name}/package.json`);
-    binary = path.join(path.dirname(manifest), "bin", "nish");
+    const manifest = createRequire(import.meta.url).resolve(`${name}/package.json`)
+    binary = path.join(path.dirname(manifest), "bin", "nish")
   } catch {
-    return `${name} is not installed`;
+    return `${name} is not installed`
+  }
+  if (!fs.existsSync(binary)) {
+    return `${name} carries no bin/nish`
   }
-  if (!fs.existsSync(binary)) return `${name} carries no bin/nish`;
 
   // The absolute path is baked in at install time, which is the one thing this
   // gives up: a `node_modules` copied to a different path without a reinstall
@@ -99,35 +109,35 @@ const swap = async () => {
   // have ended up in, the shell would expand them. A home directory with a `$`
   // in it is unusual and entirely legal. In POSIX sh nothing is special inside
   // single quotes, so the only thing to handle is a single quote itself.
-  const shellQuote = (value) => `'${value.split("'").join(`'\\''`)}'`;
-  const target = shellQuote(binary);
+  const shellQuote = (value) => `'${value.split("'").join(`'\\''`)}'`
+  const target = shellQuote(binary)
   const script =
     "#!/bin/sh\n" +
     "# Written by scripts/postinstall.mjs. `npm rebuild` regenerates it.\n" +
     `if [ -x ${target} ]; then exec ${target} "$@"; fi\n` +
     // Exit 3 is this project's toolchain code: the compiler could not be run,
     // which is exactly what has happened (docs/wp12-release.md, "Exit codes").
-    'echo "nish: the prebuilt compiler is not where it was installed; run \'npm rebuild\' to repoint this" >&2\n' +
-    "exit 3\n";
-  const temp = `${shim}.${process.pid}.tmp`;
+    "echo \"nish: the prebuilt compiler is not where it was installed; run 'npm rebuild' to repoint this\" >&2\n" +
+    "exit 3\n"
+  const temp = `${shim}.${process.pid}.tmp`
   try {
-    fs.writeFileSync(temp, script);
-    fs.chmodSync(temp, 0o755);
-    fs.renameSync(temp, shim);
+    fs.writeFileSync(temp, script)
+    fs.chmodSync(temp, 0o755)
+    fs.renameSync(temp, shim)
   } catch (err) {
     try {
-      fs.rmSync(temp, { force: true });
+      fs.rmSync(temp, { force: true })
     } catch {
       // Nothing to do about it, and it is not worth a second message.
     }
-    throw err;
+    throw err
   }
-  return `bin/nish now execs the native compiler in ${name}`;
-};
+  return `bin/nish now execs the native compiler in ${name}`
+}
 
 try {
-  console.log(`nish: ${await swap()}`);
+  console.log(`nish: ${await swap()}`)
 } catch (err) {
   // Deliberately not an error: the shim is still there and still works.
-  console.log(`nish: keeping the node launcher (${err instanceof Error ? err.message : String(err)})`);
+  console.log(`nish: keeping the node launcher (${err instanceof Error ? err.message : String(err)})`)
 }

package/scripts/size-report.sh

@@ -51,13 +51,13 @@ text_sum() {                             # text_sum <object>: every .text* secti
 }
 sect() { size -A "$2" | awk -v s="$1" '$1 == s { print $2 }'; }
 "${CC:-clang}" -Oz -c runtime/runtime.c -o build/size/runtime.o
-"${CC:-clang}" -Oz -c runtime/runtime_os.c -o build/size/runtime_os.o
+"${CC:-clang}" -Oz -c runtime/runtime-os.c -o build/size/runtime_os.o
 row runtime "$(text_sum build/size/runtime.o)" \
   "clang -Oz -c runtime/runtime.c && size -A (.text*; budget 3584)"
 row runtime_os "$(text_sum build/size/runtime_os.o)" \
-  "clang -Oz -c runtime/runtime_os.c && size -A (.text*; budget 1280)"
+  "clang -Oz -c runtime/runtime-os.c && size -A (.text*; budget 1280)"
 row rodata "$(sect .rodata build/size/runtime.o)" "the core object's .rodata (no budget; the Ryu tables live here)"
-# `scripts/build.sh` compiles runtime_os.c beside any runtime.c it is handed, so naming the
+# `scripts/build.sh` compiles runtime-os.c beside any runtime.c it is handed, so naming the
 # core here builds the whole runtime -- and `--gc-sections` then drops whatever this module
 # never calls, which for `examples/add.ts` is all of it.
 for p in debug speed size; do

package/scripts/smoke.sh

@@ -17,7 +17,7 @@
 # link, or run with the expected status. Binaries and IR go to build/smoke/.
 # Needs clang on PATH.
 set -uo pipefail
-cd "$(dirname "$0")/.."
+cd "$(dirname "$0")/.." || exit
 
 examples=${1:-examples}
 out=build/smoke

package/std/README.md

@@ -4,7 +4,7 @@ Nish modules written in Nish, for Nish programs to import. There is no magic
 here and — with three exceptions, `threads.ts`, `collections.ts` and `map.ts` —
 nothing the compiler knows about: a module in this directory is an ordinary Nish source file, compiled as part of
 whatever program imports it, and subject to the same rules as `examples/` or
-`self/` ([`docs/LANGUAGE.md`](../docs/LANGUAGE.md) is the style guide).
+`src/` ([`docs/LANGUAGE.md`](../docs/LANGUAGE.md) is the style guide).
 
 | Module | What it is |
 | --- | --- |
@@ -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:
@@ -130,7 +170,7 @@ that are *not* this package.
   stdout. `tests/link/std_text_f64` is the same corpus under
   `--number-mode f64`, which is where a module that spelled its widths and forgot
   a `toI32` is caught.
-- **`std/` is not on the compiler's dependency list.** Nothing in `self/`
+- **`std/` is not on the compiler's dependency list.** Nothing in `src/`
   imports it, and nothing should: the compiler is the thing that has to
   build before the library means anything.