@owlmeans/server-iam 0.1.7 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-iam",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,13 +22,13 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.7",
-    "@owlmeans/context": "^0.1.7",
-    "@owlmeans/entrypoint": "^0.1.7",
-    "@owlmeans/iam": "^0.1.7",
-    "@owlmeans/oidc": "^0.1.7",
-    "@owlmeans/server-context": "^0.1.7",
-    "@owlmeans/server-oidc-rp": "^0.1.7"
+    "@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:*",