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

package/dist/src/internal/cmk-wrap.js

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * CMK wrap / unwrap primitives for the data sub-protocol.
+ *
+ * These are a CANONICAL, byte-identical copy of the private crypto used by
+ * `DataClientImpl` in `../data.ts` (`#wrapCmkForRecipient` / `#unwrapCmk` and
+ * the X25519-seed derivation). They are factored out here so the legacy
+ * #data-sphere migration (`../migrate.ts`) can re-wrap a collection's CMK to
+ * the owner's `#data` key WITHOUT going through the high-level `DataClient`
+ * (which is hard-wired to a single sphere seed and so cannot unwrap a wrap
+ * sealed to a *different* legacy sphere).
+ *
+ * INVARIANT: the wire format produced here MUST stay byte-identical to
+ * `data.ts`. `test/cmk-wrap-conformance.test.ts` proves it by cross-unwrapping
+ * (data.ts wraps → cmk-wrap unwraps, and vice-versa). If you change one, change
+ * both and keep that test green — a drift here silently corrupts migrated data.
+ */
+import { x25519 } from "@noble/curves/ed25519.js";
+import { hkdf } from "@noble/hashes/hkdf.js";
+import { sha256, sha512 } from "@noble/hashes/sha2.js";
+import { XChaCha20Poly1305 } from "@stablelib/xchacha20poly1305";
+/* -------------------------------------------------------------------------- */
+/*  X25519 seed derivation (mirrors data.ts)                                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * Derive a 32-byte X25519 private key from an Ed25519 seed via SHA-512
+ * truncation + clamping (libsodium crypto_sign_ed25519_sk_to_curve25519).
+ */
+export function ed25519SeedToX25519PrivateKey(seed) {
+    if (seed.length !== 32)
+        throw new Error("Ed25519 seed must be 32 bytes");
+    const h = sha512(seed);
+    const sk = new Uint8Array(h.slice(0, 32));
+    sk[0] = sk[0] & 248;
+    sk[31] = sk[31] & 127;
+    sk[31] = sk[31] | 64;
+    return sk;
+}
+export function ed25519SeedToX25519PublicKey(seed) {
+    const sk = ed25519SeedToX25519PrivateKey(seed);
+    try {
+        return x25519.getPublicKey(sk);
+    }
+    finally {
+        sk.fill(0);
+    }
+}
+/* -------------------------------------------------------------------------- */
+/*  Wrap / unwrap (mirrors data.ts #wrapCmkForRecipient / #unwrapCmk)         */
+/* -------------------------------------------------------------------------- */
+export function wrapCmkForRecipient(args) {
+    const ephSk = x25519.utils.randomSecretKey();
+    const ephPk = x25519.getPublicKey(ephSk);
+    const shared = x25519.getSharedSecret(ephSk, args.recipientPublicKey);
+    const wrapKey = hkdf(sha256, shared, utf8("aithos-data-cmk-wrap-v1"), utf8(args.recipientDidUrl), 32);
+    const wrapNonce = randomBytes24();
+    const aad = aadCmkWrap(args.collectionUrn, args.recipientDidUrl);
+    const aead = new XChaCha20Poly1305(wrapKey);
+    const wrapped = aead.seal(wrapNonce, args.cmk, aad);
+    wrapKey.fill(0);
+    shared.fill(0);
+    return {
+        recipient: args.recipientDidUrl,
+        alg: "x25519-hkdf-sha256-aead",
+        ephemeral_public: base64Std(ephPk),
+        wrap_nonce: base64Std(wrapNonce),
+        wrapped_key: base64Std(wrapped),
+    };
+}
+/**
+ * Try to unwrap the CMK from `wrap` with `privateKey`. Returns the CMK bytes
+ * on success, or `null` when the AEAD tag fails (wrong key / AAD mismatch) —
+ * the migration relies on this null-return to AUTO-DISCOVER which legacy sphere
+ * seed sealed the wrap (try each, the right one verifies).
+ */
+export function tryUnwrapCmk(args) {
+    const ephPk = fromBase64(args.wrap.ephemeral_public);
+    const wrapNonce = fromBase64(args.wrap.wrap_nonce);
+    const wrappedKey = fromBase64(args.wrap.wrapped_key);
+    const shared = x25519.getSharedSecret(args.privateKey, ephPk);
+    const wrapKey = hkdf(sha256, shared, utf8("aithos-data-cmk-wrap-v1"), utf8(args.wrap.recipient), 32);
+    const aad = aadCmkWrap(args.collectionUrn, args.wrap.recipient);
+    const aead = new XChaCha20Poly1305(wrapKey);
+    const cmk = aead.open(wrapNonce, wrappedKey, aad);
+    wrapKey.fill(0);
+    shared.fill(0);
+    return cmk ?? null;
+}
+/* -------------------------------------------------------------------------- */
+/*  Local helpers (byte-identical to data.ts)                                 */
+/* -------------------------------------------------------------------------- */
+function aadCmkWrap(collectionUrn, recipient) {
+    const p = utf8("aithos-data-cmk-v1\0");
+    const c = utf8(collectionUrn);
+    const sep = new Uint8Array([0]);
+    const r = utf8(recipient);
+    const out = new Uint8Array(p.length + c.length + sep.length + r.length);
+    let off = 0;
+    out.set(p, off);
+    off += p.length;
+    out.set(c, off);
+    off += c.length;
+    out.set(sep, off);
+    off += sep.length;
+    out.set(r, off);
+    return out;
+}
+function utf8(s) {
+    return new TextEncoder().encode(s);
+}
+function randomBytes24() {
+    const buf = new Uint8Array(24);
+    globalThis.crypto?.getRandomValues(buf);
+    return buf;
+}
+function base64Std(bytes) {
+    let bin = "";
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin);
+}
+function fromBase64(s) {
+    const std = s.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = std + "=".repeat((4 - (std.length % 4)) % 4);
+    const bin = atob(padded);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+//# sourceMappingURL=cmk-wrap.js.map

package/dist/src/key-store.d.ts

@@ -20,9 +20,13 @@ export interface StoredOwnerKeys {
         readonly circle: string;
         readonly self: string;
         /**
-         * Optional dedicated #data sphere seed (spec/data/02-key-hierarchy.md).
-         * Present on owners created since the #data sphere landed; absent on legacy
-         * owners (which sign data/asset PDS ops under #root).
+         * Dedicated `#data` sphere seed (spec/data/02-key-hierarchy.md) — the key
+         * that signs ALL data/asset PDS operations (create, edit, manage
+         * collections), keeping the root cold. Present on owners created since the
+         * `#data` sphere landed. Absent only on legacy owners, which predate it and
+         * therefore have no dedicated PDS key — migrate them to `#data` (the backend
+         * does this lazily on next custodial sign-in; self-custody/SSO already carry
+         * it). Signing PDS ops under any other sphere is a legacy anti-pattern.
          */
         readonly data?: string;
     };

package/dist/src/migrate.d.ts

@@ -0,0 +1,105 @@
+import { type ParsedRecoveryFile } from "./internal/recovery-file.js";
+import { type CmkEnvelope } from "./internal/cmk-wrap.js";
+export interface MigrateOptions {
+    /** api.aithos.be base URL. Defaults to {@link DEFAULT_API_BASE_URL}. */
+    readonly apiBaseUrl?: string;
+    /** PDS base URL. Defaults to `https://pds.aithos.be`. Pass the raw
+     *  execute-api URL when the vanity host isn't live in your environment. */
+    readonly pdsUrl?: string;
+    /** Custom fetch (tests / SSR). Defaults to globalThis.fetch. */
+    readonly fetch?: typeof fetch;
+    /** When true, compute and report planned rekeys but DO NOT write. */
+    readonly dryRun?: boolean;
+    /**
+     * How to onboard a collection onto #data:
+     *   - "replace" (default): swap the owner wrap from the legacy sphere to
+     *     #data. Use for a clean cutover when NOTHING still reads the collection
+     *     under the old key. WARNING: breaks any app still reading under the
+     *     legacy key (e.g. linkedone reading under #root).
+     *   - "add": KEEP the legacy owner wrap and ADD a second owner wrap sealed to
+     *     #data (dual-read). Both the legacy app and a #data client can read the
+     *     same data. Requires @aithos/sdk with the multi-wrap owner reader
+     *     (this release). Safe, non-destructive — recommended for live accounts.
+     */
+    readonly mode?: "replace" | "add";
+    /**
+     * Re-key collections toward a DIFFERENT `#data` key than the one in the
+     * recovery file. Used by `rotateEthos`: unwrap with the recovery's (old)
+     * sphere seeds, wrap toward this NEW `#data` seed. When omitted, the target
+     * is the recovery file's own `#data` seed (the normal migration case).
+     */
+    readonly targetDataSeedHex?: string;
+    /** Progress callback for CLIs / UIs. */
+    readonly onProgress?: (e: MigrateProgress) => void;
+}
+export type MigrateProgress = {
+    phase: "ensure-data-sphere";
+    status: "start" | "added" | "already-present";
+} | {
+    phase: "rekey";
+    status: "collection";
+    collection: string;
+    result: CollectionRekeyStatus;
+};
+export interface EnsureDataSphereResult {
+    readonly did: string;
+    /** True when this call added #data (false = already present server-side). */
+    readonly added: boolean;
+    /** The #data sphere seed (hex). The caller MUST persist this — it's the new
+     *  key the account signs/reads data under. Returned even when `added` is
+     *  false (it's the same seed that's now published). */
+    readonly dataSeedHex: string;
+    /** Convenience: the recovery file serialized WITH the #data seed merged in. */
+    readonly updatedRecoveryFile: string;
+}
+export type CollectionRekeyStatus = "rekeyed" | "data-wrap-added" | "already-data" | "planned" | "skipped-no-owner-wrap" | "unwrap-failed";
+export interface CollectionRekeyEntry {
+    readonly name: string;
+    readonly urn: string;
+    readonly status: CollectionRekeyStatus;
+    /** Which seed successfully unwrapped the CMK (auto-discovery result). */
+    readonly unwrappedWith?: SphereName;
+    /** Count of non-owner (delegate) wraps preserved into the new envelope. */
+    readonly delegateWrapsPreserved?: number;
+    /** Pre-mutation cmk_envelope, kept so a human can roll back if needed. */
+    readonly backupEnvelope?: CmkEnvelope;
+}
+export interface RekeyReport {
+    readonly did: string;
+    readonly dryRun: boolean;
+    readonly collections: readonly CollectionRekeyEntry[];
+}
+export interface FullMigrationResult {
+    readonly ensure: EnsureDataSphereResult;
+    readonly rekey: RekeyReport;
+    /** Recovery file with the #data seed — persist this for the user. */
+    readonly updatedRecoveryFile: string;
+}
+type SphereName = "data" | "data-old" | "self" | "circle" | "public" | "root";
+/**
+ * Idempotently add the `#data` sphere to a (possibly legacy) identity and
+ * re-publish its did.json. Accepts either a parsed recovery file or the raw
+ * recovery JSON text.
+ */
+export declare function ensureDataSphere(owner: ParsedRecoveryFile | string, opts?: MigrateOptions): Promise<EnsureDataSphereResult>;
+/**
+ * Re-wrap every collection's CMK from its legacy sphere to the owner's `#data`
+ * key. Idempotent: collections already readable under `#data` are skipped.
+ * Requires that the recovery file carries a `#data` seed (run
+ * {@link ensureDataSphere} first, or pass {@link FullMigrationResult}).
+ */
+export declare function rekeyLegacyCollections(owner: ParsedRecoveryFile | string, opts?: MigrateOptions): Promise<RekeyReport>;
+/**
+ * Dual-read onboarding: KEEP each collection's legacy owner wrap and ADD a
+ * second owner wrap sealed to #data, so the existing app (reading under the
+ * legacy key) AND a #data client both decrypt the same data. Non-destructive.
+ * Thin wrapper over {@link rekeyLegacyCollections} with `mode: "add"`.
+ */
+export declare function addDataSphereWrap(owner: ParsedRecoveryFile | string, opts?: MigrateOptions): Promise<RekeyReport>;
+/**
+ * Run the full migration: ensureDataSphere then rekeyLegacyCollections.
+ * Returns the updated recovery file (with the #data seed) — persist it.
+ */
+export declare function migrateLegacyEthosToDataSphere(recoveryText: string, opts?: MigrateOptions): Promise<FullMigrationResult>;
+export {};
+//# sourceMappingURL=migrate.d.ts.map

package/dist/src/migrate.js

@@ -0,0 +1,367 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * Legacy `#data` sphere migration.
+ *
+ * Identities created before the dedicated `#data` sphere landed
+ * (spec/data/02-key-hierarchy.md) have only root/public/circle/self keys and
+ * therefore:
+ *   1. their published did.json has no `#data` / `#data-kex` entry, and
+ *   2. their existing data collections' CMK is wrapped to the X25519 key
+ *      derived from whatever sphere seed the *old* app passed to
+ *      `createDataClient({ sphereSeed })` (in practice `#self`/`#public`), even
+ *      though the wrap is LABELLED `${did}#data-kex` (the label is hard-coded
+ *      in the SDK regardless of the seed).
+ *
+ * This module performs a two-step, idempotent, owner-only migration so the
+ * account converges on the protocol-intended `#data` convention:
+ *
+ *   A. {@link ensureDataSphere} — generate a `#data` keypair (if absent),
+ *      re-publish the did.json with the appended `#data` + `#data-kex` entries
+ *      (root-signed) via the additive `aithos.augment_identity` primitive.
+ *
+ *   B. {@link rekeyLegacyCollections} — for each collection, unwrap the CMK
+ *      with the (auto-discovered) legacy sphere seed, re-wrap the SAME CMK to
+ *      the `#data` X25519 key (label unchanged: `${did}#data-kex`), and persist
+ *      via the existing `aithos.data.rotate_cmk` primitive. The CMK value is
+ *      unchanged, so per-record DEKs stay valid — no record rewrap. Delegate
+ *      wraps are preserved.
+ *
+ * Guardrails: dry-run mode, a pre-mutation backup of every `cmk_envelope`, a
+ * LOCAL round-trip verification (the freshly built `#data` wrap is unwrapped
+ * with the data seed and checked byte-equal to the CMK) BEFORE any server
+ * write, and idempotence (a collection already readable under `#data` is left
+ * untouched).
+ *
+ * Nothing here mutates any existing handler or primitive: A uses the new
+ * additive `aithos.augment_identity`, B reuses the existing `rotate_cmk`.
+ */
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha2.js";
+import { browserIdentityFromStored, signedDidDocument, } from "@aithos/protocol-client";
+import { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
+import { DEFAULT_API_BASE_URL } from "./auth.js";
+import { signOwnerEnvelope } from "./internal/envelope.js";
+import { parseRecoveryFile, serializeRecoveryFile, } from "./internal/recovery-file.js";
+import { ed25519SeedToX25519PrivateKey, ed25519SeedToX25519PublicKey, tryUnwrapCmk, wrapCmkForRecipient, } 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));
+/* -------------------------------------------------------------------------- */
+/*  A — ensureDataSphere                                                      */
+/* -------------------------------------------------------------------------- */
+/**
+ * Idempotently add the `#data` sphere to a (possibly legacy) identity and
+ * re-publish its did.json. Accepts either a parsed recovery file or the raw
+ * recovery JSON text.
+ */
+export async function ensureDataSphere(owner, opts = {}) {
+    const rec = typeof owner === "string" ? parseRecoveryFile(owner) : owner;
+    const fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    const apiBaseUrl = (opts.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/$/, "");
+    opts.onProgress?.({ phase: "ensure-data-sphere", status: "start" });
+    // Generate a #data seed if the recovery file doesn't carry one yet.
+    const hadData = typeof rec.seedsHex.data === "string";
+    const dataSeedHex = hadData ? rec.seedsHex.data : bytesToHex(randomSeed32());
+    // Rebuild the full identity (incl. #data) and produce a root-signed did.json
+    // that carries the appended #data + #data-kex entries.
+    const identity = browserIdentityFromStored({
+        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,
+            data: dataSeedHex,
+        },
+    });
+    const signedDoc = signedDidDocument(identity);
+    // Publish via the additive augment_identity primitive (idempotent server-side).
+    const rootSeed = hexToBytes(rec.seedsHex.root);
+    const url = `${apiBaseUrl}/mcp/primitives/write`;
+    const params = {
+        did_document: signedDoc,
+        handle: rec.handle,
+        display_name: rec.displayName,
+    };
+    const res = await jsonRpc(fetchImpl, url, "aithos.augment_identity", params, {
+        iss: rec.did,
+        aud: url,
+        verificationMethod: `${rec.did}#root`,
+        signSeed: rootSeed,
+    });
+    const added = res.data_sphere_added ?? !hadData;
+    // Merge the #data seed into a recovery file the caller can persist.
+    const updatedRecoveryFile = serializeRecoveryWithData(rec, dataSeedHex);
+    opts.onProgress?.({
+        phase: "ensure-data-sphere",
+        status: added ? "added" : "already-present",
+    });
+    return { did: rec.did, added, dataSeedHex, updatedRecoveryFile };
+}
+/* -------------------------------------------------------------------------- */
+/*  B — rekeyLegacyCollections                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * Re-wrap every collection's CMK from its legacy sphere to the owner's `#data`
+ * key. Idempotent: collections already readable under `#data` are skipped.
+ * Requires that the recovery file carries a `#data` seed (run
+ * {@link ensureDataSphere} first, or pass {@link FullMigrationResult}).
+ */
+export async function rekeyLegacyCollections(owner, opts = {}) {
+    const rec = typeof owner === "string" ? parseRecoveryFile(owner) : owner;
+    if (!rec.seedsHex.data && !opts.targetDataSeedHex) {
+        throw new Error("rekeyLegacyCollections: recovery file has no #data seed. Run ensureDataSphere first and persist its updatedRecoveryFile (or pass targetDataSeedHex for a rotation).");
+    }
+    const fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    const pdsUrl = (opts.pdsUrl ?? DEFAULT_SDK_ENDPOINTS.pds).replace(/\/$/, "");
+    const dryRun = opts.dryRun ?? false;
+    const mode = opts.mode ?? "replace";
+    const did = rec.did;
+    const rootSeed = hexToBytes(rec.seedsHex.root);
+    const dataKexRecipient = `${did}#data-kex`;
+    // Target #data key the wraps will be sealed TO. Defaults to the recovery's
+    // own #data; rotateEthos passes a fresh one (rotation).
+    const targetDataSeed = opts.targetDataSeedHex
+        ? hexToBytes(opts.targetDataSeedHex)
+        : hexToBytes(rec.seedsHex.data); // guard above guarantees one of the two
+    const dataPub = ed25519SeedToX25519PublicKey(targetDataSeed);
+    const dataPriv = ed25519SeedToX25519PrivateKey(targetDataSeed);
+    // Candidate seeds to UNWRAP an existing owner wrap with (auto-discovery). The
+    // target #data key is NOT in this list — "already sealed to target" is
+    // detected separately via `dataPriv`. When rotating (target ≠ recovery
+    // #data), the recovery's OLD #data is a valid unwrap key, included as
+    // "data-old".
+    const candidates = [
+        { name: "self", priv: ed25519SeedToX25519PrivateKey(hexToBytes(rec.seedsHex.self)) },
+        { name: "circle", priv: ed25519SeedToX25519PrivateKey(hexToBytes(rec.seedsHex.circle)) },
+        { name: "public", priv: ed25519SeedToX25519PrivateKey(hexToBytes(rec.seedsHex.public)) },
+        { name: "root", priv: ed25519SeedToX25519PrivateKey(rootSeed) },
+        ...(opts.targetDataSeedHex && rec.seedsHex.data
+            ? [{ name: "data-old", priv: ed25519SeedToX25519PrivateKey(hexToBytes(rec.seedsHex.data)) }]
+            : []),
+    ];
+    const readUrl = `${pdsUrl}/mcp/primitives/read`;
+    const writeUrl = `${pdsUrl}/mcp/primitives/write`;
+    const signRoot = {
+        iss: did,
+        verificationMethod: `${did}#root`,
+        signSeed: rootSeed,
+    };
+    // 1. Enumerate collections.
+    const listed = (await jsonRpc(fetchImpl, readUrl, "aithos.data.list_collections", { subject_did: did }, { ...signRoot, aud: readUrl }));
+    const names = (listed.items ?? []).map((c) => c.name);
+    const collections = [];
+    for (const name of names) {
+        const entry = await rekeyOne({
+            fetchImpl,
+            readUrl,
+            writeUrl,
+            signRoot,
+            did,
+            name,
+            candidates,
+            dataPub,
+            dataPriv,
+            dataKexRecipient,
+            dryRun,
+            mode,
+        });
+        collections.push(entry);
+        opts.onProgress?.({ phase: "rekey", status: "collection", collection: name, result: entry.status });
+    }
+    return { did, dryRun, collections };
+}
+/**
+ * Dual-read onboarding: KEEP each collection's legacy owner wrap and ADD a
+ * second owner wrap sealed to #data, so the existing app (reading under the
+ * legacy key) AND a #data client both decrypt the same data. Non-destructive.
+ * Thin wrapper over {@link rekeyLegacyCollections} with `mode: "add"`.
+ */
+export async function addDataSphereWrap(owner, opts = {}) {
+    return rekeyLegacyCollections(owner, { ...opts, mode: "add" });
+}
+async function rekeyOne(a) {
+    const meta = (await jsonRpc(a.fetchImpl, a.readUrl, "aithos.data.get_collection", { subject_did: a.did, collection_name: a.name }, { ...a.signRoot, aud: a.readUrl }));
+    const urn = meta.urn ?? `urn:aithos:collection:${a.did}:${a.name}`;
+    const env = meta.cmk_envelope;
+    if (!env || !Array.isArray(env.wraps)) {
+        return { name: a.name, urn, status: "skipped-no-owner-wrap" };
+    }
+    // Owner wraps carry the label ${did}#data-kex (delegate wraps use a
+    // did:key:...#data-kex recipient). After a dual-read "add" there can be more
+    // than one owner wrap (legacy-sealed + #data-sealed).
+    const ownerWraps = env.wraps.filter((w) => w.recipient === a.dataKexRecipient);
+    if (ownerWraps.length === 0) {
+        return { name: a.name, urn, status: "skipped-no-owner-wrap", backupEnvelope: env };
+    }
+    const dataPriv = a.dataPriv; // private key of the TARGET #data
+    // Idempotence: is any owner wrap ALREADY readable under the target #data?
+    const alreadyData = ownerWraps.some((w) => tryUnwrapCmk({ wrap: w, collectionUrn: urn, privateKey: dataPriv }) !== null);
+    if (alreadyData) {
+        // add mode: a #data reader already exists → nothing to do.
+        // replace mode: if the SOLE owner wrap is #data we're done; if a legacy
+        // wrap also lingers we still consider it "already-data" (a #data reader
+        // exists) and leave it — replace's job is to *enable* #data, already true.
+        return { name: a.name, urn, status: "already-data", unwrappedWith: "data" };
+    }
+    // Auto-discover the legacy seed that sealed an owner wrap (try each wrap with
+    // each non-#data candidate). #data already excluded by the check above.
+    let cmk = null;
+    let usedSeed;
+    outer: for (const w of ownerWraps) {
+        for (const cand of a.candidates) {
+            const out = tryUnwrapCmk({ wrap: w, collectionUrn: urn, privateKey: cand.priv });
+            if (out) {
+                cmk = out;
+                usedSeed = cand.name;
+                break outer;
+            }
+        }
+    }
+    if (!cmk || !usedSeed) {
+        // Sealed to a key we don't hold (app-derived / foreign) — do NOT touch it.
+        return { name: a.name, urn, status: "unwrap-failed", backupEnvelope: env };
+    }
+    // Build the #data wrap of the SAME CMK (recipient label unchanged).
+    const dataWrap = wrapCmkForRecipient({
+        cmk,
+        recipientPublicKey: a.dataPub,
+        recipientDidUrl: a.dataKexRecipient,
+        collectionUrn: urn,
+    });
+    // GUARDRAIL: verify the new #data wrap round-trips to EXACTLY this CMK before
+    // any server write.
+    const verify = tryUnwrapCmk({ wrap: dataWrap, collectionUrn: urn, privateKey: dataPriv });
+    if (!verify || !bytesEqual(verify, cmk)) {
+        return { name: a.name, urn, status: "unwrap-failed", backupEnvelope: env };
+    }
+    let newEnvelope;
+    let delegateWrapsPreserved;
+    if (a.mode === "add") {
+        // Keep EVERYTHING (legacy owner wrap + delegate wraps) and append #data.
+        newEnvelope = { alg: env.alg, wraps: [...env.wraps, dataWrap] };
+        delegateWrapsPreserved = env.wraps.filter((w) => w.recipient !== a.dataKexRecipient).length;
+    }
+    else {
+        // replace: drop the legacy owner wrap(s), keep delegates, set #data as the
+        // sole owner wrap.
+        const delegateWraps = env.wraps.filter((w) => w.recipient !== a.dataKexRecipient);
+        newEnvelope = { alg: env.alg, wraps: [dataWrap, ...delegateWraps] };
+        delegateWrapsPreserved = delegateWraps.length;
+    }
+    if (a.dryRun) {
+        return { name: a.name, urn, status: "planned", unwrappedWith: usedSeed, delegateWrapsPreserved, backupEnvelope: env };
+    }
+    await jsonRpc(a.fetchImpl, a.writeUrl, "aithos.data.rotate_cmk", { collection_urn: urn, new_cmk_envelope: newEnvelope }, { ...a.signRoot, aud: a.writeUrl });
+    return {
+        name: a.name,
+        urn,
+        status: a.mode === "add" ? "data-wrap-added" : "rekeyed",
+        unwrappedWith: usedSeed,
+        delegateWrapsPreserved,
+        backupEnvelope: env,
+    };
+}
+/* -------------------------------------------------------------------------- */
+/*  Combined helper                                                           */
+/* -------------------------------------------------------------------------- */
+/**
+ * Run the full migration: ensureDataSphere then rekeyLegacyCollections.
+ * Returns the updated recovery file (with the #data seed) — persist it.
+ */
+export async function migrateLegacyEthosToDataSphere(recoveryText, opts = {}) {
+    const ensure = await ensureDataSphere(recoveryText, opts);
+    // Re-parse with the freshly merged #data seed so rekey has it.
+    const recWithData = parseRecoveryFile(ensure.updatedRecoveryFile);
+    const rekey = await rekeyLegacyCollections(recWithData, opts);
+    return { ensure, rekey, updatedRecoveryFile: ensure.updatedRecoveryFile };
+}
+async function jsonRpc(fetchImpl, url, method, params, ctx) {
+    const envelope = await signOwnerEnvelope({
+        iss: ctx.iss,
+        aud: ctx.aud,
+        method,
+        params,
+        verificationMethod: ctx.verificationMethod,
+        signer: { sign: async (msg) => ed.sign(msg, ctx.signSeed) },
+    });
+    const body = {
+        jsonrpc: "2.0",
+        id: `migrate_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+        method,
+        params: { ...params, _envelope: envelope },
+    };
+    const r = await fetchImpl(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    const json = (await r.json());
+    if (json.error) {
+        const err = new Error(`${method} failed: ${json.error.message}`);
+        err.code = json.error.code;
+        err.data = json.error.data;
+        throw err;
+    }
+    return json.result ?? {};
+}
+/* -------------------------------------------------------------------------- */
+/*  Small utils                                                               */
+/* -------------------------------------------------------------------------- */
+function randomSeed32() {
+    const buf = new Uint8Array(32);
+    globalThis.crypto?.getRandomValues(buf);
+    return buf;
+}
+function hexToBytes(hex) {
+    if (hex.length % 2 !== 0)
+        throw new Error("hex must be even-length");
+    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;
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}
+/**
+ * Serialize a recovery file (SDK shape) with the #data seed merged in. We don't
+ * have a BrowserIdentity here, so we build the canonical SDK shape directly —
+ * matching `serializeRecoveryFile`'s output shape (used elsewhere for the
+ * round-trip parse test).
+ */
+function serializeRecoveryWithData(rec, dataSeedHex) {
+    void serializeRecoveryFile; // referenced for shape parity; we emit the same fields
+    const payload = {
+        aithos_recovery_version: "0.1.0-plaintext",
+        handle: rec.handle,
+        display_name: rec.displayName,
+        did: rec.did,
+        seeds_hex: {
+            root: rec.seedsHex.root,
+            public: rec.seedsHex.public,
+            circle: rec.seedsHex.circle,
+            self: rec.seedsHex.self,
+            data: dataSeedHex,
+        },
+        saved_at: new Date().toISOString(),
+    };
+    return JSON.stringify(payload, null, 2);
+}
+//# sourceMappingURL=migrate.js.map