@owlmeans/iam 0.1.18-rc.9 → 0.1.18

package/README.md

@@ -1,32 +1,202 @@
 # @owlmeans/iam
 
-Provider-agnostic IAM abstraction for the OwlMeans framework — `IamService` interface, client/realm types, and permission helpers.
-
-## Overview
-
-- `IamService` — unified interface for provisioning clients, realms, and permissions across IAM backends (e.g. Keycloak, built-in)
-- `IamClient` / `IamCredentialsPair` / `IamResourceSpec` — shared contract types used by server-side IAM implementations
-- `IamPermissionArgs` — describes a named permission including resource-scope and human-readable title
-- `hasPermission` — utility to check whether a set of grants covers a given permission/resource pair
-- Errors: `IamError` and subtypes for client-provisioning and permission failures
+Provider-agnostic IAM contracts: the `IamService` interface (client provisioning, permission
+definitions and grants, users of a client, organization/group/subject facets), the permission-name
+and gate-param grammars, `hasPermission`, the IAM errors, and the protocol declarations of the
+provider's runtime IAM API. An app imports it to type the IAM service it resolves by alias, to
+declare and grant permissions, to check an `Authorization` against a permission, and to build gate
+params. It contains no implementation and talks to no provider — a concrete backend (a Keycloak
+proxy, or the integrated backend built on `@owlmeans/server-oidc-provider`) ships separately, the
+server-side gate and runtime client are `@owlmeans/server-iam`, and the browser half (organization
+switch, `hasPermission` re-export) is `@owlmeans/client-iam`. Permission decisions belong on the
+server; the `iam` skill holds the full model.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/iam
+bun add @owlmeans/iam@^0.1.18
 ```
 
+`ajv` is a peer dependency (the runtime API schemas are `JSONSchemaType`).
+
+## Concepts
+
+- **Owning organization entity vs. acting organization** — every `IamService` method takes
+  `entityId` first: the organization entity that **owns** the client, resolved server-side. The
+  organizations a client's subjects act in are named by `entitySlug` inside the facets and on the
+  wire.
+- **Client** — an OIDC client (`IamClient`) of one organization entity. Its id is globally unique,
+  because a provider resolves the bare `client_id` with no tenant context.
+- **Permission name** — `<resource>--<action>` with **two** hyphens (`PERMISSION_ACTION_SEPARATOR`);
+  a bare `<resource>` is unscoped. A name never carries `@`.
+- **Permission kinds** — a definition is unbound, `entityScoped` (grants bound to one organization),
+  `resourceScoped` (grants may list resource ids), or both. The kind is a property of the definition.
+- **Grant form** — `IamGrantMode.Blanket` (no `resources`, covers every id), `Resources` (an explicit
+  id list), `All` (revoke-only). The two grantable forms are stored separately.
+- **Default class** — `IamDefaultClass.User` / `Member` / `Owner` / `None`: who holds a definition
+  without an explicit grant, evaluated when claims are built.
+- **Facets** — `organizations`, `groups`, `subjects` on `IamService`; a backend without one answers
+  `unsupportedFacet(what)`.
+- **Gate param** — `<permission>[@<selector>]` on an entrypoint guard; the selector says where the
+  resource id is read at request time: bare `@enquiryId` (flat key, params then query) or qualified
+  `@body:order.id` (one source, nested path).
+
 ## Usage
 
+### Check a permission
+
 ```typescript
-import type { IamService, IamClient } from '@owlmeans/iam'
 import { hasPermission } from '@owlmeans/iam'
 
