@owlmeans/server-iam 0.1.18-rc.13 → 0.1.18-rc.15

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/server-iam",
-  "version": "0.1.18-rc.12",
-  "generatedAt": "2026-08-24T21:14:00.106Z",
+  "version": "0.1.18-rc.13",
+  "generatedAt": "2026-08-27T16:32:18.467Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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;AAW1F;;;;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;AA2DD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,WAAW,MAAM,SAAqB,cAAc,KAAG,WAyF9E,CAAA"}

package/build/gate.js

@@ -2,28 +2,61 @@ 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';
+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;
+        }
+        const audit = {
+            ...(typeof entrypoint.getPath === 'function'
+                ? { routePath: entrypoint.getPath() }
+                : {}),
+            ...(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 resolved is not this gate's problem to report.
+    }
 };
 /**
  * IAM gate: claims-first with UMA2 fallback. Registered under the OIDC_GATE alias by
@@ -34,8 +67,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 +83,50 @@ 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 { permission, resource, error } = parseGateParam(param);
                     const fixed = permission.replaceAll('{entity}', auth.entityId ?? '-');
-                    if (resourceParam != null) {
-                        const resourceId = resolveResourceId(req, resourceParam);
-                        if (resourceId == null) {
+                    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":"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,EACL,aAAa,EAAE,cAAc,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,qBAAqB,EAC9F,MAAM,eAAe,CAAA;AAGtB;;;;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;AAgBtB;;;;;GAKG;AACH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAA;AAElC,MAAM,UAAU,GAAG,CAAC,GAAW,EAAE,OAAe,EAAQ,EAAE;IACxD,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,OAAM;IACR,CAAC;IACD,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACjB,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;AACxB,CAAC,CAAA;AAED,4DAA4D;AAC5D,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAA;AAEjC;;;;;;;GAOG;AACH,MAAM,eAAe,GAAG,CAAC,GAAY,EAAE,GAAoB,EAAE,MAAgB,EAAQ,EAAE;IACrF,IAAI,GAAG,CAAC,KAAK,IAAI,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,OAAM;IACR,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;IAEtB,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,GAAG,CAAC,UAAU,CAAmB,GAAG,CAAC,KAAK,CAAC,CAAA;QAC9D,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;YACvB,OAAM;QACR,CAAC;QAED,MAAM,KAAK,GAAmB;YAC5B,GAAG,CAAC,OAAQ,UAAkB,CAAC,OAAO,KAAK,UAAU;gBACnD,CAAC,CAAC,EAAE,SAAS,EAAG,UAAkB,CAAC,OAAO,EAAY,EAAE;gBACxD,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,UAAU,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,MAAkC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChG,CAAA;QAED,KAAK,MAAM,KAAK,IAAI,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;YACtD,OAAO,CAAC,KAAK,CACX,eAAe,KAAK,CAAC,KAAK,oBAAoB,GAAG,CAAC,KAAK,oBAAoB;kBACzE,KAAK,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,MAAM,EAAE,CACtC,CAAA;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,8EAA8E;IAChF,CAAC;AACH,CAAC,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAK,GAAW,SAAS,EAAE,IAAqB,EAAe,EAAE;IAC3F,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,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAAA;gBAEjC,2FAA2F;gBAC3F,sFAAsF;gBACtF,2CAA2C;gBAC3C,MAAM,UAAU,GAAa,EAAE,CAAA;gBAE/B,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;oBAClC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,cAAc,CAAC,KAAK,CAAC,CAAA;oBAC7D,MAAM,KAAK,GAAG,UAAU,CAAC,UAAU,CAAC,UAAU,EAAE,IAAI,CAAC,QAAQ,IAAI,GAAG,CAAC,CAAA;oBAErE,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;wBAClB,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,qBAAqB,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,MAAM,EAAE,CAAC,CAAA;wBAC7E,OAAO,KAAK,CAAA;oBACd,CAAC;oBAED,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;wBACrB,MAAM,UAAU,GAAG,mBAAmB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;wBACrD,IAAI,UAAU,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC;4BAC1B,IAAI,UAAU,CAAC,MAAM,KAAK,qBAAqB,CAAC,WAAW,EAAE,CAAC;gCAC5D,UAAU,CAAC,IAAI,CACb,IAAI,KAAK,8BAA8B,UAAU,CAAC,MAAM,GAAG;sCACzD,SAAS,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACzC,CAAA;4BACH,CAAC;4BACD,OAAO,KAAK,CAAA;wBACd,CAAC;wBAED,OAAO,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAA;oBAClE,CAAC;oBAED,OAAO,aAAa,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;gBACnC,CAAC,CAAC,CAAA;gBAEF,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,UAAU,CACrC,GAAG,GAAG,CAAC,KAAK,KAAK,MAAM,EAAE,EACzB,uBAAuB,GAAG,CAAC,KAAK,8CAA8C,MAAM,EAAE,CACvF,CAAC,CAAA;oBAEF,MAAM,IAAI,aAAa,CAAC,YAAY,CAAC,CAAA;gBACvC,CAAC;gBAED,OAAM;YACR,CAAC;YAED,4FAA4F;YAC5F,+FAA+F;YAC/F,+EAA+E;YAC/E,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAA;YAC7E,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,UAAU,CAChC,SAAS,GAAG,CAAC,KAAK,KAAK,KAAK,EAAE,EAC9B,eAAe,KAAK,oBAAoB,GAAG,CAAC,KAAK,4CAA4C;kBAC3F,4EAA4E,CAC/E,CAAC,CAAA;YAEF,MAAM,MAAM,GAAG,IAAI,EAAE,mBAAmB,KAAK,IAAI;gBAC/C,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,QAAQ,IAAI,IAAI,CAAC;gBAChE,CAAC,CAAC,MAAM,CAAA;YAEV,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACtB,MAAM,IAAI,aAAa,CAAC,YAAY,CAAC,CAAA;YACvC,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-iam",
-  "version": "0.1.18-rc.13",
+  "version": "0.1.18-rc.15",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -25,7 +25,7 @@
     "@owlmeans/auth": "^0.1.18-rc.6",
     "@owlmeans/context": "^0.1.18-rc.6",
     "@owlmeans/entrypoint": "^0.1.18-rc.7",
-    "@owlmeans/iam": "^0.1.18-rc.9",
+    "@owlmeans/iam": "^0.1.18-rc.11",
     "@owlmeans/oidc": "^0.1.18-rc.8",
     "@owlmeans/server-context": "^0.1.18-rc.7",
     "@owlmeans/server-oidc-rp": "^0.1.18-rc.12"

package/src/gate.ts

@@ -1,42 +1,95 @@
 import { createLazyService } from '@owlmeans/context'
-import type { GateService, AbstractRequest } from '@owlmeans/entrypoint'
+import type { GateService, AbstractRequest, CommonEntrypoint } 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'
+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
+}
+
+/**
+ * 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>()
 
-export interface ParsedGateParam {
-  permission: string
-  resourceParam?: 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]
+    const audit: GateParamAudit = {
+      ...(typeof (entrypoint as any).getPath === 'function'
+        ? { routePath: (entrypoint as any).getPath() as string }
+        : {}),
+      ...(entrypoint.filter != null ? { filter: entrypoint.filter as GateParamAudit['filter'] } : {})
+    }
 
-  return value != null ? `${value}` : undefined
+    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 resolved is not this gate's problem to report.
+  }
 }
 
 /**
@@ -48,8 +101,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 +120,71 @@ 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 { permission, resource, error } = parseGateParam(param)
           const fixed = permission.replaceAll('{entity}', auth.entityId ?? '-')
 
-          if (resourceParam != null) {
-            const resourceId = resolveResourceId(req, resourceParam)
-            if (resourceId == null) {
+          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)
 

package/tests/gate.spec.ts

@@ -21,12 +21,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 +76,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)
+  })
 })