127 lines
7.1 KiB
Markdown
127 lines
7.1 KiB
Markdown
# 1Password integration (API keys & tokens)
|
||
|
||
Use 1Password as the single source of truth for Broccolini Bot secrets. Your `.env` file then holds only **Secret References** (`op://...`), so you never store plaintext tokens on disk.
|
||
|
||
---
|
||
|
||
## Setup checklist (extension + CLI)
|
||
|
||
| Step | What to do |
|
||
|------|------------|
|
||
| **1. Extension** | In Cursor: **Extensions** (Ctrl+Shift+X) → search **1Password** → **Install**. *(On WSL/Linux the extension may refuse to install; use the CLI path below instead.)* |
|
||
| **2. Choose account** | After installing: Command Palette (Ctrl+Shift+P) → **1Password: Choose account** → sign in and pick a vault. |
|
||
| **3. CLI** | Install 1Password CLI: `sudo apt install op` (WSL/Linux) or [install from 1Password](https://developer.1password.com/docs/cli/get-started/). Then run **`eval $(op signin)`** once per terminal (or add to your shell profile). |
|
||
| **4. Store secrets** | In 1Password: create an item (e.g. **Broccolini Bot**) and add custom fields for each secret (e.g. `DISCORD_TOKEN`, `MONGODB_URI`, `REFRESH_TOKEN`). Use **Copy reference** on each field. |
|
||
| **5. .env with refs** | In `broccolini-bot/.env`: put `KEY=op://Vault/ItemName/FIELD` for each secret (no plaintext). Use **1Password: Get from 1Password** in the editor to insert refs, or paste from step 4. |
|
||
| **6. Run bot** | From `broccolini-bot/`: **`npm run start:1p`** (or `op run --env-file=.env -- npm run start`). |
|
||
|
||
If the extension is not available on your OS, use **steps 3–6 only** (CLI + Secret References in `.env` + `op run`).
|
||
|
||
---
|
||
|
||
## Extensions and Cursor integration
|
||
|
||
| What | Where | Purpose |
|
||
|------|--------|--------|
|
||
| **1Password for VS Code** | [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=1Password.1password) | Works in Cursor. Save/retrieve secrets, Secret References, detect secrets, preview `op://` refs. [Docs](https://developer.1password.com/docs/vscode/). |
|
||
| **1Password Cursor Hooks** | [1Password Marketplace](https://marketplace.1password.com/integration/cursor-hooks) | Validates that **1Password Environments**–mounted `.env` files are present and valid before Cursor Agent runs shell commands. [Cursor Hooks docs](https://developer.1password.com/docs/cursor-hooks), [validate hook guide](https://developer.1password.com/docs/environments/cursor-hook-validate). |
|
||
|
||
- **VS Code extension:** Install in Cursor via Extensions (search “1Password”). Use **1Password: Get from 1Password** / **Save in 1Password** and Secret References in `.env` and code.
|
||
- **Cursor Hooks:** Uses **1Password Environments** with *locally mounted* `.env` files (Mac/Linux; requires 1Password app + `sqlite3`). Clone [1Password/cursor-hooks](https://github.com/1Password/cursor-hooks), add the hook to `.cursor/hooks`, and optionally `.1password/environments.toml` to declare which `.env` paths to validate. Then Cursor Agent only runs commands when those env files are mounted.
|
||
|
||
---
|
||
|
||
## 1. Install
|
||
|
||
- **1Password for VS Code / Cursor**
|
||
Install the [1Password extension](https://marketplace.visualstudio.com/items?itemName=1Password.1password) in Cursor. You can then use Secret References in files and autofill from your vault.
|
||
|
||
- **1Password CLI (`op`)**
|
||
Required for running the bot with secrets from 1Password. Full install and sign-in: **[Get started with 1Password CLI](https://developer.1password.com/docs/cli/get-started/)**.
|
||
- **Install:** Linux (WSL): `sudo apt install op`; Mac: Homebrew or [manual](https://developer.1password.com/docs/cli/get-started/); Windows: winget or manual.
|
||
- **Desktop app:** In 1Password app → **Settings** → **Developer** → turn on **Integrate with 1Password CLI** (Mac: optional Touch ID; Windows: turn on Windows Hello first; Linux: **Settings** → **Security** → **Unlock using system authentication**, then Developer → Integrate).
|
||
- **Sign in:** Run `eval $(op signin)` (or any `op` command); you’ll be prompted to authenticate.
|
||
|
||
---
|
||
|
||
## 2. Store secrets in 1Password
|
||
|
||
Create an item that will hold Broccolini Bot env vars, e.g. **“Broccolini Bot”** or **“Broccolini Bot Production”**.
|
||
|
||
- **Type:** API Credential or Secure Note.
|
||
- **Fields:** Add one custom field per secret. Field names must match the env var names (e.g. `DISCORD_TOKEN`, `MONGODB_URI`, `REFRESH_TOKEN`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, etc.).
|
||
Use the same names as in `.env.example` for the sensitive values.
|
||
|
||
You can use a second item (e.g. **“Broccolini Bot Test”**) with test-only values and point `.env.test` at it (see below).
|
||
|
||
---
|
||
|
||
## 3. Use Secret References in `.env`
|
||
|
||
In `.env` (and optionally `.env.test`), **do not** put real tokens. Use 1Password Secret References instead:
|
||
|
||
```bash
|
||
# Example: vault "Personal", item "Broccolini Bot", field "password" or custom field name
|
||
DISCORD_TOKEN=op://Personal/Broccolini Bot/DISCORD_TOKEN
|
||
MONGODB_URI=op://Personal/Broccolini Bot/MONGODB_URI
|
||
REFRESH_TOKEN=op://Personal/Broccolini Bot/REFRESH_TOKEN
|
||
GOOGLE_CLIENT_ID=op://Personal/Broccolini Bot/GOOGLE_CLIENT_ID
|
||
GOOGLE_CLIENT_SECRET=op://Personal/Broccolini Bot/GOOGLE_CLIENT_SECRET
|
||
# ... same for other secrets
|
||
```
|
||
|
||
- Replace **Personal** with your vault name.
|
||
- Replace **Broccolini Bot** with your item title (spaces are fine).
|
||
- The last part is the **field name** inside that item (e.g. `DISCORD_TOKEN`).
|
||
|
||
Non-secret values (IDs, ports, feature flags) can stay as plain text in `.env` if you prefer.
|
||
|
||
To get a reference from the 1Password app: open the item → click a field → “Copy reference”.
|
||
|
||
---
|
||
|
||
## 4. Run the bot with 1Password
|
||
|
||
From the **broccolini-bot** directory:
|
||
|
||
```bash
|
||
op run --env-file=.env -- npm run start
|
||
```
|
||
|
||
For the test env:
|
||
|
||
```bash
|
||
op run --env-file=.env.test -- npm run start:test
|
||
```
|
||
|
||
`op run` reads `.env` (or `.env.test`), resolves every `op://...` value with 1Password, and runs the command with the resolved environment. The bot’s `config.js` still reads from `process.env` as usual; no code changes are required.
|
||
|
||
---
|
||
|
||
## 5. npm scripts (already in package.json)
|
||
|
||
In `broccolini-bot/`:
|
||
|
||
- `npm run start:1p` — production env from 1Password (resolves `op://` from `.env`)
|
||
- `npm run start:test:1p` — test env from 1Password (resolves `op://` from `.env.test`)
|
||
|
||
---
|
||
|
||
## 6. Security notes
|
||
|
||
- **Do not commit `.env` or `.env.test`.** They are gitignored. Even with Secret References, keep them out of the repo.
|
||
- **Rotate secrets** in 1Password when needed; no need to edit local files if you only use references.
|
||
- The 1Password Cursor extension can fill Secret References in the editor; the CLI is what actually resolves them when you run the bot.
|
||
|
||
---
|
||
|
||
## Quick reference
|
||
|
||
| Task | Command / step |
|
||
|------|----------------|
|
||
| **CLI get started** | [Get started with 1Password CLI](https://developer.1password.com/docs/cli/get-started/) (install, desktop integration, sign in) |
|
||
| Sign in to CLI | `eval $(op signin)` — required so the session is loaded into your shell; plain `op signin` only prints the commands. |
|
||
| Run bot (production) | `op run --env-file=.env -- npm run start` |
|
||
| Run bot (test) | `op run --env-file=.env.test -- npm run start:test` |
|
||
| Copy a secret reference | 1Password app → item → field → “Copy reference” |
|