[forge-iterating] AB#3677516: Add internal DPoP crypto key storage and cache helpers

[hectormmg]

Summary

Adds internal DPoP crypto, browser key lifecycle, and token-binding helper primitives for L1 DPoP while keeping app-facing DPoP acquisition disabled until the public PCA enablement work item.

Implements

• AB#3677516 - WI-2: Add internal DPoP crypto key storage and cache helpers

Scope

• Adds browser token-binding key lifecycle support for scoped ES256/P-256 DPoP keys.
• Preserves existing RSA/SHR PoP behavior while moving legacy PoP signing onto token-binding primitives.
• Splits token-binding responsibilities so ICrypto owns crypto/signing and ITokenBindingKeyManager owns key provisioning, removal, and public JWK lookup.
• Shares a controller-owned browser TokenBindingKeyManager through interaction/custom-auth clients so scoped provisioning dedupe is not lost across per-request clients.
• Adds internal DPoP proof/key helper seams and metadata needed by later PCA wiring.
• Keeps runtime DPoP acquisition fail-closed; this PR does not export AuthenticationScheme.DPOP or enable app-facing DPoP flows.
• Splits TokenBindingKeyManager lifecycle coverage into a focused spec while keeping CryptoOps proof/signing integration coverage in CryptoOps.spec.ts.

Feature flag / waiver

• Feature flag waiver: No runtime feature flag is required because this PR is internal scaffolding and is not wired into public token acquisition flows or enabled by user-facing configuration.
• Default state: No user-visible DPoP behavior is enabled by default in this PR.
• Release-safety posture: The branch is merge-safe before full L1 DPoP wiring because the public feature remains disabled until AB#3677517.

Rollout / rollback

• Owner: MSAL.js team.
• Rollout stages: Merge internal primitives first, monitor CI/package validation, then enable public L1 PCA DPoP acquisition in a separate PR/work item.
• Success criteria: Existing Bearer/PoP/SHR/SSH behavior remains unchanged, DPoP internal key/proof tests pass, and telemetry records token-binding key metadata without logging proof or key material.
• Rollback path: Revert PR [forge-iterating] AB#3677516: Add internal DPoP crypto key storage and cache helpers #8708 if the internal primitives cause regressions. No flag flip is needed because public DPoP behavior is not enabled here.

How to validate

• npm test --workspace=@azure/msal-common -- JoseHeader.spec.ts JoseHeaderError.spec.ts DpopProofGenerator.spec.ts
• npm test --workspace=@azure/msal-common -- --runTestsByPath test/crypto/PopTokenGenerator.spec.ts --runInBand
• npm test --workspace=@azure/msal-browser -- CryptoOps.spec.ts TokenBindingKeyManager.spec.ts
• npm run build:all, npm run lint, npm run format:check, and npm run apiExtractor -- --local in affected 3P packages
• For browser/node API reports after common API changes, run package build:all before apiExtractor -- --local.

Notes

This PR previously referenced removed work item AB#3674407. The active WI-2 tracking item is AB#3677516.

[Copilot]

Pull request overview

Adds browser-side ES256 DPoP token-binding key lifecycle support (provision/reuse, public JWK lookup, compact JWT signing), and refactors SHR/PoP signing to use the same token-binding seams, with new telemetry fields and updated tests/docs/API reviews across msal-common, msal-browser, and msal-node.

Changes:

• Extend ICrypto with token-binding key provisioning/lookup/signing APIs and add JOSE header helpers for SHR + DPoP.
• Implement browser token-binding key caching/scoping + signing in CryptoOps, and update PoP/DPoP generators/tests to use the new seams.
• Add new error codes/docs and enrich performance telemetry with token-binding key metadata.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
lib/msal-node/test/utils/TestConstants.ts	Extends node test crypto stub with new token-binding crypto surface (not implemented).
lib/msal-node/src/crypto/CryptoProvider.ts	Adds unimplemented node placeholders for token-binding provisioning/lookup/signing; deprecates signJwt.
lib/msal-node/apiReview/msal-node.api.md	Updates msal-node API review to include new ICrypto members and deprecation markers.
lib/msal-common/test/crypto/PopTokenGenerator.spec.ts	Updates SHR/PoP generator tests to validate token-binding provisioning and signing seams.
lib/msal-common/test/crypto/JoseHeader.spec.ts	Adds correlationId assertions for JOSE header error cases; adds DPoP header test coverage.
lib/msal-common/test/crypto/DpopProofGenerator.spec.ts	Refactors DPoP tests to use signTokenBindingJwt + key context instead of a custom signer.
lib/msal-common/test/client/ClientTestUtils.ts	Extends common test crypto mock with token-binding provisioning/lookup/signing methods.
lib/msal-common/src/utils/Constants.ts	Adds JsonWebTokenTypes.Dpop constant for DPoP JOSE headers.
lib/msal-common/src/telemetry/performance/PerformanceEvent.ts	Adds token-binding key telemetry metadata fields to performance events.
lib/msal-common/src/exports-common.ts	Exposes new crypto types/constants via common exports.
lib/msal-common/src/error/JoseHeaderErrorCodes.ts	Adds missing_jwk_error code for DPoP header validation.
lib/msal-common/src/crypto/PopTokenGenerator.ts	Updates SHR signing flow to provision token-binding key + use token-binding JWK/signing seams.
lib/msal-common/src/crypto/JoseHeader.ts	Adds jwk support and introduces typed builders for SHR and DPoP headers with correlationId propagation.
lib/msal-common/src/crypto/ICrypto.ts	Adds token-binding key provisioning/context types + new crypto interface methods; marks legacy helpers deprecated.
lib/msal-common/src/crypto/DpopProofGenerator.ts	Adds DPoP key scope + JKT generation and routes proof signing through signTokenBindingJwt.
lib/msal-common/apiReview/msal-common.api.md	Updates public API review snapshot for new crypto APIs, constants, and telemetry fields.
lib/msal-browser/test/crypto/CryptoOps.spec.ts	Adds/updates tests for scoped key reuse, signing behaviors, and token-binding telemetry emission.
lib/msal-browser/src/error/BrowserAuthErrorCodes.ts	Adds new browser error codes for token-binding JWT algorithm validation.
lib/msal-browser/src/crypto/CryptoOps.ts	Implements browser token-binding key lifecycle (scoped caching, signing, public JWK lookup) and telemetry.
lib/msal-browser/src/crypto/BrowserCrypto.ts	Broadens sign input type to BufferSource for WebCrypto API compatibility.
lib/msal-browser/apiReview/msal-browser.api.md	Updates browser API review snapshot for new error codes and JsonWebTokenTypes.Dpop.
docs/errors.md	Documents new JOSE header and browser token-binding-related error codes.

[hectormmg]

/azp run

[azure-pipelines]

Azure Pipelines:
Successfully started running 4 pipeline(s).

[Copilot]

Pull request overview

Copilot reviewed 60 out of 60 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

lib/msal-common/src/crypto/ITokenBindingKeyManager.ts:83

• DEFAULT_TOKEN_BINDING_KEY_MANAGER always throws with an empty correlationId and omits the interface parameters, which drops the caller’s correlationId from the resulting ClientAuthError. Since these methods are invoked with a correlationId, the default implementation should accept/forward it so errors are properly correlated.

[Copilot]

Pull request overview

Copilot reviewed 61 out of 61 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 61 out of 61 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (3)

lib/msal-common/src/crypto/ICrypto.ts:148

• DEFAULT_CRYPTO_IMPLEMENTATION.removeTokenBindingKey throws a methodNotImplemented error with an empty correlationId. Since ICrypto now requires correlationId and callers rely on it for diagnostics, the default stub should accept the correlationId parameter (and optional context) and pass it through to createClientAuthError.
  lib/msal-common/src/crypto/ICrypto.ts:160
