@aithos/sdk 0.1.0-alpha.28 → 0.1.0-alpha.30

package/README.md

@@ -100,6 +100,84 @@ network — they fail fast with a precise `AithosSDKError`:
   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

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

@@ -46,5 +46,60 @@ export interface LoginVerifyResponse {
     readonly blobVersion: number;
 }
 export declare function loginVerify(http: HttpClient, email: string, authKey: Uint8Array): Promise<LoginVerifyResponse>;
+export interface CustodialSignUpApiInput {
+    readonly apiKey: string;
+    readonly email: string;
+    readonly displayName?: string;
+    readonly handleHint?: string;
+}
+export interface CustodialSignUpApiResponse {
+    readonly userId: string;
+    readonly did: string;
+    readonly handle: string;
+    readonly email: string;
+    readonly mailSent: boolean;
+    readonly mailMessageId?: string;
+}
+/**
+ * Provision a custodial-mode account on behalf of a registered app.
+ * Server-only — the API key MUST be kept off the browser (it grants the
+ * ability to create accounts under your app's name). Typical use site is
+ * the app's backend in response to a sign-up form submission.
+ */
+export declare function custodialSignUp(http: HttpClient, input: CustodialSignUpApiInput): Promise<CustodialSignUpApiResponse>;
+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

@@ -99,4 +99,80 @@ export async function loginVerify(http, email, authKey) {
         blobVersion: wire.blob_version,
     };
 }
