@owlmeans/iam 0.1.18-rc.3 → 0.1.18-rc.31

package/README.md

@@ -13,7 +13,7 @@ Provider-agnostic IAM abstraction for the OwlMeans framework — `IamService` in
 ## Installation
 
 ```bash
-bun add @owlmeans/iam
+bun add @owlmeans/iam@^0.1.18-rc.31
 ```
 
 ## Usage
@@ -36,7 +36,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.27
 ```
 
 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.31",
+  "generatedAt": "2026-09-15T13:20:58.250Z",
   "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 and two-form grant model, client-id uniqueness, issuer and redirect-URI rules, and hasPermission. Load when wiring IAM operations, granting or revoking permissions, 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,7 +8,40 @@ 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.31"` in `dependencies`
+
+Provider-agnostic IAM abstraction: the `IamService` interface, the permission and grant shapes, the
+gate-param grammar, and `hasPermission`. 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.
+
+## 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 |
+| 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 } }`.
+
+The server half of the same story is `@owlmeans/server-iam` — the IAM gate that asserts the grants
+this package's screens hand out. Permission decisions are made there, never in the browser.
 
 ## Public API surface
 
@@ -18,21 +51,38 @@ Provider-agnostic IAM abstraction. Defines `IamService` interface and related ty
 | `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) |
 | `IamCredentialsPair` | type | `{ token: string; realm: string }` |
-| `IamPermissionArgs` | type | `{ permission?, resourceScoped?, title? }` — `permission` absent means unscoped resource name |
+| `IamPermissionArgs` | type | `{ permission?, resourceScoped?, title?, area?, managed? }` — `permission` absent means unscoped resource name |
 | `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? }` |
+| `IamPermissionDefinition` | type | Declared permission `{ name, resource, action?, resourceScoped?, title?, area?, managed? }` |
+| `IamPermissionFilter` | type | `{ areas?, managed?, resourceScoped? }` — narrows `listPermissions`; an `areas` entry of `null` matches untagged definitions |
+| `IamGrantArgs` | type | `{ resources?: string[], mode? }` |
+| `IamGrant` | type | `{ profileId, clientId, permission, resources?, mode? }` |
+| `IamGrantMode` | enum | `Blanket` / `Resources` / `All` — which FORM of a grant an operation addresses |
+| `IamGrantBundle` | type | `{ filter?, permissions?, mode?, resources? }` — 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 | End-user of an entity `{ profileId, email?, name?, role, disabled?, grantCount? }` |
+| `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 |
+| `HasPermissionOptions` | type | `{ scope?, resourceId? }` |
+| 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 |
+| `IamUnsupported` | class | Operation not supported by the active backend (e.g. `resource-scoped-grant`, `user-management`) |
 
 ## Permission model (two grant forms)
 
@@ -46,57 +96,120 @@ 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.
+
 ## `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
+  // 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>
+
+  // 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
   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; see "Permission model (two 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[]>
+
   listGrants: (entityId: string, clientId: string, profileId?: string) => Promise<IamGrant[]>
+
+  // --- End-user management — see "End-users are customer-wide" ---
+
+  listUsers: (entityId: string, clientId?: string) => Promise<IamUser[]>
+  getUser: (entityId: string, profileId: string) => Promise<IamUser | null>
+  inviteUser: (entityId: string, invite: IamUserInvite) => Promise<IamUser>
+  updateUser: (entityId: string, profileId: string, update: IamUserUpdate) => Promise<IamUser>
+  removeUser: (entityId: string, profileId: string) => Promise<void>
 }
 ```
 
-## `IamClient.realm` field
+## End-users are customer-wide
 
-`realm` is set by the provider to the entity ID. Use it instead of accessing internal properties:
+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.
 
-```ts
-// ✓ correct
-await meta.update('oidcRealm', client.realm ?? fallbackEntityId)
+`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.
 
-// ✗ never do this — internal Keycloak implementation detail
-await meta.update('oidcRealm', (client as any)._realm)
-```
+## 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, 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
 
@@ -117,39 +230,63 @@ 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.
+- `IamClient.realm` is set by every concrete implementation.
+- An operation a backend cannot support throws `IamUnsupported('<what>')`. Callers turn that into a
+  fallback — an "external console" link, a disabled control — rather than an error screen.
+
+## Related
+
+- `@owlmeans/server-iam` — the IAM gate that asserts both grant forms, and the gate-param grammar;
+  see the `server-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`.

package/build/consts.d.ts

