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

package/README.md

@@ -55,11 +55,170 @@ 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.
+
+## Custodial auth — onboarding users without a recovery file
+
+Three new methods on `AithosAuth` let an app create and authenticate
+its end-users via a server-managed custody flow — the user only needs
+an email address and a password sent by mail. No recovery file, no
+Google account, no client-side cryptography to handle.
+
+The model is honest custody: Aithos KMS-wraps the user's Ed25519
+identity seeds, and unwraps them on every sign-in after password
+verification. Equivalent to how Coinbase or any hosted SaaS keeps your
+private key. Annunciated to the user in the welcome email.
+
+```ts
+import { AithosSDK } from "@aithos/sdk";
+
+// ─── Server-side: sign-up ───────────────────────────────────────────
+// MUST run on your backend. The API key is a server secret —
+// provisioned by Aithos via the operator runbook.
+const sdk = new AithosSDK({ identity });
+const result = await sdk.auth.signUpCustodial({
+  apiKey: process.env.AITHOS_API_KEY!,
+  email: "alice@example.com",
+  displayName: "Alice",
+});
+// → { userId, did, handle, email, mailSent }
+// The user receives an email with their password and a sign-in link.
+
+// ─── Browser-side: sign-in ──────────────────────────────────────────
+// User pastes the password from their mail into your sign-in form,
+// then your frontend calls this. No API key needed — the password
+// is the credential.
+const { session, passwordMustChange } = await sdk.auth.signInCustodial({
+  email: "alice@example.com",
+  password: "MyTempPass32chars",
+});
+// Local KeyStore is now hydrated with the 4 Ed25519 sphere seeds —
+// the user can publish ethos editions, mint mandates, invoke compute,
+// exactly as if they had signed in via a recovery file or Google SSO.
+if (passwordMustChange) {
+  // Optional: nudge the user to set their own password via the
+  // standard reset flow.
+}
+
+// ─── Browser-side: request password reset ───────────────────────────
+// The backend always returns silently (anti-enumeration). If the email
+// is registered AND in custodial mode AND not in cooldown AND under the
+// daily cap, a magic-link email is sent to the address.
+await sdk.auth.requestPasswordReset({ email: "alice@example.com" });
+```
+
+The reset finalization (collecting the new password from the user) is
+done on a small web page hosted by Aithos at `https://app.aithos.be/reset`
+(or your app's own `reset_base_url` if you've registered one — see the
+operator runbook). The page POSTs to `/auth/custodial/reset/finalize`
+and returns the user to your sign-in page on success.
+
+### Getting an API key
+
+API keys are provisioned out-of-band by Aithos. Contact the maintainer
+(or use the self-service console at `aithos.be/console` when it ships
+in V2). The pattern is `aithos_<env>_<32 chars b58>`. Keep it in your
+backend's secrets manager — never in browser code.
+
+### Trade-offs vs. the zk and Google SSO flows
+
+|                | zk (recovery file)         | Google SSO (KMS)     | **Custodial** |
+|----------------|----------------------------|----------------------|---------------|
+| User burden    | downloads `recovery.json`  | Google consent       | email only    |
+| Password reset | requires recovery file     | re-auth via Google   | magic-link mail |
+| Trust model    | zero-knowledge (you only)  | Aithos + Google      | Aithos only   |
+| Multi-device   | re-import recovery         | re-Google            | email + password |
+| SDK signing capability | full                | full                 | full          |
+
+Custodial is the right default for SDK-integrated apps that want
+SaaS-grade UX. zk is the right default for power users who want
+sovereign custody. SSO is the right default for users already invested
+in the Google ecosystem.
+
+## Extracting webpages without an LLM
+
+`sdk.web` is a token-priced primitive that lets your agent read a
+public webpage and get back cleaned HTML, purged CSS and a
+deterministic visual signature — all computed server-side without an
+LLM in the loop. Pricing is a flat **1 microcredit** per successful
+extraction (refunded on failure), versus ~30 mc for a comparable
+LLM-based extraction.
+
+```ts
+import { AithosSDK } from "@aithos/sdk";
+
+const sdk = new AithosSDK({ auth, appDid });
+
+const { data, creditsCharged } = await sdk.web.extract({
+  url: "https://example.com",
+});
+
+console.log(data.meta.title);             // "Example Domain"
+console.log(data.visual_signature.colors.primary); // "#0078d4"
+console.log(data.styles.css.length);      // purged + minified CSS
+```
+
+Owners can mint a mandate for delegate-only extraction:
+
+```ts
+import { WEB_EXTRACT_SCOPE } from "@aithos/sdk";
+
+await sdk.mandates.create({
+  appDid: "did:aithos:app:my-agent",
+  scopes: [WEB_EXTRACT_SCOPE],
+  // ...
+});
+```
+
 ## What lives where
 
 | Namespace        | Purpose                                                                                    |
 | ---------------- | ------------------------------------------------------------------------------------------ |
 | `sdk.compute`    | Bedrock invocation through the Aithos compute proxy (signed envelope, wallet enforcement). |
