Milestone 3: NATS wait (gate 9), hash lookup, zappier timestamp, NS1 tunnel

Wait-via-NATS returns completed or pending+jobId (GATE 9). Mock SHA256 idempotent register + GET /hashes/{sha256}. Zappier commercial edge has POST /v1/timestamp and hash-lookup. GATE 12 smoke (signup + wait) passes. NS1 NATS is 127.0.0.1:4222 on 70.88.205.138; SSH tunnel :14222. Local nats-server -js used for isolated tests. Activate app adds Echo Text. Learned: JetStream on NS1 is loopback-only; do not bind 4222 public.
2026-09-09 02:54:02 -04:00 · 2026-09-09 02:54:02 -04:00 · 51ae79b75f
commit 51ae79b75f
parent 10c663cc0c
75 changed files with 1114 additions and 123 deletions
--- a/docs/modules/README.md
+++ b/docs/modules/README.md
@ -43,7 +43,9 @@ One MD file per source module.
 - [verae-zapier-middleware/nats/connection](verae-zapier-middleware/nats/connection.md)
 - [verae-zapier-middleware/nats/publishers](verae-zapier-middleware/nats/publishers.md)
 - [verae-zapier-middleware/nats/subjects](verae-zapier-middleware/nats/subjects.md)
+- [verae-zapier-middleware/nats/wait](verae-zapier-middleware/nats/wait.md)
 - [verae-zapier-middleware/routes/authRoutes](verae-zapier-middleware/routes/authRoutes.md)
+- [verae-zapier-middleware/routes/hashRoutes](verae-zapier-middleware/routes/hashRoutes.md)
 - [verae-zapier-middleware/routes/index](verae-zapier-middleware/routes/index.md)
 - [verae-zapier-middleware/routes/statusRoutes](verae-zapier-middleware/routes/statusRoutes.md)
 - [verae-zapier-middleware/routes/tenantRoutes](verae-zapier-middleware/routes/tenantRoutes.md)
@ -66,6 +68,7 @@ One MD file per source module.
 - [verae-zapier-middleware/workers/webhookWorker](verae-zapier-middleware/workers/webhookWorker.md)
 - [verae-activate/authentication](verae-activate/authentication.md)
 - [verae-activate/creates/add_numbers](verae-activate/creates/add_numbers.md)
+- [verae-activate/creates/echo](verae-activate/creates/echo.md)
 - [verae-activate/index](verae-activate/index.md)
 - [verae-zapier/authentication](verae-zapier/authentication.md)
 - [verae-zapier/creates/add_numbers](verae-zapier/creates/add_numbers.md)
@ -74,5 +77,6 @@ One MD file per source module.
 - [verae-zapier/creates/timestamp_and_wait](verae-zapier/creates/timestamp_and_wait.md)
 - [verae-zapier/creates/verify_timestamp](verae-zapier/creates/verify_timestamp.md)
 - [verae-zapier/index](verae-zapier/index.md)
+- [verae-zapier/searches/hash_lookup](verae-zapier/searches/hash_lookup.md)
 - [verae-zapier/searches/job_status](verae-zapier/searches/job_status.md)
 - [verae-zapier/triggers/timestamp_completed](verae-zapier/triggers/timestamp_completed.md)
--- a/docs/modules/verae-activate/creates/echo.md
+++ b/docs/modules/verae-activate/creates/echo.md
@ -0,0 +1,40 @@
+# `verae-activate/creates/echo`
+
+**Package:** `verae-activate`  
+**Source:** `packages/verae-activate/creates/echo.js`  
+**Lines:** 30
+
+## What this module is
+
+Implementation module in `verae-activate`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+`key`, `noun`, `display`, `label`, `description`
+
+## Types / interfaces / classes
+
+_None extracted._
+
+## Functions
+
+| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
+|------|------------|---------------------|---------|-----------------------------|
+| `perform` | `_z, bundle` | — | `unknown` | see Call graph |
+
+## What it imports / requires
+
+_No imports detected._
+
+## Call graph (identifiers invoked)
+
+`action`, `async`
+
+Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+
--- a/docs/modules/verae-activate/index.md
+++ b/docs/modules/verae-activate/index.md
@ -2,7 +2,7 @@

 **Package:** `verae-activate`  
 **Source:** `packages/verae-activate/index.js`  
-**Lines:** 21
+**Lines:** 23

 ## What this module is

@ -10,7 +10,7 @@ Implementation module in `verae-activate`. The tables below are extracted from t

 ## Exports

-`version`, `platformVersion`, `authentication`, `creates`, `addNumbers`
+`version`, `platformVersion`, `authentication`, `creates`, `addNumbers`, `echo`

 ## Types / interfaces / classes

