cauthy-auth 0.28.0 → 0.30.0

package/README.md

@@ -12,7 +12,7 @@ npm install cauthy-auth
 ```
 
 ```ts
-// auth.ts — reads CAUTHY_ISSUER, CAUTHY_CLIENT_ID, CAUTHY_SECRET (and CAUTHY_SYSTEM)
+// auth.ts — reads CAUTHY_ISSUER, CAUTHY_CLIENT_ID, CAUTHY_SECRET (and CAUTHY_SYSTEM, CAUTHY_BASE_URL)
 import { createCauthy } from 'cauthy-auth'
 export const auth = createCauthy()
 ```
@@ -64,6 +64,33 @@ import { Account } from 'cauthy-auth/react'
 <Account />                                  // or: const { account } = useAuth()
 ```
 
+And the person's organizations, run by their own members: the people of one, and the organization itself. Cauthy decides each change by the person's role in the system's catalog, with their own session:
+
+```tsx
+import { OrganizationMembers } from 'cauthy-auth/react'
+<OrganizationMembers organizationId={org.id} />   // shows only what the person's role allows
+
+const { organizations } = useAuth()
+const [org] = await organizations.list()         // org.can: { readMembers, manageMembers, removeMembers, update, archive, delete }
+await organizations.add(org.id, { email: 'ana@example.com', role: 'reader' })
+await organizations.setRole(org.id, userId, 'admin')
+await organizations.remove(org.id, userId)        // anybody may remove themselves: leave
+await organizations.rename(org.id, 'Acme Books')  // r.organization
+await organizations.archive(org.id)               // only the workspace restores it
+await organizations.delete(org.id)                // for good
+```
+
+| Reserved power | Lets a member |
+| --- | --- |
+| `cauthy:members:read` | see the people (`can.readMembers`) |
+| `cauthy:members:manage` | add and invite people, change their role (`can.manageMembers`) |
+| `cauthy:members:remove` | remove another member (`can.removeMembers`) |
+| `cauthy:organization:update` | rename the organization (`can.update`) |
+| `cauthy:organization:archive` | archive it (`can.archive`) |
+| `cauthy:organization:delete` | delete it for good (`can.delete`) |
+
+Every catalog has a reserved role, `owner`, with all of them. Only an owner gives the owner role, or changes or removes another owner, and an organization always keeps one: its last owner cannot be removed, demoted or leave (`last_owner`). On the server they read like any other permission: `can(organization, 'cauthy:organization', 'delete')`.
+
 Roles and permissions with their names, from the catalog Cauthy has:
 
 ```bash
@@ -75,6 +102,30 @@ import { can, hasRole } from './policy'
 can(organization, 'ledger:write')            // only what the catalog names compiles
 ```
 
+A system may also declare its resources: their actions, and the attributes a condition reads. A permission may then carry a condition, in CEL (`resource.attrs.amount <= 1000000`, `resource.owner_id == subject.id`). Such a permission is not in `permissions`: it comes in `organization.conditional`, `can` never counts it, and Cauthy decides it per question:
+
+```ts
+const r = await auth.check(request, { organization, resource: 'invoices', action: 'approve', attributes: { amount: 500 } })
+r.allowed, r.reason, r.rule                  // rule: which role or exception decided
+
+await organizations.check({ organization, resource: 'invoices', action: 'approve', attributes: { amount: 500 } })  // in the browser
+await auth.system.check({ organizationId, userId, resource: 'invoices', action: 'read' })                          // about any member
+```
+
+`--pull` writes the declared resources too, and a check is typed by them:
+
+```ts
+export const policy = definePolicy({
+  catalog: [{ resource: 'invoices', actions: ['read', 'approve'], attributes: { amount: 'number', branch: 'string' } }],
+  roles: [{ role: 'accountant', permissions: [{ resource: 'invoices', action: 'approve', condition: 'resource.attrs.amount <= 1000000' }] }],
+})
+
+await policy.check(auth, request, { organization, resource: 'invoices', action: 'approve', attributes: { amount: 500 } })
+// 'payroll', action 'delete' or amount: '500' do not compile
+```
+
+`npx cauthy-auth policy --file policy.json --push` loads a first catalog: a list of roles, or `{ "catalog": [...], "roles": [...] }`, whose resources go first so the roles are checked against them. Pushing takes a personal access token with `systems:policy`.
+
 Each framework has its own few lines:
 
 | | |

