@owlmeans/iam 0.1.6 → 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

@@ -11,4 +11,16 @@ export declare class IamResourceError extends IamError {
     static typeName: string;
     constructor(message?: string);
 }
+export declare class IamGrantError extends IamError {
+    static typeName: string;
+    constructor(message?: string);
+}
+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"}
+{"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

@@ -20,7 +20,31 @@ export class IamResourceError extends IamError {
         this.type = IamResourceError.typeName;
     }
 }
+export class IamGrantError extends IamError {
+    static typeName = `IamGrant${ResilientError.typeName}`;
+    constructor(message = 'error') {
+        super(`grant:${message}`);
+        this.type = IamGrantError.typeName;
+    }
+}
+export class IamUnsupported extends IamError {
+    static typeName = `IamUnsupported${ResilientError.typeName}`;
+    constructor(message = 'error') {
+        super(`unsupported:${message}`);
+        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,cAAc,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAA;AAC3C,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA;AACjD,cAAc,CAAC,kBAAkB,CAAC,gBAAgB,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/index.d.ts

@@ -1,4 +1,5 @@
 export type * from './types.js';
 export * from './consts.js';
 export * from './errors.js';
+export * from './utils.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA"}

package/build/index.js

@@ -1,3 +1,4 @@
 export * from './consts.js';
 export * from './errors.js';
+export * from './utils.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA"}

package/build/types.d.ts

@@ -15,11 +15,64 @@ export interface IamCredentialsPair {
 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. */
+    resourceScoped?: boolean;
+    /** Optional human-readable title for the permission definition. */
+    title?: string;
 }
 export interface IamResourceSpec {
     name: string;
     displayName?: string;
 }
+/** A permission declared for an entity's client (project). */
+export interface IamPermissionDefinition {
+    /** Canonical name: "res--action" or bare "res" when unscoped. */
+    name: string;
+    resource: string;
+    action?: string;
+    resourceScoped?: boolean;
+    title?: string;
+}
+export interface IamGrantArgs {
+    /** Resource ids for the resource-scoped grant form; omit for an unscoped (project-wide) grant. */
+    resources?: string[];
+}
+/** A permission granted to an end-user subject of an entity's client. */
+export interface IamGrant {
+    /** Backend-specific subject id: integrated = IdentityProfile.profileId, keycloak = KC user id. */
+    profileId: string;
+    clientId: string;
+    /** Canonical permission name. */
+    permission: string;
+    /** 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>;
@@ -35,5 +88,32 @@ export interface IamService extends InitializedService {
      * the entity-owner role. Used by payment provisioning for account/project/wl resources.
      */
     ensureResourceOwnership: (entityId: string, clientId: string, resource: IamResourceSpec) => Promise<void>;
+    /** Lists permission definitions registered for the entity's client. */
+    listPermissions: (entityId: string, clientId: string) => Promise<IamPermissionDefinition[]>;
+    /**
+     * Grants a permission to an end-user subject. With args.resources the grant is
+     * resource-scoped (bound to those resource ids); without it the grant is project-wide.
+     */
+    grantPermission: (entityId: string, clientId: string, profileId: string, permission: string, args?: IamGrantArgs) => Promise<IamGrant>;
+    /**
+     * Revokes a grant. With args.resources only those resource ids are removed;
+     * without it the whole grant is removed.
+     */
+    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":"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;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;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;CACnB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/build/utils.d.ts

@@ -0,0 +1,13 @@
+import type { Authorization } from '@owlmeans/auth';
+export interface HasPermissionOptions {
+    /** Restrict the check to PermissionSets of this scope (the project's clientId). */
+    scope?: string;
+    /** Resource-scoped check: the set must list this id — unless the set itself is unscoped. */
+    resourceId?: string;
+}
+/**
+ * True when any PermissionSet grants `permission`. An unscoped set (no resources)
+ * satisfies a resourceId check too — a project-wide grant covers every resource.
+ */
+export declare const hasPermission: (auth: Authorization, permission: string, opts?: HasPermissionOptions) => boolean;
+//# sourceMappingURL=utils.d.ts.map

package/build/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,aAAa,EACnB,YAAY,MAAM,EAClB,OAAO,oBAAoB,KAC1B,OAIO,CAAA"}

package/build/utils.js

@@ -0,0 +1,8 @@
+/**
+ * True when any PermissionSet grants `permission`. An unscoped set (no resources)
+ * satisfies a resourceId check too — a project-wide grant covers every resource.
+ */
+export const hasPermission = (auth, permission, opts) => auth.permissions?.some(set => (opts?.scope == null || set.scope === opts.scope)
+    && set.permissions[permission] === true
+    && (opts?.resourceId == null || set.resources == null || set.resources.includes(opts.resourceId))) ?? false;
+//# sourceMappingURL=utils.js.map

package/build/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,IAAmB,EACnB,UAAkB,EAClB,IAA2B,EAClB,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CACzC,CAAC,IAAI,EAAE,KAAK,IAAI,IAAI,IAAI,GAAG,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,CAAC;OAC9C,GAAG,CAAC,WAAW,CAAC,UAAU,CAAC,KAAK,IAAI;OACpC,CAAC,IAAI,EAAE,UAAU,IAAI,IAAI,IAAI,GAAG,CAAC,SAAS,IAAI,IAAI,IAAI,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAClG,IAAI,KAAK,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/iam",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,9 +22,10 @@
     }
   },
   "dependencies": {
-    "@owlmeans/context": "^0.1.6",
-    "@owlmeans/error": "^0.1.6",
-    "@owlmeans/oidc": "^0.1.6"
+    "@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

@@ -27,6 +27,36 @@ export class IamResourceError extends IamError {
   }
 }
 
+export class IamGrantError extends IamError {
+  public static override typeName = `IamGrant${ResilientError.typeName}`
+
+  constructor(message = 'error') {
+    super(`grant:${message}`)
+    this.type = IamGrantError.typeName
+  }
+}
+
+export class IamUnsupported extends IamError {
+  public static override typeName = `IamUnsupported${ResilientError.typeName}`
+
+  constructor(message = 'error') {
+    super(`unsupported:${message}`)
+    this.type = IamUnsupported.typeName
+  }
+}
+
+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/index.ts

@@ -1,3 +1,4 @@
 export type * from './types.js'
 export * from './consts.js'
 export * from './errors.js'
+export * from './utils.js'

package/src/types.ts

@@ -18,6 +18,10 @@ export interface IamCredentialsPair {
 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. */
+  resourceScoped?: boolean
+  /** Optional human-readable title for the permission definition. */
+  title?: string
 }
 
 export interface IamResourceSpec {
@@ -25,6 +29,61 @@ export interface IamResourceSpec {
   displayName?: string
 }
 
+/** A permission declared for an entity's client (project). */
+export interface IamPermissionDefinition {
+  /** Canonical name: "res--action" or bare "res" when unscoped. */
+  name: string
+  resource: string
+  action?: string
+  resourceScoped?: boolean
+  title?: string
+}
+
+export interface IamGrantArgs {
+  /** Resource ids for the resource-scoped grant form; omit for an unscoped (project-wide) grant. */
+  resources?: string[]
+}
+
+/** A permission granted to an end-user subject of an entity's client. */
+export interface IamGrant {
+  /** Backend-specific subject id: integrated = IdentityProfile.profileId, keycloak = KC user id. */
+  profileId: string
+  clientId: string
+  /** Canonical permission name. */
+  permission: string
+  /** 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 {
   // --- Admin config (backend → OIDC RP config, payment provisioning) ---
@@ -54,4 +113,56 @@ export interface IamService extends InitializedService {
     clientId: string,
     resource: IamResourceSpec
   ) => Promise<void>
+
+  // --- Authorization (permission definitions & grants) ---
+
+  /** Lists permission definitions registered for the entity's client. */
+  listPermissions: (entityId: string, clientId: string) => Promise<IamPermissionDefinition[]>
+
+  /**
+   * Grants a permission to an end-user subject. With args.resources the grant is
+   * resource-scoped (bound to those resource ids); without it the grant is project-wide.
+   */
+  grantPermission: (
+    entityId: string,
+    clientId: string,
+    profileId: string,
+    permission: string,
+    args?: IamGrantArgs
+  ) => Promise<IamGrant>
+
+  /**
+   * Revokes a grant. With args.resources only those resource ids are removed;
+   * without it the whole grant is removed.
+   */
+  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[]>
+
+  // --- 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>
 }

package/src/utils.ts

@@ -0,0 +1,22 @@
+import type { Authorization } from '@owlmeans/auth'
+
+export interface HasPermissionOptions {
+  /** Restrict the check to PermissionSets of this scope (the project's clientId). */
+  scope?: string
+  /** Resource-scoped check: the set must list this id — unless the set itself is unscoped. */
+  resourceId?: string
+}
+
+/**
+ * True when any PermissionSet grants `permission`. An unscoped set (no resources)
+ * satisfies a resourceId check too — a project-wide grant covers every resource.
+ */
+export const hasPermission = (
+  auth: Authorization,
+  permission: string,
+  opts?: HasPermissionOptions
+): boolean => auth.permissions?.some(set =>
+  (opts?.scope == null || set.scope === opts.scope)
+  && set.permissions[permission] === true
+  && (opts?.resourceId == null || set.resources == null || set.resources.includes(opts.resourceId))
+) ?? false

package/tests/utils.spec.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'bun:test'
+import { hasPermission } from '@owlmeans/iam'
+import type { Authorization } from '@owlmeans/auth'
+
+const auth: Authorization = {
+  scopes: [],
+  permissions: [
+    // unscoped (project-wide) grant — shared set per client
+    { scope: 'my-project', permissions: { 'article--modify': true } },
+    // resource-scoped grant — dedicated set carrying its resource ids
+    {
+      scope: 'my-project',
+      title: 'department--modify',
+      permissions: { 'department--modify': true },
+      resources: ['dep-12345678']
+    }
+  ]
+}
+
+describe('@owlmeans/iam — hasPermission', () => {
+  test('grants an unscoped permission', () => {
+    expect(hasPermission(auth, 'article--modify')).toBe(true)
+    expect(hasPermission(auth, 'article--delete')).toBe(false)
+  })
+
+  test('grants a resource-scoped permission only for listed resource ids', () => {
+    expect(hasPermission(auth, 'department--modify', { resourceId: 'dep-12345678' })).toBe(true)
+    expect(hasPermission(auth, 'department--modify', { resourceId: 'dep-87654321' })).toBe(false)
+  })
+
+  test('an unscoped set satisfies a resourceId check (project-wide grant covers every resource)', () => {
+    expect(hasPermission(auth, 'article--modify', { resourceId: 'art-12345678' })).toBe(true)
+  })
+
+  test('scope option restricts the check to one client', () => {
+    expect(hasPermission(auth, 'article--modify', { scope: 'my-project' })).toBe(true)
+    expect(hasPermission(auth, 'article--modify', { scope: 'other-project' })).toBe(false)
+  })
+})