@owlmeans/iam 0.1.18-rc.2 → 0.1.18-rc.21

package/build/errors.js

@@ -27,6 +27,22 @@ export class IamGrantError extends IamError {
         this.type = IamGrantError.typeName;
     }
 }
+/**
+ * A refusal about a permission DEFINITION, as opposed to a grant.
+ *
+ * Separate from `IamGrantError`, which means a grant's subject is missing or its entity does not
+ * match — reusing it for a definition-level refusal is a category error the next reader has to unpick.
+ *
+ * Codes: `permission:held:<name>` (still granted to someone, under a policy that refuses),
+ * `permission:managed:<name>` (platform-owned, deleted only with an explicit second key).
+ */
+export class IamPermissionError extends IamError {
+    static typeName = `IamPermission${ResilientError.typeName}`;
+    constructor(message = 'error') {
+        super(`permission:${message}`);
+        this.type = IamPermissionError.typeName;
+    }
+}
 export class IamUnsupported extends IamError {
     static typeName = `IamUnsupported${ResilientError.typeName}`;
     constructor(message = 'error') {
@@ -45,6 +61,7 @@ ResilientError.registerErrorClass(IamError);
 ResilientError.registerErrorClass(IamClientError);
 ResilientError.registerErrorClass(IamResourceError);
 ResilientError.registerErrorClass(IamGrantError);
+ResilientError.registerErrorClass(IamPermissionError);
 ResilientError.registerErrorClass(IamUnsupported);
 ResilientError.registerErrorClass(IamUserError);
 //# sourceMappingURL=errors.js.map

package/build/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,OAAO,QAAS,SAAQ,cAAc;IACnC,MAAM,CAAU,QAAQ,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEjE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,OAAO,EAAE,CAAC,CAAA;QAC1C,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAA;IAC/B,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACnC,MAAM,CAAU,QAAQ,GAAG,YAAY,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEvE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAA;IACrC,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,QAAQ;IACrC,MAAM,CAAU,QAAQ,GAAG,cAAc,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEzE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,YAAY,OAAO,EAAE,CAAC,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC,QAAQ,CAAA;IACvC,CAAC;CACF;AAED,MAAM,OAAO,aAAc,SAAQ,QAAQ;IAClC,MAAM,CAAU,QAAQ,GAAG,WAAW,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEtE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,SAAS,OAAO,EAAE,CAAC,CAAA;QACzB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC,QAAQ,CAAA;IACpC,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACnC,MAAM,CAAU,QAAQ,GAAG,iBAAiB,cAAc,CAAC,QAAQ,EAAE,CAAA;IAE5E,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAA;QAC/B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAA;IACrC,CAAC;CACF;AAED,MAAM,OAAO,YAAa,SAAQ,QAAQ;IACjC,MAAM,CAAU,QAAQ,GAAG,UAAU,cAAc,CAAC,QAAQ,EAAE,CAAA;IAErE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,QAAQ,OAAO,EAAE,CAAC,CAAA;QACxB,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAA;IACnC,CAAC;CACF;AAED,cAAc,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAA;AAC3C,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA;AACjD,cAAc,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAA;AACnD,cAAc,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAA;AAChD,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA;AACjD,cAAc,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAA"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,OAAO,QAAS,SAAQ,cAAc;IACnC,MAAM,CAAU,QAAQ,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEjE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,OAAO,EAAE,CAAC,CAAA;QAC1C,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAA;IAC/B,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACnC,MAAM,CAAU,QAAQ,GAAG,YAAY,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEvE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAA;IACrC,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,QAAQ;IACrC,MAAM,CAAU,QAAQ,GAAG,cAAc,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEzE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,YAAY,OAAO,EAAE,CAAC,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC,QAAQ,CAAA;IACvC,CAAC;CACF;AAED,MAAM,OAAO,aAAc,SAAQ,QAAQ;IAClC,MAAM,CAAU,QAAQ,GAAG,WAAW,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEtE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,SAAS,OAAO,EAAE,CAAC,CAAA;QACzB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC,QAAQ,CAAA;IACpC,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,kBAAmB,SAAQ,QAAQ;IACvC,MAAM,CAAU,QAAQ,GAAG,gBAAgB,cAAc,CAAC,QAAQ,EAAE,CAAA;IAE3E,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,cAAc,OAAO,EAAE,CAAC,CAAA;QAC9B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC,QAAQ,CAAA;IACzC,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACnC,MAAM,CAAU,QAAQ,GAAG,iBAAiB,cAAc,CAAC,QAAQ,EAAE,CAAA;IAE5E,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAA;QAC/B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAA;IACrC,CAAC;CACF;AAED,MAAM,OAAO,YAAa,SAAQ,QAAQ;IACjC,MAAM,CAAU,QAAQ,GAAG,UAAU,cAAc,CAAC,QAAQ,EAAE,CAAA;IAErE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,QAAQ,OAAO,EAAE,CAAC,CAAA;QACxB,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAA;IACnC,CAAC;CACF;AAED,cAAc,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAA;AAC3C,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA;AACjD,cAAc,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAA;AACnD,cAAc,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAA;AAChD,cAAc,CAAC,kBAAkB,CAAC,kBAAkB,CAAC,CAAA;AACrD,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA;AACjD,cAAc,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAA"}

package/build/gate/index.d.ts

@@ -0,0 +1,4 @@
+export * from './param.js';
+export * from './resolve.js';
+export * from './validate.js';
+//# sourceMappingURL=index.d.ts.map

package/build/gate/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/gate/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA"}

package/build/gate/index.js

@@ -0,0 +1,4 @@
+export * from './param.js';
+export * from './resolve.js';
+export * from './validate.js';
+//# sourceMappingURL=index.js.map

package/build/gate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/gate/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA"}

package/build/gate/param.d.ts

@@ -0,0 +1,31 @@
+import { GateParamSource } from '../consts.js';
+import type { GateResourceSelector, GateParamProblem, ParsedGateParam } from '../types.js';
+/**
+ * Read the `@…` half of a gate param.
+ *
+ * Two forms, and the difference between them is deliberate:
+ *
+ *   `@enquiryId`        — bare. A FLAT key, searched in `params` then `query`. It is never split on
+ *                         a dot, because a query key legally contains one and splitting it would
+ *                         change the meaning of selectors already deployed.
+ *   `@body:order.id`    — qualified. An explicit source and a nested path.
+ *
+ * The rule worth remembering: the bare form is lenient and flat, the qualified form is strict and
+ * nested.
+ */
+export declare const parseGateSelector: (selector: string) => GateResourceSelector | GateParamProblem;
+/**
+ * Split a gate param into the permission it checks and where the resource id comes from.
+ *
+ * Splits at the FIRST `@`. Everything before it is the permission name looked up in the subject's
+ * grants; everything after says where to read the resource id at request time. The suffix is the
+ * gate's syntax and nothing else's — a permission stored or granted under a name containing one is a
+ * key nothing ever looks up.
+ */
+export declare const parseGateParam: (param: string) => ParsedGateParam;
+/** Compose a gate param. The inverse of `parseGateParam` for every selector it accepts. */
+export declare const formatGateParam: (permission: string, selector?: string | {
+    source?: GateParamSource;
+    path: string[];
+}) => string;
+//# sourceMappingURL=param.d.ts.map

package/build/gate/param.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"param.d.ts","sourceRoot":"","sources":["../../src/gate/param.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,eAAe,EAChB,MAAM,cAAc,CAAA;AACrB,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAI1F;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,aAAc,MAAM,KAAG,oBAAoB,GAAG,gBA6C3E,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,UAAW,MAAM,KAAG,eAoB9C,CAAA;AAED,2FAA2F;AAC3F,eAAO,MAAM,eAAe,eACd,MAAM,aACP,MAAM,GAAG;IAAE,MAAM,CAAC,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,KAC/D,MAmBF,CAAA"}

package/build/gate/param.js

@@ -0,0 +1,99 @@
+import { RESOURCE_PARAM_SEPARATOR, RESOURCE_SOURCE_SEPARATOR, RESOURCE_PATH_SEPARATOR, GateParamSource, GateParamErrorCode, DEFAULT_GATE_PARAM_SOURCES } from '../consts.js';
+const SOURCES = Object.values(GateParamSource);
+/**
+ * Read the `@…` half of a gate param.
+ *
+ * Two forms, and the difference between them is deliberate:
+ *
+ *   `@enquiryId`        — bare. A FLAT key, searched in `params` then `query`. It is never split on
+ *                         a dot, because a query key legally contains one and splitting it would
+ *                         change the meaning of selectors already deployed.
+ *   `@body:order.id`    — qualified. An explicit source and a nested path.
+ *
+ * The rule worth remembering: the bare form is lenient and flat, the qualified form is strict and
+ * nested.
+ */
+export const parseGateSelector = (selector) => {
+    if (selector === '') {
+        return { code: GateParamErrorCode.EmptySelector, detail: 'the selector after "@" is empty' };
+    }
+    const idx = selector.indexOf(RESOURCE_SOURCE_SEPARATOR);
+    if (idx < 0) {
+        return {
+            selector,
+            path: [selector],
+            sources: DEFAULT_GATE_PARAM_SOURCES
+        };
+    }
+    const source = selector.slice(0, idx);
+    const rest = selector.slice(idx + 1);
+    if (!SOURCES.includes(source)) {
+        return {
+            code: GateParamErrorCode.UnknownSource,
+            detail: `"${source}" is not one of ${SOURCES.join(', ')}`
+        };
+    }
+    if (rest === '') {
+        return {
+            code: GateParamErrorCode.EmptySelector,
+            detail: `"${source}:" names no path`
+        };
+    }
+    const path = rest.split(RESOURCE_PATH_SEPARATOR);
+    if (path.some(segment => segment === '')) {
+        return {
+            code: GateParamErrorCode.EmptySegment,
+            detail: `"${rest}" has an empty path segment`
+        };
+    }
+    return {
+        selector,
+        source: source,
+        path,
+        sources: [source]
+    };
+};
+/**
+ * Split a gate param into the permission it checks and where the resource id comes from.
+ *
+ * Splits at the FIRST `@`. Everything before it is the permission name looked up in the subject's
+ * grants; everything after says where to read the resource id at request time. The suffix is the
+ * gate's syntax and nothing else's — a permission stored or granted under a name containing one is a
+ * key nothing ever looks up.
+ */
+export const parseGateParam = (param) => {
+    const idx = param.indexOf(RESOURCE_PARAM_SEPARATOR);
+    if (idx < 0) {
+        return { permission: param };
+    }
+    const permission = param.slice(0, idx);
+    const selector = param.slice(idx + 1);
+    const parsed = parseGateSelector(selector);
+    if ('code' in parsed) {
+        return { permission, resourceParam: selector, error: parsed };
+    }
+    return {
+        permission,
+        // Kept for readers written against the flat form. Only meaningful when the form IS flat.
+        ...(parsed.source == null ? { resourceParam: selector } : {}),
+        resource: parsed
+    };
+};
+/** Compose a gate param. The inverse of `parseGateParam` for every selector it accepts. */
+export const formatGateParam = (permission, selector) => {
+    if (selector == null) {
+        return permission;
+    }
+    if (typeof selector === 'string') {
+        return selector === '' ? permission : `${permission}${RESOURCE_PARAM_SEPARATOR}${selector}`;
+    }
+    if (selector.path.length < 1) {
+        return permission;
+    }
+    const path = selector.path.join(RESOURCE_PATH_SEPARATOR);
+    const tail = selector.source == null
+        ? path
+        : `${selector.source}${RESOURCE_SOURCE_SEPARATOR}${path}`;
+    return `${permission}${RESOURCE_PARAM_SEPARATOR}${tail}`;
+};
+//# sourceMappingURL=param.js.map

package/build/gate/param.js.map

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

package/build/gate/resolve.d.ts

@@ -0,0 +1,10 @@
+import type { GateRequestLike, GateResourceSelector, GateResourceResolution } from '../types.js';
+/**
+ * Resolve the resource id a selector points at.
+ *
+ * Sources are tried in the selector's own order — for the bare form, route params before the query —
+ * and the first that yields a value wins. When none does, the reason travels back so the caller can
+ * tell a MISCONFIGURED gate (the request never carried that key) from a legitimately DENIED one.
+ */
+export declare const resolveGateResource: (req: GateRequestLike, selector: GateResourceSelector) => GateResourceResolution;
+//# sourceMappingURL=resolve.d.ts.map

package/build/gate/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/gate/resolve.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AA4EhG;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,QACzB,eAAe,YAAY,oBAAoB,KACnD,sBA2BF,CAAA"}

package/build/gate/resolve.js

@@ -0,0 +1,93 @@
+import { GateParamSource, GateResolutionFailure } from '../consts.js';
+const isRecord = (value) => value != null && typeof value === 'object';
+/**
+ * A resource id is a scalar. Anything else is refused rather than coerced.
+ *
+ * Stringifying an object would produce `"[object Object]"`, which then either matches nothing or —
+ * far worse — matches another record that stringified the same way.
+ */
+const scalar = (value) => {
+    switch (typeof value) {
+        case 'string':
+            return value;
+        case 'number':
+        case 'boolean':
+        case 'bigint':
+            return `${value}`;
+        default:
+            return null;
+    }
+};
+const sourceOf = (req, source) => {
+    switch (source) {
+        case GateParamSource.Params: return req.params;
+        case GateParamSource.Query: return req.query;
+        case GateParamSource.Body: return req.body;
+        case GateParamSource.Headers: return req.headers;
+        case GateParamSource.Auth: return req.auth;
+    }
+};
+/**
+ * Walk one source for the selector's path.
+ *
+ * Headers get two adjustments they need and nothing else does: the first segment is lowercased,
+ * because HTTP header names are case-insensitive and every server normalises them differently; and a
+ * single-element array unwraps, because a repeated header arrives as an array and silently picking
+ * one of several values would be an authorization decision made by accident.
+ */
+const walk = (container, path, source) => {
+    if (!isRecord(container)) {
+        return { reason: GateResolutionFailure.SourceMissing };
+    }
+    let cursor = container;
+    for (const [index, rawSegment] of path.entries()) {
+        if (!isRecord(cursor)) {
+            return { reason: GateResolutionFailure.NotProvided };
+        }
+        const segment = source === GateParamSource.Headers && index === 0
+            ? rawSegment.toLowerCase()
+            : rawSegment;
+        cursor = cursor[segment];
+    }
+    if (source === GateParamSource.Headers && Array.isArray(cursor)) {
+        if (cursor.length !== 1) {
+            return { reason: GateResolutionFailure.NotScalar };
+        }
+        cursor = cursor[0];
+    }
+    if (cursor == null) {
+        return { reason: GateResolutionFailure.NotProvided };
+    }
+    return { value: cursor };
+};
+/**
+ * Resolve the resource id a selector points at.
+ *
+ * Sources are tried in the selector's own order — for the bare form, route params before the query —
+ * and the first that yields a value wins. When none does, the reason travels back so the caller can
+ * tell a MISCONFIGURED gate (the request never carried that key) from a legitimately DENIED one.
+ */
+export const resolveGateResource = (req, selector) => {
+    let reason = GateResolutionFailure.SourceMissing;
+    for (const source of selector.sources) {
+        const result = walk(sourceOf(req, source), selector.path, source);
+        if (result.reason != null) {
+            // A hard refusal is more informative than "keep looking" — report it rather than letting a
+            // later, emptier source overwrite it with a vaguer reason.
+            if (result.reason === GateResolutionFailure.NotScalar) {
+                return { reason: result.reason, from: source };
+            }
+            if (reason === GateResolutionFailure.SourceMissing) {
+                reason = result.reason;
+            }
+            continue;
+        }
+        const value = scalar(result.value);
+        if (value == null) {
+            return { reason: GateResolutionFailure.NotScalar, from: source };
+        }
+        return { id: value, from: source };
+    }
+    return { reason };
+};
+//# sourceMappingURL=resolve.js.map

package/build/gate/resolve.js.map

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

package/build/gate/validate.d.ts

@@ -0,0 +1,15 @@
+import type { GateParamAudit, GateParamIssue } from '../types.js';
+/** The `:name` segments of a route template. */
+export declare const routeParamsOf: (path: string) => string[];
+/**
+ * Check gate params against what their entrypoint declares.
+ *
+ * Reports only what is provable from the declaration itself. Anything that would need a guess is
+ * left alone: a check that fires on correct code stops being read.
+ *
+ * Meant to run where a mistake can still be fixed — while code is being generated, or once per alias
+ * as a diagnostic. It must never decide a request: with `some()` semantics across params, one
+ * malformed sibling must not be able to refuse a legitimately passing one.
+ */
+export declare const validateGateParams: (params: string[], audit?: GateParamAudit) => GateParamIssue[];
+//# sourceMappingURL=validate.d.ts.map

package/build/gate/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/gate/validate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAwB,MAAM,aAAa,CAAA;AAGvF,gDAAgD;AAChD,eAAO,MAAM,aAAa,SAAU,MAAM,KAAG,MAAM,EAGH,CAAA;AA0FhD;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,WAAY,MAAM,EAAE,UAAU,cAAc,KAAG,cAAc,EAsB3F,CAAA"}

package/build/gate/validate.js

@@ -0,0 +1,107 @@
+import { normalizePath, SEP, PARAM } from '@owlmeans/route';
+import { GateParamSource, GateParamErrorCode } from '../consts.js';
+import { parseGateParam } from './param.js';
+/** The `:name` segments of a route template. */
+export const routeParamsOf = (path) => normalizePath(path).split(SEP)
+    .filter(segment => segment.startsWith(PARAM))
+    .map(segment => segment.slice(PARAM.length));
+/**
+ * Whether a key can survive validation to reach the gate.
+ *
+ * The server compiles entrypoint filters with AJV's `removeAdditional`, which strips an undeclared
+ * key BEFORE the handler — and therefore before the gate — runs. So a selector naming a key the
+ * filter does not declare denies every request, with a clean build and nothing logged.
+ *
+ * The `additionalProperties === false` qualifier is what makes this check usable rather than noise:
+ * AJV only strips when a schema says so. An entrypoint that declares no filter for a source strips
+ * nothing, and reporting those would fire on nearly every endpoint and be ignored within a week.
+ */
+const unreachable = (schema, key) => {
+    if (schema == null) {
+        return false;
+    }
+    const { properties, additionalProperties } = schema;
+    if (additionalProperties !== false) {
+        return false;
+    }
+    return properties == null || !(key in properties);
+};
+const filterFor = (audit, source) => {
+    switch (source) {
+        case GateParamSource.Query: return audit.filter?.query;
+        case GateParamSource.Body: return audit.filter?.body;
+        case GateParamSource.Headers: return audit.filter?.headers;
+        case GateParamSource.Params: return audit.filter?.params;
+        case GateParamSource.Auth: return undefined;
+    }
+};
+const auditSelector = (audit, selector) => {
+    const key = selector.path[0];
+    if (key == null) {
+        return null;
+    }
+    // The bare form searches route params first and the query second, so it is only provably wrong
+    // when BOTH are impossible. A declared route param settles it; otherwise fall through to the
+    // query check below, which only fires on an explicitly closed schema.
+    const routeParams = audit.routeParams
+        ?? (audit.routePath != null ? routeParamsOf(audit.routePath) : undefined);
+    if (selector.source == null) {
+        if (routeParams?.includes(key) === true) {
+            return null;
+        }
+        if (unreachable(audit.filter?.query, key) && unreachable(audit.filter?.params, key)) {
+            return {
+                code: GateParamErrorCode.UnknownRouteParam,
+                detail: `"${key}" is not a route param of "${audit.routePath ?? '?'}"`
+                    + ' and is declared by neither the params nor the query filter'
+            };
+        }
+        return null;
+    }
+    if (selector.source === GateParamSource.Params) {
+        if (routeParams != null && !routeParams.includes(key) && unreachable(audit.filter?.params, key)) {
+            return {
+                code: GateParamErrorCode.UnknownRouteParam,
+                detail: `"${key}" is not a route param of "${audit.routePath ?? '?'}"`
+            };
+        }
+        return null;
+    }
+    if (unreachable(filterFor(audit, selector.source), key)) {
+        return {
+            code: GateParamErrorCode.UnreachableKey,
+            detail: `the ${selector.source} filter declares no "${key}" and forbids additional properties,`
+                + ' so it is removed by validation before the gate can read it'
+        };
+    }
+    return null;
+};
+/**
+ * Check gate params against what their entrypoint declares.
+ *
+ * Reports only what is provable from the declaration itself. Anything that would need a guess is
+ * left alone: a check that fires on correct code stops being read.
+ *
+ * Meant to run where a mistake can still be fixed — while code is being generated, or once per alias
+ * as a diagnostic. It must never decide a request: with `some()` semantics across params, one
+ * malformed sibling must not be able to refuse a legitimately passing one.
+ */
+export const validateGateParams = (params, audit) => {
+    const issues = [];
+    for (const param of params) {
+        const parsed = parseGateParam(param);
+        if (parsed.error != null) {
+            issues.push({ param, code: parsed.error.code, detail: parsed.error.detail });
+            continue;
+        }
+        if (parsed.resource == null || audit == null) {
+            continue;
+        }
+        const issue = auditSelector(audit, parsed.resource);
+        if (issue != null) {
+            issues.push({ param, ...issue });
+        }
+    }
+    return issues;
+};
+//# sourceMappingURL=validate.js.map

package/build/gate/validate.js.map

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

package/build/index.d.ts

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

package/build/index.d.ts.map

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

package/build/index.js

@@ -1,4 +1,6 @@
 export * from './consts.js';
 export * from './errors.js';
 export * from './utils.js';
+export * from './gate/index.js';
+export * from './permission.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;AAC3B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA"}

package/build/permission.d.ts

@@ -0,0 +1,21 @@
+import type { ParsedPermissionName } from './types.js';
+/**
+ * Read a permission NAME.
+ *
+ * The name is `<resource>--<action>`, with TWO hyphens. One hyphen is not a separator: `enquiry-view`
+ * is a resource called `enquiry-view` carrying no action, and it must keep parsing that way — a name
+ * already granted somewhere cannot be re-interpreted without orphaning the grant.
+ *
+ * A name never carries a gate selector. `@` is the gate's syntax, and a name containing one is
+ * exactly the corruption this function exists to make visible, so it is reported through `problem`
+ * rather than quietly split.
+ */
+export declare const parsePermissionName: (name: string) => ParsedPermissionName;
+/** Compose a permission name. The inverse of `parsePermissionName`. */
+export declare const composePermissionName: (parts: {
+    resource: string;
+    action?: string;
+}) => string;
+/** True when the value is a usable permission name — well-formed and carrying no gate selector. */
+export declare const isPermissionName: (value: string) => boolean;
+//# sourceMappingURL=permission.d.ts.map

package/build/permission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.d.ts","sourceRoot":"","sources":["../src/permission.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAEtD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,SAAU,MAAM,KAAG,oBAsBlD,CAAA;AAED,uEAAuE;AACvE,eAAO,MAAM,qBAAqB,UACzB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,KAC3C,MAEiE,CAAA;AAEpE,mGAAmG;AACnG,eAAO,MAAM,gBAAgB,UAAW,MAAM,KAAG,OACU,CAAA"}

package/build/permission.js

@@ -0,0 +1,39 @@
+import { PERMISSION_ACTION_SEPARATOR, RESOURCE_PARAM_SEPARATOR, GateParamErrorCode } from './consts.js';
+/**
+ * Read a permission NAME.
+ *
+ * The name is `<resource>--<action>`, with TWO hyphens. One hyphen is not a separator: `enquiry-view`
+ * is a resource called `enquiry-view` carrying no action, and it must keep parsing that way — a name
+ * already granted somewhere cannot be re-interpreted without orphaning the grant.
+ *
+ * A name never carries a gate selector. `@` is the gate's syntax, and a name containing one is
+ * exactly the corruption this function exists to make visible, so it is reported through `problem`
+ * rather than quietly split.
+ */
+export const parsePermissionName = (name) => {
+    const problem = name.includes(RESOURCE_PARAM_SEPARATOR)
+        ? {
+            code: GateParamErrorCode.UnreachableKey,
+            detail: `"${name}" carries a gate selector; "${RESOURCE_PARAM_SEPARATOR}" is never part of a`
+                + ' permission name, and nothing ever looks up a name that contains one'
+        }
+        : undefined;
+    const idx = name.indexOf(PERMISSION_ACTION_SEPARATOR);
+    if (idx < 0) {
+        return { name, resource: name, ...(problem != null ? { problem } : {}) };
+    }
+    const action = name.slice(idx + PERMISSION_ACTION_SEPARATOR.length);
+    return {
+        name,
+        resource: name.slice(0, idx),
+        ...(action !== '' ? { action } : {}),
+        ...(problem != null ? { problem } : {})
+    };
+};
+/** Compose a permission name. The inverse of `parsePermissionName`. */
+export const composePermissionName = (parts) => parts.action == null || parts.action === ''
+    ? parts.resource
+    : `${parts.resource}${PERMISSION_ACTION_SEPARATOR}${parts.action}`;
+/** True when the value is a usable permission name — well-formed and carrying no gate selector. */
+export const isPermissionName = (value) => value !== '' && !value.includes(RESOURCE_PARAM_SEPARATOR);
+//# sourceMappingURL=permission.js.map

package/build/permission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.js","sourceRoot":"","sources":["../src/permission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAGvG;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,IAAY,EAAwB,EAAE;IACxE,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,wBAAwB,CAAC;QACrD,CAAC,CAAC;YACA,IAAI,EAAE,kBAAkB,CAAC,cAAc;YACvC,MAAM,EAAE,IAAI,IAAI,+BAA+B,wBAAwB,sBAAsB;kBACzF,sEAAsE;SAC3E;QACD,CAAC,CAAC,SAAS,CAAA;IAEb,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,2BAA2B,CAAC,CAAA;IACrD,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;QACZ,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAA;IAC1E,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,2BAA2B,CAAC,MAAM,CAAC,CAAA;IAEnE,OAAO;QACL,IAAI;QACJ,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;QAC5B,GAAG,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpC,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxC,CAAA;AACH,CAAC,CAAA;AAED,uEAAuE;AACvE,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,KAA4C,EACpC,EAAE,CAAC,KAAK,CAAC,MAAM,IAAI,IAAI,IAAI,KAAK,CAAC,MAAM,KAAK,EAAE;IACtD,CAAC,CAAC,KAAK,CAAC,QAAQ;IAChB,CAAC,CAAC,GAAG,KAAK,CAAC,QAAQ,GAAG,2BAA2B,GAAG,KAAK,CAAC,MAAM,EAAE,CAAA;AAEpE,mGAAmG;AACnG,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAa,EAAW,EAAE,CACzD,KAAK,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,wBAAwB,CAAC,CAAA"}