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

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,18 +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) {
+            // 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 — surface the friendly error below
+            }
+        }
         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.`);
+            throw new Error(`sdk.data: schema "${meta.schema}" not known to the SDK and not published ` +
+                `on the PDS for ${this.#did}. Pass it via createDataClient({ schemas: [...] }) ` +
+                `if it's an app-defined (vendor) schema, register it via registerSchema, ` +
+                `or upgrade the SDK if it's a core schema added in a later release.`);
         }
         const state = { name, urn: meta.urn, schema };
         this.#colCache.set(name, state);
@@ -775,6 +811,43 @@ 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: {},
+    };
+}
 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.55";
 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.55";
 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

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;
     };