chore: retire the legacy examples/ directory

[desimone]

Summary

Remove the stale example content from the root examples/ directory and leave an examples/README.md stub pointing readers to pomerium/documentation/content/examples/. Most of these examples hadn't been maintained since 2020-2022 and either duplicated content already in the docs repo, referenced removed features such as forward-auth, used deprecated tooling, or depended on dev-tag images. The one example still worth preserving, mutual-tls/, was migrated in pomerium/documentation#2193, so this PR depends on that landing first.

The PR also removes the remaining root examples/ references in go.mod, .golangci.yml, .pre-commit-config.yaml, and the Makefile cover: target. Tag-pinned links (tree/v0.30.0/examples/...) keep working, and links to main/examples/... land on the redirect stub instead of a hard 404.

Related issues

Depends on pomerium/documentation#2193. PR is draft until that merges.

User Explanation

Code that used to live at github.com/pomerium/pomerium/tree/main/examples/... now lives at github.com/pomerium/documentation/tree/main/content/examples/.... The redirect stub gives anyone landing on the old URL a pointer to the new home.

Checklist

• reference any related issues
• updated unit tests — n/a, no source code touched
• add appropriate label (chore)
• ready for review — currently draft

AI assistance

Drafted and reviewed with Claude and codex; verified the diff and ran make build, make test, make lint, and make cover locally.

[github-actions]

✅ Acceptance Test Summary

Result	Count
✅ Passed	68
❌ Failed	0
⊘ Skipped	0
⏱️ Duration	61.3s

Feature Coverage

Category	Tests	Status	Features
Authentication	19	✅	OIDC Auth Code Flow, Session Cookies, Scope Negotiation, Sign Out, HMAC-Signed URLs, Session Termination
Authorization	28	✅	Email Domain Policy, Group Claims, AND/OR Logic, Claim Matching, Deny Rules, Policy Precedence
Headers	21	✅	Cookie Security Flags, HttpOnly, SameSite, CORS Preflight, Cross-Origin Requests, X-Forwarded-Host

⏱️ Slowest Tests

1. authn/token-refresh.spec.ts › Token Refresh › should maintain access after token expiry through refresh (22.4s)
2. authn/token-refresh.spec.ts › Token Refresh › should preserve session cookie after refresh (21.8s)
3. authn/pkce.spec.ts › PKCE › multiple PKCE cookies can coexist (2.7s)

📋 All Tests by Category

Authentication (19)

• ✅ should reject callback with missing state parameter (859ms)
• ✅ should reject callback with empty state parameter (834ms)
• ✅ should validate CSRF cookie matches state (1.5s)
• ✅ should reject callback without CSRF cookie (1.4s)
• ✅ should redirect unauthenticated user to Keycloak login (1.6s)
• ✅ should complete login flow and set session cookie (1.8s)
• ✅ should preserve target URL after login redirect (1.6s)
• ✅ should request correct OIDC scopes (864ms)
• ✅ should clear session cookie on logout (1.9s)
• ✅ should require authentication after logout (2.4s)
• ✅ unsigned sign_out redirects to authenticate service (1.5s)
• ✅ sign_out flow clears session via confirmation page (2.1s)
• ✅ login should set PKCE query parameters (717ms)
• ✅ login should fail with missing PKCE cookie (1.3s)
• ✅ login should fail with tampered PKCE cookie (1.3s)
• ✅ login should fail with replayed PKCE cookie (2.5s)
• ✅ multiple PKCE cookies can coexist (2.7s)
• ✅ should maintain access after token expiry through refresh (22.4s)
• ✅ should preserve session cookie after refresh (21.8s)

Authorization (28)

• ✅ should allow access for user with matching email domain (1.1s)
• ✅ should deny access for user with non-matching email domain (1.3s)
• ✅ should enforce domain policy independent of groups (1.3s)
• ✅ should deny explicitly denied user (1.3s)
• ✅ deny rule should take precedence over allow (1.4s)
• ✅ should allow user with matching group (1.1s)
• ✅ should deny user without matching group (1.3s)
• ✅ should allow user with both group AND claim (1.1s)
• ✅ should deny user with group but missing claim (1.3s)
• ✅ should enforce multiple groups requirement (1.1s)
• ✅ user in wrong group should not reach upstream (1.3s)
• ✅ should accept valid client certificate signed by root CA (692ms)
• ✅ should accept certificate signed by intermediate CA (639ms)
• ✅ should reject certificate from untrusted CA (561ms)
• ✅ should reject request without client certificate (479ms)
• ✅ should allow access without certificate on non-mTLS domain (1.0s)
• ✅ public endpoints should be accessible without authentication (186ms)
• ✅ programmatic login endpoint should be accessible (175ms)
• ✅ protected internal endpoints should require authentication (174ms)
• ✅ protected endpoints should not be reachable via traversal variants (202ms)
• ✅ route traversal under /.pomerium should not bypass auth (187ms)
• ✅ protected internal endpoints should succeed after authentication (1.4s)
• ✅ public endpoints should remain accessible after authentication (1.6s)
• ✅ session pages should not expose user data when unauthenticated (273ms)
• ✅ session pages should expose session data after authentication (1.1s)
• ✅ JWT endpoint should not bypass authentication when disabled (1.1s)
• ✅ sign_out should redirect to signed authenticate endpoint (178ms)
• ✅ webauthn endpoint should reject unsigned requests even when authenticated (991ms)

Headers (21)

• ✅ session cookie should have all required security properties (1.1s)
• ✅ CSRF cookie should have required security properties (1.1s)
• ✅ should set fresh cookies on new login (1.8s)
• ✅ should pass OPTIONS preflight with cors_allow_preflight enabled (182ms)
• ✅ should not allow unauthenticated access even when preflight is enabled (210ms)
• ✅ should redirect OPTIONS without cors_allow_preflight (186ms)
• ✅ should allow actual cross-origin GET after preflight (214ms)
• ✅ should allow cross-origin POST with cors_allow_preflight (198ms)
• ✅ should block cross-origin request without cors_allow_preflight (193ms)
• ✅ should append x-forwarded-host when host rewrite is active (1.1s)
• ✅ should append x-forwarded-host when default auto host rewrite is active (1.0s)
• ✅ should preserve the original host when preserve_host_header is enabled (1.0s)
• ✅ should allow removing x-forwarded-host after host rewrite (973ms)
• ✅ claim headers should be passed to upstream (1.0s)
• ✅ JWT claims should be accessible via /.pomerium/user endpoint (1.1s)
• ✅ identity claims should match claim headers (1.1s)
• ✅ should upgrade authenticated connection to WebSocket (1.5s)
• ✅ should send and receive WebSocket messages (1.0s)
• ✅ should reject WebSocket connection for unauthenticated user (183ms)
• ✅ should work with preserve_host_header option (1.7s)
• ✅ should handle binary WebSocket messages (1.2s)

[coveralls]

Coverage Report for CI Build 25617805785

Coverage decreased (-0.01%) to 45.424%

Details

• Coverage decreased (-0.01%) from the base build.
• Patch coverage: No coverable lines changed in this PR.
• 25 coverage regressions across 8 files.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

25 previously-covered lines in 8 files lost coverage.

File	Lines Losing Coverage	Coverage
pkg/storage/postgres/backend.go	10	75.73%
pkg/storage/postgres/postgres.go	4	88.08%
internal/databroker/server_clustered_follower.go	2	48.3%
internal/fileutil/watcher.go	2	92.78%
pkg/fanout/fanout.go	2	89.19%
pkg/fanout/receive.go	2	90.91%
pkg/grpc/databroker/syncer.go	2	85.67%
pkg/ssh/manager.go	1	80.13%

---

Coverage Stats

Relevant Lines:	78425
Covered Lines:	35624
Line Coverage:	45.42%
Coverage Strength:	113.94 hits per line

---

💛 - Coveralls