u

docs/api/README.md

@@ -32,6 +32,8 @@ Generated from `@openapi` annotations in [`src/api/routes/`](../../src/api/route
 
 | File | Endpoint |
 |------|----------|
+| [`routes/.well-known/oauth-authorization-server.md`](routes/.well-known/oauth-authorization-server.md) | `GET /.well-known/oauth-authorization-server` |
+| [`routes/.well-known/oauth-protected-resource.md`](routes/.well-known/oauth-protected-resource.md) | `GET /.well-known/oauth-protected-resource` |
 | [`routes/account.get.md`](routes/account.get.md) | `GET /account` |
 | [`routes/account.post.md`](routes/account.post.md) | `POST /account` |
 | [`routes/account/_id.md`](routes/account/_id.md) | `DELETE /account/{id}` |
@@ -155,6 +157,7 @@ Generated from `@openapi` annotations in [`src/api/routes/`](../../src/api/route
 | [`routes/ledger.post.md`](routes/ledger.post.md) | `POST /ledger` |
 | [`routes/ledger/manifestarticle/_manifestarticleId.md`](routes/ledger/manifestarticle/_manifestarticleId.md) | `GET /ledger/manifestarticle/{manifestarticleId}` |
 | [`routes/ledger/sku/_sku.md`](routes/ledger/sku/_sku.md) | `GET /ledger/sku/{sku}` |
+| [`routes/mcp.md`](routes/mcp.md) | `POST /mcp` |
 | [`routes/modelconversation.get.md`](routes/modelconversation.get.md) | `GET /modelconversation` |
 | [`routes/modelconversation.post.md`](routes/modelconversation.post.md) | `POST /modelconversation` |
 | [`routes/modelconversation/_id.delete.md`](routes/modelconversation/_id.delete.md) | `DELETE /modelconversation/{id}` |
@@ -164,6 +167,10 @@ Generated from `@openapi` annotations in [`src/api/routes/`](../../src/api/route
 | [`routes/modelconversation/_id/stream.md`](routes/modelconversation/_id/stream.md) | `GET /modelconversation/{id}/stream` |
 | [`routes/number/list.md`](routes/number/list.md) | `GET /number` |
 | [`routes/number/update.md`](routes/number/update.md) | `PATCH /number/{id}` |
+| [`routes/oauth/authorize.md`](routes/oauth/authorize.md) | `GET /oauth/authorize` |
+| [`routes/oauth/introspect.md`](routes/oauth/introspect.md) | `POST /oauth/introspect` |
+| [`routes/oauth/register.md`](routes/oauth/register.md) | `POST /oauth/register` |
+| [`routes/oauth/token.md`](routes/oauth/token.md) | `POST /oauth/token` |
 | [`routes/order/list.md`](routes/order/list.md) | `GET /order` |
 | [`routes/order/create.md`](routes/order/create.md) | `POST /order` |
 | [`routes/order/delete.md`](routes/order/delete.md) | `DELETE /order/{id}` |

docs/api/routes-all.md

@@ -1,6 +1,6 @@
 # Dash API Routes Overview (All)
 
-Overview of all 216 API endpoints across all modules.
+Overview of all 223 API endpoints across all modules.
 
 ### Notation
 
@@ -63,6 +63,15 @@ Params: path values first, then `query:` and `body:` (`body?` = optional body).
 ### Routes
 
 
+### Section: /.well-known
+
+#### OAuth 2.0 Authorization Server Metadata (RFC 8414) — `GET /.well-known/oauth-authorization-server`
+_none_
+- Returns: `200`
+#### OAuth 2.0 Protected Resource Metadata (RFC 9728) — `GET /.well-known/oauth-protected-resource`
+_none_
+- Returns: `200`
+
 ### Section: /account
 
 #### List accounts — `GET /account`
@@ -505,6 +514,12 @@ _none_
 - Params: `sku: str, query: transaction_type?: str`
 - Returns: `200 T16`
 
+### Section: /mcp
+
+#### Model Context Protocol (MCP) Streamable HTTP endpoint — `POST /mcp`
+_none_
+- Returns: `200`
+
 ### Section: /modelconversation
 
 #### List conversations — `GET /modelconversation`
@@ -538,6 +553,21 @@ _none_
 - Params: `id: int, body: { prefix?: str, padding?: int, next?: int }`
 - Returns: `200 { number: { id: int, type: str, prefix: str, padding: int, next: int } }`
 
+### Section: /oauth
+
+#### OAuth 2.1 Authorization Endpoint (RFC 6749 & RFC 7636) — `GET /oauth/authorize`
+- Params: `query: client_id: str, redirect_uri: str, response_type: str, code_challenge: str, code_challenge_method: str, state?: str`
+- Returns: `200`
+#### OAuth 2.0 Token Introspection (RFC 7662) — `POST /oauth/introspect`
+_none_
+- Returns: `200`
+#### Dynamic Client Registration (RFC 7591) — `POST /oauth/register`
+- Params: `body: { redirect_uris: str[], client_name?: str }`
+- Returns: `201`
+#### OAuth 2.1 Token Endpoint (RFC 6749 & RFC 7636) — `POST /oauth/token`
+- Params: `application/x-www-form-urlencoded`
+- Returns: `200`
+
 ### Section: /order
 
 #### List orders — `GET /order`

docs/api/routes.md

@@ -1,6 +1,6 @@
 # Dash API Routes Overview
 
-Overview of all 169 API endpoints across all modules.
+Overview of all 176 API endpoints across all modules.
 
 ### Notation
 
@@ -58,6 +58,15 @@ Params: path values first, then `query:` and `body:` (`body?` = optional body).
 ### Routes
 
 
+### Section: /.well-known
+
+#### OAuth 2.0 Authorization Server Metadata (RFC 8414) — `GET /.well-known/oauth-authorization-server`
+_none_
+- Returns: `200`
+#### OAuth 2.0 Protected Resource Metadata (RFC 9728) — `GET /.well-known/oauth-protected-resource`
+_none_
+- Returns: `200`
+
 ### Section: /account
 
 #### List accounts — `GET /account`
@@ -430,6 +439,12 @@ _none_
 - Params: `sku: str, query: transaction_type?: str`
 - Returns: `200 T15`
 
+### Section: /mcp
+
+#### Model Context Protocol (MCP) Streamable HTTP endpoint — `POST /mcp`
+_none_
+- Returns: `200`
+
 ### Section: /number
 
 #### List number sequences — `GET /number`
@@ -439,6 +454,21 @@ _none_
 - Params: `id: int, body: { prefix?: str, padding?: int, next?: int }`
 - Returns: `200 { number: { id: int, type: str, prefix: str, padding: int, next: int } }`
 
+### Section: /oauth
+
+#### OAuth 2.1 Authorization Endpoint (RFC 6749 & RFC 7636) — `GET /oauth/authorize`
+- Params: `query: client_id: str, redirect_uri: str, response_type: str, code_challenge: str, code_challenge_method: str, state?: str`
+- Returns: `200`
+#### OAuth 2.0 Token Introspection (RFC 7662) — `POST /oauth/introspect`
+_none_
+- Returns: `200`
+#### Dynamic Client Registration (RFC 7591) — `POST /oauth/register`
+- Params: `body: { redirect_uris: str[], client_name?: str }`
+- Returns: `201`
+#### OAuth 2.1 Token Endpoint (RFC 6749 & RFC 7636) — `POST /oauth/token`
+- Params: `application/x-www-form-urlencoded`
+- Returns: `200`
+
 ### Section: /order
 
 #### List orders — `GET /order`

docs/api/routes/.well-known/oauth-authorization-server.md

@@ -0,0 +1,15 @@
+# `GET /.well-known/oauth-authorization-server`
+
+Public. No cookie required.
+
+OAuth 2.0 Authorization Server Metadata (RFC 8414)
+
+Returns OAuth 2.0 authorization server endpoints and capabilities.
+
+## Response `200`
+
+Authorization Server Metadata
+
+---
+
+_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._

docs/api/routes/.well-known/oauth-protected-resource.md

@@ -0,0 +1,15 @@
+# `GET /.well-known/oauth-protected-resource`
+
+Public. No cookie required.
+
+OAuth 2.0 Protected Resource Metadata (RFC 9728)
+
+Returns protected resource metadata discovering the authorization server for the MCP endpoint.
+
+## Response `200`
+
+Protected Resource Metadata
+
+---
+
+_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._

docs/api/routes/mcp.md

@@ -0,0 +1,21 @@
+# `POST /mcp`
+
+Protected. Requires a valid session cookie (`credentials: 'include'`).
+
+Model Context Protocol (MCP) Streamable HTTP endpoint
+
+Handles MCP JSON-RPC protocol requests and streamable sessions. Protected by Bearer token authorization.
+
+## Response `200`
+
+MCP JSON-RPC response
+
+## Errors
+
+| Status | Description |
+|--------|-------------|
+| 401 | Missing or invalid authorization token |
+
+---
+
+_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._

docs/api/routes/oauth/authorize.md

@@ -0,0 +1,32 @@
+# `GET /oauth/authorize`
+
+Public. No cookie required.
+
+OAuth 2.1 Authorization Endpoint (RFC 6749 & RFC 7636)
+
+Authorization prompt for end-users to grant access to an MCP client.
+
+## Query parameters
+
+| Param | Required | Type | Description |
+|-------|----------|------|-------------|
+| `client_id` | yes | string |  |
+| `redirect_uri` | yes | string |  |
+| `response_type` | yes | string |  |
+| `code_challenge` | yes | string |  |
+| `code_challenge_method` | yes | string |  |
+| `state` | no | string |  |
+
+## Response `200`
+
+Authorization / Consent HTML form
+
+## Errors
+
+| Status | Description |
+|--------|-------------|
+| 302 | Redirect back to client callback |
+
+---
+
+_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._

docs/api/routes/oauth/introspect.md

@@ -0,0 +1,15 @@
+# `POST /oauth/introspect`
+
+Public. No cookie required.
+
+OAuth 2.0 Token Introspection (RFC 7662)
+
+Verifies the validity of an issued access token.
+
+## Response `200`
+
+Token status and metadata
+
+---
+
+_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._

docs/api/routes/oauth/register.md

@@ -0,0 +1,31 @@
+# `POST /oauth/register`
+
+Public. No cookie required.
+
+Dynamic Client Registration (RFC 7591)
+
+Registers a new OAuth MCP client dynamically.
+
+## Body (JSON)
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `client_name` | no | string |  |
+| `redirect_uris` | yes | string[] |  |
+
+```json
+{
+  "client_name": "…",
+  "redirect_uris": [
+    "…"
+  ]
+}
+```
+
+## Response `201`
+
+Registered client credentials
+
+---
+
+_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._

docs/api/routes/oauth/token.md

@@ -0,0 +1,30 @@
+# `POST /oauth/token`
+
+Public. No cookie required.
+
+OAuth 2.1 Token Endpoint (RFC 6749 & RFC 7636)
+
+Exchanges authorization code with PKCE for an access token, or refreshes an expired token.
+
+## Body
+
+`application/x-www-form-urlencoded`
+
+```json
+{
+  "grant_type": "authorization_code",
+  "code": "…",
+  "redirect_uri": "…",
+  "client_id": "…",
+  "code_verifier": "…",
+  "refresh_token": "…"
+}
+```
+
+## Response `200`
+
+Issued access token and refresh token
+
+---
+
+_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._