@voxgig/build 4.3.0 → 4.11.0

package/tm/web/backend/test/unit/env/web/api-router.test.ts.frag

@@ -0,0 +1,315 @@
+import { test, describe } from 'node:test'
+import assert from 'node:assert'
+
+import Crypto from 'node:crypto'
+
+import Seneca from 'seneca'
+
+import Model from '../../../../model/model.json'
+import { pickEntity } from '../../srv/api/api.setup'
+
+// The router under test, plus a stub-friendly seneca. The API service and
+// the entity service are stood in for with MOCK MESSAGES, so this covers
+// the HTTP mapping alone: routing, key auth, status codes, result shaping.
+const { apiHandler } = require('../../../../dist/env/web/api.js')
+
+
+// The entity and the base path come from the model, so this suite holds
+// for any entity graph.
+const ENT = pickEntity()
+const API = (Model as any).main.api || {}
+const BASE = '/' + (API.version || 'v1') + '/' + (ENT ? ENT.canon : 'none/none')
+
+const KEY = 'vk_' + 'a'.repeat(48)
+const HASH = Crypto.createHash('sha256').update(KEY).digest('hex')
+
+
+async function makeSeneca(opts: {
+  keys?: any[],          // sys/apikey rows
+  users?: any[],         // sys/user rows
+  onEnt?: (msg: any) => any,
+} = {}) {
+  const seneca = Seneca({ legacy: false, timeout: 2222, debug: { undead: true } })
+  seneca.context.model = Model
+  seneca.test().use('promisify').use('entity')
+
+  seneca.message('aim:api,on:ent', async function (msg: any) {
+    return opts.onEnt ? opts.onEnt(msg) : { ok: true, items: [], item: null }
+  })
+
+  await seneca.ready()
+
+  for (const k of opts.keys || []) {
+    await seneca.entity('sys/apikey').data$(k).save$()
+  }
+  for (const u of opts.users || []) {
+    await seneca.entity('sys/user').data$(u).save$()
+  }
+
+  return seneca
+}
+
+
+// Minimal express-alike req/res.
+function reqres(method: string, path: string, opts: {
+  headers?: Record<string, string>, body?: any, query?: any,
+} = {}) {
+  const req = {
+    method,
+    path,
+    headers: opts.headers || {},
+    body: opts.body,
+    query: opts.query || {},
+  }
+  const res: any = {
+    statusCode: 200,
+    body: undefined as any,
+    sentFile: undefined as any,
+    type() {
+      return res
+    },
+    status(code: number) {
+      res.statusCode = code
+      return res
+    },
+    send(payload: any) {
+      res.body = payload
+      return res
+    },
+    sendFile(p: string) {
+      res.sentFile = p
+      return res
+    },
+  }
+  return { req, res }
+}
+
+
+const authed = { authorization: 'Bearer ' + KEY }
+
+function liveKey() {
+  return [{ id: 'k01', user_id: 'u01', name: 'ci', hash: HASH, revoked: false }]
+}
+function liveUser() {
+  return [{ id: 'u01', email: 'alice@ex.com', name: 'Alice', pass: 'SECRET', salt: 'S' }]
+}
+
+
+describe('rest api router', () => {
+
+  // Every routed case needs an exposed entity to address.
+  const needEnt = (t: any) => (ENT ? false : (t.skip('model exposes no entities'), true))
+
+
+  test('serves the generated openapi spec unauthenticated', async () => {
+    const seneca = await makeSeneca()
+    const handle = apiHandler(seneca, Model)
+
+    const { req, res } = reqres('GET', '/openapi.json')
+    await handle(req, res)
+    assert.ok(String(res.sentFile).endsWith('openapi.json'))
+    await seneca.close()
+  })
+
+
+  test('requires a valid, unrevoked key', async (t) => {
+    if (needEnt(t)) { return }
+    const seneca = await makeSeneca({ keys: liveKey(), users: liveUser() })
+    const handle = apiHandler(seneca, Model)
+
+    // No header.
+    let rr = reqres('GET', BASE)
+    await handle(rr.req, rr.res)
+    assert.strictEqual(rr.res.statusCode, 401)
+    assert.strictEqual(rr.res.body.error.code, 'not-authenticated')
+
+    // Malformed header.
+    rr = reqres('GET', BASE, { headers: { authorization: 'Basic xyz' } })
+    await handle(rr.req, rr.res)
+    assert.strictEqual(rr.res.statusCode, 401)
+
+    // Unknown key.
+    rr = reqres('GET', BASE,
+      { headers: { authorization: 'Bearer vk_nope' } })
+    await handle(rr.req, rr.res)
+    assert.strictEqual(rr.res.statusCode, 401)
+
+    // Valid key.
+    rr = reqres('GET', BASE, { headers: authed })
+    await handle(rr.req, rr.res)
+    assert.strictEqual(rr.res.statusCode, 200)
+
+    await seneca.close()
+  })
+
+
+  test('a revoked key fails immediately', async (t) => {
+    if (needEnt(t)) { return }
+    const seneca = await makeSeneca({
+      keys: [{ id: 'k01', user_id: 'u01', hash: HASH, revoked: true }],
+      users: liveUser(),
+    })
+    const handle = apiHandler(seneca, Model)
+
+    const { req, res } = reqres('GET', BASE, { headers: authed })
+    await handle(req, res)
+    assert.strictEqual(res.statusCode, 401)
+    await seneca.close()
+  })
+
+
+  test('a key whose user is gone fails', async (t) => {
+    if (needEnt(t)) { return }
+    const seneca = await makeSeneca({ keys: liveKey() })
+    const handle = apiHandler(seneca, Model)
+
+    const { req, res } = reqres('GET', BASE, { headers: authed })
+    await handle(req, res)
+    assert.strictEqual(res.statusCode, 401)
+    await seneca.close()
+  })
+
+
+  test('maps methods and paths onto api operations', async (t) => {
+    if (needEnt(t)) { return }
+    const seen: any[] = []
+    const seneca = await makeSeneca({
+      keys: liveKey(), users: liveUser(),
+      onEnt: (msg: any) => {
+        seen.push({ op: msg.op, ent: msg.ent, id: msg.id, data: msg.data, q: msg.q })
+        return 'remove' === msg.op ? { ok: true, id: msg.id }
+          : 'list' === msg.op ? { ok: true, items: [{ id: 'p01' }] }
+            : { ok: true, item: { id: msg.id || 'p01' } }
+      },
+    })
+    const handle = apiHandler(seneca, Model)
+
+    let rr = reqres('GET', BASE, { headers: authed, query: { name: 'x' } })
+    await handle(rr.req, rr.res)
+    assert.strictEqual(rr.res.statusCode, 200)
+    assert.deepStrictEqual(rr.res.body.items, [{ id: 'p01' }])
+    assert.deepStrictEqual(seen[0], {
+      op: 'list', ent: ENT!.canon, id: undefined, data: undefined, q: { name: 'x' },
+    })
+
+    rr = reqres('GET', BASE + '/p01', { headers: authed })
+    await handle(rr.req, rr.res)
+    assert.strictEqual(seen[1].op, 'load')
+    assert.strictEqual(seen[1].id, 'p01')
+
+    rr = reqres('POST', BASE, { headers: authed, body: { name: 'New' } })
+    await handle(rr.req, rr.res)
+    // Creation answers 201.
+    assert.strictEqual(rr.res.statusCode, 201)
+    assert.strictEqual(seen[2].op, 'create')
+    assert.deepStrictEqual(seen[2].data, { name: 'New' })
+
+    rr = reqres('PUT', BASE + '/p01', { headers: authed, body: { note: 'n' } })
+    await handle(rr.req, rr.res)
+    assert.strictEqual(seen[3].op, 'update')
+
+    rr = reqres('DELETE', BASE + '/p01', { headers: authed })
+    await handle(rr.req, rr.res)
+    assert.strictEqual(seen[4].op, 'remove')
+    assert.deepStrictEqual(rr.res.body, { ok: true, id: 'p01' })
+
+    await seneca.close()
+  })
+
+
+  test('rejects unroutable paths and method/path combinations', async (t) => {
+    if (needEnt(t)) { return }
+    const seneca = await makeSeneca({ keys: liveKey(), users: liveUser() })
+    const handle = apiHandler(seneca, Model)
+
+    // Wrong version, too short, too long.
+    for (const p of ['/v9/a/b', '/v1/a', '/v1/a/b/c/d']) {
+      const rr = reqres('GET', p, { headers: authed })
+      await handle(rr.req, rr.res)
+      assert.strictEqual(rr.res.statusCode, 404, p)
+    }
+
+    // POST to an id path, PUT/DELETE to a collection path.
+    for (const [m, p] of [['POST', BASE + '/p01'],
+    ['PUT', BASE], ['DELETE', BASE]]) {
+      const rr = reqres(m, p, { headers: authed })
+      await handle(rr.req, rr.res)
+      assert.strictEqual(rr.res.statusCode, 405, m + ' ' + p)
+    }
+
+    await seneca.close()
+  })
+
+
+  test('maps service failures onto http status codes', async (t) => {
+    if (needEnt(t)) { return }
+    const cases: [string, number][] = [
+      ['unknown-entity', 404],
+      ['not-found', 404],
+      ['forbidden', 403],
+      ['invalid-data', 400],
+      ['project-required', 400],
+      ['read-only', 405],
+      ['not-authenticated', 401],
+      ['something-else', 500],
+    ]
+
+    for (const [why, status] of cases) {
+      const seneca = await makeSeneca({
+        keys: liveKey(), users: liveUser(),
+        onEnt: () => ({ ok: false, why, message: 'nope', details: [{ path: 'x' }] }),
+      })
+      const handle = apiHandler(seneca, Model)
+
+      const { req, res } = reqres('GET', BASE, { headers: authed })
+      await handle(req, res)
+      assert.strictEqual(res.statusCode, status, why)
+      assert.strictEqual(res.body.error.code, why)
+      assert.strictEqual(res.body.error.message, 'nope')
+      assert.ok(res.body.error.details)
+      await seneca.close()
+    }
+  })
+
+
+  test('an unexpected error becomes a 500', async (t) => {
+    if (needEnt(t)) { return }
+    const seneca = await makeSeneca({
+      keys: liveKey(), users: liveUser(),
+      onEnt: () => {
+        throw new Error('boom')
+      },
+    })
+    const handle = apiHandler(seneca, Model)
+
+    const { req, res } = reqres('GET', BASE, { headers: authed })
+    await handle(req, res)
+    assert.strictEqual(res.statusCode, 500)
+    assert.strictEqual(res.body.error.code, 'error')
+    await seneca.close()
+  })
+
+
+  test('the principal never carries credentials', async (t) => {
+    if (needEnt(t)) { return }
+    let principal: any = null
+    const seneca = await makeSeneca({
+      keys: liveKey(), users: liveUser(),
+      onEnt: (msg: any) => {
+        principal = msg.custom$.principal.user
+        return { ok: true, items: [] }
+      },
+    })
+    const handle = apiHandler(seneca, Model)
+
+    const { req, res } = reqres('GET', BASE, { headers: authed })
+    await handle(req, res)
+
+    assert.strictEqual(principal.id, 'u01')
+    assert.strictEqual(principal.email, 'alice@ex.com')
+    assert.strictEqual(principal.pass, undefined)
+    assert.strictEqual(principal.salt, undefined)
+    await seneca.close()
+  })
+})
+

