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

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

@@ -46,27 +46,101 @@ export interface LoginVerifyResponse {
     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 {
-    readonly apiKey: string;
+    /** 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 {
-    readonly userId: string;
-    readonly did: string;
-    readonly handle: string;
+    /** 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.
- * 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.
+ *
+ * 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;
+}
+/**
+ * Result of consuming the verification link. Magic-link mode: a
+ * successful first-time consumption returns a full session payload
+ * (JWT + seeds) so the caller can sign the user in without prompting
+ * for the password. Replays of the same link (after first consumption)
+ * land on `status: "already_verified"` — the user is already verified
+ * and must use the regular sign-in flow from now on.
+ *
+ * The discriminator is the `status` field. Callers should pattern-match.
+ */
+export type CustodialVerifyEmailApiResponse = {
+    readonly status: "signed_in";
+    readonly session: string;
+    readonly exp: number;
+    readonly did: string;
+    readonly handle: string;
+    readonly displayName: string;
+    readonly seed: Uint8Array;
+    readonly encKey: Uint8Array;
+    readonly blob: Uint8Array;
+    readonly blobNonce: Uint8Array;
+    readonly blobVersion: number;
+} | {
+    readonly status: "already_verified";
+    readonly email: string;
+};
+/**
+ * Consume the verification token from the confirmation link. On a fresh
+ * click: returns a full session payload (magic-link auto-signin). On a
+ * replayed click of an already-consumed link: returns
+ * `{ status: "already_verified" }`.
+ *
+ * Throws `auth_token_invalid_or_expired` if the token is wrong, consumed,
+ * or past its TTL.
+ */
+export declare function custodialVerifyEmail(http: HttpClient, input: CustodialVerifyEmailApiInput): Promise<CustodialVerifyEmailApiResponse>;
+/** 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;

package/dist/src/auth-api.js

@@ -101,19 +101,35 @@ export async function loginVerify(http, email, authKey) {
 }
 /**
  * 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.
+ *
+ * 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 ${input.apiKey}`,
+            authorization: `Bearer ${bearer}`,
         },
         body: JSON.stringify({
             email: input.email,
+            password: input.password,
             ...(input.displayName ? { display_name: input.displayName } : {}),
             ...(input.handleHint ? { handle_hint: input.handleHint } : {}),
         }),
@@ -122,9 +138,7 @@ export async function custodialSignUp(http, input) {
         throw await readError(res, "custodial_signup_failed");
     const wire = (await res.json());
     return {
-        userId: wire.user_id,
-        did: wire.did,
-        handle: wire.handle,
+        status: "pending_verification",
         email: wire.email,
         mailSent: wire.mail_sent,
         ...(wire.mail_message_id !== undefined
@@ -132,6 +146,64 @@ export async function custodialSignUp(http, input) {
             : {}),
     };
 }
+/**
+ * Consume the verification token from the confirmation link. On a fresh
+ * click: returns a full session payload (magic-link auto-signin). On a
+ * replayed click of an already-consumed link: returns
+ * `{ status: "already_verified" }`.
+ *
+ * Throws `auth_token_invalid_or_expired` if the token is wrong, consumed,
+ * or past its 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");
+    const wire = (await res.json());
+    if (wire.status === "already_verified") {
+        return { status: "already_verified", email: wire.email };
+    }
+    return {
+        status: "signed_in",
+        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,
+    };
+}
+/* ---- 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 {

package/dist/src/auth.d.ts

@@ -22,6 +22,22 @@ export interface AithosAuthConfig {
     readonly sessionStore?: AithosSessionStore;
     /** Pluggable key persistence. Defaults to {@link defaultKeyStore}. */
     readonly keyStore?: AithosKeyStore;
+    /**
+     * Public client key issued by Aithos for browser callers
+     * (`pk_<env>_<…>`). When set, the custodial endpoints (`signUpCustodial`,
+     * `verifyEmail`, `resendVerificationEmail`) authenticate as this app
+     * by default — the caller no longer has to repeat the key on every
+     * call. The corresponding `allowed_origins` allowlist must include the
+     * current page's origin.
+     *
+     * Safe to ship in the browser bundle: it grants nothing beyond what
+     * a visitor of the app can already do, is gated by Origin on every
+     * call, and is rate-limited per IP by the backend.
+     *
+     * If your app authenticates with a SECRET Bearer API key from a
+     * backend instead, leave this unset and pass `apiKey` per call.
+     */
+    readonly publicKey?: string;
 }
 /**
  * Active Aithos session. Returned by JWT-backed entry points
@@ -136,36 +152,85 @@ export interface ImportMandateInput {
     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.
+ * Input to {@link AithosAuth.signUpCustodial}.
+ *
+ * The caller authenticates as an app via ONE of:
+ *   - `apiKey`     : server-only secret Bearer. Pass from your backend
+ *                    only — never ship it in browser code.
+ *   - `publicKey`  : browser-safe public client key. Safe to embed in
+ *                    the bundle; the backend gates it by Origin and
+ *                    rate-limits by IP.
+ *
+ * If you set `publicKey` on the {@link AithosAuth} constructor, omit
+ * both fields here — the default credential is used.
+ *
+ * The `password` is always required and is chosen by the user (sign-up
+ * no longer auto-generates one). The created account starts as
+ * **pending** (`email_verified=false`); the user must click the
+ * confirmation link sent by SES before {@link signInCustodial} works.
  */
 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. */
+    /** Server-only Bearer secret. Mutually exclusive with `publicKey`. */
+    readonly apiKey?: string;
+    /** Browser-safe public client key. Mutually exclusive with `apiKey`.
+     *  Overrides the constructor's default `publicKey` when provided. */
+    readonly publicKey?: string;
+    /** Email address of the new user. Will receive the verification mail. */
     readonly email: string;
+    /** Raw password the user chose. ≥ 10 chars, mix of letters with
+     *  ≥ 1 digit or symbol. Enforced server-side. */
+    readonly password: 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.
+ * Result of {@link AithosAuth.signUpCustodial}. Always carries
+ * `status: "pending_verification"` — the user must click the link in
+ * their inbox before sign-in works. If `mailSent` is false the row
+ * exists in DDB anyway; trigger {@link AithosAuth.resendVerificationEmail}
+ * to retry the SES send.
  */
 export interface CustodialSignUpResult {
-    readonly userId: string;
-    readonly did: string;
-    readonly handle: string;
+    readonly status: "pending_verification";
     readonly email: string;
     readonly mailSent: boolean;
     readonly mailMessageId?: string;
 }
+/** Input to {@link AithosAuth.verifyEmail}. Both fields come straight
+ *  out of the `?email=&token=` query string of the confirmation URL. */
+export interface VerifyEmailInput {
+    readonly email: string;
+    readonly token: string;
+}
+/**
+ * Result of {@link AithosAuth.verifyEmail}. Discriminated by `status`.
+ *
+ *  - `"signed_in"` (magic-link mode): the user has been authenticated
+ *    in this call. A JWT session is persisted to the session store and
+ *    the local keystore is hydrated with the unwrapped seed bundle.
+ *    The caller can navigate the user straight to a logged-in area.
+ *  - `"already_verified"`: the verification link had already been
+ *    consumed on a previous click. No session is minted (the token is
+ *    spent). The caller should route the user to the sign-in form.
+ */
+export type VerifyEmailResult = {
+    readonly status: "signed_in";
+    readonly session: AithosSession;
+    readonly passwordMustChange: false;
+} | {
+    readonly status: "already_verified";
+    readonly email: string;
+};
+/** Input to {@link AithosAuth.resendVerificationEmail}. The `email` is
+ *  required; credential overrides follow the same rules as
+ *  {@link CustodialSignUpInput}. */
+export interface ResendVerificationInput {
+    readonly email: string;
+    readonly apiKey?: string;
+    readonly publicKey?: string;
+}
 export interface CustodialSignInInput {
     readonly email: string;
     readonly password: string;
@@ -330,25 +395,66 @@ export declare class AithosAuth {
     /**
      * 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.
+     * Two integration patterns:
+     *   - **Frontend-only** apps : set `publicKey` on the constructor
+     *     (or on this call). Safe to ship in browser bundles — the
+     *     backend gates each request by Origin + IP rate limit.
+     *   - **Backend-fronted** apps : the backend passes `apiKey` (secret
+     *     Bearer); the browser never sees the credential.
      *
-     * 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").
+     * The created account is in a *pending* state — sign-in stays blocked
+     * until the user clicks the confirmation link sent to their inbox.
+     * Call {@link verifyEmail} from the page mounted on
+     * `app.verify_base_url` to consume the token; afterwards
+     * {@link signInCustodial} works.
      *
      * Errors map to `AithosSDKError` codes:
-     *   - `auth_missing_api_key`         (your code passed empty apiKey)
+     *   - `auth_missing_api_key`         (no credential provided)
      *   - `auth_invalid_api_key`         (Bearer rejected by backend)
-     *   - `auth_api_key_revoked`         (backend marked the key revoked)
+     *   - `auth_invalid_public_key`      (public key rejected by backend)
+     *   - `auth_api_key_revoked` / `auth_public_key_revoked`
+     *   - `auth_origin_not_allowed`      (public key + Origin not in allowlist)
+     *   - `auth_password_too_weak`       (400 — server-side strength check)
      *   - `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>;
+    /**
+     * Magic-link auto-signin: consume the verification token from the
+     * confirmation link, KMS-unwrap the seed bundle server-side, and
+     * hydrate the local session + keystore in one round-trip.
+     *
+     * Outcome depends on the link's state:
+     *   - First click on a fresh link → returns
+     *     `{ status: "signed_in", session, … }`. The session store is
+     *     populated, the owner signers are loaded — the user is signed
+     *     in. The caller should navigate them to a logged-in route.
+     *   - Click of an already-consumed link → returns
+     *     `{ status: "already_verified", email }`. No session is minted;
+     *     the user must sign in via {@link signInCustodial}.
+     *
+     * Mount this on the page declared as `verify_base_url` in your app's
+     * registration. Read `email` + `token` from `window.location.search`,
+     * call this, branch on `result.status`.
+     *
+     * Throws `auth_token_invalid_or_expired` if the token is wrong or
+     * past its 1h TTL — surface a "request a fresh link" CTA in that case.
+     */
+    verifyEmail(input: VerifyEmailInput): Promise<VerifyEmailResult>;
+    /**
+     * Re-send the verification mail for a pending account. Use when the
+     * user reports never having received the welcome mail, or when their
+     * verification token expired (24h TTL).
+     *
+     * The backend is anti-enumeration (always 200) and rate-limited
+     * 1/h/account, so it's safe to call even when the state of `email`
+     * is unknown. Accepts the same credential families as
+     * {@link signUpCustodial}; falls back to the constructor's
+     * `publicKey` when neither override is set.
+     */
+    resendVerificationEmail(input: ResendVerificationInput): Promise<void>;
     /**
      * Authenticate a custodial-mode user with email + password. Single
      * round-trip: returns a fresh JWT session AND hydrates the local

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 { custodialResetFinalize, custodialResetRequest, custodialSignIn, custodialSignUp, loginChallenge, loginVerify, putBlob, registerAccount, } from "./auth-api.js";
+import { custodialResendVerify, custodialResetFinalize, custodialResetRequest, custodialSignIn, custodialSignUp, custodialVerifyEmail, 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";
@@ -43,6 +43,7 @@ export class AithosAuth {
     #win;
     #sessionStore;
     #keyStore;
+    #publicKey;
     /** In-memory owner signers — populated after sign-in or `resume`. */
     #ownerSigners = null;
     /** Active delegate registry. */
@@ -66,6 +67,7 @@ export class AithosAuth {
                 (typeof window !== "undefined" ? window : undefined);
         this.#sessionStore = config.sessionStore ?? defaultSessionStore();
         this.#keyStore = config.keyStore ?? defaultKeyStore();
+        this.#publicKey = config.publicKey;
     }
     /* ------------------------------------------------------------------------ */
     /*  Boot-time hydration                                                      */
@@ -776,32 +778,154 @@ export class AithosAuth {
     /**
      * 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.
+     * Two integration patterns:
+     *   - **Frontend-only** apps : set `publicKey` on the constructor
+     *     (or on this call). Safe to ship in browser bundles — the
+     *     backend gates each request by Origin + IP rate limit.
+     *   - **Backend-fronted** apps : the backend passes `apiKey` (secret
+     *     Bearer); the browser never sees the credential.
      *
-     * 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").
+     * The created account is in a *pending* state — sign-in stays blocked
+     * until the user clicks the confirmation link sent to their inbox.
+     * Call {@link verifyEmail} from the page mounted on
+     * `app.verify_base_url` to consume the token; afterwards
+     * {@link signInCustodial} works.
      *
      * Errors map to `AithosSDKError` codes:
-     *   - `auth_missing_api_key`         (your code passed empty apiKey)
+     *   - `auth_missing_api_key`         (no credential provided)
      *   - `auth_invalid_api_key`         (Bearer rejected by backend)
-     *   - `auth_api_key_revoked`         (backend marked the key revoked)
+     *   - `auth_invalid_public_key`      (public key rejected by backend)
+     *   - `auth_api_key_revoked` / `auth_public_key_revoked`
+     *   - `auth_origin_not_allowed`      (public key + Origin not in allowlist)
+     *   - `auth_password_too_weak`       (400 — server-side strength check)
      *   - `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);
+        if (!input.password) {
+            throw new AithosSDKError("auth_invalid_input", "signUpCustodial: password is required");
+        }
+        const apiKey = input.apiKey;
+        const publicKey = input.publicKey ?? this.#publicKey;
+        if (!apiKey && !publicKey) {
+            throw new AithosSDKError("auth_missing_api_key", "signUpCustodial: pass apiKey, or publicKey, or set publicKey on the AithosAuth constructor");
+        }
+        return custodialSignUp({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, {
+            email: input.email,
+            password: input.password,
+            ...(apiKey ? { apiKey } : {}),
+            ...(apiKey ? {} : publicKey ? { publicKey } : {}),
+            ...(input.displayName ? { displayName: input.displayName } : {}),
+            ...(input.handleHint ? { handleHint: input.handleHint } : {}),
+        });
+    }
+    /**
+     * Magic-link auto-signin: consume the verification token from the
+     * confirmation link, KMS-unwrap the seed bundle server-side, and
+     * hydrate the local session + keystore in one round-trip.
+     *
+     * Outcome depends on the link's state:
+     *   - First click on a fresh link → returns
+     *     `{ status: "signed_in", session, … }`. The session store is
+     *     populated, the owner signers are loaded — the user is signed
+     *     in. The caller should navigate them to a logged-in route.
+     *   - Click of an already-consumed link → returns
+     *     `{ status: "already_verified", email }`. No session is minted;
+     *     the user must sign in via {@link signInCustodial}.
+     *
+     * Mount this on the page declared as `verify_base_url` in your app's
+     * registration. Read `email` + `token` from `window.location.search`,
+     * call this, branch on `result.status`.
+     *
+     * Throws `auth_token_invalid_or_expired` if the token is wrong or
+     * past its 1h TTL — surface a "request a fresh link" CTA in that case.
+     */
+    async verifyEmail(input) {
+        if (!input.email || !input.token) {
+            throw new AithosSDKError("auth_invalid_input", "verifyEmail: email and token are required");
+        }
+        const resp = await custodialVerifyEmail({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, input);
+        if (resp.status === "already_verified") {
+            return { status: "already_verified", email: resp.email };
+        }
+        // Magic-link sign-in path. Mirror `signInCustodial` to materialise
+        // the 4 sphere seeds in the keystore.
+        if (resp.seed.byteLength !== 128) {
+            zeroize(resp.seed);
+            zeroize(resp.encKey);
+            throw new AithosSDKError("auth_custodial_seed_format", `verifyEmail: 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);
+        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(resp.seed);
+        zeroize(seedRoot);
+        zeroize(seedPublic);
+        zeroize(seedCircle);
+        zeroize(seedSelf);
+        zeroize(resp.encKey);
+        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: false,
+        };
+        this.#sessionStore.set(session);
+        return { status: "signed_in", session, passwordMustChange: false };
+    }
+    /**
+     * Re-send the verification mail for a pending account. Use when the
+     * user reports never having received the welcome mail, or when their
+     * verification token expired (24h TTL).
+     *
+     * The backend is anti-enumeration (always 200) and rate-limited
+     * 1/h/account, so it's safe to call even when the state of `email`
+     * is unknown. Accepts the same credential families as
+     * {@link signUpCustodial}; falls back to the constructor's
+     * `publicKey` when neither override is set.
+     */
+    async resendVerificationEmail(input) {
+        if (!input.email) {
+            throw new AithosSDKError("auth_invalid_input", "resendVerificationEmail: email is required");
+        }
+        const apiKey = input.apiKey;
+        const publicKey = input.publicKey ?? this.#publicKey;
+        if (!apiKey && !publicKey) {
+            throw new AithosSDKError("auth_missing_api_key", "resendVerificationEmail: pass apiKey, publicKey, or set publicKey on the AithosAuth constructor");
+        }
+        await custodialResendVerify({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, {
+            email: input.email,
+            ...(apiKey ? { apiKey } : {}),
+            ...(apiKey ? {} : publicKey ? { publicKey } : {}),
+        });
     }
     /**
      * Authenticate a custodial-mode user with email + password. Single

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.1.0-alpha.30";
+export declare const VERSION = "0.1.0-alpha.32";
 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, ApplyPasswordResetInput, ApplyPasswordResetResult, CompleteSsoFirstLoginInput, CompleteSsoFirstLoginResult, CustodialSignInInput, CustodialSignInResult, CustodialSignUpInput, CustodialSignUpResult, DelegateInfo, ImportMandateInput, OwnerInfo, RequestPasswordResetInput, SignInInput, SignInWithGoogleOptions, SignInWithRecoveryInput, SignUpInput, SignUpResult, } from "./auth.js";
+export type { AithosAuthConfig, AithosSession, ApplyPasswordResetInput, ApplyPasswordResetResult, CompleteSsoFirstLoginInput, CompleteSsoFirstLoginResult, CustodialSignInInput, CustodialSignInResult, CustodialSignUpInput, CustodialSignUpResult, DelegateInfo, ImportMandateInput, OwnerInfo, RequestPasswordResetInput, ResendVerificationInput, SignInInput, SignInWithGoogleOptions, SignInWithRecoveryInput, SignUpInput, SignUpResult, VerifyEmailInput, VerifyEmailResult, } 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.30";
+export const VERSION = "0.1.0-alpha.32";
 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.30",
+  "version": "0.1.0-alpha.32",
   "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",