+| `sdk.web`        | Webpage extraction without an LLM through the web extractor proxy (1 mc / call).           |
 | `sdk.wallet`     | Stripe Checkout sessions for credit-pack top-ups, balance helpers.                         |
 | `sdk.ethos`      | Ethos-zone composition / parsing — re-exported from `@aithos/protocol-client`.             |
 | `sdk.onboarding` | First-run identity / DID flows — re-exported.                                              |

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

@@ -0,0 +1,149 @@
+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>;
+/**
+ * Input for {@link custodialSignUp}. Caller authenticates the app via ONE
+ * of `apiKey` (server-only secret) or `publicKey` (browser-safe). The
+ * user's `password` is always required — sign-up no longer auto-generates
+ * one server-side. The created account starts in a *pending* state and
+ * the user must click the link sent to their inbox before they can
+ * sign in.
+ */
+export interface CustodialSignUpApiInput {
+    /** Server-only Bearer secret: `aithos_<env>_<…>`. Mutually exclusive
+     *  with `publicKey`. Use this from your backend. */
+    readonly apiKey?: string;
+    /** Browser-safe public client key: `pk_<env>_<…>`. Mutually exclusive
+     *  with `apiKey`. The browser sends its `Origin` header alongside; the
+     *  Aithos backend matches it against the app's allowed_origins list. */
+    readonly publicKey?: string;
+    readonly email: string;
+    /** Raw password the user chose. Must be ≥ 10 chars and mix letters
+     *  with at least one digit or symbol (server-side rule). */
+    readonly password: string;
+    readonly displayName?: string;
+    readonly handleHint?: string;
+}
+export interface CustodialSignUpApiResponse {
+    /** Always "pending_verification" — sign-in is blocked until the
+     *  user clicks the confirmation link. */
+    readonly status: "pending_verification";
+    readonly email: string;
+    readonly mailSent: boolean;
+    readonly mailMessageId?: string;
+}
+/**
+ * Provision a custodial-mode account on behalf of a registered app.
+ *
+ * Two integration paths:
+ *   - **Backend** caller passes `apiKey` (server-only secret).
+ *   - **Browser** caller passes `publicKey` (safe to ship in the bundle).
+ *     The browser also sends its `Origin` header automatically and the
+ *     auth backend validates it against the app's allowed_origins list.
+ *
+ * On success the account exists in DDB with `email_verified: false` and
+ * the response carries `status: "pending_verification"` — call
+ * {@link custodialVerifyEmail} after the user clicks the confirmation
+ * link before attempting sign-in.
+ */
+export declare function custodialSignUp(http: HttpClient, input: CustodialSignUpApiInput): Promise<CustodialSignUpApiResponse>;
+export interface CustodialVerifyEmailApiInput {
+    readonly email: string;
+    readonly token: string;
+}
+/** Consume the verification token from the confirmation link. Idempotent
+ *  on repeated clicks; throws `auth_token_invalid_or_expired` if the
+ *  token is wrong, consumed, or past its 24h TTL. */
+export declare function custodialVerifyEmail(http: HttpClient, input: CustodialVerifyEmailApiInput): Promise<{
+    ok: true;
+}>;
+/** Re-send the verification mail for a pending account. The backend
+ *  is anti-enum (always 200) and rate-limited 1/h/account, so this is
+ *  safe to call even when the user state is unknown. Accepts the same
+ *  credential families as {@link custodialSignUp}. */
+export declare function custodialResendVerify(http: HttpClient, args: {
+    readonly email: string;
+    readonly apiKey?: string;
+    readonly publicKey?: string;
+}): Promise<void>;
+export interface CustodialSignInApiInput {
+    readonly email: string;
+    readonly password: string;
+}
+export interface CustodialSignInApiResponse {
+    readonly session: string;
+    readonly exp: number;
+    readonly did: string;
+    readonly handle: string;
+    readonly displayName: string;
+    /** Raw 32-byte Ed25519 seed — caller MUST hydrate its keystore and
+     *  zeroize this buffer. */
+    readonly seed: Uint8Array;
+    /** Raw 32-byte vault encryption key — same lifecycle. */
+    readonly encKey: Uint8Array;
+    readonly blob: Uint8Array;
+    readonly blobNonce: Uint8Array;
+    readonly blobVersion: number;
+    readonly passwordMustChange: boolean;
+}
+export declare function custodialSignIn(http: HttpClient, input: CustodialSignInApiInput): Promise<CustodialSignInApiResponse>;
+export declare function custodialResetRequest(http: HttpClient, email: string): Promise<void>;
+export interface CustodialResetFinalizeApiInput {
+    readonly email: string;
+    readonly token: string;
+    readonly newPassword: string;
+}
+export interface CustodialResetFinalizeApiResponse {
+    readonly session: string;
+    readonly exp: number;
+    readonly did: string;
+    readonly handle: string;
+}
+export declare function custodialResetFinalize(http: HttpClient, input: CustodialResetFinalizeApiInput): Promise<CustodialResetFinalizeApiResponse>;
+export {};
+//# sourceMappingURL=auth-api.d.ts.map

