Bind each customer to a Verae userId for hop tracing

Signup registers/binds a Verae central user and stores veraeUserId. Public access stays the zappier API key. Chain JWTs stay server-side behind tokenRef. Authz, billing, and jobs.watch carry veraeUserId.

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:** 352
+**Lines:** 386
 
 ## What this module is
 
@@ -24,6 +24,7 @@ _None extracted._
 | `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 |
+| `mockCreateUser` | `{ username, password, role = 'user' }` | — | `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 |
@@ -38,6 +39,8 @@ _None extracted._
 | `setTimeout` | `(` |
 | `login` | `credentials` |
 | `validate` | `token` |
+| `createUser` | `adminToken, body` |
+| `bindUser` | `credentials` |
 | `createTimestamp` | `token, body` |
 | `lookupHash` | `token, sha256` |
 | `createBatchTimestamp` | `token, body` |
@@ -54,10 +57,11 @@ _None extracted._
 - `../config.js`
 - `../errors.js`
 - `../debug/logger.js`
+- `../lib/identity.js`
 
 ## Call graph (identifiers invoked)
 
-`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`
+`net`, `createDebugger`, `sha256Hex`, `createHash`, `update`, `digest`, `delay`, `setTimeout`, `mockLogin`, `now`, `toISOString`, `stableVeraeUserId`, `includes`, `mockValidate`, `startsWith`, `replace`, `mockCreateUser`, `mockCreateTimestamp`, `toLowerCase`, `get`, `randomUUID`, `set`, `mockGetStatus`, `mockLookupHash`, `mockVerify`, `request`, `debug`, `fetch`, `stringify`, `text`, `parse`, `error`, `client`, `login`, `validate`, `createUser`, `bindUser`, `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.
 

docs/modules/verae-zapier-middleware/lib/identity.md

@@ -0,0 +1,41 @@
+# `verae-zapier-middleware/lib/identity`
+
+**Package:** `verae-zapier-middleware`  
+**Source:** `packages/verae-zapier-middleware/src/lib/identity.js`  
+**Lines:** 17
+
+## What this module is
+
+Implementation module in `verae-zapier-middleware`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+`normalizeVeraeUsername`, `stableVeraeUserId`
+
+## Types / interfaces / classes
+
+_None extracted._
+
+## Functions
+
+| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
+|------|------------|---------------------|---------|-----------------------------|
+| `normalizeVeraeUsername` | `username` | — | `unknown` | see Call graph |
+| `stableVeraeUserId` | `username` | — | `unknown` | see Call graph |
+
+## What it imports / requires
+
+- `node:crypto`
+
+## Call graph (identifiers invoked)
+
+`normalizeVeraeUsername`, `trim`, `toLowerCase`, `stableVeraeUserId`, `createHash`, `update`, `digest`, `slice`
+
+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`.
+

docs/modules/verae-zapier-middleware/middleware/authenticate.md

@@ -2,7 +2,7 @@
 
 **Package:** `verae-zapier-middleware`  
 **Source:** `packages/verae-zapier-middleware/src/middleware/authenticate.js`  
-**Lines:** 28
+**Lines:** 34
 
 ## What this module is
 
@@ -35,7 +35,7 @@ _No top-level functions extracted._
 
 ## Call graph (identifiers invoked)
 
-`createDebugger`, `asyncHandler`, `async`, `extractBearerToken`, `resolveAuthContext`, `debug`, `next`
+`createDebugger`, `asyncHandler`, `async`, `extractBearerToken`, `resolveAuthContext`, `startsWith`, `debug`, `next`
 
 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.
 

docs/modules/verae-zapier-middleware/nats/publishers.md

@@ -2,7 +2,7 @@
 
 **Package:** `verae-zapier-middleware`  
 **Source:** `packages/verae-zapier-middleware/src/nats/publishers.js`  
-**Lines:** 96
+**Lines:** 98
 
 ## What this module is
 

