Skip to content

majiayu000/spellbook / skills/auth-security

auth-security

Verified

OAuth 2.1 + JWT authentication security best practices. Use when implementing auth, API authorization, token management. Follows RFC 9700 (2025).

FileKindSize
SKILL.mdskill md10.8 KB
reference/attacks.mdmarkdown7.8 KB
reference/jwt.mdmarkdown8.0 KB
reference/oauth2.1.mdmarkdown8.6 KB
templates/typescript/auth.service.tsscript8.2 KB

reference/oauth2.1.md

View on GitHub
# OAuth 2.1 Deep Dive

## RFC 9700 Summary

Published January 2025, consolidates security best practices from:
- RFC 6749 (OAuth 2.0)
- RFC 7636 (PKCE)
- RFC 8252 (Native Apps)
- RFC 6819 (Threat Model)
- Various security BCPs

---

## Grant Types

### Authorization Code (REQUIRED)

The only grant type for user authentication.

```
┌──────────┐     ┌───────────┐     ┌──────────────┐
│  Client  │────▶│   Auth    │────▶│   Resource   │
│   App    │◀────│  Server   │◀────│    Server    │
└──────────┘     └───────────┘     └──────────────┘

1. Client redirects to Auth Server with PKCE challenge
2. User authenticates
3. Auth Server redirects back with code
4. Client exchanges code + verifier for tokens
5. Client accesses Resource Server with access token
```

### Client Credentials

For server-to-server communication (no user context).

```typescript
const response = await fetch('https://auth.example.com/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    Authorization: `Basic ${btoa(`${clientId}:${clientSecret}`)}`,
  },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    scope: 'api:read api:write',
  }),
});
```

### Refresh Token

For obtaining new access tokens without re-authentication.

```typescript
const response = await fetch('https://auth.example.com/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'refresh_token',
    refresh_token: currentRefreshToken,
    client_id: CLIENT_ID,
  }),
});

const { access_token, refresh_token } = await response.json();
// IMPORTANT: Store new refresh_token, old one is invalidated
```

---

## PKCE Implementation

### Code Verifier Requirements

- Length: 43-128 characters
- Characters: `[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"`
- Must be cryptographically random

```typescript
function generateCodeVerifier(): string {
  // 32 bytes = 43 base64url characters
  const buffer = crypto.randomBytes(32);
  return buffer.toString('base64url');
}
```

### Code Challenge

```typescript
// S256 method (REQUIRED if supported)
function generateCodeChallenge(verifier: string): string {
  return crypto
    .createHash('sha256')
    .update(verifier)
    .digest('base64url');
}

// Plain method (only if S256 not supported)
// NOT RECOMMENDED - only for legacy compatibility
function generatePlainChallenge(verifier: string): string {
  return verifier;
}
```

### Full PKCE Flow

```typescript
class PKCEFlow {
  private verifier: string;
  private state: string;

  constructor() {
    this.verifier = generateCodeVerifier();
    this.state = crypto.randomBytes(16).toString('hex');
  }

  getAuthorizationUrl(config: AuthConfig): string {
    const url = new URL(config.authorizationEndpoint);

    url.searchParams.set('response_type', 'code');
    url.searchParams.set('client_id', config.clientId);
    url.searchParams.set('redirect_uri', config.redirectUri);
    url.searchParams.set('scope', config.scope);
    url.searchParams.set('state', this.state);
    url.searchParams.set('code_challenge', generateCodeChallenge(this.verifier));
    url.searchParams.set('code_challenge_method', 'S256');

    // OpenID Connect
    if (config.scope.includes('openid')) {
      url.searchParams.set('nonce', crypto.randomBytes(16).toString('hex'));
    }

    return url.toString();
  }

  async exchangeCode(code: string, receivedState: string, config: AuthConfig): Promise<TokenResponse> {
    // Validate state
    if (receivedState !== this.state) {
      throw new Error('State mismatch - possible CSRF attack');
    }

    const response = await fetch(config.tokenEndpoint, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'authorization_code',
        code,
        redirect_uri: config.redirectUri,
        client_id: config.clientId,
        code_verifier: this.verifier,
      }),
    });

    if (!response.ok) {
      const error = await response.json();
      throw new AuthError(error.error_description || error.error);
    }

    return response.json();
  }
}
```

---

## Client Authentication

### Confidential Clients

