From d6cdf3b8f5176b8f0bdfd75521ee2247c094ec2f Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 22 Nov 2026 00:59:54 +0100 Subject: [PATCH] S15 TypeScript seals: seal, open and sealAnonymous beside go/seal MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The forge module's minting processes are TypeScript and the vault's two steps need ADR 0206's sealed box and the NaCl anonymous box its intake opens; both now live once in mesh-sdk, proven byte for byte against the Go package's bytes (tweetnacl 1.0.3 and blakejs 1.2.1 pinned). Builds: design 47 H2 §808, §822, H-A-407 and its addendum --- go/go.mod | 2 +- go/seal/anonymous_test.go | 96 ++++++++++ go/seal/testdata/sealed-anonymous-by-go.json | 24 +++ package-lock.json | 16 ++ package.json | 7 +- src/index.ts | 1 + src/seal/index.ts | 181 +++++++++++++++++++ test/seal.test.ts | 51 ++++++ 8 files changed, 376 insertions(+), 2 deletions(-) create mode 100644 go/seal/anonymous_test.go create mode 100644 go/seal/testdata/sealed-anonymous-by-go.json create mode 100644 src/seal/index.ts create mode 100644 test/seal.test.ts diff --git a/go/go.mod b/go/go.mod index 2b853831..fe822625 100644 --- a/go/go.mod +++ b/go/go.mod @@ -6,6 +6,7 @@ require ( github.com/klauspost/compress v1.20.0 github.com/nats-io/nats-server/v2 v2.11.17 github.com/nats-io/nats.go v1.54.0 + golang.org/x/crypto v0.57.0 ) require ( @@ -15,7 +16,6 @@ require ( github.com/nats-io/jwt/v2 v2.8.1 // indirect github.com/nats-io/nkeys v0.4.16 // indirect github.com/nats-io/nuid v1.0.1 // indirect - golang.org/x/crypto v0.57.0 // indirect golang.org/x/sys v0.48.0 // indirect golang.org/x/time v0.15.0 // indirect ) diff --git a/go/seal/anonymous_test.go b/go/seal/anonymous_test.go new file mode 100644 index 00000000..88a43714 --- /dev/null +++ b/go/seal/anonymous_test.go @@ -0,0 +1,96 @@ +package seal + +import ( + "bytes" + "crypto/sha256" + "encoding/base64" + "encoding/json" + "os" + "testing" + + "golang.org/x/crypto/nacl/box" +) + +// anonymousFixture holds the NaCl anonymous boxes golang.org/x/crypto/nacl/box seals (the box the vault's intake opens), +// with their one-time keys, for the SDK's TypeScript sealAnonymous to make byte for byte (design 47 H2, H-A-407). +type anonymousFixture struct { + About string `json:"about"` + Recipient struct { + Public string `json:"public"` + Private string `json:"private"` + } `json:"recipient"` + Vectors []struct { + Plaintext string `json:"plaintext"` + EphSecret string `json:"ephSecret"` + Sealed string `json:"sealed"` + } `json:"vectors"` +} + +const anonymousFixturePath = "testdata/sealed-anonymous-by-go.json" + +// anonymousVectors seals each plaintext with box.SealAnonymous to a recipient and one-time keys derived from fixed +// labels: test keys that guard nothing. +func anonymousVectors(t *testing.T) anonymousFixture { + t.Helper() + b64 := base64.StdEncoding.EncodeToString + seed := sha256.Sum256([]byte("mesh-sdk anonymous box test recipient")) + pub, priv, err := box.GenerateKey(bytes.NewReader(seed[:])) + if err != nil { + t.Fatal(err) + } + var f anonymousFixture + f.About = "Made by this package's anonymous_test.go with golang.org/x/crypto/nacl/box's SealAnonymous, its one-time keys fixed; the test proves the file is Go's bytes on every run. Test keys; they guard nothing." + f.Recipient.Public, f.Recipient.Private = b64(pub[:]), b64(priv[:]) + for i, plain := range []string{"", "a token minted for the forge", "ünïcode and a longer value: " + string(bytes.Repeat([]byte("x"), 300))} { + eph := sha256.Sum256([]byte{byte(i), 'e', 'p', 'h'}) + sealed, err := box.SealAnonymous(nil, []byte(plain), pub, bytes.NewReader(eph[:])) + if err != nil { + t.Fatal(err) + } + f.Vectors = append(f.Vectors, struct { + Plaintext string `json:"plaintext"` + EphSecret string `json:"ephSecret"` + Sealed string `json:"sealed"` + }{plain, b64(eph[:]), b64(sealed)}) + } + return f +} + +// The anonymous-box fixture the TypeScript tests read is what box.SealAnonymous makes, and each opens with the +// recipient's key as the vault's intake opens it (box.OpenAnonymous). MESH_SDK_WRITE_FIXTURES=1 writes it anew. +func TestTheAnonymousBoxFixtureIsGosBytes(t *testing.T) { + want := anonymousVectors(t) + if os.Getenv("MESH_SDK_WRITE_FIXTURES") == "1" { + raw, _ := json.MarshalIndent(want, "", " ") + if err := os.WriteFile(anonymousFixturePath, append(raw, '\n'), 0o644); err != nil { + t.Fatal(err) + } + } + raw, err := os.ReadFile(anonymousFixturePath) + if err != nil { + t.Fatal(err) + } + var got anonymousFixture + if err := json.Unmarshal(raw, &got); err != nil { + t.Fatal(err) + } + if g, w := mustJSON(got), mustJSON(want); g != w { + t.Fatalf("the fixture is not Go's bytes:\n%s\nwant\n%s", g, w) + } + var pub, priv [32]byte + p, _ := base64.StdEncoding.DecodeString(got.Recipient.Public) + k, _ := base64.StdEncoding.DecodeString(got.Recipient.Private) + copy(pub[:], p) + copy(priv[:], k) + for _, v := range got.Vectors { + sealed, _ := base64.StdEncoding.DecodeString(v.Sealed) + if out, ok := box.OpenAnonymous(nil, sealed, &pub, &priv); !ok || string(out) != v.Plaintext { + t.Errorf("a box does not open to %q: %q, %v", v.Plaintext, out, ok) + } + } +} + +func mustJSON(v any) string { + raw, _ := json.Marshal(v) + return string(raw) +} diff --git a/go/seal/testdata/sealed-anonymous-by-go.json b/go/seal/testdata/sealed-anonymous-by-go.json new file mode 100644 index 00000000..070ae684 --- /dev/null +++ b/go/seal/testdata/sealed-anonymous-by-go.json @@ -0,0 +1,24 @@ +{ + "about": "Made by this package's anonymous_test.go with golang.org/x/crypto/nacl/box's SealAnonymous, its one-time keys fixed; the test proves the file is Go's bytes on every run. Test keys; they guard nothing.", + "recipient": { + "public": "n2nWtTM35RrjXe1pPBzIHWRfSvoE5AMFxFWA92lYmj4=", + "private": "0zveHnrRJV0at3GITmix/NpjX1sJPgsu0tGZIXFVKos=" + }, + "vectors": [ + { + "plaintext": "", + "ephSecret": "CU2adSGwGEEx6/xxSvrQ8Vfq6Yc+kR+2yX7fFriYCbg=", + "sealed": "8qO+LLqjzgOtuE2KVM6bKDB3dMiMiAuEc0hgRwGe03wNBJ60VwAAIw4xPJLmmT1g" + }, + { + "plaintext": "a token minted for the forge", + "ephSecret": "CvmgsKRsGyTmAFRD4EB0mAPpBVN3I4yLJJkkcfbqX0A=", + "sealed": "erK5lMtu+k90Thig1rpUq2jJ9DzF/WZWvVvMPNO+hiPF5uL5jnqNB7h3hQro13ZiKwK4O/hm3MvZm9glM8KqSBoeApTrVWnvP/Ekzg==" + }, + { + "plaintext": "ünïcode and a longer value: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", + "ephSecret": "ypSqdS+hEEoCsEDT6K87sc/I/h9yi06j08c1bKEJAQw=", + "sealed": "QQ7wBpBtvQH4BvkicANk50VlTJ/puVD+BhRgD9ccAl6NriByxkFqxb3GQUy++HAhByqR9vd+NSSt59dVmjKIFdiiJKCvH6zgGWkHEcVBtn1F5PUzscO+yhEwxuuPK1pLJ24PBdcef9x111Yu4aKgG31mt5z0Bnxs9YZAobz8Nx2vkPYfz1Fzu6Tqqq9bElH9rbR/Ua+ChpGu0BgnKgAWRQlnXBOjrVUC4DFa4wFDfCROgFWC1rM3fQCd8Tm4OHpa6RMRhE9pafi8OMP0XIwUrL29JDkcyMtGPuDab3f6NTgGI+yTCHxNgbOupxeA18Ied7om9rt1oAsEfo2SrYEvzplFCgYpDuXmf693zNPFKuGHd18FZmQKwp6gODpO2t+UCEzJa5EB/9vaf44BWcRIDLWiLzx2Pg0QA3DxZziSL4eff9TOeN8qUHH5pYdU5Cdu7clbhImNoe9kqNSZb3NOwav+HZh4SjtfzcHrBTMWbKs8i0jZYLgxcEcr" + } + ] +} diff --git a/package-lock.json b/package-lock.json index 395b47b7..d65254c8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -7,6 +7,10 @@ "": { "name": "@novox/mesh-sdk", "version": "0.1.19", + "dependencies": { + "blakejs": "1.2.1", + "tweetnacl": "1.0.3" + }, "devDependencies": { "@types/node": "^22.0.0", "typescript": "^5.6.0" @@ -22,6 +26,18 @@ "undici-types": "~6.21.0" } }, + "node_modules/blakejs": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/blakejs/-/blakejs-1.2.1.tgz", + "integrity": "sha512-QXUSXI3QVc/gJME0dBpXrag1kbzOqCjCX8/b54ntNyW6sjtoqxqRk3LTmXzaJoh71zMsDCjM+47jS7XiwN/+fQ==", + "license": "MIT" + }, + "node_modules/tweetnacl": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/tweetnacl/-/tweetnacl-1.0.3.tgz", + "integrity": "sha512-6rt+RN7aOi1nGMyC4Xa5DdYiukl2UWCbcJft7YhxReBGQD7OAM8Pbxw6YMo4r2diNEA8FEmu32YOn9rhaiE5yw==", + "license": "Unlicense" + }, "node_modules/typescript": { "version": "5.9.3", "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", diff --git a/package.json b/package.json index b2285b6a..47125069 100644 --- a/package.json +++ b/package.json @@ -15,7 +15,8 @@ "./state": "./dist/state/index.js", "./callers": "./dist/callers/index.js", "./runtime": "./dist/runtime/index.js", - "./views": "./dist/views/index.js" + "./views": "./dist/views/index.js", + "./seal": "./dist/seal/index.js" }, "files": [ "dist" @@ -29,5 +30,9 @@ "devDependencies": { "@types/node": "^22.0.0", "typescript": "^5.6.0" + }, + "dependencies": { + "blakejs": "1.2.1", + "tweetnacl": "1.0.3" } } diff --git a/src/index.ts b/src/index.ts index e07f2aa2..9b5ca520 100644 --- a/src/index.ts +++ b/src/index.ts @@ -16,3 +16,4 @@ export * as state from "./state/index.js"; export * as runtime from "./runtime/index.js"; export * as callers from "./callers/index.js"; export * as views from "./views/index.js"; +export * as seal from "./seal/index.js"; diff --git a/src/seal/index.ts b/src/seal/index.ts new file mode 100644 index 00000000..b1e3e28f --- /dev/null +++ b/src/seal/index.ts @@ -0,0 +1,181 @@ +// The mesh's sealed box in TypeScript (novox/hq ADR 0183, ADR 0206; design 47 H2, lead answer H-A-407), the same +// box as the Go package seal (go/seal) byte for byte: a value sealed to one recipient's public key, which only that +// recipient's private key opens. X25519 for the agreement, HKDF-SHA256 for the key, AES-256-GCM for the box. +// +// A box is `{ v: 1, eph, iv, tag, ct }`, every field standard base64; `eph` is the one-time public key as SPKI DER. +// The key is derived with the salt eph-DER ‖ the recipient's raw public key and the info "novox-mesh sealed box v1", +// so a box cannot be re-addressed to another key. Keys travel as PEM: the public key as SPKI ("PUBLIC KEY"), the +// private key as PKCS #8 ("PRIVATE KEY"). Node's crypto only. +// +// sealAnonymous is the other seal, the NaCl anonymous box (libsodium's crypto_box_seal) the vault's intake opens: +// X25519 and XSalsa20-Poly1305 under a one-time key, the nonce BLAKE2b-24 of the one-time public key ‖ the recipient's, +// the box the one-time public key ‖ the sealed bytes. From two pinned libraries, tweetnacl and blakejs (H-A-407). + +import { + createCipheriv, + createDecipheriv, + createPrivateKey, + createPublicKey, + diffieHellman, + generateKeyPairSync, + hkdfSync, + randomBytes, + type KeyObject, +} from "node:crypto"; +import nacl from "tweetnacl"; +import blakejs from "blakejs"; + +/** A value sealed to one recipient, as it travels in JSON (go/seal's Box). */ +export interface Box { + v: number; + eph: string; + iv: string; + tag: string; + ct: string; +} + +/** A recipient's keypair as the two PEM strings it is kept and sent as (go/seal's KeyPair). */ +export interface KeyPair { + publicKey: string; + privateKey: string; +} + +/** The only box version open opens. */ +export const VERSION = 1; + +const INFO = "novox-mesh sealed box v1"; + +// PKCS #8 DER of an X25519 private key is this prefix and the key's 32 raw bytes (RFC 8410). +const X25519_PKCS8_PREFIX = Buffer.from("302e020100300506032b656e04220420", "hex"); + +/** A fresh X25519 keypair, PEM-encoded. */ +export function generateKeyPair(): KeyPair { + const { publicKey, privateKey } = generateKeyPairSync("x25519"); + return { + publicKey: publicKey.export({ type: "spki", format: "pem" }).toString(), + privateKey: privateKey.export({ type: "pkcs8", format: "pem" }).toString(), + }; +} + +/** Seals plaintext to the recipient's PEM public key, with a fresh one-time key and iv. */ +export function seal(plaintext: string, recipientPEM: string): Box { + const eph = generateKeyPairSync("x25519").privateKey; + return sealWith(plaintext, recipientPEM, eph, randomBytes(12)); +} + +/** + * sealWith is seal with its two sources of randomness given: the one-time key (a KeyObject, or its 32 raw bytes) and + * the iv. Exported for the byte-for-byte tests against the Go package's vectors; a caller seals with seal. + */ +export function sealWith(plaintext: string, recipientPEM: string, eph: KeyObject | Uint8Array, iv: Uint8Array): Box { + const recipient = publicFromPEM(recipientPEM); + const ephKey = eph instanceof Uint8Array ? privateFromRaw(eph) : eph; + const secret = diffieHellman({ privateKey: ephKey, publicKey: recipient }); + const ephDER = createPublicKey(ephKey).export({ type: "spki", format: "der" }); + const cipher = createCipheriv("aes-256-gcm", boxKey(secret, ephDER, rawPublic(recipient)), iv); + const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]); + const b64 = (b: Uint8Array) => Buffer.from(b).toString("base64"); + return { v: VERSION, eph: b64(ephDER), iv: b64(iv), tag: b64(cipher.getAuthTag()), ct: b64(ct) }; +} + +/** + * Opens a box with the recipient's PEM private key. It throws for a box sealed to another key, one changed in any + * field, or one of another version. + */ +export function open(box: Box, privatePEM: string): string { + if (box.v !== VERSION) { + throw new Error(`a sealed box of version ${box.v}, not ${VERSION}`); + } + const priv = privateFromPEM(privatePEM); + const ephDER = Buffer.from(box.eph, "base64"); + let eph: KeyObject; + try { + eph = createPublicKey({ key: ephDER, format: "der", type: "spki" }); + } catch (e) { + throw new Error(`the box's eph: ${(e as Error).message}`); + } + if (eph.asymmetricKeyType !== "x25519") { + throw new Error("the box's eph is not an X25519 key"); + } + const secret = diffieHellman({ privateKey: priv, publicKey: eph }); + const iv = Buffer.from(box.iv, "base64"); + const tag = Buffer.from(box.tag, "base64"); + if (iv.length !== 12 || tag.length !== 16) { + throw new Error("the box does not open with this key"); + } + try { + const decipher = createDecipheriv("aes-256-gcm", boxKey(secret, ephDER, rawPublic(createPublicKey(priv))), iv); + decipher.setAuthTag(tag); + return Buffer.concat([decipher.update(Buffer.from(box.ct, "base64")), decipher.final()]).toString("utf8"); + } catch { + throw new Error("the box does not open with this key"); + } +} + +function publicFromPEM(pem: string): KeyObject { + let k: KeyObject; + try { + k = createPublicKey(pem); + } catch { + throw new Error("not a PEM public key"); + } + if (k.asymmetricKeyType !== "x25519") { + throw new Error("not an X25519 public key"); + } + return k; +} + +function privateFromPEM(pem: string): KeyObject { + let k: KeyObject; + try { + k = createPrivateKey(pem); + } catch { + throw new Error("not a PEM private key"); + } + if (k.asymmetricKeyType !== "x25519") { + throw new Error("not an X25519 private key"); + } + return k; +} + +function privateFromRaw(raw: Uint8Array): KeyObject { + if (raw.length !== 32) { + throw new Error("an X25519 private key is 32 bytes"); + } + return createPrivateKey({ key: Buffer.concat([X25519_PKCS8_PREFIX, raw]), format: "der", type: "pkcs8" }); +} + +// rawPublic is an X25519 public key's 32 raw bytes: the end of its SPKI DER. +function rawPublic(k: KeyObject): Buffer { + const der = k.export({ type: "spki", format: "der" }); + return der.subarray(der.length - 32); +} + +// boxKey is HKDF-SHA256 (RFC 5869) for one 32-byte block, salted with eph-DER ‖ the recipient's raw public key. +function boxKey(secret: Uint8Array, ephDER: Uint8Array, recipientRaw: Uint8Array): Buffer { + return Buffer.from(hkdfSync("sha256", secret, Buffer.concat([ephDER, recipientRaw]), INFO, 32)); +} + +/** + * Seals value to sealTo, a raw X25519 public key in standard base64 (the vault's `seal_to`), in the NaCl anonymous + * box, answered in standard base64: what golang.org/x/crypto/nacl/box's SealAnonymous makes and OpenAnonymous opens. + */ +export function sealAnonymous(value: string | Uint8Array, sealTo: string): string { + return sealAnonymousWith(value, sealTo, nacl.randomBytes(nacl.box.secretKeyLength)); +} + +/** + * sealAnonymousWith is sealAnonymous with its one-time private key given (32 bytes). Exported for the byte-for-byte + * tests against the Go package's bytes; a caller seals with sealAnonymous. + */ +export function sealAnonymousWith(value: string | Uint8Array, sealTo: string, ephSecret: Uint8Array): string { + const recipient = new Uint8Array(Buffer.from(sealTo.trim(), "base64")); + if (recipient.length !== nacl.box.publicKeyLength) { + throw new Error("the key to seal to is not a raw X25519 public key in base64"); + } + const eph = nacl.box.keyPair.fromSecretKey(new Uint8Array(ephSecret)); + const nonce = blakejs.blake2b(Buffer.concat([eph.publicKey, recipient]), undefined, nacl.box.nonceLength); + const message = typeof value === "string" ? new Uint8Array(Buffer.from(value, "utf8")) : new Uint8Array(value); + const sealed = nacl.box(message, nonce, recipient, eph.secretKey); + return Buffer.concat([eph.publicKey, sealed]).toString("base64"); +} diff --git a/test/seal.test.ts b/test/seal.test.ts new file mode 100644 index 00000000..76d2b8d2 --- /dev/null +++ b/test/seal.test.ts @@ -0,0 +1,51 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +import { seal, open, sealWith, sealAnonymous, sealAnonymousWith, generateKeyPair, type Box } from "../dist/seal/index.js"; + +// The seals are proven against the Go package's bytes (design 47 H2, H-A-407): the fixtures go/seal's tests make and +// check on every run. +const testdata = join(import.meta.dirname, "..", "go", "seal", "testdata"); +const fixture = (name: string) => JSON.parse(readFileSync(join(testdata, name), "utf8")); + +// ADR 0206's box: every box Go's seal opens (the licence manager's, the agent module's TypeScript) opens here; given +// the same one-time key and iv, seal makes Go's box byte for byte, so go/seal's Open opens it; another key and a +// changed field are refused. +test("seal and open make and open go/seal's box byte for byte", () => { + const f = fixture("sealed-by-licence-manager.json"); + for (const s of f.sealed as { plaintext: string; box: Box }[]) { + assert.equal(open(s.box, f.recipient.privateKey), s.plaintext); + } + for (const v of f.vectors as { plaintext: string; ephPrivate: string; iv: string; box: Box }[]) { + const got = sealWith(v.plaintext, f.recipient.publicKey, Buffer.from(v.ephPrivate, "base64"), Buffer.from(v.iv, "base64")); + assert.deepEqual(got, v.box); + } + const ts = fixture("sealed-by-typescript.json"); + assert.equal(open(ts.box, ts.privateKey), ts.plaintext); + + const a = generateKeyPair(); + const b = generateKeyPair(); + const box = seal("a token", a.publicKey); + assert.equal(open(box, a.privateKey), "a token"); + assert.notDeepEqual(seal("a token", a.publicKey), box); + assert.throws(() => open(box, b.privateKey), /does not open with this key/); + assert.throws(() => open({ ...box, ct: Buffer.from("changed").toString("base64") }, a.privateKey), /does not open/); + assert.throws(() => open({ ...box, v: 2 }, a.privateKey), /version 2/); +}); + +// The NaCl anonymous box the vault's intake opens: given the same one-time key, sealAnonymous makes what +// golang.org/x/crypto/nacl/box's SealAnonymous made, byte for byte; a fresh one differs and is as long. +test("sealAnonymous makes Go's anonymous box byte for byte", () => { + const f = fixture("sealed-anonymous-by-go.json"); + assert.ok(f.vectors.length > 0); + for (const v of f.vectors as { plaintext: string; ephSecret: string; sealed: string }[]) { + assert.equal(sealAnonymousWith(v.plaintext, f.recipient.public, Buffer.from(v.ephSecret, "base64")), v.sealed); + assert.equal(sealAnonymousWith(Buffer.from(v.plaintext, "utf8"), f.recipient.public, Buffer.from(v.ephSecret, "base64")), v.sealed); + } + const fresh = sealAnonymous("a token", f.recipient.public); + assert.notEqual(fresh, sealAnonymous("a token", f.recipient.public)); + assert.equal(Buffer.from(fresh, "base64").length, 32 + 16 + "a token".length); + assert.throws(() => sealAnonymous("x", "c2hvcnQ="), /not a raw X25519 public key/); +});