@aithos/sdk 0.1.0-alpha.3 → 0.1.0-alpha.31

package/dist/src/auth.js

@@ -1,65 +1,469 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright 2026 Mathieu Colla
-// Sign in with Google for Aithos apps.
+// Aithos auth — sign-up, sign-in (email+password / Google SSO /
+// recovery file), mandate import, sign-out.
 //
-// The auth flow is intentionally separate from {@link AithosSDK}: at sign-in
-// time the caller doesn't have a `BrowserIdentity` yet — that's precisely
-// what the flow returns (via the encrypted blob the response carries). So
-// we expose a standalone {@link AithosAuth} class that talks to the Aithos
-// auth backend (`auth.aithos.be`) over plain HTTPS.
+// One stateful object per app. Holds the active {@link AithosSession}
+// (JWT-backed when present), the loaded owner signers in memory (when
+// signed in as an owner), and a registry of active delegate
+// sessions. Persists across reloads via the configured
+// {@link AithosSessionStore} (JWT) and {@link AithosKeyStore} (signing
+// material).
 //
-// Flow from the caller's point of view:
+// Strict mode (per design discussion): the two stores must agree about
+// who's signed in. If sessionStore has a JWT for one DID and keyStore
+// has an owner with a DIFFERENT DID, both are wiped. If sessionStore
+// has a JWT but keyStore has no owner at all, the JWT is wiped (a
+// JWT alone is useless without local signing capability for everything
+// past compute/wallet).
 //
-//   const auth = new AithosAuth();
-//   // on a "Sign in" button:
-//   auth.signInWithGoogle({ appState: "/dashboard" });   // navigates away
-//
-//   // on the redirect-back page (e.g. /auth/callback):
-//   const session = await auth.handleCallback();
-//   if (session) {
-//     // session.session     — JWT, send as Bearer to /auth/blob etc.
-//     // session.enc_key_b64 — 32-byte vault key, base64 (raw bytes for
-//     //                        AES-GCM decryption of session.blob_b64)
-//     // session.is_first_login — true on the very first sign-in
-//   }
-//
-// We deliberately don't persist anything in this module — storage is the
-// app's call (its threat model, its choices around localStorage vs
-// sessionStorage vs IndexedDB). See README "Auth — sessions and storage"
-// for the recommended patterns.
+// 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 { 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 { OwnerSigners } from "./internal/owner-signers.js";
+import { parseRecoveryFile, readRecoveryFileText, serializeRecoveryFile, } from "./internal/recovery-file.js";
 import { AithosSDKError } from "./types.js";
 /** Default URL of the Aithos auth backend. */
 export const DEFAULT_AUTH_BASE_URL = "https://auth.aithos.be";
+/** Default URL of the Aithos primitives API (publish_identity, publish_ethos_edition, etc.). */
+export const DEFAULT_API_BASE_URL = "https://api.aithos.be";
 /* -------------------------------------------------------------------------- */
 /*  AithosAuth                                                                */
 /* -------------------------------------------------------------------------- */
-/**
- * Authenticator for the Aithos identity service. One instance per app
- * is the recommended pattern (the constructor is cheap; it just trims the
- * URL). All methods are pure — no module-global state.
- */
 export class AithosAuth {
-    /** Resolved auth base URL with a trailing slash trimmed. */
     authBaseUrl;
-    fetchImpl;
-    win;
+    apiBaseUrl;
+    #fetchImpl;
+    #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.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
-        this.win = config.window ?? (typeof window !== "undefined" ? window : undefined);
+        this.apiBaseUrl = trimSlash(config.apiBaseUrl ?? DEFAULT_API_BASE_URL);
+        this.#fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+        this.#win =
+            config.window ??
+                (typeof window !== "undefined" ? window : undefined);
+        this.#sessionStore = config.sessionStore ?? defaultSessionStore();
+        this.#keyStore = config.keyStore ?? defaultKeyStore();
+        this.#publicKey = config.publicKey;
     }
