fix and clarify previous doc files

README.md

···
 
 ## Documentation
 
-- [Architecture](./docs/ARCHITECTURE.md) - Complete server architecture
-- [Client Implementation](./docs/CLIENT_IMPLEMENTATION.md) - Client library guide
-- API Reference - Coming soon
-- Encryption Protocol - Coming soon
-- Security Best Practices - Coming soon
+### Getting Started
+- [Client README](./packages/client/README.md) - Quick start for using the client library
+- [Server README](./packages/server/README.md) - Server deployment guide
+
+### Technical Documentation
+- [Encryption Protocol](./docs/ENCRYPTION_PROTOCOL.md) - End-to-end encryption protocol specification
+- [API Reference](./docs/API_REFERENCE.md) - Complete API endpoint reference
+- [Architecture](./docs/ARCHITECTURE.md) - Server-side architecture and design
+- [Security Best Practices](./docs/SECURITY.md) - Security guidelines and threat model
+
+### Implementation
+- [Client Implementation Strategy](./docs/CLIENT_IMPLEMENTATION.md) - Client library design decisions
 
 ## Requirements
 

docs/ARCHITECTURE.md

···
 # ATP Keyserver Architecture
 
+## Documentation Guide
+
+This document focuses on **server-side architecture**. For other topics:
+
+- **End-to-end encryption protocol**: See [ENCRYPTION_PROTOCOL.md](./ENCRYPTION_PROTOCOL.md)
+- **Security best practices**: See [SECURITY.md](./SECURITY.md)
+- **Complete API reference**: See [API_REFERENCE.md](./API_REFERENCE.md)
+- **Client library usage**: See [Client README](../packages/client/README.md)
+- **Implementation strategy**: See [CLIENT_IMPLEMENTATION.md](./CLIENT_IMPLEMENTATION.md)
+
+
 ## Overview
 
 A specialized AT Protocol (ATProto) service for secure storage and distribution of cryptographic keys. This keyserver manages both asymmetric keypairs (Ed25519) for public key cryptography and symmetric keys (XChaCha20-Poly1305) for group-based encrypted communication.
 
+**Key principle:** The server manages keys but never performs encryption/decryption. All cryptographic operations happen client-side for true end-to-end encryption.
+
+
 ## Technology Stack
 
 ### Runtime & Core
···
 - `@noble/ed25519` - Ed25519 asymmetric key operations
 - `@noble/ciphers` - XChaCha20-Poly1305 symmetric encryption
 
+
 ## Architecture Components
 
 ### 1. Entry Point (`main.ts`)
···
 
 ### 2. Database Layer (`lib/db.ts`)
 
-SQLite database with three normalized tables:
+SQLite database with four tables supporting key versioning and access logging:
 
 ```sql
+-- Asymmetric keypairs (Ed25519)
 keys
-├── did (PRIMARY KEY)
-├── public_key (TEXT)
-└── private_key (TEXT)
+├── did (TEXT, NOT NULL)
+├── version (INTEGER, NOT NULL, DEFAULT 1)
+├── public_key (TEXT, NOT NULL)
+├── private_key (TEXT, NOT NULL)
+├── created_at (TEXT, NOT NULL)
+├── revoked_at (TEXT, nullable)
+├── status (TEXT, NOT NULL, DEFAULT 'active')
+├── status_comment (TEXT, nullable)
+└── PRIMARY KEY (did, version)
+    INDEX idx_keys_did_status ON (did, status)
 
+-- Symmetric group keys (XChaCha20-Poly1305)
 groups
-├── id (PRIMARY KEY)
-├── owner_did (TEXT)
-└── secret_key (TEXT)
+├── id (TEXT, NOT NULL)
+├── version (INTEGER, NOT NULL, DEFAULT 1)
+├── owner_did (TEXT, NOT NULL)
+├── secret_key (TEXT, NOT NULL)
+├── created_at (TEXT, NOT NULL)
+├── revoked_at (TEXT, nullable)
+├── status (TEXT, NOT NULL, DEFAULT 'active')
+├── status_comment (TEXT, nullable)
+└── PRIMARY KEY (id, version)
+    INDEX idx_groups_id_status ON (id, status)
 
+-- Group membership
 group_members
-├── group_id (FOREIGN KEY → groups.id)
-└── member_did (TEXT)
-```
+├── group_id (TEXT, NOT NULL)
+├── member_did (TEXT, NOT NULL)
+└── PRIMARY KEY (group_id, member_did)
+    FOREIGN KEY (group_id) REFERENCES groups(id)
 
-**Features:**
-- WAL (Write-Ahead Logging) mode enabled for better concurrency
-- Type-safe schema definitions using TypeScript
-- Single database file (`keyserver.db`)
-- Exported DBSchema type for type-safe queries throughout the application
+-- Key access audit log
+key_access_log
+├── id (INTEGER, PRIMARY KEY AUTOINCREMENT)
+├── did (TEXT, NOT NULL)
+├── version (INTEGER, NOT NULL)
+├── accessed_at (TEXT, NOT NULL)
+├── ip (TEXT, nullable)
+└── user_agent (TEXT, nullable)
+```
 
 ### 3. Authentication Middleware (`lib/authMiddleware.ts`)
 
···
 - `checkMembership(group_id, member_did)` - Verify member status
 - `createGroup(group_id, owner_did)` - Create new group with secret key
 
+
 ## API Endpoints
 
+The keyserver exposes the following endpoint categories:
+
 ### Public Endpoints (No Authentication)
+- `GET /` - Service metadata
+- `GET /.well-known/did.json` - Service DID document
+- `GET /xrpc/dev.atpkeyserver.alpha.key.public` - Get any user's public key
 
-#### `GET /`
-Returns service metadata from package.json:
-```json
-{
-  "name": "atp-keyserver",
-  "version": "1.0.0"
-}
-```
+### Protected Endpoints (Require Service Auth Token)
 
-#### `GET /.well-known/did.json`
-Returns service DID document per AT Protocol specification:
-```json
-{
-  "@context": ["https://www.w3.org/ns/did/v1"],
-  "id": "{service-did}",
-  "service": [
-    {
-      "id": "#atp_keyserver",
-      "type": "AtpKeyserver",
-      "serviceEndpoint": "{service-url}"
-    }
-  ]
-}
-```
+**Personal Key Management:**
+- `GET /xrpc/dev.atpkeyserver.alpha.key` - Get personal keypair
+- `POST /xrpc/dev.atpkeyserver.alpha.key.rotate` - Rotate personal keypair
+- `GET /xrpc/dev.atpkeyserver.alpha.key.versions` - List key versions
+- `GET /xrpc/dev.atpkeyserver.alpha.key.accessLog` - Get access logs
 
-#### `GET /xrpc/dev.atpkeyserver.alpha.key.public?did={did}`
-Retrieve any user's public key without authentication.
+**Group Key Management:**
+- `GET /xrpc/dev.atpkeyserver.alpha.group.key` - Get group key
+- `POST /xrpc/dev.atpkeyserver.alpha.group.key.rotate` - Rotate group key (owner only)
+- `GET /xrpc/dev.atpkeyserver.alpha.group.key.versions` - List group key versions
 
-**Query Parameters:**
-- `did` (required) - DID of user (must be `did:web:*` or `did:plc:*`)
+**Group Membership Management:**
+- `POST /xrpc/dev.atpkeyserver.alpha.group.member.add` - Add member (owner only)
+- `POST /xrpc/dev.atpkeyserver.alpha.group.member.remove` - Remove member (owner only)
 
-**Response:**
-```json
-{
-  "publicKey": "hex-encoded-public-key"
-}
-```
-
-**Validation:**
-- DID format validation using `isDid()`
-- Only supports `did:web` and `did:plc` methods
-- URL-decodes the DID parameter
-
-### Protected Endpoints (Require JWT Authentication)
-
-#### `GET /xrpc/dev.atpkeyserver.alpha.key`
-Retrieve the authenticated user's complete keypair.
-
-**Headers:**
-- `Authorization: Bearer {jwt}`
-
-**Response:**
-```json
-{
-  "publicKey": "hex-encoded-public-key",
-  "privateKey": "hex-encoded-private-key"
-}
-```
-
-**Implementation:** Calls `getKeypair(did)` from `lib/keys/asymmetric.ts` which returns or creates the user's Ed25519 keypair.
-
-### Key Rotation & Revocation Endpoints
-
-#### `POST /xrpc/dev.atpkeyserver.alpha.key.rotate` (Authenticated)
-Rotate the user's asymmetric keypair, marking the current version as revoked and generating a new version.
-
-**Headers:**
-- `Authorization: Bearer {jwt}`
-
-**Body:**
-```json
-{
-  "reason": "suspected_compromise" | "routine_rotation" | "user_requested"
-}
-```
-
-**Response:**
-```json
-{
-  "oldVersion": 1,
-  "newVersion": 2,
-  "rotatedAt": "2025-01-23T10:30:00.000Z"
-}
-```
-
-#### `GET /xrpc/dev.atpkeyserver.alpha.key.versions` (Authenticated)
-List all versions of the user's keypair with their status.
-
-**Headers:**
-- `Authorization: Bearer {jwt}`
-
-**Response:**
-```json
-{
-  "versions": [
-    {
-      "version": 2,
-      "status": "active",
-      "created_at": "2025-01-23T10:30:00.000Z",
-      "revoked_at": null
-    },
-    {
-      "version": 1,
-      "status": "revoked",
-      "created_at": "2025-01-20T08:00:00.000Z",
-      "revoked_at": "2025-01-23T10:30:00.000Z"
-    }
-  ]
-}
-```
-
-#### `GET /xrpc/dev.atpkeyserver.alpha.key.accessLog` (Authenticated)
-Retrieve access logs for the authenticated user's keys.
-
-**Headers:**
-- `Authorization: Bearer {jwt}`
-
-**Query Parameters:**
-- `limit` (optional) - Maximum number of log entries to return (default: 50)
-
-**Response:**
-```json
-{
-  "logs": [
-    {
-      "version": 2,
-      "accessed_at": "2025-01-23T10:30:00.000Z",
-      "ip": "192.0.2.1",
-      "user_agent": "Mozilla/5.0..."
-    },
-    {
-      "version": 1,
-      "accessed_at": "2025-01-22T08:15:00.000Z",
-      "ip": "192.0.2.1",
-      "user_agent": "Mozilla/5.0..."
-    }
-  ]
-}
-```
-
-**Note:** IP and user_agent fields may be null if not available from the request headers.
-
-#### `GET /xrpc/dev.atpkeyserver.alpha.group.key` (Authenticated)
-Get a group's symmetric key (supports version parameter for historical keys).
-
-**Headers:**
-- `Authorization: Bearer {jwt}`
-
-**Query Parameters:**
-- `group_id` (required) - Group identifier (format: `{owner_did}#{group_name}`)
-- `version` (optional) - Specific version number
-
-**Response:**
-```json
-{
-  "groupId": "did:plc:abc123#followers",
-  "secretKey": "hex-encoded-secret-key",
-  "version": 1
-}
-```
-
-#### `POST /xrpc/dev.atpkeyserver.alpha.group.key.rotate` (Owner Only, Authenticated)
-Rotate a group's symmetric key (only the group owner can perform this action).
-
-**Headers:**
-- `Authorization: Bearer {jwt}`
-
-**Body:**
-```json
-{
-  "group_id": "did:plc:abc123#followers",
-  "reason": "suspected_compromise"
-}
-```
-
-**Response:**
-```json
-{
-  "groupId": "did:plc:abc123#followers",
-  "oldVersion": 1,
-  "newVersion": 2,
-  "rotatedAt": "2025-01-23T10:30:00.000Z"
-}
-```
-
-#### `GET /xrpc/dev.atpkeyserver.alpha.group.key.versions` (Authenticated)
-List all versions of a group key (owner and members can view).
-
-**Headers:**
-- `Authorization: Bearer {jwt}`
-
-**Query Parameters:**
-- `group_id` (required)
-
-**Response:**
-```json
-{
-  "groupId": "did:plc:abc123#followers",
-  "versions": [
-    {
-      "version": 2,
-      "status": "active",
-      "created_at": "2025-01-23T10:30:00.000Z",
-      "revoked_at": null
-    },
-    {
-      "version": 1,
-      "status": "revoked",
-      "created_at": "2025-01-20T08:00:00.000Z",
-      "revoked_at": "2025-01-23T10:30:00.000Z"
-    }
-  ]
-}
-```
-
-#### `POST /xrpc/dev.atpkeyserver.alpha.group.member.add` (Owner Only, Authenticated)
-Add a member to a group (only the group owner can perform this action).
-
-**Headers:**
-- `Authorization: Bearer {jwt}`
-
-**Body:**
-```json
-{
-  "group_id": "did:plc:abc123#followers",
-  "member_did": "did:plc:xyz789"
-}
-```
-
-**Response:**
-```json
-{
-  "groupId": "did:plc:abc123#followers",
-  "memberDid": "did:plc:xyz789",
-  "status": "added"
-}
-```
-
-**Error Responses:**
-- `404` - Group not found
-- `403` - Only owner can add members
-- `409` - Member already in group
-
-#### `POST /xrpc/dev.atpkeyserver.alpha.group.member.remove` (Owner Only, Authenticated)
-Remove a member from a group (only the group owner can perform this action).
-
-**Headers:**
-- `Authorization: Bearer {jwt}`
-
-**Body:**
-```json
-{
-  "group_id": "did:plc:abc123#followers",
-  "member_did": "did:plc:xyz789"
-}
-```
-
-**Response:**
-```json
-{
-  "groupId": "did:plc:abc123#followers",
-  "memberDid": "did:plc:xyz789",
-  "status": "removed"
-}
-```
-
-**Error Responses:**
-- `404` - Group not found or member not found in group
-- `403` - Only owner can remove members
+**For complete endpoint documentation including request/response formats, parameters, error codes, and examples, see [API_REFERENCE.md](./API_REFERENCE.md).**
 
 ## Key Versioning & Revocation
 
