json-rest-api 1.0.24 → 1.0.26

package/tests/return-record-settings.test.js

@@ -0,0 +1,184 @@
+import { describe, it, before, after, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import knexLib from 'knex'
+import { createReturnRecordApi } from './fixtures/api-configs.js'
+import { cleanTables } from './helpers/test-utils.js'
+
+const knex = knexLib({
+  client: 'better-sqlite3',
+  connection: {
+    filename: ':memory:'
+  },
+  useNullAsDefault: true
+})
+
+let api
+
+function itemDocument (type, name, id) {
+  const doc = {
+    data: {
+      type,
+      attributes: { name }
+    }
+  }
+
+  if (id !== undefined) {
+    doc.data.id = String(id)
+  }
+
+  return doc
+}
+
+describe('Return record settings', () => {
+  before(async () => {
+    api = await createReturnRecordApi(knex)
+  })
+
+  after(async () => {
+    await knex.destroy()
+  })
+
+  beforeEach(async () => {
+    await cleanTables(knex, [
+      'return_global_items',
+      'return_scope_items'
+    ])
+  })
+
+  it('normalizes plugin-level boolean return settings', async () => {
+    const created = await api.resources.global_items.post({
+      inputRecord: itemDocument('global_items', 'Global Created'),
+      simplified: false
+    })
+
+    assert.equal(created.data.type, 'global_items')
+    assert.equal(created.data.attributes.name, 'Global Created')
+
+    const replaced = await api.resources.global_items.put({
+      id: created.data.id,
+      inputRecord: itemDocument('global_items', 'Global Replaced', created.data.id),
+      simplified: false
+    })
+    assert.equal(replaced, undefined)
+
+    const patched = await api.resources.global_items.patch({
+      id: created.data.id,
+      inputRecord: itemDocument('global_items', 'Global Patched', created.data.id),
+      simplified: false
+    })
+    assert.equal(patched, undefined)
+
+    const fetched = await api.resources.global_items.get({
+      id: created.data.id,
+      simplified: false
+    })
+    assert.equal(fetched.data.attributes.name, 'Global Patched')
+  })
+
+  it('normalizes per-call boolean return settings', async () => {
+    const created = await api.resources.global_items.post({
+      inputRecord: itemDocument('global_items', 'Per-call Created'),
+      simplified: false,
+      returnFullRecord: false
+    })
+    assert.equal(created, undefined)
+
+    const queryResult = await api.resources.global_items.query({
+      simplified: false
+    })
+    assert.equal(queryResult.data.length, 1)
+    const fetched = queryResult.data[0]
+    assert.equal(fetched.attributes.name, 'Per-call Created')
+
+    const patched = await api.resources.global_items.patch({
+      id: fetched.id,
+      inputRecord: itemDocument('global_items', 'Per-call Patched', fetched.id),
+      simplified: false,
+      returnFullRecord: true
+    })
+    assert.equal(patched.data.type, 'global_items')
+    assert.equal(patched.data.id, fetched.id)
+    assert.equal(patched.data.attributes.name, 'Per-call Patched')
+  })
+
+  it('normalizes resource-level boolean return settings', async () => {
+    const created = await api.resources.scope_items.post({
+      inputRecord: itemDocument('scope_items', 'Scoped Created'),
+      simplified: false
+    })
+    assert.equal(created, undefined)
+
+    const queryResult = await api.resources.scope_items.query({
+      simplified: false
+    })
+    assert.equal(queryResult.data.length, 1)
+    const fetched = queryResult.data[0]
+
+    const replaced = await api.resources.scope_items.put({
+      id: fetched.id,
+      inputRecord: itemDocument('scope_items', 'Scoped Replaced', fetched.id),
+      simplified: false
+    })
+    assert.equal(replaced.data.type, 'scope_items')
+    assert.equal(replaced.data.id, fetched.id)
+    assert.equal(replaced.data.attributes.name, 'Scoped Replaced')
+
+    const patched = await api.resources.scope_items.patch({
+      id: fetched.id,
+      inputRecord: itemDocument('scope_items', 'Scoped Patched', fetched.id),
+      simplified: false
+    })
+    assert.deepEqual(patched, {
+      data: {
+        type: 'scope_items',
+        id: fetched.id
+      }
+    })
+  })
+
+  it('normalizes transport boolean return settings', async () => {
+    const created = await api.resources.global_items.post({
+      inputRecord: itemDocument('global_items', 'Transport Created'),
+      simplified: false,
+      isTransport: true
+    })
+    assert.equal(created, undefined)
+
+    const queryResult = await api.resources.global_items.query({
+      simplified: false
+    })
+    assert.equal(queryResult.data.length, 1)
+    const fetched = queryResult.data[0]
+
+    const replaced = await api.resources.global_items.put({
+      id: fetched.id,
+      inputRecord: itemDocument('global_items', 'Transport Replaced', fetched.id),
+      simplified: false,
+      isTransport: true
+    })
+    assert.equal(replaced.data.type, 'global_items')
+    assert.equal(replaced.data.id, fetched.id)
+    assert.equal(replaced.data.attributes.name, 'Transport Replaced')
+
+    const patched = await api.resources.global_items.patch({
+      id: fetched.id,
+      inputRecord: itemDocument('global_items', 'Transport Patched', fetched.id),
+      simplified: false,
+      isTransport: true
+    })
+    assert.deepEqual(patched, {
+      data: {
+        type: 'global_items',
+        id: fetched.id
+      }
+    })
+
+    const scoped = await api.resources.scope_items.post({
+      inputRecord: itemDocument('scope_items', 'Scoped Transport Created'),
+      simplified: false,
+      isTransport: true
+    })
+    assert.equal(scoped.data.type, 'scope_items')
+    assert.equal(scoped.data.attributes.name, 'Scoped Transport Created')
+  })
+})

package/tests/row-policy.test.js

@@ -0,0 +1,489 @@
+import { describe, it, before, after, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import knexLib from 'knex'
+import {
+  cleanTables,
+  countRecords,
+  createJsonApiDocument,
+  createRelationship,
+  resourceIdentifier,
+  validateJsonApiStructure
+} from './helpers/test-utils.js'
+import { storageMode } from './helpers/storage-mode.js'
+import { createRowPolicyApi } from './fixtures/api-configs.js'
+import { createStorageAdapterUtilities } from '../plugins/core/lib/querying/storage-adapter-utils.js'
+
+const knex = knexLib({
+  client: 'better-sqlite3',
+  connection: {
+    filename: ':memory:'
+  },
+  useNullAsDefault: true
+})
+
+let api
+const policyEvents = []
+
+const adminContext = (workspaceId = 'workspace-a') => ({
+  visibility: { all: true },
+  scopeValues: { workspaceId }
+})
+const groupContext = (...groups) => ({
+  visibility: { groups },
+  scopeValues: { workspaceId: 'workspace-a' }
+})
+
+const postProject = async (name, accessGroup, context = adminContext()) => {
+  return api.resources.policy_projects.post({
+    inputRecord: createJsonApiDocument('policy_projects', {
+      name,
+      access_group: accessGroup
+    }),
+    simplified: false
+  }, context)
+}
+
+const postTask = async ({ title, accessGroup, projectId, context = adminContext() }) => {
+  const relationships = projectId === undefined
+    ? {}
+    : {
+        project: createRelationship(resourceIdentifier('policy_projects', projectId))
+      }
+
+  return api.resources.policy_tasks.post({
+    inputRecord: createJsonApiDocument('policy_tasks', {
+      title,
+      access_group: accessGroup
+    }, relationships),
+    simplified: false
+  }, context)
+}
+
+describe('RowPolicy Plugin', () => {
+  it('keeps active query translation stable after the hook context is restored', () => {
+    const queryStorageAdapter = {
+      translateColumn: (field) => field === 'id' ? 'record_id' : field
+    }
+    const ambientStorageAdapter = {
+      translateColumn: (field) => field === 'id' ? 'wrong_id' : field
+    }
+    const context = {
+      knexQuery: {
+        scopeName: 'organisationUnits',
+        tableName: 'organisation_units',
+        storageAdapter: queryStorageAdapter
+      },
+      storageAdapter: ambientStorageAdapter
+    }
+    const utilities = createStorageAdapterUtilities({ context })
+
+    delete context.knexQuery
+    delete context.storageAdapter
+
+    assert.equal(
+      utilities.translateColumn('organisationUnits', 'id'),
+      'organisation_units.record_id'
+    )
+    assert.equal(
+      utilities.translateColumn('organisationUnits', 'id', 'visible_units'),
+      'visible_units.record_id'
+    )
+    assert.equal(utilities.defaultAliasForScope('users'), 'users')
+    assert.equal(Object.hasOwn(context, 'knexQuery'), false)
+    assert.equal(Object.hasOwn(context, 'storageAdapter'), false)
+  })
+
+  before(async () => {
+    api = await createRowPolicyApi(knex, {
+      onPolicy: (event) => policyEvents.push(event)
+    })
+  })
+
+  after(async () => {
+    await knex.destroy()
+  })
+
+  beforeEach(async () => {
+    policyEvents.length = 0
+    await cleanTables(knex, [
+      'row_policy_project_tasks',
+      'row_policy_projects',
+      'row_policy_tasks',
+      'row_policy_broken'
+    ])
+  })
+
+  it('applies deferred grouped visibility before offset pagination and counts the same dataset', async () => {
+    await postProject('Allowed 1', 'group-a')
+    await postProject('Hidden 1', 'group-b')
+    await postProject('Allowed 2', 'group-a')
+    await postProject('Hidden 2', 'group-b')
+    await postProject('Allowed 3', 'group-a')
+
+    policyEvents.length = 0
+    const firstPage = await api.resources.policy_projects.query({
+      queryParams: {
+        sort: ['id'],
+        page: { number: 1, size: 2 }
+      },
+      simplified: false
+    }, groupContext('group-a'))
+
+    validateJsonApiStructure(firstPage, true)
+    assert.deepEqual(
+      firstPage.data.map((record) => record.attributes.name),
+      ['Allowed 1', 'Allowed 2']
+    )
+    assert.equal(firstPage.meta.pagination.total, 3)
+    assert.equal(firstPage.meta.pagination.pageCount, 2)
+    assert(policyEvents.some((event) => event.queryPurpose === 'collection'))
+
+    const secondPage = await api.resources.policy_projects.query({
+      queryParams: {
+        sort: ['id'],
+        page: { number: 2, size: 2 }
+      },
+      simplified: false
+    }, groupContext('group-a'))
+
+    assert.deepEqual(
+      secondPage.data.map((record) => record.attributes.name),
+      ['Allowed 3']
+    )
+  })
+
+  it('combines row policy visibility with the resource autofilter', async () => {
+    await postProject('Visible', 'group-a')
+    await postProject('Wrong group', 'group-b')
+    await postProject('Wrong workspace', 'group-a', adminContext('workspace-b'))
+
+    const result = await api.resources.policy_projects.query({
+      queryParams: { sort: ['id'] },
+      simplified: false
+    }, groupContext('group-a'))
+
+    assert.deepEqual(
+      result.data.map((record) => record.attributes.name),
+      ['Visible']
+    )
+  })
+
+  it('keeps cursor pagination inside the visible dataset', async () => {
+    await postProject('Allowed 1', 'group-a')
+    await postProject('Hidden 1', 'group-b')
+    await postProject('Allowed 2', 'group-a')
+    await postProject('Hidden 2', 'group-b')
+    await postProject('Allowed 3', 'group-a')
+
+    const firstPage = await api.resources.policy_projects.query({
+      queryParams: {
+        sort: ['name'],
+        page: { size: 2 }
+      },
+      simplified: false
+    }, groupContext('group-a'))
+
+    assert.deepEqual(
+      firstPage.data.map((record) => record.attributes.name),
+      ['Allowed 1', 'Allowed 2']
+    )
+    assert.equal(firstPage.meta.pagination.hasMore, true)
+    assert(firstPage.meta.pagination.cursor.next)
+
+    const secondPage = await api.resources.policy_projects.query({
+      queryParams: {
+        sort: ['name'],
+        page: {
+          size: 2,
+          after: firstPage.meta.pagination.cursor.next
+        }
+      },
+      simplified: false
+    }, groupContext('group-a'))
+
+    assert.deepEqual(
+      secondPage.data.map((record) => record.attributes.name),
+      ['Allowed 3']
+    )
+    assert.equal(secondPage.meta.pagination.hasMore, false)
+  })
+
+  if (storageMode.isAnyApi()) {
+    it('applies the policy to the standalone AnyAPI count helper', async () => {
+      await postProject('Allowed 1', 'group-a')
+      await postProject('Hidden 1', 'group-b')
+      await postProject('Allowed 2', 'group-a')
+
+      policyEvents.length = 0
+      const total = await api.helpers.dataQueryCount({
+        scopeName: 'policy_projects',
+        context: {
+          db: knex,
+          queryParams: {},
+          ...groupContext('group-a')
+        }
+      })
+
+      assert.equal(total, 2)
+      assert(policyEvents.some((event) => event.queryPurpose === 'count'))
+    })
+  }
+
+  it('uses the policy for single-record and write preflight lookups', async () => {
+    const allowed = await postProject('Allowed', 'group-a')
+    const hidden = await postProject('Hidden', 'group-b')
+
+    const visibleRecord = await api.resources.policy_projects.get({
+      id: allowed.data.id,
+      simplified: false
+    }, groupContext('group-a'))
+    assert.equal(visibleRecord.data.attributes.name, 'Allowed')
+
+    await assert.rejects(
+      api.resources.policy_projects.get({
+        id: hidden.data.id,
+        simplified: false
+      }, groupContext('group-a')),
+      (error) => error.code === 'REST_API_RESOURCE'
+    )
+
+    await assert.rejects(
+      api.resources.policy_projects.patch({
+        id: hidden.data.id,
+        inputRecord: {
+          data: {
+            type: 'policy_projects',
+            id: hidden.data.id,
+            attributes: { name: 'Changed' }
+          }
+        },
+        simplified: false
+      }, groupContext('group-a')),
+      (error) => error.code === 'REST_API_RESOURCE'
+    )
+
+    await assert.rejects(
+      api.resources.policy_projects.delete({
+        id: hidden.data.id,
+        simplified: false
+      }, groupContext('group-a')),
+      (error) => error.code === 'REST_API_RESOURCE'
+    )
+
+    const stillPresent = await api.resources.policy_projects.get({
+      id: hidden.data.id,
+      simplified: false
+    }, adminContext())
+    assert.equal(stillPresent.data.attributes.name, 'Hidden')
+  })
+
+  it('filters included children and relationship identifiers', async () => {
+    const project = await postProject('Visible project', 'group-a')
+    const visibleTask = await postTask({
+      title: 'Visible task',
+      accessGroup: 'group-a',
+      projectId: project.data.id
+    })
+    await postTask({
+      title: 'Hidden task',
+      accessGroup: 'group-b',
+      projectId: project.data.id
+    })
+
+    policyEvents.length = 0
+    const result = await api.resources.policy_projects.get({
+      id: project.data.id,
+      queryParams: { include: ['tasks'] },
+      simplified: false
+    }, groupContext('group-a'))
+
+    assert.deepEqual(result.data.relationships.tasks.data, [
+      resourceIdentifier('policy_tasks', visibleTask.data.id)
+    ])
+    assert.deepEqual(
+      result.included.map((record) => record.attributes.title),
+      ['Visible task']
+    )
+    assert(policyEvents.some((event) => event.queryPurpose === 'relationship-identifiers'))
+    assert(policyEvents.some((event) => event.queryPurpose === 'include'))
+
+    policyEvents.length = 0
+    const relationship = await api.resources.policy_projects.getRelationship({
+      id: project.data.id,
+      relationshipName: 'tasks',
+      simplified: false
+    }, groupContext('group-a'))
+
+    assert.deepEqual(relationship.data, [
+      resourceIdentifier('policy_tasks', visibleTask.data.id)
+    ])
+    assert(policyEvents.some((event) => event.queryPurpose === 'single'))
+  })
+
+  it('filters a belongs-to include through the target resource policy', async () => {
+    const hiddenProject = await postProject('Hidden project', 'group-b')
+    await postTask({
+      title: 'Visible task',
+      accessGroup: 'group-a',
+      projectId: hiddenProject.data.id
+    })
+
+    const result = await api.resources.policy_tasks.query({
+      queryParams: { include: ['project'], sort: ['id'] },
+      simplified: false
+    }, groupContext('group-a'))
+
+    assert.equal(result.data.length, 1)
+    assert.equal(result.included?.length || 0, 0)
+  })
+
+  it('uses target row policies during relationship validation', async () => {
+    const hiddenProject = await postProject('Hidden project', 'group-b')
+
+    await assert.rejects(
+      postTask({
+        title: 'Cross-policy task',
+        accessGroup: 'group-a',
+        projectId: hiddenProject.data.id,
+        context: groupContext('group-a')
+      }),
+      (error) => error.code === 'REST_API_RESOURCE' || error.code === 'REST_API_VALIDATION'
+    )
+
+    assert(policyEvents.some((event) => event.queryPurpose === 'relationship-validation'))
+  })
+
+  it('uses target row policies when adding many-to-many relationships', async () => {
+    const project = await postProject('Visible project', 'group-a')
+    const visibleTask = await postTask({ title: 'Visible task', accessGroup: 'group-a' })
+    const hiddenTask = await postTask({ title: 'Hidden task', accessGroup: 'group-b' })
+
+    await api.resources.policy_projects.postRelationship({
+      id: project.data.id,
+      relationshipName: 'shared_tasks',
+      relationshipData: [resourceIdentifier('policy_tasks', visibleTask.data.id)],
+      simplified: false
+    }, groupContext('group-a'))
+
+    await assert.rejects(
+      api.resources.policy_projects.postRelationship({
+        id: project.data.id,
+        relationshipName: 'shared_tasks',
+        relationshipData: [resourceIdentifier('policy_tasks', hiddenTask.data.id)],
+        simplified: false
+      }, groupContext('group-a')),
+      (error) => error.code === 'REST_API_RESOURCE'
+    )
+
+    assert.equal(await countRecords(knex, 'row_policy_project_tasks'), 1)
+  })
+
+  it('does not expose relationship routes for a hidden parent', async () => {
+    const hiddenProject = await postProject('Hidden project', 'group-b')
+
+    await assert.rejects(
+      api.resources.policy_projects.getRelated({
+        id: hiddenProject.data.id,
+        relationshipName: 'tasks',
+        queryParams: {},
+        simplified: false
+      }, groupContext('group-a')),
+      (error) => error.code === 'REST_API_RESOURCE'
+    )
+
+    await assert.rejects(
+      api.resources.policy_projects.getRelationship({
+        id: hiddenProject.data.id,
+        relationshipName: 'tasks',
+        simplified: false
+      }, groupContext('group-a')),
+      (error) => error.code === 'REST_API_RESOURCE'
+    )
+
+    await assert.rejects(
+      api.resources.policy_projects.patchRelationship({
+        id: hiddenProject.data.id,
+        relationshipName: 'tasks',
+        relationshipData: [],
+        simplified: false
+      }, groupContext('group-a')),
+      (error) => error.code === 'REST_API_RESOURCE'
+    )
+
+    assert(policyEvents.some((event) => event.queryPurpose === 'relationship-parent'))
+  })
+
+  it('filters related children before pagination and keeps target filters off the parent lookup', async () => {
+    const project = await postProject('Visible project', 'group-a')
+    await postTask({ title: 'Allowed 1', accessGroup: 'group-a', projectId: project.data.id })
+    await postTask({ title: 'Hidden 1', accessGroup: 'group-b', projectId: project.data.id })
+    await postTask({ title: 'Allowed 2', accessGroup: 'group-a', projectId: project.data.id })
+    await postTask({ title: 'Hidden 2', accessGroup: 'group-b', projectId: project.data.id })
+    await postTask({ title: 'Allowed 3', accessGroup: 'group-a', projectId: project.data.id })
+
+    const firstPage = await api.resources.policy_projects.getRelated({
+      id: project.data.id,
+      relationshipName: 'tasks',
+      queryParams: {
+        sort: ['id'],
+        page: { number: 1, size: 2 }
+      },
+      simplified: false
+    }, groupContext('group-a'))
+
+    assert.deepEqual(
+      firstPage.data.map((record) => record.attributes.title),
+      ['Allowed 1', 'Allowed 2']
+    )
+    assert.equal(firstPage.meta.pagination.total, 3)
+
+    const filtered = await api.resources.policy_projects.getRelated({
+      id: project.data.id,
+      relationshipName: 'tasks',
+      queryParams: {
+        filters: { title: 'Allowed 3' },
+        page: { number: 1, size: 2 }
+      },
+      simplified: false
+    }, groupContext('group-a'))
+
+    assert.deepEqual(
+      filtered.data.map((record) => record.attributes.title),
+      ['Allowed 3']
+    )
+    assert.equal(filtered.meta.pagination.total, 1)
+  })
+
+  it('denies all rows when a policy explicitly returns false', async () => {
+    await postProject('Hidden without context', 'group-a')
+
+    const result = await api.resources.policy_projects.query({
+      queryParams: { page: { number: 1, size: 10 } },
+      simplified: false
+    }, { scopeValues: { workspaceId: 'workspace-a' } })
+
+    assert.deepEqual(result.data, [])
+    assert.equal(result.meta.pagination.total, 0)
+  })
+
+  it('fails closed when a policy does not return an explicit decision', async () => {
+    await assert.rejects(
+      api.resources.policy_broken.query({ simplified: false }),
+      (error) => error.code === 'REST_API_ROW_POLICY_CONTRACT'
+    )
+  })
+
+  it('exposes compiled policy configuration for inspection', () => {
+    assert.deepEqual(api.rowPolicies.getConfig(), {
+      policies: ['groupVisibility']
+    })
+    assert.deepEqual(api.rowPolicies.getScopeConfig('policy_projects'), {
+      policy: 'groupVisibility',
+      source: 'registry'
+    })
+    assert.deepEqual(api.rowPolicies.getScopeConfig('policy_broken'), {
+      policy: '<inline>',
+      source: 'inline'
+    })
+  })
+})

package/tests/s3-storage.test.js

@@ -0,0 +1,38 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { S3Storage } from '../index.js'
+
+function createFile (filename = 'photo.png') {
+  return {
+    filename,
+    mimetype: 'image/png',
+    data: Buffer.from('file contents')
+  }
+}
+
+describe('S3Storage', () => {
+  it('requires a bucket name', () => {
+    assert.throws(() => new S3Storage(), /S3Storage requires a bucket name/)
+  })
+
+  it('generates S3-style mock URLs and accepts deleting returned URLs', async () => {
+    const storage = new S3Storage({
+      bucket: 'my-uploads',
+      region: 'ap-southeast-2',
+      prefix: 'uploads/'
+    })
+
+    const url = await storage.upload(createFile())
+
+    assert.match(url, /^https:\/\/my-uploads\.s3\.ap-southeast-2\.amazonaws\.com\/uploads\/[a-f0-9]{32}\.png$/)
+    await assert.doesNotReject(storage.delete(url))
+  })
+
+  it('fails clearly when real S3 mode is requested', () => {
+    assert.throws(
+      () => new S3Storage({ bucket: 'my-uploads', mockMode: false }),
+      /S3Storage real S3 mode is not implemented/
+    )
+  })
+})