# 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

```bash
# 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`](../upstream-knoe-db-sync.md) for the full sync procedure.