package/dist/src/auth-api.js

@@ -0,0 +1,226 @@
+// 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,
+    };
+}
+/**
+ * Provision a custodial-mode account on behalf of a registered app.
+ *
+ * Two integration paths:
+ *   - **Backend** caller passes `apiKey` (server-only secret).
+ *   - **Browser** caller passes `publicKey` (safe to ship in the bundle).
+ *     The browser also sends its `Origin` header automatically and the
+ *     auth backend validates it against the app's allowed_origins list.
+ *
+ * On success the account exists in DDB with `email_verified: false` and
+ * the response carries `status: "pending_verification"` — call
+ * {@link custodialVerifyEmail} after the user clicks the confirmation
+ * link before attempting sign-in.
+ */
+export async function custodialSignUp(http, input) {
+    if (!input.apiKey && !input.publicKey) {
+        throw new AithosSDKError("auth_missing_api_key", "signUpCustodial requires either apiKey or publicKey");
+    }
+    if (input.apiKey && input.publicKey) {
+        throw new AithosSDKError("auth_invalid_input", "signUpCustodial: pass exactly one of apiKey or publicKey, not both");
+    }
+    const bearer = (input.apiKey ?? input.publicKey);
+    const res = await http.fetchImpl(`${http.authBaseUrl}/auth/custodial/sign-up`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${bearer}`,
+        },
+        body: JSON.stringify({
+            email: input.email,
+            password: input.password,
+            ...(input.displayName ? { display_name: input.displayName } : {}),
+            ...(input.handleHint ? { handle_hint: input.handleHint } : {}),
+        }),
+    });
+    if (!res.ok)
+        throw await readError(res, "custodial_signup_failed");
+    const wire = (await res.json());
+    return {
+        status: "pending_verification",
+        email: wire.email,
+        mailSent: wire.mail_sent,
+        ...(wire.mail_message_id !== undefined
+            ? { mailMessageId: wire.mail_message_id }
+            : {}),
+    };
+}
+/** Consume the verification token from the confirmation link. Idempotent
+ *  on repeated clicks; throws `auth_token_invalid_or_expired` if the
+ *  token is wrong, consumed, or past its 24h TTL. */
+export async function custodialVerifyEmail(http, input) {
+    const res = await http.fetchImpl(`${http.authBaseUrl}/auth/custodial/verify`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ email: input.email, token: input.token }),
+    });
+    if (!res.ok)
+        throw await readError(res, "custodial_verify_failed");
+    return (await res.json());
+}
+/* ---- POST /auth/custodial/verify/resend -------------------------------- */
+/** Re-send the verification mail for a pending account. The backend
+ *  is anti-enum (always 200) and rate-limited 1/h/account, so this is
+ *  safe to call even when the user state is unknown. Accepts the same
+ *  credential families as {@link custodialSignUp}. */
+export async function custodialResendVerify(http, args) {
+    if (!args.apiKey && !args.publicKey) {
+        throw new AithosSDKError("auth_missing_api_key", "resendVerificationEmail requires either apiKey or publicKey");
+    }
+    const bearer = (args.apiKey ?? args.publicKey);
+    const res = await http.fetchImpl(`${http.authBaseUrl}/auth/custodial/verify/resend`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${bearer}`,
+        },
+        body: JSON.stringify({ email: args.email }),
+    });
+    if (!res.ok)
+        throw await readError(res, "custodial_resend_failed");
+}
+export async function custodialSignIn(http, input) {
+    const wire = await postJson(http, "/auth/custodial/sign-in", { email: input.email, password: input.password });
+    return {
+        session: wire.session,
+        exp: wire.exp,
+        did: wire.did,
+        handle: wire.handle,
+        displayName: wire.display_name,
+        seed: b64ToBytes(wire.seed_b64),
+        encKey: b64ToBytes(wire.enc_key_b64),
+        blob: wire.blob_b64 ? b64ToBytes(wire.blob_b64) : new Uint8Array(0),
+        blobNonce: wire.blob_nonce_b64
+            ? b64ToBytes(wire.blob_nonce_b64)
+            : new Uint8Array(0),
+        blobVersion: wire.blob_version,
+        passwordMustChange: wire.password_must_change,
+    };
+}
+/* ---- POST /auth/custodial/reset/request --------------------------------- */
+export async function custodialResetRequest(http, email) {
+    // Backend always returns 200 { ok: true } regardless. We accept any
+    // 2xx body, even non-JSON, to be defensive.
+    const res = await http.fetchImpl(`${http.authBaseUrl}/auth/custodial/reset/request`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ email }),
+    });
+    if (!res.ok)
+        throw await readError(res, "custodial_reset_request_failed");
+}
+export async function custodialResetFinalize(http, input) {
+    const wire = await postJson(http, "/auth/custodial/reset/finalize", {
+        email: input.email,
+        token: input.token,
+        new_password: input.newPassword,
+    });
+    return {
+        session: wire.session,
+        exp: wire.exp,
+        did: wire.did,
+        handle: wire.handle,
+    };
+}
+//# sourceMappingURL=auth-api.js.map