@owlmeans/iam 0.1.18-rc.0 → 0.1.18-rc.11

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/iam",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.504Z",
+  "version": "0.1.18-rc.9",
+  "generatedAt": "2026-08-27T16:32:18.499Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -23,6 +23,9 @@ Provider-agnostic IAM abstraction. Defines `IamService` interface and related ty
 | `IamPermissionDefinition` | type | Declared permission `{ name, resource, action?, resourceScoped?, title? }` |
 | `IamGrantArgs` | type | `{ resources?: string[] }` — present = resource-scoped grant form |
 | `IamGrant` | type | `{ profileId, clientId, permission, resources? }` |
+| `IamUser` | type | End-user of an entity `{ profileId, email?, name?, role, disabled?, grantCount? }` |
+| `IamUserInvite` | type | `{ email, name?, role? }` — find-or-create args |
+| `IamUserUpdate` | type | `{ name?, role?, disabled? }` |
 | `hasPermission` | fn | `(auth, permission, { scope?, resourceId? }?)` — checks `Authorization.permissions` PermissionSet[]; an unscoped set satisfies a resourceId check |
 | `DEFAULT_ALIAS` | const | Default service alias `'iam-service'` |
 | `IAM_MODE_KEYCLOAK` | const | `'keycloak'` |
@@ -62,8 +65,15 @@ interface IamService extends InitializedService {
 
   // Provision an OIDC client for a tenant and return its credentials.
   // options.redirectUris hardens the client; always pass them (see "Issuer & redirect URIs").
+  // MUST refuse an existing record owned by another entity — see "A client id is a global name".
   ensureClient: (entityId: string, clientId: string, options?: IamClientOptions) => Promise<IamClient>
 
+  // Reserve a free client id without provisioning it; false when anyone else holds it.
+  claimClient: (entityId: string, clientId: string) => Promise<boolean>
+
+  // Release a client id and everything keyed by it (called when a project/slot is deleted).
+  deleteClient: (entityId: string, clientId: string) => Promise<void>
+
   // Provision a named permission on a client resource; returns the resource name
   ensurePermission: (entityId: string, clientId: string, resource?: string, args?: IamPermissionArgs) => Promise<string>
 
@@ -83,9 +93,49 @@ interface IamService extends InitializedService {
 
   // List grants for the client, optionally for one subject
   listGrants: (entityId: string, clientId: string, profileId?: string) => Promise<IamGrant[]>
+
+  // --- End-user management (customer-wide users, shared per entityId) ---
+
+  // Every end-user of the entity. clientId scopes the reported grantCount — it does NOT filter.
+  listUsers: (entityId: string, clientId?: string) => Promise<IamUser[]>
+  getUser: (entityId: string, profileId: string) => Promise<IamUser | null>
+  // Find-or-create by email — the one way an end-user record comes into existence.
+  inviteUser: (entityId: string, invite: IamUserInvite) => Promise<IamUser>
+  updateUser: (entityId: string, profileId: string, update: IamUserUpdate) => Promise<IamUser>
+  removeUser: (entityId: string, profileId: string) => Promise<void>
 }
 ```
 
+## End-users are customer-wide
+
+An end-user belongs to the **entity**, not to a project: one customer's users are shared across every
+project they own. `listUsers` therefore returns the entity's whole set and `clientId` only scopes the
+reported `grantCount` to one project's client. Do not reintroduce a per-client filter — a person who
+has authenticated against a project but holds no grant there is still that project's user, and the
+screen that hands out grants is exactly where they have to be visible.
+
+`inviteUser` is idempotent by email, which is what lets an invitation and a first sign-in converge on
+one record instead of accumulating twins. Backends that have no user store of their own (keycloak,
+where the customer manages realm users in its console) throw `IamUnsupported('user-management')` from
+all five methods; callers turn that into an "external console" fallback rather than an error.
+
+## A client id is a global name
+
+A provider resolves a client from the bare `client_id` a relying party sends — the adapter gets no
+tenant context — so the id is unique across the whole deployment, not per entity, and the store
+cannot namespace it on a consumer's behalf. Uniqueness has to be *in the id*.
+
+- Compose it with the owning entity in it. A name derived from a project's own name alone lets two
+  organizations share one registration: one secret, one redirect-URI list, one permission-definition
+  set, and one grant namespace, because `PermissionSet.scope` is that same string.
+- `ensureClient` refuses a record belonging to another entity rather than returning it. The failure
+  is deliberate — a loud provisioning error is the only alternative to a silent cross-tenant handover.
+- Assign an id **once** and reserve it with `claimClient`. Whatever a consumer derives ids from
+  (a project alias, a slug) may later be released and re-used by a sibling, so only the registry can
+  say whether an id is free. `deleteClient` gives it back, or a deleted project's name is burned.
+- Backends whose clients are already per-tenant (keycloak realms) satisfy this by construction:
+  `claimClient` returns true and `deleteClient` may be `IamUnsupported`.
+
 ## `IamClient.realm` field
 
 `realm` is set by the provider to the entity ID. Use it instead of accessing internal properties:

package/build/consts.d.ts

@@ -2,4 +2,95 @@ export declare const DEFAULT_ALIAS = "iam-service";
 export declare const IAM_MODE_KEYCLOAK = "keycloak";
 export declare const IAM_MODE_INTEGRATED = "integrated";
 export type IamMode = typeof IAM_MODE_KEYCLOAK | typeof IAM_MODE_INTEGRATED;
+/**
+ * Gate-param syntax: `<permission>[@<selector>]`.
+ *
+ * The `@` belongs to the GATE and to nothing else. It says where a resource id is read from at
+ * request time; it is never part of a permission's stored NAME. A definition or a grant whose name
+ * carries one is a key nothing ever looks up, so every grant against it is a silent no-op.
+ */
+export declare const RESOURCE_PARAM_SEPARATOR = "@";
+/**
+ * Separates an explicit source from its path: `@body:order.id`.
+ *
+ * Deliberately `:` rather than a dot. Under a dotted-only form the meaning of a selector changes the
+ * moment a route gains a param named like a source keyword — `/report/:query` with `@query.id` flips
+ * from "the route param literally named `query.id`" to "the query string's `id`", redirecting an
+ * authorization lookup from a router-matched value to attacker-supplied input, caused by an
+ * unrelated route rename. `:` is decidable in one character, and no gate-param string written before
+ * this existed can contain one.
+ */
+export declare const RESOURCE_SOURCE_SEPARATOR = ":";
+/** Separates path segments inside a qualified selector: `@body:order.id`. */
+export declare const RESOURCE_PATH_SEPARATOR = ".";
+/** Where a qualified selector may read a resource id from. */
+export declare enum GateParamSource {
+    Params = "params",
+    Query = "query",
+    Body = "body",
+    Headers = "headers",
+    Auth = "auth"
+}
+/**
+ * What the bare form (`@enquiryId`) searches, in order.
+ *
+ * Params first, then query. The query fallback is legacy and deliberately kept: removing it would
+ * silently deny already-deployed applications whose selector happens to name a query key, and a
+ * silent denial inside a customer's running app is the worst available outcome.
+ */
+export declare const DEFAULT_GATE_PARAM_SOURCES: GateParamSource[];
+/** Why a gate param is structurally wrong — a misconfiguration, not a failed authorization. */
+export declare enum GateParamErrorCode {
+    UnknownSource = "gate-param:unknown-source",
+    EmptySelector = "gate-param:empty-selector",
+    EmptySegment = "gate-param:empty-segment",
+    /** Named a request key the entrypoint's filter does not declare — AJV strips it before the gate. */
+    UnreachableKey = "gate-param:unreachable-key",
+    /** Named a route param the entrypoint's own path does not carry. */
+    UnknownRouteParam = "gate-param:unknown-route-param"
+}
+/** Why a selector produced no resource id. */
+export declare enum GateResolutionFailure {
+    /** The source exists, the path does not. */
+    NotProvided = "not-provided",
+    /** The request carries no such source at all. */
+    SourceMissing = "source-missing",
+    /** Resolved to an object or a multi-element array — refused rather than stringified. */
+    NotScalar = "not-scalar",
+    /** The selector itself did not parse. */
+    Malformed = "malformed"
+}
+/**
+ * Which FORM of a grant an operation addresses.
+ *
+ * A resource-scoped permission is grantable two ways, under one name: `Blanket` (a PermissionSet
+ * carrying no `resources`, which `hasPermission` reads as covering every id) and `Resources` (an
+ * explicit id list). They are stored separately and must be revoked separately, or a UI offering
+ * both controls would have one silently wipe the other.
+ */
+export declare enum IamGrantMode {
+    Blanket = "blanket",
+    Resources = "resources",
+    /** Revoke-only: every form. Illegal on a grant. */
+    All = "all"
+}
+/** What to do about grants that still reference a definition being removed. */
+export declare enum IamRemovalPolicy {
+    /** Strip the permission from every subject of the entity, then drop the definition. */
+    Cascade = "cascade",
+    /** Refuse while any subject still holds it; the holders travel in the error. */
+    Refuse = "refuse"
+}
+/**
+ * The grouping tiers a permission definition may be tagged with.
+ *
+ * A tag decides NOTHING at request time — `hasPermission` and every gate treat a permission name as
+ * one opaque string — and only groups the permission in an administrator's screen. `guest` is
+ * deliberately absent: a public surface declares no permissions, and adding an area later would
+ * re-classify names already tagged.
+ */
+export declare const IAM_AREAS: readonly ['user', 'operator', 'admin'];
+export type IamArea = typeof IAM_AREAS[number];
+/** Separates the resource from the action in a permission name. TWO hyphens, never one. */
+export declare const PERMISSION_ACTION_SEPARATOR = "--";
 //# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,gBAAgB,CAAA;AAE1C,eAAO,MAAM,iBAAiB,aAAa,CAAA;AAC3C,eAAO,MAAM,mBAAmB,eAAe,CAAA;AAE/C,MAAM,MAAM,OAAO,GAAG,OAAO,iBAAiB,GAAG,OAAO,mBAAmB,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,gBAAgB,CAAA;AAE1C,eAAO,MAAM,iBAAiB,aAAa,CAAA;AAC3C,eAAO,MAAM,mBAAmB,eAAe,CAAA;AAE/C,MAAM,MAAM,OAAO,GAAG,OAAO,iBAAiB,GAAG,OAAO,mBAAmB,CAAA;AAE3E;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAE3C;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAA;AAE5C,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,MAAM,CAAA;AAE1C,8DAA8D;AAC9D,oBAAY,eAAe;IACzB,MAAM,WAAW;IACjB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,IAAI,SAAS;CACd;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,EAAE,eAAe,EAEvD,CAAA;AAED,+FAA+F;AAC/F,oBAAY,kBAAkB;IAC5B,aAAa,8BAA8B;IAC3C,aAAa,8BAA8B;IAC3C,YAAY,6BAA6B;IACzC,oGAAoG;IACpG,cAAc,+BAA+B;IAC7C,oEAAoE;IACpE,iBAAiB,mCAAmC;CACrD;AAED,8CAA8C;AAC9C,oBAAY,qBAAqB;IAC/B,4CAA4C;IAC5C,WAAW,iBAAiB;IAC5B,iDAAiD;IACjD,aAAa,mBAAmB;IAChC,wFAAwF;IACxF,SAAS,eAAe;IACxB,yCAAyC;IACzC,SAAS,cAAc;CACxB;AAED;;;;;;;GAOG;AACH,oBAAY,YAAY;IACtB,OAAO,YAAY;IACnB,SAAS,cAAc;IACvB,mDAAmD;IACnD,GAAG,QAAQ;CACZ;AAED,+EAA+E;AAC/E,oBAAY,gBAAgB;IAC1B,uFAAuF;IACvF,OAAO,YAAY;IACnB,gFAAgF;IAChF,MAAM,WAAW;CAClB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,YAAI,MAAM,EAAE,UAAU,EAAE,OAAO,CAAU,CAAA;AAE/D,MAAM,MAAM,OAAO,GAAG,OAAO,SAAS,CAAC,MAAM,CAAC,CAAA;AAE9C,2FAA2F;AAC3F,eAAO,MAAM,2BAA2B,OAAO,CAAA"}

package/build/consts.js

@@ -1,4 +1,101 @@
 export const DEFAULT_ALIAS = 'iam-service';
 export const IAM_MODE_KEYCLOAK = 'keycloak';
 export const IAM_MODE_INTEGRATED = 'integrated';
+/**
+ * Gate-param syntax: `<permission>[@<selector>]`.
+ *
+ * The `@` belongs to the GATE and to nothing else. It says where a resource id is read from at
+ * request time; it is never part of a permission's stored NAME. A definition or a grant whose name
+ * carries one is a key nothing ever looks up, so every grant against it is a silent no-op.
+ */
+export const RESOURCE_PARAM_SEPARATOR = '@';
+/**
+ * Separates an explicit source from its path: `@body:order.id`.
+ *
+ * Deliberately `:` rather than a dot. Under a dotted-only form the meaning of a selector changes the
+ * moment a route gains a param named like a source keyword — `/report/:query` with `@query.id` flips
+ * from "the route param literally named `query.id`" to "the query string's `id`", redirecting an
+ * authorization lookup from a router-matched value to attacker-supplied input, caused by an
+ * unrelated route rename. `:` is decidable in one character, and no gate-param string written before
+ * this existed can contain one.
+ */
+export const RESOURCE_SOURCE_SEPARATOR = ':';
+/** Separates path segments inside a qualified selector: `@body:order.id`. */
+export const RESOURCE_PATH_SEPARATOR = '.';
+/** Where a qualified selector may read a resource id from. */
+export var GateParamSource;
+(function (GateParamSource) {
+    GateParamSource["Params"] = "params";
+    GateParamSource["Query"] = "query";
+    GateParamSource["Body"] = "body";
+    GateParamSource["Headers"] = "headers";
+    GateParamSource["Auth"] = "auth";
+})(GateParamSource || (GateParamSource = {}));
+/**
+ * What the bare form (`@enquiryId`) searches, in order.
+ *
+ * Params first, then query. The query fallback is legacy and deliberately kept: removing it would
+ * silently deny already-deployed applications whose selector happens to name a query key, and a
+ * silent denial inside a customer's running app is the worst available outcome.
+ */
+export const DEFAULT_GATE_PARAM_SOURCES = [
+    GateParamSource.Params, GateParamSource.Query
+];
+/** Why a gate param is structurally wrong — a misconfiguration, not a failed authorization. */
+export var GateParamErrorCode;
+(function (GateParamErrorCode) {
+    GateParamErrorCode["UnknownSource"] = "gate-param:unknown-source";
+    GateParamErrorCode["EmptySelector"] = "gate-param:empty-selector";
+    GateParamErrorCode["EmptySegment"] = "gate-param:empty-segment";
+    /** Named a request key the entrypoint's filter does not declare — AJV strips it before the gate. */
+    GateParamErrorCode["UnreachableKey"] = "gate-param:unreachable-key";
+    /** Named a route param the entrypoint's own path does not carry. */
+    GateParamErrorCode["UnknownRouteParam"] = "gate-param:unknown-route-param";
+})(GateParamErrorCode || (GateParamErrorCode = {}));
+/** Why a selector produced no resource id. */
+export var GateResolutionFailure;
+(function (GateResolutionFailure) {
+    /** The source exists, the path does not. */
+    GateResolutionFailure["NotProvided"] = "not-provided";
+    /** The request carries no such source at all. */
+    GateResolutionFailure["SourceMissing"] = "source-missing";
+    /** Resolved to an object or a multi-element array — refused rather than stringified. */
+    GateResolutionFailure["NotScalar"] = "not-scalar";
+    /** The selector itself did not parse. */
+    GateResolutionFailure["Malformed"] = "malformed";
+})(GateResolutionFailure || (GateResolutionFailure = {}));
+/**
+ * Which FORM of a grant an operation addresses.
+ *
+ * A resource-scoped permission is grantable two ways, under one name: `Blanket` (a PermissionSet
+ * carrying no `resources`, which `hasPermission` reads as covering every id) and `Resources` (an
+ * explicit id list). They are stored separately and must be revoked separately, or a UI offering
+ * both controls would have one silently wipe the other.
+ */
+export var IamGrantMode;
+(function (IamGrantMode) {
+    IamGrantMode["Blanket"] = "blanket";
+    IamGrantMode["Resources"] = "resources";
+    /** Revoke-only: every form. Illegal on a grant. */
+    IamGrantMode["All"] = "all";
+})(IamGrantMode || (IamGrantMode = {}));
+/** What to do about grants that still reference a definition being removed. */
+export var IamRemovalPolicy;
+(function (IamRemovalPolicy) {
+    /** Strip the permission from every subject of the entity, then drop the definition. */
+    IamRemovalPolicy["Cascade"] = "cascade";
+    /** Refuse while any subject still holds it; the holders travel in the error. */
+    IamRemovalPolicy["Refuse"] = "refuse";
+})(IamRemovalPolicy || (IamRemovalPolicy = {}));
+/**
+ * The grouping tiers a permission definition may be tagged with.
+ *
+ * A tag decides NOTHING at request time — `hasPermission` and every gate treat a permission name as
+ * one opaque string — and only groups the permission in an administrator's screen. `guest` is
+ * deliberately absent: a public surface declares no permissions, and adding an area later would
+ * re-classify names already tagged.
+ */
+export const IAM_AREAS = ['user', 'operator', 'admin'];
+/** Separates the resource from the action in a permission name. TWO hyphens, never one. */
+export const PERMISSION_ACTION_SEPARATOR = '--';
 //# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -1 +1 @@
-{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAA;AAE1C,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAA;AAC3C,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAA"}
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAA;AAE1C,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAA;AAC3C,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAA;AAI/C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAA;AAE3C;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,CAAA;AAE5C,6EAA6E;AAC7E,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAA;AAE1C,8DAA8D;AAC9D,MAAM,CAAN,IAAY,eAMX;AAND,WAAY,eAAe;IACzB,oCAAiB,CAAA;IACjB,kCAAe,CAAA;IACf,gCAAa,CAAA;IACb,sCAAmB,CAAA;IACnB,gCAAa,CAAA;AACf,CAAC,EANW,eAAe,KAAf,eAAe,QAM1B;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAsB;IAC3D,eAAe,CAAC,MAAM,EAAE,eAAe,CAAC,KAAK;CAC9C,CAAA;AAED,+FAA+F;AAC/F,MAAM,CAAN,IAAY,kBAQX;AARD,WAAY,kBAAkB;IAC5B,iEAA2C,CAAA;IAC3C,iEAA2C,CAAA;IAC3C,+DAAyC,CAAA;IACzC,oGAAoG;IACpG,mEAA6C,CAAA;IAC7C,oEAAoE;IACpE,0EAAoD,CAAA;AACtD,CAAC,EARW,kBAAkB,KAAlB,kBAAkB,QAQ7B;AAED,8CAA8C;AAC9C,MAAM,CAAN,IAAY,qBASX;AATD,WAAY,qBAAqB;IAC/B,4CAA4C;IAC5C,qDAA4B,CAAA;IAC5B,iDAAiD;IACjD,yDAAgC,CAAA;IAChC,wFAAwF;IACxF,iDAAwB,CAAA;IACxB,yCAAyC;IACzC,gDAAuB,CAAA;AACzB,CAAC,EATW,qBAAqB,KAArB,qBAAqB,QAShC;AAED;;;;;;;GAOG;AACH,MAAM,CAAN,IAAY,YAKX;AALD,WAAY,YAAY;IACtB,mCAAmB,CAAA;IACnB,uCAAuB,CAAA;IACvB,mDAAmD;IACnD,2BAAW,CAAA;AACb,CAAC,EALW,YAAY,KAAZ,YAAY,QAKvB;AAED,+EAA+E;AAC/E,MAAM,CAAN,IAAY,gBAKX;AALD,WAAY,gBAAgB;IAC1B,uFAAuF;IACvF,uCAAmB,CAAA;IACnB,gFAAgF;IAChF,qCAAiB,CAAA;AACnB,CAAC,EALW,gBAAgB,KAAhB,gBAAgB,QAK3B;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAU,CAAA;AAI/D,2FAA2F;AAC3F,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAA"}

package/build/errors.d.ts

@@ -15,6 +15,19 @@ export declare class IamGrantError extends IamError {
     static typeName: string;
     constructor(message?: string);
 }
+/**
+ * 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 declare class IamPermissionError extends IamError {
+    static typeName: string;
+    constructor(message?: string);
+}
 export declare class IamUnsupported extends IamError {
     static typeName: string;
     constructor(message?: string);

package/build/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,qBAAa,QAAS,SAAQ,cAAc;IAC1C,OAAuB,QAAQ,SAAkC;IAEjE,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAAwC;IAEvE,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,gBAAiB,SAAQ,QAAQ;IAC5C,OAAuB,QAAQ,SAA0C;IAEzE,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,aAAc,SAAQ,QAAQ;IACzC,OAAuB,QAAQ,SAAuC;IAEtE,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAA6C;IAE5E,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,YAAa,SAAQ,QAAQ;IACxC,OAAuB,QAAQ,SAAsC;IAErE,YAAY,OAAO,SAAU,EAG5B;CACF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,qBAAa,QAAS,SAAQ,cAAc;IAC1C,OAAuB,QAAQ,SAAkC;IAEjE,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAAwC;IAEvE,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,gBAAiB,SAAQ,QAAQ;IAC5C,OAAuB,QAAQ,SAA0C;IAEzE,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,aAAc,SAAQ,QAAQ;IACzC,OAAuB,QAAQ,SAAuC;IAEtE,YAAY,OAAO,SAAU,EAG5B;CACF;AAED;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;IAC9C,OAAuB,QAAQ,SAA4C;IAE3E,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAA6C;IAE5E,YAAY,OAAO,SAAU,EAG5B;CACF;AAED,qBAAa,YAAa,SAAQ,QAAQ;IACxC,OAAuB,QAAQ,SAAsC;IAErE,YAAY,OAAO,SAAU,EAG5B;CACF"}

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