+    /* ------------------------------------------------------------------------ */
+    /*  Boot-time hydration                                                      */
+    /* ------------------------------------------------------------------------ */
     /**
-     * Redirect the browser to Google's OAuth consent screen. Must be called
-     * synchronously in response to a user gesture (button click) — most
-     * browsers block top-level navigation triggered from idle code.
+     * Reload signing material and JWT session from the configured stores.
+     * Must be called once at app boot before relying on
+     * {@link getCurrentSession} / {@link getOwnerInfo} / {@link canSignAsOwner}
+     * — until then they reflect only what's been done in-memory in the
+     * current tab.
      *
-     * Does not return: navigation tears the JS context down. The `never`
-     * return type tells callers any code after the call is unreachable.
+     * Strict consistency: if the JWT and the stored owner disagree about
+     * who's signed in, both are wiped and the user re-auths. JWT-less
+     * owner state (loaded from keyStore but no JWT) is a valid resumed
+     * state — the user signed in via recovery or imported a mandate at
+     * some earlier moment and never went through the JWT flow.
      */
+    async resume() {
+        // 1. Owner side.
+        const stored = await this.#keyStore.loadOwner().catch(() => null);
+        const jwt = this.#sessionStore.get();
+        if (stored) {
+            this.#ownerSigners = OwnerSigners.fromStoredOwnerKeys(stored);
+            // JWT must match the owner DID — otherwise it's stale state.
+            if (jwt && jwt.did !== stored.did) {
+                this.#sessionStore.clear();
+            }
+        }
+        else {
+            // No owner persisted. A lingering JWT is meaningless without local
+            // signing capability — wipe it (strict mode).
+            if (jwt)
+                this.#sessionStore.clear();
+        }
+        // 2. Delegate side. Independent of owner state — a user may hold
+        //    only delegate bundles and no owner identity at all.
+        const storedDelegates = await this.#keyStore
+            .listDelegates()
+            .catch(() => []);
+        for (const d of storedDelegates) {
+            try {
+                this.#delegates.add(DelegateActor.fromStored(d));
+            }
+            catch {
+                // Skip corrupted entries silently — the keystore validators
+                // already filter most of these. A skip here means the keystore
+                // record passed validation but the seed couldn't be re-derived
+                // (e.g. zero-length, future migration); ignore and continue.
+            }
+        }
+    }
+    /* ------------------------------------------------------------------------ */
+    /*  State accessors                                                          */
+    /* ------------------------------------------------------------------------ */
+    /** JWT-backed session. Null when signed in via recovery / mandate / not at all. */
+    getCurrentSession() {
+        const session = this.#sessionStore.get();
+        if (!session)
+            return null;
+        // Belt-and-braces: the session store auto-evicts on expiry, but we
+        // also re-check here in case the in-tab clock drifted post-load.
+        return session;
+    }
+    /** Loaded owner identity. Independent of JWT presence. */
+    getOwnerInfo() {
+        if (!this.#ownerSigners)
+            return null;
+        return {
+            did: this.#ownerSigners.did,
+            handle: this.#ownerSigners.handle,
+            displayName: this.#ownerSigners.displayName,
+        };
+    }
+    getDelegates() {
+        return this.#delegates.list().map(actorToInfo);
+    }
+    canSignAsOwner() {
+        return this.#ownerSigners !== null && !this.#ownerSigners.destroyed;
+    }
+    canSignAsDelegateFor(did) {
+        const a = this.#delegates.findForSubject(did);
+        return a !== undefined && !a.destroyed;
+    }
+    /**
+     * Internal accessor used by sibling SDK namespaces (compute, wallet,
+     * ethos) when they need to sign on behalf of the owner. Returns null
+     * if no owner is loaded.
+     *
+     * @internal
+     */
+    _getOwnerSigners() {
+        return this.#ownerSigners;
+    }
+    /**
+     * Internal accessor — looks up an active delegate by mandate id.
+     * @internal
+     */
+    _getDelegateActor(mandateId) {
+        return this.#delegates.get(mandateId);
+    }
+    /**
+     * Internal accessor — finds the first active delegate whose subject
+     * matches `did`. Used by `sdk.ethos.of(did)` when the user holds a
+     * mandate for that subject.
+     * @internal
+     */
+    _findDelegateForSubject(did) {
+        return this.#delegates.findForSubject(did);
+    }
+    /* ------------------------------------------------------------------------ */
+    /*  Email + password — signIn                                                */
+    /* ------------------------------------------------------------------------ */
+    async signIn(input) {
+        if (!input.email || !input.password) {
+            throw new AithosSDKError("auth_invalid_input", "signIn: email and password are required");
+        }
+        const challenge = await loginChallenge({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, input.email);
+        const { authKey, encKey } = await deriveAuthAndEncKeys(input.password, challenge.authSalt, challenge.encSalt, challenge.kdf);
+        let verify;
+        try {
+            verify = await loginVerify({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, input.email, authKey);
+        }
+        catch (e) {
+            // On failure, both keys must be wiped before propagating.
+            zeroize(authKey);
+            zeroize(encKey);
+            throw e;
+        }
+        zeroize(authKey);
+        // Decrypt the vault blob → plaintext seeds + delegate bundles.
+        let plaintext;
+        try {
+            const blobBytes = decryptBlob(encKey, verify.blobNonce, verify.blob);
+            try {
+                plaintext = parseBlob(blobBytes);
+            }
+            finally {
+                zeroize(blobBytes);
+            }
+        }
+        catch (e) {
+            zeroize(encKey);
+            throw new AithosSDKError("auth_blob_decrypt_failed", `Could not decrypt the vault blob: ${e.message}`);
+        }
+        zeroize(encKey);
+        // Sanity check: blob's identity must agree with what verify returned.
+        if (plaintext.identity.did !== verify.did) {
+            throw new AithosSDKError("auth_blob_identity_mismatch", "vault blob's DID does not match the verified login DID", { data: { blobDid: plaintext.identity.did, verifyDid: verify.did } });
+        }
+        // Hydrate in-memory state.
+        if (this.#ownerSigners)
+            this.#ownerSigners.destroy();
+        this.#ownerSigners = OwnerSigners.fromBlobPlaintext(plaintext);
+        // Persist to keyStore — owner first, then delegates.
+        const ownerStored = {
+            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.saveOwner(ownerStored);
+        // Replace any prior delegate set with what the blob carries.
+        await this.#keyStore.clearAllDelegates();
+        this.#delegates.destroy();
+        for (const d of plaintext.delegates) {
+            const stored = storedDelegateFromBlob(d);
+            try {
+                await this.#keyStore.saveDelegate(stored);
+            }
+            catch {
+                // Persistence failure shouldn't block the sign-in. We still load
+                // the actor in memory so the session works for the current tab.
+            }
+            try {
+                this.#delegates.add(DelegateActor.fromStored(stored));
+            }
+            catch {
+                // Skip silently — keep going on remaining delegates.
+            }
+        }
+        const session = {
+            session: verify.session,
+            exp: verify.exp,
+            did: verify.did,
+            handle: verify.handle,
+            blob_b64: bytesToB64Public(verify.blob),
+            blob_nonce_b64: bytesToB64Public(verify.blobNonce),
+            blob_version: verify.blobVersion,
+            enc_key_b64: "",
+            is_first_login: false,
+        };
+        this.#sessionStore.set(session);
+        return session;
+    }
+    /* ------------------------------------------------------------------------ */
+    /*  Email + password — signUp                                                */
+    /* ------------------------------------------------------------------------ */
+    async signUp(input) {
+        if (!input.email || !input.password) {
+            throw new AithosSDKError("auth_invalid_input", "signUp: email and password are required");
+        }
+        if (!/^[a-z0-9][a-z0-9_-]{0,62}$/i.test(input.handle)) {
+            throw new AithosSDKError("auth_invalid_handle", "signUp: handle must be 1–63 alphanumeric chars + _ -");
+        }
+        const displayName = input.displayName ?? input.handle;
+        const identity = createBrowserIdentity(input.handle, displayName);
+        const recoverySerialized = serializeRecoveryFile(identity);
+        const recoveryFile = new Blob([recoverySerialized.text], {
+            type: "application/json",
+        });
+        // Derive password-based keys, encrypt the vault blob.
+        const authSalt = randomSalt();
+        const encSalt = randomSalt();
+        const kdf = DEFAULT_KDF;
+        const { authKey, encKey } = await deriveAuthAndEncKeys(input.password, authSalt, encSalt, kdf);
+        const 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,
+            },
+            delegates: [],
+        });
+        const blobBytes = serializeBlob(plaintext);
+        const blobNonce = randomNonce();
+        const blob = encryptBlob(encKey, blobNonce, blobBytes);
+        let registerResp;
+        try {
+            registerResp = await registerAccount({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, {
+                email: input.email,
+                handle: identity.handle,
+                displayName: identity.displayName,
+                did: identity.did,
+                authKey,
+                authSalt,
+                encSalt,
+                kdf,
+                blob,
+                blobNonce,
+                blobVersion: 1,
+            });
+        }
+        finally {
+            zeroize(authKey);
+            zeroize(encKey);
+        }
+        // Bootstrap the Ethos on api.aithos.be. Without this, every subsequent
+        // write (publish_ethos_edition, etc.) errors out with -32020
+        // "subject identity not published". We do this BEFORE hydrating local
+        // state so a bootstrap failure leaves the SDK in a clean
+        // "not signed in" state — the dev shows an error, the user retries.
+        // The auth account on auth.aithos.be DOES exist at this point, but
+        // without the local hydrate the user can't act on it. Self-heal on
+        // signIn (re-attempt publish_identity if missing) is planned for a
+        // follow-up release.
+        await this.#publishIdentity(identity);
+        // 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),
+            },
+            savedAt: new Date().toISOString(),
+        });
+        const session = {
+            session: registerResp.session,
+            exp: registerResp.exp,
+            did: identity.did,
+            handle: identity.handle,
+            blob_b64: bytesToB64Public(blob),
+            blob_nonce_b64: bytesToB64Public(blobNonce),
+            blob_version: 1,
+            enc_key_b64: "",
+            is_first_login: false,
+        };
+        this.#sessionStore.set(session);
+        return {
+            session,
+            recoveryFile,
+            recoveryFilename: recoverySerialized.filename,
+        };
+    }
+    /* ------------------------------------------------------------------------ */
+    /*  Recovery file                                                            */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Sign in by uploading a recovery file. Hydrates the owner signers
+     * locally — no JWT is obtained on this path because the recovery
+     * file alone doesn't authenticate against the auth backend (no
+     * password, no Google session). Apps that need compute/wallet
+     * access should follow up with an email+password sign-in or with
+     * Google SSO.
+     *
+     * The recovery file is ALWAYS the file produced by `signUp` (or the
+     * equivalent one emitted by `protocol-client`'s `runOnboarding`).
+     * Both shapes are accepted.
+     */
+    async signInWithRecovery(input) {
+        const text = await readRecoveryFileText(input.file);
+        const parsed = parseRecoveryFile(text);
+        // Build a StoredOwnerKeys-shape on the spot, then push to keyStore +
+        // hydrate signers.
+        const stored = {
+            version: "0.1.0-hex",
+            did: parsed.did,
+            handle: parsed.handle,
+            displayName: parsed.displayName,
+            seedsHex: parsed.seedsHex,
+            savedAt: new Date().toISOString(),
+        };
+        // If a different owner is already loaded, refuse — apps must call
+        // signOut() first. Mixing two owners in one auth instance is a
+        // nonsense state we don't want to support.
+        if (this.#ownerSigners && this.#ownerSigners.did !== parsed.did) {
+            throw new AithosSDKError("auth_owner_already_loaded", "another owner is already signed in; call signOut first", { data: { current: this.#ownerSigners.did, incoming: parsed.did } });
+        }
+        if (this.#ownerSigners)
+            this.#ownerSigners.destroy();
+        this.#ownerSigners = OwnerSigners.fromStoredOwnerKeys(stored);
+        await this.#keyStore.saveOwner(stored);
+        // Recovery flow doesn't yield a JWT — wipe any stale one to keep
+        // the two stores in sync.
+        this.#sessionStore.clear();
+        return {
+            did: parsed.did,
+            handle: parsed.handle,
+            displayName: parsed.displayName,
+        };
+    }
+    /* ------------------------------------------------------------------------ */
+    /*  Mandate import                                                           */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Import a delegate bundle (`.aithos-delegate.json`). Works in any
+     * state: with no owner loaded (delegate-only session), or alongside
+     * an existing owner (the user holds mandates for other people's
+     * ethoses while also being an owner themselves).
+     */
+    async importMandate(input) {
+        const text = await readDelegateBundleText(input.bundle);
+        const parsed = parseDelegateBundle(text);
+        const stored = {
+            version: "0.1.0-hex",
+            subjectDid: parsed.subjectDid,
+            mandateId: parsed.mandateId,
+            mandate: parsed.mandate,
+            granteeId: parsed.granteeId,
+            granteePubkeyMultibase: parsed.granteePubkeyMultibase,
+            delegateSeedHex: parsed.delegateSeedHex,
+            importedAt: new Date().toISOString(),
+        };
+        await this.#keyStore.saveDelegate(stored);
+        this.#delegates.add(DelegateActor.fromStored(stored));
+        return {
+            mandateId: stored.mandateId,
+            subjectDid: stored.subjectDid,
+            granteeId: stored.granteeId,
+            scopes: scopesFromMandate(stored.mandate),
+            expiresAt: notAfterFromMandate(stored.mandate),
+        };
+    }
+    async removeMandate(mandateId) {
+        this.#delegates.remove(mandateId);
+        await this.#keyStore.removeDelegate(mandateId);
+    }
+    /* ------------------------------------------------------------------------ */
+    /*  Google SSO                                                               */
+    /* ------------------------------------------------------------------------ */
     signInWithGoogle(opts) {
-        if (!this.win) {
+        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) {
@@ -67,47 +471,145 @@ export class AithosAuth {
             }
             url.searchParams.set("app_state", opts.appState);
         }
-        this.win.location.assign(url.toString());
-        // Unreachable: location.assign navigates synchronously. The throw is
-        // belt-and-braces in case a caller awaits a microtask before unload.
+        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");
     }
     /**
-     * Inspect the current URL for an `aithos_code` query parameter. If it's
-     * present, exchange it at the backend and return the resulting
-     * {@link AithosSession}. The query params are stripped from the URL via
-     * `history.replaceState` so a page refresh doesn't replay the redeem
-     * (which would 410 anyway).
-     *
-     * Returns `null` when there's no code in the URL — safe to call on every
-     * page load. Throws {@link AithosSDKError} on backend errors or when
-     * the URL carries `aithos_error=…` (Google denial, token-exchange
-     * failure, etc.).
+     * 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)
+        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);
+        const here = new URL(this.#win.location.href);
         const error = here.searchParams.get("aithos_error");
         const code = here.searchParams.get("aithos_code");
         const appState = here.searchParams.get("app_state");
         if (error) {
-            cleanCallbackParams(this.win, here);
+            cleanCallbackParams(this.#win, here);
             throw new AithosSDKError(`auth_${error}`, `Sign-in failed: ${error}`, { data: appState ? { app_state: appState } : undefined });
         }
         if (!code)
             return null;
+        // 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);
-        cleanCallbackParams(this.win, here);
+        // 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).
+        if (session.enc_key_b64 &&
+            session.blob_b64 &&
+            session.blob_nonce_b64 &&
+            session.blob_version > 0) {
+            try {
+                const encKey = b64ToBytes(session.enc_key_b64);
+                const blob = b64ToBytes(session.blob_b64);
+                const nonce = b64ToBytes(session.blob_nonce_b64);
+                try {
+                    const blobBytes = decryptBlob(encKey, nonce, blob);
+                    try {
+                        const plaintext = parseBlob(blobBytes);
+                        // 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 */
+                            }
+                        }
+                    }
+                    finally {
+                        zeroize(blobBytes);
+                    }
+                }
+                finally {
+                    zeroize(encKey);
+                }
+            }
+            catch {
+                // Decryption failure is non-fatal here: the JWT still works for
+                // compute/wallet, the user will surface the issue if they try to
+                // edit their ethos.
+            }
+        }
+        this.#sessionStore.set(session);
         return session;
     }
