@owlmeans/server-iam 0.1.18-rc.4 → 0.1.18-rc.40

package/README.md

@@ -12,7 +12,7 @@ One-call OIDC RP wiring and IAM gate for OwlMeans servers — `appendIam()` and
 ## Installation
 
 ```bash
-bun add @owlmeans/server-iam
+bun add @owlmeans/server-iam@^0.1.18-rc.40
 ```
 
 ## Usage
@@ -20,12 +20,19 @@ bun add @owlmeans/server-iam
 ```typescript
 import { appendIam, makeIamGate } from '@owlmeans/server-iam'
 import { IAM_GATE } from '@owlmeans/server-iam'
+import { contract, protocol, typed } from '@owlmeans/entrypoint'
+import { route } from '@owlmeans/route'
+import { DEFAULT_GUARD } from '@owlmeans/auth-common'
 
 // Wire IAM into a server context
 appendIam(context)
 
-// Gate a module with a permission check
-module.gate(IAM_GATE, { permission: 'manage-users' })
+// Gate a protocol with a permission check
+protocol(
+  route('users', '/users'),
+  contract(typed<User[]>()),
+  { guards: DEFAULT_GUARD, gate: { alias: IAM_GATE, params: ['manage-users@{entity}'] } },
+)
 ```
 
 Requires `@owlmeans/oidc` OIDC shared config and a running IAM provider configured via `@owlmeans/server-oidc-rp`.
@@ -38,7 +45,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.31
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/server-iam",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.500Z",
+  "version": "0.1.18-rc.40",
+  "generatedAt": "2026-09-21T21:54:22.951Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/server-iam/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: server-iam
-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). Applies to files matching **/owlmeans.ts, **/gate*.ts, **/auth-guard*.ts."
+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), plus the gate-param grammar it re-exports. Use when gating server endpoints, declaring gate params, or diagnosing a permission refusal. Applies to files matching **/owlmeans.ts, **/gate*.ts, **/auth-guard*.ts."
 metadata:
   applyTo: "**/owlmeans.ts, **/gate*.ts, **/auth-guard*.ts"
 ---
@@ -8,6 +8,8 @@ metadata:
 
 # Using `@owlmeans/server-iam`
 
+**Install:** `"@owlmeans/server-iam": "^0.1.18-rc.40"` in `dependencies`
+
 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.
 
@@ -16,26 +18,74 @@ IAM gate; the consumer never knows which IAM backend (Keycloak or integrated) is
 | 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 | `'@'` |
+| `makeIamGate(alias?, opts?)` | fn | The IAM `GateService` — claims-first assertion with UMA2 fallback |
+| `IamGateOptions` | type | `{ strictResourceScope?: boolean }` — refuse a scoped param on the fallback path instead of widening it |
+| `parseGateParam` / `parseGateSelector` / `formatGateParam` / `resolveGateResource` / `validateGateParams` | fn | Re-exports from `@owlmeans/iam`, which owns the grammar |
+| `RESOURCE_PARAM_SEPARATOR` / `RESOURCE_SOURCE_SEPARATOR` / `RESOURCE_PATH_SEPARATOR` | const | `'@'`, `':'` and `'.'`, re-exported |
+| `GateParamSource` / `GateParamErrorCode` / `GateResolutionFailure` | enum | Re-exported; the sources a selector may name, and why one failed |
 | `hasPermission` | fn | Re-export from `@owlmeans/iam` |
+| `SERVER_IAM_SERVICE` | const | `'server-iam-service'` — exported and referenced nowhere; the gate registers under `OIDC_GATE`, not under this |
+| Every `@owlmeans/iam` type | type | Re-exported wholesale, so a server needs one IAM import |
+
+The grammar lives in **`@owlmeans/iam`**, not here — the browser, both IAM adapters and
+code-generation tooling all have to read the same rules. This package re-exports it because it is the
+documented import path for a server, so one IAM import covers the gate and its grammar.
+
+`appendIam` reads the provider configuration from `cfg.oidc.providers`, so populate that before
+calling it. It is the IAM-flavoured replacement for wiring `@owlmeans/server-oidc-rp` by hand: the
+one difference is the gate, which is `makeIamGate()` rather than `makeOidcGate()`.
 
 ## Gate-param syntax
 
 ```
-<permission>                      → unscoped (project-wide): 'article--modify'
-<permission>@<requestParam>       → resource-scoped: 'department--modify@departmentId'
+<permission>                  → unscoped (project-wide): 'article--modify'
+<permission>@<bareKey>        → bare form:      'department--modify@departmentId'
+<permission>@<source>:<path>  → qualified form: 'order--modify@body:order.id'
 ```
 
