Separate Zapier, web, API, and leaf access planes with NATS authz

Zapier is one ingress. Direct web, customer API, and S2S leaf nodes are their own services. Every hop to an internal subject must pass verae.access.authz.check (default deny by plane).

packages/verae-access-authz/src/client.js

@@ -0,0 +1,38 @@
+/** Call verae.access.authz.check then the internal subject. Fail closed. */
+import { SUBJECTS } from './subjects.js';
+
+export async function authorizeThenRequest(nc, sc, { plane, subject, principal, payload, timeout = 2000 }) {
+  const kind = payload?.kind;
+  const checkMsg = await nc.request(
+    SUBJECTS.AUTHZ_CHECK,
+    sc.encode(JSON.stringify({ plane, subject, principal, kind, payload })),
+    { timeout },
+  );
+  const decision = JSON.parse(sc.decode(checkMsg.data) || '{}');
+  if (!decision.allow) {
+    const err = new Error(decision.reason || 'denied');
+    err.decision = decision;
+    throw err;
+  }
+  const internal = decision.subject;
+  const body = { ...payload, plane, principal, traceId: payload?.traceId };
+  const m = await nc.request(internal, sc.encode(JSON.stringify(body)), { timeout });
+  return { decision, body: JSON.parse(sc.decode(m.data) || '{}') };
+}
+
+export async function authorizeThenPublish(nc, sc, { plane, subject, principal, payload, timeout = 2000 }) {
+  const kind = payload?.kind;
+  const checkMsg = await nc.request(
+    SUBJECTS.AUTHZ_CHECK,
+    sc.encode(JSON.stringify({ plane, subject, principal, kind, payload })),
+    { timeout },
+  );
+  const decision = JSON.parse(sc.decode(checkMsg.data) || '{}');
+  if (!decision.allow) {
+    const err = new Error(decision.reason || 'denied');
+    err.decision = decision;
+    throw err;
+  }
+  nc.publish(decision.subject, sc.encode(JSON.stringify({ ...payload, plane, principal })));
+  return { decision };
+}

packages/verae-access-authz/src/policy.js

@@ -0,0 +1,98 @@
+import { PLANES, parseAddress } from './subjects.js';
+
+/**
+ * Default-deny. Each access plane may only touch listed internal prefixes.
+ * Internal workers (poller, WORM, account-balance) are not planes; they
+ * already sit on the private bus. This policy gates *ingress*.
+ */
+export const POLICY = Object.freeze({
+  zapier: {
+    title: 'Zapier Platform (HTTPS only; never a NATS client)',
+    allow: [
+      'verae.zapier.jobs.watch',
+      'verae.zapier.jobs.events',
+      'verae.zapier.webhooks.deliver',
+      'verae.billing.usage.recorded',
+    ],
+  },
+  web: {
+    title: 'Direct customer web (portal browser)',
+    allow: [
+      'verae.billing.statement.get',
+      'verae.billing.balance.adjust',
+      'verae.billing.payment.recorded',
+    ],
+    adjustKinds: ['payment', 'reload'],
+  },
+  api: {
+    title: 'Direct customer API (x-api-key, not Zapier)',
+    allow: ['verae.billing.statement.get', 'verae.billing.usage.recorded', 'verae.zapier.jobs.watch'],
+  },
+  leaf: {
+    title: 'Server-to-server NATS leaf / mTLS',
+    allow: [
+      'verae.archive.put',
+      'verae.archive.query',
+      'verae.archive.reply.',
+      'verae.zapier.jobs.watch',
+      'verae.zapier.jobs.events',
+      'verae.zapier.webhooks.deliver',
+    ],
+  },
+  staff: {
+    title: 'CS / sales / admin / accounting web',
+    allow: [
+      'verae.billing.statement.get',
+      'verae.billing.balance.get',
+      'verae.billing.balance.adjust',
+      'verae.billing.credit.applied',
+      'verae.billing.payment.recorded',
+    ],
+  },
+});
+
+function prefixAllowed(allow, subject) {
+  return allow.some((p) => (p.endsWith('.') ? subject.startsWith(p) : subject === p || subject.startsWith(`${p}.`)));
+}
+
+/**
+ * @param {{ plane: string, subject: string, kind?: string, principal?: string }} req
+ */
+export function authorize(req) {
+  const plane = String(req?.plane || '');
+  const parsed = parseAddress(req?.subject, plane);
+  if (parsed.authz) {
+    return deny(plane, req?.subject, 'authz subjects are not forwardable');
+  }
+  if (!PLANES.includes(plane)) {
+    return deny(plane, parsed.internal, `unknown access plane`);
+  }
+  if (parsed.plane && parsed.plane !== plane) {
+    return deny(plane, parsed.internal, `plane mismatch (address is ${parsed.plane})`);
+  }
+  const internal = parsed.internal;
+  if (!internal.startsWith('verae.') || internal.startsWith('verae.access.')) {
+    return deny(plane, internal, 'not an internal verae.* subject');
+  }
+  const rule = POLICY[plane];
+  if (!prefixAllowed(rule.allow, internal)) {
+    return deny(plane, internal, `${plane} cannot reach ${internal}`);
+  }
+  if (internal === 'verae.billing.balance.adjust' && rule.adjustKinds) {
+    const kind = req?.kind || req?.payload?.kind;
+    if (kind && !rule.adjustKinds.includes(kind)) {
+      return deny(plane, internal, `${plane} cannot adjust kind=${kind}`);
+    }
+  }
+  return {
+    allow: true,
+    plane,
+    subject: internal,
+    principal: req?.principal || null,
+    reason: 'ok',
+  };
+}
+
+function deny(plane, subject, reason) {
+  return { allow: false, plane: plane || null, subject: subject || null, reason };
+}