-    /**
-     * Programmatically redeem an `aithos_code` for a session. `handleCallback`
-     * calls this for you; expose it directly for callers that already pulled
-     * the code out of the URL via their own router.
-     */
     async exchange(aithosCode) {
-        const res = await this.fetchImpl(`${this.authBaseUrl}/auth/sso/exchange`, {
+        const res = await this.#fetchImpl(`${this.authBaseUrl}/auth/sso/exchange`, {
             method: "POST",
             headers: { "content-type": "application/json" },
             body: JSON.stringify({ aithos_code: aithosCode }),
@@ -120,7 +622,9 @@ export class AithosAuth {
             catch {
                 // ignore non-JSON error body
             }
-            const code = typeof body?.["code"] === "string" ? `auth_${body["code"]}` : "auth_exchange_failed";
+            const code = typeof body?.["code"] === "string"
+                ? `auth_${body["code"]}`
+                : "auth_exchange_failed";
             const message = typeof body?.["error"] === "string"
                 ? body["error"]
                 : `aithos_code redemption failed (${res.status})`;
@@ -131,14 +635,474 @@ export class AithosAuth {
         }
         return (await res.json());
     }
+    /* ------------------------------------------------------------------------ */
+    /*  Complete SSO first login                                                 */
+    /* ------------------------------------------------------------------------ */
     /**
-     * Stateless sign-out. The Aithos backend doesn't track sessions, so
-     * there's nothing to revoke server-side; this method exists so the app
-     * has a symmetric API surface and to remind callers to clear their
-     * own storage. The Promise always resolves.
+     * 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,
+                },
+                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),
+            },
+            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 } : {}),
+        });
+    }
+    /**
+     * Confirm the user's email address by consuming the one-time token
+     * from the confirmation link. Idempotent on repeated clicks; throws
+     * `auth_token_invalid_or_expired` if the token is wrong, already
+     * consumed, or past its 24h TTL.
+     *
+     * Mount this on the page declared as `verify_base_url` in your app's
+     * registration. Read `email` + `token` from `window.location.search`,
+     * call this, then redirect to your sign-in page on success.
+     */
+    async verifyEmail(input) {
+        if (!input.email || !input.token) {
+            throw new AithosSDKError("auth_invalid_input", "verifyEmail: email and token are required");
+        }
+        return custodialVerifyEmail({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, input);
+    }
+    /**
+     * 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 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.
+        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),
+            },
+            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);
+        // 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() {
-        /* no-op; sessions are stateless JWTs. */
+        if (this.#ownerSigners)
+            this.#ownerSigners.destroy();
+        this.#ownerSigners = null;
+        this.#delegates.destroy();
+        this.#sessionStore.clear();
+        await this.#keyStore.clearOwner().catch(() => { });
+        await this.#keyStore.clearAllDelegates().catch(() => { });
+    }
+    /* ------------------------------------------------------------------------ */
+    /*  Internal — Ethos bootstrap                                              */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Provision the user's Ethos on `api.aithos.be` by signing and POSTing an
+     * `aithos.publish_identity` envelope. Required after a fresh sign-up so
+     * subsequent edition publishes (`me.publish()`) don't fail with
+     * `-32020 subject identity not published`.
+     *
+     * Retries twice with exponential backoff on transient errors (network or
+     * 5xx). Throws {@link AithosSDKError} with code `ethos_bootstrap_failed`
+     * on definitive failure — the caller is expected to abort sign-up.
+     *
+     * @internal
+     */
+    async #publishIdentity(identity) {
+        const url = `${this.apiBaseUrl}/mcp/primitives/write`;
+        const signedDoc = signedDidDocument(identity);
+        const params = {
+            did_document: signedDoc,
+            handle: identity.handle,
+            display_name: identity.displayName,
+        };
+        const envelope = buildSignedEnvelope({
+            iss: identity.did,
+            aud: url,
+            method: "aithos.publish_identity",
+            verificationMethod: `${identity.did}#root`,
+            params,
+            signer: identity.root,
+        });
+        const body = JSON.stringify({
+            jsonrpc: "2.0",
+            id: "publish_identity",
+            method: "aithos.publish_identity",
+            params: { ...params, _envelope: envelope },
+        });
+        // Two retries with backoff (300ms, 1500ms). Idempotent on the server
+        // side — replaying the same publish_identity for an existing DID is a
+        // no-op, so retries are safe even if the first attempt actually
+        // succeeded but the response was lost.
+        const delays = [0, 300, 1500];
+        let lastError;
+        for (const delay of delays) {
+            if (delay > 0)
+                await sleep(delay);
+            try {
+                const res = await this.#fetchImpl(url, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body,
+                });
+                // Transport errors (5xx, no body) — retry. JSON-RPC errors come
+                // back with HTTP 200 and an `error` field.
+                if (!res.ok && res.status >= 500) {
+                    lastError = new Error(`HTTP ${res.status}`);
+                    continue;
+                }
+                const json = (await res.json());
+                if (json.error) {
+                    // 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}`, {
+                        status: res.status,
+                        data: { rpc_code: json.error.code, ...(json.error.data ?? {}) },
+                    });
+                }
+                return; // success
+            }
+            catch (e) {
+                if (e instanceof AithosSDKError)
+                    throw e;
+                lastError = e;
+            }
+        }
+        throw new AithosSDKError("ethos_bootstrap_failed", `publish_identity unreachable after ${delays.length} attempts: ${lastError?.message ?? "unknown"}`);
     }
 }
 /* -------------------------------------------------------------------------- */