package/tm/web/backend/test/unit/env/web/surface.test.ts.frag

@@ -0,0 +1,109 @@
+import { test, describe } from 'node:test'
+import assert from 'node:assert'
+
+import Model from '../../../../model/model.json'
+
+
+// THE BROWSER SURFACE.
+//
+// A browser may only send aim:web messages: the gateway allow-list in
+// src/env/web/web.ts names that one namespace, and every message the SPA
+// sends is declared in the model as an aim:web proxy that forwards to the
+// real service message. These tests pin that contract from the model
+// itself, so widening the surface cannot pass unnoticed.
+
+const MSG: any = (Model as any).main.msg.aim
+const SRV: any = (Model as any).main.srv
+
+
+// Every leaf message pattern under a subtree.
+function leaves(node: any, path: string[] = []): string[][] {
+  const keys = Object.keys(node || {}).filter((k) => '$' !== k)
+  if (0 === keys.length) {
+    return [path]
+  }
+  const out: string[][] = []
+  for (const k of keys) {
+    if (node[k] && 'object' === typeof node[k]) {
+      out.push(...leaves(node[k], [...path, k]))
+    }
+  }
+  return out
+}
+
+
+describe('browser surface', () => {
+
+  test('the gateway allows aim:web and nothing else', () => {
+    const src = require('node:fs').readFileSync(
+      __dirname + '/../../../../src/env/web/web.ts', 'utf8')
+
+    // The allow-list is a literal so it can be read off the source and
+    // reviewed: no computed expansion over the service list.
+    const m = src.match(/allow:\s*\{([^}]*)\}/)
+    assert.ok(m, 'gateway allow-list not found')
+    const keys = m[1].match(/'([^']+)'/g) || []
+    assert.deepStrictEqual(keys, ["'aim:web'"])
+  })
+
+
+  test('every browser message is a declared aim:web proxy', () => {
+    const web = MSG.web
+    assert.ok(web, 'no aim:web messages declared')
+
+    // Each proxy names the action file that forwards it: proxies are
+    // explicit, never implicit pass-through.
+    for (const path of leaves(web.on || {})) {
+      const node = path.reduce((n: any, k: string) => n[k], web.on)
+      const file = node && node.$ && node.$.file
+      assert.ok(file, 'aim:web,on:' + path.join(',') + ' has no proxy action file')
+      assert.ok(String(file).includes('web_'),
+        'proxy action should be a web_ file: ' + file)
+    }
+  })
+
+
+  test('service namespaces are not part of the browser surface', () => {
+    // Every service in the model owns a message namespace of its own...
+    const services = Object.keys(SRV)
+    assert.ok(0 < services.length)
+    for (const name of services) {
+      assert.ok(MSG[name], 'expected service messages for aim:' + name)
+      // ...which is NOT the browser namespace.
+      assert.notStrictEqual(name, 'web')
+    }
+
+    // ...and no service declares that it accepts the aim:web namespace
+    // wholesale: each names only the proxy subtree it owns.
+    for (const name of Object.keys(SRV)) {
+      const inweb = SRV[name].in && SRV[name].in.aim && SRV[name].in.aim.web
+      if (null == inweb) {
+        continue
+      }
+      assert.deepStrictEqual(Object.keys(inweb), ['on'],
+        'srv ' + name + ' should only claim aim:web,on:<subtree>')
+      const owned = Object.keys(inweb.on)
+      assert.ok(0 < owned.length)
+    }
+  })
+
+
+  test('the entity service is reachable only through its proxies', () => {
+    const ent = MSG.web.on.ent
+    assert.ok(ent, 'no aim:web,on:ent proxies')
+
+    // Every command the generic entity service answers has a proxy, so
+    // the SPA never needs to post aim:ent directly.
+    const commands = Object.keys(MSG.ent.cmd).sort()
+    assert.deepStrictEqual(Object.keys(ent.cmd).sort(), commands)
+  })
+
+
+  test('the REST API namespace is not browser-reachable', () => {
+    // aim:api is the API-key clients' proxy layer, reached through the
+    // REST router - it must not appear in the browser surface.
+    assert.strictEqual(MSG.web.on.api, undefined)
+    assert.ok(MSG.api, 'aim:api messages should still exist for the router')
+  })
+})
+

