golem15/summercms
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ef0301631448e7e287c4f68ea3f16eb7ae2004c1
summercms/.planning/phases/11-jobs-realtime-and-search-infrastructure/11-04-SUMMARY.md

20 KiB
Raw Blame History

phase, plan, subsystem, tags, requires, provides, affects, actuals, plan_head_before, plan_head_after, tech-stack, key-files, key-decisions, patterns-established, requirements-completed, coverage, duration, completed, status
phase plan subsystem tags requires provides affects actuals plan_head_before plan_head_after tech-stack key-files key-decisions patterns-established requirements-completed coverage duration completed status
11-jobs-realtime-and-search-infrastructure 04 realtime
web-push
vapid
rfc8291
rfc8292
aes128gcm
centrifugo
cli
bonfire
phase provides
11-jobs-realtime-and-search-infrastructure 11-03 centrifugo.Config/LoadConfig, Client (Enabled, DebugInfo, post with apikey header), ErrNotConfigured
phase provides
11-jobs-realtime-and-search-infrastructure 11-05 fonoteka plugin.go and README layout (edited after it)
modules/flare: Pusher, Subscription, SendOptions, SubscriptionSource, SubscriptionInfo, Service/From, VAPIDPusher, Encrypt (RFC 8291), VAPIDHeader/GenerateVAPIDKeys/ParseVAPIDKeys (RFC 8292), HostAllowed allowlist
websockets:generate-vapid-keys [--update] [--show-current] and websockets:test-push <user_id> [--show-config] (flare.Commands)
centrifugo.Client.Info and websockets:health (centrifugo.Commands)
compass.Config.Persist keeps keys saved earlier in overrides.yaml
fonoteka.go: the three websockets commands in the binary, config/push.yaml with push disabled, PUSH_* env mapping
11-07 unit tests
a future app plugin that stores push subscriptions
15 cutover env mapping
tokens tasks commits
22995 2 3
a8305a015d f55cb444ab
added patterns
Web Push is hand-rolled on stdlib crypto (crypto/ecdh, crypto/hkdf, AES-GCM) plus golang-jwt ES256; no push library
Outbound requests to user-supplied URLs: https only, host allowlist checked before dialing, redirects never followed, errors name the host not the URL
Commands print their PHP-shaped lines through bonfire.Output and return a short '<command>: failed' error so the binary exits 1 without repeating the message
App-provided data seams for operator commands: the app publishes an interface (flare.SubscriptionSource) and the command looks it up
created modified
modules/flare/flare.go
modules/flare/vapid.go
modules/flare/encrypt.go
modules/flare/commands.go
modules/flare/encrypt_test.go
modules/flare/send_test.go
modules/flare/commands_test.go
modules/flare/README.md
modules/lighthouse/centrifugo/commands.go
modules/lighthouse/centrifugo/commands_test.go
../fonoteka.go/config/push.yaml
README.md
modules/lighthouse/centrifugo/client.go
modules/lighthouse/README.md
modules/compass/persist.go
modules/compass/persist_test.go
modules/compass/README.md
../fonoteka.go/plugins/golem15/fonoteka/plugin.go
../fonoteka.go/README.md
flare's VAPID driver never follows redirects (CheckRedirect returns ErrUseLastResponse on a copy of any injected client), so a push service cannot bounce a request to a host outside push.allowed_hosts
compass.Config.Persist now merges runtime values over the existing overrides.yaml instead of replacing it; otherwise websockets:generate-vapid-keys --update would silently wipe every other persisted override
websockets:health calls Centrifugo's info API method as the connectivity probe; unlike publishing, a 200 answer with an error body fails the check
Configured keys shorter than 20 characters are shown as '...' only, because first 8 + last 4 would reveal most of the value
websockets:test-push takes no user name from the source (SubscriptionSource returns subscriptions only), so it prints 'Testing push for user ID <n>'; the PHP notification-icon block is not ported because it reads another plugin's config
Command failures print their lines through Output and return '<command>: failed' (or ': check failed'); main prints that one line and exits 1
push.subject defaults to empty, not the PHP app's mailto address, as the plan specifies; VAPIDHeader refuses a subject that is not mailto: or https:
HostAllowed: exact host or '*.suffix' for any subdomain (never the apex), case-insensitive, trailing dot ignored
Secrets in config structs: String, GoString and LogValue redact the private key
RT-01
id description requirement verification human_judgment
D1 RFC 8291 aes128gcm encryption reproduces the Appendix A body, header, ciphertext, CEK and nonce byte for byte (values copied from the RFC text); Encrypt round-trips and refuses payloads above 3993 bytes RT-01
kind ref status
unit modules/flare/encrypt_test.go#TestRFC8291AppendixA pass
false
id description requirement verification human_judgment
D2 VAPID send: an httptest TLS push service verifies the ES256 JWT with the key from k=, checks aud (origin), exp within 24h, sub, typ/alg, TTL, Content-Encoding, Content-Type, Urgency and Topic, and decrypts the body to the payload; 404/410 map to ErrSubscriptionGone and 500 to StatusError without the body RT-01
kind ref status
integration modules/flare/send_test.go#TestVAPIDSendRoundTrip pass
false
id description requirement verification human_judgment
D3 Endpoint allowlist: http, unlisted host, foreign host, user info, relative, other scheme, empty host and host-suffix tricks are refused with ErrEndpointNotAllowed before any request; redirects are not followed; a disabled pusher sends nothing; errors never expose the endpoint path; default allowlist table RT-01
kind ref status
integration modules/flare/send_test.go#TestSendRefusesDisallowedEndpoint pass
false
id description requirement verification human_judgment
D4 websockets:generate-vapid-keys prints an 87/43-char pair that ParseVAPIDKeys accepts with SUMMER_PUSH__* lines; --show-current prints only first8...last4 with lengths and check marks; --update persists both keys (reloaded config returns them, earlier override kept, file mode 0600) RT-01
kind ref status
integration modules/flare/commands_test.go#TestGenerateVAPIDKeysCommand pass
kind ref status
unit modules/compass/persist_test.go#TestPersistKeepsEarlierOverrides pass
false
id description requirement verification human_judgment
D5 websockets:test-push: no source prints 'no subscription source registered' and exits 1; unknown user 'User 5 not found'; no subscriptions; push disabled lists subscriptions but sends nothing; a working source sends one encrypted push per subscription with the PHP-shaped payload; a failed send exits 1 after attempting all; the private key never appears RT-01
kind ref status
integration modules/flare/commands_test.go#TestTestPushCommand pass
false
id description requirement verification human_judgment
D6 websockets:health: empty api_key prints 'Centrifugo not configured (API key missing)' and exits 1 with no request; /info 200 prints Configuration OK and the API URL/Enabled/API Key Set table; 500, an error body and an unreachable server print 'Connection check failed:' and exit 1; the API key is never printed RT-01
kind ref status
integration modules/lighthouse/centrifugo/commands_test.go#TestHealthCommand pass
false
id description requirement verification human_judgment
D7 fonoteka binary registers the three commands and, with the committed empty api_key, websockets:health prints the not-configured line and exits 1 RT-01
kind ref status
e2e cd ../fonoteka.go && SUMMER_GOLEM15__USER__JWT__SECRET=test-only-cli-secret go run . websockets:health 2>&1 | grep -q 'Centrifugo not configured (API key missing)' pass
false
id description verification human_judgment rationale
D8 A real browser subscription receives a push from the VAPID driver (FCM or Mozilla autopush)
true Needs a live push service and a browser; Płytarium has no subscription store, so this can only be exercised by an app that publishes a SubscriptionSource
17min 2026-09-30 complete

