@aithos/sdk 0.1.0-alpha.2 → 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

@@ -0,0 +1,197 @@
+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";
+/**
+ * Construction options for {@link AithosAuth}.
+ */
+export interface AithosAuthConfig {
+    /**
+     * Base URL of the Aithos auth backend. Defaults to
+     * {@link DEFAULT_AUTH_BASE_URL}. Override for staging or self-hosted
+     * deployments.
+     */
+    readonly authBaseUrl?: string;
+    /**
+     * Optional `fetch` implementation. Defaults to `globalThis.fetch`. Used
+     * by tests to inject a mock without monkeypatching globals.
+     */
+    readonly fetch?: typeof fetch;
+    /**
+     * Optional `window`-like object. Defaults to `globalThis.window` when
+     * available. Provided so node-side tests can assert redirect URLs without
+     * 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;
+}
+/**
+ * Active Aithos session. Persisted in the configured session store and
+ * surfaced by {@link AithosAuth.getCurrentSession}.
+ *
+ * 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
+     *  app endpoints that consume it. */
+    readonly session: string;
+    /** JWT expiry, Unix seconds. */
+    readonly exp: number;
+    /** Aithos DID — `did:aithos:z…`. Stable across all the user's devices. */
+    readonly did: string;
+    /** User-visible handle (rendered as `@handle`). */
+    readonly handle: string;
+    /** 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 Google sign-in. */
+    readonly blob_nonce_b64: string;
+    /** 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.
+     *  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 (Google flow only). */
+    readonly is_first_login: boolean;
+}
+/** Options for {@link AithosAuth.signInWithGoogle}. */
+export interface SignInWithGoogleOptions {
+    /**
+     * Opaque deep-link state preserved across the OAuth round-trip and
+     * surfaced back to the app via `?app_state=…` on the callback URL. Use
+     * to remember "the user clicked sign-in from /settings/billing" so you
+     * can restore that route after the redirect chain.
+     *
+     * Maximum 1024 characters.
+     */
+    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).
+ *
+ * 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`
+     * 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, 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=…`.
+     */
+    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
+     * 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>;
+    /**
+     * 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>;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/src/auth.js

@@ -0,0 +1,355 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Aithos auth — sign-up, sign-in, sign-in-with-Google.
+//
+// One class, three flows, automatic session persistence. Apps shouldn't
+// need to touch Argon2id, AES-GCM, or {@link sessionStorage} directly :
+//
+//   const auth = new AithosAuth();
+//
+//   // 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();
+//
+//   // 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";
+/* -------------------------------------------------------------------------- */
+/*  AithosAuth                                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * Authenticator for the Aithos identity service. One instance per app
+ * 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`
+     * return type tells callers any code after the call is unreachable.
+     */
+    signInWithGoogle(opts) {
+        if (!this.win) {
+            throw new AithosSDKError("auth_no_window", "AithosAuth.signInWithGoogle requires a browser window");
+        }
+        const url = new URL(`${this.authBaseUrl}/auth/sso/google/start`);
+        if (opts?.appState) {
+            if (opts.appState.length > 1024) {
+                throw new AithosSDKError("auth_app_state_too_long", "appState must be ≤ 1024 chars");
+            }
+            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.
+        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, 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=…`.
+     */
+    async handleCallback() {
+        if (!this.win)
+            return null;
+        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);
+            throw new AithosSDKError(`auth_${error}`, `Sign-in failed: ${error}`, { data: appState ? { app_state: appState } : undefined });
+        }
+        if (!code)
+            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
+     * 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`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ aithos_code: aithosCode }),
+        });
+        if (!res.ok) {
+            let body;
+            try {
+                body = (await res.json());
+            }
+            catch {
+                // ignore non-JSON error body
+            }
+            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})`;
+            throw new AithosSDKError(code, message, {
+                status: res.status,
+                ...(body !== undefined ? { data: body } : {}),
+            });
+        }
+        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 clears the
+     * configured session store and resolves.
+     */
+    async signOut() {
+        this.store.clear();
+    }
+}
+/* -------------------------------------------------------------------------- */
+/*  Helpers                                                                   */
+/* -------------------------------------------------------------------------- */
+function trimSlash(url) {
+    return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+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());
+}
+// 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.2";
+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";
@@ -8,6 +8,9 @@ export type { ComputeMessage, InvokeBedrockArgs, InvokeBedrockResult, StopReason
 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, 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,12 +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.2";
+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-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/dist/test/auth.test.d.ts

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

package/dist/test/auth.test.js

@@ -0,0 +1,175 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Unit tests for AithosAuth — Sign in with Google flow.
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { AithosAuth, AithosSDKError } from "../src/index.js";
+/** Tiny window-shim that records calls instead of actually navigating. */
+function makeFakeWindow(initialHref) {
+    let href = initialHref;
+    let assigned = null;
+    let replacedHref = null;
+    const win = {
+        location: {
+            get href() {
+                return href;
+            },
+            assign(target) {
+                assigned = target;
+            },
+        },
+        history: {
+            replaceState(_state, _title, url) {
+                replacedHref = url;
+                href = url;
+            },
+        },
+    };
+    return {
+        win: win,
+        get assigned() {
+            return assigned;
+        },
+        get replacedHref() {
+            return replacedHref;
+        },
+    };
+}
+function fakeSession(overrides = {}) {
+    return {
+        session: "jwt-token-here",
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        did: "did:aithos:zABC123",
+        handle: "alice-x9y2",
+        blob_b64: "",
+        blob_nonce_b64: "",
+        blob_version: 0,
+        enc_key_b64: "MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTI=",
+        is_first_login: true,
+        ...overrides,
+    };
+}
+/* -------------------------------------------------------------------------- */
+/*  signInWithGoogle                                                          */
+/* -------------------------------------------------------------------------- */
+describe("AithosAuth.signInWithGoogle", () => {
+    it("navigates to /auth/sso/google/start with no params by default", () => {
+        const w = makeFakeWindow("https://app.aithos.be/login");
+        const auth = new AithosAuth({
+            authBaseUrl: "https://auth.example.test",
+            window: w.win,
+        });
+        assert.throws(() => auth.signInWithGoogle(), AithosSDKError);
+        assert.equal(w.assigned, "https://auth.example.test/auth/sso/google/start");
+    });
+    it("forwards appState as the app_state query param", () => {
+        const w = makeFakeWindow("https://app.aithos.be/login");
+        const auth = new AithosAuth({
+            authBaseUrl: "https://auth.example.test",
+            window: w.win,
+        });
+        assert.throws(() => auth.signInWithGoogle({ appState: "/dashboard" }), AithosSDKError);
+        const url = new URL(w.assigned);
+        assert.equal(url.searchParams.get("app_state"), "/dashboard");
+    });
+    it("rejects appState longer than 1024 chars without navigating", () => {
+        const w = makeFakeWindow("https://app.aithos.be/login");
+        const auth = new AithosAuth({
+            authBaseUrl: "https://auth.example.test",
+            window: w.win,
+        });
+        const tooLong = "x".repeat(1025);
+        assert.throws(() => auth.signInWithGoogle({ appState: tooLong }), (e) => e instanceof AithosSDKError && e.code === "auth_app_state_too_long");
+        assert.equal(w.assigned, null, "must not have navigated");
+    });
+    it("trims a trailing slash from authBaseUrl", () => {
+        const w = makeFakeWindow("https://app.aithos.be/");
+        const auth = new AithosAuth({
+            authBaseUrl: "https://auth.example.test/",
+            window: w.win,
+        });
+        assert.throws(() => auth.signInWithGoogle(), AithosSDKError);
+        assert.equal(w.assigned, "https://auth.example.test/auth/sso/google/start");
+    });
+});
+/* -------------------------------------------------------------------------- */
+/*  handleCallback                                                            */
+/* -------------------------------------------------------------------------- */
+describe("AithosAuth.handleCallback", () => {
+    it("returns null when the URL has no aithos_code", async () => {
+        const w = makeFakeWindow("https://app.aithos.be/auth/callback");
+        const auth = new AithosAuth({ window: w.win, fetch: undefinedFetch() });
+        const session = await auth.handleCallback();
+        assert.equal(session, null);
+    });
+    it("exchanges the code, returns the session, and strips query params", async () => {
+        const w = makeFakeWindow("https://app.aithos.be/auth/callback?aithos_code=abc123XYZ_-456&app_state=/dashboard");
+        const session = fakeSession({ is_first_login: true });
+        let capturedBody;
+        const fakeFetch = async (input, init) => {
+            assert.equal(typeof input === "string" ? input : input.toString(), "https://auth.example.test/auth/sso/exchange");
+            capturedBody = JSON.parse(init?.body);
+            return new Response(JSON.stringify(session), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        };
+        const auth = new AithosAuth({
+            authBaseUrl: "https://auth.example.test",
+            window: w.win,
+            fetch: fakeFetch,
+        });
+        const out = await auth.handleCallback();
+        assert.deepEqual(out, session);
+        assert.equal(capturedBody?.aithos_code, "abc123XYZ_-456");
+        assert.equal(w.replacedHref, "https://app.aithos.be/auth/callback", "callback params must be stripped from the URL");
+    });
+    it("throws AithosSDKError with the backend code on aithos_error", async () => {
+        const w = makeFakeWindow("https://app.aithos.be/auth/callback?aithos_error=google_id_token&app_state=/dashboard");
+        const auth = new AithosAuth({
+            authBaseUrl: "https://auth.example.test",
+            window: w.win,
+            fetch: undefinedFetch(),
+        });
+        await assert.rejects(auth.handleCallback(), (e) => e instanceof AithosSDKError && e.code === "auth_google_id_token");
+        // URL is cleaned even on error so a refresh doesn't loop the message.
+        assert.equal(w.replacedHref, "https://app.aithos.be/auth/callback");
+    });
+    it("wraps a 410 'code_consumed' as AithosSDKError(code='auth_code_consumed')", async () => {
+        const w = makeFakeWindow("https://app.aithos.be/auth/callback?aithos_code=abc123XYZ_-456");
+        const fakeFetch = async () => new Response(JSON.stringify({ error: "aithos_code expired or already used", code: "code_consumed" }), { status: 410, headers: { "content-type": "application/json" } });
+        const auth = new AithosAuth({
+            authBaseUrl: "https://auth.example.test",
+            window: w.win,
+            fetch: fakeFetch,
+        });
+        await assert.rejects(auth.handleCallback(), (e) => e instanceof AithosSDKError &&
+            e.code === "auth_code_consumed" &&
+            e.status === 410);
+    });
+    it("returns null in non-browser environments (no window)", async () => {
+        // No `window` injected and `globalThis.window` is undefined under Node test.
+        const auth = new AithosAuth({ window: undefined, fetch: undefinedFetch() });
+        const session = await auth.handleCallback();
+        assert.equal(session, null);
+    });
+});
+/* -------------------------------------------------------------------------- */
+/*  signOut                                                                   */
+/* -------------------------------------------------------------------------- */
+describe("AithosAuth.signOut", () => {
+    it("resolves immediately (sessions are stateless)", async () => {
+        const auth = new AithosAuth({ window: undefined, fetch: undefinedFetch() });
+        await auth.signOut();
+    });
+});
+/* -------------------------------------------------------------------------- */
+/*  Helpers                                                                   */
+/* -------------------------------------------------------------------------- */
+/** A fetch that fails the test if invoked — for code paths that mustn't fetch. */
+function undefinedFetch() {
+    return async () => {
+        throw new Error("fetch should not have been called");
+    };
+}
+//# sourceMappingURL=auth.test.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.2",
+  "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"
   },