package/dist/{cauthy-XkIbG5gE.d.mts → cauthy-BXgsZ-Um.d.mts}

@@ -1,4 +1,4 @@
-import { J as JsonValue, S as Session, l as SessionStatus, k as SessionOrganization, c as CauthySystem, i as PublicSession, b as CauthyOptions } from './system-BxMsSIu1.mjs';
+import { J as JsonValue, S as Session, t as SessionStatus, s as SessionOrganization, f as CheckQuestion, k as OrganizationRef, g as CheckResult, d as CauthySystem, q as PublicSession, c as CauthyOptions } from './system-0mHrdAgO.mjs';
 import { JWTVerifyGetKey } from 'jose';
 
 /** Something that happened in Cauthy, as a subscriber is told. Moments are UTC. */
@@ -80,6 +80,24 @@ interface Cauthy {
     }>;
     /** The organizations the person belongs to (of `system`, when set), with their role in each. */
     organizations(session: Session): Promise<SessionOrganization[]>;
+    /**
+     * Asks Cauthy whether the signed-in person may do an action on a resource
+     * in an organization, with what its conditions read (`attributes`, whose
+     * the record is). It is how a permission with a condition is decided —
+     * `can` never counts those — and it decides any other the same way.
+     *
+     *   const r = await auth.check(request, { organization, resource: 'invoices', action: 'approve', attributes: { amount: 500 } })
+     *   if (!r.allowed) return forbidden(r.reason)
+     *
+     * Nobody signed in, an organization the person is not in, or a disabled
+     * account answer `allowed: false`. A request whose session must be renewed
+     * first reads as nobody signed in: give it the `Session` from
+     * `getSession(request, responseHeaders)` instead. Throws `CauthyApiError`
+     * when Cauthy refuses the question itself (a malformed one) or cannot be reached.
+     */
+    check(who: Request | Session, question: CheckQuestion & {
+        organization: OrganizationRef;
+    }): Promise<CheckResult>;
     /**
      * Verifies a webhook delivery from Cauthy and answers the event it carries;
      * throws `CauthyWebhookError` for anything else. No secret is involved: the

package/dist/{cauthy-DGAy45G2.d.ts → cauthy-CHENs452.d.ts}

@@ -1,4 +1,4 @@
-import { J as JsonValue, S as Session, l as SessionStatus, k as SessionOrganization, c as CauthySystem, i as PublicSession, b as CauthyOptions } from './system-DTIeDXDP.js';
+import { J as JsonValue, S as Session, t as SessionStatus, s as SessionOrganization, f as CheckQuestion, k as OrganizationRef, g as CheckResult, d as CauthySystem, q as PublicSession, c as CauthyOptions } from './system-BIYbS7h2.js';
 import { JWTVerifyGetKey } from 'jose';
 
 /** Something that happened in Cauthy, as a subscriber is told. Moments are UTC. */
@@ -80,6 +80,24 @@ interface Cauthy {
     }>;
     /** The organizations the person belongs to (of `system`, when set), with their role in each. */
     organizations(session: Session): Promise<SessionOrganization[]>;
