expediate 1.0.4 → 1.0.6

package/docs/git.md

@@ -0,0 +1,139 @@
+# Git Smart HTTP Gateway
+
+`gitHandler` implements the Git Smart HTTP protocol, enabling clients to clone, fetch, and push to Git repositories over plain HTTP. No additional dependencies beyond a working `git` installation are required.
+
+---
+
+## Quick start
+
+```ts
+import { createRouter, gitHandler } from 'expediate';
+import path from 'path';
+
+const app = createRouter();
+
+app.use('/repos/:repo', gitHandler({
+  repository: (req) => {
+    const name = req.params.repo;
+    // Validate to prevent path confusion
+    if (!/^[\w.-]+$/.test(name)) return null;
+    return path.join('/srv/git', name + '.git');
+  },
+}));
+
+app.listen(3000);
+```
+
+Clients can now clone, fetch, and push:
+
+```bash
+git clone http://localhost:3000/repos/myproject
+git push  http://localhost:3000/repos/myproject HEAD:main
+```
+
+---
+
+## Supported endpoints
+
+| Method | Path pattern | Git service | Purpose |
+|---|---|---|---|
+| `GET` | `/info/refs?service=git-upload-pack` | `git-upload-pack` | Capability advertisement (fetch/clone) |
+| `POST` | `/git-upload-pack` | `git-upload-pack` | Pack negotiation and transfer (fetch/clone) |
+| `GET` | `/info/refs?service=git-receive-pack` | `git-receive-pack` | Capability advertisement (push) |
+| `POST` | `/git-receive-pack` | `git-receive-pack` | Pack transfer (push) |
+
+`gitHandler` registers all four endpoints under the mounted prefix.
+
+---
+
+## `gitHandler(options)`
+
+### Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `repository` | `(req) => string \| null \| false` | **required** | Resolve the absolute path to the bare Git repository. Return a falsy value to send `404` |
+| `gitPath` | `string` | `''` | Filesystem path prefix to the `git` binary directory (include trailing `/`) |
+| `strict` | `boolean` | `false` | When `true`, passes `--strict` to `git-upload-pack`; rejects non-bare repositories |
+| `timeout` | `number \| string` | — | Kill `git-upload-pack` after this many **seconds** if it does not finish |
+
+The `repository` callback receives the augmented `RouterRequest`, so `req.params`, `req.cookies`, and any upstream middleware (e.g. auth) are available:
+
+```ts
+gitHandler({
+  repository: async (req) => {
+    // Auth check using upstream middleware result
+    if (!(req as any).user) return null;
+    const name = (req as any).user.repoName;
+    return path.join('/srv/git', name + '.git');
+  },
+})
+```
+
+### Error handling
+
+| Situation | Response |
+|---|---|
+| `repository()` returns falsy | `404 Not Found` |
+| `git` spawn fails (e.g. not installed) | `500 Internal Server Error` |
+| `git` exits with non-zero code | `500 Internal Server Error` |
+| Unrecognised path (not a git endpoint) | Calls `next()` (falls through) |
+
+Client disconnections during streaming (`EPIPE` on stdin) are silently ignored.
+
+### Gzip bodies
+
+`POST` bodies with `Content-Encoding: gzip` are decompressed transparently before being piped to the git process.
+
+---
+
+## `gitCreate(gitDirectory, options?)`
+
+Programmatically initialise a new Git repository:
+
+```ts
+import { gitCreate } from 'expediate';
+
+await gitCreate('/srv/git/myproject.git', {
+  description: 'My project repository',
+});
+```
+
+Runs `git init` (`--bare` by default) and optionally writes a `description` file.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `description` | `string` | — | Contents of the repository's `description` file |
+| `gitPath` | `string` | — | Same as `gitHandler` — directory prefix for the `git` binary |
+| `bare` | `boolean` | `true` | Initialise as a bare repository (no working tree). Pass `false` for a normal repository with a checked-out working tree. |
+
+---
+
+## Access control
+
+`gitHandler` itself does not enforce authentication or authorisation. Wire in upstream middleware before the handler:
+
+```ts
+// Require Bearer token for all git operations
+const requireToken: Middleware = (req, res, next) => {
+  const auth = req.headers.authorization;
+  if (!auth?.startsWith('Bearer ')) return res.status(401).end('Unauthorized');
+  next();
+};
+
+app.use('/repos/:repo', requireToken, gitHandler({ repository: resolveRepo }));
+```
+
+For repository-level read/write separation, inspect `req.path` and `req.method` inside the `repository` callback:
+
+```ts
+gitHandler({
+  repository: (req) => {
+    const name = req.params.repo;
+    const isPush = req.path.endsWith('/git-receive-pack') ||
+                   (req.path.endsWith('/info/refs') && req.query['service'] === 'git-receive-pack');
+    if (isPush && !(req as any).user?.canPush) return null;
+    return path.join('/srv/git', name + '.git');
+  },
+})
+```