docs/modules/verae-zapier-middleware/services/authService.md

@@ -2,7 +2,7 @@
 
 **Package:** `verae-zapier-middleware`  
 **Source:** `packages/verae-zapier-middleware/src/services/authService.js`  
-**Lines:** 142
+**Lines:** 154
 
 ## What this module is
 
@@ -35,7 +35,7 @@ _None extracted._
 
 ## Call graph (identifiers invoked)
 
-`createDebugger`, `loginWithCredentials`, `debug`, `login`, `issueSessionToken`, `loginWithApiKey`, `getTenantByApiKey`, `resolveAuthContext`, `isApiKey`, `parseSessionToken`, `getTenant`, `parse`, `now`, `validateSession`, `validate`
+`createDebugger`, `loginWithCredentials`, `debug`, `login`, `upsertTenant`, `issueSessionToken`, `loginWithApiKey`, `getTenantByApiKey`, `resolveAuthContext`, `isApiKey`, `parseSessionToken`, `getTenant`, `parse`, `now`, `validateSession`, `validate`
 
 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.
 

docs/modules/verae-zapier-middleware/services/tenantService.md

@@ -2,7 +2,7 @@
 
 **Package:** `verae-zapier-middleware`  
 **Source:** `packages/verae-zapier-middleware/src/services/tenantService.js`  
-**Lines:** 138
+**Lines:** 150
 
 ## What this module is
 
@@ -45,7 +45,7 @@ _None extracted._
 
 ## Call graph (identifiers invoked)
 
-`createDebugger`, `slugify`, `toLowerCase`, `replace`, `slice`, `validateVeraeCredentials`, `login`, `selfServeSignup`, `randomUUID`, `createTenant`, `info`, `provision`, `provisionTenant`, `has`, `getTenant`, `listProvisionedTenants`, `listTenants`, `map`
+`createDebugger`, `slugify`, `toLowerCase`, `replace`, `slice`, `validateVeraeCredentials`, `login`, `selfServeSignup`, `bindUser`, `randomUUID`, `createTenant`, `info`, `provision`, `provisionTenant`, `has`, `getTenant`, `listProvisionedTenants`, `listTenants`, `map`
 
 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.
 

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:** 170
+**Lines:** 171
 
 ## What this module is
 
@@ -53,13 +53,14 @@ _None extracted._
 - `../config.js`
 - `../clients/veraeClient.js`
 - `../store/jobWatchers.js`
+- `../store/tokenRefs.js`
 - `./entitlementService.js`
 - `../debug/logger.js`
 - `../debug/trace-context.js`
 
 ## Call graph (identifiers invoked)
 
