d-OAuth-Server/docs

Documentation

Everything an operator, an integrator, a resource-server team, and a contributor needs, one guide per subject. The project README is the short version: it states what the server is and links here.

Purpose

This index tells you which guide answers your question and in which order to read them. Each guide is self-contained on its subject and authoritative for it; where two touch, the guide that owns the behavior wins and the other links to it.

Start here

• Run it locally. QUICKSTART.md takes a checkout to a server on https://localhost:8080, an administrator, and a token. Then CONFIGURATION.md for the keys and OPERATIONS.md for the command surface.
• Deploy it. DEPLOYMENT.md covers the image, the cluster contract, the reverse proxy, and supply-chain verification; RUNBOOK.md is the on-call procedure for the admin bootstrap and for a full-database disclosure.
• Integrate a client. OAUTH.md for endpoints, grants, PKCE, error codes, metadata, and CIMD; QUICKSTART.md for the end-to-end authorization-code walkthrough; OPERATIONS.md for MCP client registration and DCR access tokens.
• Build a resource server. RS-CONTRACT.md is written so an independent resource-server team can implement discovery, the challenge, token enforcement, and caching from that document alone.
• Change the code. ARCHITECTURE.md for the module map and request lifecycle, then CONTRIBUTING.md for the gates, DATABASE.md and REDIS.md for the two stores, SECURITY.md for the invariants, and TEST-COVERAGE.md for the measured baseline.

Guide index

Guide	Read it when you are...	It answers
QUICKSTART.md	running it for the first time	what do I type to get a server and a token?
CONFIGURATION.md	building an environment	what is this key, its default, and its validation rule?
OPERATIONS.md	administering a live install	which command, with which flags, in which order?
RUNBOOK.md	on call	how do I bootstrap and replace an admin, or respond to a database disclosure?
DEPLOYMENT.md	shipping to a cluster	what does the image contain and what does the runtime require?
ARCHITECTURE.md	reading the source	where does this live, and what happens per request?
OAUTH.md	integrating a client	which endpoint, grant, scope, error code, and metadata field?
RS-CONTRACT.md	protecting an API	how does an RFC 9728 resource server validate a token?
SECURITY.md	reviewing or auditing	what is the threat model and which properties are enforced?
DATABASE.md	changing a table or query	what is the schema, the migration lifecycle, and how is PII stored?
REDIS.md	changing ephemeral state	which key namespace, TTL, and durability rule applies?
CONTRIBUTING.md	opening a change	build, gates, coverage, fuzzing, conventions, doc contract
TEST-COVERAGE.md	judging test evidence	what is the measured coverage and how do I reproduce it?
CHANGELOG.md	checking a release	what changed, and does it break my client?
../SECURITY.md	reporting a vulnerability	where do I send it, and what is the disclosure policy?
../AGENTS.md	briefing an AI agent or a new maintainer	the module map and the repository rules

Conventions

Every guide follows the same shape, so you can jump to the part you need: a ## Purpose paragraph, the body, ## Edge cases, ## Operational runbook, and ## File and directory references.

Documentation is part of a change, not a follow-up. The rules that bind a code change to a guide live in CONTRIBUTING.md, and the repository rules live in ../AGENTS.md. Relative links are validated by CI, so run the same check before opening a change:

python3 scripts/check_doc_links.py

File and directory references

• ../README.md for the short project landing page.
• docs/ for the guides above; this file is its index.
• scripts/check_doc_links.py for the link check CI runs.
• ../AGENTS.md for the module map and the documentation contract summarized above.