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

package/dist/src/auth.d.ts

@@ -420,7 +420,7 @@ export declare class AithosAuth {
          * Choose `"root"`, `"circle"`, or `"self"` only if the receiving
          * server specifically expects one of those (rare).
          */
-        readonly sphere?: "root" | "public" | "circle" | "self";
+        readonly sphere?: "root" | "public" | "circle" | "self" | "data";
         /**
          * Envelope lifetime in seconds. Default 60. Aithos servers cap
          * at 300; third-party servers may apply their own cap.

package/dist/src/auth.js

@@ -192,8 +192,9 @@ export class AithosAuth {
         if (sphere !== "root" &&
             sphere !== "public" &&
             sphere !== "circle" &&
-            sphere !== "self") {
-            throw new AithosSDKError("auth_invalid_sphere", `signEnvelope: invalid sphere "${sphere}". Expected one of: root, public, circle, self.`);
+            sphere !== "self" &&
+            sphere !== "data") {
+            throw new AithosSDKError("auth_invalid_sphere", `signEnvelope: invalid sphere "${sphere}". Expected one of: root, public, circle, self, data.`);
         }
         const signer = this.#ownerSigners.signerForSphere(sphere);
         return signOwnerEnvelope({
@@ -412,6 +413,7 @@ export class AithosAuth {
                 public: identity.public.seed,
                 circle: identity.circle.seed,
                 self: identity.self.seed,
+                ...(identity.data ? { data: identity.data.seed } : {}),
             },
             delegates: [],
         });
@@ -462,6 +464,7 @@ export class AithosAuth {
                 public: bytesToHex(identity.public.seed),
                 circle: bytesToHex(identity.circle.seed),
                 self: bytesToHex(identity.self.seed),
+                ...(identity.data ? { data: bytesToHex(identity.data.seed) } : {}),
             },
             savedAt: new Date().toISOString(),
         });
@@ -833,6 +836,7 @@ export class AithosAuth {
                     public: identity.public.seed,
                     circle: identity.circle.seed,
                     self: identity.self.seed,
+                    ...(identity.data ? { data: identity.data.seed } : {}),
                 },
                 delegates: [],
             });
@@ -869,6 +873,7 @@ export class AithosAuth {
                 public: bytesToHex(identity.public.seed),
                 circle: bytesToHex(identity.circle.seed),
                 self: bytesToHex(identity.self.seed),
+                ...(identity.data ? { data: bytesToHex(identity.data.seed) } : {}),
             },
             savedAt: new Date().toISOString(),
         });

package/dist/src/internal/owner-signers.d.ts

@@ -17,6 +17,8 @@ export declare class OwnerSigners {
     readonly public: Signer;
     readonly circle: Signer;
     readonly self: Signer;
+    /** Optional dedicated #data sphere signer (absent on legacy owners). */
+    readonly data?: Signer;
     constructor(args: {
         did: string;
         handle: string;
@@ -25,6 +27,7 @@ export declare class OwnerSigners {
         public: Signer;
         circle: Signer;
         self: Signer;
+        data?: Signer;
     });
     /**
      * Build from a {@link BrowserIdentity}. The seeds inside `identity`
@@ -59,7 +62,7 @@ export declare class OwnerSigners {
      * have the sphere as a string ("public" | "circle" | "self") rather
      * than a typed accessor.
      */
-    signerForSphere(sphere: "root" | "public" | "circle" | "self"): Signer;
+    signerForSphere(sphere: "root" | "public" | "circle" | "self" | "data"): Signer;
     /**
      * Internal — project to a {@link StoredIdentity} for protocol-client
      * interop. Reads seed bytes via {@link RawSeedSigner._unsafeKeyPair}
@@ -71,7 +74,7 @@ export declare class OwnerSigners {
      * @internal
      */
     _unsafeStoredIdentity(): StoredIdentity;
-    /** Zeroize all four private seeds. Idempotent. */
+    /** Zeroize all private seeds. Idempotent. */
     destroy(): void;
     get destroyed(): boolean;
 }

package/dist/src/internal/owner-signers.js

@@ -34,6 +34,8 @@ export class OwnerSigners {
     public;
     circle;
     self;
+    /** Optional dedicated #data sphere signer (absent on legacy owners). */
+    data;
     #destroyed = false;
     constructor(args) {
         this.did = args.did;
@@ -43,6 +45,7 @@ export class OwnerSigners {
         this.public = args.public;
         this.circle = args.circle;
         this.self = args.self;
+        this.data = args.data;
     }
     /**
      * Build from a {@link BrowserIdentity}. The seeds inside `identity`
@@ -59,6 +62,11 @@ export class OwnerSigners {
             public: new RawSeedSigner(identity.public.seed, identity.public.publicKey),
             circle: new RawSeedSigner(identity.circle.seed, identity.circle.publicKey),
             self: new RawSeedSigner(identity.self.seed, identity.self.publicKey),
+            ...(identity.data
+                ? {
+                    data: new RawSeedSigner(identity.data.seed, identity.data.publicKey),
+                }
+                : {}),
         });
     }
     /**
@@ -120,6 +128,11 @@ export class OwnerSigners {
                 return this.circle;
             case "self":
                 return this.self;
+            case "data":
+                if (!this.data) {
+                    throw new Error("OwnerSigners: this owner has no #data sphere (legacy account)");
+                }
+                return this.data;
         }
     }
     /**
@@ -146,11 +159,18 @@ export class OwnerSigners {
                 public: bytesToHexLocal(asRawSeed(this.public, "public")._unsafeKeyPair().seed),
                 circle: bytesToHexLocal(asRawSeed(this.circle, "circle")._unsafeKeyPair().seed),
                 self: bytesToHexLocal(asRawSeed(this.self, "self")._unsafeKeyPair().seed),
+                // Preserve the optional #data seed on vault re-encryption — dropping it
+                // here would silently lose the data sphere on the next delegate-add.
+                ...(this.data
+                    ? {
+                        data: bytesToHexLocal(asRawSeed(this.data, "data")._unsafeKeyPair().seed),
+                    }
+                    : {}),
             },
             savedAt: new Date().toISOString(),
         };
     }
-    /** Zeroize all four private seeds. Idempotent. */
+    /** Zeroize all private seeds. Idempotent. */
     destroy() {
         if (this.#destroyed)
             return;
@@ -158,6 +178,7 @@ export class OwnerSigners {
         this.public.destroy();
         this.circle.destroy();
         this.self.destroy();
+        this.data?.destroy();
         this.#destroyed = true;
     }
     get destroyed() {

package/dist/src/internal/recovery-file.d.ts

@@ -8,6 +8,8 @@ export interface ParsedRecoveryFile {
         readonly public: string;
         readonly circle: string;
         readonly self: string;
+        /** Optional dedicated #data sphere seed (absent on legacy recovery files). */
+        readonly data?: string;
     };
 }
 /**

package/dist/src/internal/recovery-file.js

@@ -44,6 +44,11 @@ export function parseRecoveryFile(text) {
             throw bad(`seeds_hex.${k}: expected 64-char lowercase hex`);
         }
     }
+    // #data is optional (absent on legacy recovery files); validate when present.
+    const dataSeed = seeds["data"];
+    if (dataSeed !== undefined && (typeof dataSeed !== "string" || !HEX_64.test(dataSeed))) {
+        throw bad("seeds_hex.data: expected 64-char lowercase hex");
+    }
     return {
         handle,
         displayName,
@@ -53,6 +58,7 @@ export function parseRecoveryFile(text) {
             public: seeds["public"],
             circle: seeds["circle"],
             self: seeds["self"],
+            ...(typeof dataSeed === "string" ? { data: dataSeed } : {}),
         },
     };
 }
@@ -78,6 +84,7 @@ export function serializeRecoveryFile(identity) {
             public: bytesToHex(identity.public.seed),
             circle: bytesToHex(identity.circle.seed),
             self: bytesToHex(identity.self.seed),
+            ...(identity.data ? { data: bytesToHex(identity.data.seed) } : {}),
         },
         saved_at: new Date().toISOString(),
     };

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

@@ -19,6 +19,12 @@ export interface StoredOwnerKeys {
         readonly public: string;
         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).
+         */
+        readonly data?: string;
     };
     /** ISO-8601 timestamp of the original save. Informational. */
     readonly savedAt: string;

package/dist/src/key-store.js

@@ -213,6 +213,12 @@ function validOwnerOrNull(v) {
         if (s[k].length !== 64)
             return null;
     }
+    // #data is optional (absent on legacy owners); validate only when present.
+    if (s["data"] !== undefined) {
+        if (typeof s["data"] !== "string" || s["data"].length !== 64) {
+            return null;
+        }
+    }
     if (typeof o["savedAt"] !== "string")
         return null;
     return o;

package/dist/test/data-sphere.test.d.ts

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

package/dist/test/data-sphere.test.js

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Tests for the optional #data sphere through the SDK's owner key material:
+// the recovery file and OwnerSigners (vault re-encryption projection).
+// Mirrors the protocol-core / protocol-client data-sphere tests.
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { createBrowserIdentity } from "@aithos/protocol-client";
+import { OwnerSigners } from "../src/internal/owner-signers.js";
+import { serializeRecoveryFile, parseRecoveryFile, } from "../src/internal/recovery-file.js";
+describe("#data sphere — recovery file", () => {
+    it("round-trips the #data seed for a fresh (eager) identity", () => {
+        const id = createBrowserIdentity("alice", "Alice");
+        assert.ok(id.data, "createBrowserIdentity should be eager about #data");
+        const { text } = serializeRecoveryFile(id);
+        const parsed = parseRecoveryFile(text);
+        assert.equal(typeof parsed.seedsHex.data, "string");
+        assert.equal(parsed.seedsHex.data.length, 64);
+    });
+    it("legacy identity without #data serializes/parses without a data seed", () => {
+        const id = { ...createBrowserIdentity("dave", "Dave"), data: undefined };
+        const { text } = serializeRecoveryFile(id);
+        const parsed = parseRecoveryFile(text);
+        assert.equal(parsed.seedsHex.data, undefined);
+    });
+});
+describe("#data sphere — OwnerSigners", () => {
+    it("preserves the #data seed on the vault re-encryption projection", () => {
+        const id = createBrowserIdentity("bob", "Bob");
+        const signers = OwnerSigners.fromBrowserIdentity(id);
+        try {
+            // _unsafeStoredIdentity() is what the vault re-encryption path reads —
+            // dropping #data here would silently lose the sphere on delegate-add.
+            const projected = signers._unsafeStoredIdentity();
+            assert.ok(projected.seeds.data, "#data seed must survive projection");
+            // signerForSphere exposes the #data signer.
+            assert.ok(signers.data, "OwnerSigners.data signer should be present");
+            assert.equal(signers.signerForSphere("data"), signers.data);
+        }
+        finally {
+            signers.destroy();
+        }
+    });
+    it("legacy owner (no #data) → no data signer, signerForSphere('data') throws", () => {
+        const id = { ...createBrowserIdentity("erin", "Erin"), data: undefined };
+        const signers = OwnerSigners.fromBrowserIdentity(id);
+        try {
+            assert.equal(signers.data, undefined);
+            assert.equal(signers._unsafeStoredIdentity().seeds.data, undefined);
+            assert.throws(() => signers.signerForSphere("data"), /no #data sphere/);
+        }
+        finally {
+            signers.destroy();
+        }
+    });
+});
+//# sourceMappingURL=data-sphere.test.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.52",
+  "version": "0.1.0-alpha.53",
   "description": "Aithos SDK — high-level TypeScript developer kit for building agentic apps on the Aithos protocol. Wraps @aithos/protocol-client and exposes the Aithos compute proxy and wallet (Stripe top-up) endpoints.",
   "keywords": [
     "aithos",
@@ -57,7 +57,7 @@
   },
   "peerDependencies": {
     "@aithos/assets-crypto": ">=0.1.0-alpha.1 <0.2.0",
-    "@aithos/protocol-client": "^0.1.0-alpha.18",
+    "@aithos/protocol-client": "^0.1.0-alpha.19",
     "@aithos/protocol-core": ">=0.6.5 <0.7.0",
     "react": "^18.0.0 || ^19.0.0"
   },
@@ -71,7 +71,7 @@
   },
   "devDependencies": {
     "@aithos/assets-crypto": "^0.1.0-alpha.1",
-    "@aithos/protocol-client": "^0.1.0-alpha.18",
+    "@aithos/protocol-client": "^0.1.0-alpha.19",
     "@aithos/protocol-core": ">=0.6.5 <0.7.0",
     "@types/node": "^24.12.2",
     "fake-indexeddb": "^6.2.5",