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

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

@@ -0,0 +1,41 @@
+import { type KdfParams } from "@aithos/protocol-client";
+interface HttpClient {
+    readonly fetchImpl: typeof fetch;
+    readonly authBaseUrl: string;
+}
+export interface RegisterApiInput {
+    readonly email: string;
+    readonly handle: string;
+    readonly displayName: string;
+    readonly did: string;
+    readonly authKey: Uint8Array;
+    readonly authSalt: Uint8Array;
+    readonly encSalt: Uint8Array;
+    readonly kdf: KdfParams;
+    readonly blob: Uint8Array;
+    readonly blobNonce: Uint8Array;
+    readonly blobVersion: number;
+}
+export interface RegisterApiResponse {
+    readonly session: string;
+    readonly exp: number;
+}
+export declare function registerAccount(http: HttpClient, input: RegisterApiInput): Promise<RegisterApiResponse>;
+export interface LoginChallengeResponse {
+    readonly authSalt: Uint8Array;
+    readonly encSalt: Uint8Array;
+    readonly kdf: KdfParams;
+}
+export declare function loginChallenge(http: HttpClient, email: string): Promise<LoginChallengeResponse>;
+export interface LoginVerifyResponse {
+    readonly session: string;
+    readonly exp: number;
+    readonly did: string;
+    readonly handle: string;
+    readonly blob: Uint8Array;
+    readonly blobNonce: Uint8Array;
+    readonly blobVersion: number;
+}
+export declare function loginVerify(http: HttpClient, email: string, authKey: Uint8Array): Promise<LoginVerifyResponse>;
+export {};
+//# sourceMappingURL=auth-api.d.ts.map

