@owlmeans/server-iam 0.1.6 → 0.1.8

package/README.md

@@ -0,0 +1,48 @@
+# @owlmeans/server-iam
+
+One-call OIDC RP wiring and IAM gate for OwlMeans servers — `appendIam()` and the permission-asserting `makeIamGate`.
+
+## Overview
+
+- `appendIam(context)` — registers the OIDC client, wrapping service, and IAM gate in a single call, replacing verbose manual wiring
+- `makeIamGate()` — produces a guard that asserts unscoped or resource-scoped permissions against the IAM backend (claims-first, UMA2 fallback)
+- Re-exports `hasPermission` from `@owlmeans/iam` for inline permission checks
+- Designed for IAM consumers such as the viable target template backend
+
+## Installation
+
+```bash
+bun add @owlmeans/server-iam
+```
+
+## Usage
+
+```typescript
+import { appendIam, makeIamGate } from '@owlmeans/server-iam'
+import { IAM_GATE } from '@owlmeans/server-iam'
+
+// Wire IAM into a server context
+appendIam(context)
+
+// Gate a module with a permission check
+module.gate(IAM_GATE, { permission: 'manage-users' })
+```
+
+Requires `@owlmeans/oidc` OIDC shared config and a running IAM provider configured via `@owlmeans/server-oidc-rp`.
+
+<!-- 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/server-iam.instructions.md

@@ -0,0 +1,63 @@
+---
+description: "How to use @owlmeans/server-iam — one-call OIDC RP wiring (appendIam) and the IAM gate that asserts unscoped and resource-scoped permissions (claims-first, UMA2 fallback). Use when gating server endpoints in IAM consumers (e.g. the viable target template backend)."
+applyTo: "**/owlmeans.ts, **/gate*.ts, **/auth-guard*.ts"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Using `@owlmeans/server-iam`
+
+Boilerplate-less server-side consumer of the OwlMeans IAM. One call wires the OIDC RP stack and the
+IAM gate; the consumer never knows which IAM backend (Keycloak or integrated) is active.
+
+## Public API surface
+
+| Symbol | Kind | Purpose |
+|--------|------|---------|
+| `appendIam(context)` | fn | Registers `makeOidcClientService()`, `makeOidcWrappingService()`, `makeIamGate()` (under `OIDC_GATE`), and the OIDC guard |
+| `makeIamGate(alias?)` | fn | The IAM `GateService` — claims-first assertion with UMA2 fallback |
+| `parseGateParam(param)` | fn | Splits `'perm@requestParam'` into `{ permission, resourceParam? }` |
+| `RESOURCE_PARAM_SEPARATOR` | const | `'@'` |
+| `hasPermission` | fn | Re-export from `@owlmeans/iam` |
+
+## Gate-param syntax
+
+```
+<permission>                      → unscoped (project-wide): 'article--modify'
+<permission>@<requestParam>       → resource-scoped: 'department--modify@departmentId'
+```
+
+- `{entity}` substitution applies to the permission part in both forms.
+- For the resource-scoped form the gate resolves `req.params[requestParam] ?? req.query[requestParam]`
+  at assert time and requires the grant's `resources[]` to contain it (an unscoped grant always passes).
+- Params are **any-of**: one granted param is enough.
+
+```ts
+// module declaration
+gate(OIDC_GATE, ['department--modify@depId'])
+
+// or imperative
+await ctx.service<GateService>(OIDC_GATE).assert(req, res, ['article--modify'])
+```
+
+## How the gate decides
+
+1. `req.auth == null` → `AuthForbidden('auth')`.
+2. **Claims mode** — when `req.auth.permissions` is a valid `PermissionSet[]` (minted into the id_token
+   by the integrated IAM provider and mapped into `Auth` by `@owlmeans/server-oidc-rp`), params are
+   asserted locally via `hasPermission`.
+3. **Fallback** — otherwise `@…` suffixes are stripped and the check delegates to the UMA2 gate model
+   from `@owlmeans/server-oidc-rp` (`createGateModel().loadPermissions`) — byte-equivalent to the old
+   `makeOidcGate`, which keeps Keycloak-backed deployments unchanged.
+
+## Rules
+
+- Register the gate via `appendIam()`; do not also register `makeOidcGate()` — both use the
+  `OIDC_GATE` alias and the IAM gate already covers the UMA2 path.
+- Never branch on the IAM backend in consumer code — the gate's claims/fallback split is the only seam.
+- The OIDC provider entry must request the `permissions` scope (`extraScopes`) for claims mode to
+  engage; without it the gate transparently uses the fallback.
+
+## Related instructions
+
+- `@owlmeans/iam` — abstraction + `hasPermission`; see `iam.instructions.md`
+- `@owlmeans/server-oidc-rp` — claim extraction + UMA2 model; see `server-oidc-rp.instructions.md`

