@owlmeans/iam 0.1.18-rc.5 → 0.1.18-rc.50

package/README.md

@@ -6,14 +6,16 @@ Provider-agnostic IAM abstraction for the OwlMeans framework — `IamService` in
 
 - `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
+- `IamPermissionArgs` — describes a named permission: resource and organization binding (`resourceScoped`, `entityScoped`), title, area and `defaultClass`
+- Tenancy facets on `IamService` — `organizations`, `groups`, `subjects` — and `unsupportedFacet` for a backend without them
+- `makeIamRuntimeProtocols` — declarations of the provider's runtime IAM API (organizations, members, permissions, grants)
+- `hasPermission` — utility to check whether a set of grants covers a given permission, resource and acting organization
+- Errors: `IamError` and subtypes for client, permission, user, organization and group failures
 
 ## Installation
 
 ```bash
-bun add @owlmeans/iam
+bun add @owlmeans/iam@^0.1.18-rc.50
 ```
 
 ## Usage
@@ -22,8 +24,8 @@ bun add @owlmeans/iam
 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 })
+// Check whether an auth payload grants a permission for one record, in the organization the request acts in
+const allowed = hasPermission(auth, 'order--edit', { resourceId: 'ord-1', entitySlug: 'acme' })
 ```
 
 Typically consumed via `@owlmeans/server-iam` which wires the concrete OIDC-backed implementation.
