@mediaviz/sdk 0.1.0

package/oauth/src/__tests__/http.test.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const { postForm, getJson } = require('../http');
+const { OAuthError } = require('../errors');
+
+describe('postForm', () => {
+  afterEach(() => jest.restoreAllMocks());
+
+  it('sends urlencoded POST and returns parsed JSON on 2xx', async () => {
+    const mockResponse = { access_token: 'tok', token_type: 'bearer', expires_in: 3600, refresh_token: 'ref' };
+    jest.spyOn(global, 'fetch').mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => mockResponse,
+    });
+
+    const result = await postForm('https://example.com/token', { grant_type: 'authorization_code', code: 'abc' });
+
+    expect(result).toEqual(mockResponse);
+    const [url, init] = global.fetch.mock.calls[0];
+    expect(url).toBe('https://example.com/token');
+    expect(init.method).toBe('POST');
+    expect(init.headers['Content-Type']).toBe('application/x-www-form-urlencoded');
+    expect(init.body).toContain('grant_type=authorization_code');
+    expect(init.body).toContain('code=abc');
+  });
+
+  it('throws OAuthError on non-2xx with RFC 6749 body', async () => {
+    jest.spyOn(global, 'fetch').mockResolvedValue({
+      ok: false,
+      status: 400,
+      json: async () => ({ error: 'invalid_grant', error_description: 'Code expired' }),
+    });
+
+    await expect(postForm('https://example.com/token', {})).rejects.toThrow(OAuthError);
+
+    try {
+      await postForm('https://example.com/token', {});
+    } catch (err) {
+      expect(err.code).toBe('invalid_grant');
+      expect(err.description).toBe('Code expired');
+      expect(err.httpStatus).toBe(400);
+    }
+  });
+
+  it('throws OAuthError with server_error fallback for non-RFC body', async () => {
+    jest.spyOn(global, 'fetch').mockResolvedValue({
+      ok: false,
+      status: 500,
+      json: async () => ({ message: 'Something broke' }),
+    });
+
+    await expect(postForm('https://example.com/token', {})).rejects.toMatchObject({
+      code: 'server_error',
+      httpStatus: 500,
+    });
+  });
+
+  it('merges extra headers', async () => {
+    jest.spyOn(global, 'fetch').mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({}),
+    });
+
+    await postForm('https://example.com/token', {}, { 'X-Custom': 'value' });
+    const [, init] = global.fetch.mock.calls[0];
+    expect(init.headers['X-Custom']).toBe('value');
+  });
+});
+
+describe('getJson', () => {
+  afterEach(() => jest.restoreAllMocks());
+
+  it('sends GET and returns parsed JSON on 2xx', async () => {
+    const mockData = { user_id: 'u1' };
+    jest.spyOn(global, 'fetch').mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => mockData,
+    });
+
+    const result = await getJson('https://example.com/me', { Authorization: 'Bearer tok' });
+    expect(result).toEqual(mockData);
+    const [url, init] = global.fetch.mock.calls[0];
+    expect(url).toBe('https://example.com/me');
+    expect(init.headers['Authorization']).toBe('Bearer tok');
+  });
+
+  it('throws OAuthError on non-2xx', async () => {
+    jest.spyOn(global, 'fetch').mockResolvedValue({
+      ok: false,
+      status: 401,
+      json: async () => ({ error: 'invalid_token', error_description: 'Expired' }),
+    });
+
+    await expect(getJson('https://example.com/me')).rejects.toMatchObject({
+      code: 'invalid_token',
+      httpStatus: 401,
+    });
+  });
+});

