@owlmeans/iam 0.1.18-rc.8 → 0.1.18

package/src/gate/types.ts

@@ -0,0 +1,117 @@
+import type { GateParamSource, GateParamErrorCode, GateResolutionFailure } 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
+}
+
+/** The gate-param grammar: `<permission>@<selector>` read, written and taken apart. */
+export interface GateParamHelper {
+  /**
+   * 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.
+   */
+  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.
+   */
+  parseGateParam: (param: string) => ParsedGateParam
+  /** Compose a gate param. The inverse of `parseGateParam` for every selector it accepts. */
+  formatGateParam: (
+    permission: string,
+    selector?: string | { source?: GateParamSource, path: string[] }
+  ) => string
+}
+
+/** Gate params checked against the entrypoint that declares them. */
+export interface GateValidationHelper {
+  /** The `:name` segments of a route template. */
+  routeParamsOf: (path: string) => string[]
+  /**
+   * Check gate params against what their entrypoint declares.
+   *
+   * Reports only what is provable from the declaration itself. Anything that would need a guess is
+   * left alone: a check that fires on correct code stops being read.
+   *
+   * Meant to run where a mistake can still be fixed — while code is being generated, or once per alias
+   * as a diagnostic. It must never decide a request: with `some()` semantics across params, one
+   * malformed sibling must not be able to refuse a legitimately passing one.
+   */
+  validateGateParams: (params: string[], audit?: GateParamAudit) => GateParamIssue[]
+}

package/src/gate/validate.ts

@@ -0,0 +1,123 @@
+import { normalizePath, SEP, PARAM } from '@owlmeans/route'
+import { GateParamSource, GateParamErrorCode } from '../consts.js'
+import type { GateParamAudit, GateParamIssue, GateResourceSelector, GateValidationHelper } from './types.js'
+import { gateParamHelper } from './param.js'
+import type { SchemaLike } from './types.local.js'
+
+export const createGateValidationHelper = (): GateValidationHelper => {
+  const routeParamsOf = (path: string): string[] =>
+    normalizePath(path).split(SEP)
+      .filter(segment => segment.startsWith(PARAM))
+      .map(segment => segment.slice(PARAM.length))
+
+  /**
+   * Whether a key can survive validation to reach the gate.
+   *
+   * The server compiles entrypoint filters with AJV's `removeAdditional`, which strips an undeclared
+   * key BEFORE the handler — and therefore before the gate — runs. So a selector naming a key the
+   * filter does not declare denies every request, with a clean build and nothing logged.
+   *
+   * The `additionalProperties === false` qualifier is what makes this check usable rather than noise:
+   * AJV only strips when a schema says so. An entrypoint that declares no filter for a source strips
+   * nothing, and reporting those would fire on nearly every endpoint and be ignored within a week.
+   */
+  const unreachable = (schema: object | undefined, key: string): boolean => {
+    if (schema == null) {
+      return false
+    }
+
+    const { properties, additionalProperties } = schema as SchemaLike
+    if (additionalProperties !== false) {
+      return false
+    }
+
+    return properties == null || !(key in properties)
+  }
+
+  const filterFor = (audit: GateParamAudit, source: GateParamSource): object | undefined => {
+    switch (source) {
+      case GateParamSource.Query: return audit.filter?.query
+      case GateParamSource.Body: return audit.filter?.body
+      case GateParamSource.Headers: return audit.filter?.headers
+      case GateParamSource.Params: return audit.filter?.params
+      case GateParamSource.Auth: return undefined
+    }
+  }
+
+  const auditSelector = (
+    audit: GateParamAudit, selector: GateResourceSelector
+  ): Omit<GateParamIssue, 'param'> | null => {
+    const key = selector.path[0]
+    if (key == null) {
+      return null
+    }
+
+    // The bare form searches route params first and the query second, so it is only provably wrong
+    // when BOTH are impossible. A declared route param settles it; otherwise fall through to the
+    // query check below, which only fires on an explicitly closed schema.
+    const routeParams = audit.routeParams
+      ?? (audit.routePath != null ? routeParamsOf(audit.routePath) : undefined)
+
+    if (selector.source == null) {
+      if (routeParams?.includes(key) === true) {
+        return null
+      }
+      if (unreachable(audit.filter?.query, key) && unreachable(audit.filter?.params, key)) {
+        return {
+          code: GateParamErrorCode.UnknownRouteParam,
+          detail: `"${key}" is not a route param of "${audit.routePath ?? '?'}"`
+            + ' and is declared by neither the params nor the query filter'
+        }
+      }
+      return null
+    }
+
+    if (selector.source === GateParamSource.Params) {
+      if (routeParams != null && !routeParams.includes(key) && unreachable(audit.filter?.params, key)) {
+        return {
+          code: GateParamErrorCode.UnknownRouteParam,
+          detail: `"${key}" is not a route param of "${audit.routePath ?? '?'}"`
+        }
+      }
+      return null
+    }
+
+    if (unreachable(filterFor(audit, selector.source), key)) {
+      return {
+        code: GateParamErrorCode.UnreachableKey,
+        detail: `the ${selector.source} filter declares no "${key}" and forbids additional properties,`
+          + ' so it is removed by validation before the gate can read it'
+      }
+    }
+
+    return null
+  }
+
+  const validateGateParams = (params: string[], audit?: GateParamAudit): GateParamIssue[] => {
+    const issues: GateParamIssue[] = []
+
+    for (const param of params) {
+      const parsed = gateParamHelper.parseGateParam(param)
+
+      if (parsed.error != null) {
+        issues.push({ param, code: parsed.error.code, detail: parsed.error.detail })
+        continue
+      }
+
+      if (parsed.resource == null || audit == null) {
+        continue
+      }
+
+      const issue = auditSelector(audit, parsed.resource)
+      if (issue != null) {
+        issues.push({ param, ...issue })
+      }
+    }
+
+    return issues
+  }
+
+  return { routeParamsOf, validateGateParams }
+}
+
+export const gateValidationHelper = createGateValidationHelper()

