cauthy-auth 0.5.2 → 0.8.0

package/dist/react.d.mts

@@ -1,10 +1,537 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
-import { P as PublicSession } from './system-CR8p4BjB.mjs';
-export { J as JsonValue, e as SessionOrganization, g as SessionUser } from './system-CR8p4BjB.mjs';
-export { d as can } from './permissions-B-a3eN0h.mjs';
-import 'jose';
-import './theme.mjs';
+import { ComponentType, ReactNode } from 'react';
+
+/** How an application looks on Cauthy's hosted pages. Every value is optional. */
+/** One font file the application serves: a family in one weight (or a range) and one style. */
+interface ThemeFont {
+    family: string;
+    /** An https address of a `.woff2` file. It must answer with `Access-Control-Allow-Origin` for Cauthy's origin. */
+    url: string;
+    /** `400`, or `"100 900"` for a variable font. Default: 400. */
+    weight?: number | string;
+    style?: 'normal' | 'italic';
+}
+/** What an application says on its sign-in page, in one language. */
+interface ThemeTexts {
+    /** Replaces "Sign in". */
+    heading?: string;
+    /** Replaces "to continue to …". */
+    subheading?: string;
+    /** The messages of the split layout's panel, shown one at a time (up to 5). */
+    panel?: string[];
+    /** Links at the foot of the split layout: privacy, terms (up to 4). */
+    links?: {
+        label: string;
+        url: string;
+    }[];
+}
+interface CauthyTheme {
+    /** The page. Colours are `#rrggbb` or `rgba(r, g, b, a)`. */
+    background?: string;
+    /** The card, and inputs. */
+    surface?: string;
+    /** Headings and what is typed. */
+    text?: string;
+    /** Paragraphs, labels, small print. */
+    textMuted?: string;
+    border?: string;
+    /** The fields and the secondary buttons, when they are not the card's colours. */
+    inputBackground?: string;
+    inputBorder?: string;
+    /** The main button, and what is written on it. */
+    primary?: string;
+    primaryText?: string;
+    /** Links, and the focus ring. */
+    accent?: string;
+    error?: string;
+    errorBackground?: string;
+    success?: string;
+    successBackground?: string;
+    /** Corners of cards and inputs, in pixels (0–40). */
+    radius?: number;
+    /** Corners of buttons, in pixels (0–40). */
+    buttonRadius?: number;
+    /** A CSS font-family list: the application's typeface first, a system font after it. */
+    fontFamily?: string;
+    /** The files of the typefaces `fontFamily` names, for people who do not have them installed. */
+    fonts?: ThemeFont[];
+    /** An image shown where "Cauthy" is, over https. */
+    logoUrl?: string;
+    /**
+     * How the sign-in pages are laid out: `card` (the default, one card in the
+     * middle) or `split` (the form on one side, a panel that presents the
+     * application on the other).
+     */
+    layout?: 'card' | 'split';
+    /** The colours the split layout's backdrop blends, one to four. */
+    panelColors?: string[];
+    /** The colour of what is written on the panel. */
+    panelText?: string;
+    /** An https image shown over the panel's messages. */
+    panelIconUrl?: string;
+    /** The application's own words on the sign-in page, by language (`en`, `es`). */
+    texts?: Record<string, ThemeTexts>;
+    /**
+     * The application's Stackmyth tokens (`--sm-*`), from `tokensFromStackmyth`.
+     * Cauthy's pages are drawn with Stackmyth's components, so these make its
+     * buttons and fields the application's own. They are laid over the named values.
+     */
+    tokens?: Record<string, string>;
+}
+
+/** The part of an organization that says what its member may do. */
+interface Permitted {
+    /** "resource:action" entries the person is allowed; "*" is any. Absent when the system keeps no catalog in Cauthy. */
+    permissions?: string[];
+    /** Entries the person is denied whatever else allows them. */
+    denied?: string[];
+}
+/**
+ * Whether the person may do an action on a resource in an organization:
+ * allowed by some entry, and denied by none. A denial wins.
+ *
+ * An organization of a system that keeps no catalog in Cauthy carries no
+ * permissions, and the answer is `false`: decide by its `role` instead.
+ *
+ *   if (!can(organization, 'invoicing', 'write')) return forbidden()
+ */
+declare function can(organization: Permitted | null | undefined, resource: string, action: string): boolean;
+/** Something a role may do: an action on a resource, in organizations of a kind ("*", the default, is every kind). */
+interface PolicyPermission {
+    kind?: string;
+    resource: string;
+    action: string;
+}
+interface PolicyRole {
+    role: string;
+    name?: string;
+    description?: string;
+    /** Roles whose permissions this one has as well. */
+    inherits?: string[];
+    permissions?: PolicyPermission[];
+}
+/** A role as `definePolicy` reads it: any `PolicyRole`, kept as written. */
+type RoleShape = {
+    readonly role: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly inherits?: readonly string[];
+    readonly permissions?: readonly {
+        readonly kind?: string;
+        readonly resource: string;
+        readonly action: string;
+    }[];
+};
+type Named<S extends string> = S extends '*' ? string : S;
+type PermissionsIn<R> = R extends {
+    readonly permissions: readonly (infer P)[];
+} ? P extends {
+    readonly resource: infer Res extends string;
+    readonly action: infer Act extends string;
+} ? `${Named<Res>}:${Named<Act>}` : never : never;
+/** The roles a catalog names: `RoleOf<typeof policy>`. */
+type RoleOf<P> = P extends Policy<infer R, string> ? R : never;
+/** The "resource:action" permissions a catalog names: `PermissionOf<typeof policy>`. */
+type PermissionOf<P> = P extends Policy<string, infer X> ? X : never;
+interface Policy<Role extends string = string, Permission extends string = string> {
+    /** The catalog as Cauthy takes it: `pushPolicy({ roles: policy.roles })`. */
+    roles: PolicyRole[];
+    /** Every role's name. */
+    roleNames: Role[];
+    /** Every permission some role has, as "resource:action". */
+    permissions: Permission[];
+    /**
+     * Whether the person may do this in the organization: `can(org, 'ledger:write')`.
+     * It reads what Cauthy sent with the session, so a catalog edited in Cauthy
+     * since this file was written is still what decides.
+     */
+    can(organization: Permitted | null | undefined, permission: Permission): boolean;
+    /** Whether the person's role in the organization is one of these. */
+    hasRole(organization: {
+        role: string;
+    } | null | undefined, ...roles: Role[]): boolean;
+    /**
+     * What a role may do by this catalog, with what it inherits: for showing a
+     * role, never for deciding about a person (their exceptions are not here).
+     */
+    permissionsOf(role: Role): Permission[];
+}
+/** Gives a catalog of roles its types. See the top of this section. */
+declare function definePolicy<const T extends readonly RoleShape[]>(roles: T): Policy<T[number]['role'], PermissionsIn<T[number]>>;
+
+/** The person signed in. Every moment is UTC. */
+interface SessionUser {
+    id: string;
+    email: string;
+    name: string;
+    emailVerified: boolean;
+    /**
+     * True when the account ran out of time to confirm its address: let it read
+     * and refuse its writes.
+     */
+    restricted: boolean;
+    /** When an unconfirmed address stops being enough (ISO 8601, UTC), if there is a deadline. */
+    emailVerifyBy?: string;
+    /** The language the person reads in ("es", "en-US"), when Cauthy knows it. */
+    locale?: string;
+}
+/** A value JSON can carry. What crosses from server to browser is typed as this, never `unknown`. */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** An organization the person belongs to, with their role in it. */
+interface SessionOrganization {
+    id: string;
+    system: string;
+    name: string;
+    kind: string;
+    externalId?: string;
+    role: string;
+    /** What the system keeps about the organization, as it filed it in Cauthy. */
+    metadata: Record<string, JsonValue>;
+    /**
+     * What the person may do here, as "resource:action" entries ("*" is any):
+     * their role's permissions, what it inherits, and anything given to them
+     * apart from it. Absent when the system keeps no catalog of roles in Cauthy.
+     * Check with `can(organization, resource, action)`.
+     */
+    permissions?: string[];
+    /** What the person is denied here, whatever else allows it. */
+    denied?: string[];
+}
+/** What the browser is told of a session: who, and their organizations — never a token. */
+interface PublicSession {
+    user: SessionUser;
+    tenantId: string;
+    roles: string[];
+    organizations: SessionOrganization[];
+    expiresAt: string;
+}
+
+type AuthField = 'email' | 'password' | 'newPassword' | 'name' | 'code';
+
+/** 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$1 {
+    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.
+ */
+interface AccountClient {
+    /** The account, or null when nobody is signed in. */
+    get(): Promise<Account$1 | null>;
+    update(form: {
+        name: string;
+    }): Promise<AuthResult<'saved', {
+        account: Account$1;
+    }>>;
+    /** 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[];
+        }>>;
+    };
+    /** 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;
+
+/** Every sentence the forms show. Give any of them to change it. */
+interface AuthTexts {
+    email: string;
+    password: string;
+    name: string;
+    code: string;
+    signIn: string;
+    signUp: string;
+    continueWith: string;
+    orWithEmail: string;
+    forgotPassword: string;
+    noAccount: string;
+    createAccount: string;
+    haveAccount: string;
+    sendLink: string;
+    linkSent: string;
+    codeHelp: string;
+    verify: string;
+    checkEmail: string;
+    backToSignIn: string;
+    emailMeALink: string;
+    usePasskey: string;
+    codeFromMail: string;
+    signInLinkSent: string;
+    newPassword: string;
+    savePassword: string;
+    passwordChanged: string;
+    confirming: string;
+    emailConfirmed: string;
+    profile: string;
+    save: string;
+    saved: string;
+    currentPassword: string;
+    changePassword: string;
+    passwordChangedHere: string;
+    secondStep: string;
+    secondStepOn: string;
+    secondStepOff: string;
+    turnOn: string;
+    turnOff: string;
+    addToApp: string;
+    openInApp: string;
+    recoveryCodes: string;
+    newRecoveryCodes: string;
+    keepCodes: string;
+    passkeys: string;
+    managePasskeys: string;
+    sessions: string;
+    signOutEverywhere: string;
+    unknownDevice: string;
+    /** By error code; one missing shows what the server said. */
+    errors: Record<string, string>;
+}
+type Slot = 'form' | 'field' | 'label' | 'input' | 'button' | 'providerButton' | 'link' | 'error' | 'fieldError' | 'notice' | 'separator' | 'footer' | 'account' | 'section' | 'heading' | 'secret' | 'codes' | 'sessions' | 'session';
+interface AuthFormProps {
+    /** The language of the built-in sentences. Default: `en`. */
+    locale?: 'en' | 'es';
+    /** Sentences of the application's own, over the built-in ones. */
+    texts?: Partial<Omit<AuthTexts, 'errors'>> & {
+        errors?: Record<string, string>;
+    };
+    /** Called once the person is signed in. Default: go to `returnTo`. */
+    onSuccess?: () => void;
+    /** Where to go after signing in, and where a provider returns to. Default: `/`. */
+    returnTo?: string;
+    /** Paths of the application's other screens, for the links between them. */
+    links?: {
+        signIn?: string;
+        signUp?: string;
+        forgotPassword?: string;
+    };
+    /** A class for each part the form renders. A part given one is left to it by `styles.css`. */
+    classNames?: Partial<Record<Slot, string>>;
+    /**
+     * No look of Cauthy's at all: `styles.css` leaves the form alone and the
+     * workspace's colours are not read. For a form drawn wholly with the
+     * application's own `components` or `classNames`.
+     */
+    unstyled?: boolean;
+    /**
+     * Take the colours, corners and typeface a person set for the workspace in
+     * Cauthy's dashboard. Default: true. False keeps `styles.css`'s own, and
+     * whatever `--cauthy-*` variables the application sets.
+     */
+    workspaceLook?: boolean;
+    /**
+     * The application's own button and input, to draw the form with. Each is
+     * given what a `<button>` or an `<input>` would be.
+     */
+    components?: {
+        Button?: ComponentType<{
+            type: 'submit' | 'button';
+            disabled?: boolean;
+            className?: string;
+            onClick?: () => void;
+            children: ReactNode;
+        }>;
+        Input?: ComponentType<{
+            id: string;
+            name: string;
+            type: string;
+            value: string;
+            autoComplete?: string;
+            required?: boolean;
+            className?: string;
+            'aria-invalid'?: boolean;
+            'aria-describedby'?: string;
+            onChange: (e: {
+                target: {
+                    value: string;
+                };
+            }) => void;
+        }>;
+    };
+}
+declare function SignIn(props: AuthFormProps): react.JSX.Element;
+declare function SignUp(props: AuthFormProps): react.JSX.Element;
+declare function ForgotPassword(props: AuthFormProps): react.JSX.Element;
+/** The page a "choose a new password" link opens: `pages.resetPassword`. */
+declare function ResetPassword(props: AuthFormProps): react.JSX.Element;
+/** The page a "confirm your address" link opens: `pages.verifyEmail`. It confirms as it opens. */
+declare function VerifyEmail(props: AuthFormProps): react.JSX.Element;
+interface AccountProps extends Omit<AuthFormProps, 'links' | 'returnTo' | 'onSuccess'> {
+    /** Called after "sign out everywhere". Default: go to `/`. */
+    onSignedOut?: () => void;
+    /** The moment of a session, as the application writes dates. Default: the browser's own way, in the reader's time zone. */
+    formatDate?: (iso: string) => string;
+}
+/**
+ * The signed-in person's account, in the application: their name, their
+ * password, the second step, and where they are signed in. Each part saves on
+ * its own. Like the other forms, it carries no styles.
+ */
+declare function Account(props: AccountProps): react.JSX.Element;
 
 interface SessionContext {
     /** The signed-in person and their organizations, or null. */
@@ -22,6 +549,8 @@ interface SessionContext {
     refresh(): Promise<PublicSession | null>;
     /** Where the person looks after their account: password, second step, passkeys. */
     accountUrl(returnTo?: string): string;
+    /** Where the server mounted the routes. */
+    basePath: string;
 }
 interface CauthyProviderProps {
     children: ReactNode;
@@ -36,5 +565,15 @@ interface CauthyProviderProps {
 }
 declare function CauthyProvider({ children, basePath, initialSession }: CauthyProviderProps): react.JSX.Element;
 declare function useSession(): SessionContext;
+/**
+ * The application's own sign-in screens: the functions a form calls.
+ *
+ *   const { signIn, signUp, forgotPassword, signOut, session } = useAuth()
+ *   const r = await signIn.email({ email, password })
+ *
+ * They are `createAuthClient()`'s, and what is on screen follows them: after
+ * a sign-in or a sign-out, `session` is the new one with no reload.
+ */
+declare function useAuth(): AuthClient & Pick<SessionContext, 'session' | 'status' | 'refresh'>;
 
-export { CauthyProvider, type CauthyProviderProps, PublicSession, type SessionContext, useSession };
+export { Account, type AccountClient, type Account$1 as AccountDetails, type AccountProps, type AccountSession, type AuthClient, type AuthError, type AuthFormProps, type AuthMethods, type AuthResult, type AuthTexts, CauthyProvider, type CauthyProviderProps, ForgotPassword, type JsonValue, type PermissionOf, type Policy, type PublicSession, ResetPassword, type RoleOf, type SessionContext, type SessionOrganization, type SessionUser, SignIn, SignUp, VerifyEmail, can, createAuthClient, definePolicy, useAuth, useSession };