@ -24,6 +24,7 @@ _No top-level functions extracted._

 - `./authentication`
 - `./creates/add_numbers`
+- `./creates/echo`
 - `./package.json`
 - `zapier-platform-core`

--- a/docs/modules/verae-zapier-middleware/clients/veraeClient.md
+++ b/docs/modules/verae-zapier-middleware/clients/veraeClient.md
@ -2,7 +2,7 @@

 **Package:** `verae-zapier-middleware`  
 **Source:** `packages/verae-zapier-middleware/src/clients/veraeClient.js`  
-**Lines:** 288
+**Lines:** 351

 ## What this module is

@ -10,7 +10,7 @@ Implementation module in `verae-zapier-middleware`. The tables below are extract

 ## Exports

-`veraeClient`, `clearMockJobs`
+`sha256Hex`, `veraeClient`, `clearMockJobs`

 ## Types / interfaces / classes

@ -20,11 +20,13 @@ _None extracted._

 | Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
 |------|------------|---------------------|---------|-----------------------------|
+| `sha256Hex` | `data` | data: `string` | `string` | see Call graph |
 | `delay` | `ms` | ms: `number` | `Promise<void>` | see Call graph |
 | `mockLogin` | `{ username, password }` | ms: `number` | `Promise<void>` | see Call graph |
 | `mockValidate` | `token` | — | `unknown` | see Call graph |
-| `mockCreateTimestamp` | `{ data, hashAlg }` | — | `unknown` | see Call graph |
+| `mockCreateTimestamp` | `{ data, hashAlg, sha256, publicMetadata, privateMetadata }` | — | `unknown` | see Call graph |
 | `mockGetStatus` | `jobId` | — | `unknown` | see Call graph |
+| `mockLookupHash` | `sha256` | — | `unknown` | see Call graph |
 | `mockVerify` | `{ certificate }` | — | `unknown` | see Call graph |
 | `request` | `path, { method = 'GET', token, body } = {}` | path: `string` | `Promise<any>` | see Call graph |
 | `clearMockJobs` | `(none)` | — | `void` | see Call graph |
@ -37,6 +39,7 @@ _None extracted._
 | `login` | `credentials` |
 | `validate` | `token` |
 | `createTimestamp` | `token, body` |
+| `lookupHash` | `token, sha256` |
 | `createBatchTimestamp` | `token, body` |
 | `getStatus` | `token, jobId` |
 | `getBatchStatus` | `token, body` |
@ -54,7 +57,7 @@ _None extracted._

 ## Call graph (identifiers invoked)

-`net`, `createDebugger`, `delay`, `setTimeout`, `mockLogin`, `now`, `toISOString`, `randomUUID`, `includes`, `mockValidate`, `startsWith`, `replace`, `mockCreateTimestamp`, `set`, `get`, `mockGetStatus`, `mockVerify`, `request`, `debug`, `fetch`, `stringify`, `text`, `parse`, `error`, `client`, `login`, `validate`, `createTimestamp`, `createBatchTimestamp`, `push`, `getStatus`, `encodeURIComponent`, `getBatchStatus`, `verify`, `verifyBatch`, `getJobVerification`, `waitForJob`, `jobs`, `clearMockJobs`, `clear`
+`net`, `createDebugger`, `sha256Hex`, `createHash`, `update`, `digest`, `delay`, `setTimeout`, `mockLogin`, `now`, `toISOString`, `randomUUID`, `includes`, `mockValidate`, `startsWith`, `replace`, `mockCreateTimestamp`, `toLowerCase`, `get`, `set`, `mockGetStatus`, `mockLookupHash`, `mockVerify`, `request`, `debug`, `fetch`, `stringify`, `text`, `parse`, `error`, `client`, `login`, `validate`, `createTimestamp`, `lookupHash`, `createBatchTimestamp`, `push`, `getStatus`, `encodeURIComponent`, `getBatchStatus`, `verify`, `verifyBatch`, `getJobVerification`, `waitForJob`, `jobs`, `clearMockJobs`, `clear`

 Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.

--- a/docs/modules/verae-zapier-middleware/config.md
+++ b/docs/modules/verae-zapier-middleware/config.md
@ -2,7 +2,7 @@

 **Package:** `verae-zapier-middleware`  
 **Source:** `packages/verae-zapier-middleware/src/config.js`  
-**Lines:** 143
+**Lines:** 145

 ## What this module is

--- a/docs/modules/verae-zapier-middleware/nats/connection.md
+++ b/docs/modules/verae-zapier-middleware/nats/connection.md
@ -2,7 +2,7 @@

 **Package:** `verae-zapier-middleware`  
 **Source:** `packages/verae-zapier-middleware/src/nats/connection.js`  