packages/verae-access-authz/src/server.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import http from 'node:http';
+import { authorize, POLICY } from './policy.js';
+import { PLANES, SUBJECTS } from './subjects.js';
+
+const PORT = Number(process.env.PORT || process.env.FLEET_HEALTH_PORT || 3020);
+const BIND = process.env.FLEET_HEALTH_BIND || '0.0.0.0';
+let natsOk = false;
+
+async function startNats() {
+  const url = process.env.NATS_URL;
+  if (!url) return;
+  const { connect, StringCodec } = await import('nats');
+  const nc = await connect({ servers: url.split(','), name: 'verae-access-authz' });
+  const sc = StringCodec();
+  const sub = nc.subscribe(SUBJECTS.AUTHZ_CHECK, { queue: SUBJECTS.QUEUE });
+  (async () => {
+    for await (const m of sub) {
+      let payload = {};
+      try {
+        payload = JSON.parse(sc.decode(m.data) || '{}');
+      } catch {
+        payload = {};
+      }
+      const out = authorize(payload);
+      if (!out.allow && m.reply) {
+        nc.publish(SUBJECTS.AUTHZ_DENY, sc.encode(JSON.stringify({ ...out, at: new Date().toISOString() })));
+      }
+      if (m.reply) m.respond(sc.encode(JSON.stringify(out)));
+    }
+  })();
+  natsOk = true;
+  process.stdout.write(`access-authz nats ${url}\n`);
+}
+
+function readBody(req) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', () => {
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'));
+      } catch {
+        resolve({});
+      }
+    });
+  });
+}
+
+const server = http.createServer(async (req, res) => {
+  const url = new URL(req.url || '/', `http://127.0.0.1:${PORT}`);
+  const json = (code, obj) => {
+    res.writeHead(code, { 'content-type': 'application/json' });
+    res.end(JSON.stringify(obj));
+  };
+  try {
+    if (req.method === 'GET' && url.pathname === '/health') {
+      return json(200, {
+        ok: true,
+        role: 'verae-access-authz',
+        nats: natsOk,
+        planes: PLANES,
+        subject: SUBJECTS.AUTHZ_CHECK,
+      });
+    }
+    if (req.method === 'GET' && url.pathname === '/policy') {
+      return json(200, { planes: PLANES, policy: POLICY, subjects: SUBJECTS });
+    }
+    if (req.method === 'POST' && url.pathname === '/check') {
+      const body = await readBody(req);
+      const out = authorize(body);
+      return json(out.allow ? 200 : 403, out);
+    }
+    json(404, { error: 'not found' });
+  } catch (err) {
+    json(500, { error: err.message });
+  }
+});
+
+server.listen(PORT, BIND, () => {
+  process.stdout.write(`verae-access-authz http://${BIND}:${PORT}/\n`);
+});
+startNats().catch((err) => process.stderr.write(`nats optional: ${err.message}\n`));

packages/verae-access-authz/src/subjects.js

@@ -0,0 +1,36 @@
+/**
+ * Access planes sit in front of internal verae.<area>.* addresses.
+ * Pattern:
+ *   verae.access.<plane>.<area>.<resource>.<action>   ingress (that plane only)
+ *   verae.access.authz.check                          authorization step
+ *   verae.<area>.<resource>.<action>                  internal (unchanged)
+ */
+export const PLANES = Object.freeze(['zapier', 'web', 'api', 'leaf', 'staff']);
+
+export const SUBJECTS = Object.freeze({
+  AUTHZ_CHECK: 'verae.access.authz.check',
+  AUTHZ_DENY: 'verae.access.authz.deny',
+  QUEUE: 'access-authz',
+  ingress: (plane) => `verae.access.${plane}.in`,
+});
+
+/** verae.billing.statement.get + plane web → verae.access.web.billing.statement.get */
+export function accessAddress(plane, internalSubject) {
+  if (!PLANES.includes(plane)) throw new Error(`unknown plane ${plane}`);
+  if (!internalSubject.startsWith('verae.') || internalSubject.startsWith('verae.access.')) {
+    throw new Error(`not an internal verae.* subject: ${internalSubject}`);
+  }
+  return `verae.access.${plane}.${internalSubject.slice('verae.'.length)}`;
+}
+
+/** Parse an access or internal subject into { plane, internal }. */
+export function parseAddress(subject, planeHint) {
+  const s = String(subject || '');
+  const m = s.match(/^verae\.access\.([a-z]+)\.(.+)$/);
+  if (m) {
+    const plane = m[1];
+    if (plane === 'authz') return { plane: planeHint || null, internal: s, authz: true };
+    return { plane, internal: `verae.${m[2]}`, authz: false };
+  }
+  return { plane: planeHint || null, internal: s, authz: false };
+}