cauthy-auth 0.5.2 → 0.9.0

package/dist/client.d.mts

@@ -0,0 +1,273 @@
+import { CauthyTheme } from './theme.mjs';
+import { i as PublicSession } from './system-ZD_Wa8Bm.mjs';
+import { A as AuthField } from './validate-B_iC-4y8.mjs';
+export { F as FieldProblem, M as MIN_PASSWORD, c as checkCode, a as checkEmail, b as checkName, d as checkNewPassword, e as checkPassword } from './validate-B_iC-4y8.mjs';
+import 'jose';
+
+interface SessionState {
+    /** The signed-in person and their organizations, or null. */
+    session: PublicSession | null;
+    status: 'loading' | 'authenticated' | 'unauthenticated';
+}
+interface SessionStoreOptions extends AuthClientOptions {
+    /**
+     * The session the server already read while rendering (SSR): the first
+     * paint is then right, with no "loading". `null` means "nobody"; leave it
+     * out when the server did not look.
+     */
+    initialSession?: PublicSession | null;
+}
+interface SessionStore {
+    /** What is known now. */
+    get(): SessionState;
+    /** Calls `listener` now and on every change. Answers how to stop. */
+    subscribe(listener: (state: SessionState) => void): () => void;
+    /** Asks the server again who is signed in. */
+    refresh(): Promise<PublicSession | null>;
+    /** Sends the browser to Cauthy's page to sign in, and back to `returnTo` (default: where it is now). */
+    signIn(options?: {
+        returnTo?: string;
+        locale?: string;
+        prompt?: 'login';
+    }): void;
+    /** Signs out of this application and of Cauthy in this browser. */
+    signOut(): void;
+    /** Where the person looks after their account on Cauthy's page. */
+    accountUrl(returnTo?: string): string;
+    /**
+     * The functions of an application's own screens. They are
+     * `createAuthClient()`'s, and what changes who is signed in is heard by the
+     * subscribers with no reload.
+     */
+    auth: AuthClient;
+    /** Where the server mounted the routes. */
+    basePath: string;
+}
+declare function createSessionStore(options?: SessionStoreOptions): SessionStore;
+
+/** What went wrong, in a form the screen can show. */
+interface AuthError {
+    /** Stable, for translating: `invalid_credentials`, `invalid_email`, `too_short`, `email_taken`, `unavailable`… */
+    code: string;
+    message: string;
+    /** The input it is about, when it is about one. */
+    field?: AuthField;
+}
+type AuthResult<S extends string, More = unknown> = ({
+    ok: true;
+    status: S;
+} & More) | {
+    ok: false;
+    error: AuthError;
+};
+/** What the screen may offer. */
+interface AuthMethods {
+    /** The providers the workspace signs people in with: `{ id: 'google', name: 'Google' }`. */
+    providers: {
+        id: string;
+        name: string;
+    }[];
+    /** Whether people may create an account themselves. */
+    signUp: boolean;
+    magicLink: boolean;
+    /** Whether to offer a passkey. It is asked for on Cauthy's page: the person goes there for that step and comes back signed in. */
+    passkey: boolean;
+}
+/** A person's own account, as their account screen shows it. */
+interface Account {
+    id: string;
+    email: string;
+    name: string;
+    emailVerified: boolean;
+    /** False for an account that only signs in through a provider: it has no current password to ask for. */
+    hasPassword: boolean;
+    mfaEnabled: boolean;
+}
+/** Somewhere the person is signed in. Moments are UTC. */
+interface AccountSession {
+    /** "Mac · Chrome", or "" when the browser did not say. */
+    device: string;
+    ip: string;
+    createdAt: string;
+    expiresAt: string;
+}
+/**
+ * The signed-in person's own account. What weakens it — the password, the
+ * second step, its recovery codes — asks for the current password again.
+ */
+/** A provider the account can also sign in with. */
+interface LinkedIdentity {
+    provider: string;
+    /** The address the provider has for the person, when it said. */
+    email: string;
+    name: string;
+    /** When it was linked, in UTC (ISO 8601). */
+    linkedAt: string;
+}
+interface AccountClient {
+    /** The account, or null when nobody is signed in. */
+    get(): Promise<Account | null>;
+    update(form: {
+        name: string;
+    }): Promise<AuthResult<'saved', {
+        account: Account;
+    }>>;
+    /** Ends every other session of the account; this one stays signed in. */
+    changePassword(form: {
+        password: string;
+        newPassword: string;
+    }): Promise<AuthResult<'changed', {
+        signedIn: boolean;
+    }>>;
+    mfa: {
+        /** Starts turning the second step on: show `secret` (or `otpauthUri` as a QR code) to add to an authenticator app, then call `verify`. */
+        setup(form: {
+            password: string;
+        }): Promise<AuthResult<'started', {
+            secret: string;
+            otpauthUri: string;
+        }>>;
+        /** Turns it on with a code from the app. `recoveryCodes` are shown this once. */
+        verify(form: {
+            code: string;
+        }): Promise<AuthResult<'enabled', {
+            recoveryCodes: string[];
+        }>>;
+        disable(form: {
+            password: string;
+        }): Promise<AuthResult<'disabled'>>;
+        /** New recovery codes; the earlier ones stop working. */
+        recoveryCodes(form: {
+            password: string;
+        }): Promise<AuthResult<'renewed', {
+            recoveryCodes: string[];
+        }>>;
+    };
+    /**
+     * Asks to sign in with another address. Nothing changes yet: the new address
+     * is mailed a link to confirm it, and once it is confirmed the old one is
+     * told, with a link that undoes it. Both open Cauthy's own page.
+     */
+    changeEmail(form: {
+        email: string;
+        password: string;
+    }): Promise<AuthResult<'sent', {
+        email: string;
+    }>>;
+    /** The providers (Google…) the account can also sign in with. */
+    identities(): Promise<LinkedIdentity[]>;
+    /**
+     * Sends the browser to the provider, to link it to the account; it comes back
+     * at `returnTo` with `?linked=<provider>`, or `?auth_error=<code>`.
+     */
+    link(provider: string, options?: {
+        returnTo?: string;
+    }): void;
+    /** Where `link` sends the browser, for a plain link. */
+    linkUrl(provider: string, options?: {
+        returnTo?: string;
+    }): string;
+    /** The account stops signing in with that provider. Refused when it would be left with no way to sign in. */
+    unlink(provider: string): Promise<AuthResult<'unlinked', {
+        provider: string;
+    }>>;
+    /** Where the account is signed in. */
+    sessions(): Promise<AccountSession[]>;
+    /** Signs the account out everywhere, here too. */
+    signOutEverywhere(): Promise<AuthResult<'signed_out'>>;
+}
+interface AuthClient {
+    signIn: {
+        /** With address and password. `mfa_required`: ask for the code and call `signIn.mfa`. */
+        email(form: {
+            email: string;
+            password: string;
+        }): Promise<AuthResult<'signed_in', {
+            session: PublicSession;
+        }> | AuthResult<'mfa_required'>>;
+        /** The second step: the code of the authenticator app, or a recovery code. */
+        mfa(form: {
+            code: string;
+        }): Promise<AuthResult<'signed_in', {
+            session: PublicSession;
+        }>>;
+        /** Mails a link that signs the person in. The answer is the same whether or not the address has an account. */
+        magicLink(form: {
+            email: string;
+        }): Promise<AuthResult<'sent'>>;
+        /** Signs in with the token the mailed link opened the page with (`ml_token`). */
+        magicLinkVerify(form: {
+            token: string;
+        }): Promise<AuthResult<'signed_in', {
+            session: PublicSession;
+        }>>;
+        /** Signs in with the code that came in the same mail as the link, for somebody reading it on another device. */
+        emailCode(form: {
+            code: string;
+        }): Promise<AuthResult<'signed_in', {
+            session: PublicSession;
+        }>>;
+        /** Sends the browser to Cauthy's page to use a passkey; it comes back signed in, at `returnTo`. */
+        passkey(options?: {
+            returnTo?: string;
+            locale?: string;
+        }): void;
+        /** Where `passkey` sends the browser, for a plain link. */
+        passkeyUrl(options?: {
+            returnTo?: string;
+            locale?: string;
+        }): string;
+        /** Sends the browser to the provider; it comes back signed in, at `returnTo`. */
+        social(provider: string, options?: {
+            returnTo?: string;
+        }): void;
+        /** Where `social` sends the browser, for a plain link. */
+        socialUrl(provider: string, options?: {
+            returnTo?: string;
+        }): string;
+    };
+    signUp: {
+        /** `verification_required`: the account exists and must open the link Cauthy mailed before it can sign in. */
+        email(form: {
+            email: string;
+            password: string;
+            name?: string;
+        }): Promise<AuthResult<'signed_in', {
+            session: PublicSession;
+        }> | AuthResult<'verification_required', {
+            email: string;
+        }>>;
+    };
+    /** Mails a link to choose a new password. The answer is the same whether or not the address has an account. */
+    forgotPassword(form: {
+        email: string;
+    }): Promise<AuthResult<'sent'>>;
+    /** Sets the new password, with the token the mailed link opened the page with (`token`). */
+    resetPassword(form: {
+        token: string;
+        password: string;
+    }): Promise<AuthResult<'changed'>>;
+    /** Confirms the address, with the token the mailed link opened the page with (`token`). */
+    verifyEmail(form: {
+        token: string;
+    }): Promise<AuthResult<'verified'>>;
+    signOut(): Promise<AuthResult<'signed_out'>>;
+    /** The signed-in person's own account. */
+    account: AccountClient;
+    /** Who is signed in, or null. */
+    getSession(): Promise<PublicSession | null>;
+    methods(): Promise<AuthMethods>;
+    /**
+     * How the workspace's forms look — colours, corners, typeface — as a person
+     * set it in Cauthy's dashboard. Read once per page; null when Cauthy cannot say.
+     */
+    look(): Promise<CauthyTheme | null>;
+}
+interface AuthClientOptions {
+    /** Where the server mounted the routes. Default: `/api/auth`. */
+    basePath?: string;
+    fetch?: typeof fetch;
+}
+declare function createAuthClient(options?: AuthClientOptions): AuthClient;
+
+export { type Account, type AccountClient, type AccountSession, type AuthClient, type AuthClientOptions, type AuthError, AuthField, type AuthMethods, type AuthResult, type LinkedIdentity, type SessionState, type SessionStore, type SessionStoreOptions, createAuthClient, createSessionStore };

