@aithos/sdk 0.1.0-alpha.6 → 0.1.0-alpha.60

package/dist/src/auth.js

@@ -20,13 +20,17 @@
 // JWT-less sessions (recovery / mandate sign-ins) are valid: the
 // keyStore is the source of truth for "is the user signed in", the
 // JWT is auxiliary for compute/wallet.
-import { buildBlobPlaintext, buildSignedEnvelope, createBrowserIdentity, decryptBlob, DEFAULT_KDF, deriveAuthAndEncKeys, encryptBlob, parseBlob, randomNonce, randomSalt, serializeBlob, signedDidDocument, zeroize, } from "@aithos/protocol-client";
-import { loginChallenge, loginVerify, registerAccount, } from "./auth-api.js";
+import { browserIdentityFromStored, buildBlobPlaintext, buildSignedEnvelope, createBrowserIdentity, decryptBlob, DEFAULT_KDF, deriveAuthAndEncKeys, encryptBlob, parseBlob, randomNonce, randomSalt, serializeBlob, signedDidDocument, zeroize, } from "@aithos/protocol-client";
+import { custodialAccept, custodialInvite, custodialResendVerify, custodialResetFinalize, custodialResetRequest, custodialSignIn, custodialSignUp, custodialVerifyEmail, loginChallenge, loginVerify, putBlob, registerAccount, } from "./auth-api.js";
 import { defaultSessionStore, } from "./session-store.js";
 import { defaultKeyStore, } from "./key-store.js";
 import { parseDelegateBundle, readDelegateBundleText, } from "./internal/delegate-bundle.js";
 import { DelegateActor, DelegateRegistry, } from "./internal/delegate-state.js";
+import { signOwnerEnvelope, } from "./internal/envelope.js";
 import { OwnerSigners } from "./internal/owner-signers.js";
