@owlmeans/iam 0.1.18-rc.2 → 0.1.18-rc.21

package/src/gate/resolve.ts

@@ -0,0 +1,114 @@
+import { GateParamSource, GateResolutionFailure } from '../consts.js'
+import type { GateRequestLike, GateResourceSelector, GateResourceResolution } from '../types.js'
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value != null && typeof value === 'object'
+
+/**
+ * A resource id is a scalar. Anything else is refused rather than coerced.
+ *
+ * Stringifying an object would produce `"[object Object]"`, which then either matches nothing or —
+ * far worse — matches another record that stringified the same way.
+ */
+const scalar = (value: unknown): string | null => {
+  switch (typeof value) {
+    case 'string':
+      return value
+    case 'number':
+    case 'boolean':
+    case 'bigint':
+      return `${value}`
+    default:
+      return null
+  }
+}
+
+const sourceOf = (req: GateRequestLike, source: GateParamSource): unknown => {
+  switch (source) {
+    case GateParamSource.Params: return req.params
+    case GateParamSource.Query: return req.query
+    case GateParamSource.Body: return req.body
+    case GateParamSource.Headers: return req.headers
+    case GateParamSource.Auth: return req.auth
+  }
+}
+
+/**
+ * Walk one source for the selector's path.
+ *
+ * Headers get two adjustments they need and nothing else does: the first segment is lowercased,
+ * because HTTP header names are case-insensitive and every server normalises them differently; and a
+ * single-element array unwraps, because a repeated header arrives as an array and silently picking
+ * one of several values would be an authorization decision made by accident.
+ */
+const walk = (
+  container: unknown, path: string[], source: GateParamSource
+): { value?: unknown, reason?: GateResolutionFailure } => {
+  if (!isRecord(container)) {
+    return { reason: GateResolutionFailure.SourceMissing }
+  }
+
+  let cursor: unknown = container
+  for (const [index, rawSegment] of path.entries()) {
+    if (!isRecord(cursor)) {
+      return { reason: GateResolutionFailure.NotProvided }
+    }
+
+    const segment = source === GateParamSource.Headers && index === 0
+      ? rawSegment.toLowerCase()
+      : rawSegment
+
+    cursor = cursor[segment]
+  }
+
+  if (source === GateParamSource.Headers && Array.isArray(cursor)) {
+    if (cursor.length !== 1) {
+      return { reason: GateResolutionFailure.NotScalar }
+    }
+    cursor = cursor[0]
+  }
+
+  if (cursor == null) {
+    return { reason: GateResolutionFailure.NotProvided }
+  }
+
+  return { value: cursor }
+}
+
+/**
+ * Resolve the resource id a selector points at.
+ *
+ * Sources are tried in the selector's own order — for the bare form, route params before the query —
+ * and the first that yields a value wins. When none does, the reason travels back so the caller can
+ * tell a MISCONFIGURED gate (the request never carried that key) from a legitimately DENIED one.
+ */
+export const resolveGateResource = (
+  req: GateRequestLike, selector: GateResourceSelector
+): GateResourceResolution => {
+  let reason: GateResolutionFailure = GateResolutionFailure.SourceMissing
+
+  for (const source of selector.sources) {
+    const result = walk(sourceOf(req, source), selector.path, source)
+
+    if (result.reason != null) {
+      // A hard refusal is more informative than "keep looking" — report it rather than letting a
+      // later, emptier source overwrite it with a vaguer reason.
+      if (result.reason === GateResolutionFailure.NotScalar) {
+        return { reason: result.reason, from: source }
+      }
+      if (reason === GateResolutionFailure.SourceMissing) {
+        reason = result.reason
+      }
+      continue
+    }
+
+    const value = scalar(result.value)
+    if (value == null) {
+      return { reason: GateResolutionFailure.NotScalar, from: source }
+    }
+
+    return { id: value, from: source }
+  }
+
+  return { reason }
+}

package/src/gate/validate.ts

