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

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

package/dist/src/rotate.d.ts

@@ -0,0 +1,94 @@
+/** Raw 32-byte seeds for a rotation. `root` is unchanged; the rest are new. */
+export interface RotationSeeds {
+    readonly root: Uint8Array;
+    readonly public: Uint8Array;
+    readonly circle: Uint8Array;
+    readonly self: Uint8Array;
+    /** Optional dedicated #data sphere (added if present). */
+    readonly data?: Uint8Array;
+}
+interface VerificationMethodLike {
+    id: string;
+    type: "Ed25519VerificationKey2020" | "X25519KeyAgreementKey2020";
+    controller: string;
+    publicKeyMultibase: string;
+}
+/** Minimal structural view of a did.json (browser-safe; no node import). */
+export interface DidDocumentLike {
+    "@context": readonly string[];
+    id: string;
+    verificationMethod: readonly VerificationMethodLike[];
+    keyAgreement?: readonly VerificationMethodLike[];
+    aithos: {
+        version: "0.1.0";
+        display_name?: string;
+        created_at: string;
+        rotated: readonly unknown[];
+    };
+    proof?: unknown;
+}
+/**
+ * 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 declare function buildSignedRotatedDidDocument(seeds: RotationSeeds, previousDoc: DidDocumentLike, displayName: string, reason?: string): DidDocumentLike;
+import { type RekeyReport } from "./migrate.js";
+import { type ParsedRecoveryFile } from "./internal/recovery-file.js";
+export interface RotateEthosOptions {
+    /** api.aithos.be base URL. Default {@link DEFAULT_API_BASE_URL}. NOTE: the
+     *  Ethos-zone recopy uses @aithos/protocol-client's ambient endpoint
+     *  (api.aithos.be); a non-default apiBaseUrl only redirects the did.json
+     *  rotation, not the zone publish — keep them aligned (prod) for now. */
+    readonly apiBaseUrl?: string;
+    /** PDS base URL for the collection re-key. Default `https://pds.aithos.be`. */
+    readonly pdsUrl?: string;
+    readonly fetch?: typeof fetch;
+    /** Audit reason recorded in rotated[]. */
+    readonly reason?: string;
+    /**
+     * Skip the Ethos circle/self zone recopy (the live, protocol-client-RPC part).
+     * Used by hermetic tests and by data-only accounts. WARNING: with real
+     * circle/self content, skipping while rotating the sphere keys would orphan
+     * that content — rotateEthos refuses to rotate the Ethos spheres when an
+     * edition exists and zones are skipped (unless `force`).
+     */
+    readonly skipZones?: boolean;
+    /** Override the safety refusal above. */
+    readonly force?: boolean;
+    readonly onProgress?: (msg: string) => void;
+}
+export interface RotateEthosResult {
+    readonly did: string;
+    /** Ethos spheres whose key changed (always public/circle/self here). */
+    readonly rotatedSpheres: readonly string[];
+    /** Whether a fresh edition was republished (zones re-sealed under new keys). */
+    readonly editionRepublished: boolean;
+    /** Whether the account had an Ethos edition at all. */
+    readonly hadEdition: boolean;
+    /** Collection re-key report (dual #data wraps toward the NEW #data). */
+    readonly collections: RekeyReport;
+    /** New recovery file (ALL new sphere seeds + new #data). PERSIST THIS. */
+    readonly updatedRecoveryFile: string;
+}
+/**
+ * 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 declare function rotateEthos(recovery: ParsedRecoveryFile | string, opts?: RotateEthosOptions): Promise<RotateEthosResult>;
+export {};
+//# sourceMappingURL=rotate.d.ts.map