-- `{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.
+Sources: `params`, `query`, `body`, `headers`, `auth`.
+
+- **The bare form is lenient and flat**; the qualified form is strict and nested. `@a.b` in the bare
+  form is the literal key `"a.b"` — a query key may legally contain a dot, and splitting it would
+  change what already-deployed selectors mean. Dotted paths exist only after a `source:`.
+- The separator is `:` and not a dot on purpose. With a dotted-only form, a route that gains a param
+  named like a source keyword silently changes a selector's meaning: `/report/:query` with
+  `@query.id` flips from "the route param named `query.id`" to "the query string's `id`" — an
+  authorization lookup redirected to attacker-supplied input by an unrelated route rename.
+- The bare form searches `params` then `query`. That query fallback is legacy and deliberately kept:
+  removing it would silently deny deployed apps whose selector names a query key.
+- `headers:` lowercases its first segment and unwraps a single-element array; a repeated header is
+  refused rather than silently narrowed to one of its values.
+- `auth:` is the only source that is neither attacker-controlled nor subject to `removeAdditional`.
+  Prefer it whenever the rule is "bound to their own profile or entity".
+- A resolved id must satisfy the grant's `resources[]` — **and a grant carrying no `resources` at all
+  covers every id**. That is the all-resources form of the same permission, not a separate one.
+- Params are **any-of**: one granted param is enough. Which is why a malformed or unresolvable param
+  can only contribute `false` and never throw — otherwise one bad sibling would refuse a request the
+  subject is legitimately entitled to.
+
+**The `@` belongs to the gate and nowhere else.** It is never part of a permission's stored NAME. A
+definition or grant written as `enquiry--view@enquiryId` is a key nothing looks up, so the permission
+reads as granted in every screen and every request is still refused, with nothing logged.
+`ensurePermission` refuses such a name; `validateGateParams` catches the mirror-image mistake at
+generation time.
+
+### `validateGateParams(params, audit?)`
+
+Reports what is provable from an entrypoint's own declaration: a selector naming a route param the
+path does not carry, or a `body`/`query`/`headers` key the `Filter` does not declare **while that
+schema sets `additionalProperties: false`**. That qualifier matters — the server's AJV runs
+`removeAdditional`, which strips only what a schema closes, so without it the check would fire on
+every unfiltered endpoint and be ignored within a week. It never decides a request; the gate runs it
+once per alias and only logs.
+
+The route half of the audit comes from `entrypoint.mount()`, which needs a service with a resolvable
+address. An entrypoint that has none is still audited against its filter — the route-param check is
+simply skipped rather than the whole audit being lost.
 
 ```ts
 // module declaration
-gate(OIDC_GATE, ['department--modify@depId'])
+{ gate: { alias: OIDC_GATE, params: ['department--modify@depId'] } }
 
 // or imperative
 await ctx.service<GateService>(OIDC_GATE).assert(req, res, ['article--modify'])
@@ -48,8 +98,35 @@ await ctx.service<GateService>(OIDC_GATE).assert(req, res, ['article--modify'])
    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.
