Develop

alchemy-web/src/content/docs/providers/1password/index.md

@@ -0,0 +1,120 @@
+---
+title: 1Password
+description: Securely manage secrets and credentials with 1Password
+---
+
+# 1Password
+
+The 1Password provider allows you to create and manage items in [1Password](https://1password.com) vaults, enabling secure secret management in your infrastructure-as-code deployments.
+
+## Installation
+
+::: code-group
+
+```sh [bun]
+bun add @1password/sdk
+```
+
+```sh [npm]
+npm install @1password/sdk
+```
+
+```sh [pnpm]
+pnpm add @1password/sdk
+```
+
+```sh [yarn]
+yarn add @1password/sdk
+```
+
+:::
+
+## Authentication
+
+The 1Password provider uses Service Account authentication. You'll need to:
+
+1. [Create a Service Account](https://my.1password.com/developer-tools/infrastructure-secrets/serviceaccount/) in your 1Password account
+2. Give the service account appropriate permissions in your vaults
+3. Set the `OP_SERVICE_ACCOUNT_TOKEN` environment variable
+
+```bash
+export OP_SERVICE_ACCOUNT_TOKEN=<your-service-account-token>
+```
+
+## Resources
+
+- [Item](./item.md) - Create and manage items (logins, secure notes, API credentials, etc.)
+- [ItemRef](./item.md#fetching-an-existing-item-itemref) - Fetch an existing item by vault ID and item ID
+
+## Example Usage
+
+```ts
+import { Item, ItemRef } from "alchemy/1password";
+
+// Create a secure note
+const note = await Item("app-secrets", {
+  vault: "vault-id",
+  title: "Application Secrets",
+  category: "SecureNote",
+  notes: "Important configuration data",
+  tags: ["production", "api"],
+});
+
+// Fetch an existing item
+const existingItem = await ItemRef({
+  vaultId: "vault-id",
+  itemId: "item-id",
+});
+console.log(existingItem.title);
+console.log(existingItem.fields);
+
+// Create a login item
+const login = await Item("service-login", {
+  vault: "vault-id",
+  title: "Service Account",
+  category: "Login",
+  fields: [
+    {
+      id: "username",
+      title: "Username",
+      fieldType: "Text",
+      value: "[email protected]",
+    },
+    {
+      id: "password",
+      title: "Password",
+      fieldType: "Concealed",
+      value: "secure-password",
+    },
+  ],
+  websites: [
+    {
+      url: "https://app.example.com",
+      label: "Application",
+      autofillBehavior: "AnywhereOnWebsite",
+    },
+  ],
+});
+
+// Create an API credential
+const apiKey = await Item("api-credentials", {
+  vault: "vault-id",
+  title: "Production API Key",
+  category: "ApiCredentials",
+  fields: [
+    {
+      id: "api-key",
+      title: "API Key",
+      fieldType: "Concealed",
+      value: "sk_live_xxxxx",
+      sectionId: "credentials",
+    },
+  ],
+  sections: [
+    {
+      id: "credentials",
+      title: "Credentials",
+    },
+  ],
+});
+```

alchemy-web/src/content/docs/providers/1password/item.md

@@ -0,0 +1,202 @@
+---
+title: Item
+description: Create and manage 1Password items including logins, secure notes, and API credentials
+---
+
+The Item resource lets you create and manage items in [1Password](https://1password.com) vaults, including logins, secure notes, API credentials, and more.
+
+## Minimal Example
+
+Create a basic secure note:
+
+```ts
+import { Item } from "alchemy/1password";
+
+const note = await Item("my-note", {
+  vault: "vault-id",
+  title: "My Secure Note",
+});
+```
+
+## Fetching an Existing Item (ItemRef)
+
+Use `ItemRef` to fetch an existing item by vault ID and item ID:
+
+```ts
+import { ItemRef } from "alchemy/1password";
+
+const item = await ItemRef({
+  vaultId: "abc123",
+  itemId: "xyz789",
+});
+
+// Access the full item data
+console.log(item.title);
+console.log(item.fields);
+console.log(item.notes);
+```
+
+:::note
+`ItemRef` is a read-only reference that does not manage the item's lifecycle. It simply fetches and returns the existing item data.
+:::
+
+## Login Item
+
+Create a login item with username, password, and website for autofill:
+
+```ts
+import { Item } from "alchemy/1password";
+
+const login = await Item("app-login", {
+  vault: "vault-id",
+  title: "My App Login",
+  category: "Login",
+  fields: [
+    {
+      id: "username",
+      title: "Username",
+      fieldType: "Text",
+      value: "[email protected]",
+    },
+    {
+      id: "password",
+      title: "Password",
+      fieldType: "Concealed",
+      value: "my-secret-password",
+    },
+  ],
+  websites: [
+    {
+      url: "https://app.example.com",
+      label: "Application",
+      autofillBehavior: "AnywhereOnWebsite",
+    },
+  ],
+});
+```
+
+## API Credential
+
+Create an API credential with custom sections:
+
+```ts
+import { Item } from "alchemy/1password";
+
+const apiCred = await Item("api-key", {
+  vault: "vault-id",
+  title: "Production API Key",
+  category: "ApiCredentials",
+  fields: [
+    {
+      id: "api-key",
+      title: "API Key",
+      fieldType: "Concealed",
+      value: "sk_live_xxxxx",
+      sectionId: "credentials",
+    },
+    {
+      id: "api-url",
+      title: "API URL",
+      fieldType: "Url",
+      value: "https://api.example.com/v1",
+      sectionId: "credentials",
+    },
+  ],
+  sections: [
+    {
+      id: "credentials",
+      title: "Credentials",
+    },
+  ],
+});
+```
+
+## Secure Note with Tags
+
+Create a secure note with tags for organization:
+
+```ts
+import { Item } from "alchemy/1password";
+
+const note = await Item("config-note", {
+  vault: "vault-id",
+  title: "Configuration Notes",
+  category: "SecureNote",
+  notes: "Important configuration details for production environment",
+  tags: ["production", "config", "sensitive"],
+});
+```
+
+## Prevent Deletion
+
+Create an item that won't be deleted when removed from Alchemy:
+
+```ts
+import { Item } from "alchemy/1password";
+
+const persistentItem = await Item("permanent-secret", {
+  vault: "vault-id",
+  title: "Permanent Secret",
+  category: "SecureNote",
+  notes: "This item will remain even after Alchemy cleanup",
+  delete: false,
+});
+```
+
+:::caution
+When `delete: false` is set, the item will remain in 1Password after your Alchemy stack is destroyed. You'll need to manually delete it from 1Password if you no longer need it.
+:::
+
+## Custom Service Account Token
+
+Use a specific service account token instead of the environment variable:
+
+```ts
+import { Item } from "alchemy/1password";
+
+const item = await Item("custom-auth-item", {
+  vault: "vault-id",
+  title: "Custom Auth Item",
+  serviceAccountToken: alchemy.secret(process.env.CUSTOM_OP_TOKEN),
+});
+```
+
+## Field Types
+
+The following field types are supported:
+
+| Field Type | Description |
+|------------|-------------|
+| `Text` | Plain text value |
+| `Concealed` | Hidden/password value |
+| `Url` | URL value |
+| `Email` | Email address |
+| `Phone` | Phone number |
+| `Totp` | One-time password |
+| `Date` | Date value |
+| `MonthYear` | Month/Year value |
+| `Address` | Address with components |
+| `CreditCardType` | Credit card type |
+| `CreditCardNumber` | Credit card number |
+| `Reference` | Reference to another item |
+| `SshKey` | SSH key |
+| `Menu` | Menu selection |
+
+## Item Categories
+
+The following item categories are supported:
+
+| Category | Description |
+|----------|-------------|
+| `Login` | Website login credentials |
+| `SecureNote` | Secure text notes |
+| `ApiCredentials` | API keys and tokens |
+| `Password` | Standalone password |
+| `CreditCard` | Credit card information |
+| `Identity` | Personal identity information |
+| `Database` | Database credentials |
+| `Server` | Server access credentials |
+| `SshKey` | SSH key pairs |
+| `Document` | Document storage |
+| `BankAccount` | Bank account details |
+| And more... | See 1Password documentation |

alchemy/package.json

@@ -38,6 +38,10 @@
       "bun": "./src/llms.ts",
       "import": "./lib/llms.js"
     },
+    "./1password": {
+      "bun": "./src/1password/index.ts",
+      "import": "./lib/1password/index.js"
+    },
     "./coinbase": {
       "bun": "./src/coinbase/index.ts",
       "import": "./lib/coinbase/index.js"
@@ -207,6 +211,7 @@
     "yaml": "^2.0.0"
   },
   "peerDependencies": {
+    "@1password/sdk": "^0.1.6",
     "@astrojs/cloudflare": "^12.6.4",
     "@aws-sdk/client-dynamodb": "^3.0.0",
     "@coinbase/cdp-sdk": "^0.10.0",
@@ -228,6 +233,9 @@
     "wrangler": "catalog:"
   },
   "peerDependenciesMeta": {
+    "@1password/sdk": {
+      "optional": true
+    },
     "@astrojs/cloudflare": {
       "optional": true
     },
@@ -284,6 +292,7 @@
     }
   },
   "devDependencies": {
+    "@1password/sdk": "^0.1.6",
     "@astrojs/cloudflare": "^12.6.4",
     "@aws-sdk/client-dynamodb": "^3.0.0",
     "@aws-sdk/client-ec2": "^3.868.0",