@@ -0,0 +1,132 @@
+import { normalizePath, SEP, PARAM } from '@owlmeans/route'
+import { GateParamSource, GateParamErrorCode } from '../consts.js'
+import type { GateParamAudit, GateParamIssue, GateResourceSelector } from '../types.js'
+import { parseGateParam } from './param.js'
+
+/** The `:name` segments of a route template. */
+export const routeParamsOf = (path: string): string[] =>
+  normalizePath(path).split(SEP)
+    .filter(segment => segment.startsWith(PARAM))
+    .map(segment => segment.slice(PARAM.length))
+
+interface SchemaLike {
+  properties?: Record<string, unknown>
+  additionalProperties?: unknown
+}
+
+/**
+ * Whether a key can survive validation to reach the gate.
+ *
+ * The server compiles entrypoint filters with AJV's `removeAdditional`, which strips an undeclared
+ * key BEFORE the handler — and therefore before the gate — runs. So a selector naming a key the
+ * filter does not declare denies every request, with a clean build and nothing logged.
+ *
+ * The `additionalProperties === false` qualifier is what makes this check usable rather than noise:
+ * AJV only strips when a schema says so. An entrypoint that declares no filter for a source strips
+ * nothing, and reporting those would fire on nearly every endpoint and be ignored within a week.
+ */
+const unreachable = (schema: object | undefined, key: string): boolean => {
+  if (schema == null) {
+    return false
+  }
+
+  const { properties, additionalProperties } = schema as SchemaLike
+  if (additionalProperties !== false) {
+    return false
+  }
+
+  return properties == null || !(key in properties)
+}
+
+const filterFor = (audit: GateParamAudit, source: GateParamSource): object | undefined => {
+  switch (source) {
+    case GateParamSource.Query: return audit.filter?.query
+    case GateParamSource.Body: return audit.filter?.body
+    case GateParamSource.Headers: return audit.filter?.headers
+    case GateParamSource.Params: return audit.filter?.params
+    case GateParamSource.Auth: return undefined
+  }
+}
+
+const auditSelector = (
+  audit: GateParamAudit, selector: GateResourceSelector
+): Omit<GateParamIssue, 'param'> | null => {
+  const key = selector.path[0]
+  if (key == null) {
+    return null
+  }
+
+  // The bare form searches route params first and the query second, so it is only provably wrong
+  // when BOTH are impossible. A declared route param settles it; otherwise fall through to the
+  // query check below, which only fires on an explicitly closed schema.
+  const routeParams = audit.routeParams
+    ?? (audit.routePath != null ? routeParamsOf(audit.routePath) : undefined)
+
+  if (selector.source == null) {
+    if (routeParams?.includes(key) === true) {
+      return null
+    }
+    if (unreachable(audit.filter?.query, key) && unreachable(audit.filter?.params, key)) {
+      return {
+        code: GateParamErrorCode.UnknownRouteParam,
+        detail: `"${key}" is not a route param of "${audit.routePath ?? '?'}"`
+          + ' and is declared by neither the params nor the query filter'
+      }
+    }
+    return null
+  }
+
+  if (selector.source === GateParamSource.Params) {
+    if (routeParams != null && !routeParams.includes(key) && unreachable(audit.filter?.params, key)) {
+      return {
+        code: GateParamErrorCode.UnknownRouteParam,
+        detail: `"${key}" is not a route param of "${audit.routePath ?? '?'}"`
+      }
+    }
+    return null
+  }
+
+  if (unreachable(filterFor(audit, selector.source), key)) {
+    return {
+      code: GateParamErrorCode.UnreachableKey,
+      detail: `the ${selector.source} filter declares no "${key}" and forbids additional properties,`
+        + ' so it is removed by validation before the gate can read it'
+    }
+  }
+
+  return null
+}
+
+/**
+ * Check gate params against what their entrypoint declares.
+ *
+ * Reports only what is provable from the declaration itself. Anything that would need a guess is
+ * left alone: a check that fires on correct code stops being read.
+ *
+ * Meant to run where a mistake can still be fixed — while code is being generated, or once per alias
+ * as a diagnostic. It must never decide a request: with `some()` semantics across params, one
+ * malformed sibling must not be able to refuse a legitimately passing one.
+ */
+export const validateGateParams = (params: string[], audit?: GateParamAudit): GateParamIssue[] => {
+  const issues: GateParamIssue[] = []
+
+  for (const param of params) {
+    const parsed = parseGateParam(param)
+
+    if (parsed.error != null) {
+      issues.push({ param, code: parsed.error.code, detail: parsed.error.detail })
+      continue
+    }
+
+    if (parsed.resource == null || audit == null) {
+      continue
+    }
+
+    const issue = auditSelector(audit, parsed.resource)
+    if (issue != null) {
+      issues.push({ param, ...issue })
+    }
+  }
+
+  return issues
+}

