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

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.d.ts

@@ -1,197 +1,166 @@
 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";
-/**
- * Construction options for {@link AithosAuth}.
- */
+/** 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 {
-    /**
-     * 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.
+     * 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;
-    /**
-     * 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.
-     */
+    /** Pluggable JWT-session storage. Defaults to {@link defaultSessionStore}. */
     readonly sessionStore?: AithosSessionStore;
+    /** Pluggable key persistence. Defaults to {@link defaultKeyStore}. */
+    readonly keyStore?: AithosKeyStore;
 }
 /**
- * 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.
+ * 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 {
-    /** 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}. */
+/**
+ * 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 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 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 {
-    /** Resolved auth base URL with a trailing slash trimmed. */
+    #private;
     readonly authBaseUrl: string;
-    private readonly fetchImpl;
-    private readonly win;
-    private readonly store;
+    readonly apiBaseUrl: string;
     constructor(config?: AithosAuthConfig);
     /**
-     * Sign in to an existing Aithos account. Two-round-trip flow under the
-     * hood :
+     * 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.
      *
-     *   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.
+     * 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.
      */
-    signIn(input: SignInInput): Promise<AithosSession>;
+    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;
     /**
-     * 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
+     * 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.
      *
-     * 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.
+     * @internal
      */
-    signUp(input: SignUpInput): Promise<SignUpResult>;
+    _getOwnerSigners(): OwnerSigners | null;
     /**
-     * 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.
+     * Internal accessor — looks up an active delegate by mandate id.
+     * @internal
      */
-    signInWithGoogle(opts?: SignInWithGoogleOptions): never;
+    _getDelegateActor(mandateId: string): DelegateActor | undefined;
     /**
-     * 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=…`.
+     * 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
      */
-    handleCallback(): Promise<AithosSession | null>;
+    _findDelegateForSubject(did: string): DelegateActor | undefined;
+    signIn(input: SignInInput): Promise<AithosSession>;
+    signUp(input: SignUpInput): Promise<SignUpResult>;
     /**
-     * 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.
+     * 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.
      *
-     * Note : this method does NOT persist the session — it's the lower-level
-     * primitive. Use `handleCallback` for the full pipe.
+     * The recovery file is ALWAYS the file produced by `signUp` (or the
+     * equivalent one emitted by `protocol-client`'s `runOnboarding`).
+     * Both shapes are accepted.
      */
-    exchange(aithosCode: string): Promise<AithosSession>;
+    signInWithRecovery(input: SignInWithRecoveryInput): Promise<OwnerInfo>;
     /**
-     * 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.
+     * 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;
+    handleCallback(): Promise<AithosSession | null>;
+    exchange(aithosCode: string): Promise<AithosSession>;
     signOut(): Promise<void>;
 }
 //# sourceMappingURL=auth.d.ts.map