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

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/src/wallet.d.ts

@@ -1,3 +1,4 @@
+import type { AithosAuth } from "./auth.js";
 import { type AithosSdkEndpoints } from "./endpoints.js";
 /**
  * Canonical credit-pack identifiers. Pricing and microcredit amounts are
@@ -24,8 +25,29 @@ 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 {
-    readonly userDid: string;
+    /** Auth instance — the wallet reads the active owner DID + signing key from here. */
+    readonly auth: AithosAuth;
+    /** App DID — sent as audit attribution alongside the balance request. */
+    readonly appDid: string;
     readonly endpoints: AithosSdkEndpoints;
     readonly fetch: typeof fetch;
 }
@@ -40,10 +62,28 @@ export declare class WalletNamespace {
      * hosted URL — the caller is responsible for redirecting the user (e.g.
      * `window.location.href = result.checkoutUrl`).
      *
-     * On success, the Stripe webhook will credit `userDid`'s wallet once the
+     * On success, the Stripe webhook will credit the user's wallet once the
      * payment clears. Wallet balances are shared across all Aithos apps that
      * 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,21 @@
 // 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 { ownerKeyPair } from "./internal/protocol-client-bridge.js";
 import { AithosSDKError } from "./types.js";
 /**
  * `sdk.wallet` namespace.
@@ -26,12 +30,16 @@ export class WalletNamespace {
      * hosted URL — the caller is responsible for redirecting the user (e.g.
      * `window.location.href = result.checkoutUrl`).
      *
-     * On success, the Stripe webhook will credit `userDid`'s wallet once the
+     * On success, the Stripe webhook will credit the user's wallet once the
      * payment clears. Wallet balances are shared across all Aithos apps that
      * use the same DID.
      */
     async createTopupSession(args) {
-        const { userDid, endpoints, fetch: fetchImpl } = this.#deps;
+        const { auth, endpoints, fetch: fetchImpl } = this.#deps;
+        const owner = auth._getOwnerSigners();
+        if (!owner || owner.destroyed) {
+            throw new AithosSDKError("sdk_no_owner", "no owner signed in; sign in first");
+        }
         const url = walletTopupCheckoutUrl(endpoints);
         let res;
         try {
@@ -39,7 +47,7 @@ export class WalletNamespace {
                 method: "POST",
                 headers: { "content-type": "application/json" },
                 body: JSON.stringify({
-                    user_did: userDid,
+                    user_did: owner.did,
                     pack_id: args.packId,
                     success_url: args.successUrl,
                     cancel_url: args.cancelUrl,
@@ -67,5 +75,72 @@ 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 { auth, appDid, endpoints, fetch: fetchImpl } = this.#deps;
+        const owner = auth._getOwnerSigners();
+        if (!owner || owner.destroyed) {
+            throw new AithosSDKError("sdk_no_owner", "no owner signed in; sign in first");
+        }
+        const publicKp = ownerKeyPair(owner, "public");
+        const url = computeInvokeUrl(endpoints);
+        const params = { app_did: appDid };
+        const envelope = buildSignedEnvelope({
+            iss: owner.did,
+            aud: url,
+            method: "aithos.wallet_get_balance",
+            verificationMethod: `${owner.did}#public`,
+            params,
+            signer: publicKp,
+        });
+        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-j3.test.d.ts

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