package/src/index.ts

@@ -2,3 +2,5 @@ export type * from './types.js'
 export * from './consts.js'
 export * from './errors.js'
 export * from './utils.js'
+export * from './gate/index.js'
+export * from './permission.js'

package/src/permission.ts

@@ -0,0 +1,48 @@
+import { PERMISSION_ACTION_SEPARATOR, RESOURCE_PARAM_SEPARATOR, GateParamErrorCode } from './consts.js'
+import type { ParsedPermissionName } from './types.js'
+
+/**
+ * Read a permission NAME.
+ *
+ * The name is `<resource>--<action>`, with TWO hyphens. One hyphen is not a separator: `enquiry-view`
+ * is a resource called `enquiry-view` carrying no action, and it must keep parsing that way — a name
+ * already granted somewhere cannot be re-interpreted without orphaning the grant.
+ *
+ * A name never carries a gate selector. `@` is the gate's syntax, and a name containing one is
+ * exactly the corruption this function exists to make visible, so it is reported through `problem`
+ * rather than quietly split.
+ */
+export const parsePermissionName = (name: string): ParsedPermissionName => {
+  const problem = name.includes(RESOURCE_PARAM_SEPARATOR)
+    ? {
+      code: GateParamErrorCode.UnreachableKey,
+      detail: `"${name}" carries a gate selector; "${RESOURCE_PARAM_SEPARATOR}" is never part of a`
+        + ' permission name, and nothing ever looks up a name that contains one'
+    }
+    : undefined
+
+  const idx = name.indexOf(PERMISSION_ACTION_SEPARATOR)
+  if (idx < 0) {
+    return { name, resource: name, ...(problem != null ? { problem } : {}) }
+  }
+
+  const action = name.slice(idx + PERMISSION_ACTION_SEPARATOR.length)
+
+  return {
+    name,
+    resource: name.slice(0, idx),
+    ...(action !== '' ? { action } : {}),
+    ...(problem != null ? { problem } : {})
+  }
+}
+
+/** Compose a permission name. The inverse of `parsePermissionName`. */
+export const composePermissionName = (
+  parts: { resource: string, action?: string }
+): string => parts.action == null || parts.action === ''
+  ? parts.resource
+  : `${parts.resource}${PERMISSION_ACTION_SEPARATOR}${parts.action}`
+
+/** True when the value is a usable permission name — well-formed and carrying no gate selector. */
+export const isPermissionName = (value: string): boolean =>
+  value !== '' && !value.includes(RESOURCE_PARAM_SEPARATOR)

package/src/types.ts

@@ -1,5 +1,87 @@
 import type { InitializedService } from '@owlmeans/context'
 import type { OidcProviderConfig } from '@owlmeans/oidc'
