new proxy-auth-lib/ workspace for applications that sit behind an identity-aware proxy with JWKS-backed JWT verification

[horner]

This introduces a new proxy-auth-lib/ workspace for applications that sit behind an identity-aware proxy and need to trust signed identity assertions instead of raw forwarded headers. It provides a consistent MVP across Node.js, Python, Rust, and Go for header extraction, JWKS-backed JWT verification, issuer/audience/expiration checks, and verified identity propagation.

• Multi-language middleware scaffold

  • Added proxy-auth-lib/ with language-specific implementations for:
    • Node.js: Express-style middleware
    • Python: ASGI middleware for FastAPI / Starlette-style apps
    • Rust: Axum middleware
    • Go: net/http middleware
  • Standardized the shared config model across all four implementations:
    • TRUSTED_PROXY_ASSERTION_HEADER
    • TRUSTED_PROXY_JWKS_URL
    • TRUSTED_PROXY_ISSUER
    • TRUSTED_PROXY_AUDIENCE

• Verification model

  • Each implementation now handles:
    • configured assertion header lookup
    • JWKS key resolution
    • JWT/JWS signature verification
    • issuer validation
    • audience validation
    • expiration validation
    • verified identity extraction (subject, email, name, raw claims)
  • Invalid, missing, expired, malformed, or wrongly scoped assertions are rejected with a 401 without leaking token contents.

• Shared fixtures and coverage

  • Added shared JWKS/JWT fixtures under proxy-auth-lib/testdata/
  • Added per-language coverage for:
    • valid assertion
    • missing assertion
    • expired assertion
    • invalid signature
    • wrong issuer
    • wrong audience
    • malformed token

• Docs and repository structure

  • Added a dedicated docs page for the trusted proxy auth pattern
  • Updated navigation and repository layout references
  • Extended architecture docs to explicitly warn against trusting unsigned identity headers and to point readers at the new middleware examples
  • Kept vendor references neutral: Cloudflare, Pomerium, OAuth2 Proxy, Envoy, Traefik, and NGINX are described as examples of the same upstream-auth pattern, not special cases

• Example

  • Node.js usage is intentionally minimal:

app.use(createTrustedProxyAuth(loadConfigFromEnv()));

app.get('/me', (req, res) => {
  res.json(req.trustedProxyIdentity);
});

---

Updates since initial draft

• Hostname-derived config defaults

  • When env vars are unset, the auth domain defaults to auth.<parent-domain> of the host FQDN (e.g. web1.os.example.org → auth.os.example.org), with issuer/JWKS/audience derived from it. All vars remain optional overrides.

• Static public-key verification (JWKS still preferred)

  • Added TRUSTED_PROXY_PUBLIC_KEY (inline PEM) and TRUSTED_PROXY_PUBLIC_KEY_FILE (path) across all four languages.
  • When a public key is configured, verification uses it directly and performs no network calls; otherwise JWKS is used (the default and recommended path for key rotation / OIDC providers).
  • Config validation now requires either a JWKS URL or a public key.

• Algorithm pinning

  • Verification is pinned to RS256 in every implementation.

• Fixtures & tests

  • Added shared proxy-auth-lib/testdata/public-key.pem (matches existing token fixtures) plus offline static-key tests in each language.

[runleveldev]

This is a large addition that is only orthogonally related to the work done in this repo. Due to that fact, I would like this moved to its own repo where the library lifecycle can be managed independently of the infrastructure.

[horner]

I don't necessarily disagree but I want to test alongside the server config for now. I'd like to merge it and then I'll use subtree to fork it out. We need a test environment to prove it out.

[horner]

Also. I want every container to default to proxy auth and have these libraries installed in the templates and be prompted to use them.

[runleveldev]

Also. I want every container to default to proxy auth and have these libraries installed in the templates and be prompted to use them.

Defaulting to proxy auth is very doable. There's no clean way to preinstall this (these?) libraries though. You'd want to handle that at a project template layer which we don't currently provide.

[runleveldev]

Per our discussion, moving this to draft until the header contract is stabilized. See #355 for progress.

[runleveldev]

@horner I think I've stablized the header contract we'll be supporting. It's described https://github.com/mieweb/opensource-server/blob/348-oauth2-proxy-forward-auth/mie-opensource-landing/docs/users/consuming-auth.md which will be going out with the next update. That document is suggesting the environment variables OIDC_ISSUER, OIDC_JWKS_URI and OIDC_AUDIENCE. As an admin, I can force these environment variables into all containers to be read from /etc/environment (or PID 1's environ per container standards). All 3 (even audience) is going to be identical across all containers because technically the audience is for the proxy, not each individual app.