@@ -147,10 +1111,75 @@ export class AithosAuth {
 function trimSlash(url) {
     return url.endsWith("/") ? url.slice(0, -1) : url;
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function cleanCallbackParams(win, url) {
     url.searchParams.delete("aithos_code");
     url.searchParams.delete("aithos_error");
     url.searchParams.delete("app_state");
     win.history.replaceState(null, "", url.toString());
 }
+function bytesToB64Public(bytes) {
+    if (bytes.length === 0)
+        return "";
+    let bin = "";
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin).replace(/=+$/, "");
+}
+function b64ToBytes(b64) {
+    if (!b64)
+        return new Uint8Array(0);
+    // standard b64 — pad to multiple of 4 if needed
+    const pad = b64.length % 4 === 0 ? "" : "=".repeat(4 - (b64.length % 4));
+    const bin = atob(b64 + pad);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function bytesToHex(b) {
+    let out = "";
+    for (let i = 0; i < b.length; i++)
+        out += b[i].toString(16).padStart(2, "0");
+    return out;
+}
+/**
+ * Project a delegate as it appears in a `BlobPlaintext` (extension-kit
+ * `StoredDelegate` shape) onto the SDK's own {@link StoredDelegateKeys}.
+ */
+function storedDelegateFromBlob(d) {
+    return {
+        version: "0.1.0-hex",
+        subjectDid: d.subjectDid,
+        mandateId: d.mandateId,
+        mandate: d.mandate,
+        granteeId: d.granteeId,
+        granteePubkeyMultibase: d.granteePubkeyMultibase,
+        delegateSeedHex: d.delegateSeedHex,
+        importedAt: new Date().toISOString(),
+    };
+}
+function actorToInfo(a) {
+    return {
+        mandateId: a.mandateId,
+        subjectDid: a.subjectDid,
+        granteeId: a.granteeId,
+        scopes: scopesFromMandate(a.mandate),
+        expiresAt: notAfterFromMandate(a.mandate),
+    };
+}
+function scopesFromMandate(m) {
+    const raw = m["scopes"];
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((s) => typeof s === "string");
+}
+function notAfterFromMandate(m) {
+    const raw = m["not_after"];
+    if (typeof raw !== "string")
+        return null;
+    return raw;
+}
 //# sourceMappingURL=auth.js.map