outlook-cli AGENTS.md

AGENTS.md

Instructions for AI coding agents (Claude Code, Cursor, Aider, Codex, …) working on this repository.

If you only read one other file, read LEARNINGS.md. It documents the long sequence of dead ends we hit before landing on the current architecture. Skim it before proposing alternative approaches — most of the "obvious" ideas have already been tried and won't work in a locked-down enterprise tenant.

---

TL;DR — what this project is

A small Node.js CLI that talks to the Outlook REST API by capturing the Bearer JWT that Outlook Web (OWA) already uses for its own API calls. It does this by launching Playwright Chromium against the user's persistent profile, watching the network for the first authed request, and snapshotting the Authorization + routing headers to disk. Subsequent CLI calls reuse the cached headers from Node fetch without re-opening the browser.

Multiple resources (Outlook / Graph / Substrate)

Each Microsoft API is a separate OAuth resource with its own token audience; a token is only valid against its own resource. resources.mjs is the registry. Tokens are captured per-resource (captureAllTokens classifies every Bearer OWA/Teams/Copilot emit by audience), cached per-resource (auth-<resource>.json), and routed per-resource (call(auth, path, { resource }), getAuth({ resource })). outlook graph <path> is the generic Graph passthrough; outlook token-audit reports what's reachable. Reaching Teams/Copilot is a capture problem (get the right-audience token), not a consent problem — see LEARNINGS.md §13. Non-default resources never auto-launch the browser mid-command; they error toward auth --all.

TL;DR — hard constraints you must respect

1. Never add OAuth flows that require admin consent. The whole point of this project is to avoid them. Many corporate tenants block them. See LEARNINGS.md §1–4.
2. Never assume headless Chromium will work. Microsoft Conditional Access stalls silent SSO when the UA looks headless. We always launch headed. See LEARNINGS.md §10.
3. Never read tokens from the macOS keychain in Office identity slots. They're ACL-protected to Microsoft-signed binaries; CLI tools just get silent empty reads. See LEARNINGS.md §5.
4. Never authenticate with cookies alone against the REST API. The /api/v2.0/me/messages endpoint returns 401 on cookie-only calls — it requires a Bearer token with audience https://outlook.office.com/.
5. Don't commit anything from ~/.cache/outlook-spike/ or ~/.local/share/ outlook-spike/ into the repo. These contain real credentials. The .gitignore already protects against the obvious filenames; double-check anything you stage.