@aithos/sdk 0.1.0-alpha.12 → 0.1.0-alpha.14

package/dist/src/auth-api.d.ts

@@ -21,6 +21,15 @@ export interface RegisterApiResponse {
     readonly exp: number;
 }
 export declare function registerAccount(http: HttpClient, input: RegisterApiInput): Promise<RegisterApiResponse>;
+export interface PutBlobApiInput {
+    readonly jwt: string;
+    readonly blob: Uint8Array;
+    readonly blobNonce: Uint8Array;
+    readonly blobVersion: number;
+}
+export declare function putBlob(http: HttpClient, input: PutBlobApiInput): Promise<{
+    ok: true;
+}>;
 export interface LoginChallengeResponse {
     readonly authSalt: Uint8Array;
     readonly encSalt: Uint8Array;

package/dist/src/auth-api.js

@@ -41,6 +41,19 @@ async function postJson(http, path, body, jwt) {
         throw await readError(res, "request_failed");
     return (await res.json());
 }
+async function putJson(http, path, body, jwt) {
+    const res = await http.fetchImpl(`${http.authBaseUrl}${path}`, {
+        method: "PUT",
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${jwt}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok)
+        throw await readError(res, "request_failed");
+    return (await res.json());
+}
 export async function registerAccount(http, input) {
     return postJson(http, "/auth/register", {
         email: input.email,
@@ -56,6 +69,13 @@ export async function registerAccount(http, input) {
         blob_version: input.blobVersion,
     });
 }
+export async function putBlob(http, input) {
+    return putJson(http, "/auth/blob", {
+        blob_b64: bytesToB64(input.blob),
+        blob_nonce_b64: bytesToB64(input.blobNonce),
+        blob_version: input.blobVersion,
+    }, input.jwt);
+}
 export async function loginChallenge(http, email) {
     const wire = await postJson(http, "/auth/login/challenge", { email });
     return {

package/dist/src/auth.d.ts

@@ -105,6 +105,28 @@ export interface SignUpResult {
     readonly recoveryFile: Blob;
     readonly recoveryFilename: string;
 }
+/**
+ * Input to {@link AithosAuth.completeSsoFirstLogin}. The handle is
+ * required (the auth backend pre-generated one from the user's email
+ * local-part, available on the session payload — we re-confirm it
+ * here so the user can edit before commit).
+ */
+export interface CompleteSsoFirstLoginInput {
+    readonly handle: string;
+    readonly displayName?: string;
+}
+/**
+ * Result of {@link AithosAuth.completeSsoFirstLogin}. Returns a recovery
+ * file just like signUp — even though the user authenticated via Google,
+ * the freshly-generated Ed25519 seeds are the only material that can
+ * sign Aithos artifacts; without the recovery file, losing access to
+ * the Google account means losing the ethos forever.
+ */
+export interface CompleteSsoFirstLoginResult {
+    readonly session: AithosSession;
+    readonly recoveryFile: Blob;
+    readonly recoveryFilename: string;
+}
 export interface SignInWithRecoveryInput {
     /** Recovery file as a Blob (browser File input) or already-decoded JSON string. */
     readonly file: Blob | string;
@@ -183,8 +205,49 @@ export declare class AithosAuth {
     importMandate(input: ImportMandateInput): Promise<DelegateInfo>;
     removeMandate(mandateId: string): Promise<void>;
     signInWithGoogle(opts?: SignInWithGoogleOptions): never;
+    /**
+     * 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.
+     */
     handleCallback(): Promise<AithosSession | null>;
     exchange(aithosCode: string): Promise<AithosSession>;
+    /**
+     * 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).
+     */
+    completeSsoFirstLogin(input: CompleteSsoFirstLoginInput): Promise<CompleteSsoFirstLoginResult>;
     signOut(): Promise<void>;
 }
 //# sourceMappingURL=auth.d.ts.map

package/dist/src/auth.js

@@ -21,7 +21,7 @@
 // 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 { 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";
@@ -47,6 +47,16 @@ export class AithosAuth {
     #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);
@@ -466,7 +476,41 @@ export class AithosAuth {
         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);
@@ -504,34 +548,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 */
                             }
                         }
                     }
@@ -580,6 +634,143 @@ 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,
+                },
+                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,
+        };
+    }
+    /* ------------------------------------------------------------------------ */
     /*  Sign-out                                                                 */
     /* ------------------------------------------------------------------------ */
     async signOut() {

package/dist/src/index.d.ts

@@ -10,7 +10,7 @@ export { ComputeNamespace } from "./compute.js";
 export type { CreditPackId, CreateTopupSessionArgs, CreateTopupSessionResult, GetBalanceArgs, GetBalanceResult, } from "./wallet.js";
 export { WalletNamespace } from "./wallet.js";
 export { AithosAuth, DEFAULT_API_BASE_URL, DEFAULT_AUTH_BASE_URL, } from "./auth.js";
-export type { AithosAuthConfig, AithosSession, DelegateInfo, ImportMandateInput, OwnerInfo, SignInInput, SignInWithGoogleOptions, SignInWithRecoveryInput, SignUpInput, SignUpResult, } from "./auth.js";
+export type { AithosAuthConfig, AithosSession, CompleteSsoFirstLoginInput, CompleteSsoFirstLoginResult, DelegateInfo, ImportMandateInput, OwnerInfo, SignInInput, SignInWithGoogleOptions, SignInWithRecoveryInput, SignUpInput, SignUpResult, } from "./auth.js";
 export { DEFAULT_SESSION_STORAGE_KEY, defaultSessionStore, localStorageStore, noopStore, sessionStorageStore, type AithosSessionStore, } from "./session-store.js";
 export { DEFAULT_KEYSTORE_DB_NAME, defaultKeyStore, indexedDbKeyStore, memoryKeyStore, type AithosKeyStore, type StoredDelegateKeys, type StoredOwnerKeys, } from "./key-store.js";
 export { EthosClient, EthosNamespace, EthosZone, ZONE_NAMES, } from "./ethos.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.12",
+  "version": "0.1.0-alpha.14",
   "description": "Aithos SDK — high-level TypeScript developer kit for building agentic apps on the Aithos protocol. Wraps @aithos/protocol-client and exposes the Aithos compute proxy and wallet (Stripe top-up) endpoints.",
   "keywords": [
     "aithos",