···
 
 **Key rotation limits damage radius:** When a key leaks, rotation prevents new posts from being decrypted, while old posts remain readable to authorized parties.
 
-### Database Schema
-
-Both `keys` and `groups` tables use versioning:
-
-```sql
--- Asymmetric keys
-CREATE TABLE keys (
-  did TEXT NOT NULL,
-  version INTEGER NOT NULL DEFAULT 1,
-  public_key TEXT NOT NULL,
-  private_key TEXT NOT NULL,
-  created_at TEXT NOT NULL,
-  revoked_at TEXT,
-  status TEXT NOT NULL DEFAULT 'active',
-  PRIMARY KEY (did, version)
-);
-CREATE INDEX idx_keys_did_status ON keys(did, status);
-
--- Symmetric group keys
-CREATE TABLE groups (
-  id TEXT NOT NULL,
-  version INTEGER NOT NULL DEFAULT 1,
-  owner_did TEXT NOT NULL,
-  secret_key TEXT NOT NULL,
-  created_at TEXT NOT NULL,
-  revoked_at TEXT,
-  status TEXT NOT NULL DEFAULT 'active',
-  PRIMARY KEY (id, version)
-);
-CREATE INDEX idx_groups_id_status ON groups(id, status);
-
--- Access logging
-CREATE TABLE key_access_log (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  did TEXT NOT NULL,
-  version INTEGER NOT NULL,
-  accessed_at TEXT NOT NULL,
-  ip TEXT,
-  user_agent TEXT
-);
-```
-
 ### Key Lifecycle
 
 **Status Values:**
 - `active` - Current version, used for encryption
-- `revoked` - Compromised or rotated out, still available for decryption
-- `rotated` - Replaced during routine rotation (reserved for future use)
+- `revoked` - No longer active (compromised or rotated out), still available for decryption
 
 **Default Behavior:**
 - New keys start as version 1 with status `active`
···
 - Audit compliance requirements
 - Incident response investigation
 
-**API Access:**
+**API Access to logs:**
 Users can retrieve access logs for their keys via the authenticated `/xrpc/dev.atpkeyserver.alpha.key.accessLog` endpoint. This allows users to:
 - Monitor their own key usage
 - Detect unauthorized access attempts
···
 - **Member Verification**: Key access validated against membership table
 - **Namespace Isolation**: Group IDs scoped by owner DID
 
+For more insight on the security model, see [SECURITY.md](SECURITY.md)
+
+
 ## Configuration
 
-### Environment Variables
+There is not much to configure yet in this first version. The only thing would be the DID of the service and the port this service is running on, which are configured with environment variables as described here:
+
 - `DID` (required) - Service's own DID identifier
 - `PORT` (optional) - HTTP server port (default: 4000)
 
-### Database
-- File: `keyserver.db`
-- Mode: WAL (Write-Ahead Logging)
-- Auto-created on first run
 
 ## Development Workflow
 
-### Scripts
-- `bun run dev` - Development mode with auto-reload (uses `DID=test`)
-- `bun start` - Production mode
-- `bun run format` - Format code with Prettier
+To create a new endpoint for the server, the development workflow would be something like this:
 
-### Dependencies
-- Uses Bun's native package management
-- Lock file: `bun.lock`
-- Separate dev dependencies for tooling
+1. Define the endpoint route in `main.ts` and decide whether it requires authentication or not.
+2. Implement the new endpoint inner logic in a file in the `lib` folder.
+3. Create a lexicon definition file for the new endpoint in the `lexicons` folder.
+4. Update the related documentation about API endpoints.
 
 ## Design Patterns
 
···
 - URL-safe without additional encoding
 - Human-readable for debugging
 
-### Type-Safe Database Queries
-Database schema exported as TypeScript types:
-- Compile-time type checking for queries
-- IntelliSense support in IDEs
-- Reduces runtime errors
 
 ## Project Structure
 
 ```
-atp-keyserver/
-├── main.ts                     # Entry point and routing
-├── package.json                # Dependencies and scripts
-├── bun.lock                    # Dependency lock file
-├── README.md                   # Project documentation
-├── CLAUDE.md                   # Architecture documentation (this file)
-├── keyserver.db                # SQLite database (generated at runtime)
-├── lib/
-│   ├── db.ts                   # Database schema and connection
-│   ├── authMiddleware.ts       # JWT authentication with DID resolution
-│   └── keys/
-│       ├── asymmetric.ts       # Ed25519 keypair management with versioning
-│       ├── symmetric.ts        # XChaCha20 encryption & group management with versioning
-│       └── access-log.ts       # Key access logging for security auditing
-└── lexicons/
-    └── dev/
-        └── atpkeyserver/
-            └── defs.json       # XRPC lexicon definitions (placeholder)
+atp-keyserver/                        # Monorepo root
+├── packages/
+│   ├── server/                       # Keyserver service
+│   │   ├── main.ts                   # Entry point and routing
+│   │   ├── package.json              # Server dependencies
+│   │   ├── tsconfig.json             # Server TypeScript config
+│   │   ├── README.md                 # Server starting documentation
+│   │   ├── lib/
+│   │   │   ├── db.ts                 # Database schema and connection
+│   │   │   ├── authMiddleware.ts     # JWT authentication with DID resolution
+│   │   │   └── keys/
+│   │   │       ├── asymmetric.ts     # Ed25519 keypair management with versioning
+│   │   │       ├── symmetric.ts      # XChaCha20 encryption & group management
+│   │   │       └── access-log.ts     # Key access logging
+│   │   ├── lexicons/                 # XRPC lexicon definitions
+│   │   │   └── ...
+│   │   └── keyserver.db              # SQLite database (generated at runtime)
+│   └── client/                       # Client library
+│       ├── src/
+│       │   ├── index.ts              # Package entry point
+│       │   ├── crypto.ts             # Encryption/decryption functions
+│       │   └── types.ts              # TypeScript type definitions
+│       ├── dist/                     # Compiled output (generated)
+│       ├── package.json              # Client dependencies
+│       ├── tsconfig.json             # ESM build config
+│       ├── tsconfig.cjs.json         # CommonJS build config
+│       └── README.md                 # Client starting documentation
+├── docs/                             # Centralized documentation
+│   ├── ARCHITECTURE.md               # Server architecture (this file)
+│   ├── ENCRYPTION_PROTOCOL.md        # E2E encryption protocol specification
+│   ├── SECURITY.md                   # Security best practices for new clients
+│   ├── API_REFERENCE.md              # Complete API endpoint reference
+│   └── CLIENT_IMPLEMENTATION.md      # Client library design decisions
+├── package.json                      # Workspace root configuration
+├── tsconfig.json                     # Base TypeScript configuration
+├── bun.lock                          # Dependency lock file
+├── README.md                         # Project overview
+└── LICENSE.md                        # License information
 ```
 
 ## Code Quality