package/agent-meta/manifest.json

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

package/build/append.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"append.d.ts","sourceRoot":"","sources":["../src/append.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAC3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAGtD,KAAK,eAAe,GAAG,YAAY,GAAG,gBAAgB,CAAA;AACtD,KAAK,gBAAgB,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,IAAI,aAAa,CAAC,CAAC,CAAC,CAAA;AAErF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,eAAe,EAAE,CAAC,SAAS,gBAAgB,CAAC,CAAC,CAAC,EAChF,SAAS,CAAC,KACT,CAMF,CAAA"}
+{"version":3,"file":"append.d.ts","sourceRoot":"","sources":["../src/append.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAC3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAItD,KAAK,eAAe,GAAG,YAAY,GAAG,gBAAgB,CAAA;AACtD,KAAK,gBAAgB,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,IAAI,aAAa,CAAC,CAAC,CAAC,CAAA;AAErF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,eAAe,EAAE,CAAC,SAAS,gBAAgB,CAAC,CAAC,CAAC,EAChF,SAAS,CAAC,KACT,CAQF,CAAA"}

package/build/append.js

@@ -1,4 +1,5 @@
-import { appendOidcGuard, makeOidcClientService, makeOidcGate, makeOidcWrappingService } from '@owlmeans/server-oidc-rp';
+import { appendOidcGuard, makeOidcClientService, makeOidcWrappingService } from '@owlmeans/server-oidc-rp';
+import { makeIamGate } from './gate.js';
 /**
  * One-call OIDC RP setup for a server context.
  *
@@ -14,7 +15,9 @@ import { appendOidcGuard, makeOidcClientService, makeOidcGate, makeOidcWrappingS
 export const appendIam = (context) => {
     context.registerService(makeOidcClientService());
     context.registerService(makeOidcWrappingService());
-    context.registerService(makeOidcGate());
+    // IAM gate under the OIDC_GATE alias: claims-first (integrated mode),
+    // UMA2 fallback byte-equivalent to makeOidcGate (keycloak mode)
+    context.registerService(makeIamGate());
     appendOidcGuard(context);
     return context;
 };

package/build/append.js.map

@@ -1 +1 @@
-{"version":3,"file":"append.js","sourceRoot":"","sources":["../src/append.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAA;AAKxH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,OAAU,EACP,EAAE;IACL,OAAO,CAAC,eAAe,CAAC,qBAAqB,EAAE,CAAC,CAAA;IAChD,OAAO,CAAC,eAAe,CAAC,uBAAuB,EAAE,CAAC,CAAA;IAClD,OAAO,CAAC,eAAe,CAAC,YAAY,EAAE,CAAC,CAAA;IACvC,eAAe,CAAO,OAAO,CAAC,CAAA;IAC9B,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA"}
+{"version":3,"file":"append.js","sourceRoot":"","sources":["../src/append.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAA;AAC1G,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAKvC;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,OAAU,EACP,EAAE;IACL,OAAO,CAAC,eAAe,CAAC,qBAAqB,EAAE,CAAC,CAAA;IAChD,OAAO,CAAC,eAAe,CAAC,uBAAuB,EAAE,CAAC,CAAA;IAClD,sEAAsE;IACtE,gEAAgE;IAChE,OAAO,CAAC,eAAe,CAAC,WAAW,EAAE,CAAC,CAAA;IACtC,eAAe,CAAO,OAAO,CAAC,CAAA;IAC9B,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA"}

package/build/gate.d.ts

@@ -0,0 +1,27 @@
+import type { GateService } from '@owlmeans/entrypoint';
+/**
+ * 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.
+ */
+export declare const RESOURCE_PARAM_SEPARATOR = "@";
+export interface ParsedGateParam {
+    permission: string;
+    resourceParam?: string;
+}
+export declare const parseGateParam: (param: string) => ParsedGateParam;
+/**
+ * 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.
+ * 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.
+ */
+export declare const makeIamGate: (alias?: string) => GateService;
+//# sourceMappingURL=gate.d.ts.map

package/build/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAmB,MAAM,sBAAsB,CAAA;AAQxE;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAE3C,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,eAO9C,CAAA;AAUD;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,QAAO,MAAkB,KAAG,WAgDvD,CAAA"}

package/build/gate.js

@@ -0,0 +1,76 @@
+import { createLazyService } from '@owlmeans/context';
+import { OIDC_GATE } from '@owlmeans/oidc';
+import { AuthForbidden } from '@owlmeans/auth';
+import { createGateModel, extractPermissionSets } from '@owlmeans/server-oidc-rp';
+import { hasPermission } from '@owlmeans/iam';
+/**
+ * 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.
+ */
+export const RESOURCE_PARAM_SEPARATOR = '@';
+export const parseGateParam = (param) => {
+    const idx = param.indexOf(RESOURCE_PARAM_SEPARATOR);
+    if (idx < 0) {
+        return { permission: param };
+    }
+    return { permission: param.slice(0, idx), resourceParam: param.slice(idx + 1) };
+};
+const resolveResourceId = (req, resourceParam) => {
+    const params = req.params;
+    const query = req.query;
+    const value = params?.[resourceParam] ?? query?.[resourceParam];
+    return value != null ? `${value}` : undefined;
+};
+/**
+ * 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.
+ * 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.
+ */
+export const makeIamGate = (alias = OIDC_GATE) => {
+    const service = createLazyService(alias, {
+        assert: async (req, _, params) => {
+            await service.ready();
+            const ctx = service.assertCtx();
+            if (req.auth == null) {
+                throw new AuthForbidden('auth');
+            }
+            const auth = req.auth;
+            const sets = extractPermissionSets(auth.permissions);
+            if (sets != null) {
+                const granted = params.some(param => {
+                    const { permission, resourceParam } = parseGateParam(param);
+                    const fixed = permission.replaceAll('{entity}', auth.entityId ?? '-');
+                    if (resourceParam != null) {
+                        const resourceId = resolveResourceId(req, resourceParam);
+                        if (resourceId == null) {
+                            return false;
+                        }
+                        return hasPermission(auth, fixed, { resourceId });
+                    }
+                    return hasPermission(auth, fixed);
+                });
+                if (!granted) {
+                    throw new AuthForbidden('permission');
+                }
+                return;
+            }
+            const stripped = params.map(param => parseGateParam(param).permission);
+            const model = createGateModel(ctx);
+            const permissions = await model.loadPermissions(auth, stripped);
+            if (permissions.length < 1) {
+                throw new AuthForbidden('permission');
+            }
+        }
+    });
+    return service;
+};
+//# sourceMappingURL=gate.js.map

package/build/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAErD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAE9C,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAA;AAEjF,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAE7C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAA;AAO3C,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAa,EAAmB,EAAE;IAC/D,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,wBAAwB,CAAC,CAAA;IACnD,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;QACZ,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,CAAA;IAC9B,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,aAAa,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,CAAA;AACjF,CAAC,CAAA;AAED,MAAM,iBAAiB,GAAG,CAAC,GAAoB,EAAE,aAAqB,EAAsB,EAAE;IAC5F,MAAM,MAAM,GAAG,GAAG,CAAC,MAA6C,CAAA;IAChE,MAAM,KAAK,GAAG,GAAG,CAAC,KAA4C,CAAA;IAC9D,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,aAAa,CAAC,IAAI,KAAK,EAAE,CAAC,aAAa,CAAC,CAAA;IAE/D,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;AAC/C,CAAC,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAgB,SAAS,EAAe,EAAE;IACpE,MAAM,OAAO,GAAgB,iBAAiB,CAAc,KAAK,EAAE;QACjE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE;YAC/B,MAAM,OAAO,CAAC,KAAK,EAAE,CAAA;YACrB,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,EAAmB,CAAA;YAEhD,IAAI,GAAG,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC;gBACrB,MAAM,IAAI,aAAa,CAAC,MAAM,CAAC,CAAA;YACjC,CAAC;YAED,MAAM,IAAI,GAAG,GAAG,CAAC,IAAY,CAAA;YAC7B,MAAM,IAAI,GAAG,qBAAqB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;YAEpD,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;gBACjB,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;oBAClC,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,GAAG,cAAc,CAAC,KAAK,CAAC,CAAA;oBAC3D,MAAM,KAAK,GAAG,UAAU,CAAC,UAAU,CAAC,UAAU,EAAE,IAAI,CAAC,QAAQ,IAAI,GAAG,CAAC,CAAA;oBAErE,IAAI,aAAa,IAAI,IAAI,EAAE,CAAC;wBAC1B,MAAM,UAAU,GAAG,iBAAiB,CAAC,GAAG,EAAE,aAAa,CAAC,CAAA;wBACxD,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;4BACvB,OAAO,KAAK,CAAA;wBACd,CAAC;wBAED,OAAO,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,UAAU,EAAE,CAAC,CAAA;oBACnD,CAAC;oBAED,OAAO,aAAa,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;gBACnC,CAAC,CAAC,CAAA;gBAEF,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,MAAM,IAAI,aAAa,CAAC,YAAY,CAAC,CAAA;gBACvC,CAAC;gBAED,OAAM;YACR,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,CAAA;YACtE,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,CAAC,CAAA;YAClC,MAAM,WAAW,GAAG,MAAM,KAAK,CAAC,eAAe,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;YAE/D,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC3B,MAAM,IAAI,aAAa,CAAC,YAAY,CAAC,CAAA;YACvC,CAAC;QACH,CAAC;KACF,CAAC,CAAA;IAEF,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA"}

package/build/index.d.ts

@@ -1,4 +1,6 @@
 export type * from '@owlmeans/iam';
+export { hasPermission } from '@owlmeans/iam';
 export * from './consts.js';
 export * from './append.js';
+export * from './gate.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,eAAe,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,eAAe,CAAA;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA"}

package/build/index.js

@@ -1,3 +1,5 @@
+export { hasPermission } from '@owlmeans/iam';
 export * from './consts.js';
 export * from './append.js';
+export * from './gate.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,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-iam",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,11 +22,13 @@
     }
   },
   "dependencies": {
-    "@owlmeans/context": "^0.1.6",
-    "@owlmeans/iam": "^0.1.6",
-    "@owlmeans/oidc": "^0.1.6",
-    "@owlmeans/server-context": "^0.1.6",
-    "@owlmeans/server-oidc-rp": "^0.1.6"
+    "@owlmeans/auth": "^0.1.8",
+    "@owlmeans/context": "^0.1.8",
+    "@owlmeans/entrypoint": "^0.1.8",
+    "@owlmeans/iam": "^0.1.8",
+    "@owlmeans/oidc": "^0.1.8",
+    "@owlmeans/server-context": "^0.1.8",
+    "@owlmeans/server-oidc-rp": "^0.1.8"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",

package/src/append.ts

@@ -1,6 +1,7 @@
 import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
 import type { WithSharedConfig } from '@owlmeans/oidc'
-import { appendOidcGuard, makeOidcClientService, makeOidcGate, makeOidcWrappingService } from '@owlmeans/server-oidc-rp'
+import { appendOidcGuard, makeOidcClientService, makeOidcWrappingService } from '@owlmeans/server-oidc-rp'
+import { makeIamGate } from './gate.js'
 
 type IamServerConfig = ServerConfig & WithSharedConfig
 type IamServerContext<C extends IamServerConfig = IamServerConfig> = ServerContext<C>
@@ -22,7 +23,9 @@ export const appendIam = <C extends IamServerConfig, T extends IamServerContext<
 ): T => {
   context.registerService(makeOidcClientService())
   context.registerService(makeOidcWrappingService())
-  context.registerService(makeOidcGate())
+  // IAM gate under the OIDC_GATE alias: claims-first (integrated mode),
+  // UMA2 fallback byte-equivalent to makeOidcGate (keycloak mode)
+  context.registerService(makeIamGate())
   appendOidcGuard<C, T>(context)
   return context
 }