package/oauth/src/__tests__/index.test.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const sdk = require('../index');
+
+describe('barrel export (index.js)', () => {
+  test('exports OAuthClient', () => {
+    expect(typeof sdk.OAuthClient).toBe('function');
+  });
+
+  test('exports OAuthError', () => {
+    expect(typeof sdk.OAuthError).toBe('function');
+  });
+
+  test('exports OAuthErrorCode', () => {
+    expect(typeof sdk.OAuthErrorCode).toBe('object');
+    expect(sdk.OAuthErrorCode).not.toBeNull();
+  });
+
+  test('OAuthErrorCode is frozen', () => {
+    expect(Object.isFrozen(sdk.OAuthErrorCode)).toBe(true);
+  });
+
+  test('OAuthErrorCode contains required codes', () => {
+    expect(sdk.OAuthErrorCode.INVALID_REQUEST).toBe('invalid_request');
+    expect(sdk.OAuthErrorCode.INVALID_CLIENT).toBe('invalid_client');
+    expect(sdk.OAuthErrorCode.INVALID_GRANT).toBe('invalid_grant');
+    expect(sdk.OAuthErrorCode.UNAUTHORIZED_CLIENT).toBe('unauthorized_client');
+    expect(sdk.OAuthErrorCode.UNSUPPORTED_GRANT_TYPE).toBe('unsupported_grant_type');
+    expect(sdk.OAuthErrorCode.ACCESS_DENIED).toBe('access_denied');
+    expect(sdk.OAuthErrorCode.SERVER_ERROR).toBe('server_error');
+  });
+
+  test('OAuthClient is instantiable with config', () => {
+    const client = new sdk.OAuthClient({
+      baseUrl: 'https://auth.example.com',
+      clientId: 'cid',
+      clientSecret: 'csecret',
+      redirectUri: 'https://myapp.com/callback',
+    });
+    expect(client).toBeInstanceOf(sdk.OAuthClient);
+  });
+
+  test('OAuthError is a subclass of Error', () => {
+    const err = new sdk.OAuthError('server_error', 'boom', 500);
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(sdk.OAuthError);
+  });
+
+  test('no unexpected exports', () => {
+    const keys = Object.keys(sdk);
+    expect(keys.sort()).toEqual(['OAuthClient', 'OAuthError', 'OAuthErrorCode'].sort());
+  });
+});

package/oauth/src/__tests__/package-fields.test.js

@@ -0,0 +1,29 @@
+const path = require('path');
+const pkg = require('../../package.json');
+
+describe('package.json build fields (task 5)', () => {
+  test('main points to CJS entry', () => {
+    expect(pkg.main).toBe('src/index.js');
+  });
+
+  test('module field points to ESM dist', () => {
+    expect(pkg.module).toBe('dist/oauth-sdk.esm.js');
+  });
+
+  test('browser field points to UMD dist', () => {
+    expect(pkg.browser).toBe('dist/oauth-sdk.umd.js');
+  });
+
+  test('files includes src/ and dist/', () => {
+    expect(pkg.files).toContain('src/');
+    expect(pkg.files).toContain('dist/');
+  });
+
+  test('build script runs rollup', () => {
+    expect(pkg.scripts.build).toBe('rollup -c');
+  });
+
+  test('prepublishOnly runs build', () => {
+    expect(pkg.scripts.prepublishOnly).toBe('npm run build');
+  });
+});

package/oauth/src/__tests__/pkce.test.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const { generateCodeVerifier, generateCodeChallenge, generateState } = require('../pkce');
+
+const VERIFIER_ALPHABET = /^[A-Za-z0-9\-._~]+$/;
+
+describe('generateCodeVerifier', () => {
+  test('returns a 64-character string', () => {
+    expect(generateCodeVerifier()).toHaveLength(64);
+  });
+
+  test('only contains valid PKCE alphabet characters', () => {
+    expect(generateCodeVerifier()).toMatch(VERIFIER_ALPHABET);
+  });
+
+  test('generates unique values', () => {
+    expect(generateCodeVerifier()).not.toBe(generateCodeVerifier());
+  });
+});
+
+describe('generateCodeChallenge', () => {
+  // RFC 7636 Appendix B test vector
+  const KNOWN_VERIFIER = 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk';
+  const KNOWN_CHALLENGE = 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM';
+
+  test('matches known PKCE S256 test vector', async () => {
+    expect(await generateCodeChallenge(KNOWN_VERIFIER)).toBe(KNOWN_CHALLENGE);
+  });
+
+  test('output has no base64 padding', async () => {
+    const challenge = await generateCodeChallenge(generateCodeVerifier());
+    expect(challenge).not.toContain('=');
+  });
+
+  test('output uses URL-safe base64 (no + or /)', async () => {
+    for (let i = 0; i < 20; i++) {
+      const challenge = await generateCodeChallenge(generateCodeVerifier());
+      expect(challenge).not.toMatch(/[+/]/);
+    }
+  });
+});
+
+describe('generateState', () => {
+  test('returns a 32-character string', () => {
+    expect(generateState()).toHaveLength(32);
+  });
+
+  test('is lowercase hex', () => {
+    expect(generateState()).toMatch(/^[0-9a-f]{32}$/);
+  });
+
+  test('generates unique values', () => {
+    expect(generateState()).not.toBe(generateState());
+  });
+});

