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

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

@@ -96,12 +96,42 @@ 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;
-}>;
+/**
+ * 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

package/dist/src/auth-api.js

@@ -146,9 +146,15 @@ export async function custodialSignUp(http, input) {
             : {}),
     };
 }
-/** 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. */
+/**
+ * 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",
@@ -157,7 +163,25 @@ export async function custodialVerifyEmail(http, input) {
     });
     if (!res.ok)
         throw await readError(res, "custodial_verify_failed");
-    return (await res.json());
+    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

package/dist/src/auth.d.ts

@@ -204,6 +204,25 @@ 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}. */
@@ -403,18 +422,27 @@ export declare class AithosAuth {
      */
     signUpCustodial(input: CustodialSignUpInput): Promise<CustodialSignUpResult>;
     /**
-     * Confirm the user's email address by consuming the one-time token
-     * from the confirmation link. Idempotent on repeated clicks; throws
-     * `auth_token_invalid_or_expired` if the token is wrong, already
-     * consumed, or past its 24h TTL.
+     * 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, then redirect to your sign-in page on success.
+     * 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<{
-        ok: true;
-    }>;
+    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

package/dist/src/auth.js

@@ -20,7 +20,7 @@
 // JWT-less sessions (recovery / mandate sign-ins) are valid: the
 // 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 { browserIdentityFromStored, buildBlobPlaintext, buildSignedEnvelope, createBrowserIdentity, decryptBlob, DEFAULT_KDF, deriveAuthAndEncKeys, encryptBlob, parseBlob, randomNonce, randomSalt, serializeBlob, signedDidDocument, zeroize, } from "@aithos/protocol-client";
 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";
@@ -825,20 +825,93 @@ export class AithosAuth {
         });
     }
     /**
-     * Confirm the user's email address by consuming the one-time token
-     * from the confirmation link. Idempotent on repeated clicks; throws
-     * `auth_token_invalid_or_expired` if the token is wrong, already
-     * consumed, or past its 24h TTL.
+     * 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, then redirect to your sign-in page on success.
+     * 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");
         }
-        return custodialVerifyEmail({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, input);
+        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);
+        // Bootstrap the Ethos on api.aithos.be (cf. notes in signInCustodial).
+        // The magic-link flow is the FIRST time the user actually has
+        // hydrated keys client-side, so this is typically when the identity
+        // gets published. Idempotent — safe to call again on subsequent
+        // clicks (which won't get here normally, but defensively).
+        const identity = browserIdentityFromStored({
+            handle: stored.handle,
+            displayName: stored.displayName,
+            did: stored.did,
+            seeds: stored.seedsHex,
+        });
+        await this.#publishIdentity(identity);
+        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
@@ -928,6 +1001,24 @@ export class AithosAuth {
         // 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);
+        // Bootstrap the Ethos on api.aithos.be — same as signUp(zk). Without
+        // this, the DID returned by signInCustodial isn't resolvable on the
+        // platform (feed / profile lookups return "not found: did …"). The
+        // call is idempotent server-side: a published identity replays as a
+        // no-op. We do it here (rather than only on a "first login" flag)
+        // because the auth Lambda doesn't know whether the api.aithos.be
+        // side has been populated — the SDK is the single source of truth
+        // for "the user's Ethos is bootstrapped".
+        //
+        // Failure aborts the sign-in: the user can retry (same behaviour as
+        // signUp(zk)), and the local keystore is NOT populated half-way.
+        const identity = browserIdentityFromStored({
+            handle: stored.handle,
+            displayName: stored.displayName,
+            did: stored.did,
+            seeds: stored.seedsHex,
+        });
+        await this.#publishIdentity(identity);
         // Hydrate in-memory owner signers from the freshly-stored material.
         if (this.#ownerSigners)
             this.#ownerSigners.destroy();

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.1.0-alpha.31";
+export declare const VERSION = "0.1.0-alpha.33";
 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, ResendVerificationInput, SignInInput, SignInWithGoogleOptions, SignInWithRecoveryInput, SignUpInput, SignUpResult, VerifyEmailInput, } 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.31";
+export const VERSION = "0.1.0-alpha.33";
 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,7 +1,7 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.31",
-  "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.",
+  "version": "0.1.0-alpha.33",
+  "description": "Aithos SDK — 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",
     "sdk",
@@ -39,15 +39,6 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsc",
-    "build:test": "tsc -p tsconfig.test.json",
-    "check-types": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
-    "test": "npm run clean && npm run build && npm run build:test && cd dist && node --test",
-    "test:watch": "cd dist && node --test --watch",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "npm run clean && npm run build && npm test"
-  },
   "engines": {
     "node": ">=20"
   },
@@ -63,5 +54,13 @@
   "publishConfig": {
     "access": "public",
     "tag": "alpha"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:test": "tsc -p tsconfig.test.json",
+    "check-types": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test": "npm run clean && npm run build && npm run build:test && cd dist && node --test",
+    "test:watch": "cd dist && node --test --watch",
+    "clean": "rm -rf dist"
   }
-}
+}