Phase 11 Plan 04: flare Web Push and the websockets console commands Summary

A new framework package, flare, sends Web Push with a standard-library VAPID driver: RFC 8291 aes128gcm encryption that matches the RFC's Appendix A vector byte for byte, and an RFC 8292 ES256 vapid t=…, k=… header. It sends only to https endpoints on a push-service allowlist and never follows redirects. The three WinterCMS websockets commands (websockets:health, websockets:generate-vapid-keys, websockets:test-push) now run from the fonoteka binary, and none of them prints a configured secret.

Performance

  • Duration: 17 min
  • Started: 2026-09-30T11:35:45Z
  • Completed: 2026-09-30T11:53:01Z
  • Tasks: 2
  • Files modified: 19 (16 in summercms.go, 3 in fonoteka.go)

Accomplishments

  • flare core (D-15, user decision 3).
    • Types: Pusher, Subscription, SendOptions, SubscriptionSource and SubscriptionInfo.
    • Errors: ErrPushDisabled, ErrEndpointNotAllowed, ErrSubscriptionGone, ErrUserNotFound and StatusError.
    • From(app) builds the service from push.* and publishes it. It reads enabled, public_key, private_key and subject, plus ttl (default 2419200 s) and allowed_hosts (default FCM, Mozilla autopush, *.push.apple.com and *.notify.windows.com).
  • RFC 8291. Encrypt uses an ephemeral P-256 key through crypto/ecdh and the HKDF-SHA-256 key schedule through crypto/hkdf. It writes one AES-128-GCM record with the 0x02 delimiter, and the header is salt, rs 4096, idlen 65 and the key id. Payloads over 3993 bytes are refused. TestRFC8291AppendixA compares the output against the published body, header, ciphertext, CEK and nonce, with values copied verbatim from the RFC text. Changing the nonce label makes the test fail.
  • RFC 8292.
    • GenerateVAPIDKeys returns an unpadded base64url pair (87 and 43 characters).
    • ParseVAPIDKeys accepts padded or unpadded input and checks that the public key matches the private key.
    • VAPIDHeader signs an ES256 JWT (golang-jwt/v5) with aud set to the endpoint origin, exp 12 h ahead and a sub that must be mailto: or https:.
  • VAPIDPusher.
    • Refusals come first. It refuses while disabled. Before dialing, it refuses any endpoint that is not https, carries user info, or has a host outside the allowlist.
    • It POSTs TTL, Content-Encoding: aes128gcm and Content-Type: application/octet-stream, the optional Urgency and Topic, and the VAPID Authorization. The request times out after 10 s.
    • 2xx is success. 404 and 410 return ErrSubscriptionGone, and any other status returns StatusError without the body.
    • It never follows redirects, and its errors name the host, never the endpoint path.
  • Commands.
    • websockets:health ports CentrifugoHealthCheck. It now calls the real info API through the new Client.Info, because PHP's getDebugInfo never contacted the server.
    • websockets:generate-vapid-keys ports GenerateVapidKeys. Configured keys are truncated. --show-current stops after showing them. --update saves through compass Set/Persist to a 0600 overrides file. Without it, the command prints manual SUMMER_PUSH__* lines.
    • websockets:test-push ports TestPushNotifications. It reads subscriptions through the app-published SubscriptionSource and asks a confirm prompt whose default is yes. It refuses to send while push is disabled and reports a result for each subscription.
  • fonoteka.go.
    • Commands() appends centrifugo.Commands(p.app) and flare.Commands(p.app).
    • config/push.yaml ships with push disabled.
    • The README maps PUSH_* to SUMMER_PUSH__* and notes that Płytarium registers no SubscriptionSource.
  • Docs.
    • A new modules/flare/README.md follows the standard structure and gets a root modules row with the same summary sentence.
    • The lighthouse README gains Client.Info, Commands and a CLI commands section.
    • The compass README describes the new Persist merge.