package/src/index.ts

@@ -1,4 +1,13 @@
 export type * from './types.js'
+export type * from './gate/types.js'
+export type * from './permission/types.js'
+export type * from './runtime/types.js'
+export type * from './utils/types.js'
 export * from './consts.js'
 export * from './errors.js'
 export * from './utils.js'
+export * from './facet.js'
+export * from './gate/index.js'
+export * from './permission.js'
+export * from './runtime.js'
+export { IamRuntimeOrganizationSchema, IamRuntimeOrganizationListSchema, IamRuntimeMemberSchema, IamRuntimeMemberListSchema, IamRuntimeMemberUpdateSchema, IamRuntimePermissionSchema, IamRuntimePermissionListSchema, IamRuntimeGrantSchema, IamRuntimeGrantListSchema, IamRuntimeGrantRequestSchema } from './schemas.js'

package/src/permission/types.ts

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

package/src/permission.ts

@@ -0,0 +1,48 @@
+import { PERMISSION_ACTION_SEPARATOR, RESOURCE_PARAM_SEPARATOR, GateParamErrorCode } from './consts.js'
+import type { ParsedPermissionName, PermissionNameHelper } from './permission/types.js'
+
+export const createPermissionNameHelper = (): PermissionNameHelper => {
+  const parsePermissionName = (name: string): ParsedPermissionName => {
+    const problem = name.includes(RESOURCE_PARAM_SEPARATOR)
+      ? {
+        code: GateParamErrorCode.UnreachableKey,
+        detail: `"${name}" carries a gate selector; "${RESOURCE_PARAM_SEPARATOR}" is never part of a`
+          + ' permission name, and nothing ever looks up a name that contains one'
+      }
+      : undefined
+
+    const idx = name.indexOf(PERMISSION_ACTION_SEPARATOR)
+    if (idx < 0) {
+      return { name, resource: name, ...(problem != null ? { problem } : {}) }
+    }
+
+    const action = name.slice(idx + PERMISSION_ACTION_SEPARATOR.length)
+
+    return {
+      name,
+      resource: name.slice(0, idx),
+      ...(action !== '' ? { action } : {}),
+      ...(problem != null ? { problem } : {})
+    }
+  }
+
+  const composePermissionName = (
+    parts: { resource: string, action?: string }
+  ): string => parts.action == null || parts.action === ''
+    ? parts.resource
+    : `${parts.resource}${PERMISSION_ACTION_SEPARATOR}${parts.action}`
+
+  const isPermissionName = (value: string): boolean =>
+    value !== '' && !value.includes(RESOURCE_PARAM_SEPARATOR)
+
+  return { parsePermissionName, composePermissionName, isPermissionName }
+}
+
+export const permissionNameHelper = createPermissionNameHelper()
+
+/** @deprecated compat:factory-refactor — use `permissionNameHelper.parsePermissionName(…)` */
+export const parsePermissionName = (name: string): ParsedPermissionName =>
+  permissionNameHelper.parsePermissionName(name)
+
+/** @deprecated compat:factory-refactor — use `permissionNameHelper.isPermissionName(…)` */
+export const isPermissionName = (value: string): boolean => permissionNameHelper.isPermissionName(value)

