watahub 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 El Hub Ventures Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,333 @@
-# Temporary Holding Version
+# 🌊 watahub
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?logo=typescript)](https://www.typescriptlang.org/)
+[![Runtime: Hono](https://img.shields.io/badge/Runtime-Hono%20%2F%20Cloudflare-orange?logo=cloudflare)](https://hono.dev/)
+[![Tests: Vitest](https://img.shields.io/badge/Tests-Vitest-yellow?logo=vitest)](https://vitest.dev/)
+
+> **What a hub for WhatsApp!**  
+> An open-source, high-performance WhatsApp Cloud API Gateway and Bridge built with [Hono](https://hono.dev). Connect your applications directly to Meta's Cloud API with **zero middleman markups**, normalized webhook events, cryptographic HMAC verification, streaming media uploads, and an importable library architecture.
+
+Built with ❤️ by [Hub Ventures](https://github.com/Hub-Ventures).
+
+---
+
+## 🎯 What is Watahub and Who is it For?
+
+**Watahub** is designed for engineering teams and developers who already use or plan to use the official Meta WhatsApp Cloud API and want:
+1. **Total Infrastructure Control:** Self-host your own gateway on Cloudflare Workers, Node.js, or Bun.
+2. **Zero Markups:** Pay Meta's official conversation rates directly without third-party SaaS surcharges.
+3. **Clean Developer Experience:** Receive normalized, flat JSON events instead of navigating Meta's deeply nested webhook structures.
+4. **Hardened Security by Default:** Cryptographic signature validation, replay protection, and rate limiting out of the box.
+
+---
+
+## 📚 Documentation Suite
+
+- 📖 [**Getting Started Guide**](docs/GETTING_STARTED.md): Step-by-step walkthrough from prerequisites to your first message and webhook.
+- 📡 [**API Reference**](docs/API_REFERENCE.md): Full endpoints specification, schemas, and interactive examples for all routes.
+- 🔔 [**Webhooks & Event Catalog**](docs/WEBHOOKS_AND_EVENTS.md): HMAC verification in TypeScript, Python & Go, deduplication, and normalized event JSONs.
+- 📐 [**Architecture & Design**](docs/ARCHITECTURE.md): Deep dive into ports & adapters, dependency inversion, request lifecycles, and error engine.
+- 🏢 [**Multi-Tenancy & Extensibility**](docs/MULTI_TENANCY_AND_EXTENSIONS.md): Scaling with `PhoneDirectory`, KV adapters, and custom enterprise databases.
+- 🚢 [**Production Deployment**](docs/DEPLOYMENT.md): Production setups for Cloudflare Workers, Node.js (Docker/PM2), and Nginx reverse proxies.
+
+---
+
+## ⚡ Why Watahub?
+
+* 🚀 **Zero Middleman Markup:** Pay only Meta's official conversation fees directly to Meta.
+* ⚡ **Ultra-lightweight & Fast:** Built on Hono with Web Standards (`crypto.subtle`, `fetch`, `ReadableStream`).
+* 🔄 **Event Normalization:** Transforms Meta's deeply nested webhook envelopes into clean, standardized event payloads (text, media, interactive buttons/lists, reactions, delivery status receipts).
+* 🔐 **Cryptographic Verification:** Automatic HMAC-SHA256 verification of incoming Meta webhooks (`X-Hub-Signature-256`) and outgoing subscriber payload signing (`X-Watahub-Signature`).
+* 📤 **Streaming Media Support:** Native `/v1/media` endpoints and streaming proxy passthrough that handle uploads up to 100 MB without isolate memory buffering.
+* 🏢 **Pluggable Multi-Tenant Routing:** Modular `PhoneDirectory` port to dynamically resolve Meta access tokens and subscriber webhook targets per phone number.
+* 🛡️ **Production-Hardened Error Engine:** Automated classification of Meta Graph API errors (Rate Limits `130429`, Auth Expiry `190`, Billing/Payment Failures `131042`, Transient Network Failures `131016`).
+
+---
+
+## 📐 Architecture
+
+```mermaid
+flowchart LR
+    User["WhatsApp User"] <--> Meta["Meta Cloud API (v24.0)"]
+    Meta <--> Watahub["🌊 Watahub Gateway (Hono)"]
+    Watahub <--> Backend["Your Backend / Webhook Subscriber"]
+```
+
+---
+
+## 📋 Prerequisites
+
+Before setting up Watahub, ensure you have:
+
+1. **Meta for Developers Account:** An App with the **WhatsApp** product configured ([Meta Developer Portal](https://developers.facebook.com/)).
+2. **WhatsApp Business Account (WABA):** A configured WABA with at least one verified phone number ID.
+3. **Node.js Environment:** Node.js 20 or higher and `pnpm` (required for local development and build steps).
+4. *(Optional for Cloudflare Workers)*: A Cloudflare account and Wrangler CLI installed (`pnpm dlx wrangler`).
+
+---
+
+## 📦 Quick Start: From Zero to First Message
+
+### 1. Clone & Install
+
+```bash
+git clone https://github.com/Hub-Ventures/watahub.git
+cd watahub
+pnpm install
+```
+
+### 2. Environment Configuration
+
+Copy the example environment file:
+
+```bash
+cp .env.example .env
+```
+
+Generate strong keys (min 32 characters) for your gateway and subscriber:
+
+```bash
+# Generate WATAHUB_API_KEY
+openssl rand -hex 32
+
+# Generate SUBSCRIBER_WEBHOOK_SECRET
+openssl rand -hex 32
+```
+
+Configure your `.env`:
+
+| Variable | Description | Default |
+| :--- | :--- | :--- |
+| `PORT` | Local Node.js server port | `3000` |
+| `META_APP_ID` | Meta Developer App ID. Optional at boot; required by connect and launch | - |
+| `META_APP_SECRET` | **Required.** Meta App Secret, used to verify `X-Hub-Signature-256` and to exchange Embedded Signup codes. Without it `POST /webhook` answers 503 | - |
+| `META_CONFIGURATION_ID` | Embedded Signup configuration id (`FB.login` `config_id`). Optional at boot; required by `GET /v1/onboarding/launch` | - |
+| `META_SYSTEM_USER_TOKEN` | Fallback Meta token when the phone has no stored business token and the request has no `X-Meta-Access-Token` | - |
+| `META_WEBHOOK_VERIFY_TOKEN` | **Required.** Token for Meta's webhook handshake (min 16 characters) | - |
+| `META_DEFAULT_PHONE_NUMBER_ID` | Default WhatsApp Business Phone Number ID | - |
+| `META_DEFAULT_WABA_ID` | Default WhatsApp Business Account ID | - |
+| `META_API_VERSION` | Graph API Version | `v24.0` |
+| `WATAHUB_API_KEY` | **Required.** Key for every `/v1/*` and `/v24.0/*` call (min 32 characters). Without it those routes answer 503 | - |
+| `SUBSCRIBER_WEBHOOK_URL` | Forwarding destination URL (https; `http://localhost` allowed for development) | - |
+| `SUBSCRIBER_WEBHOOK_SECRET` | Required with `SUBSCRIBER_WEBHOOK_URL`. Signs deliveries (min 32 characters) | - |
+| `META_WEBHOOK_MAX_AGE_SECONDS` | Signed deliveries whose newest event is older than this are acknowledged but not forwarded | `604800` (7 days) |
+| `RATE_LIMIT_PER_MINUTE` | Optional per-client request limit on `/v1/*` and `/v24.0/*` | off |
+| `TRUSTED_CLIENT_IP_HEADER` | Header with the real client IP when Node runs behind a reverse proxy (e.g. `X-Real-IP`) | - |
+| `CORS_ALLOWED_ORIGINS` | Comma-separated exact origins allowed from browsers. No wildcards | off |
+
+> [!NOTE]
+> On Node.js, the gateway validates this configuration at boot and refuses to start if a required value is missing, too short, or retains the `.env.example` placeholder. Cloudflare Workers enforces these same rules per request on protected routes.
+
+### 3. Start the Gateway
+
+```bash
+pnpm run dev:node
+```
+
+### 4. Verify Gateway Health
+
+```bash
+curl http://localhost:3000/health
+```
+
+Expected response:
+```json
+{
+  "status": "ok",
+  "service": "watahub",
+  "version": "0.2.0",
+  "timestamp": 1729620000000
+}
+```
+
+### 5. Configure Meta Webhook Handshake
+
+1. Expose your local port (e.g., via `cloudflared tunnel` or `ngrok http 3000`).
+2. In your Meta Developer App Dashboard, go to **WhatsApp > Configuration > Edit Webhook**.
+3. Set **Callback URL** to `https://<your-public-url>/webhook`.
+4. Set **Verify Token** to the exact value of your `META_WEBHOOK_VERIFY_TOKEN`.
+5. Click **Verify and Save**. Meta will send a `GET /webhook` challenge handshake that Watahub verifies in constant time.
+6. Under **Webhook fields**, subscribe to `messages`.
+
+### 6. Send Your First Message
+
+```bash
+curl -X POST http://localhost:3000/v1/messages \
+  -H "Authorization: Bearer <WATAHUB_API_KEY>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": "+15551234567",
+    "phoneNumberId": "100609346426000",
+    "kind": "text",
+    "text": {
+      "body": "Hello from Watahub!"
+    }
+  }'
+```
+
+Expected response:
+```json
+{
+  "success": true,
+  "messageId": "wamid.HBgLNTczMDAxMjM0NTY3FQIAEhgg...",
+  "recipient": "15551234567",
+  "phoneNumberId": "100609346426000"
+}
+```
+
+### 7. Receive Your First Normalized Webhook Event
+
+When a user replies on WhatsApp, Meta posts to Watahub's `/webhook`. Watahub verifies the HMAC signature, normalizes the payload, returns `200 OK` to Meta immediately, and forwards the signed payload to your `SUBSCRIBER_WEBHOOK_URL`.
+
+---
+
+## 🔄 Normalized Webhook Events
+
+Meta's raw webhook format nests data under `entry[].changes[].value`. Watahub flattens these events into a clean, typed schema.
+
+### Sample Forwarded Payload (`POST $SUBSCRIBER_WEBHOOK_URL`)
+
+```json
+{
+  "timestamp": 1729620000000,
+  "events": [
+    {
+      "id": "wamid.HBgLNTczMDAxMjM0NTY3FQIAEhgg...",
+      "timestamp": 1729620000000,
+      "phoneNumberId": "100609346426000",
+      "displayPhoneNumber": "15550293848",
+      "type": "message",
+      "message": {
+        "from": "573001234567",
+        "senderName": "Jane Doe",
+        "kind": "text",
+        "text": "Hello Watahub!"
+      }
+    }
+  ],
+  "raw": {
+    "object": "whatsapp_business_account",
+    "entry": [ ... ]
+  }
+}
+```
+
+### Supported Event Types
+- **Inbound Messages (`type: "message"`):** `text`, `image`, `audio`, `video`, `document`, `location`, `contacts`, `reaction`, and `interactive` (button replies, list selections).
+- **Echoes (`type: "echo"`):** Outbound messages sent directly from the WhatsApp Business mobile app, normalized with recipient info and `isEcho: true`.
+- **Status Updates (`type: "status"`):** Delivery lifecycle tracking (`sent`, `delivered`, `read`, `failed` with classified error codes).
+
+---
+
+## 🏢 Open Core & Enterprise Edition (/ee)
+
+Watahub is structured as an **open core** project:
+
+### 1. Single-Operator Core (Open Source, MIT)
+One operator: one Meta app, one subscriber webhook, one `WATAHUB_API_KEY`, and N phone lines. The core does not make the developer perform Meta's onboarding by hand.
+- **No tenant model:** No per-tenant API keys, no per-tenant subscriber URL, no phone ownership checks, no `tenantId`.
+- **Static app config:** `META_APP_ID`, `META_APP_SECRET`, `META_CONFIGURATION_ID`, `META_API_VERSION`. The business token is not a pasted secret.
+- **Line connect:** `POST /v1/onboarding/connect` exchanges the Embedded Signup code, stores the business token keyed by phone number id, subscribes that WABA to this gateway's webhook, and registers the phone. The response does not include the token.
+- **Launch config:** `GET /v1/onboarding/launch` returns `{ appId, configurationId, apiVersion }` so a frontend can call `FB.login`. The app secret is never returned.
+- **Token resolution:** `X-Meta-Access-Token`, then the stored token for that phone number id, then `META_SYSTEM_USER_TOKEN`.
+- **One subscriber:** `SUBSCRIBER_WEBHOOK_URL`.
+
+### 2. Enterprise Edition (`/ee`, Private Repository)
+Multi-tenant routing. Not in this repository.
+- **Per-tenant API keys** and phone ownership checks.
+- **Per-tenant subscriber URLs** and signing secrets (`tenantId` stays in `/ee`).
+- **Credential injection:** the wrapper resolves a tenant token and sends `X-Meta-Access-Token`. That header still wins over the MIT line store.
+
+### 3. Embedded Signup
+`POST /v1/onboarding/connect` is the operator path. It does not return the business token.
+`GET /v1/onboarding/launch` is what a frontend needs for `FB.login`. `config_id` is not a parameter of the code exchange.
+These stay for existing callers:
+- `POST /v1/onboarding/exchange`: exchanges the code and **returns** the token. Prefer connect.
+- `POST /v1/onboarding/subscribe`: subscribes a WABA using the header or `META_SYSTEM_USER_TOKEN`. Connect already subscribes with the new business token.
+- `POST /v1/onboarding/override-callback`: explicit phone-level callback override. Connect does not set one; subscribing attaches Meta to the callback already configured on the app.
+
+---
+
+## 🚀 Running & Deploying Watahub
+
+### Development (Node.js)
+```bash
+pnpm run dev:node
+```
+
+### Development (Cloudflare Workers via Wrangler)
+```bash
+pnpm run dev:worker
+```
+
+### Typecheck, Lint & Test Suite
+```bash
+pnpm check   # typecheck + eslint + prettier check + vitest with coverage
+```
+
+### Production Deploy (Cloudflare Workers)
+
+Before deploying to Cloudflare Workers, configure required secrets using the Wrangler CLI:
+
+```bash
+npx wrangler secret put META_APP_SECRET
+npx wrangler secret put META_WEBHOOK_VERIFY_TOKEN
+npx wrangler secret put WATAHUB_API_KEY
+npx wrangler secret put META_SYSTEM_USER_TOKEN
+
+# Optional subscriber credentials
+npx wrangler secret put SUBSCRIBER_WEBHOOK_SECRET
+```
+
+Then deploy the worker:
+```bash
+pnpm run deploy
+```
+
+---
+
+## 📡 API Reference Summary
+
+| Method | Endpoint | Description |
+| :--- | :--- | :--- |
+| `GET` | `/health` | Service status, version, and server timestamp |
+| `GET` | `/webhook` | Meta verification handshake (`hub.challenge`) |
+| `POST` | `/webhook` | Ingests Meta webhooks, verifies HMAC, normalizes & dispatches |
+| `POST` | `/v1/messages` | Unified message dispatch (text, template, media, interactive) |
+| `GET` | `/v1/media/:mediaId` | Resolves media ID to temporary CDN download URL |
+| `POST` | `/v1/media` | Uploads media file (`multipart/form-data`) streaming to Meta |
+| `POST` | `/v1/media/:phoneNumberId` | Uploads media scoped to a specific phone number |
+| `GET` | `/v1/templates/:wabaId` | Lists a WABA's message templates from Meta Graph API, one page per call (`?after=`) |
+| `POST` | `/v1/onboarding/connect` | Connects one phone line (exchange, store, subscribe, register). Does not return the token |
+| `GET` | `/v1/onboarding/launch` | Public Embedded Signup parameters for `FB.login` (`appId`, `configurationId`, `apiVersion`) |
+| `POST` | `/v1/onboarding/exchange` | Low-level code exchange. Returns the token. Prefer connect |
+| `POST` | `/v1/onboarding/subscribe` | Subscribes application to WABA message webhooks |
+| `POST` | `/v1/onboarding/override-callback` | Overrides webhook URL for a specific phone number |
+| `ALL` | `/v24.0/*` | Direct Graph API passthrough proxy for allowlisted routes |
+
+---
+
+## 🔒 Security Model
+
+* **Authentication:** `/v1/*` and `/v24.0/*` require `WATAHUB_API_KEY` (in `X-API-Key` or `Authorization: Bearer`), compared in constant time. Keys must be at least 32 characters. A client address with more than 10 failed attempts in a minute receives `429 Too Many Requests` with a `Retry-After` header.
+* **Inbound Webhooks:** `POST /webhook` strictly verifies `X-Hub-Signature-256`. Deliveries whose events are older than `META_WEBHOOK_MAX_AGE_SECONDS` are acknowledged with `200 OK` but dropped to protect against replay attacks.
+* **Outbound Deliveries:** If `SUBSCRIBER_WEBHOOK_URL` is set without `SUBSCRIBER_WEBHOOK_SECRET`, `POST /webhook` answers `503` so Meta retries until the signing secret is configured. Forwards include `X-Watahub-Signature: sha256=...` and `X-Watahub-Delivery-Id`.
+* **Streaming & Isolate Memory:** Media uploads stream directly to Meta via chunked Transfer-Encoding, preventing memory spikes and Workers isolate evictions on 100 MB payloads.
+* **Pluggable State Stores:** Replay cache and rate limiting use pluggable ports (`ReplayStore`, `RateLimitStore`), defaulting to in-memory on Node and easily swapped with `DistributedReplayStore` and `DistributedRateLimitStore` on Workers.
+* **Callback Overrides:** Destination URLs must be `https://` on a public host; loopback, private, link-local, and internal addresses are rejected.
+* **HTTP Hardening:** Security headers (`Content-Security-Policy: default-src 'none'`, `X-Frame-Options: DENY`, HSTS, `X-Content-Type-Options: nosniff`) are set on every response. Responses on authenticated surfaces carry `Cache-Control: no-store`.
+
+---
+
+## 🚦 Project Status
+
+Watahub is currently in active development (**v0.2.0**).
+
+The core WhatsApp bridge functionality (message dispatch, streaming media uploads, HMAC verification, replay protection, rate limiting, and library exports) is production-ready and fully tested with 100% passing automated tests across Node.js and Cloudflare Workers.
+
+---
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).

package/dist/clock.d.ts

@@ -0,0 +1,3 @@
+/** Current time in epoch milliseconds. Injected so tests and replays are deterministic. */
+export type Clock = () => number;
+export declare const systemClock: Clock;

package/dist/clock.js

@@ -0,0 +1 @@
+export const systemClock = () => Date.now();

package/dist/config.d.ts

@@ -0,0 +1,31 @@
+import type { Context } from 'hono';
+export declare const GATEWAY_NAME = "watahub";
+export declare const GATEWAY_VERSION = "0.2.0";
+export declare const GATEWAY_USER_AGENT = "Watahub-Gateway/0.2.0";
+export declare const META_GRAPH_BASE_URL = "https://graph.facebook.com";
+export declare const DEFAULT_META_API_VERSION = "v24.0";
+/**
+ * Typed view of the gateway configuration for the current request.
+ * Values come from Worker bindings first, then process.env (see getEnvVar).
+ * Boot-time rules live in utils/env.ts (validateEnv).
+ */
+export interface GatewayConfig {
+    apiKey?: string;
+    metaAppId?: string;
+    /** Embedded Signup configuration id. Public; never the app secret. */
+    metaConfigurationId?: string;
+    metaAppSecret?: string;
+    metaSystemUserToken?: string;
+    metaWebhookVerifyToken?: string;
+    metaDefaultPhoneNumberId?: string;
+    metaDefaultWabaId?: string;
+    metaApiVersion: string;
+    subscriberWebhookUrl?: string;
+    subscriberWebhookSecret?: string;
+    webhookDeliveryMode?: 'sync' | 'async';
+    metaWebhookMaxAgeSeconds?: string;
+    corsAllowedOrigins?: string;
+    rateLimitPerMinute?: string;
+    trustedClientIpHeader?: string;
+}
+export declare function getConfig(c: Context): GatewayConfig;

package/dist/config.js

@@ -0,0 +1,26 @@
+import { getEnvVar } from './utils/env.js';
+export const GATEWAY_NAME = 'watahub';
+export const GATEWAY_VERSION = '0.2.0';
+export const GATEWAY_USER_AGENT = `Watahub-Gateway/${GATEWAY_VERSION}`;
+export const META_GRAPH_BASE_URL = 'https://graph.facebook.com';
+export const DEFAULT_META_API_VERSION = 'v24.0';
+export function getConfig(c) {
+    return {
+        apiKey: getEnvVar(c, 'WATAHUB_API_KEY'),
+        metaAppId: getEnvVar(c, 'META_APP_ID'),
+        metaConfigurationId: getEnvVar(c, 'META_CONFIGURATION_ID'),
+        metaAppSecret: getEnvVar(c, 'META_APP_SECRET'),
+        metaSystemUserToken: getEnvVar(c, 'META_SYSTEM_USER_TOKEN'),
+        metaWebhookVerifyToken: getEnvVar(c, 'META_WEBHOOK_VERIFY_TOKEN'),
+        metaDefaultPhoneNumberId: getEnvVar(c, 'META_DEFAULT_PHONE_NUMBER_ID'),
+        metaDefaultWabaId: getEnvVar(c, 'META_DEFAULT_WABA_ID'),
+        metaApiVersion: getEnvVar(c, 'META_API_VERSION') || DEFAULT_META_API_VERSION,
+        subscriberWebhookUrl: getEnvVar(c, 'SUBSCRIBER_WEBHOOK_URL'),
+        subscriberWebhookSecret: getEnvVar(c, 'SUBSCRIBER_WEBHOOK_SECRET'),
+        webhookDeliveryMode: getEnvVar(c, 'WEBHOOK_DELIVERY_MODE') || 'sync',
+        metaWebhookMaxAgeSeconds: getEnvVar(c, 'META_WEBHOOK_MAX_AGE_SECONDS'),
+        corsAllowedOrigins: getEnvVar(c, 'CORS_ALLOWED_ORIGINS'),
+        rateLimitPerMinute: getEnvVar(c, 'RATE_LIMIT_PER_MINUTE'),
+        trustedClientIpHeader: getEnvVar(c, 'TRUSTED_CLIENT_IP_HEADER'),
+    };
+}

package/dist/deps.d.ts

@@ -0,0 +1,67 @@
+import { type Clock } from './clock.js';
+import { type Logger } from './logger.js';
+import { type MetaClientConfig, type MetaGraphClient } from './services/meta-client.js';
+/**
+ * Business token for one phone line of this operator.
+ * Stored server-side. Never copied into an API response or a log line.
+ */
+export interface StoredLine {
+    phoneNumberId: string;
+    wabaId: string;
+    accessToken: string;
+}
+/**
+ * Phone-line credentials for one operator (one Meta app, N numbers).
+ * Sync for one process, async for KV. Not a tenant directory.
+ */
+export interface LineStore {
+    get(phoneNumberId: string): Promise<StoredLine | undefined> | StoredLine | undefined;
+    put(line: StoredLine): Promise<void> | void;
+}
+/**
+ * In-process line store owned by `createApp`. Isolates do not share it;
+ * `DistributedLineStore` is the KV adapter when tokens must outlive the process.
+ */
+export declare class MemoryLineStore implements LineStore {
+    private readonly lines;
+    get(phoneNumberId: string): StoredLine | undefined;
+    put(line: StoredLine): void;
+}
+export interface ReplayStore {
+    has(id: string, nowMs?: number): boolean | Promise<boolean>;
+    /**
+     * Records a delivered ID. `ttlSeconds` is how long it must be kept so a replay
+     * inside the webhook age window is still caught; keep it at least that long.
+     */
+    remember(id: string, nowMs?: number, ttlSeconds?: number): boolean | Promise<boolean>;
+    clear(): void | Promise<void>;
+}
+export interface RateLimitStore {
+    blockedFor(key: string, nowMs?: number): number | Promise<number>;
+    hit(key: string, nowMs?: number): void | Promise<void>;
+    clear(): void | Promise<void>;
+}
+/**
+ * Collaborators the HTTP layer depends on. Pass overrides to `createApp` to
+ * swap implementations (tests, custom transports, structured logging) without
+ * touching routes.
+ */
+export interface GatewayDeps {
+    /** Builds the Meta Graph client for one request */
+    createMetaClient: (config: MetaClientConfig) => MetaGraphClient;
+    /** Outbound HTTP for the Graph proxy and subscriber delivery */
+    fetch: typeof fetch;
+    now: Clock;
+    logger: Logger;
+    /** Webhook replay protection store */
+    replayStore: ReplayStore;
+    /** Rate limiter for failed API keys */
+    apiKeyLimiter: RateLimitStore;
+    /** Rate limiter for failed webhook verify tokens */
+    verifyTokenLimiter: RateLimitStore;
+    /** Optional factory for per-client request rate limiters */
+    createRequestLimiter?: (limit: number) => RateLimitStore;
+    /** Business tokens produced when a phone line connects */
+    lineStore: LineStore;
+}
+export declare function createDefaultDeps(overrides?: Partial<GatewayDeps>): GatewayDeps;

package/dist/deps.js

@@ -0,0 +1,38 @@
+import { systemClock } from './clock.js';
+import { apiKeyFailures, verifyTokenFailures } from './http/rate-limit.js';
+import { consoleLogger } from './logger.js';
+import { MetaClient } from './services/meta-client.js';
+import { webhookDeliveryIds } from './services/replay.js';
+/**
+ * In-process line store owned by `createApp`. Isolates do not share it;
+ * `DistributedLineStore` is the KV adapter when tokens must outlive the process.
+ */
+export class MemoryLineStore {
+    lines = new Map();
+    get(phoneNumberId) {
+        return this.lines.get(phoneNumberId);
+    }
+    put(line) {
+        this.lines.set(line.phoneNumberId, {
+            phoneNumberId: line.phoneNumberId,
+            wabaId: line.wabaId,
+            accessToken: line.accessToken,
+        });
+    }
+}
+export function createDefaultDeps(overrides = {}) {
+    // The global fetch is resolved on every call so runtime polyfills and test spies apply
+    const fetchFn = overrides.fetch ?? ((input, init) => fetch(input, init));
+    return {
+        createMetaClient: (config) => new MetaClient({ fetch: fetchFn, ...config }),
+        fetch: fetchFn,
+        now: systemClock,
+        logger: consoleLogger,
+        replayStore: overrides.replayStore ?? webhookDeliveryIds,
+        apiKeyLimiter: overrides.apiKeyLimiter ?? apiKeyFailures,
+        verifyTokenLimiter: overrides.verifyTokenLimiter ?? verifyTokenFailures,
+        ...overrides,
+        // After the spread so a partial override cannot leave the port unset
+        lineStore: overrides.lineStore ?? new MemoryLineStore(),
+    };
+}

package/dist/http/auth.d.ts

@@ -0,0 +1,23 @@
+import type { Context, MiddlewareHandler } from 'hono';
+import type { LineStore, RateLimitStore } from '../deps.js';
+import type { Logger } from '../logger.js';
+/**
+ * Gateway API key guard for every authenticated surface (/v1/*, /v24.0/*).
+ *
+ * Fails closed: if WATAHUB_API_KEY is not configured (or too weak) the gateway
+ * refuses to serve these routes instead of exposing the Meta system user token
+ * to anyone. Accepts either `Authorization: Bearer <key>` or `X-API-Key: <key>`.
+ */
+export declare function requireApiKey(logger: Logger, limiter?: RateLimitStore): MiddlewareHandler;
+export interface MetaTokenSource {
+    /** When set, the line store is consulted after the header and before the env token. */
+    phoneNumberId?: string;
+    lineStore?: LineStore;
+}
+/**
+ * Resolves the Meta access token for the request:
+ * 1. `X-Meta-Access-Token` (operators and enterprise wrappers inject this).
+ * 2. The business token stored for `phoneNumberId`, when that line was connected.
+ * 3. `META_SYSTEM_USER_TOKEN`, the old single-token path.
+ */
+export declare function resolveMetaAccessToken(c: Context, source?: MetaTokenSource): Promise<string | undefined>;

package/dist/http/auth.js

@@ -0,0 +1,61 @@
+import { getConfig } from '../config.js';
+import { timingSafeEqual } from '../services/crypto.js';
+import { isStrongApiKey } from '../utils/env.js';
+import { apiKeyFailures, clientAddress, tooManyRequests } from './rate-limit.js';
+/**
+ * Gateway API key guard for every authenticated surface (/v1/*, /v24.0/*).
+ *
+ * Fails closed: if WATAHUB_API_KEY is not configured (or too weak) the gateway
+ * refuses to serve these routes instead of exposing the Meta system user token
+ * to anyone. Accepts either `Authorization: Bearer <key>` or `X-API-Key: <key>`.
+ */
+export function requireApiKey(logger, limiter = apiKeyFailures) {
+    return async (c, next) => {
+        const { apiKey } = getConfig(c);
+        // Workers has no boot step, so the strength rules from validateEnv are enforced here too
+        if (!apiKey || !isStrongApiKey(apiKey)) {
+            logger.error('[watahub] WATAHUB_API_KEY is missing, too short or a placeholder; refusing authenticated route');
+            return c.json({ error: 'Gateway misconfigured: WATAHUB_API_KEY is missing or too weak' }, 503);
+        }
+        if (!(await hasValidApiKey(c, apiKey))) {
+            // Only failing callers are throttled, after the comparison: clients behind one
+            // proxy or NAT share an address, and a correct key must never be locked out by
+            // someone else's guesses. Guessing resistance comes from the 32+ character key.
+            const client = clientAddress(c);
+            const retryAfter = await limiter.blockedFor(client);
+            if (retryAfter > 0)
+                return tooManyRequests(c, retryAfter);
+            await limiter.hit(client);
+            return c.json({ error: 'Unauthorized: Invalid Watahub API key' }, 401);
+        }
+        await next();
+    };
+}
+/**
+ * Drop-in Meta clients send `Authorization: Bearer <meta token>` next to X-API-Key,
+ * so either header may carry the gateway key. Every candidate is compared in constant time.
+ */
+async function hasValidApiKey(c, apiKey) {
+    const authHeader = c.req.header('authorization');
+    const bearer = authHeader?.startsWith('Bearer ') ? authHeader.slice('Bearer '.length) : undefined;
+    const candidates = [bearer, c.req.header('x-api-key')].filter((value) => !!value);
+    const matches = await Promise.all(candidates.map((candidate) => timingSafeEqual(candidate, apiKey)));
+    return matches.includes(true);
+}
+/**
+ * Resolves the Meta access token for the request:
+ * 1. `X-Meta-Access-Token` (operators and enterprise wrappers inject this).
+ * 2. The business token stored for `phoneNumberId`, when that line was connected.
+ * 3. `META_SYSTEM_USER_TOKEN`, the old single-token path.
+ */
+export async function resolveMetaAccessToken(c, source = {}) {
+    const headerToken = c.req.header('x-meta-access-token');
+    if (headerToken)
+        return headerToken;
+    if (source.phoneNumberId && source.lineStore) {
+        const line = await source.lineStore.get(source.phoneNumberId);
+        if (line?.accessToken)
+            return line.accessToken;
+    }
+    return getConfig(c).metaSystemUserToken;
+}

package/dist/http/background.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from 'hono';
+/**
+ * Keeps `task` alive after the response is sent. On Workers it is handed to
+ * waitUntil; on Node there is no ExecutionContext (Hono's getter throws) and
+ * the already-running promise completes on its own while being tracked in-flight
+ * for graceful shutdown.
+ */
+export declare function runInBackground(c: Context, task: Promise<unknown>): void;
+/**
+ * Awaits all pending background tasks up to `timeoutMs` during graceful shutdown.
+ */
+export declare function drainBackgroundTasks(timeoutMs?: number): Promise<void>;
+export declare function getInFlightTaskCount(): number;
+export declare function clearInFlightTasksForTests(): void;