offline / test (push) Waiting to run

Details

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).

2026-09-11 16:05:05 -04:00

6 KiB

Raw Blame History

Modules and NATS message contracts

Master map of every service in the Zapier ↔ middleware ↔ chain ↔ WORM-archive path.

Zapier cloud never connects to NATS. Internal services do: middleware workers, archives, account-balance, zappier-edge billing, CS, sales, and accounting.

Who talks to whom (HTTPS vs NATS)

[Zapier Platform app]  HTTPS  [zappier-edge]  HTTPS  [middleware-http]
        |                     | NATS verae.billing.*          |
        |                     v                               |
[customer portal]      [account-balance]                 NATS JetStream
[CS :3011]             queue account-balance             (NS1 loopback :4222)
[sales :3012]                 ^                               |
[accounting :3013]            | request-reply                 |
                              +-------------------------------+
          +------------------+------------------+-------------+
          |                  |                  |
   [job-poller]      [webhook-deliver]   [archive-aggregator]
          |                                     |
          | HTTPS                               | NATS query/reply
   [verae-chain-client]                         |
                                          [archive-worm × N]
                                          bloom miss = silence

Module catalog

Module	Repo (Forgejo)	Runtime	Listens	Sends
zapier-platform-app	`verae-zapier-app`	Zapier cloud	User Zap steps	HTTPS to zappier-edge
zappier-edge	`zappier-edge`	Public HTTPS :3000	Zapier, portal, admin	HTTPS to middleware; NATS billing after authz
access-authz	`verae-access-authz`	:3020 + NATS	`verae.access.authz.check`	allow/deny
access-web	`verae-access-web`	:3021	customer browser	billing statement/reload
access-api	`verae-access-api`	:3022	x-api-key	statement; HTTPS to middleware
access-leaf	`verae-access-leaf`	:3023	S2S leaf	archive/jobs only
access-zapier	`verae-access-zapier`	:3024	Zapier HTTPS	jobs.watch after authz
account-balance	`zappier-account-balance`	:3010 + NATS	`verae.billing.*`	statement/adjust replies
customer-service	`zappier-customer-service`	:3011	CS staff HTTP	NATS balance.adjust / statement.get
sales-pricing	`zappier-sales-pricing`	:3012	Sales HTTP	NATS statement.get; HTTPS to edge for multipliers
accounting-export	`zappier-accounting-export`	:3013	Accounting HTTP	reads invoices; NATS statement
middleware-http	`verae-middleware`	Public HTTPS :3100	zappier-edge	NATS jobs.watch; HTTP to chain; wait on jobs.events
job-poller	`verae-job-poller`	Worker	`verae.zapier.jobs.watch`	`verae.zapier.jobs.events`; HTTP GET chain status
webhook-deliver	`verae-webhook-deliver`	Worker	`verae.zapier.webhooks.deliver` + events	HTTPS POST Zapier REST Hook
request-splitter	`verae-request-splitter`	In middleware	HTTP body / multipart	chain hash; `verae.archive.put`
archive-aggregator	`verae-archive-aggregator`	Worker / in wait	`includeAttached` on wait	`verae.archive.query`; reads `verae.archive.reply.<id>`
archive-worm	`verae-archive-worm`	N copies	`verae.archive.query`, `verae.archive.put`	`verae.archive.reply.<id>` if bloom hits
tree-node	`verae-tree-node`	N copies (WORM role)	`verae.archive.query`, `verae.archive.put` kind `tree`	`verae.archive.reply.<id>` if bloom hits
zapier-simulator	`verae-zapier-simulator`	Local HTTP :3847	operator browser	in-process replay of all addresses
zapier-user-docs	`zapier-user-docs`	Static	—	catalog `/user-docs/`
verae-chain-client	`verae-chain-client`	Library	—	HTTPS `api.veraetime.net` or MOCK
fleet	`verae-fleet`	Local HTTP :3850	operator	keepFloor + SSH hosts
overview	`overview`	Static	—	high-level map
nats-process	`verae-nats-process`	Template worker	`verae.example.process.in`	`.out` / `.reply.*`
docs-master	`zapier-docs-master`	Static	—	published on zapier.georgelambert.org

Addresses (subjects)

Address	Kind	Payload (required fields)
`verae.zapier.jobs.watch`	JetStream work queue	`tenantId`, `jobId`, `tokenRef`, `enqueuedAt`, `attempt`, `maxAttempts`, `intervalMs`, `traceId`
`verae.zapier.jobs.events`	JetStream events	`event` (`timestamp.completed\|failed\|timeout`), `tenantId`, `jobId`, `status`, `traceId`, `emittedAt`
`verae.zapier.webhooks.deliver`	JetStream work queue	`hookId`, `tenantId`, `targetUrl`, `event`, `payload`, `attempt`, `traceId`
`verae.zapier.usage`	optional	`tenantId`, `action`, `amount`, `at`
`verae.billing.statement.get`	request-reply	`customerId` → prepaid, credits, usage, payments
`verae.billing.balance.adjust`	request-reply	`customerId`, `cents`, `reason`, `agent`
`verae.billing.usage.recorded`	pub	meter events from zappier-edge
`verae.billing.payment.recorded`	pub	portal reload / invoice paid
`verae.billing.credit.applied`	pub	CS goodwill
`verae.access.authz.check`	request-reply	`{ plane, subject, principal }` → `{ allow, reason }`
`verae.access.web.billing.statement.get`	ingress	web plane only; mapped after authz
`verae.access.api.*`	ingress	customer API plane
`verae.access.zapier.*`	ingress	Zapier plane
`verae.access.leaf.in`	ingress	S2S leaf; never billing
`verae.archive.put`	JetStream	`sha256`, `tenantId`, `kind` (`publicMeta\|privateMeta\|file\|tree`), `record`, `traceId`
`verae.archive.query`	pub to all archives	`correlationId`, `sha256`, `tenantId`, `kinds[]`, `traceId`
`verae.archive.reply.<correlationId>`	replies	`archiveId`, `sha256`, `records[]`, `traceId`

Completed job JSON (back to Zapier)

See docs/02-architecture/archive-nats.md. Seal receipts from chain; extra receipts and files[] from archive aggregation when includeAttached is true.

6 KiB Raw Blame History Unescape Escape