package/src/runtime/types.ts

@@ -0,0 +1,107 @@
+import type { IamDefaultClass, IamGrantMode, IamGrantOrigin } from '../consts.js'
+
+/** One organization of the calling subject. */
+export interface IamRuntimeOrganization {
+  entitySlug: string
+  title?: string
+  owner: boolean
+  groups?: string[]
+  home?: boolean
+}
+
+export interface IamRuntimeOrganizationList {
+  items: IamRuntimeOrganization[]
+}
+
+export interface IamRuntimeOrganizationCreate {
+  title?: string
+}
+
+export interface IamRuntimeOrganizationUpdate {
+  title: string
+}
+
+export interface IamRuntimeOrganizationParams {
+  entitySlug: string
+}
+
+export interface IamRuntimeMember {
+  profileId: string
+  email?: string
+  name?: string
+  owner: boolean
+  groups: string[]
+  managed?: boolean
+}
+
+export interface IamRuntimeMemberList {
+  items: IamRuntimeMember[]
+}
+
+/** Find-or-create by e-mail; adding someone twice answers the same member. */
+export interface IamRuntimeMemberInvite {
+  email: string
+  name?: string
+  owner?: boolean
+}
+
+export interface IamRuntimeMemberUpdate {
+  owner?: boolean
+  groups?: string[]
+}
+
+export interface IamRuntimeMemberParams {
+  entitySlug: string
+  profileId: string
+}
+
+/** A definition of the calling client that can be granted in an organization. */
+export interface IamRuntimePermission {
+  name: string
+  title?: string
+  area?: string
+  resourceScoped?: boolean
+  managed?: boolean
+  defaultClass?: IamDefaultClass
+}
+
+export interface IamRuntimePermissionList {
+  items: IamRuntimePermission[]
+}
+
+/** A grant of a member in the organization; `through` names the group a `Group`-origin one comes from. */
+export interface IamRuntimeGrant {
+  profileId: string
+  permission: string
+  resources?: string[]
+  mode?: IamGrantMode
+  origin?: IamGrantOrigin
+  through?: string
+}
+
+export interface IamRuntimeGrantList {
+  items: IamRuntimeGrant[]
+}
+
+export interface IamRuntimeGrantQuery {
+  profileId?: string
+}
+
+/** Grant or revoke. The binding is the path's organization — the body cannot name another. */
+export interface IamRuntimeGrantRequest {
+  profileId: string
+  permission: string
+  resources?: string[]
+  mode?: IamGrantMode
+}
+
+export interface IamRuntimeAck {
+  ok: boolean
+}
+
+export interface IamRuntimeProtocolOptions {
+  /** The service alias that serves the API — every route, the base included, is pinned to it. */
+  service: string
+  /** The base path under that service. Defaults to `IAM_RUNTIME_PATH`. */
+  path?: string
+}

package/src/runtime.ts