@@ -36,7 +38,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-rc.49
 ```
 
 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,
   "package": "@owlmeans/iam",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.504Z",
+  "version": "0.1.18-rc.50",
+  "generatedAt": "2026-10-05T21:03:06.386Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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,33 +8,84 @@ 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-rc.50"` 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 below); `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? }` |
-| `hasPermission` | fn | `(auth, permission, { scope?, resourceId? }?)` — checks `Authorization.permissions` PermissionSet[]; an unscoped set satisfies a resourceId check |
+| `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") |
+| `IamGrantArgs` | type | `{ resources?, mode?, entitySlug? }` — `entitySlug` binds an `entityScoped` grant |
+| `IamGrant` | type | `{ profileId? \| group?, clientId, permission, resources?, mode?, entitySlug?, origin?, through? }` — exactly one subject |
+| `IamGrantOrigin` | enum | `Direct` / `Default` / `Group` — why a listed grant is held; `through` names the group |
+| `IamGroupRef` | type | `{ entitySlug, key }` — a group by its organization's slug and its key |
+| `IamGrantMode` | enum | `Blanket` / `Resources` / `All` — which FORM of a grant an operation addresses |
+| `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? }` — `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 |
+| `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" |
+| `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) |
+| `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, a managed group written by an operator, another app's group |
+| `IamUnsupported` | class | Operation not supported by the active backend (e.g. `resource-scoped-grant`, `user-management`) |
 
-## Permission model (two grant forms)
+## Permission model (kinds and grant forms)
 
 Permissions are declared per entity client (project) with `ensurePermission` and granted to end-user
 subjects with `grantPermission`:
@@ -46,58 +97,244 @@ subjects with `grantPermission`:
 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).
 
+A **name** is `<resource>--<action>`, with two hyphens. One hyphen is not a separator: `enquiry-view`
+is a resource named `enquiry-view` with no action, and it must keep parsing that way, because a name
+already granted somewhere cannot be reinterpreted without orphaning the grant. Build and read names
+through `composePermissionName` / `parsePermissionName` rather than splitting strings.
+
+`resourceScoped: true` says a permission *may* be bound to resource ids, not that it must be. The
+same name is grantable in both forms and they are stored separately, which is what `IamGrantMode`
+addresses: `Blanket` is the set carrying no `resources` (and `hasPermission` reads it as covering
+every id), `Resources` is an explicit id list, and `All` is revoke-only. The defaults are asymmetric
+on purpose — `grantPermission` defaults to `Blanket`, `revokePermission` to `All`, because a bare
+revoke has always meant "remove it everywhere". Pass `mode` explicitly rather than relying on either.
+
+`area` is a presentational grouping tag (`IAM_AREAS`, or any string a deployment defines) and decides
+nothing at request time. `managed: true` marks a definition the platform owns: an operator cannot
+revoke it from an undifferentiated list, and a repair that deletes "definitions no declaration names"
+must not reach one.
+
+### Permission kinds
+
+What a grant binds to is a property of the DEFINITION, and grants follow it:
+
+| Kind | Definition flags | Grant stored on | Applies |
+|---|---|---|---|
+| unbound | none | the subject's primary row, or a group | everywhere |
+| entity-bound | `entityScoped` | the subject's row of THAT organization, or a group of it | only while acting in that organization |
+| resource-bound | `resourceScoped` | the primary row, a titled set with `resources` | to those resource ids |
+| both | both | that organization's row, a titled set with `resources` | both checks |
+
+- Granting an `entityScoped` definition REQUIRES `args.entitySlug`, which names the subject's row
+  there — the subject must be a member. Any other definition refuses `args.entitySlug`. Turning
+  `entityScoped` off while grants exist is refused: every bound grant would silently widen.
+- Stored sets carry the organization's id; CLAIM sets (provider → relying party only) carry its
+  `entitySlug` instead (`OidcPermissionSetClaim`). The relying party keeps the unbound sets and the
+  acting organization's, strips the binding, and drops the rest — a browser token never carries a
+  bound set of another organization.
+- `hasPermission(auth, name, { entitySlug })` applies a set without `entitySlug` everywhere and a
+  bound one only when `opts.entitySlug` names its organization — fail-closed, so a bound set that
+  leaked into a token never counts where the caller named no organization.
+
+### Default classes
+
+`defaultClass` says who holds a definition without an explicit grant. It is evaluated when claims and
+grant listings are built — never written onto a row:
+
+- `User` — every signed-in subject of the client. Requires an unbound, unmanaged `user`-area definition.
+- `Member` / `Owner` — every member / owner of the organization the subject acts in. Requires
+  `entityScoped`.
+- `None` — nobody.
+
+A class default is a BLANKET set, so `Owner` on a resource-scoped definition is its all-records form.
+An explicit `false` on a row suppresses only the class default of that binding (an unbound `false`
+suppresses `User`; a `false` on the row of an organization suppresses `Member`/`Owner` there).
+Grants are additive — there is no deny rule over a group's grant. A listing marks each grant's
+`origin`: `Direct`, `Default`, or `Group` with `through` naming the group. A backend that cannot
+evaluate classes (Keycloak) refuses any `defaultClass` other than `None` with `IamUnsupported`.
+
 ## `IamService` interface
 
 ```ts
 interface IamService extends InitializedService {
-  // Get the admin OIDC provider config for a tenant (used in payment provisioning, RP config)
+  // The tenant's admin OIDC provider config, and a raw admin { token, realm } pair.
   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.
+  // The tenant's public issuer URL — see "Issuer & redirect URIs".
   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").
+  // Provision an OIDC client for a tenant — see "Issuer & redirect URIs" and
+  // "A client id is a global name" for the two rules it has to obey.
   ensureClient: (entityId: string, clientId: string, options?: IamClientOptions) => Promise<IamClient>
 
-  // Provision a named permission on a client resource; returns the resource name
+  // The entity's client without its secret, or null. Never provisions.
+  getClient: (entityId: string, clientId: string) => Promise<IamClientInfo | null>
+
+  // 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 — its subjects' rows, its groups, its
+  // definitions (called when a project/slot is deleted).
+  deleteClient: (entityId: string, clientId: string) => Promise<void>
+
+  // Declare a permission. Returns the canonical name. MERGES into an existing definition —
+  // resource/action re-derived, omitted flags kept — and NEVER rewrites the name. Refuses a
+  // `resource` carrying an `@` selector.
   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)
