@owlmeans/iam 0.1.7 → 0.1.8

package/README.md

@@ -0,0 +1,46 @@
+# @owlmeans/iam
+
+Provider-agnostic IAM abstraction for the OwlMeans framework — `IamService` interface, client/realm types, and permission helpers.
+
+## Overview
+
+- `IamService` — unified interface for provisioning clients, realms, and permissions across IAM backends (e.g. Keycloak, built-in)
+- `IamClient` / `IamCredentialsPair` / `IamResourceSpec` — shared contract types used by server-side IAM implementations
+- `IamPermissionArgs` — describes a named permission including resource-scope and human-readable title
+- `hasPermission` — utility to check whether a set of grants covers a given permission/resource pair
+- Errors: `IamError` and subtypes for client-provisioning and permission failures
+
+## Installation
+
+```bash
+bun add @owlmeans/iam
+```
+
+## Usage
+
+```typescript
+import type { IamService, IamClient } from '@owlmeans/iam'
+import { hasPermission } from '@owlmeans/iam'
+
+// Check whether an auth payload includes a required permission
+const allowed = hasPermission(auth, { permission: 'manage-users', resourceScoped: false })
+```
+
+Typically consumed via `@owlmeans/server-iam` which wires the concrete OIDC-backed implementation.
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded Claude Code skills and GitHub Copilot instructions under
+`agent-meta/`. After installing your `@owlmeans/*` packages, run the OwlMeans
+agent-skills installer to place them into your project's native locations
+(`.claude/skills/` and `.github/instructions/`):
+
+```sh
+npx @owlmeans/agent-skills
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/instructions/iam.instructions.md

@@ -0,0 +1,115 @@
+---
+description: "IamService abstraction for provider-agnostic IAM provisioning. Load when wiring IAM operations, switching IAM mode, or implementing a new IAM provider."
+applyTo: "**/services/iam*.ts, **/context.ts, **/types.ts"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# 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`.
+
+## Public API surface
+
+| Symbol | Kind | Purpose |
+|--------|------|---------|
+| `IamService` | type | Unified IAM interface — all provisioning + authorization operations |
+| `IamClient` | type | Provisioned OIDC client `{ id?, clientId, secret?, name?, realm? }` |
+| `IamCredentialsPair` | type | `{ token: string; realm: string }` |
+| `IamPermissionArgs` | type | `{ permission?, resourceScoped?, title? }` — `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? }` |
+| `hasPermission` | fn | `(auth, permission, { scope?, resourceId? }?)` — checks `Authorization.permissions` PermissionSet[]; an unscoped set satisfies a resourceId check |
+| `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 |
+| `IamGrantError` | class | Grant subject missing or entity mismatch |
+| `IamUnsupported` | class | Operation not supported by the active backend (e.g. resource-scoped grants on Keycloak) |
+
+## Permission model (two 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).
+
+## `IamService` interface
+
+```ts
+interface IamService extends InitializedService {
+  // Get the admin OIDC provider config for a tenant (used in payment provisioning, RP config)
+  getEntityAdminConfig: (entityId: string) => Promise<OidcProviderConfig>
+
+  // Get an admin { token, realm } pair for raw low-level calls (avoid unless necessary)
+  getCredentialsPair: (entityId: string) => Promise<IamCredentialsPair>
+
+  // Provision an OIDC client for a tenant and return its credentials
+  ensureClient: (entityId: string, clientId: string) => Promise<IamClient>
+
+  // Provision a named permission on a client resource; returns the resource name
+  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)
+  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[]>
+
+  // Grant a permission to an end-user subject; args.resources = resource-scoped form
+  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
+  listGrants: (entityId: string, clientId: string, profileId?: string) => Promise<IamGrant[]>
+}
+```
+
+## `IamClient.realm` field
+
+`realm` is set by the provider to the entity ID. Use it instead of accessing internal properties:
+
+```ts
+// ✓ correct
+await meta.update('oidcRealm', client.realm ?? fallbackEntityId)
+
+// ✗ never do this — internal Keycloak implementation detail
+await meta.update('oidcRealm', (client as any)._realm)
+```
+
+## Selecting the IAM provider
+
+The platform wires the correct implementation via `IAM_MODE` environment variable. Default is `'keycloak'`. Do not read `IAM_MODE` directly from feature code — it belongs in the service-factory only:
+
+```ts
+export const makeIamService = (mode = process.env.IAM_MODE ?? 'keycloak') => {
+  if (mode === 'integrated') return makeIamIntegratedService(VIABLE_IAM)
+  return makeIamKeycloakService(VIABLE_IAM, { oidcProductAlias: OIDC_PRODUCT })
+}
+```
+
+## Rules
+
+- 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.
+
+## Related instructions
+
+- `@owlmeans/iam-keycloak` (internal) — full proxy over Keycloak; see `iam-keycloak.instructions.md`
+- `@owlmeans/keycloak` (internal) — low-level KC admin API; see `keycloak.instructions.md`
+- `@owlmeans/server-iam` — IAM gate asserting both grant forms; see `server-iam.instructions.md`

package/agent-meta/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "package": "@owlmeans/iam",
+  "version": "0.1.8",
+  "generatedAt": "2026-06-11T16:30:27.190Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "instruction",
+      "name": "iam",
+      "category": "package-specific",
+      "file": "instructions/iam.instructions.md",
+      "canonicalPath": ".github/instructions/iam.instructions.md"
+    }
+  ]
+}

package/build/errors.d.ts

@@ -19,4 +19,8 @@ export declare class IamUnsupported extends IamError {
     static typeName: string;
     constructor(message?: string);
 }
+export declare class IamUserError extends IamError {
+    static typeName: string;
+    constructor(message?: string);
+}
 //# sourceMappingURL=errors.d.ts.map

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;gBAErD,OAAO,SAAU;CAI9B;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAAwC;gBAE3D,OAAO,SAAU;CAI9B;AAED,qBAAa,gBAAiB,SAAQ,QAAQ;IAC5C,OAAuB,QAAQ,SAA0C;gBAE7D,OAAO,SAAU;CAI9B;AAED,qBAAa,aAAc,SAAQ,QAAQ;IACzC,OAAuB,QAAQ,SAAuC;gBAE1D,OAAO,SAAU;CAI9B;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAA6C;gBAEhE,OAAO,SAAU;CAI9B"}
+{"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;gBAErD,OAAO,SAAU;CAI9B;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAAwC;gBAE3D,OAAO,SAAU;CAI9B;AAED,qBAAa,gBAAiB,SAAQ,QAAQ;IAC5C,OAAuB,QAAQ,SAA0C;gBAE7D,OAAO,SAAU;CAI9B;AAED,qBAAa,aAAc,SAAQ,QAAQ;IACzC,OAAuB,QAAQ,SAAuC;gBAE1D,OAAO,SAAU;CAI9B;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAA6C;gBAEhE,OAAO,SAAU;CAI9B;AAED,qBAAa,YAAa,SAAQ,QAAQ;IACxC,OAAuB,QAAQ,SAAsC;gBAEzD,OAAO,SAAU;CAI9B"}

package/build/errors.js

@@ -34,9 +34,17 @@ export class IamUnsupported extends IamError {
         this.type = IamUnsupported.typeName;
     }
 }
+export class IamUserError extends IamError {
+    static typeName = `IamUser${ResilientError.typeName}`;
+    constructor(message = 'error') {
+        super(`user:${message}`);
+        this.type = IamUserError.typeName;
+    }
+}
 ResilientError.registerErrorClass(IamError);
 ResilientError.registerErrorClass(IamClientError);
 ResilientError.registerErrorClass(IamResourceError);
 ResilientError.registerErrorClass(IamGrantError);
 ResilientError.registerErrorClass(IamUnsupported);
+ResilientError.registerErrorClass(IamUserError);
 //# sourceMappingURL=errors.js.map

package/build/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,OAAO,QAAS,SAAQ,cAAc;IACnC,MAAM,CAAU,QAAQ,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEjE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,OAAO,EAAE,CAAC,CAAA;QAC1C,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAA;IAC/B,CAAC;;AAGH,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACnC,MAAM,CAAU,QAAQ,GAAG,YAAY,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEvE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAA;IACrC,CAAC;;AAGH,MAAM,OAAO,gBAAiB,SAAQ,QAAQ;IACrC,MAAM,CAAU,QAAQ,GAAG,cAAc,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEzE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,YAAY,OAAO,EAAE,CAAC,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC,QAAQ,CAAA;IACvC,CAAC;;AAGH,MAAM,OAAO,aAAc,SAAQ,QAAQ;IAClC,MAAM,CAAU,QAAQ,GAAG,WAAW,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEtE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,SAAS,OAAO,EAAE,CAAC,CAAA;QACzB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC,QAAQ,CAAA;IACpC,CAAC;;AAGH,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACnC,MAAM,CAAU,QAAQ,GAAG,iBAAiB,cAAc,CAAC,QAAQ,EAAE,CAAA;IAE5E,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAA;QAC/B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAA;IACrC,CAAC;;AAGH,cAAc,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAA;AAC3C,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA;AACjD,cAAc,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAA;AACnD,cAAc,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAA;AAChD,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,OAAO,QAAS,SAAQ,cAAc;IACnC,MAAM,CAAU,QAAQ,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEjE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,OAAO,EAAE,CAAC,CAAA;QAC1C,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAA;IAC/B,CAAC;;AAGH,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACnC,MAAM,CAAU,QAAQ,GAAG,YAAY,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEvE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAA;IACrC,CAAC;;AAGH,MAAM,OAAO,gBAAiB,SAAQ,QAAQ;IACrC,MAAM,CAAU,QAAQ,GAAG,cAAc,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEzE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,YAAY,OAAO,EAAE,CAAC,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC,QAAQ,CAAA;IACvC,CAAC;;AAGH,MAAM,OAAO,aAAc,SAAQ,QAAQ;IAClC,MAAM,CAAU,QAAQ,GAAG,WAAW,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEtE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,SAAS,OAAO,EAAE,CAAC,CAAA;QACzB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC,QAAQ,CAAA;IACpC,CAAC;;AAGH,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACnC,MAAM,CAAU,QAAQ,GAAG,iBAAiB,cAAc,CAAC,QAAQ,EAAE,CAAA;IAE5E,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAA;QAC/B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAA;IACrC,CAAC;;AAGH,MAAM,OAAO,YAAa,SAAQ,QAAQ;IACjC,MAAM,CAAU,QAAQ,GAAG,UAAU,cAAc,CAAC,QAAQ,EAAE,CAAA;IAErE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,QAAQ,OAAO,EAAE,CAAC,CAAA;QACxB,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAA;IACnC,CAAC;;AAGH,cAAc,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAA;AAC3C,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA;AACjD,cAAc,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAA;AACnD,cAAc,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAA;AAChD,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA;AACjD,cAAc,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAA"}

package/build/types.d.ts

@@ -47,6 +47,32 @@ export interface IamGrant {
     /** Present only for resource-scoped grants. */
     resources?: string[];
 }
+/** An end-user of an entity (customer-wide; shared across that entity's projects). */
+export interface IamUser {
+    /** Backend-specific subject id: integrated = IdentityProfile.profileId, keycloak = KC user id. */
+    profileId: string;
+    /** Primary login identifier (email for the integrated OTP path). */
+    email?: string;
+    name?: string;
+    /** AuthRole value. */
+    role: string;
+    disabled?: boolean;
+    /** Convenience count of permission grants the user holds (across clients, or for one client). */
+    grantCount?: number;
+}
+/** Args to invite/create an end-user under an entity. */
+export interface IamUserInvite {
+    email: string;
+    name?: string;
+    /** AuthRole value; defaults to the backend's standard end-user role. */
+    role?: string;
+}
+/** Args to update an existing end-user. */
+export interface IamUserUpdate {
+    name?: string;
+    role?: string;
+    disabled?: boolean;
+}
 /** Unified IAM provider interface — all platform/agent code calls only this, never a backend directly */
 export interface IamService extends InitializedService {
     getEntityAdminConfig: (entityId: string) => Promise<OidcProviderConfig>;
@@ -76,5 +102,18 @@ export interface IamService extends InitializedService {
     revokePermission: (entityId: string, clientId: string, profileId: string, permission: string, args?: IamGrantArgs) => Promise<void>;
     /** Lists grants for the entity's client, optionally for a single subject. */
     listGrants: (entityId: string, clientId: string, profileId?: string) => Promise<IamGrant[]>;
+    /**
+     * Lists the entity's end-users. With clientId, narrows to users holding at least
+     * one grant for that client (per-project view).
+     */
+    listUsers: (entityId: string, clientId?: string) => Promise<IamUser[]>;
+    /** Loads a single end-user by subject id, or null when absent. */
+    getUser: (entityId: string, profileId: string) => Promise<IamUser | null>;
+    /** Creates (or resolves, idempotently by email) an end-user under the entity. */
+    inviteUser: (entityId: string, invite: IamUserInvite) => Promise<IamUser>;
+    /** Updates an end-user's mutable fields (name, role, disabled). */
+    updateUser: (entityId: string, profileId: string, update: IamUserUpdate) => Promise<IamUser>;
+    /** Removes an end-user from the entity (their grants go with them). */
+    removeUser: (entityId: string, profileId: string) => Promise<void>;
 }
 //# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAExD,MAAM,WAAW,SAAS;IACxB,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qFAAqF;IACrF,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,8DAA8D;AAC9D,MAAM,WAAW,uBAAuB;IACtC,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,kGAAkG;IAClG,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CACrB;AAED,yEAAyE;AACzE,MAAM,WAAW,QAAQ;IACvB,kGAAkG;IAClG,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAA;IAClB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CACrB;AAED,sFAAsF;AACtF,MAAM,WAAW,OAAO;IACtB,kGAAkG;IAClG,SAAS,EAAE,MAAM,CAAA;IACjB,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,iGAAiG;IACjG,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,yGAAyG;AACzG,MAAM,WAAW,UAAW,SAAQ,kBAAkB;IAEpD,oBAAoB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAA;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAGrE,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAA;IAExE;;;OAGG;IACH,gBAAgB,EAAE,CAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,iBAAiB,KACrB,OAAO,CAAC,MAAM,CAAC,CAAA;IAEpB;;;OAGG;IACH,uBAAuB,EAAE,CACvB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,eAAe,KACtB,OAAO,CAAC,IAAI,CAAC,CAAA;IAIlB,uEAAuE;IACvE,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAA;IAE3F;;;OAGG;IACH,eAAe,EAAE,CACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,YAAY,KAChB,OAAO,CAAC,QAAQ,CAAC,CAAA;IAEtB;;;OAGG;IACH,gBAAgB,EAAE,CAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,YAAY,KAChB,OAAO,CAAC,IAAI,CAAC,CAAA;IAElB,6EAA6E;IAC7E,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;IAI3F;;;OAGG;IACH,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;IAEtE,kEAAkE;IAClE,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAA;IAEzE,iFAAiF;IACjF,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAEzE,mEAAmE;IACnE,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAE5F,uEAAuE;IACvE,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACnE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/iam",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,10 +22,10 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.7",
-    "@owlmeans/context": "^0.1.7",
-    "@owlmeans/error": "^0.1.7",
-    "@owlmeans/oidc": "^0.1.7"
+    "@owlmeans/auth": "^0.1.8",
+    "@owlmeans/context": "^0.1.8",
+    "@owlmeans/error": "^0.1.8",
+    "@owlmeans/oidc": "^0.1.8"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",

package/src/errors.ts

@@ -45,8 +45,18 @@ export class IamUnsupported extends IamError {
   }
 }
 
+export class IamUserError extends IamError {
+  public static override typeName = `IamUser${ResilientError.typeName}`
+
+  constructor(message = 'error') {
+    super(`user:${message}`)
+    this.type = IamUserError.typeName
+  }
+}
+
 ResilientError.registerErrorClass(IamError)
 ResilientError.registerErrorClass(IamClientError)
 ResilientError.registerErrorClass(IamResourceError)
 ResilientError.registerErrorClass(IamGrantError)
 ResilientError.registerErrorClass(IamUnsupported)
+ResilientError.registerErrorClass(IamUserError)

package/src/types.ts

@@ -55,6 +55,35 @@ export interface IamGrant {
   resources?: string[]
 }
 
+/** An end-user of an entity (customer-wide; shared across that entity's projects). */
+export interface IamUser {
+  /** Backend-specific subject id: integrated = IdentityProfile.profileId, keycloak = KC user id. */
+  profileId: string
+  /** Primary login identifier (email for the integrated OTP path). */
+  email?: string
+  name?: string
+  /** AuthRole value. */
+  role: string
+  disabled?: boolean
+  /** Convenience count of permission grants the user holds (across clients, or for one client). */
+  grantCount?: number
+}
+
+/** Args to invite/create an end-user under an entity. */
+export interface IamUserInvite {
+  email: string
+  name?: string
+  /** AuthRole value; defaults to the backend's standard end-user role. */
+  role?: string
+}
+
+/** Args to update an existing end-user. */
+export interface IamUserUpdate {
+  name?: string
+  role?: string
+  disabled?: boolean
+}
+
 /** Unified IAM provider interface — all platform/agent code calls only this, never a backend directly */
 export interface IamService extends InitializedService {
   // --- Admin config (backend → OIDC RP config, payment provisioning) ---
@@ -116,4 +145,24 @@ export interface IamService extends InitializedService {
 
   /** 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).
+   */
+  listUsers: (entityId: string, clientId?: string) => Promise<IamUser[]>
+
+  /** Loads a single end-user by subject id, or null when absent. */
+  getUser: (entityId: string, profileId: string) => Promise<IamUser | null>
+
+  /** Creates (or resolves, idempotently by email) an end-user under the entity. */
+  inviteUser: (entityId: string, invite: IamUserInvite) => Promise<IamUser>
+
+  /** Updates an end-user's mutable fields (name, role, disabled). */
+  updateUser: (entityId: string, profileId: string, update: IamUserUpdate) => Promise<IamUser>
+
+  /** Removes an end-user from the entity (their grants go with them). */
+  removeUser: (entityId: string, profileId: string) => Promise<void>
 }