Repository navigation
chore(0.3-s5a): WhatsApp spike — pinned WAHA, fake WAHA, sending controls - #75
Merged
Merged
Conversation
Checkpoint A: WAHA 2026.10.1 (GOWS build) and PostgreSQL 18 pinned by digest; WAHA on an internal network with no published port, API key, PostgreSQL session storage in its own namespace and role on a database host separate from the spike's state, QR printing, dashboard and Swagger off, JSON logs, per-container HMAC webhook config. The pinned image's OpenAPI document is committed with its source digest for the fake's parity test. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ult injection Checkpoint B: the fake serves only methods and paths of the pinned OpenAPI document (session create/start/stop/status, QR, sendText, sendSeen, typing, LID lookup) behind the API key, keeps WAHA's session state machine and emits HMAC-SHA512-signed webhooks in WAHA's documented shapes. Faults: 463/475 on send and in a later ERROR ack, capping warnings and the reachout timelock from the pinned docs, forced states, timeouts and hung sends, gateway down, held, reordered, duplicated and replayed webhooks, @lid senders, edits, revokes and reactions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e, breaker, health and acks Checkpoints C-E: sendWhatsApp validates the template and refuses before queueing (allowlist with a number-free log line, no opt-in, opted out); the webhook router checks the container's HMAC key and session ownership, drops exact replays and applies opt-in state in message order (@lid senders resolved through the receiving container; groups and broadcasts ignored). A per-session tick on a stately pg-boss queue holds the session's advisory lock, sends FIFO with the pure scheduler's gap, rolling cap and quiet hours, seen and typing first, and commits 'sending' before the WAHA call so a lost or timed-out send becomes a 'maybe sent' manual task. Ban codes and documented warnings pause the session 24 h and then until the admin resumes it; outages fall back without the pause. The health job maps WAHA states and warns on a phone not seen for 10 days; acks only move forward. Manual workflow s5-whatsapp runs every suite. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…id retry; docs Review fixes: the attempt keeps the number it was queued for and is dropped when the number changed or left the allowlist; a new number starts without opt-in. Workers run one tick handler per session at once, so a session waiting for its gap does not hold up others. A failed @lid lookup answers 503 without recording the event, so the retry still applies an opt-out. A failed tick re-kicks itself and the health job kicks sessions with work left; an orphaned send counts for the gap and cap; a handler that lost its lock does not send; short keys are refused. Slice file evidence, roadmap and backlog updated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
HussienALfajer
enabled auto-merge (squash)
November 17, 2026 09:17
HussienALfajer
added a commit
that referenced
this pull request
Nov 17, 2026
Roadmap: 0.3-S4c Done (#74), 0.3-S5a Done (#75), 0.3-S5b in review. Slice file: as built, evidence and both reviews. The owner's manual-day checklist. Backlog: open review findings. verify.test.ts carries the phrase rule. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ay8hovfxFk7etuMM9KQWsE
Merged
4 of 6 tasks
HussienALfajer
added a commit
that referenced
this pull request
Nov 17, 2026
…n, manual-run tooling (#79) ## Summary Slice [0.3-S5b](docs/slices/0.3-s5b-whatsapp-verification-and-tooling.md) (T0) of spike [0.3-S5 WhatsApp](docs/specs/spikes/0.3-s5-whatsapp.md), criteria 9, 10 and 11 (tooling). Throwaway spike code under `spikes/s5-whatsapp/`; no product schema. - **Reverse verification (criterion 9, MSG-12/20/22/24):** `POST /verify/nonce` issues a nonce bound to the device and the claimed number (128-bit id, device secret stored as SHA-256, 10-minute TTL, single use) and a `wa.me` link with the prefilled `رمز التحقق في شفاء: <code>`. The platform webhook matches a code only right after that phrase (case, Arabic-Indic digits and tashkeel folded), compares the sender (an `@lid` is resolved through the receiving container; unresolvable fails closed), and records every outcome without the number. Codes and numbers are stored only as HMAC keys. Limits: 5 nonce requests and 5 failed matches per device and per number per hour. - **The platform never initiates (MSG-22):** its only send, `platformReply({ session, replyTo })`, replies once to an inbound on that session that is less than 10 minutes old, to an allowlisted number (MSG-32), and only after a successful verification. A call without `replyTo` is a type error and a runtime refusal. - **Separation (criterion 10, MSG-09):** (container, session) decides the role. Start-up refuses a platform session that shares a container with clinic sessions, a clinic id on the platform session, two platform sessions, shared keys, and stored session rows that differ from the config. - **Manual-run tooling (criterion 11):** a local admin page on `127.0.0.1` (per-run token, Host check, CSP; QR proxied and never stored; start creates unknown sessions; resume; opt-in and alert counts); `scripts/manual-run.ts` (`serve`, paced `batch`); `scripts/device.ts`; raw capture to git-ignored `.cache/s5/raw/`; an allow-list scrubber and a fixture check; the owner's checklist `docs/spikes/s5-manual-checklist.md`. - **Docs:** roadmap (0.3-S4c Done #74, 0.3-S5a Done #75, 0.3-S5b in review), slice file (as built, evidence, reviews) and backlog. Reviews (`reviewer` and `security-reviewer`): all 4 blocking findings fixed. Two of them required changes to locked tests, which the owner approved: a code now counts only after the fixed phrase, and the scrubber became an allow-list. The open non-blocking items are in `docs/backlog.md`. ## Test plan - [x] `pnpm verify` (fast): all green - [x] Messaging `test:spike` run locally in a Node 24 container against PostgreSQL 18.6 (pinned digest), with a git-ignored shim instead of Testcontainers (the cloud sandbox blocks Docker from Node): 19 files, 101 tests pass. These include the 0.3-S5a suites and the new `verify`, `platform-never-initiates`, `separation`, `scrubber`, `admin-page` and `review-fixes` suites. - [x] Fake WAHA OpenAPI parity: 4 pass - [x] `node scripts/check-fixtures.ts`: pass - [ ] Manual `s5-whatsapp` workflow dispatch (runs the pinned-WAHA half of `no-secrets-in-logs`, which the shim could not run) - [ ] CI `verify (full)` --- _Generated by [Claude Code](https://claude.ai/code/session_01Ay8hovfxFk7etuMM9KQWsE)_ --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Slice 0.3-S5a (T0) of the WhatsApp spike (slice, spec criteria 1–8, OD-45, OD-46). Throwaway spike code; no real-schema migration; CI never touches real WhatsApp.
spikes/s5-whatsapp/stack):devlikeapro/waha:gows-2026.10.1@sha256:…and PostgreSQL 18 pinned by digest. WAHA runs on an internal network with no published port, behind an API key. Its session storage is on its own PostgreSQL, with its own namespace and role. QR printing, dashboard and Swagger are off, logs are JSON, and each container has its own webhook HMAC key. No session is ever started.fake-waha): serves only the methods and paths of the pinned OpenAPI document, which is committed with the digest it came from. It sends signed webhooks in WAHA's shapes and can inject 463/475 (both as an HTTP error and as an ERROR ack), the capping and reachout-timelock warnings documented in the pinned OpenAPI, forced states, timeouts and hung sends, gateway down, held, reordered, duplicated and replayed webhooks,@lidsenders, edits, revokes and reactions.messaging):sendWhatsAppchecks the allowlist (MSG-32) and opt-in/opt-out (MSG-13/14) before queueing, and again at send time.statelyqueue holds an advisory lock. It sends in FIFO order with the pure scheduler (20–60 s gap, rolling 60-minute cap, quiet hours 21:00–08:00 Asia/Damascus with a deferral spread, variants), seen and typing first.s5-whatsapp(workflow_dispatch,permissions: {}, SHA-pinned actions, no secrets).key_strict_fifois not used. A failed or expired job blocks its key, and deferred jobs let later jobs overtake them, so the plan's per-session tick fallback is used (reason inmessaging/src/queue.ts).Test plan
pnpm verify(fast): all greenpnpm run test:spikelocally with Docker: stack 12/12, fake-waha 4/4, messaging 63/63 (200-message simulated day; two worker processes on real pg-boss; a killed worker and a job expiring mid-send; one worker with two sessions)reviewer+security-reviewer: every blocking finding fixed with new tests; non-blocking findings indocs/backlog.mds5-whatsappworkflow dispatch after mergeTier: T0.
🤖 Generated with Claude Code