@voxgig/build 4.4.0 → 4.12.0

package/tm/web/backend/srv/ent/cmd_save.ts.frag

@@ -0,0 +1,141 @@
+import {
+  principalOf, validCanon, scopeOf, projectOf, ownerOf, asOwner, asSystem,
+  stripOwned, isDenied, OWNER_FIELDS,
+} from './access'
+
+// aim:ent,cmd:save  { ent:'zone/name', item:{...} }
+//
+// Create or update. Row-level access is NOT enforced here: the save runs on
+// a delegate carrying custom.sysowner, and @seneca/owner injects the
+// ownership axes on create and refines the query on update - so an update
+// naming a row outside the caller's project simply does not find it.
+// Timestamps (t_c/t_m) are maintained by @seneca/entity-util.
+//
+// What this action must get right is WHICH TENANT the save acts in. On
+// create the payload names it (there is no row to contradict). On update
+// the tenant is read from the STORED row, and the payload's project field
+// is pinned to it. Taking the tenant from the payload would let a caller
+// name a project they DO belong to, pass the membership check, and have
+// owner refine the query by that same project - overwriting someone else's
+// row. This surface therefore does not move rows between projects.
+module.exports = function make_cmd_save() {
+  return async function cmd_save(this: any, msg: any, meta: any) {
+    const seneca = this
+    const model = seneca.context.model
+    const canon = String(msg.ent || '')
+    if (!validCanon(model, canon)) {
+      return { ok: false, why: 'unknown-entity' }
+    }
+    const user = principalOf(meta)
+    if (!user) {
+      return { ok: false, why: 'not-authenticated' }
+    }
+
+    const scope = scopeOf(model, canon)
+    if ('open' === scope.kind) {
+      return { ok: false, why: 'read-only' }
+    }
+
+    const data = Object.assign({}, msg.item)
+
+    // An id naming no existing row is a create with a client-chosen id, not
+    // an update: there is no stored tenant, and nothing to hijack.
+    const found = null == data.id
+      ? null
+      : await asSystem(seneca).entity(canon).load$(data.id)
+
+    let projectId: string | null = null
+
+    if (null == found) {
+      projectId = projectOf(model, canon, msg)
+      if ('scoped' === scope.kind && null == projectId) {
+        return { ok: false, why: 'project-required' }
+      }
+
+      // A client-chosen id must move to `id$`. @seneca/owner takes the
+      // create path only when ent.id is null - with a plain id it treats
+      // the save as an update, finds no row, and fails save-not-found.
+      // `id$` is seneca-entity's "create with this id", so the row still
+      // goes through owner's create path and gets its axes injected.
+      if (null != data.id) {
+        data.id$ = data.id
+        delete data.id
+      }
+    }
+    else if ('project' === scope.kind) {
+      // The project IS the tenant, so updating one acts within itself.
+      projectId = found.id
+    }
+    else if ('scoped' === scope.kind) {
+      const via = (scope as any).via
+      projectId = found[via]
+
+      // A scoped row with no stored tenant is an anomaly (orphaned or
+      // legacy data), NOT user-scoped data. Refuse it rather than let
+      // ownerOf fall back to owner-only scoping, which would hand its
+      // creator access outside any project.
+      if (null == projectId) {
+        return { ok: false, why: 'forbidden' }
+      }
+
+      // Pin the tenant to the stored row. `via` is whatever field the
+      // model points at proj/project, so it is NOT necessarily one of the
+      // owner fields stripOwned removes - overwrite it explicitly, or a
+      // model naming it anything but project_id lets the payload move the
+      // row to another project.
+      data[via] = projectId
+    }
+
+    const owner = await ownerOf(seneca, user, projectId)
+    if (null == owner) {
+      return { ok: false, why: 'forbidden' }
+    }
+
+    // The ownership axes come from the delegate, never the payload - a row
+    // loaded by the client carries them, and re-sending them unchanged
+    // would otherwise be read as a claim.
+    stripOwned(data)
+
+    // An update keeps the row's STORED ownership. stripOwned has just
+    // removed the client's copy, and owner injects any axis it finds
+    // null - so without this, one member editing another member's row
+    // silently transfers its owner_id to the editor (the `member` role
+    // relaxes writes on that axis, so the plugin raises no objection).
+    if (null != found) {
+      for (const f of OWNER_FIELDS) {
+        if (null != found[f]) {
+          data[f] = found[f]
+        }
+      }
+    }
+
+    let item: any
+    try {
+      item = await asOwner(seneca, owner).entity(canon).data$(data).save$()
+    }
+    catch (err: any) {
+      if (isDenied(err)) {
+        return { ok: false, why: 'forbidden' }
+      }
+      throw err
+    }
+    if (null == item) {
+      return { ok: false, why: 'forbidden' }
+    }
+
+    // Creating a project makes the creator its first (owner) member. This
+    // is bookkeeping for a project the caller is not yet a member of, so
+    // it cannot run as `member` - see the `system` role in basic.ts.
+    if ('project' === scope.kind && null == found) {
+      await asSystem(seneca).entity('proj/member').data$({
+        project_id: item.id,
+        user_id: user.id,
+        role: 'owner',
+        owner_id: user.id,
+      }).save$()
+    }
+
+    return { ok: true, item }
+  }
+}
+

