@aithos/sdk 0.1.0-alpha.54 → 0.1.0-alpha.55

package/dist/test/rotate-ethos.test.js

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Hermetic test of the rotateEthos orchestration, MINUS the live zone recopy
+// (the protocol-client editor uses ambient fetch and can't be mocked here, so
+// we drive the no-edition path). Covers: did.json rotation (rotate_sphere_key
+// with a root-verifiable rotated doc) + collections dual-wrapped toward the NEW
+// #data, readable under the new key while the old wrap is preserved.
+import { test } from "node:test";
+import { strict as assert } from "node:assert";
+import { createBrowserIdentity, signedDidDocument } from "@aithos/protocol-client";
+import { verifyDidDocument } from "@aithos/protocol-core";
+import { createDataClient } from "../src/data.js";
+import { rotateEthos } from "../src/rotate.js";
+import { parseRecoveryFile } from "../src/internal/recovery-file.js";
+const API = "https://api.test";
+const PDS = "https://pds.test";
+function hex(b) {
+    let s = "";
+    for (const x of b)
+        s += x.toString(16).padStart(2, "0");
+    return s;
+}
+function hexToBytes(h) {
+    const o = new Uint8Array(h.length / 2);
+    for (let i = 0; i < o.length; i++)
+        o[i] = parseInt(h.substr(i * 2, 2), 16);
+    return o;
+}
+/** Mock api.aithos.be (identity) + pds.aithos.be (data). No edition exists. */
+function makeMock(initialDidDoc) {
+    let didDoc = initialDidDoc;
+    const collections = new Map();
+    const records = new Map();
+    let rotateCalls = 0;
+    const fetchImpl = (async (url, init) => {
+        const body = JSON.parse(init.body);
+        const m = body.method;
+        const p = body.params ?? {};
+        const ok = (result) => new Response(JSON.stringify({ jsonrpc: "2.0", id: body.id, result }), { status: 200, headers: { "content-type": "application/json" } });
+        const rpcErr = (code, message) => new Response(JSON.stringify({ jsonrpc: "2.0", id: body.id, error: { code, message } }), { status: 200, headers: { "content-type": "application/json" } });
+        const urnFor = (did, name) => `urn:aithos:collection:${did}:${name}`;
+        switch (m) {
+            // --- identity (api) ---
+            case "aithos.get_identity":
+                return ok({ object: didDoc });
+            case "aithos.get_ethos_manifest":
+                return rpcErr(-32020, "not found: edition for " + p.did); // no edition
+            case "aithos.rotate_sphere_key":
+                didDoc = p.new_did_document;
+                rotateCalls++;
+                return ok({ did: p.new_did_document.id, rotated_spheres: ["public", "circle", "self"] });
+            // --- data (pds) ---
+            case "aithos.data.create_collection": {
+                const urn = urnFor(p.subject_did, p.collection_name);
+                collections.set(urn, { urn, name: p.collection_name, schema: p.schema, subject_did: p.subject_did, cmk_envelope: p.cmk_envelope, record_count: 0 });
+                records.set(urn, new Map());
+                return ok({ urn, name: p.collection_name, schema: p.schema, cmk_envelope: p.cmk_envelope });
+            }
+            case "aithos.data.get_collection": {
+                const c = collections.get(urnFor(p.subject_did, p.collection_name));
+                if (!c)
+                    return rpcErr(-32020, "not found");
+                return ok({ urn: c.urn, name: c.name, schema: c.schema, cmk_envelope: c.cmk_envelope, record_count: c.record_count });
+            }
+            case "aithos.data.list_collections":
+                return ok({ items: [...collections.values()].filter((c) => c.subject_did === p.subject_did).map((c) => ({ name: c.name, schema: c.schema, record_count: c.record_count })) });
+            case "aithos.data.insert_record": {
+                const recs = records.get(p.collection_urn);
+                recs.set(p.record_id, { record_id: p.record_id, metadata: p.metadata, payload: p.payload });
+                return ok({ record_id: p.record_id });
+            }
+            case "aithos.data.get_record": {
+                const r = records.get(p.collection_urn)?.get(p.record_id);
+                return r ? ok(r) : rpcErr(-32020, "not found");
+            }
+            case "aithos.data.rotate_cmk": {
+                const c = [...collections.values()].find((x) => x.urn === p.collection_urn);
+                c.cmk_envelope = p.new_cmk_envelope;
+                return ok({ rotated_at: new Date().toISOString() });
+            }
+            default:
+                return rpcErr(-32601, `method not found: ${m}`);
+        }
+    });
+    return { fetchImpl, getDidDoc: () => didDoc, collections, rotateCalls: () => rotateCalls };
+}
+test("rotateEthos: rotates did.json (verifiable) + dual-wraps collections to the new #data", async () => {
+    // Legacy identity: published did.json WITHOUT #data (strip it).
+    const id = createBrowserIdentity("rotee", "Rotee");
+    const legacyDoc = signedDidDocument({ ...id, data: undefined });
+    const mock = makeMock(legacyDoc);
+    const did = id.did;
+    const legacyRecovery = JSON.stringify({
+        aithos_recovery_version: "0.1.0-plaintext",
+        handle: id.handle,
+        display_name: id.displayName,
+        did,
+        seeds_hex: { root: hex(id.root.seed), public: hex(id.public.seed), circle: hex(id.circle.seed), self: hex(id.self.seed) },
+    });
+    // A collection created + sealed under the OLD #self key.
+    const oldClient = createDataClient({ pdsUrl: PDS, did, sphereSeed: id.self.seed, verificationMethod: `${did}#self`, fetch: mock.fetchImpl });
+    await oldClient.createCollection({ name: "contacts", schema: "aithos.contacts.v1" });
+    const recId = await oldClient.collection("contacts").insert({ name: "Iris", phone: "+33-rot-secret" });
+    // Rotate everything. No edition exists → zones skipped automatically.
+    const result = await rotateEthos(legacyRecovery, { apiBaseUrl: API, pdsUrl: PDS, fetch: mock.fetchImpl });
+    assert.equal(result.hadEdition, false);
+    assert.equal(result.editionRepublished, false);
+    assert.equal(mock.rotateCalls(), 1, "rotate_sphere_key called once");
+    // The newly published did.json verifies under root, rotated all 3 spheres, added #data.
+    const newDoc = mock.getDidDoc();
+    assert.equal(verifyDidDocument(newDoc), true, "rotated did.json verifies under root");
+    assert.equal(newDoc.aithos.rotated.length, 3);
+    assert.ok(newDoc.verificationMethod.some((v) => v.id === `${did}#data`), "#data added");
+    for (const s of ["public", "circle", "self"]) {
+        const oldK = legacyDoc.verificationMethod.find((v) => v.id === `${did}#${s}`).publicKeyMultibase;
+        const newK = newDoc.verificationMethod.find((v) => v.id === `${did}#${s}`).publicKeyMultibase;
+        assert.notEqual(newK, oldK, `${s} rotated`);
+    }
+    // Collections re-keyed toward the new #data (dual). Read under the NEW #data.
+    assert.equal(result.collections.collections[0].status, "data-wrap-added");
+    const newRec = parseRecoveryFile(result.updatedRecoveryFile);
+    assert.ok(newRec.seedsHex.data && newRec.seedsHex.data.length === 64, "new recovery carries #data");
+    // all sphere seeds changed
+    assert.notEqual(newRec.seedsHex.public, hex(id.public.seed));
+    const dataClient = createDataClient({ pdsUrl: PDS, did, sphereSeed: hexToBytes(newRec.seedsHex.data), verificationMethod: `${did}#data`, fetch: mock.fetchImpl });
+    const got = await dataClient.collection("contacts").get(recId);
+    assert.equal(got.phone, "+33-rot-secret", "record decrypts under the NEW #data");
+    // The OLD #self reader still works (dual: old wrap preserved).
+    const selfClient = createDataClient({ pdsUrl: PDS, did, sphereSeed: id.self.seed, verificationMethod: `${did}#self`, fetch: mock.fetchImpl });
+    const viaSelf = await selfClient.collection("contacts").get(recId);
+    assert.equal(viaSelf.phone, "+33-rot-secret", "old #self reader still decrypts");
+});
+test("rotateEthos: refuses to skip zones when an edition exists (no force)", async () => {
+    const id = createBrowserIdentity("rotee2", "Rotee2");
+    const mock = makeMock(signedDidDocument({ ...id, data: undefined }));
+    // Make get_ethos_manifest succeed → an edition "exists".
+    const patched = (async (url, init) => {
+        const body = JSON.parse(init.body);
+        if (body.method === "aithos.get_ethos_manifest") {
+            return new Response(JSON.stringify({ jsonrpc: "2.0", id: body.id, result: { object: { edition: { height: 0 } } } }), { status: 200 });
+        }
+        return mock.fetchImpl(url, init);
+    });
+    const legacyRecovery = JSON.stringify({
+        aithos_recovery_version: "0.1.0-plaintext",
+        handle: id.handle, display_name: id.displayName, did: id.did,
+        seeds_hex: { root: hex(id.root.seed), public: hex(id.public.seed), circle: hex(id.circle.seed), self: hex(id.self.seed) },
+    });
+    await assert.rejects(() => rotateEthos(legacyRecovery, { apiBaseUrl: API, pdsUrl: PDS, fetch: patched, skipZones: true }), /would orphan that content/);
+});
+//# sourceMappingURL=rotate-ethos.test.js.map

