json-rest-api 1.0.24 → 1.0.25

package/tests/http-connectors-parity.test.js

@@ -25,13 +25,21 @@ const knex = knexLib({
   useNullAsDefault: true
 })
 
-async function createConnectorParityApi () {
+async function createConnectorParityApi ({
+  name = 'connector-parity-test-api',
+  tableName = 'connector_parity_countries',
+  publicBaseUrl = ''
+} = {}) {
   const expressApp = express()
   const fastifyApp = new FakeFastifyApp()
   const api = new Api({
-    name: 'connector-parity-test-api',
+    name,
     log: { level: process.env.LOG_LEVEL || 'silent' }
   })
+  const transportOptions = {
+    mountPath: '/api',
+    ...(publicBaseUrl ? { publicBaseUrl } : {})
+  }
 
   await api.use(RestApiPlugin, {
     simplifiedApi: false,
@@ -50,10 +58,10 @@ async function createConnectorParityApi () {
   })
 
   await api.use(RestApiKnexPlugin, { knex })
-  await api.use(ExpressPlugin, { mountPath: '/api' })
+  await api.use(ExpressPlugin, transportOptions)
   await api.use(FastifyPlugin, {
     app: fastifyApp,
-    mountPath: '/api'
+    ...transportOptions
   })
 
   await api.customize({
@@ -61,6 +69,10 @@ async function createConnectorParityApi () {
       'transport:request': {
         functionName: 'connector-parity-rejector',
         handler: async ({ context }) => {
+          if (context.transport?.request?.headers?.['x-use-public-url-override'] === 'yes') {
+            context.urlPrefixOverride = 'https://trusted.example/api'
+          }
+
           if (context.transport?.request?.headers?.['x-block-request'] === 'yes') {
             context.reject(401, 'Blocked by connector parity hook', {
               title: 'Unauthorized'
@@ -83,7 +95,7 @@ async function createConnectorParityApi () {
       name: { type: 'string', required: true, max: 100 },
       code: { type: 'string', max: 2 }
     },
-    tableName: 'connector_parity_countries'
+    tableName
   })
 
   await api.resources.countries.createKnexTable()
@@ -101,6 +113,12 @@ function assertLocationSuffix (location, resourceId) {
   )
 }
 
+function assertResourceLinksUsePrefix (body, expectedPrefix) {
+  const resourceId = body.data.id
+  assert.equal(body.data.links.self, `${expectedPrefix}/countries/${resourceId}`)
+  assert.equal(body.links.self, `${expectedPrefix}/countries/${resourceId}`)
+}
+
 describe('HTTP Connector Parity', () => {
   let api
   let expressApp
@@ -159,6 +177,148 @@ describe('HTTP Connector Parity', () => {
     assertLocationSuffix(fastifyReply.headers.Location, fastifyReply.payload.data.id)
   })
 
+  it('does not build response URLs from untrusted proxy headers', async () => {
+    const expressDoc = createJsonApiDocument('countries', {
+      name: 'Express Hostile Header Country',
+      code: 'EH'
+    })
+    const fastifyDoc = createJsonApiDocument('countries', {
+      name: 'Fastify Hostile Header Country',
+      code: 'FH'
+    })
+
+    const expressResponse = await request(expressApp)
+      .post('/api/countries')
+      .set('Content-Type', 'application/vnd.api+json')
+      .set('Accept', 'application/vnd.api+json')
+      .set('Host', 'attacker.example')
+      .set('X-Forwarded-Host', 'proxy-attacker.example')
+      .set('X-Forwarded-Proto', 'https')
+      .send(expressDoc)
+
+    const { reply: fastifyReply } = await invokeFastifyRoute(fastifyApp, {
+      method: 'POST',
+      routeUrl: '/api/countries',
+      requestUrl: '/api/countries',
+      headers: {
+        'content-type': 'application/vnd.api+json',
+        accept: 'application/vnd.api+json',
+        host: 'attacker.example',
+        'x-forwarded-host': 'proxy-attacker.example',
+        'x-forwarded-proto': 'https'
+      },
+      body: fastifyDoc
+    })
+
+    assert.equal(expressResponse.status, 201)
+    assert.equal(fastifyReply.statusCode, 201)
+    assert.equal(
+      expressResponse.headers.location,
+      `/api/countries/${expressResponse.body.data.id}`
+    )
+    assert.equal(
+      fastifyReply.headers.Location,
+      `/api/countries/${fastifyReply.payload.data.id}`
+    )
+    assertResourceLinksUsePrefix(expressResponse.body, '/api')
+    assertResourceLinksUsePrefix(fastifyReply.payload, '/api')
+  })
+
+  it('uses explicit publicBaseUrl when a connector is configured with one', async () => {
+    const {
+      expressApp: publicExpressApp,
+      fastifyApp: publicFastifyApp
+    } = await createConnectorParityApi({
+      name: 'connector-parity-public-url-test-api',
+      tableName: 'connector_parity_public_countries',
+      publicBaseUrl: 'https://public.example/api/'
+    })
+
+    const expressDoc = createJsonApiDocument('countries', {
+      name: 'Express Public Country',
+      code: 'EP'
+    })
+    const fastifyDoc = createJsonApiDocument('countries', {
+      name: 'Fastify Public Country',
+      code: 'FP'
+    })
+
+    const expressResponse = await request(publicExpressApp)
+      .post('/api/countries')
+      .set('Content-Type', 'application/vnd.api+json')
+      .set('Accept', 'application/vnd.api+json')
+      .send(expressDoc)
+
+    const { reply: fastifyReply } = await invokeFastifyRoute(publicFastifyApp, {
+      method: 'POST',
+      routeUrl: '/api/countries',
+      requestUrl: '/api/countries',
+      headers: {
+        'content-type': 'application/vnd.api+json',
+        accept: 'application/vnd.api+json'
+      },
+      body: fastifyDoc
+    })
+
+    assert.equal(expressResponse.status, 201)
+    assert.equal(fastifyReply.statusCode, 201)
+    assert.equal(
+      expressResponse.headers.location,
+      `https://public.example/api/countries/${expressResponse.body.data.id}`
+    )
+    assert.equal(
+      fastifyReply.headers.Location,
+      `https://public.example/api/countries/${fastifyReply.payload.data.id}`
+    )
+    assertResourceLinksUsePrefix(expressResponse.body, 'https://public.example/api')
+    assertResourceLinksUsePrefix(fastifyReply.payload, 'https://public.example/api')
+
+    await cleanTables(knex, ['connector_parity_public_countries'])
+  })
+
+  it('honors urlPrefixOverride set during transport request hooks', async () => {
+    const expressDoc = createJsonApiDocument('countries', {
+      name: 'Express Override Country',
+      code: 'EO'
+    })
+    const fastifyDoc = createJsonApiDocument('countries', {
+      name: 'Fastify Override Country',
+      code: 'FO'
+    })
+
+    const expressResponse = await request(expressApp)
+      .post('/api/countries')
+      .set('Content-Type', 'application/vnd.api+json')
+      .set('Accept', 'application/vnd.api+json')
+      .set('x-use-public-url-override', 'yes')
+      .send(expressDoc)
+
+    const { reply: fastifyReply } = await invokeFastifyRoute(fastifyApp, {
+      method: 'POST',
+      routeUrl: '/api/countries',
+      requestUrl: '/api/countries',
+      headers: {
+        'content-type': 'application/vnd.api+json',
+        accept: 'application/vnd.api+json',
+        'x-use-public-url-override': 'yes'
+      },
+      body: fastifyDoc
+    })
+
+    assert.equal(expressResponse.status, 201)
+    assert.equal(fastifyReply.statusCode, 201)
+    assert.equal(
+      expressResponse.headers.location,
+      `https://trusted.example/api/countries/${expressResponse.body.data.id}`
+    )
+    assert.equal(
+      fastifyReply.headers.Location,
+      `https://trusted.example/api/countries/${fastifyReply.payload.data.id}`
+    )
+    assertResourceLinksUsePrefix(expressResponse.body, 'https://trusted.example/api')
+    assertResourceLinksUsePrefix(fastifyReply.payload, 'https://trusted.example/api')
+  })
+
   it('rejects unsupported write content types using each connector transport policy', async () => {
     const expressResponse = await request(expressApp)
       .post('/api/countries')

package/tests/local-storage.test.js

@@ -0,0 +1,96 @@
+import { describe, it, beforeEach, afterEach } from 'node:test'
+import assert from 'node:assert/strict'
+import { promises as fs } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { LocalStorage } from '../plugins/storage/local-storage.js'
+
+let tempRoot
+
+async function createTempRoot () {
+  tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'json-rest-api-local-storage-'))
+  return tempRoot
+}
+
+function createFile (filename = 'photo.png') {
+  return {
+    filename,
+    mimetype: 'image/png',
+    data: Buffer.from('x')
+  }
+}
+
+describe('LocalStorage path containment', () => {
+  beforeEach(async () => {
+    await createTempRoot()
+  })
+
+  afterEach(async () => {
+    await fs.rm(tempRoot, { recursive: true, force: true })
+  })
+
+  it('rejects custom generated paths that escape to sibling directories', async () => {
+    const directory = path.join(tempRoot, 'uploads')
+    const evilDirectory = path.join(tempRoot, 'uploads_evil')
+    await fs.mkdir(evilDirectory, { recursive: true })
+
+    const storage = new LocalStorage({
+      directory,
+      fileBaseUrl: '/uploads',
+      nameStrategy: 'custom',
+      nameGenerator: async () => '../uploads_evil/pwn'
+    })
+
+    await assert.rejects(
+      storage.upload(createFile()),
+      /Custom nameGenerator must return a basename, not a path/
+    )
+
+    await assert.rejects(
+      fs.access(path.join(evilDirectory, 'pwn.png')),
+      { code: 'ENOENT' }
+    )
+  })
+
+  it('rejects empty and drive-prefixed custom generated names', async () => {
+    const directory = path.join(tempRoot, 'uploads')
+
+    const emptyNameStorage = new LocalStorage({
+      directory,
+      nameStrategy: 'custom',
+      nameGenerator: async () => '   '
+    })
+    await assert.rejects(
+      emptyNameStorage.upload(createFile()),
+      /Custom nameGenerator must return a non-empty basename/
+    )
+
+    const driveNameStorage = new LocalStorage({
+      directory,
+      nameStrategy: 'custom',
+      nameGenerator: async () => 'C:evil'
+    })
+    await assert.rejects(
+      driveNameStorage.upload(createFile()),
+      /Custom nameGenerator must return a basename, not a path/
+    )
+  })
+
+  it('keeps safe custom basenames inside the configured directory', async () => {
+    const directory = path.join(tempRoot, 'uploads')
+    const storage = new LocalStorage({
+      directory,
+      fileBaseUrl: '/uploads',
+      nameStrategy: 'custom',
+      nameGenerator: async () => 'avatar'
+    })
+
+    const firstUrl = await storage.upload(createFile())
+    const secondUrl = await storage.upload(createFile())
+
+    assert.equal(firstUrl, '/uploads/avatar.png')
+    assert.equal(secondUrl, '/uploads/avatar_1.png')
+    assert.equal(await fs.readFile(path.join(directory, 'avatar.png'), 'utf8'), 'x')
+    assert.equal(await fs.readFile(path.join(directory, 'avatar_1.png'), 'utf8'), 'x')
+  })
+})

package/tests/pagination-cursor-multifield.test.js

@@ -7,6 +7,7 @@ import {
   createJsonApiDocument
 } from './helpers/test-utils.js'
 import { createCursorPaginationApi } from './fixtures/api-configs.js'
+import { storageMode } from './helpers/storage-mode.js'
 
 // Create Knex instance for tests
 const knex = knexLib({
@@ -19,6 +20,19 @@ const knex = knexLib({
 
 // API instance that persists across tests
 let api
+const anyapiIt = storageMode.isAnyApi() ? it : it.skip
+
+async function countAnyRecords (resource) {
+  const result = await knex('any_records')
+    .where({
+      tenant_id: api.anyapi.tenantId,
+      resource
+    })
+    .count('* as count')
+    .first()
+
+  return Number(result?.count ?? 0)
+}
 
 describe('Multi-field Cursor Pagination', () => {
   before(async () => {
@@ -31,6 +45,43 @@ describe('Multi-field Cursor Pagination', () => {
     await knex.destroy()
   })
 
+  anyapiIt('cleans cursor fixture records from AnyAPI canonical storage', async () => {
+    await cleanTables(knex, ['cursor_products', 'cursor_items'])
+
+    await api.resources.products.post({
+      inputRecord: createJsonApiDocument('products', {
+        name: 'Cleanup Product',
+        category: 'Cleanup',
+        brand: 'Fixture',
+        price: 10,
+        sku: 'CLEAN-001'
+      }),
+      simplified: false
+    })
+
+    await api.resources.items.post({
+      inputRecord: createJsonApiDocument('items', {
+        code: 'CLEAN',
+        name: 'Cleanup Item',
+        category: 'Cleanup',
+        type: 'fixture'
+      }),
+      simplified: false
+    })
+
+    assert.equal(await countAnyRecords('products'), 1)
+    assert.equal(await countAnyRecords('items'), 1)
+
+    await cleanTables(knex, ['cursor_products'])
+
+    assert.equal(await countAnyRecords('products'), 0)
+    assert.equal(await countAnyRecords('items'), 1)
+
+    await cleanTables(knex, ['cursor_items'])
+
+    assert.equal(await countAnyRecords('items'), 0)
+  })
+
   describe('Basic Multi-field Cursor Pagination', () => {
     beforeEach(async () => {
       await cleanTables(knex, ['cursor_products'])
@@ -222,6 +273,76 @@ describe('Multi-field Cursor Pagination', () => {
         'Prices should be non-decreasing across pages')
     })
 
+    it('should advance when sorting by logical camelCase fields backed by snake_case storage columns', async () => {
+      await cleanTables(knex, ['cursor_products'])
+
+      const products = [
+        {
+          name: 'Newest Product',
+          category: 'Catalog',
+          brand: 'Acme',
+          price: 10,
+          sku: 'CAMEL-001',
+          createdAt: '2026-05-03T10:00:00.000Z'
+        },
+        {
+          name: 'Recent Product',
+          category: 'Catalog',
+          brand: 'Acme',
+          price: 20,
+          sku: 'CAMEL-002',
+          createdAt: '2026-05-03T09:00:00.000Z'
+        },
+        {
+          name: 'Older Product',
+          category: 'Catalog',
+          brand: 'Acme',
+          price: 30,
+          sku: 'CAMEL-003',
+          createdAt: '2026-05-03T08:00:00.000Z'
+        }
+      ]
+
+      for (const product of products) {
+        await api.resources.products.post({
+          inputRecord: createJsonApiDocument('products', product),
+          simplified: false
+        })
+      }
+
+      const firstPage = await api.resources.products.query({
+        queryParams: {
+          page: { size: 2 },
+          sort: ['-createdAt']
+        },
+        simplified: false
+      })
+
+      assert.equal(firstPage.data.length, 2)
+      assert.equal(firstPage.meta.pagination.cursor?.next.includes('createdAt:'), true,
+        'Cursor should include the logical createdAt field')
+
+      const secondPage = await api.resources.products.query({
+        queryParams: {
+          page: {
+            size: 2,
+            after: firstPage.meta.pagination.cursor.next
+          },
+          sort: ['-createdAt']
+        },
+        simplified: false
+      })
+
+      assert.deepEqual(
+        firstPage.data.map((record) => record.attributes.name),
+        ['Newest Product', 'Recent Product']
+      )
+      assert.deepEqual(
+        secondPage.data.map((record) => record.attributes.name),
+        ['Older Product']
+      )
+    })
+
     it('should generate correct cursor values for multi-field sorting', async () => {
       const result = await api.resources.products.query({
         queryParams: {

package/tests/pagination-enhanced.test.js

@@ -9,6 +9,7 @@ import {
   resourceIdentifier
 } from './helpers/test-utils.js'
 import { createPaginationApi } from './fixtures/api-configs.js'
+import { parseJsonApiQuery } from '../plugins/core/lib/querying-writing/connectors-query-parser.js'
 
 // Create Knex instance for tests
 const knex = knexLib({
@@ -22,6 +23,11 @@ const knex = knexLib({
 // API instance that persists across tests
 let api
 
+const parseLinkQuery = (link) => {
+  const url = new URL(link, 'https://example.test')
+  return parseJsonApiQuery(url.search.slice(1))
+}
+
 describe('Enhanced Pagination Features', () => {
   before(async () => {
     // Initialize API once with pagination features
@@ -34,6 +40,8 @@ describe('Enhanced Pagination Features', () => {
   })
 
   describe('Self Links', () => {
+    let countryId
+
     beforeEach(async () => {
       await cleanTables(knex, [
         'pagination_countries', 'pagination_publishers', 'pagination_books'
@@ -45,6 +53,7 @@ describe('Enhanced Pagination Features', () => {
         inputRecord: countryDoc,
         simplified: false
       })
+      countryId = countryResult.data.id
 
       // Create some books
       for (let i = 1; i <= 3; i++) {
@@ -131,6 +140,38 @@ describe('Enhanced Pagination Features', () => {
       assert(result.links, 'Response should have top-level links')
       assert(result.links.self.startsWith('/books'), 'Top-level self link should be relative')
     })
+
+    it('should serialize collection self-link query parameters in JSON:API form', async () => {
+      const result = await api.resources.books.query({
+        queryParams: {
+          filters: {
+            country: countryId
+          },
+          fields: {
+            books: 'title,country_id',
+            countries: 'name,code'
+          },
+          include: ['country'],
+          sort: ['title']
+        },
+        simplified: false
+      })
+
+      validateJsonApiStructure(result, true)
+
+      const selfUrl = new URL(result.links.self, 'https://example.test')
+      const selfQuery = parseLinkQuery(result.links.self)
+
+      assert.equal(selfUrl.searchParams.get('filter[country]'), countryId)
+      assert.equal(selfUrl.searchParams.has('filters[country]'), false)
+      assert.deepEqual(selfQuery.filters, { country: countryId })
+      assert.deepEqual(selfQuery.include, ['country'])
+      assert.deepEqual(selfQuery.sort, ['title'])
+      assert.deepEqual(selfQuery.fields, {
+        books: 'title,country_id',
+        countries: 'name,code'
+      })
+    })
   })
 
   describe('Pagination Metadata', () => {
@@ -207,13 +248,11 @@ describe('Enhanced Pagination Features', () => {
       assert(result.links.prev, 'Should have prev link')
       assert(result.links.next, 'Should have next link')
 
-      // Verify link structure
-      assert(result.links.self.includes('page[number]=2'))
-      assert(result.links.self.includes('page[size]=3'))
-      assert(result.links.first.includes('page[number]=1'))
-      assert(result.links.last.includes('page[number]=4'))
-      assert(result.links.prev.includes('page[number]=1'))
-      assert(result.links.next.includes('page[number]=3'))
+      assert.deepEqual(parseLinkQuery(result.links.self).page, { number: 2, size: 3 })
+      assert.deepEqual(parseLinkQuery(result.links.first).page, { number: 1, size: 3 })
+      assert.deepEqual(parseLinkQuery(result.links.last).page, { number: 4, size: 3 })
+      assert.deepEqual(parseLinkQuery(result.links.prev).page, { number: 1, size: 3 })
+      assert.deepEqual(parseLinkQuery(result.links.next).page, { number: 3, size: 3 })
     })
 
     it('should not include prev link on first page', async () => {
@@ -253,9 +292,9 @@ describe('Enhanced Pagination Features', () => {
 
       assert(result.links, 'Should have links')
       assert(result.links.next, 'Should have next link since page 2 of 4')
-      assert(result.links.next.includes('sort=-title'))
-      assert(result.links.next.includes('page[number]=3'))
-      assert(result.links.next.includes('page[size]=3'))
+      const nextQuery = parseLinkQuery(result.links.next)
+      assert.deepEqual(nextQuery.sort, ['-title'])
+      assert.deepEqual(nextQuery.page, { number: 3, size: 3 })
     })
   })
 
@@ -335,7 +374,7 @@ describe('Enhanced Pagination Features', () => {
       assert(result.links.self)
       assert(result.links.first)
       assert(result.links.next)
-      assert(result.links.next.includes('page[after]='), 'Next link should include cursor parameter')
+      assert(parseLinkQuery(result.links.next).page.after, 'Next link should include cursor parameter')
     })
 
     it('should handle last page with cursor pagination', async () => {
@@ -476,6 +515,10 @@ describe('Enhanced Pagination Features', () => {
           filters: {
             country: parseInt(usCountryId)
           },
+          fields: {
+            books: 'title,country_id',
+            countries: 'name,code'
+          },
           include: ['country'],
           sort: ['title']
         },
@@ -503,10 +546,18 @@ describe('Enhanced Pagination Features', () => {
         assert(book.links.self)
       })
 
-      // Check pagination links include all parameters
-      assert(result.links.next.includes(`filters[country]=${usCountryId}`))
-      assert(result.links.next.includes('include=country'))
-      assert(result.links.next.includes('sort=title'))
+      const nextUrl = new URL(result.links.next, 'https://example.test')
+      const nextQuery = parseJsonApiQuery(nextUrl.search.slice(1))
+      assert.equal(nextUrl.searchParams.get('filter[country]'), usCountryId)
+      assert.equal(nextUrl.searchParams.has('filters[country]'), false)
+      assert.deepEqual(nextQuery.filters, { country: usCountryId })
+      assert.deepEqual(nextQuery.include, ['country'])
+      assert.deepEqual(nextQuery.sort, ['title'])
+      assert.deepEqual(nextQuery.fields, {
+        books: 'title,country_id',
+        countries: 'name,code'
+      })
+      assert.deepEqual(nextQuery.page, { number: 2, size: 5 })
     })
   })
 })