package/docs/jwt-auth.md

@@ -0,0 +1,251 @@
+# JWT Authentication
+
+`createJwtPlugin()` returns a self-contained authentication plugin built on Node.js `crypto` — no external JWT library is required.
+
+Features: HMAC / RSA / ECDSA algorithms, refresh token rotation, role and permission guards, pluggable user database, pluggable token store.
+
+---
+
+## Quick start
+
+```ts
+import { createRouter, json, createJwtPlugin, createMapTokenStore } from 'expediate';
+
+const app  = createRouter();
+const auth = createJwtPlugin({
+  accessTokenSecret: process.env.JWT_SECRET!,
+  refreshTokenStore: createMapTokenStore(), // omit to disable refresh tokens entirely
+});
+
+// Auth endpoints (all require the json() body parser)
+app.post('/auth/login',   json(), auth.login);
+app.post('/auth/refresh', json(), auth.refresh);
+app.post('/auth/logout',  json(), auth.logout);
+
+// Protected route
+app.get('/me', auth.authenticate, auth.authorize, (req, res) => {
+  res.json((req as any).user);
+});
+```
+
+Refresh tokens are opt-in: `auth.login` only includes a `refreshToken` in its
+response when `refreshTokenStore` is configured, and `auth.refresh` responds
+`501 Not Implemented` otherwise.
+
+---
+
+## Auth endpoints
+
+### `POST /auth/login`
+
+```json
+// Request
+{ "username": "alice", "password": "password123" }
+
+// Response 200 (refreshToken present only when refreshTokenStore is configured)
+{
+  "accessToken":  "eyJ...",
+  "refreshToken": "eyJ...",
+  "expiresIn":    900,
+  "tokenType":    "Bearer"
+}
+```
+
+### `POST /auth/refresh`
+
+```json
+// Request
+{ "refreshToken": "eyJ..." }
+
+// Response 200 — new token pair (old refresh token is invalidated immediately)
+{ "accessToken": "eyJ...", "refreshToken": "eyJ...", "expiresIn": 900, "tokenType": "Bearer" }
+```
+
+Refresh tokens are **rotated** on every use — the old token is invalidated before the new pair is issued, so a stolen refresh token can only be used once. Responds `501 Not Implemented` if no `refreshTokenStore` was configured.
+
+### `POST /auth/logout`
+
+```json
+// Request
+{ "refreshToken": "b9c2..." }
+
+// Response 200 — refresh token revoked
+{ "message": "Logged out successfully" }
+```
+
+---
+
+## Protecting routes
+
+```ts
+// authenticate — populates req.user; calls next() silently on failure
+// authorize   — rejects with 401 Unauthorized if req.user is not set
+app.get('/profile', auth.authenticate, auth.authorize, handler);
+```
+
+`authenticate` always clears `req.user` at the start of the middleware call to prevent stale data leaking across requests. This split design means you can optionally inspect `req.user` in middleware before requiring it.
+
+`req.user` shape when authenticated:
+
+```ts
+interface TokenPayload {
+  sub:          string;    // user ID
+  username:     string;
+  iss:          string;    // issuer
+  iat:          number;    // issued at (Unix seconds)
+  exp:          number;    // expires at (Unix seconds)
+  roles?:       string[];
+  permissions?: string[];
+}
+```
+
+---
+
+## Role and permission guards
+
+Both helpers return `[authenticate, guard]` — spread them into route registration:
+
+```ts
+// Require at least ONE of the listed roles
+app.delete('/admin/users/:id', ...auth.requireRole('admin'), deleteUser);
+app.get('/reports',           ...auth.requireRole('admin', 'editor'), getReports);
+
+// Require ALL of the listed permissions
+app.put('/posts/:id', ...auth.requirePermission('write', 'publish'), updatePost);
+```
+
+---
+
+## Configuration reference
+
+```ts
+const auth = createJwtPlugin({
+  // ── Secrets (always set in production) ──────────────────────────────────
+  accessTokenSecret:  'change-me',      // shared HMAC secret (HS*)
+  refreshTokenSecret: 'change-me-too',  // shared HMAC secret for refresh JWTs (HS*)
+
+  // For asymmetric algorithms (RS*, ES*), supply PEM keys instead:
+  // accessTokenPrivateKey: readFileSync('private.pem', 'utf8'),
+  // accessTokenPublicKey:  readFileSync('public.pem',  'utf8'),
+  // Optional separate key pair for refresh tokens — falls back to the
+  // access token keys above when omitted:
+  // refreshTokenPrivateKey: readFileSync('refresh-private.pem', 'utf8'),
+  // refreshTokenPublicKey:  readFileSync('refresh-public.pem',  'utf8'),
+
+  // ── Algorithm ───────────────────────────────────────────────────────────
+  alg: 'HS256',  // 'HS256' | 'HS384' | 'HS512'
+                 // 'RS256' | 'RS384' | 'RS512'
+                 // 'ES256' | 'ES384' | 'ES512'
+
+  // ── Expiry ──────────────────────────────────────────────────────────────
+  accessTokenExpiry:  15 * 60,        // 15 minutes (seconds)
+  refreshTokenExpiry: 7 * 24 * 3600,  // 7 days (seconds)
+
+  // ── Claims ──────────────────────────────────────────────────────────────
+  issuer:      'my-app',
+  checkIssuer: true,  // reject tokens with a different iss claim (default: false)
+
+  // ── User database ───────────────────────────────────────────────────────
+  // Replace with a real database query; return null to reject login
+  fetchUser: async (username) => {
+    return await db.users.findOne({ username });
+  },
+
+  // Extracts the subject identifier from a user record (default: user => user.username)
+  username: (user) => user.id,
+
+  // ── Password validation ─────────────────────────────────────────────────
+  // Default uses SHA-256 — replace with bcrypt/argon2 for production
+  isPasswordValid: async (user, password) => {
+    return await bcrypt.compare(password, user.passwordHash);
+  },
+
+  // ── Custom JWT payload ──────────────────────────────────────────────────
+  payload: (user) => ({
+    sub:         user.id,
+    username:    user.username,
+    roles:       user.roles,
+    permissions: user.permissions,
+  }),
+
+  // ── Token store ─────────────────────────────────────────────────────────
+  // Required to enable refresh tokens at all — omit to disable them entirely
+  // (auth.login then omits refreshToken, auth.refresh responds 501).
+  // createMapTokenStore() is a simple in-memory default; replace with a
+  // Redis adapter for multi-instance deployments.
+  refreshTokenStore: redisAdapter,
+});
+```
+
+---
+
+## Token store interface
+
+The store is keyed by JWT ID (`jti`), not by the token string itself — every
+issued refresh token carries a unique `jti` claim, and the store maps that ID
+to a record. Methods may return their result directly or as a `Promise`:
+
+```ts
+interface TokenStore {
+  set(jti: string, record: RefreshTokenRecord): void | Promise<void>;
+  get(jti: string): RefreshTokenRecord | undefined | Promise<RefreshTokenRecord | undefined>;
+  delete(jti: string): void | Promise<void>;
+  deleteBySubject?(sub: string): void | Promise<void>;  // optional — "log out all sessions"
+}
+
+interface RefreshTokenRecord {
+  sub:       string;  // subject the token was issued to
+  issuedAt:  number;  // Unix ms timestamp
+  expiresAt: number;  // Unix ms timestamp
+}
+```
+
+A built-in in-memory store is available for testing:
+
+```ts
+import { createMapTokenStore } from 'expediate';
+
+const auth = createJwtPlugin({
+  accessTokenSecret: 'dev-secret',
+  refreshTokenStore: createMapTokenStore(),
+});
+```
+
+### Refresh token internals
+
+Refresh tokens are signed JWTs, not opaque strings. Their payload carries:
+
+```json
+{ "sub": "alice", "jti": "uuid-v4", "type": "refresh", "iss": "my-app", "iat": 0, "exp": 0 }
+```
+
+The `jti` (a `crypto.randomUUID()` value) is the token store key. Refresh
+tokens are signed with `refreshTokenSecret` (HS*) or `refreshTokenPrivateKey`
+/ `refreshTokenPublicKey` (RS*/ES*, falling back to the access-token PEM keys
+when omitted) — a distinct key from the access token where configured, so an
+access token can never be replayed as a refresh token. On every
+`POST /auth/refresh`, the old `jti` is looked up, deleted, then a fresh pair
+is issued (rotation).
+
+---
+
+## Algorithms
+
+All algorithms are implemented using Node.js `crypto` — no third-party JWT library:
+
+| Algorithm | Key type | Notes |
+|---|---|---|
+| `HS256` / `HS384` / `HS512` | Shared HMAC secret string | Default; `accessTokenSecret` |
+| `RS256` / `RS384` / `RS512` | RSA PEM key pair | `accessTokenPrivateKey` + `accessTokenPublicKey` |
+| `ES256` / `ES384` / `ES512` | ECDSA PEM key pair | DER↔P1363 conversion for standard JWT wire format |
+
+Verification uses `crypto.timingSafeEqual` to prevent timing attacks.
+
+---
+
+## Security notes
+
+- The default password hashing uses SHA-256, which is **not suitable for production**. Always supply an `isPasswordValid` function that uses bcrypt, argon2, or scrypt.
+- Calling `createJwtPlugin()` with no `accessTokenSecret` uses a placeholder secret and should only be done in tests or demos.
+- Refresh tokens are signed JWTs carrying a `jti` claim, not opaque strings — see [Refresh token internals](#refresh-token-internals). Only the `jti` is stored server-side (in the token store), and it's invalidated on each use.
+- Refresh tokens are entirely opt-in: omit `refreshTokenStore` to disable them — `auth.login` then omits `refreshToken` from its response and `auth.refresh` responds `501 Not Implemented`.

package/docs/logo.svg

@@ -0,0 +1,12 @@
+<svg viewBox="15.109859154929579 17.64 214.05633802816902 215.88" xmlns="http://www.w3.org/2000/svg" version="1.2" style="max-height: 500px" width="214.05633802816902" height="215.88">
+	<style>
+		.s0 { fill: #cc5535 } 
+		.s1 { fill: #000000 } 
+	</style>
+	<g id="Layer 1">
+		<path d="m101.62 96.81c4.32 0.2 4.48 9.14 0.08 9.08-3.68-0.05-33.34 0-39.17-0.51-6.21-0.53-6.39-8.5 1.01-8.57 3.98-0.04 35.33-0.12 38.08 0z" class="s0" fill-rule="evenodd" id="Forme 2"/>
+		<path d="m108.62 155.81c4.32 0.2 4.48 9.14 0.08 9.08-3.68-0.05-33.34 0-39.17-0.51-6.21-0.53-6.39-8.5 1.01-8.57 3.98-0.04 35.33-0.12 38.08 0z" class="s0" fill-rule="evenodd" id="Forme 2 copy"/>
+		<path d="m95.51 125.97c7.09 0.01 5.67 9.39-1.02 9.49-3.68 0.06-61.13-0.57-66.96-1.08-6.21-0.53-6.39-8.5 1.01-8.57 3.98-0.04 59.36 0.15 66.97 0.16z" class="s0" fill-rule="evenodd" id="Forme 2 copy 2"/>
+		<path d="m93.66 115.38c4.43 0.06 108.79 0.29 108.79 0.29 0 0 3.82-18.38-22.58-37.88-20.91-15.45-47.18-5.46-53.92-1.06-6.54 4.28-12.49 10.58-15.92 13.03-4.33 3.09-12.62-0.42-10.4-7.19 1.81-5.55 16.67-17.87 27.53-22.38 10.87-4.5 42.59-10.28 68.32 11.9 16.47 14.2 20.24 33.45 21.14 47.51 0.18 2.86-0.38 8.87-6.1 8.92-5.72 0.05-109.37 0.01-109.37 0.01 0 0 0.9 13.13 6.8 21.54 3.9 5.56 15.34 25.02 43.58 24.82 20.03-0.15 30.18-8.42 35.87-13.71 8.28-7.69 15.47 2.14 10.85 7.15-11.11 12.02-29.37 24.43-55.25 19.73-22.41-4.07-34.63-13.89-43.79-27.13-7.5-10.84-10.53-24.82-11.56-35.98-0.65-7.03 1.57-9.63 6.01-9.57z" class="s1" fill-rule="evenodd" id="Forme 1"/>
+	</g>
+</svg>

package/docs/middleware.md

@@ -0,0 +1,264 @@
+# Middleware
+
+Expediate ships a suite of production-ready middleware. All factories return standard `(req, res, next)` functions and can be mounted globally or scoped to specific paths.
+
+---
+
+## `compress()`
+
+Transparent response compression. Must be mounted **before** any middleware that writes response bodies.
+
+Algorithm priority (based on `Accept-Encoding`): Brotli > gzip > deflate.
+
+```ts
+import { compress } from 'expediate';
+
+app.use(compress());
+app.use(compress({ threshold: 512, brotliQuality: 6 }));
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `threshold` | `number` | `1024` | Minimum response size in bytes before compression is applied |
+| `br` | `boolean` | `true` | Enable Brotli compression |
+| `brotliQuality` | `number` | `4` | Brotli quality level (0–11) |
+| `gzipLevel` | `number` | Node default | gzip/deflate compression level (1–9) |
+| `filter` | `(req, res) => boolean` | — | Custom predicate; return `false` to skip compression for a response |
+
+The middleware removes `Content-Length` (size changes after compression) and sets `Content-Encoding` and `Vary: Accept-Encoding`.
+
+---
+
+## `conditionalGet()`
+
+Handles `If-None-Match` and `If-Modified-Since` headers (RFC 7232). When the client's cached response is still fresh, sends `304 Not Modified` with no body instead of the full response.
+
+```ts
+import { conditionalGet } from 'expediate';
+
+app.get('/users/:id', conditionalGet(), (req, res) => {
+  const user = getUser(req.params.id);
+  res.etag(user.updatedAt.toISOString());
+  res.json(user);  // → 304 when the client is up to date
+});
+```
+
+Freshness checks follow RFC 7232 priority: `If-None-Match` (weak comparison, `*` wildcard supported) first, then `If-Modified-Since`. Only GET and HEAD are eligible — other methods pass through unchanged.
+
+A `304` response strips `Content-Type`, `Content-Length`, and `Content-Encoding` but retains `ETag`, `Cache-Control`, `Vary`, and `Last-Modified`.
+
+---
+
+## `cacheControl()`
+
+Sets `Cache-Control`, `Expires`, and `Vary` response headers.
+
+```ts
+import { cacheControl } from 'expediate';
+
+app.use('/api',    cacheControl({ noStore: true }));
+app.use('/assets', cacheControl({ maxAge: 31_536_000, immutable: true }));
+```
+
+| Option | Type | Description |
+|---|---|---|
+| `maxAge` | `number` | `max-age=<seconds>`. Also sets `Expires` |
+| `sMaxAge` | `number` | `s-maxage=<seconds>` for CDN/shared caches |
+| `public` | `boolean` | `public` directive |
+| `private` | `boolean` | `private` directive |
+| `noStore` | `boolean` | `no-store` — disables all caching |
+| `noCache` | `boolean` | `no-cache` — requires revalidation |
+| `mustRevalidate` | `boolean` | `must-revalidate` |
+| `immutable` | `boolean` | `immutable` — response body will never change within `max-age` |
+| `vary` | `string \| string[]` | Sets the `Vary` header |
+
+---
+
+## `requestId()`
+
+Attaches a unique ID to every request and echoes it in the response header.
+
+```ts
+import { requestId } from 'expediate';
+
+app.use(requestId());
+
+app.get('/health', (req, res) => {
+  res.json({ id: req.id, status: 'ok' });
+});
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `header` | `string` | `'x-request-id'` | Header name to read and echo |
+| `allowFromHeader` | `boolean` | `true` | Reuse client-supplied ID. Set `false` to always generate a new one |
+| `generator` | `() => string` | `crypto.randomUUID` | Custom ID generator |
+
+The ID is exposed as `req.id` on the augmented request object.
+
+---
+
+## `rateLimit()`
+
+In-memory sliding-window rate limiting. State is per-process and lost on restart.
+
+```ts
+import { rateLimit } from 'expediate';
+
+// 100 requests per minute per IP (global)
+app.use(rateLimit({ windowMs: 60_000, max: 100 }));
+
+// Tighter limit on authentication endpoints
+app.post('/auth/login', rateLimit({ windowMs: 60_000, max: 5 }), loginHandler);
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `windowMs` | `number` | **required** | Sliding window duration in milliseconds |
+| `max` | `number` | **required** | Max requests per key within the window |
+| `keyBy` | `(req) => string` | `req.ip` | Function to extract the rate-limit key |
+| `message` | `string` | `'Too Many Requests'` | Response body when limit is exceeded |
+| `statusCode` | `number` | `429` | HTTP status when limit is exceeded |
+| `headers` | `boolean` | `true` | Set `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` |
+
+> Not suitable for multi-process deployments without a shared external store.
+
+---
+
+## `csrf()`
+
+CSRF protection via the double-submit cookie pattern. Safe methods (GET, HEAD, OPTIONS, TRACE) are exempted. State-mutating methods must supply the token in the `X-CSRF-Token` header or `_csrf` body field.
+
+```ts
+import { csrf } from 'expediate';
+
+app.use(csrf());
+
+// Expose the token to client-side JavaScript
+app.get('/form', (req, res) =>
+  res.send(`<input type="hidden" name="_csrf" value="${req.csrfToken!()}">`));
+// POST /form — token validated automatically
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `cookieName` | `string` | `'_csrf'` | Cookie storing the token |
+| `headerName` | `string` | `'x-csrf-token'` | Request header carrying the token |
+| `fieldName` | `string` | `'_csrf'` | Parsed body field (fallback when header is absent) |
+| `secure` | `boolean` | `false` | Mark the CSRF cookie as `Secure` |
+| `sameSite` | `'Strict'\|'Lax'\|'None'` | `'Strict'` | `SameSite` attribute of the cookie |
+
+The cookie is **not** `HttpOnly` — client JavaScript must be able to read it to include it in requests.
+
+---
+
+## `securityHeaders()`
+
+Sets a hardened baseline of HTTP security response headers.
+
+```ts
+import { securityHeaders } from 'expediate';
+
+app.use(securityHeaders());
+
+// Disable HSTS for plain-HTTP development servers
+app.use(securityHeaders({ hsts: false }));
+```
+
+| Header | Default value |
+|---|---|
+| `Strict-Transport-Security` | `max-age=15552000; includeSubDomains` |
+| `X-Frame-Options` | `SAMEORIGIN` |
+| `X-Content-Type-Options` | `nosniff` |
+| `Referrer-Policy` | `strict-origin-when-cross-origin` |
+| `Permissions-Policy` | `geolocation=(), microphone=(), camera=()` |
+| `X-XSS-Protection` | `0` |
+
+Pass `false` to disable a header, or a string to override it:
+
+```ts
+app.use(securityHeaders({
+  hsts: false,
+  frameOptions: 'DENY',
+  permissionsPolicy: "geolocation=(self 'https://maps.example.com')",
+}));
+```
+
+---
+
+## `cors()`
+
+Adds Cross-Origin Resource Sharing headers. Headers are only set when the request includes an `Origin` header (browser-only). `OPTIONS` preflight requests are handled and terminated — `next()` is not called for preflights.
+
+```ts
+import { cors } from 'expediate';
+
+app.use(cors({ origin: 'https://example.com' }));
+
+app.use(cors({
+  origin:           ['https://app.example.com', 'https://admin.example.com'],
+  allowCredentials: true,
+  maxAge:           86400,
+}));
+```
+
+When `origin` is an array, the middleware compares the request `Origin` against the list and echoes back only the matching origin (or omits the header entirely if no match) — a plain array can't be passed straight to `Access-Control-Allow-Origin` since the CORS spec only allows a single value. `Vary` is **not** added automatically; if a cache sits in front of an array-origin response, set `vary: 'Origin'` yourself so the cache keys on it.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `origin` | `string \| string[]` | `'*'` | Allowed origin(s). Array triggers request-origin matching |
+| `allowHeaders` | `string \| string[]` | `'Accept, Content-Type, Authorization'` | `Access-Control-Allow-Headers` value |
+| `allowMethods` | `string \| string[]` | `'GET,HEAD,PUT,PATCH,POST,DELETE'` | `Access-Control-Allow-Methods` value |
+| `allowCredentials` | `boolean` | — | Set `Access-Control-Allow-Credentials: true` |
+| `maxAge` | `number` | — | Preflight cache lifetime in seconds |
+| `vary` | `string \| string[]` | — | Additional `Vary` header value |
+| `optionsStatus` | `number` | `204` | Status code for OPTIONS preflight responses |
+| `preflight` | `(req) => boolean` | — | Custom guard; return `false` to reject (OPTIONS → 403, others → 400) |
+
+---
+
+## `logger()`
+
+Logs one line per completed request. Integrated with the request lifecycle — the timer starts when the request arrives and fires when the response finishes.
+
+```ts
+import { logger } from 'expediate';
+
+app.use(logger({
+  user:   (req) => (req as any).user?.username ?? '-',
+  locale: 'en-US',
+  logger: (msg) => process.stderr.write(msg + '\n'),
+}));
+```
+
+Default output format (ANSI-coloured by status class):
+
+```
+21 Mar, 14:32  200  GET  /api/users  127.0.0.1  alice  4 ms  (1234)
+```
+
+With `json: true`, the logger calls the `logger` function with a structured object instead of a string:
+
+```ts
+{
+  timestamp: '2024-03-21T14:32:00.000Z',
+  status:    200,
+  method:    'GET',
+  path:      '/api/users',
+  ip:        '127.0.0.1',
+  user:      'alice',
+  elapsed:   4,
+  host:      'localhost:3000',
+  length:    256,
+}
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `track` | `boolean` | `false` | Emit a `LOST` warning for requests that never complete |
+| `trackTimeout` | `number` | `30000` | Milliseconds before emitting the LOST warning |
+| `user` | `(req) => string` | `() => '-'` | Extract a user identity from the request |
+| `locale` | `string` | `'en-GB'` | BCP 47 locale for the timestamp |
+| `dateFormat` | `Intl.DateTimeFormatOptions` | short date+time | Timestamp format options |
+| `json` | `boolean` | `false` | Log structured objects instead of formatted strings |
+| `logger` | `(msg: string \| object) => void` | `console.log` | Custom logging sink |