The Complete Production SOP: How to Deploy and Run OAuth 2.0 PKCE Flow Authorization Verifier in Autonomous AI Agents

---
name: "oauth2-pkce-flow-verifier"
description: "Implement secure OAuth 2.0 authorization code flow with Proof Key for Code Exchange (PKCE)."
metadata:
  author: "IETF OAuth WG"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "implement oauth2 pkce"
  - "generate code challenge sha256"
  - "verify oauth state token"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# OAuth 2.0 PKCE Flow Authorization Verifier

1. Generate high-entropy code_verifier between 43 and 128 characters using crypto.getRandomValues() or crypto.randomBytes().
2. Compute code_challenge = base64url(sha256(code_verifier)). Never allow 'plain' method.
3. Verify returned state equals stored state prior to dispatching token exchange request.
4. Prohibit localStorage/sessionStorage persistence for exchanged Bearer access and refresh tokens.

import { webcrypto } from 'node:crypto';

export function generateRandomString(length: number = 64): string {
  const charset = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
  const randomValues = new Uint8Array(length);
  webcrypto.getRandomValues(randomValues);
  return Array.from(randomValues)
    .map((x) => charset[x % charset.length])
    .join('');
}

export async function generateCodeChallenge(verifier: string): Promise<string> {
  const encoder = new TextEncoder();
  const data = encoder.encode(verifier);
  const digest = await webcrypto.subtle.digest('SHA-256', data);
  return Buffer.from(digest)
    .toString('base64')
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');
}

import { describe, it, expect } from 'vitest';
import { generateRandomString, generateCodeChallenge } from '../../src/auth/pkce';

describe('PKCE Verification Test Suite', () => {
  it('generates verifier matching RFC 7636 length boundaries', () => {
    const verifier = generateRandomString(64);
    expect(verifier.length).toBeGreaterThanOrEqual(43);
    expect(verifier.length).toBeLessThanOrEqual(128);
    expect(verifier).toMatch(/^[A-Za-z0-9\-._~]+$/);
  });

  it('generates valid RFC 7636 code challenge without base64 padding', async () => {
    const verifier = 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk';
    const challenge = await generateCodeChallenge(verifier);
    expect(challenge).toBe('E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-wiM'.replace(/=+$/, ''));
    expect(challenge).not.toContain('=');
    expect(challenge).not.toContain('+');
    expect(challenge).not.toContain('/');
  });
});