package/oauth/src/__tests__/rollup-build.test.js

@@ -0,0 +1,58 @@
+const path = require('path');
+const fs = require('fs');
+
+const distDir = path.resolve(__dirname, '../../dist');
+const umdPath = path.join(distDir, 'oauth-sdk.umd.js');
+const esmPath = path.join(distDir, 'oauth-sdk.esm.js');
+
+describe('Rollup build output', () => {
+  test('dist/oauth-sdk.umd.js exists', () => {
+    expect(fs.existsSync(umdPath)).toBe(true);
+  });
+
+  test('dist/oauth-sdk.esm.js exists', () => {
+    expect(fs.existsSync(esmPath)).toBe(true);
+  });
+
+  test('UMD bundle is non-empty and minified (single line)', () => {
+    const content = fs.readFileSync(umdPath, 'utf8').trim();
+    expect(content.length).toBeGreaterThan(100);
+    // terser produces a single line
+    expect(content.split('\n').length).toBe(1);
+  });
+
+  test('UMD bundle registers OAuthSDK global', () => {
+    const content = fs.readFileSync(umdPath, 'utf8');
+    expect(content).toContain('OAuthSDK');
+  });
+
+  test('UMD bundle exports OAuthClient, OAuthError, OAuthErrorCode', () => {
+    const content = fs.readFileSync(umdPath, 'utf8');
+    expect(content).toContain('OAuthClient');
+    expect(content).toContain('OAuthError');
+    expect(content).toContain('OAuthErrorCode');
+  });
+
+  test('ESM bundle uses export syntax', () => {
+    const content = fs.readFileSync(esmPath, 'utf8');
+    expect(content).toMatch(/export\s*\{/);
+  });
+
+  test('UMD bundle uses Web Crypto (no require crypto)', () => {
+    const content = fs.readFileSync(umdPath, 'utf8');
+    expect(content).not.toContain("require('crypto')");
+    expect(content).toContain('globalThis.crypto');
+  });
+
+  test('rollup.config.js exists', () => {
+    const configPath = path.resolve(__dirname, '../../rollup.config.js');
+    expect(fs.existsSync(configPath)).toBe(true);
+  });
+
+  test('package.json includes rollup dev dependencies', () => {
+    const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../../package.json'), 'utf8'));
+    expect(pkg.devDependencies).toHaveProperty('rollup');
+    expect(pkg.devDependencies).toHaveProperty('@rollup/plugin-node-resolve');
+    expect(pkg.devDependencies).toHaveProperty('@rollup/plugin-terser');
+  });
+});

package/oauth/src/__tests__/smoke-test.test.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const SDK_ROOT = path.resolve(__dirname, '..', '..', '..', '..', '..');
+const JS_ROOT = path.resolve(__dirname, '..', '..');
+
+describe('task 6: smoke-test and gitignore', () => {
+  test('smoke-test.js exits 0', () => {
+    const result = execSync(`node ${path.join(JS_ROOT, 'smoke-test.js')}`, { encoding: 'utf8' });
+    expect(result.trim()).toBe('OK');
+  });
+
+  test('.gitignore includes dist/', () => {
+    const gitignore = fs.readFileSync(path.join(JS_ROOT, '.gitignore'), 'utf8');
+    const lines = gitignore.split('\n').map(l => l.trim());
+    expect(lines).toContain('dist/');
+  });
+
+  test('smoke-test.js awaits generateAuthorizationUrl', () => {
+    const src = fs.readFileSync(path.join(JS_ROOT, 'smoke-test.js'), 'utf8');
+    expect(src).toMatch(/await\s+client\.generateAuthorizationUrl\(\)/);
+  });
+});

package/oauth/src/__tests__/types.test.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const { OAuthErrorCode } = require('../types');
+
+describe('OAuthErrorCode', () => {
+  test('has all required error codes with correct values', () => {
+    expect(OAuthErrorCode.INVALID_REQUEST).toBe('invalid_request');
+    expect(OAuthErrorCode.INVALID_CLIENT).toBe('invalid_client');
+    expect(OAuthErrorCode.INVALID_GRANT).toBe('invalid_grant');
+    expect(OAuthErrorCode.UNAUTHORIZED_CLIENT).toBe('unauthorized_client');
+    expect(OAuthErrorCode.UNSUPPORTED_GRANT_TYPE).toBe('unsupported_grant_type');
+    expect(OAuthErrorCode.ACCESS_DENIED).toBe('access_denied');
+    expect(OAuthErrorCode.SERVER_ERROR).toBe('server_error');
+  });
+
+  test('is frozen (immutable)', () => {
+    expect(Object.isFrozen(OAuthErrorCode)).toBe(true);
+  });
+
+  test('mutation attempt does not change values', () => {
+    const original = OAuthErrorCode.INVALID_REQUEST;
+    try { OAuthErrorCode.INVALID_REQUEST = 'mutated'; } catch (_) {}
+    expect(OAuthErrorCode.INVALID_REQUEST).toBe(original);
+  });
+
+  test('has exactly 7 entries', () => {
+    expect(Object.keys(OAuthErrorCode).length).toBe(7);
+  });
+});

package/oauth/src/client.js

@@ -0,0 +1,180 @@
+'use strict';
+
+const { generateCodeVerifier, generateCodeChallenge, generateState } = require('./pkce');
+const { postForm, postJson } = require('./http');
+const { OAuthError } = require('./errors');
+
+class OAuthClient {
+  /**
+   * @param {import('./types').OAuthClientConfig} config
+   */
+  constructor(config) {
+    this._config = config;
+    this._inFlightRefreshes = new Map();
+  }
+
+  /**
+   * @param {import('./types').ClientRegistrationRequest} params
+   * @returns {Promise<import('./types').ClientRegistrationResponse>}
+   */
+  static async registerClient(params) {
+    const baseUrl = params.baseUrl.replace(/\/+$/, '');
+    return postJson(`${baseUrl}/oauth/clients`, {
+      client_name: params.clientName,
+      client_type: params.clientType,
+      redirect_uris: params.redirectUris,
+      is_first_party: params.isFirstParty,
+    });
+  }
+
+  /**
+   * @param {string} [state]
+   * @returns {import('./types').AuthorizationUrlResult}
+   */
+  async generateAuthorizationUrl(state) {
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = await generateCodeChallenge(codeVerifier);
+    const resolvedState = state ?? generateState();
+
+    const params = new URLSearchParams({
+      response_type: 'code',
+      client_id: this._config.clientId,
+      redirect_uri: this._config.redirectUri,
+      state: resolvedState,
+      code_challenge: codeChallenge,
+      code_challenge_method: 'S256',
+    });
+
+    return {
+      url: `${this._config.baseUrl}/oauth/authorize?${params}`,
+      state: resolvedState,
+      code_verifier: codeVerifier,
+    };
+  }
+
+  /**
+   * @param {string} code
+   * @param {string} codeVerifier
+   * @param {string} [redirectUri]
+   * @returns {Promise<import('./types').TokenResponse>}
+   */
+  async exchangeCode(code, codeVerifier, redirectUri) {
+    return postForm(`${this._config.baseUrl}/oauth/token`, {
+      grant_type: 'authorization_code',
+      code,
+      code_verifier: codeVerifier,
+      redirect_uri: redirectUri ?? this._config.redirectUri,
+      client_id: this._config.clientId,
+      client_secret: this._config.clientSecret,
+    });
+  }
+
+  /**
+   * RFC 6749 §4.4 — machine-to-machine token exchange. No user login.
+   * Returned TokenResponse has no refresh_token.
+   * @returns {Promise<import('./types').TokenResponse>}
+   */
+  async getClientCredentialsToken() {
+    return postForm(`${this._config.baseUrl}/oauth/token`, {
+      grant_type: 'client_credentials',
+      client_id: this._config.clientId,
+      client_secret: this._config.clientSecret,
+    });
+  }
+
+  /**
+   * @param {string} refreshToken
+   * @returns {Promise<import('./types').TokenResponse>}
+   */
+  async refreshAccessToken(refreshToken) {
+    return postForm(`${this._config.baseUrl}/oauth/token`, {
+      grant_type: 'refresh_token',
+      refresh_token: refreshToken,
+      client_id: this._config.clientId,
+      client_secret: this._config.clientSecret,
+    });
+  }
+
+  /**
+   * @param {string} token
+   * @param {string} [tokenTypeHint]
+   * @returns {Promise<void>}
+   */
+  async revokeToken(token, tokenTypeHint) {
+    const params = { token, client_id: this._config.clientId, client_secret: this._config.clientSecret };
+    if (tokenTypeHint) params.token_type_hint = tokenTypeHint;
+    await postForm(`${this._config.baseUrl}/oauth/revoke`, params);
+  }
+
+  /**
+   * Makes an authenticated request with 401-intercept-and-retry.
+   *
+   * `onRefreshSuccess` fires synchronously the moment the rotated tokens are received,
+   * BEFORE the retry. The server has already deleted the old refresh token by then;
+   * if the retry throws, the new tokens would otherwise be lost in this call frame.
+   * Long-lived callers MUST persist via this callback — not from the resolved value —
+   * to stay in sync with single-use refresh-token rotation (RFC 6749 §6).
+   *
+   * @param {string} url
+   * @param {string} method
+   * @param {string} accessToken
+   * @param {string} refreshToken
+   * @param {object} [body]
+   * @param {(newTokens: import('./types').TokenResponse) => void} [onRefreshSuccess]
+   * @returns {Promise<import('./types').AuthenticatedResponse>}
+   */
+  async request(url, method, accessToken, refreshToken, body, onRefreshSuccess) {
+    const buildOptions = (token) => {
+      const headers = { Authorization: `Bearer ${token}` };
+      const options = { method, headers };
+      if (body != null) {
+        headers['Content-Type'] = 'application/json';
+        options.body = JSON.stringify(body);
+      }
+      return options;
+    };
+
+    const firstResponse = await fetch(`${this._config.baseUrl}${url}`, buildOptions(accessToken));
+
+    if (firstResponse.status !== 401) {
+      const json = await firstResponse.json();
+      if (!firstResponse.ok) throw OAuthError.fromResponse(firstResponse.status, json);
+      return { data: json, updatedTokens: null };
+    }
+
+    // 401: attempt refresh — propagate OAuthError if refresh fails.
+    // Concurrent request() callers with the same refresh_token share one in-flight
+    // call so the server only sees one rotation (the second would get invalid_grant).
+    let pending = this._inFlightRefreshes.get(refreshToken);
+    if (!pending) {
+      pending = this.refreshAccessToken(refreshToken).finally(() => {
+        this._inFlightRefreshes.delete(refreshToken);
+      });
+      this._inFlightRefreshes.set(refreshToken, pending);
+    }
+    const newTokens = await pending;
+
+    if (onRefreshSuccess) onRefreshSuccess(newTokens);
+
+    const retryResponse = await fetch(`${this._config.baseUrl}${url}`, buildOptions(newTokens.access_token));
+    const retryJson = await retryResponse.json();
+    if (!retryResponse.ok) throw OAuthError.fromResponse(retryResponse.status, retryJson);
+    return { data: retryJson, updatedTokens: newTokens };
+  }
+
+  /**
+   * Decodes a JWT access token payload without verifying the signature.
+   * @param {string} accessToken
+   * @returns {import('./types').TokenPayload}
+   */
+  decodeAccessToken(accessToken) {
+    const segment = accessToken.split('.')[1];
+    if (!segment) throw new OAuthError('invalid_token', 'Malformed JWT', 400);
+    const b64 = segment.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(segment.length / 4) * 4, '=');
+    const bytes = Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+    const payload = JSON.parse(new TextDecoder().decode(bytes));
+    return payload;
+  }
+}
+
+module.exports = { OAuthClient };

