@owlmeans/iam 0.1.18-rc.46 → 0.1.18-rc.48

package/README.md

@@ -15,7 +15,7 @@ Provider-agnostic IAM abstraction for the OwlMeans framework — `IamService` in
 ## Installation
 
 ```bash
-bun add @owlmeans/iam@^0.1.18-rc.46
+bun add @owlmeans/iam@^0.1.18-rc.48
 ```
 
 ## Usage
@@ -38,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@^0.1.18-rc.45
+npx @owlmeans/agent-skills@^0.1.18-rc.47
 ```
 
 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.46",
-  "generatedAt": "2026-10-01T23:27:48.730Z",
+  "version": "0.1.18-rc.48",
+  "generatedAt": "2026-10-03T20:05:07.591Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -8,7 +8,7 @@ metadata:
 
 # Using `@owlmeans/iam`
 
-**Install:** `"@owlmeans/iam": "^0.1.18-rc.46"` in `dependencies`
+**Install:** `"@owlmeans/iam": "^0.1.18-rc.48"` 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
@@ -16,41 +16,13 @@ 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.
 
-## The browser half — `@owlmeans/client-iam`
-
-`@owlmeans/client-iam` has no skill of its own because it is a wiring package: it re-exports these
-types and `hasPermission`, and adds the two calls that turn "this application uses IAM" into two
-lines.
-
-| Export | Description |
-|--------|-------------|
-| `appendIam(context, opts?)` | Wires the OIDC guard onto a web context **and** installs the consent-before-sign-in precondition |
-| `withIamGuard(protocolTree, coguards?)` | Returns a decorated immutable protocol tree with IAM's OIDC guard applied |
-| `iamEntrypoints(dispatcherProps?)` | Browser-local OIDC bindings and dispatcher-screen binding |
-| `requireConsentForLogin(ctx, opts?)` | That precondition on its own, for a context wired some other way |
-| `CONSENT_LOGIN_PRECONDITION` / `CLIENT_IAM_SERVICE` | The precondition alias and the service alias |
-| `useLogin` / `useLogout`, `LoginOutcome` / `LoginIntent`, `LoginPlugin` / `LoginService` / … | Re-exported sign-in surface, so an app has one IAM import rather than three |
-| `listOrganizations(ctx)` | The signed-in subject's organizations (`OidcOrganizationItem[]`, the acting one marked `acting`) over `oidcProtocols.organizations` |
-| `switchOrganization(ctx, entitySlug)` | Moves the session into another of its organizations over `oidcProtocols.organization` and adopts the re-signed token with `adoptToken` |
-| `ORGANIZATION_REFUSAL` / `ORGANIZATION_OWNER_REFUSAL` | Re-exported from `@owlmeans/oidc`: the `AuthForbidden` reasons a screen phrases (not a member; not the owner) |
-| Everything from `@owlmeans/iam` | The types above, plus `hasPermission` |
-
-The protocol tree is immutable. Decorate it once with `withIamGuard(protocols)` before binding local
-screens and API callers, then spread `iamEntrypoints()` once into that browser binding list. The
-helper deliberately does not add declarations to a flattened entrypoint array.
-
-And the consent precondition sits on `LoginService.begin` rather than on a hook, a screen or a login
-plugin, because `begin` is the single funnel every sign-in mechanic passes through and the one place
-the user's gesture is still live — a refusal resolves as `LoginOutcome.Gesture` and opens the consent dialog in
-the same gesture. An application that genuinely sets no cookie passes `{ consent: { disabled: true } }`.
-
-Both organization calls need the bindings `iamEntrypoints()` spreads, and both are answered by the
-application's own server from the session it holds — there is no per-request organization selector,
-so a screen that offers "act in another organization" calls `switchOrganization` and re-reads `auth`.
-
-The server half of the same story is `@owlmeans/server-iam` — the IAM gate that asserts the grants
-this package's screens hand out, and the runtime IAM client. Permission decisions are made there,
-never in the browser.
+## 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
 
@@ -220,7 +192,8 @@ interface IamService extends InitializedService {
   // 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
+  // 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) ---
@@ -298,7 +271,7 @@ promise would hand it the wrong type — an awaited call rejects either way.
   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. `ensure`, `remove`, `members`, `addMembers`,
+  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
@@ -359,8 +332,8 @@ cannot namespace it on a consumer's behalf. Uniqueness has to be *in the id*.
 
 ## `IamClient.realm` field
 
-`realm` is set by the provider 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.
+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
 
@@ -429,7 +402,6 @@ the same options — otherwise they disagree about the issuer, and only one of t
 - 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.
-- `IamClient.realm` is set by every concrete implementation.
 - 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.
@@ -440,6 +412,8 @@ the same options — otherwise they disagree about the issuer, and only one of t
 
 - `@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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/iam",
-  "version": "0.1.18-rc.46",
+  "version": "0.1.18-rc.48",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,11 +22,11 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.37",
+    "@owlmeans/auth": "^0.1.18-rc.38",
     "@owlmeans/context": "^0.1.18-rc.32",
-    "@owlmeans/entrypoint": "^0.1.18-rc.38",
+    "@owlmeans/entrypoint": "^0.1.18-rc.39",
     "@owlmeans/error": "^0.1.18-rc.36",
-    "@owlmeans/oidc": "^0.1.18-rc.51",
+    "@owlmeans/oidc": "^0.1.18-rc.53",
     "@owlmeans/route": "^0.1.18-rc.33"
   },
   "peerDependencies": {