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: fips-204-ml-dsa-pqc-service-jwt-standard

NIST FIPS 204 ML-DSA Post-Quantum Service-to-Service JWT Standard

Mandates post-quantum digital signature standards (NIST FIPS 204 ML-DSA) for all internal service-to-service JSON Web Tokens across distributed mesh fabrics. Eliminates vulnerability to harvest-now-decrypt-later adversaries by enforcing lattice-based signatures (ML-DSA-65/ML-DSA-87) over classical RSA or ECC primitives. Enforces strict token header verification, signature length assertions, and prevents algorithmic downgrade attacks.

Prohibited Anti-Pattern: Signing or Validating Distributed Machine-to-Machine JWTs with Quantum-Vulnerable Classical Primitives (RS256, ES256)

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: NIST FIPS 204 ML-DSA Post-Quantum Service-to-Service JWT Standard - Mandates post-quantum digital signature standards (NIST FIPS 204 ML-DSA) for all internal service-to-service JSON Web Tokens across distributed mesh fabrics. Eliminates vulnerability to harvest-now-decrypt-later adversaries by enforcing lattice-based signatures (ML-DSA-65/ML-DSA-87) over classical RSA or ECC primitives. Enforces strict token header verification, signature length assertions, and prevents algorithmic downgrade attacks.
globs: src/**/*.{ts,tsx,js,jsx}, lib/**/*.{ts,tsx,js,jsx}, services/**/*.{ts,tsx,js,jsx}
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/fips-204-ml-dsa-pqc-service-jwt-standard"
---

# NIST FIPS 204 ML-DSA Post-Quantum Service-to-Service JWT Standard

> **Severity**: CRITICAL | **Category**: security
> **Anti-Pattern Warning**: Signing or Validating Distributed Machine-to-Machine JWTs with Quantum-Vulnerable Classical Primitives (RS256, ES256)

## System Constraints
You are a Principal Security Architect enforcing the NIST FIPS 204 ML-DSA Post-Quantum Cryptography (PQC) standard for distributed service-to-service authentication. Eliminate all classical asymmetric signature algorithms (RSA, ECDSA, Ed25519) in M2M JWT pipelines in favor of FIPS 204 ML-DSA (specifically ML-DSA-65 or ML-DSA-87) or compliant hybrid composites. Enforce strict alg header validation, allocate adequate buffer capacities for lattice-based signature payloads (approx. 3.3KB for ML-DSA-65), and ensure signature binding invariants cannot be bypassed.

## Strict Guidelines
- Services MUST ALWAYS issue and verify inter-service M2M authorization tokens using NIST FIPS 204 ML-DSA-65 or ML-DSA-87 algorithms.
- Services MUST NOT sign or accept internal service tokens using classical algorithms (RS256, RS512, ES256, ES384, EdDSA) without a mandatory FIPS 204 dual-signature hybrid envelope.
- Engineers MUST explicitly enforce the 'alg' claim check using an immutable allowlist consisting strictly of ['ML-DSA-65', 'ML-DSA-87'] to prevent algorithm downgrade attacks.
- Services MUST configure internal HTTP gateways, proxies, and mesh ingress points to support expanded HTTP Authorization headers capable of carrying lattice-based signatures (~4KB-8KB).
- Token validation components MUST verify the public key length exactly matches the expected FIPS 204 parameter size (1,952 bytes for ML-DSA-65; 2,592 bytes for ML-DSA-87) before invoking cryptographic verification.