+import type {
+  GateParamSource, GateParamErrorCode, GateResolutionFailure, IamGrantMode, IamRemovalPolicy
+} from './consts.js'
+
+/**
+ * The parts of a request a gate selector may read.
+ *
+ * Structural on purpose: `AbstractRequest` is assignable to it, so `@owlmeans/server-iam` passes its
+ * request straight through, while tooling outside the server stack can resolve a selector against a
+ * plain object without taking a dependency on `@owlmeans/entrypoint`.
+ */
+export interface GateRequestLike {
+  params?: unknown
+  query?: unknown
+  body?: unknown
+  headers?: unknown
+  auth?: unknown
+}
+
+/** Where one gate param reads its resource id from. */
+export interface GateResourceSelector {
+  /** The selector text exactly as written, for diagnostics. */
+  readonly selector: string
+  /** Undefined for the bare form, which searches `sources` in order. */
+  readonly source?: GateParamSource
+  /** Length 1 and UNSPLIT for the bare form — a bare key may legally contain dots. */
+  readonly path: string[]
+  /** The explicit source, or `DEFAULT_GATE_PARAM_SOURCES`. */
+  readonly sources: GateParamSource[]
+}
+
+export interface GateParamProblem {
+  code: GateParamErrorCode
+  detail: string
+}
+
+export interface ParsedGateParam {
+  permission: string
+  /**
+   * @deprecated The bare-form flat key, kept so existing readers keep compiling. Read `resource`,
+   * which carries the source and the path for both forms.
+   */
+  resourceParam?: string
+  resource?: GateResourceSelector
+  error?: GateParamProblem
+}
+
+export interface GateResourceResolution {
+  id?: string
+  from?: GateParamSource
+  reason?: GateResolutionFailure
+}
+
+/** What an entrypoint declares, so a selector can be checked against it before it is ever deployed. */
+export interface GateParamAudit {
+  routePath?: string
+  routeParams?: string[]
+  filter?: {
+    query?: object
+    params?: object
+    body?: object
+    headers?: object
+  }
+}
+
+export interface GateParamIssue {
+  param: string
+  code: GateParamErrorCode
+  detail: string
+}
+
+/** A permission NAME taken apart. Never carries a selector — `@` is the gate's syntax alone. */
+export interface ParsedPermissionName {
+  /** The whole name, exactly as it must be stored and granted. */
+  name: string
+  /** What IAM stores as `resource`. The whole name when there is no action separator. */
+  resource: string
+  /** What IAM stores as `action`. Absent for a bare, unsplittable legacy name. */
+  action?: string
+  /** Set when the argument carried an `@` — which a NAME never legally does. */
+  problem?: GateParamProblem
+}
 
 export interface IamClient {
   id?: string
@@ -33,10 +115,32 @@ export interface IamClientOptions {
 export interface IamPermissionArgs {
   /** Action name. When absent the permission is unscoped (project-wide). */
   permission?: string
-  /** Declares that grants of this permission may be bound to specific resource ids. */
+  /**
+   * Declares that grants of this permission may be bound to specific resource ids.
+   *
+   * It does NOT mean grants must be: the same name is grantable in either form. A grant carrying no
+   * resource ids covers every resource, which is what `hasPermission` already implements.
+   */
   resourceScoped?: boolean
   /** Optional human-readable title for the permission definition. */
   title?: string
+  /**
+   * Grouping tag — one of `IAM_AREAS`, or any string a deployment defines.
+   *
+   * Purely presentational: it groups the permission in an administrator's screen and is never read
+   * when a request is authorized. It is a TAG rather than a name segment precisely so an existing
+   * permission can be grouped without renaming it, which would orphan every grant already made.
+   */
+  area?: string
+  /**
+   * Marks a permission the PLATFORM owns rather than one the application declared for itself.
+   *
+   * The distinction is not cosmetic: an operator must not be able to revoke a platform marker from
+   * an undifferentiated list, and a repair that deletes "definitions no declaration names" must not
+   * reach one — a marker can be enforced by a runtime decoration rather than by a gate parameter,
+   * so its absence from the declarations is not evidence that it is unused.
+   */
+  managed?: boolean
 }
 
 export interface IamResourceSpec {
@@ -46,17 +150,42 @@ export interface IamResourceSpec {
 
 /** A permission declared for an entity's client (project). */
 export interface IamPermissionDefinition {
-  /** Canonical name: "res--action" or bare "res" when unscoped. */
+  /** Canonical name: "res--action" or bare "res" when unscoped. NEVER carries an `@` selector. */
   name: string
   resource: string
   action?: string
   resourceScoped?: boolean
   title?: string
+  /** Grouping tag; presentational only. See `IamPermissionArgs.area`. */
+  area?: string
+  /** Owned by the platform rather than declared by the application. See `IamPermissionArgs.managed`. */
+  managed?: boolean
+}
+
+/** Narrows a definition listing. An `areas` entry of `null` matches definitions carrying no tag. */
+export interface IamPermissionFilter {
+  areas?: (string | null)[]
+  managed?: boolean
+  resourceScoped?: boolean
 }
 
 export interface IamGrantArgs {
   /** Resource ids for the resource-scoped grant form; omit for an unscoped (project-wide) grant. */
   resources?: string[]
+  /**
+   * Which form to address. THE DEFAULTS ARE ASYMMETRIC ON PURPOSE, to preserve the semantics every
+   * existing caller already relies on:
+   *
+   *   grantPermission  — `resources != null` ? Resources : Blanket
+   *   revokePermission — `resources != null` ? Resources : All
+   *
+   * Revoke defaults to `All` because a bare `revokePermission(...)` has always meant "remove it
+   * everywhere". Narrowing that to `Blanket` would leave the resource-scoped set standing for every
+   * existing caller — a live grant surviving a revoke, which is the failure direction nobody detects.
+   *
+   * Pass `mode` explicitly rather than depending on the default.
+   */
+  mode?: IamGrantMode
 }
 
 /** A permission granted to an end-user subject of an entity's client. */
@@ -68,6 +197,48 @@ export interface IamGrant {
   permission: string
   /** Present only for resource-scoped grants. */
   resources?: string[]
+  /** Which form this record is. Derived from `resources`, not new information. */
+  mode?: IamGrantMode
+}
+
+/** Grants every definition a filter selects, plus any named outright. */
+export interface IamGrantBundle {
+  filter?: IamPermissionFilter
+  /** Extra names included regardless of the filter — a platform marker, for instance. */
+  permissions?: string[]
+  /** Defaults to `Blanket`: a tier of access is a role, not a resource ACL. */
+  mode?: IamGrantMode
+  /** Only meaningful with `mode: Resources`. */
+  resources?: string[]
+}
+
+export interface IamPermissionDeleteArgs {
+  /** Defaults to `Cascade`. */
+  policy?: IamRemovalPolicy
+  /** Required to delete a `managed` definition. Defaults to false. */
+  managed?: boolean
+}
+
+export interface IamPermissionRemoval {
+  permission: string
+  clientId: string
+  /** The definition existed and was removed. False is a normal, non-error outcome. */
+  found: boolean
+  /** Grants stripped as part of the removal. */
+  revoked: IamGrant[]
+}
+
+export interface IamNormalizeArgs {
+  /** Compute and report the plan without writing anything. */
+  dryRun?: boolean
+}
+
+export interface IamNormalizationReport {
+  clientId: string
+  renamed: { from: string, to: string, grantsMoved: number }[]
+  merged: { from: string, into: string, grantsMoved: number }[]
+  /** Well-formed definitions deliberately left alone. */
+  untouched: string[]
 }
 
 /** An end-user of an entity (customer-wide; shared across that entity's projects). */
@@ -120,11 +291,50 @@ export interface IamService extends InitializedService {
   getIssuerUrl: (entityId: string) => Promise<string>
 
   // --- Provisioning (agent → story development) ---
+
+  /**
+   * Find-or-create the entity's OIDC client.
+   *
+   * A client id is globally unique — a provider resolves it from the bare `client_id` a relying
+   * party sends, with no tenant context — so an implementation MUST refuse an existing record
+   * that belongs to a different entity (`IamClientError('client:entity-mismatch')`) rather than
+   * returning it. Silently adopting one hands the caller another tenant's secret and overwrites
+   * that tenant's redirect URIs.
+   */
   ensureClient: (entityId: string, clientId: string, options?: IamClientOptions) => Promise<IamClient>
 
+  /**
+   * Reserve a client id for the entity without provisioning it, so a caller can find a free name
+   * before committing to it. Returns false when the id is already taken — by this entity or any
+   * other — and true when the reservation is now held.
+   *
+   * This exists because the id is minted from a name that may later be released (a project alias
+   * moves when its hostname is refused), so the naming index cannot answer whether an id is free.
+   * The registry is the only authority.
+   */
+  claimClient: (entityId: string, clientId: string) => Promise<boolean>
+
+  /**
+   * Release a client id and everything keyed by it. Called when a project or slot is deleted —
+   * without it a recreated project can inherit a stale registration.
+   */
+  deleteClient: (entityId: string, clientId: string) => Promise<void>
+
   /**
    * Ensures a permission/resource exists in the entity's client.
    * Returns the canonical resource name (e.g. "res--action" or "res").
+   *
+   * MERGES into an existing definition rather than replacing it: `resource` and `action` are
+   * re-derived and overwrite, while `title`, `resourceScoped`, `area` and `managed` are set when
+   * provided — including when provided as `false` — and KEPT when omitted. Replacing wholesale made
+   * every flag last-write-wins, so a caller that happened not to pass one erased it.
+   *
+   * It NEVER rewrites the name. Callers round-trip a definition's `resource` + `action` back through
+   * this method to copy a definition set between clients, so a rename here would silently orphan
+   * every grant made against the old name.
+   *
+   * The `resource` argument must not carry a gate selector: `@` is the gate's syntax and is never
+   * part of a stored name. Implementations reject one rather than storing a key no gate looks up.
    */
   ensurePermission: (
     entityId: string,
@@ -133,6 +343,49 @@ export interface IamService extends InitializedService {
     args?: IamPermissionArgs
   ) => Promise<string>
 
+  /**
+   * Removes permission definitions, and by default every grant that referenced them.
+   *
+   * Takes NAMES: the definition record is keyed by name, and a malformed definition's stored
+   * `resource`/`action` cannot be trusted to recompose that key. Accepts an array so a repair costs
+   * one sweep of the entity's subjects rather than one per name.
+   *
+   * Idempotent — a name with no definition yields `{ found: false }` and writes nothing. Every other
+   * lifecycle operation here converges rather than erroring, and two repairs may run concurrently on
+   * one project.
+   *
+   * Implementations MUST revoke the grants before dropping the definition. There is no transaction
+   * across the two stores, and a crash between them must leave a definition with no grants — visible
+   * and re-runnable — rather than grants with no definition, which are invisible to any screen that
+   * renders the definition list yet still satisfy a gate.
+   *
+   * A `managed` definition is refused unless `args.managed` is explicitly true.
+   */
+  deletePermission: (
+    entityId: string,
+    clientId: string,
+    permission: string | string[],
+    args?: IamPermissionDeleteArgs
+  ) => Promise<IamPermissionRemoval[]>
+
+  /**
+   * Repairs definitions whose stored name carries a gate selector, moving grants with them.
+   *
+   * Strictly a rename and merge — never a delete, never an invention. Where the stripped name
+   * already exists the two are merged, because one entrypoint scoping a permission by `:id` and
+   * another by `:enquiryId` describe ONE permission. The target is marked resource-scoped: a leaked
+   * selector is positive evidence that it is, and that evidence is otherwise discarded.
+   *
+   * Grants move in the same write that renames the definition, which is why this exists as its own
+   * operation: reconstructing it as delete + re-declare + re-grant drops real access on any failure
+   * between the three steps.
+   */
+  normalizePermissions: (
+    entityId: string,
+    clientId: string,
+    args?: IamNormalizeArgs
+  ) => Promise<IamNormalizationReport>
+
   /**
    * Idempotent: creates a resource, a client role for it, and assigns that role to
    * the entity-owner role. Used by payment provisioning for account/project/wl resources.
@@ -145,8 +398,12 @@ export interface IamService extends InitializedService {
 
   // --- Authorization (permission definitions & grants) ---
 
-  /** Lists permission definitions registered for the entity's client. */
-  listPermissions: (entityId: string, clientId: string) => Promise<IamPermissionDefinition[]>
+  /** Lists permission definitions registered for the entity's client, optionally narrowed. */
+  listPermissions: (
+    entityId: string,
+    clientId: string,
+    filter?: IamPermissionFilter
+  ) => Promise<IamPermissionDefinition[]>
 
   /**
    * Grants a permission to an end-user subject. With args.resources the grant is
@@ -172,14 +429,34 @@ export interface IamService extends InitializedService {
     args?: IamGrantArgs
   ) => Promise<void>
 
+  /**
+   * Grants every permission a bundle selects to each subject, idempotently.
+   *
+   * Exists as its own operation rather than a loop over `grantPermission` because a backend that
+   * loads-mutates-saves a subject per call turns N permissions across M subjects into N·M writes and
+   * N·M lost-update windows on the same records. Collapsing to one read and one write per subject is
+   * also what makes re-running it genuinely idempotent.
+   *
+   * Returns what each subject now holds, not what changed.
+   */
+  grantBundle: (
+    entityId: string,
+    clientId: string,
+    profileIds: string[],
+    bundle: IamGrantBundle
+  ) => Promise<IamGrant[]>
+
   /** Lists grants for the entity's client, optionally for a single subject. */
   listGrants: (entityId: string, clientId: string, profileId?: string) => Promise<IamGrant[]>
 
   // --- End-user management (customer-wide users, shared per entityId) ---
 
   /**
-   * Lists the entity's end-users. With clientId, narrows to users holding at least
-   * one grant for that client (per-project view).
+   * Lists the entity's end-users. End-users are customer-wide — shared across every project of
+   * the entity — so `clientId` scopes the reported `grantCount` to one project's client and does
+   * **not** filter the set: a user who has authenticated against a project but holds no grant
+   * there is still that project's user, and the screen that manages grants is exactly where they
+   * must be visible.
    */
   listUsers: (entityId: string, clientId?: string) => Promise<IamUser[]>