feat(auth): add resource indicator, refresh, and client caching to DCR provider

[scottlovegrove]

Why

createDcrProvider covered RFC 7591 dynamic client registration + PKCE code exchange, but a consumer that needs any of the following had to abandon the factory and hand-roll a full AuthProvider (raw fetch DCR + PKCE + token exchange + refresh). This was discovered while reviewing comms-cli, whose auth-provider.ts reimplements ~500 lines of OAuth that this factory already owns, purely to add three missing capabilities:

1. RFC 8707 resource indicator — when the authorization server (e.g. Todoist) and the protected resource (e.g. Comms) differ, the token's audience must be pinned via resource on the authorize URL and token requests. The factory had no hook for it.
2. Refresh — the DCR provider didn't implement refreshToken at all (only createPkceProvider did), so DCR consumers couldn't use cli-core's silent-refresh path.
3. Client caching — prepare() re-registered on every login; no way to reuse an issued client_id.

What

• resource?: OAuthLazyString — threaded into the authorize URL (new optional additionalParameters on buildPkceAuthorizeUrl) and the authorization_code + refresh_token token request bodies (oauth4webapi additionalParameters).
• refreshToken on the DCR provider — honours the handshake's client auth (public None / client_secret_post / RFC-3986 Basic), the resource indicator, and a 10s timeout; maps invalid_grant → AUTH_REFRESH_EXPIRED, else AUTH_REFRESH_TRANSIENT.
• loadClient / saveClient hooks — reuse a registered client across logins. A cache hit skips both the registration round-trip and the oauth4webapi load. cli-core stays storage-agnostic; the consumer owns persistence.

Internal cleanup

• Extracted the refresh-error mapping into oauth.ts as mapRefreshError and reused it from createPkceProvider (−38 lines of duplicated mapping there).
• Extracted selectClientAuth / tokenRequestOptions / clientHandshake helpers in dcr.ts, shared by exchangeCode and the new refreshToken.

Tests

9 new dcr.test.ts cases: resource on authorize URL + token body, refresh grant (+ resource), confidential-client refresh auth, invalid_grant → AUTH_REFRESH_EXPIRED, missing-clientId → AUTH_REFRESH_UNAVAILABLE, loadClient cache hit (no registration POST), and saveClient on a cache miss. Full suite green, type-check + lint + format clean.

🤖 Generated with Claude Code

[doistbot]

Thanks Scott for expanding the DCR provider with resource indicators, refresh capabilities, and client caching 😇.

Few things worth tightening:

• Apply additionalParameters before standard PKCE parameters so standard values aren't accidentally overwritten.
• Ensure loadClient validates the returned cache shape, and include the redirect_uri in DcrRegisteredClient so cached clients don't use mismatched callbacks on subsequent logins.
• Provide a way for refreshToken to reload the cached client itself, since the standard silent-refresh path doesn't persist the DCR handshake.
• Update the README.md to reflect the new API and remove the outdated caching claim, and ensure tests cover async cache hooks and distinct auth-method precedence.

I also included a few optional follow-up notes in the details below.

Optional follow-up note (1)

• [P3] src/auth/providers/dcr.ts:349: tokenUrl and resource are resolved serially here. Both are OAuthLazyStrings, so if a consumer supplies async resolvers, every silent refresh now waits for them back-to-back. Resolve them with Promise.all (and likewise in the new authorize/exchangeCode resource lookups) to avoid adding avoidable latency on this path.

_{Share Feedback • Review Logs}

[amix]

Looked through the code and reads well.

I think it’s critical that we test the refresh paths using comms-cli / ⁠todoist-cli to ensure everything works properly. There’s a lot of complexity in this flow, and plenty of places where things could break ... either in the implementation or on the backend.

[scottlovegrove]

I think it’s critical that we test the refresh paths using comms-cli

Yup, just linking this PR to Comms CLI locally now to try it out.

[doist-release-bot]

🎉 This PR is included in version 0.25.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