package/dist/src/auth-api.js

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Thin HTTP client over the Aithos auth Lambda.
+//
+// Internal — not exported from the package's public surface. The
+// {@link AithosAuth} class composes these calls with the crypto
+// primitives in `@aithos/protocol-client` and the session store in
+// {@link ./session-store.ts} to expose a high-level
+// signIn / signUp / signInWithGoogle API.
+//
+// Wire format mirrors `aithos/auth/API.md` exactly. All `*_b64` fields
+// are standard-base64 (not URL-safe), padding stripped — see
+// `bytesToB64` / `b64ToBytes` in `@aithos/protocol-client`.
+import { bytesToB64, b64ToBytes, } from "@aithos/protocol-client";
+import { AithosSDKError } from "./types.js";
+async function readError(res, defaultCode) {
+    let body = null;
+    try {
+        body = (await res.json());
+    }
+    catch {
+        /* body not JSON */
+    }
+    const code = typeof body?.code === "string" ? `auth_${body.code}` : `auth_${defaultCode}`;
+    const message = body?.error ?? `${res.status} ${res.statusText || "request failed"}`;
+    return new AithosSDKError(code, message, {
+        status: res.status,
+        ...(body !== null ? { data: body } : {}),
+    });
+}
+async function postJson(http, path, body, jwt) {
+    const res = await http.fetchImpl(`${http.authBaseUrl}${path}`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            ...(jwt ? { 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,
+        handle: input.handle,
+        display_name: input.displayName,
+        did: input.did,
+        auth_key_b64: bytesToB64(input.authKey),
+        auth_salt_b64: bytesToB64(input.authSalt),
+        enc_salt_b64: bytesToB64(input.encSalt),
+        kdf: input.kdf,
+        blob_b64: bytesToB64(input.blob),
+        blob_nonce_b64: bytesToB64(input.blobNonce),
+        blob_version: input.blobVersion,
+    });
+}
+export async function loginChallenge(http, email) {
+    const wire = await postJson(http, "/auth/login/challenge", { email });
+    return {
+        authSalt: b64ToBytes(wire.auth_salt_b64),
+        encSalt: b64ToBytes(wire.enc_salt_b64),
+        kdf: wire.kdf,
+    };
+}
+export async function loginVerify(http, email, authKey) {
+    const wire = await postJson(http, "/auth/login/verify", {
+        email,
+        auth_key_b64: bytesToB64(authKey),
+    });
+    return {
+        session: wire.session,
+        exp: wire.exp,
+        did: wire.did,
+        handle: wire.handle,
+        blob: b64ToBytes(wire.blob_b64),
+        blobNonce: b64ToBytes(wire.blob_nonce_b64),
+        blobVersion: wire.blob_version,
+    };
+}
+//# sourceMappingURL=auth-api.js.map

package/dist/src/auth.d.ts

@@ -1,3 +1,4 @@
+import { type AithosSessionStore } from "./session-store.js";
 /** Default URL of the Aithos auth backend. */
 export declare const DEFAULT_AUTH_BASE_URL = "https://auth.aithos.be";
 /**
@@ -21,14 +22,20 @@ export interface AithosAuthConfig {
      * shimming jsdom.
      */
     readonly window?: Pick<Window, "location" | "history">;
+    /**
+     * Pluggable session storage. Defaults to {@link sessionStorageStore}
+     * in browser environments, {@link noopStore} elsewhere. See
+     * `./session-store.ts` for built-in alternatives or to roll your own.
+     */
+    readonly sessionStore?: AithosSessionStore;
 }
 /**
- * Payload returned by a successful Google sign-in.
+ * Active Aithos session. Persisted in the configured session store and
+ * surfaced by {@link AithosAuth.getCurrentSession}.
  *
- * Wire-compatible with the auth Lambda's `SsoExchangeResponse`. Field names
- * are kept snake_case to match the backend; rationale: avoids an extra
- * mapping layer and keeps the SDK transparent if the user opens the
- * Network panel.
+ * Wire-compatible with the auth Lambda's `SsoExchangeResponse` and
+ * register/verify payloads ; field names are kept snake_case to match
+ * the backend.
  */
 export interface AithosSession {
     /** HS256 JWT — send in `Authorization: Bearer <session>` to auth/* and
@@ -40,21 +47,20 @@ export interface AithosSession {
     readonly did: string;
     /** User-visible handle (rendered as `@handle`). */
     readonly handle: string;
-    /** Encrypted vault, base64. Empty string + version 0 on first sign-in. */
+    /** Encrypted vault blob, base64. Empty string on first Google sign-in. */
     readonly blob_b64: string;
-    /** AES-GCM nonce for the blob, base64 (12 bytes). Empty on first sign-in. */
+    /** AES-GCM nonce for the blob, base64 (12 bytes). Empty on first Google sign-in. */
     readonly blob_nonce_b64: string;
-    /** Monotonic blob version. Bumped on every PUT /auth/blob. */
+    /** Monotonic blob version. 0 on first Google sign-in. */
     readonly blob_version: number;
-    /** 32-byte vault key, base64. Decrypts {@link blob_b64} via AES-GCM-256. */
+    /** 32-byte vault key, base64. Decrypts {@link blob_b64} via AES-GCM-256.
+     *  Returned by Google SSO ; absent (empty string) for password sign-in
+     *  where the key stays in browser memory only. */
     readonly enc_key_b64: string;
-    /** True the first time this user signs in. The app should run its
-     *  onboarding flow rather than mounting an empty blob. */
+    /** True the first time this user signs in (Google flow only). */
     readonly is_first_login: boolean;
 }
-/**
- * Options for {@link AithosAuth.signInWithGoogle}.
- */
+/** Options for {@link AithosAuth.signInWithGoogle}. */
 export interface SignInWithGoogleOptions {
     /**
      * Opaque deep-link state preserved across the OAuth round-trip and
@@ -66,50 +72,125 @@ export interface SignInWithGoogleOptions {
      */
     readonly appState?: string;
 }