Task Commits

summercms.go:

  1. Task 1: VAPID driver, RFC 8291/8292, flare README and root row (tracer): a9af0d7 (feat)
  2. Task 2 (prerequisite fix): compass Persist keeps earlier overrides: 5fb22c2 (fix)
  3. Task 2: websockets:health, generate-vapid-keys and test-push: f55cb44 (feat)

fonoteka.go:

  1. Task 2: command registration, config/push.yaml, README: cdb87d9 (feat)

Files Created/Modified

  • modules/flare/flare.go: types, errors, Config/LoadConfig (with redaction), Service/From, VAPIDPusher, HostAllowed
  • modules/flare/encrypt.go: Encrypt, the RFC 8291 key schedule, base64url decoding
  • modules/flare/vapid.go: VAPIDKeys, GenerateVAPIDKeys, ParseVAPIDKeys, VAPIDHeader, origin serialization
  • modules/flare/commands.go: Commands, the two push commands and their name constants
  • modules/flare/*_test.go: the RFC vector, the TLS push-service round trip with a test-side RFC 8291 decrypt, the allowlist refusals, and the command behaviour list
  • modules/lighthouse/centrifugo/client.go: Client.Info
  • modules/lighthouse/centrifugo/commands.go, commands_test.go: Commands, HealthCommandName, websockets:health and its tests
  • modules/compass/persist.go, persist_test.go, README.md: Persist merges over the saved file
  • README.md, modules/flare/README.md, modules/lighthouse/README.md: docs
  • fonoteka.go: plugins/golem15/fonoteka/plugin.go, config/push.yaml, README.md

Decisions Made

See key-decisions in the frontmatter.

TDD Gate Compliance (Task 2)

  • RED: The tests were written against stubs with the final signatures, where each command's Run returned nil and Client.Info returned an empty map. Every subtest of TestGenerateVAPIDKeysCommand, TestTestPushCommand and TestHealthCommand failed on its assertions, with no build or load errors. The compass test TestPersistKeepsEarlierOverrides failed with app.name = "base", want the earlier persisted value. gsd-tools check tdd-red-evidence returned RED_EVIDENCE_OK (target_test_failed) for all three records (TestTestPushCommand, TestHealthCommand, TestPersistKeepsEarlierOverrides).
  • GREEN: 5fb22c2 and f55cb44. All subtests pass, including under -race.
  • Gate note: there are no separate test(11-04) commits. The project requires go vet and go test ./... to be green at every commit, so tests and code landed together, as in plans 11-01 to 11-06.

Deviations from Plan

Auto-fixed Issues

1. [Rule 2 - Missing critical] compass Persist dropped earlier overrides

  • Found during: Task 2, while reading compass/persist.go before wiring --update
  • Issue: Persist wrote only this process's runtime values. websockets:generate-vapid-keys --update would therefore replace overrides.yaml with the two push keys and silently delete every other persisted override.
  • Fix: Persist loads the existing file, merges the runtime values over it and writes the result atomically with mode 0600, as before. The README and doc comment describe the merge.
  • Files modified: modules/compass/persist.go, persist_test.go, README.md
  • Verification: TestPersistKeepsEarlierOverrides (RED, then GREEN). The existing compass tests pass. The flare --update subtest asserts that an earlier app.name override survives.
  • Committed in: 5fb22c2

2. [Rule 2 - Security] The VAPID driver refuses redirects

  • Found during: Task 1
  • Issue: The allowlist is checked before dialing, but Go's default client follows redirects. A push service, or anything that answers on an allowed host, could bounce the request to an arbitrary host (T-11-22).
  • Fix: NewVAPIDPusher copies any given client and sets CheckRedirect to http.ErrUseLastResponse. A 3xx answer is returned as a StatusError.
  • Verification: The redirect case in TestSendRefusesDisallowedEndpoint. The redirect target gets zero requests.
  • Committed in: a9af0d7

3. [Rule 2 - Security] Secret-safe formatting and errors

  • flare.Config and flare.VAPIDKeys redact the private key in String, GoString and LogValue.
  • Transport errors drop *url.Error's repeated endpoint URL and name only the host, because an endpoint path is a capability.
  • The test asserts that %v/%#v never print the private key.
  • Committed in: a9af0d7

4. [Additions] Extra exported surface, all in the READMEs and checked with go doc

  • flare:
    • Config (Keys, String, GoString, LogValue) and LoadConfig
    • Service.Config, Service.Enabled, Service.SetHTTPClient (test injection) and Service.Logger
    • VAPIDPusher and NewVAPIDPusher
    • HostAllowed and DefaultAllowedHosts
    • StatusError, ErrPayloadTooLarge, ErrInvalidVAPIDKeys and ErrInvalidSubject
    • the constants ContentEncoding, MaxPayloadSize, DefaultTTL, DefaultTimeout, VAPIDTokenLifetime, PublicKeyLength and PrivateKeyLength
    • GenerateVAPIDKeysCommandName and TestPushCommandName
  • centrifugo: HealthCommandName.
  • The name constants keep each command name literal to one occurrence per file, as the acceptance greps require.

5. [Output shape] Documented differences from PHP

  • Titles are framework-neutral. For example, "Push Notification Tester" replaces "QuestStream Push Notification Tester".
  • "Testing push for user ID " replaces PHP's name line, because a SubscriptionSource returns no user name.
  • The notification icon/badge block is not ported. It reads the absent notifications plugin's config.
  • A failing command ends with one <command>: failed line, which the binary prints before it exits 1.
  • websockets:health hints at SUMMER_REALTIME__CENTRIFUGO__API_KEY instead of .env.

Total deviations: 3 auto-fixed (all Rule 2), plus 2 documented notes. Impact on plan: Fix 1 prevents config data loss from the new --update flag. Fixes 2 and 3 harden the T-11-22 and T-11-11 mitigations. No scope creep.

Issues Encountered

None. TestRFC8291AppendixA passed on the first run. A mutation of the nonce label confirmed that the test is sensitive to it.

Known Stubs

None. Płytarium publishing no SubscriptionSource is intended, per the plan: the PHP app has no subscription store. websockets:test-push reports this and exits 1.

Threat Flags

None beyond the plan's threat model. The only new surface is outbound HTTPS to push services, which T-11-22 covers with the allowlist and, now, the refused redirects. No inbound endpoint was added.

User Setup Required

None. To enable push in a deployment later:

  1. Run fonoteka websockets:generate-vapid-keys.
  2. Set SUMMER_PUSH__PUBLIC_KEY, SUMMER_PUSH__PRIVATE_KEY, SUMMER_PUSH__SUBJECT and SUMMER_PUSH__ENABLED=true.
  3. Have an app plugin publish a flare.SubscriptionSource.

Next Phase Readiness

  • Plan 11-07 (unit tests) can add:
    • HostAllowed edge cases beyond the smoke table
    • LoadConfig parsing (ttl as a duration string, allowed_hosts as a comma string)
    • ParseVAPIDKeys mismatch and padded input
    • VAPIDHeader subject and origin rules (default port stripped, IPv6)
    • the ago formatting
    • Service.SetHTTPClient
  • An application that stores push subscriptions only needs to publish a flare.SubscriptionSource and call flare.From(app).Pusher().Send.

Phase: 11-jobs-realtime-and-search-infrastructure Completed: 2026-09-30

Self-Check: PASSED

  • All 11 key created files exist on disk.
  • summercms.go commits a9af0d7, 5fb22c2 and f55cb44 exist, and so does fonoteka.go commit cdb87d9. The fonoteka.go working tree is clean.
  • Task 1 verify: go vet ./... passes. TestRFC8291AppendixA, TestVAPIDSendRoundTrip and TestSendRefusesDisallowedEndpoint each report --- PASS, with no SKIP.
  • Task 2 verify: go vet ./... && go test ./... passes in summercms.go. The fonoteka.go vet and test commands pass for all three modules. fonoteka websockets:health prints Centrifugo not configured (API key missing) and exits 1.
  • Every acceptance-criteria grep and go doc check passed in both tasks, including the exact counts of 1.
Reference in New Issue View Git Blame Copy Permalink