Merge pull request #127 from Kzoeps/75-sdk-operations-only-work-on-pds-registered-in-sdk-instance

feat(sdk-core): auto-detect PDS URL from OAuth session

Author: aspiers

.changeset/auto-detect-pds-from-session.md

@@ -0,0 +1,39 @@
+---
+"@hypercerts-org/sdk-core": minor
+---
+
+Auto-detect user's PDS URL from OAuth session instead of requiring static configuration
+
+**Breaking Changes:**
+
+- `servers.pds` config option has been removed. The user's PDS URL is now automatically detected from the OAuth
+  session's token info (`tokenInfo.aud`) during `callback()` and `restoreSession()`. This means the SDK correctly routes
+  operations to each user's actual PDS regardless of which server they're hosted on.
+- A new `handleResolver` config option replaces `servers.pds` for its handle resolution role during OAuth authorization.
+  This is optional — if omitted, DNS-based resolution is used.
+- `getAccountEmail()` no longer requires `servers.pds` to be configured, since it uses the session's fetch handler which
+  internally routes to the correct PDS.
+- `sdk.repository()` is now async (returns `Promise<Repository>`). On cache miss it automatically resolves the PDS from
+  the session's token info, so callers no longer need to manually call `resolveSessionPds()` first.
+
+**New APIs:**
+
+- `sdk.resolveSessionPds(session)` — Manually resolve and cache a session's PDS URL. Useful for pre-warming the cache or
+  for sessions created outside the SDK's auth flow.
+
+**Migration:**
+
+```typescript
+// Before
+const sdk = createATProtoSDK({
+  oauth: { ... },
+  servers: { pds: "https://bsky.social", sds: "https://sds.example.com" },
+});
+
+// After
+const sdk = createATProtoSDK({
+  oauth: { ... },
+  handleResolver: "https://bsky.social", // optional, for handle resolution only
+  servers: { sds: "https://sds.example.com" },
+});
+```

CERTS_SDK.md

@@ -53,7 +53,7 @@ Host a `client-metadata.json` file at a public URL (e.g., `https://your-app.com/
 # .env.local
 NEXT_PUBLIC_OAUTH_CLIENT_ID=https://your-app.com/client-metadata.json
 NEXT_PUBLIC_OAUTH_REDIRECT_URI=https://your-app.com/callback
-NEXT_PUBLIC_PDS_URL=https://bsky.social
+NEXT_PUBLIC_HANDLE_RESOLVER_URL=https://bsky.social
 NEXT_PUBLIC_SDS_URL=https://sds.hypercerts.org
 JWK_PRIVATE_KEY={"kty":"EC","crv":"P-256",...}
 ```
@@ -86,8 +86,9 @@ export const atproto = createATProtoReact({
       redirectUri: process.env.NEXT_PUBLIC_OAUTH_REDIRECT_URI!,
       scope: "atproto transition:generic",
     },
+    // Optional: URL for handle resolution during OAuth (defaults to DNS-based resolution)
+    handleResolver: process.env.NEXT_PUBLIC_HANDLE_RESOLVER_URL || "https://bsky.social",
     servers: {
-      pds: process.env.NEXT_PUBLIC_PDS_URL || "https://bsky.social",
       sds: process.env.NEXT_PUBLIC_SDS_URL,
     },
   },
@@ -565,8 +566,8 @@ const sdk = new ATProtoSDK({
     jwksUri: `${process.env.NEXT_PUBLIC_APP_URL}/.well-known/jwks.json`,
     jwkPrivate: process.env.JWK_PRIVATE_KEY!,
   },
+  handleResolver: process.env.NEXT_PUBLIC_HANDLE_RESOLVER_URL || "https://bsky.social",
   servers: {
-    pds: process.env.NEXT_PUBLIC_PDS_URL || "https://bsky.social",
     sds: process.env.NEXT_PUBLIC_SDS_URL,
   },
 });
@@ -673,8 +674,8 @@ export const atproto = createATProtoReact({
       redirectUri: process.env.NEXT_PUBLIC_OAUTH_REDIRECT_URI!,
       scope: "atproto transition:generic",
     },
+    handleResolver: process.env.NEXT_PUBLIC_HANDLE_RESOLVER_URL || "https://bsky.social",
     servers: {
-      pds: process.env.NEXT_PUBLIC_PDS_URL || "https://bsky.social",
       sds: process.env.NEXT_PUBLIC_SDS_URL,
     },
   },

packages/sdk-core/README.md

@@ -20,11 +20,9 @@ const sdk = createATProtoSDK({
     jwksUri: "https://your-app.com/jwks.json",
     jwkPrivate: process.env.ATPROTO_JWK_PRIVATE!,
   },
-  // set up with your pds url.
-  // entryway doesn't work for this. Has to be a PDS URL.
-  servers: {
-    pds: "https://pds-eu-west4.test.certified.app",
-  },
+  // Optional: URL for handle resolution during OAuth.
+  // If omitted, DNS-based resolution is used.
+  handleResolver: "https://pds-eu-west4.test.certified.app",
 });
 
 // 2. Authenticate user
@@ -80,10 +78,8 @@ const sdk = createATProtoSDK({
     // Optional: suppress warnings
     developmentMode: true,
   },
-  servers: {
-    // Point to local PDS for testing
-    pds: "http://localhost:2583",
-  },
+  // Optional: handle resolver for local testing
+  handleResolver: "http://localhost:2583",
   logger: console, // Enable debug logging
 });
 
@@ -155,17 +151,17 @@ The SDK supports two types of AT Protocol servers:
 - **Purpose**: User's own data storage (e.g., Bluesky)
 - **Use case**: Individual hypercerts, personal records
 - **Features**: Profile management, basic CRUD operations
-- **Example**: `bsky.social`, any Bluesky PDS
+- **Auto-detected**: The SDK automatically discovers the user's PDS from the OAuth session -- no configuration needed
 
 #### Shared Data Server (SDS)
 
 - **Purpose**: Collaborative data storage with access control
 - **Use case**: Organization hypercerts, team collaboration
 - **Features**: Organizations, multi-user access, role-based permissions
-- **Example**: `sds.hypercerts.org`
+- **Configured via**: `servers.sds` in SDK config
 
 ```typescript
-// Connect to user's PDS (default)
+// Connect to user's PDS (default) -- auto-detected from session
 const pdsRepo = sdk.repository(session);
 await pdsRepo.hypercerts.create({ ... }); // Creates in user's PDS
 
@@ -179,20 +175,34 @@ const orgRepo = sdsRepo.repo(orgs.organizations[0].did);
 await orgRepo.hypercerts.list(); // Queries organization's hypercerts on SDS
 ```
 
+#### How PDS Auto-Detection Works
+
+The SDK automatically discovers each user's PDS URL from their OAuth session. You do not need to configure a PDS URL.
+
+1. **During authentication** (`callback()` or `restoreSession()`), the SDK extracts the user's PDS URL from the OAuth
+   token's `aud` field, which is resolved from the user's DID Document.
+
+2. **When creating a repository** (`sdk.repository(session)`), the SDK uses the cached PDS URL for that session's DID.
+
+3. **For sessions created outside the SDK**, you can manually resolve the PDS:
+   ```typescript
+   await sdk.resolveSessionPds(session);
+   ```
+
 #### How Repository Routing Works
 
 The SDK uses a `ConfigurableAgent` to route requests to different servers while maintaining your OAuth authentication:
 
 1. **Initial Repository Creation**
 
    ```typescript
-   // User authenticates (OAuth session knows user's PDS)
+   // User authenticates -- PDS URL is automatically cached from the session
    const session = await sdk.callback(params);
 
-   // Create PDS repository - routes to user's PDS
+   // Create PDS repository -- routes to user's auto-detected PDS
    const pdsRepo = sdk.repository(session);
 
-   // Create SDS repository - routes to SDS server
+   // Create SDS repository -- routes to configured SDS server
    const sdsRepo = sdk.repository(session, { server: "sds" });
    ```
 
@@ -206,21 +216,22 @@ The SDK uses a `ConfigurableAgent` to route requests to different servers while
    const orgRepo = userSdsRepo.repo("did:plc:org-did");
 
    // All operations on orgRepo still route to SDS, not user's PDS
-   await orgRepo.hypercerts.list(); // ✅ Queries SDS
-   await orgRepo.collaborators.list(); // ✅ Queries SDS
+   await orgRepo.hypercerts.list(); // Queries SDS
+   await orgRepo.collaborators.list(); // Queries SDS
    ```
 
 3. **Key Implementation Details**
    - Each Repository uses a `ConfigurableAgent` that wraps your OAuth session's fetch handler
    - The agent routes all requests to the specified server URL (PDS, SDS, or custom)
+   - The user's PDS URL is auto-detected from the OAuth session's token info (`tokenInfo.aud`)
    - When you call `.repo(did)`, a new Repository is created with the same server configuration
    - Your OAuth session provides authentication (DPoP, access tokens), while the agent handles routing
    - This enables simultaneous connections to multiple servers with one authentication session
 
 #### Common Patterns
 
 ```typescript
-// Pattern 1: Personal hypercerts on PDS
+// Pattern 1: Personal hypercerts on PDS (auto-detected)
 const myRepo = sdk.repository(session);
 await myRepo.hypercerts.create({ title: "My Personal Impact" });
 

packages/sdk-core/src/auth/OAuthClient.ts

@@ -52,7 +52,7 @@ interface AuthorizeOptions {
  *     jwksUri: "https://my-app.com/.well-known/jwks.json",
  *     jwkPrivate: process.env.JWK_PRIVATE_KEY!,
  *   },
- *   servers: { pds: "https://bsky.social" },
+ *   handleResolver: "https://pds-eu-west4.test.certified.app",
  * });
  *
  * // Start authorization
@@ -146,7 +146,7 @@ export class OAuthClient {
       keyset,
       stateStore: this.createStateStoreAdapter(stateStore),
       sessionStore: this.createSessionStoreAdapter(sessionStore),
-      handleResolver: this.config.servers?.pds,
+      handleResolver: this.config.handleResolver,
       fetch: this.config.fetch ?? fetchWithTimeout,
     });