-**Lines:** 112
+**Lines:** 117

 ## What this module is

@ -10,7 +10,7 @@ Implementation module in `verae-zapier-middleware`. The tables below are extract

 ## Exports

-`connectNats`, `ensureStreams`, `closeNats`, `getJetStream`, `isNatsConnected`
+`connectNats`, `getNatsConnection`, `ensureStreams`, `closeNats`, `getJetStream`, `isNatsConnected`

 ## Types / interfaces / classes

@ -21,6 +21,7 @@ _None extracted._
 | Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
 |------|------------|---------------------|---------|-----------------------------|
 | `connectNats` | `url = config.natsUrl` | url: `string` | `Promise<{ nc: import('nats').NatsConnection, js: import('nats').JetStreamClient, jsm: import('nats').JetStreamManager ` — >} | see Call graph |
+| `getNatsConnection` | `(none)` | — | `import('nats').NatsConnection|null` | see Call graph |
 | `ensureStreams` | `manager` | manager: `import('nats').JetStreamManager` | `Promise<void>` | see Call graph |
 | `closeNats` | `(none)` | — | `Promise<void>` | see Call graph |
 | `getJetStream` | `(none)` | — | `import('nats').JetStreamClient|null` | see Call graph |
@ -34,7 +35,7 @@ _None extracted._

 ## Call graph (identifiers invoked)

-`createDebugger`, `import`, `connectNats`, `debug`, `disabled`, `info`, `connect`, `jetstream`, `jetstreamManager`, `ensureStreams`, `add`, `closeNats`, `drain`, `getJetStream`, `isNatsConnected`, `isClosed`
+`createDebugger`, `import`, `connectNats`, `debug`, `disabled`, `info`, `connect`, `jetstream`, `jetstreamManager`, `getNatsConnection`, `ensureStreams`, `add`, `closeNats`, `drain`, `getJetStream`, `isNatsConnected`, `isClosed`

 Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.

--- a/docs/modules/verae-zapier-middleware/nats/wait.md
+++ b/docs/modules/verae-zapier-middleware/nats/wait.md
@ -0,0 +1,44 @@
+# `verae-zapier-middleware/nats/wait`
+
+**Package:** `verae-zapier-middleware`  
+**Source:** `packages/verae-zapier-middleware/src/nats/wait.js`  
+**Lines:** 60
+
+## What this module is
+
+Implementation module in `verae-zapier-middleware`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+`waitForJobEvent`
+
+## Types / interfaces / classes
+
+_None extracted._
+
+## Functions
+
+| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
+|------|------------|---------------------|---------|-----------------------------|
+| `waitForJobEvent` | `jobId, timeoutMs` | jobId: `string`, timeoutMs: `number` | `Promise<object|null>` — event payload or null on timeout | see Call graph |
+| `firstMatch` | `async (` | — | `unknown` | see Call graph |
+
+## What it imports / requires
+
+- `../debug/logger.js`
+- `../debug/trace-context.js`
+- `./subjects.js`
+- `./connection.js`
+
+## Call graph (identifiers invoked)
+
+`createDebugger`, `waitForJobEvent`, `getNatsConnection`, `connectNats`, `subscribe`, `getTraceId`, `debug`, `setTimeout`, `resolve`, `async`, `parse`, `string`, `race`, `unsubscribe`
+
+Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+
--- a/docs/modules/verae-zapier-middleware/routes/hashRoutes.md
+++ b/docs/modules/verae-zapier-middleware/routes/hashRoutes.md
@ -0,0 +1,46 @@
+# `verae-zapier-middleware/routes/hashRoutes`
+
+**Package:** `verae-zapier-middleware`  
+**Source:** `packages/verae-zapier-middleware/src/routes/hashRoutes.js`  
+**Lines:** 22
+
+## What this module is
+
+Implementation module in `verae-zapier-middleware`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+`hashRoutes`
+
+## Types / interfaces / classes
+
+_None extracted._
+
+## Functions
+
+_No top-level functions extracted._
+
+## Methods (class / object)
+
+| Name | Parameters |
+|------|------------|
+| `asyncHandler` | `async (req, res` |
+
+## What it imports / requires
+
+- `express`
+- `../errors.js`
+- `../services/timestampService.js`
+
+## Call graph (identifiers invoked)
+
+`get`, `asyncHandler`, `async`, `test`, `lookupHash`, `json`
+
+Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+
--- a/docs/modules/verae-zapier-middleware/routes/index.md
+++ b/docs/modules/verae-zapier-middleware/routes/index.md
@ -2,7 +2,7 @@

 **Package:** `verae-zapier-middleware`  
 **Source:** `packages/verae-zapier-middleware/src/routes/index.js`  
