Add OAuth 2.0 and Bot Password authentication infrastructure

[Copilot]

Bot Password Authentication Infrastructure

Status: Ready for merge. Bot Password authentication is complete and fully functional.

What's Included

BotPasswordAuth Provider

• Action API login with cookie jar persistence
• Automatic re-login on session expiration
• CSRF token fetching and caching
• Implements AuthProvider interface (authorize(), getCsrfToken(), onAuthError())

Infrastructure

• Cookie jar support via tough-cookie + axios-cookiejar-support
• Error taxonomy with typed errors (NotLoggedInError, PermissionDeniedError, RateLimitedError, etc.)
• Retry utilities for exponential backoff
• Header redaction for logging

Testing

• All 41 test suites passing (409 tests)
• Build successful
• Linting clean (0 errors)

Usage Example

import { BotPasswordAuth } from 'iwf';

const auth = new BotPasswordAuth({
    username: 'User@BotName',
    password: process.env.BOT_PASSWORD!,
    userAgent: 'MyBot/1.0'
});

// Get CSRF token
const token = await auth.getCsrfToken('https://www.wikidata.org');

Dependencies

• axios-cookiejar-support@^5.0.5
• tough-cookie@^5.0.0

Original prompt

Build Brief — Add OAuth to iwf (breaking API, axios, no code snippets)
Goal

Implement a new authentication system for iwf that supports:

OAuth 2.0 Authorization Code (+ PKCE) with refresh tokens for user-context edits.

Owner-only OAuth pattern for headless CI (use stored refresh token).

Bot Passwords (Action API action=login) for simple non-interactive bots.
All HTTP must go through axios. The public API may change (no backwards compatibility required).

Scope & Out of Scope

In scope: auth modules, token storage interfaces, CSRF handling, request signing, retry/backoff, error taxonomy, config, docs, unit tests, Cypress e2e tests (mocked), minimal examples in README (but do not write code examples here).

Out of scope: real network calls in CI/e2e against Wikimedia. Use mocks/fixtures.

Tech/Lib Choices

HTTP: axios (single shared instance, per-wiki baseURL support).

Test unit: keep current test runner; add axios mocking (axios-mock-adapter) or MSW (node).

E2E: Cypress with network stubbing.

Node runtime first. If browser support exists, ensure CORS notes are documented, but do not implement browser-specific flows unless already supported.

Public API (Breaking)

Design a new top-level API:

AuthProvider interface:

authorize(request): RequestConfig — returns axios config with headers/cookies for authenticated calls.

getCsrfToken(site: string): Promise — fetches a CSRF token via Action API.

onAuthError?(err): Promise — optional hook to refresh/recover.

Concrete providers:

OAuth2AuthCode — supports interactive bootstrap + headless refresh.

BotPasswordAuth — Action API login + cookie jar.

(Optional) OAuth2ClientCredentials — for api.wikimedia.org read-only portal endpoints.

Factory:

createAuth(...) — constructs the appropriate provider from config.

Core mutation functions (e.g., edit, upload, move, etc.) must:

Accept { auth: AuthProvider, summary?: string, ... }.

Always add assert=user to writes.

Always resolve a CSRF token via auth.getCsrfToken(...) just-in-time.

HTTP client:

Export an internal createAxios(site, userAgent, cookieJar?).

Global retry policy for 429/5xx with exponential backoff and Retry-After support.

Attach a descriptive User-Agent (configurable).

Configuration