## Bad vs Good Implementations
### Classical ES256 JWT Issuance and Verification (Quantum-Vulnerable)

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: ES256 relies on secp256r1 elliptic curves, which offer zero protection against quantum adversaries running Shor's algorithm. Intercepted M2M tokens allow adversaries to recover private signing keys from historical signatures, forge internal service credentials, and achieve complete lateral mesh impersonation.
```typescript
import * as jwt from 'jsonwebtoken';

interface ServicePayload {
  iss: string;
  sub: string;
  aud: string;
}

// VULNERABLE: Classical ECDSA is completely vulnerable to Shor's algorithm.
// Captured tokens can be reverse-engineered by store-now-decrypt-later adversaries.
export function issueServiceToken(payload: ServicePayload, ecdsaPrivateKeyPem: string): string {
  return jwt.sign(payload, ecdsaPrivateKeyPem, {
    algorithm: 'ES256',
    expiresIn: '5m'
  });
}

export function verifyServiceToken(token: string, ecdsaPublicKeyPem: string): ServicePayload {
  return jwt.verify(token, ecdsaPublicKeyPem, {
    algorithms: ['ES256']
  }) as ServicePayload;
}
```

#### Production Standard (Correct)
> **Standard**: This implementation uses NIST FIPS 204 ML-DSA-65, establishing lattice-based post-quantum authenticity for service-to-service communications. It strictly validates the algorithm header against downgrade attacks, enforces byte-level assertions on public key and signature sizes, and secures the internal mesh against store-now-decrypt-later adversaries.
```typescript
import { ml_dsa65 } from '@noble/post-quantum/ml-dsa';

interface ServicePayload {
  iss: string;
  sub: string;
  aud: string;
  exp: number;
  iat: number;
}

interface PqcJwtHeader {
  alg: 'ML-DSA-65';
  typ: 'JWT';
}

const ML_DSA_65_PUBKEY_BYTES = 1952;
const ML_DSA_65_SIG_BYTES = 3309;
const ALLOWED_ALGORITHMS = Object.freeze(['ML-DSA-65'] as const);

function base64UrlEncode(buffer: Uint8Array): string {
  return Buffer.from(buffer).toString('base64url');
}

function base64UrlDecode(str: string): Uint8Array {
  return new Uint8Array(Buffer.from(str, 'base64url'));
}

export function issuePqcServiceToken(
  payload: Omit<ServicePayload, 'iat'>,
  privateKey: Uint8Array
): string {
  const header: PqcJwtHeader = { alg: 'ML-DSA-65', typ: 'JWT' };
  const fullPayload: ServicePayload = {
    ...payload,
    iat: Math.floor(Date.now() / 1000)
  };

  const encodedHeader = base64UrlEncode(Buffer.from(JSON.stringify(header)));
  const encodedPayload = base64UrlEncode(Buffer.from(JSON.stringify(fullPayload)));
  const signingInput = new TextEncoder().encode(`${encodedHeader}.${encodedPayload}`);

  const signature = ml_dsa65.sign(privateKey, signingInput);
  return `${encodedHeader}.${encodedPayload}.${base64UrlEncode(signature)}`;
}

export function verifyPqcServiceToken(
  token: string,
  publicKey: Uint8Array,
  expectedAudience: string
): ServicePayload {
  if (publicKey.byteLength !== ML_DSA_65_PUBKEY_BYTES) {
    throw new Error(`Invalid ML-DSA-65 public key size: ${publicKey.byteLength}`);
  }

  const parts = token.split('.');
  if (parts.length !== 3) {
    throw new Error('Malformed JWT structure');
  }

  const [headerB64, payloadB64, sigB64] = parts;
  const header: PqcJwtHeader = JSON.parse(Buffer.from(headerB64, 'base64url').toString('utf8'));

  if (!ALLOWED_ALGORITHMS.includes(header.alg)) {
    throw new Error(`Unauthorized algorithm: ${header.alg}. Downgrade rejected.`);
  }

  const signature = base64UrlDecode(sigB64);
  if (signature.byteLength !== ML_DSA_65_SIG_BYTES) {
    throw new Error(`Invalid ML-DSA-65 signature size: ${signature.byteLength}`);
  }

  const signingInput = new TextEncoder().encode(`${headerB64}.${payloadB64}`);
  const isValid = ml_dsa65.verify(publicKey, signingInput, signature);
  if (!isValid) {
    throw new Error('Cryptographic signature verification failed');
  }

  const payload: ServicePayload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf8'));
  const now = Math.floor(Date.now() / 1000);

  if (payload.exp <= now) {
    throw new Error('Token expired');
  }
  if (payload.aud !== expectedAudience) {
    throw new Error(`Audience mismatch: expected ${expectedAudience}, got ${payload.aud}`);
  }

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

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

Cryptographic Static Analysis Server
Scans codebase ASTs for deprecated classical cryptographic algorithms (RSA, ECDSA) and flags missing FIPS 204 compliance.
Recommended Agent Skills (askills.dev)

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

Post-Quantum JWT Rule Linter
Validates that authentication endpoints and service mesh proxies correctly configure header buffer sizes and reject classical asymmetric signature algorithms.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: NIST FIPS 204 ML-DSA Post-Quantum Service-to-Service JWT Standard

NIST FIPS 204 ML-DSA Post-Quantum Service-to-Service JWT Standard defines an industrial-grade behavioral standard for security engineering. Mandates post-quantum digital signature standards (NIST FIPS 204 ML-DSA) for all internal service-to-service JSON Web Tokens across distributed mesh fabrics. Eliminates vulnerability to harvest-now-decrypt-later adversaries by enforcing lattice-based signatures (ML-DSA-65/ML-DSA-87) over classical RSA or ECC primitives. Enforces strict token header verification, signature length assertions, and prevents algorithmic downgrade attacks. 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: Signing or Validating Distributed Machine-to-Machine JWTs with Quantum-Vulnerable Classical Primitives (RS256, ES256) 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 DriftSigning or Validating Distributed Machine-to-Machine JWTs with Quantum-Vulnerable Classical Primitives (RS256, ES256)Critical
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

Services MUST ALWAYS issue and verify inter-service M2M authorization tokens using NIST FIPS 204 ML-DSA-65 or ML-DSA-87 algorithms.

Services MUST ALWAYS issue and verify inter-service M2M authorization tokens using NIST FIPS 204 ML-DSA-65 or ML-DSA-87 algorithms.

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

Services MUST NOT sign or accept internal service tokens using classical algorithms (RS256, RS512, ES256, ES384, EdDSA) without a mandatory FIPS 204 dual-signature hybrid envelope.

Services MUST NOT sign or accept internal service tokens using classical algorithms (RS256, RS512, ES256, ES384, EdDSA) without a mandatory FIPS 204 dual-signature hybrid envelope.

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

Engineers MUST explicitly enforce the 'alg' claim check using an immutable allowlist consisting strictly of ['ML-DSA-65', 'ML-DSA-87'] to prevent algorithm downgrade attacks.

Engineers MUST explicitly enforce the 'alg' claim check using an immutable allowlist consisting strictly of ['ML-DSA-65', 'ML-DSA-87'] to prevent algorithm downgrade attacks.

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

Services MUST configure internal HTTP gateways, proxies, and mesh ingress points to support expanded HTTP Authorization headers capable of carrying lattice-based signatures (~4KB-8KB).

Services MUST configure internal HTTP gateways, proxies, and mesh ingress points to support expanded HTTP Authorization headers capable of carrying lattice-based signatures (~4KB-8KB).

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

Token validation components MUST verify the public key length exactly matches the expected FIPS 204 parameter size (1,952 bytes for ML-DSA-65

Token validation components MUST verify the public key length exactly matches the expected FIPS 204 parameter size (1,952 bytes for ML-DSA-65; 2,592 bytes for ML-DSA-87) before invoking cryptographic verification.

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 NIST FIPS 204 ML-DSA Post-Quantum Service-to-Service JWT Standard critical for AI coding assistants?

Mandates post-quantum digital signature standards (NIST FIPS 204 ML-DSA) for all internal service-to-service JSON Web Tokens across distributed mesh fabrics. Eliminates vulnerability to harvest-now-decrypt-later adversaries by enforcing lattice-based signatures (ML-DSA-65/ML-DSA-87) over classical RSA or ECC primitives. Enforces strict token header verification, signature length assertions, and prevents algorithmic downgrade attacks. 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 (Signing or Validating Distributed Machine-to-Machine JWTs with Quantum-Vulnerable Classical Primitives (RS256, ES256)) 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

NIST