package/oauth/src/errors.js

@@ -0,0 +1,32 @@
+'use strict';
+
+class OAuthError extends Error {
+  /**
+   * @param {string} code - RFC 6749 error code
+   * @param {string} description - Human-readable description
+   * @param {number} httpStatus - HTTP status code
+   * @param {unknown} [body] - Raw response body (parsed JSON when available)
+   */
+  constructor(code, description, httpStatus, body = null) {
+    super(description);
+    this.name = 'OAuthError';
+    this.code = code;
+    this.description = description;
+    this.httpStatus = httpStatus;
+    this.body = body;
+  }
+
+  /**
+   * @param {number} status
+   * @param {unknown} body
+   * @returns {OAuthError}
+   */
+  static fromResponse(status, body) {
+    if (body && typeof body === 'object' && typeof body.error === 'string') {
+      return new OAuthError(body.error, body.error_description ?? '', status, body);
+    }
+    return new OAuthError('server_error', 'Unexpected server response', status, body);
+  }
+}
+
+module.exports = { OAuthError };

package/oauth/src/http.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const { OAuthError } = require('./errors');
+
+/**
+ * @param {string} url
+ * @param {Record<string, string>} params
+ * @param {Record<string, string>} [headers]
+ * @returns {Promise<unknown>}
+ */
+async function postForm(url, params, headers = {}) {
+  const body = new URLSearchParams(params).toString();
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', ...headers },
+    body,
+  });
+  const json = await response.json();
+  if (!response.ok) throw OAuthError.fromResponse(response.status, json);
+  return json;
+}
+
+/**
+ * @param {string} url
+ * @param {Record<string, string>} [headers]
+ * @returns {Promise<unknown>}
+ */
+async function getJson(url, headers = {}) {
+  const response = await fetch(url, { headers });
+  const json = await response.json();
+  if (!response.ok) throw OAuthError.fromResponse(response.status, json);
+  return json;
+}
+
+/**
+ * @param {string} url
+ * @param {object} body
+ * @param {Record<string, string>} [headers]
+ * @returns {Promise<unknown>}
+ */
+async function postJson(url, body, headers = {}) {
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...headers },
+    body: JSON.stringify(body),
+  });
+  const json = await response.json();
+  if (!response.ok) throw OAuthError.fromResponse(response.status, json);
+  return json;
+}
+
+module.exports = { postForm, getJson, postJson };

