cauthy-auth 0.28.1 → 0.30.0

package/dist/next.d.mts

@@ -1,5 +1,5 @@
-import { C as Cauthy } from './cauthy-CTVg4kvo.mjs';
-import { S as Session } from './system-CVBW_AV8.mjs';
+import { C as Cauthy } from './cauthy-BXgsZ-Um.mjs';
+import { S as Session } from './system-0mHrdAgO.mjs';
 import 'jose';
 import './theme.mjs';
 

package/dist/next.d.ts

@@ -1,5 +1,5 @@
-import { C as Cauthy } from './cauthy-BAwAJChs.js';
-import { S as Session } from './system-Bn8uckvQ.js';
+import { C as Cauthy } from './cauthy-CHENs452.js';
+import { S as Session } from './system-BIYbS7h2.js';
 import 'jose';
 import './theme.js';
 

package/dist/react.d.mts

@@ -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 {
@@ -385,19 +531,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 +583,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 +620,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. */
@@ -1027,6 +1212,15 @@ 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. */
@@ -1144,10 +1338,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;