# Security Policy

Usher is a single-tenant **OpenID Provider** (OP): it authenticates humans and
issues signed OIDC/OAuth 2.0 tokens that relying-party applications trust. It is
security-critical by nature, and this document defines what we consider a
security bug, what we consider the integrator's responsibility, and how to
report an issue privately.

The full design rationale and threat model live in
[`docs/design.md`](docs/design.md) (see §11, the security checklist). This file
is the short, authoritative statement of scope and process.

## Status

Usher is **early MVP (0.x)**. It has not yet completed OpenID Foundation
conformance testing or an independent security audit. Treat pre-1.0 releases as
**not production-hardened**: pin a version, read the design doc, and review the
configuration guidance below before relying on it to protect real accounts.

## Supported versions

Only the latest `0.x` release on `main` receives security fixes. There are no
long-term-support branches during the 0.x series.

| Version        | Supported          |
| -------------- | ------------------ |
| latest `0.x`   | :white_check_mark: |
| older `0.x`    | :x:                |

## Reporting a vulnerability

**Please do not open a public GitHub issue for a suspected vulnerability.**

Report privately to **green@moxielogic.com**. If your platform supports it, you
may also use GitHub's [private vulnerability
reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability)
("Report a vulnerability" under the repository's **Security** tab).

Please include:

- The affected version / commit and the backend in use (memory, SQLite, Postgres).
- A description of the flaw and its security impact.
- A minimal proof of concept — the request(s), token(s), or configuration that
  trigger it — and the observed vs. expected behaviour.

What to expect:

- **Acknowledgement** within a few business days.
- A short assessment of severity and scope, and an expected fix timeline.
- Credit in the release notes / advisory if you'd like it (let us know how you
  wish to be named).

Because Usher is a small, single-maintainer MVP, timelines are best-effort
rather than contractual. Please allow a reasonable coordinated-disclosure window
before publishing details.

## In scope

Defects in Usher's own code that weaken authentication or token security are in
scope. In particular:

- **Token issuance & verification** — JWT signing/validation flaws, `alg=none`
  or HS/RS algorithm-confusion bypasses, `kid` handling, missing or incorrect
  `iss` / `aud` / `exp` / `iat` / `nonce` / `auth_time` checks, JWKS exposure of
  private material.
- **Authorization-code flow & PKCE** — code replay, PKCE downgrade or bypass,
  validating the client/PKCE *after* consuming the code, authorization-code
  injection.
- **`redirect_uri` handling** — anything that defeats exact-match allow-listing
  (wildcard acceptance, normalization/parsing mismatches, open redirect).
- **Refresh-token rotation** — failure to detect reuse, missing family
  revocation, non-atomic rotation, cross-client or cross-family token
  acceptance.
- **Password handling** — Argon2 misuse, non-constant-time verification, user
  enumeration via timing or differential responses, missing dummy-hash on miss.
- **TOTP / two-factor & recovery codes** — second-factor bypass, replay of a
  used TOTP or backup code, weak/predictable secret or code generation.
- **Email verification & password reset** — token predictability, missing
  single-use/expiry enforcement, reset-token leakage, account takeover via the
  reset flow.
- **Social login / identity brokering** — mislinking a local account to the
  wrong upstream identity, trusting an unverified upstream email, state/CSRF
  gaps in the `/social/*` callback.
- **Session & CSRF** — missing/weak cookie flags where Usher controls them,
  absent session rotation on authentication, CSRF on state-changing forms.
- **Rate-limiting / lockout bypass** that removes the brute-force and
  Argon2-CPU/memory bounds.
- **Injection** into the store layer (SQL) or into server-rendered auth pages
  (XSS/header injection) reachable from request-controlled input.
- **Secrets at rest** — signing keys or credentials persisted unencrypted or
  logged in cleartext by Usher itself.

## Out of scope (integrator / operator responsibility)

Usher is a **library and a single process**, not a managed platform. The
following are the deploying application's responsibility, and reports limited to
them will be treated as hardening notes rather than vulnerabilities:

- **Deployment configuration.** Running the `:tls '(:mode :none)` plain-HTTP
  mode, or a non-HTTPS `:issuer`, outside local development. These are
  documented development conveniences; production requires TLS and an HTTPS
  issuer (see README and `docs/design.md` §8.1). The `:none` TLS mode and the
  in-memory store are **development/test only** by design.
- **The in-memory store.** It is non-persistent and unsynchronized; it exists
  for dev/tests. Data-durability or concurrency issues in it are not security
  bugs.
- **Host-application security.** When Usher is embedded, the correctness of the
  host app's routing, TLS termination, reverse proxy, header forwarding, and
  overall configuration is the host's responsibility. Usher trusts the process
  and host it runs in.
- **Secret management.** Protection of the master key used to encrypt signing
  keys at rest, database credentials, social-login client secrets, and any
  pepper is an operational concern. Committing such secrets to your own repo or
  passing them insecurely is out of scope for Usher.
- **Client / relying-party misuse.** Correct verification of Usher-issued tokens
  by RPs, and correct registration of `redirect_uri`s, are the RP's
  responsibility. Usher assumes statically configured clients are trusted.
- **Local / same-host attackers** who already have shell, REPL, or deploy access
  to the Usher process, and anything reachable only via the administrative
  REPL/CLI (administration is intentionally not a network-exposed console).
- **Third-party dependency vulnerabilities.** CVEs in `ironclad`, `jose`,
  `pure-tls`, `postmodern`, Hunchentoot, etc. should be reported upstream; we
  will bump affected pins, but the flaw is not in Usher. (Report to us if Usher
  *uses* a dependency in an unsafe way.)
- **Volumetric / network-layer denial of service** and other pure-infrastructure
  concerns. Note: an *input-driven* algorithmic blowup reachable from a single
  request (unbounded allocation, catastrophic backtracking) **is** in scope.
- **Findings only in test code, fixtures, benchmarks, or documentation examples**
  that are not reachable in a running deployment.

## Coordinated disclosure

Please keep vulnerability details private until a fix is released and, where the
issue is exploitable against deployed instances, until integrators have had a
reasonable window to upgrade. We're happy to coordinate timing and public
messaging with you.

Thank you for helping keep Usher and the people who rely on it safe.