dev-overview

Developer map of the Verae Time × Zapier NATS message fabric: what was designed, what is actually running on NS1, how a Zapier timestamp job reaches api.veraetime.net (or the mock) and comes back, and what is still unwired.

Forgejo: https://git.georgelambert.org/marchon/dev-overview
SSH: ssh://git@git.georgelambert.org:2223/marchon/dev-overview.git
Catalog: https://zapier.georgelambert.org/packages/dev-overview/
Date: 2026-09-14

Zapier cloud never connects to NATS. It talks HTTPS to https://zap.zapier.georgelambert.org (access-zapier) then middleware. api.veraetime.net is HTTPS only — middleware is the NATS client.

Contents

Cluster (running)

nats://10.10.10.21:4222,nats://10.10.10.22:4222,nats://10.10.10.23:4222

JetStream streams (replicas=3, file): ZAPIER_JOBS, ZAPIER_EVENTS, ZAPIER_WEBHOOKS, ZAPIER_USAGE, VERAE_ARCHIVE.

Public token-gated client edge (not cluster routes): nats://<token>@70.88.205.138:4222, wss://nats.zapier.georgelambert.org. Do not put this in Zapier.

Sources (other documentation that names routes)

This inventory is compiled from code and from these docs. Do not invent extra verae.* names.

Master maps

Per-package NATS.md (Forgejo module copies also live under docs-master/modules/)

Simulator src/pipeline.js and src/monitors.js list the same product addresses for traces; they are not live subscribers.

Designed vs running NATS routes

Designed = named in docs or in code.
Running = a process on NS1 is subscribed or publishing it today, and (for durable work) a JetStream stream exists.

Cluster name verae. Internal clients use the three LXC on vmbr1. Public edge is a leaf, not a second cluster.

Legend: JS = JetStream stream; RR = core request-reply; pub = core or JS fire-and-forget; Q = queue group.

Transport (TCP / leaf / public)

These are NATS server routes, not verae.* subjects.

Internal keep/fleet/middleware URL:

nats://10.10.10.21:4222,nats://10.10.10.22:4222,nats://10.10.10.23:4222

Public (token in /etc/nats/public-edge.token on NS1): nats://<token>@70.88.205.138:4222. Isolation on the hub is still $G + private LAN. nkeys/mTLS sketched in verae-nats-accounts, not flipped.

JetStream streams (running)

Created by verae-nats-cluster/scripts/ensure-streams.sh (middleware ensureStreams also creates the first three).

Billing is core request-reply / pub, not a JetStream stream.

Address inventory

Plane mapping (verae-access-authz): internal verae.billing.statement.get + plane web → ingress verae.access.web.billing.statement.get. Planes never publish internal subjects until authz.check returns allow.

Durable consumers (named in middleware)

Fleet overlay vs in-process

packages/verae-fleet/overlays/ns1/fleet.json (2026-09-14):

Endpoint I/O

Each product NATS address: what it is for, who sends, who receives, how to attach.

Connect with a long-lived client (reconnect-per-message is the anti-pattern):

NATS_URL=nats://10.10.10.21:4222,nats://10.10.10.22:4222,nats://10.10.10.23:4222

Public edge (token in /etc/nats/public-edge.token on NS1): nats://<token>@70.88.205.138:4222. Do not put that URL in Zapier or in Verae.

verae.zapier.jobs.watch

Payload: tenantId, veraeUserId, jobId, tokenRef, enqueuedAt, attempt, maxAttempts, intervalMs, traceId. JWT stays in middleware (tokenRef); never on Zapier.

Connect Verae-side: do not subscribe this from api.veraetime.net. The poller is the Verae HTTP client. To add another watcher, start another job-poller consumer in the same queue group.

verae.zapier.jobs.events

If JOBS_EVENTS_EXCLUSIVE=1, only verae-jobs-events is the durable consumer and republishes verae.internal.jobs.events. Default lab: middleware wait + webhook worker share the stream.

Payload: event, tenantId, jobId, status, traceId, emittedAt.

verae.zapier.webhooks.deliver

Payload: hookId, tenantId, targetUrl, event, payload, attempt, traceId. Slow consumer: keep replica floors on the worker if you split it out of middleware.