+   from `@owlmeans/server-oidc-rp` (`createGateModel().loadPermissions`) — exactly the check
+   `makeOidcGate` performs, which is what a Keycloak-backed deployment gets.
+
+Which branch runs is decided per request by the token alone: a conforming `permissions` claim selects
+claims mode, its absence selects the fallback. Nothing configures it, and there is no environment
+variable behind it.
+
+**The fallback path does not enforce resource scoping**, so one declaration means two different
+things depending on which backend answered. It cannot be fixed by denying — a Keycloak-backed adapter
+throws `IamUnsupported('resource-scoped-grant')`, so a scoped grant cannot exist there and denying
+would lock every user out of every scoped endpoint. The gate logs each such param once per alias;
+`makeIamGate(alias, { strictResourceScope: true })` opts into denial where the refusals are the
+intended outcome.
+
+A denial distinguishes its reasons in the log: a param that failed **structurally** (unparseable,
+source absent, value not a scalar) is reported separately from one that resolved fine and simply was
+not granted. The HTTP answer is identical — `AuthForbidden('permission')` either way — because the
+caller must never learn which.
+
+## `{entity}` in a permission name
+
+A gate param may carry the literal `{entity}`, which is substituted at assertion time with the
+organization entity's **stable id** — `req.entity.id`, resolved once at the server boundary — falling
+back to the token's `entitySlug` and then to `-`. So `my-service-account-{entity}` asserts a
+per-organization permission without the declaration knowing which organization it is for.
+
+Grants are stored against the id wherever one is resolvable. The slug fallback exists for deployments
+with no organization store of their own, where the slug *is* the identifier; a deployment that has a
+store must not grant against slugs, because a rename would then orphan every grant.
 
 ## Rules
 

package/build/gate.d.ts

@@ -1,18 +1,23 @@
 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.
+ * The gate-param grammar lives in `@owlmeans/iam` so the browser, the adapters and code-generation
+ * tooling can all read it. Re-exported here because this module was its home and is the documented
+ * import path.
  */
