@owlmeans/iam 0.1.18-rc.8 → 0.1.18

package/src/utils.ts

@@ -1,15 +1,19 @@
-import type { Authorization } from '@owlmeans/auth'
+import type { Authorization, PermissionSet } from '@owlmeans/auth'
+import type { OidcPermissionSetClaim } from '@owlmeans/oidc'
+import type { HasPermissionOptions } from './utils/types.js'
 
-export interface HasPermissionOptions {
-  /** Restrict the check to PermissionSets of this scope (the project's clientId). */
-  scope?: string
-  /** Resource-scoped check: the set must list this id — unless the set itself is unscoped. */
-  resourceId?: string
-}
+/** The organization a set is bound to, when it is a claim set that kept its binding. */
+const boundTo = (set: PermissionSet): string | undefined => (set as OidcPermissionSetClaim).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: Authorization,
@@ -19,4 +23,5 @@ export const hasPermission = (
   (opts?.scope == null || set.scope === opts.scope)
   && set.permissions[permission] === true
   && (opts?.resourceId == null || set.resources == null || set.resources.includes(opts.resourceId))
+  && (boundTo(set) == null || (opts?.entitySlug != null && boundTo(set) === opts.entitySlug))
 ) ?? false

package/tests/gate-param.spec.ts

@@ -0,0 +1,233 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  gateParamHelper, gateValidationHelper, resolveGateResource, permissionNameHelper,
+  GateParamSource, GateParamErrorCode, GateResolutionFailure
+} from '../src/index.js'
+import type { GateResourceSelector } from '../src/index.js'
+
+const selectorOf = (param: string): GateResourceSelector => {
+  const resource = gateParamHelper.parseGateParam(param).resource
+  if (resource == null) {
+    throw new Error(`"${param}" produced no selector`)
+  }
+  return resource
+}
+
+describe('gate params — the grammar', () => {
+  test('an unscoped param is the permission and nothing else', () => {
+    const parsed = gateParamHelper.parseGateParam('enquiry--modify')
+    expect(parsed.permission).toBe('enquiry--modify')
+    expect(parsed.resource).toBeUndefined()
+    expect(parsed.error).toBeUndefined()
+  })
+
+  test('the bare form stays FLAT and keeps searching params then query', () => {
+    const parsed = gateParamHelper.parseGateParam('enquiry--view@enquiryId')
+    expect(parsed.permission).toBe('enquiry--view')
+    expect(parsed.resourceParam).toBe('enquiryId')
+    expect(parsed.resource?.path).toEqual(['enquiryId'])
+    expect(parsed.resource?.sources).toEqual([GateParamSource.Params, GateParamSource.Query])
+  })
+
+  /**
+   * A query key may legally contain a dot, so splitting the bare form on one would change the
+   * meaning of selectors already deployed inside customer projects.
+   */
+  test('a dot in the bare form is part of the key, never a path', () => {
+    expect(selectorOf('a--view@filter.orgId').path).toEqual(['filter.orgId'])
+  })
+
+  test('a qualified selector names its source and walks a path', () => {
+    const selector = selectorOf('order--modify@body:order.id')
+    expect(selector.source).toBe(GateParamSource.Body)
+    expect(selector.path).toEqual(['order', 'id'])
+    expect(selector.sources).toEqual([GateParamSource.Body])
+  })
+
+  test('the qualified form does not populate the deprecated flat field', () => {
+    expect(gateParamHelper.parseGateParam('order--modify@body:order.id').resourceParam).toBeUndefined()
+  })
+
+  test('an unknown source is reported rather than treated as a key', () => {
+    const parsed = gateParamHelper.parseGateParam('a--view@cookies:sid')
+    expect(parsed.error?.code).toBe(GateParamErrorCode.UnknownSource)
+    expect(parsed.resource).toBeUndefined()
+  })
+
+  test.each([
+    ['a--view@', GateParamErrorCode.EmptySelector],
+    ['a--view@body:', GateParamErrorCode.EmptySelector],
+    ['a--view@body:order..id', GateParamErrorCode.EmptySegment],
+  ])('%s is refused as %s', (param, code) => {
+    expect(gateParamHelper.parseGateParam(param).error?.code).toBe(code)
+  })
+
+  test('format is the inverse of parse for both forms', () => {
+    for (const param of ['a--view', 'a--view@id', 'a--view@body:order.id', 'a--view@auth:profileId']) {
+      const parsed = gateParamHelper.parseGateParam(param)
+      expect(gateParamHelper.formatGateParam(parsed.permission, parsed.resource)).toBe(param)
+    }
+  })
+
+  test('parseGateSelector reports a problem instead of throwing', () => {
+    const result = gateParamHelper.parseGateSelector('')
+    expect('code' in result).toBe(true)
+  })
+})
+
+describe('gate params — resolution', () => {
+  const req = {
+    params: { enquiryId: 'e-1', n: 7 },
+    query: { tenant: 't-9', filter: { orgId: 'o-3' } },
+    body: { order: { id: 'o-77' }, nested: { deep: { value: 'v' } } },
+    headers: { 'x-tenant-id': 'h-1', 'x-many': ['a', 'b'], 'x-one': ['solo'] },
+    auth: { profileId: 'p-1', entityId: 'ent-1' }
+  }
+
+  test('the bare form prefers a route param over a query key of the same name', () => {
+    const ambiguous = { ...req, query: { ...req.query, enquiryId: 'from-query' } }
+    expect(resolveGateResource(ambiguous, selectorOf('a--view@enquiryId')).id).toBe('e-1')
+  })
+
+  test('the bare form still falls back to the query — deployed apps depend on it', () => {
+    const resolution = resolveGateResource(req, selectorOf('a--view@tenant'))
+    expect(resolution.id).toBe('t-9')
+    expect(resolution.from).toBe(GateParamSource.Query)
+  })
+
+  test.each([
+    ['a--view@body:order.id', 'o-77'],
+    ['a--view@body:nested.deep.value', 'v'],
+    ['a--view@query:filter.orgId', 'o-3'],
+    ['a--view@auth:profileId', 'p-1'],
+    ['a--view@headers:x-tenant-id', 'h-1'],
+  ])('%s resolves to %s', (param, expected) => {
+    expect(resolveGateResource(req, selectorOf(param)).id).toBe(expected)
+  })
+
+  test('a header name resolves case-insensitively', () => {
+    expect(resolveGateResource(req, selectorOf('a--view@headers:X-Tenant-Id')).id).toBe('h-1')
+  })
+
+  test('a single-element header array unwraps', () => {
+    expect(resolveGateResource(req, selectorOf('a--view@headers:x-one')).id).toBe('solo')
+  })
+
+  /** Picking one of several repeated headers would be an authorization decision made by accident. */
+  test('a repeated header is refused, never silently narrowed', () => {
+    const resolution = resolveGateResource(req, selectorOf('a--view@headers:x-many'))
+    expect(resolution.id).toBeUndefined()
+    expect(resolution.reason).toBe(GateResolutionFailure.NotScalar)
+  })
+
+  test('a non-string scalar stringifies, preserving what AJV coercion produces', () => {
+    expect(resolveGateResource(req, selectorOf('a--view@params:n')).id).toBe('7')
+  })
+
+  test('an object is refused rather than stringified to "[object Object]"', () => {
+    const resolution = resolveGateResource(req, selectorOf('a--view@body:order'))
+    expect(resolution.reason).toBe(GateResolutionFailure.NotScalar)
+  })
+
+  test('a missing path reports why nothing was found', () => {
+    expect(resolveGateResource(req, selectorOf('a--view@body:absent')).reason)
+      .toBe(GateResolutionFailure.NotProvided)
+  })
+
+  test('an absent source is distinguished from an absent key', () => {
+    expect(resolveGateResource({}, selectorOf('a--view@body:order.id')).reason)
+      .toBe(GateResolutionFailure.SourceMissing)
+  })
+})
+
+describe('gate params — validation against the declaration', () => {
+  test('a bare selector naming a real route param passes', () => {
+    expect(gateValidationHelper.validateGateParams(['a--view@enquiryId'], { routePath: '/enquiries/:enquiryId' }))
+      .toEqual([])
+  })
+
+  /**
+   * The bare form searches the query too, and an entrypoint that declares no query filter strips
+   * nothing — so an unknown name is only provably wrong when both routes to it are closed.
+   */
+  test('a bare selector on an entrypoint with no query filter is left alone', () => {
+    expect(gateValidationHelper.validateGateParams(['a--view@whatever'], { routePath: '/enquiries/:enquiryId' }))
+      .toEqual([])
+  })
+
+  test('a bare selector is reported once BOTH the params and query filters close the door', () => {
+    const issues = gateValidationHelper.validateGateParams(['a--view@whatever'], {
+      routePath: '/enquiries/:enquiryId',
+      filter: {
+        params: { properties: { enquiryId: {} }, additionalProperties: false },
+        query: { properties: { page: {} }, additionalProperties: false }
+      }
+    })
+    expect(issues[0]?.code).toBe(GateParamErrorCode.UnknownRouteParam)
+  })
+
+  /**
+   * `removeAdditional` strips an undeclared key before the gate runs, so the endpoint denies every
+   * request with a clean build and nothing logged. That is the whole reason this check exists.
+   */
+  test('a body selector the filter forbids is reported as unreachable', () => {
+    const issues = gateValidationHelper.validateGateParams(['a--modify@body:orderId'], {
+      routePath: '/orders/transfer',
+      filter: { body: { properties: { amount: {} }, additionalProperties: false } }
+    })
+    expect(issues[0]?.code).toBe(GateParamErrorCode.UnreachableKey)
+  })
+
+  test('a body selector the filter declares passes', () => {
+    expect(gateValidationHelper.validateGateParams(['a--modify@body:orderId'], {
+      filter: { body: { properties: { orderId: {} }, additionalProperties: false } }
+    })).toEqual([])
+  })
+
+  test('an open body schema strips nothing, so nothing is reported', () => {
+    expect(gateValidationHelper.validateGateParams(['a--modify@body:orderId'], {
+      filter: { body: { properties: { amount: {} } } }
+    })).toEqual([])
+  })
+
+  test('an auth selector is never subject to the filter', () => {
+    expect(gateValidationHelper.validateGateParams(['a--modify@auth:profileId'], {
+      routePath: '/me', filter: { body: { properties: {}, additionalProperties: false } }
+    })).toEqual([])
+  })
+
+  test('a malformed param is reported without an audit', () => {
+    expect(gateValidationHelper.validateGateParams(['a--view@cookies:sid'])[0]?.code)
+      .toBe(GateParamErrorCode.UnknownSource)
+  })
+})
+
+describe('permission names', () => {
+  test('splits on TWO hyphens', () => {
+    expect(permissionNameHelper.parsePermissionName('enquiry--modify')).toMatchObject({
+      resource: 'enquiry', action: 'modify'
+    })
+  })
+
+  /** A single hyphen is not a separator, and a name already granted cannot be re-read. */
+  test('a single-hyphen legacy name stays one resource with no action', () => {
+    const parsed = permissionNameHelper.parsePermissionName('article-create')
+    expect(parsed.resource).toBe('article-create')
+    expect(parsed.action).toBeUndefined()
+  })
+
+  test('compose round-trips both shapes', () => {
+    for (const name of ['enquiry--modify', 'article-create', 'project--admin']) {
+      const parsed = permissionNameHelper.parsePermissionName(name)
+      expect(permissionNameHelper.composePermissionName(parsed)).toBe(name)
+    }
+  })
+
+  /** The live corruption this whole change exists to stop. */
+  test('a name carrying a gate selector is reported, not quietly split', () => {
+    const parsed = permissionNameHelper.parsePermissionName('enquiry--view@enquiryId')
+    expect(parsed.problem).toBeDefined()
+    expect(permissionNameHelper.isPermissionName('enquiry--view@enquiryId')).toBe(false)
+    expect(permissionNameHelper.isPermissionName('enquiry--view')).toBe(true)
+  })
+})

