diff --git a/Open-Questions.md b/Open-Questions.md index b7de094..baa28b0 100644 --- a/Open-Questions.md +++ b/Open-Questions.md @@ -29,17 +29,17 @@ When a question is decided, this doc gets updated; the decision is also reflecte | ID | Topic | Status | Decide by | |----|-------|--------|-----------| | Q01 | Concrete org table abstraction (Company โ†’ generic Organization?) | โœ… Decided (2026-06-24) | n/a | -| Q02 | Microsoft Entra ID in v0.1 or defer to v0.2 | ๐ŸŸก Leaning | Before W2 starts | -| Q03 | Flyway migration strategy (separate schema_history vs baseline reset) | ๐ŸŸก Leaning | Before W5 (Flyway work) | +| Q02 | Microsoft Entra ID in v0.1 or defer to v0.2 | โœ… Decided (2026-06-24) โ€” **Defer to v0.2** | n/a | +| Q03 | Flyway migration strategy (separate schema_history vs baseline reset) | โœ… Decided (2026-06-24) โ€” **Separate `flyway_schema_history_auth` table** (already implemented) | n/a | | Q04 | Email magic-link provider in v0.1 or v0.2 | โญ๏ธ Deferred | n/a | | Q05 | npm package name (`@platesoft/auth` vs alternatives) | โœ… Decided (2026-06-24) | n/a | -| Q06 | SemVer policy details โ€” peer-version lockstep enforcement | ๐ŸŸก Leaning | Before v0.1.0 release | -| Q07 | Gitea publishing pipeline (Gitea Actions vs manual deploy) | ๐ŸŸก Leaning | Before W6 | +| Q06 | SemVer policy details โ€” peer-version lockstep enforcement | โœ… Decided (2026-06-24) โ€” **Wire-version constant (WIRE_VERSION=1) in envelope + npm peer dep** | n/a | +| Q07 | Gitea publishing pipeline (Gitea Actions vs manual deploy) | โœ… Decided (2026-06-24) โ€” **Gitea Actions on `v*` tag** (workflows exist, test in W12) | n/a | | Q08 | Spring Boot version pin (4.0.7 vs 4.1.0 vs latest milestone) | โœ… Decided | n/a (4.1.0) | | Q09 | Frontend bundler โ€” `tsup` vs `tsc` vs `unbuild` | โœ… Decided (2026-06-24) | n/a | | Q10 | License โ€” MIT, Apache-2.0, or internal proprietary | โœ… Decided (2026-06-24) | n/a | | Q11 | First-class i18n in `@platesoft/auth`/react? | โญ๏ธ Deferred | n/a | -| Q12 | Audit emit channel โ€” DB rows only, or also event stream? | ๐ŸŸก Leaning | Before W2 | +| Q12 | Audit emit channel โ€” DB rows only, or also event stream? | โœ… Decided (2026-06-24) โ€” **DB rows only v0.1; `LoginEventSink` SPI in v0.2** | n/a | | Q13 | SecurityFilterChain scoping โ€” `securityMatcher` vs unscoped `anyRequest` | โœ… Decided (2026-06-24) โ€” fixed in code @ b43ab5e | n/a | | Q14 | Remove `@ComponentScan` from auto-config โ€” explicit `@Bean`/`@Import`? | โœ… Decided (2026-06-24) โ€” fixed in code @ b43ab5e | n/a | | Q15 | v0.1.0 surface โ€” finish full extraction vs rescope to OAuth-core | โœ… Decided (2026-06-24) โ€” **Path A: full extraction** | n/a | @@ -73,10 +73,12 @@ When a question is decided, this doc gets updated; the decision is also reflecte ### Q02 โ€” Microsoft Entra ID in v0.1? -**Status:** ๐ŸŸก Leaning toward: **Defer to v0.2** +**Status:** โœ… **Decided 2026-06-24** โ€” **Defer to v0.2** (extraction discipline > AI-assisted ease) **Context.** InspectFlow Sprint 14.1 ships Google OAuth. Microsoft Entra ID was scoped into the "SSO sprint" but never landed. Sparkboard does not need it day 1. +**GLM-5.2 + Lumen lens.** With full AI power, adding MS Entra would be ~half a day (same OAuth pattern, SPI hooks ready, V5 migration already indexes the tenant field). The data model supports it. BUT โ€” Sprint 0 is an *extraction* sprint, and MS Entra was never in InspectFlow's Sprint 14 code. Adding it would be a NEW feature, not an extraction. The discipline of "no new features in extraction" holds regardless of how easy AI makes it. The provider is a clean v0.2 addition โ€” same pattern, ~1 day with AI. + **Options:** | Option | Pros | Cons | @@ -95,7 +97,9 @@ When a question is decided, this doc gets updated; the decision is also reflecte ### Q03 โ€” Flyway migration strategy -**Status:** ๐ŸŸก Leaning toward: **Separate `flyway_schema_history_auth` table + multi-locations** +**Status:** โœ… **Decided 2026-06-24** โ€” **Separate `flyway_schema_history_auth` table** (already implemented in `PlateAuthFlywayConfig`) + +**GLM-5.2 + Lumen lens.** This was already implemented (W5 โ€” `PlateAuthFlywayConfig` creates a second Flyway bean with `table = "flyway_schema_history_auth"`, `locations = "classpath:db/migration/auth"`). It works, it's clean, no reason to revisit. The W-B co-existence test (W12) will prove it against a consumer that also has its own primary Flyway. **Context.** InspectFlow has migrations V1..V31 in one history table. plate-auth needs V1..V6 (its own 6 auth migrations โ€” see F2). If we deploy plate-auth into InspectFlow's existing DB, Flyway sees "your V1 is not my V1" โ€” collision. @@ -151,7 +155,9 @@ When a question is decided, this doc gets updated; the decision is also reflecte ### Q06 โ€” SemVer policy and peer-version lockstep -**Status:** ๐ŸŸก Leaning toward: **Lockstep enforced via npm `peerDependencies` + a startup check in the starter** +**Status:** โœ… **Decided 2026-06-24** โ€” **Wire-version constant (`WIRE_VERSION=1`) in HMAC envelope + npm `peerDependencies`** + +**GLM-5.2 + Lumen lens.** With AI assistance, implementing the wire-version is trivial: add `WIRE_VERSION = 1` to the envelope JSON in both `ExchangeService` (backend) and `signEnvelope()` (frontend), reject on mismatch. This is the *real* enforcement โ€” it's testable, strict, and prevents silent contract drift between the two artifacts. The npm peer dep is a secondary guard. Implement in W8 (backend) + W9 (frontend). ~2 hours across both halves. Bumping wire-version = trigger for a 0.x โ†’ 0.(x+1) release. **Context.** Backend and frontend ship from the same monorepo at the same version. If a consumer pins backend `0.1.0` and frontend `0.2.0`, the HMAC envelope contract might drift. @@ -173,7 +179,19 @@ When a question is decided, this doc gets updated; the decision is also reflecte ### Q07 โ€” Gitea publishing pipeline -**Status:** ๐ŸŸก Leaning toward: **Gitea Actions on tag `v*`** +**Status:** โœ… **Decided 2026-06-24** โ€” **Gitea Actions on `v*` tag โ€” full CI/CD, not just basic publishing** + +**Patrick's directive:** *"For Gitea and the DevOps tools behind us that make our lives so much nicer โ€” always try to be up-to-date. For Gitea, let's explore and do the hard stuff if it's worth it. We will learn and get better."* + +**Decision:** Full Gitea Actions pipeline, not just basic tag-publishing. This includes: +1. **`ci.yml`** โ€” on every push/PR: `mvn verify` + `pnpm build` + unit/integration tests (matrix Java 25 + Node 22) +2. **`release.yml`** โ€” on `v*` tag: build + test + publish Maven JAR to Gitea Package Registry + publish npm tarball to Gitea npm registry +3. **Snyk / OWASP dep-check** (ยง9.10 security checklist) โ€” scan for CVEs at release tag, fail build on >medium severity +4. **Renovate** โ€” configured for post-release dependency management (keeps deps current automatically) +5. **Provenance** โ€” explore Gitea Package Registry's provenance/signing features as they mature +6. **Test with `v0.0.1` validation tag** (W12) before cutting the real `v0.1.0` + +Workflows (`ci.yml` + `release.yml`) already exist in the repo. W12 tests the full pipeline end-to-end. The homelab's self-hosted `act_runner` on TrueNAS is the execution backend (same as CannaManage/InspectFlow). With GLM-5.2 + Lumen, we explore and adopt Gitea's latest Actions features as they land. **Context.** Gitea supports both Maven and npm registries. We need to publish on each tag. @@ -248,7 +266,9 @@ When a question is decided, this doc gets updated; the decision is also reflecte ### Q12 โ€” Audit emit channel -**Status:** ๐ŸŸก Leaning toward: **DB rows only in v0.1; pluggable `AuditEmitter` SPI in v0.2** +**Status:** โœ… **Decided 2026-06-24** โ€” **DB rows only v0.1; `LoginEventSink` SPI in v0.2** + +**GLM-5.2 + Lumen lens.** A `LoginEventSink` SPI is trivially easy to add (one interface, one no-op default, one `@ConditionalOnMissingBean`). But the question isn't effort โ€” it's *need*. For a 2-consumer homelab library (Sparkboard + InspectFlow), DB rows are sufficient. The `LoginEventService` writes rows, and W11 adds Envers `RevInfo` for entity-change audit. Together these cover the full v0.1 audit surface (login events + state changes). External shipping (Kafka/SIEM) is a v0.2 concern. The SPI will be a clean addition then. **Context.** [`LoginEvent`](backend/src/main/java/de/platesoft/inspectflow/entity) writes a DB row per login. Some consumers may want to emit to Kafka, NATS, syslog, or an external SIEM. @@ -345,6 +365,11 @@ When a question is decided, this doc gets updated; the decision is also reflecte | Q17 | `RefreshToken` entity/repository deleted โ€” stateless JWT refresh for v0.1 โ€” fixed @ b43ab5e | 2026-06-24 | Review v3 ยง1 B5 | | Q18 | `spring-boot-starter-web` โ†’ `spring-boot-starter-webmvc` (Spring Boot 4.x deprecation) โ€” fix in W10 | 2026-06-24 | Review v3 ยง2 N1, Plan v2 ยง13.3 | | Q09 | Frontend bundler โ†’ **`tsup`** (`packages/auth/tsup.config.ts` exists) โ€” implemented in W9 | 2026-06-24 | Plan v2 ยง13.2, this doc | +| Q02 | Microsoft Entra ID โ†’ **defer to v0.2** (extraction discipline holds even with AI ease; SPI + V5 migration ready) | 2026-06-24 | Roadmap.md v0.2, this doc | +| Q03 | Flyway โ†’ **separate `flyway_schema_history_auth` table** (already implemented in `PlateAuthFlywayConfig`) | 2026-06-24 | Plan v2 ยง7.3, this doc | +| Q06 | Lockstep โ†’ **wire-version constant (`WIRE_VERSION=1`) in HMAC envelope + npm peer dep** (implement in W8/W9) | 2026-06-24 | Architecture.md ยง1, Plan v2 ยง13.1/ยง13.2 | +| Q07 | Publishing โ†’ **full Gitea Actions CI/CD** (ci.yml + release.yml + Snyk + Renovate; test with v0.0.1 in W12) | 2026-06-24 | Plan v2 ยง8 + ยง13.5 W12, this doc | +| Q12 | Audit โ†’ **DB rows only v0.1** (LoginEventService + Envers RevInfo in W11); `LoginEventSink` SPI v0.2 | 2026-06-24 | Roadmap.md v0.2, this doc | ---