+/** Options for {@link AithosAuth.signIn}. */
+export interface SignInInput {
+    readonly email: string;
+    readonly password: string;
+}
+/** Options for {@link AithosAuth.signUp}. */
+export interface SignUpInput {
+    readonly email: string;
+    readonly password: string;
+    /** Aithos handle (the @-name). 1–63 alphanumeric chars + `_`/`-`. */
+    readonly handle: string;
+    /** Optional human-readable name. Defaults to the handle. */
+    readonly displayName?: string;
+}
+/** Result of {@link AithosAuth.signUp}. */
+export interface SignUpResult {
+    readonly session: AithosSession;
+    /**
+     * Recovery file containing the user's seed material, plaintext at the
+     * V1 spec ; the app should offer this to the user as a download. Lose
+     * this file AND forget the password = lose the ethos.
+     *
+     * Format : JSON, content-type `application/json`. Filename suggestion
+     * exposed as {@link recoveryFilename} for direct use with `<a download>`.
+     */
+    readonly recoveryFile: Blob;
+    /** Suggested filename for {@link recoveryFile}. */
+    readonly recoveryFilename: string;
+}
 /**
  * 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.
+ * is the recommended pattern (the constructor is cheap).
+ *
+ * The class is **stateful** in one specific way : it owns a session store
+ * that gets written on every successful auth call and read by
+ * {@link getCurrentSession}. Pass a custom store at construction time
+ * if you need different persistence (localStorage, IndexedDB, no-op).
  */
 export declare class AithosAuth {
     /** Resolved auth base URL with a trailing slash trimmed. */
     readonly authBaseUrl: string;
     private readonly fetchImpl;
     private readonly win;
+    private readonly store;
     constructor(config?: AithosAuthConfig);
+    /**
+     * Sign in to an existing Aithos account. Two-round-trip flow under the
+     * hood :
+     *
+     *   1. POST /auth/login/challenge → server returns the salts + KDF params
+     *   2. derive auth_key from password + salt (Argon2id)
+     *   3. POST /auth/login/verify → server checks auth_key, returns JWT + blob
+     *
+     * The returned `enc_key_b64` is empty by design : password sign-in
+     * doesn't release the vault key over the wire (it's derived locally
+     * but discarded after the call). Apps that need the seeds — most
+     * apps don't — should use the (forthcoming) `loadEthos` helper
+     * separately with the password still in hand.
+     *
+     * Persists the session in the configured store before returning.
+     */
+    signIn(input: SignInInput): Promise<AithosSession>;
+    /**
+     * Create a new Aithos account end-to-end :
+     *
+     *   1. Generate a fresh `BrowserIdentity` (4 Ed25519/X25519 seeds)
+     *   2. Build the recovery file (plaintext JSON, the user must save it)
+     *   3. Derive auth_key + enc_key from the password (Argon2id, fresh salts)
+     *   4. Encrypt the seeds in a vault blob (AES-GCM-256)
+     *   5. POST /auth/register with everything → JWT
+     *   6. Persist the session and return it + the recovery Blob
+     *
+     * The seeds are NOT published as an Aithos ethos here : the user's
+     * profile on `app.aithos.be` won't appear until they (or another app)
+     * publishes their first edition. This matches `aithos/app`'s design,
+     * where the vault is the source of truth for keys and the published
+     * edition is a separate concern.
+     */
+    signUp(input: SignUpInput): Promise<SignUpResult>;
     /**
      * 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.
      *
-     * Does not return: navigation tears the JS context down. The `never`
+     * Does not return : navigation tears the JS context down. The `never`
      * return type tells callers any code after the call is unreachable.
      */
     signInWithGoogle(opts?: SignInWithGoogleOptions): never;
     /**
      * 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
+     * present, exchange it at the backend, persist the session, and return
+     * it. 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.).
+     * the URL carries `aithos_error=…`.
      */
     handleCallback(): Promise<AithosSession | null>;
     /**
      * Programmatically redeem an `aithos_code` for a session. `handleCallback`
-     * calls this for you; expose it directly for callers that already pulled
+     * calls this for you ; expose it directly for callers that already pulled
      * the code out of the URL via their own router.
+     *
+     * Note : this method does NOT persist the session — it's the lower-level
+     * primitive. Use `handleCallback` for the full pipe.
      */
     exchange(aithosCode: string): Promise<AithosSession>;
     /**
-     * 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.
+     * Read the active session from the configured store. Returns null if
+     * the user is signed out, or if the JWT has expired (the store
+     * auto-evicts expired entries — see ./session-store.ts).
+     */
+    getCurrentSession(): AithosSession | null;
+    /**
+     * Stateless sign-out — the Aithos backend doesn't track sessions, so
+     * there's nothing to revoke server-side ; this method clears the
+     * configured session store and resolves.
      */
     signOut(): Promise<void>;
 }

