feat(stdlib): Crypto.* — SHA-256 + HMAC-SHA256, constant-time verify (#19)

The security-sensitive counterpart to the fast, non-cryptographic Hash.*
library: standard, test-vector-backed hashing for signed saves and message
integrity, kept in its own namespace so nobody reaches for the wrong tool.

  Crypto.sha256(s)                SHA-256 -> 64-char lowercase hex
  Crypto.hmac_sha256(key, msg)    HMAC-SHA256 -> 64-char hex
  Crypto.verify_hmac(key, msg, mac)  recompute + constant-time compare -> bool
  Crypto.hex(s)                   lowercase hex of a string's bytes
  Crypto.ct_equal(a, b)           constant-time string equality

The primitives are implemented from scratch in plain integer LLVM IR
(FIPS 180-4 / RFC 2104): no libc crypto, no data-dependent branches in the
compression rounds, so a given input hashes to the same 32 bytes on every
platform and run. Digests are returned as hex strings, not raw bytes, because
a `str` is null-terminated and a raw digest can contain a NUL. MAC checks use
a non-short-circuiting compare so timing does not leak how much of a forged tag
was correct.

Emitted on demand via g_uses_cryptort, mirroring the emit_hash prelude gate.
Scoped to the deterministic, known-answer-testable core; OS-backed
random_bytes (the one piece that can't be validated by test vectors) is left
for a follow-up.

Tested against published SHA-256 vectors (empty/"abc"/fox + 55/56/64-byte
multi-block padding) and HMAC-SHA256 vectors; wired into the self-host suite as
`crypto`. Docs: a new Crypto section with honest "what this protects / does
not" guidance, one page per method, all fences checked and in the inventory.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/language/crypto/_section.md

@@ -0,0 +1,11 @@
+---
+id: crypto
+title: Crypto
+order: 6
+---
+
+Secure, test-vector-backed hashing for the handful of security-sensitive things a game actually does: signing a save or leaderboard payload so casual tampering is detectable, and verifying that a network message or token was not forged by someone who does not hold the key. This is the deliberate counterpart to the fast <a href="ns-Hash"><code>Hash</code></a> library — same idea, opposite trade-off. <code>Hash</code> is fast and reversible and must never guard anything; <code>Crypto</code> is <a href="crypto-sha256"><code>SHA-256</code></a> and <a href="crypto-hmac_sha256"><code>HMAC-SHA256</code></a> implemented to the standard, so the algorithms are the ones with published known-answer tests rather than anything home-grown.
+
+Digests are returned as lowercase hex strings, not raw bytes — a <code>str</code> is null-terminated and a raw digest can contain a zero byte, so hex is the form you can print, store, and compare directly.
+
+What this is not: it is not DRM and it is not unbeatable anti-cheat. A client-side game cannot keep a secret from the machine it runs on — a determined owner can always read the key out of the binary. Use it to make *casual* tampering detectable and to authenticate messages between parties who share a key. To verify a MAC always use <a href="crypto-verify_hmac"><code>Crypto.verify_hmac</code></a> (a constant-time check), never <code>==</code>, which leaks how much of a guessed MAC was correct.

docs/language/crypto/crypto-ct_equal.md

@@ -0,0 +1,27 @@
+---
+id: crypto-ct_equal
+name: Crypto.ct_equal
+category: crypto
+kind: namespace-method
+tokens: Crypto.ct_equal
+sig: Crypto.ct_equal(a, b) -> bool
+tip: Constant-time string equality for secrets.
+order: 5
+ns: Crypto
+member: ct_equal
+---
+
+Compares two strings for equality without short-circuiting: every character is examined even once a difference is found, so the time taken does not reveal where — or whether — the strings first diverged. Reach for it whenever you compare a secret, token, or MAC that an attacker might be probing. For the common case of checking a message tag, <a href="crypto-verify_hmac"><code>Crypto.verify_hmac</code></a> already does this for you; use <code>ct_equal</code> directly when you hold both values yourself. Strings of different length return <code>false</code> at once (length is not secret). For ordinary, non-secret text just use <code>==</code> — the constant-time guarantee is not free.
+
+Parameters:
+- `a` — one string
+- `b` — the other string
+
+```ludic
+program CompareToken {
+  entry {
+    if Crypto.ct_equal("abc", "abc") { print(1) } else { print(0) }   # 1
+    if Crypto.ct_equal("abc", "abd") { print(1) } else { print(0) }   # 0
+  }
+}
+```

docs/language/crypto/crypto-hex.md

@@ -0,0 +1,25 @@
+---
+id: crypto-hex
+name: Crypto.hex
+category: crypto
+kind: namespace-method
+tokens: Crypto.hex
+sig: Crypto.hex(s) -> string
+tip: Lowercase hex of a string's bytes.
+order: 4
+ns: Crypto
+member: hex
+---
+
+Encodes the bytes of <code>s</code> as a lowercase hex string — two characters per byte, so an <em>n</em>-byte input becomes a <em>2n</em>-character result. It is the same encoding <a href="crypto-sha256"><code>Crypto.sha256</code></a> already applies to a digest, exposed on its own so you can render arbitrary bytes (a key id, a small binary token) in a form that is safe to print, log, or embed in text.
+
+Parameters:
+- `s` — the string whose bytes are encoded
+
+```ludic
+program HexDump {
+  entry {
+    print(Crypto.hex("abc"))   # 616263
+  }
+}
+```

docs/language/crypto/crypto-hmac_sha256.md

@@ -0,0 +1,29 @@
+---
+id: crypto-hmac_sha256
+name: Crypto.hmac_sha256
+category: crypto
+kind: namespace-method
+tokens: Crypto.hmac_sha256
+sig: Crypto.hmac_sha256(key, msg) -> string
+tip: Sign a message with a shared secret key.
+order: 2
+ns: Crypto
+member: hmac_sha256
+---
+
+Computes HMAC-SHA256 over <code>msg</code> under the secret <code>key</code> (RFC 2104) and returns the 64-character lowercase hex tag. Unlike a bare hash, a MAC cannot be recomputed without the key, so it authenticates the message: attach the tag to a save file or a network packet, and a receiver who shares the key can tell whether the payload was altered or forged. To check the tag on the other side, pass it to <a href="crypto-verify_hmac"><code>Crypto.verify_hmac</code></a> rather than comparing hex with <code>==</code>.
+
+Parameters:
+- `key` — the shared secret; keep it out of the shipped client where you can
+- `msg` — the payload being signed
+
+```ludic
+program SignSave {
+  entry {
+    let key = "s3cret"
+    let payload = "score=9001;level=12"
+    let mac = Crypto.hmac_sha256(key, payload)
+    print(mac)
+  }
+}
+```

docs/language/crypto/crypto-sha256.md

@@ -0,0 +1,26 @@
+---
+id: crypto-sha256
+name: Crypto.sha256
+category: crypto
+kind: namespace-method
+tokens: Crypto.sha256
+sig: Crypto.sha256(s) -> string
+tip: SHA-256 of a string, as 64 hex characters.
+order: 1
+ns: Crypto
+member: sha256
+---
+
+Computes the SHA-256 digest of the bytes of <code>s</code> and returns it as a 64-character lowercase hex string. This is the standard, FIPS 180-4 algorithm — the same digest every other conforming implementation produces — so it is deterministic across platforms and runs and is backed by published known-answer vectors. Use it to fingerprint content, or as the building block under <a href="crypto-hmac_sha256"><code>Crypto.hmac_sha256</code></a> for signing. On its own SHA-256 is <em>not</em> a message authentication code: anyone can recompute it, so it proves what the data is, not who produced it.
+
+Parameters:
+- `s` — the string whose bytes are hashed
+
+```ludic
+program Fingerprint {
+  entry {
+    let digest = Crypto.sha256("abc")
+    print(digest)   # ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
+  }
+}
+```

docs/language/crypto/crypto-verify_hmac.md

@@ -0,0 +1,34 @@
+---
+id: crypto-verify_hmac
+name: Crypto.verify_hmac
+category: crypto
+kind: namespace-method
+tokens: Crypto.verify_hmac
+sig: Crypto.verify_hmac(key, msg, mac) -> bool
+tip: Constant-time check that a MAC matches.
+order: 3
+ns: Crypto
+member: verify_hmac
+---
+
+Recomputes HMAC-SHA256(<code>key</code>, <code>msg</code>) and compares it to the supplied <code>mac</code> hex string, returning <code>true</code> only if they match. The comparison is <em>constant-time</em>: it never stops early on the first differing character, so it does not leak — through how long the check took — how many leading bytes of a forged tag happened to be right. That leak is exactly what lets an attacker guess a MAC one byte at a time, which is why you should always verify with this and never with <code>==</code>. A mismatched length returns <code>false</code> immediately (the length of a MAC is not a secret).
+
+Parameters:
+- `key` — the shared secret used to sign
+- `msg` — the payload as received
+- `mac` — the hex tag to check, e.g. from <a href="crypto-hmac_sha256"><code>Crypto.hmac_sha256</code></a>
+
+```ludic
+program CheckSave {
+  entry {
+    let key = "s3cret"
+    let payload = "score=9001;level=12"
+    let mac = Crypto.hmac_sha256(key, payload)
+    if Crypto.verify_hmac(key, payload, mac) {
+      print(1)   # untampered
+    } else {
+      print(0)   # altered or forged
+    }
+  }
+}
+```