@aithos/sdk 0.1.0-alpha.5 → 0.1.0-alpha.51

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

@@ -21,6 +21,15 @@ export interface RegisterApiResponse {
     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;
@@ -37,5 +46,215 @@ 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 {
+    /** 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;
+}
+/**
+ * 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>;
+/**
+ * Input for {@link custodialInvite}. The app authenticates via `apiKey`
+ * (server-only secret) or `publicKey` (browser-safe, Origin-gated). The
+ * `invitePayload` is an OPAQUE app string delivered verbatim to the invitee
+ * on {@link custodialAccept}. For Aithos invitations it's a delegate bundle
+ * (mandate + seed) serialized as JSON — but the auth backend never parses it;
+ * it stores it bound to a single-use token and returns it at accept time.
+ */
+export interface CustodialInviteApiInput {
+    readonly apiKey?: string;
+    readonly publicKey?: string;
+    readonly email: string;
+    /** Opaque payload delivered to the invitee on accept (e.g. a mandate bundle JSON). */
+    readonly invitePayload: string;
+    /** Token TTL in seconds. Backend clamps to its own min/max. Default backend-side. */
+    readonly ttlSeconds?: number;
+    /** Optional display name pre-filled on the pending account. */
+    readonly displayName?: string;
+}
+export interface CustodialInviteApiResponse {
+    readonly status: "invited";
+    readonly email: string;
+    readonly mailSent: boolean;
+    readonly mailMessageId?: string;
+}
+/**
+ * Send an invitation magic link carrying an opaque payload. The backend
+ * mints a single-use token, stores `{ token, email, invite_payload, ttl }`,
+ * and emails the magic link (same SES path as the verification mail). The
+ * payload (e.g. a mandate bundle) stays server-side — it never rides the
+ * email URL. The invitee redeems it via {@link custodialAccept}.
+ *
+ * No password here: this is an invitation, not an account creation. The
+ * invitee chooses their password when they accept.
+ */
+export declare function custodialInvite(http: HttpClient, input: CustodialInviteApiInput): Promise<CustodialInviteApiResponse>;
+export interface CustodialAcceptApiInput {
+    readonly email: string;
+    readonly token: string;
+    /**
+     * Password. For a brand-new account the invitee SETS it here; for an
+     * existing account they AUTHENTICATE with it. Required unless the backend
+     * accepts a session-bound redemption (not in v1).
+     */
+    readonly password?: string;
+}
+/**
+ * Result of redeeming an invitation. Always `signed_in` on success — the
+ * token is consumed, the account is created (or the existing one is
+ * authenticated), and a full session payload is returned alongside the
+ * `invitePayload` the inviter attached. `accountCreated` distinguishes the
+ * two cases for UX.
+ */
+export interface CustodialAcceptApiResponse {
+    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;
+    /** The opaque payload the inviter attached (e.g. a mandate bundle JSON). */
+    readonly invitePayload: string;
+    /** True when a new account was provisioned; false when an existing one signed in. */
+    readonly accountCreated: boolean;
+}
+/**
+ * Redeem an invitation token from the magic link. Consumes the token
+ * (single-use), creates the account with the supplied password (or
+ * authenticates an existing account), and returns a session + the inviter's
+ * `invitePayload`.
+ *
+ * Throws `auth_token_invalid_or_expired` (bad/consumed/expired token) or an
+ * auth error if an existing account's password is wrong / a new password is
+ * too weak.
+ */
+export declare function custodialAccept(http: HttpClient, input: CustodialAcceptApiInput): Promise<CustodialAcceptApiResponse>;
+/** 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

@@ -41,6 +41,19 @@ async function postJson(http, path, body, jwt) {
         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,
@@ -56,6 +69,13 @@ export async function registerAccount(http, input) {
         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 {
@@ -79,4 +99,232 @@ export async function loginVerify(http, email, authKey) {
         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. 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,
+    };
+}
+/**
+ * Send an invitation magic link carrying an opaque payload. The backend
+ * mints a single-use token, stores `{ token, email, invite_payload, ttl }`,
+ * and emails the magic link (same SES path as the verification mail). The
+ * payload (e.g. a mandate bundle) stays server-side — it never rides the
+ * email URL. The invitee redeems it via {@link custodialAccept}.
+ *
+ * No password here: this is an invitation, not an account creation. The
+ * invitee chooses their password when they accept.
+ */
+export async function custodialInvite(http, input) {
+    if (!input.apiKey && !input.publicKey) {
+        throw new AithosSDKError("auth_missing_api_key", "inviteCustodial requires either apiKey or publicKey");
+    }
+    if (input.apiKey && input.publicKey) {
+        throw new AithosSDKError("auth_invalid_input", "inviteCustodial: pass exactly one of apiKey or publicKey, not both");
+    }
+    const bearer = (input.apiKey ?? input.publicKey);
+    const res = await http.fetchImpl(`${http.authBaseUrl}/auth/custodial/invite`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${bearer}`,
+        },
+        body: JSON.stringify({
+            email: input.email,
+            invite_payload: input.invitePayload,
+            ...(input.ttlSeconds !== undefined ? { ttl_seconds: input.ttlSeconds } : {}),
+            ...(input.displayName ? { display_name: input.displayName } : {}),
+        }),
+    });
+    if (!res.ok)
+        throw await readError(res, "custodial_invite_failed");
+    const wire = (await res.json());
+    return {
+        status: "invited",
+        email: wire.email,
+        mailSent: wire.mail_sent,
+        ...(wire.mail_message_id !== undefined ? { mailMessageId: wire.mail_message_id } : {}),
+    };
+}
+/**
+ * Redeem an invitation token from the magic link. Consumes the token
+ * (single-use), creates the account with the supplied password (or
+ * authenticates an existing account), and returns a session + the inviter's
+ * `invitePayload`.
+ *
+ * Throws `auth_token_invalid_or_expired` (bad/consumed/expired token) or an
+ * auth error if an existing account's password is wrong / a new password is
+ * too weak.
+ */
+export async function custodialAccept(http, input) {
+    const res = await http.fetchImpl(`${http.authBaseUrl}/auth/custodial/accept`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            email: input.email,
+            token: input.token,
+            ...(input.password ? { password: input.password } : {}),
+        }),
+    });
+    if (!res.ok)
+        throw await readError(res, "custodial_accept_failed");
+    const wire = (await res.json());
+    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,
+        invitePayload: wire.invite_payload,
+        accountCreated: wire.account_created,
+    };
+}
+/* ---- 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