Merge pull request #4060 from sfdctaka/feature/dpopApiCalls

DPoP proof JWT on API calls (with nonce retry per RFC 9449 §8/§9)

Author: sfdctaka

.github/workflows/pr.yaml

@@ -6,7 +6,7 @@ on:
   pull_request_target:  # zizmor: ignore[dangerous-triggers]
     # feature/dpopBehavior is a temporary entry: PRs in the multi-PR DPoP
     # rollout target this branch. Remove once DPoP is merged back to dev.
-    branches: [dev, master, feature/dpopBehavior]
+    branches: [dev, master, dpop]
 
 permissions:
   contents: read

libs/SalesforceSDKCore/SalesforceSDKCore/Classes/Identity/SFIdentityCoordinator.m

@@ -150,10 +150,21 @@ - (void)sendRequest
                                                                 cachePolicy:NSURLRequestReloadIgnoringCacheData
                                                             timeoutInterval:self.timeout];
     [request setHTTPMethod:@"GET"];
-    [request setValue:[NSString stringWithFormat:kHttpAuthHeaderFormatString, self.credentials.accessToken] forHTTPHeaderField:kHttpHeaderAuthorization];
+    NSError *authError = nil;
+    BOOL ok = [SFSDKDPoPRequestDecorator applyAuthHeaders:request
+                                                    scope:self.credentials.identifier
+                                              accessToken:self.credentials.accessToken
+                                                tokenType:self.credentials.tokenType
+                                                    error:&authError];
+    if (!ok) {
+        [SFSDKCoreLogger e:[self class] format:@"SFIdentityCoordinator: Failed to stamp authorization headers: %@", authError.localizedDescription];
+        [self notifyDelegateOfFailure:authError];
+        return;
+    }
     [request setTimeoutInterval:self.timeout];
     [request setHTTPShouldHandleCookies:NO];
     [SFSDKCoreLogger d:[self class] format:@"SFIdentityCoordinator:Starting identity request at %@", self.credentials.identityUrl.absoluteString];
+
     __weak __typeof(self) weakSelf = self;
     self.networkIdentifier = [SFNetwork uniqueInstanceIdentifier];
     SFNetwork *network = [SFNetwork sharedEphemeralInstanceWithIdentifier:self.networkIdentifier];

libs/SalesforceSDKCore/SalesforceSDKCore/Classes/OAuth/DPoP/DPoPNonceCache.swift

@@ -28,26 +28,26 @@ import Foundation
 
 /// Process-lifetime cache of `DPoP-Nonce` values, keyed by `(htu, scope)`.
 /// `scope` is typically `SFOAuthCredentials.identifier`. Fed by:
-///  - reactive 400 / 401 challenges (RFC 9449 §8)
-///  - proactive `DPoP-Nonce` response headers on 200 OK (Salesforce backend rotation).
+///  - proactive `DPoP-Nonce` harvest from token-endpoint responses (Salesforce only
+///    emits nonces from the token endpoint — resource-server responses don't carry
+///    `DPoP-Nonce` on 2xx or on challenges).
+///  - reactive 400 / 401 challenges at the token endpoint (RFC 9449 §8).
 ///
-/// Read semantics (`nonce(htu:scope:)`) are intentionally non-destructive: the cache
-/// returns the most recently observed nonce for a given `(htu, scope)` and does NOT
+/// Read semantics (`nonce(htu:scope:)`, `latest(forScope:)`) are intentionally
+/// non-destructive: the cache returns the most recently observed nonce and does NOT
 /// invalidate it on read. Rationale:
-///  - The Salesforce backend rotates the nonce on every response, so a successful
-///    request's response brings the next nonce via `harvestNonce(...)` — staleness
-///    is bounded to "exactly one outbound request" in the steady state.
-///  - The server is the authority on freshness: a stale nonce produces a
-///    `use_dpop_nonce` challenge that the caller already retries once.
-///  - Read-and-remove would force concurrent callers to race for a single nonce,
-///    causing all-but-one to fall back to the unauthenticated path and incur an
-///    extra round-trip per concurrent call.
-///
-/// This PR uses the cache only at the token endpoint, where requests are serial,
-/// so the read-doesn't-remove choice has no observable effect today. The model
-/// will be revisited when DPoP is extended to API calls in a later phase: with
-/// concurrent REST calls, the right policy might be "one-use-per-write" or
-/// "serialize on rotation."
+///  - Per RFC 9449 §9, a server-issued nonce is reusable until the server rotates it.
+///    Read-and-remove would force concurrent callers to race for a single nonce.
+///    The non-destructive read lets every concurrent caller use the most recently
+///    harvested value.
+///  - Resource-server calls reuse the latest token-endpoint nonce via
+///    `latest(forScope:)`. When the access token's nonce ages out, the next refresh
+///    (driven by the existing 401-on-resource → refresh-on-token → retry-resource
+///    path) hits the token endpoint and harvests a fresh nonce on the way back, so
+///    the retried resource-server call picks up the new value.
+///  - When the server rotates the nonce mid-flight, harvest from the in-flight
+///    response wins over harvest from a stale response that lost the race;
+///    last-writer-wins is acceptable because both values are server-issued.
 @objc(SFSDKDPoPNonceCache)
 public final class DPoPNonceCache: NSObject {
 
@@ -62,14 +62,38 @@ public final class DPoPNonceCache: NSObject {
 
     /// Returns the most recently observed nonce for `(htu, scope)`, or `nil` if none.
     /// Non-destructive — see class doc comment for rationale.
-    // TODO: Revisit read semantics when DPoP extends to API calls. Concurrent REST callers may
-    // need one-use-per-write or serialize-on-rotation to avoid all-but-one hitting use_dpop_nonce.
     @objc(nonceForHtu:scope:)
     public func nonce(htu: URL, scope: String?) -> String? {
         let key = Self.cacheKey(htu: htu, scope: scope)
         return queue.sync { storage[key] }
     }
 
+    /// Returns the most recently observed nonce for `scope`, regardless of `htu`.
+    ///
+    /// RFC 9449 §8/§9 leaves it to the authorization server to decide whether resource
+    /// servers also emit `DPoP-Nonce`. Salesforce's deployment seeds the nonce only on
+    /// token-endpoint responses; resource-server responses do not refresh it. Clients
+    /// are expected to reuse that token-endpoint nonce on every DPoP-protected call for
+    /// the lifetime of the DPoP session, and re-authenticate (which mints a fresh nonce)
+    /// when the session expires or the server replies with `use_dpop_nonce`.
+    ///
+    /// `nonce(htu:scope:)` is the spec-correct per-resource lookup. This method is the
+    /// fall-through used by `DPoPRequestDecorator` when the per-`htu` slot is empty —
+    /// in practice the only populated slot for a given scope is the token endpoint, and
+    /// returning it lets the proof carry the server-issued nonce on resource-server
+    /// calls without an unnecessary `use_dpop_nonce` round-trip.
+    @objc(latestForScope:)
+    public func latest(forScope scope: String?) -> String? {
+        let scopeKey = (scope?.isEmpty == false) ? scope! : "anonymous"
+        let suffix = "|" + scopeKey
+        return queue.sync {
+            for (key, value) in storage where key.hasSuffix(suffix) {
+                return value
+            }
+            return nil
+        }
+    }
+
     @objc(setNonce:htu:scope:)
     public func setNonce(_ nonce: String, htu: URL, scope: String?) {
         let key = Self.cacheKey(htu: htu, scope: scope)

libs/SalesforceSDKCore/SalesforceSDKCore/Classes/OAuth/DPoP/DPoPProofBuilder.swift

@@ -43,11 +43,16 @@ public final class DPoPProofBuilder: NSObject {
     ///   - httpMethod: HTTP verb (`"POST"` for token endpoint).
     ///   - htu: Full request URL with no query and no fragment, per RFC 9449 §4.2.
     ///   - nonce: Optional `nonce` claim from a prior `DPoP-Nonce` server hint.
+    ///   - accessToken: Optional access token bound to the request. When non-nil and
+    ///     non-empty, the payload includes the `ath` claim per RFC 9449 §4.2,
+    ///     computed as `base64url(SHA-256(accessToken))`. Required for resource-server
+    ///     calls; omitted for token-endpoint calls.
     ///   - keyPair: Public key is embedded in the JWS header `jwk`; private key signs.
     ///   - now: Injected clock for deterministic tests; defaults to `Date()`.
     @objc public static func buildProof(httpMethod: String,
                                         htu: URL,
                                         nonce: String?,
+                                        accessToken: String? = nil,
                                         keyPair: DPoPKeyPair,
                                         now: Date = Date()) throws -> String {
         let jwk: [String: String]
@@ -70,6 +75,10 @@ public final class DPoPProofBuilder: NSObject {
         if let nonce = nonce, !nonce.isEmpty {
             payload["nonce"] = nonce
         }
+        if let accessToken = accessToken, !accessToken.isEmpty,
+           let ath = athClaim(for: accessToken) {
+            payload["ath"] = ath
+        }
         guard let headerSegment = encode(json: header),
               let payloadSegment = encode(json: payload) else {
             throw DPoPProofBuilderError.serializationFailed
@@ -96,6 +105,18 @@ public final class DPoPProofBuilder: NSObject {
         return (raw as NSData).sfsdk_base64UrlString()
     }
 
+    /// `ath = base64url(SHA-256(access_token))` per RFC 9449 §4.2. The input is the
+    /// literal access-token string the SDK sends in the `Authorization: DPoP <token>`
+    /// header — confirmed by backend (Salesforce, 2026-06-10) as the exact `<token>`
+    /// value, byte-for-byte, no encoding or canonicalization.
+    private static func athClaim(for accessToken: String) -> String? {
+        guard let tokenData = accessToken.data(using: .utf8),
+              let digest = (tokenData as NSData).sfsdk_sha256() else {
+            return nil
+        }
+        return (digest as NSData).sfsdk_base64UrlString()
+    }
+
     private static func encode(json: [String: Any]) -> String? {
         // .sortedKeys keeps output stable so unit tests can snapshot byte-for-byte.
         guard let data = try? JSONSerialization.data(withJSONObject: json,

libs/SalesforceSDKCore/SalesforceSDKCore/Classes/OAuth/DPoP/DPoPRequestDecorator.swift

@@ -33,12 +33,26 @@ public final class DPoPRequestDecorator: NSObject {
     @objc public static let dpopNonceHeaderName = "DPoP-Nonce"
     @objc public static let nonceErrorCode = "use_dpop_nonce"
 
+    /// Authorization scheme value used when the token endpoint returns
+    /// `token_type: "DPoP"` (RFC 6749 §5.1 / RFC 9449 §6.1).
+    @objc public static let dpopTokenType = "DPoP"
+
     /// No-op when `SalesforceSDKManager.shared.useDPoP == NO`. Otherwise builds a fresh
     /// proof JWT (with cached nonce if any) and sets it on the `DPoP` header.
     /// `scope` is typically `SFOAuthCredentials.identifier` so the keypair and nonce cache
     /// are isolated per-account, even before an `SFUserAccount` exists.
     @objc(decorateRequest:scope:error:)
     public static func decorate(_ request: NSMutableURLRequest, scope: String) throws {
+        try decorate(request, scope: scope, accessToken: nil)
+    }
+
+    /// Same as `decorate(_:scope:)` but binds the proof to the given access token via the
+    /// `ath` claim (RFC 9449 §4.2). Use at resource-server call sites where the SDK already
+    /// holds a token; pass `nil` (or use the no-token overload) at the token endpoint.
+    @objc(decorateRequest:scope:accessToken:error:)
+    public static func decorate(_ request: NSMutableURLRequest,
+                                scope: String,
+                                accessToken: String?) throws {
         guard SalesforceManager.shared.usesDPoP else { return }
         guard !scope.isEmpty else {
             SFSDKCoreLogger.i(self, message: "DPoP decorator skipped: empty scope identifier")
@@ -48,28 +62,59 @@ public final class DPoPRequestDecorator: NSObject {
         let method = request.httpMethod
 
         let keyPair = try DPoPKeyStore.shared.keyPair(forScope: scope)
+        // Salesforce seeds DPoP-Nonce only on token-endpoint responses; resource-server
+        // responses don't refresh it. RFC 9449 §8/§9 permits this. Look up the per-htu
+        // entry first (spec-correct), then fall back to the latest nonce for the same
+        // scope so resource-server calls reuse the token-endpoint nonce instead of
+        // paying a `use_dpop_nonce` round-trip.
         let nonce = DPoPNonceCache.shared.nonce(htu: url, scope: scope)
+            ?? DPoPNonceCache.shared.latest(forScope: scope)
         let proof = try DPoPProofBuilder.buildProof(httpMethod: method,
-                                                         htu: url,
-                                                         nonce: nonce,
-                                                         keyPair: keyPair)
+                                                    htu: url,
+                                                    nonce: nonce,
+                                                    accessToken: accessToken,
+                                                    keyPair: keyPair)
         request.setValue(proof, forHTTPHeaderField: dpopHeaderName)
     }
 
-    /// Reads `DPoP-Nonce` from a response and stores it in the cache for the next outbound
-    /// request to the same `htu`. Per backend design doc, harvest from both 200 OK responses
-    /// (proactive rotation) and 400/401 challenges (reactive).
+    /// Central helper for stamping the Authorization header on authenticated outbound
+    /// requests. Decides scheme from `tokenType`:
+    ///
+    /// - `"DPoP"` → `Authorization: DPoP <token>` and a fresh DPoP proof header bound
+    ///   to `accessToken` via the `ath` claim.
+    /// - anything else (including `nil` / `"Bearer"`) → `Authorization: Bearer <token>`,
+    ///   no DPoP header.
     ///
-    /// Concurrency note: the token endpoint is called serially, so this PR's caller pattern
-    /// is "request → harvest → next request" with no overlap. When DPoP is extended to REST
-    /// API calls in a later phase, in-flight concurrent calls will all carry the same nonce
-    /// and only one will rotate it cleanly; the others will see a `use_dpop_nonce` challenge
-    /// and retry. At that point, this site needs to decide between accepting the extra
-    /// round-trip, serializing requests through a per-`htu` lock, or pre-fetching a nonce.
-    /// Out of scope for the token-endpoint PR.
-    // TODO: Handle concurrent REST callers when DPoP extends to API calls. Today's serial
-    // token-endpoint caller pattern means harvest-then-next-request never overlaps; with
-    // concurrent REST, decide between extra-round-trip, per-htu serialization, or pre-fetch.
+    /// No-op when `accessToken` is empty — preserves the existing "no token, skip stamp"
+    /// behavior of the four call sites.
+    ///
+    /// - Parameters:
+    ///   - request: the request to mutate. Existing `Authorization`/`DPoP` headers are
+    ///     overwritten by this method (callers should guard against double-stamping
+    ///     via their own checks).
+    ///   - scope: per-account isolation key, typically `SFOAuthCredentials.identifier`.
+    ///   - accessToken: the access token string sent in the Authorization header.
+    ///   - tokenType: `SFOAuthCredentials.tokenType` (the OAuth `token_type` returned
+    ///     by the token endpoint, RFC 6749 §5.1). Case-sensitive equality match against
+    ///     `"DPoP"` is the only positive branch.
+    @objc(applyAuthHeaders:scope:accessToken:tokenType:error:)
+    public static func applyAuthHeaders(_ request: NSMutableURLRequest,
+                                        scope: String,
+                                        accessToken: String?,
+                                        tokenType: String?) throws {
+        guard let accessToken, !accessToken.isEmpty else { return }
+        if tokenType == dpopTokenType {
+            request.setValue("DPoP \(accessToken)", forHTTPHeaderField: "Authorization")
+            try decorate(request, scope: scope, accessToken: accessToken)
+        } else {
+            request.setValue("Bearer \(accessToken)", forHTTPHeaderField: "Authorization")
+        }
+    }
+
+    /// Reads `DPoP-Nonce` from a response and stores it in the cache for the next outbound
+    /// request to the same `htu`. Per RFC 9449 §8/§9, harvest from both 2xx responses
+    /// (proactive rotation) and 400/401 nonce challenges (reactive). Safe to call on every
+    /// response — a missing or empty header is a no-op.
     @objc(harvestNonceFromResponse:requestURL:scope:)
     public static func harvestNonce(from response: URLResponse?,
                                     requestURL: URL?,

libs/SalesforceSDKCore/SalesforceSDKCore/Classes/OAuth/SFOAuthCredentials+Internal.h

@@ -82,6 +82,7 @@ extern NSException * _Nullable SFOAuthInvalidIdentifierException(void);
 @property (nonatomic, readwrite, nullable) NSString *sidCookieName;
 @property (nonatomic, readwrite, nullable) NSString *parentSid;
 @property (nonatomic, readwrite, nullable) NSString *tokenFormat;
+@property (nonatomic, readwrite, nullable) NSString *tokenType;
 @property (nonatomic, readwrite, nullable) NSString *beaconChildConsumerKey;
 @property (nonatomic, readwrite, nullable) NSString *beaconChildConsumerSecret;
 

libs/SalesforceSDKCore/SalesforceSDKCore/Classes/OAuth/SFOAuthCredentials.h

@@ -138,6 +138,7 @@ NS_SWIFT_NAME(OAuthCredentials)
 @property (nonatomic, readonly, nullable) NSString *sidCookieName;
 @property (nonatomic, readonly, nullable) NSString *parentSid;
 @property (nonatomic, readonly, nullable) NSString *tokenFormat;
+@property (nonatomic, readonly, nullable) NSString *tokenType;
 @property (nonatomic, readonly, nullable) NSString *beaconChildConsumerKey;
 @property (nonatomic, readonly, nullable) NSString *beaconChildConsumerSecret;
 

libs/SalesforceSDKCore/SalesforceSDKCore/Classes/OAuth/SFOAuthCredentials.m

@@ -117,6 +117,7 @@ - (id)initWithCoder:(NSCoder *)coder {
             self.cookieSidClient  = [coder decodeObjectOfClass:[NSString class] forKey:@"SFOAuthCookieSidClient"];
             self.sidCookieName  = [coder decodeObjectOfClass:[NSString class] forKey:@"SFOAuthSidCookieName"];
             self.tokenFormat  = [coder decodeObjectOfClass:[NSString class] forKey:@"SFOAuthTokenFormat"];
+            self.tokenType  = [coder decodeObjectOfClass:[NSString class] forKey:@"SFOAuthTokenType"];
 
             if ([self isMemberOfClass:[SFOAuthCredentials class]]) {
                 // Otherwise they are stored in keychain
@@ -159,6 +160,7 @@ - (void)encodeWithCoder:(NSCoder *)coder {
     [coder encodeObject:self.cookieSidClient    forKey:@"SFOAuthCookieSidClient"];
     [coder encodeObject:self.sidCookieName      forKey:@"SFOAuthSidCookieName"];
     [coder encodeObject:self.tokenFormat        forKey:@"SFOAuthTokenFormat"];
+    [coder encodeObject:self.tokenType          forKey:@"SFOAuthTokenType"];
     [coder encodeObject:kSFOAuthArchiveVersion  forKey:@"SFOAuthArchiveVersion"];
     [coder encodeObject:@(self.isEncrypted)     forKey:@"SFOAuthEncrypted"];
     [coder encodeObject:self.additionalOAuthFields forKey:@"SFOAuthAdditionalFields"];
@@ -229,6 +231,7 @@ - (id)copyWithZone:(nullable NSZone *)zone {
     copyCreds.sidCookieName = self.sidCookieName;
     copyCreds.parentSid = self.parentSid;
     copyCreds.tokenFormat = self.tokenFormat;
+    copyCreds.tokenType = self.tokenType;
     copyCreds.beaconChildConsumerKey = self.beaconChildConsumerKey;
     copyCreds.beaconChildConsumerSecret = self.beaconChildConsumerSecret;
     copyCreds.additionalOAuthFields = [self.additionalOAuthFields copy];
@@ -343,6 +346,7 @@ - (void)revokeRefreshToken {
     self.sidCookieName = nil;
     self.parentSid = nil;
     self.tokenFormat = nil;
+    self.tokenType = nil;
     self.beaconChildConsumerKey = nil;
     self.beaconChildConsumerSecret = nil;
 }
@@ -469,6 +473,9 @@ - (void)updateCredentials:(NSDictionary *) params {
     if (params[kSFOAuthTokenFormat]) {
         self.tokenFormat = params[kSFOAuthTokenFormat];
     }
+    if (params[kSFOAuthTokenType]) {
+        self.tokenType = params[kSFOAuthTokenType];
+    }
     if (params[kSFOAuthBeaconChildConsumerKey]) {
         self.beaconChildConsumerKey = params[kSFOAuthBeaconChildConsumerKey];
     }

libs/SalesforceSDKCore/SalesforceSDKCore/Classes/RestAPI/SFRestAPI.m

@@ -324,6 +324,7 @@ - (void)enqueueRequest:(SFRestRequest *)request shouldRetry:(BOOL)shouldRetry {
         } else {
             network = [self networkForRequest:request];
         }
+
         __block NSURLSessionDataTask *dataTask = [network sendRequest:finalRequest dataResponseBlock:^(NSData *data, NSURLResponse *response, NSError *error) {
             __strong typeof(weakSelf) strongSelf = weakSelf;
             [SFNetwork removeSharedInstanceForIdentifier:instanceIdentifier];