AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
securitycritical PriorityID: oidc-dpop-token-binding-guardrail

RFC 9449 Demonstrating Proof-of-Possession (DPoP) & Server-Nonce Invariants

Enforces RFC 9449 Demonstrating Proof-of-Possession (DPoP) token binding across all client and resource server interactions. Ensures access and refresh tokens are cryptographically sender-constrained using non-exportable asymmetric keypairs and mandates automated retry semantics with strict server-nonce verification to mitigate replay and exfiltration vectors.

Prohibited Anti-Pattern: Transmitting bearer tokens without cryptographic key binding or ignoring DPoP-Nonce rotation protocols

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: RFC 9449 Demonstrating Proof-of-Possession (DPoP) & Server-Nonce Invariants - Enforces RFC 9449 Demonstrating Proof-of-Possession (DPoP) token binding across all client and resource server interactions. Ensures access and refresh tokens are cryptographically sender-constrained using non-exportable asymmetric keypairs and mandates automated retry semantics with strict server-nonce verification to mitigate replay and exfiltration vectors.
globs: src/auth/**/*.{ts,tsx}, src/api/**/*.{ts,tsx}, src/http/**/*.{ts,tsx}, src/middleware/**/*.{ts,tsx}
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/oidc-dpop-token-binding-guardrail"
---

# RFC 9449 Demonstrating Proof-of-Possession (DPoP) & Server-Nonce Invariants

> **Severity**: CRITICAL | **Category**: security
> **Anti-Pattern Warning**: Transmitting bearer tokens without cryptographic key binding or ignoring DPoP-Nonce rotation protocols

## System Constraints
You are a Principal Security Architect enforcing OIDC RFC 9449 DPoP (Demonstrating Proof-of-Possession) token sender-constraining and cryptographic nonce management. You must prohibit the use of unconstrained Bearer tokens in sensitive flows, require all outbound requests to attach a fresh DPoP proof signed with an ephemeral or secure hardware-backed asymmetric key (WebCrypto CryptoKey), enforce jti generation, htu/htm claim binding, ath hash generation on access tokens, and implement transparent single-attempt retry logic when upstream servers respond with use_dpop_nonce errors.

## Strict Guidelines
- Clients MUST generate DPoP proofs using non-exportable asymmetric keys (ES256/Ed25519) via WebCrypto or native secure enclaves.
- Clients MUST include 'htm' (HTTP method), 'htu' (HTTP target URI stripped of query parameters and fragments), 'iat' (issued at timestamp), and a unique cryptographically random 'jti' UUID in every DPoP proof JWT payload.
- Clients MUST calculate the 'ath' (Access Token Hash) claim using base64url(sha256(token)) whenever presenting an access token to a protected resource.
- HTTP clients MUST intercept 'use_dpop_nonce' errors (HTTP 401 with DPoP-Nonce header), update the stored nonce, and retry the request exactly once with the new nonce attached to the proof.
- Engineers MUST NOT persist private signing keys in localStorage or non-sandboxed memory pools subject to XSS exfiltration.
- Resource servers and gateways MUST reject any authorization header prefixed with 'Bearer' when endpoints require DPoP sender-constraining (HTTP 401 with 'WWW-Authenticate: DPoP error="invalid_token"').
- Resource servers MUST enforce replay protection by checking 'jti' uniqueness within an acceptable time window (skew <= 60 seconds) and validating the 'DPoP-Nonce' matches the server's stateful or stateless encrypted nonce.

## Bad vs Good Implementations
### Client-Side Outbound DPoP Fetch Interceptor with Nonce Rotation and Token Binding

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Transmits tokens as unconstrained bearer tokens. If an attacker intercepts the token or extracts it via an XSS/SSRF vector, it can be used anywhere without verification of client possession or target URI binding.
```typescript
import axios from 'axios';

// Anti-pattern: Unconstrained Bearer token transmission vulnerable to exfiltration
export async function callProtectedApi(url: string, method: string, accessToken: string) {
  return axios({
    url,
    method,
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
}
```

