@owlmeans/server-iam 0.1.18-rc.9 → 0.1.18

package/src/gate.ts

@@ -1,97 +1,209 @@
 import { createLazyService } from '@owlmeans/context'
-import type { GateService, AbstractRequest } from '@owlmeans/entrypoint'
+import type { GateService, AbstractRequest, CommonEntrypoint } from '@owlmeans/entrypoint'
+import { authHelper, AuthForbidden, type Auth } from '@owlmeans/auth'
 import { OIDC_GATE } from '@owlmeans/oidc'
-import { AuthForbidden } from '@owlmeans/auth'
-import type { Auth } from '@owlmeans/auth'
-import { createGateModel, extractPermissionSets } from '@owlmeans/server-oidc-rp'
-import type { Config, Context } from '@owlmeans/server-oidc-rp'
-import { hasPermission } from '@owlmeans/iam'
+import { createGateModel, extractPermissionSets, type Config, type Context } from '@owlmeans/server-oidc-rp'
+import { hasPermission, gateParamHelper, gateValidationHelper, resolveGateResource, GateResolutionFailure, type GateParamAudit } from '@owlmeans/iam'
+import { logger, logThrottle } from '@owlmeans/log'
+import type { IamGateOptions } from './types.js'
 
 /**
- * Gate-param syntax:
- *   <permission>                — unscoped (project-wide) check, e.g. 'article--modify'
- *   <permission>@<requestParam> — resource-scoped: the resource id is resolved from
- *                                 req.params[requestParam] ?? req.query[requestParam]
- *                                 and must be listed in the grant's resources[]
- * '{entity}' substitution applies to the permission part in both forms.
+ * The gate-param grammar lives in `@owlmeans/iam` so the browser, the adapters and code-generation
+ * tooling can all read it. Re-exported here because this module was its home and is the documented
+ * import path.
  */
-export const RESOURCE_PARAM_SEPARATOR = '@'
+export {
+  RESOURCE_PARAM_SEPARATOR, RESOURCE_SOURCE_SEPARATOR, RESOURCE_PATH_SEPARATOR,
+  GateParamSource, GateParamErrorCode, GateResolutionFailure,
+  gateParamHelper, gateValidationHelper, resolveGateResource
+} from '@owlmeans/iam'
+export type { ParsedGateParam, GateResourceSelector, GateParamAudit, GateParamHelper, GateValidationHelper } from '@owlmeans/iam'
 
-export interface ParsedGateParam {
-  permission: string
-  resourceParam?: string
-}
-
-export const parseGateParam = (param: string): ParsedGateParam => {
-  const idx = param.indexOf(RESOURCE_PARAM_SEPARATOR)
-  if (idx < 0) {
-    return { permission: param }
-  }
-
-  return { permission: param.slice(0, idx), resourceParam: param.slice(idx + 1) }
-}
+/**
+ * Structural faults are logged once per alias+param+reason.
+ *
+ * A gate on a hot endpoint runs on every request, and a misconfiguration is by definition permanent,
+ * so an un-deduplicated log turns one typo into the incident.
+ */
+const reported = new Set<string>()
 
-const resolveResourceId = (req: AbstractRequest, resourceParam: string): string | undefined => {
-  const params = req.params as Record<string, unknown> | undefined
-  const query = req.query as Record<string, unknown> | undefined
-  const value = params?.[resourceParam] ?? query?.[resourceParam]
+const log = logger('server-iam:gate')
 
-  return value != null ? `${value}` : undefined
-}
+/** Aliases whose declarations have already been checked. */
+const audited = new Set<string>()
 
 /**
  * IAM gate: claims-first with UMA2 fallback. Registered under the OIDC_GATE alias by
  * appendIam() so target code never knows which IAM backend is active.
  *
  * 1. When the Auth carries a valid PermissionSet[] claim (integrated IAM mode),
- *    params are asserted locally against it — both unscoped and resource-scoped forms.
+ *    params are asserted locally against it — both unscoped and resource-scoped forms, and a set
+ *    bound to an organization only for the organization the request acts in.
  * 2. Otherwise (Keycloak mode — its tokens never produce a conforming claim) the
  *    @-suffixes are stripped and the check delegates to the UMA2 gate model from
  *    @owlmeans/server-oidc-rp, byte-equivalent to makeOidcGate.
+ *
+ * Params are OR'd: holding any one of them admits the request. That is why a malformed or
+ * unresolvable param can only contribute `false` and never throw — a sibling that would otherwise
+ * have passed must not be refused because of it.
  */