package/dist/client.d.ts

@@ -0,0 +1,273 @@
+import { CauthyTheme } from './theme.js';
+import { i as PublicSession } from './system-DhRr_WxR.js';
+import { A as AuthField } from './validate-B_iC-4y8.js';
+export { F as FieldProblem, M as MIN_PASSWORD, c as checkCode, a as checkEmail, b as checkName, d as checkNewPassword, e as checkPassword } from './validate-B_iC-4y8.js';
+import 'jose';
+
+interface SessionState {
+    /** The signed-in person and their organizations, or null. */
+    session: PublicSession | null;
+    status: 'loading' | 'authenticated' | 'unauthenticated';
+}
+interface SessionStoreOptions extends AuthClientOptions {
+    /**
+     * The session the server already read while rendering (SSR): the first
+     * paint is then right, with no "loading". `null` means "nobody"; leave it
+     * out when the server did not look.
+     */
+    initialSession?: PublicSession | null;
+}
+interface SessionStore {
+    /** What is known now. */
+    get(): SessionState;
+    /** Calls `listener` now and on every change. Answers how to stop. */
+    subscribe(listener: (state: SessionState) => void): () => void;
+    /** Asks the server again who is signed in. */
+    refresh(): Promise<PublicSession | null>;
+    /** Sends the browser to Cauthy's page to sign in, and back to `returnTo` (default: where it is now). */
+    signIn(options?: {
+        returnTo?: string;
+        locale?: string;
+        prompt?: 'login';
+    }): void;
+    /** Signs out of this application and of Cauthy in this browser. */
+    signOut(): void;
+    /** Where the person looks after their account on Cauthy's page. */
+    accountUrl(returnTo?: string): string;
+    /**
+     * The functions of an application's own screens. They are
+     * `createAuthClient()`'s, and what changes who is signed in is heard by the
+     * subscribers with no reload.
+     */
+    auth: AuthClient;
+    /** Where the server mounted the routes. */
+    basePath: string;
+}
+declare function createSessionStore(options?: SessionStoreOptions): SessionStore;
+
+/** What went wrong, in a form the screen can show. */
+interface AuthError {
+    /** Stable, for translating: `invalid_credentials`, `invalid_email`, `too_short`, `email_taken`, `unavailable`… */
+    code: string;
+    message: string;
+    /** The input it is about, when it is about one. */
+    field?: AuthField;
+}
+type AuthResult<S extends string, More = unknown> = ({
+    ok: true;
+    status: S;
+} & More) | {
+    ok: false;
+    error: AuthError;
+};
+/** What the screen may offer. */
+interface AuthMethods {
+    /** The providers the workspace signs people in with: `{ id: 'google', name: 'Google' }`. */
+    providers: {
+        id: string;
+        name: string;
+    }[];
+    /** Whether people may create an account themselves. */
+    signUp: boolean;
+    magicLink: boolean;
+    /** Whether to offer a passkey. It is asked for on Cauthy's page: the person goes there for that step and comes back signed in. */
+    passkey: boolean;
+}
+/** A person's own account, as their account screen shows it. */
+interface Account {
+    id: string;
+    email: string;
+    name: string;
+    emailVerified: boolean;
+    /** False for an account that only signs in through a provider: it has no current password to ask for. */
+    hasPassword: boolean;
+    mfaEnabled: boolean;
+}
+/** Somewhere the person is signed in. Moments are UTC. */
+interface AccountSession {
+    /** "Mac · Chrome", or "" when the browser did not say. */
+    device: string;
+    ip: string;
+    createdAt: string;
+    expiresAt: string;
+}
+/**
+ * The signed-in person's own account. What weakens it — the password, the
+ * second step, its recovery codes — asks for the current password again.
+ */
+/** A provider the account can also sign in with. */
+interface LinkedIdentity {
+    provider: string;
+    /** The address the provider has for the person, when it said. */
+    email: string;
+    name: string;
+    /** When it was linked, in UTC (ISO 8601). */
+    linkedAt: string;
+}
+interface AccountClient {
+    /** The account, or null when nobody is signed in. */
+    get(): Promise<Account | null>;
+    update(form: {
+        name: string;
+    }): Promise<AuthResult<'saved', {
+        account: Account;
+    }>>;
+    /** Ends every other session of the account; this one stays signed in. */
+    changePassword(form: {
+        password: string;
+        newPassword: string;
+    }): Promise<AuthResult<'changed', {
+        signedIn: boolean;
+    }>>;
+    mfa: {
+        /** Starts turning the second step on: show `secret` (or `otpauthUri` as a QR code) to add to an authenticator app, then call `verify`. */
+        setup(form: {
+            password: string;
+        }): Promise<AuthResult<'started', {
+            secret: string;
+            otpauthUri: string;
+        }>>;
+        /** Turns it on with a code from the app. `recoveryCodes` are shown this once. */
+        verify(form: {
+            code: string;
+        }): Promise<AuthResult<'enabled', {
+            recoveryCodes: string[];
+        }>>;
+        disable(form: {
+            password: string;
+        }): Promise<AuthResult<'disabled'>>;
+        /** New recovery codes; the earlier ones stop working. */
+        recoveryCodes(form: {
+            password: string;
+        }): Promise<AuthResult<'renewed', {
+            recoveryCodes: string[];
+        }>>;
+    };
+    /**
+     * Asks to sign in with another address. Nothing changes yet: the new address
+     * is mailed a link to confirm it, and once it is confirmed the old one is
+     * told, with a link that undoes it. Both open Cauthy's own page.
+     */
+    changeEmail(form: {
+        email: string;
+        password: string;
+    }): Promise<AuthResult<'sent', {
+        email: string;
+    }>>;
+    /** The providers (Google…) the account can also sign in with. */
+    identities(): Promise<LinkedIdentity[]>;
+    /**
+     * Sends the browser to the provider, to link it to the account; it comes back
+     * at `returnTo` with `?linked=<provider>`, or `?auth_error=<code>`.
+     */
+    link(provider: string, options?: {
+        returnTo?: string;
+    }): void;
+    /** Where `link` sends the browser, for a plain link. */
+    linkUrl(provider: string, options?: {
+        returnTo?: string;
+    }): string;
+    /** The account stops signing in with that provider. Refused when it would be left with no way to sign in. */
+    unlink(provider: string): Promise<AuthResult<'unlinked', {
+        provider: string;
+    }>>;
+    /** Where the account is signed in. */
+    sessions(): Promise<AccountSession[]>;
+    /** Signs the account out everywhere, here too. */
+    signOutEverywhere(): Promise<AuthResult<'signed_out'>>;
+}
+interface AuthClient {
+    signIn: {
+        /** With address and password. `mfa_required`: ask for the code and call `signIn.mfa`. */
+        email(form: {
+            email: string;
+            password: string;
+        }): Promise<AuthResult<'signed_in', {
+            session: PublicSession;
+        }> | AuthResult<'mfa_required'>>;
+        /** The second step: the code of the authenticator app, or a recovery code. */
+        mfa(form: {
+            code: string;
+        }): Promise<AuthResult<'signed_in', {
+            session: PublicSession;
+        }>>;
+        /** Mails a link that signs the person in. The answer is the same whether or not the address has an account. */
+        magicLink(form: {
+            email: string;
+        }): Promise<AuthResult<'sent'>>;
+        /** Signs in with the token the mailed link opened the page with (`ml_token`). */
+        magicLinkVerify(form: {
+            token: string;
+        }): Promise<AuthResult<'signed_in', {
+            session: PublicSession;
+        }>>;
+        /** Signs in with the code that came in the same mail as the link, for somebody reading it on another device. */
+        emailCode(form: {
+            code: string;
+        }): Promise<AuthResult<'signed_in', {
+            session: PublicSession;
+        }>>;
+        /** Sends the browser to Cauthy's page to use a passkey; it comes back signed in, at `returnTo`. */
+        passkey(options?: {
+            returnTo?: string;
+            locale?: string;
+        }): void;
+        /** Where `passkey` sends the browser, for a plain link. */
+        passkeyUrl(options?: {
+            returnTo?: string;
+            locale?: string;
+        }): string;
+        /** Sends the browser to the provider; it comes back signed in, at `returnTo`. */
+        social(provider: string, options?: {
+            returnTo?: string;
+        }): void;
+        /** Where `social` sends the browser, for a plain link. */
+        socialUrl(provider: string, options?: {
+            returnTo?: string;
+        }): string;
+    };
+    signUp: {
+        /** `verification_required`: the account exists and must open the link Cauthy mailed before it can sign in. */
+        email(form: {
+            email: string;
+            password: string;
+            name?: string;
+        }): Promise<AuthResult<'signed_in', {
+            session: PublicSession;
+        }> | AuthResult<'verification_required', {
+            email: string;
+        }>>;
+    };
+    /** Mails a link to choose a new password. The answer is the same whether or not the address has an account. */
+    forgotPassword(form: {
+        email: string;
+    }): Promise<AuthResult<'sent'>>;
+    /** Sets the new password, with the token the mailed link opened the page with (`token`). */
+    resetPassword(form: {
+        token: string;
+        password: string;
+    }): Promise<AuthResult<'changed'>>;
+    /** Confirms the address, with the token the mailed link opened the page with (`token`). */
+    verifyEmail(form: {
+        token: string;
+    }): Promise<AuthResult<'verified'>>;
+    signOut(): Promise<AuthResult<'signed_out'>>;
+    /** The signed-in person's own account. */
+    account: AccountClient;
+    /** Who is signed in, or null. */
+    getSession(): Promise<PublicSession | null>;
+    methods(): Promise<AuthMethods>;
+    /**
+     * How the workspace's forms look — colours, corners, typeface — as a person
+     * set it in Cauthy's dashboard. Read once per page; null when Cauthy cannot say.
+     */
+    look(): Promise<CauthyTheme | null>;
+}
+interface AuthClientOptions {
+    /** Where the server mounted the routes. Default: `/api/auth`. */
+    basePath?: string;
+    fetch?: typeof fetch;
+}
+declare function createAuthClient(options?: AuthClientOptions): AuthClient;
+
+export { type Account, type AccountClient, type AccountSession, type AuthClient, type AuthClientOptions, type AuthError, AuthField, type AuthMethods, type AuthResult, type LinkedIdentity, type SessionState, type SessionStore, type SessionStoreOptions, createAuthClient, createSessionStore };