Sites: accept full origin per call or a default (e.g., https://www.wikidata.org).

User agent: required string in top-level config.

Timeouts: configurable (default e.g., 30s).

Retries: configurable (max attempts, base delay, jitter).

Secrets:

OAuth client id/secret, refresh token via env or injected config.

Bot username (Main@Bot) and bot password via env or injected config.

Token persistence:

Define an interface TokenStore with loadRefreshToken(), saveRefreshToken(value).

Provide a simple file-based store for Node; allow user-supplied implementations.

OAuth 2.0 Authorization Code (+ PKCE)

Endpoints (Meta-Wiki):

authorize: /w/rest.php/oauth2/authorize

token: /w/rest.php/oauth2/access_token

Interactive bootstrap (one-time or per user):

Generate PKCE verifier/challenge.

Open system browser to the authorize URL with required query params.

Run a minimal localhost callback receiver to capture code.

Exchange code for access_token and refresh_token.

Persist the refresh_token via TokenStore.

Headless usage (CI):

At startup, exchange stored refresh_token for a fresh access_token.

Cache access_token and its expiry; auto-refresh on expiry or 401.

Action API usage:

Use Authorization: Bearer <access_token> for all requests requiring auth.

Fetch CSRF token via action=query&meta=tokens&type=csrf&format=json.

Grants:

Make requested scopes configurable; default to minimal grants needed for edits.

Bot Passwords (CI-friendly)

Login sequence:

Get login token (type=login), then action=login with lgname=Main@BotName and bot password.

Persist cookies in a cookie jar bound to the axios instance.

Fetch CSRF token (type=csrf) after successful login.

Notes:

Use only with Bot Passwords; never main account password.

Support 2FA-protected main accounts via app-specific bot password.

CSRF & Writes

Before any write:

Ensure authenticated context.

Get CSRF token and include it in the write call.

Add assert=user to prevent anonymous fallbacks.

If CSRF fetch returns notloggedin/permissiondenied:

For OAuth: refresh and retry once.

For Bot Passwords: re-login once.

Error Taxonomy & Handling

Normalize common failure modes:

AuthExpired (401/invalid_token).

NotLoggedIn (assertion failed).

PermissionDenied (insufficient grants/rights).

RateLimited (429).

AbuseFilter / SpamBlacklist / CaptchaNeeded (map Action API errors).

NetworkError (axios level).

Include wiki, title, and the underlying API error code in thrown errors where applicable.

Retries:

429 and 5xx: exponential backoff with jitter; honor Retry-After.

No automatic retry for semantic API errors (e.g., permission, abusefilter).

Logging & Privacy

Structured debug logs with request id, wiki, endpoint, attempt, and elapsed tim...

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[wvanderp]

@copilot you forgot to update the documentation like the readme.

and the linter fails

[Copilot]

@copilot you forgot to update the documentation like the readme.

and the linter fails

Fixed both issues in commit 4fe01e0:

Documentation: The README and AUTHENTICATION.md were already updated in the previous commits. The README now includes authentication examples with both OAuth2 and BotPassword, and AUTHENTICATION.md provides comprehensive setup and usage guides.

Linting: All 87 linting errors are now resolved. Changes include:

• Switched to default exports for auth providers
• Renamed SpamBlacklistError → SpamBlocklistError
• Fixed line lengths, variable names, and import patterns
• All 430 tests passing, build successful

Only 84 JSDoc documentation warnings remain (suggestions, not errors).

[wvanderp]

@copilot can you remove all the oauth stuff. I don't have time to test it.

Keep the bot login as that is what I need.

Clean up the pr to get it ready for merging

[Copilot]

@copilot can you remove all the oauth stuff. I don't have time to test it.

Keep the bot login as that is what I need....

Removed OAuth code and kept only Bot Password authentication in commit 24640da.

Changes:

• Removed OAuth2AuthCode.ts and tokenStore.ts
• Simplified types, utils, and index exports
• Updated AUTHENTICATION.md to focus on Bot Password only
• Updated README.md
• Added jest.config.js for ESM module support
• All 409 tests passing, linting clean

[Copilot]

@copilot can you remove all the oauth stuff. I don't have time to test it.

Keep the bot login as that is what I need....

Removed all OAuth code in commit dda1efb. The PR now only includes the Bot Password authentication (BotPasswordAuth).

Changes:

• Removed OAuth2AuthCode.ts, tokenStore.ts, and PKCE utilities
• Removed AUTHENTICATION.md
• Updated README to document only Bot Password auth
• Downgraded axios-cookiejar-support to v5.0.5 for CommonJS/Jest compatibility

All 41 test suites (409 tests) passing, build successful, linting clean.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://storage.googleapis.com/chromium-browser-snapshots/Linux_x64/1069273/chrome-linux.zip
  • Triggering command: /usr/local/bin/node node install.js (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[codecov]

Codecov Report

❌ Patch coverage is 95.07042% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.21%. Comparing base (d5a02c2) to head (da57126).
⚠️ Report is 12 commits behind head on main.

Files with missing lines	Patch %	Lines
src/auth/BotPasswordAuth.ts	89.83%	6 Missing ⚠️
src/auth/utils.ts	96.29%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #12      +/-   ##
==========================================
+ Coverage   94.08%   94.21%   +0.12%     
==========================================
  Files          43       46       +3     
  Lines         964     1106     +142     
  Branches      272      307      +35     
==========================================
+ Hits          907     1042     +135     
- Misses         57       64       +7     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

To fix the problem, ensure that the dots in the hostname and path (i.e., https://en.wikipedia.org/w/api.php) are escaped in the regular expression used for mocking. Specifically, when constructing the RegExp, replace every . in the hostname and path with \. to enforce matching literal periods. This requires escaping dots in the interpolation of apiURL. The best way is to modify the test code so that apiURL is converted to a string where each . is replaced by \. before embedding in the regex. This can be done using apiURL.replace(/\./g, '\\.') as part of the RegExp construction in the test suite. Change all relevant lines where a RegExp is constructed using unsanitized hostnames or full URLs.

Required changes:

• On all lines constructing a RegExp with ${apiURL} (lines 60 and 94), replace with ${apiURL.replace(/\./g, '\\.')} to escape the dots.

No imports or new methods are needed.

---

To fix the issue, escape all regular expression special characters in the interpolated apiURL variable in test mocks. The best way is to use a helper function to escape the string before constructing the regular expression. This can be done by adding a regexpEscape function within the test file and wrapping apiURL like so: new RegExp(${regexpEscape(apiURL)}.*action=query.*type=login). All instances where ${apiURL} is interpolated into RegExp constructors for axios-mock-adapter should be updated in the relevant code regions. Define the escape function (as a simple utility) near the top of the file (before the tests), so there is no need for external dependencies.

---

To fix the problem, all literal dots in domain names used as part of a regular expression should be escaped (\.), so that they match only a literal dot and not any character. In the affected lines, ${site} is https://en.wikipedia.org, and is used to form ${apiURL}.*action=query.*type=login in a regex pattern for mock API calls. We should ensure that every dot in the ${site} string is escaped in the resulting regex, e.g. converting https://en.wikipedia.org into https://en\.wikipedia\.org.

The single best way to fix this without breaking any existing test logic is to preprocess ${site} before interpolation, escaping every . with a backslash: site.replace(/\./g, '\\.'). Apply this change to all relevant places where the domain is used within a regex construction in this file.

Required changes:

• Update the definition of ${apiURL} or construct the regex such that the dots in ${site} are escaped.
• No new imports are needed.
• Only lines that interpolate ${site} within a RegExp construction should be updated.

To fix the problem, escape the periods in the host portion ('en.wikipedia.org') of the regex by replacing each . with \. in the string provided to the regex. This can be accomplished in the test by defining the site/apiURL with the correct (unescaped) value and then using a helper function or inline replacement to escape periods when interpolating into the regex construction. This ensures the mocked requests only match the exact URL (with actual dots), not arbitrary substitutions. Update all instances in the provided code where a regex is dynamically created using apiURL or similar variables that may contain unescaped periods in hostnames. No other dependencies are required; String.prototype.replace is sufficient.

---

The problem is caused by interpolating a URL string containing literal dots (e.g., en.wikipedia.org) directly into a regular expression constructor, resulting in those dots being interpreted as "any character" in RegExp patterns. To fix this, escape all dots that appear in the interpolated string before using it in a RegExp. The best way is to replace all occurrences of . with \. in the site value before constructing apiURL, or just before using in RegExp. A helper function should be added within the test to escape RegExp metacharacters in interpolated URLs. For this case, only dots need escaping, but using a general-purpose escape (escaping all RegExp metacharacters) is safer and more extensible. The required changes are:

• Add a small function in the test file to escape RegExp metacharacters.
• Use this function when constructing RegExp objects on lines 411 and 417 (and the identical uses in the second test at 442 and 448).
• No external dependencies are needed; a simple function suffices.
• The changes are all within tests/unit/auth/BotPasswordAuth.spec.ts.

To fix the problem, we need to ensure that whenever we interpolate a domain name (or anything containing dots meant to be literal), we escape each . with a backslash (\.) before building the regular expression. In this file, on lines 542–545, the variable site is assigned as 'https://en.wikipedia.org', and then used to create apiURL (which becomes 'https://en.wikipedia.org/w/api.php'). This is then interpolated in a regular expression on lines 545, 560, and 579.

The single best fix is to escape all . characters in the site (and therefore apiURL) before using it in regular expression construction. This is best done by introducing a utility line in the test that replaces every . with \. in the string before interpolation. It should be done for each location where the regular expression uses the domain (i.e., the interpolated apiURL). No dependency is needed; native JS String.prototype.replace suffices.

Edit the following code regions in tests/unit/auth/BotPasswordAuth.spec.ts:

• After assigning site, create an escapedSite variable.
• Use escapedSite in constructing apiURL for the regular expression purpose.
• Update the relevant mock stubs (lines 545, 560, 579) to use the correctly constructed regular expression.

---

To fix this issue, we should ensure that all dynamic hostnames or URLs interpolated into regular expressions have their metacharacters escaped, especially the dot (.), to avoid matching unintended strings. The best way is to escape all regex metacharacters in ${apiURL} before constructing the RegExp object. In particular, for a known pattern such as https://en.wikipedia.org/w/api.php, we should escape the dots. This can be achieved by passing apiURL through a helper function such as escapeRegExp before interpolation.

The code change will:

• Add a small utility function, escapeRegExp, at the top of the file before the tests.
• Replace usages of new RegExp(\${apiURL}.*action=query.*type=login`)(and similar) withnew RegExp(`${escapeRegExp(apiURL)}.*action=query.*type=login`)`.
  This will ensure all periods (and other metacharacters) in the host/domain/API path are properly escaped in the mock's regex matching.

No new imports are necessary; the utility is simple enough to define locally.

---