+  // Remove definitions BY NAME, and by default their grants. Idempotent ({ found: false } when
+  // absent). Grants go first: a crash between the stores must leave a definition with no grants,
+  // never grants with no definition. A `managed` definition needs args.managed === true.
+  deletePermission: (entityId: string, clientId: string, permission: string | string[], args?: IamPermissionDeleteArgs) => Promise<IamPermissionRemoval[]>
+
+  // Repair definitions whose stored name leaked a gate selector, moving grants in the same write.
+  // A rename and a merge — never a delete, never an invention.
+  normalizePermissions: (entityId: string, clientId: string, args?: IamNormalizeArgs) => Promise<IamNormalizationReport>
+
+  // Provision a resource and assign it to the tenant's owner role (keycloak). A no-op on the
+  // integrated backend, which has no owner role to assign to.
   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[]>
+  listPermissions: (entityId: string, clientId: string, filter?: IamPermissionFilter) => Promise<IamPermissionDefinition[]>
 
-  // Grant a permission to an end-user subject; args.resources = resource-scoped form
+  // args.resources selects the resource-scoped form, args.entitySlug the binding of an entityScoped
+  // definition; see "Permission model (kinds and grant forms)"
   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
+  // Grant everything a bundle selects to each subject, idempotently, in ONE read and write per
+  // subject. Returns what each subject now holds, not what changed. Use it instead of looping over
+  // grantPermission, which costs N·M writes and N·M lost-update windows on the same records.
+  grantBundle: (entityId: string, clientId: string, profileIds: string[], bundle: IamGrantBundle) => Promise<IamGrant[]>
+
+  // Direct, default-class and group grants, each with its `origin`.
   listGrants: (entityId: string, clientId: string, profileId?: string) => Promise<IamGrant[]>
-}
-```
 
-## `IamClient.realm` field
+  // --- Users of one client — see "Users are per client" ---
 
-`realm` is set by the provider to the entity ID. Use it instead of accessing internal properties:
+  listUsers: (entityId: string, clientId?: string) => Promise<IamUser[]>
+  getUser: (entityId: string, clientId: string, profileId: string) => Promise<IamUser | null>
+  inviteUser: (entityId: string, clientId: string, invite: IamUserInvite) => Promise<IamUser>
+  updateUser: (entityId: string, clientId: string, profileId: string, update: IamUserUpdate) => Promise<IamUser>
+  removeUser: (entityId: string, clientId: string, profileId: string) => Promise<void>
 
-```ts
-// ✓ correct
-await meta.update('oidcRealm', client.realm ?? fallbackEntityId)
+  // The owning organization's staff, admitted to the client through the managed `members` group.
+  syncStaff: (entityId: string, clientId: string, args: IamStaffSyncArgs) => Promise<IamStaffSyncReport>
 