+    /**
+     * Asks Cauthy whether the signed-in person may do an action on a resource
+     * in an organization, with what its conditions read (`attributes`, whose
+     * the record is). It is how a permission with a condition is decided —
+     * `can` never counts those — and it decides any other the same way.
+     *
+     *   const r = await auth.check(request, { organization, resource: 'invoices', action: 'approve', attributes: { amount: 500 } })
+     *   if (!r.allowed) return forbidden(r.reason)
+     *
+     * Nobody signed in, an organization the person is not in, or a disabled
+     * account answer `allowed: false`. A request whose session must be renewed
+     * first reads as nobody signed in: give it the `Session` from
+     * `getSession(request, responseHeaders)` instead. Throws `CauthyApiError`
+     * when Cauthy refuses the question itself (a malformed one) or cannot be reached.
+     */
+    check(who: Request | Session, question: CheckQuestion & {
+        organization: OrganizationRef;
+    }): Promise<CheckResult>;
     /**
      * Verifies a webhook delivery from Cauthy and answers the event it carries;
      * throws `CauthyWebhookError` for anything else. No secret is involved: the

package/dist/cli.js

@@ -368,73 +368,147 @@ ${declaration}() {
 
 // src/permissions.ts
 var IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
-function policySource(system, roles) {
+function policySource(system, read) {
+  const roles = Array.isArray(read) ? read : read.roles;
+  const catalog = Array.isArray(read) ? [] : read.catalog ?? [];
   const text = (v) => JSON.stringify(v);
   const key = (k) => IDENT.test(k) ? k : text(k);
-  const one = (r) => {
+  const one = (r, pad) => {
     const parts = [`role: ${text(r.role)}`];
     if (r.name) parts.push(`name: ${text(r.name)}`);
     if (r.description) parts.push(`description: ${text(r.description)}`);
     if (r.inherits?.length) parts.push(`inherits: [${r.inherits.map(text).join(", ")}]`);
     if (r.permissions?.length) {
-      const list = r.permissions.map((p) => `      { ${[...p.kind && p.kind !== "*" ? [`${key("kind")}: ${text(p.kind)}`] : [], `resource: ${text(p.resource)}`, `action: ${text(p.action)}`].join(", ")} },`);
+      const list = r.permissions.map((p) => `${pad}      { ${[
+        ...p.kind && p.kind !== "*" ? [`${key("kind")}: ${text(p.kind)}`] : [],
+        `resource: ${text(p.resource)}`,
+        `action: ${text(p.action)}`,
+        ...p.condition ? [`condition: ${text(p.condition)}`] : []
+      ].join(", ")} },`);
       parts.push(`permissions: [
 ${list.join("\n")}
-    ]`);
+${pad}    ]`);
     }
-    return `  {
-    ${parts.join(",\n    ")},
-  },`;
+    return `${pad}  {
+${pad}    ${parts.join(`,
+${pad}    `)},
+${pad}  },`;
   };
-  return `// The catalog of roles of ${text(system)}, as Cauthy has it.
+  const resource = (c) => {
+    const parts = [`resource: ${text(c.resource)}`];
+    if (c.description) parts.push(`description: ${text(c.description)}`);
+    parts.push(`actions: [${c.actions.map(text).join(", ")}]`);
+    const attrs = Object.entries(c.attributes ?? {});
+    if (attrs.length) parts.push(`attributes: { ${attrs.map(([k, v]) => `${key(k)}: ${text(v)}`).join(", ")} }`);
+    return `    { ${parts.join(", ")} },`;
+  };
+  const head = `// The catalog of roles of ${text(system)}, as Cauthy has it.
 // Written by \`cauthy-auth policy --pull\`: run it again after the catalog
 // changes, and do not edit this file by hand.
-
+`;
+  if (catalog.length === 0) {
+    return `${head}
 import { definePolicy, type PermissionOf, type RoleOf } from 'cauthy-auth'
 
 export const policy = definePolicy([
-${roles.map(one).join("\n")}
+${roles.map((r) => one(r, "")).join("\n")}
 ])
 
 export const { can, hasRole } = policy
 export type Role = RoleOf<typeof policy>
 export type Permission = PermissionOf<typeof policy>
 `;
-}
-async function pullPolicy(o = {}) {
-  const env2 = (n) => typeof process !== "undefined" ? process.env?.[n] : void 0;
-  const issuer = withoutTrailingSlashes(o.issuer ?? env2("CAUTHY_ISSUER") ?? "");
-  const system = o.system ?? env2("CAUTHY_SYSTEM") ?? "";
-  const tenant = o.tenant ?? env2("CAUTHY_TENANT") ?? "";
-  const token = o.token ?? env2("CAUTHY_TOKEN") ?? "";
-  for (const [name, v] of Object.entries({ CAUTHY_ISSUER: issuer, CAUTHY_SYSTEM: system, CAUTHY_TENANT: tenant, CAUTHY_TOKEN: token })) {
-    if (v === "") throw new Error(`cauthy-auth: ${name} is required to read a policy`);
   }
-  const res = await (o.fetch ?? fetch)(`${issuer}/v1/systems/${encodeURIComponent(system)}/policy`, {
-    headers: { authorization: `Bearer ${token}`, "x-tenant-key": tenant, accept: "application/json" }
-  });
-  const body = await res.json().catch(() => null);
-  if (!res.ok) throw new Error(`cauthy-auth: Cauthy refused to give the policy (${res.status}): ${body?.errors?.[0]?.message ?? res.statusText}`);
-  return body?.data?.roles ?? [];
+  return `${head}
+import { definePolicy, type CheckOf, type PermissionOf, type RoleOf } from 'cauthy-auth'
+
+export const policy = definePolicy({
+  catalog: [
+${catalog.map(resource).join("\n")}
+  ],
+  roles: [
+${roles.map((r) => one(r, "  ")).join("\n")}
+  ],
+})
+
+export const { can, hasRole } = policy
+export type Role = RoleOf<typeof policy>
+export type Permission = PermissionOf<typeof policy>
+/** What a check may ask: \`policy.check(auth, request, { organization, ...question })\`. */
+export type Check = CheckOf<typeof policy>
+`;
 }
-async function pushPolicy(o) {
+function reach(o, doing) {
   const env2 = (n) => typeof process !== "undefined" ? process.env?.[n] : void 0;
-  const issuer = withoutTrailingSlashes(o.issuer ?? env2("CAUTHY_ISSUER") ?? "");
-  const system = o.system ?? env2("CAUTHY_SYSTEM") ?? "";
-  const tenant = o.tenant ?? env2("CAUTHY_TENANT") ?? "";
-  const token = o.token ?? env2("CAUTHY_TOKEN") ?? "";
-  for (const [name, v] of Object.entries({ CAUTHY_ISSUER: issuer, CAUTHY_SYSTEM: system, CAUTHY_TENANT: tenant, CAUTHY_TOKEN: token })) {
-    if (v === "") throw new Error(`cauthy-auth: ${name} is required to push a policy`);
+  const r = {
+    issuer: withoutTrailingSlashes(o.issuer ?? env2("CAUTHY_ISSUER") ?? ""),
+    system: o.system ?? env2("CAUTHY_SYSTEM") ?? "",
+    tenant: o.tenant ?? env2("CAUTHY_TENANT") ?? "",
+    token: o.token ?? env2("CAUTHY_TOKEN") ?? ""
+  };
+  for (const [name, v] of Object.entries({ CAUTHY_ISSUER: r.issuer, CAUTHY_SYSTEM: r.system, CAUTHY_TENANT: r.tenant, CAUTHY_TOKEN: r.token })) {
+    if (v === "") throw new Error(`cauthy-auth: ${name} is required to ${doing}`);
   }
-  const res = await (o.fetch ?? fetch)(`${issuer}/v1/systems/${encodeURIComponent(system)}/policy`, {
-    method: "PUT",
-    headers: { authorization: `Bearer ${token}`, "x-tenant-key": tenant, "content-type": "application/json" },
-    body: JSON.stringify({ roles: o.roles })
+  return { ...r, fetch: o.fetch ?? fetch };
+}
+async function systemCall(r, method, what, body) {
+  const res = await r.fetch(`${r.issuer}/v1/systems/${encodeURIComponent(r.system)}/${what}`, {
+    ...method === "PUT" ? { method } : {},
+    headers: {
+      authorization: `Bearer ${r.token}`,
+      "x-tenant-key": r.tenant,
+      ...body === void 0 ? { accept: "application/json" } : { "content-type": "application/json" }
+    },
+    ...body === void 0 ? {} : { body: JSON.stringify(body) }
   });
+  const answer = await res.json().catch(() => null);
   if (!res.ok) {
-    const body = await res.json().catch(() => null);
-    throw new Error(`cauthy-auth: Cauthy refused the policy (${res.status}): ${body?.errors?.[0]?.message ?? res.statusText}`);
+    const verb = method === "GET" ? `refused to give the ${what}` : `refused the ${what}`;
+    throw new Error(`cauthy-auth: Cauthy ${verb} (${res.status}): ${answer?.errors?.[0]?.message ?? res.statusText}`);
   }
+  return answer?.data;
+}
+async function pullPolicy(o = {}) {
+  const data = await systemCall(reach(o, "read a policy"), "GET", "policy");
+  return data?.roles ?? [];
+}
+async function pullCatalog(o = {}) {
+  const data = await systemCall(reach(o, "read a catalog"), "GET", "catalog");
+  return data?.resources ?? [];
+}
+async function pushPolicy(o) {
+  const r = reach(o, "push a policy");
+  if (o.catalog !== void 0) await systemCall(r, "PUT", "catalog", { resources: o.catalog });
+  await systemCall(r, "PUT", "policy", { roles: o.roles });
+}
+function readPolicyFile(parsed) {
+  if (Array.isArray(parsed)) return { catalog: [], roles: parsed };
+  const o = parsed ?? {};
+  if (!Array.isArray(o.roles)) throw new Error('no "roles" list');
+  if (o.catalog !== void 0 && !Array.isArray(o.catalog)) throw new Error('"catalog" is not a list');
+  return { catalog: o.catalog ?? [], roles: o.roles };
+}
+function checkWire(q) {
+  return {
+    resource: q.resource,
+    action: q.action,
+    ...q.resourceId !== void 0 ? { resource_id: q.resourceId } : {},
+    ...q.ownerId !== void 0 ? { owner_id: q.ownerId } : {},
+    ...q.attributes !== void 0 ? { attributes: q.attributes } : {}
+  };
+}
+function checkResultOf(d) {
+  const r = d?.rule;
+  const rule = r && typeof r === "object" ? {
+    source: r.source === "exception" ? "exception" : "role",
+    ...r.role ? { role: String(r.role) } : {},
+    kind: String(r.kind ?? "*"),
+    resource: String(r.resource ?? ""),
+    action: String(r.action ?? ""),
+    effect: r.effect === "allow" ? "allow" : "deny",
+    ...r.condition ? { condition: String(r.condition) } : {}
+  } : void 0;
+  return { allowed: d?.allowed === true, reason: String(d?.reason ?? ""), ...rule ? { rule } : {} };
 }
 
 // src/system.ts
@@ -914,6 +988,7 @@ function createSystem(given = {}) {
   const clientSecret = given.clientSecret ?? env("CAUTHY_CLIENT_SECRET") ?? "";
   const envKey = env("CAUTHY_SYSTEM_KEY");
   const key = given.key ?? (envKey ? { privateKey: envKey, keyId: env("CAUTHY_SYSTEM_KEY_ID") ?? "" } : void 0);
+  const ownSystem = given.system ?? env("CAUTHY_SYSTEM") ?? "";
   const doFetch = (...args) => (given.fetch ?? fetch)(...args);
   const tokenEndpoint = `${issuer}/v1/oauth/token`;
   function configured() {
@@ -1031,6 +1106,19 @@ function createSystem(given = {}) {
         return (await data("GET", `/v1/systems/${id(system)}/policy`)).roles ?? [];
       }
     },
+    catalog: {
+      async get(system) {
+        return (await data("GET", `/v1/systems/${id(system)}/catalog`)).resources ?? [];
+      },
+      async set(system, resources) {
+        return (await data("PUT", `/v1/systems/${id(system)}/catalog`, { resources })).resources ?? [];
+      }
+    },
+    async check(q) {
+      const system = q.system ?? ownSystem;
+      if (system === "") throw new CauthyConfigError("name the system to check in (system, or CAUTHY_SYSTEM)");
+      return checkResultOf(await data("POST", `/v1/systems/${id(system)}/check`, { organization_id: q.organizationId, user_id: q.userId, ...checkWire(q) }));
+    },
     async publicJwks() {
       if (!key) return { keys: [] };
       const { kty, n, e } = asJwk(key) ?? await (0, import_jose.exportJWK)(await signingKey());
@@ -1194,10 +1282,12 @@ var POLICY_HELP = `cauthy-auth policy --pull [--out <file.ts>] [--system <name>]
 cauthy-auth policy --file <roles.json> [--system <name>] [--push]
 
 --pull writes the catalog Cauthy has as a TypeScript module, so the
