Problem
Three published statements about the API contradict the code. Each was found by measurement, and each misleads a reader who acts on it.
1. The auth page contradicts itself about private documents. docs/api/authentication.md:23 says the service-role key "passes every document, public and private. It is not scoped, and it cannot be narrowed", and :37 repeats it. Then :73 says the key "does not open a private document" by slug.
Both are true of different routes, and the page never says so. The metadata route gates privacy; the content route does not gate it at all. A reader who trusts line 23 builds an automation that resolves a private document by slug, and it fails.
2. API.md:67 is wrong about media. It lists media-upload guards among the handlers that return an ad-hoc { "error": "..." } shape. Measured: POST /api/plugins/hypermultimedia/abc returns {"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED"}}, which is the house envelope.
3. The rate limit has four values and no two agree.
| Source |
Value |
apps/hocuspocus.server/src/config/env.schema.ts:76 |
100 |
apps/hocuspocus.server/API.md:1135 |
100 |
| Production, measured |
500 |
| Local, measured |
1000 |
What to do
Correct all three. Documentation only.
For the auth page, state the rule per route rather than as one sentence about the key.
For the rate limit, API.md states the production value. #166 already asks for this as part of its own acceptance, so land it here if #166 stays open.
Acceptance
Notes
docs/api/authentication.md is tracked and reader-facing, so item 1 is the one an outside reader hits first.
A session hook currently rejects edits to apps/hocuspocus.server/API.md, which blocks items 2 and 3 but not item 1.
Problem
Three published statements about the API contradict the code. Each was found by measurement, and each misleads a reader who acts on it.
1. The auth page contradicts itself about private documents.
docs/api/authentication.md:23says the service-role key "passes every document, public and private. It is not scoped, and it cannot be narrowed", and:37repeats it. Then:73says the key "does not open a private document" by slug.Both are true of different routes, and the page never says so. The metadata route gates privacy; the content route does not gate it at all. A reader who trusts line 23 builds an automation that resolves a private document by slug, and it fails.
2.
API.md:67is wrong about media. It lists media-upload guards among the handlers that return an ad-hoc{ "error": "..." }shape. Measured:POST /api/plugins/hypermultimedia/abcreturns{"success":false,"error":{"message":"Authentication required","code":"UNAUTHORIZED"}}, which is the house envelope.3. The rate limit has four values and no two agree.
apps/hocuspocus.server/src/config/env.schema.ts:76apps/hocuspocus.server/API.md:1135What to do
Correct all three. Documentation only.
For the auth page, state the rule per route rather than as one sentence about the key.
For the rate limit,
API.mdstates the production value. #166 already asks for this as part of its own acceptance, so land it here if #166 stays open.Acceptance
docs/api/authentication.mdstates one rule, and names the routes each half applies to.API.md:67no longer lists media-upload guards among the ad-hoc shapes.API.mdstates the production rate limit.Notes
docs/api/authentication.mdis tracked and reader-facing, so item 1 is the one an outside reader hits first.A session hook currently rejects edits to
apps/hocuspocus.server/API.md, which blocks items 2 and 3 but not item 1.