Design 47 H2: the kept call paced, take once, page by cursor, settings, class and caps, check-needs #209

Merged
mesh-tools merged 35 commits from feat/47-H2 into main 2026-11-22 03:50:59 +00:00
8 changed files with 376 additions and 2 deletions
Showing only changes of commit d6cdf3b8f5 - Show all commits
+1 -1
View File
@@ -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
)
+96
View File
@@ -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)
}
+24
View File
@@ -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"
}
]
}
+16
View File
@@ -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",
+6 -1
View File
@@ -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"
}
}
+1
View File
@@ -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";
+181
View File
@@ -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");
}
+51
View File
@@ -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/);
});