package/oauth/src/index.js

@@ -0,0 +1,7 @@
+'use strict';
+
+const { OAuthClient } = require('./client');
+const { OAuthError } = require('./errors');
+const { OAuthErrorCode } = require('./types');
+
+module.exports = { OAuthClient, OAuthError, OAuthErrorCode };

package/oauth/src/pkce.js

@@ -0,0 +1,50 @@
+'use strict';
+
+// base64url-encode a Uint8Array without padding
+function base64urlEncode(bytes) {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+  let result = '';
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i];
+    const b1 = i + 1 < bytes.length ? bytes[i + 1] : 0;
+    const b2 = i + 2 < bytes.length ? bytes[i + 2] : 0;
+    result += chars[b0 >> 2];
+    result += chars[((b0 & 3) << 4) | (b1 >> 4)];
+    if (i + 1 < bytes.length) result += chars[((b1 & 0xf) << 2) | (b2 >> 6)];
+    if (i + 2 < bytes.length) result += chars[b2 & 0x3f];
+  }
+  return result;
+}
+
+/**
+ * Generates a 64-character PKCE code verifier from [A-Za-z0-9-._~].
+ * @returns {string}
+ */
+function generateCodeVerifier() {
+  const bytes = new Uint8Array(48);
+  globalThis.crypto.getRandomValues(bytes);
+  return base64urlEncode(bytes).slice(0, 64);
+}
+
+/**
+ * Computes Base64URL(SHA256(verifier)) with no padding.
+ * @param {string} verifier
+ * @returns {Promise<string>}
+ */
+async function generateCodeChallenge(verifier) {
+  const encoded = new TextEncoder().encode(verifier);
+  const hashBuf = await globalThis.crypto.subtle.digest('SHA-256', encoded);
+  return base64urlEncode(new Uint8Array(hashBuf));
+}
+
+/**
+ * Generates a cryptographically random 32-char hex state value.
+ * @returns {string}
+ */
+function generateState() {
+  const bytes = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(bytes);
+  return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+module.exports = { generateCodeVerifier, generateCodeChallenge, generateState };