package/src/gate.ts

@@ -0,0 +1,100 @@
+import { createLazyService } from '@owlmeans/context'
+import type { GateService, AbstractRequest } from '@owlmeans/entrypoint'
+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'
+
+/**
+ * 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.
+ */
+export const RESOURCE_PARAM_SEPARATOR = '@'
+
+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) }
+}
+
+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]
+
+  return value != null ? `${value}` : undefined
+}
+
+/**
+ * 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.
+ * 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.
+ */
+export const makeIamGate = (alias: string = OIDC_GATE): GateService => {
+  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')
+      }
+
+      const auth = req.auth as Auth
+      const sets = extractPermissionSets(auth.permissions)
+
+      if (sets != null) {
+        const granted = params.some(param => {
+          const { permission, resourceParam } = parseGateParam(param)
+          const fixed = permission.replaceAll('{entity}', auth.entityId ?? '-')
+
+          if (resourceParam != null) {
+            const resourceId = resolveResourceId(req, resourceParam)
+            if (resourceId == null) {
+              return false
+            }
+
+            return hasPermission(auth, fixed, { resourceId })
+          }
+
+          return hasPermission(auth, fixed)
+        })
+
+        if (!granted) {
+          throw new AuthForbidden('permission')
+        }
+
+        return
+      }
+
+      const stripped = params.map(param => parseGateParam(param).permission)
+      const model = createGateModel(ctx)
+      const permissions = await model.loadPermissions(auth, stripped)
+
+      if (permissions.length < 1) {
+        throw new AuthForbidden('permission')
+      }
+    }
+  })
+
+  return service
+}

package/src/index.ts

@@ -1,3 +1,5 @@
 export type * from '@owlmeans/iam'
+export { hasPermission } from '@owlmeans/iam'
 export * from './consts.js'
 export * from './append.js'
+export * from './gate.js'

package/tests/gate.spec.ts

@@ -0,0 +1,75 @@
+import { describe, expect, test } from 'bun:test'
+import { AppType, Layer, makeBasicContext } from '@owlmeans/context'
+import type { BasicConfig } from '@owlmeans/context'
+import type { AbstractRequest, AbstractResponse, GateService } from '@owlmeans/entrypoint'
+import type { Auth } from '@owlmeans/auth'
+import { AuthForbidden, AuthRole } from '@owlmeans/auth'
+import { OIDC_GATE } from '@owlmeans/oidc'
+import { makeIamGate } from '@owlmeans/server-iam'
+
+const makeGate = async (): Promise<GateService> => {
+  const ctx = makeBasicContext<BasicConfig>({
+    ready: false,
+    service: 'server-iam-tests',
+    layer: Layer.Service,
+    type: AppType.Backend,
+  })
+  ctx.registerService(makeIamGate())
+  ctx.configure()
+  await ctx.init()
+
+  return ctx.service<GateService>(OIDC_GATE)
+}
+
+const makeRequest = (params: Record<string, string> = {}): AbstractRequest => ({
+  alias: 'test',
+  headers: {},
+  params,
+  query: {},
+  body: {},
+  path: '/',
+  auth: {
+    type: 'oidc-wrapped-token',
+    token: 'test',
+    userId: 'user-1',
+    role: AuthRole.User,
+    scopes: [],
+    entityId: 'entity-1',
+    isUser: true,
+    createdAt: new Date(),
+    permissions: [
+      { scope: 'my-project', permissions: { 'article--modify': true } },
+      {
+        scope: 'my-project',
+        permissions: { 'department--modify': true },
+        resources: ['dep-12345678']
+      }
+    ]
+  } satisfies Auth
+}) as unknown as AbstractRequest
+
+const res = {} as AbstractResponse<unknown>
+
+describe('@owlmeans/server-iam — makeIamGate (claims mode)', () => {
+  test('passes an unscoped permission param', async () => {
+    const gate = await makeGate()
+    await gate.assert(makeRequest(), res, ['article--modify'])
+  })
+
+  test('passes a resource-scoped param when the request resource id is granted', async () => {
+    const gate = await makeGate()
+    await gate.assert(makeRequest({ depId: 'dep-12345678' }), res, ['department--modify@depId'])
+  })
+
+  test('params are any-of — one granted param is enough', async () => {
+    const gate = await makeGate()
+    await gate.assert(makeRequest(), res, ['unknown--permission', 'article--modify'])
+  })
+
+  test('rejects a resource-scoped param for an ungranted resource id', async () => {
+    const gate = await makeGate()
+    expect(
+      gate.assert(makeRequest({ depId: 'dep-87654321' }), res, ['department--modify@depId'])
+    ).rejects.toBeInstanceOf(AuthForbidden)
+  })
+})