cauthy-auth 0.28.1 → 0.31.0

package/README.md

@@ -47,16 +47,21 @@ const { signIn } = useAuth()
 const r = await signIn.email({ email, password })   // r.ok, r.status, r.error.field
 ```
 
-What Cauthy mails opens your pages too: a new password, a confirmed address, a sign-in link.
+What Cauthy mails opens your pages too: a new password, a confirmed address, a sign-in link, an invitation.
 
 ```ts
-export const auth = createCauthy({ pages: { signIn: '/sign-in', resetPassword: '/new-password', verifyEmail: '/confirm' } })
+export const auth = createCauthy({ pages: { signIn: '/sign-in', resetPassword: '/new-password', verifyEmail: '/confirm', acceptInvite: '/accept-invite' } })
 ```
 
 ```tsx
-import { ResetPassword, VerifyEmail } from 'cauthy-auth/react'
+import { AcceptInvite, ResetPassword, VerifyEmail } from 'cauthy-auth/react'
+<AcceptInvite links={{ signIn: '/sign-in' }} returnTo="/" />   // "You've been invited to Acme", a password, signed in
+
+const { invitation, acceptInvitation } = useAuth()               // or with your own form
 ```
 
+The forms follow what the workspace turned on in Cauthy's dashboard: each provider's button carries its logo (`classNames.providerIcon` styles it), and a workspace that turned off the password or passkeys does not see them offered. `methods()` says so: `passwordSignIn`, `passkey`, `providers[].iconUrl`.
+
 And the person's account, in your application: name, password, second step, sessions.
 
 ```tsx
@@ -64,6 +69,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 +107,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:
 
 | | |
@@ -115,6 +171,8 @@ const org = await auth.system.organizations.create({ name: 'Acme' })
 await auth.system.members.add(org.id, { role: 'owner', email: 'ana@acme.com' })
 ```
 
+Its invitations open your `pages.acceptInvite` when the application knows its public origin (`baseURL`, `CAUTHY_BASE_URL`); otherwise Cauthy's own page.
+
 A backend that is handed a Cauthy access token checks it with Cauthy's published keys: no secret, no call per request.
 
 ```ts

package/dist/{cauthy-CTVg4kvo.d.mts → cauthy-2jtP2LVQ.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-CVBW_AV8.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-BrrJsrFW.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-BAwAJChs.d.ts → cauthy-CKfvvv_i.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-Bn8uckvQ.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-BvvoNs2y.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,9 @@ 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 acceptInviteUrl = given.acceptInviteUrl ?? env("CAUTHY_ACCEPT_INVITE_URL") ?? "";
+  const inviteHeaders = /^https?:\/\//.test(acceptInviteUrl) ? { "x-cauthy-client-id": clientId, "x-cauthy-link-to": acceptInviteUrl } : {};
   const doFetch = (...args) => (given.fetch ?? fetch)(...args);
   const tokenEndpoint = `${issuer}/v1/oauth/token`;
   function configured() {
@@ -956,10 +1033,10 @@ function createSystem(given = {}) {
       asking = void 0;
     });
   }
-  async function call(method, path, body) {
+  async function call(method, path, body, extra = {}) {
     const send = async () => doFetch(`${issuer}${path}`, {
       method,
-      headers: { authorization: `Bearer ${await token()}`, ...body === void 0 ? {} : { "content-type": "application/json" } },
+      headers: { authorization: `Bearer ${await token()}`, ...extra, ...body === void 0 ? {} : { "content-type": "application/json" } },
       body: body === void 0 ? void 0 : JSON.stringify(body)
     });
     let res = await send();
@@ -970,7 +1047,7 @@ function createSystem(given = {}) {
     if (!res.ok) await fail2(res, `${method} ${path}`);
     return res.status === 204 ? void 0 : res.json();
   }
-  const data = async (method, path, body) => (await call(method, path, body))?.data;
+  const data = async (method, path, body, extra) => (await call(method, path, body, extra))?.data;
   const id = encodeURIComponent;
   return {
     token,
@@ -1007,7 +1084,8 @@ function createSystem(given = {}) {
         return toMember(await data(
           "POST",
           `/v1/organizations/${id(orgId)}/members`,
-          { role: m.role, user_id: m.userId, email: m.email, name: m.name, locale: m.locale, client_id: clientId }
+          { role: m.role, user_id: m.userId, email: m.email, name: m.name, locale: m.locale, client_id: clientId },
+          inviteHeaders
         ));
       },
       async setRole(orgId, userId, role) {
@@ -1018,7 +1096,7 @@ function createSystem(given = {}) {
       }
     },
     async invite(person) {
-      const u = await data("POST", "/v1/users", { ...person, client_id: clientId });
+      const u = await data("POST", "/v1/users", { ...person, client_id: clientId }, inviteHeaders);
       return { id: u.id, email: u.email };
     },
     theme: {
@@ -1031,6 +1109,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 +1285,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 +1301,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 +1322,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 +1348,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 +1363,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");