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

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

@@ -0,0 +1,41 @@
+import { type KdfParams } from "@aithos/protocol-client";
+interface HttpClient {
+    readonly fetchImpl: typeof fetch;
+    readonly authBaseUrl: string;
+}
+export interface RegisterApiInput {
+    readonly email: string;
+    readonly handle: string;
+    readonly displayName: string;
+    readonly did: string;
+    readonly authKey: Uint8Array;
+    readonly authSalt: Uint8Array;
+    readonly encSalt: Uint8Array;
+    readonly kdf: KdfParams;
+    readonly blob: Uint8Array;
+    readonly blobNonce: Uint8Array;
+    readonly blobVersion: number;
+}
+export interface RegisterApiResponse {
+    readonly session: string;
+    readonly exp: number;
+}
+export declare function registerAccount(http: HttpClient, input: RegisterApiInput): Promise<RegisterApiResponse>;
+export interface LoginChallengeResponse {
+    readonly authSalt: Uint8Array;
+    readonly encSalt: Uint8Array;
+    readonly kdf: KdfParams;
+}
+export declare function loginChallenge(http: HttpClient, email: string): Promise<LoginChallengeResponse>;
+export interface LoginVerifyResponse {
+    readonly session: string;
+    readonly exp: number;
+    readonly did: string;
+    readonly handle: string;
+    readonly blob: Uint8Array;
+    readonly blobNonce: Uint8Array;
+    readonly blobVersion: number;
+}
+export declare function loginVerify(http: HttpClient, email: string, authKey: Uint8Array): Promise<LoginVerifyResponse>;
+export {};
+//# sourceMappingURL=auth-api.d.ts.map

package/dist/src/auth-api.js

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Thin HTTP client over the Aithos auth Lambda.
+//
+// Internal — not exported from the package's public surface. The
+// {@link AithosAuth} class composes these calls with the crypto
+// primitives in `@aithos/protocol-client` and the session store in
+// {@link ./session-store.ts} to expose a high-level
+// signIn / signUp / signInWithGoogle API.
+//
+// Wire format mirrors `aithos/auth/API.md` exactly. All `*_b64` fields
+// are standard-base64 (not URL-safe), padding stripped — see
+// `bytesToB64` / `b64ToBytes` in `@aithos/protocol-client`.
+import { bytesToB64, b64ToBytes, } from "@aithos/protocol-client";
+import { AithosSDKError } from "./types.js";
+async function readError(res, defaultCode) {
+    let body = null;
+    try {
+        body = (await res.json());
+    }
+    catch {
+        /* body not JSON */
+    }
+    const code = typeof body?.code === "string" ? `auth_${body.code}` : `auth_${defaultCode}`;
+    const message = body?.error ?? `${res.status} ${res.statusText || "request failed"}`;
+    return new AithosSDKError(code, message, {
+        status: res.status,
+        ...(body !== null ? { data: body } : {}),
+    });
+}
+async function postJson(http, path, body, jwt) {
+    const res = await http.fetchImpl(`${http.authBaseUrl}${path}`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            ...(jwt ? { authorization: `Bearer ${jwt}` } : {}),
+        },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok)
+        throw await readError(res, "request_failed");
+    return (await res.json());
+}
+export async function registerAccount(http, input) {
+    return postJson(http, "/auth/register", {
+        email: input.email,
+        handle: input.handle,
+        display_name: input.displayName,
+        did: input.did,
+        auth_key_b64: bytesToB64(input.authKey),
+        auth_salt_b64: bytesToB64(input.authSalt),
+        enc_salt_b64: bytesToB64(input.encSalt),
+        kdf: input.kdf,
+        blob_b64: bytesToB64(input.blob),
+        blob_nonce_b64: bytesToB64(input.blobNonce),
+        blob_version: input.blobVersion,
+    });
+}
+export async function loginChallenge(http, email) {
+    const wire = await postJson(http, "/auth/login/challenge", { email });
+    return {
+        authSalt: b64ToBytes(wire.auth_salt_b64),
+        encSalt: b64ToBytes(wire.enc_salt_b64),
+        kdf: wire.kdf,
+    };
+}
+export async function loginVerify(http, email, authKey) {
+    const wire = await postJson(http, "/auth/login/verify", {
+        email,
+        auth_key_b64: bytesToB64(authKey),
+    });
+    return {
+        session: wire.session,
+        exp: wire.exp,
+        did: wire.did,
+        handle: wire.handle,
+        blob: b64ToBytes(wire.blob_b64),
+        blobNonce: b64ToBytes(wire.blob_nonce_b64),
+        blobVersion: wire.blob_version,
+    };
+}
+//# sourceMappingURL=auth-api.js.map

package/dist/src/auth.d.ts

@@ -1,116 +1,155 @@
+import { type AithosSessionStore } from "./session-store.js";
+import { type AithosKeyStore } from "./key-store.js";
+import { DelegateActor } from "./internal/delegate-state.js";
+import { OwnerSigners } from "./internal/owner-signers.js";
 /** Default URL of the Aithos auth backend. */
 export declare const DEFAULT_AUTH_BASE_URL = "https://auth.aithos.be";
