Skip to content

chore(0.3-s5a): WhatsApp spike — pinned WAHA, fake WAHA, sending controls - #75

Merged
HussienALfajer merged 4 commits into
mainfrom
chore/0.3-s5a-whatsapp-stack-and-sending
Nov 17, 2026
Merged

HussienALfajer merged 4 commits into
mainfrom
chore/0.3-s5a-whatsapp-stack-and-sending

Conversation

@HussienALfajer

Copy link
Copy Markdown
Owner

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.

  • Pinned WAHA stack (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 (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, @lid senders, edits, revokes and reactions.
  • Messaging service (messaging):
    • sendWhatsApp checks the allowlist (MSG-32) and opt-in/opt-out (MSG-13/14) before queueing, and again at send time.
    • Webhooks are routed per container (HMAC, session ownership, dedupe, ordered opt-in).
    • A per-session tick on a pg-boss stately queue 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.
    • Sends are at most once: an unknown outcome becomes a "maybe sent" manual task.
    • The breaker pauses 24 h and then waits for admin resume (OD-46); outages fall back without the pause.
    • A health job and forward-only acks.
  • Manual workflow s5-whatsapp (workflow_dispatch, permissions: {}, SHA-pinned actions, no secrets).
  • Deviation: key_strict_fifo is 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 in messaging/src/queue.ts).
  • Size: about 5,280 hand-written lines, over the ADR-0032 budget of about 4,000. The owner is told in the report.

Test plan

  • pnpm verify (fast): all green
  • pnpm run test:spike locally 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 in docs/backlog.md
  • s5-whatsapp workflow dispatch after merge

Tier: T0.

🤖 Generated with Claude Code

HussienALfajer and others added 4 commits November 17, 2026 11:46
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
HussienALfajer enabled auto-merge (squash) November 17, 2026 09:17
@HussienALfajer
HussienALfajer merged commit 7b6c50a into main Nov 17, 2026
11 checks passed
@HussienALfajer
HussienALfajer deleted the chore/0.3-s5a-whatsapp-stack-and-sending branch November 17, 2026 09:20
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
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant