feat: CTE delegation and impersonation support

[NandanPrabhu]

• All new/changed/fixed functionality is covered by tests (or N/A)
• I have added documentation for all new/changed functionality (or N/A)

📋 Changes

Adds delegation and impersonation support for Custom Token Exchange (CTE) per RFC 8693, allowing an actor (e.g. an AI agent or support rep) to act on behalf of a user.

Types added:

• ActorToken — A struct that bundles token and tokenType together, ensuring both are always provided when performing delegation/impersonation token exchanges (per RFC 8693).
• ActClaim — A final class representing the act (actor) claim from an ID token. Supports recursive nesting for multi-hop delegation chains. Exposes sub, nested act, and additionalClaims.

Methods changed:

• Authentication.customTokenExchange(...) — Added optional actorToken: ActorToken? parameter. When provided, actor_token and actor_token_type are sent in the token exchange request.

Properties added:

• UserInfo.act: ActClaim? — Parses the act claim from the ID token JSON body. Also added "act" to UserInfo.publicClaims so it is excluded from customClaims.

Documentation:

• Updated EXAMPLES.md with sections on actor token delegation and reading the act claim.
• Updated README.md to mention custom token exchange in the comprehensive guides note.

📎 References

• RFC 8693: OAuth 2.0 Token Exchange
• RFC 8693 Section 4.1: act Claim
• Auth0 Custom Token Exchange Documentation

🎯 Testing

• Unit tests added in AuthenticationSpec for actor token parameter in CTE requests.
• Unit tests added in UserInfoSpec for act claim parsing: nil when absent, basic parsing, nested delegation chains, and exclusion from custom claims.
• Run swift test to verify all tests pass.

[sanchitmehtagit]

could this be struct instead

[kishore7snehil]

This references RFC 8693 Section 4.1, but the act claim is defined in Section 4.4 ("Delegation Semantics"). Section 4.1 covers the token exchange response structure.

Suggestion: https://tools.ietf.org/html/rfc8693#section-4.4

[kishore7snehil]

Per RFC 8693 Section 4.4: "The sub claim is required" within an act claim. The Android SDK (ActorClaim) makes sub non-optional and returns null for the entire object if sub is missing from the JSON.

Here, sub is String? which means callers always need to nil-check even though a valid act claim per the RFC will always have it. This creates inconsistent behavior across platforms.

Consider either:

1. Making sub non-optional (String) and returning nil from init? if sub is absent, or
2. Documenting why the lenient approach was chosen (e.g., forward-compatibility with potential spec changes)

[kishore7snehil]

additionalClaims is [String: String] and the initializer only keeps values that cast to String, silently dropping non-string JSON values (booleans, numbers, objects, arrays). While RFC 8693 act claims primarily use string values like sub, custom Auth0 Actions could set non-string values via api.authentication.setActor() that would be lost here.

[kishore7snehil]

Adding actorToken: ActorToken? as a required parameter to the public Authentication protocol is a source-breaking change for anyone who has created a custom conformance . Their implementation will fail to compile until they add the new parameter.

Consider noting it in the changelog, or providing a default implementation in a protocol extension to avoid breaking custom conformers.

[kishore7snehil]

This test verifies actor_token/actor_token_type ARE sent when provided, but there's no corresponding test verifying they are NOT present in the request body when actorToken is nil (the default).

The hasAllOf matcher only checks for presence of specified keys, not absence of others. Consider adding a test like:

it("should not include actor token params when actorToken is nil") {
    // ... call customTokenExchange without actorToken
    // assert body does NOT contain "actor_token" or "actor_token_type"
}

The Android PR includes this test (shouldSendCTERequestWithoutActorToken).

[kishore7snehil]

Same issue as in ActClaim.swift: this links to Section 4.1 but the act claim is defined in Section 4.4 ("Delegation Semantics"). Section 4.1 covers the token exchange response structure.

Should be: https://tools.ietf.org/html/rfc8693#section-4.4

[kishore7snehil]

This says "Auth0 may include an act claim" but doesn't explain when it will. The act claim only appears when an Action is configured server-side that calls api.authentication.setActor(). Without that, the response will never have an act claim regardless of whether actor_token is sent.

Consider adding a note like:

The act claim is set server-side via an Auth0 Action that calls api.authentication.setActor(). Without this Action configured, the ID token will not contain an act claim even when an actor token is provided in the request.

[kishore7snehil]

JWTDecode is a separate package (JWTDecode.swift) that needs to be added as a dependency. Developers copying this example may not know they need to add it to their project.

Consider adding a brief note: "This example uses JWTDecode.swift — add it to your project if you haven't already."