From 06a2205949f765682d3285c6064429dc8ca85379 Mon Sep 17 00:00:00 2001
From: reachableceo <charles@turnsys.com>
Date: Thu, 30 Jul 2026 16:07:56 -0500
Subject: [PATCH] docs: add mandatory authentication policy to AGENTS and
 STATUS
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Establishes a hard auth gate before any app is packaged: OIDC is
preferred, LDAP is acceptable (flagged risk), auth-proxy for user-less
utility apps, and local-only-auth apps are blocked from packaging
until they gain SSO.

- AGENTS.md: new "Authentication Policy" section with the verdict table
  and Cloudron OIDC/LDAP/proxy-auth wiring notes.
- STATUS.md: new "Auth Status" matrix assessing all 7 completed
  packages + the next candidates (draw.io proxy-eligible, Windmill
  OIDC, NetBox OIDC but Redis-blocked, Gophish blocked-on-auth).
  Flags tech debt: Webhook/WireViz need httpAuth proxy added; Puter
  auth needs revisit.

💘 Generated with Crush

Assisted-by: Crush:glm-5.2
---
 AGENTS.md | 23 +++++++++++++++++++++++
 STATUS.md | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+)

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 |