@owlmeans/iam 0.1.18-rc.9 → 0.1.18

package/build/utils.js

@@ -1,8 +1,17 @@
+/** The organization a set is bound to, when it is a claim set that kept its binding. */
+const boundTo = (set) => set.entitySlug;
 /**
  * True when any PermissionSet grants `permission`. An unscoped set (no resources)
  * satisfies a resourceId check too — a project-wide grant covers every resource.
+ *
+ * The organization follows the same rule the other way round, fail-closed: a set without a binding
+ * applies everywhere, a bound one only when `opts.entitySlug` names its organization. A relying
+ * party strips the binding from the sets of the organization a session acts in and drops every
+ * other bound set, so a bound set reaching a check is one that leaked — and it must not count
+ * merely because the caller did not say where the request acts.
  */
 export const hasPermission = (auth, permission, opts) => auth.permissions?.some(set => (opts?.scope == null || set.scope === opts.scope)
     && set.permissions[permission] === true
-    && (opts?.resourceId == null || set.resources == null || set.resources.includes(opts.resourceId))) ?? false;
+    && (opts?.resourceId == null || set.resources == null || set.resources.includes(opts.resourceId))
+    && (boundTo(set) == null || (opts?.entitySlug != null && boundTo(set) === opts.entitySlug))) ?? false;
 //# sourceMappingURL=utils.js.map

package/build/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,IAAmB,EACnB,UAAkB,EAClB,IAA2B,EAClB,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CACzC,CAAC,IAAI,EAAE,KAAK,IAAI,IAAI,IAAI,GAAG,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,CAAC;OAC9C,GAAG,CAAC,WAAW,CAAC,UAAU,CAAC,KAAK,IAAI;OACpC,CAAC,IAAI,EAAE,UAAU,IAAI,IAAI,IAAI,GAAG,CAAC,SAAS,IAAI,IAAI,IAAI,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAClG,IAAI,KAAK,CAAA"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAIA,wFAAwF;AACxF,MAAM,OAAO,GAAG,CAAC,GAAkB,EAAsB,EAAE,CAAE,GAA8B,CAAC,UAAU,CAAA;AAEtG;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,IAAmB,EACnB,UAAkB,EAClB,IAA2B,EAClB,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CACzC,CAAC,IAAI,EAAE,KAAK,IAAI,IAAI,IAAI,GAAG,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,CAAC;OAC9C,GAAG,CAAC,WAAW,CAAC,UAAU,CAAC,KAAK,IAAI;OACpC,CAAC,IAAI,EAAE,UAAU,IAAI,IAAI,IAAI,GAAG,CAAC,SAAS,IAAI,IAAI,IAAI,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;OAC9F,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,UAAU,IAAI,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,UAAU,CAAC,CAAC,CAC5F,IAAI,KAAK,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/iam",
-  "version": "0.1.18-rc.9",
+  "version": "0.1.18",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,14 +22,19 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.6",
-    "@owlmeans/context": "^0.1.18-rc.6",
-    "@owlmeans/error": "^0.1.18-rc.6",
-    "@owlmeans/oidc": "^0.1.18-rc.8"
+    "@owlmeans/auth": "^0.1.18",
+    "@owlmeans/context": "^0.1.18",
+    "@owlmeans/entrypoint": "^0.1.18",
+    "@owlmeans/error": "^0.1.18",
+    "@owlmeans/oidc": "^0.1.18",
+    "@owlmeans/route": "^0.1.18"
+  },
+  "peerDependencies": {
+    "ajv": "*"
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "workspace:*",
-    "@types/bun": "^1.3.14",
+    "@owlmeans/dep-config": "^0.1.18",
+    "@types/bun": "^1.4.2",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },

package/src/consts.local.ts