package/tests/runtime.spec.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test } from 'bun:test'
+import Ajv from 'ajv'
+import addFormats from 'ajv-formats'
+import { protocols } from '@owlmeans/entrypoint'
+import type { EntrypointProtocol, EntrypointTree } from '@owlmeans/entrypoint'
+import { IAM_RUNTIME_GUARD, IAM_RUNTIME_PATH, IAM_RUNTIME_ROUTES, makeIamRuntimeProtocols } from '@owlmeans/iam'
+
+const SERVICE = 'iam-api'
+const tree = makeIamRuntimeProtocols({ service: SERVICE })
+const all = protocols(tree as unknown as EntrypointTree) as EntrypointProtocol[]
+
+/** Every object schema reachable from `schema`, so closure can be asserted at every level. */
+const objectSchemas = (schema: unknown): Record<string, unknown>[] => {
+  if (schema == null || typeof schema !== 'object') {
+    return []
+  }
+  const node = schema as Record<string, unknown>
+  const own = node.type === 'object' ? [node] : []
+  const nested = [
+    ...Object.values((node.properties ?? {}) as Record<string, unknown>),
+    ...(node.items != null ? [node.items] : []),
+  ]
+
+  return [...own, ...nested.flatMap(objectSchemas)]
+}
+
+const sectionsOf = (declaration: EntrypointProtocol): unknown[] => [
+  ...Object.values(declaration.contract?.requestSchemas ?? {}),
+  declaration.contract?.responseSchemas?.default,
+].filter(schema => schema != null)
+
+describe('@owlmeans/iam — runtime IAM API declarations', () => {
+  test('every route, the base included, is pinned to the serving service', () => {
+    expect(all.length).toBe(12)
+    all.forEach(declaration => expect(declaration.route.route.service).toBe(SERVICE))
+  })
+
+  test('the base carries the runtime guard and every leaf hangs under it', () => {
+    expect(tree.base.guards).toEqual([IAM_RUNTIME_GUARD])
+    expect(tree.base.route.route.path).toBe(IAM_RUNTIME_PATH)
+    all.filter(declaration => declaration !== tree.base)
+      .forEach(declaration => expect(declaration.route.route.parent).toBe(tree.base.alias))
+  })
+
+  test('a custom base path is honoured', () => {
+    expect(makeIamRuntimeProtocols({ service: SERVICE, path: '/api/runtime' }).base.route.route.path)
+      .toBe('/api/runtime')
+  })
+
+  test.each([
+    [tree.organizations.list, 'GET', IAM_RUNTIME_ROUTES.organizations],
+    [tree.organizations.create, 'POST', IAM_RUNTIME_ROUTES.organizations],
+    [tree.organizations.update, 'POST', IAM_RUNTIME_ROUTES.organization],
+    [tree.members.list, 'GET', IAM_RUNTIME_ROUTES.members],
+    [tree.members.add, 'POST', IAM_RUNTIME_ROUTES.members],
+    [tree.members.update, 'POST', IAM_RUNTIME_ROUTES.member],
+    [tree.members.remove, 'POST', IAM_RUNTIME_ROUTES.memberRemove],
+    [tree.permissions.list, 'GET', IAM_RUNTIME_ROUTES.permissions],
+    [tree.grants.list, 'GET', IAM_RUNTIME_ROUTES.grants],
+    [tree.grants.assign, 'POST', IAM_RUNTIME_ROUTES.grants],
+    [tree.grants.revoke, 'POST', IAM_RUNTIME_ROUTES.grantsRevoke],
+  ] as const)('%#: %p answers on its method and shared path', (declaration, method, path) => {
+    expect(declaration.route.route.method?.toUpperCase()).toBe(method)
+    expect(declaration.route.route.path).toBe(path)
+  })
+
+  test('every request section and every response is a closed schema', () => {
+    const leaves = all.filter(declaration => declaration !== tree.base)
+    leaves.forEach(declaration => {
+      const schemas = sectionsOf(declaration)
+      expect(schemas.length).toBeGreaterThan(0)
+      schemas.flatMap(objectSchemas).forEach(schema => expect(schema.additionalProperties).toBe(false))
+    })
+  })
+
+  test('every schema compiles the way the server compiles it, and strips what it does not declare', () => {
+    // The server's own options: `removeAdditional` is what makes an undeclared key vanish.
+    const ajv = new Ajv({ removeAdditional: true, useDefaults: true, coerceTypes: true, allErrors: true, strict: false })
+    addFormats(ajv)
+    all.flatMap(sectionsOf).forEach(schema => expect(() => ajv.compile(schema as object)).not.toThrow())
+
+    const invite = ajv.compile(tree.members.add.contract!.requestSchemas.body!)
+    const body: Record<string, unknown> = { email: 'Person@Example.test', owner: true, entityId: '0123456789abcdef01234567' }
+    expect(invite(body)).toBe(true)
+    expect(body).toEqual({ email: 'Person@Example.test', owner: true })
+    expect(invite({ email: 'not-an-address' })).toBe(false)
+
+    const params = ajv.compile(tree.members.update.contract!.requestSchemas.params!)
+    expect(params({ entitySlug: 'acme', profileId: 'acme-preview:3vQB7B6MrGQZaxCuFg4oh' })).toBe(true)
+    expect(params({ entitySlug: 'acme', profileId: 'has space' })).toBe(false)
+  })
+
+  test('the wire names organizations by slug only — no id field anywhere', () => {
+    const names = all.flatMap(sectionsOf).flatMap(objectSchemas)
+      .flatMap(schema => Object.keys((schema.properties ?? {}) as object))
+    expect(names).toContain('entitySlug')
+    expect(names).not.toContain('entityId')
+    expect(names).not.toContain('accountId')
+    expect(names).not.toContain('entityKey')
+  })
+})