#### Production Standard (Correct)
> **Standard**: Adheres strictly to RFC 9449. Creates an ephemeral sender-bound DPoP proof with htm/htu binding, generates the required 'ath' digest for access tokens, signs the payload with ES256, and correctly processes the DPoP-Nonce rotation challenge.
```typescript
import { SignJWT, importJWK, exportJWK } from 'jose';

interface DPoPState {
  keyPair: CryptoKeyPair;
  cachedNonce?: string;
}

async function computeAth(accessToken: string): Promise<string> {
  const encoder = new TextEncoder();
  const hash = await crypto.subtle.digest('SHA-256', encoder.encode(accessToken));
  return Buffer.from(hash).toString('base64url');
}

export async function generateDPoPProof(
  keyPair: CryptoKeyPair,
  method: string,
  url: string,
  accessToken?: string,
  nonce?: string
): Promise<string> {
  const parsedUrl = new URL(url);
  const htu = `${parsedUrl.origin}${parsedUrl.pathname}`;
  const publicJwk = await exportJWK(keyPair.publicKey);

  let jwt = new SignJWT({
    htm: method.toUpperCase(),
    htu,
    jti: crypto.randomUUID(),
    ...(accessToken ? { ath: await computeAth(accessToken) } : {}),
    ...(nonce ? { nonce } : {})
  })
    .setProtectedHeader({ alg: 'ES256', typ: 'dpop+jwt', jwk: publicJwk })
    .setIssuedAt();

  return jwt.sign(keyPair.privateKey);
}

export async function executeDPoPRequest(
  state: DPoPState,
  url: string,
  method: string,
  accessToken: string
): Promise<Response> {
  const send = async (nonce?: string) => {
    const proof = await generateDPoPProof(state.keyPair, method, url, accessToken, nonce);
    return fetch(url, {
      method,
      headers: {
        'Authorization': `DPoP ${accessToken}`,
        'DPoP': proof,
      },
    });
  };

  let response = await send(state.cachedNonce);

  // Handle mandatory server-nonce rotation challenge (RFC 9449 Section 8)
  if (response.status === 401) {
    const serverNonce = response.headers.get('DPoP-Nonce');
    if (serverNonce && serverNonce !== state.cachedNonce) {
      state.cachedNonce = serverNonce;
      response = await send(serverNonce); // Re-issue proof with mandated nonce
    }
  }

  return response;
}
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

Crypto & JWT Spec Validator MCP
Inspects cryptographic assertions, JWT/JWS structures, and validates DPoP proof claims against RFC 9449 specifications.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

JOSE/DPoP Cryptographic Token Debugger
CLI utility to assert valid signatures, verify thumbprints (jkt), and test DPoP nonces in authentication headers.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: RFC 9449 Demonstrating Proof-of-Possession (DPoP) & Server-Nonce Invariants

RFC 9449 Demonstrating Proof-of-Possession (DPoP) & Server-Nonce Invariants defines an industrial-grade behavioral standard for security engineering. Enforces RFC 9449 Demonstrating Proof-of-Possession (DPoP) token binding across all client and resource server interactions. Ensures access and refresh tokens are cryptographically sender-constrained using non-exportable asymmetric keypairs and mandates automated retry semantics with strict server-nonce verification to mitigate replay and exfiltration vectors. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Transmitting bearer tokens without cryptographic key binding or ignoring DPoP-Nonce rotation protocols Without an explicit system instruction file, developers spend hours debugging silent failures.
Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftTransmitting bearer tokens without cryptographic key binding or ignoring DPoP-Nonce rotation protocolsCritical
Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production.
Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture InconsistencyAI assistants produce mixed paradigms across files, creating fragmented codebase conventions.Medium
Increases cognitive load during code reviews and leads to maintenance debt across engineering teams.
Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.
Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

1

Clients MUST generate DPoP proofs using non-exportable asymmetric keys (ES256/Ed25519) via WebCrypto or native secure enclaves.

Clients MUST generate DPoP proofs using non-exportable asymmetric keys (ES256/Ed25519) via WebCrypto or native secure enclaves.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Clients MUST include 'htm' (HTTP method), 'htu' (HTTP target URI stripped of query parameters and fragments), 'iat' (issued at timestamp), and a unique cryptographically random 'jti' UUID in every DPoP proof JWT payload.

Clients MUST include 'htm' (HTTP method), 'htu' (HTTP target URI stripped of query parameters and fragments), 'iat' (issued at timestamp), and a unique cryptographically random 'jti' UUID in every DPoP proof JWT payload.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Clients MUST calculate the 'ath' (Access Token Hash) claim using base64url(sha256(token)) whenever presenting an access token to a protected resource.

Clients MUST calculate the 'ath' (Access Token Hash) claim using base64url(sha256(token)) whenever presenting an access token to a protected resource.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

HTTP clients MUST intercept 'use_dpop_nonce' errors (HTTP 401 with DPoP-Nonce header), update the stored nonce, and retry the request exactly once with the new nonce attached to the proof.

HTTP clients MUST intercept 'use_dpop_nonce' errors (HTTP 401 with DPoP-Nonce header), update the stored nonce, and retry the request exactly once with the new nonce attached to the proof.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Engineers MUST NOT persist private signing keys in localStorage or non-sandboxed memory pools subject to XSS exfiltration.

Engineers MUST NOT persist private signing keys in localStorage or non-sandboxed memory pools subject to XSS exfiltration.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
6

Resource servers and gateways MUST reject any authorization header prefixed with 'Bearer' when endpoints require DPoP sender-constraining (HTTP 401 with 'WWW-Authenticate

Resource servers and gateways MUST reject any authorization header prefixed with 'Bearer' when endpoints require DPoP sender-constraining (HTTP 401 with 'WWW-Authenticate: DPoP error="invalid_token"').

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
7

Resource servers MUST enforce replay protection by checking 'jti' uniqueness within an acceptable time window (skew <= 60 seconds) and validating the 'DPoP-Nonce' matches the server's stateful or stateless encrypted nonce.

Resource servers MUST enforce replay protection by checking 'jti' uniqueness within an acceptable time window (skew <= 60 seconds) and validating the 'DPoP-Nonce' matches the server's stateful or stateless encrypted nonce.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is RFC 9449 Demonstrating Proof-of-Possession (DPoP) & Server-Nonce Invariants critical for AI coding assistants?

Enforces RFC 9449 Demonstrating Proof-of-Possession (DPoP) token binding across all client and resource server interactions. Ensures access and refresh tokens are cryptographically sender-constrained using non-exportable asymmetric keypairs and mandates automated retry semantics with strict server-nonce verification to mitigate replay and exfiltration vectors. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Transmitting bearer tokens without cryptographic key binding or ignoring DPoP-Nonce rotation protocols) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related SECURITY Rules

View all rules →
security
105

OpenFGA Graph Invariants: Cyclic Relation Prevention & Contextual Tuple Hardening

Enforces strict directed acyclic graph (DAG) topology validation during relationship mutation writes and mandates strict server-side schema verification for ephemeral contextual tuples in OpenFGA evaluations. Prohibits persistent storage of ephemeral request attributes and guards against recursive relation loops causing graph expansion denial-of-service.

security
81

WebAuthn Conditional UI Mediation, Nonce Atomicity, and Assertion Cryptographic Verification

Enforces zero-trust cryptographic validation for FIDO2/WebAuthn Passkey authentication with Conditional UI autofill. Requires atomic single-use challenge consumption to eliminate replay attacks, strict RP ID hash and origin binding, authenticatorData flag verification (User Presence and User Verification), and monotonic signature counter enforcement to detect authenticator cloning.

security
111

Enforce Sigstore Keyless OIDC Attestation and Admission Controller Verification

Enforces immutable supply-chain security using Sigstore Cosign keyless signing via ephemeral OIDC tokens issued by Fulcio and verified against the Rekor transparency log. Container workloads must be signed and attested at build time by digest, and admission controllers (such as Kyverno or Sigstore Policy Controller) must strictly validate the OIDC issuer and subject identity before allowing image execution.

1 Rule in Stack

RFC