Milestone 0: import zappier billing, Verae middleware, and Zapier research

Compose-ready workspace: packages/zappier (rate card, portal, Stripe),
packages/verae-zapier-middleware (timestamp + NATS), packages/verae-zapier
(CLI app), vendor/zapier-platform, and research/zapier vendor corpus.

Gate 0 structure checks pass. Product code and research are not yet wired.
This commit is contained in:
George Lambert 2026-09-09 02:37:36 -04:00
commit b4150c8250
38 changed files with 6814366 additions and 0 deletions

View file

@ -0,0 +1,50 @@
/**
* @fileoverview Express application factory for the Zapier-facing HTTP edge.
* @module app
*/
import express from 'express';
import { sendError } from './errors.js';
import { createDebugger } from './debug/logger.js';
import { traceMiddleware } from './debug/trace.js';
import { apiRoutes } from './routes/index.js';
import { loadStore } from './store/db.js';
const log = createDebugger('app');
/**
* Create the Express app (does not listen).
*
* @param {{ load?: boolean }} [options]
* @returns {import('express').Express}
*/
export function createApp(options = {}) {
if (options.load !== false) {
loadStore();
}
const app = express();
app.disable('x-powered-by');
app.use(express.json({ limit: '1mb' }));
app.use(traceMiddleware);
/**
* Liveness probe.
*/
app.get('/health', (_req, res) => {
res.json({
status: 'ok',
service: 'verae-zapier-middleware',
});
});
app.use('/zapier', apiRoutes);
app.use((err, _req, res, _next) => {
sendError(res, err);
});
log.info('express app created');
return app;
}

View file

@ -0,0 +1,287 @@
/**
* @fileoverview HTTP client for api.veraetime.net (with mock mode).
* @module clients/veraeClient
*/
import { randomUUID } from 'node:crypto';
import { config } from '../config.js';
import { AppError } from '../errors.js';
import { createDebugger } from '../debug/logger.js';
const log = createDebugger('http');
const mockJobs = new Map();
/**
* @param {number} ms
* @returns {Promise<void>}
*/
function delay(ms) {
return new Promise((resolve) => setTimeout(resolve, ms));
}
async function mockLogin({ username, password }) {
if (!username || !password) {
throw new AppError('Invalid credentials', { status: 401, code: 'UNAUTHORIZED' });
}
const expiresAt = new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString();
return {
token: `mock-jwt-${username}`,
expiresAt,
user: {
id: randomUUID(),
username,
role: username.includes('admin') ? 'admin' : 'user',
},
};
}
async function mockValidate(token) {
if (!token?.startsWith('mock-jwt-')) {
throw new AppError('Invalid or expired token', { status: 401, code: 'UNAUTHORIZED' });
}
const username = token.replace('mock-jwt-', '');
return {
valid: true,
userId: randomUUID(),
username,
role: 'user',
expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
};
}
async function mockCreateTimestamp({ data, hashAlg }) {
if (!data) {
throw new AppError('Invalid input data', { status: 400, code: 'VALIDATION_ERROR' });
}
const jobId = randomUUID();
mockJobs.set(jobId, {
id: jobId,
status: 'pending',
createdAt: Date.now(),
data,
hashAlg: hashAlg ?? 'SHA256',
});
setTimeout(() => {
const job = mockJobs.get(jobId);
if (!job) return;
job.status = 'completed';
job.result = `mock-cert-${jobId}`;
job.completedAt = new Date().toISOString();
job.metadata = {
blockIndex: 42,
timestamp: job.completedAt,
certificate: job.result,
};
}, 150);
return { jobId };
}
async function mockGetStatus(jobId) {
const job = mockJobs.get(jobId);
if (!job) {
throw new AppError('Job not found', { status: 404, code: 'NOT_FOUND' });
}
return {
id: job.id,
status: job.status,
result: job.result,
completedAt: job.completedAt,
metadata: job.metadata,
error: job.error,
};
}
async function mockVerify({ certificate }) {
if (!certificate) {
throw new AppError('Invalid input data', { status: 400, code: 'VALIDATION_ERROR' });
}
const valid = certificate.startsWith('mock-cert-') || certificate.startsWith('eyJ');
return valid
? { valid: true, timestamp: new Date().toISOString(), blockIndex: 42 }
: { valid: false };
}
/**
* Low-level fetch to Verae API.
* @param {string} path
* @param {{ method?: string, token?: string, body?: unknown }} [options]
* @returns {Promise<any>}
*/
async function request(path, { method = 'GET', token, body } = {}) {
const url = `${config.veraeApiBaseUrl}${path}`;
const headers = { Accept: 'application/json' };
if (token) {
headers.Authorization = `Bearer ${token}`;
}
if (body !== undefined) {
headers['Content-Type'] = 'application/json';
}
const started = Date.now();
log.debug('verae request', { method, path, hasToken: Boolean(token) });
const response = await fetch(url, {
method,
headers,
body: body !== undefined ? JSON.stringify(body) : undefined,
});
let payload = null;
const text = await response.text();
if (text) {
try {
payload = JSON.parse(text);
} catch {
payload = { error: text };
}
}
log.debug('verae response', {
method,
path,
status: response.status,
durationMs: Date.now() - started,
});
if (!response.ok) {
throw new AppError(payload?.error ?? `Verae API error (${response.status})`, {
status: response.status,
code: payload?.code ?? 'VERAE_API_ERROR',
details: payload,
});
}
return payload;
}
/**
* Verae API client (mock when config.mockVerae is true).
*/
export const veraeClient = {
/**
* @param {{ username: string, password: string }} credentials
*/
async login(credentials) {
if (config.mockVerae) return mockLogin(credentials);
return request('/auth/login', { method: 'POST', body: credentials });
},
/**
* @param {string} token
*/
async validate(token) {
if (config.mockVerae) return mockValidate(token);
return request('/auth/validate', { token });
},
/**
* @param {string} token
* @param {{ data: string, hashAlg?: string }} body
*/
async createTimestamp(token, body) {
if (config.mockVerae) return mockCreateTimestamp(body);
return request('/api/timestamp', { method: 'POST', token, body });
},
/**
* @param {string} token
* @param {{ items: Array<{ data: string, hashAlg?: string }> }} body
*/
async createBatchTimestamp(token, body) {
if (config.mockVerae) {
const jobIds = [];
for (const item of body.items ?? []) {
const res = await mockCreateTimestamp(item);
jobIds.push(res.jobId);
}
return { jobIds };
}
return request('/api/batch/timestamp', { method: 'POST', token, body });
},
/**
* @param {string} token
* @param {string} jobId
*/
async getStatus(token, jobId) {
if (config.mockVerae) return mockGetStatus(jobId);
return request(`/api/status/${encodeURIComponent(jobId)}`, { token });
},
/**
* @param {string} token
* @param {{ jobIds: string[] }} body
*/
async getBatchStatus(token, body) {
if (config.mockVerae) {
const results = {};
for (const jobId of body.jobIds ?? []) {
results[jobId] = await mockGetStatus(jobId);
}
return { results };
}
return request('/api/batch/status', { method: 'POST', token, body });
},
/**
* @param {string} token
* @param {{ certificate: string }} body
*/
async verify(token, body) {
if (config.mockVerae) return mockVerify(body);
return request('/api/verify', { method: 'POST', token, body });
},
/**
* @param {string} token
* @param {{ certificates: string[] }} body
*/
async verifyBatch(token, body) {
if (config.mockVerae) {
const results = [];
for (const certificate of body.certificates ?? []) {
results.push(await mockVerify({ certificate }));
}
return { results };
}
return request('/api/batch/verify', { method: 'POST', token, body });
},
/**
* @param {string} token
* @param {string} jobId
*/
async getJobVerification(token, jobId) {
if (config.mockVerae) return mockGetStatus(jobId);
return request(`/api/verify/${encodeURIComponent(jobId)}`, { token });
},
/**
* Poll until completed/failed or timeout.
* @param {string} token
* @param {string} jobId
* @param {{ maxAttempts: number, intervalMs: number }} options
*/
async waitForJob(token, jobId, { maxAttempts, intervalMs }) {
for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
const status = await this.getStatus(token, jobId);
if (status.status === 'completed' || status.status === 'failed') {
return status;
}
await delay(intervalMs);
}
throw new AppError(`Job ${jobId} timed out`, { status: 504, code: 'GATEWAY_TIMEOUT' });
},
};
/**
* Clear mock jobs (tests only).
* @returns {void}
*/
export function clearMockJobs() {
mockJobs.clear();
}