package/tests/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "types": ["bun"],
+    "rootDir": "../",
+    "noEmit": true
+  },
+  "include": ["./**/*", "../src/**/*"]
+}

package/tests/utils.spec.ts

@@ -1,6 +1,8 @@
 import { describe, expect, test } from 'bun:test'
-import { hasPermission } from '@owlmeans/iam'
+import { hasPermission, IamUnsupported, unsupportedFacet } from '@owlmeans/iam'
+import type { IamSubjectFacet } from '@owlmeans/iam'
 import type { Authorization } from '@owlmeans/auth'
+import type { OidcPermissionSetClaim } from '@owlmeans/oidc'
 
 const auth: Authorization = {
   scopes: [],
@@ -37,3 +39,47 @@ describe('@owlmeans/iam — hasPermission', () => {
     expect(hasPermission(auth, 'article--modify', { scope: 'other-project' })).toBe(false)
   })
 })
+
+describe('@owlmeans/iam — hasPermission and the acting organization', () => {
+  const sets: OidcPermissionSetClaim[] = [
+    { scope: 'my-project', permissions: { 'report--view': true } },
+    { scope: 'my-project', permissions: { 'order--edit': true }, entitySlug: 'acme' },
+    {
+      scope: 'my-project', title: 'order--delete', permissions: { 'order--delete': true },
+      resources: ['ord-1'], entitySlug: 'acme',
+    },
+  ]
+  const bound: Authorization = { scopes: [], permissions: sets }
+
+  test.each([
+    ['an unbound set applies with no organization named', 'report--view', {}, true],
+    ['an unbound set applies in any organization', 'report--view', { entitySlug: 'beta' }, true],
+    ['a bound set applies in its organization', 'order--edit', { entitySlug: 'acme' }, true],
+    ['a bound set does not apply in another organization', 'order--edit', { entitySlug: 'beta' }, false],
+    // Fail-closed: a bound set that leaked into a token must not count where the caller named none.
+    ['a bound set does not apply when no organization is named', 'order--edit', {}, false],
+    ['bound and resource-scoped: both checks pass', 'order--delete', { entitySlug: 'acme', resourceId: 'ord-1' }, true],
+    ['bound and resource-scoped: wrong record', 'order--delete', { entitySlug: 'acme', resourceId: 'ord-2' }, false],
+    ['bound and resource-scoped: wrong organization', 'order--delete', { entitySlug: 'beta', resourceId: 'ord-1' }, false],
+  ] as const)('%s', (_, permission, opts, expected) => {
+    expect(hasPermission(bound, permission, opts)).toBe(expected)
+  })
+})
+
+describe('@owlmeans/iam — unsupportedFacet', () => {
+  const facet = unsupportedFacet<IamSubjectFacet>('subjects')
+
+  test('every method throws IamUnsupported naming the facet', () => {
+    expect(() => facet.identify('client', 'account')).toThrow(IamUnsupported)
+    expect(() => facet.resolve('client', 'account')).toThrow('iam:unsupported:subjects')
+  })
+
+  test('an awaited call rejects the same way', async () => {
+    const attempt = async () => await facet.signIn('client', { email: 'a@example.test' })
+    expect(attempt()).rejects.toBeInstanceOf(IamUnsupported)
+  })
+
+  test('is not a thenable, so awaiting the facet itself does not throw', async () => {
+    expect(await Promise.resolve(facet)).toBe(facet)
+  })
+})