@epic-flow/flowstate-env

Provider-based secrets management for Epic Flow applications with 1Password integration.

Features

• Provider pattern - Pluggable backends (1Password, env, custom)
• In-memory caching - Configurable TTL for performance
• Flexible authentication - Service accounts (CI/CD) or CLI (local dev)
• TypeScript support - Full type definitions
• Testing friendly - Mock provider included

Installation

yarn add @epic-flow/flowstate-env

Quick Start

import { FlowstateEnv } from '@epic-flow/flowstate-env';

// Create client
const secrets = new FlowstateEnv({
  provider: '1password',
  '1password': {
    vaultName: 'flowstate-development',
    serviceAccountToken: process.env.OP_SERVICE_ACCOUNT_TOKEN,
  },
  cache: {
    enabled: true,
    ttl: 3600, // 1 hour
  },
});

// Initialize
await secrets.initialize();

// Get secrets
const apiKey = await secrets.get('OPENAI_API_KEY');

// Refresh secret (bypass cache)
const fresh = await secrets.refresh('OPENAI_API_KEY');

// List secrets
const all = await secrets.list();

// Cleanup
await secrets.close();

Providers

1Password Provider

Uses @1password/sdk to load secrets from 1Password vaults.

Configuration:

{
  provider: '1password',
  '1password': {
    vaultName: 'your-vault-name',
    serviceAccountToken: 'your-token', // Optional, uses op CLI if not provided
    integration: {
      name: 'your-app',
      version: '1.0.0',
    },
  },
}

Secret References:

• Full reference: op://vault-name/item-name/field-name
• Simple name: OPENAI_API_KEY (auto-constructs op://vault-name/OPENAI_API_KEY/password)

Env Provider

Fallback provider that reads from process.env.

{
  provider: 'env',
}

Custom Providers

import { BaseProvider, registerProvider } from '@epic-flow/flowstate-env';

class MyProvider extends BaseProvider {
  async initialize(config) { /* ... */ }
  async getSecret(reference) { /* ... */ }
  async listSecrets() { /* ... */ }
  async refreshSecret(reference) { /* ... */ }
}

registerProvider('my-provider', MyProvider);

const secrets = new FlowstateEnv({ provider: 'my-provider' });

Testing

import { FlowstateEnv } from '@epic-flow/flowstate-env';

// Use env provider in tests
process.env.SECRETS_PROVIDER = 'env';
process.env.TEST_SECRET = 'test-value';

const secrets = new FlowstateEnv({ provider: 'env' });
await secrets.initialize();

const value = await secrets.get('TEST_SECRET');
// value === 'test-value'

Setup

1Password Vault Setup

1. Install 1Password CLI: https://developer.1password.com/docs/cli/get-started/
2. Authenticate: op signin
3. Create vault: op vault create flowstate-development
4. Create service account (for CI/CD): https://my.1password.com/developer-tools/infrastructure-secrets/serviceaccount/

Service Account Setup

1. Go to https://my.1password.com/developer-tools/infrastructure-secrets/serviceaccount/
2. Create new service account named "Epic Flow CI/CD"
3. Grant read access to "flowstate-development" vault
4. Save token securely
5. Add to CI/CD secrets as OP_SERVICE_ACCOUNT_TOKEN

See MIGRATION.md for vault setup and secret migration guide.

API Reference

FlowstateEnv

Main client for secrets management.

Methods

• initialize(): Promise<void> - Initialize the provider
• get(reference: string): Promise<string> - Get a secret (uses cache)
• refresh(reference: string): Promise<string> - Refresh a secret (bypass cache)
• refreshAll(): Promise<void> - Refresh all cached secrets
• list(filter?: string): Promise<string[]> - List available secrets
• clearCache(): void - Clear the cache
• close(): Promise<void> - Close the provider and clean up

Configuration

interface FlowstateEnvConfig {
  provider: '1password' | 'env' | string;
  '1password'?: {
    serviceAccountToken?: string;
    vaultName: string;
    integration?: {
      name: string;
      version: string;
    };
  };
  cache?: {
    enabled: boolean;
    ttl: number; // seconds
  };
}

License

MIT