-`createDebugger`, `enqueueWatchForJob`, `getTraceId`, `import`, `enqueueWatch`, `debug`, `enqueueJob`, `createTimestamp`, `checkEntitlement`, `recordUsage`, `createTimestampAndWait`, `waitForJobEvent`, `getStatus`, `waitForJob`, `createBatchTimestamp`, `getJobStatus`, `getBatchJobStatus`, `getBatchStatus`, `getJobVerification`, `lookupHash`
+`createDebugger`, `enqueueWatchForJob`, `getTraceId`, `import`, `enqueueWatch`, `issueTokenRef`, `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.
 

docs/modules/verae-zapier-middleware/store/db.md

@@ -2,7 +2,7 @@
 
 **Package:** `verae-zapier-middleware`  
 **Source:** `packages/verae-zapier-middleware/src/store/db.js`  
-**Lines:** 118
+**Lines:** 120
 
 ## What this module is
 

docs/modules/verae-zapier-middleware/store/tenants.md

@@ -2,7 +2,7 @@
 
 **Package:** `verae-zapier-middleware`  
 **Source:** `packages/verae-zapier-middleware/src/store/tenants.js`  
-**Lines:** 138
+**Lines:** 142
 
 ## What this module is
 
@@ -30,8 +30,9 @@ _None extracted._
   plan = 'free',
   veraeUsername,
   veraePassword,
+  veraeUserId,
   contract = null,
-  apiKey = generateApiKey(` | params: `object`, params.id: `string`, params.name: `string`, params.plan: `string`, params.veraeUsername: `string`, params.veraePassword: `string`, params.contract: `object|null`, params.apiKey: `string`, params.metadata: `object` | `{ tenant: Tenant, apiKey: string ` — } | see Call graph |
+  apiKey = generateApiKey(` | params: `object`, params.id: `string`, params.name: `string`, params.plan: `string`, params.veraeUsername: `string`, params.veraePassword: `string`, params.veraeUserId: `string`, params.contract: `object|null`, params.apiKey: `string`, params.metadata: `object` | `{ tenant: Tenant, apiKey: string ` — } | see Call graph |
 | `resolveLimits` | `tenant` | tenant: `Tenant` | `{
  *   timestamps: number|null,
  *   verifications: number|null,

docs/modules/verae-zapier-middleware/store/tokenRefs.md

@@ -0,0 +1,48 @@
+# `verae-zapier-middleware/store/tokenRefs`
+
+**Package:** `verae-zapier-middleware`  
+**Source:** `packages/verae-zapier-middleware/src/store/tokenRefs.js`  
+**Lines:** 21
+
+## What this module is
+
+Implementation module in `verae-zapier-middleware`. The tables below are extracted from the source (signatures + JSDoc).
+
+## Exports
+
+`issueTokenRef`, `resolveTokenRef`
+
+## Types / interfaces / classes
+
+_None extracted._
+
+## Functions
+
+| Name | Parameters | Param types (JSDoc) | Returns | Calls (same file / helpers) |
+|------|------------|---------------------|---------|-----------------------------|
+| `issueTokenRef` | `tenantId` | — | `unknown` | see Call graph |
+| `resolveTokenRef` | `ref` | — | `unknown` | see Call graph |
+
+## Methods (class / object)
+
+| Name | Parameters |
+|------|------------|
+| `persist` | `(none)` |
+
+## What it imports / requires
+
+- `node:crypto`
+- `./db.js`
+
+## Call graph (identifiers invoked)
+
+`issueTokenRef`, `randomBytes`, `toString`, `getStore`, `toISOString`, `persist`, `resolveTokenRef`
+
+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`.
+

docs/modules/verae-zapier-middleware/workers/jobPollerWorker.md

@@ -2,7 +2,7 @@
 
 **Package:** `verae-zapier-middleware`  
 **Source:** `packages/verae-zapier-middleware/src/workers/jobPollerWorker.js`  
-**Lines:** 159
+**Lines:** 161
 
 ## What this module is
 
@@ -34,11 +34,12 @@ _None extracted._
 - `../nats/publishers.js`
 - `../clients/veraeClient.js`
 - `../store/tenants.js`
+- `../store/tokenRefs.js`
 - `../debug/trace.js`
 
 ## Call graph (identifiers invoked)
 
-`createDebugger`, `polling`, `resolveVeraeToken`, `getTenant`, `login`, `handleWatch`, `withTrace`, `async`, `publishJobEvent`, `ack`, `getStatus`, `debug`, `nak`, `startJobPollerWorker`, `stopJobPollerWorker`, `connectNats`, `ensureStreams`, `consumer`, `add`, `get`, `info`, `consume`, `parse`, `string`, `error`, `abort`
+`createDebugger`, `polling`, `resolveVeraeToken`, `resolveTokenRef`, `getTenant`, `login`, `handleWatch`, `withTrace`, `async`, `publishJobEvent`, `ack`, `getStatus`, `debug`, `nak`, `startJobPollerWorker`, `stopJobPollerWorker`, `connectNats`, `ensureStreams`, `consumer`, `add`, `get`, `info`, `consume`, `parse`, `string`, `error`, `abort`
 
 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.