Feature Proposal: Authentication Digest

[o-nnerb]

Overview

HTTP Digest Authentication (RFC 7616) doesn't need new API in this package — it's already achievable today by composing two existing pieces of public API, with no changes to the network layer.

Why

Digest auth is a two-round-trip challenge-response: send a request, get a 401 back with a WWW-Authenticate: Digest realm=..., nonce=... challenge, compute a response hash from it, and resend the request with the computed Authorization: Digest ... header.

• TaskResult.head (returned by DataTask.result()) already exposes both the status code and the response headers, so the challenge is fully readable.
• .map(_:) is already generic enough ((Input) async throws -> Output, with Input == Output here) to inspect that result and, when it's a 401, build and execute an entirely new DataTask with the computed header — no replay of the original request needed, no new modifier required.
• Authorization's existing (_:token:) initializer already produces the right header shape by coincidence: it builds "\(type.rawValue) \(token)", and Digest's header is exactly "Digest " + comma-separated-key-value-string, so Authorization(.init("Digest"), token: "username=\"...\", realm=\"...\", nonce=\"...\", response=\"...\"") is already correct today.

DataTask { BaseURL("example.com") }
    .map { result -> TaskResult<Data> in
        guard result.head.status.code == 401,
              let challenge = result.head.headers.first(name: "WWW-Authenticate") else {
            return result
        }

        let token = computeDigestResponse(challenge: challenge, method: "GET", uri: "/", ...) // RFC 7616 hashing, e.g. via swift-crypto

        return try await DataTask {
            BaseURL("example.com")
            Authorization(.init("Digest"), token: token)
        }.result()
    }

No infinite-retry risk: the retried call is a plain DataTask, not wrapped in .map again, so it only ever gets the one extra attempt.

Decision

Closing as out of scope for the network layer. The RFC 7616 challenge-parsing and hashing (HA1/HA2/response, MD5 or SHA-256, qop/cnonce/nc bookkeeping) is generic auth logic that belongs in userland or a small crypto-facing helper (swift-crypto), not this package — and the retry orchestration itself is already fully expressible with .map, so there isn't even a convenience modifier worth bundling here (unlike a case where the pattern couldn't be expressed with existing API at all).

[o-nnerb]

Closing this — see the updated body. Digest authentication is already fully achievable today by composing TaskResult.head (for the WWW-Authenticate challenge) with .map(_:) (to build and execute a fresh DataTask carrying the computed Authorization: Digest ... header). No core/network-layer change is needed, and .map is already general enough that there isn't even a named convenience modifier worth bundling for this. The RFC 7616 hashing itself belongs in userland or swift-crypto. Happy to reopen if there's real demand for a bundled shortcut later.