@@ -2,4 +2,95 @@ export declare const DEFAULT_ALIAS = "iam-service";
 export declare const IAM_MODE_KEYCLOAK = "keycloak";
 export declare const IAM_MODE_INTEGRATED = "integrated";
 export type IamMode = typeof IAM_MODE_KEYCLOAK | typeof IAM_MODE_INTEGRATED;
+/**
+ * Gate-param syntax: `<permission>[@<selector>]`.
+ *
+ * The `@` belongs to the GATE and to nothing else. It says where a resource id is read from at
+ * request time; it is never part of a permission's stored NAME. A definition or a grant whose name
+ * carries one is a key nothing ever looks up, so every grant against it is a silent no-op.
+ */
+export declare const RESOURCE_PARAM_SEPARATOR = "@";
+/**
+ * Separates an explicit source from its path: `@body:order.id`.
+ *
+ * Deliberately `:` rather than a dot. Under a dotted-only form the meaning of a selector changes the
+ * moment a route gains a param named like a source keyword — `/report/:query` with `@query.id` flips
+ * from "the route param literally named `query.id`" to "the query string's `id`", redirecting an
+ * authorization lookup from a router-matched value to attacker-supplied input, caused by an
+ * unrelated route rename. `:` is decidable in one character, and no gate-param string written before
+ * this existed can contain one.
+ */
+export declare const RESOURCE_SOURCE_SEPARATOR = ":";
+/** Separates path segments inside a qualified selector: `@body:order.id`. */
+export declare const RESOURCE_PATH_SEPARATOR = ".";
+/** Where a qualified selector may read a resource id from. */
+export declare enum GateParamSource {
+    Params = "params",
+    Query = "query",
+    Body = "body",
+    Headers = "headers",
+    Auth = "auth"
+}
+/**
+ * What the bare form (`@enquiryId`) searches, in order.
+ *
+ * Params first, then query. The query fallback is legacy and deliberately kept: removing it would
+ * silently deny already-deployed applications whose selector happens to name a query key, and a
+ * silent denial inside a customer's running app is the worst available outcome.
+ */
+export declare const DEFAULT_GATE_PARAM_SOURCES: GateParamSource[];
+/** Why a gate param is structurally wrong — a misconfiguration, not a failed authorization. */
+export declare enum GateParamErrorCode {
+    UnknownSource = "gate-param:unknown-source",
+    EmptySelector = "gate-param:empty-selector",
+    EmptySegment = "gate-param:empty-segment",
+    /** Named a request key the entrypoint's filter does not declare — AJV strips it before the gate. */
+    UnreachableKey = "gate-param:unreachable-key",
+    /** Named a route param the entrypoint's own path does not carry. */
+    UnknownRouteParam = "gate-param:unknown-route-param"
+}
+/** Why a selector produced no resource id. */
+export declare enum GateResolutionFailure {
+    /** The source exists, the path does not. */
+    NotProvided = "not-provided",
+    /** The request carries no such source at all. */
+    SourceMissing = "source-missing",
+    /** Resolved to an object or a multi-element array — refused rather than stringified. */
+    NotScalar = "not-scalar",
+    /** The selector itself did not parse. */
+    Malformed = "malformed"
+}
+/**
+ * Which FORM of a grant an operation addresses.
+ *
+ * A resource-scoped permission is grantable two ways, under one name: `Blanket` (a PermissionSet
+ * carrying no `resources`, which `hasPermission` reads as covering every id) and `Resources` (an
+ * explicit id list). They are stored separately and must be revoked separately, or a UI offering
+ * both controls would have one silently wipe the other.
+ */
+export declare enum IamGrantMode {
+    Blanket = "blanket",
+    Resources = "resources",
+    /** Revoke-only: every form. Illegal on a grant. */
+    All = "all"
+}
+/** What to do about grants that still reference a definition being removed. */
+export declare enum IamRemovalPolicy {
+    /** Strip the permission from every subject of the entity, then drop the definition. */
+    Cascade = "cascade",
+    /** Refuse while any subject still holds it; the holders travel in the error. */
+    Refuse = "refuse"
+}
+/**
+ * The grouping tiers a permission definition may be tagged with.
+ *
+ * A tag decides NOTHING at request time — `hasPermission` and every gate treat a permission name as
+ * one opaque string — and only groups the permission in an administrator's screen. `guest` is
+ * deliberately absent: a public surface declares no permissions, and adding an area later would
+ * re-classify names already tagged.
+ */
+export declare const IAM_AREAS: readonly ['user', 'operator', 'admin'];
+export type IamArea = typeof IAM_AREAS[number];
+/** Separates the resource from the action in a permission name. TWO hyphens, never one. */
+export declare const PERMISSION_ACTION_SEPARATOR = "--";
 //# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,gBAAgB,CAAA;AAE1C,eAAO,MAAM,iBAAiB,aAAa,CAAA;AAC3C,eAAO,MAAM,mBAAmB,eAAe,CAAA;AAE/C,MAAM,MAAM,OAAO,GAAG,OAAO,iBAAiB,GAAG,OAAO,mBAAmB,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,gBAAgB,CAAA;AAE1C,eAAO,MAAM,iBAAiB,aAAa,CAAA;AAC3C,eAAO,MAAM,mBAAmB,eAAe,CAAA;AAE/C,MAAM,MAAM,OAAO,GAAG,OAAO,iBAAiB,GAAG,OAAO,mBAAmB,CAAA;AAE3E;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAE3C;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAA;AAE5C,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,MAAM,CAAA;AAE1C,8DAA8D;AAC9D,oBAAY,eAAe;IACzB,MAAM,WAAW;IACjB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,IAAI,SAAS;CACd;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,EAAE,eAAe,EAEvD,CAAA;AAED,+FAA+F;AAC/F,oBAAY,kBAAkB;IAC5B,aAAa,8BAA8B;IAC3C,aAAa,8BAA8B;IAC3C,YAAY,6BAA6B;IACzC,oGAAoG;IACpG,cAAc,+BAA+B;IAC7C,oEAAoE;IACpE,iBAAiB,mCAAmC;CACrD;AAED,8CAA8C;AAC9C,oBAAY,qBAAqB;IAC/B,4CAA4C;IAC5C,WAAW,iBAAiB;IAC5B,iDAAiD;IACjD,aAAa,mBAAmB;IAChC,wFAAwF;IACxF,SAAS,eAAe;IACxB,yCAAyC;IACzC,SAAS,cAAc;CACxB;AAED;;;;;;;GAOG;AACH,oBAAY,YAAY;IACtB,OAAO,YAAY;IACnB,SAAS,cAAc;IACvB,mDAAmD;IACnD,GAAG,QAAQ;CACZ;AAED,+EAA+E;AAC/E,oBAAY,gBAAgB;IAC1B,uFAAuF;IACvF,OAAO,YAAY;IACnB,gFAAgF;IAChF,MAAM,WAAW;CAClB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,YAAI,MAAM,EAAE,UAAU,EAAE,OAAO,CAAU,CAAA;AAE/D,MAAM,MAAM,OAAO,GAAG,OAAO,SAAS,CAAC,MAAM,CAAC,CAAA;AAE9C,2FAA2F;AAC3F,eAAO,MAAM,2BAA2B,OAAO,CAAA"}

package/build/consts.js

@@ -1,4 +1,101 @@
 export const DEFAULT_ALIAS = 'iam-service';
 export const IAM_MODE_KEYCLOAK = 'keycloak';
 export const IAM_MODE_INTEGRATED = 'integrated';
+/**
+ * Gate-param syntax: `<permission>[@<selector>]`.
+ *
+ * The `@` belongs to the GATE and to nothing else. It says where a resource id is read from at
+ * request time; it is never part of a permission's stored NAME. A definition or a grant whose name
+ * carries one is a key nothing ever looks up, so every grant against it is a silent no-op.
+ */
+export const RESOURCE_PARAM_SEPARATOR = '@';
+/**
+ * Separates an explicit source from its path: `@body:order.id`.
+ *
+ * Deliberately `:` rather than a dot. Under a dotted-only form the meaning of a selector changes the
+ * moment a route gains a param named like a source keyword — `/report/:query` with `@query.id` flips
+ * from "the route param literally named `query.id`" to "the query string's `id`", redirecting an
+ * authorization lookup from a router-matched value to attacker-supplied input, caused by an
+ * unrelated route rename. `:` is decidable in one character, and no gate-param string written before
+ * this existed can contain one.
+ */
+export const RESOURCE_SOURCE_SEPARATOR = ':';
+/** Separates path segments inside a qualified selector: `@body:order.id`. */
+export const RESOURCE_PATH_SEPARATOR = '.';
+/** Where a qualified selector may read a resource id from. */
+export var GateParamSource;
+(function (GateParamSource) {
+    GateParamSource["Params"] = "params";
+    GateParamSource["Query"] = "query";
+    GateParamSource["Body"] = "body";
+    GateParamSource["Headers"] = "headers";
+    GateParamSource["Auth"] = "auth";
+})(GateParamSource || (GateParamSource = {}));
+/**
+ * What the bare form (`@enquiryId`) searches, in order.
+ *
+ * Params first, then query. The query fallback is legacy and deliberately kept: removing it would
+ * silently deny already-deployed applications whose selector happens to name a query key, and a
+ * silent denial inside a customer's running app is the worst available outcome.
+ */
+export const DEFAULT_GATE_PARAM_SOURCES = [
+    GateParamSource.Params, GateParamSource.Query
+];
+/** Why a gate param is structurally wrong — a misconfiguration, not a failed authorization. */
+export var GateParamErrorCode;
+(function (GateParamErrorCode) {
+    GateParamErrorCode["UnknownSource"] = "gate-param:unknown-source";
+    GateParamErrorCode["EmptySelector"] = "gate-param:empty-selector";
+    GateParamErrorCode["EmptySegment"] = "gate-param:empty-segment";
+    /** Named a request key the entrypoint's filter does not declare — AJV strips it before the gate. */
+    GateParamErrorCode["UnreachableKey"] = "gate-param:unreachable-key";
+    /** Named a route param the entrypoint's own path does not carry. */
+    GateParamErrorCode["UnknownRouteParam"] = "gate-param:unknown-route-param";
+})(GateParamErrorCode || (GateParamErrorCode = {}));
+/** Why a selector produced no resource id. */
+export var GateResolutionFailure;
+(function (GateResolutionFailure) {
+    /** The source exists, the path does not. */
+    GateResolutionFailure["NotProvided"] = "not-provided";
+    /** The request carries no such source at all. */
+    GateResolutionFailure["SourceMissing"] = "source-missing";
+    /** Resolved to an object or a multi-element array — refused rather than stringified. */
+    GateResolutionFailure["NotScalar"] = "not-scalar";
+    /** The selector itself did not parse. */
+    GateResolutionFailure["Malformed"] = "malformed";
+})(GateResolutionFailure || (GateResolutionFailure = {}));
+/**
+ * Which FORM of a grant an operation addresses.
+ *
+ * A resource-scoped permission is grantable two ways, under one name: `Blanket` (a PermissionSet
+ * carrying no `resources`, which `hasPermission` reads as covering every id) and `Resources` (an
+ * explicit id list). They are stored separately and must be revoked separately, or a UI offering
+ * both controls would have one silently wipe the other.
+ */
+export var IamGrantMode;
+(function (IamGrantMode) {
+    IamGrantMode["Blanket"] = "blanket";
+    IamGrantMode["Resources"] = "resources";
+    /** Revoke-only: every form. Illegal on a grant. */
+    IamGrantMode["All"] = "all";
+})(IamGrantMode || (IamGrantMode = {}));
+/** What to do about grants that still reference a definition being removed. */
+export var IamRemovalPolicy;
+(function (IamRemovalPolicy) {
+    /** Strip the permission from every subject of the entity, then drop the definition. */
+    IamRemovalPolicy["Cascade"] = "cascade";
+    /** Refuse while any subject still holds it; the holders travel in the error. */
+    IamRemovalPolicy["Refuse"] = "refuse";
+})(IamRemovalPolicy || (IamRemovalPolicy = {}));
+/**
+ * The grouping tiers a permission definition may be tagged with.
+ *
+ * A tag decides NOTHING at request time — `hasPermission` and every gate treat a permission name as
+ * one opaque string — and only groups the permission in an administrator's screen. `guest` is
+ * deliberately absent: a public surface declares no permissions, and adding an area later would
+ * re-classify names already tagged.
+ */
+export const IAM_AREAS = ['user', 'operator', 'admin'];
+/** Separates the resource from the action in a permission name. TWO hyphens, never one. */
+export const PERMISSION_ACTION_SEPARATOR = '--';
 //# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -1 +1 @@
-{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAA;AAE1C,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAA;AAC3C,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAA"}
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAA;AAE1C,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAA;AAC3C,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAA;AAI/C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAA;AAE3C;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,CAAA;AAE5C,6EAA6E;AAC7E,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAA;AAE1C,8DAA8D;AAC9D,MAAM,CAAN,IAAY,eAMX;AAND,WAAY,eAAe;IACzB,oCAAiB,CAAA;IACjB,kCAAe,CAAA;IACf,gCAAa,CAAA;IACb,sCAAmB,CAAA;IACnB,gCAAa,CAAA;AACf,CAAC,EANW,eAAe,KAAf,eAAe,QAM1B;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAsB;IAC3D,eAAe,CAAC,MAAM,EAAE,eAAe,CAAC,KAAK;CAC9C,CAAA;AAED,+FAA+F;AAC/F,MAAM,CAAN,IAAY,kBAQX;AARD,WAAY,kBAAkB;IAC5B,iEAA2C,CAAA;IAC3C,iEAA2C,CAAA;IAC3C,+DAAyC,CAAA;IACzC,oGAAoG;IACpG,mEAA6C,CAAA;IAC7C,oEAAoE;IACpE,0EAAoD,CAAA;AACtD,CAAC,EARW,kBAAkB,KAAlB,kBAAkB,QAQ7B;AAED,8CAA8C;AAC9C,MAAM,CAAN,IAAY,qBASX;AATD,WAAY,qBAAqB;IAC/B,4CAA4C;IAC5C,qDAA4B,CAAA;IAC5B,iDAAiD;IACjD,yDAAgC,CAAA;IAChC,wFAAwF;IACxF,iDAAwB,CAAA;IACxB,yCAAyC;IACzC,gDAAuB,CAAA;AACzB,CAAC,EATW,qBAAqB,KAArB,qBAAqB,QAShC;AAED;;;;;;;GAOG;AACH,MAAM,CAAN,IAAY,YAKX;AALD,WAAY,YAAY;IACtB,mCAAmB,CAAA;IACnB,uCAAuB,CAAA;IACvB,mDAAmD;IACnD,2BAAW,CAAA;AACb,CAAC,EALW,YAAY,KAAZ,YAAY,QAKvB;AAED,+EAA+E;AAC/E,MAAM,CAAN,IAAY,gBAKX;AALD,WAAY,gBAAgB;IAC1B,uFAAuF;IACvF,uCAAmB,CAAA;IACnB,gFAAgF;IAChF,qCAAiB,CAAA;AACnB,CAAC,EALW,gBAAgB,KAAhB,gBAAgB,QAK3B;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAU,CAAA;AAI/D,2FAA2F;AAC3F,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAA"}

package/build/errors.d.ts

@@ -15,6 +15,19 @@ export declare class IamGrantError extends IamError {
     static typeName: string;
     constructor(message?: string);
 }
+/**
+ * A refusal about a permission DEFINITION, as opposed to a grant.
+ *
+ * Separate from `IamGrantError`, which means a grant's subject is missing or its entity does not
+ * match — reusing it for a definition-level refusal is a category error the next reader has to unpick.
+ *
+ * Codes: `permission:held:<name>` (still granted to someone, under a policy that refuses),
+ * `permission:managed:<name>` (platform-owned, deleted only with an explicit second key).
+ */
+export declare class IamPermissionError extends IamError {
+    static typeName: string;
+    constructor(message?: string);
+}
 export declare class IamUnsupported extends IamError {
     static typeName: string;
     constructor(message?: string);

package/build/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,qBAAa,QAAS,SAAQ,cAAc;IAC1C,OAAuB,QAAQ,SAAkC;IAEjE,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAAwC;IAEvE,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,gBAAiB,SAAQ,QAAQ;IAC5C,OAAuB,QAAQ,SAA0C;IAEzE,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,aAAc,SAAQ,QAAQ;IACzC,OAAuB,QAAQ,SAAuC;IAEtE,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAA6C;IAE5E,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,YAAa,SAAQ,QAAQ;IACxC,OAAuB,QAAQ,SAAsC;IAErE,YAAY,OAAO,SAAU,EAG5B;CACF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,qBAAa,QAAS,SAAQ,cAAc;IAC1C,OAAuB,QAAQ,SAAkC;IAEjE,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAAwC;IAEvE,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,gBAAiB,SAAQ,QAAQ;IAC5C,OAAuB,QAAQ,SAA0C;IAEzE,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,aAAc,SAAQ,QAAQ;IACzC,OAAuB,QAAQ,SAAuC;IAEtE,YAAY,OAAO,SAAU,EAG5B;CACF;AAED;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;IAC9C,OAAuB,QAAQ,SAA4C;IAE3E,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAA6C;IAE5E,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,YAAa,SAAQ,QAAQ;IACxC,OAAuB,QAAQ,SAAsC;IAErE,YAAY,OAAO,SAAU,EAG5B;CACF"}