-application's roles and permissions are typed from it:
+application's roles and permissions are typed from it, and, when the system
+declares its resources, what a check may ask (resources, actions, attributes):
 
-  import { can, hasRole } from './policy'
+  import { can, hasRole, policy } from './policy'
   can(organization, 'ledger:write')
+  await policy.check(auth, request, { organization, resource: 'invoices', action: 'approve', attributes: { amount: 500 } })
 
   --pull            Read the catalog from Cauthy.
   --out <file>      Write the module there. Without it, it is printed.
@@ -1208,13 +1298,19 @@ CAUTHY_TOKEN (a personal access token with organizations:manage).
 
 --file does the opposite, once:
 
-Loads a system's catalog of roles into Cauthy from a file:
+Loads a system's catalog of roles into Cauthy from a file: a list of roles,
+or the resources the system declares with them.
 
-  { "roles": [ { "role": "accountant", "name": "Accountant", "inherits": ["reader"],
-      "permissions": [ { "resource": "ledger", "action": "write" },
-                       { "kind": "business", "resource": "books.close", "action": "write" } ] } ] }
+  { "catalog": [ { "resource": "invoices", "actions": ["read", "approve"],
+                   "attributes": { "amount": "number", "branch": "string" } } ],
+    "roles": [ { "role": "accountant", "name": "Accountant", "inherits": ["reader"],
+      "permissions": [ { "resource": "invoices", "action": "read" },
+                       { "resource": "invoices", "action": "approve",
+                         "condition": "resource.attrs.amount <= 1000000" } ] } ] }
 