verae.zapier.usage

Prepaid meter that is wired uses verae.billing.usage.recorded (core pub), not this stream. Finish: either publish here from recordUsage or drop the stream.

Billing (verae.billing.*) — account-balance source of truth

Request-reply unless noted. Queue account-balance. Not JetStream.

Authz must pass verae.access.authz.check before these from a public plane. Leaf plane cannot call billing (policy).

Middleware recordUsage still writes local tenant files and does not publish usage.recorded. Two meters until that is unified.

Access planes

Ingress mapping: accessAddress(plane, 'verae.billing.statement.get') → verae.access.<plane>.billing.statement.get.

Identity

Queue identity. Fleet keepFloor.

Archive / tree

Silence = miss. Chain seal does not wait on archive. Bytes never go to the chain.

Template / unused

How to connect Verae API to NATS

api.veraetime.net is HTTPS. It does not subscribe. The glue is middleware:

1. Set VERAE_API_BASE_URL=https://api.veraetime.net and MOCK_VERAE=false.
2. Middleware login (username/password) → JWT stored as tokenRef.
3. POST /api/timestamp → 202 { jobId }.
4. Publish verae.zapier.jobs.watch.
5. Poller GET /api/status/{jobId} until completed / failed.
6. Publish verae.zapier.jobs.events.
7. Wait HTTP and/or REST Hook.

Do not point Verae at NATS_URL. Do not put NATS in Zapier env. A new worker that must see seals uses jobs.events or HTTP GET /zapier/v1/status/{jobId}.

Template for a new addressed process: clone verae-nats-process, rename verae.example.process.*, add the subject to verae-access-authz policy for the plane that may call it.

Zapier → Verae API → Zapier

How a timestamp job is submitted, watched, and returned. Lab today: MOCK_VERAE=true. Live path is the same HTTP contract with MOCK_VERAE=false.

Rule

Zapier cloud  --HTTPS only-->  zap.zapier.georgelambert.org  (access-zapier)
                                    |
                                    v HTTPS
                              middleware :3100 /zapier/v1
                                    |
                    +---------------+----------------+
                    | HTTPS                         | NATS (private cluster)
                    v                               v
            api.veraetime.net              jobs.watch → poller
            POST /api/timestamp            GET /api/status/{jobId}
            GET  /api/status/{jobId}              |
            POST /api/verify                      v
                                           jobs.events
                                              |
                         +--------------------+--------------------+
                         | wait subscriber                         | webhook-deliver
                         v                                         v
                    HTTP response to Zap                    POST hooks.zapier.com

Zapier never has NATS_URL. Verae never has NATS_URL.

1. Submit (async create)

1. Zap action Create Timestamp (or curl) POST https://zap.zapier.georgelambert.org/zapier/v1/timestamp with portal API key zmw_… (not a Verae JWT).
2. access-zapier / edge: authz, then meter() records cents; if NATS_URL is set, natsPublish(verae.billing.usage.recorded).
3. Forwards to middleware POST /zapier/v1/timestamp.
4. Middleware checkEntitlement (local plan limits today).
5. veraeClient.createTimestamp:
   • Mock: in-process job, fake jobId.
   • Live: POST https://api.veraetime.net/api/timestamp with JWT → 202 { jobId }.
6. Splitter (in-process): hash vs attachments; optional verae.archive.put (bytes never go to chain).
7. enqueueWatch → JetStream verae.zapier.jobs.watch.
8. HTTP 202 { jobId, sha256, existing } back to Zapier immediately.

Same SHA-256 is idempotent (existing: true).

2. Monitor (job poller)

The poller is in the middleware Node process when NATS_ENABLED=true (startJobPollerWorker). Fleet does not spawn a second copy (job-poller.enabled: false).

1. Durable consumer job-poller on ZAPIER_JOBS / verae.zapier.jobs.watch.
2. Resolve tokenRef → tenant Verae password → POST login → JWT (stays in middleware).
3. GET /api/status/{jobId} (mock or live timestamp server).
4. pending → nak after intervalMs (retry).
5. completed → publish jobs.events { event: timestamp.completed, status, jobId, tenantId, traceId }.
6. failed → timestamp.failed. Too many attempts → timestamp.timeout.
7. ack the watch message.