-**Lines:** 34
+**Lines:** 36

 ## What this module is

@ -29,6 +29,7 @@ _No top-level functions extracted._
 - `./statusRoutes.js`
 - `./webhookRoutes.js`
 - `./tenantRoutes.js`
+- `./hashRoutes.js`
 - `../middleware/authenticate.js`
 - `../middleware/rateLimit.js`

--- a/docs/modules/verae-zapier-middleware/routes/timestampRoutes.md
+++ b/docs/modules/verae-zapier-middleware/routes/timestampRoutes.md
@ -2,7 +2,7 @@

 **Package:** `verae-zapier-middleware`  
 **Source:** `packages/verae-zapier-middleware/src/routes/timestampRoutes.js`  
-**Lines:** 50
+**Lines:** 62

 ## What this module is

--- a/docs/modules/verae-zapier-middleware/services/timestampService.md
+++ b/docs/modules/verae-zapier-middleware/services/timestampService.md
@ -2,7 +2,7 @@

 **Package:** `verae-zapier-middleware`  
 **Source:** `packages/verae-zapier-middleware/src/services/timestampService.js`  
-**Lines:** 123
+**Lines:** 160

 ## What this module is

@ -10,7 +10,7 @@ Implementation module in `verae-zapier-middleware`. The tables below are extract

 ## Exports

-`createTimestamp`, `createTimestampAndWait`, `createBatchTimestamp`, `getJobStatus`, `getBatchJobStatus`, `getJobVerification`
+`createTimestamp`, `createTimestampAndWait`, `createBatchTimestamp`, `getJobStatus`, `getBatchJobStatus`, `getJobVerification`, `lookupHash`

 ## Types / interfaces / classes

@ -21,12 +21,13 @@ _None extracted._
 | Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
 |------|------------|---------------------|---------|-----------------------------|
 | `enqueueWatchForJob` | `ctx, jobId` | ctx: `object`, jobId: `string` | `unknown` | see Call graph |
-| `createTimestamp` | `ctx, body` | ctx: `object` | `Promise<{ jobId: string ` — >} | see Call graph |
+| `createTimestamp` | `ctx, body` | ctx: `object` | `Promise<{ jobId: string, sha256?: string, existing?: boolean ` — >} | see Call graph |
 | `createTimestampAndWait` | `ctx, body` | ctx: `object` | `Promise<object>` — StatusResponse | see Call graph |
 | `createBatchTimestamp` | `ctx, body` | ctx: `object` | `unknown` | see Call graph |
 | `getJobStatus` | `ctx, jobId` | ctx: `object`, jobId: `string` | `unknown` | see Call graph |
 | `getBatchJobStatus` | `ctx, body` | ctx: `object` | `unknown` | see Call graph |
 | `getJobVerification` | `ctx, jobId` | ctx: `object`, jobId: `string` | `unknown` | see Call graph |
+| `lookupHash` | `ctx, sha256` | ctx: `object`, sha256: `string` | `unknown` | see Call graph |

 ## Methods (class / object)