···
 - Good use of AT Protocol standards
 - Proper DID validation and method checking
 - WAL mode enabled for SQLite (better concurrency)
-- Direct imports eliminate unnecessary module layers
 
 ### Considerations for Future Development
 - Database error handling could be more comprehensive
···
 - **Group Key Rotation**: `/xrpc/dev.atpkeyserver.alpha.group.key.rotate` (owner only)
 - **Version Listing**: View all key versions with status and timestamps
 - **Specific Version Access**: Retrieve historical keys for decrypting old content
-- **Status Tracking**: Active, revoked, or rotated status per version
+- **Status Tracking**: Active or revoked status per version (with reason in metadata)
 
 ### Design Trade-offs
 - **Backward Compatibility Over Forward Secrecy**: All versions retained to prevent data loss
···
 - Encrypted backup strategy for database
 - Scheduled/automatic key rotation policies
 - Enhanced anomaly detection based on access logs
-
-## AT Protocol Integration
-
-This keyserver implements a custom AT Protocol service type:
-
-**Service Type**: `AtpKeyserver`
-**Lexicon Scope**: `dev.atpkeyserver.alpha`
-
-The service follows AT Protocol conventions:
-- DID-based identity
-- JWT authentication with signing key verification
-- XRPC method naming (`/xrpc/{lexicon}.{method}`)
-- Service discovery via DID documents
-
-This allows AT Protocol applications to discover and interact with the keyserver using standard DID resolution.

docs/CLIENT_IMPLEMENTATION.md

···
-# Client-Side Encryption Implementation Plan
+# Client Implementation Strategy
 
-## Overview
+## Purpose
 
-This document outlines the implementation plan for client-side encryption/decryption of "followers-only" posts in the ATP keyserver ecosystem. The approach prioritizes end-to-end encryption, performance, and alignment with ATProto's decentralized philosophy.
+This document outlines the design philosophy and implementation strategy for the ATP Keyserver client library. It serves as a roadmap for contributors and explains key architectural decisions.
 
-## Recommended Solution: Client-Side with Key Caching
+For protocol details, see [ENCRYPTION_PROTOCOL.md](./ENCRYPTION_PROTOCOL.md).
+For security guidelines, see [SECURITY.md](./SECURITY.md).
+For usage instructions, see [Client README](../packages/client/README.md).
 
-The keyserver's role is **key management and authorization**, not content processing. By keeping cryptographic operations client-side, we preserve the security model while maintaining better performance and scalability.
+## Design Philosophy
 
-**Core Principle:** The server should only answer "Is this user authorized to decrypt this group's messages?" - it should never answer "What does this message say?"
-
-## Key Benefits vs Server-Side Encryption
+### Client-Side Encryption
 
-1. **Security**: True end-to-end encryption - server never sees plaintext
-2. **Performance**: Operations complete in <1ms vs 100-500ms for server round-trips
-3. **Scalability**: 50% less server load, 97% less bandwidth usage
-4. **Philosophy**: Aligns with ATProto's decentralized design principles
-5. **Cost**: Significantly lower server infrastructure costs
-6. **Privacy**: Users don't need to trust server operator with message content
+**Decision:** Cryptographic operations (encryption/decryption) happen on the client, not the server.
 
-## Optimal Protocol
+**Rationale:**
+- **True end-to-end encryption**: Server never sees plaintext
+- **Better performance**: <1ms local crypto vs 100-500ms server round-trip
+- **Lower server load**: 50% less CPU, 97% less bandwidth
+- **Aligned with ATProto**: Decentralized architecture, user sovereignty
+- **Cost efficiency**: Scales with user devices, not server capacity
 
-### Creating an Encrypted "Followers-Only" Post
+**Trade-offs:**
+- Clients must handle cryptography correctly
+- Requires distributing crypto library (~52KB)
+- Key caching responsibility on client
 
-```typescript
-import { encryptMessage } from '@atpkeyserver/client/crypto'
+**Alternative considered:** Server-side encryption (rejected due to trust model and performance)
 
-// 1. Define the group for followers-only visibility
-const groupId = `${authorDid}#followers`
+### Single Package Architecture
 
-// 2. Fetch active group key from keyserver (with caching)
-let key = keyCache.get(groupId)
-if (!key) {
-  const response = await fetch(
-    `/xrpc/dev.atpkeyserver.alpha.group.key?group_id=${encodeURIComponent(groupId)}`,
-    { headers: { Authorization: `Bearer ${jwt}` } }
-  )
-  const data = await response.json()
-  key = { secretKey: data.secretKey, version: data.version }
-  keyCache.set(groupId, key, { ttl: 3600 }) // Cache for 1 hour
-}
+**Decision:** One npm package `@atpkeyserver/client` with optional imports via subpath exports.
 
-// 3. Encrypt the post content locally
-const post = { text: "Secret message for followers", createdAt: new Date() }
-const postUri = `at://${authorDid}/app.bsky.feed.post/${rkey}`
-const ciphertext = encryptMessage(postUri, key.secretKey, JSON.stringify(post))
+**Rationale:**
+- Crypto library (@noble/ciphers) is ~52KB and represents 90% of bundle
+- High-level client adds only ~8KB on top of crypto functions
+- Maintenance overhead of separate packages not justified by small size difference
+- Subpath exports allow tree-shaking for minimal bundle impact
 
-// 4. Store encrypted content in PDS
-await pds.createRecord({
-  collection: 'app.bsky.feed.post',
-  record: {
-    encrypted_content: ciphertext,
-    key_version: key.version,
-    encrypted_at: new Date().toISOString(),
-    visibility: 'followers'
-  }
-})
+**Package structure:**
 ```
-
-### Decrypting a "Followers-Only" Post
+@atpkeyserver/client
+├── /crypto      → Just crypto functions (52KB)
+├── /client      → Just KeyserverClient (60KB, includes crypto)
+└── / (main)     → Both exports (60KB, tree-shaken)
+```
 
-```typescript
-import { decryptMessage } from '@atpkeyserver/client/crypto'
+**Alternative considered:** Separate `@atpkeyserver/client-crypto` and `@atpkeyserver/client` packages (rejected due to minimal size benefit)
 
-// 1. Read encrypted post from feed
-const encryptedPost = await pds.getRecord(postUri)
-const { encrypted_content, key_version } = encryptedPost.value
-
-// 2. Determine group ID from author
-const authorDid = postUri.split('/')[2]
-const groupId = `${authorDid}#followers`
+### Service Auth Integration
 
-// 3. Fetch the specific key version (with caching)
-const cacheKey = `${groupId}:${key_version}`
-let key = keyCache.get(cacheKey)
+**Decision:** Client library abstracts service auth token management via callback pattern.
 
-if (!key) {
-  const response = await fetch(
-    `/xrpc/dev.atpkeyserver.alpha.group.key?` +
-    `group_id=${encodeURIComponent(groupId)}&version=${key_version}`,
-    { headers: { Authorization: `Bearer ${followerJwt}` } }
-  )
-  const data = await response.json()
-  key = data.secretKey
+**Rationale:**
+- PDS clients vary by platform (@atproto/api, custom implementations)
+- Callback pattern allows any PDS client integration
+- Client library handles token caching automatically
+- Separates concerns: client lib = crypto + keyserver API, user provides = PDS auth
 
-  // Cache historical keys for 24 hours (they never change)
-  keyCache.set(cacheKey, key, { ttl: 86400 })
-}
-
-// 4. Decrypt locally
-const plaintext = decryptMessage(postUri, key, encrypted_content)
-const post = JSON.parse(plaintext)
+**Implementation:**
+```typescript
+new KeyserverClient({
+  keyserverDid: 'did:web:keyserver.example.com',
+  getServiceAuthToken: async (aud, lxm) => {
+    // User provides: obtain token from their PDS client
+    return await pdsClient.getServiceAuth({ aud, lxm })
+  }
+})
 ```
 