@@ -0,0 +1,26 @@
+export const TitleSchema = { type: 'string', minLength: 0, maxLength: 256 } as const
+
+/** A pairwise subject: `<clientId>:<digest>`. Never a path separator, never whitespace. */
+export const ProfileIdSchema = { type: 'string', minLength: 1, maxLength: 256, pattern: '^[^/\\s]+$' } as const
+
+export const PermissionNameSchema = { type: 'string', minLength: 1, maxLength: 128 } as const
+
+export const EmailSchema = { type: 'string', format: 'email', minLength: 3, maxLength: 254 } as const
+
+export const ResourcesSchema = {
+  type: 'array', items: { type: 'string', minLength: 1, maxLength: 128 }, maxItems: 256, nullable: true,
+} as const
+
+export const aliases = {
+  base: 'iam-runtime',
+  organization: { list: 'iam-runtime:organization:list', create: 'iam-runtime:organization:create', update: 'iam-runtime:organization:update' },
+  member: {
+    list: 'iam-runtime:member:list', add: 'iam-runtime:member:add',
+    update: 'iam-runtime:member:update', remove: 'iam-runtime:member:remove',
+  },
+  permission: { list: 'iam-runtime:permission:list' },
+  grant: { list: 'iam-runtime:grant:list', assign: 'iam-runtime:grant:assign', revoke: 'iam-runtime:grant:revoke' },
+} as const
+
+/** Keys a facet stand-in answers `undefined` for, so it is never mistaken for a thenable or a primitive. */
+export const INERT_KEYS = new Set<PropertyKey>(['then', 'toJSON'])

package/src/consts.ts

@@ -1,6 +1,246 @@
+import { EmailSchema, ProfileIdSchema, TitleSchema } from './consts.local.js'
+import type { IamRuntimeAck, IamRuntimeGrantQuery, IamRuntimeMemberInvite, IamRuntimeMemberParams, IamRuntimeOrganizationCreate, IamRuntimeOrganizationParams, IamRuntimeOrganizationUpdate } from './runtime/types.js'
+import type { JSONSchemaType } from 'ajv'
+import { EntitySlugValueSchema } from '@owlmeans/auth'
+
 export const DEFAULT_ALIAS = 'iam-service'
 
 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.