-// ✗ never do this — internal Keycloak implementation detail
-await meta.update('oidcRealm', (client as any)._realm)
+  // --- Tenancy facets — see "Organizations, groups and subjects" ---
+  organizations: IamOrganizationFacet
+  groups: IamGroupFacet
+  subjects: IamSubjectFacet
+}
 ```
 
+The first parameter of every method is `entityId` — the organization that OWNS the client — and
+every `(entityId, clientId)` method verifies that ownership before it reads or writes anything. The
+organizations a client's subjects act in are a different thing, named by `entitySlug` inside the
+facets.
+
+## Users are per client
+
+A person is ONE account (one per e-mail address); what a client sees of it are its rows of that app —
+one per (account, app, organization), the PRIMARY one in the account's own organization. The
+`profileId` a client knows is the pairwise subject, the same on every row of one (account, app) and
+different for every app, so two apps of one customer cannot correlate their users by it.
+
+- `listUsers(entityId, clientId)` lists every account holding a row of the client, in whichever
+  organization. Without `clientId` it is a read-only aggregate over the entity's clients, for a
+  console — nothing is written through it.
+- `getUser` / `inviteUser` / `updateUser` / `removeUser` take the client. `removeUser` deletes this
+  account's rows of THAT app only — the account, and its rows of other apps, stay. `updateUser`
+  writes `disabled` on the primary row, which is what refuses the subject at the provider.
+- `inviteUser` is idempotent by email, which is what lets an invitation and a first sign-in converge on
+  one record instead of accumulating twins.
+
+A backend with no user store of its own — one where the customer manages users in the provider's own
+console — throws `IamUnsupported('user-management')` from all five methods.
+
+## Organizations, groups and subjects
+
+The three facets of `IamService` carry tenancy. A backend that cannot provide one answers
+`unsupportedFacet<IamOrganizationFacet>('organizations')` (and so on): every method of it throws
+`IamUnsupported(what)` SYNCHRONOUSLY, because `subjects.identify` is synchronous and a rejected
+promise would hand it the wrong type — an awaited call rejects either way.
+
+- **Tenancy is the client's configuration.** `IamClientConfig.users` / `.operators` turn it on: with
+  neither flag, every subject acts in the client's owning organization (a single-tenant app); with
+  either, each subject acts in organizations of its own and the provider claims them under the
+  `organizations` scope (`@owlmeans/oidc`). The flags also gate the runtime API's writes by area.
+- **`organizations`** — `list`, `get`, `create({ title?, profileId? })` (that subject becomes the
+  owner), `update({ title })`, `members`, `addMember` (find-or-create by e-mail, idempotent, refused
+  past the membership cap), `updateMember`, `removeMember`. The last owner cannot be demoted or
+  removed (`IamOrganizationError`).
+- **`groups`** — a group is (organization, client, key), kept inside the organization record; one
+  client never reads or writes another's. `list`, `ensure`, `remove`, `members`, `addMembers`,
+  `removeMembers`, `grant` / `revoke` (bound to the group's organization), `grants`, and
+  `setBundles` — a bundle (`{ filter?, permissions? }`) grants every definition it selects to the
+  group's members at claim time. `IAM_MEMBERS_GROUP` is the managed group `syncStaff` keeps in the
+  owning organization; it is read-only to an operator (`IamGroupError`).
+- **`subjects`** — the provider's half, keyed by the ACCOUNT, which never leaves the provider.
+  `signIn(clientId, { email })` finds or creates the account and its rows for the client;
+  `resolve(clientId, accountId)` builds the `IamSubject` the claims come from (`null` = not admitted:
+  no row, or a disabled primary row); `identify(clientId, accountId)` is the pairwise `sub`.
+
+## Runtime IAM API
+
+`makeIamRuntimeProtocols({ service, path? })` declares the provider-side API a tenanted client's
+server calls on behalf of its signed-in subject. It is declarations only: the provider binds it, and
+a relying party calls it through `iamRuntime` (`@owlmeans/server-iam`) over plain `fetch`.
+
+| Route (under `path`, default `IAM_RUNTIME_PATH`) | Tree | Who |
+|---|---|---|
+| `GET /organizations` | `organizations.list` | any subject — its own |
+| `POST /organizations` `{ title? }` | `organizations.create` | any subject of a tenanted client; it becomes owner |
+| `POST /organizations/:entitySlug` `{ title }` | `organizations.update` | owner |
+| `GET /organizations/:entitySlug/members` | `members.list` | member |
+| `POST /organizations/:entitySlug/members` `{ email, name?, owner? }` | `members.add` | owner; idempotent by e-mail |
+| `POST …/members/:profileId` `{ owner?, groups? }` | `members.update` | owner |
+| `POST …/members/:profileId/remove` | `members.remove` | owner, or the member itself |
+| `GET …/permissions` | `permissions.list` | member |
+| `GET …/grants` `?profileId` | `grants.list` | owner |
+| `POST …/grants`, `POST …/grants/revoke` `{ profileId, permission, resources?, mode? }` | `grants.assign` / `grants.revoke` | owner |
+
+- **Every route, the base included, is pinned to `service`** — a route's service is never inherited
+  from its parent — and every leaf hangs under ONE base carrying `IAM_RUNTIME_GUARD`. The serving
+  process registers that guard: it admits only a bearer access token the provider issued, and takes
+  the client and the account from it, never from the request.
+- **The wire names organizations by `entitySlug` and subjects by the calling client's pairwise
+  `profileId`** — no organization or account id appears in any shape. Every schema is closed, since
+  the server's AJV strips an undeclared key silently. `IAM_RUNTIME_ROUTES` is the one leaf-path table
+  the declarations and the fetch client share.
+- The serving process enforces the write rules: only `entityScoped`, unmanaged definitions of the
+  CALLING client, binding forced to the path's organization, the last owner protected, the
+  membership cap, and only for an area the client's tenancy config opens (`users` → `user`,
+  `operators` → `operator`). A non-owner write is `AuthForbidden(ORGANIZATION_OWNER_REFUSAL)`.
+
+## 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
+
+Every implementation sets `realm` to the entity id, so read `client.realm ?? fallbackEntityId` and
+never reach into an adapter's own internals (`(client as any)._realm`) for the same value.
+
 ## Issuer & redirect URIs
 
 **`getIssuerUrl(entityId)` is the only place an issuer URL may be composed.** Consumers pass the
@@ -117,39 +354,67 @@ 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
+`oidc-provider` refuses to load a client whose `redirect_uris` are not absolute URIs — so an
+integrated backend's `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
+## Selecting the IAM backend
 