-## Authentication Flow
+See [ENCRYPTION_PROTOCOL.md](./ENCRYPTION_PROTOCOL.md#authentication-flow) for service auth details.
 
-### Overview
+## Component Architecture
 
-The keyserver uses **ATProto service auth** - a secure, decentralized authentication mechanism where clients obtain short-lived JWT tokens from their PDS (Personal Data Server) to authenticate with the keyserver. This design ensures the keyserver never needs to store passwords or trust specific PDS instances.
+### Core Components
 
-**Key Properties:**
-- Tokens signed with user's ATProto signing key (from DID document)
-- Short-lived (default: 60 seconds, configurable up to server limits)
-- Audience-bound (only valid for specific keyserver DID)
-- Method-bound (optional: restrict to specific XRPC endpoint)
-- Direct client → keyserver communication (PDS only issues tokens)
+**1. Crypto Module (`crypto.ts`)**
+- XChaCha20-Poly1305 encryption/decryption
+- Uses @noble/ciphers library
+- Stateless, pure functions
+- No network dependencies
 
-### Complete Authentication Flow
+**2. KeyserverClient (`client.ts`)**
+- HTTP client for keyserver API
+- Service auth token management
+- Key caching with TTL
+- Error handling and retries
 
-```
-┌─────────┐                    ┌─────────┐                     ┌───────────┐
-│ Client  │                    │   PDS   │                     │ Keyserver │
-└────┬────┘                    └────┬────┘                     └─────┬─────┘
-     │                              │                                │
-     │ 1. Authenticate              │                                │
-     │ ────────────────────────────>│                                │
-     │    (OAuth or createSession)  │                                │
-     │                              │                                │
-     │ 2. Return access token       │                                │
-     │ <────────────────────────────│                                │
-     │                              │                                │
-     │ 3. Request service auth      │                                │
-     │ ────────────────────────────>│                                │
-     │    (getServiceAuth)          │                                │
-     │                              │                                │
-     │ 4. Sign & return JWT         │                                │
-     │ <────────────────────────────│                                │
-     │    (signed with user's key)  │                                │
-     │                              │                                │
-     │ 5. Call keyserver with JWT   │                                │
-     │ ────────────────────────────────────────────────────────────> │
-     │                              │                                │
-     │                              │           6. Verify JWT        │
-     │                              │           - Check aud          │
-     │                              │           - Resolve DID        │
-     │                              │           - Verify permissions │
-     │                              │                                │
-     │ 7. Return encrypted key      │                                │
-     │ <──────────────────────────────────────────────────────────── │
-     │                              │                                │
-```
+**3. Cache Module (`cache.ts`)**
+- In-memory LRU cache
+- Separate TTLs for active/historical keys
+- Service auth token caching
+- Automatic expiry
 
-### Step 1: Authenticate to PDS
+**4. Service Auth Module (`service-auth.ts`)**
+- Token cache management
+- Expiry checking with safety margin
+- Automatic refresh logic
 
-Clients first authenticate with their PDS using OAuth (recommended) or legacy JWT authentication.
+**5. Types Module (`types.ts`)**
+- TypeScript interfaces
+- Configuration types
+- Response types
 
-**OAuth (Modern):**
-```typescript
-import { OAuthClient } from '@atproto/oauth-client'
+**6. Errors Module (`errors.ts`)**
+- Custom error classes
+- Structured error handling
+- HTTP status code mapping
 
-const oauthClient = new OAuthClient({
-  clientId: 'your-app-client-id',
-  // ... OAuth configuration
-})
+### Dependency Graph
 
-// Redirect user to PDS for authentication
-await oauthClient.authorize({
-  scope: 'atproto transition:generic'
-})
-
-// After OAuth callback:
-const { access_token, sub: userDid } = oauthClient.getTokens()
 ```
-
-**Legacy JWT (com.atproto.server.createSession):**
-```typescript
-const { accessJwt, refreshJwt, did } = await fetch(
-  'https://bsky.social/xrpc/com.atproto.server.createSession',
-  {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      identifier: 'user.bsky.social',
-      password: 'app-password-here'
-    })
-  }
-).then(r => r.json())
+index.ts
+├── crypto.ts
+│   └── @noble/ciphers
+├── client.ts
+│   ├── crypto.ts
+│   ├── cache.ts
+│   ├── service-auth.ts
+│   ├── types.ts
+│   └── errors.ts
+├── types.ts
+└── errors.ts
 ```
 
-### Step 2: Request Service Auth Token
-
-Call `com.atproto.server.getServiceAuth` on the user's PDS to obtain a service auth token for the keyserver.
-
-```typescript
-// Get service auth token for keyserver
-const { token: serviceAuthToken } = await fetch(
-  `https://bsky.social/xrpc/com.atproto.server.getServiceAuth?` +
-  new URLSearchParams({
-    aud: 'did:web:keyserver.example.com',        // Keyserver DID (required)
-    lxm: 'dev.atpkeyserver.alpha.key',           // Optional: method binding
-    exp: String(Math.floor(Date.now() / 1000) + 300) // Optional: 5 min expiry
-  }),
-  {
-    headers: {
-      // OAuth: Authorization: DPoP {access_token} + DPoP header
-      // Legacy: Authorization: Bearer {accessJwt}
-      Authorization: `Bearer ${accessJwt}`
-    }
-  }
-).then(r => r.json())
-```
+## Key Features
 
-**Parameters:**
-- `aud` (required): The DID of your keyserver (must match keyserver's serviceDid)
-- `lxm` (optional): XRPC method to bind token to (e.g., `dev.atpkeyserver.alpha.key`)
-- `exp` (optional): Expiration time in Unix epoch seconds (default: 60 seconds from now)
+### Automatic Caching
 
-**What the PDS does:**
-1. Verifies client's authentication (OAuth or JWT)
-2. Creates JWT with claims:
-   - `iss`: User's DID
-   - `aud`: Keyserver's DID
-   - `exp`: Expiration timestamp
-   - `iat`: Issued-at timestamp
-   - `lxm`: Method binding (if specified)
-3. Signs JWT with user's ATProto signing key (from DID document)
-4. Returns `{ token: "eyJhbG..." }`
+**Key Caching:**
+- Active keys: 1 hour TTL (may change with rotation)
+- Historical keys: 24 hour TTL (immutable)
+- LRU eviction when max size reached
 
-### Step 3: Call Keyserver with Service Auth Token
+**Service Auth Token Caching:**
+- 60 second TTL (or server-specified `exp`)
+- Refresh when <10 seconds remain
+- Memory-only storage
 
-```typescript
-// Use service auth token to fetch group key
-const { secretKey, version } = await fetch(
-  `https://keyserver.example.com/xrpc/dev.atpkeyserver.alpha.group.key?` +
-  `group_id=${encodeURIComponent(`${userDid}#followers`)}`,
-  {
-    headers: {
-      Authorization: `Bearer ${serviceAuthToken}`
-    }
-  }
-).then(r => r.json())
-```
+**Benefits:**
+- Reduces keyserver load
+- Improves client performance
+- Handles token refresh automatically
 
-**Keyserver verification (automatic in authMiddleware.ts):**
-1. Extracts JWT from Authorization header
-2. Parses JWT to get `iss` (user DID) and `aud` (keyserver DID)
-3. Checks `aud` matches keyserver's DID (prevents token misuse)
-4. Resolves user's DID to get signing key
-5. Verifies JWT signature with user's signing key
-6. Checks expiration timestamp
-7. Returns authenticated user's DID to request handler
+See [SECURITY.md](./SECURITY.md#token-caching) for security considerations.
 
-### Service Auth Token Caching
+### Request Deduplication
 
-Service auth tokens are short-lived (60 seconds default). Clients should cache tokens to avoid excessive PDS requests:
+Multiple simultaneous requests for the same key are collapsed into a single network request:
 
 ```typescript