Live OpenAPI: poll until completed / failed. Hash lookup is 501 on live (lookupHash). Map certificate, timestamp, blockIndex, sha256 into the receipt Zap samples expect.

3. Wait (sync Zap step)

Create Timestamp and Wait → POST /zapier/v1/timestamp/wait.

1. Same as submit (watch is already on NATS).
2. waitForJobEvent(jobId, WAIT_TIMEOUT_MS) subscribes to verae.zapier.jobs.events.
3. On matching jobId event: return status JSON (certificate / receipt).
4. On timeout: { status: pending, jobId } so the REST Hook can finish the Zap.

includeAttached: after seal, aggregator should verae.archive.query; bloom hits merge extra receipts. Simulator does this; live aggregator hook is TBD.

4. Push back to Zapier

• Wait response: HTTP body on the same Zap step.
• REST Hook: Zapier subscribes POST /zapier/v1/hooks. On jobs.events, middleware enqueues verae.zapier.webhooks.deliver. Worker POSTs targetUrl (hooks.zapier.com).
• Poll status: Zap action Find Job Status → GET /zapier/v1/status/{jobId} → middleware GET Verae (or last event).

5. Verify

POST /zapier/v1/verify → middleware → Verae POST /api/verify. No job watch.

6. Batch Merkle (designed; same bus)

From MESSAGE-FLOWS.md:

1. POST /v1/timestamp/batch — one item per line.
2. Middleware hashes leaves, builds Merkle tree.
3. Chain seals only the root (POST /api/timestamp on the root).
4. Each leaf proof → verae.archive.put kind: tree.
5. Central hash lookup of a leaf misses unless includeTree=true.
6. Aggregator broadcasts verae.archive.query kinds=["tree"].
7. Tree node bloom hit → archive.reply.<id> with proof.

Live wait path does not yet call the aggregator, so tree-leaf receipts are not merged on NS1.

Connect live api.veraetime.net

Still blocked on operator bind credentials. When ready:

# middleware env
MOCK_VERAE=false
VERAE_API_BASE_URL=https://api.veraetime.net
NATS_ENABLED=true
NATS_URL=nats://10.10.10.21:4222,nats://10.10.10.22:4222,nats://10.10.10.23:4222
JETSTREAM_REPLICAS=3

Then: working Verae login, one live seal, confirm 202/status/verify, map receipt fields, REST Hook to a private Zap. See zapier-decisions/STATUS.md “Once MOCK_VERAE=false”.

Billing on this path

Connect a new internal process

export NATS_URL=nats://10.10.10.21:4222,nats://10.10.10.22:4222,nats://10.10.10.23:4222
# clone verae-nats-process, rename subjects, register in verae-fleet

Jobs stay: HTTP in from Zapier → HTTPS to Verae → NATS watch/events → HTTP back to Zapier.

Gaps and finish list

Modules and addresses that are designed but not fully connected, not running as fleet workers, or not on the live Verae/Zapier path.

Blocked on the operator (not a NATS bug)

Running on HTTP/NATS but incomplete routing

Designed, not a live worker

Aux (no product subjects, or HTTP only)

Billing triggers and event logging

Ordered finish for message routing

1. Do not double-start job-poller: either in-process or fleet copies, same queue job-poller.
2. Confirm edge NATS_URL so usage.recorded actually lands; then 402 from books. Unify or drop middleware local recordUsage.
3. Enable archive-aggregator (or in-process equivalent) so includeAttached and tree proofs work on wait/status.
4. Raise worm/tree replica floors on 510/more CTs if archive HA is required (fleet overlay min 3).
5. Operator: Zapier push + MOCK_VERAE=false.
6. Prove: Zap create → jobs.watch → live GET /api/status → jobs.events → wait body + REST Hook.
7. nkeys/mTLS after every client has creds; then lock down the public edge to accounts (LEAF vs INTERNAL).
8. Optional: exclusive jobs-events mailbox; SIEM on authz.deny and jobs.events; verae.splitter.in if splitter is split out; USAGE_WRITER or delete ZAPIER_USAGE.