• DEFAULT_CRYPTO_IMPLEMENTATION.signTokenBindingJwt throws methodNotImplemented with an empty correlationId and doesn't accept the required parameters. Update the stub signature to match ICrypto and pass the provided correlationId through to createClientAuthError for better diagnostics.
  lib/msal-node/src/crypto/CryptoProvider.ts:81
• CryptoProvider.removeTokenBindingKey stub no longer matches the ICrypto signature (kid, correlationId, optional context). Because CryptoProvider is a public class, consumers calling it directly will see the wrong type signature. Align the method signature with ICrypto even if the node implementation remains unimplemented.

[Copilot]

Pull request overview

Copilot reviewed 67 out of 67 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

lib/msal-browser/src/cache/AsyncMemoryStorage.ts:106

• AsyncMemoryStorage.getKeys now always queries IndexedDB even when in-memory keys exist. DatabaseStorage.getKeys() can reject with a raw Event (transaction error), and handleDatabaseAccessError will rethrow non-databaseUnavailable errors, meaning getKeys can now throw instead of falling back to in-memory keys. This undermines the intended "persistent storage backed by memory" behavior and can cause unexpected failures in callers that only need the in-memory keys (e.g., key-scope lookups).

    async getKeys(correlationId: string): Promise<string[]> {
        const cacheKeys = this.inMemoryCache.getKeys();
        try {
            const persistentCacheKeys = await this.indexedDBCache.getKeys();
            return Array.from(new Set([...cacheKeys, ...persistentCacheKeys]));

lib/msal-common/src/crypto/ICrypto.ts:101

• ICrypto is exported as part of the public @azure/msal-common surface, and this change removes/renames existing members (getPublicKeyThumbprint, signJwt) into signTokenBindingJwt with a different signature. Any external consumer providing a custom cryptoInterface implementation (or calling these methods on an ICrypto-typed object) will experience a compile-time break, which is semver-major. Consider keeping the old members as deprecated (with a compatibility shim/fallback in internal call sites) for at least one major version before removing them, or otherwise ensure this lands under an intentional major-version plan.

[Copilot]

Pull request overview

Copilot reviewed 67 out of 67 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

lib/msal-browser/src/crypto/CryptoOps.ts:322

• When the token-binding JWT header includes a jwk property but it is not an object, this throws invalidPublicJwk with subError token_binding_key_jwk_thumbprint_mismatch. That subError is misleading here (no thumbprint comparison occurred) and makes diagnostics harder. Prefer throwing invalidPublicJwk without the thumbprint-mismatch subError for this malformed-header case; keep the mismatch subError only for the actual kid vs JWK-thumbprint mismatch path in validateTokenBindingJwtHeaderKey.

    throw createBrowserAuthError(
        BrowserAuthErrorCodes.invalidPublicJwk,
        correlationId,
        BrowserAuthErrorCodes.tokenBindingKeyJwkThumbprintMismatch
    );

lib/msal-common/src/crypto/ICrypto.ts:161

• DEFAULT_CRYPTO_IMPLEMENTATION.signTokenBindingJwt always throws methodNotImplemented with an empty correlationId (""), even though callers now must provide a correlationId to signTokenBindingJwt. This drops useful diagnostics. Update the default stub to accept the method parameters and pass the provided correlationId through to createClientAuthError.

[Copilot]

Pull request overview

Copilot reviewed 67 out of 67 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 67 out of 67 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

lib/msal-browser/src/crypto/CryptoOps.ts:322

• When header.jwk is present but not an object, validateTokenBindingSigningHeader throws invalid_public_jwk with subError token_binding_key_jwk_thumbprint_mismatch. That subError is misleading here (no thumbprint comparison happened), and will complicate diagnosing malformed headers.

    throw createBrowserAuthError(
        BrowserAuthErrorCodes.invalidPublicJwk,
        correlationId,
        BrowserAuthErrorCodes.tokenBindingKeyJwkThumbprintMismatch
    );