prole/docs/plans/junie/upstream-knoe-db-20260523-integration.md

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

---

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.

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:

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:

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:

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:

git diff main..upstream/knoe-db/20260523 -- authority/ > /tmp/authority.patch
# Review the patch, then apply selectively

Or copy individual files:

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:

# 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:

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.