-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`):
+The choice is made **once, in a service factory**, and nowhere else. Feature code depends on
+`IamService` and never learns which implementation answers it. `IAM_MODE_INTEGRATED` /
+`IAM_MODE_KEYCLOAK` and `OidcIamConfig.iamMode` (`@owlmeans/oidc`) exist so a deployment can carry
+that choice as ordinary configuration rather than as a branch scattered through handlers. No OwlMeans
+package reads `iamMode`; it is declared for the consumer's own factory to switch on, which is the
+only thing that may branch.
 
 ```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,
-  })
-}
+import { DEFAULT_ALIAS, IAM_MODE_INTEGRATED, IAM_MODE_KEYCLOAK } from '@owlmeans/iam'
+import type { IamMode, IamService } from '@owlmeans/iam'
+
+// makeKeycloakAdapter / makeIntegratedAdapter are PLACEHOLDER names standing in for whichever
+// adapter packages the deployment installs — this factory is the one place either is named, and
+// every consumer resolves IamService by alias instead. An adapter exposes a
+// `(alias?: string, options?: object) => IamService` factory whose alias defaults to DEFAULT_ALIAS.
+export const makeIamService = (mode: IamMode = IAM_MODE_INTEGRATED): IamService =>
+  mode === IAM_MODE_KEYCLOAK
+    ? makeKeycloakAdapter(DEFAULT_ALIAS, /* adapter options */)
+    : makeIntegratedAdapter(DEFAULT_ALIAS, /* adapter options */)
+
+// cfg.oidc typed as OidcSharedConfig & OidcIamConfig is what carries the mode
+context.registerService(makeIamService(cfg.oidc?.iamMode))
 ```
 
-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.
+An adapter that reassembles the issuer from a registered service alias plus a base path must be given
+the **consumer's own** alias and path. Whatever an adapter defaults to is a placeholder, and a
+mismatch makes every service lookup behind `getIssuerUrl` miss.
 
-## Rules
+An integrated backend — one built on `@owlmeans/server-oidc-provider`, so the deployment hosts its
+own provider — is the default choice; a Keycloak-backed adapter exists for deployments that already
+run one.
 
-- Always depend on `IamService` from `@owlmeans/iam`, not on `KeycloakApiService` directly.
-- 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.
+When a context hosts **more than one** `IamService` instance, every instance must be constructed with
+the same options — otherwise they disagree about the issuer, and only one of them can be right.
 
-## Related instructions
+## Rules
 
-- `@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
+- 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 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`.