package/dist/src/auth.js

@@ -1,32 +1,38 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright 2026 Mathieu Colla
-// Sign in with Google for Aithos apps.
+// Aithos auth — sign-up, sign-in, sign-in-with-Google.
 //
-// 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.
-//
-// Flow from the caller's point of view:
+// One class, three flows, automatic session persistence. Apps shouldn't
+// need to touch Argon2id, AES-GCM, or {@link sessionStorage} directly :
 //
 //   const auth = new AithosAuth();
-//   // on a "Sign in" button:
-//   auth.signInWithGoogle({ appState: "/dashboard" });   // navigates away
 //
-//   // on the redirect-back page (e.g. /auth/callback):
+//   // Sign in (existing account, email + password)
+//   const session = await auth.signIn({ email, password });
+//
+//   // Sign up (creates an Aithos identity end-to-end)
+//   const { recoveryFile, ...session } = await auth.signUp({
+//     email, password, handle, displayName,
+//   });
+//
+//   // Sign in with Google — redirects to Google's consent screen
+//   auth.signInWithGoogle({ appState: "/dashboard" });
+//
+//   // Back on /auth/callback after Google
 //   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.
+//   // Anywhere — read the active session, null if signed out / expired
+//   const current = auth.getCurrentSession();
+//
+//   // Sign out — clears the session store
+//   await auth.signOut();
+//
+// Storage : by default, sessions are persisted in `sessionStorage` (web)
+// or no-op (Node / SSR). Apps with different needs pass their own
+// `AithosSessionStore` to the constructor — see ./session-store.ts.
+import { DEFAULT_KDF, buildBlobPlaintext, createBrowserIdentity, deriveAuthAndEncKeys, encryptBlob, randomNonce, randomSalt, serializeBlob, zeroize, } from "@aithos/protocol-client";
+import { loginChallenge, loginVerify, registerAccount, } from "./auth-api.js";
+import { defaultSessionStore, } from "./session-store.js";
 import { AithosSDKError } from "./types.js";
 /** Default URL of the Aithos auth backend. */
 export const DEFAULT_AUTH_BASE_URL = "https://auth.aithos.be";
@@ -35,25 +41,185 @@ export const DEFAULT_AUTH_BASE_URL = "https://auth.aithos.be";
 /* -------------------------------------------------------------------------- */
 /**
  * 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.
+ * is the recommended pattern (the constructor is cheap).
+ *
+ * The class is **stateful** in one specific way : it owns a session store
+ * that gets written on every successful auth call and read by
+ * {@link getCurrentSession}. Pass a custom store at construction time
+ * if you need different persistence (localStorage, IndexedDB, no-op).
  */
 export class AithosAuth {
     /** Resolved auth base URL with a trailing slash trimmed. */
     authBaseUrl;
     fetchImpl;
     win;
+    store;
     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.store = config.sessionStore ?? defaultSessionStore();
     }