What is already enough for a mock Zap

HTTPS zap/mw → mock create → jobs.watch → in-process poller → mock status completed → jobs.events → wait returns mock certificate. Archive extras and live chain are the missing middle.

Developer credentials and connection info

Lab pack for the Verae Time × Zapier stack on NS1.GEORGELAMBERT.ORG (70.88.205.138). Values below were checked 2026-09-14. These are lab defaults, not production secrets. Rotate the public NATS token and admin secrets before treating this as a customer environment.

Zapier cloud never gets a NATS URL or a Verae password.

1. Who you are talking to

SSH to the box: ssh marchon@70.88.205.138
Git SSH: ssh://git@git.georgelambert.org:2223/marchon/<repo>.git (port 2223)

2. Public HTTPS doors (live)

Wildcard *.zapier.georgelambert.org → 70.88.205.138.

Loopback on NS1 (not public): zappier-edge 127.0.0.1:13000 (admin + Stripe + SQLite). Tunnel:

ssh -L 13000:127.0.0.1:13000 marchon@70.88.205.138
# then http://127.0.0.1:13000/admin  and  /docs

Operator console tunnel: ssh -L 3850:127.0.0.1:3850 marchon@70.88.205.138

3. NATS

Internal cluster (workers, keep, fleet)

No token. Private vmbr1 only.

NATS_URL=nats://10.10.10.21:4222,nats://10.10.10.22:4222,nats://10.10.10.23:4222
JETSTREAM_REPLICAS=3

From a laptop you cannot reach 10.10.10.x unless you are on NS1 or you tunnel:

ssh -L 14222:10.10.10.21:4222 -L 14223:10.10.10.22:4222 -L 14224:10.10.10.23:4222 marchon@70.88.205.138
export NATS_URL=nats://127.0.0.1:14222,nats://127.0.0.1:14223,nats://127.0.0.1:14224

Public client edge (token)

Live token (file /etc/nats/public-edge.token on NS1):

4743a49383ce2ce86e99d9d41c45c0004fe75eb23ef3a2b9

nats://4743a49383ce2ce86e99d9d41c45c0004fe75eb23ef3a2b9@70.88.205.138:4222
wss://nats.zapier.georgelambert.org

CONNECT with that token returns PONG (checked 2026-09-14). auth_required: true. Server name nats-public-edge. Do not put this URL in Zapier. Recreate: bash packages/verae-nats-cluster/scripts/expose-public.sh on NS1.

Leftover lab listeners (ignore for new clients): host 127.0.0.1:4222 docker-proxy, 10.10.10.1:4222 socat. zappier-edge process still has NATS_URL=nats://127.0.0.1:4222 — billing pubs may miss the 3-node cluster until that env is flipped.

nkeys/mTLS: not on. Isolation is LAN + token.

4. Middleware (jobs)

Live: MOCK_VERAE=true, NATS_ENABLED=true, cluster URL as above, ADMIN_SECRET=change-me-admin (default), TOKEN_SECRET=dev-secret-change-me (default).

Lab tenant (created 2026-09-14 for this pack)

Proven: GET /zapier/v1/auth/me → valid; POST /zapier/v1/timestamp → 202 jobId; wait → mock certificate blockIndex: 42.

KEY=zmw_pXdwlUUyMHkAvqj3RRoQ2gOG6yAUQlun

curl -sS -H "x-api-key: $KEY" https://mw.zapier.georgelambert.org/zapier/v1/auth/me

curl -sS -H "x-api-key: $KEY" -H "content-type: application/json" \
  -d '{"sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}' \
  https://mw.zapier.georgelambert.org/zapier/v1/timestamp

curl -sS -H "x-api-key: $KEY" -H "content-type: application/json" \
  -d '{"sha256":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"}' \
  https://mw.zapier.georgelambert.org/zapier/v1/timestamp/wait

Customer API plane (forwards x-api-key to middleware):

curl -sS -H "x-api-key: $KEY" -H "content-type: application/json" \
  -d '{"sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}' \
  https://api.zapier.georgelambert.org/v1/timestamp

