Merge pull request #3 from thedavidweng/plaid-dashboard-login-plans

Add Plaid dashboard flows and complete verification gate

Author: thedavidweng

.github/workflows/ci.yml

@@ -13,11 +13,11 @@ jobs:
         os: [ubuntu-latest, macos-latest]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-go@v5
+      - uses: actions/setup-go@v6
         with:
-          go-version: "1.25"
+          go-version-file: 'go.mod'
           cache: true
 
       - run: go vet ./...

.github/workflows/release.yml

@@ -28,7 +28,7 @@ jobs:
           go-version-file: 'go.mod'
 
       - name: Install Cosign
-        uses: sigstore/cosign-installer@v4.1.1
+        uses: sigstore/cosign-installer@v4.1.2
 
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v7

.github/workflows/website.yml

@@ -22,21 +22,22 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
         with:
-          node-version: '22'
-          cache: npm
-          cache-dependency-path: website/package-lock.json
+          node-version: '22.12.0'
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: '1.3'
       - name: Install and build
         run: |
-          npm ci
-          npm audit --audit-level=high
-          npm run build
+          bun install --frozen-lockfile
+          bun run test
+          bun run build
         working-directory: website
       - name: Upload Pages artifact
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v5
         with:
           path: website/dist
 
@@ -52,4 +53,4 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

.gitignore

@@ -24,7 +24,6 @@ dist/
 # Frontend (Astro).
 website/node_modules/
 website/dist/
-website/test/
 
 # Local test artifacts
 .playwright-mcp/

.goreleaser.yaml

@@ -15,7 +15,7 @@ builds:
       - arm64
 
 archives:
-  - format: tar.gz
+  - formats: [tar.gz]
     name_template: "money_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
 
 checksum:
@@ -26,15 +26,13 @@ release:
     owner: thedavidweng
     name: money
 
-brews:
+homebrew_casks:
   - name: money
+    binaries:
+      - money
     repository:
       owner: thedavidweng
       name: homebrew-tap
       token: "{{ .Env.HOMEBREW_TAP_GITHUB_TOKEN }}"
-    directory: Formula
     homepage: "https://github.com/thedavidweng/money"
-    description: "A local-first, self-hostable personal finance backend for AI agents and power users."
-    license: MIT
-    install: |
-      bin.install "money"
+    description: "Local-first personal finance backend for agents and power users"

IMPLEMENTATION_PLAN.md

@@ -41,6 +41,7 @@ The Ray OpenRay documents are especially important. They define the product lang
 - A **Sync** updates local data only.
 - Read commands must not require AI keys or provider credentials.
 - Provider commands require provider credentials and should fail explicitly when missing.
+- Plaid Dashboard login may bootstrap local Plaid API credentials, but it remains a Plaid-specific setup convenience: it writes the same Provider credential contract as manual configuration, stores Dashboard auth beside the resolved config, and keeps manual `money providers configure plaid` as the supported fallback if Dashboard contracts reject or drift.
 
 When command, data model, or Provider behavior can be answered by donor code, prefer donor evidence before asking product questions. Use Ray Finance as the primary engineering donor for local data model decisions, Provider sync, Plaid/Bridge flow, encrypted local storage behavior, imports, local annotations, and query fields. Use `monarchmoney-cli` for command naming habits, JSON envelopes, stdout/stderr behavior, exit codes, safety gates, and agent-facing ergonomics. If Ray lacks a feature, do not invent a first-version stable contract from Monarch alone; defer it unless it is required by `money`'s goals. Ask only when donor behavior conflicts with `money` boundaries or a real product trade-off remains.
 
@@ -451,6 +452,10 @@ Initial commands:
 - `money link`
 - `money providers configure plaid`
 - `money providers configure bridge`
+- `money plaid login`
+- `money plaid logout`
+- `money providers plaid login`
+- `money providers plaid logout`
 - `money providers plaid link`
 - `money providers bridge link`
 - `money sync`

README.md

@@ -39,10 +39,10 @@ Existing personal finance tools either lock data behind a paid SaaS, embed opini
 ### Quick Start
 
 ```bash
-# Install via Homebrew (macOS/Linux)
-brew install thedavidweng/tap/money
+# Install via Homebrew Cask (macOS/Linux)
+brew install --cask thedavidweng/tap/money
 
-# Or install via Go (cross-platform)
+# Or install via Go (macOS/Linux/cross-platform)
 go install github.com/thedavidweng/money/cmd/money@latest
 
 # Initialize configuration and encrypted database (interactive)
@@ -57,6 +57,17 @@ money accounts list --json
 money transactions search "Costco" --json
 ```
 