-export declare const RESOURCE_PARAM_SEPARATOR = "@";
-export interface ParsedGateParam {
-    permission: string;
-    resourceParam?: string;
+export { RESOURCE_PARAM_SEPARATOR, RESOURCE_SOURCE_SEPARATOR, RESOURCE_PATH_SEPARATOR, GateParamSource, GateParamErrorCode, GateResolutionFailure, parseGateParam, parseGateSelector, formatGateParam, resolveGateResource, validateGateParams } from '@owlmeans/iam';
+export type { ParsedGateParam, GateResourceSelector, GateParamAudit } from '@owlmeans/iam';
+export interface IamGateOptions {
+    /**
+     * Refuse a resource-scoped param on the UMA2 fallback path instead of widening it to a
+     * project-wide check.
+     *
+     * Off by default, and deliberately so. A Keycloak-backed deployment cannot hold a resource-scoped
+     * grant at all — the adapter throws `IamUnsupported('resource-scoped-grant')` — so denying would
+     * lock every user out of every scoped endpoint rather than tightening anything. Turn it on only
+     * where the resulting refusals are the intended outcome.
+     */
+    strictResourceScope?: boolean;
 }
-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.
@@ -22,6 +27,10 @@ export declare const parseGateParam: (param: string) => ParsedGateParam;
  * 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.
+ *
+ * Params are OR'd: holding any one of them admits the request. That is why a malformed or
+ * unresolvable param can only contribute `false` and never throw — a sibling that would otherwise
+ * have passed must not be refused because of it.
  */
-export declare const makeIamGate: (alias?: string) => GateService;
+export declare const makeIamGate: (alias?: string, opts?: IamGateOptions) => GateService;
 //# sourceMappingURL=gate.d.ts.map

package/build/gate.d.ts.map

@@ -1 +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,UAAW,MAAM,KAAG,eAO9C,CAAA;AAUD;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,WAAW,MAAM,KAAe,WAgDvD,CAAA"}
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAqC,MAAM,sBAAsB,CAAA;AAY1F;;;;GAIG;AACH,OAAO,EACL,wBAAwB,EAAE,yBAAyB,EAAE,uBAAuB,EAC5E,eAAe,EAAE,kBAAkB,EAAE,qBAAqB,EAC1D,cAAc,EAAE,iBAAiB,EAAE,eAAe,EAAE,mBAAmB,EAAE,kBAAkB,EAC5F,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAE1F,MAAM,WAAW,cAAc;IAC7B;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B;AAiED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,WAAW,MAAM,SAAqB,cAAc,KAAG,WA4F9E,CAAA"}

package/build/gate.js

@@ -1,29 +1,69 @@
 import { createLazyService } from '@owlmeans/context';
+import { entitySlugOf } from '@owlmeans/auth';
 import { OIDC_GATE } from '@owlmeans/oidc';
 import { AuthForbidden } from '@owlmeans/auth';
 import { createGateModel, extractPermissionSets } from '@owlmeans/server-oidc-rp';
-import { hasPermission } from '@owlmeans/iam';
+import { hasPermission, parseGateParam, resolveGateResource, validateGateParams, GateResolutionFailure } 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.
+ * The gate-param grammar lives in `@owlmeans/iam` so the browser, the adapters and code-generation
+ * tooling can all read it. Re-exported here because this module was its home and is the documented
+ * import path.
  */
-export const RESOURCE_PARAM_SEPARATOR = '@';
-export const parseGateParam = (param) => {
-    const idx = param.indexOf(RESOURCE_PARAM_SEPARATOR);
-    if (idx < 0) {
-        return { permission: param };
+export { RESOURCE_PARAM_SEPARATOR, RESOURCE_SOURCE_SEPARATOR, RESOURCE_PATH_SEPARATOR, GateParamSource, GateParamErrorCode, GateResolutionFailure, parseGateParam, parseGateSelector, formatGateParam, resolveGateResource, validateGateParams } from '@owlmeans/iam';
+/**
+ * Structural faults are logged once per alias+param+reason.
+ *
+ * A gate on a hot endpoint runs on every request, and a misconfiguration is by definition permanent,
+ * so an un-deduplicated log turns one typo into the incident.
+ */
+const reported = new Set();
+const reportOnce = (key, message) => {
+    if (reported.has(key)) {
+        return;
     }
-    return { permission: param.slice(0, idx), resourceParam: param.slice(idx + 1) };
+    reported.add(key);
+    console.error(message);
 };
-const resolveResourceId = (req, resourceParam) => {
-    const params = req.params;
-    const query = req.query;
-    const value = params?.[resourceParam] ?? query?.[resourceParam];
-    return value != null ? `${value}` : undefined;
+/** Aliases whose declarations have already been checked. */
+const audited = new Set();
+/**
+ * Check an entrypoint's gate params against what it declares, once, the first time it is reached.
+ *
+ * Structurally unable to affect the outcome: it only ever logs. A selector naming a key the
+ * entrypoint's filter does not declare is stripped by validation before the gate runs, so the
+ * endpoint denies every request with a clean build and nothing else to go on — this is the line that
+ * says why.
+ */
+const auditEntrypoint = (ctx, req, params) => {
+    if (req.alias == null || audited.has(req.alias)) {
+        return;
+    }
+    audited.add(req.alias);
+    try {
+        const entrypoint = ctx.entrypoint(req.alias);
+        if (entrypoint == null) {
+            return;
+        }
+        let routePath;
+        try {
+            routePath = entrypoint.mount();
+        }
+        catch {
+            // The mount needs a service with an address; an entrypoint that has none still has a filter
+            // worth auditing.
+        }
+        const audit = {
+            ...(routePath != null ? { routePath } : {}),
+            ...(entrypoint.filter != null ? { filter: entrypoint.filter } : {})
+        };
+        for (const issue of validateGateParams(params, audit)) {
+            console.error(`Gate param "${issue.param}" on entrypoint "${req.alias}" is misconfigured`
+                + ` [${issue.code}]: ${issue.detail}`);
+        }
+    }
+    catch {
+        // An entrypoint that cannot be looked up is not this gate's problem to report.
+    }
 };
 /**
  * IAM gate: claims-first with UMA2 fallback. Registered under the OIDC_GATE alias by
@@ -34,8 +74,12 @@ const resolveResourceId = (req, resourceParam) => {
  * 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.
+ *
+ * Params are OR'd: holding any one of them admits the request. That is why a malformed or
+ * unresolvable param can only contribute `false` and never throw — a sibling that would otherwise
+ * have passed must not be refused because of it.
  */
-export const makeIamGate = (alias = OIDC_GATE) => {
+export const makeIamGate = (alias = OIDC_GATE, opts) => {
     const service = createLazyService(alias, {
         assert: async (req, _, params) => {
             await service.ready();
@@ -46,24 +90,53 @@ export const makeIamGate = (alias = OIDC_GATE) => {
             const auth = req.auth;
             const sets = extractPermissionSets(auth.permissions);
             if (sets != null) {
+                auditEntrypoint(ctx, req, params);
+                // Why a param failed, kept aside so a denial can say whether the gate was misconfigured or
+                // the subject simply lacks the grant. The two look identical from the outside and are
+                // repaired in completely different places.
+                const structural = [];
                 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) {
+                    const { permission, resource, error } = parseGateParam(param);
+                    // Grants are stored against the entity's stable id wherever one is resolvable; the
+                    // slug is only a fallback for deployments with no organization store of their own,
+                    // where the slug IS the identifier.
+                    const fixed = permission.replaceAll('{entity}', req.entity?.id ?? entitySlugOf(auth) ?? '-');
+                    if (error != null) {
+                        structural.push(`"${param}" does not parse [${error.code}]: ${error.detail}`);
+                        return false;
+                    }
+                    if (resource != null) {
+                        const resolution = resolveGateResource(req, resource);
+                        if (resolution.id == null) {
+                            if (resolution.reason !== GateResolutionFailure.NotProvided) {
+                                structural.push(`"${param}" resolved no resource id [${resolution.reason}]`
+                                    + ` from ${resource.sources.join(', ')}`);
+                            }
                             return false;
                         }
-                        return hasPermission(auth, fixed, { resourceId });
+                        return hasPermission(auth, fixed, { resourceId: resolution.id });
                     }
                     return hasPermission(auth, fixed);
                 });
                 if (!granted) {
+                    structural.forEach(detail => reportOnce(`${req.alias}\0${detail}`, `Gate on entrypoint "${req.alias}" refused a request it could not evaluate: ${detail}`));
                     throw new AuthForbidden('permission');
                 }
                 return;
             }
-            const stripped = params.map(param => parseGateParam(param).permission);
+            // UMA2 fallback. Resource scoping is NOT enforced here: a Keycloak-backed deployment cannot
+            // store a resource-scoped grant, so a scoped param widens to a project-wide check and the same
+            // declaration means two different things depending on which backend is active.
+            const scoped = params.filter(param => parseGateParam(param).resource != null);
+            scoped.forEach(param => reportOnce(`uma2\0${req.alias}\0${param}`, `Gate param "${param}" on entrypoint "${req.alias}" is resource-scoped, but resource scoping`
+                + ' is not enforced in UMA2 mode — it is checked as a project-wide permission'));
+            const usable = opts?.strictResourceScope === true
+                ? params.filter(param => parseGateParam(param).resource == null)
+                : params;
+            if (usable.length < 1) {
+                throw new AuthForbidden('permission');
+            }
+            const stripped = usable.map(param => parseGateParam(param).permission);
             const model = createGateModel(ctx);
             const permissions = await model.loadPermissions(auth, stripped);
             if (permissions.length < 1) {

package/build/gate.js.map

@@ -1 +1 @@
-{"version":3,"file":"gate.js","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-iam",
-  "version": "0.1.18-rc.4",
+  "version": "0.1.18-rc.40",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,17 +22,17 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.4",
-    "@owlmeans/context": "^0.1.18-rc.4",
-    "@owlmeans/entrypoint": "^0.1.18-rc.4",
-    "@owlmeans/iam": "^0.1.18-rc.4",
-    "@owlmeans/oidc": "^0.1.18-rc.4",
-    "@owlmeans/server-context": "^0.1.18-rc.4",
-    "@owlmeans/server-oidc-rp": "^0.1.18-rc.4"
+    "@owlmeans/auth": "^0.1.18-rc.29",
+    "@owlmeans/context": "^0.1.18-rc.27",
+    "@owlmeans/entrypoint": "^0.1.18-rc.30",
+    "@owlmeans/iam": "^0.1.18-rc.34",
+    "@owlmeans/oidc": "^0.1.18-rc.39",
+    "@owlmeans/server-context": "^0.1.18-rc.30",
+    "@owlmeans/server-oidc-rp": "^0.1.18-rc.38"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@types/bun": "^1.3.14",
+    "@types/bun": "^1.4.0",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },

package/src/gate.ts

@@ -1,42 +1,102 @@
 import { createLazyService } from '@owlmeans/context'
-import type { GateService, AbstractRequest } from '@owlmeans/entrypoint'
+import type { GateService, AbstractRequest, CommonEntrypoint } from '@owlmeans/entrypoint'
+import { entitySlugOf } from '@owlmeans/auth'
 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'
+import {
+  hasPermission, parseGateParam, resolveGateResource, validateGateParams, GateResolutionFailure
+} from '@owlmeans/iam'
+import type { GateParamAudit } 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.
+ * The gate-param grammar lives in `@owlmeans/iam` so the browser, the adapters and code-generation
+ * tooling can all read it. Re-exported here because this module was its home and is the documented
+ * import path.
  */
-export const RESOURCE_PARAM_SEPARATOR = '@'
+export {
+  RESOURCE_PARAM_SEPARATOR, RESOURCE_SOURCE_SEPARATOR, RESOURCE_PATH_SEPARATOR,
+  GateParamSource, GateParamErrorCode, GateResolutionFailure,
+  parseGateParam, parseGateSelector, formatGateParam, resolveGateResource, validateGateParams
+} from '@owlmeans/iam'
+export type { ParsedGateParam, GateResourceSelector, GateParamAudit } from '@owlmeans/iam'
+
+export interface IamGateOptions {
+  /**
+   * Refuse a resource-scoped param on the UMA2 fallback path instead of widening it to a
+   * project-wide check.
+   *
+   * Off by default, and deliberately so. A Keycloak-backed deployment cannot hold a resource-scoped
+   * grant at all — the adapter throws `IamUnsupported('resource-scoped-grant')` — so denying would
+   * lock every user out of every scoped endpoint rather than tightening anything. Turn it on only
+   * where the resulting refusals are the intended outcome.
+   */
+  strictResourceScope?: boolean
+}
 
-export interface ParsedGateParam {
-  permission: string
-  resourceParam?: string
+/**
+ * Structural faults are logged once per alias+param+reason.
+ *
+ * A gate on a hot endpoint runs on every request, and a misconfiguration is by definition permanent,
+ * so an un-deduplicated log turns one typo into the incident.
+ */
+const reported = new Set<string>()
+
+const reportOnce = (key: string, message: string): void => {
+  if (reported.has(key)) {
+    return
+  }
+  reported.add(key)
+  console.error(message)
 }
 
-export const parseGateParam = (param: string): ParsedGateParam => {
-  const idx = param.indexOf(RESOURCE_PARAM_SEPARATOR)
-  if (idx < 0) {
-    return { permission: param }
+/** Aliases whose declarations have already been checked. */
+const audited = new Set<string>()
+
+/**
+ * Check an entrypoint's gate params against what it declares, once, the first time it is reached.
+ *
+ * Structurally unable to affect the outcome: it only ever logs. A selector naming a key the
+ * entrypoint's filter does not declare is stripped by validation before the gate runs, so the
+ * endpoint denies every request with a clean build and nothing else to go on — this is the line that
+ * says why.
+ */
+const auditEntrypoint = (ctx: Context, req: AbstractRequest, params: string[]): void => {
+  if (req.alias == null || audited.has(req.alias)) {
+    return
   }
+  audited.add(req.alias)
 
-  return { permission: param.slice(0, idx), resourceParam: param.slice(idx + 1) }
-}
+  try {
+    const entrypoint = ctx.entrypoint<CommonEntrypoint>(req.alias)
+    if (entrypoint == null) {
+      return
+    }
 
-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]
+    let routePath: string | undefined
+    try {
+      routePath = entrypoint.mount()
+    } catch {
+      // The mount needs a service with an address; an entrypoint that has none still has a filter
+      // worth auditing.
+    }
 
-  return value != null ? `${value}` : undefined
+    const audit: GateParamAudit = {
+      ...(routePath != null ? { routePath } : {}),
+      ...(entrypoint.filter != null ? { filter: entrypoint.filter as GateParamAudit['filter'] } : {})
+    }
+
+    for (const issue of validateGateParams(params, audit)) {
+      console.error(
+        `Gate param "${issue.param}" on entrypoint "${req.alias}" is misconfigured`
+        + ` [${issue.code}]: ${issue.detail}`
+      )
+    }
+  } catch {
+    // An entrypoint that cannot be looked up is not this gate's problem to report.
+  }
 }
 
 /**
@@ -48,8 +108,12 @@ const resolveResourceId = (req: AbstractRequest, resourceParam: string): string
  * 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.
+ *
+ * Params are OR'd: holding any one of them admits the request. That is why a malformed or
+ * unresolvable param can only contribute `false` and never throw — a sibling that would otherwise
+ * have passed must not be refused because of it.
  */
-export const makeIamGate = (alias: string = OIDC_GATE): GateService => {
+export const makeIamGate = (alias: string = OIDC_GATE, opts?: IamGateOptions): GateService => {
   const service: GateService = createLazyService<GateService>(alias, {
     assert: async (req, _, params) => {
       await service.ready()
@@ -63,30 +127,74 @@ export const makeIamGate = (alias: string = OIDC_GATE): GateService => {
       const sets = extractPermissionSets(auth.permissions)
 
       if (sets != null) {
+        auditEntrypoint(ctx, req, params)
+
+        // Why a param failed, kept aside so a denial can say whether the gate was misconfigured or
+        // the subject simply lacks the grant. The two look identical from the outside and are
+        // repaired in completely different places.
+        const structural: string[] = []
+
         const granted = params.some(param => {
-          const { permission, resourceParam } = parseGateParam(param)
-          const fixed = permission.replaceAll('{entity}', auth.entityId ?? '-')
+          const { permission, resource, error } = parseGateParam(param)
+          // Grants are stored against the entity's stable id wherever one is resolvable; the
+          // slug is only a fallback for deployments with no organization store of their own,
+          // where the slug IS the identifier.
+          const fixed = permission.replaceAll('{entity}', req.entity?.id ?? entitySlugOf(auth) ?? '-')
+
+          if (error != null) {
+            structural.push(`"${param}" does not parse [${error.code}]: ${error.detail}`)
+            return false
+          }
 
-          if (resourceParam != null) {
-            const resourceId = resolveResourceId(req, resourceParam)
-            if (resourceId == null) {
+          if (resource != null) {
+            const resolution = resolveGateResource(req, resource)
+            if (resolution.id == null) {
+              if (resolution.reason !== GateResolutionFailure.NotProvided) {
+                structural.push(
+                  `"${param}" resolved no resource id [${resolution.reason}]`
+                  + ` from ${resource.sources.join(', ')}`
+                )
+              }
               return false
             }
 
-            return hasPermission(auth, fixed, { resourceId })
+            return hasPermission(auth, fixed, { resourceId: resolution.id })
           }
 
           return hasPermission(auth, fixed)
         })
 
         if (!granted) {
+          structural.forEach(detail => reportOnce(
+            `${req.alias}\0${detail}`,
+            `Gate on entrypoint "${req.alias}" refused a request it could not evaluate: ${detail}`
+          ))
+
           throw new AuthForbidden('permission')
         }
 
         return
       }
 
-      const stripped = params.map(param => parseGateParam(param).permission)
+      // UMA2 fallback. Resource scoping is NOT enforced here: a Keycloak-backed deployment cannot
+      // store a resource-scoped grant, so a scoped param widens to a project-wide check and the same
+      // declaration means two different things depending on which backend is active.
+      const scoped = params.filter(param => parseGateParam(param).resource != null)
+      scoped.forEach(param => reportOnce(
+        `uma2\0${req.alias}\0${param}`,
+        `Gate param "${param}" on entrypoint "${req.alias}" is resource-scoped, but resource scoping`
+        + ' is not enforced in UMA2 mode — it is checked as a project-wide permission'
+      ))
+
+      const usable = opts?.strictResourceScope === true
+        ? params.filter(param => parseGateParam(param).resource == null)
+        : params
+
+      if (usable.length < 1) {
+        throw new AuthForbidden('permission')
+      }
+
+      const stripped = usable.map(param => parseGateParam(param).permission)
       const model = createGateModel(ctx)
       const permissions = await model.loadPermissions(auth, stripped)
 

package/tests/gate.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test'
-import { AppType, Layer, makeBasicContext } from '@owlmeans/context'
+import { AppType, makeBasicContext } from '@owlmeans/context'
 import type { BasicConfig } from '@owlmeans/context'
 import type { AbstractRequest, AbstractResponse, GateService } from '@owlmeans/entrypoint'
 import type { Auth } from '@owlmeans/auth'
@@ -11,7 +11,6 @@ const makeGate = async (): Promise<GateService> => {
   const ctx = makeBasicContext<BasicConfig>({
     ready: false,
     service: 'server-iam-tests',
-    layer: Layer.Service,
     type: AppType.Backend,
   })
   ctx.registerService(makeIamGate())
@@ -21,12 +20,16 @@ const makeGate = async (): Promise<GateService> => {
   return ctx.service<GateService>(OIDC_GATE)
 }
 
-const makeRequest = (params: Record<string, string> = {}): AbstractRequest => ({
+const makeRequest = (
+  params: Record<string, string> = {},
+  rest: Partial<Pick<AbstractRequest, 'query' | 'body' | 'headers'>> = {}
+): AbstractRequest => ({
   alias: 'test',
   headers: {},
   params,
   query: {},
   body: {},
+  ...rest,
   path: '/',
   auth: {
     type: 'oidc-wrapped-token',
@@ -72,4 +75,53 @@ describe('@owlmeans/server-iam — makeIamGate (claims mode)', () => {
       gate.assert(makeRequest({ depId: 'dep-87654321' }), res, ['department--modify@depId'])
     ).rejects.toBeInstanceOf(AuthForbidden)
   })
+
+  test('resolves a resource id from an explicitly named source', async () => {
+    const gate = await makeGate()
+    await gate.assert(
+      makeRequest({}, { body: { department: { id: 'dep-12345678' } } }), res,
+      ['department--modify@body:department.id']
+    )
+  })
+
+  test('resolves a resource id from the auth object', async () => {
+    const gate = await makeGate()
+    // `entity-1` is this subject's own entityId, and the unscoped grant covers every resource.
+    await gate.assert(makeRequest(), res, ['article--modify@auth:entityId'])
+  })
+
+  /**
+   * Params are OR'd, so a param the gate cannot even evaluate must contribute nothing. Letting one
+   * throw would turn a typo in an unrelated sibling into a denial of a grant the subject really has.
+   */
+  test('a malformed param does not refuse a sibling that passes', async () => {
+    const gate = await makeGate()
+    await gate.assert(makeRequest(), res, ['article--modify@cookies:sid', 'article--modify'])
+  })
+
+  test('an unresolvable selector refuses without breaking the OR', async () => {
+    const gate = await makeGate()
+    await gate.assert(makeRequest(), res, ['department--modify@missingParam', 'article--modify'])
+
+    expect(
+      gate.assert(makeRequest(), res, ['department--modify@missingParam'])
+    ).rejects.toBeInstanceOf(AuthForbidden)
+  })
+
+  /**
+   * The stored grant is keyed `department--modify`; the gate splits the selector off before looking
+   * it up. A grant written under the whole string — the corruption this grammar exists to stop —
+   * is a key nothing reads.
+   */
+  test('a permission granted WITH the selector in its name never satisfies the gate', async () => {
+    const gate = await makeGate()
+    const req = makeRequest({ depId: 'dep-1' })
+    ;(req.auth as unknown as Auth).permissions = [
+      { scope: 'my-project', permissions: { 'department--modify@depId': true } }
+    ]
+
+    expect(
+      gate.assert(req, res, ['department--modify@depId'])
+    ).rejects.toBeInstanceOf(AuthForbidden)
+  })
 })