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

package/dist/src/rotate.js

@@ -0,0 +1,298 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * Ethos rotation — building blocks.
+ *
+ * This module currently ships the foundational, fully-tested piece of the
+ * "rotate an Ethos completely" feature: {@link buildSignedRotatedDidDocument},
+ * which produces a root-signed did.json that rotates one or more sphere keys
+ * (and carries / adds the optional `#data` sphere), extending `aithos.rotated[]`
+ * so it is accepted by the existing `aithos.rotate_sphere_key` primitive.
+ *
+ * Root is NEVER rotated — it IS the DID (`did:aithos:<root-mb>`). Rotating it
+ * would change the DID (= a new identity).
+ *
+ * Browser-safe: only depends on `@aithos/protocol-core/{did,canonical}`
+ * (node-free) + the SDK's own X25519 derivation + @noble. So it runs both in
+ * the migration script (node) and in a future in-browser app.aithos.be/rotate
+ * page.
+ *
+ * NOTE (scope): the *full* `rotateEthos` orchestration also re-encrypts the
+ * Ethos circle/self ZONES under the new sphere keys (publish a fresh edition)
+ * before the rotated sphere keys take effect — otherwise existing encrypted
+ * zone content sealed to the old sphere kex becomes unreadable. That zone
+ * recopy goes through `@aithos/protocol-client`'s editor (loadEditSnapshot /
+ * publishZoneEdit) and is built/tested separately. This module deliberately
+ * exposes only the did.json builder so callers can't accidentally rotate the
+ * Ethos sphere keys without the matching zone recopy.
+ */
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha2.js";
+import { canonicalize } from "@aithos/protocol-core/canonical";
+import { ed25519PublicKeyToMultibase, x25519PublicKeyToMultibase, } from "@aithos/protocol-core/did";
+import { ed25519SeedToX25519PublicKey } from "./internal/cmk-wrap.js";
+// noble/ed25519 v2 needs a sync sha512 for sync sign.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+ed.etc.sha512Sync = (...m) => 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+sha512(ed.etc.concatBytes(...m));
+const SPHERES = ["public", "circle", "self"];
+/**
+ * Build + sign a rotated did.json. The result rotates every Ethos sphere whose
+ * seed differs from the previously-published key, appends one `rotated[]` entry
+ * per changed sphere (preserving prior history), carries / adds `#data`, and is
+ * signed by `#root`. Ready to POST via `aithos.rotate_sphere_key`.
+ *
+ * @param seeds        the post-rotation seeds (same root, new sphere seeds).
+ * @param previousDoc  the currently-published did.json (old pubkeys + history).
+ * @param displayName  display name to carry on the doc.
+ * @param reason       audit reason recorded on each new rotated entry.
+ */
+export function buildSignedRotatedDidDocument(seeds, previousDoc, displayName, reason = "rotate") {
+    const rootPub = ed.getPublicKey(seeds.root);
+    const did = "did:aithos:" + ed25519PublicKeyToMultibase(rootPub);
+    if (previousDoc.id !== did) {
+        throw new Error("buildSignedRotatedDidDocument: root seed does not match previousDoc.id — root (and the DID) is never rotated");
+    }
+    const now = new Date().toISOString();
+    const verificationMethod = SPHERES.map((sphere) => ({
+        id: `${did}#${sphere}`,
+        type: "Ed25519VerificationKey2020",
+        controller: did,
+        publicKeyMultibase: ed25519PublicKeyToMultibase(ed.getPublicKey(seeds[sphere])),
+    }));
+    const keyAgreement = SPHERES.map((sphere) => ({
+        id: `${did}#${sphere}-kex`,
+        type: "X25519KeyAgreementKey2020",
+        controller: did,
+        publicKeyMultibase: x25519PublicKeyToMultibase(ed25519SeedToX25519PublicKey(seeds[sphere])),
+    }));
+    if (seeds.data) {
+        verificationMethod.push({
+            id: `${did}#data`,
+            type: "Ed25519VerificationKey2020",
+            controller: did,
+            publicKeyMultibase: ed25519PublicKeyToMultibase(ed.getPublicKey(seeds.data)),
+        });
+        keyAgreement.push({
+            id: `${did}#data-kex`,
+            type: "X25519KeyAgreementKey2020",
+            controller: did,
+            publicKeyMultibase: x25519PublicKeyToMultibase(ed25519SeedToX25519PublicKey(seeds.data)),
+        });
+    }
+    // Carry prior history + append one entry per Ethos sphere whose key changed.
+    const prevKeyOf = (sphere) => previousDoc.verificationMethod.find((vm) => vm.id === `${did}#${sphere}`)?.publicKeyMultibase;
+    const rotated = [...(previousDoc.aithos.rotated ?? [])];
+    for (const sphere of SPHERES) {
+        const oldKey = prevKeyOf(sphere);
+        const newKey = ed25519PublicKeyToMultibase(ed.getPublicKey(seeds[sphere]));
+        if (oldKey && oldKey !== newKey) {
+            rotated.push({ sphere, previous_key: oldKey, rotated_at: now, reason });
+        }
+    }
+    const unsigned = {
+        "@context": ["https://www.w3.org/ns/did/v1", "https://aithos.dev/spec/v0.1"],
+        id: did,
+        verificationMethod,
+        keyAgreement,
+        aithos: { version: "0.1.0", display_name: displayName, created_at: now, rotated },
+        proof: {
+            type: "Ed25519Signature2020",
+            created: now,
+            verificationMethod: `${did}#root`,
+            proofPurpose: "assertionMethod",
+            proofValue: "",
+        },
+    };
+    const bytes = new TextEncoder().encode(canonicalize(unsigned));
+    const sig = ed.sign(bytes, seeds.root);
+    return { ...unsigned, proof: { ...unsigned.proof, proofValue: base64url(sig) } };
+}
+function base64url(bytes) {
+    let bin = "";
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/* ========================================================================== */
+/*  rotateEthos — full rotation orchestration                                 */
+/* ========================================================================== */
+import { loadEditSnapshot, publishZoneEdit, } from "@aithos/protocol-client";
+import { addDataSphereWrap } from "./migrate.js";
+import { DEFAULT_API_BASE_URL } from "./auth.js";
+import { signOwnerEnvelope } from "./internal/envelope.js";
+import { parseRecoveryFile, } from "./internal/recovery-file.js";
+/**
+ * Fully rotate an Ethos: new public/circle/self/#data keys (root unchanged),
+ * re-encrypt the Ethos zones under the new keys (fresh edition), and dual-wrap
+ * every data collection toward the new #data. Entirely client-side; uses only
+ * existing API primitives (rotate_sphere_key, publish_ethos_edition via the
+ * protocol-client editor, rotate_cmk). Returns a new recovery file — persist it.
+ *
+ * Option (a) semantics: the new head edition (carrying all current content) is
+ * fully verifiable under the new keys; pre-rotation edition snapshots are not
+ * re-verifiable against the rotated did.json (rotated[] retains the old keys so
+ * a rotated[]-aware verifier can be added later without re-rotating).
+ */
+export async function rotateEthos(recovery, opts = {}) {
+    const rec = typeof recovery === "string" ? parseRecoveryFile(recovery) : recovery;
+    const fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    const apiBaseUrl = (opts.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/$/, "");
+    const reason = opts.reason ?? "full-rotation";
+    const did = rec.did;
+    const rootSeed = hexToBytes(rec.seedsHex.root);
+    const log = opts.onProgress ?? (() => { });
+    // 1. Fetch the currently-published did.json.
+    log("fetching current did.json");
+    const idRes = await apiRpc(fetchImpl, apiBaseUrl, "aithos.get_identity", { did }, did, rootSeed);
+    const previousDoc = (idRes.object ?? idRes);
+    // 2. Generate fresh seeds (root kept).
+    const newSeeds = {
+        root: rootSeed,
+        public: randomSeed32(),
+        circle: randomSeed32(),
+        self: randomSeed32(),
+        data: randomSeed32(),
+    };
+    const newDataHex = bytesToHex(newSeeds.data);
+    // 3. Probe whether an Ethos edition exists (mockable apiRpc — NOT the
+    //    protocol-client editor, so this stays testable). Absent → -32020.
+    let hadEdition = true;
+    try {
+        log("probing for an existing edition");
+        await apiRpc(fetchImpl, apiBaseUrl, "aithos.get_ethos_manifest", { did }, did, rootSeed);
+    }
+    catch (e) {
+        if (e.code === -32020 || /not found/i.test(String(e.message))) {
+            hadEdition = false;
+        }
+        else {
+            throw e;
+        }
+    }
+    if (hadEdition && opts.skipZones && !opts.force) {
+        throw new Error("rotateEthos: this Ethos has an edition with (possibly encrypted) zone content, but skipZones was set. " +
+            "Rotating the sphere keys without recopying the zones would orphan that content. " +
+            "Pass force: true only if you are certain the zones hold nothing to preserve.");
+    }
+    // 4. Publish the rotated did.json (root-signed) via rotate_sphere_key.
+    log("publishing rotated did.json");
+    const rotatedDoc = buildSignedRotatedDidDocument(newSeeds, previousDoc, rec.displayName, reason);
+    await apiRpc(fetchImpl, apiBaseUrl, "aithos.rotate_sphere_key", { new_did_document: rotatedDoc }, did, rootSeed);
+    // 5. Republish a fresh edition under the NEW identity → zones re-sealed under
+    //    the new sphere keys (LIVE: protocol-client editor, ambient api endpoint).
+    //    loadEditSnapshot decrypts circle/self with the OLD keys; publishZoneEdit
+    //    re-seals them under the NEW identity.
+    let editionRepublished = false;
+    if (hadEdition && !opts.skipZones) {
+        log("loading current edition (old keys) + republishing (new keys)");
+        const snap = await loadEditSnapshot(did, toStoredIdentity(rec));
+        const newStored = toStoredIdentity({
+            handle: rec.handle,
+            displayName: rec.displayName,
+            did,
+            seedsHex: {
+                root: rec.seedsHex.root,
+                public: bytesToHex(newSeeds.public),
+                circle: bytesToHex(newSeeds.circle),
+                self: bytesToHex(newSeeds.self),
+                data: newDataHex,
+            },
+        });
+        await publishZoneEdit({
+            identity: newStored,
+            snapshot: snap,
+            newPublicSections: snap.publicSections ?? [],
+            ...(snap.circleSections ? { newCircleSections: snap.circleSections } : {}),
+            ...(snap.selfSections ? { newSelfSections: snap.selfSections } : {}),
+        });
+        editionRepublished = true;
+    }
+    // 6. Dual-wrap every collection toward the NEW #data (unwrap with old seeds).
+    log("re-keying collections toward the new #data");
+    const collections = await addDataSphereWrap(rec, {
+        ...(opts.pdsUrl ? { pdsUrl: opts.pdsUrl } : {}),
+        fetch: fetchImpl,
+        targetDataSeedHex: newDataHex,
+    });
+    // 7. New recovery (all new seeds; persist!).
+    const updatedRecoveryFile = JSON.stringify({
+        aithos_recovery_version: "0.1.0-plaintext",
+        handle: rec.handle,
+        display_name: rec.displayName,
+        did,
+        seeds_hex: {
+            root: rec.seedsHex.root,
+            public: bytesToHex(newSeeds.public),
+            circle: bytesToHex(newSeeds.circle),
+            self: bytesToHex(newSeeds.self),
+            data: newDataHex,
+        },
+        saved_at: new Date().toISOString(),
+    }, null, 2);
+    return {
+        did,
+        rotatedSpheres: ["public", "circle", "self"],
+        editionRepublished,
+        hadEdition,
+        collections,
+        updatedRecoveryFile,
+    };
+}
+/* -------------------------------------------------------------------------- */
+/*  helpers                                                                   */
+/* -------------------------------------------------------------------------- */
+function toStoredIdentity(rec) {
+    return {
+        handle: rec.handle,
+        displayName: rec.displayName,
+        did: rec.did,
+        seeds: {
+            root: rec.seedsHex.root,
+            public: rec.seedsHex.public,
+            circle: rec.seedsHex.circle,
+            self: rec.seedsHex.self,
+            ...(rec.seedsHex.data ? { data: rec.seedsHex.data } : {}),
+        },
+    };
+}
+async function apiRpc(fetchImpl, apiBaseUrl, method, params, did, rootSeed) {
+    const url = `${apiBaseUrl}/mcp/primitives/${method.includes("get_") ? "read" : "write"}`;
+    const envelope = await signOwnerEnvelope({
+        iss: did,
+        aud: url,
+        method,
+        params,
+        verificationMethod: `${did}#root`,
+        signer: { sign: async (m) => ed.sign(m, rootSeed) },
+    });
+    const r = await fetchImpl(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: `rotate_${Date.now()}`, method, params: { ...params, _envelope: envelope } }),
+    });
+    const j = (await r.json());
+    if (j.error) {
+        throw Object.assign(new Error(`${method} failed: ${j.error.message}`), { code: j.error.code });
+    }
+    return j.result ?? {};
+}
+function randomSeed32() {
+    const buf = new Uint8Array(32);
+    globalThis.crypto?.getRandomValues(buf);
+    return buf;
+}
+function hexToBytes(hex) {
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(hex.substr(i * 2, 2), 16);
+    return out;
+}
+function bytesToHex(b) {
+    let out = "";
+    for (let i = 0; i < b.length; i++)
+        out += b[i].toString(16).padStart(2, "0");
+    return out;
+}
+//# sourceMappingURL=rotate.js.map

