cauthy-auth 0.28.1 → 0.31.0

package/dist/react.d.ts

@@ -85,6 +85,8 @@ interface Permitted {
     permissions?: string[];
     /** Entries the person is denied whatever else allows them. */
     denied?: string[];
+    /** Permissions with a condition: in neither list, so `can` never counts them. Ask with `auth.check`. */
+    conditional?: ConditionalPermission[];
 }
 /**
  * Whether the person may do an action on a resource in an organization:
@@ -93,6 +95,11 @@ interface Permitted {
  * An organization of a system that keeps no catalog in Cauthy carries no
  * permissions, and the answer is `false`: decide by its `role` instead.
  *
+ * A permission with a condition (`organization.conditional`) is not in the
+ * lists, so `can` answers `false` for what only it allows: the condition reads
+ * the record at hand, which only Cauthy can weigh. Ask with `auth.check`
+ * (`organizations.check` in the browser).
+ *
  *   if (!can(organization, 'invoicing', 'write')) return forbidden()
  */
 declare function can(organization: Permitted | null | undefined, resource: string, action: string): boolean;
@@ -101,6 +108,21 @@ interface PolicyPermission {
     kind?: string;
     resource: string;
     action: string;
+    /**
+     * When it holds, in CEL: `resource.attrs.amount <= 1000000`. A permission
+     * with one is decided by Cauthy per question (`auth.check`), never by `can`.
+     */
+    condition?: string;
+}
+/** The type of an attribute a condition may read: `list` is any JSON array. */
+type AttributeType = 'string' | 'number' | 'bool' | 'list';
+/** A resource of a system's catalog: the actions done on it and the attributes its conditions read. */
+interface CatalogResource {
+    resource: string;
+    description?: string;
+    actions: string[];
+    /** Name → type, as `resource.attrs.<name>` in a condition. */
+    attributes?: Record<string, AttributeType>;
 }
 interface PolicyRole {
     role: string;
@@ -110,17 +132,28 @@ interface PolicyRole {
     inherits?: string[];
     permissions?: PolicyPermission[];
 }
+type PermissionShape = {
+    readonly kind?: string;
+    readonly resource: string;
+    readonly action: string;
+    readonly condition?: string;
+};
 /** 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;
-    }[];
+    readonly permissions?: readonly PermissionShape[];
+};
+/** A resource as `definePolicy` reads it: any `CatalogResource`, kept as written. */
+type ResourceShape = {
+    readonly resource: string;
+    readonly description?: string;
+    readonly actions: readonly string[];
+    readonly attributes?: {
+        readonly [name: string]: AttributeType;
+    };
 };
 type Named<S extends string> = S extends '*' ? string : S;
 type PermissionsIn<R> = R extends {
@@ -129,13 +162,56 @@ type PermissionsIn<R> = R extends {
     readonly resource: infer Res extends string;
     readonly action: infer Act extends string;
 } ? `${Named<Res>}:${Named<Act>}` : never : never;
+type ValueOf<T> = T extends 'string' ? string : T extends 'number' ? number : T extends 'bool' ? boolean : T extends 'list' ? unknown[] : never;
+/** What a check may say about one declared resource. */
+type QuestionAbout<E> = E extends {
+    readonly resource: infer R extends string;
+    readonly actions: readonly (infer A extends string)[];
+} ? {
+    resource: R;
+    action: A;
+    attributes?: E extends {
+        readonly attributes: infer T;
+    } ? {
+        [K in keyof T]?: ValueOf<T[K]>;
+    } : Record<string, never>;
+    resourceId?: string;
+    ownerId?: string;
+} : never;
+/**
+ * What a role of a catalog that declares its resources may name: a declared
+ * resource with one of its actions, or "*", or one of Cauthy's own powers.
+ */
+type PermissionFor<C extends readonly ResourceShape[]> = {
+    readonly kind?: string;
+    readonly condition?: string;
+} & ((C[number] extends infer E ? E extends {
+    readonly resource: infer R extends string;
+    readonly actions: readonly (infer A extends string)[];
+} ? {
+    readonly resource: R;
+    readonly action: A | '*';
+} : never : never) | {
+    readonly resource: '*';
+    readonly action: string;
+} | {
+    readonly resource: `cauthy:${string}`;
+    readonly action: string;
+});
+type RoleFor<C extends readonly ResourceShape[]> = Omit<RoleShape, 'permissions'> & {
+    readonly permissions?: readonly PermissionFor<C>[];
+};
 /** The roles a catalog names: `RoleOf<typeof policy>`. */
-type RoleOf<P> = P extends Policy<infer R, string> ? R : never;
+type RoleOf<P> = P extends Policy<infer R, any, any> ? 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> {
+type PermissionOf<P> = P extends Policy<any, infer X, any> ? X : never;
+/** The fields of a question: whatever else the asker takes (the organization, the person) passes through. */
+type QuestionKeys = keyof CheckQuestion;
+interface Policy<Role extends string = string, Permission extends string = string, Question extends CheckQuestion = CheckQuestion> {
     /** The catalog as Cauthy takes it: `pushPolicy({ roles: policy.roles })`. */
     roles: PolicyRole[];
+    /** The resources the system declares, as Cauthy takes them; empty when it declares none. */
+    catalog: CatalogResource[];
     /** Every role's name. */
     roleNames: Role[];
     /** Every permission some role has, as "resource:action". */
@@ -143,7 +219,8 @@ interface Policy<Role extends string = string, Permission extends string = strin
     /**
      * 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.
+     * since this file was written is still what decides. A permission with a
+     * condition is not there: ask with `check`.
      */
     can(organization: Permitted | null | undefined, permission: Permission): boolean;
     /** Whether the person's role in the organization is one of these. */
@@ -155,9 +232,30 @@ interface Policy<Role extends string = string, Permission extends string = strin
      * role, never for deciding about a person (their exceptions are not here).
      */
     permissionsOf(role: Role): Permission[];
+    /**
+     * Asks Cauthy, with the resource, action and attributes typed by the
+     * catalog. Give it whoever asks: the server's `auth` with the request,
+     * the browser's `organizations`, or the application's `system`.
+     *
+     *   await policy.check(auth, request, { organization, resource: 'invoices', action: 'approve', attributes: { amount: 500 } })
+     *   await policy.check(auth.system, { organizationId, userId, resource: 'invoices', action: 'read' })
+     */
+    check<I extends CheckQuestion>(asker: {
+        check(input: I): Promise<CheckResult>;
+    }, input: Omit<I, QuestionKeys> & Question): Promise<CheckResult>;
+    check<R, I extends CheckQuestion>(asker: {
+        check(request: R, input: I): Promise<CheckResult>;
+    }, request: R, input: Omit<I, QuestionKeys> & Question): Promise<CheckResult>;
+}
+/** A catalog with its resources declared, for `definePolicy`. */
+interface PolicyDefinition<C extends readonly ResourceShape[], T extends readonly RoleShape[]> {
+    catalog: C;
+    roles: T;
 }
 /** 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]>>;
+/** Gives a catalog of resources and roles its types: a role names only what the catalog declares. */
+declare function definePolicy<const C extends readonly ResourceShape[], const T extends readonly RoleFor<C>[]>(definition: PolicyDefinition<C, T>): Policy<T[number]['role'], PermissionsIn<T[number]>, QuestionAbout<C[number]>>;
 
 /** The person signed in. Every moment is UTC. */
 interface SessionUser {
@@ -200,6 +298,54 @@ interface SessionOrganization {
     permissions?: string[];
     /** What the person is denied here, whatever else allows it. */
     denied?: string[];
+    /**
+     * Permissions that hold only when their condition does (an amount under a
+     * limit, the person's own records…). They are in neither list above: `can`
+     * answers no for them, and `auth.check` asks Cauthy. Present, maybe empty,
+     * whenever `permissions` is.
+     */
+    conditional?: ConditionalPermission[];
+}
+/** A permission with a condition: Cauthy decides it per question (`auth.check`). */
+interface ConditionalPermission {
+    resource: string;
+    action: string;
+    effect: 'allow' | 'deny';
+}
+/** What to ask Cauthy about: an action on a resource, with what the conditions read of it. */
+interface CheckQuestion {
+    resource: string;
+    action: string;
+    /** What a condition reads as `resource.attrs`: `{ amount: 500 }`. */
+    attributes?: Record<string, unknown>;
+    /** The record's id, as a condition reads it (`resource.id`). */
+    resourceId?: string;
+    /** Whose the record is (`resource.owner_id`): `resource.owner_id == subject.id`. */
+    ownerId?: string;
+}
+/** An organization, by its id or as the session has it. */
+type OrganizationRef = string | {
+    id: string;
+};
+/** The rule that decided a check. */
+interface CheckRule {
+    /** A permission of the person's role, or an exception given to the person. */
+    source: 'role' | 'exception';
+    /** The role, when `source` is `role`. */
+    role?: string;
+    kind: string;
+    resource: string;
+    action: string;
+    effect: 'allow' | 'deny';
+    condition?: string;
+}
+/** Cauthy's answer to a check. */
+interface CheckResult {
+    allowed: boolean;
+    /** Why, in words: "allowed by role accountant: invoices:approve". */
+    reason: string;
+    /** The rule that decided; absent when none did (nothing allows it). */
+    rule?: CheckRule;
 }
 /** What the browser is told of a session: who, and their organizations — never a token. */
 interface PublicSession {
@@ -257,11 +403,25 @@ type AuthResult<S extends string, More = unknown> = ({
 };
 /** What the screen may offer. */
 interface AuthMethods {
-    /** The providers the workspace signs people in with: `{ id: 'google', name: 'Google' }`. */
+    /**
+     * The providers the workspace signs people in with and has turned on:
+     * `{ id: 'google', name: 'Google', iconUrl: 'https://…/v1/social/icons/google.svg' }`.
+     * `iconUrl` is the provider's logo, served by Cauthy; absent from a Cauthy
+     * that does not serve logos.
+     */
     providers: {
         id: string;
         name: string;
+        iconUrl?: string;
     }[];
+    /**
+     * Whether the workspace signs people in with a password. False: the
+     * password field, "forgot your password" and a sign-up with a password are
+     * not offered, and Cauthy refuses them (`password_disabled`). True from a
+     * server that does not say. (`password` is something else: the policy a new
+     * password must meet.)
+     */
+    passwordSignIn: boolean;
     /** Whether people may create an account themselves. */
     signUp: boolean;
     /** Set when the application's system makes an organization per sign-up: the form asks the company's name. */
@@ -270,7 +430,7 @@ interface AuthMethods {
         required: boolean;
     };
     magicLink: boolean;
-    /** Whether to offer a passkey. */
+    /** Whether to offer a passkey. False when the workspace turned passkeys off. */
     passkey: boolean;
     /**
      * Whether the passkey is used on this page itself. False: `signIn.passkey`
@@ -322,6 +482,15 @@ interface AuthMethods {
      */
     password?: PasswordPolicy;
 }
+/** An invitation, as its page shows it before the person chooses a password. */
+interface Invitation {
+    /** The address invited: the account the person signs in as. */
+    email: string;
+    /** The workspace's name. */
+    workspace: string;
+    /** The organization the person was invited to, when there is one. */
+    organization?: string;
+}
 /** A legal document the person owes: not yet accepted in its current version. */
 interface PendingLegal {
     kind: string;
@@ -385,19 +554,29 @@ interface ConnectedAgent {
     connectedAt: string;
     lastUsedAt: string;
 }
-/** An organization the person belongs to, with what their role lets them do with its people. */
+/** An organization the person belongs to, with what their role lets them do with it and its people. */
 interface OrganizationSeat {
     id: string;
-    /** The client system it is of (`pondari`). */
+    /** The client system it is of (`acme-crm`). */
     system: string;
     name: string;
     kind: string;
     /** The person's role in it. */
     role: string;
-    /** Cauthy's member powers, from the system's catalog: cauthy:members read and manage. */
+    /**
+     * Cauthy's reserved powers, from the system's catalog. `manageMembers`
+     * (cauthy:members:manage) adds, invites and changes roles; removing another
+     * member is `removeMembers` (cauthy:members:remove), and anybody may leave.
+     * `update`, `archive` and `delete` are cauthy:organization's: rename it,
+     * archive it, delete it for good.
+     */
     can: {
         readMembers: boolean;
         manageMembers: boolean;
+        removeMembers: boolean;
+        update: boolean;
+        archive: boolean;
+        delete: boolean;
     };
 }
 /** A person of an organization, as a member who may see them reads it. */
@@ -427,8 +606,12 @@ interface OrganizationRoleChoice {
 }
 /**
  * The signed-in person's organizations, and their people. Seeing them needs
- * cauthy:members read in the person's role; changing them needs manage. Cauthy
- * decides, with the person's own session: the application authorizes nothing.
+ * cauthy:members read in the person's role; changing them needs manage, and
+ * removing someone needs remove. The organization itself is renamed, archived
+ * or deleted with cauthy:organization update, archive or delete. Only an
+ * `owner` gives the owner role or changes an owner, and the last owner stays
+ * (`last_owner`). Cauthy decides, with the person's own session: the
+ * application authorizes nothing.
  */
 interface OrganizationsClient {
     /** The organizations the person belongs to; one system's only with `system`. */
@@ -460,6 +643,31 @@ interface OrganizationsClient {
     }): Promise<AuthResult<'sent', {
         userId: string;
     }>>;
+    /** Gives the organization a new name (cauthy:organization update). */
+    rename(organizationId: string, name: string): Promise<AuthResult<'renamed', {
+        organization: OrganizationSeat;
+    }>>;
+    /** Archives the organization: its members no longer reach it, and only the workspace restores it. */
+    archive(organizationId: string): Promise<AuthResult<'archived', {
+        organizationId: string;
+    }>>;
+    /** Deletes the organization for good. */
+    delete(organizationId: string): Promise<AuthResult<'deleted', {
+        organizationId: string;
+    }>>;
+    /**
+     * Asks Cauthy, through the application's server, whether the person may do
+     * an action on a resource in the organization, with what its conditions
+     * read. A question that could not be asked is a no, with `error` saying why.
+     *
+     *   const r = await organizations.check({ organization, resource: 'invoices', action: 'approve', attributes: { amount: 500 } })
+     *   if (r.allowed) showApprove()
+     */
+    check(question: CheckQuestion & {
+        organization: OrganizationRef;
+    }): Promise<CheckResult & {
+        error?: AuthError;
+    }>;
 }
 interface AccountSession {
     /** "Mac · Chrome", or "" when the browser did not say. */
@@ -874,7 +1082,25 @@ interface AuthClient {
         token: string;
         password: string;
     }): Promise<AuthResult<'changed'>>;
-    /** Confirms the address, with the token the mailed link opened the page with (`token`). */
+    /**
+     * Who an invitation is for and to what, with the token the mailed link
+     * opened the page with (`token`). Reading it does not spend it.
+     * `invalid_token`: unknown, spent or expired.
+     */
+    invitation(token: string): Promise<AuthResult<'ok', {
+        invitation: Invitation;
+    }>>;
+    /**
+     * Accepts an invitation with the password the person chose (the workspace's
+     * policy, as for a sign-up) and signs them in. `mfa_required`: the account
+     * owes a second step; ask for the code and call `signIn.mfa`, as after
+     * `signIn.email`. A password refused leaves the invitation good.
+     */
+    acceptInvitation(token: string, password: string): Promise<AuthResult<'signed_in', {
+        session: PublicSession;
+    }> | AuthResult<'mfa_required', {
+        method?: 'email';
+    }>>;
     /** Confirms the address a mailed link is for. The person is signed in from the link when their account asks no second step. */
     verifyEmail(form: {
         token: string;
@@ -966,6 +1192,13 @@ interface AuthTexts {
     passwordChanged: string;
     confirming: string;
     emailConfirmed: string;
+    invitedTo: string;
+    invitedToOrganization: string;
+    invitedAs: string;
+    choosePassword: string;
+    acceptInvite: string;
+    openingInvitation: string;
+    invitationInvalid: string;
     profile: string;
     save: string;
     saved: string;
@@ -1027,12 +1260,21 @@ interface AuthTexts {
     memberLeaveConfirm: string;
     memberInviteAgain: string;
     memberInvitationSent: string;
+    organization: string;
+    organizationRename: string;
+    organizationRenamed: string;
+    organizationArchive: string;
+    organizationArchiveConfirm: string;
+    organizationArchived: string;
+    organizationDelete: string;
+    organizationDeleteConfirm: string;
+    organizationDeleted: string;
     yes: string;
     cancel: 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' | 'hint' | 'notice' | 'separator' | 'footer' | 'check' | 'account' | 'section' | 'heading' | 'secret' | 'codes' | 'sessions' | 'session';
+type Slot = 'form' | 'field' | 'label' | 'input' | 'button' | 'providerButton' | 'providerIcon' | 'link' | 'error' | 'fieldError' | 'hint' | 'notice' | 'separator' | 'footer' | 'check' | 'account' | 'section' | 'heading' | 'secret' | 'codes' | 'sessions' | 'session';
 interface AuthFormProps {
     /** The language of the built-in sentences. Default: `en`. */
     locale?: 'en' | 'es';
@@ -1122,6 +1364,14 @@ declare function ForgotPassword(props: AuthFormProps): react.JSX.Element;
 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;
+/**
+ * The page an invitation opens: `pages.acceptInvite`. It says who is invited
+ * to what, asks for a password under the workspace's policy, signs the person
+ * in (with the second step, when their account owes one) and goes on to
+ * `returnTo`. The invitation is good until it is accepted: reading it, or a
+ * password refused, does not spend it.
+ */
+declare function AcceptInvite(props: AuthFormProps): react.JSX.Element;
 interface AccountProps extends Omit<AuthFormProps, 'links' | 'returnTo' | 'onSuccess'> {
     /** Called after "sign out everywhere". Default: go to `/`. */
     onSignedOut?: () => void;
@@ -1144,10 +1394,12 @@ interface OrganizationMembersProps extends Omit<AuthFormProps, 'links' | 'return
  * The people of one of the signed-in person's organizations, administered
  * from the application. What it offers follows the person's role in the
  * system's catalog: cauthy:members read lists the people; manage adds them by
- * address (one with no account is invited), changes their role, sends an
- * invitation again and removes them. Anybody may leave. Cauthy checks each
- * change with the person's own session; the application authorizes nothing.
- * Like the other forms, it carries no styles.
+ * address (one with no account is invited), changes their role and sends an
+ * invitation again; remove removes them. Anybody may leave. Only an owner
+ * gives the owner role or changes an owner. cauthy:organization update,
+ * archive and delete rename the organization, archive it, delete it. Cauthy
+ * checks each change with the person's own session; the application
+ * authorizes nothing. Like the other forms, it carries no styles.
  */
 declare function OrganizationMembers(props: OrganizationMembersProps): react.JSX.Element;
 
@@ -1194,4 +1446,4 @@ declare function useSession(): SessionContext;
  */
 declare function useAuth(): AuthClient & Pick<SessionContext, 'session' | 'status' | 'refresh'>;
 
-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, type ConnectedAgent, ForgotPassword, GoogleOneTap, type GoogleOneTapProps, type JsonValue, type LinkedIdentity, OrganizationMembers, type OrganizationMembersProps, type OrganizationPerson, type OrganizationRoleChoice, type OrganizationSeat, type OrganizationsClient, type Passkey, type PasskeyKind, type PermissionOf, type Policy, type PublicSession, ResetPassword, type RoleOf, type SSOConnection, type SecondStep, type SessionContext, type SessionOrganization, type SessionUser, SignIn, SignUp, VerifyEmail, can, canAutofillPasskeys, canUsePasskeys, createAuthClient, definePolicy, useAuth, useSession };
+export { AcceptInvite, 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, type ConnectedAgent, ForgotPassword, GoogleOneTap, type GoogleOneTapProps, type Invitation, type JsonValue, type LinkedIdentity, OrganizationMembers, type OrganizationMembersProps, type OrganizationPerson, type OrganizationRoleChoice, type OrganizationSeat, type OrganizationsClient, type Passkey, type PasskeyKind, type PermissionOf, type Policy, type PublicSession, ResetPassword, type RoleOf, type SSOConnection, type SecondStep, type SessionContext, type SessionOrganization, type SessionUser, SignIn, SignUp, VerifyEmail, can, canAutofillPasskeys, canUsePasskeys, createAuthClient, definePolicy, useAuth, useSession };