prole/docs/branches/upstream-knoe-db-20260523.md

Upstream review: upstream/knoe-db/20260523

Branch: upstream/knoe-db/20260523
Upstream: git@git.knoe.dev:knoe-dev/knoe-db.git (main)
Fetched: 2026-05-23
Commits ahead of our main: 684
Files differing from our main: 403

⚠️ No shared history. The upstream repo and this fork have diverged from separate roots — there is no common merge base. A standard git merge will refuse unless --allow-unrelated-histories is passed. Do not attempt a bulk merge. Cherry-pick or copy individual files/directories that are valuable.

---

Summary of incoming changes

1. authority/ — knoe-auth Java OIDC service (high value)

The upstream has a substantially evolved authority/ (knoe-auth) Java app:

Area	What changed
LoginController, OidcAuthorizeController, OidcTokenController, OidcUserInfoController	Robust next-URL handling, absolute issuer URL, @RequestMapping removed from LoginController, URL-encoding fixes
OidcCodeService, OidcTokenService	Real access JWT, Bearer userinfo, groups claim, allowedClientIds in token endpoint, email_verified=true
GoogleOAuthService, InviteService	Google client_id/secret whitespace strip, authorization URL encoding to prevent URI.create() crash
AuthProperties, application.yml	emailDomain config replaces hardcoded @prole.org
V1__oidc_authorization_codes.sql	OIDC authorization codes migration
Tests	AdminControllerTest, OidcCodeServiceTest, IdentityRegressionTest, KadminClientTest, EnrollValueTypesTest

Action: Review and cherry-pick the OIDC fixes into our authority/ — these are bug fixes we likely want.

---

2. knoe/core/ — installer core (high value, high conflict risk)

403 files differ; the installer core is heavily changed upstream:

Module	What changed
actions.py	Large changes — upstream has pruned pg_knoe_auth references, added k3d paths
milestones.py	k3d milestone additions, kerberos disable for k3d
env.py	Likely diverged from our gke_ kubecontext detection work
ops/ (16 files)	garage_store, registry, monitoring, openbao, opentofu, storage, gke_clusters
build_context.py, controller.py, topology.py, policy.py	Various upstream changes

Conflict risk: HIGH. We have local commits to env.py (gke_ detection), knoe_conf.py, and cfg.py that are not in upstream. A file-level merge will require careful diff review.

---

3. pg-knoe-auth/ — PostgreSQL C extension (upstream-only, new)

The upstream has a pg-knoe-auth/ PostgreSQL C extension for JWT-based auth at the DB level:

Path	Description
pg-knoe-auth/src/pg_knoe_auth.c	C extension source
pg-knoe-auth/src/Makefile	Build
pg-knoe-auth/test/integration/	Integration tests with mock JWKS server
pg-knoe-auth/test/unit/	Unit tests
pg-knoe-auth/README.md	Documentation

Note: Upstream commit 270aba3 (prune: remove pg_knoe_auth references from installer and UI) and f40cb32 (merge k3d branch) suggest upstream itself is in the process of removing pg_knoe_auth from the installer. The extension code remains but is being decoupled.