+import { createDataClient, createDelegateDataClient, } from "./data.js";
+import { delegateKeyPair } from "./internal/protocol-client-bridge.js";
+import { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
 import { parseRecoveryFile, readRecoveryFileText, serializeRecoveryFile, } from "./internal/recovery-file.js";
 import { AithosSDKError } from "./types.js";
 /** Default URL of the Aithos auth backend. */
@@ -43,10 +47,21 @@ export class AithosAuth {
     #win;
     #sessionStore;
     #keyStore;
+    #publicKey;
     /** In-memory owner signers — populated after sign-in or `resume`. */
     #ownerSigners = null;
     /** Active delegate registry. */
     #delegates = new DelegateRegistry();
+    /**
+     * In-flight (or just-resolved) `handleCallback()` result. React
+     * StrictMode (dev) double-invokes the mount effect — the URL clean
+     * inside the first call makes the second invocation see a clean URL
+     * and resolve to `null`, with the session it just consumed locked
+     * inside the first promise. Caching the result here lets both
+     * invocations resolve to the same value. Cleared on next mount via
+     * the wrapper's once-per-instance dedup.
+     */
+    #handleCallbackPromise = null;
     constructor(config = {}) {
         this.authBaseUrl = trimSlash(config.authBaseUrl ?? DEFAULT_AUTH_BASE_URL);
         this.apiBaseUrl = trimSlash(config.apiBaseUrl ?? DEFAULT_API_BASE_URL);
@@ -56,6 +71,7 @@ export class AithosAuth {
                 (typeof window !== "undefined" ? window : undefined);
         this.#sessionStore = config.sessionStore ?? defaultSessionStore();
         this.#keyStore = config.keyStore ?? defaultKeyStore();
+        this.#publicKey = config.publicKey;
     }
     /* ------------------------------------------------------------------------ */
     /*  Boot-time hydration                                                      */
@@ -135,6 +151,65 @@ export class AithosAuth {
     canSignAsOwner() {
         return this.#ownerSigners !== null && !this.#ownerSigners.destroyed;
     }
+    /**
+     * Sign an envelope (spec §11.2) as the active owner, to authenticate
+     * a call to a third-party Aithos-aware backend.
+     *
+     * Same primitive that SDK namespaces (`sdk.data`, `sdk.ethos`,
+     * `sdk.mandates`, ...) use internally to sign their own writes to
+     * `api.aithos.be`. Exposed here so apps can sign envelopes for their
+     * own backends — any service that verifies a `SignedEnvelope` per
+     * spec §11.2 (typically using `@aithos/protocol-core/envelope`'s
+     * `verifyEnvelope`) accepts the resulting object.
+     *
+     * The envelope binds the signature to `(iss, aud, method,
+     * params_hash, nonce, iat, exp)`, so it cannot be replayed against a
+     * different endpoint, method, or payload, and expires after
+     * `ttlSeconds` (default 60s, server-side typically caps at 300s).
+     *
+     * Usage:
+     *
+     * ```ts
+     * const envelope = await sdk.auth.signEnvelope({
+     *   aud: "https://api.example.com/v1/widgets",
+     *   method: "myapp.widgets.create",
+     *   params: { name: "Widget #1" },
+     * });
+     * await fetch("https://api.example.com/v1/widgets", {
+     *   method: "POST",
+     *   headers: { "content-type": "application/json" },
+     *   body: JSON.stringify({ ...payload, _envelope: envelope }),
+     * });
+     * ```
+     *
+     * @throws {AithosSDKError} `auth_not_signed_in` if no owner identity
+     *   is loaded (call `signIn` / `signUp` / `signInCustodial` first).
+     * @throws {AithosSDKError} `auth_invalid_sphere` if `sphere` is not
+     *   one of `"root" | "public" | "circle" | "self"`.
+     */
+    async signEnvelope(args) {
+        if (!this.#ownerSigners || this.#ownerSigners.destroyed) {
+            throw new AithosSDKError("auth_not_signed_in", "signEnvelope: no owner is signed in. Call signIn / signUp / signInCustodial first.");
+        }
+        const sphere = args.sphere ?? "public";
+        if (sphere !== "root" &&
+            sphere !== "public" &&
+            sphere !== "circle" &&
+            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({
+            iss: this.#ownerSigners.did,
+            aud: args.aud,
+            method: args.method,
+            params: args.params,
+            verificationMethod: `${this.#ownerSigners.did}#${sphere}`,
+            signer,
+            ttlSeconds: args.ttlSeconds,
+        });
+    }
     canSignAsDelegateFor(did) {
         const a = this.#delegates.findForSubject(did);
         return a !== undefined && !a.destroyed;
@@ -149,6 +224,118 @@ export class AithosAuth {
     _getOwnerSigners() {
         return this.#ownerSigners;
     }
+    /**
+     * Ready-made owner data client bound to the signed-in account, signing +
+     * sealing under the dedicated **`#data`** sphere (the protocol-intended owner
+     * data key). This is the one-liner apps should use instead of hand-rolling
+     * `createDataClient` with a raw seed — hand-rolling with `#root` is exactly
+     * what left legacy collections sealed to the wrong key.
+     *
+     *   const data = auth.ownerDataClient({ schemas: [myVendorLite] });
+     *   await data.collection("notes").insert({ ... });   // owned under #data
+     *
+     * Throws when no owner is signed in, or when the account has no `#data`
+     * sphere (legacy accounts created before #data, or imported from a 4-seed
+     * recovery). Add one first with `rotateEthos` / the migration scripts, then
+     * re-import the resulting recovery — the error message says so.
+     *
+     * @param args.pdsUrl  PDS base URL. Defaults to the SDK default (pds.aithos.be).
+     * @param args.schemas Vendor `AithosSchemaLite` definitions to register for
+     *   WRITES (reads auto-resolve published schemas from the PDS).
+     */
+    ownerDataClient(args = {}) {
+        if (!this.#ownerSigners || this.#ownerSigners.destroyed) {
+            throw new AithosSDKError("auth_not_signed_in", "ownerDataClient: no owner is signed in. Call signIn / signUp / signInCustodial first.");
+        }
+        const stored = this.#ownerSigners._unsafeStoredIdentity();
+        if (!stored.seeds.data) {
+            throw new AithosSDKError("auth_no_data_sphere", "ownerDataClient: this account has no #data sphere, so it cannot own collections under " +
+                "the #data convention. New accounts get one at sign-up; a legacy account (or a 4-seed " +
+                "recovery) must add it first via rotateEthos / the migration scripts, then re-import the " +
+                "resulting recovery (which carries the #data seed).");
+        }
+        return createDataClient({
+            pdsUrl: args.pdsUrl ?? DEFAULT_SDK_ENDPOINTS.pds,
+            did: stored.did,
+            sphereSeed: hexToBytesLocal(stored.seeds.data),
+            verificationMethod: `${stored.did}#data`,
+            ...(args.schemas ? { schemas: args.schemas } : {}),
+            fetch: this.#fetchImpl,
+        });
+    }
+    /**
+     * Ready-made DELEGATE data client, bound to a mandate held in this session
+     * (imported via `importMandate` / an accepted invite). Same record-CRUD
+     * surface as the owner client, bounded by the mandate's scope — you never
+     * pass a key, a sphere, or the mandate itself to the data calls.
+     *
+     *   const db = auth.delegateDataClient();            // single active mandate
+     *   await db.collection("prospects").insert({ ... }); // needs data.prospects.write
+     *
+     * With several active mandates, pass `{ subjectDid }` or `{ mandateId }`.
+     * Owner-only ops (createCollection, authorizeDelegate, …) throw -32042 — the
+     * owner does those once, at onboarding.
+     */
+    delegateDataClient(args = {}) {
+        let actor;
+        if (args.mandateId) {
+            actor = this.#delegates.get(args.mandateId);
+        }
+        else if (args.subjectDid) {
+            actor = this.#delegates.findForSubject(args.subjectDid);
+        }
+        else {
+            const all = this.#delegates.list();
+            if (all.length === 1) {
+                actor = all[0];
+            }
+            else if (all.length === 0) {
+                throw new AithosSDKError("auth_no_delegate", "delegateDataClient: no mandate imported in this session. Call importMandate / accept an invite first.");
+            }
+            else {
+                throw new AithosSDKError("auth_ambiguous_delegate", `delegateDataClient: ${all.length} mandates are active — pass { subjectDid } or { mandateId } to choose one.`);
+            }
+        }
+        if (!actor || actor.destroyed) {
+            throw new AithosSDKError("auth_no_delegate", "delegateDataClient: the requested mandate is not active in this session.");
+        }
+        return createDelegateDataClient({
+            pdsUrl: args.pdsUrl ?? DEFAULT_SDK_ENDPOINTS.pds,
+            subjectDid: actor.subjectDid,
+            mandate: actor.mandate,
+            delegateSeed: delegateKeyPair(actor).seed,
+            granteePubkeyMultibase: actor.granteePubkeyMultibase,
+            ...(args.schemas ? { schemas: args.schemas } : {}),
+            fetch: this.#fetchImpl,
+        });
+    }
+    /**
+     * Unified data accessor — the database for "however you connected":
+     *   - signed in as owner            → your own collections under `#data`;
+     *   - acting under an imported mandate → the subject's collections (per scope).
+     *
+     * Identical CRUD surface either way; the developer never sees a sphere, a
+     * key, or the mandate. The mode follows how you authenticated, not a flag on
+     * the data calls.
+     *
+     *   const db = auth.data;
+     *   await db.collection("prospects").insert({ ... });
+     *
+     * Only ambiguous when you are BOTH signed in as owner AND holding mandates;
+     * then call `ownerDataClient()` / `delegateDataClient({ … })` explicitly.
+     */
+    get data() {
+        const ownerActive = !!this.#ownerSigners && !this.#ownerSigners.destroyed;
+        const delegateCount = this.#delegates.list().length;
+        if (ownerActive && delegateCount === 0)
+            return this.ownerDataClient();
+        if (!ownerActive && delegateCount >= 1)
+            return this.delegateDataClient();
+        if (ownerActive && delegateCount >= 1) {
+            throw new AithosSDKError("auth_data_ambiguous", "auth.data: both an owner and delegate mandate(s) are active. Use ownerDataClient() or delegateDataClient({ … }) explicitly.");
+        }
+        throw new AithosSDKError("auth_not_signed_in", "auth.data: no owner signed in and no mandate imported. Call signIn / signUp or importMandate first.");
+    }
     /**
      * Internal accessor — looks up an active delegate by mandate id.
      * @internal
@@ -166,6 +353,63 @@ export class AithosAuth {
         return this.#delegates.findForSubject(did);
     }
     /* ------------------------------------------------------------------------ */
+    /*  Unified email + password — signInAuto (zk / custodial dispatch)         */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Sign in with email + password, dispatching automatically between
+     * the legacy zero-knowledge flow ({@link signIn}) and the custodial
+     * flow ({@link signInCustodial}) based on which mode the account
+     * was provisioned with.
+     *
+     * Use this in apps that want a single sign-in form for users who
+     * may have been created under either mode (e.g. an app that's
+     * migrating from zk to custodial — pre-existing users stay zk
+     * forever, new ones go custodial, the SDK figures it out).
+     *
+     * Strategy: try {@link signInCustodial} first (the modern path).
+     * If the backend reports `auth_invalid_credentials` — which it
+     * uniformly returns for "wrong password", "unknown user", AND
+     * "user exists but not in custodial mode" (anti-enum) — fall
+     * back to {@link signIn} (zk).
+     *
+     * Other failure modes from the custodial path are NOT swallowed:
+     *   - `auth_email_not_verified` → propagate (user is custodial but
+     *     hasn't clicked the confirmation link yet; the app should
+     *     surface a "resend mail" CTA rather than retrying as zk,
+     *     which would also fail and mask the real cause)
+     *   - server / network errors → propagate (don't double the
+     *     incident by retrying through the other flow)
+     *
+     * Latency profile:
+     *   - Pure custodial (success or wrong pwd) : 1 round-trip
+     *   - Pure zk (any outcome)                 : 1 custodial probe + 2 zk
+     *   - Unknown email                         : same as zk worst case
+     *
+     * Anti-enum note: timing slightly leaks the mode (custodial path is
+     * faster than zk). Acceptable for V1 — rate limiting + strong
+     * passwords are the real defenses. A future strict-anti-enum mode
+     * could race both paths in parallel and accept the 2x backend load.
+     */
+    async signInAuto(input) {
+        if (!input.email || !input.password) {
+            throw new AithosSDKError("auth_invalid_input", "signInAuto: email and password are required");
+        }
+        try {
+            const r = await this.signInCustodial(input);
+            return r.session;
+        }
+        catch (e) {
+            // Only fall back on the specific anti-enum sentinel — preserve
+            // other error codes (notably auth_email_not_verified) so the
+            // caller can surface the right UI hint.
+            if (e instanceof AithosSDKError &&
+                e.code === "auth_invalid_credentials") {
+                return await this.signIn(input);
+            }
+            throw e;
+        }
+    }
+    /* ------------------------------------------------------------------------ */
     /*  Email + password — signIn                                                */
     /* ------------------------------------------------------------------------ */
     async signIn(input) {
@@ -284,6 +528,7 @@ export class AithosAuth {
                 public: identity.public.seed,
                 circle: identity.circle.seed,
                 self: identity.self.seed,
+                ...(identity.data ? { data: identity.data.seed } : {}),
             },
             delegates: [],
         });
@@ -334,6 +579,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(),
         });
@@ -445,6 +691,13 @@ export class AithosAuth {
         if (!this.#win) {
             throw new AithosSDKError("auth_no_window", "AithosAuth.signInWithGoogle requires a browser window");
         }
+        // appId + returnTo must come together — the backend rejects
+        // half-presence at /sso/google/start. Surface that as a clean SDK
+        // error before the network round-trip rather than letting the user
+        // bounce to Google and back for nothing.
+        if ((opts?.appId && !opts?.returnTo) || (!opts?.appId && opts?.returnTo)) {
+            throw new AithosSDKError("auth_sso_app_redirect_pair_required", "appId and returnTo must be provided together (or both omitted to use the legacy redirect)");
+        }
         const url = new URL(`${this.authBaseUrl}/auth/sso/google/start`);
         if (opts?.appState) {
             if (opts.appState.length > 1024) {
@@ -452,10 +705,48 @@ export class AithosAuth {
             }
             url.searchParams.set("app_state", opts.appState);
         }
+        if (opts?.appId && opts?.returnTo) {
+            url.searchParams.set("app_id", opts.appId);
+            url.searchParams.set("redirect_uri", opts.returnTo);
+        }
         this.#win.location.assign(url.toString());
         throw new AithosSDKError("auth_redirecting", "redirecting to google");
     }
+    /**
+     * Public entrypoint — dedupes concurrent calls (React StrictMode).
+     * The first call kicks off the actual exchange; subsequent calls
+     * before that promise resolves return the SAME promise so they all
+     * receive the same `AithosSession | null`. Otherwise StrictMode's
+     * second invocation would race against the URL clean done by the
+     * first call and resolve to `null`, robbing the AuthCallback page
+     * of the session it actually obtained.
+     */
     async handleCallback() {
+        if (!this.#win)
+            return null;
+        if (this.#handleCallbackPromise)
+            return this.#handleCallbackPromise;
+        const p = this.#doHandleCallback();
+        this.#handleCallbackPromise = p;
+        // Clear the cache once the promise settles so a subsequent
+        // signInWithGoogle round-trip on the same AithosAuth instance can
+        // process its own callback. We use `then(cleanup, cleanup)`
+        // rather than `finally(...)` because `finally` re-throws — without
+        // a downstream `.catch` the resulting promise becomes an
+        // unhandledrejection when `p` itself rejects (the caller already
+        // surfaces that rejection via the returned `p`). `then(success,
+        // error)` converts a rejection into a clean resolution on this
+        // side-effect chain so node:test doesn't flag the orphan as a
+        // failure.
+        const clear = () => {
+            if (this.#handleCallbackPromise === p) {
+                this.#handleCallbackPromise = null;
+            }
+        };
+        p.then(clear, clear);
+        return p;
+    }
+    async #doHandleCallback() {
         if (!this.#win)
             return null;
         const here = new URL(this.#win.location.href);
@@ -468,8 +759,16 @@ export class AithosAuth {
         }
         if (!code)
             return null;
-        const session = await this.exchange(code);
+        // Strip the aithos_code from the URL SYNCHRONOUSLY, before any
+        // await. React StrictMode (dev) invokes effects twice — without
+        // this, the first call awaits exchange (microtask, code still in
+        // the URL), the second invocation reads the same code and POSTs
+        // again, hitting `auth_code_consumed: aithos_code expired or
+        // already used`. Cleaning before the await makes the second
+        // invocation read a clean URL and return null without a network
+        // round-trip.
         cleanCallbackParams(this.#win, here);
+        const session = await this.exchange(code);
         // Hydrate signers if the SSO response carried an enc_key (Google flow
         // gives us the AES-GCM key in plaintext, encrypted only in transit
         // by TLS — see auth.aithos.be design doc).
@@ -485,34 +784,44 @@ export class AithosAuth {
                     const blobBytes = decryptBlob(encKey, nonce, blob);
                     try {
                         const plaintext = parseBlob(blobBytes);
-                        if (plaintext.identity.did === session.did) {
-                            if (this.#ownerSigners)
-                                this.#ownerSigners.destroy();
-                            this.#ownerSigners = OwnerSigners.fromBlobPlaintext(plaintext);
-                            await this.#keyStore.saveOwner({
-                                version: "0.1.0-hex",
-                                did: plaintext.identity.did,
-                                handle: plaintext.identity.handle,
-                                displayName: plaintext.identity.displayName,
-                                seedsHex: plaintext.seeds,
-                                savedAt: new Date().toISOString(),
-                            });
-                            await this.#keyStore.clearAllDelegates();
-                            this.#delegates.destroy();
-                            for (const d of plaintext.delegates) {
-                                const stored = storedDelegateFromBlob(d);
-                                try {
-                                    await this.#keyStore.saveDelegate(stored);
-                                }
-                                catch {
-                                    /* keep going */
-                                }
-                                try {
-                                    this.#delegates.add(DelegateActor.fromStored(stored));
-                                }
-                                catch {
-                                    /* keep going */
-                                }
+                        // Earlier versions of the SDK gated hydration on
+                        // `plaintext.identity.did === session.did` as a defense
+                        // against tampered sessionStores. The check breaks SSO
+                        // flows: the auth backend assigns a placeholder random
+                        // DID at user-record creation time (no client keypair on
+                        // hand), but the BLOB is built around a real
+                        // BrowserIdentity whose DID is derived from its root
+                        // pubkey. The two intentionally differ — the blob is the
+                        // truth source for everything downstream (signing, DID
+                        // resolution against api.aithos.be), the session.did is
+                        // just auth-side bookkeeping. Drop the check and trust
+                        // the blob.
+                        if (this.#ownerSigners)
+                            this.#ownerSigners.destroy();
+                        this.#ownerSigners = OwnerSigners.fromBlobPlaintext(plaintext);
+                        await this.#keyStore.saveOwner({
+                            version: "0.1.0-hex",
+                            did: plaintext.identity.did,
+                            handle: plaintext.identity.handle,
+                            displayName: plaintext.identity.displayName,
+                            seedsHex: plaintext.seeds,
+                            savedAt: new Date().toISOString(),
+                        });
+                        await this.#keyStore.clearAllDelegates();
+                        this.#delegates.destroy();
+                        for (const d of plaintext.delegates) {
+                            const stored = storedDelegateFromBlob(d);
+                            try {
+                                await this.#keyStore.saveDelegate(stored);
+                            }
+                            catch {
+                                /* keep going */
+                            }
+                            try {
+                                this.#delegates.add(DelegateActor.fromStored(stored));
+                            }
+                            catch {
+                                /* keep going */
                             }
                         }
                     }
@@ -561,6 +870,549 @@ export class AithosAuth {
         return (await res.json());
     }
     /* ------------------------------------------------------------------------ */
+    /*  Complete SSO first login                                                 */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Finish the first-time Google SSO bootstrap. After
+     * `signInWithGoogle()` + `handleCallback()`, a brand-new SSO user has
+     * a session JWT and an `enc_key` released by the auth backend, but
+     * NO Aithos identity yet (no Ed25519 seeds, no published did.json,
+     * no blob in the auth vault). This method closes that gap:
+     *
+     *   1. Generates a fresh {@link BrowserIdentity} client-side (4
+     *      Ed25519 keypairs, derived DID).
+     *   2. Calls `aithos.publish_identity` on api.aithos.be so reads
+     *      and writes against the Aithos primitives have an ethos to
+     *      anchor to.
+     *   3. AES-GCM-encrypts the seeds with the session's `enc_key`,
+     *      PUTs the result to `/auth/blob`. From now on, every Google
+     *      sign-in for this user will receive the encrypted blob and
+     *      hydrate locally.
+     *   4. Hydrates `ownerSigners` + `keyStore` so `canSignAsOwner()`
+     *      flips to true.
+     *   5. Returns a recovery-file Blob — the only material that can
+     *      restore this ethos if Google access is lost.
+     *
+     * Preconditions:
+     *   - `getCurrentSession()` returns a non-null session (caller went
+     *     through `handleCallback()` already).
+     *   - The session's `blob_version` is 0 (i.e. no blob yet).
+     *   - The session's `enc_key_b64` is non-empty.
+     *
+     * Throws `AithosSDKError("auth_sso_no_pending_first_login", …)` if
+     * preconditions don't hold (e.g. blob_version > 0 means the user has
+     * already completed setup; nothing to do).
+     */
+    async completeSsoFirstLogin(input) {
+        if (!/^[a-z0-9][a-z0-9_-]{0,62}$/i.test(input.handle)) {
+            throw new AithosSDKError("auth_invalid_handle", "handle must be 1–63 alphanumeric chars + _ -");
+        }
+        const displayName = input.displayName ?? input.handle;
+        const session = this.#sessionStore.get();
+        if (!session) {
+            throw new AithosSDKError("auth_sso_no_pending_first_login", "no active session — sign in via Google first");
+        }
+        if (!session.enc_key_b64) {
+            throw new AithosSDKError("auth_sso_no_pending_first_login", "session does not carry an enc_key (not an SSO-flow session?)");
+        }
+        if (session.blob_version > 0) {
+            throw new AithosSDKError("auth_sso_no_pending_first_login", "this session already has a published blob — nothing to bootstrap");
+        }
+        // 1. Fresh identity client-side. The DID derived here is the
+        //    truth source from now on — the placeholder DID stamped in
+        //    the user record by the auth Lambda is left as-is (auth-side
+        //    bookkeeping; never used for signing).
+        const identity = createBrowserIdentity(input.handle, displayName);
+        const recoverySerialized = serializeRecoveryFile(identity);
+        const recoveryFile = new Blob([recoverySerialized.text], {
+            type: "application/json",
+        });
+        // 2. publish_identity on api.aithos.be — reuses the alpha.6
+        //    helper. Must succeed before we persist anything locally:
+        //    a half-completed bootstrap (blob uploaded but identity not
+        //    published) would leave the user with seeds they can't use.
+        await this.#publishIdentity(identity);
+        // 3. Encrypt the seeds with the SSO-released enc_key and PUT
+        //    /auth/blob. The auth Lambda accepts the new blob_version=1
+        //    and stores the bytes verbatim.
+        const encKey = b64ToBytes(session.enc_key_b64);
+        let blob;
+        let blobNonce;
+        let plaintext;
+        try {
+            plaintext = buildBlobPlaintext({
+                identity: {
+                    did: identity.did,
+                    handle: identity.handle,
+                    displayName: identity.displayName,
+                },
+                seeds: {
+                    root: identity.root.seed,
+                    public: identity.public.seed,
+                    circle: identity.circle.seed,
+                    self: identity.self.seed,
+                    ...(identity.data ? { data: identity.data.seed } : {}),
+                },
+                delegates: [],
+            });
+            const blobBytes = serializeBlob(plaintext);
+            blobNonce = randomNonce();
+            blob = encryptBlob(encKey, blobNonce, blobBytes);
+        }
+        finally {
+            zeroize(encKey);
+        }
+        const newBlobVersion = 1;
+        try {
+            await putBlob({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, {
+                jwt: session.session,
+                blob,
+                blobNonce,
+                blobVersion: newBlobVersion,
+            });
+        }
+        catch (e) {
+            throw new AithosSDKError("auth_sso_blob_upload_failed", `couldn't store the encrypted vault on auth.aithos.be: ${e.message ?? "unknown"}`);
+        }
+        // 4. Hydrate in-memory state from the fresh identity.
+        if (this.#ownerSigners)
+            this.#ownerSigners.destroy();
+        this.#ownerSigners = OwnerSigners.fromBrowserIdentity(identity);
+        await this.#keyStore.saveOwner({
+            version: "0.1.0-hex",
+            did: identity.did,
+            handle: identity.handle,
+            displayName: identity.displayName,
+            seedsHex: {
+                root: bytesToHex(identity.root.seed),
+                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(),
+        });
+        // 5. Persist the updated session — same JWT, but now carrying
+        //    the freshly-built blob bytes so a subsequent `resume()` can
+        //    rehydrate without another /auth/blob round-trip.
+        const refreshed = {
+            ...session,
+            blob_b64: bytesToB64Public(blob),
+            blob_nonce_b64: bytesToB64Public(blobNonce),
+            blob_version: newBlobVersion,
+        };
+        this.#sessionStore.set(refreshed);
+        return {
+            session: refreshed,
+            recoveryFile,
+            recoveryFilename: recoverySerialized.filename,
+        };
+    }
+    /* ------------------------------------------------------------------------ */
+    /*  Custodial flow (V2 — see PLATFORM-AUTH-PASSWORD-V2-PLAN.md)             */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Provision a custodial-mode account on behalf of a registered app.
+     *
+     * Two integration patterns:
+     *   - **Frontend-only** apps : set `publicKey` on the constructor
+     *     (or on this call). Safe to ship in browser bundles — the
+     *     backend gates each request by Origin + IP rate limit.
+     *   - **Backend-fronted** apps : the backend passes `apiKey` (secret
+     *     Bearer); the browser never sees the credential.
+     *
+     * The created account is in a *pending* state — sign-in stays blocked
+     * until the user clicks the confirmation link sent to their inbox.
+     * Call {@link verifyEmail} from the page mounted on
+     * `app.verify_base_url` to consume the token; afterwards
+     * {@link signInCustodial} works.
+     *
+     * Errors map to `AithosSDKError` codes:
+     *   - `auth_missing_api_key`         (no credential provided)
+     *   - `auth_invalid_api_key`         (Bearer rejected by backend)
+     *   - `auth_invalid_public_key`      (public key rejected by backend)
+     *   - `auth_api_key_revoked` / `auth_public_key_revoked`
+     *   - `auth_origin_not_allowed`      (public key + Origin not in allowlist)
+     *   - `auth_password_too_weak`       (400 — server-side strength check)
+     *   - `auth_email_exists`            (409 — email already registered)
+     *   - `auth_email_invalid`           (400 — bad email format)
+     *   - `auth_mail_send_failed`        (502 — DDB row exists but SES failed)
+     *   - `auth_custodial_signup_failed` (catch-all)
+     */
+    async signUpCustodial(input) {
+        if (!input.email) {
+            throw new AithosSDKError("auth_invalid_input", "signUpCustodial: email is required");
+        }
+        if (!input.password) {
+            throw new AithosSDKError("auth_invalid_input", "signUpCustodial: password is required");
+        }
+        const apiKey = input.apiKey;
+        const publicKey = input.publicKey ?? this.#publicKey;
+        if (!apiKey && !publicKey) {
+            throw new AithosSDKError("auth_missing_api_key", "signUpCustodial: pass apiKey, or publicKey, or set publicKey on the AithosAuth constructor");
+        }
+        return custodialSignUp({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, {
+            email: input.email,
+            password: input.password,
+            ...(apiKey ? { apiKey } : {}),
+            ...(apiKey ? {} : publicKey ? { publicKey } : {}),
+            ...(input.displayName ? { displayName: input.displayName } : {}),
+            ...(input.handleHint ? { handleHint: input.handleHint } : {}),
+        });
+    }
+    /**
+     * Magic-link auto-signin: consume the verification token from the
+     * confirmation link, KMS-unwrap the seed bundle server-side, and
+     * hydrate the local session + keystore in one round-trip.
+     *
+     * Outcome depends on the link's state:
+     *   - First click on a fresh link → returns
+     *     `{ status: "signed_in", session, … }`. The session store is
+     *     populated, the owner signers are loaded — the user is signed
+     *     in. The caller should navigate them to a logged-in route.
+     *   - Click of an already-consumed link → returns
+     *     `{ status: "already_verified", email }`. No session is minted;
+     *     the user must sign in via {@link signInCustodial}.
+     *
+     * Mount this on the page declared as `verify_base_url` in your app's
+     * registration. Read `email` + `token` from `window.location.search`,
+     * call this, branch on `result.status`.
+     *
+     * Throws `auth_token_invalid_or_expired` if the token is wrong or
+     * past its 1h TTL — surface a "request a fresh link" CTA in that case.
+     */
+    async verifyEmail(input) {
+        if (!input.email || !input.token) {
+            throw new AithosSDKError("auth_invalid_input", "verifyEmail: email and token are required");
+        }
+        const resp = await custodialVerifyEmail({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, input);
+        if (resp.status === "already_verified") {
+            return { status: "already_verified", email: resp.email };
+        }
+        // Magic-link sign-in path. Mirror `signInCustodial` to materialise
+        // the 4 sphere seeds in the keystore.
+        const stored = {
+            version: "0.1.0-hex",
+            did: resp.did,
+            handle: resp.handle,
+            displayName: resp.displayName,
+            // Accepts 128 (legacy) or 160 (with #data); zeroizes resp.seed.
+            seedsHex: custodialSeedsHex(resp.seed),
+            savedAt: new Date().toISOString(),
+        };
+        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
+        // hydrated keys client-side, so this is typically when the identity
+        // gets published. Idempotent — safe to call again on subsequent
+        // clicks (which won't get here normally, but defensively).
+        const identity = browserIdentityFromStored({
+            handle: stored.handle,
+            displayName: stored.displayName,
+            did: stored.did,
+            seeds: stored.seedsHex,
+        });
+        await this.#publishIdentity(identity);
+        if (this.#ownerSigners)
+            this.#ownerSigners.destroy();
+        this.#ownerSigners = OwnerSigners.fromStoredOwnerKeys(stored);
+        await this.#keyStore.saveOwner(stored);
+        const session = {
+            session: resp.session,
+            exp: resp.exp,
+            did: resp.did,
+            handle: resp.handle,
+            blob_b64: bytesToB64Public(resp.blob),
+            blob_nonce_b64: bytesToB64Public(resp.blobNonce),
+            blob_version: resp.blobVersion,
+            enc_key_b64: "",
+            is_first_login: false,
+        };
+        this.#sessionStore.set(session);
+        return { status: "signed_in", session, passwordMustChange: false };
+    }
+    /**
+     * Send an invitation magic link carrying a mandate. The issuer (owner)
+     * mints any mandate via {@link AithosSDK.mandates} (read/write/append/…),
+     * then calls this with the bundle: the auth backend stores it bound to a
+     * single-use token and emails the magic link. The mandate (and its delegate
+     * seed) never ride the email URL. The invitee redeems it via
+     * {@link acceptInvite}.
+     *
+     * Generic — knows nothing about the mandate's scope. Authenticate with
+     * `apiKey` (server) or `publicKey` (browser, Origin-gated).
+     */
+    async inviteCustodial(input) {
+        if (!input.email) {
+            throw new AithosSDKError("auth_invalid_input", "inviteCustodial: email is required");
+        }
+        if (input.mandateBundle === undefined || input.mandateBundle === null) {
+            throw new AithosSDKError("auth_invalid_input", "inviteCustodial: mandateBundle is required");
+        }
+        const apiKey = input.apiKey;
+        const publicKey = input.publicKey ?? this.#publicKey;
+        if (!apiKey && !publicKey) {
+            throw new AithosSDKError("auth_missing_api_key", "inviteCustodial: pass apiKey, or publicKey, or set publicKey on the AithosAuth constructor");
+        }
+        // Normalize the bundle to a JSON string (the opaque invite payload).
+        let invitePayload;
+        if (typeof input.mandateBundle === "string") {
+            invitePayload = input.mandateBundle;
+        }
+        else if (input.mandateBundle instanceof Blob) {
+            invitePayload = await input.mandateBundle.text();
+        }
+        else {
+            invitePayload = JSON.stringify(input.mandateBundle);
+        }
+        const result = await custodialInvite({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, {
+            email: input.email,
+            invitePayload,
+            ...(apiKey ? { apiKey } : publicKey ? { publicKey } : {}),
+            ...(input.ttlSeconds !== undefined ? { ttlSeconds: input.ttlSeconds } : {}),
+            ...(input.displayName ? { displayName: input.displayName } : {}),
+        });
+        return {
+            status: "invited",
+            email: result.email,
+            mailSent: result.mailSent,
+            ...(result.mailMessageId !== undefined ? { mailMessageId: result.mailMessageId } : {}),
+        };
+    }
+    /**
+     * Redeem an invitation from the magic link: consume the token, sign in
+     * (create the account with `password`, or authenticate an existing one),
+     * and AUTO-IMPORT the mandate the inviter attached. Returns the session and
+     * the imported {@link DelegateInfo}.
+     *
+     * Mount this on the page declared as the invitation's verify/redirect URL;
+     * read `email` + `token` from `window.location.search`, collect the
+     * `password`, call this.
+     *
+     * Throws `auth_token_invalid_or_expired` (bad/consumed/expired token) or an
+     * auth error if an existing account's password is wrong / a new one is weak.
+     */
+    async acceptInvite(input) {
+        if (!input.email || !input.token) {
+            throw new AithosSDKError("auth_invalid_input", "acceptInvite: email and token are required");
+        }
+        const resp = await custodialAccept({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, {
+            email: input.email,
+            token: input.token,
+            ...(input.password ? { password: input.password } : {}),
+        });
+        // Materialise the 4 sphere seeds + session — same shape as the verifyEmail
+        // magic-link path. Kept inline (additive; verifyEmail is left untouched).
+        const stored = {
+            version: "0.1.0-hex",
+            did: resp.did,
+            handle: resp.handle,
+            displayName: resp.displayName,
+            // Accepts 128 (legacy) or 160 (with #data); zeroizes resp.seed.
+            seedsHex: custodialSeedsHex(resp.seed),
+            savedAt: new Date().toISOString(),
+        };
+        zeroize(resp.encKey);
+        const identity = browserIdentityFromStored({
+            handle: stored.handle,
+            displayName: stored.displayName,
+            did: stored.did,
+            seeds: stored.seedsHex,
+        });
+        await this.#publishIdentity(identity);
+        if (this.#ownerSigners)
+            this.#ownerSigners.destroy();
+        this.#ownerSigners = OwnerSigners.fromStoredOwnerKeys(stored);
+        await this.#keyStore.saveOwner(stored);
+        const session = {
+            session: resp.session,
+            exp: resp.exp,
+            did: resp.did,
+            handle: resp.handle,
+            blob_b64: bytesToB64Public(resp.blob),
+            blob_nonce_b64: bytesToB64Public(resp.blobNonce),
+            blob_version: resp.blobVersion,
+            enc_key_b64: "",
+            is_first_login: false,
+        };
+        this.#sessionStore.set(session);
+        // Import the invited mandate into the keystore (generic — any scope).
+        const delegate = await this.importMandate({ bundle: resp.invitePayload });
+        return {
+            status: "signed_in",
+            session,
+            delegate,
+            accountCreated: resp.accountCreated,
+        };
+    }
+    /**
+     * Re-send the verification mail for a pending account. Use when the
+     * user reports never having received the welcome mail, or when their
+     * verification token expired (24h TTL).
+     *
+     * The backend is anti-enumeration (always 200) and rate-limited
+     * 1/h/account, so it's safe to call even when the state of `email`
+     * is unknown. Accepts the same credential families as
+     * {@link signUpCustodial}; falls back to the constructor's
+     * `publicKey` when neither override is set.
+     */
+    async resendVerificationEmail(input) {
+        if (!input.email) {
+            throw new AithosSDKError("auth_invalid_input", "resendVerificationEmail: email is required");
+        }
+        const apiKey = input.apiKey;
+        const publicKey = input.publicKey ?? this.#publicKey;
+        if (!apiKey && !publicKey) {
+            throw new AithosSDKError("auth_missing_api_key", "resendVerificationEmail: pass apiKey, publicKey, or set publicKey on the AithosAuth constructor");
+        }
+        await custodialResendVerify({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, {
+            email: input.email,
+            ...(apiKey ? { apiKey } : {}),
+            ...(apiKey ? {} : publicKey ? { publicKey } : {}),
+        });
+    }
+    /**
+     * Authenticate a custodial-mode user with email + password. Single
+     * round-trip: returns a fresh JWT session AND hydrates the local
+     * KeyStore with the user's 4 Ed25519 seeds (KMS-unwrapped server-side
+     * after Argon2id verify).
+     *
+     * After this returns, the SDK is ready to publish ethos editions,
+     * invoke compute, mint mandates, etc. — exactly as if the user had
+     * signed in via {@link signIn} (zk) or {@link handleCallback} (SSO).
+     *
+     * Errors map to `AithosSDKError` codes:
+     *   - `auth_invalid_input`        (your code passed empty fields)
+     *   - `auth_invalid_credentials`  (401 — wrong email / wrong password)
+     *   - `auth_wrong_auth_mode`      (403 — user exists in another flow)
+     */
+    async signInCustodial(input) {
+        if (!input.email || !input.password) {
+            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 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,
+            // Accepts 128 (legacy, no #data) or 160 (with #data); zeroizes resp.seed.
+            seedsHex: custodialSeedsHex(resp.seed),
+            savedAt: new Date().toISOString(),
+        };
+        // 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);
+        // Bootstrap the Ethos on api.aithos.be — same as signUp(zk). Without
+        // this, the DID returned by signInCustodial isn't resolvable on the
+        // platform (feed / profile lookups return "not found: did …"). The
+        // call is idempotent server-side: a published identity replays as a
+        // no-op. We do it here (rather than only on a "first login" flag)
+        // because the auth Lambda doesn't know whether the api.aithos.be
+        // side has been populated — the SDK is the single source of truth
+        // for "the user's Ethos is bootstrapped".
+        //
+        // Failure aborts the sign-in: the user can retry (same behaviour as
+        // signUp(zk)), and the local keystore is NOT populated half-way.
+        const identity = browserIdentityFromStored({
+            handle: stored.handle,
+            displayName: stored.displayName,
+            did: stored.did,
+            seeds: stored.seedsHex,
+        });
+        await this.#publishIdentity(identity);
+        // Hydrate in-memory owner signers from the freshly-stored material.
+        if (this.#ownerSigners)
+            this.#ownerSigners.destroy();
+        this.#ownerSigners = OwnerSigners.fromStoredOwnerKeys(stored);
+        await this.#keyStore.saveOwner(stored);
+        const session = {
+            session: resp.session,
+            exp: resp.exp,
+            did: resp.did,
+            handle: resp.handle,
+            blob_b64: bytesToB64Public(resp.blob),
+            blob_nonce_b64: bytesToB64Public(resp.blobNonce),
+            blob_version: resp.blobVersion,
+            enc_key_b64: "",
+            is_first_login: resp.passwordMustChange,
+        };
+        this.#sessionStore.set(session);
+        return { session, passwordMustChange: resp.passwordMustChange };
+    }
+    /**
+     * Trigger a password-reset email to the given address. Backend ALWAYS
+     * resolves silently (no enumeration) — caller cannot tell whether the
+     * email is registered or not. The mail itself, if sent, contains a
+     * magic-link URL of shape `<resetBaseUrl>?token=<raw>&email=<email>`.
+     *
+     * Per-email rate limits apply server-side (5 mails/day, 5 min cooldown
+     * between consecutive requests). Calls during cooldown silently no-op
+     * the mail send while still returning success here.
+     */
+    async requestPasswordReset(input) {
+        if (!input.email) {
+            throw new AithosSDKError("auth_invalid_input", "requestPasswordReset: email is required");
+        }
+        await custodialResetRequest({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, input.email);
+    }
+    /**
+     * Finalise a password reset using the magic-link token sent to the
+     * user's inbox by {@link requestPasswordReset}.
+     *
+     * Typical use site: the page mounted on the reset URL declared in
+     * `aithos-auth-apps.reset_base_url`. The page reads `email` and
+     * `token` from `window.location.search`, prompts the user for a new
+     * password, then calls this method.
+     *
+     * On success, the returned {@link AithosSession} is persisted to the
+     * session store but the local keystore is NOT hydrated — the backend
+     * does not return the seed bundle on this endpoint. To get a fully
+     * usable session (one that can sign envelopes), follow up with
+     * {@link signInCustodial} using the email + new password. The two
+     * round-trips can be hidden inside a single UI action: reset → auto
+     * sign-in → redirect to dashboard.
+     *
+     * Errors map to `AithosSDKError` codes:
+     *   - `auth_invalid_input`              (your code passed empty fields)
+     *   - `auth_reset_token_invalid`        (400 — token forged / wrong email)
+     *   - `auth_reset_token_expired`        (410 — token TTL elapsed)
+     *   - `auth_reset_token_consumed`       (409 — already used)
+     *   - `auth_password_too_short`         (400 — < 10 chars)
+     *   - `auth_custodial_reset_failed`     (catch-all)
+     */
+    async applyPasswordReset(input) {
+        if (!input.email || !input.token || !input.newPassword) {
+            throw new AithosSDKError("auth_invalid_input", "applyPasswordReset: email, token and newPassword are required");
+        }
+        const resp = await custodialResetFinalize({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, input);
+        // The reset endpoint mints a JWT but doesn't ship the seed bundle —
+        // the caller still has to signInCustodial() to materialise the keys
+        // locally. We persist the session anyway so any code that reads
+        // `getCurrentSession()` between the reset and the follow-up sign-in
+        // sees the new JWT (e.g. an analytics hook).
+        const session = {
+            session: resp.session,
+            exp: resp.exp,
+            did: resp.did,
+            handle: resp.handle,
+            // No blob / enc_key on this path — the reset endpoint doesn't
+            // re-issue the vault. Leave the blob slots empty; the follow-up
+            // signInCustodial() will populate them.
+            blob_b64: "",
+            blob_nonce_b64: "",
+            blob_version: 0,
+            enc_key_b64: "",
+            is_first_login: false,
+        };
+        this.#sessionStore.set(session);
+        return { session };
+    }
+    /* ------------------------------------------------------------------------ */
     /*  Sign-out                                                                 */
     /* ------------------------------------------------------------------------ */
     async signOut() {
@@ -632,6 +1484,24 @@ export class AithosAuth {
                 }
                 const json = (await res.json());
                 if (json.error) {
+                    // Backward-compat shim for backends without the semantic-equality
+                    // fix on publish-identity (alpha.33+ regression): the server may
+                    // reject a republish with -32022 because the client regenerates
+                    // `aithos.created_at` (and `proof.created`) on every
+                    // `signedDidDocument()` call, breaking the strict byte-equal
+                    // idempotence the server enforces. For an honest signer (same
+                    // root key, same DID) the only way to hit this code path is the
+                    // timestamp-drift case — which is semantically a no-op. Treat as
+                    // success.
+                    //
+                    // Server-side fix (publish-identity.ts switched to semantic
+                    // equality on cryptographic fields only) makes this branch dead
+                    // code on upgraded backends. Kept here as defense-in-depth for
+                    // SDK consumers pointing at older deployments.
+                    if (json.error.code === -32022 &&
+                        /different did\.json already published/i.test(json.error.message)) {
+                        return; // already published with same crypto material — no-op
+                    }
                     // JSON-RPC error: don't retry — these are deterministic
                     // (validation, permission, identity-already-tombstoned, …).
                     throw new AithosSDKError("ethos_bootstrap_failed", `publish_identity rejected: ${json.error.message}`, {
@@ -690,6 +1560,52 @@ function bytesToHex(b) {
         out += b[i].toString(16).padStart(2, "0");
     return out;
 }
+function hexToBytesLocal(hex) {
+    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;
+}
+/**
+ * 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}.