+If you installed an older Homebrew formula release, migrate to the cask:
+
+```bash
+brew update
+brew uninstall --formula thedavidweng/tap/money
+brew install --cask thedavidweng/tap/money
+money version
+```
+
+Your local `~/.money` config, secrets, and database are not removed by uninstalling the old formula.
+
 Try it without real credentials:
 
 ```bash
@@ -91,6 +102,9 @@ money items remove <id>             Remove a linked provider item with cascade d
 # Provider Management
 money link                          Link a financial institution
 money providers configure <provider> Configure provider credentials
+money plaid login                    Sign in to Plaid Dashboard and fetch API keys
+money plaid logout                   Remove Plaid Dashboard auth; keep API keys
+money plaid sandbox link             Create and store a Plaid Sandbox Provider Item
 money providers plaid link          Link a Plaid Provider Item
 money providers bridge link         Link a Bridge Provider Item
 money sync                          Sync linked provider data (supports --start-date/--end-date)

docs/ARCHITECTURE.md

@@ -161,13 +161,17 @@ When an alternate config path is selected, its default env companion is `.env` i
 
 Provider secret names should follow the provider's common official vocabulary. For Plaid, use `PLAID_CLIENT_ID`, `PLAID_SECRET`, `PLAID_ENV`, `PLAID_PRODUCTS`, `PLAID_COUNTRY_CODES`, and `PLAID_REDIRECT_URI`. For Bridge, use `BRIDGE_CLIENT_ID` and `BRIDGE_CLIENT_SECRET`. For MX, use `MX_CLIENT_ID` and `MX_API_KEY`. For Finicity, use `FINICITY_APP_KEY`, `FINICITY_PARTNER_ID`, and `FINICITY_PARTNER_SECRET`.
 
+Plaid Dashboard login is a Plaid-specific credential bootstrap flow, not a generic Provider interface. `money plaid login` and `money providers plaid login` use the Plaid CLI-compatible Dashboard OAuth path to fetch API keys, then write only `PLAID_CLIENT_ID` and the selected environment's `PLAID_SECRET` through the normal Provider config writer. Dashboard OAuth tokens are stored separately as `plaid-dashboard-auth.json` beside the resolved config file with the same local-user file security expectations as `.env`. If Plaid rejects or changes the private Dashboard contract, the command fails explicitly and tells the user to configure Plaid manually; it must not try alternate private clients, scraping, or hidden fallback behavior.
+
 Plaid defaults to the `transactions` product. Additional products such as `investments` and `liabilities` require explicit configuration and should not expand stable read contracts until their local data model is ready. Recurring transaction streams should be synced when the configured Provider returns them; otherwise `recurring.list` returns an empty local result with a normal success envelope.
 
 Bridge link creates or reuses a Bridge external user ID without creating a `money` user account. By default `money` generates and stores the external user ID in Provider Item state during link. Advanced commands may accept an existing external user ID for reconnect or migration cases.
 
 Provider link flows may use a short-lived localhost callback helper when required by the Provider, such as Plaid Link. This helper is not a required persistent server, local API, daemon, or background service. It should bind only for the active link session, use a random state value, shut down after completion or timeout, and fail explicitly when the callback cannot be started. Interactive link commands should follow GitHub CLI's browser flow: print the authorization URL and wait for the user to press Enter before opening the browser. If the user does not press Enter, nothing is opened and the printed URL remains usable for manual/headless handling. `--no-open` suppresses browser opening for SSH, cron, and headless environments while still printing the URL.
 
-Plaid Link in CLI mode is implemented as a short-lived local Link page, not as a raw Plaid redirect URL. The command creates a Plaid `link_token`, starts a localhost callback/page server, prints the local URL, waits for Enter, then opens that local URL unless `--no-open` is set. The page loads Plaid Link from Plaid's CDN with the `link_token`; on `onSuccess`, it posts the `public_token`, Plaid institution metadata, selected account metadata, and random state back to the localhost helper. The CLI validates state, exchanges the `public_token` for an access token, stores only the encrypted access token and mapped metadata, then shuts down the helper. The helper must not expose general API endpoints or serve real financial data.
+Plaid Link in CLI mode is implemented as a short-lived local Link page, not as a raw Plaid redirect URL. The command creates a Plaid `link_token`, starts a localhost callback/page server, prints the local URL, waits for Enter, then opens that local URL unless `--no-open` is set. The page loads Plaid Link from Plaid's CDN with the `link_token`; on `onSuccess`, it posts a `success` callback containing the `public_token`, Plaid institution metadata, selected account metadata, and random state back to the localhost helper. On `onExit`, it posts either a `cancel` callback or an `error` callback with Plaid's error type/code/message plus request and link-session metadata when available. The CLI validates state and same-host origin, exchanges only success callbacks for access tokens, stores only the encrypted access token and mapped metadata, then shuts down the helper. Cancel and Link error callbacks do not exchange a token. The helper must not expose general API endpoints or serve real financial data.
+
+Plaid Link consent product options are explicit configuration/flag inputs. `products` remains the initial product set. `additional_consented_products`, `required_if_supported_products`, and `optional_products` may be configured or passed to Plaid link commands to shape consent without expanding local stable read contracts. Unsupported Plaid product names fail validation before calling Plaid.
 
 Bridge link uses the same browser ergonomics but does not pretend to be Plaid Link. The Bridge adapter creates a connect session, prints the connect URL, waits for Enter before opening unless `--no-open` is set, then polls or checks provider item state according to Bridge's API. If Bridge institution discovery is unavailable in the first adapter, `money link` omits Bridge from institution-first choices and `money providers bridge link` remains the supported path.
 

docs/CONFIG.md

@@ -21,6 +21,9 @@ providers:
     environment: sandbox
     products: [transactions]
     country_codes: [US]
+    additional_consented_products: [investments]
+    required_if_supported_products: [liabilities]
+    optional_products: [auth]
     redirect_uri:
       env: PLAID_REDIRECT_URI
   bridge:
@@ -30,7 +33,7 @@ providers:
       env: BRIDGE_CLIENT_SECRET
 ```
 