-export const makeIamGate = (alias: string = OIDC_GATE): GateService => {
+export const makeIamGate = (alias: string = OIDC_GATE, opts?: IamGateOptions): GateService => {
+  const reportOnce = (key: string, message: string, data: Record<string, unknown>): void => {
+    if (reported.has(key)) {
+      return
+    }
+    reported.add(key)
+    log.error(message, data)
+  }
+
+  /**
+   * A refusal of the gate. Logged once a minute per route, reason and subject — a hot endpoint
+   * refuses on every request, and one line per window says the same thing.
+   */
+  const forbidden = (req: AbstractRequest, reason: string, params: string[]): AuthForbidden => {
+    const auth = req.auth as Auth | undefined
+    if (logThrottle(`access.forbidden\0${req.alias ?? ''}\0${reason}\0${auth?.userId ?? ''}`, 60_000)) {
+      log.warn('Access forbidden', {
+        alias: req.alias, reason, params, userId: auth?.userId, entitySlug: req.entity?.slug ?? (auth != null ? authHelper.entitySlugOf(auth) : undefined),
+      }, { event: 'access.forbidden' })
+    }
+    return new AuthForbidden(reason)
+  }
+
+  /**
+   * Check an entrypoint's gate params against what it declares, once, the first time it is reached.
+   *
+   * Structurally unable to affect the outcome: it only ever logs. A selector naming a key the
+   * entrypoint's filter does not declare is stripped by validation before the gate runs, so the
+   * endpoint denies every request with a clean build and nothing else to go on — this is the line that
+   * says why.
+   */
+  const auditEntrypoint = (ctx: Context, req: AbstractRequest, params: string[]): void => {
+    if (req.alias == null || audited.has(req.alias)) {
+      return
+    }
+    audited.add(req.alias)
+
+    try {
+      const entrypoint = ctx.entrypoint<CommonEntrypoint>(req.alias)
+      if (entrypoint == null) {
+        return
+      }
+
+      let routePath: string | undefined
+      try {
+        routePath = entrypoint.mount()
+      } catch {
+        // The mount needs a service with an address; an entrypoint that has none still has a filter
+        // worth auditing.
+      }
+
+      const audit: GateParamAudit = {
+        ...(routePath != null ? { routePath } : {}),
+        ...(entrypoint.filter != null ? { filter: entrypoint.filter as GateParamAudit['filter'] } : {})
+      }
+
+      for (const issue of gateValidationHelper.validateGateParams(params, audit)) {
+        log.error('Gate param is misconfigured', {
+          param: issue.param, alias: req.alias, code: issue.code, detail: issue.detail,
+        })
+      }
+    } catch {
+      // An entrypoint that cannot be looked up is not this gate's problem to report.
+    }
+  }
+
   const service: GateService = createLazyService<GateService>(alias, {
     assert: async (req, _, params) => {
       await service.ready()
       const ctx = service.assertCtx<Config, Context>()
 
       if (req.auth == null) {
-        throw new AuthForbidden('auth')
+        throw forbidden(req, 'auth', params)
       }
 
       const auth = req.auth as Auth
       const sets = extractPermissionSets(auth.permissions)
 
       if (sets != null) {
+        auditEntrypoint(ctx, req, params)
+
+        // Why a param failed, kept aside so a denial can say whether the gate was misconfigured or
+        // the subject simply lacks the grant. The two look identical from the outside and are
+        // repaired in completely different places.
+        const structural: string[] = []
+
+        // The organization the request acts in. A relying party of a tenanted client attaches it
+        // through the guard; otherwise it is the token's. A set bound to any other organization
+        // never satisfies the check.
+        const entitySlug = req.entity?.slug ?? authHelper.entitySlugOf(auth)
+
         const granted = params.some(param => {
-          const { permission, resourceParam } = parseGateParam(param)
-          const fixed = permission.replaceAll('{entity}', auth.entityId ?? '-')
+          const { permission, resource, error } = gateParamHelper.parseGateParam(param)
+          // Grants are stored against the entity's stable id wherever one is resolvable; the
+          // slug is only a fallback for deployments with no organization store of their own,
+          // where the slug IS the identifier.
+          const fixed = permission.replaceAll('{entity}', req.entity?.id ?? authHelper.entitySlugOf(auth) ?? '-')
+
+          if (error != null) {
+            structural.push(`"${param}" does not parse [${error.code}]: ${error.detail}`)
+            return false
+          }
 
-          if (resourceParam != null) {
-            const resourceId = resolveResourceId(req, resourceParam)
-            if (resourceId == null) {
+          if (resource != null) {
+            const resolution = resolveGateResource(req, resource)
+            if (resolution.id == null) {
+              if (resolution.reason !== GateResolutionFailure.NotProvided) {
+                structural.push(
+                  `"${param}" resolved no resource id [${resolution.reason}]`
+                  + ` from ${resource.sources.join(', ')}`
+                )
+              }
               return false
             }
 
-            return hasPermission(auth, fixed, { resourceId })
+            return hasPermission(auth, fixed, { resourceId: resolution.id, entitySlug })
           }
 
-          return hasPermission(auth, fixed)
+          return hasPermission(auth, fixed, { entitySlug })
         })
 
         if (!granted) {
-          throw new AuthForbidden('permission')
+          structural.forEach(detail => reportOnce(
+            `${req.alias}\0${detail}`,
+            'Gate refused a request it could not evaluate', { alias: req.alias, detail }
+          ))
+
+          throw forbidden(req, 'permission', params)
         }
 
         return
       }
 
-      const stripped = params.map(param => parseGateParam(param).permission)
+      // UMA2 fallback. Resource scoping is NOT enforced here: a Keycloak-backed deployment cannot
+      // store a resource-scoped grant, so a scoped param widens to a project-wide check and the same
+      // declaration means two different things depending on which backend is active.
+      const scoped = params.filter(param => gateParamHelper.parseGateParam(param).resource != null)
+      scoped.forEach(param => reportOnce(
+        `uma2\0${req.alias}\0${param}`,
+        'Gate param is resource-scoped, but resource scoping is not enforced in UMA2 mode — it is checked as a '
+        + 'project-wide permission', { param, alias: req.alias }
+      ))
+
+      const usable = opts?.strictResourceScope === true
+        ? params.filter(param => gateParamHelper.parseGateParam(param).resource == null)
+        : params
+
+      if (usable.length < 1) {
+        throw forbidden(req, 'permission', params)
+      }
+
+      const stripped = usable.map(param => gateParamHelper.parseGateParam(param).permission)
       const model = createGateModel(ctx)
       const permissions = await model.loadPermissions(auth, stripped)
 
       if (permissions.length < 1) {
-        throw new AuthForbidden('permission')
+        throw forbidden(req, 'permission', params)
       }
     }
   })

package/src/index.ts

@@ -1,5 +1,11 @@
 export type * from '@owlmeans/iam'
 export { hasPermission } from '@owlmeans/iam'
+export { ORGANIZATION_REFUSAL, ORGANIZATION_OWNER_REFUSAL } from '@owlmeans/oidc'
 export * from './consts.js'
 export * from './append.js'
 export * from './gate.js'
+export type * from './types.js'
+export { makeOrganizationScope, organizationOf, organizationsOf } from './organization.js'
+export type * from './organization/types.js'
+export { makeIamRuntimeClient, iamRuntime } from './runtime.js'
+export type { IamRuntimeClient } from './types.js'

package/src/organization/types.ts

@@ -0,0 +1,21 @@
+import type { ResolvedEntity } from '@owlmeans/entrypoint'
+import type { OIDCAuthCache } from '@owlmeans/server-oidc-rp'
+
+/** The organizations of one request's subject, read from its session — built once per handler. */
+export interface OrganizationScope {
+  /** The session record behind the request's wrapped token — the guard has already refreshed it. */
+  sessionOf: () => Promise<OIDCAuthCache>
+  /**
+   * Every organization of the request's subject, as request entities keyed by their frozen IAM key.
+   *
+   * The session record is the authority — the provider's last claim, re-read on every validation —
+   * never the browser: a relying party of a tenanted client has no organization registry of its own.
+   */
+  organizationsOf: () => Promise<ResolvedEntity[]>
+  /**
+   * One organization of the request's subject by its slug — for a handler that acts in an
+   * organization the URL names rather than in the session's acting one. One the subject is not in is
+   * refused as `AuthForbidden(ORGANIZATION_REFUSAL)`, exactly as the switch refuses it.
+   */
+  organizationOf: (entitySlug: string) => Promise<ResolvedEntity>
+}

package/src/organization.ts

@@ -0,0 +1,49 @@
+import { AuthForbidden, AuthorizationError } from '@owlmeans/auth'
+import type { AbstractRequest, ResolvedEntity } from '@owlmeans/entrypoint'
+import { ORGANIZATION_REFUSAL } from '@owlmeans/oidc'
+import type { OidcOrganizationClaim } from '@owlmeans/oidc'
+import { resolvedEntityOf, sessionRecord } from '@owlmeans/server-oidc-rp'
+import type { Config, Context, OIDCAuthCache } from '@owlmeans/server-oidc-rp'
+import type { OrganizationScope } from './organization/types.js'
+
+/**
+ * The organizations the provider last claimed for the session's subject. A session that acts in
+ * none — a client without the organizations scope — has none to offer, whatever its record holds.
+ */
+const claimedOf = (record: OIDCAuthCache): OidcOrganizationClaim[] =>
+  record.acting == null ? [] : record.organizations ?? []
+
+export const makeOrganizationScope = <C extends Config, T extends Context<C>>(
+  context: T, request: AbstractRequest
+): OrganizationScope => {
+  const sessionOf = async (): Promise<OIDCAuthCache> => {
+    if (request.auth == null) {
+      throw new AuthorizationError('auth')
+    }
+
+    return sessionRecord<C, T>(context, request.auth.token)
+  }
+
+  const organizationsOf = async (): Promise<ResolvedEntity[]> => claimedOf(await sessionOf()).map(resolvedEntityOf)
+
+  const organizationOf = async (entitySlug: string): Promise<ResolvedEntity> => {
+    const org = claimedOf(await sessionOf()).find(org => org.entitySlug === entitySlug)
+    if (org == null) {
+      throw new AuthForbidden(ORGANIZATION_REFUSAL)
+    }
+
+    return resolvedEntityOf(org)
+  }
+
+  return { sessionOf, organizationsOf, organizationOf }
+}
+
+/** @deprecated compat:factory-refactor — use `makeOrganizationScope(context, request).organizationsOf()` */
+export const organizationsOf = async <C extends Config, T extends Context<C>>(
+  context: T, request: AbstractRequest
+): Promise<ResolvedEntity[]> => await makeOrganizationScope<C, T>(context, request).organizationsOf()
+
+/** @deprecated compat:factory-refactor — use `makeOrganizationScope(context, request).organizationOf(…)` */
+export const organizationOf = async <C extends Config, T extends Context<C>>(
+  context: T, request: AbstractRequest, entitySlug: string
+): Promise<ResolvedEntity> => await makeOrganizationScope<C, T>(context, request).organizationOf(entitySlug)

package/src/runtime.ts

@@ -0,0 +1,193 @@
+import { AuthForbidden, AuthorizationError, AuthUnavailable } from '@owlmeans/auth'
+import type { AbstractRequest } from '@owlmeans/entrypoint'
+import { ResilientError } from '@owlmeans/error'
+import { IAM_RUNTIME_ROUTES, IamClientError, IamError, type IamRuntimeAck, type IamRuntimeGrant, type IamRuntimeGrantList, type IamRuntimeMember, type IamRuntimeMemberList, type IamRuntimeOrganization, type IamRuntimeOrganizationList, type IamRuntimePermissionList } from '@owlmeans/iam'
+import { IAM_API_METADATA, ORGANIZATION_OWNER_REFUSAL, ORGANIZATION_REFUSAL } from '@owlmeans/oidc'
+import { DEFAULT_ALIAS as OIDC_CLIENT_SERVICE, type Config, type Context, type OidcClientService } from '@owlmeans/server-oidc-rp'
+import { makeOrganizationScope } from './organization.js'
+import { INCIDENT_ID_HEADER } from './consts.local.js'
+import type { Access, Call } from './types.local.js'
+import type { IamRuntimeClient } from './types.js'
+
+/**
+ * Discovered runtime bases, per context and per client. Discovery is a network round trip the OIDC
+ * client service does not memoise, and the base never changes while a provider runs. A failed
+ * lookup is forgotten, so the next request asks again rather than inheriting the error.
+ */
+const bases = new WeakMap<object, Map<string, Promise<string>>>()
+
+const pathOf = (path: string, params: Record<string, string> = {}): string =>
+  path.replace(/:(\w+)/g, (_, key: string) => {
+    const value = params[key]
+    if (value == null || value === '') {
+      throw new IamError(`runtime:param:${key}`)
+    }
+
+    return encodeURIComponent(value)
+  })
+
+/**
+ * The error a refused call rejects with.
+ *
+ * A development server sends the marshalled error, which is rebuilt into its own class. A production
+ * one sends only an incident id, so the status and the route's access level are all there is to go
+ * on: a 403 from an owner-level route is the subject not owning the organization, from any other
+ * route the subject not being in it.
+ */
+const failureOf = async (response: Response, access: Access): Promise<Error> => {
+  const text = await response.text().catch(() => '')
+  const incidentId = response.headers.get(INCIDENT_ID_HEADER) ?? undefined
+
+  if (text.includes(ResilientError.separator)) {
+    try {
+      const error = ResilientError.ensure(text, true)
+      error.incidentId ??= incidentId
+      return error
+    } catch {
+      // Not a marshalled error after all — fall through to the status.
+    }
+  }
+
+  const error = response.status === 401 ? new AuthorizationError('iam-runtime')
+    : response.status === 403 ? new AuthForbidden(access === 'owner' ? ORGANIZATION_OWNER_REFUSAL : ORGANIZATION_REFUSAL)
+      : new IamError(`runtime:status:${response.status}`)
+  if (incidentId != null) {
+    error.incidentId = incidentId
+  }
+
+  return error
+}
+
+/**
+ * A typed client of the provider's runtime IAM API, bound to one request.
+ *
+ * It calls as the request's subject: the bearer is the provider access token of that request's
+ * session record, read afresh on every call, so a token the guard has just refreshed is the one
+ * sent. The base URL is the provider's discovery field `IAM_API_METADATA`. Calls travel over plain
+ * `fetch`, because the API is another service's tree and a relying party binds none of it.
+ */
+export const makeIamRuntimeClient = <C extends Config, T extends Context<C>>(
+  context: T, request: AbstractRequest
+): IamRuntimeClient => {
+  const runtimeBase = (clientId: string): Promise<string> => {
+    const known = bases.get(context) ?? new Map<string, Promise<string>>()
+    bases.set(context, known)
+    const cached = known.get(clientId)
+    if (cached != null) {
+      return cached
+    }
+
+    const attempt = (async () => {
+      const client = await context.service<OidcClientService>(OIDC_CLIENT_SERVICE).getClient(clientId)
+      const base = client.getMetadata()[IAM_API_METADATA]
+      if (typeof base !== 'string' || base === '') {
+        // A provider that advertises no runtime API — Keycloak, or an integrated provider that does not
+        // serve it — has nothing to call.
+        throw new IamClientError(`runtime-api:${clientId}`)
+      }
+
+      return base.replace(/\/+$/, '')
+    })()
+    known.set(clientId, attempt)
+    attempt.catch(() => {
+      if (known.get(clientId) === attempt) {
+        known.delete(clientId)
+      }
+    })
+
+    return attempt
+  }
+
+  const scope = makeOrganizationScope<C, T>(context, request)
+
+  const call = async <R>({ method, path, access, params, query, body }: Call): Promise<R> => {
+    const record = await scope.sessionOf()
+    const clientId = record.client ?? context.service<OidcClientService>(OIDC_CLIENT_SERVICE).getDefault()
+    if (clientId == null) {
+      throw new AuthUnavailable('oidc-client')
+    }
+    const token = record.payload?.access_token
+    if (token == null || token === '') {
+      throw new AuthForbidden('record')
+    }
+
+    const url = new URL(`${await runtimeBase(clientId)}${pathOf(path, params)}`)
+    Object.entries(query ?? {}).forEach(([key, value]) => {
+      if (value != null) {
+        url.searchParams.set(key, String(value))
+      }
+    })
+
+    const response = await fetch(url, {
+      method,
+      headers: {
+        authorization: `Bearer ${token}`,
+        accept: 'application/json',
+        ...(method === 'POST' ? { 'content-type': 'application/json' } : {}),
+      },
+      // A JSON content type with an empty body is refused by the server, so a POST always sends one.
+      ...(method === 'POST' ? { body: JSON.stringify(body ?? {}) } : {}),
+    })
+
+    if (!response.ok) {
+      throw await failureOf(response, access)
+    }
+
+    return await response.json() as R
+  }
+
+  const R = IAM_RUNTIME_ROUTES
+
+  return {
+    organizations: {
+      list: async () => (await call<IamRuntimeOrganizationList>({
+        method: 'GET', path: R.organizations, access: 'subject',
+      })).items,
+      create: async body => call<IamRuntimeOrganization>({
+        method: 'POST', path: R.organizations, access: 'subject', body: body ?? {},
+      }),
+      update: async (entitySlug, body) => call<IamRuntimeOrganization>({
+        method: 'POST', path: R.organization, access: 'owner', params: { entitySlug }, body,
+      }),
+    },
+    members: {
+      list: async entitySlug => (await call<IamRuntimeMemberList>({
+        method: 'GET', path: R.members, access: 'member', params: { entitySlug },
+      })).items,
+      add: async (entitySlug, invite) => call<IamRuntimeMember>({
+        method: 'POST', path: R.members, access: 'owner', params: { entitySlug }, body: invite,
+      }),
+      update: async (entitySlug, profileId, update) => call<IamRuntimeMember>({
+        method: 'POST', path: R.member, access: 'owner', params: { entitySlug, profileId }, body: update,
+      }),
+      remove: async (entitySlug, profileId) => {
+        await call<IamRuntimeAck>({
+          method: 'POST', path: R.memberRemove, access: 'owner', params: { entitySlug, profileId },
+        })
+      },
+    },
+    permissions: {
+      list: async entitySlug => (await call<IamRuntimePermissionList>({
+        method: 'GET', path: R.permissions, access: 'member', params: { entitySlug },
+      })).items,
+    },
+    grants: {
+      list: async (entitySlug, query) => (await call<IamRuntimeGrantList>({
+        method: 'GET', path: R.grants, access: 'owner', params: { entitySlug }, query,
+      })).items,
+      assign: async (entitySlug, grant) => call<IamRuntimeGrant>({
+        method: 'POST', path: R.grants, access: 'owner', params: { entitySlug }, body: grant,
+      }),
+      revoke: async (entitySlug, grant) => {
+        await call<IamRuntimeAck>({
+          method: 'POST', path: R.grantsRevoke, access: 'owner', params: { entitySlug }, body: grant,
+        })
+      },
+    },
+  }
+}
+
+/** @deprecated compat:factory-refactor — use `makeIamRuntimeClient(context, request)` */
+export const iamRuntime = <C extends Config, T extends Context<C>>(
+  context: T, request: AbstractRequest
+): IamRuntimeClient => makeIamRuntimeClient<C, T>(context, request)

package/src/types.local.ts

@@ -0,0 +1,18 @@
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import type { WithSharedConfig } from '@owlmeans/oidc'
+
+export interface IamServerConfig extends ServerConfig, WithSharedConfig {}
+
+export type IamServerContext<C extends IamServerConfig = IamServerConfig> = ServerContext<C>
+
+/** Who a route admits — and therefore which refusal a bare 403 from it means. */
+export type Access = 'subject' | 'member' | 'owner'
+
+export interface Call {
+  method: 'GET' | 'POST'
+  path: string
+  access: Access
+  params?: Record<string, string>
+  query?: object
+  body?: object
+}

package/src/types.ts

@@ -0,0 +1,43 @@
+import type { IamRuntimeGrant, IamRuntimeGrantQuery, IamRuntimeGrantRequest, IamRuntimeMember, IamRuntimeMemberInvite, IamRuntimeMemberUpdate, IamRuntimeOrganization, IamRuntimeOrganizationCreate, IamRuntimeOrganizationUpdate, IamRuntimePermission } from '@owlmeans/iam'
+
+export interface IamGateOptions {
+  /**
+   * Refuse a resource-scoped param on the UMA2 fallback path instead of widening it to a
+   * project-wide check.
+   *
+   * Off by default, and deliberately so. A Keycloak-backed deployment cannot hold a resource-scoped
+   * grant at all — the adapter throws `IamUnsupported('resource-scoped-grant')` — so denying would
+   * lock every user out of every scoped endpoint rather than tightening anything. Turn it on only
+   * where the resulting refusals are the intended outcome.
+   */
+  strictResourceScope?: boolean
+}
+
+/**
+ * The runtime IAM API as the signed-in subject of one request: its organizations, their members,
+ * the grantable definitions and the grants. Every call acts as that subject — the provider decides
+ * owner and member rights from the access token, never from anything sent here.
+ */
+export interface IamRuntimeClient {
+  organizations: {
+    list: () => Promise<IamRuntimeOrganization[]>
+    /** The subject becomes the new organization's owner. */
+    create: (body?: IamRuntimeOrganizationCreate) => Promise<IamRuntimeOrganization>
+    update: (entitySlug: string, body: IamRuntimeOrganizationUpdate) => Promise<IamRuntimeOrganization>
+  }
+  members: {
+    list: (entitySlug: string) => Promise<IamRuntimeMember[]>
+    /** Find-or-create by e-mail: adding an address twice answers the same member. */
+    add: (entitySlug: string, invite: IamRuntimeMemberInvite) => Promise<IamRuntimeMember>
+    update: (entitySlug: string, profileId: string, update: IamRuntimeMemberUpdate) => Promise<IamRuntimeMember>
+    remove: (entitySlug: string, profileId: string) => Promise<void>
+  }
+  permissions: {
+    list: (entitySlug: string) => Promise<IamRuntimePermission[]>
+  }
+  grants: {
+    list: (entitySlug: string, query?: IamRuntimeGrantQuery) => Promise<IamRuntimeGrant[]>
+    assign: (entitySlug: string, grant: IamRuntimeGrantRequest) => Promise<IamRuntimeGrant>
+    revoke: (entitySlug: string, grant: IamRuntimeGrantRequest) => Promise<void>
+  }
+}