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

package/build/types.d.ts

@@ -1,5 +1,77 @@
 import type { InitializedService } from '@owlmeans/context';
 import type { OidcProviderConfig } from '@owlmeans/oidc';
+import type { GateParamSource, GateParamErrorCode, GateResolutionFailure, IamGrantMode, IamRemovalPolicy } from './consts.js';
+/**
+ * The parts of a request a gate selector may read.
+ *
+ * Structural on purpose: `AbstractRequest` is assignable to it, so `@owlmeans/server-iam` passes its
+ * request straight through, while tooling outside the server stack can resolve a selector against a
+ * plain object without taking a dependency on `@owlmeans/entrypoint`.
+ */
+export interface GateRequestLike {
+    params?: unknown;
+    query?: unknown;
+    body?: unknown;
+    headers?: unknown;
+    auth?: unknown;
+}
+/** Where one gate param reads its resource id from. */
+export interface GateResourceSelector {
+    /** The selector text exactly as written, for diagnostics. */
+    readonly selector: string;
+    /** Undefined for the bare form, which searches `sources` in order. */
+    readonly source?: GateParamSource;
+    /** Length 1 and UNSPLIT for the bare form — a bare key may legally contain dots. */
+    readonly path: string[];
+    /** The explicit source, or `DEFAULT_GATE_PARAM_SOURCES`. */
+    readonly sources: GateParamSource[];
+}
+export interface GateParamProblem {
+    code: GateParamErrorCode;
+    detail: string;
+}
+export interface ParsedGateParam {
+    permission: string;
+    /**
+     * @deprecated The bare-form flat key, kept so existing readers keep compiling. Read `resource`,
+     * which carries the source and the path for both forms.
+     */
+    resourceParam?: string;
+    resource?: GateResourceSelector;
+    error?: GateParamProblem;
+}
+export interface GateResourceResolution {
+    id?: string;
+    from?: GateParamSource;
+    reason?: GateResolutionFailure;
+}
+/** What an entrypoint declares, so a selector can be checked against it before it is ever deployed. */
+export interface GateParamAudit {
+    routePath?: string;
+    routeParams?: string[];
+    filter?: {
+        query?: object;
+        params?: object;
+        body?: object;
+        headers?: object;
+    };
+}
+export interface GateParamIssue {
+    param: string;
+    code: GateParamErrorCode;
+    detail: string;
+}
+/** A permission NAME taken apart. Never carries a selector — `@` is the gate's syntax alone. */
+export interface ParsedPermissionName {
+    /** The whole name, exactly as it must be stored and granted. */
+    name: string;
+    /** What IAM stores as `resource`. The whole name when there is no action separator. */
+    resource: string;
+    /** What IAM stores as `action`. Absent for a bare, unsplittable legacy name. */
+    action?: string;
+    /** Set when the argument carried an `@` — which a NAME never legally does. */
+    problem?: GateParamProblem;
+}
 export interface IamClient {
     id?: string;
     clientId: string;
@@ -29,10 +101,32 @@ export interface IamClientOptions {
 export interface IamPermissionArgs {
     /** Action name. When absent the permission is unscoped (project-wide). */
     permission?: string;
-    /** Declares that grants of this permission may be bound to specific resource ids. */
+    /**
+     * Declares that grants of this permission may be bound to specific resource ids.
+     *
+     * It does NOT mean grants must be: the same name is grantable in either form. A grant carrying no
+     * resource ids covers every resource, which is what `hasPermission` already implements.
+     */
     resourceScoped?: boolean;
     /** Optional human-readable title for the permission definition. */
     title?: string;
+    /**
+     * Grouping tag — one of `IAM_AREAS`, or any string a deployment defines.
+     *
+     * Purely presentational: it groups the permission in an administrator's screen and is never read
+     * when a request is authorized. It is a TAG rather than a name segment precisely so an existing
+     * permission can be grouped without renaming it, which would orphan every grant already made.
+     */
+    area?: string;
+    /**
+     * Marks a permission the PLATFORM owns rather than one the application declared for itself.
+     *
+     * The distinction is not cosmetic: an operator must not be able to revoke a platform marker from
+     * an undifferentiated list, and a repair that deletes "definitions no declaration names" must not
+     * reach one — a marker can be enforced by a runtime decoration rather than by a gate parameter,
+     * so its absence from the declarations is not evidence that it is unused.
+     */
+    managed?: boolean;
 }
 export interface IamResourceSpec {
     name: string;
@@ -40,16 +134,40 @@ export interface IamResourceSpec {
 }
 /** A permission declared for an entity's client (project). */
 export interface IamPermissionDefinition {
-    /** Canonical name: "res--action" or bare "res" when unscoped. */
+    /** Canonical name: "res--action" or bare "res" when unscoped. NEVER carries an `@` selector. */
     name: string;
     resource: string;
     action?: string;
     resourceScoped?: boolean;
     title?: string;
+    /** Grouping tag; presentational only. See `IamPermissionArgs.area`. */
+    area?: string;
+    /** Owned by the platform rather than declared by the application. See `IamPermissionArgs.managed`. */
+    managed?: boolean;
+}
+/** Narrows a definition listing. An `areas` entry of `null` matches definitions carrying no tag. */
+export interface IamPermissionFilter {
+    areas?: (string | null)[];
+    managed?: boolean;
+    resourceScoped?: boolean;
 }
 export interface IamGrantArgs {
     /** Resource ids for the resource-scoped grant form; omit for an unscoped (project-wide) grant. */
     resources?: string[];
+    /**
+     * Which form to address. THE DEFAULTS ARE ASYMMETRIC ON PURPOSE, to preserve the semantics every
+     * existing caller already relies on:
+     *
+     *   grantPermission  — `resources != null` ? Resources : Blanket
+     *   revokePermission — `resources != null` ? Resources : All
+     *
+     * Revoke defaults to `All` because a bare `revokePermission(...)` has always meant "remove it
+     * everywhere". Narrowing that to `Blanket` would leave the resource-scoped set standing for every
+     * existing caller — a live grant surviving a revoke, which is the failure direction nobody detects.
+     *
+     * Pass `mode` explicitly rather than depending on the default.
+     */
+    mode?: IamGrantMode;
 }
 /** A permission granted to an end-user subject of an entity's client. */
 export interface IamGrant {
@@ -60,6 +178,51 @@ export interface IamGrant {
     permission: string;
     /** Present only for resource-scoped grants. */
     resources?: string[];
+    /** Which form this record is. Derived from `resources`, not new information. */
+    mode?: IamGrantMode;
+}
+/** Grants every definition a filter selects, plus any named outright. */
+export interface IamGrantBundle {
+    filter?: IamPermissionFilter;
+    /** Extra names included regardless of the filter — a platform marker, for instance. */
+    permissions?: string[];
+    /** Defaults to `Blanket`: a tier of access is a role, not a resource ACL. */
+    mode?: IamGrantMode;
+    /** Only meaningful with `mode: Resources`. */
+    resources?: string[];
+}
+export interface IamPermissionDeleteArgs {
+    /** Defaults to `Cascade`. */
+    policy?: IamRemovalPolicy;
+    /** Required to delete a `managed` definition. Defaults to false. */
+    managed?: boolean;
+}
+export interface IamPermissionRemoval {
+    permission: string;
+    clientId: string;
+    /** The definition existed and was removed. False is a normal, non-error outcome. */
+    found: boolean;
+    /** Grants stripped as part of the removal. */
+    revoked: IamGrant[];
+}
+export interface IamNormalizeArgs {
+    /** Compute and report the plan without writing anything. */
+    dryRun?: boolean;
+}
+export interface IamNormalizationReport {
+    clientId: string;
+    renamed: {
+        from: string;
+        to: string;
+        grantsMoved: number;
+    }[];
+    merged: {
+        from: string;
+        into: string;
+        grantsMoved: number;
+    }[];
+    /** Well-formed definitions deliberately left alone. */
+    untouched: string[];
 }
 /** An end-user of an entity (customer-wide; shared across that entity's projects). */
 export interface IamUser {
@@ -104,19 +267,87 @@ export interface IamService extends InitializedService {
      * misconfiguration is loud instead of yielding a silently wrong issuer.
      */
     getIssuerUrl: (entityId: string) => Promise<string>;
+    /**
+     * Find-or-create the entity's OIDC client.
+     *
+     * A client id is globally unique — a provider resolves it from the bare `client_id` a relying
+     * party sends, with no tenant context — so an implementation MUST refuse an existing record
+     * that belongs to a different entity (`IamClientError('client:entity-mismatch')`) rather than
+     * returning it. Silently adopting one hands the caller another tenant's secret and overwrites
+     * that tenant's redirect URIs.
+     */
     ensureClient: (entityId: string, clientId: string, options?: IamClientOptions) => Promise<IamClient>;
+    /**
+     * Reserve a client id for the entity without provisioning it, so a caller can find a free name
+     * before committing to it. Returns false when the id is already taken — by this entity or any
+     * other — and true when the reservation is now held.
+     *
+     * This exists because the id is minted from a name that may later be released (a project alias
+     * moves when its hostname is refused), so the naming index cannot answer whether an id is free.
+     * The registry is the only authority.
+     */
+    claimClient: (entityId: string, clientId: string) => Promise<boolean>;
+    /**
+     * Release a client id and everything keyed by it. Called when a project or slot is deleted —
+     * without it a recreated project can inherit a stale registration.
+     */
+    deleteClient: (entityId: string, clientId: string) => Promise<void>;
     /**
      * Ensures a permission/resource exists in the entity's client.
      * Returns the canonical resource name (e.g. "res--action" or "res").
+     *
+     * MERGES into an existing definition rather than replacing it: `resource` and `action` are
+     * re-derived and overwrite, while `title`, `resourceScoped`, `area` and `managed` are set when
+     * provided — including when provided as `false` — and KEPT when omitted. Replacing wholesale made
+     * every flag last-write-wins, so a caller that happened not to pass one erased it.
+     *
+     * It NEVER rewrites the name. Callers round-trip a definition's `resource` + `action` back through
+     * this method to copy a definition set between clients, so a rename here would silently orphan
+     * every grant made against the old name.
+     *
+     * The `resource` argument must not carry a gate selector: `@` is the gate's syntax and is never
+     * part of a stored name. Implementations reject one rather than storing a key no gate looks up.
      */
     ensurePermission: (entityId: string, clientId: string, resource?: string, args?: IamPermissionArgs) => Promise<string>;
+    /**
+     * Removes permission definitions, and by default every grant that referenced them.
+     *
+     * Takes NAMES: the definition record is keyed by name, and a malformed definition's stored
+     * `resource`/`action` cannot be trusted to recompose that key. Accepts an array so a repair costs
+     * one sweep of the entity's subjects rather than one per name.
+     *
+     * Idempotent — a name with no definition yields `{ found: false }` and writes nothing. Every other
+     * lifecycle operation here converges rather than erroring, and two repairs may run concurrently on
+     * one project.
+     *
+     * Implementations MUST revoke the grants before dropping the definition. There is no transaction
+     * across the two stores, and a crash between them must leave a definition with no grants — visible
+     * and re-runnable — rather than grants with no definition, which are invisible to any screen that
+     * renders the definition list yet still satisfy a gate.
+     *
+     * A `managed` definition is refused unless `args.managed` is explicitly true.
+     */
+    deletePermission: (entityId: string, clientId: string, permission: string | string[], args?: IamPermissionDeleteArgs) => Promise<IamPermissionRemoval[]>;
+    /**
+     * Repairs definitions whose stored name carries a gate selector, moving grants with them.
+     *
+     * Strictly a rename and merge — never a delete, never an invention. Where the stripped name
+     * already exists the two are merged, because one entrypoint scoping a permission by `:id` and
+     * another by `:enquiryId` describe ONE permission. The target is marked resource-scoped: a leaked
+     * selector is positive evidence that it is, and that evidence is otherwise discarded.
+     *
+     * Grants move in the same write that renames the definition, which is why this exists as its own
+     * operation: reconstructing it as delete + re-declare + re-grant drops real access on any failure
+     * between the three steps.
+     */
+    normalizePermissions: (entityId: string, clientId: string, args?: IamNormalizeArgs) => Promise<IamNormalizationReport>;
     /**
      * Idempotent: creates a resource, a client role for it, and assigns that role to
      * the entity-owner role. Used by payment provisioning for account/project/wl resources.
      */
     ensureResourceOwnership: (entityId: string, clientId: string, resource: IamResourceSpec) => Promise<void>;
-    /** Lists permission definitions registered for the entity's client. */
-    listPermissions: (entityId: string, clientId: string) => Promise<IamPermissionDefinition[]>;
+    /** Lists permission definitions registered for the entity's client, optionally narrowed. */
+    listPermissions: (entityId: string, clientId: string, filter?: IamPermissionFilter) => Promise<IamPermissionDefinition[]>;
     /**
      * Grants a permission to an end-user subject. With args.resources the grant is
      * resource-scoped (bound to those resource ids); without it the grant is project-wide.
@@ -127,11 +358,25 @@ export interface IamService extends InitializedService {
      * without it the whole grant is removed.
      */
     revokePermission: (entityId: string, clientId: string, profileId: string, permission: string, args?: IamGrantArgs) => Promise<void>;
+    /**
+     * Grants every permission a bundle selects to each subject, idempotently.
+     *
+     * Exists as its own operation rather than a loop over `grantPermission` because a backend that
+     * loads-mutates-saves a subject per call turns N permissions across M subjects into N·M writes and
+     * N·M lost-update windows on the same records. Collapsing to one read and one write per subject is
+     * also what makes re-running it genuinely idempotent.
+     *
+     * Returns what each subject now holds, not what changed.
+     */
+    grantBundle: (entityId: string, clientId: string, profileIds: string[], bundle: IamGrantBundle) => Promise<IamGrant[]>;
     /** Lists grants for the entity's client, optionally for a single subject. */
     listGrants: (entityId: string, clientId: string, profileId?: string) => Promise<IamGrant[]>;
     /**
-     * Lists the entity's end-users. With clientId, narrows to users holding at least
-     * one grant for that client (per-project view).
+     * Lists the entity's end-users. End-users are customer-wide — shared across every project of
+     * the entity — so `clientId` scopes the reported `grantCount` to one project's client and does
+     * **not** filter the set: a user who has authenticated against a project but holds no grant
+     * there is still that project's user, and the screen that manages grants is exactly where they
+     * must be visible.
      */
     listUsers: (entityId: string, clientId?: string) => Promise<IamUser[]>;
     /** Loads a single end-user by subject id, or null when absent. */

package/build/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/iam",
-  "version": "0.1.18-rc.2",
+  "version": "0.1.18-rc.21",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,14 +22,15 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.2",
-    "@owlmeans/context": "^0.1.18-rc.2",
-    "@owlmeans/error": "^0.1.18-rc.2",
-    "@owlmeans/oidc": "^0.1.18-rc.2"
+    "@owlmeans/auth": "^0.1.18-rc.14",
+    "@owlmeans/context": "^0.1.18-rc.13",
+    "@owlmeans/error": "^0.1.18-rc.13",
+    "@owlmeans/oidc": "^0.1.18-rc.26",
+    "@owlmeans/route": "^0.1.18-rc.14"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@types/bun": "^1.3.14",
+    "@types/bun": "^1.4.0",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },

package/src/consts.ts

@@ -4,3 +4,108 @@ export const IAM_MODE_KEYCLOAK = 'keycloak'
 export 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 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 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 const DEFAULT_GATE_PARAM_SOURCES: GateParamSource[] = [
+  GateParamSource.Params, GateParamSource.Query
+]
+
+/** Why a gate param is structurally wrong — a misconfiguration, not a failed authorization. */
+export 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 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 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 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 const IAM_AREAS = ['user', 'operator', 'admin'] as const
+
+export type IamArea = typeof IAM_AREAS[number]
+
+/** Separates the resource from the action in a permission name. TWO hyphens, never one. */
+export const PERMISSION_ACTION_SEPARATOR = '--'

package/src/errors.ts

@@ -36,6 +36,24 @@ export class IamGrantError extends IamError {
   }
 }
 
+/**
+ * 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 {
+  public static override typeName = `IamPermission${ResilientError.typeName}`
+
+  constructor(message = 'error') {
+    super(`permission:${message}`)
+    this.type = IamPermissionError.typeName
+  }
+}
+
 export class IamUnsupported extends IamError {
   public static override typeName = `IamUnsupported${ResilientError.typeName}`
 
@@ -58,5 +76,6 @@ ResilientError.registerErrorClass(IamError)
 ResilientError.registerErrorClass(IamClientError)
 ResilientError.registerErrorClass(IamResourceError)
 ResilientError.registerErrorClass(IamGrantError)
+ResilientError.registerErrorClass(IamPermissionError)
 ResilientError.registerErrorClass(IamUnsupported)
 ResilientError.registerErrorClass(IamUserError)

package/src/gate/index.ts

@@ -0,0 +1,3 @@
+export * from './param.js'
+export * from './resolve.js'
+export * from './validate.js'

package/src/gate/param.ts

@@ -0,0 +1,122 @@
+import {
+  RESOURCE_PARAM_SEPARATOR, RESOURCE_SOURCE_SEPARATOR, RESOURCE_PATH_SEPARATOR,
+  GateParamSource, GateParamErrorCode, DEFAULT_GATE_PARAM_SOURCES
+} from '../consts.js'
+import type { GateResourceSelector, GateParamProblem, ParsedGateParam } from '../types.js'
+
+const SOURCES = Object.values(GateParamSource) as string[]
+
+/**
+ * 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: string): GateResourceSelector | GateParamProblem => {
+  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 as GateParamSource,
+    path,
+    sources: [source as GateParamSource]
+  }
+}
+
+/**
+ * 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: string): ParsedGateParam => {
+  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: string,
+  selector?: string | { source?: GateParamSource, path: string[] }
+): string => {
+  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}`
+}