-/**
- * Construction options for {@link AithosAuth}.
- */
 export interface AithosAuthConfig {
-    /**
-     * Base URL of the Aithos auth backend. Defaults to
-     * {@link DEFAULT_AUTH_BASE_URL}. Override for staging or self-hosted
-     * deployments.
-     */
     readonly authBaseUrl?: string;
-    /**
-     * Optional `fetch` implementation. Defaults to `globalThis.fetch`. Used
-     * by tests to inject a mock without monkeypatching globals.
-     */
     readonly fetch?: typeof fetch;
-    /**
-     * Optional `window`-like object. Defaults to `globalThis.window` when
-     * available. Provided so node-side tests can assert redirect URLs without
-     * shimming jsdom.
-     */
     readonly window?: Pick<Window, "location" | "history">;
+    /** Pluggable JWT-session storage. Defaults to {@link defaultSessionStore}. */
+    readonly sessionStore?: AithosSessionStore;
+    /** Pluggable key persistence. Defaults to {@link defaultKeyStore}. */
+    readonly keyStore?: AithosKeyStore;
 }
 /**
- * Payload returned by a successful Google sign-in.
- *
- * Wire-compatible with the auth Lambda's `SsoExchangeResponse`. Field names
- * are kept snake_case to match the backend; rationale: avoids an extra
- * mapping layer and keeps the SDK transparent if the user opens the
- * Network panel.
+ * Active Aithos session. Returned by JWT-backed entry points
+ * (`signIn`, `signUp`, `handleCallback`). Recovery-file and mandate
+ * sign-ins do NOT return an `AithosSession` — they yield the lighter
+ * {@link OwnerInfo} / {@link DelegateInfo}.
  */
 export interface AithosSession {
-    /** HS256 JWT — send in `Authorization: Bearer <session>` to auth/* and
-     *  app endpoints that consume it. */
     readonly session: string;
-    /** JWT expiry, Unix seconds. */
     readonly exp: number;
-    /** Aithos DID — `did:aithos:z…`. Stable across all the user's devices. */
     readonly did: string;
-    /** User-visible handle (rendered as `@handle`). */
     readonly handle: string;
-    /** Encrypted vault, base64. Empty string + version 0 on first sign-in. */
     readonly blob_b64: string;
-    /** AES-GCM nonce for the blob, base64 (12 bytes). Empty on first sign-in. */
     readonly blob_nonce_b64: string;
-    /** Monotonic blob version. Bumped on every PUT /auth/blob. */
     readonly blob_version: number;
-    /** 32-byte vault key, base64. Decrypts {@link blob_b64} via AES-GCM-256. */
     readonly enc_key_b64: string;
-    /** True the first time this user signs in. The app should run its
-     *  onboarding flow rather than mounting an empty blob. */
     readonly is_first_login: boolean;
 }
 /**
- * Options for {@link AithosAuth.signInWithGoogle}.
+ * Public information about the loaded owner identity. Available after
+ * any owner-side sign-in (password, Google, recovery), regardless of
+ * whether a JWT is also present.
  */