package/dist/test/rotate.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rotate.test.d.ts.map

package/dist/test/rotate.test.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Unit tests for buildSignedRotatedDidDocument: the rotated did.json must (1)
+// verify under the unchanged root key, (2) grow aithos.rotated[] by one entry
+// per changed Ethos sphere, (3) carry the #data sphere, (4) keep the DID.
+import { test } from "node:test";
+import { strict as assert } from "node:assert";
+import { randomBytes } from "node:crypto";
+import { createBrowserIdentity, signedDidDocument } from "@aithos/protocol-client";
+import { verifyDidDocument } from "@aithos/protocol-core";
+import { buildSignedRotatedDidDocument } from "../src/rotate.js";
+function seed() {
+    return new Uint8Array(randomBytes(32));
+}
+test("rotate: rotated did.json verifies under root, grows rotated[], carries #data, keeps DID", () => {
+    // Baseline: a legacy-style identity (no rotation history).
+    const id = createBrowserIdentity("rot_user", "Rot User");
+    const previousDoc = signedDidDocument(id);
+    assert.equal(previousDoc.aithos.rotated.length, 0, "baseline has empty rotation history");
+    // Rotate all three Ethos spheres + #data; keep root.
+    const seeds = { root: id.root.seed, public: seed(), circle: seed(), self: seed(), data: seed() };
+    const rotated = buildSignedRotatedDidDocument(seeds, previousDoc, "Rot User", "key-rotation");
+    // 1. Root signature still valid (root unchanged).
+    assert.equal(verifyDidDocument(rotated), true, "rotated doc verifies under root");
+    // 2. DID unchanged.
+    assert.equal(rotated.id, previousDoc.id);
+    // 3. rotated[] grew by exactly 3 (public, circle, self all changed).
+    assert.equal(rotated.aithos.rotated.length, 3);
+    const spheres = rotated.aithos.rotated.map((r) => r.sphere).sort();
+    assert.deepEqual(spheres, ["circle", "public", "self"]);
+    // Each entry records the OLD key.
+    for (const entry of rotated.aithos.rotated) {
+        const prev = previousDoc.verificationMethod.find((v) => v.id === `${rotated.id}#${entry.sphere}`);
+        assert.equal(entry.previous_key, prev.publicKeyMultibase, `${entry.sphere} records previous key`);
+    }
+    // 4. New keys actually differ + #data present.
+    for (const sphere of ["public", "circle", "self"]) {
+        const oldVm = previousDoc.verificationMethod.find((v) => v.id === `${rotated.id}#${sphere}`);
+        const newVm = rotated.verificationMethod.find((v) => v.id === `${rotated.id}#${sphere}`);
+        assert.notEqual(newVm.publicKeyMultibase, oldVm.publicKeyMultibase, `${sphere} key rotated`);
+    }
+    assert.ok(rotated.verificationMethod.some((v) => v.id === `${rotated.id}#data`), "#data VM present");
+    assert.ok((rotated.keyAgreement ?? []).some((v) => v.id === `${rotated.id}#data-kex`), "#data-kex present");
+});
+test("rotate: history is carried forward across a second rotation", () => {
+    const id = createBrowserIdentity("rot2", "Rot2");
+    const doc0 = signedDidDocument(id);
+    const seeds1 = { root: id.root.seed, public: seed(), circle: seed(), self: seed(), data: seed() };
+    const doc1 = buildSignedRotatedDidDocument(seeds1, doc0, "Rot2");
+    assert.equal(doc1.aithos.rotated.length, 3);
+    // Second rotation from doc1 → 3 more entries (total 6).
+    const seeds2 = { root: id.root.seed, public: seed(), circle: seed(), self: seed(), data: seeds1.data };
+    const doc2 = buildSignedRotatedDidDocument(seeds2, doc1, "Rot2");
+    assert.equal(doc2.aithos.rotated.length, 6, "prior history preserved + new entries appended");
+    assert.equal(verifyDidDocument(doc2), true);
+});
+test("rotate: refuses if root seed does not match the DID", () => {
+    const id = createBrowserIdentity("rot3", "Rot3");
+    const doc0 = signedDidDocument(id);
+    const seeds = { root: seed() /* WRONG root */, public: seed(), circle: seed(), self: seed() };
+    assert.throws(() => buildSignedRotatedDidDocument(seeds, doc0, "Rot3"), /root .* never rotated/);
+});
+//# sourceMappingURL=rotate.test.js.map

