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

package/dist/src/auth.d.ts

@@ -0,0 +1,116 @@
+/** 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">;
+}
+/**
+ * Payload returned by a successful Google sign-in.
+ *
+ * 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.
+ */
+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, base64. Empty string + version 0 on first sign-in. */
+    readonly blob_b64: string;
+    /** AES-GCM nonce for the blob, base64 (12 bytes). Empty on first sign-in. */
+    readonly blob_nonce_b64: string;
+    /** Monotonic blob version. Bumped on every PUT /auth/blob. */
+    readonly blob_version: number;
+    /** 32-byte vault key, base64. Decrypts {@link blob_b64} via AES-GCM-256. */
+    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. */
+    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;
+}
+/**
+ * Authenticator for the Aithos identity service. One instance per app
+ * is the recommended pattern (the constructor is cheap; it just trims the
+ * URL). All methods are pure — no module-global state.
+ */
+export declare class AithosAuth {
+    /** Resolved auth base URL with a trailing slash trimmed. */
+    readonly authBaseUrl: string;
+    private readonly fetchImpl;
+    private readonly win;
+    constructor(config?: AithosAuthConfig);
+    /**
+     * 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 and return the resulting
+     * {@link AithosSession}. The query params are stripped from the URL via
+     * `history.replaceState` so a page refresh doesn't replay the redeem
+     * (which would 410 anyway).
+     *
+     * Returns `null` when there's no code in the URL — safe to call on every
+     * page load. Throws {@link AithosSDKError} on backend errors or when
+     * the URL carries `aithos_error=…` (Google denial, token-exchange
+     * failure, etc.).
+     */
+    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.
+     */
+    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.
+     */
+    signOut(): Promise<void>;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/src/auth.js

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Sign in with Google for Aithos apps.
+//
+// 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:
+//
+//   const auth = new AithosAuth();
+//   // on a "Sign in" button:
+//   auth.signInWithGoogle({ appState: "/dashboard" });   // navigates away
+//
+//   // on the redirect-back page (e.g. /auth/callback):
+//   const session = await auth.handleCallback();
+//   if (session) {
+//     // session.session     — JWT, send as Bearer to /auth/blob etc.
+//     // session.enc_key_b64 — 32-byte vault key, base64 (raw bytes for
+//     //                        AES-GCM decryption of session.blob_b64)
+//     // session.is_first_login — true on the very first sign-in
+//   }
+//
+// We deliberately don't persist anything in this module — storage is the
+// app's call (its threat model, its choices around localStorage vs
+// sessionStorage vs IndexedDB). See README "Auth — sessions and storage"
+// for the recommended patterns.
+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; it just trims the
+ * URL). All methods are pure — no module-global state.
+ */
+export class AithosAuth {
+    /** Resolved auth base URL with a trailing slash trimmed. */
+    authBaseUrl;
+    fetchImpl;
+    win;
+    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);
+    }
+    /**
+     * 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 and return the resulting
+     * {@link AithosSession}. The query params are stripped from the URL via
+     * `history.replaceState` so a page refresh doesn't replay the redeem
+     * (which would 410 anyway).
+     *
+     * Returns `null` when there's no code in the URL — safe to call on every
+     * page load. Throws {@link AithosSDKError} on backend errors or when
+     * the URL carries `aithos_error=…` (Google denial, token-exchange
+     * failure, etc.).
+     */
+    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);
+        return session;
+    }
+    /**
+     * Programmatically redeem an `aithos_code` for a session. `handleCallback`
+     * calls this for you; expose it directly for callers that already pulled
+     * the code out of the URL via their own router.
+     */
+    async exchange(aithosCode) {
+        const res = await this.fetchImpl(`${this.authBaseUrl}/auth/sso/exchange`, {
+            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());
+    }
+    /**
+     * 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.
+     */
+    async signOut() {
+        /* no-op; sessions are stateless JWTs. */
+    }
+}
+/* -------------------------------------------------------------------------- */
+/*  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());
+}
+//# sourceMappingURL=auth.js.map

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.1.0-alpha.0";
+export declare const VERSION = "0.1.0-alpha.3";
 export { AithosSDK } from "./sdk.js";
 export type { AithosSDKConfig } from "./types.js";
 export { AithosSDKError } from "./types.js";
@@ -6,8 +6,10 @@ export type { AithosSdkEndpoints } from "./endpoints.js";
 export { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
 export type { ComputeMessage, InvokeBedrockArgs, InvokeBedrockResult, StopReason, } from "./compute.js";
 export { ComputeNamespace } from "./compute.js";
-export type { CreditPackId, CreateTopupSessionArgs, CreateTopupSessionResult, } from "./wallet.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 * 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,16 @@
 // 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.0";
+export const VERSION = "0.1.0-alpha.3";
 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).
+export { AithosAuth, DEFAULT_AUTH_BASE_URL } from "./auth.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/sdk.js

@@ -47,6 +47,8 @@ export class AithosSDK {
             fetch: fetchImpl,
         });
         this.wallet = new WalletNamespace({
+            identity: config.identity,
+            appDid: config.appDid,
             userDid: config.identity.did,
             endpoints: this.endpoints,
             fetch: fetchImpl,

package/dist/src/wallet.d.ts

@@ -1,3 +1,4 @@
+import { type BrowserIdentity } from "@aithos/protocol-client";
 import { type AithosSdkEndpoints } from "./endpoints.js";
 /**
  * Canonical credit-pack identifiers. Pricing and microcredit amounts are
@@ -24,7 +25,30 @@ export interface CreateTopupSessionResult {
     /** Stripe Checkout session id (for diagnostics). */
     readonly sessionId: string;
 }