package/tm/web/backend/srv/ent/ent-srv.ts.frag

@@ -0,0 +1,4 @@
+import { MakeSrv } from '@voxgig/system'
+
+module.exports = MakeSrv('ent', require)
+

package/tm/web/backend/srv/ent/get_info.ts.frag

@@ -0,0 +1,6 @@
+module.exports = function make_get_info() {
+  return async function get_info(this: any, _msg: any) {
+    return { ok: true, srv: 'ent' }
+  }
+}
+

package/tm/web/backend/srv/ent/web_cmd_list.ts.frag

@@ -0,0 +1,17 @@
+// Browser proxy: aim:web,on:ent,cmd:list -> aim:ent,cmd:list
+//
+// aim:web is the only namespace the gateway accepts from a browser, so
+// every entity operation a browser may perform is declared as one of
+// these proxies. The principal the gateway resolved travels with the
+// message (meta.custom), so the real action scopes by membership.
+module.exports = function make_web_cmd_list() {
+  return async function web_cmd_list(this: any, msg: any) {
+    return this.post('aim:ent,cmd:list', {
+      ent: msg.ent,
+      id: msg.id,
+      q: msg.q,
+      item: msg.item,
+    })
+  }
+}
+

package/tm/web/backend/srv/ent/web_cmd_load.ts.frag

@@ -0,0 +1,17 @@
+// Browser proxy: aim:web,on:ent,cmd:load -> aim:ent,cmd:load
+//
+// aim:web is the only namespace the gateway accepts from a browser, so
+// every entity operation a browser may perform is declared as one of
+// these proxies. The principal the gateway resolved travels with the
+// message (meta.custom), so the real action scopes by membership.
+module.exports = function make_web_cmd_load() {
+  return async function web_cmd_load(this: any, msg: any) {
+    return this.post('aim:ent,cmd:load', {
+      ent: msg.ent,
+      id: msg.id,
+      q: msg.q,
+      item: msg.item,
+    })
+  }
+}
+

package/tm/web/backend/srv/ent/web_cmd_remove.ts.frag

@@ -0,0 +1,17 @@
+// Browser proxy: aim:web,on:ent,cmd:remove -> aim:ent,cmd:remove
+//
+// aim:web is the only namespace the gateway accepts from a browser, so
+// every entity operation a browser may perform is declared as one of
+// these proxies. The principal the gateway resolved travels with the
+// message (meta.custom), so the real action scopes by membership.
+module.exports = function make_web_cmd_remove() {
+  return async function web_cmd_remove(this: any, msg: any) {
+    return this.post('aim:ent,cmd:remove', {
+      ent: msg.ent,
+      id: msg.id,
+      q: msg.q,
+      item: msg.item,
+    })
+  }
+}
+

package/tm/web/backend/srv/ent/web_cmd_save.ts.frag

@@ -0,0 +1,17 @@
+// Browser proxy: aim:web,on:ent,cmd:save -> aim:ent,cmd:save
+//
+// aim:web is the only namespace the gateway accepts from a browser, so
+// every entity operation a browser may perform is declared as one of
+// these proxies. The principal the gateway resolved travels with the
+// message (meta.custom), so the real action scopes by membership.
+module.exports = function make_web_cmd_save() {
+  return async function web_cmd_save(this: any, msg: any) {
+    return this.post('aim:ent,cmd:save', {
+      ent: msg.ent,
+      id: msg.id,
+      q: msg.q,
+      item: msg.item,
+    })
+  }
+}
+

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')
+  })
+})
+