|
| 1 | +# AI Agent Guidelines for auth0-spa-js |
| 2 | + |
| 3 | +This document provides context and guidelines for AI coding assistants working with the auth0-spa-js codebase. |
| 4 | + |
| 5 | +## Your Role |
| 6 | + |
| 7 | +You are a TypeScript SDK engineer working on auth0-spa-js, the Auth0 authentication SDK for browser-based single-page applications. You write small, well-tested, tree-shakeable code, and you keep the browser SPA use case — where the SDK runs in a hostile environment — front of mind. |
| 8 | + |
| 9 | +--- |
| 10 | + |
| 11 | +## Working Principles |
| 12 | + |
| 13 | +Apply these on every task in this repo — they keep changes correct, small, and reviewable. |
| 14 | + |
| 15 | +- **Think before coding.** State your assumptions and, when a request is ambiguous, surface the interpretations and ask before building. Recommend a simpler approach when you see one. A clarifying question up front beats a wrong implementation. |
| 16 | +- **Simplicity first.** Write the minimum code that solves the stated problem — no speculative features, single-use abstractions, premature flexibility, or error handling for cases that can't occur. |
| 17 | +- **Surgical changes.** Touch only what the request requires. Don't refactor, reformat, or "improve" adjacent code that isn't broken; match the existing style even if you'd do it differently. Every changed line should trace directly to the request. Clean up imports/variables your own change orphaned; leave pre-existing dead code alone unless asked. |
| 18 | +- **Goal-driven execution.** Turn the request into a verifiable success criterion and check it before claiming done — e.g. "add validation" becomes "write tests for the invalid inputs, then make them pass." Don't report success you haven't verified. |
| 19 | + |
| 20 | +--- |
| 21 | + |
| 22 | +## Project Overview |
| 23 | + |
| 24 | +**auth0-spa-js** is the Auth0 SDK for Single-Page Applications — authorization-code + PKCE login, token caching, and silent refresh in the browser. |
| 25 | + |
| 26 | +- **Language:** TypeScript (compiled to ES2017 UMD/ESM/CJS + worker bundles via Rollup) |
| 27 | +- **Package manager:** npm (CI builds on Node 22) |
| 28 | +- **Test:** Jest (unit, jsdom) + Cypress (integration, against a local mock OIDC provider) |
| 29 | +- **Dependencies:** `@auth0/auth0-auth-js` (foundational OAuth/MFA client), `dpop` (RFC 9449 proofs), `browser-tabs-lock`, `es-cookie` — see `package.json` (the authoritative, never-stale source) |
| 30 | + |
| 31 | +--- |
| 32 | + |
| 33 | +## Project Structure |
| 34 | + |
| 35 | +```text |
| 36 | +src/ |
| 37 | + ├─ index.ts # entry point — createAuth0Client() factory + re-exports |
| 38 | + ├─ Auth0Client.ts # main client; orchestrates PKCE authorization-code flow |
| 39 | + ├─ global.ts # public types (Auth0ClientOptions, etc.) |
| 40 | + ├─ api.ts # token endpoint calls + Auth0-Client telemetry header |
| 41 | + ├─ cache/ # ICache + InMemoryCache / LocalStorageCache |
| 42 | + ├─ transaction-manager.ts # PKCE verifier + app state across redirects |
| 43 | + ├─ dpop/ # DPoP proof generation (RFC 9449) |
| 44 | + ├─ mfa/ # MFA client (wraps @auth0/auth0-auth-js) |
| 45 | + ├─ myaccount/ # MyAccount API client |
| 46 | + ├─ passkey/ # passkey (WebAuthn) enrollment + login |
| 47 | + ├─ http.ts # low-level fetch: timeout, retry, DPoP; switchFetch() worker/non-worker routing |
| 48 | + ├─ fetcher.ts # HTTP wrapper: auth header + DPoP injection |
| 49 | + └─ worker/token.worker.ts # refreshes tokens off the main thread |
| 50 | +__tests__/ # Jest unit specs (mirror src/) cypress/ # e2e |
| 51 | +docs/ # generated TypeDoc output (do not hand-edit) |
| 52 | +``` |
| 53 | + |
| 54 | +Key files: `src/index.ts` (entry), `src/Auth0Client.ts` (core), `src/api.ts` (telemetry header lives here), `src/errors.ts` (error hierarchy, rooted at `GenericError`). |
| 55 | + |
| 56 | +--- |
| 57 | + |
| 58 | +## Boundaries |
| 59 | + |
| 60 | +### ✅ Always Do |
| 61 | + |
| 62 | +- Run `npm test` and `npm run lint` before committing |
| 63 | +- Add Jest specs for new behavior; keep code ES2017-clean (`npm run test:es-check`) and tree-shakeable |
| 64 | +- Update `README.md` and `EXAMPLES.md` in the same PR when changing the public API, options, or supported integration patterns |
| 65 | +- Keep the version in sync across its sources — `.version`, `src/version.ts`, `package.json`, and the `README.md` / `FAQ.md` pins (wired via `.shiprc`). Reference these files rather than pasting a version number into prose. |
| 66 | +- When adding a **new request path to Auth0** (not every feature — most ride on the shared transport), route it through the existing `src/api.ts` fetch layer so it carries the `Auth0-Client` header (base64 `{name,version,env}`) — don't create a separate HTTP client. Since this SDK wraps `@auth0/auth0-auth-js`, preserve the `auth0Client` wrapping (this SDK's name/version, the wrapped lib under `env`) and the opt-out. |
| 67 | + |
| 68 | +### ⚠️ Ask First |
| 69 | + |
| 70 | +- **Any breaking change — always ask first.** Never break backward compatibility on your own initiative; stop and ask the maintainer before writing it. (On approval, document the upgrade path in the migration guide for the target major.) |
| 71 | +- Adding/bumping runtime dependencies (they ship in the browser bundle — watch bundle size) |
| 72 | +- Modifying the public API on `Auth0Client` / `createAuth0Client` / `global.ts` |
| 73 | +- Changes to token storage, DPoP proof generation, PKCE, or the web-worker refresh path |
| 74 | +- Changes to `.github/workflows/` or the Rollup build config |
| 75 | + |
| 76 | +### 🚫 Never Do |
| 77 | + |
| 78 | +- Commit secrets, API keys, or tokens |
| 79 | +- Log or expose `access_token` / `refresh_token` / `id_token` — especially not to the main thread when the web worker is in use |
| 80 | +- Disable PKCE, or weaken DPoP proofs |
| 81 | +- Hand-edit `dist/` or `docs/` (generated build/TypeDoc output) |
| 82 | +- Remove or skip failing tests instead of fixing them |
| 83 | + |
| 84 | +--- |
| 85 | + |
| 86 | +## Security Considerations |
| 87 | + |
| 88 | +- **PKCE:** always used for the authorization-code flow — never expose an option to disable it. |
| 89 | +- **Token storage:** in-memory by default (`InMemoryCache`); `LocalStorageCache` is opt-in and documented as higher-risk. With refresh tokens + in-memory cache, refresh happens in a **web worker** (`src/worker/token.worker.ts`) to keep tokens off the main thread. |
| 90 | +- **DPoP:** `src/dpop/` binds tokens to a key pair (RFC 9449); `fetcher.ts` attaches the proof. Don't bypass it when DPoP is enabled. |
| 91 | +- **Silent auth:** hidden-iframe `prompt=none` needs a custom domain to survive third-party-cookie restrictions. |
| 92 | + |
| 93 | +--- |
| 94 | + |
| 95 | +> The sections below are **reference** — each keeps a one-line anchor inline and offloads its body to `references/*.md` behind a linked pointer. Read a pointer only when the task needs it. |
| 96 | +
|
| 97 | +## Commands |
| 98 | + |
| 99 | +```bash |
| 100 | +# Unit tests (with coverage) |
| 101 | +npm test |
| 102 | + |
| 103 | +# Lint |
| 104 | +npm run lint |
| 105 | + |
| 106 | +# Dev server with live reload (http://localhost:3000) |
| 107 | +npm run dev |
| 108 | + |
| 109 | +# Production build (UMD + ESM + CJS + worker bundles; runs test:es-check) |
| 110 | +npm run build |
| 111 | +``` |
| 112 | + |
| 113 | +See [references/commands.md](references/commands.md) for the full command list (integration/Cypress, es-check, bundle stats, security lint, docs, release). Read only when you need to run, build, or test something beyond the four above. |
| 114 | + |
| 115 | +--- |
| 116 | + |
| 117 | +## Testing |
| 118 | + |
| 119 | +The default `npm test` suite is **unit-only — no credentials required** (Jest + jsdom, in `__tests__/`). The Cypress integration tier runs against a **local** mock OIDC provider — not a live tenant. |
| 120 | + |
| 121 | +See [references/testing.md](references/testing.md) for conventions, mocking utilities, the integration/Cypress commands, and coverage. Read when writing or debugging tests. |
| 122 | + |
| 123 | +--- |
| 124 | + |
| 125 | +## Code Style |
| 126 | + |
| 127 | +`PascalCase` types/classes, `camelCase` members; ESLint + Prettier (single quotes, no trailing commas, 80-col). Code must stay ES2017-clean and tree-shakeable. |
| 128 | + |
| 129 | +See [references/code-style.md](references/code-style.md) for the full conventions — linter/formatter setup, naming, bundle discipline, and dominant patterns. Read when writing or reviewing code. |
| 130 | + |
| 131 | +--- |
| 132 | + |
| 133 | +## Git Workflow |
| 134 | + |
| 135 | +Conventional Commits, **enforced by commitlint** — a non-conforming message (or PR title) fails CI. Allowed types: `feat, fix, docs, chore, build, refactor, test, ci, perf, revert`. |
| 136 | + |
| 137 | +See [references/git-workflow.md](references/git-workflow.md) for branch naming and PR requirements (template + required checks). Read when committing or opening a PR. |
| 138 | + |
| 139 | +--- |
| 140 | + |
| 141 | +## Common Pitfalls |
| 142 | + |
| 143 | +The high-frequency traps: **don't move worker-side token refresh onto the main thread**, silent-iframe auth needs a custom domain, and new code must stay ES2017-clean + tree-shakeable. |
| 144 | + |
| 145 | +See [references/pitfalls.md](references/pitfalls.md) for the full list with fixes (web-worker token exposure, third-party-cookie silent auth, bundle/ES level, DPoP online-mode dual checks, wrapping `@auth0/auth0-auth-js`). Read when touching token handling, the web worker, DPoP, bundling, or the auth-js wrapping. |
| 146 | + |
| 147 | +--- |
| 148 | + |
| 149 | +## Docs Update Rules |
| 150 | + |
| 151 | +Tracked docs are `README.md` and `EXAMPLES.md`. A PR that changes the public API, configuration, or supported patterns is **not complete** until they're updated in the same PR (enforced by the Always Do boundary above). |
| 152 | + |
| 153 | +See [references/docs-update.md](references/docs-update.md) for the full code-to-docs mapping — which doc to touch for each kind of change. Read when changing the public API, config, install requirements, token/cache/DPoP behavior, or adding an integration pattern. |
0 commit comments