@owlmeans/iam 0.1.18-rc.9 → 0.1.18

package/agent-meta/skills/iam/parts/clients.md

@@ -0,0 +1,93 @@
+---
+name: clients
+description: Provisioning OIDC clients — globally unique client ids, the realm field, issuer and redirect-URI rules — and selecting the IAM backend.
+metadata:
+  purposes: auth, config
+  mentions: claimClient, deleteClient, getIssuerUrl, redirectUris, IamClientError, IAM_MODE_INTEGRATED, IAM_MODE_KEYCLOAK, iamMode, IamClient
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/iam — Clients, issuers and backend selection
+
+## 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
+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 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 backend
+
+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
+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))
+```
+
+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.
+
+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.
+
+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.

package/agent-meta/skills/iam/parts/permissions.md

@@ -0,0 +1,106 @@
+---
+name: permissions
+description: Permission names and grant forms, IamGrantMode, the four permission kinds, default classes and restrictions.
+metadata:
+  purposes: auth
+  mentions: hasPermission, grantPermission, revokePermission, ensurePermission, IamGrantMode, IamDefaultClass, composePermissionName, parsePermissionName, entityScoped, resourceScoped, defaultClass
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/iam — Permission model
+
+## Permission model (kinds and 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).
+
+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, `All` (revoke-only) is every form, and `Inherit`
+(revoke-only) is the subject's own blanket value — see "Restrictions". A grant in `All` or `Inherit`
+is refused (`IamGrantError('mode:all-is-revoke-only')`, `'mode:inherit-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.
+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`.
+
+### Restrictions
+
+Every subject — a person or a group — has ONE blanket value of its own per binding: `true` grants,
+`false` RESTRICTS, absent inherits. A subject holds a name when its own value is `true`, or when it is
+not `false` and something it inherits grants it.
+
+| Subject | Inherits from | Its own value lives on |
+|---|---|---|
+| person | class defaults, its groups' grants and its groups' bundles | the primary row (unbound definition); the row of the binding's organization (bound — for a group-derived name, the row that names the group) |
+| group | its bundles | the group's own blanket set |
+
+- A restriction withholds every INHERITED form of the name in that binding — a class default, a
+  group's blanket grant, a group's per-record grant, a bundle's selection. The subject's OWN grants,
+  per-record ones included, are never cut. A group's restriction cuts only its own bundles, for all
+  its members; another group granting the name still grants it.
+- A `Blanket` or `All` revoke of a DECLARED definition writes the restriction (an undeclared name gets
+  none). `Inherit` drops the subject's own value — grant or restriction — writes nothing in its
+  place, leaves resource-scoped sets alone and ignores `resources`; a bound definition needs
+  `entitySlug` for it as for `Blanket`. A later `Blanket` grant overwrites a restriction with `true`.
+- Tokens carry only what is held: a relying party never sees a restriction, only fewer permissions.
+- Listings (`listGrants`, `groups.grants`) answer what is held; `IamGrantListArgs.restricted` adds
+  the inherited grants the subject's own restriction withholds as `restricted: true` (same `origin` /
+  `through` as the held form), so a console can show them and lift them with `Inherit`. A user's
+  `grantCount` counts held grants only.
+- A backend without inheritance (Keycloak) has nothing to restrict: every revoke, `Inherit`
+  included, removes the role, and a listing ignores `restricted`.

package/agent-meta/skills/iam/parts/service.md

@@ -0,0 +1,115 @@
+---
+name: service
+description: The full IamService interface with its per-method contracts, and the per-client user operations.
+metadata:
+  purposes: auth, server-api
+  mentions: IamService, getEntityAdminConfig, ensureClient, getClient, grantBundle, listGrants, listUsers, inviteUser, updateUser, removeUser, syncStaff, normalizePermissions, deletePermission
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/iam — The IamService interface
+
+## `IamService` interface
+
+```ts
+interface IamService extends InitializedService {
+  // The tenant's admin OIDC provider config, and a raw admin { token, realm } pair.
+  getEntityAdminConfig: (entityId: string) => Promise<OidcProviderConfig>
+  getCredentialsPair: (entityId: string) => Promise<IamCredentialsPair>
+
+  // The tenant's public issuer URL — see "Issuer & redirect URIs" (the clients part).
+  getIssuerUrl: (entityId: string) => Promise<string>
+
+  // Provision an OIDC client for a tenant — see "Issuer & redirect URIs" and
+  // "A client id is a global name" (the clients part) for the two rules it has to obey.
+  ensureClient: (entityId: string, clientId: string, options?: IamClientOptions) => Promise<IamClient>
+
+  // 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>
+
+  // 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) ---
+
+  listPermissions: (entityId: string, clientId: string, filter?: IamPermissionFilter) => Promise<IamPermissionDefinition[]>
+
+  // args.resources selects the resource-scoped form, args.entitySlug the binding of an entityScoped
+  // definition; see "Permission model (kinds and grant forms)" in the permissions part. A
+  // blanket/all revoke of a declared definition RESTRICTS; mode Inherit takes the own value
+  // back — see "Restrictions" there
+  grantPermission: (entityId: string, clientId: string, profileId: string, permission: string, args?: IamGrantArgs) => Promise<IamGrant>
+  revokePermission: (entityId: string, clientId: string, profileId: string, permission: string, args?: IamGrantArgs) => Promise<void>
+
+  // 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` — what is HELD; args.restricted
+  // adds what the subject's own restrictions withhold (`restricted: true`).
+  listGrants: (entityId: string, clientId: string, profileId?: string, args?: IamGrantListArgs) => Promise<IamGrant[]>
+
+  // --- Users of one client — see "Users are per client" ---
+
+  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>
+
+  // The owning organization's staff, admitted to the client through the managed `members` group.
+  syncStaff: (entityId: string, clientId: string, args: IamStaffSyncArgs) => Promise<IamStaffSyncReport>
+
+  // --- Tenancy facets — see "Organizations, groups and subjects" (the tenancy part) ---
+  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.

package/agent-meta/skills/iam/parts/tenancy.md

@@ -0,0 +1,72 @@
+---
+name: tenancy
+description: The organizations, groups and subjects facets of IamService, and the runtime IAM API a tenanted client's server calls.
+metadata:
+  purposes: auth, server-api
+  mentions: IamOrganizationFacet, IamGroupFacet, IamSubjectFacet, unsupportedFacet, IAM_MEMBERS_GROUP, makeIamRuntimeProtocols, IAM_RUNTIME_GUARD, IAM_RUNTIME_ROUTES, IAM_RUNTIME_PATH, iamRuntime
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/iam — Organizations, groups, subjects and the runtime API
+
+## 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; a revoke restricts, as for
+  a person), `grants(…, key, args?)` (its own grants as `Direct`, the names its bundles select as
+  `Bundle`, minus what it restricts; `args.restricted` adds the cut bundle names), 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:
+  its existence, key, membership and bundles are the sync's (`ensure`, `remove`, `addMembers`,
+  `removeMembers`, `setBundles` → `IamGroupError('managed:members')`), while its grants and
+  restrictions are the operator's (`grant` / `revoke`) and survive every sync.
+- **`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` (a revoke restricts; `mode: inherit` takes the own value back) | 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)`.

package/build/consts.d.ts

@@ -1,5 +1,174 @@
+import type { IamRuntimeAck, IamRuntimeGrantQuery, IamRuntimeMemberInvite, IamRuntimeMemberParams, IamRuntimeOrganizationCreate, IamRuntimeOrganizationParams, IamRuntimeOrganizationUpdate } from './runtime/types.js';
+import type { JSONSchemaType } from 'ajv';
 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.
+ *
+ * Every subject, person or group, also has ONE blanket value of its own per binding: `true` grants,
+ * `false` RESTRICTS (it cuts what the subject would inherit from a default class, a group or a
+ * bundle), absent inherits. A `Blanket` or `All` revoke of a declared definition writes the
+ * restriction; `Inherit` takes the subject's own value back.
+ */
+export declare enum IamGrantMode {
+    Blanket = "blanket",
+    Resources = "resources",
+    /** Revoke-only: every form. Illegal on a grant. */
+    All = "all",
+    /**
+     * Revoke-only: drop the subject's OWN blanket value in the binding — a grant or a restriction —
+     * so it holds exactly what it inherits. Resource-scoped sets are untouched. Illegal on a grant.
+     */
+    Inherit = "inherit"
+}
+/** 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'];
+/** Separates the resource from the action in a permission name. TWO hyphens, never one. */
+export declare const PERMISSION_ACTION_SEPARATOR = "--";
+/**
+ * Who holds a permission without an explicit grant — a property of the DEFINITION, evaluated when
+ * claims are built and never written onto a profile.
+ *
+ * `User` is every signed-in subject of the client (an unbound, unmanaged `user`-area definition
+ * only); `Member` and `Owner` are every member / owner of the organization the subject acts in, so
+ * they require an `entityScoped` definition. A class default is a BLANKET set: `Owner` on a
+ * resource-scoped definition is its all-records form.
+ */
+export declare enum IamDefaultClass {
+    None = "none",
+    User = "user",
+    Member = "member",
+    Owner = "owner"
+}
+/** Why a subject holds a grant, as a listing reports it. */
+export declare enum IamGrantOrigin {
+    /** Written on the subject's own row. */
+    Direct = "direct",
+    /** The definition's `defaultClass` covers the subject. */
+    Default = "default",
+    /** Held by a group the subject is a member of — `IamGrant.through` names it. */
+    Group = "group",
+    /** A group's own listing only: the names its bundles select; its own grants are `Direct`. */
+    Bundle = "bundle"
+}
+/**
+ * The managed group `syncStaff` keeps in a client's owning organization: the owner's own staff,
+ * admitted to the client with the bundles the sync hands it. Its key, membership, bundles and
+ * existence are the synchronization's alone; its grants and restrictions are the operator's and
+ * survive every sync.
+ */
+export declare const IAM_MEMBERS_GROUP = "members";
+/**
+ * The `profileId` of a credential that proves an e-mail address and identifies nobody yet: what the
+ * end-user sign-in hands the provider's finalizer, which then resolves the account itself. It carries
+ * no `entitySlug` — a proof bound to an organization is something else.
+ */
+export declare const IAM_EMAIL_PROOF = "proof:email";
+/**
+ * The guard of the runtime IAM API (`makeIamRuntimeProtocols`). The serving process registers it: it
+ * admits a bearer access token the provider itself issued, and takes the client and the account from
+ * that token, never from the request.
+ */
+export declare const IAM_RUNTIME_GUARD = "iam-runtime-guard";
+/** Where the runtime IAM API mounts under its service unless the declaration names another path. */
+export declare const IAM_RUNTIME_PATH = "/runtime";
+/**
+ * The runtime API's leaf paths under its base. One table so the declarations and a fetch-only client
+ * (a target's server, which binds no entrypoint of the provider's tree) cannot disagree on a segment.
+ */
+export declare const IAM_RUNTIME_ROUTES: {
+    readonly organizations: '/organizations';
+    readonly organization: '/organizations/:entitySlug';
+    readonly members: '/organizations/:entitySlug/members';
+    readonly member: '/organizations/:entitySlug/members/:profileId';
+    readonly memberRemove: '/organizations/:entitySlug/members/:profileId/remove';
+    readonly permissions: '/organizations/:entitySlug/permissions';
+    readonly grants: '/organizations/:entitySlug/grants';
+    readonly grantsRevoke: '/organizations/:entitySlug/grants/revoke';
+};
+export declare const IamRuntimeOrganizationCreateSchema: JSONSchemaType<IamRuntimeOrganizationCreate>;
+export declare const IamRuntimeOrganizationUpdateSchema: JSONSchemaType<IamRuntimeOrganizationUpdate>;
+export declare const IamRuntimeOrganizationParamsSchema: JSONSchemaType<IamRuntimeOrganizationParams>;
+export declare const IamRuntimeMemberInviteSchema: JSONSchemaType<IamRuntimeMemberInvite>;
+export declare const IamRuntimeMemberParamsSchema: JSONSchemaType<IamRuntimeMemberParams>;
+export declare const IamRuntimeGrantQuerySchema: JSONSchemaType<IamRuntimeGrantQuery>;
+export declare const IamRuntimeAckSchema: JSONSchemaType<IamRuntimeAck>;
 //# 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":"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"}