-Direct scalar values are allowed only for non-secrets such as `database.path`, `providers.plaid.environment`, `products`, and `country_codes`. Direct scalar secrets are accepted for manually edited files, but config loading emits a structured warning recommending `.env` references.
+Direct scalar values are allowed only for non-secrets such as `database.path`, `providers.plaid.environment`, `products`, `country_codes`, and Plaid Link consent product lists. Direct scalar secrets are accepted for manually edited files, but config loading emits a structured warning recommending `.env` references.
 
 ## Path Resolution
 
@@ -60,6 +63,8 @@ Profile names must be alphanumeric, hyphen, or underscore only; path traversal c
 
 Environment variables complete explicit references; they do not form a magic override chain. For example, `PLAID_SECRET` is used only when config says `secret: { env: PLAID_SECRET }` or a setup/configure command writes that reference.
 
+Plaid Dashboard OAuth bootstrap state is stored outside YAML at `plaid-dashboard-auth.json` beside the resolved config file. It is local bootstrap state for `money plaid login`, written `0600`, and may include Dashboard access/refresh tokens plus selected `team_id` and `client_id`. Provider API credentials still use the normal `.env` plus YAML `env:` references model.
+
 ## Pseudocode
 
 ```text

docs/CONTRACTS.md

@@ -152,19 +152,39 @@ Provider errors are classified as:
 
 Reconnect-required provider states are machine-readable through item status or classified provider errors. Removed provider transactions are soft-deleted: normal reads exclude them, `--removed include|only` can show them, and permanent purge is reserved for an explicit confirmed cleanup command.
 
+Shared command error codes include:
+
+| Code | Category | Retryable | Exit code | Meaning |
+| --- | --- | --- | --- | --- |
+| `BASE_CONFIG_MISSING` | `config` | false | 3 | `money plaid login` was run before the base config exists. |
+| `NOT_LOGGED_IN` | `auth` | false | 3 | Dashboard-only operation needs Plaid Dashboard auth. |
+| `TEAM_SELECTION_REQUIRED` | `validation` | false | 2 | Multiple Plaid Dashboard teams exist and no interactive or `--team` selection was available. |
+| `API_KEYS_FETCH_REQUIRED` | `auth` | true | 3 | Dashboard auth exists but Plaid API keys still need to be fetched. |
+| `DASHBOARD_TOKEN_REFRESH_FAILED` | `auth` | false | 3 | Stored Dashboard refresh token cannot refresh; rerun `money plaid login`. |
+| `DASHBOARD_CONTRACT_CHANGED` | `api` | false | 6 | Plaid Dashboard private response shape no longer matches the known CLI-compatible contract. |
+| `PLAID_DASHBOARD_LOGIN_REJECTED` | `auth` | false | 3 | Plaid rejected the CLI-compatible Dashboard OAuth path. |
+| `PLAID_CREDENTIALS_OVERWRITE_REQUIRED` | `safety` | false | 10 | Existing Plaid API credentials would be replaced and `--force` is required. |
+| `PLAID_ENVIRONMENT_NOT_PROVISIONED` | `validation` | false | 2 | Dashboard returned no secret for the selected Plaid environment. |
+| `READ_ONLY_VIOLATION` | `safety` | false | 4 | The command would mutate local config, env, store, or auth files while read-only mode is enabled. |
+
 ## Examples
 
 ```bash
 money setup --json
 money doctor --json
 money version --json
 money providers configure plaid --client-id ... --secret ... --environment sandbox --json