+export interface GetBalanceArgs {
+    /** Abort signal to cancel the request. */
+    readonly signal?: AbortSignal;
+}
+export interface GetBalanceResult {
+    /** Current wallet balance in microcredits. 0 if the wallet does not yet exist. */
+    readonly balance: number;
+    /**
+     * Microcredits spent today. Resets server-side at midnight UTC.
+     * Useful for showing "X / daily cap" UI.
+     */
+    readonly dailySpent: number;
+    /**
+     * Whether a wallet row exists for this DID. False on a never-funded
+     * identity — `balance` will be 0 in that case.
+     */
+    readonly exists: boolean;
+}
 export interface WalletNamespaceDeps {
+    /** User identity — needed to sign the balance-lookup envelope. */
+    readonly identity: BrowserIdentity;
+    /** App DID — sent as audit attribution alongside the balance request. */
+    readonly appDid: string;
+    /** Pre-resolved DID convenience accessor (mirrors identity.did). */
     readonly userDid: string;
     readonly endpoints: AithosSdkEndpoints;
     readonly fetch: typeof fetch;
@@ -45,5 +69,23 @@ export declare class WalletNamespace {
      * use the same DID.
      */
     createTopupSession(args: CreateTopupSessionArgs): Promise<CreateTopupSessionResult>;
+    /**
+     * Read the user's current wallet balance.
+     *
+     * Routed through the compute proxy at `${compute}/v1/invoke` because
+     * that's where the Aithos-platform DDB IAM lives — keeps the wallet
+     * Lambda focused on Stripe and avoids granting read-on-wallet to a
+     * second function. The call is gated by the same signed-envelope
+     * verification as `invokeBedrock`: only the owner of the user's
+     * `#public` key can read their balance.
+     *
+     * Returns `{ balance: 0, exists: false, dailySpent: 0 }` for an
+     * identity that has never been funded — the call still succeeds,
+     * the row just doesn't exist yet.
+     *
+     * @throws {AithosSDKError} on protocol errors (network, http,
+     *   envelope-verify failures from the proxy).
+     */
+    getBalance(args?: GetBalanceArgs): Promise<GetBalanceResult>;
 }
 //# sourceMappingURL=wallet.d.ts.map

package/dist/src/wallet.js

@@ -1,17 +1,20 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright 2026 Mathieu Colla
-// Wallet namespace — Stripe Checkout for credit-pack top-ups.
+// Wallet namespace — credit-pack top-ups (Stripe) and balance lookup.
 //
-// Posts to `${wallet}/v1/wallet/topup/checkout`. The Lambda creates a
-// Stripe Checkout session bound to the user's DID via `metadata`, returns
-// the hosted URL. The frontend then redirects the user. Stripe webhook
-// (server-side) credits the wallet on `checkout.session.completed`.
-//
-// v0 scope: no envelope verify on the checkout endpoint — the link is
-// single-use and metadata-bound to `user_did`. Anyone creating a session
-// for someone else's DID would just gift them credits, no value to an
-// attacker. Envelope-verify gets added in a follow-up if abuse appears.
-import { walletTopupCheckoutUrl, } from "./endpoints.js";
+// Two methods:
+//   - createTopupSession() — posts to `${wallet}/v1/wallet/topup/checkout`
+//     to create a Stripe Checkout session. The Lambda binds the session
+//     to the user's DID via metadata; the Stripe webhook credits the
+//     wallet on `checkout.session.completed`. No envelope verify on this
+//     endpoint at v0 (the link is single-use and metadata-bound — anyone
+//     creating a session for someone else's DID just gifts them credits).
+//   - getBalance() — JSON-RPC `aithos.wallet_get_balance` against the
+//     compute proxy at `${compute}/v1/invoke`. Read-only DDB GetItem on
+//     the wallet table, gated by the same signed envelope verification
+//     as compute_invoke. Returns the current balance + daily spent.
+import { buildSignedEnvelope, } from "@aithos/protocol-client";
+import { computeInvokeUrl, walletTopupCheckoutUrl, } from "./endpoints.js";
 import { AithosSDKError } from "./types.js";
 /**
  * `sdk.wallet` namespace.
@@ -67,5 +70,67 @@ export class WalletNamespace {
         }
         return { checkoutUrl: ok.checkout_url, sessionId: ok.session_id };
     }
+    /**
+     * Read the user's current wallet balance.
+     *
+     * Routed through the compute proxy at `${compute}/v1/invoke` because
+     * that's where the Aithos-platform DDB IAM lives — keeps the wallet
+     * Lambda focused on Stripe and avoids granting read-on-wallet to a
+     * second function. The call is gated by the same signed-envelope
+     * verification as `invokeBedrock`: only the owner of the user's
+     * `#public` key can read their balance.
+     *
+     * Returns `{ balance: 0, exists: false, dailySpent: 0 }` for an
+     * identity that has never been funded — the call still succeeds,
+     * the row just doesn't exist yet.
+     *
+     * @throws {AithosSDKError} on protocol errors (network, http,
+     *   envelope-verify failures from the proxy).
+     */
+    async getBalance(args = {}) {
+        const { identity, appDid, endpoints, fetch: fetchImpl } = this.#deps;
+        const url = computeInvokeUrl(endpoints);
+        const params = { app_did: appDid };
+        const envelope = buildSignedEnvelope({
+            iss: identity.did,
+            aud: url,
+            method: "aithos.wallet_get_balance",
+            verificationMethod: `${identity.did}#public`,
+            params,
+            signer: identity.public,
+        });
+        let res;
+        try {
+            res = await fetchImpl(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: "aithos.wallet_get_balance",
+                    method: "aithos.wallet_get_balance",
+                    params: { ...params, _envelope: envelope },
+                }),
+                ...(args.signal ? { signal: args.signal } : {}),
+            });
+        }
+        catch (e) {
+            throw new AithosSDKError("network", e.message);
+        }
+        if (!res.ok) {
+            throw new AithosSDKError("http", `HTTP ${res.status} ${res.statusText}`, { status: res.status });
+        }
+        const body = (await res.json());
+        if (body.error) {
+            throw new AithosSDKError(String(body.error.code), body.error.message, body.error.data ? { data: body.error.data } : undefined);
+        }
+        if (!body.result) {
+            throw new AithosSDKError("empty", "empty result from wallet_get_balance");
+        }
+        return {
+            balance: typeof body.result.balance === "number" ? body.result.balance : 0,
+            dailySpent: typeof body.result.dailySpent === "number" ? body.result.dailySpent : 0,
+            exists: body.result.exists === true,
+        };
+    }
 }
 //# sourceMappingURL=wallet.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.1",
+  "version": "0.1.0-alpha.3",
   "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",