package/dist/test/migrate.test.d.ts

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

package/dist/test/migrate.test.js

@@ -0,0 +1,340 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Hermetic end-to-end tests for the legacy #data sphere migration
+// (src/migrate.ts). No network: an in-memory PDS + registry mock implements
+// the subset of primitives the flow touches. This also serves as the
+// conformance guard between src/internal/cmk-wrap.ts and src/data.ts — the
+// migration re-wraps with cmk-wrap, and a real DataClient (data.ts) must be
+// able to read the result, and vice-versa.
+import { test } from "node:test";
+import { strict as assert } from "node:assert";
+import { createBrowserIdentity } from "@aithos/protocol-client";
+import { createDataClient } from "../src/data.js";
+import { ensureDataSphere, rekeyLegacyCollections, addDataSphereWrap, migrateLegacyEthosToDataSphere, } from "../src/migrate.js";
+import { parseRecoveryFile } from "../src/internal/recovery-file.js";
+function makePds() {
+    const collections = new Map();
+    const records = new Map();
+    const augmentCalls = [];
+    const fetchImpl = (async (_url, init) => {
+        const body = JSON.parse(init.body);
+        const p = body.method;
+        const params = 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 (p) {
+            case "aithos.augment_identity": {
+                augmentCalls.push(params.did_document);
+                return ok({ did: params.did_document.id, idempotent: false, data_sphere_added: true });
+            }
+            case "aithos.data.create_collection": {
+                const urn = urnFor(params.subject_did, params.collection_name);
+                collections.set(urn, {
+                    urn,
+                    name: params.collection_name,
+                    schema: params.schema,
+                    subject_did: params.subject_did,
+                    cmk_envelope: params.cmk_envelope,
+                    record_count: 0,
+                });
+                records.set(urn, new Map());
+                return ok({ urn, name: params.collection_name, schema: params.schema, cmk_envelope: params.cmk_envelope });
+            }
+            case "aithos.data.get_collection": {
+                const urn = urnFor(params.subject_did, params.collection_name);
+                const c = collections.get(urn);
+                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": {
+                const items = [...collections.values()]
+                    .filter((c) => c.subject_did === params.subject_did)
+                    .map((c) => ({ name: c.name, schema: c.schema, record_count: c.record_count }));
+                return ok({ items });
+            }
+            case "aithos.data.insert_record": {
+                const recs = records.get(params.collection_urn);
+                if (!recs)
+                    return rpcErr(-32020, "no collection");
+                recs.set(params.record_id, {
+                    record_id: params.record_id,
+                    metadata: params.metadata,
+                    payload: params.payload,
+                });
+                const c = [...collections.values()].find((x) => x.urn === params.collection_urn);
+                if (c)
+                    c.record_count++;
+                return ok({ record_id: params.record_id });
+            }
+            case "aithos.data.get_record": {
+                const recs = records.get(params.collection_urn);
+                const r = recs?.get(params.record_id);
+                if (!r)
+                    return rpcErr(-32020, "not found");
+                return ok(r);
+            }
+            case "aithos.data.list_records": {
+                const recs = records.get(params.collection_urn) ?? new Map();
+                return ok({ items: [...recs.values()] });
+            }
+            case "aithos.data.rotate_cmk": {
+                const c = [...collections.values()].find((x) => x.urn === params.collection_urn);
+                if (!c)
+                    return rpcErr(-32020, "not found");
+                c.cmk_envelope = params.new_cmk_envelope;
+                return ok({ rotated_at: new Date().toISOString(), records_rewrapped: (params.re_wrapped_deks ?? []).length });
+            }
+            default:
+                return rpcErr(-32601, `method not found: ${p}`);
+        }
+    });
+    return { fetchImpl, collections, records, augmentCalls };
+}
+/* -------------------------------------------------------------------------- */
+/*  Helpers                                                                   */
+/* -------------------------------------------------------------------------- */
+function hex(b) {
+    let s = "";
+    for (const x of b)
+        s += x.toString(16).padStart(2, "0");
+    return s;
+}
+function hexToBytes(h) {
+    const out = new Uint8Array(h.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(h.substr(i * 2, 2), 16);
+    return out;
+}
+/** A legacy recovery file (root/public/circle/self only — NO #data). */
+function legacyRecoveryJson(id) {
+    return 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),
+        },
+        saved_at: new Date().toISOString(),
+    });
+}
+const API = "https://api.test";
+const PDS = "https://pds.test";
+/* -------------------------------------------------------------------------- */
+/*  Tests                                                                     */
+/* -------------------------------------------------------------------------- */
+test("migrate: legacy collection (self-sealed) → #data, record stays readable", async () => {
+    const id = createBrowserIdentity("legacy_user", "Legacy User");
+    const did = id.did;
+    const pds = makePds();
+    const recovery = legacyRecoveryJson(id);
+    // 1. Old app created the collection signing under #self (sphereSeed = self).
+    const legacyClient = createDataClient({
+        pdsUrl: PDS,
+        did,
+        sphereSeed: id.self.seed,
+        verificationMethod: `${did}#self`,
+        fetch: pds.fetchImpl,
+    });
+    await legacyClient.createCollection({ name: "contacts", schema: "aithos.contacts.v1" });
+    const recId = await legacyClient.collection("contacts").insert({
+        name: "Jean Dupont",
+        phone: "+33612345678",
+        notes: "secret pre-migration note",
+    });
+    const before = await legacyClient.collection("contacts").get(recId);
+    assert.equal(before.phone, "+33612345678", "legacy read works pre-migration");
+    // Sanity: the stored owner wrap is labelled #data-kex but sealed to the self key.
+    const urn = `urn:aithos:collection:${did}:contacts`;
+    assert.equal(pds.collections.get(urn).cmk_envelope.wraps[0].recipient, `${did}#data-kex`, "owner wrap is labelled #data-kex regardless of the sealing seed");
+    // 2. ensureDataSphere — adds #data, returns a recovery file carrying it.
+    const ensure = await ensureDataSphere(recovery, { apiBaseUrl: API, pdsUrl: PDS, fetch: pds.fetchImpl });
+    assert.equal(ensure.added, true);
+    assert.equal(ensure.dataSeedHex.length, 64, "a 32-byte #data seed was generated");
+    assert.equal(pds.augmentCalls.length, 1, "augment_identity was called once");
+    // 3. rekey — re-wrap CMK from self to #data.
+    const rekey = await rekeyLegacyCollections(parseRecoveryFile(ensure.updatedRecoveryFile), {
+        pdsUrl: PDS,
+        fetch: pds.fetchImpl,
+    });
+    assert.equal(rekey.collections.length, 1);
+    assert.equal(rekey.collections[0].status, "rekeyed");
+    assert.equal(rekey.collections[0].unwrappedWith, "self", "auto-discovered the self seed");
+    // owner wrap recipient label unchanged; still exactly one owner wrap.
+    const envAfter = pds.collections.get(urn).cmk_envelope;
+    const ownerWraps = envAfter.wraps.filter((w) => w.recipient === `${did}#data-kex`);
+    assert.equal(ownerWraps.length, 1, "exactly one owner wrap after rekey");
+    // 4. A fresh #data client reads the SAME record and decrypts it.
+    const dataClient = createDataClient({
+        pdsUrl: PDS,
+        did,
+        sphereSeed: hexToBytes(ensure.dataSeedHex),
+        verificationMethod: `${did}#data`,
+        fetch: pds.fetchImpl,
+    });
+    const after = await dataClient.collection("contacts").get(recId);
+    assert.ok(after, "record fetched post-migration");
+    assert.equal(after.phone, "+33612345678", "phone decrypts under #data");
+    assert.equal(after.notes, "secret pre-migration note", "notes decrypt under #data");
+    // 5. Idempotence — re-running rekey is a no-op (already-data).
+    const rekey2 = await rekeyLegacyCollections(parseRecoveryFile(ensure.updatedRecoveryFile), {
+        pdsUrl: PDS,
+        fetch: pds.fetchImpl,
+    });
+    assert.equal(rekey2.collections[0].status, "already-data");
+});
+test("migrate: dry-run reports a planned rekey without mutating the envelope", async () => {
+    const id = createBrowserIdentity("dry_user", "Dry User");
+    const did = id.did;
+    const pds = makePds();
+    const legacyClient = createDataClient({
+        pdsUrl: PDS,
+        did,
+        sphereSeed: id.public.seed, // sealed under #public this time
+        verificationMethod: `${did}#public`,
+        fetch: pds.fetchImpl,
+    });
+    await legacyClient.createCollection({ name: "leads", schema: "aithos.contacts.v1" });
+    await legacyClient.collection("leads").insert({ name: "Ana", phone: "+34000" });
+    const urn = `urn:aithos:collection:${did}:leads`;
+    const envBefore = JSON.stringify(pds.collections.get(urn).cmk_envelope);
+    const ensure = await ensureDataSphere(legacyRecoveryJson(id), { apiBaseUrl: API, pdsUrl: PDS, fetch: pds.fetchImpl });
+    const rekey = await rekeyLegacyCollections(parseRecoveryFile(ensure.updatedRecoveryFile), {
+        pdsUrl: PDS,
+        fetch: pds.fetchImpl,
+        dryRun: true,
+    });
+    assert.equal(rekey.dryRun, true);
+    assert.equal(rekey.collections[0].status, "planned");
+    assert.equal(rekey.collections[0].unwrappedWith, "public");
+    assert.equal(JSON.stringify(pds.collections.get(urn).cmk_envelope), envBefore, "dry-run did NOT touch the stored envelope");
+});
+test("migrate: delegate wraps are preserved across rekey", async () => {
+    const id = createBrowserIdentity("deleg_user", "Deleg User");
+    const did = id.did;
+    const pds = makePds();
+    const legacyClient = createDataClient({
+        pdsUrl: PDS,
+        did,
+        sphereSeed: id.self.seed,
+        verificationMethod: `${did}#self`,
+        fetch: pds.fetchImpl,
+    });
+    await legacyClient.createCollection({ name: "shared", schema: "aithos.contacts.v1" });
+    // Inject a fake delegate wrap (a did:key recipient) directly into the stored
+    // envelope to simulate a prior authorize_app.
+    const urn = `urn:aithos:collection:${did}:shared`;
+    const env = pds.collections.get(urn).cmk_envelope;
+    env.wraps.push({
+        recipient: "did:key:zDelegateKey#data-kex",
+        // The other fields aren't read by the migration (it filters by recipient).
+    });
+    const ensure = await ensureDataSphere(legacyRecoveryJson(id), { apiBaseUrl: API, pdsUrl: PDS, fetch: pds.fetchImpl });
+    const rekey = await rekeyLegacyCollections(parseRecoveryFile(ensure.updatedRecoveryFile), {
+        pdsUrl: PDS,
+        fetch: pds.fetchImpl,
+    });
+    assert.equal(rekey.collections[0].status, "rekeyed");
+    assert.equal(rekey.collections[0].delegateWrapsPreserved, 1);
+    const after = pds.collections.get(urn).cmk_envelope;
+    assert.ok(after.wraps.some((w) => w.recipient === "did:key:zDelegateKey#data-kex"), "delegate wrap survived the rekey");
+    assert.equal(after.wraps.filter((w) => w.recipient === `${did}#data-kex`).length, 1, "still exactly one owner wrap");
+});
+test("migrate: add-data-wrap keeps the legacy reader AND enables #data (dual-read)", async () => {
+    // Mirrors linkedone: a collection created+read under #root (post-store passes
+    // sphereSeed: rootSeed). We must NOT break the #root reader, but ALSO let a
+    // #data client read the same data.
+    const id = createBrowserIdentity("dual_user", "Dual User");
+    const did = id.did;
+    const pds = makePds();
+    // Legacy app wraps the CMK under #root (recipient label is #data-kex anyway).
+    const rootClient = createDataClient({
+        pdsUrl: PDS,
+        did,
+        sphereSeed: id.root.seed,
+        verificationMethod: `${did}#root`,
+        fetch: pds.fetchImpl,
+    });
+    await rootClient.createCollection({ name: "posts", schema: "aithos.contacts.v1" });
+    const recId = await rootClient.collection("posts").insert({ name: "Léa", phone: "+33secret-root" });
+    // Onboard onto #data in ADD mode (non-destructive).
+    const ensure = await ensureDataSphere(legacyRecoveryJson(id), { apiBaseUrl: API, pdsUrl: PDS, fetch: pds.fetchImpl });
+    const report = await addDataSphereWrap(parseRecoveryFile(ensure.updatedRecoveryFile), {
+        pdsUrl: PDS,
+        fetch: pds.fetchImpl,
+    });
+    assert.equal(report.collections[0].status, "data-wrap-added");
+    assert.equal(report.collections[0].unwrappedWith, "root");
+    // Two owner wraps now share the #data-kex label.
+    const urn = `urn:aithos:collection:${did}:posts`;
+    const ownerWraps = pds.collections.get(urn).cmk_envelope.wraps.filter((w) => w.recipient === `${did}#data-kex`);
+    assert.equal(ownerWraps.length, 2, "legacy + #data owner wraps coexist");
+    // 1) The legacy #root reader STILL works (unchanged app).
+    const rootClient2 = createDataClient({
+        pdsUrl: PDS,
+        did,
+        sphereSeed: id.root.seed,
+        verificationMethod: `${did}#root`,
+        fetch: pds.fetchImpl,
+    });
+    const viaRoot = await rootClient2.collection("posts").get(recId);
+    assert.equal(viaRoot.phone, "+33secret-root", "#root reader still decrypts (multi-wrap reader tries all)");
+    // 2) A #data client reads the SAME record.
+    const dataClient = createDataClient({
+        pdsUrl: PDS,
+        did,
+        sphereSeed: hexToBytes(ensure.dataSeedHex),
+        verificationMethod: `${did}#data`,
+        fetch: pds.fetchImpl,
+    });
+    const viaData = await dataClient.collection("posts").get(recId);
+    assert.equal(viaData.phone, "+33secret-root", "#data reader decrypts the same data");
+    // Idempotent: re-running add is a no-op.
+    const again = await addDataSphereWrap(parseRecoveryFile(ensure.updatedRecoveryFile), { pdsUrl: PDS, fetch: pds.fetchImpl });
+    assert.equal(again.collections[0].status, "already-data");
+});
+test("migrate: combined helper runs ensure + rekey and returns updated recovery", async () => {
+    const id = createBrowserIdentity("combo_user", "Combo User");
+    const did = id.did;
+    const pds = makePds();
+    const legacyClient = createDataClient({
+        pdsUrl: PDS,
+        did,
+        sphereSeed: id.self.seed,
+        verificationMethod: `${did}#self`,
+        fetch: pds.fetchImpl,
+    });
+    await legacyClient.createCollection({ name: "contacts", schema: "aithos.contacts.v1" });
+    const recId = await legacyClient.collection("contacts").insert({ name: "Zoe", phone: "+1999" });
+    const out = await migrateLegacyEthosToDataSphere(legacyRecoveryJson(id), {
+        apiBaseUrl: API,
+        pdsUrl: PDS,
+        fetch: pds.fetchImpl,
+    });
+    assert.equal(out.ensure.added, true);
+    assert.equal(out.rekey.collections[0].status, "rekeyed");
+    const parsed = parseRecoveryFile(out.updatedRecoveryFile);
+    assert.equal(typeof parsed.seedsHex.data, "string");
+    // Read back under #data via the returned seed.
+    const dataClient = createDataClient({
+        pdsUrl: PDS,
+        did,
+        sphereSeed: hexToBytes(out.ensure.dataSeedHex),
+        verificationMethod: `${did}#data`,
+        fetch: pds.fetchImpl,
+    });
+    const after = await dataClient.collection("contacts").get(recId);
+    assert.equal(after.phone, "+1999");
+});
+//# sourceMappingURL=migrate.test.js.map

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

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