@pokit/op 0.0.1 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pokit/op",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Operation utilities for pok CLI applications",
   "keywords": [
     "cli",
@@ -25,9 +25,8 @@
   "bugs": {
     "url": "https://github.com/notation-dev/openpok/issues"
   },
-  "main": "./src/index.ts",
-  "module": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "bun": "./src/index.ts",
@@ -38,13 +37,14 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "src"
   ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@pokit/core": "0.0.1"
+    "@pokit/core": "0.0.3"
   },
   "devDependencies": {
     "@types/bun": "latest"

package/src/checks.ts

@@ -0,0 +1,25 @@
+import { defineCheck } from '@pokit/core';
+import { isInstalled, isAuthenticated, getAuthErrorMessage } from './op';
+
+export const opInstalled = defineCheck({
+  label: '1Password CLI installed',
+  check: async () => {
+    const installed = await isInstalled();
+    if (!installed) {
+      throw new Error(
+        '1Password CLI is not installed. ' +
+          'Install from: https://developer.1password.com/docs/cli/get-started/'
+      );
+    }
+  },
+});
+
+export const opAuthenticated = defineCheck({
+  label: '1Password authenticated',
+  check: async () => {
+    const authenticated = await isAuthenticated();
+    if (!authenticated) {
+      throw new Error(getAuthErrorMessage());
+    }
+  },
+});

package/src/op.ts

@@ -0,0 +1,239 @@
+import { $ } from 'bun';
+
+// =============================================================================
+// Input Validation
+// =============================================================================
+
+/**
+ * Valid characters for 1Password identifiers (vault, item, field names).
+ * Allows alphanumeric, spaces, dashes, underscores, and periods.
+ */
+const VALID_IDENTIFIER_PATTERN = /^[a-zA-Z0-9 _.-]+$/;
+
+/**
+ * Validate a 1Password identifier (vault name, item name, or field name).
+ * Throws if the identifier contains invalid characters.
+ */
+function validateIdentifier(value: string, type: 'vault' | 'item' | 'field'): void {
+  if (!value || value.trim().length === 0) {
+    throw new Error(`${type} name cannot be empty`);
+  }
+  if (!VALID_IDENTIFIER_PATTERN.test(value)) {
+    throw new Error(
+      `Invalid ${type} name: "${value}". Only alphanumeric characters, spaces, dashes, underscores, and periods are allowed.`
+    );
+  }
+}
+
+// =============================================================================
+// Authentication
+// =============================================================================
+
+/**
+ * Check if 1Password CLI is installed
+ */
+export async function isInstalled(): Promise<boolean> {
+  const result = await $`which op`.nothrow().quiet();
+  return result.exitCode === 0;
+}
+
+/**
+ * Check if authenticated with 1Password CLI
+ * Works for both desktop (app/signin) and CI (OP_SERVICE_ACCOUNT_TOKEN)
+ */
+export async function isAuthenticated(): Promise<boolean> {
+  const result = await $`op whoami`.nothrow().quiet();
+  return result.exitCode === 0;
+}
+
+/**
+ * Get helpful error message for authentication failure
+ */
+export function getAuthErrorMessage(): string {
+  if (process.env.OP_SERVICE_ACCOUNT_TOKEN) {
+    return (
+      '1Password authentication failed. ' +
+      'The OP_SERVICE_ACCOUNT_TOKEN may be invalid or expired.'
+    );
+  }
+  return (
+    '1Password authentication failed. ' +
+    'Either run `op signin` or ensure the 1Password app is running with CLI integration enabled.'
+  );
+}
+
+/**
+ * Check if a vault exists
+ */
+export async function vaultExists(vault: string): Promise<boolean> {
+  validateIdentifier(vault, 'vault');
+  const result = await $`op vault get ${vault} --format=json`.nothrow().quiet();
+  return result.exitCode === 0;
+}
+
+/**
+ * Create a vault
+ */
+export async function createVault(vault: string): Promise<void> {
+  validateIdentifier(vault, 'vault');
+  await $`op vault create ${vault}`.quiet();
+}
+
+/**
+ * List all vaults
+ */
+export async function listVaults(): Promise<string[]> {
+  const result = await $`op vault list --format=json`.quiet();
+  const vaults = JSON.parse(result.text()) as Array<{ name: string }>;
+  return vaults.map((v) => v.name);
+}
+
+/**
+ * Item structure
+ */
+export interface OpItem {
+  id: string;
+  title: string;
+  vault: { id: string; name: string };
+  fields: Record<string, string>;
+}
+
+/**
+ * Check if an item exists in a vault
+ */
+export async function itemExists(vault: string, item: string): Promise<boolean> {
+  validateIdentifier(vault, 'vault');
+  validateIdentifier(item, 'item');
+  const result = await $`op item get ${item} --vault=${vault} --format=json`.nothrow().quiet();
+  return result.exitCode === 0;
+}
+
+/**
+ * Get a field value from a 1Password item
+ */
+export async function getField(vault: string, item: string, field: string): Promise<string | null> {
+  validateIdentifier(vault, 'vault');
+  validateIdentifier(item, 'item');
+  validateIdentifier(field, 'field');
+  const result = await $`op read op://${vault}/${item}/${field}`.nothrow().quiet();
+  if (result.exitCode !== 0) {
+    return null;
+  }
+  return result.text().trim();
+}
+
+/**
+ * Get all fields from a 1Password item
+ */
+export async function getItem(vault: string, item: string): Promise<OpItem | null> {
+  validateIdentifier(vault, 'vault');
+  validateIdentifier(item, 'item');
+  const result = await $`op item get ${item} --vault=${vault} --format=json`.nothrow().quiet();
+
+  if (result.exitCode !== 0) {
+    return null;
+  }
+
+  const data = JSON.parse(result.text()) as {
+    id: string;
+    title: string;
+    vault: { id: string; name: string };
+    fields: Array<{ label: string; value?: string }>;
+  };
+
+  const fields: Record<string, string> = {};
+  for (const f of data.fields) {
+    if (f.value) {
+      fields[f.label] = f.value;
+    }
+  }
+
+  return {
+    id: data.id,
+    title: data.title,
+    vault: data.vault,
+    fields,
+  };
+}
+
+/**
+ * Get multiple items from a vault in a single batch
+ * More efficient than calling getItem multiple times
+ */
+export async function getItemsBatch(
+  vault: string,
+  itemNames: string[]
+): Promise<Map<string, OpItem>> {
+  validateIdentifier(vault, 'vault');
+  for (const itemName of itemNames) {
+    validateIdentifier(itemName, 'item');
+  }
+
+  const results = new Map<string, OpItem>();
+
+  // Fetch items in parallel
+  await Promise.all(
+    itemNames.map(async (itemName) => {
+      const item = await getItem(vault, itemName);
+      if (item) {
+        results.set(itemName, item);
+      }
+    })
+  );
+
+  return results;
+}
+
+/**
+ * Set a field on a 1Password item, creating the item if it doesn't exist
+ */
+export async function setField(
+  vault: string,
+  item: string,
+  field: string,
+  value: string
+): Promise<void> {
+  return setFieldsBatch(vault, item, { [field]: value });
+}
+
+/**
+ * Set multiple fields on a 1Password item in a single operation.
+ * Batches all field updates into a single CLI call for efficiency.
+ */
+export async function setFieldsBatch(
+  vault: string,
+  item: string,
+  fields: Record<string, string>
+): Promise<void> {
+  validateIdentifier(vault, 'vault');
+  validateIdentifier(item, 'item');
+  for (const fieldName of Object.keys(fields)) {
+    validateIdentifier(fieldName, 'field');
+  }
+
+  const exists = await itemExists(vault, item);
+
+  // Build field arguments for all fields
+  const fieldArgs = Object.entries(fields).map(
+    ([fieldName, fieldValue]) => `${fieldName}[concealed]=${fieldValue}`
+  );
+
+  if (exists) {
+    // Update existing item - edit all fields in a single command
+    await $`op item edit ${item} --vault=${vault} ${fieldArgs}`.quiet();
+  } else {
+    // Create new item with all fields
+    await $`op item create --category=login --vault=${vault} --title=${item} ${fieldArgs}`.quiet();
+  }
+}
+
+/**
+ * Resolve a secret reference (op://vault/item/field)
+ */
+export async function resolveSecret(reference: string): Promise<string | null> {
+  const result = await $`op read ${reference}`.nothrow().quiet();
+  if (result.exitCode !== 0) {
+    return null;
+  }
+  return result.text().trim();
+}

package/src/resolver.ts

@@ -0,0 +1,143 @@
+import { z } from 'zod';
+import type { TypedEnvResolver, ResolverResult } from '@pokit/core';
+import { type OpVault, type InferOpVaultKeys, parseOpRef } from './vault';
+import * as op from './op';
+
+type KeyMapping = {
+  key: string;
+  item: string;
+  field: string;
+};
+
+export type OpResolverConfig<TVault extends OpVault<any>, TEnvs extends string> = {
+  vault: TVault;
+  vaults: Record<TEnvs, string>;
+};
+
+/**
+ * Define a 1Password resolver that fetches and writes secrets to 1Password vaults.
+ *
+ * @example
+ * ```ts
+ * const vault = defineOpVault({
+ *   POSTGRES_URL: 'supabase:SUPABASE_SESSION_DSN',
+ *   SUPABASE_URL: 'supabase:SUPABASE_URL',
+ * });
+ *
+ * const opResolver = defineOpResolver({
+ *   vault,
+ *   vaults: {
+ *     dev: 'my-app-secrets-dev',
+ *     staging: 'my-app-secrets-staging',
+ *     prod: 'my-app-secrets-prod',
+ *   },
+ * });
+ * ```
+ */
+export function defineOpResolver<TVault extends OpVault<any>, const TEnvs extends string>(
+  config: OpResolverConfig<TVault, TEnvs>
+): TypedEnvResolver<InferOpVaultKeys<TVault> & string> {
+  type VaultKey = InferOpVaultKeys<TVault> & string;
+  const envValues = Object.keys(config.vaults) as TEnvs[];
+  const availableVars = Object.keys(config.vault.secrets) as VaultKey[];
+
+  return {
+    requiredContext: z.object({
+      env: z.enum(envValues as [TEnvs, ...TEnvs[]]),
+    }),
+    availableVars,
+
+    resolve: async (keys, context) => {
+      const ctx = z.object({ env: z.enum(envValues as [TEnvs, ...TEnvs[]]) }).parse(context);
+      const vaultName = config.vaults[ctx.env as TEnvs];
+      if (!vaultName) {
+        throw new Error(`No vault configured for environment: ${ctx.env}`);
+      }
+
+      // Build mapping of keys to their 1Password item/field locations
+      const keyMappings: KeyMapping[] = [];
+      const unknownKeys: string[] = [];
+
+      for (const key of keys) {
+        const ref = config.vault.secrets[key];
+        if (!ref) {
+          unknownKeys.push(key);
+          continue;
+        }
+        const { item, field } = parseOpRef(ref);
+        keyMappings.push({ key, item, field });
+      }
+
+      if (unknownKeys.length > 0) {
+        throw new Error(`No secret config for keys: ${unknownKeys.join(', ')}`);
+      }
+
+      // Group by item name to minimize 1Password calls
+      const itemNames = [...new Set(keyMappings.map((m) => m.item))];
+
+      // Fetch all items in parallel
+      const items = await op.getItemsBatch(vaultName, itemNames);
+
+      // Extract requested fields from fetched items
+      const result: Record<string, string> = {};
+      const missingSecrets: string[] = [];
+
+      for (const { key, item, field } of keyMappings) {
+        const opItem = items.get(item);
+        if (!opItem) {
+          missingSecrets.push(`op://${vaultName}/${item}/${field} (item not found)`);
+          continue;
+        }
+
+        const value = opItem.fields[field];
+        if (value === undefined) {
+          missingSecrets.push(`op://${vaultName}/${item}/${field} (field not found)`);
+          continue;
+        }
+
+        result[key] = value;
+      }
+
+      if (missingSecrets.length > 0) {
+        throw new Error(
+          `Failed to fetch secrets from 1Password:\n  - ${missingSecrets.join('\n  - ')}`
+        );
+      }
+
+      return result as ResolverResult<VaultKey>;
+    },
+
+    write: async (values, context) => {
+      const ctx = z.object({ env: z.enum(envValues as [TEnvs, ...TEnvs[]]) }).parse(context);
+      const vaultName = config.vaults[ctx.env as TEnvs];
+      if (!vaultName) {
+        throw new Error(`No vault configured for environment: ${ctx.env}`);
+      }
+
+      // Group values by 1Password item for batch writes
+      const byItem = new Map<string, Record<string, string>>();
+
+      for (const [key, value] of Object.entries(values) as [string, string | undefined][]) {
+        if (value === undefined) continue;
+
+        const ref = config.vault.secrets[key];
+        if (!ref) {
+          throw new Error(
+            `Unknown variable "${key}". ` + `Ensure it is declared in the vault configuration.`
+          );
+        }
+
+        const { item, field } = parseOpRef(ref);
+        if (!byItem.has(item)) {
+          byItem.set(item, {});
+        }
+        byItem.get(item)![field] = value;
+      }
+
+      // Batch write each item (fail fast on error)
+      for (const [item, fields] of byItem) {
+        await op.setFieldsBatch(vaultName, item, fields);
+      }
+    },
+  };
+}

package/src/vault.ts

@@ -0,0 +1,55 @@
+/**
+ * Vault definition for 1Password secrets.
+ *
+ * Each entry maps a variable name to an "item:field" reference.
+ * Format: `"itemName:fieldName"` where both are required.
+ *
+ * @example
+ * ```ts
+ * const vault = defineOpVault({
+ *   POSTGRES_URL: 'supabase:SUPABASE_SESSION_DSN',
+ *   SUPABASE_URL: 'supabase:SUPABASE_URL',
+ *   STRIPE_SECRET_KEY: 'stripe:STRIPE_SECRET_KEY',
+ * });
+ * ```
+ */
+
+export type OpVaultRef = `${string}:${string}`;
+
+export type OpVault<TSecrets extends Record<string, OpVaultRef>> = {
+  secrets: TSecrets;
+};
+
+export type InferOpVaultKeys<T> = T extends OpVault<infer S> ? keyof S : never;
+
+/**
+ * Parse an "item:field" reference into its components.
+ */
+export function parseOpRef(ref: OpVaultRef): { item: string; field: string } {
+  const colonIndex = ref.indexOf(':');
+  if (colonIndex === -1) {
+    throw new Error(`Invalid vault reference: ${ref}. Expected "item:field".`);
+  }
+  return {
+    item: ref.slice(0, colonIndex),
+    field: ref.slice(colonIndex + 1),
+  };
+}
+
+/**
+ * Define a vault with typed secret declarations.
+ *
+ * @example
+ * ```ts
+ * const vault = defineOpVault({
+ *   POSTGRES_URL: 'supabase:SUPABASE_SESSION_DSN',
+ *   SUPABASE_URL: 'supabase:SUPABASE_URL',
+ *   VITE_SUPABASE_URL: 'supabase:SUPABASE_URL',
+ * });
+ * ```
+ */
+export function defineOpVault<const TSecrets extends Record<string, OpVaultRef>>(
+  secrets: TSecrets
+): OpVault<TSecrets> {
+  return { secrets };
+}