@griffinwork40/outlook-cli 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Griffin Long
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,325 @@
-# Temporary Holding Version
+# outlook-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A lightweight CLI wrapper for the **Microsoft Graph v1.0 Outlook Mail API** —
+read, search, send, reply, forward, draft, organize, and handle attachments
+from the shell or from an agent.
+
+Built so an AI agent can do everything email-related through a Microsoft
+account without a browser.
+
+---
+
+## Quick start
+
+```bash
+pnpm install && pnpm build
+
+# one-time: register an Azure app and export its client id (see SETUP.md)
+export GRAPH_CLIENT_ID=<application-client-id>
+
+outlook auth login      # device-code sign-in, ~30 seconds
+outlook me              # confirm which mailbox you are on
+outlook list            # newest inbox messages
+```
+
+**First time?** Read [SETUP.md](./SETUP.md). The Azure app registration is the
+only step that cannot be automated, and it takes about three minutes.
+
+---
+
+## Safety model
+
+Email is irreversible and reaches other people. Six deliberate guardrails:
+
+**1. `--dry-run` on every mutating command.** Prints the exact HTTP request that
+would be issued, then exits without touching the network. The short-circuit
+lives in one shared chokepoint (`guardMutation`), not in each command, so no
+command can forget it.
+
+```bash
+outlook send --to a@example.com --subject "Test" --body "Hi" --dry-run
+```
+```
+DRY RUN — nothing was sent. The request below is what would go out:
+
+POST https://graph.microsoft.com/v1.0/me/sendMail
+Content-Type: application/json
+
+{
+  "message": { "subject": "Test", ... },
+  "saveToSentItems": true
+}
+```
+
+**2. `delete` is recoverable; `purge` is not and is gated.** `outlook delete`
+*moves* the message to Deleted Items, where you can get it back. Microsoft's
+documentation never states whether a raw `DELETE` is recoverable, so that path
+is exposed separately as `outlook purge` and refuses to run without `--yes`.
+
+**3. Sends are never retried.** `sendMail`, `reply`, `replyAll`, `forward` and
+draft-send carry no idempotency guarantee — an automatic retry after a network
+timeout can deliver the message twice. The HTTP layer retries idempotent verbs
+(GET/DELETE/PATCH) on throttling, and deliberately does not retry POST.
+
+**4. Unknown flags are rejected, not ignored.** A misspelled flag is a hard
+error before anything runs. This matters more than it sounds: with a
+permissive parser, `--dryrun` is silently ignored, `dryRun` stays false, and
+"show me what would be sent" becomes "send it now." Every command declares its
+accepted flags in `src/flagSpec.ts`, and a test asserts no command can be
+registered without an entry.
+
+```bash
+outlook send --to a@example.com --subject "Test" --body "Hi" --dryrun
+```
+```
+Unknown flag for 'send': --dryrun
+Did you mean --dry-run?
+```
+
+**5. Confirmation flags cannot be faked.** `--yes` accepts only explicit
+boolean spellings. `--yes=false`, `--yes=0` and `--no-yes` all mean *no* — a
+user typing `--yes=false` to decline a permanent delete gets a refusal, not a
+deletion.
+
+**6. Least privilege is available.** `outlook auth login --readonly` requests
+`Mail.Read` instead of `Mail.ReadWrite` and drops `Mail.Send` entirely, so the
+**access** token this session carries cannot send, delete, or modify mail. The
+mode is recorded with the token and survives refreshes, and any mutating
+command fails fast against a read-only session. Recommended whenever an agent
+only needs to read.
+
+It narrows the blast radius; it is not a substitute for protecting the token
+file. The local read-only gate reads `mode` from that same file, and the cached
+refresh token is only as narrow as the consent your tenant has already recorded
+for this client — so someone holding the file can edit the mode back. Treat
+`--readonly` as reducing what a leaked token is worth, not as sealing it.
+
+```bash
+outlook auth login --readonly
+outlook send --to a@example.com --subject S --body B
+# This session was signed in with --readonly, so it cannot POST .../sendMail.
+```
+
+Credentialed requests are additionally pinned to HTTPS on the Graph host, so a
+malformed or hostile `@odata.nextLink` cannot redirect your bearer token to
+another server. See [docs/security-review-2026-08-07.md](./docs/security-review-2026-08-07.md)
+for the full audit and the two items deliberately left open.
+
+---
+
+## Restricted agent mode
+
+An unattended agent that only files mail should not be able to send, edit
+rules, or move messages anywhere it likes. Two opt-in controls narrow what the
+CLI will do for it. With neither set, behavior is unchanged.
+
+**1. A scoped token in its own cache.** `--scopes` requests exactly the listed
+scopes (`offline_access` is added if missing) and records that set with the
+token; `auth refresh` re-requests the same set rather than the default list, so
+the grant never widens. `GRAPH_TOKEN_CACHE` keeps it apart from your main
+login.
+
+```bash
+export GRAPH_TOKEN_CACHE=~/.afk/state/outlook/agent-token.json
+outlook auth login --scopes Mail.ReadWrite
+outlook auth status --json   # "grantScopes": ["offline_access", "Mail.ReadWrite"]
+```
+
+**2. A mutation policy.** `OUTLOOK_POLICY=<path>` points at a JSON file that
+every mutating request is checked against, inside the same `guardMutation`
+chokepoint that implements `--dry-run`. Reads are never affected.
+
+```json
+{
+  "$comment": "mail-filing agent: two destinations, nothing else",
+  "allowCommands": ["move", "mark-read"],
+  "move": {
+    "allowedDestinations": ["AAMkAGI2...ReviewFolderId", "archive"],
+    "denySenders": {
+      "file": "protected_senders.json",
+      "maxAgeHours": 48,
+      "destinations": ["AAMkAGI2...ReviewFolderId"]
+    }
+  }
+}
+```
+
+| Key | Effect |
+|---|---|
+| `allowCommands` | Mutating commands that may run. `"draft create"` allows one subcommand; `"draft"` allows them all. Anything else (send, reply, rules create, purge) is refused. |
+| `move.allowedDestinations` | Folder ids or well-known names a move (including `delete`, which moves to `deleteditems`) may target. Well-known names match case-insensitively; ids match exactly, so list the form the agent will pass. |
+| `move.denySenders` | Before a move into one of `destinations`, the CLI fetches the message's `from` (`GET /me/messages/{id}?$select=from`) and refuses if that address is in `file` (relative to the policy file): a JSON array of addresses, or `{"addresses": [...], "built_at": "<ISO time>"}`. |
+
+It fails closed. A missing, unparseable or misspelled policy file (unknown keys
+are errors) refuses every mutation. A deny list that is missing, unparseable,
+or older than `maxAgeHours` (by `built_at`, else file mtime) refuses moves to
+its destinations. A message with no sender address is refused for those
+destinations, and so is a message id that would change the request path
+(`../`, `%2e%2e`, backslashes).
+
+Refusals exit with code **4** and, under `--json`, print
+`{"error": {"code": "PolicyRefused", "rule": "...", "message": "..."}}` to
+stdout. `--dry-run` still prints the request without any network call and adds
+the policy's verdict; the deny-list sender lookup is a network call, so a dry
+run reports it as skipped.
+
+```bash
+export OUTLOOK_POLICY=~/.afk/config/agent-policy.json
+outlook send --to a@example.com --subject S --body B
+# Refused by mutation policy (allowCommands): 'send' is not in allowCommands   (exit 4)
+outlook move <id> --folder inbox --dry-run
+# ...request...
+# Policy (/home/me/.afk/config/agent-policy.json): would REFUSE (move.allowedDestinations): ...
+```
+
+The policy is a guard inside the CLI, not an operating-system boundary. A
+process that can run its own code as your user can read the token cache and
+call Graph directly, or unset the variable. Pair it with a scoped token (a
+`Mail.ReadWrite`-only token cannot send mail or edit inbox rules even outside
+the CLI), and keep the policy and deny list files out of the agent's write
+reach.
+
+---
+
+## Commands
+
+### Auth
+| Command | Purpose |
+|---|---|
+| `outlook auth login` | Device-code sign-in (`--readonly`, or `--scopes a,b` for an exact scope set) |
+| `outlook auth status` | Signed-in identity and token expiry (token never printed) |
+| `outlook auth refresh` | Force a token refresh |
+| `outlook auth logout` | Delete the cached token |
+
+A plain `outlook auth login` requests `offline_access`, `User.Read`,
+`Mail.ReadWrite`, `Mail.Send`, `MailboxSettings.ReadWrite`, `Contacts.Read`,
+`Calendars.Read`, `Files.Read.All` and `Sites.Read.All`. The last three are
+read-only and let the same token read calendar events and search or download
+OneDrive/SharePoint files through Graph. `Files.Read.All` and `Sites.Read.All`
+are delegated permissions that need **admin consent** in the Azure app
+registration on work/school tenants; `Calendars.Read` does not. See
+[SETUP.md](./SETUP.md#admin-consent-for-filesreadall-and-sitesreadall).
+`--readonly` keeps its smaller mail-only set.
+
+### Reading
+| Command | Purpose |
+|---|---|
+| `outlook me` | Your profile and primary address |
+| `outlook list [--folder <name\|id>] [--unread] [--all] [--limit N]` | List messages |
+| `outlook get <messageId> [--html]` | Full message, plain text by default |
+| `outlook search <kql> [--folder <name\|id>] [--limit N]` | KQL search across the mailbox |
+| `outlook folders list` | Mail folders with unread/total counts |
+| `outlook attachments list <messageId>` | Attachments on a message |
+| `outlook attachments download <messageId> <attachmentId> --out <path> [--force]` | Save an attachment |
+
+Folder arguments accept the well-known names — `inbox`, `drafts`, `sentitems`,
+`deleteditems`, `archive`, `junkemail`, and others — or a raw folder id.
+
+### Sending
+| Command | Purpose |
+|---|---|
+| `outlook send --to <addr> --subject <s> [--body <text> \| --body-file <path>] [--cc] [--bcc] [--html] [--attach <path>...] [--signature <path> \| --no-signature] [--no-save-sent]` | Send a message |
+| `outlook reply <messageId> --body <text>` | Reply to the sender |
+| `outlook reply-all <messageId> --body <text>` | Reply to everyone |
+| `outlook forward <messageId> --to <addr> [--body <text>]` | Forward |
+
+`--to`, `--cc`, `--bcc` and `--attach` are repeatable, and address flags also
+accept comma-separated lists.
+
+### Signatures
+
+Microsoft Graph never adds your Outlook signature to mail sent through the API,
+so the CLI appends one itself. Point it at a file once:
+
+```bash
+echo 'OUTLOOK_SIGNATURE_FILE=/Users/you/.config/outlook/signature.txt' >> ~/.afk/config/afk.env
+echo 'OUTLOOK_SIGNATURE_HTML_FILE=/Users/you/.config/outlook/signature.html' >> ~/.afk/config/afk.env  # optional
+```
+
+- **On by default once configured** for `send`, `draft create`, `reply`,
+  `reply-all` and `forward`. `--no-signature` skips it for one message;
+  `--signature <path>` uses a different file (`.html`/`.htm` = HTML).
+- **Plain-text bodies** get the RFC 3676 `-- ` delimiter and the text signature.
+  **HTML bodies** (`--html`) get the HTML signature, or the text one escaped.
+  An HTML-only setup with a plain-text body is an error, not a silent skip.
+- **Replies and forwards** use Graph's plain-text `comment`, so they take the
+  text signature, placed above the quoted original.
+- **No `--body`:** a reply, reply-all or forward without `--body` still sends the signature on its own, as Outlook does when you sign an empty reply.
+- **`draft update` never adds one** (it would duplicate the create-time copy).
+- **Visible, never silent:** `--dry-run` shows the appended text and `--json`
+  reports `signatureApplied`. An unreadable signature file is a hard error.
+- `~/.afk/config/afk.env` is shared by every afk agent on the machine, so any
+  agent sending through this CLI will sign as you. Export the variable per
+  shell instead if that is not what you want.
+- **HTML signature files are trusted and inserted verbatim** (no sanitisation).
+  Treat them like the token cache: restrict write access to the file owner
+  (`chmod 600 ~/sig.html`). Do not point the variable at world-writable paths.
+
+### Drafts
+| Command | Purpose |
+|---|---|
+| `outlook draft list` | List drafts |
+| `outlook draft create --subject <s> [--to ...] [--body ...] [--attach ...]` | Create a draft |
+| `outlook draft update <draftId> [--subject] [--body] [--to]` | Edit a draft |
+| `outlook draft send <draftId>` | Send an existing draft |
+
+Drafts are the safest way to send: compose, inspect, then send as a separate act.
+
+### Organizing
+| Command | Purpose |
+|---|---|
+| `outlook delete <messageId>` | Move to Deleted Items (**recoverable**) |
+| `outlook purge <messageId> --yes` | Hard delete (**may be unrecoverable**) |
+| `outlook move <messageId> --folder <name\|id>` | Move to a folder |
+| `outlook mark-read <messageId>` / `mark-unread` | Set read state |
+| `outlook flag <messageId>` / `unflag` | Set follow-up flag |
+| `outlook folders create --name <text>` | Create a folder (Graph creates at root only) |
+
+### Global flags
+| Flag | Effect |
+|---|---|
+| `--json` | Machine-readable output on every command |
+| `--dry-run` | Render the request, send nothing (mutating commands) |
+| `--help` / `-h` | Usage for the command |
+
+Pagination flags are **not** global — each command declares its own flags and
+rejects anything else (see "Unknown flags fail closed" above). `--all` is
+accepted by `list`, `search`, `folders`, `draft`, and `attachments`; `--limit N`
+by `list`, `search`, and `draft`. The authoritative list is `COMMAND_FLAGS` in
+[`src/flagSpec.ts`](./src/flagSpec.ts), and `outlook <command> --help` prints it.
+
+---
+
+## Notes and limits
+
+- **Attachments are inline only, under 3 MB.** Larger files need a Graph upload
+  session, which is not implemented; the CLI fails loudly with the actual file
+  size rather than truncating.
+- **Message ids change when a message moves between folders.** All reads send
+  `Prefer: IdType="ImmutableId"` so stored ids stay stable, but an id captured
+  before a `move` should not be reused after it.
+- **`$search` and `$orderby` are not combined.** Microsoft's docs do not confirm
+  that pairing for messages, so `search` omits ordering rather than emitting a
+  request that may be rejected.
+- **`$orderby` must agree with `$filter`.** Graph returns `InefficientFilter`
+  when ordering references properties the filter does not; the CLI surfaces that
+  with an explanation.
+
+## Development
+
+```bash
+pnpm test          # file-size gate + vitest
+pnpm typecheck     # tsc --noEmit
+pnpm build         # tsup -> dist/cli.js
+pnpm test:coverage
+```
+
+Tests never touch the network and never send mail: the HTTP layer is injected,
+and command tests run against a real client whose `fetch` throws, so any
+unguarded network call fails the suite instead of quietly passing.
+
+**No source file may exceed 350 lines** — enforced by
+`scripts/check-file-size.sh`, wired into `pnpm test`. At the ceiling, extract a
+concern into a new file rather than compressing an existing one.
+
+API reference notes gathered during the build live in `docs/`.

package/SETUP.md

@@ -0,0 +1,199 @@
+# Setup — one-time Azure app registration
+
+`outlook-cli` talks to your mailbox through the Microsoft Graph API. Microsoft
+requires every Graph client to be a registered application, so there is exactly
+one step a human has to do that no script can do for you: **register an app and
+copy its client ID.**
+
+It takes about three minutes, costs nothing, and needs no Azure subscription —
+a plain Microsoft account (outlook.com, hotmail, live) or a work/school account
+is enough.
+
+---
+
+## Why this step exists
+
+There is no "just give me an API key" path for Outlook mail. Microsoft issues
+credentials to *applications*, not to users, and a token is only ever minted
+after you personally sign in and consent. That is also what keeps this safe:
+the CLI never sees your password, and you can revoke its access at any time
+without changing your password.
+
+The client ID you create is **not a secret**. It identifies the app, not you.
+The device-code flow this CLI uses is designed for exactly this case — a
+command-line tool on a machine you control, with no client secret to leak.
+
+---
+
+## Step 1 — Open the app registration page
+
+Go to <https://entra.microsoft.com> → **Applications** → **App registrations**.
+
+Direct link: <https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade>
+
+(The older <https://portal.azure.com> → *Azure Active Directory* → *App
+registrations* path leads to the same screen.)
+
+Sign in with the Microsoft account whose mail you want the CLI to read.
+
+## Step 2 — New registration
+
+Click **+ New registration**.
+
+- **Name:** anything — `outlook-cli` is fine. Only you ever see it.
+- **Supported account types:** choose
+
+  > **Accounts in any organizational directory (Any Microsoft Entra ID tenant —
+  > Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)**
+
+  This is the option that makes one registration work for BOTH a personal
+  outlook.com mailbox and a work/school Microsoft 365 mailbox. Picking a
+  narrower option is the single most common reason sign-in later fails with
+  *"unauthorized_client"*.
+- **Redirect URI:** leave it **blank**. The device-code flow does not use one.
+
+Click **Register**.
+
+## Step 3 — Copy the client ID
+
+On the app's **Overview** page, copy **Application (client) ID**. It looks like:
+
+```
+11111111-2222-3333-4444-555555555555
+```
+
+That is your `GRAPH_CLIENT_ID`.
+
+## Step 4 — Turn on public client flows
+
+This is the step people miss, and it is required.
+
+Go to **Authentication** (left sidebar) → scroll to **Advanced settings** →
+**Allow public client flows** → set to **Yes** → **Save**.
+
+Without this, `outlook auth login` fails with:
+
+```
+AADSTS7000218: The request body must contain the following parameter:
+'client_assertion' or 'client_secret'.
+```
+
+That error means precisely this toggle is off — not that you need a secret.
+
+## Step 5 — Export the client ID and sign in
+
+```bash
+export GRAPH_CLIENT_ID=11111111-2222-3333-4444-555555555555
+outlook auth login
+```
+
+You will see something like:
+
+```
+To sign in, open https://microsoft.com/devicelogin and enter code ABCD-EFGH
+```
+
+Open that URL, enter the code, sign in, and approve the permission list. The
+CLI polls in the background and confirms once you are done. The token is cached
+at `~/.afk/state/outlook/token.json` (mode `0600`) and refreshes itself from
+then on — you should not need to log in again unless you revoke access.
+
+Verify:
+
+```bash
+outlook auth status
+outlook me
+```
+
+---
+
+## Making it permanent
+
+Add the export to your shell profile, or drop it in AFK's env file so every
+session picks it up:
+
+```bash
+echo 'GRAPH_CLIENT_ID=11111111-2222-3333-4444-555555555555' >> ~/.afk/config/afk.env
+```
+
+Optional variables (see `.env.example`):
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `GRAPH_CLIENT_ID` | *(required)* | Application (client) ID from Step 3 |
+| `GRAPH_TENANT_ID` | `common` | `common` supports personal **and** work accounts |
+| `GRAPH_CLIENT_SECRET` | *(unset)* | Only for confidential-client mode; leave blank |
+| `GRAPH_TOKEN_CACHE` | `~/.afk/state/outlook/token.json` | Token cache location |
+| `OUTLOOK_SIGNATURE_FILE` | *(unset)* | Plain-text signature appended to outgoing mail (see README "Signatures") |
+| `OUTLOOK_SIGNATURE_HTML_FILE` | *(unset)* | HTML signature used for `--html` bodies |
+
+---
+
+## What the CLI asks permission for
+
+At first sign-in Microsoft shows a consent screen listing these scopes:
+
+| Scope | Why it is needed |
+|---|---|
+| `offline_access` | Refresh the token so you sign in once, not daily |
+| `User.Read` | Read your own profile — powers `outlook me` |
+| `Mail.ReadWrite` | Read messages, manage drafts, flags, folders |
+| `Mail.Send` | Send, reply, forward |
+| `MailboxSettings.ReadWrite` | Read/write mailbox settings (needed for `rules create`) |
+| `Contacts.Read` | Read your contacts — powers `outlook contacts` |
+| `Calendars.Read` | Read your calendar events through Graph |
+| `Files.Read.All` | Read OneDrive and SharePoint files you can access (search and download) |
+| `Sites.Read.All` | Read SharePoint sites, documents and list items you can access |
+
+These are **delegated** permissions: the CLI can only ever do what *you* can do,
+and only while your token is valid. `outlook auth login --readonly` requests a
+smaller mail-only set (`offline_access`, `User.Read`, `Mail.Read`,
+`MailboxSettings.Read`) and none of the calendar or file scopes.
+
+### Admin consent for Files.Read.All and Sites.Read.All
+
+`Files.Read.All` and `Sites.Read.All` are delegated permissions that need
+**admin consent** in the Azure app registration on work/school tenants. Since
+August 2025 Microsoft's default user-consent policy ("Let Microsoft manage your
+consent settings") blocks users from consenting to them for third-party apps,
+so sign-in fails at the consent screen until an admin grants them. A tenant
+admin can do this once:
+
+**App registrations** → your app → **API permissions** → **+ Add a permission**
+→ **Microsoft Graph** → **Delegated permissions** → add `Files.Read.All` and
+`Sites.Read.All` (add the other scopes in the table too) → **Grant admin
+consent for &lt;tenant&gt;**.
+
+`Calendars.Read` does not need admin consent; like the mail scopes, the user
+approves it on the sign-in consent screen. Personal Microsoft accounts
+(outlook.com) have no tenant admin and consent to all of these scopes
+themselves.
+
+After upgrading from a version without these scopes, run `outlook auth logout`
+then `outlook auth login` so the new token carries them.
+
+## Revoking access
+
+<https://account.live.com/consent/Manage> (personal accounts) or your tenant's
+*Enterprise applications* blade (work accounts). Revoking is immediate and does
+not require deleting the app registration.
+
+To just clear the local token:
+
+```bash
+outlook auth logout
+```
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `AADSTS7000218 ... client_assertion or client_secret` | Public client flows off | Step 4 |
+| `AADSTS700016 ... application not found` | Wrong or unset `GRAPH_CLIENT_ID` | Re-copy from Step 3 |
+| `unauthorized_client` on a personal account | Registration is single-tenant | Re-do Step 2 with the multitenant + personal option |
+| `Missing required environment variable(s): GRAPH_CLIENT_ID` | Not exported | Step 5 |
+| `InvalidAuthenticationToken` on a call | Token expired and refresh failed | `outlook auth login` |
+| Sign-in works, mail calls 403 | Consent was declined or partial | `outlook auth logout` then log in again and accept all scopes |
+| Consent screen says "Need admin approval" (`AADSTS90094` / `AADSTS65001`) | Tenant blocks user consent to `Files.Read.All` / `Sites.Read.All` | Ask a tenant admin to grant admin consent (see "Admin consent" above), or sign in with `--readonly` / `--scopes` to skip those scopes |