-class ServiceAuthCache {
-  private tokens = new Map<string, {
-    token: string
-    expiresAt: number
-  }>()
+// Both calls trigger only one network request
+const [key1, key2] = await Promise.all([
+  client.getGroupKey('did:plc:abc#followers'),
+  client.getGroupKey('did:plc:abc#followers')
+])
+```
 
-  async getToken(
-    pdsClient: PdsClient,
-    aud: string,
-    lxm?: string
-  ): Promise<string> {
-    const cacheKey = `${aud}:${lxm || ''}`
-    const cached = this.tokens.get(cacheKey)
+### Automatic Retry
 
-    // Use cached token if valid for at least 10 more seconds
-    const now = Math.floor(Date.now() / 1000)
-    if (cached && cached.expiresAt > now + 10) {
-      return cached.token
-    }
+Network failures retry with exponential backoff:
+- Retry on: 5xx errors, network timeouts
+- Don't retry on: 4xx errors (client errors are permanent)
+- Max retries: 3 attempts
+- Backoff: 100ms, 200ms, 400ms
 
-    // Request new token (60 second expiry)
-    const exp = now + 60
-    const { token } = await pdsClient.getServiceAuth({ aud, lxm, exp })
+### Type Safety
 
-    this.tokens.set(cacheKey, { token, expiresAt: exp })
-    return token
-  }
+Full TypeScript support:
+- Strict typing for all APIs
+- IntelliSense support
+- Compile-time error detection
+- Generated type definitions
 
-  clear(): void {
-    this.tokens.clear()
-  }
-}
-```
+## Bundle Size Analysis
 
-**Cache strategy:**
-- Keep tokens for up to 60 seconds (or specified `exp`)
-- Refresh when <10 seconds remain (safety margin)
-- Separate cache keys for different services (`aud`) and methods (`lxm`)
-- Clear cache on logout
+Tree-shaking eliminates unused code. Actual bundle sizes depend on what you import:
 
-### Complete End-to-End Example
+### Scenario 1: Crypto Functions Only
 
 ```typescript
-import { KeyserverClient } from '@atpkeyserver/client'
-import { encryptMessage } from '@atpkeyserver/client/crypto'
-
-// 1. Authenticate to PDS (one-time or when session expires)
-const pdsClient = new AtpAgent({ service: 'https://bsky.social' })
-await pdsClient.login({
-  identifier: 'user.bsky.social',
-  password: 'app-password'
-})
-
-// 2. Create keyserver client with service auth integration
-const keyserverClient = new KeyserverClient({
-  keyserverDid: 'did:web:keyserver.example.com',
-  getServiceAuthToken: async (aud, lxm) => {
-    // Get service auth token from PDS
-    const { token } = await pdsClient.com.atproto.server.getServiceAuth({
-      aud,
-      lxm,
-      exp: Math.floor(Date.now() / 1000) + 60
-    })
-    return token
-  }
-})
-
-// 3. Encrypt and publish post (automatic token handling)
-const groupId = `${pdsClient.session.did}#followers`
-const { ciphertext, version } = await keyserverClient.encrypt(
-  groupId,
-  postUri,
-  JSON.stringify({ text: "Secret message for followers" })
-)
-
-await pdsClient.com.atproto.repo.createRecord({
-  repo: pdsClient.session.did,
-  collection: 'app.bsky.feed.post',
-  record: {
-    encrypted_content: ciphertext,
-    key_version: version,
-    encrypted_at: new Date().toISOString(),
-    createdAt: new Date().toISOString()
-  }
-})
+import { encryptMessage, decryptMessage } from '@atpkeyserver/client/crypto'
 ```
 
-### Security Properties
+**Bundled:** ~52KB (minified + gzipped ~15KB)
+- @noble/ciphers: 50KB
+- crypto.ts: 2KB
 
-**Audience Binding:**
-- Tokens only valid for specific keyserver DID
-- Prevents token reuse across services
-- Keyserver rejects tokens with wrong `aud`
+**Use case:** You handle keyserver API calls manually, just need crypto.
 
-**Method Binding (Optional):**
-- `lxm` parameter restricts token to specific endpoint
-- Extra security for sensitive operations
-- Example: token only valid for `dev.atpkeyserver.alpha.key.rotate`
-
-**Short-Lived Tokens:**
-- Default 60 second expiry limits attack window
-- Compromised token quickly becomes useless
-- No long-term credential storage on client
-
-**Decentralized Verification:**
-- Keyserver verifies signature using public key from DID document
-- No shared secrets between PDS and keyserver
-- Works with any ATProto-compliant PDS
-
-**User Key Signing:**
-- Token signed with user's signing key, not PDS key
-- User maintains cryptographic control over identity
-- PDS cannot forge tokens for users without their key
+### Scenario 2: Full Client
 
-## Implementation Plan
-
-### 1. Create npm Package: `@atpkeyserver/client`
-
-**Purpose:** Unified client library for keyserver integration, providing both low-level cryptographic functions and high-level API wrapper with built-in caching.
-
-**Package Structure:**
-```
-@atpkeyserver/client/
-├── src/
-│   ├── index.ts          # Main exports (KeyserverClient + crypto)
-│   ├── client.ts         # KeyserverClient class
-│   ├── crypto.ts         # Encryption/decryption functions
-│   ├── cache.ts          # Key caching with TTL
-│   ├── service-auth.ts   # Service auth token caching
-│   ├── types.ts          # TypeScript types
-│   └── errors.ts         # Custom error classes
-├── package.json          # With subpath exports configured
-├── tsconfig.json
-├── README.md
-└── examples/
-    ├── basic-usage.ts
-    ├── react-hook.tsx
-    └── cli-example.ts
-```
-
-**Subpath Exports Configuration:**
-```json
-// package.json
-{
-  "name": "@atpkeyserver/client",
-  "version": "1.0.0",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    },
-    "./crypto": {
-      "import": "./dist/crypto.js",
-      "require": "./dist/crypto.cjs"
-    },
-    "./client": {
-      "import": "./dist/client.js",
-      "require": "./dist/client.cjs"
-    }
-  }
-}
+```typescript
+import { KeyserverClient } from '@atpkeyserver/client'
 ```
 
-**Import Patterns:**
-```typescript
-// Option 1: Import just crypto functions (tree-shaken, minimal bundle)
-import { encryptMessage, decryptMessage } from '@atpkeyserver/client/crypto'
+**Bundled:** ~60KB (minified + gzipped ~18KB)
+- @noble/ciphers: 50KB
+- Client code: 10KB (includes crypto, caching, HTTP, errors)
 
-// Option 2: Import just the client
-import { KeyserverClient } from '@atpkeyserver/client/client'
+**Use case:** Full-featured client with automatic caching and token management.
 
-// Option 3: Import everything from main entry
-import { KeyserverClient, encryptMessage, decryptMessage } from '@atpkeyserver/client'
-```
+### Scenario 3: Both
 
-**Crypto Functions API:**
 ```typescript
-// Export from lib/keys/client.ts
-export function encryptMessage(
-  id: string,
-  key: string,
-  plaintext: string
-): string
-
-export function decryptMessage(
-  id: string,
-  key: string,
-  ciphertext: string
-): string
-
+import { KeyserverClient, encryptMessage } from '@atpkeyserver/client'
 ```
 
-**KeyserverClient API:**
-```typescript
-class KeyserverClient {
-  constructor(config: {
-    keyserverDid: string
-    getServiceAuthToken: (aud: string, lxm?: string) => Promise<string>
-    cache?: CacheOptions
-  })
+**Bundled:** ~60KB (same as scenario 2)
+- Client includes crypto, no duplication
 
-  // Get active group key (auto-cached)
-  async getGroupKey(groupId: string): Promise<{
-    secretKey: string
-    version: number
-  }>
+**Use case:** Mix high-level and low-level APIs as needed.
 
-  // Get specific key version (auto-cached with longer TTL)
-  async getGroupKeyVersion(
-    groupId: string,
-    version: number
-  ): Promise<{ secretKey: string }>
+### Bundle Optimization
 
-  // Encrypt message with auto key fetching
-  async encrypt(
-    groupId: string,
-    messageId: string,
-    plaintext: string
-  ): Promise<{
-    ciphertext: string
-    version: number
-  }>
+**Automatic:**
+- Tree-shaking removes unused exports
+- Minification reduces code size
+- Gzip compresses for network transfer
 
-  // Decrypt message with auto key fetching
-  async decrypt(
-    groupId: string,
-    messageId: string,
-    ciphertext: string,
-    version: number
-  ): Promise<string>
+**Manual optimization:**
+- Use subpath imports (`/crypto`, `/client`) for smaller bundles
+- Import only what you need
+- Modern bundlers (webpack, vite, rollup) handle this automatically
 
-  // Clear cache (useful for testing or logout)
-  clearCache(): void
-}
-```
+**Conclusion:** Crypto library dominates bundle size. Single package vs separate packages saves only ~8KB, not worth maintenance complexity.
 
-**Caching Strategy:**
-```typescript
-interface CacheOptions {
-  activeKeyTtl?: number      // Default: 3600 (1 hour)
-  historicalKeyTtl?: number  // Default: 86400 (24 hours)
-  maxSize?: number           // Default: 1000 keys
-}
-```
+## Implementation Phases
 
-**Error Handling:**
-```typescript
-class KeyserverError extends Error {
-  constructor(
-    message: string,
-    public statusCode: number,
-    public code: string
-  )
-}
+### Phase 1: Foundation (Complete)
 
-// Specific error types
-class UnauthorizedError extends KeyserverError
-class GroupNotFoundError extends KeyserverError
-class NetworkError extends KeyserverError
-class DecryptionError extends KeyserverError
-```
+- [x] Crypto functions (encryptMessage, decryptMessage)
+- [x] Type definitions
+- [x] Package structure with subpath exports
+- [x] Build configuration (ESM + CJS)
 
-**Key Features:**
-- TypeScript-first with full type safety
-- Tree-shakeable ESM exports (import only what you need)
-- CommonJS compatibility for Node.js
-- **Service auth token management with automatic caching**
-- **Integration with PDS via getServiceAuthToken callback**
-- Automatic retry logic with exponential backoff
-- Request deduplication (multiple simultaneous requests for same key)
-- Built-in cache invalidation strategies (keys + auth tokens)
-- Supports custom cache implementations
-- Comprehensive error handling
-- Request/response logging hooks
-- Zero runtime dependencies beyond @noble/ciphers
-- Comprehensive JSDoc documentation
+### Phase 2: Client Library (In Progress)
 
-**README Contents:**
-- Installation instructions
-- Quick start guide showing both high-level and low-level usage
-- **Service auth token integration with PDS**
-- Complete API documentation for KeyserverClient and crypto functions
-- Caching behavior explanation (keys + service auth tokens)
-- Error handling guide
-- Security considerations and best practices
-- Tree-shaking and bundle optimization tips
-- Usage examples for common scenarios:
-  - Creating encrypted posts
-  - Reading encrypted feeds
-  - Key rotation handling
-  - Group management
-  - **PDS authentication and service auth token flow**
-- Integration guides for:
-  - React/React Native apps
-  - Node.js services
-  - CLI tools
-- Browser and Node.js compatibility notes
+- [ ] KeyserverClient class
+- [ ] Service auth token management
+- [ ] Key caching with TTL
+- [ ] HTTP client with retry logic
+- [ ] Error handling
+- [ ] Request deduplication
 
----
+### Phase 3: Documentation (In Progress)
 
-### 2. Documentation
+- [x] Protocol specification (ENCRYPTION_PROTOCOL.md)
+- [x] Security guidelines (SECURITY.md)
+- [x] API reference (API_REFERENCE.md)
+- [ ] Client README with usage examples
+- [ ] Example implementations (React, Node.js, CLI)
 
-#### Protocol Specification Document
+### Phase 4: Testing
 
-Create `docs/ENCRYPTION_PROTOCOL.md` with:
+- [ ] Unit tests for crypto functions
+- [ ] Integration tests for client
+- [ ] Mock keyserver for testing
+- [ ] E2E encryption flow test
+- [ ] Cache behavior tests
+- [ ] Service auth token refresh tests
 
-**Overview:**
-- End-to-end encryption architecture
-- **Service auth token authentication flow**
-- Key versioning and rotation strategy
-- Group-based access control model
+### Phase 5: Polish
 
-**Message Format:**
-```typescript
-// Encrypted post record structure
-{
-  encrypted_content: string,  // hex(nonce) + hex(ciphertext)
-  key_version: number,        // Required for decryption
-  encrypted_at: string,       // ISO timestamp
-  visibility: 'followers' | 'mentioned' | string
-}
-```
+- [ ] Performance benchmarks
+- [ ] Bundle size analysis
+- [ ] Documentation review
+- [ ] Example applications
+- [ ] npm package publication
 
-**Encryption Process:**
-1. Authenticate to PDS (OAuth or legacy JWT)
-2. Request service auth token from PDS for keyserver
-3. Determine group ID from visibility setting
-4. Fetch active group key from keyserver using service auth token
-5. Generate AT-URI as message ID
-6. Encrypt content with XChaCha20-Poly1305
-7. Store ciphertext with key version metadata
+## Success Metrics
 
-**Decryption Process:**
-1. Authenticate to PDS (OAuth or legacy JWT)
-2. Request service auth token from PDS for keyserver
-3. Read encrypted_content and key_version from record
-4. Determine group ID from author DID and visibility
-5. Fetch specific key version from keyserver using service auth token
-6. Decrypt using AT-URI as AAD (Additional Authenticated Data)
-7. Parse and display plaintext content
+### Performance Targets
 
-**Security Considerations:**
-- **Service auth tokens are short-lived (60 seconds default)**
-- **Cache service auth tokens to avoid PDS rate limits**
-- **Clear auth token cache on logout**
-- Never reuse nonces (automatically handled by random generation)
-- Always include AT-URI as AAD for binding
-- Cache keys appropriately (short TTL for active, long for historical)
-- Validate key_version exists before attempting decryption
-- Handle decryption failures gracefully (deleted posts, revoked access)
+| Operation | Target | Measurement |
+|-----------|--------|-------------|
+| Encryption | <1ms | Local crypto operation |
+| Decryption (cached key) | <5ms | Cache lookup + crypto |
+| Decryption (cache miss) | <200ms | Network fetch + crypto |
+| Service auth (cached) | <1ms | Cache lookup |
+| Service auth (cache miss) | <100ms | PDS round-trip |
 
-**Key Rotation Handling:**
-- Old posts encrypted with old key versions
-- New posts use current active key
-- Clients must support multi-version decryption
-- No re-encryption required for historical posts
+### Developer Experience
 
-**Error Scenarios:**
-- Missing key_version: Cannot decrypt (malformed post)
-- 403 Unauthorized: User lost group access
-- 404 Not Found: Group was deleted
-- Decryption failure: Corrupted data or wrong key
+- [ ] Complete TypeScript types
+- [ ] Comprehensive JSDoc comments
+- [ ] Working examples for 3+ platforms
+- [ ] <5 minutes from install to first encrypted message
+- [ ] Clear error messages with actionable guidance
 
-#### Security Best Practices Document
+### Security
 
-Create `docs/SECURITY.md` with:
+- [ ] Zero plaintext exposure to server
+- [ ] Keys cached in memory only
+- [ ] Service auth tokens cached for max 60 seconds
+- [ ] Proper cleanup on logout
+- [ ] No key or token leakage in logs
+- [ ] Audience binding prevents token misuse
+- [ ] Short-lived tokens limit attack window
 
-**Client Implementation Guidelines:**
-- Key material handling in memory
-- Service auth token and key cache security considerations
-- Error message sanitization (don't leak keys or tokens)
-- Secure key and token deletion on logout
-- Rate limiting recommendations
+### Code Quality
 
-**Service Auth Token Caching:**
-- **Short-lived tokens: 60 second TTL (default)**
-- **Refresh when <10 seconds remain (safety margin)**
-- **Memory-only cache (NEVER persist to disk)**
-- **Clear token cache on logout or session end**
-- **Separate cache keys per service (aud) and method (lxm)**
+- [ ] >80% test coverage
+- [ ] Zero runtime dependencies beyond @noble/ciphers
+- [ ] Tree-shakeable exports
+- [ ] CommonJS + ESM support
+- [ ] Works in Node.js, browser, React Native
 
-**Encryption Key Caching:**
-- Active keys: 1 hour TTL (balance freshness vs performance)
-- Historical keys: 24 hour TTL (never change, safe to cache longer)
-- Memory-only cache (never persist keys to disk without encryption)
-- Clear key cache on user logout
-- Cache size limits to prevent memory exhaustion
+## Testing Strategy
 
-**Common Pitfalls:**
-- Don't log decrypted content, keys, or auth tokens
-- Don't persist keys or tokens in localStorage without encryption
-- Don't skip version validation
-- Don't assume key fetch always succeeds
-- Don't retry decryption failures infinitely
-- **Don't reuse expired service auth tokens**
-- **Don't share service auth tokens between services (audience binding)**
+### Unit Tests
 
-#### Example Implementations
+**Crypto module:**
+- Encrypt/decrypt round-trip
+- Nonce uniqueness
+- AAD binding
+- Error handling
 
-**React Hook Example:**
-```typescript
-// useEncryptedPost.ts
-import { useCallback } from 'react'
-import { KeyserverClient } from '@atpkeyserver/client'
+**Cache module:**
+- TTL expiry
+- LRU eviction
+- Get/set operations
+- Clear operation
 
-export function useEncryptedPost(keyserverClient: KeyserverClient) {
-  const createEncryptedPost = useCallback(async (
-    visibility: 'followers',
-    content: string
-  ) => {
-    const groupId = `${userDid}#${visibility}`
-    const postUri = generatePostUri()
+**Service auth module:**
+- Token expiry checking
+- Refresh logic
+- Cache key generation
 
-    const { ciphertext, version } = await keyserverClient.encrypt(
-      groupId,
-      postUri,
-      JSON.stringify({ text: content, createdAt: new Date() })
-    )
+### Integration Tests
 
-    return {
-      encrypted_content: ciphertext,
-      key_version: version,
-      encrypted_at: new Date().toISOString()
-    }
-  }, [keyserverClient, userDid])
+**Client:**
+- Key fetch with caching
+- Service auth integration
+- Retry logic
+- Error handling
 
-  const decryptPost = useCallback(async (
-    encryptedPost: EncryptedPost
-  ) => {
-    const { encrypted_content, key_version } = encryptedPost
-    const authorDid = extractDidFromUri(encryptedPost.uri)
-    const groupId = `${authorDid}#followers`
+**E2E:**
+- Full encryption flow (PDS → keyserver → encrypt → store)
+- Full decryption flow (fetch → keyserver → decrypt → display)
+- Key rotation handling
 
-    const plaintext = await keyserverClient.decrypt(
-      groupId,
-      encryptedPost.uri,
-      encrypted_content,
-      key_version
-    )
+### Mock Server
+
+Build lightweight mock keyserver for testing:
+- Simulates auth verification
+- Returns mock keys
+- Configurable latency
+- Error injection
 
-    return JSON.parse(plaintext)
-  }, [keyserverClient])
+## Open Questions
 
-  return { createEncryptedPost, decryptPost }
-}
-```
+### Rate Limiting
 
-**CLI Example:**
-```typescript
-// encrypt-cli.ts
-import { KeyserverClient } from '@atpkeyserver/client'
+**Question:** Should client enforce rate limits?
 
-const client = new KeyserverClient({
-  baseUrl: process.env.KEYSERVER_URL,
-  getAuthToken: async () => process.env.ATP_JWT
-})
+**Options:**
+1. No client-side limits (rely on server)
+2. Simple debouncing (prevent rapid duplicate requests)
+3. Full rate limit tracking (mirror server limits)
 
-// Encrypt a message
-const { ciphertext, version } = await client.encrypt(
-  'did:plc:abc123#followers',
-  'at://did:plc:abc123/app.bsky.feed.post/xyz789',
-  'Secret message for followers only'
-)
+**Current decision:** Option 2 (debouncing via request deduplication)
 
-console.log(`Encrypted (v${version}):`, ciphertext)
+### Cache Persistence
 
-// Decrypt a message
-const plaintext = await client.decrypt(
-  'did:plc:abc123#followers',
-  'at://did:plc:abc123/app.bsky.feed.post/xyz789',
-  ciphertext,
-  version
-)
+**Question:** Should keys be persisted to disk?
 