@@ -0,0 +1,142 @@
+import { contract, openProtocol, protocol, typed, type EntrypointProtocol, type OpenRequest, type OpenValue } from '@owlmeans/entrypoint'
+import { backend, route, RouteMethod } from '@owlmeans/route'
+import { IAM_RUNTIME_GUARD, IAM_RUNTIME_PATH, IAM_RUNTIME_ROUTES, IamRuntimeAckSchema, IamRuntimeGrantQuerySchema, IamRuntimeMemberInviteSchema, IamRuntimeMemberParamsSchema, IamRuntimeOrganizationCreateSchema, IamRuntimeOrganizationParamsSchema, IamRuntimeOrganizationUpdateSchema } from './consts.js'
+import { aliases } from './consts.local.js'
+import type { IamRuntimeAck, IamRuntimeGrant, IamRuntimeGrantList, IamRuntimeGrantQuery, IamRuntimeGrantRequest, IamRuntimeMember, IamRuntimeMemberInvite, IamRuntimeMemberList, IamRuntimeMemberParams, IamRuntimeMemberUpdate, IamRuntimeOrganization, IamRuntimeOrganizationCreate, IamRuntimeOrganizationList, IamRuntimeOrganizationParams, IamRuntimeOrganizationUpdate, IamRuntimePermissionList, IamRuntimeProtocolOptions } from './runtime/types.js'
+import { IamRuntimeOrganizationSchema, IamRuntimeOrganizationListSchema, IamRuntimeMemberSchema, IamRuntimeMemberListSchema, IamRuntimeMemberUpdateSchema, IamRuntimePermissionListSchema, IamRuntimeGrantSchema, IamRuntimeGrantListSchema, IamRuntimeGrantRequestSchema } from './schemas.js'
+
+// ---------------------------------------------------------------------------------------------
+// Schemas — closed throughout: the server's AJV strips an undeclared key silently, so a field a
+// caller sends and the schema omits would vanish without an error.
+// ---------------------------------------------------------------------------------------------
+// ---------------------------------------------------------------------------------------------
+// The protocol tree
+// ---------------------------------------------------------------------------------------------
+
+// Kept as a type: the inferred shape of the declareRuntime protocol tree, so it cannot leave this file.
+export type IamRuntimeProtocols = ReturnType<typeof declareRuntime>
+
+const declareRuntime = (opts: IamRuntimeProtocolOptions) => {
+  const { service } = opts
+  const base: EntrypointProtocol<OpenRequest, OpenValue> = openProtocol(
+    route(aliases.base, opts.path ?? IAM_RUNTIME_PATH, backend({ service })),
+    { guards: IAM_RUNTIME_GUARD },
+  )
+  // A route's service is never inherited from its parent, so each leaf names it too: a leaf left
+  // unpinned would be mounted by every process that happens to bind the tree.
+  const leaf = (alias: string, path: string, method: RouteMethod) =>
+    route(alias, path, backend({ parent: base, service }, method))
+
+  return Object.freeze({
+    base,
+
+    organizations: Object.freeze({
+      /** Any subject: its own organizations. */
+      list: protocol(
+        leaf(aliases.organization.list, IAM_RUNTIME_ROUTES.organizations, RouteMethod.GET),
+        contract(typed<IamRuntimeOrganizationList>(IamRuntimeOrganizationListSchema)),
+      ),
+      /** Any subject of a tenanted client; the caller becomes its owner. */
+      create: protocol(
+        leaf(aliases.organization.create, IAM_RUNTIME_ROUTES.organizations, RouteMethod.POST),
+        contract.request(
+          { body: typed<IamRuntimeOrganizationCreate>(IamRuntimeOrganizationCreateSchema) },
+          typed<IamRuntimeOrganization>(IamRuntimeOrganizationSchema),
+        ),
+      ),
+      /** Owner. */
+      update: protocol(
+        leaf(aliases.organization.update, IAM_RUNTIME_ROUTES.organization, RouteMethod.POST),
+        contract.request({
+          params: typed<IamRuntimeOrganizationParams>(IamRuntimeOrganizationParamsSchema),
+          body: typed<IamRuntimeOrganizationUpdate>(IamRuntimeOrganizationUpdateSchema),
+        }, typed<IamRuntimeOrganization>(IamRuntimeOrganizationSchema)),
+      ),
+    }),
+
+    members: Object.freeze({
+      /** Member. */
+      list: protocol(
+        leaf(aliases.member.list, IAM_RUNTIME_ROUTES.members, RouteMethod.GET),
+        contract.request(
+          { params: typed<IamRuntimeOrganizationParams>(IamRuntimeOrganizationParamsSchema) },
+          typed<IamRuntimeMemberList>(IamRuntimeMemberListSchema),
+        ),
+      ),
+      /** Owner. Find-or-create by e-mail, idempotent. */
+      add: protocol(
+        leaf(aliases.member.add, IAM_RUNTIME_ROUTES.members, RouteMethod.POST),
+        contract.request({
+          params: typed<IamRuntimeOrganizationParams>(IamRuntimeOrganizationParamsSchema),
+          body: typed<IamRuntimeMemberInvite>(IamRuntimeMemberInviteSchema),
+        }, typed<IamRuntimeMember>(IamRuntimeMemberSchema)),
+      ),
+      /** Owner. */
+      update: protocol(
+        leaf(aliases.member.update, IAM_RUNTIME_ROUTES.member, RouteMethod.POST),
+        contract.request({
+          params: typed<IamRuntimeMemberParams>(IamRuntimeMemberParamsSchema),
+          body: typed<IamRuntimeMemberUpdate>(IamRuntimeMemberUpdateSchema),
+        }, typed<IamRuntimeMember>(IamRuntimeMemberSchema)),
+      ),
+      /** Owner, or the member itself. */
+      remove: protocol(
+        leaf(aliases.member.remove, IAM_RUNTIME_ROUTES.memberRemove, RouteMethod.POST),
+        contract.request(
+          { params: typed<IamRuntimeMemberParams>(IamRuntimeMemberParamsSchema) },
+          typed<IamRuntimeAck>(IamRuntimeAckSchema),
+        ),
+      ),
+    }),
+
+    permissions: Object.freeze({
+      /** Member. */
+      list: protocol(
+        leaf(aliases.permission.list, IAM_RUNTIME_ROUTES.permissions, RouteMethod.GET),
+        contract.request(
+          { params: typed<IamRuntimeOrganizationParams>(IamRuntimeOrganizationParamsSchema) },
+          typed<IamRuntimePermissionList>(IamRuntimePermissionListSchema),
+        ),
+      ),
+    }),
+
+    grants: Object.freeze({
+      /** Owner. */
+      list: protocol(
+        leaf(aliases.grant.list, IAM_RUNTIME_ROUTES.grants, RouteMethod.GET),
+        contract.request({
+          params: typed<IamRuntimeOrganizationParams>(IamRuntimeOrganizationParamsSchema),
+          query: typed<IamRuntimeGrantQuery>(IamRuntimeGrantQuerySchema),
+        }, typed<IamRuntimeGrantList>(IamRuntimeGrantListSchema)),
+      ),
+      /** Owner. */
+      assign: protocol(
+        leaf(aliases.grant.assign, IAM_RUNTIME_ROUTES.grants, RouteMethod.POST),
+        contract.request({
+          params: typed<IamRuntimeOrganizationParams>(IamRuntimeOrganizationParamsSchema),
+          body: typed<IamRuntimeGrantRequest>(IamRuntimeGrantRequestSchema),
+        }, typed<IamRuntimeGrant>(IamRuntimeGrantSchema)),
+      ),
+      /** Owner. */
+      revoke: protocol(
+        leaf(aliases.grant.revoke, IAM_RUNTIME_ROUTES.grantsRevoke, RouteMethod.POST),
+        contract.request({
+          params: typed<IamRuntimeOrganizationParams>(IamRuntimeOrganizationParamsSchema),
+          body: typed<IamRuntimeGrantRequest>(IamRuntimeGrantRequestSchema),
+        }, typed<IamRuntimeAck>(IamRuntimeAckSchema)),
+      ),
+    }),
+  })
+}
+
+/**
+ * Declare the runtime IAM API — the provider-side surface a tenanted client's server calls on behalf
+ * of its signed-in subject: the subject's organizations, their members, the grantable definitions
+ * and the grants inside one organization.
+ *
+ * Every leaf hangs under ONE base carrying `IAM_RUNTIME_GUARD`, so none can be reached without the
+ * provider's own access token; the caller's client and account come from that token, the
+ * organization from the path. Owner/member checks, the tenancy-config gate and the write rules are
+ * the serving process's — a declaration decides nothing.
+ */
+export const makeIamRuntimeProtocols = (opts: IamRuntimeProtocolOptions): IamRuntimeProtocols => declareRuntime(opts)