@ -40,12 +41,12 @@ _None extracted._
  }` |
 | `checkEntitlement` | `ctx.tenantId, 'timestamp'` |
 | `recordUsage` | `ctx.tenantId, 'timestamp'` |
-| `recordUsage` | `ctx.tenantId, 'status'` |
 | `checkEntitlement` | `ctx.tenantId, 'batch_timestamp', { amount: itemCount }` |
 | `recordUsage` | `ctx.tenantId, 'batch_timestamp', { amount: itemCount }` |
 | `recordUsage` | `ctx.tenantId, 'status'` |
 | `recordUsage` | `ctx.tenantId, 'status', { amount: body.jobIds?.length ?? 1 }` |
 | `recordUsage` | `ctx.tenantId, 'status'` |
+| `recordUsage` | `ctx.tenantId, 'status'` |

 ## What it imports / requires

@ -58,7 +59,7 @@ _None extracted._

 ## Call graph (identifiers invoked)

-`createDebugger`, `enqueueWatchForJob`, `getTraceId`, `import`, `enqueueWatch`, `debug`, `enqueueJob`, `createTimestamp`, `checkEntitlement`, `recordUsage`, `createTimestampAndWait`, `waitForJob`, `createBatchTimestamp`, `getJobStatus`, `getStatus`, `getBatchJobStatus`, `getBatchStatus`, `getJobVerification`
+`createDebugger`, `enqueueWatchForJob`, `getTraceId`, `import`, `enqueueWatch`, `debug`, `enqueueJob`, `createTimestamp`, `checkEntitlement`, `recordUsage`, `createTimestampAndWait`, `waitForJobEvent`, `getStatus`, `waitForJob`, `createBatchTimestamp`, `getJobStatus`, `getBatchJobStatus`, `getBatchStatus`, `getJobVerification`, `lookupHash`

 Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.

--- a/docs/modules/verae-zapier/index.md
+++ b/docs/modules/verae-zapier/index.md
@ -2,7 +2,7 @@

 **Package:** `verae-zapier`  
 **Source:** `packages/verae-zapier/index.js`  
-**Lines:** 79
+**Lines:** 81

 ## What this module is

@ -32,6 +32,7 @@ _None extracted._
 - `./creates/batch_timestamp`
 - `./creates/add_numbers`
 - `./searches/job_status`
+- `./searches/hash_lookup`
 - `./triggers/timestamp_completed`
 - `zapier-platform-core`
 - `./package.json`
--- a/docs/modules/verae-zapier/searches/hash_lookup.md
+++ b/docs/modules/verae-zapier/searches/hash_lookup.md
@ -0,0 +1,41 @@
+# `verae-zapier/searches/hash_lookup`
+
+**Package:** `verae-zapier`  
+**Source:** `packages/verae-zapier/searches/hash_lookup.js`  
+**Lines:** 35
+
+## What this module is
+
+Implementation module in `verae-zapier`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+`key`, `noun`, `display`, `label`, `description`
+
+## Types / interfaces / classes
+
+_None extracted._
+
+## Functions
+
+| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
+|------|------------|---------------------|---------|-----------------------------|
+| `base` | `(none)` | — | `unknown` | see Call graph |
+| `perform` | `z, bundle` | — | `unknown` | see Call graph |
+
+## What it imports / requires
+
+_No imports detected._
+
+## Call graph (identifiers invoked)
+
+`async`, `request`, `base`, `encodeURIComponent`, `digest`
+
+Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.
+
+## Return values (how to read this)
+
+- HTTP route handlers return Express `res.json(...)` bodies (see route docs).
+- Zapier `perform` functions return a **single object** (creates) or an **array** (triggers/searches).
+- Pricing functions return integer **cents** on `Quote.totalCents`.
+
--- a/docs/modules/zappier/app.md
+++ b/docs/modules/zappier/app.md
@ -2,7 +2,7 @@

 **Package:** `zappier`  
 **Source:** `packages/zappier/src/app.ts`  
-**Lines:** 203
+**Lines:** 237

 ## What this module is

@ -47,7 +47,7 @@ Implementation module in `zappier`. The tables below are extracted from the sour

 ## Call graph (identifiers invoked)

-`join`, `next`, `parse`, `status`, `json`, `buildApp`, `seeded`, `seedAdminUsersFromEnv`, `rateCard`, `getRateCard`, `tiers`, `getTiers`, `express`, `use`, `load`, `setup`, `adminLoginRouter`, `adminAuth`, `adminRouter`, `static`, `async`, `import`, `toDataURL`, `portalRouter`, `apiKeyAuth`, `middleware`, `get`, `meter`, `post`, `toUpperCase`, `isFinite`, `randomUUID`, `map`, `toISOString`, `unshift`, `filter`, `setUTCDate`, `setUTCHours`, `summaryFor`, `find`, `applyMonthlyCredit`
+`join`, `next`, `parse`, `status`, `json`, `buildApp`, `seeded`, `seedAdminUsersFromEnv`, `rateCard`, `getRateCard`, `tiers`, `getTiers`, `express`, `use`, `load`, `setup`, `adminLoginRouter`, `adminAuth`, `adminRouter`, `static`, `async`, `import`, `toDataURL`, `portalRouter`, `apiKeyAuth`, `middleware`, `get`, `meter`, `post`, `toUpperCase`, `toLowerCase`, `createHash`, `update`, `digest`, `randomUUID`, `toISOString`, `set`, `isFinite`, `map`, `unshift`, `filter`, `setUTCDate`, `setUTCHours`, `summaryFor`, `find`, `applyMonthlyCredit`

 Each identifier is a call site in this file. Follow the import list to see the defining module; open that module’s MD for parameter and return types.

--- a/docs/modules/zappier/pricing.md
+++ b/docs/modules/zappier/pricing.md
@ -2,7 +2,7 @@

 **Package:** `zappier`  
 **Source:** `packages/zappier/src/pricing.ts`  
-**Lines:** 171
+**Lines:** 173

 ## What this module is