Add basic-auth example: the simplest whole-site auth gate

Cargo.toml

@@ -34,9 +34,13 @@ ephpm-kv = { git = "https://github.com/ephpm/ephpm.git", rev = "e63284838d07d348
 
 # Every example parses its config out of a `serde_json::Value`.
 serde_json = "1"
-# api-key: constant-time key comparison to close the timing oracle a naive `==`
-# would open. Tiny, no_std, no transitive deps.
+# api-key + basic-auth: constant-time credential comparison to close the timing
+# oracle a naive `==` would open. Tiny, no_std, no transitive deps.
 subtle = "2"
+# basic-auth: standard-alphabet base64 to decode the RFC 7617 `Authorization:
+# Basic` credential. Tiny, no_std, audited — the same crate the ePHPm middleware
+# workspace uses for its token codecs.
+base64ct = { version = "1", features = ["alloc"] }
 
 # Release-profile tuning. `panic = "abort"` is DELIBERATELY NOT set: the
 # `declare!` glue in `ephpm-middleware` uses `catch_unwind` to fail CLOSED on a

README.md

@@ -40,10 +40,11 @@ for chain semantics, `match`/`order`, and mounting.
 
 ## The examples
 
-Three modules, chosen to cover the range rather than every use case:
+Four modules, chosen to cover the range rather than every use case:
 
 | Example | Crate | Teaches |
 |---------|-------|---------|
+| `basic-auth` | `ephpm-middleware-basic-auth` | The **simplest whole-site auth gate**: verify an `Authorization: Basic` credential (RFC 7617) with a constant-time compare, `401` + `WWW-Authenticate` otherwise. No KV. Gates static assets and PHP alike (ePHPm #408/#395). Start here. |
 | `api-key` | `ephpm-middleware-api-key` | A **request-phase auth gate** that also **uses the KV store**: read a key from a header (or query param), validate it against a static map **or** a `kv_get` lookup with a constant-time compare, and forward the resolved consumer id to PHP — or short-circuit `401`. |
 | `redirect` | `ephpm-middleware-redirect` | The **simplest early-return**: compute a canonical URL (scheme / host / trailing slash) and emit a single `301`/`308`, or `CONTINUE`. No KV, no extra deps. |
 | `header-transform` | `ephpm-middleware-header-transform` | The **response phase**: `declare!(Type, response)`, setting request headers PHP sees *and* setting/removing response headers on the way out. |
@@ -167,6 +168,7 @@ instead.
 
 ```
 crates/
+  ephpm-middleware-basic-auth         HTTP Basic whole-site gate    (declare!(BasicAuth))
   ephpm-middleware-api-key            request-phase auth gate + KV  (declare!(ApiKey))
   ephpm-middleware-redirect           canonical-URL redirect        (declare!(Redirect))
   ephpm-middleware-header-transform   response phase                (declare!(HeaderTransform, response))

crates/ephpm-middleware-basic-auth/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "ephpm-middleware-basic-auth"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "Example ePHPm native middleware: HTTP Basic auth gate (RFC 7617) — the simplest whole-site auth gate, gating static assets and PHP alike"
+
+[lib]
+# cdylib = the loadable module ePHPm dlopen()s; rlib so the unit tests can link
+# the crate as a library.
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+ephpm-middleware.workspace = true
+serde_json.workspace = true
+# Constant-time credential comparison — closes the timing oracle a naive `==`
+# opens (and avoids leaking which usernames exist).
+subtle.workspace = true
+# Decode the base64 `Authorization: Basic` credential.
+base64ct.workspace = true
+
+[dev-dependencies]
+# `host` gives the tests RequestCtx / host_table to fabricate a request without
+# a running server. Dev-only: resolver 3 keeps it out of the shipped cdylib.
+ephpm-middleware = { workspace = true, features = ["host"] }
+
+[lints]
+workspace = true