View file

@ -0,0 +1,142 @@
/**
* @fileoverview Process configuration for the Verae Zapier middleware.
* @module config
*
* Loads optional `.env` then exports typed settings used by HTTP, NATS, and workers.
*/
import { readFileSync, existsSync } from 'node:fs';
import { resolve, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { createDebugger } from './debug/logger.js';
const log = createDebugger('app');
const __dirname = dirname(fileURLToPath(import.meta.url));
const rootDir = resolve(__dirname, '..');
/**
* Load KEY=VALUE pairs from `.env` without overriding existing process.env keys.
* @returns {void}
*/
export function loadEnvFile() {
const envPath = resolve(rootDir, '.env');
if (!existsSync(envPath)) return;
for (const line of readFileSync(envPath, 'utf8').split('\n')) {
const trimmed = line.trim();
if (!trimmed || trimmed.startsWith('#')) continue;
const eq = trimmed.indexOf('=');
if (eq === -1) continue;
const key = trimmed.slice(0, eq).trim();
const value = trimmed.slice(eq + 1).trim();
if (!(key in process.env)) {
process.env[key] = value;
}
}
}
loadEnvFile();
/**
* @param {string|undefined} value
* @param {boolean} [fallback=false]
* @returns {boolean}
*/
function bool(value, fallback = false) {
if (value === undefined) return fallback;
return ['1', 'true', 'yes', 'on'].includes(String(value).toLowerCase());
}
/**
* @param {string|undefined} value
* @param {number} fallback
* @returns {number}
*/
function int(value, fallback) {
const parsed = Number.parseInt(value ?? '', 10);
return Number.isFinite(parsed) ? parsed : fallback;
}
/**
* Runtime configuration object.
* @type {{
* port: number,
* host: string,
* veraeApiBaseUrl: string,
* mockVerae: boolean,
* natsEnabled: boolean,
* natsUrl: string,
* tokenSecret: string,
* jobPollIntervalMs: number,
* jobPollMaxAttempts: number,
* storePath: string,
* upgradeUrl: string,
* adminSecret: string,
* }}
*/
export const config = {
port: int(process.env.PORT, 3100),
host: process.env.HOST ?? '0.0.0.0',
veraeApiBaseUrl: (process.env.VERAE_API_BASE_URL ?? 'http://localhost:8080').replace(
/\/$/,
'',
),
mockVerae: bool(process.env.MOCK_VERAE, false),
natsEnabled: bool(process.env.NATS_ENABLED, false),
natsUrl: process.env.NATS_URL ?? 'nats://127.0.0.1:4222',
tokenSecret: process.env.TOKEN_SECRET ?? 'dev-secret-change-me',
jobPollIntervalMs: int(process.env.JOB_POLL_INTERVAL_MS, 2000),
jobPollMaxAttempts: int(process.env.JOB_POLL_MAX_ATTEMPTS, 60),
storePath: resolve(rootDir, process.env.STORE_PATH ?? './data/store.json'),
upgradeUrl: process.env.UPGRADE_URL ?? 'https://veraetime.net/billing',
adminSecret: process.env.ADMIN_SECRET ?? 'change-me-admin',
};
/**
* Default plan limits. `null` numeric fields mean unlimited.
* @type {Record<string, {
* timestamps: number|null,
* verifications: number|null,
* batch: boolean,
* batchMaxItems: number|null,
* requestsPerMinute: number
* }>}
*/
export const PLAN_LIMITS = {
free: {
timestamps: 50,
verifications: 50,
batch: false,
batchMaxItems: 0,
requestsPerMinute: 30,
},
starter: {
timestamps: 500,
verifications: 500,
batch: true,
batchMaxItems: 10,
requestsPerMinute: 120,
},
pro: {
timestamps: 5000,
verifications: 5000,
batch: true,
batchMaxItems: 100,
requestsPerMinute: 600,
},
enterprise: {
timestamps: null,
verifications: null,
batch: true,
batchMaxItems: null,
requestsPerMinute: 3000,
},
};
log.info('config loaded', {
veraeApiBaseUrl: config.veraeApiBaseUrl,
mockVerae: config.mockVerae,
natsEnabled: config.natsEnabled,
natsUrl: config.natsUrl,
port: config.port,
});

View file

@ -0,0 +1,106 @@
/**
* @fileoverview Runtime debug configuration.
*
* Reads process environment at call time of {@link loadDebugConfig} so tests can
* mutate `process.env` between cases. Production servers typically load once at boot.
*
* @module debug/config
*/
/**
* @typedef {Object} DebugConfig
* @property {boolean} enabled - True when any debug output should be produced.
* @property {Set<string>|null} namespaces - Allowed namespaces; `null` means all.
* @property {'debug'|'info'|'warn'|'error'} level - Minimum severity to emit.
* @property {string|null} filePath - Optional secondary log file path.
*/
const LEVEL_ORDER = { debug: 10, info: 20, warn: 30, error: 40 };
/**
* Parse `DEBUG_VERAE` into an enabled flag and optional namespace allow-list.
*
* @param {string|undefined} raw - Raw env value (e.g. `"1"`, `"*"`, `"auth,nats"`).
* @returns {{ enabled: boolean, namespaces: Set<string>|null }}
*
* @example
* parseDebugVeraeEnv('auth,jobs'); // { enabled: true, namespaces: Set{'auth','jobs'} }
* parseDebugVeraeEnv(undefined); // { enabled: false, namespaces: null }
*/
export function parseDebugVeraeEnv(raw) {
if (raw === undefined || raw === null) {
return { enabled: false, namespaces: null };
}
const trimmed = String(raw).trim();
if (!trimmed || trimmed === '0' || trimmed.toLowerCase() === 'false' || trimmed.toLowerCase() === 'off') {
return { enabled: false, namespaces: null };
}
if (trimmed === '1' || trimmed === '*' || trimmed.toLowerCase() === 'true' || trimmed.toLowerCase() === 'all') {
return { enabled: true, namespaces: null };
}
const parts = trimmed
.split(',')
.map((p) => p.trim().toLowerCase())
.filter(Boolean);
if (parts.length === 0) {
return { enabled: false, namespaces: null };
}
return { enabled: true, namespaces: new Set(parts) };
}
/**
* Normalize a level string to a known level.
*
* @param {string|undefined} raw - Env level value.
* @param {'debug'|'info'|'warn'|'error'} [fallback='debug'] - Default level.
* @returns {'debug'|'info'|'warn'|'error'}
*/
export function parseLevel(raw, fallback = 'debug') {
const value = String(raw ?? fallback).toLowerCase();
if (value in LEVEL_ORDER) return /** @type {'debug'|'info'|'warn'|'error'} */ (value);
return fallback;
}
/**
* Load full debug configuration from `process.env`.
*
* Environment variables:
* - `DEBUG_VERAE` — enable + namespaces (see {@link parseDebugVeraeEnv})
* - `DEBUG_VERAE_LEVEL` — minimum level
* - `DEBUG_VERAE_FILE` — optional log file path
*
* @param {NodeJS.ProcessEnv} [env=process.env] - Environment map (injectable for tests).
* @returns {DebugConfig}
*/
export function loadDebugConfig(env = process.env) {
const { enabled, namespaces } = parseDebugVeraeEnv(env.DEBUG_VERAE);
return {
enabled,
namespaces,
level: parseLevel(env.DEBUG_VERAE_LEVEL, 'debug'),
filePath: env.DEBUG_VERAE_FILE ? String(env.DEBUG_VERAE_FILE) : null,
};
}
/**
* Whether a message at `messageLevel` in `namespace` should be emitted.
*
* @param {DebugConfig} config - Active config.
* @param {string} namespace - Logger namespace (e.g. `auth`).
* @param {'debug'|'info'|'warn'|'error'} messageLevel - Message severity.
* @returns {boolean}
*/
export function shouldLog(config, namespace, messageLevel) {
if (!config.enabled) return false;
if (config.namespaces && !config.namespaces.has(String(namespace).toLowerCase())) {
return false;
}
return LEVEL_ORDER[messageLevel] >= LEVEL_ORDER[config.level];
}
export { LEVEL_ORDER };

View file

@ -0,0 +1,24 @@
/**
* @fileoverview Public exports for the runtime debug facility.
* @module debug
*/
export {
loadDebugConfig,
parseDebugVeraeEnv,
parseLevel,
shouldLog,
LEVEL_ORDER,
} from './config.js';
export { createDebugger, formatLogLine, setDebugTestSink } from './logger.js';
export { redact, redactString } from './redact.js';
export {
generateTraceId,
getTraceId,
getTraceContext,
withTrace,
traceMiddleware,
} from './trace.js';

View file

@ -0,0 +1,121 @@
/**
* @fileoverview Namespaced debug logger with runtime enable/disable.
* @module debug/logger
*/
import { appendFileSync } from 'node:fs';
import { loadDebugConfig, shouldLog } from './config.js';
import { redact } from './redact.js';
import { getTraceId } from './trace-context.js';
/**
* @typedef {Object} Debugger
* @property {(msg: string, meta?: Record<string, unknown>) => void} debug
* @property {(msg: string, meta?: Record<string, unknown>) => void} info
* @property {(msg: string, meta?: Record<string, unknown>) => void} warn
* @property {(msg: string, meta?: Record<string, unknown>) => void} error
* @property {string} namespace
*/
/**
* Optional sink for tests — when set, lines go here instead of/in addition to stderr.
* @type {null|((line: string) => void)}
*/
let testSink = null;
/**
* Install a test sink that captures formatted log lines.
* Used only by unit tests; do not use in production code.
*
* @param {null|((line: string) => void)} sink - Callback or null to clear.
* @returns {void}
*/
export function setDebugTestSink(sink) {
testSink = sink;
}
/**
* Format a single log line.
*
* @param {object} parts
* @param {string} parts.level
* @param {string} parts.namespace
* @param {string} parts.message
* @param {Record<string, unknown>|undefined} parts.meta
* @param {string|null} parts.traceId
* @returns {string}
*/
export function formatLogLine({ level, namespace, message, meta, traceId }) {
const ts = new Date().toISOString();
const tracePart = traceId ? ` [trace=${traceId}]` : '';
const metaPart =
meta && Object.keys(meta).length > 0 ? ` ${JSON.stringify(redact(meta))}` : '';
return `${ts} ${level.toUpperCase()} ${namespace}${tracePart} ${message}${metaPart}`;
}
/**
* Emit a log line to stderr, optional file, and optional test sink.
*
* @param {string} line - Full formatted line.
* @param {string|null} filePath - Optional file from config.
* @returns {void}
*/
function emit(line, filePath) {
if (testSink) {
testSink(line);
} else {
// eslint-disable-next-line no-console
console.error(line);
}
if (filePath) {
try {
appendFileSync(filePath, `${line}\n`, 'utf8');
} catch {
// ignore file errors in debug path
}
}
}
/**
* Create a namespaced debugger bound to current env configuration.
*
* Configuration is re-read on every log call so tests can toggle `DEBUG_VERAE`
* without reloading modules. Slight cost is acceptable for debug-only paths.
*
* @param {string} namespace - Namespace such as `auth`, `nats`, `jobs`.
* @returns {Debugger} Logger with debug/info/warn/error methods.
*
* @example
* const log = createDebugger('jobs');
* log.debug('poll start', { jobId: 'abc' });
*/
export function createDebugger(namespace) {
const ns = String(namespace || 'app').toLowerCase();
/**
* @param {'debug'|'info'|'warn'|'error'} level
* @param {string} message
* @param {Record<string, unknown>} [meta]
*/
function write(level, message, meta) {
const config = loadDebugConfig();
if (!shouldLog(config, ns, level)) return;
const line = formatLogLine({
level,
namespace: ns,
message: String(message),
meta,
traceId: getTraceId(),
});
emit(line, config.filePath);
}
return {
namespace: ns,
debug: (message, meta) => write('debug', message, meta),
info: (message, meta) => write('info', message, meta),
warn: (message, meta) => write('warn', message, meta),
error: (message, meta) => write('error', message, meta),
};
}

View file

@ -0,0 +1,93 @@
/**
* @fileoverview Secret redaction for debug logs.
* @module debug/redact
*/
const SENSITIVE_KEYS = new Set([
'password',
'veraepassword',
'token',
'veraetoken',
'accesstoken',
'apikey',
'api_key',
'secret',
'authorization',
'x-api-key',
'cookie',
'sessionkey',
]);
const BEARER_RE = /^Bearer\s+.+/i;
const API_KEY_RE = /^zmw_[A-Za-z0-9_-]+/;
const SESSION_RE = /^zmt_[A-Za-z0-9_.-]+/;
const JWT_RE = /^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/;
/**
* Redact a single string value if it looks like a secret.
*
* @param {string} value - Raw string.
* @returns {string} Original or `[REDACTED]`.
*/
export function redactString(value) {
if (typeof value !== 'string') return value;
if (
BEARER_RE.test(value) ||
API_KEY_RE.test(value) ||
SESSION_RE.test(value) ||
JWT_RE.test(value)
) {
return '[REDACTED]';
}
return value;
}
/**
* Deep-clone plain data structures while redacting sensitive keys and values.
*
* @param {unknown} input - Any JSON-like value.
* @param {number} [depth=0] - Recursion depth guard.
* @returns {unknown} Redacted structure safe for logging.
*
* @example
* redact({ password: 'x', jobId: '1' }); // { password: '[REDACTED]', jobId: '1' }
*/
export function redact(input, depth = 0) {
if (depth > 8) return '[MaxDepth]';
if (input === null || input === undefined) return input;
if (typeof input === 'string') return redactString(input);
if (typeof input === 'number' || typeof input === 'boolean') return input;
if (input instanceof Error) {
return { name: input.name, message: redactString(input.message), stack: undefined };
}
if (Array.isArray(input)) {
return input.map((item) => redact(item, depth + 1));
}
if (typeof input === 'object') {
/** @type {Record<string, unknown>} */
const out = {};
for (const [key, value] of Object.entries(input)) {
if (SENSITIVE_KEYS.has(key.toLowerCase())) {
out[key] = '[REDACTED]';
} else if (key.toLowerCase() === 'targeturl' && typeof value === 'string') {
try {
const u = new URL(value);
out[key] = `${u.origin}${u.pathname}`;
} catch {
out[key] = '[REDACTED_URL]';
}
} else {
out[key] = redact(value, depth + 1);
}
}
return out;
}
return String(input);
}

View file

@ -0,0 +1,39 @@
/**
* @fileoverview AsyncLocalStorage-backed trace context (no logger dependency).
* Split from trace.js to avoid circular imports with logger.js.
* @module debug/trace-context
*/
import { AsyncLocalStorage } from 'node:async_hooks';
import { randomBytes } from 'node:crypto';
/**
* @typedef {Object} TraceContext
* @property {string} traceId
* @property {string} [span]
*/
/** @type {AsyncLocalStorage<TraceContext>} */
export const traceStorage = new AsyncLocalStorage();
/**
* Generate a short opaque trace id (16 hex chars).
* @returns {string}
*/
export function generateTraceId() {
return randomBytes(8).toString('hex');
}
/**
* @returns {string|null}
*/
export function getTraceId() {
return traceStorage.getStore()?.traceId ?? null;
}
/**
* @returns {TraceContext|null}
*/
export function getTraceContext() {
return traceStorage.getStore() ?? null;
}

View file

@ -0,0 +1,95 @@
/**
* @fileoverview Correlation / trace IDs for failure tracing across HTTP and NATS.
* @module debug/trace
*/
import { createDebugger } from './logger.js';
import {
traceStorage,
generateTraceId,
getTraceId,
getTraceContext,
} from './trace-context.js';
export { generateTraceId, getTraceId, getTraceContext };
const log = createDebugger('trace');
/**
* Run `fn` within a trace context. Nested calls inherit the same `traceId`
* unless `traceId` is explicitly overridden.
*
* @template T
* @param {object|(() => T|Promise<T>)} options - Options or the callback itself.
* @param {string} [options.traceId] - Existing id (e.g. from `X-Trace-Id` header).
* @param {string} [options.span] - Human label for this span (logged when debug on).
* @param {() => T|Promise<T>} [fn] - Work to execute inside the context when options is an object.
* @returns {T|Promise<T>} Return value of `fn`.
*
* @example
* await withTrace({ span: 'timestamp.wait', traceId: req.headers['x-trace-id'] }, async () => {
* // getTraceId() is stable here and in awaited children
* });
*/
export function withTrace(options, fn) {
const opts = typeof options === 'function' ? {} : options ?? {};
const callback = typeof options === 'function' ? options : fn;
if (typeof callback !== 'function') {
throw new TypeError('withTrace requires a function to execute');
}
const parent = traceStorage.getStore();
const traceId = opts.traceId || parent?.traceId || generateTraceId();
const span = opts.span || parent?.span || 'root';
const ctx = { traceId, span };
return traceStorage.run(ctx, () => {
log.debug('span enter', { span });
try {
const result = callback();
if (result && typeof result.then === 'function') {
return result.then(
(value) => {
log.debug('span exit', { span, ok: true });
return value;
},
(err) => {
log.debug('span exit', { span, ok: false, error: err?.message });
throw err;
},
);
}
log.debug('span exit', { span, ok: true });
return result;
} catch (err) {
log.debug('span exit', { span, ok: false, error: err?.message });
throw err;
}
});
}
/**
* Express middleware that establishes a trace context per request.
*
* Reads `X-Trace-Id` when present; otherwise generates a new id.
* Sets `req.traceId` and response header `X-Trace-Id`.
*
* @param {import('express').Request} req
* @param {import('express').Response} res
* @param {import('express').NextFunction} next
* @returns {void}
*/
export function traceMiddleware(req, res, next) {
const incoming = req.headers['x-trace-id'];
const traceId =
typeof incoming === 'string' && incoming.trim() ? incoming.trim() : generateTraceId();
req.traceId = traceId;
res.setHeader('X-Trace-Id', traceId);
withTrace({ traceId, span: `${req.method} ${req.path}` }, () => {
next();
});
}

View file

@ -0,0 +1,75 @@
/**
* @fileoverview Structured errors and Express helpers.
* @module errors
*/
import { createDebugger } from './debug/logger.js';
import { getTraceId } from './debug/trace-context.js';
const log = createDebugger('app');
/**
* Operational error with HTTP status and machine-readable code.
*/
export class AppError extends Error {
/**
* @param {string} message - Human-readable error.
* @param {object} [options]
* @param {number} [options.status=500] - HTTP status code.
* @param {string} [options.code='INTERNAL_ERROR'] - Machine code.
* @param {unknown} [options.details] - Optional structured details (safe for clients).
*/
constructor(message, { status = 500, code = 'INTERNAL_ERROR', details } = {}) {
super(message);
this.name = 'AppError';
this.status = status;
this.code = code;
this.details = details;
}
}
/**
* Wrap an async Express handler so rejected promises reach the error middleware.
*
* @param {(req: import('express').Request, res: import('express').Response, next: import('express').NextFunction) => Promise<unknown>} fn
* @returns {import('express').RequestHandler}
*/
export function asyncHandler(fn) {
return (req, res, next) => {
Promise.resolve(fn(req, res, next)).catch(next);
};
}
/**
* Send a JSON error response. Logs server errors when debug is enabled.
*
* @param {import('express').Response} res
* @param {Error|AppError} err
* @returns {void}
*/
export function sendError(res, err) {
const status = err instanceof AppError ? err.status : 500;
const code = err instanceof AppError ? err.code : 'INTERNAL_ERROR';
const message = err?.message || 'Internal server error';
const details = err instanceof AppError ? err.details : undefined;
const traceId = getTraceId();
if (status >= 500) {
log.error('request failed', {
status,
code,
message,
traceId,
stack: err?.stack,
});
} else {
log.debug('client error', { status, code, message, traceId });
}
res.status(status).json({
error: message,
code,
...(details !== undefined ? { details } : {}),
...(traceId ? { traceId } : {}),
});
}

View file

@ -0,0 +1,51 @@
/**
* @fileoverview Process entrypoint: HTTP listen + optional in-process poller.
* @module index
*/
import { createApp } from './app.js';
import { config } from './config.js';
import { createDebugger } from './debug/logger.js';
import { startInProcessJobPoller } from './workers/inProcessJobPoller.js';
import { connectNats, ensureStreams } from './nats/connection.js';
import { startJobPollerWorker } from './workers/jobPollerWorker.js';
import { startWebhookWorker } from './workers/webhookWorker.js';
const log = createDebugger('app');
/**
* Start the HTTP server and background workers.
* @returns {import('http').Server}
*/
export function startServer() {
const app = createApp();
if (config.natsEnabled) {
connectNats()
.then(({ jsm }) => ensureStreams(jsm))
.then(() => Promise.all([startJobPollerWorker(), startWebhookWorker()]))
.then(() => log.info('NATS workers started'))
.catch((err) => log.error('NATS worker start failed', { error: err.message }));
} else {
startInProcessJobPoller();
}
const server = app.listen(config.port, config.host, () => {
log.info('middleware listening', {
host: config.host,
port: config.port,
veraeApiBaseUrl: config.veraeApiBaseUrl,
mockVerae: config.mockVerae,
natsEnabled: config.natsEnabled,
});
// eslint-disable-next-line no-console
console.log(
`Verae Zapier middleware listening on http://${config.host}:${config.port}`,
);
});
return server;
}
if (process.argv[1]?.includes('index.js')) {
startServer();
}

View file

@ -0,0 +1,97 @@
/**
* @fileoverview API keys and HMAC session tokens for the middleware auth bridge.
* @module lib/tokens
*/
import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
import { config } from '../config.js';
const TOKEN_PREFIX = 'zmt_';
const API_KEY_PREFIX = 'zmw_';
/**
* @param {string} payload
* @returns {string}
*/
function sign(payload) {
return createHmac('sha256', config.tokenSecret).update(payload).digest('base64url');
}
/**
* Issue a signed middleware session token embedding tenant + Verae JWT.
*
* @param {object} params
* @param {string} params.tenantId
* @param {string} params.veraeToken
* @param {string} [params.expiresAt]
* @returns {string} Token string starting with `zmt_`
*/
export function issueSessionToken({ tenantId, veraeToken, expiresAt }) {
const payload = Buffer.from(
JSON.stringify({
tenantId,
veraeToken,
expiresAt,
nonce: randomBytes(8).toString('hex'),
}),
).toString('base64url');
const signature = sign(payload);
return `${TOKEN_PREFIX}${payload}.${signature}`;
}
/**
* Parse and verify a session token.
*
* @param {string} token
* @returns {{ tenantId: string, veraeToken: string, expiresAt?: string, nonce?: string }|null}
*/
export function parseSessionToken(token) {
if (!token?.startsWith(TOKEN_PREFIX)) return null;
const raw = token.slice(TOKEN_PREFIX.length);
const dot = raw.lastIndexOf('.');
if (dot === -1) return null;
const payload = raw.slice(0, dot);
const signature = raw.slice(dot + 1);
const expected = sign(payload);
const sigBuf = Buffer.from(signature);
const expBuf = Buffer.from(expected);
if (sigBuf.length !== expBuf.length || !timingSafeEqual(sigBuf, expBuf)) {
return null;
}
try {
return JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
} catch {
return null;
}
}
/**
* Generate a new public API key (`zmw_…`).
* @returns {string}
*/
export function generateApiKey() {
return `${API_KEY_PREFIX}${randomBytes(24).toString('base64url')}`;
}
/**
* @param {unknown} value
* @returns {boolean}
*/
export function isApiKey(value) {
return typeof value === 'string' && value.startsWith(API_KEY_PREFIX);
}
/**
* Extract bearer credential from an Authorization header.
* @param {string|undefined} header
* @returns {string|null}
*/
export function extractBearerToken(header) {
if (!header) return null;
const match = String(header).match(/^Bearer\s+(.+)$/i);
return match?.[1] ?? null;
}

View file

@ -0,0 +1,27 @@
/**
* @fileoverview Express auth middleware — populates req.auth.
* @module middleware/authenticate
*/
import { extractBearerToken } from '../lib/tokens.js';
import { resolveAuthContext } from '../services/authService.js';
import { asyncHandler } from '../errors.js';
import { createDebugger } from '../debug/logger.js';
const log = createDebugger('auth');
/**
* Resolve Bearer or x-api-key into `req.auth`.
*/
export const authenticate = asyncHandler(async (req, res, next) => {
const rawToken =
extractBearerToken(req.headers.authorization) ?? req.headers['x-api-key'] ?? null;
req.auth = await resolveAuthContext(rawToken);
log.debug('authenticated', {
tenantId: req.auth.tenantId,
method: req.auth.authMethod,
plan: req.auth.tenant?.plan,
});
next();
});

View file

@ -0,0 +1,56 @@
/**
* @fileoverview Simple in-memory per-tenant rate limiter.
* @module middleware/rateLimit
*/
import { AppError, asyncHandler } from '../errors.js';
import { getTenant, resolveLimits } from '../store/tenants.js';
import { createDebugger } from '../debug/logger.js';
const log = createDebugger('billing');
/** @type {Map<string, { windowStart: number, count: number }>} */
const windows = new Map();
/**
* Reset rate limit windows (tests).
* @returns {void}
*/
export function resetRateLimitWindows() {
windows.clear();
}
/**
* Enforce plan requestsPerMinute using a 60s sliding fixed window.
*/
export const rateLimit = asyncHandler(async (req, res, next) => {
const tenantId = req.auth?.tenantId;
if (!tenantId) return next();
const tenant = getTenant(tenantId);
const limits = tenant
? resolveLimits(tenant)
: { requestsPerMinute: 30 };
const rpm = limits.requestsPerMinute ?? 30;
const now = Date.now();
const windowMs = 60_000;
let entry = windows.get(tenantId);
if (!entry || now - entry.windowStart >= windowMs) {
entry = { windowStart: now, count: 0 };
windows.set(tenantId, entry);
}
entry.count += 1;
if (entry.count > rpm) {
log.debug('rate limited', { tenantId, count: entry.count, rpm });
throw new AppError('Rate limit exceeded', {
status: 429,
code: 'RATE_LIMITED',
details: { requestsPerMinute: rpm },
});
}
next();
});

View file

@ -0,0 +1,111 @@
/**
* @fileoverview NATS + JetStream connection lifecycle.
* @module nats/connection
*/
import { createDebugger } from '../debug/logger.js';
import { config } from '../config.js';
import { SUBJECTS, STREAMS } from './subjects.js';
const log = createDebugger('nats');
/** @type {import('nats').NatsConnection|null} */
let nc = null;
/** @type {import('nats').JetStreamClient|null} */
let js = null;
/** @type {import('nats').JetStreamManager|null} */
let jsm = null;
/**
* Connect to NATS and return JetStream handles.
*
* @param {string} [url=config.natsUrl]
* @returns {Promise<{ nc: import('nats').NatsConnection, js: import('nats').JetStreamClient, jsm: import('nats').JetStreamManager }>}
*/
export async function connectNats(url = config.natsUrl) {
if (!config.natsEnabled && process.env.NATS_FORCE_CONNECT !== '1') {
log.debug('connect skipped — NATS_ENABLED=false');
throw new Error('NATS is disabled (NATS_ENABLED=false)');
}
if (nc && js && jsm) {
return { nc, js, jsm };
}
log.info('connecting to NATS', { url });
const { connect } = await import('nats');
nc = await connect({ servers: url, name: 'verae-zapier-middleware' });
js = nc.jetstream();
jsm = await nc.jetstreamManager();
log.info('NATS connected', { url });
return { nc, js, jsm };
}
/**
* Idempotently create JetStream streams required by this middleware.
*
* @param {import('nats').JetStreamManager} [manager]
* @returns {Promise<void>}
*/
export async function ensureStreams(manager) {
const m = manager ?? jsm;
if (!m) {
throw new Error('JetStream manager not available — call connectNats first');
}
/** @type {Array<{ name: string, subjects: string[] }>} */
const defs = [
{ name: STREAMS.ZAPIER_JOBS, subjects: [SUBJECTS.JOBS_WATCH] },
{ name: STREAMS.ZAPIER_EVENTS, subjects: [SUBJECTS.JOBS_EVENTS] },
{ name: STREAMS.ZAPIER_WEBHOOKS, subjects: [SUBJECTS.WEBHOOKS_DELIVER] },
];
for (const def of defs) {
try {
await m.streams.info(def.name);
log.debug('stream exists', { stream: def.name });
} catch {
await m.streams.add({
name: def.name,
subjects: def.subjects,
retention: 'limits',
storage: 'file',
max_age: 24 * 60 * 60 * 1e9, // 24h in ns
num_replicas: 1,
});
log.info('stream created', { stream: def.name, subjects: def.subjects });
}
}
}
/**
* Close the shared NATS connection if open.
* @returns {Promise<void>}
*/
export async function closeNats() {
if (!nc) {
log.debug('closeNats: no active connection');
return;
}
log.info('closing NATS connection');
await nc.drain();
nc = null;
js = null;
jsm = null;
}
/**
* @returns {import('nats').JetStreamClient|null}
*/
export function getJetStream() {
return js;
}
/**
* @returns {boolean}
*/
export function isNatsConnected() {
return Boolean(nc && !nc.isClosed());
}

View file

@ -0,0 +1,95 @@
/**
* @fileoverview JetStream publishers for jobs, events, and webhooks.
* @module nats/publishers
*/
import { createDebugger } from '../debug/logger.js';
import { getTraceId } from '../debug/trace-context.js';
import { SUBJECTS } from './subjects.js';
import { getJetStream, connectNats } from './connection.js';
const log = createDebugger('nats');
/**
* @returns {Promise<import('nats').JetStreamClient>}
*/
async function requireJs() {
let js = getJetStream();
if (!js) {
const handles = await connectNats();
js = handles.js;
}
return js;
}
/**
* @param {object} partial
* @returns {Promise<{ seq: number }>}
*/
export async function enqueueWatch(partial) {
const msg = {
attempt: 0,
enqueuedAt: new Date().toISOString(),
traceId: getTraceId() || 'no-trace',
...partial,
};
log.debug('enqueueWatch', {
subject: SUBJECTS.JOBS_WATCH,
tenantId: msg.tenantId,
jobId: msg.jobId,
attempt: msg.attempt,
traceId: msg.traceId,
});
const js = await requireJs();
const ack = await js.publish(SUBJECTS.JOBS_WATCH, JSON.stringify(msg));
return { seq: Number(ack.seq) };
}
/**
* @param {object} partial
* @returns {Promise<{ seq: number }>}
*/
export async function publishJobEvent(partial) {
const msg = {
emittedAt: new Date().toISOString(),
traceId: getTraceId() || 'no-trace',
...partial,
};
log.debug('publishJobEvent', {
subject: SUBJECTS.JOBS_EVENTS,
event: msg.event,
jobId: msg.jobId,
tenantId: msg.tenantId,
});
const js = await requireJs();
const ack = await js.publish(SUBJECTS.JOBS_EVENTS, JSON.stringify(msg));
return { seq: Number(ack.seq) };
}
/**
* @param {object} partial
* @returns {Promise<{ seq: number }>}
*/
export async function enqueueWebhook(partial) {
const msg = {
attempt: 1,
traceId: getTraceId() || 'no-trace',
...partial,
};
log.debug('enqueueWebhook', {
subject: SUBJECTS.WEBHOOKS_DELIVER,
hookId: msg.hookId,
tenantId: msg.tenantId,
event: msg.event,
targetUrl: msg.targetUrl,
});
const js = await requireJs();
const ack = await js.publish(SUBJECTS.WEBHOOKS_DELIVER, JSON.stringify(msg));
return { seq: Number(ack.seq) };
}

View file

@ -0,0 +1,43 @@
/**
* @fileoverview NATS subject and stream name constants.
* @module nats/subjects
*
* See docs/architecture/nats-subjects.md for payload schemas.
*/
/**
* Subject strings used by publishers and consumers.
* @readonly
*/
export const SUBJECTS = Object.freeze({
/** Work queue: poll Verae job status */
JOBS_WATCH: 'verae.zapier.jobs.watch',
/** Terminal job outcomes */
JOBS_EVENTS: 'verae.zapier.jobs.events',
/** Work queue: HTTP POST to Zapier REST Hooks */
WEBHOOKS_DELIVER: 'verae.zapier.webhooks.deliver',
/** Optional metering stream */
USAGE: 'verae.zapier.usage',
});
/**
* JetStream stream names.
* @readonly
*/
export const STREAMS = Object.freeze({
ZAPIER_JOBS: 'ZAPIER_JOBS',
ZAPIER_EVENTS: 'ZAPIER_EVENTS',
ZAPIER_WEBHOOKS: 'ZAPIER_WEBHOOKS',
ZAPIER_USAGE: 'ZAPIER_USAGE',
});
/**
* Durable consumer names (queue groups).
* @readonly
*/
export const CONSUMERS = Object.freeze({
JOB_POLLER: 'job-poller',
EVENT_WEBHOOK_ROUTER: 'event-webhook-router',
WEBHOOK_DELIVER: 'webhook-deliver',
USAGE_WRITER: 'usage-writer',
});

View file

@ -0,0 +1,57 @@
/**
* @fileoverview Auth routes under /zapier/v1/auth
* @module routes/authRoutes
*/
import { Router } from 'express';
import { asyncHandler, AppError } from '../errors.js';
import { loginWithCredentials, loginWithApiKey, validateSession } from '../services/authService.js';
import { getUsageSummary } from '../store/usage.js';
import { getTenant } from '../store/tenants.js';
import { extractBearerToken } from '../lib/tokens.js';
export const authRoutes = Router();
authRoutes.post(
'/login',
asyncHandler(async (req, res) => {
const { username, password, api_key: apiKey } = req.body ?? {};
if (apiKey) {
const session = await loginWithApiKey(apiKey);
return res.json(session);
}
if (!username || !password) {
throw new AppError('username and password are required', {
status: 400,
code: 'VALIDATION_ERROR',
});
}
const session = await loginWithCredentials({ username, password });
res.json(session);
}),
);
authRoutes.get(
'/me',
asyncHandler(async (req, res) => {
const rawToken =
extractBearerToken(req.headers.authorization) ?? req.headers['x-api-key'] ?? null;
if (!rawToken) {
throw new AppError('Missing authorization token', { status: 401, code: 'UNAUTHORIZED' });
}
const validation = await validateSession(rawToken);
const tenant = getTenant(validation.tenantId);
const usage = getUsageSummary(validation.tenantId);
res.json({
...validation,
plan: tenant?.plan ?? validation.plan ?? 'free',
usage,
});
}),
);

View file

@ -0,0 +1,33 @@
/**
* @fileoverview Mount all /zapier routes.
* @module routes/index
*/
import { Router } from 'express';
import { authRoutes } from './authRoutes.js';
import { timestampRoutes } from './timestampRoutes.js';
import { verifyRoutes } from './verifyRoutes.js';
import { statusRoutes } from './statusRoutes.js';
import { webhookRoutes } from './webhookRoutes.js';
import { publicTenantRoutes, adminTenantRoutes } from './tenantRoutes.js';
import { authenticate } from '../middleware/authenticate.js';
import { rateLimit } from '../middleware/rateLimit.js';
export const apiRoutes = Router();
// Public
apiRoutes.use('/v1/auth', authRoutes);
apiRoutes.use('/v1', publicTenantRoutes);
apiRoutes.use('/v1/admin', adminTenantRoutes);
// Protected
const protectedRoutes = Router();
protectedRoutes.use(authenticate);
protectedRoutes.use(rateLimit);
protectedRoutes.use('/timestamp', timestampRoutes);
protectedRoutes.use('/verify', verifyRoutes);
protectedRoutes.use('/status', statusRoutes);
protectedRoutes.use('/webhooks', webhookRoutes);
apiRoutes.use('/v1', protectedRoutes);

View file

@ -0,0 +1,46 @@
/**
* @module routes/statusRoutes
*/
import { Router } from 'express';
import { asyncHandler, AppError } from '../errors.js';
import {
getJobStatus,
getBatchJobStatus,
getJobVerification,
} from '../services/timestampService.js';
export const statusRoutes = Router();
// Static/more-specific routes first
statusRoutes.post(
'/batch',
asyncHandler(async (req, res) => {
const { jobIds } = req.body ?? {};
if (!Array.isArray(jobIds) || jobIds.length === 0) {
throw new AppError('jobIds array is required', { status: 400, code: 'VALIDATION_ERROR' });
}
const result = await getBatchJobStatus(req.auth, { jobIds });
res.json(result);
}),
);
statusRoutes.get(
'/:jobId/verification',
asyncHandler(async (req, res) => {
const result = await getJobVerification(req.auth, req.params.jobId);
res.json(result);
}),
);
statusRoutes.get(
'/:jobId',
asyncHandler(async (req, res) => {
const { jobId } = req.params;
if (!jobId) {
throw new AppError('jobId is required', { status: 400, code: 'VALIDATION_ERROR' });
}
const result = await getJobStatus(req.auth, jobId);
res.json(result);
}),
);

Some files were not shown because too many files have changed in this diff Show more