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

package/README.md

@@ -169,9 +169,11 @@ const { session, passwordMustChange } = await sdk.auth.signInCustodial({
   email: "alice@example.com",
   password: "MyTempPass32chars",
 });
-// Local KeyStore is now hydrated with the 4 Ed25519 sphere seeds —
-// the user can publish ethos editions, mint mandates, invoke compute,
-// exactly as if they had signed in via a recovery file or Google SSO.
+// Local KeyStore is now hydrated with the 5 Ed25519 sphere seeds
+// (root, public, circle, self, #data) — the user can publish ethos
+// editions, mint mandates, invoke compute, and own PDS data/asset
+// collections (signed under the dedicated #data sphere), exactly as if
+// they had signed in via a recovery file or Google SSO.
 if (passwordMustChange) {
   // Optional: nudge the user to set their own password via the
   // standard reset flow.

package/dist/src/assets.d.ts

@@ -39,11 +39,27 @@ export interface CreateAssetsClientArgs {
      * production vanity domain — SEPARATE from the data PDS) when omitted.
      * Override for self-hosting/staging. */
     readonly pdsUrl?: string;
-    /** Subject DID. */
+    /**
+     * Subject DID that owns the assets. The canonical owner is a `did:aithos:…`
+     * account signing under its dedicated `#data` sphere; a `did:key:…` is a
+     * throwaway identity for demos/tests only.
+     */
     readonly did: string;
-    /** Ed25519 sphere seed (32 bytes). */
+    /**
+     * Ed25519 sphere seed (32 bytes) that signs every assets-PDS envelope. For a
+     * `did:aithos` account this MUST be the subject's dedicated **`#data`** sphere
+     * seed (root stays cold). For a `did:key` it is the single embedded key.
+     *
+     * Note: this is the SIGNING key. Per-asset AMKs for private uploads are
+     * wrapped to the attaching context's X25519 key (`#data-kex` / `#circle-kex`
+     * / `#self-kex`) by the RecipientResolver — a separate mechanism.
+     */
     readonly sphereSeed: Uint8Array;
-    /** Verification method URL within the DID document (e.g. `<did>#<multibase>` for did:key). */
+    /**
+     * Verification method URL within the DID document used to sign envelopes.
+     * For a `did:aithos` account this is **`<did>#data`**; for a `did:key` it is
+     * `<did>#<multibase>`.
+     */
     readonly verificationMethod: string;
     /** Optional fetch implementation. Defaults to globalThis.fetch. */
     readonly fetch?: typeof fetch;

package/dist/src/auth.js

@@ -976,33 +976,15 @@ export class AithosAuth {
         }
         // Magic-link sign-in path. Mirror `signInCustodial` to materialise
         // the 4 sphere seeds in the keystore.
-        if (resp.seed.byteLength !== 128) {
-            zeroize(resp.seed);
-            zeroize(resp.encKey);
-            throw new AithosSDKError("auth_custodial_seed_format", `verifyEmail: expected 128-byte seed bundle, got ${resp.seed.byteLength}`);
-        }
-        const seedRoot = resp.seed.slice(0, 32);
-        const seedPublic = resp.seed.slice(32, 64);
-        const seedCircle = resp.seed.slice(64, 96);
-        const seedSelf = resp.seed.slice(96, 128);
         const stored = {
             version: "0.1.0-hex",
             did: resp.did,
             handle: resp.handle,
             displayName: resp.displayName,
-            seedsHex: {
-                root: bytesToHex(seedRoot),
-                public: bytesToHex(seedPublic),
-                circle: bytesToHex(seedCircle),
-                self: bytesToHex(seedSelf),
-            },
+            // Accepts 128 (legacy) or 160 (with #data); zeroizes resp.seed.
+            seedsHex: custodialSeedsHex(resp.seed),
             savedAt: new Date().toISOString(),
         };
-        zeroize(resp.seed);
-        zeroize(seedRoot);
-        zeroize(seedPublic);
-        zeroize(seedCircle);
-        zeroize(seedSelf);
         zeroize(resp.encKey);
         // Bootstrap the Ethos on api.aithos.be (cf. notes in signInCustodial).
         // The magic-link flow is the FIRST time the user actually has
@@ -1106,33 +1088,15 @@ export class AithosAuth {
         });
         // Materialise the 4 sphere seeds + session — same shape as the verifyEmail
         // magic-link path. Kept inline (additive; verifyEmail is left untouched).
