@aithos/sdk 0.1.0-alpha.2 → 0.1.0-alpha.20

package/README.md

@@ -55,6 +55,51 @@ const reply = await sdk.compute.invokeBedrock({
 console.log(reply.content);
 ```
 
+## Delegating compute to an agent — opt-in token spending
+
+To let an agent (or another user, or a third-party app) invoke Bedrock
+**in your name**, with **your credits**, you mint a mandate. Token
+spending is its own opt-in capability — passing it is a separate,
+named, validated input that a consent UI can review. It is NEVER an
+implicit side-effect of an ethos read/write scope.
+
+```ts
+// Mint a mandate that lets agent Bob read your public ethos AND
+// spend up to 5 000 microcredits/day on Haiku, capped at 100 000
+// microcredits over the whole mandate lifetime.
+const mandate = await sdk.mandates.create({
+  granteeId: "urn:agent:bob",
+  scopes: ["ethos.read.public"],
+  ttlSeconds: 86_400,
+  compute: {
+    dailyCapMicrocredits: 5_000,
+    totalCapMicrocredits: 100_000,
+    maxCreditsPerCall: 500,
+    allowedModels: ["claude-haiku-4-5"],
+  },
+});
+
+// Hand `mandate.bundle` (a `.aithos-delegate.json` Blob) to Bob.
+// He imports it, then signs his own envelopes and calls
+// sdk.compute.invokeBedrock({ mandateId: mandate.mandateId, … })
+// — every invocation debits *your* wallet, capped per the budget
+// you set.
+```
+
+Three invariants the SDK enforces synchronously, before reaching the
+network — they fail fast with a precise `AithosSDKError`:
+
+- **No smuggling.** Adding `"compute.invoke"` directly to `scopes[]`
+  throws `mandates_invalid_scopes`. The `compute` namespace is the
+  only path, so a UI reviewing `compute` can never be bypassed.
+- **No bearer compute.** A `compute` namespace without at least one
+  of `dailyCapMicrocredits` or `totalCapMicrocredits` throws
+  `mandates_invalid_compute`. Unbounded compute mandates are forbidden
+  by construction.
+- **Compute-only is fine.** `scopes: []` is allowed when `compute` is
+  set — useful for agents that only consume tokens (e.g. creative
+  assistants) without seeing any of your data.
+
 ## What lives where
 
 | Namespace        | Purpose                                                                                    |

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

@@ -0,0 +1,50 @@
+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 PutBlobApiInput {
+    readonly jwt: string;
+    readonly blob: Uint8Array;
+    readonly blobNonce: Uint8Array;
+    readonly blobVersion: number;
+}
+export declare function putBlob(http: HttpClient, input: PutBlobApiInput): Promise<{
+    ok: true;
+}>;
+export interface LoginChallengeResponse {
+    readonly authSalt: Uint8Array;
+    readonly encSalt: Uint8Array;
+    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,102 @@
+// 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());
+}
+async function putJson(http, path, body, jwt) {
+    const res = await http.fetchImpl(`${http.authBaseUrl}${path}`, {
+        method: "PUT",
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${jwt}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok)
+        throw await readError(res, "request_failed");
+    return (await res.json());
+}
+export async function registerAccount(http, input) {
+    return postJson(http, "/auth/register", {
+        email: input.email,
+        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 putBlob(http, input) {
+    return putJson(http, "/auth/blob", {
+        blob_b64: bytesToB64(input.blob),
+        blob_nonce_b64: bytesToB64(input.blobNonce),
+        blob_version: input.blobVersion,
+    }, input.jwt);
+}
+export async function loginChallenge(http, email) {
+    const wire = await postJson(http, "/auth/login/challenge", { email });
+    return {
+        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,253 @@
+import { type AithosSessionStore } from "./session-store.js";
+import { type AithosKeyStore } from "./key-store.js";
+import { DelegateActor } from "./internal/delegate-state.js";
+import { OwnerSigners } from "./internal/owner-signers.js";
+/** Default URL of the Aithos auth backend. */
+export declare const DEFAULT_AUTH_BASE_URL = "https://auth.aithos.be";
+/** Default URL of the Aithos primitives API (publish_identity, publish_ethos_edition, etc.). */
+export declare const DEFAULT_API_BASE_URL = "https://api.aithos.be";
+export interface AithosAuthConfig {
+    readonly authBaseUrl?: string;
+    /**
+     * Base URL of the Aithos primitives API (`api.aithos.be`). Used by
+     * {@link AithosAuth.signUp} to bootstrap the user's Ethos via
+     * `aithos.publish_identity` after the auth account is created. Override
+     * for staging or self-hosted deployments. Defaults to
+     * {@link DEFAULT_API_BASE_URL}.
+     */
+    readonly apiBaseUrl?: string;
+    readonly fetch?: typeof fetch;
+    readonly window?: Pick<Window, "location" | "history">;
+    /** Pluggable JWT-session storage. Defaults to {@link defaultSessionStore}. */
+    readonly sessionStore?: AithosSessionStore;
+    /** Pluggable key persistence. Defaults to {@link defaultKeyStore}. */
+    readonly keyStore?: AithosKeyStore;
+}
+/**
+ * Active Aithos session. Returned by JWT-backed entry points
+ * (`signIn`, `signUp`, `handleCallback`). Recovery-file and mandate
+ * sign-ins do NOT return an `AithosSession` — they yield the lighter
+ * {@link OwnerInfo} / {@link DelegateInfo}.
+ */
+export interface AithosSession {
+    readonly session: string;
+    readonly exp: number;
+    readonly did: string;
+    readonly handle: string;
+    readonly blob_b64: string;
+    readonly blob_nonce_b64: string;
+    readonly blob_version: number;
+    readonly enc_key_b64: string;
+    readonly is_first_login: boolean;
+}
+/**
+ * Public information about the loaded owner identity. Available after
+ * any owner-side sign-in (password, Google, recovery), regardless of
+ * whether a JWT is also present.
+ */
+export interface OwnerInfo {
+    readonly did: string;
+    readonly handle: string;
+    readonly displayName: string;
+}
+/**
+ * Public information about a delegate session held by the SDK. Returned
+ * by `importMandate` and `getDelegates`.
+ */
+export interface DelegateInfo {
+    readonly mandateId: string;
+    readonly subjectDid: string;
+    readonly granteeId: string;
+    readonly scopes: readonly string[];
+    /** ISO-8601, or null when the mandate has no `not_after`. */
+    readonly expiresAt: string | null;
+    readonly label?: string;
+}
+export interface SignInWithGoogleOptions {
+    /**
+     * Opaque state the consumer app wants to recover after the OAuth
+     * round-trip (e.g. a deep-link to resume on). Echoed back as
+     * `?app_state=` on the final redirect.
+     */
+    readonly appState?: string;
+    /**
+     * App id registered in the Aithos `aithos-auth-apps` table. When set
+     * together with {@link returnTo}, the auth backend redirects the
+     * browser to {@link returnTo} (post Google + Aithos sign-in) instead
+     * of the legacy hard-coded `app.aithos.be/auth/callback`.
+     *
+     * The pair is required together: the backend rejects half-presence
+     * with `sso_app_redirect_pair_required`. Use it for any consumer app
+     * other than the canonical `app.aithos.be` (typically your own
+     * domain in prod, `http://localhost:<port>/auth/callback` in dev).
+     */
+    readonly appId?: string;
+    /**
+     * Where the auth backend should 302 the browser back to after a
+     * successful Google sign-in. MUST be on the app's
+     * `allowed_redirect_uris` allowlist (registered with Aithos out of
+     * band; see {@link appId}). Exact-match — wildcards rejected.
+     */
+    readonly returnTo?: string;
+}
+export interface SignInInput {
+    readonly email: string;
+    readonly password: string;
+}
+export interface SignUpInput {
+    readonly email: string;
+    readonly password: string;
+    readonly handle: string;
+    readonly displayName?: string;
+}
+export interface SignUpResult {
+    readonly session: AithosSession;
+    readonly recoveryFile: Blob;
+    readonly recoveryFilename: string;
+}
+/**
+ * Input to {@link AithosAuth.completeSsoFirstLogin}. The handle is
+ * required (the auth backend pre-generated one from the user's email
+ * local-part, available on the session payload — we re-confirm it
+ * here so the user can edit before commit).
+ */
+export interface CompleteSsoFirstLoginInput {
+    readonly handle: string;
+    readonly displayName?: string;
+}
+/**
+ * Result of {@link AithosAuth.completeSsoFirstLogin}. Returns a recovery
+ * file just like signUp — even though the user authenticated via Google,
+ * the freshly-generated Ed25519 seeds are the only material that can
+ * sign Aithos artifacts; without the recovery file, losing access to
+ * the Google account means losing the ethos forever.
+ */
+export interface CompleteSsoFirstLoginResult {
+    readonly session: AithosSession;
+    readonly recoveryFile: Blob;
+    readonly recoveryFilename: string;
+}
+export interface SignInWithRecoveryInput {
+    /** Recovery file as a Blob (browser File input) or already-decoded JSON string. */
+    readonly file: Blob | string;
+}
+export interface ImportMandateInput {
+    /** Delegate bundle as a Blob or already-decoded JSON string. */
+    readonly bundle: Blob | string;
+}
+export declare class AithosAuth {
+    #private;
+    readonly authBaseUrl: string;
+    readonly apiBaseUrl: string;
+    constructor(config?: AithosAuthConfig);
+    /**
+     * Reload signing material and JWT session from the configured stores.
+     * Must be called once at app boot before relying on
+     * {@link getCurrentSession} / {@link getOwnerInfo} / {@link canSignAsOwner}
+     * — until then they reflect only what's been done in-memory in the
+     * current tab.
+     *
+     * Strict consistency: if the JWT and the stored owner disagree about
+     * who's signed in, both are wiped and the user re-auths. JWT-less
+     * owner state (loaded from keyStore but no JWT) is a valid resumed
+     * state — the user signed in via recovery or imported a mandate at
+     * some earlier moment and never went through the JWT flow.
+     */
+    resume(): Promise<void>;
+    /** JWT-backed session. Null when signed in via recovery / mandate / not at all. */
+    getCurrentSession(): AithosSession | null;
+    /** Loaded owner identity. Independent of JWT presence. */
+    getOwnerInfo(): OwnerInfo | null;
+    getDelegates(): readonly DelegateInfo[];
+    canSignAsOwner(): boolean;
+    canSignAsDelegateFor(did: string): boolean;
+    /**
+     * Internal accessor used by sibling SDK namespaces (compute, wallet,
+     * ethos) when they need to sign on behalf of the owner. Returns null
+     * if no owner is loaded.
+     *
+     * @internal
+     */
+    _getOwnerSigners(): OwnerSigners | null;
+    /**
+     * Internal accessor — looks up an active delegate by mandate id.
+     * @internal
+     */
+    _getDelegateActor(mandateId: string): DelegateActor | undefined;
+    /**
+     * Internal accessor — finds the first active delegate whose subject
+     * matches `did`. Used by `sdk.ethos.of(did)` when the user holds a
+     * mandate for that subject.
+     * @internal
+     */
+    _findDelegateForSubject(did: string): DelegateActor | undefined;
+    signIn(input: SignInInput): Promise<AithosSession>;
+    signUp(input: SignUpInput): Promise<SignUpResult>;
+    /**
+     * Sign in by uploading a recovery file. Hydrates the owner signers
+     * locally — no JWT is obtained on this path because the recovery
+     * file alone doesn't authenticate against the auth backend (no
+     * password, no Google session). Apps that need compute/wallet
+     * access should follow up with an email+password sign-in or with
+     * Google SSO.
+     *
+     * The recovery file is ALWAYS the file produced by `signUp` (or the
+     * equivalent one emitted by `protocol-client`'s `runOnboarding`).
+     * Both shapes are accepted.
+     */
+    signInWithRecovery(input: SignInWithRecoveryInput): Promise<OwnerInfo>;
+    /**
+     * Import a delegate bundle (`.aithos-delegate.json`). Works in any
+     * state: with no owner loaded (delegate-only session), or alongside
+     * an existing owner (the user holds mandates for other people's
+     * ethoses while also being an owner themselves).
+     */
+    importMandate(input: ImportMandateInput): Promise<DelegateInfo>;
+    removeMandate(mandateId: string): Promise<void>;
+    signInWithGoogle(opts?: SignInWithGoogleOptions): never;
+    /**
+     * Public entrypoint — dedupes concurrent calls (React StrictMode).
+     * The first call kicks off the actual exchange; subsequent calls
+     * before that promise resolves return the SAME promise so they all
+     * receive the same `AithosSession | null`. Otherwise StrictMode's
+     * second invocation would race against the URL clean done by the
+     * first call and resolve to `null`, robbing the AuthCallback page
+     * of the session it actually obtained.
+     */
+    handleCallback(): Promise<AithosSession | null>;
+    exchange(aithosCode: string): Promise<AithosSession>;
+    /**
+     * Finish the first-time Google SSO bootstrap. After
+     * `signInWithGoogle()` + `handleCallback()`, a brand-new SSO user has
+     * a session JWT and an `enc_key` released by the auth backend, but
+     * NO Aithos identity yet (no Ed25519 seeds, no published did.json,
+     * no blob in the auth vault). This method closes that gap:
+     *
+     *   1. Generates a fresh {@link BrowserIdentity} client-side (4
+     *      Ed25519 keypairs, derived DID).
+     *   2. Calls `aithos.publish_identity` on api.aithos.be so reads
+     *      and writes against the Aithos primitives have an ethos to
+     *      anchor to.
+     *   3. AES-GCM-encrypts the seeds with the session's `enc_key`,
+     *      PUTs the result to `/auth/blob`. From now on, every Google
+     *      sign-in for this user will receive the encrypted blob and
+     *      hydrate locally.
+     *   4. Hydrates `ownerSigners` + `keyStore` so `canSignAsOwner()`
+     *      flips to true.
+     *   5. Returns a recovery-file Blob — the only material that can
+     *      restore this ethos if Google access is lost.
+     *
+     * Preconditions:
+     *   - `getCurrentSession()` returns a non-null session (caller went
+     *     through `handleCallback()` already).
+     *   - The session's `blob_version` is 0 (i.e. no blob yet).
+     *   - The session's `enc_key_b64` is non-empty.
+     *
+     * Throws `AithosSDKError("auth_sso_no_pending_first_login", …)` if
+     * preconditions don't hold (e.g. blob_version > 0 means the user has
+     * already completed setup; nothing to do).
+     */
+    completeSsoFirstLogin(input: CompleteSsoFirstLoginInput): Promise<CompleteSsoFirstLoginResult>;
+    signOut(): Promise<void>;
+}
+//# sourceMappingURL=auth.d.ts.map