-  --file <file>     The catalog, as JSON.
+  --file <file>     The catalog, as JSON. Without "catalog", the resources
+                    Cauthy has stay as they are; with it, they are sent first
+                    and the roles are checked against them.
   --system <name>   The system it is of. Default: CAUTHY_SYSTEM.
   --push            Send it to Cauthy, REPLACING the catalog it has. Without it
                     the catalog is only checked and shown.
@@ -1223,7 +1319,7 @@ Use it to load a first catalog. Afterwards the catalog is Cauthy's, edited in
 its dashboard: pushing again overwrites what was edited there.
 
 To push: CAUTHY_ISSUER, CAUTHY_TENANT (the workspace's slug) and CAUTHY_TOKEN
-(a personal access token with organizations:manage).
+(a personal access token with systems:policy).
 `;
 async function policy(argv) {
   if (argv.includes("--help") || argv.includes("-h")) {
@@ -1249,12 +1345,14 @@ ${POLICY_HELP}`);
   }
   if (pull) {
     const of = system ?? process.env.CAUTHY_SYSTEM ?? fail("name the system with --system or CAUTHY_SYSTEM");
-    const read = process.env.CAUTHY_TOKEN ? await pullPolicy({ system: of }) : await createSystem().policy.get(of);
+    const own = process.env.CAUTHY_TOKEN ? void 0 : createSystem();
+    const [read, catalog2] = await Promise.all(own ? [own.policy.get(of), own.catalog.get(of).catch(() => [])] : [pullPolicy({ system: of }), pullCatalog({ system: of }).catch(() => [])]);
     if (read.length === 0) fail(`Cauthy has no catalog of roles for "${of}"`);
-    const source = policySource(of, read);
+    const source = policySource(of, { catalog: catalog2, roles: read });
     if (out2) {
       (0, import_node_fs.writeFileSync)(out2, source);
-      process.stdout.write(`${read.length} roles written to ${out2}: ${read.map((r) => r.role).join(", ")}
+      const resources = catalog2.length ? ` and ${catalog2.length} resources (${catalog2.map((c) => c.resource).join(", ")})` : "";
+      process.stdout.write(`${read.length} roles${resources} written to ${out2}: ${read.map((r) => r.role).join(", ")}
 `);
     } else {
       process.stdout.write(source);
@@ -1262,20 +1360,23 @@ ${POLICY_HELP}`);
     return;
   }
   if (!file) fail("give the catalog with --file\n\n" + POLICY_HELP);
-  let roles;
+  let given;
+  let withCatalog = false;
   try {
     const parsed = JSON.parse((0, import_node_fs.readFileSync)(file, "utf8"));
-    const list = Array.isArray(parsed) ? parsed : parsed.roles;
-    if (!Array.isArray(list)) throw new Error('no "roles" list');
-    roles = list;
+    given = readPolicyFile(parsed);
+    withCatalog = !Array.isArray(parsed) && parsed.catalog !== void 0;
   } catch (err) {
     return fail(`cannot read ${file}: ${err instanceof Error ? err.message : String(err)}`);
   }
+  const { roles, catalog } = given;
   const permissions = roles.reduce((n, r) => n + (r.permissions?.length ?? 0), 0);
+  if (withCatalog) process.stdout.write(`${catalog.length} resources: ${catalog.map((c) => c.resource).join(", ")}
+`);
   process.stdout.write(`${roles.length} roles, ${permissions} permissions: ${roles.map((r) => r.role).join(", ")}
 `);
   if (push) {
-    await pushPolicy({ system, roles });
+    await pushPolicy({ system, roles, ...withCatalog ? { catalog } : {} });
     process.stdout.write("Sent to Cauthy: this is now the catalog of the system.\n");
   } else {
     process.stdout.write("Not sent. Add --push to give it to Cauthy.\n");

package/dist/client.d.mts

@@ -1,5 +1,6 @@
 import { CauthyTheme } from './theme.mjs';
-import { i as PublicSession } from './system-BxMsSIu1.mjs';
+import { q as PublicSession, f as CheckQuestion, k as OrganizationRef, g as CheckResult } from './system-0mHrdAgO.mjs';
+export { h as CheckRule } from './system-0mHrdAgO.mjs';
 import { A as AuthField, b as PasswordPolicy } from './validate-sEXG82po.mjs';
 export { D as DEFAULT_PASSWORD_POLICY, F as FieldProblem, M as MIN_PASSWORD, P as PasswordClass, a as PasswordLocale, c as PasswordReason, d as checkCode, e as checkEmail, f as checkName, g as checkNewPassword, h as checkPassword, i as describePasswordPolicy, j as explainPasswordProblems, p as passwordPolicyOf, k as passwordProblems } from './validate-sEXG82po.mjs';
 import 'jose';
@@ -201,19 +202,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. */
@@ -243,8 +254,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`. */
@@ -276,6 +291,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. */
@@ -725,4 +765,4 @@ interface AuthClientOptions {
 }
 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 ConnectedAgent, type LinkedIdentity, type OrganizationPerson, type OrganizationRoleChoice, type OrganizationSeat, type OrganizationsClient, type Passkey, type PasskeyKind, PasswordPolicy, type PendingLegal, type SSOConnection, type SecondStep, type SessionState, type SessionStore, type SessionStoreOptions, canAutofillPasskeys, canUsePasskeys, createAuthClient, createSessionStore };
+export { type Account, type AccountClient, type AccountSession, type AuthClient, type AuthClientOptions, type AuthError, AuthField, type AuthMethods, type AuthResult, CheckQuestion, CheckResult, type ConnectedAgent, type LinkedIdentity, type OrganizationPerson, OrganizationRef, type OrganizationRoleChoice, type OrganizationSeat, type OrganizationsClient, type Passkey, type PasskeyKind, PasswordPolicy, type PendingLegal, type SSOConnection, type SecondStep, type SessionState, type SessionStore, type SessionStoreOptions, canAutofillPasskeys, canUsePasskeys, createAuthClient, createSessionStore };

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 import { CauthyTheme } from './theme.js';
-import { i as PublicSession } from './system-DTIeDXDP.js';
+import { q as PublicSession, f as CheckQuestion, k as OrganizationRef, g as CheckResult } from './system-BIYbS7h2.js';
+export { h as CheckRule } from './system-BIYbS7h2.js';
 import { A as AuthField, b as PasswordPolicy } from './validate-sEXG82po.js';
 export { D as DEFAULT_PASSWORD_POLICY, F as FieldProblem, M as MIN_PASSWORD, P as PasswordClass, a as PasswordLocale, c as PasswordReason, d as checkCode, e as checkEmail, f as checkName, g as checkNewPassword, h as checkPassword, i as describePasswordPolicy, j as explainPasswordProblems, p as passwordPolicyOf, k as passwordProblems } from './validate-sEXG82po.js';
 import 'jose';
@@ -201,19 +202,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. */
@@ -243,8 +254,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`. */
@@ -276,6 +291,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. */
@@ -725,4 +765,4 @@ interface AuthClientOptions {
 }
 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 ConnectedAgent, type LinkedIdentity, type OrganizationPerson, type OrganizationRoleChoice, type OrganizationSeat, type OrganizationsClient, type Passkey, type PasskeyKind, PasswordPolicy, type PendingLegal, type SSOConnection, type SecondStep, type SessionState, type SessionStore, type SessionStoreOptions, canAutofillPasskeys, canUsePasskeys, createAuthClient, createSessionStore };
+export { type Account, type AccountClient, type AccountSession, type AuthClient, type AuthClientOptions, type AuthError, AuthField, type AuthMethods, type AuthResult, CheckQuestion, CheckResult, type ConnectedAgent, type LinkedIdentity, type OrganizationPerson, OrganizationRef, type OrganizationRoleChoice, type OrganizationSeat, type OrganizationsClient, type Passkey, type PasskeyKind, PasswordPolicy, type PendingLegal, type SSOConnection, type SecondStep, type SessionState, type SessionStore, type SessionStoreOptions, canAutofillPasskeys, canUsePasskeys, createAuthClient, createSessionStore };