chadtmiller.com/pds.js
An atproto PDS in JavaScript, for Cloudflare Workers and Node
0
0
# Direct Authorization Support Implementation Plan
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
**Goal:** Support direct OAuth authorization requests (without PAR) to match the official AT Protocol PDS behavior.
**Architecture:** When `/oauth/authorize` receives direct parameters instead of a `request_uri`, create an authorization request record on-the-fly (same as PAR does internally), then render the consent page. The token endpoint will bind DPoP at exchange time for direct auth flows.
**Tech Stack:** JavaScript, Cloudflare Workers, SQLite
---
## Task 1: Add Tests for Direct Authorization
**Files:**
- Modify: `test/e2e.test.js`
**Step 1: Write failing test for direct authorization GET**
Add this test in the `OAuth endpoints` describe block (after existing OAuth tests around line 1452):
```javascript
it('supports direct authorization without PAR', async () => {
const clientId = `http://localhost:${mockClientPort}/client-metadata.json`;
const redirectUri = `http://localhost:${mockClientPort}/callback`;
const codeVerifier = 'test-verifier-for-direct-auth-flow-min-43-chars!!';
const codeChallenge = await generateCodeChallenge(codeVerifier);
const state = 'test-direct-auth-state';
// Step 1: GET authorize with direct parameters (no PAR)
const authorizeUrl = new URL(`${BASE}/oauth/authorize`);
authorizeUrl.searchParams.set('client_id', clientId);
authorizeUrl.searchParams.set('redirect_uri', redirectUri);
authorizeUrl.searchParams.set('response_type', 'code');
authorizeUrl.searchParams.set('scope', 'atproto');
authorizeUrl.searchParams.set('code_challenge', codeChallenge);
authorizeUrl.searchParams.set('code_challenge_method', 'S256');
authorizeUrl.searchParams.set('state', state);
authorizeUrl.searchParams.set('login_hint', DID);
const getRes = await fetch(authorizeUrl.toString());
assert.strictEqual(getRes.status, 200, 'Direct authorize GET should succeed');
const html = await getRes.text();
assert.ok(html.includes('Authorize'), 'Should show consent page');
assert.ok(html.includes('request_uri'), 'Should include request_uri in form');
});
```
**Step 2: Run test to verify it fails**
Run: `npm test -- --grep "supports direct authorization"`
Expected: FAIL with "Direct authorize GET should succeed" - status will be 400 "Missing parameters"
**Step 3: Add test for full direct auth flow**
Add after the previous test:
```javascript
it('completes full direct authorization flow', async () => {
const clientId = `http://localhost:${mockClientPort}/client-metadata.json`;
const redirectUri = `http://localhost:${mockClientPort}/callback`;
const codeVerifier = 'test-verifier-for-direct-auth-flow-min-43-chars!!';
const codeChallenge = await generateCodeChallenge(codeVerifier);
const state = 'test-direct-auth-state';
// Step 1: GET authorize with direct parameters
const authorizeUrl = new URL(`${BASE}/oauth/authorize`);
authorizeUrl.searchParams.set('client_id', clientId);
authorizeUrl.searchParams.set('redirect_uri', redirectUri);
authorizeUrl.searchParams.set('response_type', 'code');
authorizeUrl.searchParams.set('scope', 'atproto');
authorizeUrl.searchParams.set('code_challenge', codeChallenge);
authorizeUrl.searchParams.set('code_challenge_method', 'S256');
authorizeUrl.searchParams.set('state', state);
authorizeUrl.searchParams.set('login_hint', DID);
const getRes = await fetch(authorizeUrl.toString());
assert.strictEqual(getRes.status, 200);
const html = await getRes.text();
// Extract request_uri from the form
const requestUriMatch = html.match(/name="request_uri" value="([^"]+)"/);
assert.ok(requestUriMatch, 'Should have request_uri in form');
const requestUri = requestUriMatch[1];
// Step 2: POST to authorize (user approval)
const authRes = await fetch(`${BASE}/oauth/authorize`, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
request_uri: requestUri,
client_id: clientId,
password: PASSWORD,
}).toString(),
redirect: 'manual',
});
assert.strictEqual(authRes.status, 302, 'Should redirect after approval');
const location = authRes.headers.get('location');
assert.ok(location, 'Should have Location header');
const locationUrl = new URL(location);
const code = locationUrl.searchParams.get('code');
assert.ok(code, 'Should have authorization code');
assert.strictEqual(locationUrl.searchParams.get('state'), state);
// Step 3: Exchange code for tokens
const { privateKey: dpopPrivateKey, publicJwk: dpopPublicJwk } =
await generateDpopKeyPair();
const dpopProof = await createDpopProof(
dpopPrivateKey,
dpopPublicJwk,
'POST',
`${BASE}/oauth/token`,
);
const tokenRes = await fetch(`${BASE}/oauth/token`, {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
DPoP: dpopProof,
},
body: new URLSearchParams({
grant_type: 'authorization_code',
code,
redirect_uri: redirectUri,
client_id: clientId,
code_verifier: codeVerifier,
}).toString(),
});
assert.strictEqual(tokenRes.status, 200, 'Token exchange should succeed');
const tokenData = await tokenRes.json();
assert.ok(tokenData.access_token, 'Should have access_token');
assert.strictEqual(tokenData.token_type, 'DPoP');
});
```
**Step 4: Run tests to verify they fail**
Run: `npm test -- --grep "direct authorization"`
Expected: Both tests FAIL
**Step 5: Commit test file**
```bash
git add test/e2e.test.js
git commit -m "test: add failing tests for direct OAuth authorization flow"
```
---
## Task 2: Extract Shared Validation Logic
**Files:**
- Modify: `src/pds.js:3737-3845` (handleOAuthPar method)
**Step 1: Create validateAuthorizationParameters helper**
Add this new method to the PersonalDataServer class, before `handleOAuthPar` (around line 3730):
```javascript
/**
* Validate OAuth authorization request parameters.
* Shared between PAR and direct authorization flows.
* @param {Object} params - The authorization parameters
* @param {string} params.clientId - The client_id
* @param {string} params.redirectUri - The redirect_uri
* @param {string} params.responseType - The response_type
* @param {string} [params.responseMode] - The response_mode
* @param {string} [params.scope] - The scope
* @param {string} [params.state] - The state
* @param {string} params.codeChallenge - The code_challenge
* @param {string} params.codeChallengeMethod - The code_challenge_method
* @param {string} [params.loginHint] - The login_hint
* @returns {Promise<{error: Response} | {clientMetadata: ClientMetadata}>}
*/
async validateAuthorizationParameters({
clientId,
redirectUri,
responseType,
codeChallenge,
codeChallengeMethod,
}) {
if (!clientId) {
return { error: errorResponse('invalid_request', 'client_id required', 400) };
}
if (!redirectUri) {
return { error: errorResponse('invalid_request', 'redirect_uri required', 400) };
}
if (responseType !== 'code') {
return {
error: errorResponse(
'unsupported_response_type',
'response_type must be code',
400,
),
};
}
if (!codeChallenge || codeChallengeMethod !== 'S256') {
return { error: errorResponse('invalid_request', 'PKCE with S256 required', 400) };
}
let clientMetadata;
try {
clientMetadata = await getClientMetadata(clientId);
} catch (err) {
return { error: errorResponse('invalid_client', err.message, 400) };
}
// Validate redirect_uri against registered URIs
const isLoopback =
clientId.startsWith('http://localhost') ||
clientId.startsWith('http://127.0.0.1');
const redirectUriValid = clientMetadata.redirect_uris.some((uri) => {
if (isLoopback) {
try {
const registered = new URL(uri);
const requested = new URL(redirectUri);
return registered.origin === requested.origin;
} catch {
return false;
}
}
return uri === redirectUri;
});
if (!redirectUriValid) {
return {
error: errorResponse(
'invalid_request',
'redirect_uri not registered for this client',
400,
),
};
}
return { clientMetadata };
}
```
**Step 2: Run existing tests to verify nothing broke**
Run: `npm test`
Expected: All existing tests PASS (new method not called yet)
**Step 3: Commit**
```bash
git add src/pds.js
git commit -m "refactor: extract validateAuthorizationParameters helper"
```
---
## Task 3: Refactor handleOAuthPar to Use Shared Validation
**Files:**
- Modify: `src/pds.js:3737-3845` (handleOAuthPar method)
**Step 1: Update handleOAuthPar to use the new helper**
Replace the validation section in `handleOAuthPar` (lines ~3760-3815) with:
```javascript
async handleOAuthPar(request, url) {
// Opportunistically clean up expired authorization requests
this.cleanupExpiredAuthorizationRequests();
const issuer = `${url.protocol}//${url.host}`;
const dpopResult = await this.validateRequiredDpop(
request,
'POST',
`${issuer}/oauth/par`,
);
if ('error' in dpopResult) return dpopResult.error;
const { dpop } = dpopResult;
// Parse body - support both JSON and form-encoded
/** @type {Record<string, string|undefined>} */
let data;
try {
data = await parseRequestBody(request);
} catch {
return errorResponse('invalid_request', 'Invalid JSON body', 400);
}
const clientId = data.client_id;
const redirectUri = data.redirect_uri;
const responseType = data.response_type;
const responseMode = data.response_mode;
const scope = data.scope;
const state = data.state;
const codeChallenge = data.code_challenge;
const codeChallengeMethod = data.code_challenge_method;
const loginHint = data.login_hint;
// Use shared validation
const validationResult = await this.validateAuthorizationParameters({
clientId,
redirectUri,
responseType,
codeChallenge,
codeChallengeMethod,
});
if ('error' in validationResult) return validationResult.error;
const { clientMetadata } = validationResult;
const requestId = crypto.randomUUID();
const requestUri = `urn:ietf:params:oauth:request_uri:${requestId}`;
const expiresIn = 600;
const expiresAt = new Date(Date.now() + expiresIn * 1000).toISOString();
this.sql.exec(
`INSERT INTO authorization_requests (
id, client_id, client_metadata, parameters,
code_challenge, code_challenge_method, dpop_jkt,
expires_at, created_at
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
requestId,
clientId,
JSON.stringify(clientMetadata),
JSON.stringify({
redirect_uri: redirectUri,
scope,
state,
response_mode: responseMode,
login_hint: loginHint,
}),
codeChallenge,
codeChallengeMethod,
dpop.jkt,
expiresAt,
new Date().toISOString(),
);
return Response.json({ request_uri: requestUri, expires_in: expiresIn });
}
```
**Step 2: Run all OAuth tests to verify PAR still works**
Run: `npm test -- --grep OAuth`
Expected: All existing OAuth tests PASS
**Step 3: Commit**
```bash
git add src/pds.js
git commit -m "refactor: use validateAuthorizationParameters in handleOAuthPar"
```
---
## Task 4: Implement Direct Authorization in handleOAuthAuthorizeGet
**Files:**
- Modify: `src/pds.js:3869-3911` (handleOAuthAuthorizeGet method)
**Step 1: Update handleOAuthAuthorizeGet to handle direct parameters**
Replace the entire `handleOAuthAuthorizeGet` method:
```javascript
/**
* Handle GET /oauth/authorize - displays the consent UI.
* Supports both PAR (request_uri) and direct authorization parameters.
* @param {URL} url - Parsed request URL
* @returns {Promise<Response>} HTML consent page
*/
async handleOAuthAuthorizeGet(url) {
// Opportunistically clean up expired authorization requests
this.cleanupExpiredAuthorizationRequests();
const requestUri = url.searchParams.get('request_uri');
const clientId = url.searchParams.get('client_id');
// If request_uri is present, use PAR flow
if (requestUri) {
if (!clientId) {
return new Response('Missing client_id parameter', { status: 400 });
}
const match = requestUri.match(/^urn:ietf:params:oauth:request_uri:(.+)$/);
if (!match) return new Response('Invalid request_uri', { status: 400 });
const rows = this.sql
.exec(
`SELECT * FROM authorization_requests WHERE id = ? AND client_id = ?`,
match[1],
clientId,
)
.toArray();
const authRequest = rows[0];
if (!authRequest) return new Response('Request not found', { status: 400 });
if (new Date(/** @type {string} */ (authRequest.expires_at)) < new Date())
return new Response('Request expired', { status: 400 });
if (authRequest.code)
return new Response('Request already used', { status: 400 });
const clientMetadata = JSON.parse(
/** @type {string} */ (authRequest.client_metadata),
);
const parameters = JSON.parse(
/** @type {string} */ (authRequest.parameters),
);
return new Response(
renderConsentPage({
clientName: clientMetadata.client_name || clientId,
clientId: clientId || '',
scope: parameters.scope || 'atproto',
requestUri: requestUri || '',
}),
{ status: 200, headers: { 'Content-Type': 'text/html; charset=utf-8' } },
);
}
// Direct authorization flow - create request on-the-fly
if (!clientId) {
return new Response('Missing client_id parameter', { status: 400 });
}
const redirectUri = url.searchParams.get('redirect_uri');
const responseType = url.searchParams.get('response_type');
const responseMode = url.searchParams.get('response_mode');
const scope = url.searchParams.get('scope');
const state = url.searchParams.get('state');
const codeChallenge = url.searchParams.get('code_challenge');
const codeChallengeMethod = url.searchParams.get('code_challenge_method');
const loginHint = url.searchParams.get('login_hint');
// Validate parameters using shared helper
const validationResult = await this.validateAuthorizationParameters({
clientId,
redirectUri,
responseType,
codeChallenge,
codeChallengeMethod,
});
if ('error' in validationResult) return validationResult.error;
const { clientMetadata } = validationResult;
// Create authorization request record (same as PAR but without DPoP)
const requestId = crypto.randomUUID();
const newRequestUri = `urn:ietf:params:oauth:request_uri:${requestId}`;
const expiresIn = 600;
const expiresAt = new Date(Date.now() + expiresIn * 1000).toISOString();
this.sql.exec(
`INSERT INTO authorization_requests (
id, client_id, client_metadata, parameters,
code_challenge, code_challenge_method, dpop_jkt,
expires_at, created_at
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
requestId,
clientId,
JSON.stringify(clientMetadata),
JSON.stringify({
redirect_uri: redirectUri,
scope,
state,
response_mode: responseMode,
login_hint: loginHint,
}),
codeChallenge,
codeChallengeMethod,
null, // No DPoP for direct authorization - will be bound at token exchange
expiresAt,
new Date().toISOString(),
);
return new Response(
renderConsentPage({
clientName: clientMetadata.client_name || clientId,
clientId: clientId,
scope: scope || 'atproto',
requestUri: newRequestUri,
}),
{ status: 200, headers: { 'Content-Type': 'text/html; charset=utf-8' } },
);
}
```
**Step 2: Run the first direct auth test**
Run: `npm test -- --grep "supports direct authorization without PAR"`
Expected: PASS
**Step 3: Commit**
```bash
git add src/pds.js
git commit -m "feat: support direct authorization in handleOAuthAuthorizeGet"
```
---
## Task 5: Update Token Endpoint for Null DPoP Binding
**Files:**
- Modify: `src/pds.js:4097-4098` (handleAuthCodeGrant method)
**Step 1: Update DPoP validation to handle null dpop_jkt**
Find the DPoP check in `handleAuthCodeGrant` (around line 4097) and replace:
```javascript
if (authRequest.dpop_jkt !== dpop.jkt)
return errorResponse('invalid_dpop_proof', 'DPoP key mismatch', 400);
```
With:
```javascript
// For PAR flow, dpop_jkt is set at PAR time and must match
// For direct authorization, dpop_jkt is null and we bind to the token request's DPoP
if (authRequest.dpop_jkt !== null && authRequest.dpop_jkt !== dpop.jkt) {
return errorResponse('invalid_dpop_proof', 'DPoP key mismatch', 400);
}
```
**Step 2: Run full direct auth flow test**
Run: `npm test -- --grep "completes full direct authorization flow"`
Expected: PASS
**Step 3: Run all OAuth tests to verify nothing broke**
Run: `npm test -- --grep OAuth`
Expected: All OAuth tests PASS
**Step 4: Commit**
```bash
git add src/pds.js
git commit -m "feat: allow null dpop_jkt binding for direct authorization"
```
---
## Task 6: Update AS Metadata
**Files:**
- Modify: `src/pds.js:3695` (handleOAuthAuthServerMetadata method)
**Step 1: Change require_pushed_authorization_requests to false**
Find line 3695 and change:
```javascript
require_pushed_authorization_requests: true,
```
To:
```javascript
require_pushed_authorization_requests: false,
```
**Step 2: Update the e2e test expectation**
Find the AS metadata test in `test/e2e.test.js` (around line 541) and change:
```javascript
assert.strictEqual(data.require_pushed_authorization_requests, true);
```
To:
```javascript
assert.strictEqual(data.require_pushed_authorization_requests, false);
```
**Step 3: Run tests**
Run: `npm test`
Expected: All tests PASS
**Step 4: Commit**
```bash
git add src/pds.js test/e2e.test.js
git commit -m "feat: set require_pushed_authorization_requests to false"
```
---
## Task 7: Final Verification
**Step 1: Run all tests**
Run: `npm test`
Expected: All tests PASS
**Step 2: Manual verification with the original URL**
Test that the original failing URL now works by deploying to your worker and visiting:
```
https://chad-pds.chad-53c.workers.dev/oauth/authorize?client_id=https%3A%2F%2Fquickslice-production-9cf4.up.railway.app%2Foauth-client-metadata.json&redirect_uri=https%3A%2F%2Fquickslice-production-9cf4.up.railway.app%2Foauth%2Fatp%2Fcallback&response_type=code&code_challenge=v9w-ACgE-QauiZkLpSDeZTjgGDmGdVHbegFe18dkQSw&code_challenge_method=S256&state=QkxYNYrf73X0rLaU6XBUyg&scope=atproto%20...&login_hint=did%3Aplc%3Ac6vxslynzebnlk5kw2orx37o
```
Expected: Should show consent page instead of "Missing parameters" error
**Step 3: Final commit (if any cleanup needed)**
```bash
git add -A
git commit -m "chore: cleanup after direct authorization implementation"
```
---
## Summary
This implementation:
1. **Extracts shared validation** - `validateAuthorizationParameters()` is used by both PAR and direct auth
2. **Creates request records on-the-fly** - Direct auth creates the same DB record as PAR, just without DPoP binding
3. **Defers DPoP binding** - For direct auth, DPoP is bound at token exchange time instead of request time
4. **Updates metadata** - Sets `require_pushed_authorization_requests: false` to signal clients that PAR is optional
5. **Maintains backwards compatibility** - PAR flow continues to work exactly as before