+/**
+ * Provision a custodial-mode account on behalf of a registered app.
+ * Server-only — the API key MUST be kept off the browser (it grants the
+ * ability to create accounts under your app's name). Typical use site is
+ * the app's backend in response to a sign-up form submission.
+ */
+export async function custodialSignUp(http, input) {
+    const res = await http.fetchImpl(`${http.authBaseUrl}/auth/custodial/sign-up`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${input.apiKey}`,
+        },
+        body: JSON.stringify({
+            email: input.email,
+            ...(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 {
+        userId: wire.user_id,
+        did: wire.did,
+        handle: wire.handle,
+        email: wire.email,
+        mailSent: wire.mail_sent,
+        ...(wire.mail_message_id !== undefined
+            ? { mailMessageId: wire.mail_message_id }
+            : {}),
+    };
+}
+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

package/dist/src/auth.d.ts

@@ -135,6 +135,85 @@ export interface ImportMandateInput {
     /** Delegate bundle as a Blob or already-decoded JSON string. */
     readonly bundle: Blob | string;
 }
+/**
+ * Input to {@link AithosAuth.signUpCustodial}. Server-side only — the
+ * API key MUST stay off the browser (it grants account-creation
+ * authority under your app's name). Typical use site: your app's
+ * backend in response to a sign-up form submission.
+ */
+export interface CustodialSignUpInput {
+    /** Bearer API key issued to your app (`aithos_<env>_<32b58>`). */
+    readonly apiKey: string;
+    /** Email address of the new user. Will receive the welcome mail. */
+    readonly email: string;
+    /** Optional display name. Capped at 200 chars by the backend. */
+    readonly displayName?: string;
+    /** Optional handle hint. Backend may sanitise or replace. */
+    readonly handleHint?: string;
+}
+/**
+ * Result of {@link AithosAuth.signUpCustodial}. The raw password is
+ * NEVER returned in this response — it lives only in the welcome email
+ * sent to the user via SES. `mailSent: false` means the account row
+ * was created but the email handoff to SES failed; the operator can
+ * trigger a manual resend.
+ */
+export interface CustodialSignUpResult {
+    readonly userId: string;
+    readonly did: string;
+    readonly handle: string;
+    readonly email: string;
+    readonly mailSent: boolean;
+    readonly mailMessageId?: string;
+}
+export interface CustodialSignInInput {
+    readonly email: string;
+    readonly password: string;
+}
+/**
+ * Active custodial session. Same JWT-backed shape as {@link AithosSession}
+ * but adds a `passwordMustChange` flag the UI can honour to nudge the
+ * user toward a `requestPasswordReset` on first login.
+ */
+export interface CustodialSignInResult {
+    readonly session: AithosSession;
+    readonly passwordMustChange: boolean;
+}
+export interface RequestPasswordResetInput {
+    readonly email: string;
+}
+/**
+ * Input to {@link AithosAuth.applyPasswordReset}. Finalises a password
+ * reset started by {@link AithosAuth.requestPasswordReset}. The `email`
+ * and `token` come straight from the magic-link URL that landed in the
+ * user's inbox (`?email=…&token=…`); the `newPassword` is what the user
+ * just typed in the reset page.
+ */
+export interface ApplyPasswordResetInput {
+    /** Email address whose password is being reset. */
+    readonly email: string;
+    /** Raw reset token extracted from the magic-link URL query string. */
+    readonly token: string;
+    /** New password — must satisfy the backend's policy (≥ 10 chars). */
+    readonly newPassword: string;
+}
+/**
+ * Result of {@link AithosAuth.applyPasswordReset}. Carries a fresh JWT
+ * session so the UI can either redirect to a "you're now signed in"
+ * landing or prompt the user to sign in explicitly with their new
+ * credentials — same {@link CustodialSignInResult} shape as a normal
+ * sign-in.
+ *
+ * Note: unlike {@link signInCustodial}, this DOES NOT hydrate the local
+ * keystore. The reset path on the auth Lambda re-wraps the seed bundle
+ * with KMS but doesn't return it (the user just typed a password — they
+ * still need to sign in once to materialise the seeds locally). The
+ * {@link AithosSession} returned here lets the app store the JWT and
+ * call {@link signInCustodial} to complete hydration.
+ */
+export interface ApplyPasswordResetResult {
+    readonly session: AithosSession;
+}
 export declare class AithosAuth {
     #private;
     readonly authBaseUrl: string;
@@ -248,6 +327,81 @@ export declare class AithosAuth {
      * already completed setup; nothing to do).
      */
     completeSsoFirstLogin(input: CompleteSsoFirstLoginInput): Promise<CompleteSsoFirstLoginResult>;
+    /**
+     * Provision a custodial-mode account on behalf of a registered app.
+     *
+     * SERVER-ONLY — the API key MUST stay off the browser. The raw user
+     * password is generated server-side and sent to the user via the
+     * Aithos welcome email; it is NEVER returned in this response.
+     *
+     * Typical use site: your app's backend in response to a sign-up form
+     * submission. The frontend never sees the API key, only the resulting
+     * `{ userId, did, handle, email, mailSent }` it can show to the user
+     * ("we just sent you a mail with your credentials").
+     *
+     * Errors map to `AithosSDKError` codes:
+     *   - `auth_missing_api_key`         (your code passed empty apiKey)
+     *   - `auth_invalid_api_key`         (Bearer rejected by backend)
+     *   - `auth_api_key_revoked`         (backend marked the key revoked)
+     *   - `auth_email_exists`            (409 — email already registered)
+     *   - `auth_email_invalid`           (400 — bad email format)
+     *   - `auth_mail_send_failed`        (502 — DDB row exists but SES failed)
+     *   - `auth_custodial_signup_failed` (catch-all)
+     */
+    signUpCustodial(input: CustodialSignUpInput): Promise<CustodialSignUpResult>;
+    /**
+     * Authenticate a custodial-mode user with email + password. Single
+     * round-trip: returns a fresh JWT session AND hydrates the local
+     * KeyStore with the user's 4 Ed25519 seeds (KMS-unwrapped server-side
+     * after Argon2id verify).
+     *
+     * After this returns, the SDK is ready to publish ethos editions,
+     * invoke compute, mint mandates, etc. — exactly as if the user had
+     * signed in via {@link signIn} (zk) or {@link handleCallback} (SSO).
+     *
+     * Errors map to `AithosSDKError` codes:
+     *   - `auth_invalid_input`        (your code passed empty fields)
+     *   - `auth_invalid_credentials`  (401 — wrong email / wrong password)
+     *   - `auth_wrong_auth_mode`      (403 — user exists in another flow)
+     */
+    signInCustodial(input: CustodialSignInInput): Promise<CustodialSignInResult>;
+    /**
+     * Trigger a password-reset email to the given address. Backend ALWAYS
+     * resolves silently (no enumeration) — caller cannot tell whether the
+     * email is registered or not. The mail itself, if sent, contains a
+     * magic-link URL of shape `<resetBaseUrl>?token=<raw>&email=<email>`.
+     *
+     * Per-email rate limits apply server-side (5 mails/day, 5 min cooldown
+     * between consecutive requests). Calls during cooldown silently no-op
+     * the mail send while still returning success here.
+     */
+    requestPasswordReset(input: RequestPasswordResetInput): Promise<void>;
+    /**
+     * Finalise a password reset using the magic-link token sent to the
+     * user's inbox by {@link requestPasswordReset}.
+     *
+     * Typical use site: the page mounted on the reset URL declared in
+     * `aithos-auth-apps.reset_base_url`. The page reads `email` and
+     * `token` from `window.location.search`, prompts the user for a new
+     * password, then calls this method.
+     *
+     * On success, the returned {@link AithosSession} is persisted to the
+     * session store but the local keystore is NOT hydrated — the backend
+     * does not return the seed bundle on this endpoint. To get a fully
+     * usable session (one that can sign envelopes), follow up with
+     * {@link signInCustodial} using the email + new password. The two
+     * round-trips can be hidden inside a single UI action: reset → auto
+     * sign-in → redirect to dashboard.
+     *
+     * Errors map to `AithosSDKError` codes:
+     *   - `auth_invalid_input`              (your code passed empty fields)
+     *   - `auth_reset_token_invalid`        (400 — token forged / wrong email)
+     *   - `auth_reset_token_expired`        (410 — token TTL elapsed)
+     *   - `auth_reset_token_consumed`       (409 — already used)
+     *   - `auth_password_too_short`         (400 — < 10 chars)
+     *   - `auth_custodial_reset_failed`     (catch-all)
+     */
+    applyPasswordReset(input: ApplyPasswordResetInput): Promise<ApplyPasswordResetResult>;
     signOut(): Promise<void>;
 }
 //# sourceMappingURL=auth.d.ts.map

package/dist/src/auth.js

@@ -21,7 +21,7 @@
 // keyStore is the source of truth for "is the user signed in", the
 // JWT is auxiliary for compute/wallet.
 import { buildBlobPlaintext, buildSignedEnvelope, createBrowserIdentity, decryptBlob, DEFAULT_KDF, deriveAuthAndEncKeys, encryptBlob, parseBlob, randomNonce, randomSalt, serializeBlob, signedDidDocument, zeroize, } from "@aithos/protocol-client";
-import { loginChallenge, loginVerify, putBlob, registerAccount, } from "./auth-api.js";
+import { custodialResetFinalize, custodialResetRequest, custodialSignIn, custodialSignUp, loginChallenge, loginVerify, putBlob, registerAccount, } from "./auth-api.js";
 import { defaultSessionStore, } from "./session-store.js";
 import { defaultKeyStore, } from "./key-store.js";
 import { parseDelegateBundle, readDelegateBundleText, } from "./internal/delegate-bundle.js";
@@ -771,6 +771,188 @@ export class AithosAuth {
         };
     }
     /* ------------------------------------------------------------------------ */
+    /*  Custodial flow (V2 — see PLATFORM-AUTH-PASSWORD-V2-PLAN.md)             */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Provision a custodial-mode account on behalf of a registered app.
+     *
+     * SERVER-ONLY — the API key MUST stay off the browser. The raw user
+     * password is generated server-side and sent to the user via the
+     * Aithos welcome email; it is NEVER returned in this response.
+     *
+     * Typical use site: your app's backend in response to a sign-up form
+     * submission. The frontend never sees the API key, only the resulting
+     * `{ userId, did, handle, email, mailSent }` it can show to the user
+     * ("we just sent you a mail with your credentials").
+     *
+     * Errors map to `AithosSDKError` codes:
+     *   - `auth_missing_api_key`         (your code passed empty apiKey)
+     *   - `auth_invalid_api_key`         (Bearer rejected by backend)
+     *   - `auth_api_key_revoked`         (backend marked the key revoked)
+     *   - `auth_email_exists`            (409 — email already registered)
+     *   - `auth_email_invalid`           (400 — bad email format)
+     *   - `auth_mail_send_failed`        (502 — DDB row exists but SES failed)
+     *   - `auth_custodial_signup_failed` (catch-all)
+     */
+    async signUpCustodial(input) {
+        if (!input.apiKey) {
+            throw new AithosSDKError("auth_missing_api_key", "signUpCustodial: apiKey is required");
+        }
+        if (!input.email) {
+            throw new AithosSDKError("auth_invalid_input", "signUpCustodial: email is required");
+        }
+        return custodialSignUp({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, input);
+    }
+    /**
+     * Authenticate a custodial-mode user with email + password. Single
+     * round-trip: returns a fresh JWT session AND hydrates the local
+     * KeyStore with the user's 4 Ed25519 seeds (KMS-unwrapped server-side
+     * after Argon2id verify).
+     *
+     * After this returns, the SDK is ready to publish ethos editions,
+     * invoke compute, mint mandates, etc. — exactly as if the user had
+     * signed in via {@link signIn} (zk) or {@link handleCallback} (SSO).
+     *
+     * Errors map to `AithosSDKError` codes:
+     *   - `auth_invalid_input`        (your code passed empty fields)
+     *   - `auth_invalid_credentials`  (401 — wrong email / wrong password)
+     *   - `auth_wrong_auth_mode`      (403 — user exists in another flow)
+     */
+    async signInCustodial(input) {
+        if (!input.email || !input.password) {
+            throw new AithosSDKError("auth_invalid_input", "signInCustodial: email and password are required");
+        }
+        const resp = await custodialSignIn({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, input);
+        // Split the 128-byte seed bundle into the four sphere seeds. The
+        // backend lays them out in the canonical order
+        // [root || public || circle || self] (cf. seed-wrapper.ts).
+        if (resp.seed.byteLength !== 128) {
+            // Legacy 32-byte rows shouldn't happen in production (we wiped the
+            // single test row before redeploying with the 4-seed bundle), but
+            // we surface a clear error rather than silently corrupting the
+            // identity.
+            zeroize(resp.seed);
+            zeroize(resp.encKey);
+            throw new AithosSDKError("auth_custodial_seed_format", `signInCustodial: expected 128-byte seed bundle, got ${resp.seed.byteLength}`);
+        }
+        const seedRoot = resp.seed.slice(0, 32);
+        const seedPublic = resp.seed.slice(32, 64);
+        const seedCircle = resp.seed.slice(64, 96);
+        const seedSelf = resp.seed.slice(96, 128);
+        // Stored shape uses hex strings; round-trip through bytesToHex
+        // so the keyStore record is identical to what signUp(zk) writes.
+        const stored = {
+            version: "0.1.0-hex",
+            did: resp.did,
+            handle: resp.handle,
+            displayName: resp.displayName,
+            seedsHex: {
+                root: bytesToHex(seedRoot),
+                public: bytesToHex(seedPublic),
+                circle: bytesToHex(seedCircle),
+                self: bytesToHex(seedSelf),
+            },
+            savedAt: new Date().toISOString(),
+        };
+        // Zeroize the raw bundle + the split copies now that they've been
+        // serialised into the keyStore record (hex strings live in the
+        // record; the original bytes can go).
+        zeroize(resp.seed);
+        zeroize(seedRoot);
+        zeroize(seedPublic);
+        zeroize(seedCircle);
+        zeroize(seedSelf);
+        // The enc_key is informational here — the custodial blob is empty
+        // at first login. We still don't keep it in memory.
+        zeroize(resp.encKey);
+        // Hydrate in-memory owner signers from the freshly-stored material.
+        if (this.#ownerSigners)
+            this.#ownerSigners.destroy();
+        this.#ownerSigners = OwnerSigners.fromStoredOwnerKeys(stored);
+        await this.#keyStore.saveOwner(stored);
+        const session = {
+            session: resp.session,
+            exp: resp.exp,
+            did: resp.did,
+            handle: resp.handle,
+            blob_b64: bytesToB64Public(resp.blob),
+            blob_nonce_b64: bytesToB64Public(resp.blobNonce),
+            blob_version: resp.blobVersion,
+            enc_key_b64: "",
+            is_first_login: resp.passwordMustChange,
+        };
+        this.#sessionStore.set(session);
+        return { session, passwordMustChange: resp.passwordMustChange };
+    }
+    /**
+     * Trigger a password-reset email to the given address. Backend ALWAYS
+     * resolves silently (no enumeration) — caller cannot tell whether the
+     * email is registered or not. The mail itself, if sent, contains a
+     * magic-link URL of shape `<resetBaseUrl>?token=<raw>&email=<email>`.
+     *
+     * Per-email rate limits apply server-side (5 mails/day, 5 min cooldown
+     * between consecutive requests). Calls during cooldown silently no-op
+     * the mail send while still returning success here.
+     */
+    async requestPasswordReset(input) {
+        if (!input.email) {
+            throw new AithosSDKError("auth_invalid_input", "requestPasswordReset: email is required");
+        }
+        await custodialResetRequest({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, input.email);
+    }
+    /**
+     * Finalise a password reset using the magic-link token sent to the
+     * user's inbox by {@link requestPasswordReset}.
+     *
+     * Typical use site: the page mounted on the reset URL declared in
+     * `aithos-auth-apps.reset_base_url`. The page reads `email` and
+     * `token` from `window.location.search`, prompts the user for a new
+     * password, then calls this method.
+     *
+     * On success, the returned {@link AithosSession} is persisted to the
+     * session store but the local keystore is NOT hydrated — the backend
+     * does not return the seed bundle on this endpoint. To get a fully
+     * usable session (one that can sign envelopes), follow up with
+     * {@link signInCustodial} using the email + new password. The two
+     * round-trips can be hidden inside a single UI action: reset → auto
+     * sign-in → redirect to dashboard.
+     *
+     * Errors map to `AithosSDKError` codes:
+     *   - `auth_invalid_input`              (your code passed empty fields)
+     *   - `auth_reset_token_invalid`        (400 — token forged / wrong email)
+     *   - `auth_reset_token_expired`        (410 — token TTL elapsed)
+     *   - `auth_reset_token_consumed`       (409 — already used)
+     *   - `auth_password_too_short`         (400 — < 10 chars)
+     *   - `auth_custodial_reset_failed`     (catch-all)
+     */
+    async applyPasswordReset(input) {
+        if (!input.email || !input.token || !input.newPassword) {
+            throw new AithosSDKError("auth_invalid_input", "applyPasswordReset: email, token and newPassword are required");
+        }
+        const resp = await custodialResetFinalize({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, input);
+        // The reset endpoint mints a JWT but doesn't ship the seed bundle —
+        // the caller still has to signInCustodial() to materialise the keys
+        // locally. We persist the session anyway so any code that reads
+        // `getCurrentSession()` between the reset and the follow-up sign-in
+        // sees the new JWT (e.g. an analytics hook).
+        const session = {
+            session: resp.session,
+            exp: resp.exp,
+            did: resp.did,
+            handle: resp.handle,
+            // No blob / enc_key on this path — the reset endpoint doesn't
+            // re-issue the vault. Leave the blob slots empty; the follow-up
+            // signInCustodial() will populate them.
+            blob_b64: "",
+            blob_nonce_b64: "",
+            blob_version: 0,
+            enc_key_b64: "",
+            is_first_login: false,
+        };
+        this.#sessionStore.set(session);
+        return { session };
+    }
+    /* ------------------------------------------------------------------------ */
     /*  Sign-out                                                                 */
     /* ------------------------------------------------------------------------ */
     async signOut() {

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.1.0-alpha.26";
+export declare const VERSION = "0.1.0-alpha.30";
 export { AithosSDK } from "./sdk.js";
 export type { AithosSDKConfig } from "./types.js";
 export { AithosSDKError } from "./types.js";
@@ -12,7 +12,7 @@ export { WalletNamespace } from "./wallet.js";
 export type { ComponentStyle, ExtractArgs, ExtractContent, ExtractData, ExtractForm, ExtractFormField, ExtractHeading, ExtractIconDeclaration, ExtractImage, ExtractLink, ExtractLogo, ExtractMeta, ExtractResult, ExtractSection, ExtractStructure, ExtractStyles, FetchAssetArgs, FetchAssetResult, PaletteEntry, VisualSignature, WebNamespaceDeps, } from "./web.js";
 export { WebNamespace, WEB_EXTRACT_SCOPE } from "./web.js";
 export { AithosAuth, DEFAULT_API_BASE_URL, DEFAULT_AUTH_BASE_URL, } from "./auth.js";
-export type { AithosAuthConfig, AithosSession, CompleteSsoFirstLoginInput, CompleteSsoFirstLoginResult, DelegateInfo, ImportMandateInput, OwnerInfo, SignInInput, SignInWithGoogleOptions, SignInWithRecoveryInput, SignUpInput, SignUpResult, } from "./auth.js";
+export type { AithosAuthConfig, AithosSession, ApplyPasswordResetInput, ApplyPasswordResetResult, CompleteSsoFirstLoginInput, CompleteSsoFirstLoginResult, CustodialSignInInput, CustodialSignInResult, CustodialSignUpInput, CustodialSignUpResult, DelegateInfo, ImportMandateInput, OwnerInfo, RequestPasswordResetInput, SignInInput, SignInWithGoogleOptions, SignInWithRecoveryInput, SignUpInput, SignUpResult, } from "./auth.js";
 export { DEFAULT_SESSION_STORAGE_KEY, defaultSessionStore, localStorageStore, noopStore, sessionStorageStore, type AithosSessionStore, } from "./session-store.js";
 export { DEFAULT_KEYSTORE_DB_NAME, defaultKeyStore, indexedDbKeyStore, memoryKeyStore, type AithosKeyStore, type StoredDelegateKeys, type StoredOwnerKeys, } from "./key-store.js";
 export { EthosClient, EthosNamespace, EthosZone, ZONE_NAMES, } from "./ethos.js";

package/dist/src/index.js

@@ -17,7 +17,7 @@
 // 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.26";
+export const VERSION = "0.1.0-alpha.30";
 export { AithosSDK } from "./sdk.js";
 export { AithosSDKError } from "./types.js";
 // Re-export protocol-client's JSON-RPC error type so consumers can

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.28",
+  "version": "0.1.0-alpha.30",
   "description": "Aithos SDK \u2014 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",