solpbc.org
open-source, lexicon-agnostic PDS for AI agents. welcome-mat enrollment, AT Proto federation.
agents
atprotocol
pds
cloudflare
docs: add security + XRPC API + verify-before-claim principles to agent guide
rookery is an identity provider (auth/DPoP/DID resolution) but the agent guide
only carried generic 'fail fast'. Inlines the security, API-design, and
verify-before-claim principles a hopper lode needs (it can't read the private
org standards), plus the operator-driven/no-CI note. (CIO AGENTS.md audit.)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
author
Jer Miller
co-author
Claude Opus 4.8 (1M context)
date
(Jun 22, 2026, 9:36 PM -0600)
commit
70194ae6
70194ae66e2ba89831eaededa1a790d6aed15419
parent
94709218
94709218726ee7f7ae8df56321de8dad88cc8d88
+25
-3
+25
-3
CLAUDE.md
+25
-3
CLAUDE.md
···
27
27
28
28
## Development Principles
29
29
30
-
- **Simple code** - Prefer plain functions. Keep modules self-contained.
31
-
- **DRY, KISS** - Extract common logic, prefer simple solutions.
32
-
- **Fail fast** - Validate inputs and external state early. Clear error messages.
30
+
sol pbc's coding standards, distilled. They live inline here because a coding
31
+
agent working in this repo can't read the private org engineering standards —
32
+
this section is the source of truth a lode sees.
33
+
34
+
- **Simple code.** Prefer plain functions. Keep modules self-contained. KISS/YAGNI — don't add abstraction, config, or fallbacks for cases that don't exist today. No backwards-compatibility shims; update call sites directly.
35
+
- **DRY.** Extract common logic; reference the source of truth instead of duplicating it.
36
+
- **Fail fast, fail clearly, never silently.** Validate inputs and external state at the boundary; raise/return clear, specific errors. Don't swallow an exception and return a success-looking result on a degraded path — a silent failure in an auth/repo layer is an invisible outage.
37
+
- **Verify before you claim.** Recall is a hypothesis, not evidence. Any claim about atproto/XRPC behavior, a lexicon shape, DPoP/JWT semantics, or a Cloudflare runtime API gets verified against the live source before it lands in code — and contract tests round-trip the real serialization boundary, not a mock of both sides.
38
+
39
+
## Security — this is an identity provider; treat it accordingly
40
+
41
+
rookery hands AI agents their own atproto identity and data repository. Auth,
42
+
DID/handle resolution, and DPoP are the trust boundary.
43
+
44
+
- **Validate and sanitize all external input.** Every XRPC request body, header, DPoP proof, and lexicon record arrives from outside the trust boundary — assume it's hostile and validate it. Don't reason on a malformed record as if it were valid.
45
+
- **Identity is resolved at the boundary, never client-supplied.** Derive the actor from the authenticated DPoP/WelcomeMat credential, not from an id named in the request body or path. Treat any account/DID in the URL as an assertion to check against the authenticated record, not as input.
46
+
- **Never expose secrets.** Signing keys, tokens, and credentials come from Worker secrets (`wrangler secret put`) / env bindings — never in source, never in a commit, never in a log line, an error message, or a response body.
47
+
- **Privacy is architecture.** Per-agent data isolation is a structural choice (the Account Durable Object boundary), not a feature. No analytics, no behavioral tracking — Article 8 covenant.
48
+
49
+
## XRPC / HTTP API design
50
+
51
+
- **Status is the success signal; the body is the resource.** Don't add a `{"success": true}` flag that duplicates the status. Collections return an envelope (`{records, cursor}`), never a bare top-level array.
52
+
- **One error envelope with a machine-readable code**, the HTTP status carried by a central registry — not a status literal sprinkled at each call site, never raw exception text in the body.
53
+
- **Bounded reads.** A list/repo endpoint never returns an unbounded collection — one shared pagination primitive (cursor or offset/limit with a hard max); a missing clamp is a denial-of-service vector.
33
54
34
55
## Verification
35
56
36
57
- Always run `npm test` before committing — all tests must pass.
58
+
- **No GitHub CI/CD — operator-driven only.** Every `wrangler deploy` is run by an authenticated operator from a local machine; credentials never live in GitHub Actions. Don't add a `.github/workflows/` deploy or test job.
37
59
38
60
## File Headers
39
61