https://zap.zapier.georgelambert.org is the Zapier plane. It does not currently forward x-api-key on timestamp (401 if you curl it with a key). Zapier Platform push is still waiting on login; when it is live, set MIDDLEWARE_BASE_URL=https://zap.zapier.georgelambert.org and use a zmw_… key in the Zap.

Mint another key (mock Verae accepts any username/password):

curl -sS -H "content-type: application/json" \
  -d '{"email":"you@lab.local","name":"You","veraeUsername":"you","veraePassword":"you-pass"}' \
  https://mw.zapier.georgelambert.org/zapier/v1/signup

Admin list/provision:

curl -sS -H "x-admin-secret: change-me-admin" \
  https://mw.zapier.georgelambert.org/zapier/v1/admin/tenants

5. Portal / zappier-edge (billing users)

SQLite /SSD3/moved/home-marchon/verae-stack/packages/zappier/zappier.db. Bind 127.0.0.1:13000.

Seed customer API keys (x-api-key on edge /v1/*, not middleware zmw_):

These keys are for the edge meter / portal. Middleware jobs need a zmw_… key (section 4).

Seed admin console (/admin, x-admin-key or login):

ZAPPIER_ADMIN_KEY default on CS/sales/staff processes: admin-dev-key.

Stripe: not live (lab quotes only). Env STRIPE_* unset on the sampled edge process.

Signup more customers at https://portal.zapier.georgelambert.org/portal/

6. Staff IAM

https://login.zapier.georgelambert.org/ · https://iam.zapier.georgelambert.org/

Seed users (defaults; live IAM has these five):

STAFF_KEY / session fallback: admin-dev-key.

7. Leaf plane

https://leaf.zapier.georgelambert.org/health → verae.access.leaf.in

Live: LEAF_TOKEN=leaf-dev-token

curl -sS -H "content-type: application/json" \
  -d '{"token":"leaf-dev-token","target":"verae.archive.put","payload":{},"principal":"dev"}' \
  https://leaf.zapier.georgelambert.org/

Billing targets are denied on this plane.

8. Git (Forgejo)

GIT_SSH_COMMAND="ssh -p 2223" git clone ssh://git@git.georgelambert.org:2223/marchon/dev-overview.git

Add your SSH public key on Forgejo (user marchon or a new account). Do not commit deploy tokens.

Clone-all:

git clone ssh://git@git.georgelambert.org:2223/marchon/verae-bootstrap.git
cd verae-bootstrap
export VERAE_SRC=$HOME/verae-src
bash scripts/fetch.sh ns1-all-in-one

9. Environment cheat sheet (new worker on the cluster)

export NATS_URL=nats://10.10.10.21:4222,nats://10.10.10.22:4222,nats://10.10.10.23:4222
export JETSTREAM_REPLICAS=3
export NATS_ENABLED=true
export MOCK_VERAE=true          # flip to false only with live Verae login
export VERAE_API_BASE_URL=https://api.veraetime.net
export AUTHZ_URL=http://127.0.0.1:3020
export ZAPPIER_UPSTREAM=http://127.0.0.1:3100
export ZAPPIER_ADMIN_URL=http://127.0.0.1:13000
export ZAPPIER_ADMIN_KEY=admin-dev-key
export LEAF_TOKEN=leaf-dev-token
export STAFF_IAM_URL=http://127.0.0.1:3028

Template worker: clone verae-nats-process, rename verae.example.process.*.

10. Not issued yet (blocked)

When Zapier login exists: MIDDLEWARE_BASE_URL=https://zap.zapier.georgelambert.org, auth field api_key = zmw_….

When live Verae exists: middleware MOCK_VERAE=false + VERAE_API_BASE_URL=https://api.veraetime.net + working login. Zapier still never sees that password.

11. Related docs

• Routes: 01-nats-routes.md
• Endpoint I/O: 02-endpoint-io.md
• Job path: 03-zapier-verae-path.md
• Gaps: 04-gaps-and-finish.md
• Ops start: https://zapier.georgelambert.org/packages/verae-ops/GETTING-STARTED.pdf
• Status: https://zapier.georgelambert.org/packages/zapier-decisions/STATUS.pdf