+ *
+ * Every subject, person or group, also has ONE blanket value of its own per binding: `true` grants,
+ * `false` RESTRICTS (it cuts what the subject would inherit from a default class, a group or a
+ * bundle), absent inherits. A `Blanket` or `All` revoke of a declared definition writes the
+ * restriction; `Inherit` takes the subject's own value back.
+ */
+export enum IamGrantMode {
+  Blanket = 'blanket',
+  Resources = 'resources',
+  /** Revoke-only: every form. Illegal on a grant. */
+  All = 'all',
+  /**
+   * Revoke-only: drop the subject's OWN blanket value in the binding — a grant or a restriction —
+   * so it holds exactly what it inherits. Resource-scoped sets are untouched. Illegal on a grant.
+   */
+  Inherit = 'inherit'
+}
+
+/** 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
+
+/** Separates the resource from the action in a permission name. TWO hyphens, never one. */
+export const PERMISSION_ACTION_SEPARATOR = '--'
+
+/**
+ * Who holds a permission without an explicit grant — a property of the DEFINITION, evaluated when
+ * claims are built and never written onto a profile.
+ *
+ * `User` is every signed-in subject of the client (an unbound, unmanaged `user`-area definition
+ * only); `Member` and `Owner` are every member / owner of the organization the subject acts in, so
+ * they require an `entityScoped` definition. A class default is a BLANKET set: `Owner` on a
+ * resource-scoped definition is its all-records form.
+ */
+export enum IamDefaultClass {
+  None = 'none',
+  User = 'user',
+  Member = 'member',
+  Owner = 'owner'
+}
+
+/** Why a subject holds a grant, as a listing reports it. */
+export enum IamGrantOrigin {
+  /** Written on the subject's own row. */
+  Direct = 'direct',
+  /** The definition's `defaultClass` covers the subject. */
+  Default = 'default',
+  /** Held by a group the subject is a member of — `IamGrant.through` names it. */
+  Group = 'group',
+  /** A group's own listing only: the names its bundles select; its own grants are `Direct`. */
+  Bundle = 'bundle'
+}
+
+/**
+ * The managed group `syncStaff` keeps in a client's owning organization: the owner's own staff,
+ * admitted to the client with the bundles the sync hands it. Its key, membership, bundles and
+ * existence are the synchronization's alone; its grants and restrictions are the operator's and
+ * survive every sync.
+ */
+export const IAM_MEMBERS_GROUP = 'members'
+
+/**
+ * The `profileId` of a credential that proves an e-mail address and identifies nobody yet: what the
+ * end-user sign-in hands the provider's finalizer, which then resolves the account itself. It carries
+ * no `entitySlug` — a proof bound to an organization is something else.
+ */
+export const IAM_EMAIL_PROOF = 'proof:email'
+
+/**
+ * The guard of the runtime IAM API (`makeIamRuntimeProtocols`). The serving process registers it: it
+ * admits a bearer access token the provider itself issued, and takes the client and the account from
+ * that token, never from the request.
+ */
+export const IAM_RUNTIME_GUARD = 'iam-runtime-guard'
+
+/** Where the runtime IAM API mounts under its service unless the declaration names another path. */
+export const IAM_RUNTIME_PATH = '/runtime'
+
+/**
+ * The runtime API's leaf paths under its base. One table so the declarations and a fetch-only client
+ * (a target's server, which binds no entrypoint of the provider's tree) cannot disagree on a segment.
+ */
+export const IAM_RUNTIME_ROUTES = {
+  organizations: '/organizations',
+  organization: '/organizations/:entitySlug',
+  members: '/organizations/:entitySlug/members',
+  member: '/organizations/:entitySlug/members/:profileId',
+  memberRemove: '/organizations/:entitySlug/members/:profileId/remove',
+  permissions: '/organizations/:entitySlug/permissions',
+  grants: '/organizations/:entitySlug/grants',
+  grantsRevoke: '/organizations/:entitySlug/grants/revoke',
+} as const
+
+export const IamRuntimeOrganizationCreateSchema: JSONSchemaType<IamRuntimeOrganizationCreate> = {
+  type: 'object',
+  properties: { title: { ...TitleSchema, nullable: true } },
+  required: [],
+  additionalProperties: false,
+}
+
+export const IamRuntimeOrganizationUpdateSchema: JSONSchemaType<IamRuntimeOrganizationUpdate> = {
+  type: 'object',
+  properties: { title: { ...TitleSchema } },
+  required: ['title'],
+  additionalProperties: false,
+}
+
+export const IamRuntimeOrganizationParamsSchema: JSONSchemaType<IamRuntimeOrganizationParams> = {
+  type: 'object',
+  properties: { entitySlug: { ...EntitySlugValueSchema } },
+  required: ['entitySlug'],
+  additionalProperties: false,
+}
+
+export const IamRuntimeMemberInviteSchema: JSONSchemaType<IamRuntimeMemberInvite> = {
+  type: 'object',
+  properties: {
+    email: { ...EmailSchema },
+    name: { ...TitleSchema, nullable: true },
+    owner: { type: 'boolean', nullable: true },
+  },
+  required: ['email'],
+  additionalProperties: false,
+}
+
+export const IamRuntimeMemberParamsSchema: JSONSchemaType<IamRuntimeMemberParams> = {
+  type: 'object',
+  properties: {
+    entitySlug: { ...EntitySlugValueSchema },
+    profileId: { ...ProfileIdSchema },
+  },
+  required: ['entitySlug', 'profileId'],
+  additionalProperties: false,
+}
+
+export const IamRuntimeGrantQuerySchema: JSONSchemaType<IamRuntimeGrantQuery> = {
+  type: 'object',
+  properties: { profileId: { ...ProfileIdSchema, nullable: true } },
+  required: [],
+  additionalProperties: false,
+}
+
+export const IamRuntimeAckSchema: JSONSchemaType<IamRuntimeAck> = {
+  type: 'object',
+  properties: { ok: { type: 'boolean' } },
+  required: ['ok'],
+  additionalProperties: false,
+}

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}`
 
@@ -54,9 +72,35 @@ export class IamUserError extends IamError {
   }
 }
 
+/**
+ * A refusal about an organization or a membership in it — an unknown organization, the last owner,
+ * the membership cap.
+ */
+export class IamOrganizationError extends IamError {
+  public static override typeName = `IamOrganization${ResilientError.typeName}`
+
+  constructor(message = 'error') {
+    super(`organization:${message}`)
+    this.type = IamOrganizationError.typeName
+  }
+}
+
+/** A refusal about a group: an unknown key, a managed group written by an operator, another app's group. */
+export class IamGroupError extends IamError {
+  public static override typeName = `IamGroup${ResilientError.typeName}`
+
+  constructor(message = 'error') {
+    super(`group:${message}`)
+    this.type = IamGroupError.typeName
+  }
+}
+
 ResilientError.registerErrorClass(IamError)
 ResilientError.registerErrorClass(IamClientError)
 ResilientError.registerErrorClass(IamResourceError)
 ResilientError.registerErrorClass(IamGrantError)
+ResilientError.registerErrorClass(IamPermissionError)
 ResilientError.registerErrorClass(IamUnsupported)
 ResilientError.registerErrorClass(IamUserError)
+ResilientError.registerErrorClass(IamOrganizationError)
+ResilientError.registerErrorClass(IamGroupError)

package/src/facet.ts

@@ -0,0 +1,17 @@
+import { IamUnsupported } from './errors.js'
+import { INERT_KEYS } from './consts.local.js'
+
+/**
+ * A facet a backend cannot provide: every method throws `IamUnsupported(what)`.
+ *
+ * It throws SYNCHRONOUSLY, because a facet may carry synchronous methods (`subjects.identify`) and a
+ * rejected promise would hand those a value of the wrong type; an awaited call rejects the same way
+ * either way. Caller code turns the refusal into a fallback, exactly as for any other unsupported
+ * operation.
+ */
+export const unsupportedFacet = <T extends object>(what: string): T =>
+  new Proxy(Object.freeze({}) as T, {
+    get: (_, key) => typeof key === 'symbol' || INERT_KEYS.has(key)
+      ? undefined
+      : () => { throw new IamUnsupported(what) },
+  })

package/src/gate/consts.local.ts

@@ -0,0 +1,3 @@
+import { GateParamSource } from '../consts.js'
+
+export const SOURCES = Object.values(GateParamSource) as string[]

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,108 @@
+import {
+  RESOURCE_PARAM_SEPARATOR, RESOURCE_SOURCE_SEPARATOR, RESOURCE_PATH_SEPARATOR,
+  GateParamSource, GateParamErrorCode, DEFAULT_GATE_PARAM_SOURCES
+} from '../consts.js'
+import type { GateParamHelper, GateResourceSelector, GateParamProblem, ParsedGateParam } from './types.js'
+import { SOURCES } from './consts.local.js'
+
+export const createGateParamHelper = (): GateParamHelper => {
+  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]
+    }
+  }
+
+  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
+    }
+  }
+
+  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}`
+  }
+
+  return { parseGateSelector, parseGateParam, formatGateParam }
+}
+
+export const gateParamHelper = createGateParamHelper()
+
+/** @deprecated compat:factory-refactor — use `gateParamHelper.parseGateParam(…)` */
+export const parseGateParam = (param: string): ParsedGateParam => gateParamHelper.parseGateParam(param)

package/src/gate/resolve.ts

@@ -0,0 +1,114 @@
+import { GateParamSource, GateResolutionFailure } from '../consts.js'
+import type { GateRequestLike, GateResourceSelector, GateResourceResolution } from './types.js'
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  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: unknown): string | null => {
+  switch (typeof value) {
+    case 'string':
+      return value
+    case 'number':
+    case 'boolean':
+    case 'bigint':
+      return `${value}`
+    default:
+      return null
+  }
+}
+
+const sourceOf = (req: GateRequestLike, source: GateParamSource): unknown => {
+  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: unknown, path: string[], source: GateParamSource
+): { value?: unknown, reason?: GateResolutionFailure } => {
+  if (!isRecord(container)) {
+    return { reason: GateResolutionFailure.SourceMissing }
+  }
+
+  let cursor: unknown = 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: GateRequestLike, selector: GateResourceSelector
+): GateResourceResolution => {
+  let reason: GateResolutionFailure = 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 }
+}

package/src/gate/types.local.ts

@@ -0,0 +1,4 @@
+export interface SchemaLike {
+  properties?: Record<string, unknown>
+  additionalProperties?: unknown
+}