diff --git a/AGENTS.md b/AGENTS.md index 27db6d6..14a7609 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -98,6 +98,29 @@ Docs and code drift apart. After any work session, an agent MUST: | [`GitUrlList.txt`](GitUrlList.txt) | Master upstream repo list (source of truth) | | [`Package-Templates/`](Package-Templates/) | Reusable templates per packaging pattern | +## Authentication Policy (MANDATORY) + +Every app must have an auth story **before** packaging. Research it up front and +record it in the [Auth Status](STATUS.md#auth-status) matrix. + +| Auth type | Verdict | Action | +|-----------|---------|--------| +| **OIDC client** (native or plugin) | ✅ PREFERRED | Package; wire Cloudron OIDC provider env vars. | +| **LDAP** (native or plugin) | ⚠️ ACCEPTABLE w/ RISK | Package, but FLAG as "auth-risk: LDAP" in STATUS + README — must be fixed/validated before production. | +| **Local-only** (built-in user DB, no SSO) | ❌ UNACCEPTABLE | Do NOT package. Record in STATUS as blocked-on-auth. | +| **No user concept** (stateless/utility app) | ✅ via AUTH PROXY | Package with `httpAuth: {"type":"proxy"}` so Cloudron gates access at the proxy. Admin restricts who can reach it. | + +**OIDC env vars Cloudron exposes** (when the app consumes the platform OIDC +provider): `CLOUDRON_OIDC_ISSUER`, `CLOUDRON_OIDC_CLIENT_ID`, +`CLOUDRON_OIDC_CLIENT_SECRET`, `CLOUDRON_OIDC_TOKEN_SIGNATURE_ALGORITHM` +(manifestVersion 2 / platform OIDC). LDAP addon env vars: +`CLOUDRON_LDAP_*`. See `CloudronManifest.json` `addons` (no extra addon needed +for proxy auth; use the `httpAuth` field). + +**Before writing a Dockerfile**, determine which row applies and write the +finding into STATUS.md's Auth Status table. Never silently ship a local-only- +auth app. + ## Cloudron Packaging — Quick Reference **Pick a pattern** (see JOURNAL.md for full templates and worked examples): diff --git a/STATUS.md b/STATUS.md index 1476424..722586b 100644 --- a/STATUS.md +++ b/STATUS.md @@ -64,6 +64,39 @@ Full write-ups of each pattern + challenges are in [`JOURNAL.md`](JOURNAL.md). | Security | 5 | 0/5 | | | System-Administration | 2 | 0/2 | | +## Auth Status + +Auth capability is a hard gate before packaging (see +[AGENTS.md § Authentication Policy](AGENTS.md)). ✅ = OIDC preferred, ⚠️ = +LDAP acceptable (risk flag), 🔄 = auth-proxy (no users), ❌ = local-only +(unacceptable / blocked-on-auth). + +### Completed packages (7) + +| App | OIDC | LDAP | Verdict | Note | +|-----|------|------|---------|------| +| Webhook | n/a | n/a | 🔄 proxy-eligible | No user concept; **auth-gap: needs `httpAuth` proxy added** | +| APISIX | plugin | plugin | ⚠️ risk | openid-connect/ldap-auth gateway plugins (edge auth, not dashboard) | +| Healthchecks | no | no | 🔄 proxy-eligible | REMOTE_USER_HEADER support; consider httpAuth proxy | +| Review Board | no | yes | ⚠️ risk (LDAP) | SAML 2.0 via plugin; built-in LDAP/AD backend | +| WireViz Web | n/a | n/a | 🔄 proxy-eligible | Stateless, no users; **auth-gap: needs `httpAuth` proxy added** | +| Puter | no | no | ❌ risk | Own user system, no SSO federation — needs revisit | +| Corteza | yes | no | ✅ preferred | Native OIDC via `auth.external.providers.openid-connect.*` | + +### Candidates researched + +| App | OIDC | LDAP | Verdict | Note | +|-----|------|------|---------|------| +| docker-drawio | n/a | n/a | 🔄 proxy-eligible | Stateless diagramming; package with `httpAuth` proxy | +| Windmill | yes | no | ✅ preferred | OIDC native; configured via Admin Settings UI (no env vars) | +| NetBox | yes | yes | ✅ auth, ❌ Redis | OIDC+LDAP native, but HARD Redis dep (Cloudron has none) — Complex | +| Gophish | no | no | ❌ blocked | Local admin login only, no SSO — do not package until auth added | + +**Immediate queue:** docker-drawio (proxy auth), Windmill (OIDC). +**Deferred:** NetBox (bundle Valkey+supervisor — significant), Gophish +(blocked-on-auth). +**Tech debt:** add `httpAuth` proxy to Webhook + WireViz Web; revisit Puter auth. + ## Known Issues | Issue | Impact | Status |