+money plaid login --json
+money providers plaid login --json
+money plaid logout --json
 money demo accounts list --json
 money demo transactions list --json --merchant Coffee --pending true --limit 10
 money demo transactions search coffee --json --limit 5
 money sync --json
 money sync --provider plaid --provider-item pi_example --json
 money sync --start-date 2024-01-01 --end-date 2024-03-01 --json
+money providers plaid link --optional-products auth --additional-consented-products investments
+money plaid sandbox link --products transactions --institution-id ins_56
 
 # Read synced data
 money investments holdings --json
@@ -174,6 +194,21 @@ money items list --json
 money items rename <id> "My Bank" --json
 ```
 
+## Link Commands
+
+Plaid link commands are human-mode browser flows. JSON mode is rejected for live Link because completion depends on a local callback.
+
+`money link <institution-query>` and `money providers plaid link` support:
+
+- `--no-open`
+- `--additional-consented-products`
+- `--required-if-supported-products`
+- `--optional-products`
+
+The three consent flags accept comma-separated Plaid product names and are validated before Plaid is called. `products` remains the configured initial product set. Canceling Plaid Link exits without exchanging a public token or writing a Provider Item. Plaid Link errors preserve Plaid error type/code/message plus request and link session metadata internally for diagnostics.
+
+`money plaid sandbox link` creates a Plaid Sandbox public token, exchanges it through the same Provider Item persistence path as browser Link, and stores the linked item in the encrypted local store. It only runs when `providers.plaid.environment` is `sandbox`. `balance` is rejected as an initial product instead of being remapped.
+
 ## Setup Command
 
 `setup --json` returns:
@@ -239,6 +274,38 @@ Default output is plain text: `money 0.1.0 (commit abc1234)`.
 }
 ```
 
+## Plaid Dashboard Login Commands
+
+`plaid login --json` and `providers plaid login --json` return:
+
+```json
+{
+  "provider": "plaid",
+  "team_id": "team_...",
+  "environment": "sandbox",
+  "keys_written": 2,
+  "credential_action": "written",
+  "dashboard_auth_path": "/Users/you/.money/plaid-dashboard-auth.json",
+  "next_command": "money link <institution-query>",
+  "config_path": "/Users/you/.money/config.yaml",
+  "env_path": "/Users/you/.money/.env"
+}
+```
+
+`plaid logout --json` and `providers plaid logout --json` return:
+
+```json
+{
+  "provider": "plaid",
+  "dashboard_auth_removed": true,
+  "dashboard_auth_path": "/Users/you/.money/plaid-dashboard-auth.json",
+  "api_keys_preserved": true,
+  "env_path": "/Users/you/.money/.env"
+}
+```
+
+These commands never include Plaid API secrets, Dashboard OAuth tokens, masked secrets, or reversible previews.
+
 ## Monarch Compatibility Notes
 
 The command names and stdout/stderr discipline follow Monarch CLI habits where useful. `money` differs by using object-wrapped collection fields, multi-error envelopes, explicit source provenance, encrypted local storage, and BYOK Provider adapters.