-console.log('Decrypted:', plaintext)
-```
+**Options:**
+1. Memory-only (current implementation)
+2. Encrypted disk cache (requires key derivation)
+3. Platform-specific secure storage (iOS Keychain, Android KeyStore)
 
----
+**Current decision:** Memory-only for security and simplicity
 
-## Bundle Size & Tree-Shaking
+**Rationale:**
+- Simpler implementation
+- Better security (no disk persistence)
+- Works across all platforms
+- User can implement custom cache if needed
 
-Modern bundlers (webpack, vite, rollup) automatically eliminate unused code through tree-shaking. This means developers can choose their level of abstraction without worrying about bundle size:
+### Error Recovery
 
-**Scenario 1: Just Crypto Functions**
-```typescript
-import { encryptMessage, decryptMessage } from '@atpkeyserver/client/crypto'
-// Bundled: ~52KB (@noble/ciphers + crypto.ts)
-// KeyserverClient, cache, and HTTP client code eliminated
-```
+**Question:** How should clients handle persistent decryption failures?
 
-**Scenario 2: Full Client with Caching**
-```typescript
-import { KeyserverClient } from '@atpkeyserver/client'
-// Bundled: ~60KB (includes everything)
-// Crypto functions included since client depends on them
-```
+**Options:**
+1. Fail silently (hide post)
+2. Show error message
+3. Retry with exponential backoff
+4. Prompt user action (e.g., "Request access")
 
-**Scenario 3: Both (Advanced)**
-```typescript
-import { KeyserverClient, encryptMessage } from '@atpkeyserver/client'
-// Bundled: ~60KB (same as scenario 2)
-// Manual crypto calls available alongside client methods
-```
+**Current decision:** Show error message, no retry (decryption failures are permanent)
 
-**Key Insight:** The crypto library (@noble/ciphers) represents 90%+ of the total bundle size. Whether you import crypto functions alone or the full client, the bundle size difference is only ~8-10KB. This validates the single-package approach - the maintenance complexity of separate packages isn't justified by such a small size difference.
+## Related Documentation
 
----
+- [Encryption Protocol](./ENCRYPTION_PROTOCOL.md) - Protocol specification
+- [Security Best Practices](./SECURITY.md) - Security guidelines
+- [API Reference](./API_REFERENCE.md) - Complete endpoint reference
+- [Architecture](./ARCHITECTURE.md) - Server architecture
+- [Client README](../packages/client/README.md) - Usage instructions
 
-## Success Metrics
+## Contributing
 
-**Performance Targets:**
-- Encryption operation: <1ms
-- Decryption operation: <5ms (including cache lookup)
-- Key fetch with cache hit: <1ms
-- Key fetch with cache miss: <200ms
-- **Service auth token fetch: <100ms (PDS round-trip)**
-- **Service auth token cache hit: <1ms**
+Contributions welcome! Please:
 
-**Developer Experience:**
-- Complete TypeScript types
-- Comprehensive documentation
-- Working examples for 3+ platforms
-- <5 minutes from npm install to first encrypted message
-- **Clear service auth integration patterns**
-- **Automatic token refresh handling**
+1. Read existing documentation
+2. Follow code style (Prettier)
+3. Add tests for new features
+4. Update documentation as needed
+5. Submit PR with clear description
 
-**Security:**
-- Zero plaintext exposure to server
-- All keys cached in memory only
-- **Service auth tokens cached for max 60 seconds**
-- Proper cleanup on logout (keys + tokens)
-- No key or token leakage in logs or errors
-- **Audience binding prevents token misuse**
-- **Short-lived tokens limit attack window**
+For questions, open an issue in the [Codeberg repository](https://codeberg.org/juandjara/atp-keyserver).

packages/client/README.md

···
 # @atpkeyserver/client
 
-Client library for ATP keyserver with end-to-end encryption support.
+TypeScript client library for ATP Keyserver with end-to-end encryption.
 
 ## Status
 
-🚧 **Under Development** - This package is currently being built.
+🚧 **Under Development** - Core crypto functions implemented, KeyserverClient in progress.
 
-## Overview
+## Features
 
-This client library provides:
-- End-to-end encryption functions (XChaCha20-Poly1305)
-- Type-safe keyserver API client
-- Automatic service auth token management
-- Built-in key caching
+- **End-to-end encryption** with XChaCha20-Poly1305
+- **Service auth integration** with ATProto PDS
+- **Automatic key caching** for performance
+- **TypeScript-first** with full type safety
+- **Tree-shakeable** ESM and CommonJS support
+- **Zero runtime dependencies** (except @noble/ciphers)
 
 ## Installation
 
 ```bash
 npm install @atpkeyserver/client
+# or
+bun add @atpkeyserver/client
 ```
 
 ## Quick Start
 
+### Using Crypto Functions Only
+
+If you want to handle key management manually:
+
 ```typescript
 import { encryptMessage, decryptMessage } from '@atpkeyserver/client/crypto'
 
 // Encrypt a message
+const messageId = 'at://did:plc:abc123/app.bsky.feed.post/xyz789'
+const secretKey = '0123456789abcdef...' // 64 hex chars (32 bytes)
+const plaintext = JSON.stringify({ text: 'Secret message' })
+
+const ciphertext = encryptMessage(messageId, secretKey, plaintext)
+// Returns: hex(nonce) + hex(ciphertext)
+
+// Decrypt a message
+const decrypted = decryptMessage(messageId, secretKey, ciphertext)
+const post = JSON.parse(decrypted)
+// Returns: { text: 'Secret message' }
+```
+
+### Using KeyserverClient (Coming Soon)
+
+Full-featured client with automatic caching and service auth:
+
+```typescript
+import { KeyserverClient } from '@atpkeyserver/client'
+import { AtpAgent } from '@atproto/api'
+
+// 1. Set up PDS client
+const agent = new AtpAgent({ service: 'https://bsky.social' })
+await agent.login({
+  identifier: 'user.bsky.social',
+  password: 'app-password'
+})
+
+// 2. Create keyserver client
+const keyserver = new KeyserverClient({
+  keyserverDid: 'did:web:keyserver.example.com',
+  getServiceAuthToken: async (aud, lxm) => {
+    const { token } = await agent.com.atproto.server.getServiceAuth({
+      aud,
+      lxm,
+      exp: Math.floor(Date.now() / 1000) + 60
+    })
+    return token
+  }
+})
+
+// 3. Encrypt a post
+const groupId = `${agent.session.did}#followers`
+const postUri = 'at://did:plc:abc123/app.bsky.feed.post/xyz789'
+const { ciphertext, version } = await keyserver.encrypt(
+  groupId,
+  postUri,
+  JSON.stringify({ text: 'Secret message for followers' })
+)
+
+// 4. Store encrypted post in PDS
+await agent.com.atproto.repo.createRecord({
+  repo: agent.session.did,
+  collection: 'app.bsky.feed.post',
+  record: {
+    encrypted_content: ciphertext,
+    key_version: version,
+    encrypted_at: new Date().toISOString(),
+    createdAt: new Date().toISOString()
+  }
+})
+
+// 5. Decrypt a post from feed
+const encryptedPost = await agent.getPost(postUri)
+const plaintext = await keyserver.decrypt(
+  groupId,
+  postUri,
+  encryptedPost.encrypted_content,
+  encryptedPost.key_version
+)
+const post = JSON.parse(plaintext)
+```
+
+## API Reference
+
+### Crypto Functions
+
+#### `encryptMessage(id, key, plaintext)`
+
+Encrypts plaintext using XChaCha20-Poly1305 with additional authenticated data.
+
+**Parameters:**
+- `id` (string): Message ID (AT-URI) used as AAD
+- `key` (string): Hex-encoded 32-byte secret key (64 hex characters)
+- `plaintext` (string): UTF-8 plaintext to encrypt
+
+**Returns:** `string` - Hex-encoded nonce (48 chars) + ciphertext
+
+**Example:**
+```typescript
 const ciphertext = encryptMessage(
-  'at://did:plc:abc123/app.bsky.feed.post/xyz',
-  secretKey,
+  'at://did:plc:abc123/app.bsky.feed.post/xyz789',
+  '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
   'Secret message'
 )