Action: Evaluate whether we want this extension. If yes, copy pg-knoe-auth/ wholesale (it doesn't conflict with anything we have).

---

4. deploy/gcp/gke/ and deploy/opentofu/k3s/manifests/knoe/ — K8s manifests

New and updated manifests upstream:

File	Description
deploy/gcp/gke/knoe-auth-deployment.yaml	knoe-auth GKE deployment
deploy/gcp/gke/svc-knoe-auth-ingress.yaml	knoe-auth ingress
deploy/gcp/gke/oauth2-proxy-*.yaml	oauth2-proxy deployment + secrets examples
deploy/gcp/gke/knoe-onboard.yaml	Onboarding manifest
deploy/opentofu/k3s/manifests/knoe/knoe-auth-service.yaml	knoe-auth k3s service
deploy/opentofu/k3s/manifests/knoe/grafana-proxy-*.yaml	Grafana proxy configmap/deployment/service
deploy/opentofu/k3s/manifests/knoe/gitea-spnego-proxy.yaml	Gitea SPNEGO proxy
deploy/opentofu/k3s/manifests/knoe/traefik-helmchartconfig.yaml	Traefik config

Action: Review against our GKE manifests in k8s/. Some of these may be additive.

---

5. k8s/knoe/ — k3d cluster manifests (new)

File	Description
k8s/knoe/knoe-db-k3d.yaml	CNPG cluster manifest for k3d (new)
k8s/knoe/garage-statefulset-k3d.yaml	Garage statefulset for k3d (new)
k8s/knoe/knoe-db.yaml	Updated production CNPG manifest

Action: knoe-db-k3d.yaml and garage-statefulset-k3d.yaml are likely additive — copy in.

---

6. etc/ — init scripts (moderate conflict risk)

17 etc/ files differ. We have our own versions of many of these in mock_val/ (committed in 3f96f66). Key upstream additions:

File	Notes
etc/init_knoe_auth.sh	knoe-auth init — compare with our mock_val/init_knoe_auth.sh
etc/init_knoe_users.sh	User init — compare with our mock_val/init_knoe_users.sh
etc/init_cnpg_gke.sh	GKE CNPG init — compare with our version
etc/init_user_schemas_gke.sh	New GKE user schema init
etc/init_grafana_oauth_prole.sh	Grafana OAuth (prole variant)
etc/init_oauth2_proxy_prole.sh	oauth2-proxy (prole variant)
etc/sync_cnpg_grafana_dashboard.py	Dashboard sync script
etc/knoe_cfg.sh	Config helper
etc/build_db.sh, etc/fetch_prole_secrets.sh	Build/secrets helpers

---

7. docs/plans/junie/ — upstream Junie briefs (informational)

The upstream has 20 Junie brief files that differ from ours. Notable upstream-only briefs:

File	Subject
knoeledge-naming-standards.md	Naming conventions doc
knoeledge-tenant-onboarding.md	Tenant onboarding playbook
per-user-supabase-workspace.md	Per-user Supabase workspace design
knoe-auth-device-flow.md	Device flow for knoe-auth
pg-knoe-auth-build-fix-and-installer-integration.md	pg-knoe-auth build/integration
deploy-pipeline-restore.md	Deploy pipeline restore
db-secret-username-drift-fix.md	DB secret username drift fix
init-user-schemas-heredoc-fix.md	Heredoc fix for user schema init
auth-0-ingress-and-rename-regression.md	Auth ingress regression
black-sweep-and-pin.md	Black formatter sweep

Action: Read these briefs — several describe work we may want to implement (device flow, per-user Supabase, tenant onboarding).

---

8. conf/ — config files (conflict)

conf/k3d.cfg, conf/k3s.cfg, conf/gke.cfg, conf/knoe.cfg, conf/service/knoe.cfg, conf/service/prod.cfg all differ. We just cleaned our cfg files of MagicMock contamination. Do not overwrite our cfg files with upstream versions — they contain our environment-specific values.

---

9. infrastructure/ — Ansible roles and playbooks

File	Notes
infrastructure/roles/samba_dns/tasks/ (3 files)	DNS role updates
infrastructure/roles/samba_reverse_dns/tasks/ (2 files)	Reverse DNS role
infrastructure/roles/acme/tasks/main.yml	ACME cert role
infrastructure/playbooks/kerberos_trust_setup.yml	Kerberos trust playbook
infrastructure/playbooks/workstation_kerberos.yml	Workstation Kerberos
infrastructure/inventory/	hosts.ini, group_vars updates

Action: Review Ansible role changes — likely additive/safe to merge.

---

Conflict summary

Area	Risk	Recommendation
knoe/core/ (actions, milestones, env, ops)	🔴 HIGH	Manual file-by-file diff; protect our env.py gke_ detection
conf/*.cfg	🔴 HIGH	Do NOT overwrite — keep our values
authority/ OIDC fixes	🟡 MEDIUM	Cherry-pick individual commits (listed above)
etc/ init scripts	🟡 MEDIUM	Compare with mock_val/ equivalents before replacing
pg-knoe-auth/	🟢 LOW	Additive — copy wholesale if desired
k8s/knoe/*-k3d.yaml	🟢 LOW	Additive — copy in
deploy/gcp/gke/ manifests	🟢 LOW	Review and add selectively
docs/plans/junie/ briefs	🟢 LOW	Read and adopt relevant ones
infrastructure/ Ansible	🟢 LOW	Likely additive

---

Next steps

# Inspect a specific file from upstream without switching branches
git show upstream/knoe-db/20260523:authority/src/main/java/dev/knoe/auth/web/LoginController.java

# Copy a whole directory from upstream into working tree
git checkout upstream/knoe-db/20260523 -- pg-knoe-auth/

# Diff a specific file
git diff main..upstream/knoe-db/20260523 -- knoe/core/env.py

See also: docs/upstream-knoe-db-sync.md for the full sync procedure.