```typescript
// Method 1: client_secret_basic (Header)
const credentials = btoa(`${clientId}:${clientSecret}`);
headers['Authorization'] = `Basic ${credentials}`;

// Method 2: client_secret_post (Body)
body.append('client_id', clientId);
body.append('client_secret', clientSecret);

// Method 3: private_key_jwt (Recommended for high security)
const assertion = await new SignJWT({
  iss: clientId,
  sub: clientId,
  aud: tokenEndpoint,
})
  .setProtectedHeader({ alg: 'ES256' })
  .setExpirationTime('5m')
  .setIssuedAt()
  .setJti(crypto.randomUUID())
  .sign(privateKey);

body.append('client_assertion_type', 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer');
body.append('client_assertion', assertion);
```

### Public Clients

- Mobile apps, SPAs, desktop apps
- Cannot store secrets securely
- MUST use PKCE
- client_id only (no secret)

---

## Redirect URI Validation

### Server-Side

```typescript
function validateRedirectUri(requested: string, registered: string[]): boolean {
  // MUST be exact match (no pattern matching)
  return registered.includes(requested);
}

// Avoid these patterns (security risks):
// ❌ Wildcard subdomains: https://*.example.com/callback
// ❌ Path prefix: https://example.com/callback/*
// ❌ Query parameter variations
```

### Registered URIs

```typescript
const registeredRedirectUris = [
  'https://app.example.com/callback',
  'https://staging.example.com/callback',
  // Mobile: Custom scheme
  'com.example.app://callback',
  // Desktop: Loopback
  'http://127.0.0.1/callback',
  'http://[::1]/callback',
];
```

---

## Token Response

### Standard Fields

```typescript
interface TokenResponse {
  access_token: string;
  token_type: 'Bearer' | 'DPoP';
  expires_in: number;           // Seconds until expiration
  refresh_token?: string;       // Optional
  scope?: string;               // May differ from requested
  id_token?: string;            // OpenID Connect
}
```

### Error Response

```typescript
interface TokenErrorResponse {
  error: 'invalid_request' | 'invalid_client' | 'invalid_grant' |
         'unauthorized_client' | 'unsupported_grant_type' | 'invalid_scope';
  error_description?: string;
  error_uri?: string;
}
```

---

## Scopes

### Design Guidelines

```typescript
// Resource-based scopes
const scopes = [
  'users:read',
  'users:write',
  'orders:read',
  'orders:write',
  'admin:full',
];

// Action-based scopes
const scopes = [
  'read',
  'write',
  'delete',
  'admin',
];

// OpenID Connect scopes
const oidcScopes = [
  'openid',   // Required for OIDC
  'profile',  // name, family_name, etc.
  'email',    // email, email_verified
  'address',  // address claim
  'phone',    // phone_number, phone_number_verified
];
```

### Scope Validation

```typescript
function validateScopes(requested: string[], allowed: string[]): string[] {
  // Return intersection of requested and allowed
  return requested.filter(scope => allowed.includes(scope));
}

function hasScope(tokenScopes: string, required: string): boolean {
  const scopes = tokenScopes.split(' ');
  return scopes.includes(required);
}
```

---

## Security Considerations

### State Parameter

```typescript
// Generate cryptographically random state
const state = crypto.randomBytes(32).toString('base64url');

// Store in session before redirect
session.oauthState = state;

// Validate on callback
if (callbackState !== session.oauthState) {
  throw new Error('Invalid state - CSRF detected');
}
```

### Nonce (OpenID Connect)

```typescript
// Include in authorization request
url.searchParams.set('nonce', crypto.randomBytes(16).toString('hex'));

// Validate in ID token
if (idToken.nonce !== session.nonce) {
  throw new Error('Invalid nonce - replay attack detected');
}
```

### Token Binding

```typescript
// DPoP (Demonstration of Proof of Possession)
// Binds tokens to client's key pair

// 1. Client generates key pair
const { publicKey, privateKey } = await crypto.subtle.generateKey(
  { name: 'ECDSA', namedCurve: 'P-256' },
  true,
  ['sign', 'verify']
);

// 2. Create DPoP proof for token request
const dpopProof = await createDPoPProof(privateKey, {
  htm: 'POST',
  htu: tokenEndpoint,
});

// 3. Include in token request
headers['DPoP'] = dpopProof;

// 4. Server binds token to public key
// 5. All API requests require fresh DPoP proof
```
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall