Feature Request: Simplify ATProto OAuth Setup (Remove Manual JWK Requirement)

[daviddao]

Describe the feature you'd like to request

Problem

The current createATProtoSDK function requires developers to manually generate and manage JWK (JSON Web Key) pairs for DPoP authentication:

const sdk = createATProtoSDK({
  oauth: {
    clientId: "https://your-app.com/client-metadata.json",
    redirectUri: "https://your-app.com/callback",
    scope: "atproto",
    jwksUri: "https://your-app.com/.well-known/jwks.json",  // Must host public key
    jwkPrivate: process.env.ATPROTO_JWK_PRIVATE!,            // Must generate & store private key
  },
});

This creates significant friction for developers because they must:

1. Generate JWK key pairs - Learn cryptographic key generation tools or libraries
2. Host public keys - Create and maintain a /.well-known/jwks.json endpoint
3. Securely store private keys - Set up environment variables and secrets management
4. Understand DPoP - Learn OAuth 2.0 DPoP specification details

This complexity is a barrier to adoption, especially for developers who just want to add ATProto authentication to their app.

Current Workaround

Developers currently use the lower-level @atproto/oauth-client-node package directly, which auto-generates DPoP keys:

import { NodeOAuthClient } from '@atproto/oauth-client-node'

const client = new NodeOAuthClient({
  clientMetadata: {
    client_name: 'My App',
    client_id: `${publicUrl}/api/oauth/client-metadata.json`,
    redirect_uris: [`${publicUrl}/api/oauth/callback`],
    scope: 'atproto',
    dpop_bound_access_tokens: true,
  },
})

However, this means:

• Missing out on Hypercerts SDK features like sdk.repository(session)
• Having to implement ATProto record storage manually
• Duplicating authentication logic that the SDK should handle

Describe the solution you'd like

Proposed Solution

Make JWK setup optional with automatic key generation as the default:

Option 1: Auto-generate keys (default behavior)

const sdk = createATProtoSDK({
  oauth: {
    clientId: "https://your-app.com/client-metadata.json",
    redirectUri: "https://your-app.com/callback",
    scope: "atproto",
    // No jwksUri or jwkPrivate needed! SDK handles it internally
  },
});

The SDK would:

• Auto-generate ephemeral JWK pairs on initialization
• Handle DPoP signing internally
• Store keys in the session/state stores provided

Option 2: Advanced users can still provide custom keys

const sdk = createATProtoSDK({
  oauth: {
    clientId: "https://your-app.com/client-metadata.json",
    redirectUri: "https://your-app.com/callback",
    scope: "atproto",
    // Optional: for advanced use cases
    jwksUri: "https://your-app.com/.well-known/jwks.json",
    jwkPrivate: process.env.ATPROTO_JWK_PRIVATE,
  },
});

Benefits

1. Lower barrier to entry - Developers can get started immediately without crypto knowledge
2. Better DX - Matches expectations from other OAuth libraries (simpler = better)
3. Fewer configuration errors - Auto-generation eliminates key generation mistakes
4. Increased adoption - More developers will use Hypercerts SDK instead of raw @atproto/oauth-client-node
5. Still supports advanced use cases - Power users can still bring their own keys

Implementation Notes

The underlying @atproto/oauth-client-node already supports auto-generation of DPoP keys. The SDK could:

1. Check if jwksUri and jwkPrivate are provided
2. If not provided, let the OAuth client auto-generate keys
3. Store generated keys in the session store for persistence across requests
4. Provide a helper method to export keys if users want to persist them:

   const keys = await sdk.exportDpopKeys()
   // Save to database/file system for reuse

Related Work

• @atproto/oauth-client-node - Already implements automatic DPoP key generation
• Other OAuth libraries (NextAuth, Auth.js, Passport) - Don't require manual crypto key management
• AT Protocol OAuth spec - DPoP is transparent to most application developers

Use Case

I'm building a hyperboard management tool and want to use ATProto authentication. The current JWK requirement is blocking me from using the Hypercerts SDK's repository() API, forcing me to either:

• Use raw OAuth client and lose SDK features
• Spend hours learning JWK generation (tangential to my actual feature)

Making JWK setup optional would let me authenticate users in minutes instead of hours.

Describe alternatives you've considered

Not using the SDK

[Kzoeps]

Technical Analysis: JWK Requirements in ATProto OAuth

Thank you for this feature request! I've done a deep dive into the documentation and our SDK implementation to clarify what's actually possible here.

TL;DR

The request is partially valid but the claim about "auto-generation" is misleading. There's no automatic JWK generation - instead, there are two distinct OAuth client modes with different trade-offs.

---

What ATProto OAuth Actually Supports

The @atproto/oauth-client-node package supports two authentication modes:

Mode 1: Backend Service (Current SDK Implementation)

const client = new NodeOAuthClient({
  clientMetadata: {
    token_endpoint_auth_method: 'private_key_jwt',  // Requires JWK
    dpop_bound_access_tokens: true,
    jwks_uri: 'https://my-app.com/jwks.json',
  },
  keyset: [/* JWK keys - REQUIRED */],
  // ...
})

Characteristics:

• ✅ Long session lifetimes
• ✅ Higher security (client authenticates to auth server)
• ❌ Requires JWK key generation and hosting

Mode 2: Native Application (Public Client)

const client = await NodeOAuthClient.fromClientId({
  clientId: 'https://my-app.com/client-metadata.json',
  // NO keyset parameter
  stateStore: {...},
  sessionStore: {...},
})

Characteristics:

• ✅ No JWK required (token_endpoint_auth_method: 'none')
• ✅ Simpler setup
• ⚠️ Shorter session lifetimes
• ⚠️ Lower security (client cannot authenticate itself)

From the ATProto OAuth docs:

"There is no keyset in this instance. This is due to the fact that app clients cannot safely store a private key. The token_endpoint_auth_method is set to none in the client metadata, which means that the client will not be authenticating itself to the token endpoint. This will cause sessions to have a shorter lifetime."

---

What This Means for the Hypercerts SDK

There is NO automatic JWK generation. Instead, we could support both modes:

Configuration	Mode	Session Lifetime	Use Case
Provide jwkPrivate + jwksUri	private_key_jwt	Long	Web backends (recommended)
Omit JWK fields	none	Short	Native apps, prototyping

---

Recommendation

We could implement this feature, but it should be clear that:

1. This is NOT about auto-generation - it's about supporting unauthenticated public clients
2. Sessions will be shorter-lived without JWK authentication
3. Web backends should still use JWKs for production

Questions Before Implementation

1. Is the shorter session lifetime acceptable for your use case?
2. Are you building a native app or web backend?
   • Native apps: This feature makes sense
   • Web backends: JWK is still recommended for production
3. Would you be okay with prominent warnings in the docs about the trade-offs?

---

Alternative: Better DX for JWK Generation

Instead of removing the JWK requirement, we could improve the developer experience by:

1. CLI tool to generate JWKs: npx @hypercerts-org/sdk generate-keys
2. Better documentation with copy-paste examples
3. Helper functions in the SDK:

   import { generateJWK } from '@hypercerts-org/sdk-core/utils'
   const { publicKey, privateKey } = await generateJWK()

This would maintain security best practices while reducing friction.

---

Let me know your thoughts! Happy to discuss the trade-offs or help implement whichever approach makes sense for your use case.

[Kzoeps]

sorry for the ai spam. just wanted to try it out and see what it says