package/tm/web/backend/test/unit/srv/api/api.setup.ts.frag

@@ -0,0 +1,162 @@
+import Seneca from 'seneca'
+
+import Model from '../../../../model/model.json'
+
+const Expose = require('../../../../dist/srv/api/expose.js')
+
+
+// Seneca with the REST API service loaded from compiled dist/srv.
+//
+// The generic entity service is NOT loaded: it is stood in for with MOCK
+// MESSAGES (see mockEnt below), so these tests exercise the API layer -
+// exposure rules, generated-shape validation, op routing, result shaping -
+// in isolation, with no store and no access control in the way.
+async function makeSeneca(mock?: (seneca: any) => void) {
+  const seneca = Seneca({ legacy: false, timeout: 2222, debug: { undead: true } })
+  seneca.context.model = Model
+  seneca.context.env = 'test'
+
+  seneca.test()
+
+  seneca
+    .use('promisify')
+    .use('reload')
+    .use('../../../../dist/srv/api/api-srv')
+
+  if (mock) {
+    mock(seneca)
+  }
+
+  return seneca.ready()
+}
+
+
+// Stand-in for the generic entity service: records the calls it receives
+// and answers from a simple in-test store.
+function mockEnt(store: Record<string, any[]> = {}) {
+  const calls: any[] = []
+
+  const install = (seneca: any) => {
+    seneca.message('aim:ent,cmd:list', async function (msg: any) {
+      calls.push({ cmd: 'list', ent: msg.ent, q: msg.q })
+      const list = (store[msg.ent] || []).filter((item: any) =>
+        Object.keys(msg.q || {}).every((k) => item[k] === msg.q[k]))
+      return { ok: true, list }
+    })
+
+    seneca.message('aim:ent,cmd:load', async function (msg: any) {
+      calls.push({ cmd: 'load', ent: msg.ent, id: msg.id })
+      const item = (store[msg.ent] || []).find((i: any) => i.id === msg.id)
+      return { ok: true, item: item || null }
+    })
+
+    seneca.message('aim:ent,cmd:save', async function (msg: any) {
+      calls.push({ cmd: 'save', ent: msg.ent, item: msg.item })
+      const item = Object.assign({ id: msg.item.id || 'new01' }, msg.item)
+      store[msg.ent] = (store[msg.ent] || []).filter((i: any) => i.id !== item.id)
+      store[msg.ent].push(item)
+      return { ok: true, item }
+    })
+
+    seneca.message('aim:ent,cmd:remove', async function (msg: any) {
+      calls.push({ cmd: 'remove', ent: msg.ent, id: msg.id })
+      store[msg.ent] = (store[msg.ent] || []).filter((i: any) => i.id !== msg.id)
+      return { ok: true, id: msg.id }
+    })
+  }
+
+  return { install, calls, store }
+}
+
+
+// Post an API message AS a given user (the router resolves the principal
+// from the API key and passes it the same way).
+function as(seneca: any, user: any, msg: any) {
+  return seneca.post(Object.assign({}, msg, {
+    custom$: { principal: { user } },
+  }))
+}
+
+
+// ---- model-driven test subject -----------------------------------------
+//
+// These tests must hold for ANY model, so the entity under test and the
+// payloads are derived from the model rather than hard-coded.
+
+// Fields the server owns: never client-writable.
+const MANAGED = ['id', 'owner_id', 't_c', 't_m']
+
+const SAMPLE: Record<string, any> = {
+  String: 'test-value',
+  Number: 42,
+  Boolean: true,
+}
+
+// The wrong type to send for a given kind (to trip validation).
+const WRONG: Record<string, any> = {
+  String: 123,
+  Number: 'not-a-number',
+  Boolean: 'not-a-boolean',
+}
+
+
+// Pick an entity the API exposes, with everything a test needs to build
+// valid and invalid payloads for it. Returns null for a model with no
+// exposed entities (a brand new project).
+function pickEntity() {
+  const canons: string[] = Expose.exposedCanons(Model)
+  if (0 === canons.length) {
+    return null
+  }
+
+  const canon = canons[0]
+  const [zone, name] = canon.split('/')
+  const fields = ((Model as any).main.ent[zone][name] || {}).field || {}
+
+  const writable = Object.keys(fields).filter((f) => !MANAGED.includes(f))
+  const required = writable.filter((f) => {
+    const valid = null == fields[f].valid ? '' : String(fields[f].valid)
+    return !/Skip/.test(valid)
+  })
+
+  const kindOf = (f: string) =>
+    ['String', 'Number', 'Boolean'].includes(fields[f].kind) ? fields[f].kind : 'String'
+
+  // A minimal valid payload: every required field, nothing else.
+  const valid = () => required.reduce((a: any, f: string) =>
+    (a[f] = SAMPLE[kindOf(f)], a), {} as any)
+
+  // A payload with one field of the wrong type, when the entity has a
+  // field whose kind can be violated unambiguously.
+  const typed = writable.find((f) => 'Number' === kindOf(f) || 'Boolean' === kindOf(f))
+  const wrongType = () => {
+    if (null == typed) {
+      return null
+    }
+    return Object.assign(valid(), { [typed]: WRONG[kindOf(typed)] })
+  }
+
+  // A VALID value for a field that differs from what valid() sets, so a
+  // partial update is observable.
+  const patchValue = (f: string) => {
+    const kind = kindOf(f)
+    return 'String' === kind ? 'changed-value'
+      : 'Number' === kind ? 99
+        : false
+  }
+
+  return {
+    canon, zone, name, fields, writable, required,
+    valid, wrongType, kindOf, patchValue,
+  }
+}
+
+
+export {
+  makeSeneca,
+  mockEnt,
+  as,
+  pickEntity,
+  Model,
+}
+