# Junie brief: integrate upstream knoe-db/20260523 **Tracked at:** `docs/branches/upstream-knoe-db-20260523.md` **Branch:** `upstream/knoe-db/20260523` **Priority:** Medium — work through sections in order, lowest-risk first. --- ## Why On 2026-05-23 we fetched the upstream `git@git.knoe.dev:knoe-dev/knoe-db.git` `main` branch into a review branch (`upstream/knoe-db/20260523`). The upstream has 684 commits and 403 differing files relative to our `main`. There is **no shared history** — a bulk merge is not safe. This brief tracks the structured cherry-pick/copy work to land the valuable upstream changes without clobbering our local customisations. Full analysis: [`docs/branches/upstream-knoe-db-20260523.md`](../../branches/upstream-knoe-db-20260523.md) --- ## What changes (ordered by risk, lowest first) ### Task 1 — Copy `pg-knoe-auth/` wholesale (additive, no conflict) The upstream has a PostgreSQL C extension (`pg-knoe-auth/`) for JWT-based DB-level auth. We have no local version of this directory. ```bash git checkout upstream/knoe-db/20260523 -- pg-knoe-auth/ git add pg-knoe-auth/ git commit -m "feat(pg-knoe-auth): import upstream PostgreSQL JWT auth extension" ``` **Note:** Upstream is decoupling this from the installer (`270aba3`, `f40cb32`) — the extension code is stable but installer wiring is being removed. Import the code; do not wire it into the installer yet. **Definition of done:** - [ ] `pg-knoe-auth/` directory present in `main` with `src/`, `test/`, `README.md` - [ ] `make test` still passes (Python tests unaffected) --- ### Task 2 — Copy k3d cluster manifests (additive, no conflict) Two new k3d-specific manifests exist upstream that we don't have: ```bash git checkout upstream/knoe-db/20260523 -- k8s/knoe/knoe-db-k3d.yaml git checkout upstream/knoe-db/20260523 -- k8s/knoe/garage-statefulset-k3d.yaml ``` Also review the updated `k8s/knoe/knoe-db.yaml`: ```bash git diff main..upstream/knoe-db/20260523 -- k8s/knoe/knoe-db.yaml ``` Apply any production CNPG manifest improvements that don't conflict with our GKE-specific settings (storage class, SA name, backup config). **Definition of done:** - [ ] `k8s/knoe/knoe-db-k3d.yaml` present - [ ] `k8s/knoe/garage-statefulset-k3d.yaml` present - [ ] `k8s/knoe/knoe-db.yaml` reviewed; any safe upstream improvements applied --- ### Task 3 — Review and adopt upstream Junie briefs Read the following upstream-only briefs and decide which to adopt: ```bash git show upstream/knoe-db/20260523:docs/plans/junie/knoeledge-naming-standards.md git show upstream/knoe-db/20260523:docs/plans/junie/knoeledge-tenant-onboarding.md git show upstream/knoe-db/20260523:docs/plans/junie/per-user-supabase-workspace.md git show upstream/knoe-db/20260523:docs/plans/junie/knoe-auth-device-flow.md git show upstream/knoe-db/20260523:docs/plans/junie/deploy-pipeline-restore.md git show upstream/knoe-db/20260523:docs/plans/junie/db-secret-username-drift-fix.md git show upstream/knoe-db/20260523:docs/plans/junie/init-user-schemas-heredoc-fix.md ``` For each brief that is relevant to our environment: copy it into `docs/plans/junie/` and add it to the active table in `docs/plans/junie/README.md`. **Definition of done:** - [ ] Each upstream brief read and evaluated - [ ] Relevant briefs copied to `docs/plans/junie/` - [ ] `docs/plans/junie/README.md` active table updated --- ### Task 4 — Cherry-pick `authority/` OIDC fixes (medium risk) The upstream has a series of bug fixes to the knoe-auth Java OIDC service. These are the upstream commits to cherry-pick (inspect each before applying): | Commit | Subject | |---|---| | `b588412` | fix(knoe-auth): replace hardcoded @prole.org with configured emailDomain | | `1ad7049` | fix(knoe-auth): remove @RequestMapping("/auth") from LoginController | | `5d43721` | fix(knoe-auth): use absolute issuer URL for login redirect in /authorize | | `202c16b` | fix(knoe-auth): robust next-URL handling — skip null nonce, encode scope spaces | | `7147758` | fix(knoe-auth): KNOE_AUTH_ENABLED=true + robust safeNext() URL parsing | | `ce78730` | fix(auth): URL-encode next param in login page hrefs | | `878254e` | fix(auth): strip leading/trailing whitespace from Google client_id/secret | | `ee3f16f` | fix(auth): encode Google authorization URL to prevent URI.create() crash | | `e5522d4` | fix(oidc): real access JWT + Bearer userinfo + groups claim | | `b8a4028` | fix(oidc): add email_verified=true to id_token claims | | `ce78730` | fix(oidc): accept allowedClientIds in token endpoint + fix audience | Since there is no shared history, cherry-pick will not work directly. Instead, copy the changed files: ```bash git diff main..upstream/knoe-db/20260523 -- authority/ > /tmp/authority.patch # Review the patch, then apply selectively ``` Or copy individual files: ```bash git checkout upstream/knoe-db/20260523 -- authority/src/main/java/dev/knoe/auth/web/LoginController.java # etc. ``` **Definition of done:** - [ ] All OIDC fix commits reviewed - [ ] Safe fixes applied to `authority/` - [ ] `authority/` Java tests pass (`mvn test` in `authority/`) --- ### Task 5 — Diff `knoe/core/` installer modules (high risk — do not bulk-copy) The upstream has significant changes to the installer core. **Do not overwrite our files.** Instead, diff each module and apply upstream improvements that don't conflict with our local changes: ```bash # Key files to diff: git diff main..upstream/knoe-db/20260523 -- knoe/core/env.py git diff main..upstream/knoe-db/20260523 -- knoe/core/actions.py git diff main..upstream/knoe-db/20260523 -- knoe/core/milestones.py git diff main..upstream/knoe-db/20260523 -- knoe/core/ops/monitoring.py git diff main..upstream/knoe-db/20260523 -- knoe/core/ops/garage_store.py ``` **Protect these local changes:** - `knoe/core/env.py` — our `gke_` kubecontext prefix detection (`da0fd2c`) - `knoe/knoe_conf.py` — our `normalize_environment()` patch - `knoe/ui/screens/cfg.py` — our `_validate_cfg_values` fix (`ef20c8a`) For each file: read the upstream diff, identify upstream improvements (k3d support, pg_knoe_auth pruning, etc.), and apply them manually without overwriting our local additions. **Definition of done:** - [ ] `knoe/core/env.py` reviewed; upstream improvements applied without losing `gke_` detection - [ ] `knoe/core/actions.py` reviewed; k3d additions and pg_knoe_auth pruning evaluated - [ ] `knoe/core/milestones.py` reviewed; k3d milestones evaluated - [ ] `make test` passes after all changes --- ### Task 6 — Review `etc/` init scripts (medium risk) Compare upstream `etc/` scripts with our `mock_val/` equivalents: ```bash git diff main..upstream/knoe-db/20260523 -- etc/init_knoe_auth.sh git diff main..upstream/knoe-db/20260523 -- etc/init_knoe_users.sh git diff main..upstream/knoe-db/20260523 -- etc/init_cnpg_gke.sh git diff main..upstream/knoe-db/20260523 -- etc/init_user_schemas_gke.sh ``` `etc/init_user_schemas_gke.sh` is upstream-only (new) — copy it in if it applies to our GKE setup. **Definition of done:** - [ ] Each `etc/` script diffed against our `mock_val/` equivalent - [ ] `etc/init_user_schemas_gke.sh` evaluated and copied if applicable - [ ] No regressions in existing init scripts --- ## Out of scope - `conf/*.cfg` — **never overwrite** with upstream versions; our env-specific values must be preserved. - `infrastructure/inventory/` — contains our host-specific values; review manually before touching. - Bulk `git merge --allow-unrelated-histories` — explicitly forbidden; too much conflict surface. --- ## Commit shape Each task above should be a separate commit: ``` feat(pg-knoe-auth): import upstream PostgreSQL JWT auth extension feat(k8s): add k3d cluster manifests from upstream (knoe-db-k3d, garage-k3d) docs(plans): adopt upstream Junie briefs — device-flow, tenant-onboarding, etc. fix(authority): apply upstream OIDC fixes from knoe-db/20260523 feat(core): apply upstream k3d installer improvements from knoe-db/20260523 feat(etc): apply upstream init script improvements from knoe-db/20260523 ``` When all tasks are done, update `docs/branches/README.md` status to ✅ Done.