diff --git a/.planning/STATE.md b/.planning/STATE.md index ec5fb385..c65d8f2a 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -5,10 +5,10 @@ current_phase: 30 current_phase_name: Płytarium cutover status: planning stopped_at: Phase 35 complete, ready to plan Phase 30 -last_updated: "2026-11-18T19:24:37.982Z" -last_activity: 2026-11-18 -last_activity_desc: "Completed quick task 261118-qsd: module README Go examples compiled via src=" -state_head: 8c03cc362190f72d8ba24e8fcc60bc09a5f26cc7 +last_updated: "2026-11-19T14:08:02.608Z" +last_activity: 2026-11-19 +last_activity_desc: "Completed quick task 261119-kj8: sm-user-plugin JWT blacklist sweep as scheduled command" +state_head: 005fb4a2cb09b64dcd83483182e9327d736b6b77 progress: total_phases: 52 completed_phases: 37 @@ -33,7 +33,7 @@ See: .planning/PROJECT.md (updated 2026-10-22) Phase: 30 — Płytarium cutover Plan: Not started Status: Ready to plan -Last activity: 2026-11-18 — Completed quick task 261118-qsd: module README Go examples compiled via src= +Last activity: 2026-11-19 — Completed quick task 261119-kj8: sm-user-plugin JWT blacklist sweep as scheduled command Progress: [████████░░] 77% @@ -1254,6 +1254,7 @@ Recent decisions affecting current work: | 261115-cha | Let a mail template use another plugin's layout by full code (G-35-9) | 2026-11-15 | b8487b02 | [261115-cha-let-a-mail-template-use-another-plugin-s](./quick/261115-cha-let-a-mail-template-use-another-plugin-s/) | | 261118-lbt | Per-app plugin instances, closable limiter store, one router build | 2026-11-18 | 38f7f3a7 | [261118-lbt-per-app-plugin-instances-closable-limite](./quick/261118-lbt-per-app-plugin-instances-closable-limite/) | | 261118-qsd | Compile module README Go examples via src= references | 2026-11-18 | 8c03cc36 | [261118-qsd-compile-module-readme-go-examples-via-sr](./quick/261118-qsd-compile-module-readme-go-examples-via-sr/) | +| 261119-kj8 | sm-user-plugin: JWT blacklist sweep as scheduled user:jwt-blacklist-sweep command (sm-user-plugin bc5f4f7) | 2026-11-19 | bc5f4f7 | [261119-kj8-sm-user-plugin-replace-the-jwt-blacklist](./quick/261119-kj8-sm-user-plugin-replace-the-jwt-blacklist/) | ## Deferred Items diff --git a/.planning/quick/261119-kj8-sm-user-plugin-replace-the-jwt-blacklist/261119-kj8-PLAN.md b/.planning/quick/261119-kj8-sm-user-plugin-replace-the-jwt-blacklist/261119-kj8-PLAN.md new file mode 100644 index 00000000..2706ed1a --- /dev/null +++ b/.planning/quick/261119-kj8-sm-user-plugin-replace-the-jwt-blacklist/261119-kj8-PLAN.md @@ -0,0 +1,220 @@ +--- +phase: quick-261119-kj8 +plan: 01 +type: execute +wave: 1 +depends_on: [] +files_modified: + - ../sm-user-plugin/classes/blacklist_sweep.go + - ../sm-user-plugin/classes/blacklist_sweep_test.go + - ../sm-user-plugin/console/jwt_blacklist_sweep.go + - ../sm-user-plugin/plugin.go + - ../sm-user-plugin/session_test.go + - ../sm-user-plugin/blacklist_sweep_test.go + - ../sm-user-plugin/logger.go + - ../sm-user-plugin/README.md +autonomous: true +requirements: [QUICK-261119-kj8] + +estimate: + tokens: 70000 + raw_tokens: 70000 + tasks: 3 + confidence: low + +must_haves: + truths: + - "Booting golem15.user (serve, any console command, any test boot) starts no background goroutine: the ticker loop, its helper method and the stop-channel field on Plugin are gone" + - "`user:jwt-blacklist-sweep` is registered by Plugin.Commands() and deletes the jwt_blacklist rows whose expires_at is before now, through the published bouncer.BlacklistStore or, with no published database, a store over a database opened from database.dsn; it prints `Deleted the expired JWT blacklist rows.`" + - "Plugin.Schedule() returns exactly one entry {Command: user:jwt-blacklist-sweep, Cadence: pact.Every(interval)}; the interval is golem15.user.jwt.blacklist_sweep_interval, default 10m; 0 (\"0\", \"0s\", YAML int 0) returns no entry" + - "Boot fails with an error naming golem15.user.jwt.blacklist_sweep_interval for a value that does not parse, is negative, is shorter than 1s or does not divide 24h evenly" + - "README documents the command, the config semantics (0 disables, must divide 24h) and that the sweep runs on the job worker's scheduled queue" + - "go vet ./... and go test -short ./... in sm-user-plugin are green; the new Postgres test skips under -short" + artifacts: + - path: ../sm-user-plugin/classes/blacklist_sweep.go + provides: "BlacklistSweepInterval(app), DefaultBlacklistSweepInterval, JWTBlacklistTable" + - path: ../sm-user-plugin/console/jwt_blacklist_sweep.go + provides: "JWTBlacklistSweep(app) bonfire.Command (user:jwt-blacklist-sweep)" + - path: ../sm-user-plugin/plugin.go + provides: "Schedule() []pact.ScheduledCommand, Boot validation, Commands() registration, no goroutine" + - path: ../sm-user-plugin/blacklist_sweep_test.go + provides: "-short schedule/boot/command tests and the Postgres-backed command test" + key_links: + - from: "plugin.go Schedule()" + to: "classes.BlacklistSweepInterval" + via: "same parser Boot validates with" + - from: "plugin.go Commands()" + to: "console.JWTBlacklistSweep(p.app)" + via: "command name matches the schedule entry" + - from: "console.JWTBlacklistSweep Run" + to: "app.Lookup[bouncer.BlacklistStore] / lagoon.OpenFromApp + bouncer.NewPostgresBlacklist(sqlDB, classes.JWTBlacklistTable)" + via: "Sweep(ctx, time.Now())" + - from: "conga scheduleEntries (summercms.go/modules/conga/scheduler.go)" + to: "pact.HasSchedule on *user.Plugin" + via: "var _ pact.HasSchedule = (*Plugin)(nil)" +--- + + +Replace the JWT blacklist sweep goroutine that `golem15.user` starts from Boot (inside `lagoon.OnDatabase`, never stopped, leaking one per booting process) with a console command `user:jwt-blacklist-sweep` that the framework scheduler (conga) runs on the job worker every `golem15.user.jwt.blacklist_sweep_interval`. + +Purpose: no process leaks a ticker goroutine; the sweep runs once per period across instances (conga's leader election and unique-by-period jobs) instead of once per process; operators can run it by hand. +Output: new command, `Schedule()`, boot-time interval validation, tests, README; one commit in the sm-user-plugin repo. + +Non-breaking for consumers (core plugin): config key, default (10m), table and routes unchanged. The only behaviour narrowing: an interval that the scheduler cannot run (does not divide 24h, under 1s, negative, unparsable) now fails boot instead of silently disabling or ticking off-grid. No consumer app overrides the key (checked: sm-*-app, fonoteka.go). Consumer apps keep `queue.work_in_serve: true`, so serve's in-process worker carries the schedule. + + + +@~/.claude/msd-core/workflows/execute-plan.md +@~/.claude/msd-core/templates/summary.md + + + +@/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/CLAUDE.md +@/media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin/plugin.go +@/media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin/console/backfill_handles.go +@/media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin/classes/backend_links.go +@/media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/schedule.go + +Work repo: /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin (its own git repo, branch master, clean at 6ec4c85). The paths in files_modified are relative to summercms.go; all edits and the commit happen in sm-user-plugin. + +Interfaces (already in the codebase, do not re-derive): +- pact (framework): `type ScheduledCommand struct { Command string; Args []string; Cadence Cadence }`, `type HasSchedule interface { Schedule() []ScheduledCommand }`, `func Every(d time.Duration) Cadence` (Cadence is comparable; tests compare with `!=`). conga's scheduleFor rejects d < 1s and 24h % d != 0, and fails the worker start; Boot must catch those first. +- conga calls `Schedule()` on booted plugins (StartWorker, schedule:run, schedule:run --once), and resolves the scheduled command among the plugins' `Commands()`. +- bouncer: `type BlacklistStore interface { Add(...); IsBlacklisted(...); Sweep(ctx context.Context, now time.Time) error }`; `bouncer.NewPostgresBlacklist(sqlDB *sql.DB, table string)`; PostgresBlacklist.Sweep runs `DELETE FROM WHERE expires_at < $1`. +- Plugin publishes the store in Boot: `app.Publish[bouncer.BlacklistStore](store)` inside `lagoon.OnDatabase`. +- `lagoon.OpenFromApp(ctx, app) (*sql.DB, *gorm.DB, error)` opens from database.dsn (needs app.key too). +- Reference pattern: sm-oauthserver-plugin schedule.go + plugin.go Schedule() + commands_test.go TestScheduleConfig (default entry, custom intervals, bad values → boot error naming the key, every scheduled command is registered). +- Test helpers in sm-user-plugin: `bareApp(t)` (admin_users_edge_test.go), `commandNamed(t, cmds, name)` and `emailArg{}` as a bonfire.Input (console_test.go), `sessionApp(t, sweep)`, `newSessionApp`, `bootPlugin`, `sessionConfig`, `sessionDB`, package var `sessionDSN` (session_test.go), `skipShortPostgres(t)` (social_hooks_test.go), TestMailFallbackLocaleBoot (mail_locale_test.go, Boot-error pattern with a jwt secret on bareApp), TestBackfillHandlesOpensFromConfigWhenUnpublished (console_test.go, the database.dsn + app.key CLI-path pattern). + +**Pre-existing go.mod drift (do not commit a fix).** sm-user-plugin's go.mod replaces the framework with ../summercms.go, whose master pulled new indirect deps, so plain `go vet ./...` currently stops with "updates to go.mod needed". Run every go command against a tidied copy of the module file kept outside the repo: `S="$SCRATCH/user-modfile"; mkdir -p "$S" && cp go.mod go.sum "$S"/ && go mod tidy -modfile="$S/go.mod"`, then pass `-modfile="$S/go.mod"` to go vet / go test. `$SCRATCH` is your session scratchpad directory (substitute it inline in each command; shell state does not persist between calls). If `go mod tidy -diff` prints nothing, plain commands work. go.mod and go.sum in the repo must stay byte-identical (`git diff --quiet -- go.mod go.sum`); mention the drift in the SUMMARY. + +Concurrency: other sessions may touch sibling repos; stage files by explicit path only, never `git add -A`. No co-author tags in the commit message. No push, no tag. + + + + + + Task 1: End-to-end "scheduled sweep command" — parser, command, Schedule(), goroutine removed + ../sm-user-plugin/classes/blacklist_sweep.go, ../sm-user-plugin/console/jwt_blacklist_sweep.go, ../sm-user-plugin/plugin.go, ../sm-user-plugin/session_test.go, ../sm-user-plugin/blacklist_sweep_test.go + + - (&Plugin{app: bareApp(t)}).Schedule() with the key unset returns one entry: Command "user:jwt-blacklist-sweep", Cadence pact.Every(10*time.Minute); (&Plugin{}).Schedule() (nil app) returns the same. + - Every scheduled command name is among (&Plugin{app: app}).Commands() names. + - With a fake bouncer.BlacklistStore published on bareApp (app.Publish[bouncer.BlacklistStore](fake)), running the command calls fake.Sweep exactly once with a now between the times taken before and after Run, and the output contains "Deleted the expired JWT blacklist rows." + - A fake whose Sweep returns an error makes Run return an error wrapping it (errors.Is) and print no success line. + - The command built with a nil app returns an error from Run, and building it with nil does not panic (TestCommandsDocumented calls (&Plugin{}).Commands()). + + +Before editing, record a baseline: run the full short suite with the modfile copy (see context) and save the list of failing tests, if any, to your scratchpad, so Task 2 can tell pre-existing failures from new ones. + +1. New file classes/blacklist_sweep.go (package classes), modelled on BackendLinkRequestTTL in classes/backend_links.go: + - exported const JWTBlacklistTable = "jwt_blacklist" (doc: the table of migration 202609220007_create_jwt_blacklist that the plugin's blacklist store uses); + - exported const DefaultBlacklistSweepInterval = 10 * time.Minute; + - unexported const for the key golem15.user.jwt.blacklist_sweep_interval; + - func BlacklistSweepInterval(app *backpack.App) (time.Duration, error): nil app or nil Config → default; read the value with app.Config.String and TrimSpace; empty → default; otherwise time.ParseDuration. Result 0 → (0, nil), meaning no sweep is scheduled. A parse error, a negative value, a value below time.Second, or one where (24*time.Hour) % d != 0 → (0, error) with the message shape "golem15.user: golem15.user.jwt.blacklist_sweep_interval must be 0 (no sweep) or a duration of at least 1s that divides 24h evenly, such as 10m, got %q". Check that an unquoted YAML 0 (app.Config.Set(key, 0)) reads as "0" through Config.String; if String returns "" for a non-string, fall back to app.Config.Lookup and fmt.Sprint so an int 0 means off, not the default. Doc comment states why the 24h rule exists (conga's Every cadence is aligned to local midnight). + +2. New file console/jwt_blacklist_sweep.go (package console), same shape as BackfillHandles: func JWTBlacklistSweep(app *backpack.App) bonfire.Command with Name "user:jwt-blacklist-sweep", Description "Delete the expired JWT blacklist rows", a Long help (what it deletes: jwt_blacklist rows whose expires_at has passed, nothing still valid, safe to run twice; the scheduler runs it every golem15.user.jwt.blacklist_sweep_interval on the job worker's scheduled queue; run it by hand or from cron when no worker runs that queue; ends with "Deleted the expired JWT blacklist rows."), and two Examples (plain, and -q). Run: nil app → error "user:jwt-blacklist-sweep: app is nil"; look up the published bouncer.BlacklistStore via app.Lookup; when none is published, open the database with lagoon.OpenFromApp (defer closing the *sql.DB) and build bouncer.NewPostgresBlacklist(sqlDB, classes.JWTBlacklistTable); call Sweep(ctx, time.Now()); wrap a failure as "user:jwt-blacklist-sweep: %w"; on success out.Success("Deleted the expired JWT blacklist rows."). Sweep returns no count, so print no count. + +3. plugin.go: + - Delete the ticker goroutine method (current lines 224-255), its call inside the lagoon.OnDatabase callback (line 93), and the stop-channel field from the Plugin struct (line 57) so Plugin holds only app. Update the comment above lagoon.OnDatabase (lines 82-84) to say the GORM hooks and the blacklist store are installed there; expired rows are deleted by the scheduled user:jwt-blacklist-sweep command. + - Use classes.JWTBlacklistTable instead of the string literal in bouncer.NewPostgresBlacklist. + - Add `_ pact.HasSchedule = (*Plugin)(nil)` to the interface assertion block. + - In Boot, right after the classes.MailFallbackLocale check, return the error of classes.BlacklistSweepInterval(app) so a bad value fails boot before anything is published. + - Add method Schedule() []pact.ScheduledCommand with a doc comment: reads classes.BlacklistSweepInterval(p.app) (p.app may be nil before Register; that yields the default); on error return nil (Boot reports it, same as oauthserver's config()); on 0 return nil; else return a single entry with Command "user:jwt-blacklist-sweep" and Cadence pact.Every(interval). + - Commands(): add console.JWTBlacklistSweep(p.app) to the returned list (after BackfillHandles). Update the Commands doc if present. + - Keep imports compiling (context and time remain used by other code). + +4. session_test.go: bootPlugin keeps its (t, app, sweep string) parameters (it still sets the config key) but returns only *Plugin; drop the block that closed the plugin's stop channel and the now-unused sync.Once use there (sessionOnce still needs the sync import). Update its callers (sessionApp at ~line 691 ignores the result). Delete TestLoginBlacklistSweep (it relied on a 50ms in-process ticker, which now fails boot by design); Task 2 adds its replacement. The many sessionApp(t, "0s") callers stay as they are: "0s" is a valid "off". + +5. New file blacklist_sweep_test.go (package user) with the -short tests from : TestBlacklistSweepSchedule (default entry, nil-app entry, scheduled names registered) and TestJWTBlacklistSweepCommand (fake store: success, failing store, nil app). Write them first and see them fail (RED), then implement (GREEN). The fake implements all three bouncer.BlacklistStore methods; record calls under a mutex. + + + cd /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin && S="$SCRATCH/user-modfile" && mkdir -p "$S" && cp go.mod go.sum "$S"/ && go mod tidy -modfile="$S/go.mod" && go vet -modfile="$S/go.mod" ./... && go test -modfile="$S/go.mod" -short -count=1 -run 'TestBlacklistSweepSchedule|TestJWTBlacklistSweepCommand|TestCommandsDocumented|TestAppBlacklist|TestMailFallbackLocaleBoot|TestPluginManifest' . && ! grep -nE 'NewTicker|chan struct' plugin.go && git diff --quiet -- go.mod go.sum + + go vet clean; the two new -short tests and the existing documented/manifest/blacklist tests pass; plugin.go has no ticker or stop channel; Schedule() and the command are wired; go.mod/go.sum untouched. + + + + Task 2: Interval validation tables, boot errors and the Postgres-backed command test + ../sm-user-plugin/classes/blacklist_sweep_test.go, ../sm-user-plugin/blacklist_sweep_test.go, ../sm-user-plugin/logger.go + + - classes TestBlacklistSweepInterval (-short): nil app → 10m; unset key → 10m; "10m" → 10m; "1h" → 1h; "30s" → 30s; "24h" → 24h; "0", "0s" and int 0 → 0 with no error; "soon", "3", "-1m", "500ms", "7m", "48h" → error containing golem15.user.jwt.blacklist_sweep_interval. + - root TestBlacklistSweepSchedule gains a table: "1h" → one entry with pact.Every(time.Hour); "30s" → pact.Every(30*time.Second); "0", "0s" and SUMMER_-style string "0" → empty schedule; a bad value → nil schedule. + - root TestBlacklistSweepBoot (-short): on bareApp with golem15.user.jwt.secret set, Boot with each bad value above returns an error naming the key; Boot with "10m", "0" and the key unset returns no error naming the key (tolerate unrelated bareApp boot errors exactly as TestMailFallbackLocaleBoot does). + - root TestJWTBlacklistSweepPostgres (skips under -short): (a) published path: newSessionApp + bootPlugin(t, app, "0s") publishes the store; insert one row with expires_at and valid_until a minute in the past (jti sweep-me) and one with both an hour ahead (jti sweep-keep); run the command from p.Commands(); sweep-me is gone, sweep-keep remains, output has the result line. (b) console path: backpack.New(sessionConfig(t)) with database.dsn = sessionDSN and an app.key, no published *gorm.DB; insert another expired row; running the command removes it. Use unique jti values per test and delete the kept rows in t.Cleanup. + + +Add classes/blacklist_sweep_test.go (package classes) with the table test from ; build the app with the compass-backed config pattern the classes package already uses in its tests (look at an existing classes test that calls Config.Set, e.g. the mail fallback locale test), or backpack.New with a compass config from a temp dir. + +Extend blacklist_sweep_test.go with the custom-interval table in TestBlacklistSweepSchedule, a new TestBlacklistSweepBoot, and TestJWTBlacklistSweepPostgres. The Postgres test starts with skipShortPostgres(t) (or testing.Short with t.Skip("Postgres (testcontainers)")), reuses sessionDB/newSessionApp/bootPlugin, and for the console path follows TestBackfillHandlesOpensFromConfigWhenUnpublished in console_test.go (database.dsn, app.key, assert no *gorm.DB is published before Run). Insert rows with raw SQL into jwt_blacklist (jti, expires_at, valid_until), as the deleted TestLoginBlacklistSweep did. + +Root logger.go: after Task 1 the root package no longer references its logger variable. Run a grep over the root package's .go files (not subpackages: classes and controllers have their own). If nothing in the root package (tests included) references it, delete logger.go; otherwise leave it. + +Then run the whole module: go vet, go test -short ./..., and the Docker-backed run of the new Postgres test plus the blacklist-related tests (TestLogoutEndsTheSession, TestBootBeforeDatabase). If Docker access is denied although the user is in the docker group, run through sudo -u golem. Compare any failure with the Task 1 baseline; a new failure is a bug to fix, a baseline failure is reported in the SUMMARY. + + + cd /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin && S="$SCRATCH/user-modfile" && mkdir -p "$S" && cp go.mod go.sum "$S"/ && go mod tidy -modfile="$S/go.mod" && go vet -modfile="$S/go.mod" ./... && go test -modfile="$S/go.mod" -short -count=1 ./... && go test -modfile="$S/go.mod" -count=1 -run 'TestJWTBlacklistSweepPostgres|TestLogoutEndsTheSession|TestBootBeforeDatabase|TestBlacklistSweep' . && go test -modfile="$S/go.mod" -short -count=1 -run TestBlacklistSweepInterval ./classes && git diff --quiet -- go.mod go.sum + + All interval, schedule, boot and command tests pass; the Postgres test passes with Docker and skips under -short; go vet ./... and go test -short ./... green (or only baseline failures, listed in the SUMMARY); root logger.go removed if unreferenced. + + + + Task 3: README, manifest check and commit in sm-user-plugin + ../sm-user-plugin/README.md + +README.md edits (keep the existing structure and voice; every identifier named must exist): +- Features, "JWT sessions" bullet (line ~20): replace the clause saying Boot starts the blacklist's background sweep with: Boot installs the GORM hooks and publishes the Postgres jwt_blacklist store through lagoon.OnDatabase, and the expired rows are deleted by the scheduled user:jwt-blacklist-sweep command (see Configuration). Keep the rest of the bullet unchanged. +- API reference, classes bullet (line ~241 list): add BlacklistSweepInterval(app), DefaultBlacklistSweepInterval and JWTBlacklistTable. Console bullet (line ~265): list RequirePasswordChange, BackfillHandles, JWTBlacklistSweep and APITokenCommands. +- Configuration row golem15.user.jwt.blacklist_sweep_interval (line ~278), default 10m: how often the scheduler runs user:jwt-blacklist-sweep, which deletes the jwt_blacklist rows whose expires_at has passed (a Go duration). It must be at least 1s and divide 24h evenly (1m, 10m, 1h); 0 schedules no sweep. A value that does not parse, is negative, is shorter than a second or does not divide 24h fails boot. The sweep runs on the job worker's scheduled queue: the in-process worker of summer serve while queue.work_in_serve is on, queue:work, or schedule:run; with no worker on that queue run schedule:run --once from cron or the command by hand. The schedule runs once per period across instances. +- CLI commands table: a row for user:jwt-blacklist-sweep (purpose: delete the jwt_blacklist rows whose expires_at has passed; the scheduler runs it every golem15.user.jwt.blacklist_sweep_interval; ends with "Deleted the expired JWT blacklist rows."; example bin/ user:jwt-blacklist-sweep). The paragraph under the table (published database or database.dsn) already covers it. +- Testing: one sentence naming TestBlacklistSweepInterval (in classes, -short), TestBlacklistSweepSchedule, TestBlacklistSweepBoot and TestJWTBlacklistSweepCommand (root, -short) and TestJWTBlacklistSweepPostgres (Postgres, skipped under -short), with what each pins. +- Do not change the summary sentence (plugin.yaml's description derives from it) and do not touch config/config.yaml except, optionally, a one-line YAML comment above blacklist_sweep_interval saying 0 disables and the value must divide 24h; if you add it, include config/config.yaml in the commit. + +plugin.yaml lists no commands, so it needs no edit; TestPluginManifest confirms it still matches. + +Commit in /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin with explicit paths only (the files from Tasks 1-3 that changed, plus logger.go if deleted, via git rm or git add of the deletion), code and README in one commit. Message: "fix(quick-261119-kj8): sweep the JWT blacklist from a scheduled user:jwt-blacklist-sweep command" with a short body (the goroutine leaked one ticker per booting process because nothing stopped it; the sweep is now a console command the conga scheduler runs every blacklist_sweep_interval; an interval the scheduler cannot run now fails boot). No co-author or attribution trailers. Do not push or tag. Do not stage go.mod or go.sum. + + + cd /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin && grep -c 'user:jwt-blacklist-sweep' README.md && grep -n 'blacklist_sweep_interval' README.md | grep -c 'divide' && S="$SCRATCH/user-modfile" && go test -modfile="$S/go.mod" -short -count=1 -run 'TestPluginManifest|TestCommandsDocumented' . && SUBJ=$(git log -1 --format=%s) && case "$SUBJ" in *quick-261119-kj8*) true ;; *) false ;; esac && BODY=$(git log -1 --format=%B) && ! printf '%s\n' "$BODY" | grep -qi 'co-authored' && git diff --quiet HEAD -- go.mod go.sum + + README documents the command, the config semantics and where the sweep runs; manifest and docs tests pass; one commit in sm-user-plugin with code, tests and README, no trailers, go.mod/go.sum untouched, nothing pushed. + + + + + +## Trust Boundaries + +| Boundary | Description | +|----------|-------------| +| config → Boot | Operator-supplied golem15.user.jwt.blacklist_sweep_interval (YAML or SUMMER_ env) | +| scheduler → command | conga runs the compiled schedule entry on the job worker; only compiled entries run | + +## STRIDE Threat Register + +| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan | +|-----------|----------|-----------|----------|-------------|-----------------| +| T-kj8-01 | Denial of service | plugin.go Boot (goroutine per process) | medium | mitigate | Remove the in-process ticker; the sweep runs as a scheduled command once per period across instances | +| T-kj8-02 | Tampering | blacklist_sweep_interval value | low | mitigate | classes.BlacklistSweepInterval rejects unparsable, negative, sub-second and non-24h-divisor values at Boot, so a typo cannot silently stop revocation-row cleanup or make the worker fail to start | +| T-kj8-03 | Elevation of privilege | Sweep deleting live blacklist rows | high | mitigate | The command only calls bouncer's Sweep (DELETE WHERE expires_at < now); rows still inside their refresh window keep expires_at in the future (EndSession sets it), and TestJWTBlacklistSweepPostgres asserts an unexpired row survives | +| T-kj8-04 | Denial of service | No worker on the scheduled queue | low | accept | Blacklist rows then grow until a worker or cron runs; correctness of revocation is unaffected (expired rows only). README states how to run it without a worker | +| T-kj8-SC | Tampering | npm/pip/cargo installs | high | mitigate | No packages are installed by this plan; go.mod/go.sum must stay unchanged | + + + +- No goroutine: plugin.go contains no ticker and no stop channel; Plugin struct has only app. +- `(&Plugin{}).Schedule()` → [{user:jwt-blacklist-sweep, pact.Every(10m)}]; "0" → none; bad values fail Boot naming the key. +- `user:jwt-blacklist-sweep` deletes expired rows via the published store and via database.dsn, keeps unexpired rows. +- go vet ./... and go test -short ./... green in sm-user-plugin (modfile copy because of the pre-existing drift); Postgres test passes with Docker. +- README CLI row, config row and Features text updated; one commit, no push. + + + +- The plugin no longer starts a background goroutine in any process. +- The sweep runs through the framework scheduler on the job worker, at the configured interval, once per period. +- Defaults and config key unchanged for consumers; misconfiguration surfaces at boot. +- Tests and README cover the new command and schedule. + + + +Create `/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/quick/261119-kj8-sm-user-plugin-replace-the-jwt-blacklist/261119-kj8-SUMMARY.md` when done (include the sm-user-plugin commit hash, the go.mod drift note and any baseline test failures). + diff --git a/.planning/quick/261119-kj8-sm-user-plugin-replace-the-jwt-blacklist/261119-kj8-SUMMARY.md b/.planning/quick/261119-kj8-sm-user-plugin-replace-the-jwt-blacklist/261119-kj8-SUMMARY.md new file mode 100644 index 00000000..eeafbcc9 --- /dev/null +++ b/.planning/quick/261119-kj8-sm-user-plugin-replace-the-jwt-blacklist/261119-kj8-SUMMARY.md @@ -0,0 +1,129 @@ +--- +phase: quick-261119-kj8 +plan: 01 +subsystem: sm-user-plugin (golem15.user) +tags: [jwt, blacklist, scheduler, conga, console, goroutine-leak] +status: complete +requires: [pact.HasSchedule, pact.Every, conga scheduler, bouncer.BlacklistStore, lagoon.OpenFromApp] +provides: [user:jwt-blacklist-sweep, Plugin.Schedule, classes.BlacklistSweepInterval, classes.DefaultBlacklistSweepInterval, classes.JWTBlacklistTable, console.JWTBlacklistSweep] +affects: [every app mounting golem15.user (sweep now needs a worker on the scheduled queue)] +tech-stack: + added: [] + patterns: [scheduled console command via pact.HasSchedule (same shape as sm-oauthserver-plugin)] +key-files: + created: + - ../sm-user-plugin/classes/blacklist_sweep.go + - ../sm-user-plugin/classes/blacklist_sweep_test.go + - ../sm-user-plugin/console/jwt_blacklist_sweep.go + - ../sm-user-plugin/blacklist_sweep_test.go + modified: + - ../sm-user-plugin/plugin.go + - ../sm-user-plugin/session_test.go + - ../sm-user-plugin/README.md + - ../sm-user-plugin/config/config.yaml + deleted: + - ../sm-user-plugin/logger.go +decisions: + - "golem15.user JWT blacklist sweep runs as the scheduled console command user:jwt-blacklist-sweep (conga, job worker) instead of a per-process ticker goroutine; an interval the scheduler cannot run (unparsable, negative, under 1s, not dividing 24h) fails boot" +metrics: + completed: 2026-11-19 + duration: ~35m +actuals: + tokens: 11700 + tasks: 3 + commits: 1 +sm_user_plugin_commit: bc5f4f7 +plan_head_before: 6ec4c85 +plan_head_after: bc5f4f7 +--- + +# Quick 261119-kj8: Replace the JWT blacklist sweep goroutine with a scheduled command Summary + +golem15.user no longer starts a ticker goroutine from Boot. Expired `jwt_blacklist` rows are now deleted by a console command, `user:jwt-blacklist-sweep`. `Plugin.Schedule()` hands that command to the conga scheduler every `golem15.user.jwt.blacklist_sweep_interval` (default 10m, `0` disables it), and Boot rejects interval values the scheduler cannot run. + +All work is in the sm-user-plugin repo (`/media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin`), on master, in one commit: **bc5f4f7** `fix(quick-261119-kj8): sweep the JWT blacklist from a scheduled user:jwt-blacklist-sweep command`. The commit has no trailers. Nothing was pushed or tagged. + +## What changed + +- **classes/blacklist_sweep.go**: `JWTBlacklistTable`, `DefaultBlacklistSweepInterval` (10m), and `BlacklistSweepInterval(app)`. + - A nil app or nil config, or an unset or empty key, gives the 10m default. + - `0`, `0s` and an unquoted int `0` give 0, which means no sweep. + - Any other value must parse, be at least 1s and divide 24h. Otherwise the error names the key. + - A non-string config value falls back to `Config.Lookup` plus `fmt.Sprint`. +- **console/jwt_blacklist_sweep.go**: `JWTBlacklistSweep(app)` builds the command. + - It uses the published `bouncer.BlacklistStore`. If none is published, it opens a database through `lagoon.OpenFromApp` and calls `bouncer.NewPostgresBlacklist(sqlDB, classes.JWTBlacklistTable)`. + - It calls `Sweep(ctx, time.Now())`, wraps any error as `user:jwt-blacklist-sweep: %w`, and on success prints `Deleted the expired JWT blacklist rows.` + - A nil app returns an error. +- **plugin.go**: + - Removed `startBlacklistSweep`, the call to it and the `sweepStop` field. `Plugin` now holds only `app`. + - Boot validates the interval right after the mail fallback locale check. + - `Schedule()` returns one entry, `{user:jwt-blacklist-sweep, pact.Every(interval)}`. It returns nothing when the interval is 0 or invalid. + - Added the `pact.HasSchedule` assertion. + - `Commands()` registers the new command after `BackfillHandles`. + - The store is built with `classes.JWTBlacklistTable`. +- **session_test.go**: `bootPlugin` now returns only `*Plugin`, without the stop-channel cleanup. `TestLoginBlacklistSweep` is deleted (it used a 50ms ticker); the new Postgres test replaces it. +- **logger.go (root)** is deleted. Its `pluginLog` is no longer used in the root package. `classes` and `controllers` keep their own loggers, so the README line about the `user` log component is still accurate. +- **README.md**: updated the Features JWT sessions bullet, added a classes API sub-bullet, added `JWTBlacklistSweep` to the console bullet, rewrote the config row (0 disables, must divide 24h, failure at boot, where the sweep runs, `schedule:run --once` from cron), added a CLI table row and a paragraph in Testing. +- **config/config.yaml**: added a one-line comment above `blacklist_sweep_interval`. The value is unchanged. + +Consumers keep the same config key, default, table and routes. + +## Verification + +All Go commands ran with the scratch modfile (see Go module drift below). + +| Check | Result | +|---|---| +| `go vet ./...` | clean | +| `go test -short ./...` | green apart from the 2 baseline failures below | +| `go test ./...` (Docker, testcontainers) | green apart from the same 2 baseline failures; classes, middleware, models and updates pass | +| `TestJWTBlacklistSweepPostgres` (published store, and database from `database.dsn`) | PASS; skipped under `-short` | +| `TestBlacklistSweepSchedule`, `TestBlacklistSweepBoot`, `TestJWTBlacklistSweepCommand` (root, `-short`) | PASS | +| `TestBlacklistSweepInterval` (classes, `-short`) | PASS | +| `TestLogoutEndsTheSession`, `TestBootBeforeDatabase`, `TestAppBlacklist`, `TestBackfillHandlesOpensFromConfigWhenUnpublished` | PASS | +| `TestPluginManifest`, `TestCommandsDocumented`, `TestMailFallbackLocaleBoot`, `TestMailFallbackLocaleConfig` | PASS | +| `grep -nE 'NewTicker\|chan struct' plugin.go` | no match | +| `git diff --quiet HEAD -- go.mod go.sum` | unchanged | + +Docker access worked directly, so `sudo -u golem` was not needed. + +### Baseline failures (recorded before any edit, unchanged afterwards) + +- `TestRegisterImportDirection`: it runs a plain `go list -deps ./...`, which ignores `-modfile` and so stops at the go.mod drift ("updates to go.mod needed"). +- `TestRegisterCORSPath`: it reads the host app's `config/http.yaml`. That file does not exist in a standalone plugin checkout, as the README already says. + +## Go module drift (pre-existing, not fixed) + +sm-user-plugin's `go.mod` replaces the framework with `../summercms.go`. Framework master now pulls indirect dependencies that this go.mod does not list: goquery, cascadia, fatih/color, html2text, go-colorable, go-isatty, olekukonko/*, ssor/bom, vanng822/css, go-premailer, plus newer golang.org/x/crypto, net, sync, sys, term and text. Because of this, plain `go vet` / `go test` stop with "updates to go.mod needed". + +Every command ran with `-modfile` pointing to a tidied copy in the session scratchpad. The repo's go.mod and go.sum are byte-identical to before. The drift should be fixed when the plugin's framework requirement is next bumped. + +## Deviations from Plan + +**1. [Rule 2] More cases in the tests than the plan listed.** `TestBlacklistSweepInterval` also checks a `SUMMER_` env `0`, a whitespace-padded `" 1m "`, a nil config and an int `-5`. Both Postgres sub-tests also check that the unexpired row survives (threat T-kj8-03). Test files only. + +**2. [Rule 3] Added a small `envApp(t, environ...)` helper** to blacklist_sweep_test.go. It is needed for the `SUMMER_`-variable case of the schedule table, because `bareApp` takes no environment. + +**3. Commit granularity.** The plan's Task 3 asks for one combined commit (code, tests and README), so Tasks 1 and 2 were not committed separately. + +**4. Commit on master.** The commit is on sm-user-plugin's master. That repo is not an MSD worktree, and the plan and the orchestrator named master as the target. + +## TDD + +- **RED**: `blacklist_sweep_test.go` was written first and failed to compile (`p.Schedule undefined`). +- **GREEN**: the implementation made it pass. +- The Task 2 tables were added after the implementation; they pass. + +## Known Stubs + +None. + +## Threat Flags + +None. No new network endpoints or auth paths. The command only calls bouncer's existing `Sweep`. + +## Self-Check: PASSED + +- FOUND: classes/blacklist_sweep.go, classes/blacklist_sweep_test.go, console/jwt_blacklist_sweep.go, blacklist_sweep_test.go (in sm-user-plugin HEAD) +- FOUND: commit bc5f4f7 in sm-user-plugin +- logger.go deleted in bc5f4f7 (intentional)