-        if (resp.seed.byteLength !== 128) {
-            zeroize(resp.seed);
-            zeroize(resp.encKey);
-            throw new AithosSDKError("auth_custodial_seed_format", `acceptInvite: expected 128-byte seed bundle, got ${resp.seed.byteLength}`);
-        }
-        const seedRoot = resp.seed.slice(0, 32);
-        const seedPublic = resp.seed.slice(32, 64);
-        const seedCircle = resp.seed.slice(64, 96);
-        const seedSelf = resp.seed.slice(96, 128);
         const stored = {
             version: "0.1.0-hex",
             did: resp.did,
             handle: resp.handle,
             displayName: resp.displayName,
-            seedsHex: {
-                root: bytesToHex(seedRoot),
-                public: bytesToHex(seedPublic),
-                circle: bytesToHex(seedCircle),
-                self: bytesToHex(seedSelf),
-            },
+            // Accepts 128 (legacy) or 160 (with #data); zeroizes resp.seed.
+            seedsHex: custodialSeedsHex(resp.seed),
             savedAt: new Date().toISOString(),
         };
-        zeroize(resp.seed);
-        zeroize(seedRoot);
-        zeroize(seedPublic);
-        zeroize(seedCircle);
-        zeroize(seedSelf);
         zeroize(resp.encKey);
         const identity = browserIdentityFromStored({
             handle: stored.handle,
@@ -1212,45 +1176,19 @@ export class AithosAuth {
             throw new AithosSDKError("auth_invalid_input", "signInCustodial: email and password are required");
         }
         const resp = await custodialSignIn({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, input);
-        // Split the 128-byte seed bundle into the four sphere seeds. The
-        // backend lays them out in the canonical order
-        // [root || public || circle || self] (cf. seed-wrapper.ts).
-        if (resp.seed.byteLength !== 128) {
-            // Legacy 32-byte rows shouldn't happen in production (we wiped the
-            // single test row before redeploying with the 4-seed bundle), but
-            // we surface a clear error rather than silently corrupting the
-            // identity.
-            zeroize(resp.seed);
-            zeroize(resp.encKey);
-            throw new AithosSDKError("auth_custodial_seed_format", `signInCustodial: expected 128-byte seed bundle, got ${resp.seed.byteLength}`);
-        }
-        const seedRoot = resp.seed.slice(0, 32);
-        const seedPublic = resp.seed.slice(32, 64);
-        const seedCircle = resp.seed.slice(64, 96);
-        const seedSelf = resp.seed.slice(96, 128);
-        // Stored shape uses hex strings; round-trip through bytesToHex
-        // so the keyStore record is identical to what signUp(zk) writes.
+        // Split the custodial seed bundle into the sphere seeds. The backend
+        // lays them out in the canonical order [root || public || circle || self]
+        // (128 bytes), plus the dedicated #data sphere when migrated (160 bytes).
+        // See seed-wrapper.ts / custodialSeedsHex.
         const stored = {
             version: "0.1.0-hex",
             did: resp.did,
             handle: resp.handle,
             displayName: resp.displayName,
-            seedsHex: {
-                root: bytesToHex(seedRoot),
-                public: bytesToHex(seedPublic),
-                circle: bytesToHex(seedCircle),
-                self: bytesToHex(seedSelf),
-            },
+            // Accepts 128 (legacy, no #data) or 160 (with #data); zeroizes resp.seed.
+            seedsHex: custodialSeedsHex(resp.seed),
             savedAt: new Date().toISOString(),
         };
-        // Zeroize the raw bundle + the split copies now that they've been
-        // serialised into the keyStore record (hex strings live in the
-        // record; the original bytes can go).
-        zeroize(resp.seed);
-        zeroize(seedRoot);
-        zeroize(seedPublic);
-        zeroize(seedCircle);
-        zeroize(seedSelf);
         // The enc_key is informational here — the custodial blob is empty
         // at first login. We still don't keep it in memory.
         zeroize(resp.encKey);
@@ -1507,6 +1445,46 @@ function bytesToHex(b) {
         out += b[i].toString(16).padStart(2, "0");
     return out;
 }
+/**
+ * Split a custodial seed bundle into the keystore's hex seeds, zeroizing the
+ * raw bytes (the bundle and every slice) before returning.
+ *
+ * Two bundle shapes are accepted, in canonical sphere order:
+ *   - 128 bytes = root || public || circle || self            (legacy, no #data)
+ *   - 160 bytes = root || public || circle || self || data    (V2.2+, with #data)
+ *
+ * A 160-byte bundle yields a `data` seed so the custodial owner carries the
+ * dedicated `#data` sphere — identical to a self-custody / SSO account. A
+ * 128-byte bundle (an account the backend hasn't migrated yet) yields no
+ * `data`; the backend upgrades it to 160 on the user's next sign-in.
+ */
+function custodialSeedsHex(seed) {
+    const len = seed.byteLength;
+    if (len !== 128 && len !== 160) {
+        zeroize(seed);
+        throw new AithosSDKError("auth_custodial_seed_format", `expected a 128- or 160-byte custodial seed bundle, got ${len}`);
+    }
+    const root = seed.slice(0, 32);
+    const pub = seed.slice(32, 64);
+    const circle = seed.slice(64, 96);
+    const self = seed.slice(96, 128);
+    const data = len === 160 ? seed.slice(128, 160) : undefined;
+    const hex = {
+        root: bytesToHex(root),
+        public: bytesToHex(pub),
+        circle: bytesToHex(circle),
+        self: bytesToHex(self),
+        ...(data ? { data: bytesToHex(data) } : {}),
+    };
+    zeroize(root);
+    zeroize(pub);
+    zeroize(circle);
+    zeroize(self);
+    if (data)
+        zeroize(data);
+    zeroize(seed);
+    return hex;
+}
 /**
  * Project a delegate as it appears in a `BlobPlaintext` (extension-kit
  * `StoredDelegate` shape) onto the SDK's own {@link StoredDelegateKeys}.

package/dist/src/data.d.ts

@@ -13,18 +13,25 @@ export interface CreateDataClientArgs {
      * staging (e.g. a raw `execute-api` URL).
      */
     readonly pdsUrl?: string;
-    /** Subject DID — typically did:key:… in dev, did:aithos:… in prod. */
+    /**
+     * Subject DID that owns the data. The canonical owner is a `did:aithos:…`
+     * account signing under its dedicated `#data` sphere (see below). A
+     * `did:key:…` is a throwaway identity for quick demos/tests only — it has no
+     * sphere separation (every sphere collapses to the single embedded key).
+     */
     readonly did: string;
     /**
-     * Ed25519 sphere seed (32 bytes). For did:key this is the same as
-     * the key embedded in the DID itself. For did:aithos this is the
-     * subject's `#data` (or `#public`) sphere key.
+     * Ed25519 sphere seed (32 bytes) that signs every PDS envelope. For a
+     * `did:aithos` account this MUST be the subject's dedicated **`#data`** sphere
+     * seed — never the root key nor an Ethos sphere — so the root stays cold and
+     * data operations are isolated to their own key. For a `did:key` it is the
+     * single key embedded in the DID.
      */
     readonly sphereSeed: Uint8Array;
     /**
-     * The verification method URL within the DID document used to sign
-     * envelopes. For did:key this is `<did>#<multibase>`. For did:aithos
-     * this is `<did>#data` (or `#public`).
+     * The verification method URL within the DID document used to sign PDS
+     * envelopes. For a `did:aithos` account this is **`<did>#data`**. For a
+     * `did:key` it is `<did>#<multibase>`.
      */
     readonly verificationMethod: string;
     /** Optional fetch implementation. Defaults to globalThis.fetch. */
@@ -339,4 +346,18 @@ export interface CreateAppendDataClientArgs {
  * (insert allowed; get/list/update/delete refused).
  */
 export declare function createAppendDataClient(args: CreateAppendDataClientArgs): AppendOnlyDataClient;
+/**
+ * Derive an {@link AithosSchemaLite} from a PUBLISHED JSON Schema document (the
+ * shape `aithos.data.get_schema` / `registerSchema` round-trip). The field
+ * split is read from the per-property annotations:
+ *   - `aithos:indexable: true` → indexable (server-visible, filter/sort)
+ *   - `aithos:auto: …`         → auto (server-populated, e.g. created_at)
+ *   - anything else            → encrypted (AEAD'd client-side)
+ *
+ * These annotations are authoritative — by convention they mirror the writer's
+ * own lite — so a reader that never bundled the schema can still split records
+ * correctly. `defaults` is left empty (it only matters for inserts; the writer
+ * supplies its own).
+ */
+export declare function liteFromPublishedSchema(doc: object): AithosSchemaLite;
 //# sourceMappingURL=data.d.ts.map

package/dist/src/data.js

@@ -370,8 +370,16 @@ class DataClientImpl {
         const ourRecipient = this.#delegate
             ? delegateRecipientDidUrl(this.#delegate.granteePubkeyMultibase)
             : `${this.#did}#data-kex`;
-        const wrap = meta.cmk_envelope.wraps.find((w) => w.recipient === ourRecipient);
-        if (!wrap) {
+        // A collection may carry MORE THAN ONE wrap under our recipient label —
+        // e.g. after the #data-sphere dual-read migration an owner collection holds
+        // both the legacy-sphere-sealed wrap (kept so the old app keeps reading) and
+        // a #data-sealed wrap (both labelled `${did}#data-kex`). The label alone
+        // can't tell them apart (it's fixed regardless of the sealing key), so we
+        // try EVERY matching wrap with our key and keep the one that actually
+        // decrypts. For the common single-wrap case this is identical to the old
+        // `find` + unwrap behaviour.
+        const matching = meta.cmk_envelope.wraps.filter((w) => w.recipient === ourRecipient);
+        if (matching.length === 0) {
             throw new Error(this.#delegate
                 ? `sdk.data: no CMK wrap for ${ourRecipient} in collection "${name}". ` +
                     `The owner has not authorized this delegate on the collection yet — ` +
@@ -379,20 +387,46 @@ class DataClientImpl {
                 : `sdk.data: no CMK wrap for ${ourRecipient} in collection ${name}. The collection was either created with a different recipient, or this client is not the owner.`);
         }
         const unwrapSeed = this.#delegate ? this.#delegate.delegateSeed : this.#seed;
-        const cmk = this.#unwrapCmk({
-            wrap,
-            collectionUrn: meta.urn,
-            privateKey: ed25519SeedToX25519PrivateKey(unwrapSeed),
-        });
+        const privateKey = ed25519SeedToX25519PrivateKey(unwrapSeed);
+        let cmk;
+        for (const wrap of matching) {
+            try {
+                cmk = this.#unwrapCmk({ wrap, collectionUrn: meta.urn, privateKey });
+                break;
+            }
+            catch {
+                // Wrong wrap for this key (e.g. the legacy-sphere wrap when we hold the
+                // #data key, or vice-versa) — try the next same-label wrap.
+            }
+        }
+        if (!cmk) {
+            throw new Error(`sdk.data: found ${matching.length} CMK wrap(s) for ${ourRecipient} in collection ${name}, ` +
+                `but none could be unwrapped with this client's key. The collection may be sealed to a ` +
+                `different sphere/key than the one this client was constructed with.`);
+        }
         this.#cmkCache.set(name, cmk);
-        const schema = this.#resolveSchema(meta.schema);
+        let schema = this.#resolveSchema(meta.schema);
         if (!schema) {
-            throw new Error(`sdk.data: schema "${meta.schema}" not known to the SDK. ` +
-                `Pass it via createDataClient({ schemas: [...] }) if it's an ` +
-                `app-defined (vendor) schema, or upgrade the SDK if it's a core ` +
-                `schema added in a later release.`);
+            // Auto-resolve a PUBLISHED vendor schema from the PDS. This lets any
+            // up-to-date client read ANY collection whose owner registered its schema
+            // (via registerSchema) without the reading app having to bundle the lite
+            // locally — the published JSON Schema's `aithos:indexable` / `aithos:auto`
+            // annotations are the authoritative field split (they mirror the writer's
+            // lite by convention). Falls through to the error if nothing is published.
+            try {
+                const published = await this.getSchema(meta.schema, { subjectDid: this.#did });
+                if (published)
+                    schema = liteFromPublishedSchema(published);
+            }
+            catch {
+                // network / not-found — leave `schema` undefined (reads still work)
+            }
         }
-        const state = { name, urn: meta.urn, schema };
+        // Do NOT throw when the schema is unknown: reads decrypt from the CMK +
+        // metadata/payload alone (the schema is only needed to SPLIT on write).
+        // Leaving `schema` undefined keeps the collection fully readable; an
+        // insert/update will surface a precise "schema required to write" error.
+        const state = { name, urn: meta.urn, ...(schema ? { schema } : {}), schemaId: meta.schema };
         this.#colCache.set(name, state);
         return state;
     }
@@ -401,7 +435,7 @@ class DataClientImpl {
         const cmk = this.#cmkCache.get(state.name);
         if (!cmk)
             throw new Error("CMK not loaded");
-        const { metadata, payload } = splitRecord(record, state.schema);
+        const { metadata, payload } = splitRecord(record, requireSchema(state));
         const recordId = `record_${makeUlid()}`;
         const encrypted = this.#encryptPayload({
             collectionName: state.name,
@@ -470,7 +504,7 @@ class DataClientImpl {
         const cmk = this.#cmkCache.get(state.name);
         if (!cmk)
             throw new Error("CMK not loaded");
-        const { metadata, payload } = splitRecord(record, state.schema);
+        const { metadata, payload } = splitRecord(record, requireSchema(state));
         const encrypted = this.#encryptPayload({
             collectionName: state.name,
             recordId,
@@ -721,7 +755,7 @@ class DataClientImpl {
         if (!this.#deposit) {
             throw new Error("sdk.data: _insertDeposit called without a deposit session");
         }
-        const { metadata, payload } = splitRecord(record, state.schema);
+        const { metadata, payload } = splitRecord(record, requireSchema(state));
         const recordId = `record_${makeUlid()}`;
         const encrypted = this.#encryptPayloadForOwner({
             collectionName: state.name,
@@ -741,7 +775,7 @@ class DataClientImpl {
     /** Build a local collection state for the deposit path (no server fetch:
      * append clients are not authorized to read collection metadata). */
     _depositCollectionState(name, schema) {
-        return { name, urn: this.#collectionUrn(name), schema };
+        return { name, urn: this.#collectionUrn(name), schema, schemaId: schema.schema };
     }
 }
 class DataCollectionImpl {
@@ -775,6 +809,58 @@ class DataCollectionImpl {
 /* -------------------------------------------------------------------------- */
 /*  Record split (metadata vs payload)                                        */
 /* -------------------------------------------------------------------------- */
+/**
+ * Derive an {@link AithosSchemaLite} from a PUBLISHED JSON Schema document (the
+ * shape `aithos.data.get_schema` / `registerSchema` round-trip). The field
+ * split is read from the per-property annotations:
+ *   - `aithos:indexable: true` → indexable (server-visible, filter/sort)
+ *   - `aithos:auto: …`         → auto (server-populated, e.g. created_at)
+ *   - anything else            → encrypted (AEAD'd client-side)
+ *
+ * These annotations are authoritative — by convention they mirror the writer's
+ * own lite — so a reader that never bundled the schema can still split records
+ * correctly. `defaults` is left empty (it only matters for inserts; the writer
+ * supplies its own).
+ */
+export function liteFromPublishedSchema(doc) {
+    const d = doc;
+    const props = d.properties ?? {};
+    const indexable = new Set();
+    const encrypted = new Set();
+    const auto = new Set();
+    for (const [k, v] of Object.entries(props)) {
+        const hasAuto = v?.["aithos:auto"] !== undefined;
+        const isIndexable = v?.["aithos:indexable"] === true;
+        if (hasAuto)
+            auto.add(k);
+        if (isIndexable)
+            indexable.add(k);
+        if (!isIndexable && !hasAuto)
+            encrypted.add(k);
+    }
+    return {
+        schema: d["aithos:schema"] ?? "",
+        indexable,
+        encrypted,
+        auto,
+        defaults: {},
+    };
+}
+/**
+ * Return the collection's write schema or throw a precise error. Writes need
+ * the schema to split a record into indexable metadata vs encrypted payload (and
+ * so the PDS can validate); reads never call this.
+ */
+function requireSchema(state) {
+    if (!state.schema) {
+        const e = new Error(`sdk.data: writing to "${state.name}" needs its schema "${state.schemaId}", which is ` +
+            `neither bundled in this client (createDataClient({ schemas: [...] })) nor published on ` +
+            `the PDS (registerSchema). Reads work without it — only inserts/updates require it.`);
+        e.code = -32602;
+        throw e;
+    }
+    return state.schema;
+}
 function splitRecord(record, schema) {
     const metadata = {};
     const payload = {};

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.1.0-alpha.44";
+export declare const VERSION = "0.1.0-alpha.56";
 export { AithosSDK } from "./sdk.js";
 export type { AithosSDKConfig } from "./types.js";
 export { AithosSDKError } from "./types.js";
@@ -27,6 +27,8 @@ export type { AudienceSet, AppCreditPackId, CreateAppTopupSessionArgs, CreateApp
 export * as onboarding from "./onboarding.js";
 export { createBrowserIdentity, browserIdentityFromStored, type BrowserIdentity, } from "@aithos/protocol-client";
 export type { Section } from "@aithos/protocol-client";
-export { createDataClient, createDelegateDataClient, createAppendDataClient, type CreateDataClientArgs, type CreateDelegateDataClientArgs, type CreateAppendDataClientArgs, type DataClient, type DataCollection, type ReadonlyDataClient, type ReadonlyDataCollection, type AppendOnlyDataClient, type AppendOnlyDataCollection, type ListOpts, type AithosSchemaLite, } from "./data.js";
+export { createDataClient, createDelegateDataClient, createAppendDataClient, type CreateDataClientArgs, type CreateDelegateDataClientArgs, type CreateAppendDataClientArgs, type DataClient, type DataCollection, type ReadonlyDataClient, type ReadonlyDataCollection, type AppendOnlyDataClient, type AppendOnlyDataCollection, type ListOpts, type AithosSchemaLite, liteFromPublishedSchema, } from "./data.js";
+export { ensureDataSphere, rekeyLegacyCollections, addDataSphereWrap, migrateLegacyEthosToDataSphere, type MigrateOptions, type MigrateProgress, type EnsureDataSphereResult, type RekeyReport, type CollectionRekeyEntry, type CollectionRekeyStatus, type FullMigrationResult, } from "./migrate.js";
+export { buildSignedRotatedDidDocument, rotateEthos, type RotationSeeds, type DidDocumentLike, type RotateEthosOptions, type RotateEthosResult, } from "./rotate.js";
 export { createAssetsClient, AssetsClient, type CreateAssetsClientArgs, type AttachedContext, type AssetUploadInput, type AssetUploadResult, type AssetFetchResult, type AssetBrief, type ListAssetsOpts, type ThumbnailUploadInput, type ThumbnailUploadResult, type RecipientResolver, type RecipientSet, } from "./assets.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -17,7 +17,7 @@
 // Public types specific to the SDK (`AithosSDKConfig`, `AithosSDKError`)
 // are exported from here. Endpoint config (`AithosSdkEndpoints`,
 // `DEFAULT_SDK_ENDPOINTS`) likewise.
-export const VERSION = "0.1.0-alpha.44";
+export const VERSION = "0.1.0-alpha.56";
 export { AithosSDK } from "./sdk.js";
 export { AithosSDKError } from "./types.js";
 // Re-export protocol-client's JSON-RPC error type so consumers can
@@ -68,7 +68,20 @@ export { createBrowserIdentity, browserIdentityFromStored, } from "@aithos/proto
 // `sdk.data` namespace — Aithos data sub-protocol PDS client. Manages
 // the lifecycle of subject-owned, encrypted, schema-validated records.
 // See spec/data/ in the aithos-protocol repo.
-export { createDataClient, createDelegateDataClient, createAppendDataClient, } from "./data.js";
+export { createDataClient, createDelegateDataClient, createAppendDataClient, 
+// Derive an AithosSchemaLite from a published JSON Schema (vendor schemas the
+// client didn't bundle). The SDK uses this internally to auto-resolve unknown
+// collection schemas from the PDS; exported for apps that want it directly.
+liteFromPublishedSchema, } from "./data.js";
+// Legacy `#data` sphere migration — add the dedicated #data sphere to a
+// pre-#data identity and re-wrap its collections' CMK from the legacy sphere
+// to #data. Idempotent, owner-only, dry-run capable. See ./migrate.ts.
+export { ensureDataSphere, rekeyLegacyCollections, addDataSphereWrap, migrateLegacyEthosToDataSphere, } from "./migrate.js";
+// Ethos rotation building blocks — buildSignedRotatedDidDocument produces a
+// root-signed, rotated did.json (all spheres + #data, root unchanged) ready for
+// aithos.rotate_sphere_key. The full rotateEthos orchestration (incl. zone
+// recopy) builds on this. See ./rotate.ts.
+export { buildSignedRotatedDidDocument, rotateEthos, } from "./rotate.js";
 // `sdk.assets` — Aithos assets sub-protocol PDS client. Upload,
 // fetch, list, ref/unref binary content (images, PDFs, audio, video)
 // owned by a subject. AEAD-encrypted per-asset under AMKs wrapped for

package/dist/src/internal/cmk-wrap.d.ts

@@ -0,0 +1,41 @@
+export interface CmkWrap {
+    readonly recipient: string;
+    readonly alg: "x25519-hkdf-sha256-aead";
+    readonly ephemeral_public: string;
+    readonly wrap_nonce: string;
+    readonly wrapped_key: string;
+}
+/** The CMK envelope stored on a collection. */
+export interface CmkEnvelope {
+    readonly alg: string;
+    readonly wraps: CmkWrap[];
+}
+/**
+ * Derive a 32-byte X25519 private key from an Ed25519 seed via SHA-512
+ * truncation + clamping (libsodium crypto_sign_ed25519_sk_to_curve25519).
+ */
+export declare function ed25519SeedToX25519PrivateKey(seed: Uint8Array): Uint8Array;
+export declare function ed25519SeedToX25519PublicKey(seed: Uint8Array): Uint8Array;
+export declare function wrapCmkForRecipient(args: {
+    cmk: Uint8Array;
+    recipientPublicKey: Uint8Array;
+    recipientDidUrl: string;
+    collectionUrn: string;
+}): CmkWrap;
+/**
+ * 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 declare function tryUnwrapCmk(args: {
+    wrap: {
+        recipient: string;
+        ephemeral_public: string;
+        wrap_nonce: string;
+        wrapped_key: string;
+    };
+    collectionUrn: string;
+    privateKey: Uint8Array;
+}): Uint8Array | null;
+//# sourceMappingURL=cmk-wrap.d.ts.map