+```
 
-// Decrypt a message
+#### `decryptMessage(id, key, ciphertext)`
+
+Decrypts ciphertext using XChaCha20-Poly1305.
+
+**Parameters:**
+- `id` (string): Message ID (AT-URI) used as AAD (must match encryption)
+- `key` (string): Hex-encoded 32-byte secret key (64 hex characters)
+- `ciphertext` (string): Hex-encoded nonce + ciphertext from `encryptMessage`
+
+**Returns:** `string` - UTF-8 plaintext
+
+**Throws:** Error if:
+- AAD doesn't match (wrong message ID)
+- Key is incorrect
+- Ciphertext is corrupted
+- Authentication tag verification fails
+
+**Example:**
+```typescript
 const plaintext = decryptMessage(
-  'at://did:plc:abc123/app.bsky.feed.post/xyz',
-  secretKey,
-  ciphertext
+  'at://did:plc:abc123/app.bsky.feed.post/xyz789',
+  '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
+  '48a3f2c1...9b8d7e6f'
 )
 ```
 
-## Documentation
+### KeyserverClient (Coming Soon)
 
-See the [Client Implementation Guide](../../docs/CLIENT_IMPLEMENTATION.md) for complete documentation.
+#### Constructor
+
+```typescript
+new KeyserverClient(config: KeyserverClientConfig)
+```
+
+**Config Options:**
+```typescript
+interface KeyserverClientConfig {
+  keyserverDid: string                                    // DID of keyserver
+  getServiceAuthToken: (aud: string, lxm?: string) => Promise<string>  // Token provider
+  cache?: CacheOptions                                   // Optional cache config
+}
+
+interface CacheOptions {
+  activeKeyTtl?: number      // Active key TTL in seconds (default: 3600)
+  historicalKeyTtl?: number  // Historical key TTL in seconds (default: 86400)
+  maxSize?: number           // Max cache entries (default: 1000)
+}
+```
+
+#### `getGroupKey(groupId: string)`
+
+Fetch the active group key with automatic caching.
+
+**Parameters:**
+- `groupId` (string): Group ID in format `{owner_did}#{group_name}`
+
+**Returns:** `Promise<{ secretKey: string, version: number }>`
+
+**Throws:**
+- `UnauthorizedError` - Invalid or expired service auth token
+- `ForbiddenError` - User not a member of group
+- `NotFoundError` - Group doesn't exist
+- `NetworkError` - Network or server error
+
+#### `getGroupKeyVersion(groupId: string, version: number)`
+
+Fetch a specific historical key version with automatic caching.
+
+**Parameters:**
+- `groupId` (string): Group ID
+- `version` (number): Key version number
+
+**Returns:** `Promise<{ secretKey: string }>`
+
+#### `encrypt(groupId: string, messageId: string, plaintext: string)`
+
+Encrypt message with automatic key fetching.
+
+**Parameters:**
+- `groupId` (string): Group ID
+- `messageId` (string): Message ID (AT-URI)
+- `plaintext` (string): UTF-8 plaintext
+
+**Returns:** `Promise<{ ciphertext: string, version: number }>`
+
+#### `decrypt(groupId: string, messageId: string, ciphertext: string, version: number)`
+
+Decrypt message with automatic key fetching.
+
+**Parameters:**
+- `groupId` (string): Group ID
+- `messageId` (string): Message ID (AT-URI)
+- `ciphertext` (string): Hex-encoded nonce + ciphertext
+- `version` (number): Key version from encrypted record
+
+**Returns:** `Promise<string>` - Decrypted plaintext
+
+#### `clearCache()`
+
+Clear all cached keys and service auth tokens. Call on logout.
+
+```typescript
+keyserver.clearCache()
+```
+
+## Service Auth Integration
+
+The keyserver uses ATProto service auth for authentication. You need to provide a `getServiceAuthToken` callback that obtains tokens from the user's PDS.
+
+### With @atproto/api
+
+```typescript
+import { AtpAgent } from '@atproto/api'
+import { KeyserverClient } from '@atpkeyserver/client'
+
+const agent = new AtpAgent({ service: 'https://bsky.social' })
+await agent.login({ identifier: 'user.bsky.social', password: 'app-password' })
+
+const keyserver = new KeyserverClient({
+  keyserverDid: 'did:web:keyserver.example.com',
+  getServiceAuthToken: async (aud, lxm) => {
+    const { token } = await agent.com.atproto.server.getServiceAuth({
+      aud,
+      lxm,
+      exp: Math.floor(Date.now() / 1000) + 60
+    })
+    return token
+  }
+})
+```
+
+### With OAuth
+
+```typescript
+import { OAuthClient } from '@atproto/oauth-client'
+import { KeyserverClient } from '@atpkeyserver/client'
+
+const oauthClient = new OAuthClient({ /* config */ })
+await oauthClient.authorize({ scope: 'atproto transition:generic' })
+
+const keyserver = new KeyserverClient({
+  keyserverDid: 'did:web:keyserver.example.com',
+  getServiceAuthToken: async (aud, lxm) => {
+    // Implement service auth token fetch with OAuth
+    // See ENCRYPTION_PROTOCOL.md for details
+  }
+})
+```
+
+See [Encryption Protocol](../../docs/ENCRYPTION_PROTOCOL.md#authentication-flow) for complete service auth flow.
+
+## Caching Behavior
+
+### Key Caching
+
+The client automatically caches keys in memory for performance:
+
+- **Active keys:** 1 hour TTL (may change with rotation)
+- **Historical keys:** 24 hour TTL (immutable)
+- **LRU eviction:** When max size reached (default 1000 entries)
+
+Cache keys are formatted as `{groupId}:{version}` for precise version tracking.
+
+### Service Auth Token Caching
+
+Service auth tokens are cached with short TTL:
+
+- **TTL:** 60 seconds (or server-specified `exp`)
+- **Refresh:** Automatic when <10 seconds remain
+- **Memory-only:** Never persisted to disk
+
+### Cache Security
+
+- All caches are **memory-only** (never persisted)
+- Cleared automatically on logout (call `clearCache()`)
+- No sensitive data in cache keys
+
+See [Security Best Practices](../../docs/SECURITY.md#token-caching) for details.
+
+## Error Handling
+
+### Error Types
+
+```typescript
+import {
+  UnauthorizedError,      // 401 - Invalid/expired auth token
+  ForbiddenError,         // 403 - Not authorized for resource
+  NotFoundError,          // 404 - Resource doesn't exist
+  NetworkError,           // Network or server error
+  DecryptionError         // Decryption failed
+} from '@atpkeyserver/client'
+```
+
+### Handling Errors
+
+```typescript
+try {
+  const plaintext = await keyserver.decrypt(groupId, messageId, ciphertext, version)
+  return JSON.parse(plaintext)
+} catch (error) {
+  if (error instanceof ForbiddenError) {
+    // User lost access to group
+    return { error: 'You no longer have access to this content' }
+  } else if (error instanceof NotFoundError) {
+    // Group was deleted
+    return { error: 'This group no longer exists' }
+  } else if (error instanceof DecryptionError) {
+    // Corrupted data or wrong key
+    return { error: 'Cannot decrypt this message' }
+  } else if (error instanceof NetworkError) {
+    // Temporary network issue - could retry
+    throw error
+  } else {
+    // Unknown error
+    throw error
+  }
+}
+```
+
+### Automatic Retry
+
+Network errors (5xx, timeouts) are automatically retried with exponential backoff:
+- Max retries: 3 attempts
+- Backoff: 100ms, 200ms, 400ms
+
+Client errors (4xx) are NOT retried as they indicate permanent issues.
+
+## Platform Compatibility
+
+### Node.js
+
+Requires Node.js 22+ with native crypto support.
+
+```typescript
+import { encryptMessage } from '@atpkeyserver/client/crypto'
+```
+
+### Browser
+
+Works in all modern browsers with Web Crypto API:
+
+```typescript
+import { KeyserverClient } from '@atpkeyserver/client'
+```
+
+### React Native
+
+Requires crypto polyfills. See examples/ directory for setup.
+
+## Bundle Size
+
+Tree-shaking automatically eliminates unused code:
+
+| Import | Bundle Size (minified + gzipped) |
+|--------|----------------------------------|
+| `@atpkeyserver/client/crypto` | ~15KB |
+| `@atpkeyserver/client` | ~18KB |
+
+The crypto library (@noble/ciphers) represents 90% of bundle size.
+
+## Examples
+
+Check the `examples/` directory for complete implementations:
+
+- **basic-usage.ts** - Minimal crypto-only example
+- **react-hook.tsx** - React hooks for encrypted posts
+- **cli-example.ts** - Command-line encryption tool
+
+## Security
+
+### Best Practices
+
+- Never log keys or tokens to console/files
+- Never persist keys to localStorage without encryption
+- Always use HTTPS for keyserver communication
+- Clear cache on logout with `clearCache()`
+- Use AT-URI as message ID for AAD binding
+
+See [Security Best Practices](../../docs/SECURITY.md) for comprehensive guidelines.
+
+### Threat Model
+
+- **Client-side encryption**: Server never sees plaintext
+- **Short-lived tokens**: 60 second expiry limits attack window
+- **Audience binding**: Tokens valid only for specific keyserver
+- **No forward secrecy**: Old keys retained for compatibility (by design)
+
+See [Encryption Protocol](../../docs/ENCRYPTION_PROTOCOL.md#security-considerations) for details.
+
+## Contributing
+
+Contributions welcome! Please:
+
+1. Read [Client Implementation Strategy](../../docs/CLIENT_IMPLEMENTATION.md)
+2. Follow TypeScript and Prettier conventions
+3. Add tests for new features
+4. Update documentation as needed
 
 ## License
 
-MIT
+See [LICENSE.md](../../LICENSE.md)
+
+## Resources
+
+- [Encryption Protocol](../../docs/ENCRYPTION_PROTOCOL.md) - Protocol specification
+- [Security Best Practices](../../docs/SECURITY.md) - Security guidelines
+- [API Reference](../../docs/API_REFERENCE.md) - Complete endpoint reference
+- [Client Implementation](../../docs/CLIENT_IMPLEMENTATION.md) - Design decisions
+- [Server Architecture](../../docs/ARCHITECTURE.md) - Server architecture

packages/server/README.md

···
 4. **SSL/TLS**: Terminate SSL at reverse proxy.
 5. **Monitoring**: Monitor database size and access logs regularly.
 
-## Database
-
-SQLite database (`keyserver.db`) is created automatically on first run with:
-- Automatic schema migrations
-- WAL mode enabled for better concurrency
-
-**Note:** Ensure the database file is included in your backup strategy.
-
-## API Endpoints
-
-See [Architecture Documentation](../../docs/ARCHITECTURE.md#api-endpoints) for complete API reference.
-
-### Public Endpoints
-- `GET /` - Service metadata
-- `GET /.well-known/did.json` - Service DID document
-- `GET /xrpc/dev.atpkeyserver.alpha.key.public` - Get public key (no auth)
-
-### Protected Endpoints (require service auth token)
-- `GET /xrpc/dev.atpkeyserver.alpha.key` - Get keypair
-- `POST /xrpc/dev.atpkeyserver.alpha.key.rotate` - Rotate keypair
-- `GET /xrpc/dev.atpkeyserver.alpha.key.versions` - List key versions
-- `GET /xrpc/dev.atpkeyserver.alpha.key.accessLog` - Get key access logs
-- `GET /xrpc/dev.atpkeyserver.alpha.group.key` - Get group key
-- `POST /xrpc/dev.atpkeyserver.alpha.group.key.rotate` - Rotate group key
-- `GET /xrpc/dev.atpkeyserver.alpha.group.key.versions` - List group key versions
-- `POST /xrpc/dev.atpkeyserver.alpha.group.member.add` - Add group member
-- `POST /xrpc/dev.atpkeyserver.alpha.group.member.remove` - Remove group member
-
-## Security Considerations
-
-- Server never performs encryption or decryption
-- All keys are stored in SQLite with proper access controls
-- JWT tokens are verified via ATProto signing keys
-- Basic access logging allows for security monitoring
-- Key versioning prevents data loss
-
 ## License
 
 See [LICENSE.md](../../LICENSE.md)