-// Check whether an auth payload includes a required permission
-const allowed = hasPermission(auth, { permission: 'manage-users', resourceScoped: false })
+// A blanket set satisfies a resourceId check; a bound set counts only for the named organization
+const allowed = hasPermission(auth, 'order--edit', { scope: clientId, resourceId: 'ord-1', entitySlug: 'acme' })
 ```
 
-Typically consumed via `@owlmeans/server-iam` which wires the concrete OIDC-backed implementation.
+### Declare and grant permissions
+
+```typescript
+import { DEFAULT_ALIAS, IamDefaultClass, IamGrantMode, permissionNameHelper } from '@owlmeans/iam'
+import type { IamService } from '@owlmeans/iam'
+
+const iam = context.service<IamService>(DEFAULT_ALIAS)
+
+const name = await iam.ensurePermission(entityId, clientId, 'order', {
+  permission: 'edit', resourceScoped: true, entityScoped: true, area: 'user',
+  defaultClass: IamDefaultClass.Owner,
+})                                                          // 'order--edit'
+
+await iam.grantPermission(entityId, clientId, profileId, name, {
+  mode: IamGrantMode.Resources, resources: ['ord-1'], entitySlug: 'acme',
+})
+await iam.revokePermission(entityId, clientId, profileId, name, { mode: IamGrantMode.All, entitySlug: 'acme' })
+
+permissionNameHelper.parsePermissionName('order--edit')    // { name, resource: 'order', action: 'edit' }
+permissionNameHelper.composePermissionName({ resource: 'order', action: 'edit' })
+```
+
+### Provision a client
+
+```typescript
+const client = await iam.ensureClient(entityId, clientId, {
+  redirectUris: ['https://acme.example.com/callback'],
+  config: { users: true },                                  // tenanted: subjects get organizations of their own
+})
+const issuer = await iam.getIssuerUrl(entityId)             // pass through as the discovery URL, never rebuild it
+```
+
+### Work with gate params
+
+```typescript
+import { GateParamSource, gateParamHelper, gateValidationHelper, resolveGateResource } from '@owlmeans/iam'
+
+const param = gateParamHelper.formatGateParam('order--edit', { source: GateParamSource.Body, path: ['order', 'id'] })
+// 'order--edit@body:order.id'
+
+const { permission, resource, error } = gateParamHelper.parseGateParam(param)
+const resolved = resource != null ? resolveGateResource(req, resource) : undefined   // { id?, from?, reason? }
+
+const issues = gateValidationHelper.validateGateParams(['order--view@orderId'], { routePath: '/orders/:orderId' })
+```
+
+### A backend without a facet
+
+```typescript
+import { unsupportedFacet } from '@owlmeans/iam'
+import type { IamGroupFacet } from '@owlmeans/iam'
+
+const groups = unsupportedFacet<IamGroupFacet>('groups')    // every method throws IamUnsupported('groups') synchronously
+```
+
+## API
+
+### `IamService` (alias `DEFAULT_ALIAS` = `'iam-service'`)
+
+| Group | Methods |
+|---|---|
+| Admin config | `getEntityAdminConfig`, `getCredentialsPair`, `getIssuerUrl` |
+| Clients | `ensureClient(entityId, clientId, { redirectUris?, config? }?)`, `getClient`, `claimClient`, `deleteClient` |
+| Definitions | `ensurePermission`, `deletePermission(…, names, { policy?, managed? }?)`, `normalizePermissions`, `ensureResourceOwnership`, `listPermissions(…, filter?)` |
+| Grants | `grantPermission`, `revokePermission`, `grantBundle`, `listGrants` |
+| Users of a client | `listUsers`, `getUser`, `inviteUser`, `updateUser`, `removeUser`, `syncStaff` |
+| Facets | `organizations` (`IamOrganizationFacet`), `groups` (`IamGroupFacet`), `subjects` (`IamSubjectFacet`) |
+
+### Functions and helpers
+
+| Symbol | Purpose |
+|---|---|
+| `hasPermission(auth, permission, { scope?, resourceId?, entitySlug? }?)` | Does an `Authorization`'s permission sets grant it |
+| `permissionNameHelper` (`createPermissionNameHelper()`) | `parsePermissionName`, `composePermissionName`, `isPermissionName` |
+| `gateParamHelper` (`createGateParamHelper()`) | `parseGateParam`, `parseGateSelector`, `formatGateParam` |
+| `gateValidationHelper` (`createGateValidationHelper()`) | `validateGateParams(params, audit?)`, `routeParamsOf(path)` |
+| `resolveGateResource(req, selector)` | Read the resource id a selector points at → `{ id?, from?, reason? }` |
+| `unsupportedFacet<T>(what)` | A facet whose every method throws `IamUnsupported(what)` |
+| `makeIamRuntimeProtocols({ service, path? })` | Protocol tree of the runtime IAM API: `organizations.{list,create,update}`, `members.{list,add,update,remove}`, `permissions.list`, `grants.{list,assign,revoke}` |
+| `parsePermissionName`, `isPermissionName`, `parseGateParam` | Deprecated standalone forms of the helper members |
+
+### Constants and enums
+
+| Symbol | Value / members |
+|---|---|
+| `IAM_MODE_KEYCLOAK`, `IAM_MODE_INTEGRATED`, `IamMode` | `'keycloak'`, `'integrated'` — a config seam for the app's own service factory |
+| `IAM_AREAS`, `IamArea` | `['user', 'operator', 'admin']` — presentational grouping tags |
+| `PERMISSION_ACTION_SEPARATOR` | `'--'` |
+| `RESOURCE_PARAM_SEPARATOR`, `RESOURCE_SOURCE_SEPARATOR`, `RESOURCE_PATH_SEPARATOR` | `'@'`, `':'`, `'.'` |
+| `GateParamSource`, `DEFAULT_GATE_PARAM_SOURCES` | `Params` `Query` `Body` `Headers` `Auth`; bare form searches `[Params, Query]` |
+| `GateParamErrorCode`, `GateResolutionFailure` | structural selector problems; why a selector yielded no id |
+| `IamGrantMode`, `IamRemovalPolicy`, `IamDefaultClass`, `IamGrantOrigin` | `Blanket`/`Resources`/`All`; `Cascade`/`Refuse`; `None`/`User`/`Member`/`Owner`; `Direct`/`Default`/`Group` |
+| `IAM_MEMBERS_GROUP`, `IAM_EMAIL_PROOF` | `'members'` (managed staff group), `'proof:email'` |
+| `IAM_RUNTIME_GUARD`, `IAM_RUNTIME_PATH`, `IAM_RUNTIME_ROUTES` | runtime API guard alias, default base `'/runtime'`, leaf-path table |
+| `IamRuntime*Schema` | closed AJV schemas of the runtime API's wire shapes |
+
+### Types
+
+`IamClient`, `IamClientInfo`, `IamClientConfig`, `IamClientOptions`, `IamCredentialsPair`,
+`IamPermissionArgs`, `IamPermissionDefinition`, `IamPermissionFilter`, `IamResourceSpec`,
+`IamGrant`, `IamGrantArgs`, `IamGrantBundle`, `IamGroupRef`, `IamPermissionDeleteArgs`,
+`IamPermissionRemoval`, `IamNormalizeArgs`, `IamNormalizationReport`, `IamUser`, `IamUserInvite`,
+`IamUserUpdate`, `IamMembershipInfo`, `IamOrganization*`, `IamMember*`, `IamGroup*`,
+`IamStaffSync*`, `IamSubject`, `IamSignIn*`, the three facet interfaces, `HasPermissionOptions`,
+`ParsedPermissionName`, `PermissionNameHelper`, the `Gate*` types and the `IamRuntime*` wire types.
+
+### Errors
+
+All extend `IamError` (a `ResilientError`) and are registered for marshalling.
+
+| Class | Meaning |
+|---|---|
+| `IamClientError` | client invalid or unusable — `client:entity-mismatch`, `redirect-uris`, unconfigured provider route |
+| `IamResourceError` | a provider resource came back without a name |
+| `IamGrantError` | grant subject missing or entity mismatch |
+| `IamPermissionError` | definition refusal — `permission:held:<name>`, `permission:managed:<name>`, a disallowed `defaultClass` |
+| `IamUserError` | an end-user operation was refused |
+| `IamOrganizationError` | unknown organization, last owner, membership cap |
+| `IamGroupError` | unknown group key, managed group written by an operator, another client's group |
+| `IamUnsupported` | the active backend cannot do it (`user-management`, `resource-scoped-grant`, a facet) |
+
+## Common pitfalls
+
+- `revokePermission` without `mode` defaults to `All`, `grantPermission` to `Blanket`; pass `mode`
+  explicitly.
+- Granting an `entityScoped` definition requires `args.entitySlug`; any other definition refuses it.
+- One hyphen is not a separator: `enquiry-view` is a resource with no action. Build names with
+  `permissionNameHelper`, never by splitting strings.
+- `@` belongs to the gate param, never to a stored name — `ensurePermission` refuses it.
+- Always pass `redirectUris` to `ensureClient`; the integrated provider refuses the legacy wildcard.
+- Never rebuild an issuer URL from a host and base path — use `getIssuerUrl`.
+- A client id must include the owning organization entity and be reserved with `claimClient`;
+  `ensureClient` refuses another entity's record.
+- Use `grantBundle` instead of looping over `grantPermission`.
+- `getCredentialsPair` returns a raw admin token — never hand it to a request handler.
+- `entityId` never comes from a token or request; the wire names organizations by `entitySlug` only.
+
+## Related packages
+
+- [`@owlmeans/server-iam`](../server-iam) — the IAM gate, the session's organizations on the server, the runtime IAM client
+- [`@owlmeans/client-iam`](../client-iam) — browser wiring, organization switch, `hasPermission` re-export
+- [`@owlmeans/oidc`](../oidc) — provider descriptors, claim shapes, the `iamMode` config field
+- [`@owlmeans/auth`](../auth) — `Authorization` and `PermissionSet`, which `hasPermission` reads
+- [`@owlmeans/server-oidc-provider`](../server-oidc-provider) — the provider the integrated backend is built on
+- [`@owlmeans/entrypoint`](../entrypoint) — the protocol builders behind `makeIamRuntimeProtocols`
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -36,7 +206,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "package": "@owlmeans/iam",
-  "version": "0.1.18-rc.8",
-  "generatedAt": "2026-08-24T21:14:00.118Z",
+  "version": "0.1.18",
+  "generatedAt": "2026-10-28T00:31:34.724Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {
@@ -10,7 +10,95 @@
       "name": "iam",
       "category": "package-specific",
       "file": "skills/iam/SKILL.md",
-      "canonicalPath": ".agents/skills/iam/SKILL.md"
+      "canonicalPath": ".agents/skills/iam/SKILL.md",
+      "parts": [
+        {
+          "name": "clients",
+          "file": "skills/iam/parts/clients.md",
+          "description": "Provisioning OIDC clients — globally unique client ids, the realm field, issuer and redirect-URI rules — and selecting the IAM backend.",
+          "purposes": [
+            "auth",
+            "config"
+          ],
+          "mentions": [
+            "claimClient",
+            "deleteClient",
+            "getIssuerUrl",
+            "redirectUris",
+            "IamClientError",
+            "IAM_MODE_INTEGRATED",
+            "IAM_MODE_KEYCLOAK",
+            "iamMode",
+            "IamClient"
+          ]
+        },
+        {
+          "name": "permissions",
+          "file": "skills/iam/parts/permissions.md",
+          "description": "Permission names and grant forms, IamGrantMode, the four permission kinds, default classes and restrictions.",
+          "purposes": [
+            "auth"
+          ],
+          "mentions": [
+            "hasPermission",
+            "grantPermission",
+            "revokePermission",
+            "ensurePermission",
+            "IamGrantMode",
+            "IamDefaultClass",
+            "composePermissionName",
+            "parsePermissionName",
+            "entityScoped",
+            "resourceScoped",
+            "defaultClass"
+          ]
+        },
+        {
+          "name": "service",
+          "file": "skills/iam/parts/service.md",
+          "description": "The full IamService interface with its per-method contracts, and the per-client user operations.",
+          "purposes": [
+            "auth",
+            "server-api"
+          ],
+          "mentions": [
+            "IamService",
+            "getEntityAdminConfig",
+            "ensureClient",
+            "getClient",
+            "grantBundle",
+            "listGrants",
+            "listUsers",
+            "inviteUser",
+            "updateUser",
+            "removeUser",
+            "syncStaff",
+            "normalizePermissions",
+            "deletePermission"
+          ]
+        },
+        {
+          "name": "tenancy",
+          "file": "skills/iam/parts/tenancy.md",
+          "description": "The organizations, groups and subjects facets of IamService, and the runtime IAM API a tenanted client's server calls.",
+          "purposes": [
+            "auth",
+            "server-api"
+          ],
+          "mentions": [
+            "IamOrganizationFacet",
+            "IamGroupFacet",
+            "IamSubjectFacet",
+            "unsupportedFacet",
+            "IAM_MEMBERS_GROUP",
+            "makeIamRuntimeProtocols",
+            "IAM_RUNTIME_GUARD",
+            "IAM_RUNTIME_ROUTES",
+            "IAM_RUNTIME_PATH",
+            "iamRuntime"
+          ]
+        }
+      ]
     }
   ]
 }

package/agent-meta/skills/iam/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: iam
-description: "IamService abstraction for provider-agnostic IAM provisioning. Load when wiring IAM operations, switching IAM mode, or implementing a new IAM provider. Applies to files matching **/services/iam*.ts, **/context.ts, **/types.ts."
+description: "How to use @owlmeans/iam — the provider-agnostic IamService, the permission-definition model with its four kinds (unbound, entity-bound, resource-bound, both) and default classes, the organization/group/subject facets, the runtime IAM API declarations, client-id uniqueness, issuer and redirect-URI rules, and hasPermission. Load when wiring IAM operations, granting or revoking permissions, working with tenanted clients, selecting the IAM backend, or implementing a new IAM provider. Applies to files matching **/services/iam*.ts, **/context.ts, **/types.ts."
 metadata:
   applyTo: "**/services/iam*.ts, **/context.ts, **/types.ts"
 ---
@@ -8,198 +8,112 @@ metadata:
 
 # Using `@owlmeans/iam`
 
-Provider-agnostic IAM abstraction. Defines `IamService` interface and related types. Used by both the platform backend (`viable-backend`) and the agent library (`@owlmeans/viable`). Concrete implementations live in `@owlmeans/iam-keycloak` (full proxy) and `@owlmeans/iam-integrated`.
+**Install:** `"@owlmeans/iam": "^0.1.18"` in `dependencies`
+
+Provider-agnostic IAM abstraction: the `IamService` interface, the permission and grant shapes, the
+gate-param grammar, `hasPermission`, and the declarations of the provider's runtime IAM API. It
+contains no implementation and talks to no provider —
+concrete backends (a Keycloak proxy, an integrated backend built on the OwlMeans OIDC provider) are
+separate packages, and every consumer depends on this interface rather than on one of them.
+
+## Where the halves live
+
+This package is contracts only. The browser half — `appendIam`, the session's organizations and the
+switch, `hasPermission` re-exported — is `@owlmeans/client-iam` (`client-iam` skill); the server half
+— the IAM gate, the session's organizations on the server and the runtime IAM client — is
+`@owlmeans/server-iam` (`server-iam` skill). Permission decisions are made on the server, never in
+the browser.
 
 ## Public API surface
 
 | Symbol | Kind | Purpose |
 |--------|------|---------|
 | `IamService` | type | Unified IAM interface — all provisioning + authorization operations |
-| `IamClient` | type | Provisioned OIDC client `{ id?, clientId, secret?, name?, realm? }` |
-| `IamClientOptions` | type | `{ redirectUris? }` — explicit `ensureClient` hardening; omitting is a keycloak-only legacy shape (see below) |
+| `IamClient` | type | Provisioned OIDC client `{ id?, clientId, secret?, name?, realm?, config? }` |
+| `IamClientInfo` | type | `IamClient` without `secret` — what `getClient` answers |
+| `IamClientConfig` | type | `{ operators?, users?, [key]: unknown }` — the two tenancy flags plus the client's arbitrary configuration |
+| `IamClientOptions` | type | `{ redirectUris?, config? }` — explicit `ensureClient` hardening (omitting `redirectUris` is a keycloak-only legacy shape, see the `clients` part); `config` merges shallowly |
 | `IamCredentialsPair` | type | `{ token: string; realm: string }` |
-| `IamPermissionArgs` | type | `{ permission?, resourceScoped?, title? }` — `permission` absent means unscoped resource name |
+| `IamPermissionArgs` | type | `{ permission?, resourceScoped?, entityScoped?, title?, area?, managed?, defaultClass? }` — `permission` absent means unscoped resource name; omitted flags are kept, passed ones (`false` / `None` included) written |
 | `IamResourceSpec` | type | `{ name: string; displayName?: string }` |
-| `IamPermissionDefinition` | type | Declared permission `{ name, resource, action?, resourceScoped?, title? }` |
-| `IamGrantArgs` | type | `{ resources?: string[] }` — present = resource-scoped grant form |
-| `IamGrant` | type | `{ profileId, clientId, permission, resources? }` |
-| `IamUser` | type | End-user of an entity `{ profileId, email?, name?, role, disabled?, grantCount? }` |
+| `IamPermissionDefinition` | type | Declared permission `{ name, resource, action?, resourceScoped?, entityScoped?, title?, area?, managed?, defaultClass? }` |
+| `IamPermissionFilter` | type | `{ areas?, managed?, resourceScoped?, entityScoped? }` — narrows `listPermissions`; an `areas` entry of `null` matches untagged definitions |
+| `IamDefaultClass` | enum | `None` / `User` / `Member` / `Owner` — who holds a definition without a grant (see "Permission kinds" in the `permissions` part) |
+| `IamGrantArgs` | type | `{ resources?, mode?, entitySlug? }` — `entitySlug` binds an `entityScoped` grant |
+| `IamGrant` | type | `{ profileId? \| group?, clientId, permission, resources?, mode?, entitySlug?, origin?, through?, restricted? }` — exactly one subject; `restricted: true` only in a listing that asked for it (withheld, not held) |
+| `IamGrantListArgs` | type | `{ restricted? }` — `listGrants` / `groups.grants` also list what the subject's own restriction withholds |
+| `IamGrantOrigin` | enum | `Direct` / `Default` / `Group` / `Bundle` — why a listed grant is held; `through` names the group; `Bundle` only in a group's own listing |
+| `IamGroupRef` | type | `{ entitySlug, key }` — a group by its organization's slug and its key |
+| `IamGrantMode` | enum | `Blanket` / `Resources` / `All` / `Inherit` — which FORM of a grant an operation addresses; `All` and `Inherit` are revoke-only |
+| `IamGrantBundle` | type | `{ filter?, permissions?, mode?, resources?, entitySlug? }` — what `grantBundle` hands out |
+| `IamRemovalPolicy` | enum | `Cascade` / `Refuse` — what to do about grants of a definition being deleted |
+| `IamPermissionDeleteArgs`, `IamPermissionRemoval` | type | `{ policy?, managed? }` and `{ permission, clientId, found, revoked }` |
+| `IamNormalizeArgs`, `IamNormalizationReport` | type | `{ dryRun? }` and the rename/merge plan `normalizePermissions` reports |
+| `IAM_AREAS`, `IamArea` | const/type | `['user', 'operator', 'admin']` — presentational grouping tags, read by no gate |
+| `PERMISSION_ACTION_SEPARATOR` | const | `'--'` — TWO hyphens, never one |
+| `parsePermissionName` / `composePermissionName` / `isPermissionName` | fn | Read, build and validate a permission NAME |
+| `ParsedPermissionName` | type | `{ name, resource, action?, problem? }` |
+| `IamUser` | type | Subject of one client `{ profileId, email?, name?, role, disabled?, grantCount?, home?, memberships? }` |
+| `IamMembershipInfo` | type | `{ entitySlug, title?, owner, groups, home? }` — one organization of an `IamUser` |
 | `IamUserInvite` | type | `{ email, name?, role? }` — find-or-create args |
-| `IamUserUpdate` | type | `{ name?, role?, disabled? }` |
-| `hasPermission` | fn | `(auth, permission, { scope?, resourceId? }?)` — checks `Authorization.permissions` PermissionSet[]; an unscoped set satisfies a resourceId check |
+| `IamUserUpdate` | type | `{ name?, role?, disabled? }` — `disabled` lands on the primary row |
+| `IamOrganization`, `IamOrganizationArgs`, `IamOrganizationUpdate` | type | `{ entitySlug, title?, members? }`; create `{ title?, profileId? }` (the new owner); update `{ title }` |
+| `IamMember`, `IamMemberInvite`, `IamMemberUpdate` | type | `{ profileId, email?, name?, owner, groups, managed? }`; `{ email, name?, owner? }`; `{ owner?, groups? }` |
+| `IamGroup`, `IamGroupArgs`, `IamGroupBundle` | type | `{ entitySlug, key, title?, managed?, members?, bundles }`; `{ title?, bundles? }`; `{ filter?, permissions? }` |
+| `IamStaffSyncArgs`, `IamStaffSyncReport` | type | `{ bundles }` and `{ added, removed }` (profile ids) of `syncStaff` |
+| `IamSubject`, `IamSignInArgs`, `IamSignInResult` | type | `{ profileId, email?, name?, organizations, permissions }` (claims input); `{ email, name? }`; `{ accountId, profileId }` |
+| `IamOrganizationFacet`, `IamGroupFacet`, `IamSubjectFacet` | type | The three facets of `IamService` |
+| `unsupportedFacet<T>(what)` | fn | A facet whose every method throws `IamUnsupported(what)` — synchronously |
+| `IAM_MEMBERS_GROUP` | const | `'members'` — the managed staff group `syncStaff` keeps (structure the sync's, permissions the operator's) |
+| `IAM_EMAIL_PROOF` | const | `'proof:email'` — the `profileId` of a credential that proves an address and identifies nobody yet |
+| `hasPermission` | fn | `(auth, permission, { scope?, resourceId?, entitySlug? }?)` — checks `Authorization.permissions`; an unscoped set satisfies a resourceId check, an unbound set any organization |
+| `HasPermissionOptions` | type | `{ scope?, resourceId?, entitySlug? }` |
+| `makeIamRuntimeProtocols({ service, path? })` | fn | The runtime IAM API's protocol tree — see "Runtime IAM API" in the `tenancy` part |
+| `IAM_RUNTIME_GUARD`, `IAM_RUNTIME_PATH`, `IAM_RUNTIME_ROUTES` | const | Its guard alias, default base path (`'/runtime'`) and leaf-path table |
+| `IamRuntime*` | type/schema | Its wire shapes and closed schemas (`IamRuntimeOrganization`, `IamRuntimeMember`, `IamRuntimePermission`, `IamRuntimeGrant`, `IamRuntimeGrantRequest`, … and `*Schema`) |
+| Gate grammar | fn/type | `parseGateParam`, `parseGateSelector`, `formatGateParam`, `resolveGateResource`, `validateGateParams`, `routeParamsOf`, plus `RESOURCE_*_SEPARATOR`, `GateParamSource`, `DEFAULT_GATE_PARAM_SOURCES`, `GateParamErrorCode`, `GateResolutionFailure` and the `Gate*` types. The syntax itself is documented in the `server-iam` skill |
 | `DEFAULT_ALIAS` | const | Default service alias `'iam-service'` |
 | `IAM_MODE_KEYCLOAK` | const | `'keycloak'` |
 | `IAM_MODE_INTEGRATED` | const | `'integrated'` |
 | `IamMode` | type | `'keycloak' \| 'integrated'` |
 | `IamError` | class | Base IAM error |
-| `IamClientError` | class | Thrown when an OIDC client is missing a required field (e.g. `secret`) |
-| `IamResourceError` | class | Thrown when a KC resource returns with no name |
+| `IamClientError` | class | An OIDC client is invalid or unusable — missing `secret`, unusable `redirect_uris`, `client:entity-mismatch`, an unconfigured provider route |
+| `IamResourceError` | class | A provider resource returned with no name |
 | `IamGrantError` | class | Grant subject missing or entity mismatch |
-| `IamUnsupported` | class | Operation not supported by the active backend (e.g. resource-scoped grants on Keycloak) |
-
-## Permission model (two grant forms)
-
-Permissions are declared per entity client (project) with `ensurePermission` and granted to end-user
-subjects with `grantPermission`:
-
-- **Unscoped (project-wide)**: `grantPermission(entityId, clientId, profileId, 'article--modify')`
-- **Resource-scoped**: `grantPermission(entityId, clientId, profileId, 'department--modify', { resources: ['dep-123'] })` —
-  the grant only applies to the listed resource ids.
-
-Grants materialize as OwlMeans `PermissionSet[]` (`scope` = clientId; resource-scoped grants live in a
-dedicated set per permission carrying `resources[]`, because `resources` applies to all keys of a set).
-
-## `IamService` interface
-
-```ts
-interface IamService extends InitializedService {
-  // Get the admin OIDC provider config for a tenant (used in payment provisioning, RP config)
-  getEntityAdminConfig: (entityId: string) => Promise<OidcProviderConfig>
-
-  // Get an admin { token, realm } pair for raw low-level calls (avoid unless necessary)
-  getCredentialsPair: (entityId: string) => Promise<IamCredentialsPair>
-
-  // The tenant's public, fully-qualified OIDC issuer URL — the single value a relying party needs.
-  // Config-only (no remote call); throws IamClientError when the provider route is unconfigured.
-  getIssuerUrl: (entityId: string) => Promise<string>
-
-  // Provision an OIDC client for a tenant and return its credentials.
-  // options.redirectUris hardens the client; always pass them (see "Issuer & redirect URIs").
-  // MUST refuse an existing record owned by another entity — see "A client id is a global name".
-  ensureClient: (entityId: string, clientId: string, options?: IamClientOptions) => Promise<IamClient>
-
-  // Reserve a free client id without provisioning it; false when anyone else holds it.
-  claimClient: (entityId: string, clientId: string) => Promise<boolean>
-
-  // Release a client id and everything keyed by it (called when a project/slot is deleted).
-  deleteClient: (entityId: string, clientId: string) => Promise<void>
-
-  // Provision a named permission on a client resource; returns the resource name
-  ensurePermission: (entityId: string, clientId: string, resource?: string, args?: IamPermissionArgs) => Promise<string>
-
-  // Provision a resource and assign it to the tenant's owner role (used in payment provisioning)
-  ensureResourceOwnership: (entityId: string, clientId: string, resource: IamResourceSpec) => Promise<void>
-
-  // --- Authorization (permission definitions & grants) ---
-
-  // List permission definitions registered for the entity's client
-  listPermissions: (entityId: string, clientId: string) => Promise<IamPermissionDefinition[]>
-
-  // Grant a permission to an end-user subject; args.resources = resource-scoped form
-  grantPermission: (entityId: string, clientId: string, profileId: string, permission: string, args?: IamGrantArgs) => Promise<IamGrant>
-
-  // Revoke; with args.resources only those ids are removed, else the whole grant
-  revokePermission: (entityId: string, clientId: string, profileId: string, permission: string, args?: IamGrantArgs) => Promise<void>
-
-  // List grants for the client, optionally for one subject
-  listGrants: (entityId: string, clientId: string, profileId?: string) => Promise<IamGrant[]>
-
-  // --- End-user management (customer-wide users, shared per entityId) ---
-
-  // Every end-user of the entity. clientId scopes the reported grantCount — it does NOT filter.
-  listUsers: (entityId: string, clientId?: string) => Promise<IamUser[]>
-  getUser: (entityId: string, profileId: string) => Promise<IamUser | null>
-  // Find-or-create by email — the one way an end-user record comes into existence.
-  inviteUser: (entityId: string, invite: IamUserInvite) => Promise<IamUser>
-  updateUser: (entityId: string, profileId: string, update: IamUserUpdate) => Promise<IamUser>
-  removeUser: (entityId: string, profileId: string) => Promise<void>
-}
-```
-
-## End-users are customer-wide
-
-An end-user belongs to the **entity**, not to a project: one customer's users are shared across every
-project they own. `listUsers` therefore returns the entity's whole set and `clientId` only scopes the
-reported `grantCount` to one project's client. Do not reintroduce a per-client filter — a person who
-has authenticated against a project but holds no grant there is still that project's user, and the
-screen that hands out grants is exactly where they have to be visible.
-
-`inviteUser` is idempotent by email, which is what lets an invitation and a first sign-in converge on
-one record instead of accumulating twins. Backends that have no user store of their own (keycloak,
-where the customer manages realm users in its console) throw `IamUnsupported('user-management')` from
-all five methods; callers turn that into an "external console" fallback rather than an error.
-
-## A client id is a global name
-
-A provider resolves a client from the bare `client_id` a relying party sends — the adapter gets no
-tenant context — so the id is unique across the whole deployment, not per entity, and the store
-cannot namespace it on a consumer's behalf. Uniqueness has to be *in the id*.
-
-- Compose it with the owning entity in it. A name derived from a project's own name alone lets two
-  organizations share one registration: one secret, one redirect-URI list, one permission-definition
-  set, and one grant namespace, because `PermissionSet.scope` is that same string.
-- `ensureClient` refuses a record belonging to another entity rather than returning it. The failure
-  is deliberate — a loud provisioning error is the only alternative to a silent cross-tenant handover.
-- Assign an id **once** and reserve it with `claimClient`. Whatever a consumer derives ids from
-  (a project alias, a slug) may later be released and re-used by a sibling, so only the registry can
-  say whether an id is free. `deleteClient` gives it back, or a deleted project's name is burned.
-- Backends whose clients are already per-tenant (keycloak realms) satisfy this by construction:
-  `claimClient` returns true and `deleteClient` may be `IamUnsupported`.
-
-## `IamClient.realm` field
-
-`realm` is set by the provider to the entity ID. Use it instead of accessing internal properties:
-
-```ts
-// ✓ correct
-await meta.update('oidcRealm', client.realm ?? fallbackEntityId)
-
-// ✗ never do this — internal Keycloak implementation detail
-await meta.update('oidcRealm', (client as any)._realm)
-```
-
-## Issuer & redirect URIs
-
-**`getIssuerUrl(entityId)` is the only place an issuer URL may be composed.** Consumers pass the
-result straight through as `OidcProviderDescriptor.discoveryUrl`; they must never rebuild it from a
-host plus a base path. Each backend owns its own shape (keycloak `{iam-host}/realms/{entityId}`,
-integrated `{provider-host}/{basePath}`), and an implementation must:
-
-- resolve it from configuration only — no admin round-trip, so a consumer that just needs the issuer
-  never pays for or fails on a token grant;
-- return exactly what the provider advertises as `issuer` (`openid-client` compares the two and fails
-  discovery on any difference — build it with the same `makeUrl(..., { base: true })` call
-  `@owlmeans/server-oidc-provider` uses);
-- throw `IamClientError` when the provider's service route is missing, never fall back silently.
-
-`getEntityAdminConfig` additionally carries the same value as `discoveryUrl`, so the admin provider
-config is self-sufficient too.
-
-**Always pass `redirectUris`.** Omitting them is a keycloak-only legacy default (`['*']`, which
-Keycloak expands per-origin). The integrated provider does exact `redirect_uri` matching and
-`oidc-provider` refuses to load a client whose `redirect_uris` are not absolute URIs — so
-`iam-integrated.ensureClient` throws `IamClientError('redirect-uris')` on creation rather than
-registering a client that can never complete a callback. An omitted list never widens an existing
-hardened client.
-
-## Selecting the IAM provider
-
-The platform wires the correct implementation via the `IAM_MODE` environment variable. The default is **`integrated`** (the internal IAM); `IAM_MODE=keycloak` is opt-in, used mainly for custom / standalone customer production setups. Do not read `IAM_MODE` directly from feature code — it belongs in the service-factory only (the platform exposes `resolveIamMode()` / `isIntegratedIam()` from `viable-common`):
-
-```ts
-export const makeIamService = (mode = resolveIamMode()) => {
-  if (mode === IAM_MODE_KEYCLOAK) return makeIamKeycloakService(VIABLE_IAM, { oidcProductAlias: OIDC_PRODUCT })
-  // Pass the consumer's OWN service alias + base path: the package defaults ('manager-api',
-  // '/oidc') are placeholders, and a mismatch makes every cfg.services[...] lookup miss.
-  return makeIamIntegratedService(VIABLE_IAM, {
-    providerServiceAlias: MANAGER_API, providerBasePath: IAM_PROVIDER_BASE_PATH,
-  })
-}
-```
-
-When a context hosts **more than one** `IamService` instance (the viable agent registers both
-`viable-backend`'s and the agent library's), every instance must be constructed with the same
-options — otherwise they disagree about the issuer.
+| `IamPermissionError` | class | A refusal about a DEFINITION: `permission:held:<name>`, `permission:managed:<name>` |
+| `IamUserError` | class | An end-user operation was refused |
+| `IamOrganizationError` | class | An organization or membership refusal — unknown organization, last owner, membership cap |
+| `IamGroupError` | class | A group refusal — unknown key, an operator writing a managed group's structure, another app's group |
+| `IamUnsupported` | class | Operation not supported by the active backend (e.g. `resource-scoped-grant`, `user-management`) |
 
 ## Rules
 
-- Always depend on `IamService` from `@owlmeans/iam`, not on `KeycloakApiService` directly.
+- Always depend on `IamService`, never on a backend's own admin client.
 - Do not expose `getCredentialsPair` to request handlers — it returns a raw admin token.
-- `IamClientError` means the provisioned client was invalid (missing secret, null token). The proxy already throws it; callers only need to handle it, not re-throw wrapped errors.
-- The `realm` field on `IamClient` is guaranteed to be set by all concrete implementations.
-
-## Related instructions
-
-- `@owlmeans/iam-keycloak` (internal) — full proxy over Keycloak; see the `iam-keycloak` skill
-- `@owlmeans/keycloak` (internal) — low-level KC admin API; see the `keycloak` skill
-- `@owlmeans/server-iam` — IAM gate asserting both grant forms; see the `server-iam` skill
+- `IamClientError` means the provisioned client was invalid (missing secret, null token). The adapter
+  already throws it; callers handle it rather than re-throwing a wrapped error.
+- An operation a backend cannot support throws `IamUnsupported('<what>')`; a whole facet it cannot
+  support is `unsupportedFacet(what)`. Callers turn that into a fallback — an "external console"
+  link, a disabled control — rather than an error screen.
+- A wire value names an organization by `entitySlug` only; the `entityId` parameter is the client's
+  OWNER, resolved server-side, never taken from a token or a request.
+
+## Related
+
+- `@owlmeans/server-iam` — the IAM gate that asserts every permission kind, the gate-param grammar,
+  the session's organizations and the runtime IAM client; see the `server-iam` skill
+- `@owlmeans/client-iam` — browser wiring, the organization switch and `hasPermission`; see the
+  `client-iam` skill
+- `@owlmeans/oidc` — provider descriptors and the `iamMode` config seam; see the `oidc` skill
+- The concrete adapters (a Keycloak proxy, and the integrated backend built on
+  `@owlmeans/server-oidc-provider` plus `@owlmeans/server-auth-identity`) ship separately and are
+  reached only through `IamService`.
+
+## Parts
+
+| Part | Load it when |
+|---|---|
+| [permissions](parts/permissions.md) | declaring, granting, revoking or checking a permission, or reasoning about what a subject holds |
+| [service](parts/service.md) | calling IamService methods, or implementing a new IAM provider |
+| [tenancy](parts/tenancy.md) | working with tenanted clients, organizations, members or groups, or the runtime IAM API |
+| [clients](parts/clients.md) | provisioning a client, composing an issuer URL, or choosing between the integrated and Keycloak backends |