package/dist/test/schema-autoresolve.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=schema-autoresolve.test.d.ts.map

package/dist/test/schema-autoresolve.test.js

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// A reader that did NOT bundle a vendor schema can still read a collection that
+// uses it, by auto-resolving the PUBLISHED JSON Schema from the PDS and
+// deriving the field split from its aithos:indexable / aithos:auto annotations.
+// This is what lets the strangler reference app (and any latest-SDK client)
+// read any collection without hardcoding VENDOR_SCHEMAS.
+import { test } from "node:test";
+import { strict as assert } from "node:assert";
+import { randomBytes } from "node:crypto";
+import { createDataClient, liteFromPublishedSchema } from "../src/data.js";
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha2.js";
+ed.etc.sha512Sync = (...m) => sha512(ed.etc.concatBytes(...m));
+const MEMO_ID = "aithos.x.demo.memo.v1";
+const memoLite = {
+    schema: MEMO_ID,
+    indexable: new Set(["title"]),
+    encrypted: new Set(["body"]),
+    auto: new Set(),
+    defaults: {},
+};
+const memoJson = {
+    "aithos:schema": MEMO_ID,
+    "aithos:version": "1.0.0",
+    type: "object",
+    additionalProperties: false,
+    required: ["title"],
+    properties: {
+        title: { type: "string", "aithos:indexable": true },
+        body: { type: "string" },
+    },
+};
+test("liteFromPublishedSchema derives the field split from annotations", () => {
+    const lite = liteFromPublishedSchema(memoJson);
+    assert.equal(lite.schema, MEMO_ID);
+    assert.deepEqual([...lite.indexable].sort(), ["title"]);
+    assert.deepEqual([...lite.encrypted].sort(), ["body"]);
+    assert.equal(lite.auto.size, 0);
+});
+function makePds() {
+    const collections = new Map();
+    const records = new Map();
+    const schemas = new Map();
+    const fetchImpl = (async (_url, init) => {
+        const body = JSON.parse(init.body);
+        const p = body.params ?? {};
+        const ok = (result) => new Response(JSON.stringify({ jsonrpc: "2.0", id: body.id, result }), { status: 200 });
+        const er = (code, m) => new Response(JSON.stringify({ jsonrpc: "2.0", id: body.id, error: { code, message: m } }), { status: 200 });
+        const urn = (did, n) => `urn:aithos:collection:${did}:${n}`;
+        switch (body.method) {
+            case "aithos.data.register_schema":
+                schemas.set(p.schema_doc["aithos:schema"], p.schema_doc);
+                return ok({ schema_id: p.schema_doc["aithos:schema"], doc_hash: "h", created: true });
+            case "aithos.data.get_schema": {
+                const d = schemas.get(p.schema);
+                return d ? ok({ schema: d }) : er(-32070, "unknown schema");
+            }
+            case "aithos.data.create_collection": {
+                const u = urn(p.subject_did, p.collection_name);
+                collections.set(u, { urn: u, name: p.collection_name, schema: p.schema, subject_did: p.subject_did, cmk_envelope: p.cmk_envelope, record_count: 0 });
+                records.set(u, new Map());
+                return ok({ urn: u, name: p.collection_name, schema: p.schema, cmk_envelope: p.cmk_envelope });
+            }
+            case "aithos.data.get_collection": {
+                const c = collections.get(urn(p.subject_did, p.collection_name));
+                return c ? ok({ urn: c.urn, name: c.name, schema: c.schema, cmk_envelope: c.cmk_envelope, record_count: c.record_count }) : er(-32020, "nf");
+            }
+            case "aithos.data.insert_record": {
+                records.get(p.collection_urn).set(p.record_id, { record_id: p.record_id, metadata: p.metadata, payload: p.payload });
+                return ok({ record_id: p.record_id });
+            }
+            case "aithos.data.get_record": {
+                const r = records.get(p.collection_urn)?.get(p.record_id);
+                return r ? ok(r) : er(-32020, "nf");
+            }
+            default:
+                return er(-32601, body.method);
+        }
+    });
+    return { fetchImpl, schemas };
+}
+test("a reader without the bundled vendor lite decodes via the published schema", async () => {
+    const seed = new Uint8Array(randomBytes(32));
+    const pub = ed.getPublicKey(seed);
+    // did:key style (single-key) — fine for the data PDS owner path in this mock.
+    let n = 0n;
+    const mc = new Uint8Array([0xed, 0x01, ...pub]);
+    for (const b of mc)
+        n = (n << 8n) | BigInt(b);
+    const alpha = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+    let mb = "";
+    let x = n;
+    while (x > 0n) {
+        mb = alpha[Number(x % 58n)] + mb;
+        x /= 58n;
+    }
+    const did = `did:key:z${mb}`;
+    const vm = `${did}#z${mb}`;
+    const pds = makePds();
+    // Writer: bundles the lite, registers the JSON schema, writes a record.
+    const writer = createDataClient({ pdsUrl: "https://pds.test", did, sphereSeed: seed, verificationMethod: vm, schemas: [memoLite], fetch: pds.fetchImpl });
+    await writer.registerSchema(memoJson);
+    await writer.createCollection({ name: "memos", schema: MEMO_ID });
+    const recId = await writer.collection("memos").insert({ title: "Hello", body: "top secret body" });
+    // Reader: NO bundled schema. Must auto-resolve from the PDS-published schema.
+    const reader = createDataClient({ pdsUrl: "https://pds.test", did, sphereSeed: seed, verificationMethod: vm, fetch: pds.fetchImpl });
+    const got = await reader.collection("memos").get(recId);
+    assert.equal(got.title, "Hello", "indexable field present");
+    assert.equal(got.body, "top secret body", "encrypted field decoded via auto-resolved schema");
+});
+test("a reader still fails cleanly when the schema is neither bundled nor published", async () => {
+    const seed = new Uint8Array(randomBytes(32));
+    const pub = ed.getPublicKey(seed);
+    let n = 0n;
+    const mc = new Uint8Array([0xed, 0x01, ...pub]);
+    for (const b of mc)
+        n = (n << 8n) | BigInt(b);
+    const alpha = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+    let mb = "";
+    let x = n;
+    while (x > 0n) {
+        mb = alpha[Number(x % 58n)] + mb;
+        x /= 58n;
+    }
+    const did = `did:key:z${mb}`;
+    const vm = `${did}#z${mb}`;
+    const pds = makePds();
+    // Writer creates the collection WITHOUT registering the schema on the PDS.
+    const writer = createDataClient({ pdsUrl: "https://pds.test", did, sphereSeed: seed, verificationMethod: vm, schemas: [memoLite], fetch: pds.fetchImpl });
+    await writer.createCollection({ name: "memos", schema: MEMO_ID });
+    await writer.collection("memos").insert({ title: "x", body: "y" });
+    const reader = createDataClient({ pdsUrl: "https://pds.test", did, sphereSeed: seed, verificationMethod: vm, fetch: pds.fetchImpl });
+    await assert.rejects(() => reader.collection("memos").get("anything"), /not known to the SDK and not published/);
+});
+//# sourceMappingURL=schema-autoresolve.test.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.54",
+  "version": "0.1.0-alpha.55",
   "description": "Aithos SDK — high-level TypeScript developer kit for building agentic apps on the Aithos protocol. Wraps @aithos/protocol-client and exposes the Aithos compute proxy and wallet (Stripe top-up) endpoints.",
   "keywords": [
     "aithos",