-export interface SignInWithGoogleOptions {
-    /**
-     * Opaque deep-link state preserved across the OAuth round-trip and
-     * surfaced back to the app via `?app_state=…` on the callback URL. Use
-     * to remember "the user clicked sign-in from /settings/billing" so you
-     * can restore that route after the redirect chain.
-     *
-     * Maximum 1024 characters.
-     */
-    readonly appState?: string;
+export interface OwnerInfo {
+    readonly did: string;
+    readonly handle: string;
+    readonly displayName: string;
 }
 /**
- * Authenticator for the Aithos identity service. One instance per app
- * is the recommended pattern (the constructor is cheap; it just trims the
- * URL). All methods are pure — no module-global state.
+ * Public information about a delegate session held by the SDK. Returned
+ * by `importMandate` and `getDelegates`.
  */
+export interface DelegateInfo {
+    readonly mandateId: string;
+    readonly subjectDid: string;
+    readonly granteeId: string;
+    readonly scopes: readonly string[];
+    /** ISO-8601, or null when the mandate has no `not_after`. */
+    readonly expiresAt: string | null;
+    readonly label?: string;
+}
+export interface SignInWithGoogleOptions {
+    readonly appState?: string;
+}
+export interface SignInInput {
+    readonly email: string;
+    readonly password: string;
+}
+export interface SignUpInput {
+    readonly email: string;
+    readonly password: string;
+    readonly handle: string;
+    readonly displayName?: string;
+}
+export interface SignUpResult {
+    readonly session: AithosSession;
+    readonly recoveryFile: Blob;
+    readonly recoveryFilename: string;
+}
+export interface SignInWithRecoveryInput {
+    /** Recovery file as a Blob (browser File input) or already-decoded JSON string. */
+    readonly file: Blob | string;
+}
+export interface ImportMandateInput {
+    /** Delegate bundle as a Blob or already-decoded JSON string. */
+    readonly bundle: Blob | string;
+}
 export declare class AithosAuth {
-    /** Resolved auth base URL with a trailing slash trimmed. */
+    #private;
     readonly authBaseUrl: string;
-    private readonly fetchImpl;
-    private readonly win;
     constructor(config?: AithosAuthConfig);
     /**
-     * Redirect the browser to Google's OAuth consent screen. Must be called
-     * synchronously in response to a user gesture (button click) — most
-     * browsers block top-level navigation triggered from idle code.
+     * Reload signing material and JWT session from the configured stores.
+     * Must be called once at app boot before relying on
+     * {@link getCurrentSession} / {@link getOwnerInfo} / {@link canSignAsOwner}
+     * — until then they reflect only what's been done in-memory in the
+     * current tab.
      *
-     * Does not return: navigation tears the JS context down. The `never`
-     * return type tells callers any code after the call is unreachable.
+     * Strict consistency: if the JWT and the stored owner disagree about
+     * who's signed in, both are wiped and the user re-auths. JWT-less
+     * owner state (loaded from keyStore but no JWT) is a valid resumed
+     * state — the user signed in via recovery or imported a mandate at
+     * some earlier moment and never went through the JWT flow.
      */
-    signInWithGoogle(opts?: SignInWithGoogleOptions): never;
+    resume(): Promise<void>;
+    /** JWT-backed session. Null when signed in via recovery / mandate / not at all. */
+    getCurrentSession(): AithosSession | null;
+    /** Loaded owner identity. Independent of JWT presence. */
+    getOwnerInfo(): OwnerInfo | null;
+    getDelegates(): readonly DelegateInfo[];
+    canSignAsOwner(): boolean;
+    canSignAsDelegateFor(did: string): boolean;
     /**
-     * Inspect the current URL for an `aithos_code` query parameter. If it's
-     * present, exchange it at the backend and return the resulting
-     * {@link AithosSession}. The query params are stripped from the URL via
-     * `history.replaceState` so a page refresh doesn't replay the redeem
-     * (which would 410 anyway).
+     * Internal accessor used by sibling SDK namespaces (compute, wallet,
+     * ethos) when they need to sign on behalf of the owner. Returns null
+     * if no owner is loaded.
      *
-     * Returns `null` when there's no code in the URL — safe to call on every
-     * page load. Throws {@link AithosSDKError} on backend errors or when
-     * the URL carries `aithos_error=…` (Google denial, token-exchange
-     * failure, etc.).
+     * @internal
      */
-    handleCallback(): Promise<AithosSession | null>;
+    _getOwnerSigners(): OwnerSigners | null;
     /**
-     * Programmatically redeem an `aithos_code` for a session. `handleCallback`
-     * calls this for you; expose it directly for callers that already pulled
-     * the code out of the URL via their own router.
+     * Internal accessor — looks up an active delegate by mandate id.
+     * @internal
      */
-    exchange(aithosCode: string): Promise<AithosSession>;
+    _getDelegateActor(mandateId: string): DelegateActor | undefined;
     /**
-     * Stateless sign-out. The Aithos backend doesn't track sessions, so
-     * there's nothing to revoke server-side; this method exists so the app
-     * has a symmetric API surface and to remind callers to clear their
-     * own storage. The Promise always resolves.
+     * Internal accessor — finds the first active delegate whose subject
+     * matches `did`. Used by `sdk.ethos.of(did)` when the user holds a
+     * mandate for that subject.
+     * @internal
      */
+    _findDelegateForSubject(did: string): DelegateActor | undefined;
+    signIn(input: SignInInput): Promise<AithosSession>;
+    signUp(input: SignUpInput): Promise<SignUpResult>;
+    /**
+     * Sign in by uploading a recovery file. Hydrates the owner signers
+     * locally — no JWT is obtained on this path because the recovery
+     * file alone doesn't authenticate against the auth backend (no
+     * password, no Google session). Apps that need compute/wallet
+     * access should follow up with an email+password sign-in or with
+     * Google SSO.
+     *
+     * The recovery file is ALWAYS the file produced by `signUp` (or the
+     * equivalent one emitted by `protocol-client`'s `runOnboarding`).
+     * Both shapes are accepted.
+     */
+    signInWithRecovery(input: SignInWithRecoveryInput): Promise<OwnerInfo>;
+    /**
+     * Import a delegate bundle (`.aithos-delegate.json`). Works in any
+     * state: with no owner loaded (delegate-only session), or alongside
+     * an existing owner (the user holds mandates for other people's
+     * ethoses while also being an owner themselves).
+     */
+    importMandate(input: ImportMandateInput): Promise<DelegateInfo>;
+    removeMandate(mandateId: string): Promise<void>;
+    signInWithGoogle(opts?: SignInWithGoogleOptions): never;
+    handleCallback(): Promise<AithosSession | null>;
+    exchange(aithosCode: string): Promise<AithosSession>;
     signOut(): Promise<void>;
 }
 //# sourceMappingURL=auth.d.ts.map