+    /* ------------------------------------------------------------------------ */
+    /*  Email + password                                                         */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Sign in to an existing Aithos account. Two-round-trip flow under the
+     * hood :
+     *
+     *   1. POST /auth/login/challenge → server returns the salts + KDF params
+     *   2. derive auth_key from password + salt (Argon2id)
+     *   3. POST /auth/login/verify → server checks auth_key, returns JWT + blob
+     *
+     * The returned `enc_key_b64` is empty by design : password sign-in
+     * doesn't release the vault key over the wire (it's derived locally
+     * but discarded after the call). Apps that need the seeds — most
+     * apps don't — should use the (forthcoming) `loadEthos` helper
+     * separately with the password still in hand.
+     *
+     * Persists the session in the configured store before returning.
+     */
+    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);
+        // We don't keep enc_key around for the password flow — apps that
+        // need it can call deriveAuthAndEncKeys themselves with the password
+        // still available in their UI state. Wipe to be defensive.
+        zeroize(encKey);
+        let verify;
+        try {
+            verify = await loginVerify({ fetchImpl: this.fetchImpl, authBaseUrl: this.authBaseUrl }, input.email, authKey);
+        }
+        finally {
+            zeroize(authKey);
+        }
+        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.store.set(session);
+        return session;
+    }
+    /**
+     * Create a new Aithos account end-to-end :
+     *
+     *   1. Generate a fresh `BrowserIdentity` (4 Ed25519/X25519 seeds)
+     *   2. Build the recovery file (plaintext JSON, the user must save it)
+     *   3. Derive auth_key + enc_key from the password (Argon2id, fresh salts)
+     *   4. Encrypt the seeds in a vault blob (AES-GCM-256)
+     *   5. POST /auth/register with everything → JWT
+     *   6. Persist the session and return it + the recovery Blob
+     *
+     * The seeds are NOT published as an Aithos ethos here : the user's
+     * profile on `app.aithos.be` won't appear until they (or another app)
+     * publishes their first edition. This matches `aithos/app`'s design,
+     * where the vault is the source of truth for keys and the published
+     * edition is a separate concern.
+     */
+    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;
+        // 1) Identity.
+        const identity = createBrowserIdentity(input.handle, displayName);
+        // 2) Recovery file — same shape as @aithos/protocol-client emits in
+        //    `runOnboarding`, plaintext v0.1.0.
+        const recoveryJson = {
+            aithos_recovery_version: "0.1.0-plaintext",
+            handle: identity.handle,
+            display_name: identity.displayName,
+            did: identity.did,
+            seeds_hex: {
+                root: bytesToHex(identity.root.seed),
+                public: bytesToHex(identity.public.seed),
+                circle: bytesToHex(identity.circle.seed),
+                self: bytesToHex(identity.self.seed),
+            },
+            saved_at: new Date().toISOString(),
+        };
+        const recoveryFile = new Blob([JSON.stringify(recoveryJson, null, 2)], { type: "application/json" });
+        const recoveryFilename = `aithos-recovery-${identity.handle}.json`;
+        // 3) Derive password-based keys.
+        const authSalt = randomSalt();
+        const encSalt = randomSalt();
+        const kdf = DEFAULT_KDF;
+        const { authKey, encKey } = await deriveAuthAndEncKeys(input.password, authSalt, encSalt, kdf);
+        // 4) Build & encrypt the vault blob.
+        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);
+        // 5) Register.
+        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);
+        }
+        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.store.set(session);
+        return { session, recoveryFile, recoveryFilename };
+    }
+    /* ------------------------------------------------------------------------ */
+    /*  Google SSO                                                               */
+    /* ------------------------------------------------------------------------ */
     /**
      * 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.
      *
-     * Does not return: navigation tears the JS context down. The `never`
+     * Does not return : navigation tears the JS context down. The `never`
      * return type tells callers any code after the call is unreachable.
      */
     signInWithGoogle(opts) {
@@ -68,21 +234,20 @@ export class AithosAuth {
             url.searchParams.set("app_state", opts.appState);
         }
         this.win.location.assign(url.toString());
-        // Unreachable: location.assign navigates synchronously. The throw is
+        // Unreachable : location.assign navigates synchronously. The throw is
         // belt-and-braces in case a caller awaits a microtask before unload.
         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
+     * present, exchange it at the backend, persist the session, and return
+     * it. 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.).
+     * the URL carries `aithos_error=…`.
      */
     async handleCallback() {
         if (!this.win)
@@ -99,12 +264,16 @@ export class AithosAuth {
             return null;
         const session = await this.exchange(code);
         cleanCallbackParams(this.win, here);
+        this.store.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
+     * calls this for you ; expose it directly for callers that already pulled
      * the code out of the URL via their own router.
+     *
+     * Note : this method does NOT persist the session — it's the lower-level
+     * primitive. Use `handleCallback` for the full pipe.
      */
     async exchange(aithosCode) {
         const res = await this.fetchImpl(`${this.authBaseUrl}/auth/sso/exchange`, {
@@ -120,7 +289,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 +302,24 @@ export class AithosAuth {
         }
         return (await res.json());
     }
+    /* ------------------------------------------------------------------------ */
+    /*  Session lifecycle                                                        */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Read the active session from the configured store. Returns null if
+     * the user is signed out, or if the JWT has expired (the store
+     * auto-evicts expired entries — see ./session-store.ts).
+     */
+    getCurrentSession() {
+        return this.store.get();
+    }
     /**
-     * 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.
+     * Stateless sign-out — the Aithos backend doesn't track sessions, so
+     * there's nothing to revoke server-side ; this method clears the
+     * configured session store and resolves.
      */
     async signOut() {
-        /* no-op; sessions are stateless JWTs. */
+        this.store.clear();
     }
 }
 /* -------------------------------------------------------------------------- */
@@ -153,4 +334,22 @@ function cleanCallbackParams(win, url) {
     url.searchParams.delete("app_state");
     win.history.replaceState(null, "", url.toString());
 }
+// Local copy of bytesToB64 — protocol-client exports it but we keep a
+// thin local wrapper to avoid a name collision with public surface and
+// to flag this is the "encode for the wire" path, not the "encode an
+// auth_key" path.
+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 bytesToHex(b) {
+    let out = "";
+    for (let i = 0; i < b.length; i++)
+        out += b[i].toString(16).padStart(2, "0");
+    return out;
+}
 //# sourceMappingURL=auth.js.map

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.1.0-alpha.3";
+export declare const VERSION = "0.1.0-alpha.4";
 export { AithosSDK } from "./sdk.js";
 export type { AithosSDKConfig } from "./types.js";
 export { AithosSDKError } from "./types.js";
@@ -9,7 +9,8 @@ export { ComputeNamespace } from "./compute.js";
 export type { CreditPackId, CreateTopupSessionArgs, CreateTopupSessionResult, GetBalanceArgs, GetBalanceResult, } from "./wallet.js";
 export { WalletNamespace } from "./wallet.js";
 export { AithosAuth, DEFAULT_AUTH_BASE_URL } from "./auth.js";
-export type { AithosAuthConfig, AithosSession, SignInWithGoogleOptions, } from "./auth.js";
+export type { AithosAuthConfig, AithosSession, SignInInput, SignInWithGoogleOptions, SignUpInput, SignUpResult, } from "./auth.js";
+export { DEFAULT_SESSION_STORAGE_KEY, defaultSessionStore, localStorageStore, noopStore, sessionStorageStore, type AithosSessionStore, } from "./session-store.js";
 export * as ethos from "./ethos.js";
 export * as onboarding from "./onboarding.js";
 export * as mandates from "./mandates.js";

package/dist/src/index.js

@@ -17,16 +17,22 @@
 // Public types specific to the SDK (`AithosSDKConfig`, `AithosSDKError`)
 // are exported from here. Endpoint config (`AithosSdkEndpoints`,
 // `DEFAULT_SDK_ENDPOINTS`) likewise.
-export const VERSION = "0.1.0-alpha.3";
+export const VERSION = "0.1.0-alpha.4";
 export { AithosSDK } from "./sdk.js";
 export { AithosSDKError } from "./types.js";
 export { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
 export { ComputeNamespace } from "./compute.js";
 export { WalletNamespace } from "./wallet.js";
-// Sign in with Google (and future SSO providers). Lives outside the
-// AithosSDK class because the auth flow runs *before* the user has a
-// BrowserIdentity — that's what the flow returns (via the encrypted blob).
+// Sign-up, sign-in, sign-in-with-Google. Lives outside the AithosSDK
+// class because the auth flow runs *before* the user has a
+// BrowserIdentity (sign-up creates one, sign-in restores it from the
+// server). The class also owns the session store — see
+// ./session-store.ts for pluggable persistence.
 export { AithosAuth, DEFAULT_AUTH_BASE_URL } from "./auth.js";
+// Session storage backends used by AithosAuth. `sessionStorageStore` is
+// the default in browser environments ; pass another store at construction
+// time if you need different persistence.
+export { DEFAULT_SESSION_STORAGE_KEY, defaultSessionStore, localStorageStore, noopStore, sessionStorageStore, } from "./session-store.js";
 // Re-exports under stable namespace modules. Apps may also import these
 // directly via `@aithos/protocol-client`; the SDK simply curates them.
 export * as ethos from "./ethos.js";

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

@@ -0,0 +1,58 @@
+import type { AithosSession } from "./auth.js";
+/**
+ * Pluggable storage backend for the active session.
+ *
+ * Implementations should be **synchronous** : the SDK reads the store on
+ * boot to surface `getCurrentSession()` and async storage would force a
+ * Promise everywhere it's not warranted. Async backends should pre-warm
+ * the cache during the app's bootstrap and then implement the methods
+ * over that cache.
+ *
+ * `set` is called after every successful sign-in / sign-up / Google
+ * callback exchange. `clear` is called on `signOut`. `get` is called by
+ * `getCurrentSession()` and may also be called by the app on boot.
+ */
+export interface AithosSessionStore {
+    /** Read the persisted session. Return null if none, or if it's expired. */
+    get(): AithosSession | null;
+    /** Persist the session. Implementations should not throw — at worst
+     *  they should warn and silently no-op (e.g. quota exceeded). */
+    set(session: AithosSession): void;
+    /** Wipe the persisted session. */
+    clear(): void;
+}
+/**
+ * Storage key used by the bundled stores. Apps that want to coexist with
+ * other Aithos-aware libs (or that want to scope sessions per-tenant) can
+ * pass a custom key via {@link sessionStorageStore} or
+ * {@link localStorageStore}.
+ */
+export declare const DEFAULT_SESSION_STORAGE_KEY = "aithos.session.v1";
+interface WebStorageStoreOptions {
+    /** Storage key. Defaults to {@link DEFAULT_SESSION_STORAGE_KEY}. */
+    readonly key?: string;
+}
+/**
+ * Default web store : `sessionStorage`. The session lives until the tab
+ * is closed. Cleared on `signOut()`. Use this when reauthenticating each
+ * day is acceptable and reduces blast radius after an XSS.
+ */
+export declare function sessionStorageStore(opts?: WebStorageStoreOptions): AithosSessionStore;
+/**
+ * `localStorage` store. The session persists until the JWT expires or the
+ * user explicitly signs out. Higher convenience, larger XSS blast radius.
+ */
+export declare function localStorageStore(opts?: WebStorageStoreOptions): AithosSessionStore;
+/**
+ * No-op store. `set` and `clear` discard their input ; `get` always
+ * returns null. The default in non-browser contexts (Node, edge runtimes)
+ * — apps running there should pass their own store explicitly.
+ */
+export declare function noopStore(): AithosSessionStore;
+/**
+ * Pick a sensible default : `sessionStorage` if the browser environment
+ * is available, {@link noopStore} otherwise.
+ */
+export declare function defaultSessionStore(): AithosSessionStore;
+export {};
+//# sourceMappingURL=session-store.d.ts.map

package/dist/src/session-store.js

@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/* -------------------------------------------------------------------------- */
+/*  Storage key & expiration                                                   */
+/* -------------------------------------------------------------------------- */
+/**
+ * Storage key used by the bundled stores. Apps that want to coexist with
+ * other Aithos-aware libs (or that want to scope sessions per-tenant) can
+ * pass a custom key via {@link sessionStorageStore} or
+ * {@link localStorageStore}.
+ */
+export const DEFAULT_SESSION_STORAGE_KEY = "aithos.session.v1";
+/** Conservative buffer — drop the session 30 s before its `exp` so we
+ *  don't hand out a token the server is about to reject. */
+const SESSION_EXPIRY_BUFFER_S = 30;
+function isExpired(session, nowSec) {
+    return session.exp <= nowSec + SESSION_EXPIRY_BUFFER_S;
+}
+/**
+ * Validate at runtime that an opaque object looks like an `AithosSession`.
+ * Storage values come from JSON.parse over user-controlled data — we can't
+ * trust them blind. This isn't a security check (the server validates the
+ * JWT ; persistence layers don't authenticate themselves) ; it just
+ * prevents weird crashes when the storage was tampered with.
+ */
+function isSessionShaped(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const o = v;
+    return (typeof o["session"] === "string" &&
+        typeof o["exp"] === "number" &&
+        typeof o["did"] === "string" &&
+        typeof o["handle"] === "string");
+}
+function browserStorageStore(storageRef, opts = {}) {
+    const key = opts.key ?? DEFAULT_SESSION_STORAGE_KEY;
+    return {
+        get() {
+            const s = storageRef();
+            if (!s)
+                return null;
+            let raw;
+            try {
+                raw = s.getItem(key);
+            }
+            catch {
+                return null;
+            }
+            if (!raw)
+                return null;
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                // Corrupted entry — wipe to recover.
+                try {
+                    s.removeItem(key);
+                }
+                catch {
+                    /* ignore */
+                }
+                return null;
+            }
+            if (!isSessionShaped(parsed))
+                return null;
+            const nowSec = Math.floor(Date.now() / 1000);
+            if (isExpired(parsed, nowSec)) {
+                // Auto-evict — let the caller see "no session" and re-auth.
+                try {
+                    s.removeItem(key);
+                }
+                catch {
+                    /* ignore */
+                }
+                return null;
+            }
+            return parsed;
+        },
+        set(session) {
+            const s = storageRef();
+            if (!s)
+                return;
+            try {
+                s.setItem(key, JSON.stringify(session));
+            }
+            catch (e) {
+                // Quota exceeded, private mode, etc. — log but don't throw : the
+                // sign-in returned successfully, the in-memory session is still
+                // usable for this tab.
+                // eslint-disable-next-line no-console
+                console.warn("[AithosAuth] failed to persist session:", e.message);
+            }
+        },
+        clear() {
+            const s = storageRef();
+            if (!s)
+                return;
+            try {
+                s.removeItem(key);
+            }
+            catch {
+                /* ignore */
+            }
+        },
+    };
+}
+function safeStorage(getter) {
+    return () => {
+        try {
+            const s = getter();
+            return s ?? null;
+        }
+        catch {
+            // Some restricted contexts (sandboxed iframes, file:// URLs) throw
+            // on access. Treat them as "no storage available".
+            return null;
+        }
+    };
+}
+/**
+ * Default web store : `sessionStorage`. The session lives until the tab
+ * is closed. Cleared on `signOut()`. Use this when reauthenticating each
+ * day is acceptable and reduces blast radius after an XSS.
+ */
+export function sessionStorageStore(opts) {
+    return browserStorageStore(safeStorage(() => (typeof sessionStorage !== "undefined" ? sessionStorage : undefined)), opts);
+}
+/**
+ * `localStorage` store. The session persists until the JWT expires or the
+ * user explicitly signs out. Higher convenience, larger XSS blast radius.
+ */
+export function localStorageStore(opts) {
+    return browserStorageStore(safeStorage(() => (typeof localStorage !== "undefined" ? localStorage : undefined)), opts);
+}
+/**
+ * No-op store. `set` and `clear` discard their input ; `get` always
+ * returns null. The default in non-browser contexts (Node, edge runtimes)
+ * — apps running there should pass their own store explicitly.
+ */
+export function noopStore() {
+    return {
+        get: () => null,
+        set: () => { },
+        clear: () => { },
+    };
+}
+/**
+ * Pick a sensible default : `sessionStorage` if the browser environment
+ * is available, {@link noopStore} otherwise.
+ */
+export function defaultSessionStore() {
+    if (typeof sessionStorage !== "undefined") {
+        return sessionStorageStore();
+    }
+    return noopStore();
+}
+//# sourceMappingURL=session-store.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.4",
   "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",
@@ -52,10 +52,10 @@
     "node": ">=20"
   },
   "peerDependencies": {
-    "@aithos/protocol-client": ">=0.1.0-alpha.7 <0.2.0"
+    "@aithos/protocol-client": ">=0.1.0-alpha.11 <0.2.0"
   },
   "devDependencies": {
-    "@aithos/protocol-client": "^0.1.0-alpha.7",
+    "@aithos/protocol-client": "^0.1.0-alpha.11",
     "@types/node": "^24.12.2",
     "typescript": "^5.9.2"
   },