@vibesdotdev/secrets 0.0.2 → 1.0.0-rc.3

package/src/docs/backends.docs.descriptor.ts

@@ -1,151 +0,0 @@
-import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
-
-const descriptor: DocsTopicDescriptor = {
-  kind: 'docs/topic',
-  id: 'secrets.backends',
-  title: 'Secret Backends',
-  summary: 'Pluggable secret storage backends (vault, wrangler, encrypted-local)',
-  body: {
-    type: 'markdown',
-    sourceType: 'raw',
-    source: `---
-title: Secret Backends
-summary: Pluggable secret storage backends for different environments
-tags: [secrets, backends, vault, wrangler, encryption]
-parent: secrets
-order: 1
-surfaces: [cli, web, in-app]
-hardware: [consumer, cloud]
----
-
-The secrets package uses a **pluggable backend architecture** to support different secret storage mechanisms across environments. Backends register themselves as \`secrets/store\` descriptors with the runtime.
-
-## Available backends
-
-### Vault backend (production cloud)
-
-HashiCorp Vault backend for production cloud deployments:
-
-\`\`\`ts
-import { vaultBackend } from '@vibesdotdev/secrets-backend-vault';
-
-await runtime.registerPlugin(vaultBackend.plugin({
-  address: process.env.VAULT_ADDR,
-  token: process.env.VAULT_TOKEN
-}));
-\`\`\`
-
-**Use when:** Running in production cloud environments with Vault infrastructure.
-
-### Wrangler secrets (Cloudflare Workers)
-
-Cloudflare Workers secrets via Wrangler:
-
-\`\`\`ts
-import { wranglerBackend } from '@vibesdotdev/secrets-backend-wrangler';
-
-await runtime.registerPlugin(wranglerBackend.plugin());
-\`\`\`
-
-**Use when:** Deploying to Cloudflare Workers edge runtime.
-
-### Encrypted local backend (development)
-
-Local development with encryption at rest:
-
-\`\`\`ts
-import { encryptedLocalBackend } from '@vibesdotdev/secrets-backend-encrypted-local';
-
-await runtime.registerPlugin(encryptedLocalBackend.plugin({
-  keyPath: '.vibes/secrets.key',
-  dataPath: '.vibes/secrets.enc.json'
-}));
-\`\`\`
-
-**Use when:** Local development, testing, or single-user consumer apps.
-
-## Backend resolution
-
-The runtime selects backends based on **environment tier** and **priority**:
-
-\`\`\`ts
-const store = await runtime.query('secrets/store')
-  .forHardware('consumer')
-  .resolve();
-
-// Resolution logic:
-// 1. Filter by environment tier (from scope qualifiers)
-// 2. Sort by priority (higher = preferred)
-// 3. Return first match
-\`\`\`
-
-Environment tiers:
-- \`local\` — Development environments
-- \`staging\` — Staging/pre-production
-- \`production\` — Production cloud
-
-## WRONG: Hardcoding backend selection
-
-\`\`\`ts
-// ❌ NEVER — bypasses tier-based resolution
-const store = await runtime.query('secrets/store')
-  .withId('encrypted-local')
-  .resolve();
-\`\`\`
-
-## RIGHT: Hardware-scoped resolution
-
-\`\`\`ts
-// ✅ Let runtime select based on tier + priority
-const store = await runtime.query('secrets/store')
-  .forHardware('consumer')
-  .resolve();
-\`\`\`
-
-## Backend registration
-
-Backends register as \`secrets/store\` descriptors:
-
-\`\`\`ts
-export const vaultBackend = createRuntimePlugin({
-  id: 'secrets-backend-vault',
-  descriptors: [{
-    kind: 'secrets/store',
-    id: 'vault',
-    title: 'HashiCorp Vault',
-    tiers: ['production'],
-    priority: 100,  // highest priority for production
-    implementation: VaultStoreImplementation
-  }]
-});
-\`\`\`
-
-## Missing backend behavior
-
-**Hard rule:** Missing backends cause hard failure. The \`resolve()\` method throws if no backend has registered for the current scope.
-
-\`\`\`ts
-try {
-  const store = await runtime.query('secrets/store').resolve();
-} catch (error) {
-  // No backend registered for current tier/hardware
-  console.error('No secrets backend available');
-}
-\`\`\`
-
-:::card{title="See also"}
-- [\`secrets.encryption\`](secrets.encryption) — Encryption at rest, key management
-- [\`secrets.env-file\`](secrets.env-file) — .env file handling
-- [\`config/environment\`](config.environment) — Environment tier configuration
-:::
-`
-  },
-  parent: 'secrets',
-  order: 1,
-  tags: ['secrets', 'backends', 'vault', 'wrangler', 'encryption'],
-  surfaces: ['cli', 'web', 'in-app'],
-  hardware: ['consumer', 'cloud'],
-  enabled: true
-};
-
-export default descriptor;

package/src/docs/encryption.docs.descriptor.ts

@@ -1,165 +0,0 @@
-import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
-
-const descriptor: DocsTopicDescriptor = {
-  kind: 'docs/topic',
-  id: 'secrets.encryption',
-  title: 'Encryption at Rest',
-  summary: 'Secret encryption, key management, and rotation strategies',
-  body: {
-    type: 'markdown',
-    sourceType: 'raw',
-    source: `---
-title: Encryption at Rest
-summary: Secret encryption, key management, and rotation strategies
-tags: [secrets, encryption, key-management, rotation, security]
-parent: secrets
-order: 2
-surfaces: [cli, web, in-app]
-hardware: [consumer, cloud]
----
-
-Secrets are **encrypted at rest** using industry-standard algorithms. Encryption is handled automatically by backends — applications never see plaintext encryption keys.
-
-## Encryption algorithms
-
-### AES-256-GCM (symmetric)
-
-Default algorithm for secret encryption:
-
-- **Key size:** 256 bits
-- **Mode:** GCM (Galois/Counter Mode)
-- **IV:** 96-bit random nonce per encryption
-- **Tag:** 128-bit authentication tag
-
-\`\`\`ts
-import { encrypt, decrypt } from '@vibesdotdev/secrets/encryption';
-
-const key = await deriveKeyFromMasterKey(masterKey, salt);
-const ciphertext = await encrypt(plaintext, key);
-// ciphertext = { iv, tag, data }
-\`\`\`
-
-### Key derivation (PBKDF2)
-
-Master keys are derived from user-provided passphrases:
-
-- **Algorithm:** PBKDF2-HMAC-SHA256
-- **Iterations:** 100,000 (adjusts with hardware)
-- **Salt:** 32-byte random per key
-
-\`\`\`ts
-import { deriveKeyFromPassphrase } from '@vibesdotdev/secrets/encryption';
-
-const masterKey = await deriveKeyFromPassphrase(passphrase, salt, {
-  iterations: 100_000,
-  keyLength: 32
-});
-\`\`\`
-
-## Key management
-
-### Master key storage
-
-Master keys are stored **separately** from encrypted data:
-
-1. **Hardware security module (HSM)** — Production cloud
-2. **OS keychain** — Local development (macOS Keychain, Windows Credential Manager)
-3. **Environment variable** — CI/CD (never committed)
-
-### Key rotation
-
-Keys can be rotated without decrypting data:
-
-\`\`\`ts
-import { rotateKey, reEncryptSecrets } from '@vibesdotdev/secrets/encryption';
-
-// Generate new key
-const newKey = await generateRandomKey(32);
-
-// Re-encrypt all secrets with new key
-await reEncryptSecrets(oldKey, newKey);
-
-// Update key storage
-await storeMasterKey(newKey);
-\`\`\`
-
-**Rotation triggers:**
-- Scheduled rotation (every 90 days)
-- Suspected compromise
-- Employee offboarding
-- Compliance requirements
-
-## Encryption envelope
-
-Encrypted secrets use a standard envelope format:
-
-\`\`\`json
-{
-  "version": 1,
-  "algorithm": "aes-256-gcm",
-  "kdf": "pbkdf2-hmac-sha256",
-  "salt": "base64-encoded-salt",
-  "iv": "base64-encoded-iv",
-  "tag": "base64-encoded-tag",
-  "ciphertext": "base64-encoded-ciphertext"
-}
-\`\`\`
-
-## WRONG: Manual encryption
-
-\`\`\`ts
-// ❌ NEVER — use backend APIs instead
-import { encrypt } from '@vibesdotdev/secrets/encryption';
-
-const encrypted = await encrypt(secret, key);
-await fs.writeFile('.secrets.enc.json', JSON.stringify(encrypted));
-\`\`\`
-
-## RIGHT: Backend-managed encryption
-
-\`\`\`ts
-// ✅ Backend handles encryption automatically
-const store = await runtime.query('secrets/store').resolve();
-await store.set('API_KEY', '<api-key>');
-// Encryption happens transparently
-\`\`\`
-
-## Compliance considerations
-
-### SOC 2 Type II
-
-- ✅ Encryption at rest (AES-256)
-- ✅ Key rotation policies
-- ✅ Access logging and auditing
-- ✅ Separation of duties (key custodians)
-
-### GDPR
-
-- ✅ Data minimization (encrypt only what's needed)
-- ✅ Right to erasure (delete keys = delete data)
-- ✅ Data processing records (audit logs)
-
-## Key backup
-
-**Critical:** Losing the master key means **permanent data loss**. Backups are essential:
-
-1. **Shamir's Secret Sharing** — Split key into N shares, require M to reconstruct
-2. **Geographic distribution** — Store shares in different regions
-3. **Hardware tokens** — YubiKey, smartcards for key storage
-
-:::card{title="See also"}
-- [\`secrets.backends\`](secrets.backends) — Secret backend implementations
-- [\`secrets.env-file\`](secrets.env-file) — Encrypted .env files
-- [\`config/secrets\`](config.secrets) — Secret requirements and validation
-:::
-`
-  },
-  parent: 'secrets',
-  order: 2,
-  tags: ['secrets', 'encryption', 'key-management', 'rotation', 'security'],
-  surfaces: ['cli', 'web', 'in-app'],
-  hardware: ['consumer', 'cloud'],
-  enabled: true
-};
-
-export default descriptor;

package/src/docs/env-file.docs.descriptor.ts

@@ -1,209 +0,0 @@
-import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
-
-const descriptor: DocsTopicDescriptor = {
-  kind: 'docs/topic',
-  id: 'secrets.env-file',
-  title: 'Encrypted Environment Files',
-  summary: '.env file encryption, decryption, and secure handling',
-  body: {
-    type: 'markdown',
-    sourceType: 'raw',
-    source: `---
-title: Encrypted Environment Files
-summary: Secure .env file handling with encryption at rest
-tags: [secrets, env, dotenv, encryption, configuration]
-parent: secrets
-order: 3
-surfaces: [cli, web, in-app]
-hardware: [consumer, cloud]
-man:
-  name: "secrets.env-file — Encrypted environment files"
-  section: 1
-  synopsis: "vibes man secrets.env-file"
-  seeAlso: ["secrets.set", "secrets.reveal", "config.environment"]
----
-
-Environment files (\`.env\`) can be **encrypted at rest** to protect secrets in version control and local storage.
-
-## File formats
-
-### Plaintext .env (development only)
-
-\`\`\`bash
-# .env (development only — never commit)
-DATABASE_URL=postgres://localhost/mydb
-API_KEY=sk-test-123456789
-\`\`\`
-
-**Security:** ❌ No encryption — suitable for local development only.
-
-### Encrypted .env.enc
-
-\`\`\`bash
-# .env.enc (safe to commit)
-{
-  "version": 1,
-  "algorithm": "aes-256-gcm",
-  "salt": "...",
-  "iv": "...",
-  "tag": "...",
-  "ciphertext": "..."
-}
-\`\`\`
-
-**Security:** ✅ Encrypted — safe to commit to version control.
-
-## CLI commands
-
-### Encrypt a .env file
-
-\`\`\`bash
-vibes secrets encrypt .env --output .env.enc
-\`\`\`
-
-Prompts for encryption passphrase (or uses \`VIBES_SECRET_PASSPHRASE\` env var).
-
-### Decrypt a .env.enc file
-
-\`\`\`bash
-vibes secrets decrypt .env.enc --output .env
-\`\`\`
-
-Creates decrypted file in memory only — never writes plaintext to disk.
-
-### Reveal secrets (one-time)
-
-\`\`\`bash
-vibes secrets reveal --format export
-# Output:
-# export DATABASE_URL="postgres://..."
-# export API_KEY="<api-key>"
-\`\`\`
-
-## Programmatic usage
-
-### Load encrypted .env
-
-\`\`\`ts
-import { loadEncryptedEnv } from '@vibesdotdev/secrets/env-file';
-
-const secrets = await loadEncryptedEnv('.env.enc', {
-  passphrase: process.env.VIBES_SECRET_PASSPHRASE
-});
-
-// Secrets available in memory only
-console.log(secrets.DATABASE_URL);
-\`\`\`
-
-### Write encrypted .env
-
-\`\`\`ts
-import { writeEncryptedEnv } from '@vibesdotdev/secrets/env-file';
-
-await writeEncryptedEnv('.env.enc', {
-  DATABASE_URL: 'postgres://...',
-  API_KEY: '<api-key>'
-}, {
-  passphrase: 'your-passphrase'
-});
-\`\`\`
-
-## Integration with backends
-
-Encrypted .env files can **sync** with secret backends:
-
-### Push to backend
-
-\`\`\`bash
-vibes secrets push --from .env.enc
-\`\`\`
-
-Decrypts and uploads secrets to the configured backend (Vault, Wrangler, etc.).
-
-### Pull from backend
-
-\`\`\`bash
-vibes secrets pull --to .env.enc
-\`\`\`
-
-Downloads secrets from backend and writes encrypted file.
-
-## WRONG: Committing plaintext .env
-
-\`\`\`bash
-# ❌ NEVER — add to .gitignore immediately
-echo ".env" >> .gitignore
-git add .env  # DON'T DO THIS
-\`\`\`
-
-## RIGHT: Commit encrypted version
-
-\`\`\`bash
-# ✅ Safe to commit
-vibes secrets encrypt .env --output .env.enc
-git add .env.enc
-git commit -m "Add encrypted environment"
-\`\`\`
-
-## Pre-commit hook
-
-The pre-commit hook **blocks** plaintext secrets:
-
-\`\`\`bash
-# .git/hooks/pre-commit
-vibes secrets pre-commit-check
-\`\`\`
-
-Scans staged files for:
-- AWS access keys (\`AKIA...\`)
-- PEM private-key headers
-- API tokens (Stripe, GitHub, etc.)
-- High-entropy strings (potential secrets)
-
-## Environment variable injection
-
-Decrypted secrets are injected as environment variables:
-
-\`\`\`ts
-// apps/my-app/src/server/hooks/env.ts
-import { loadEncryptedEnv } from '@vibesdotdev/secrets/env-file';
-
-export async function handle(): Promise<void> {
-  const secrets = await loadEncryptedEnv('.env.enc');
-  Object.entries(secrets).forEach(([key, value]) => {
-    process.env[key] = value;
-  });
-}
-\`\`\`
-
-## File permissions
-
-Encrypted files should have restrictive permissions:
-
-\`\`\`bash
-chmod 600 .env.enc      # Owner read/write only
-chmod 600 .vibes/       # Secrets directory
-\`\`\`
-
-:::card{title="See also"}
-- [\`secrets.backends\`](secrets.backends) — Secret storage backends
-- [\`secrets.encryption\`](secrets.encryption) — Encryption algorithms
-- [\`secrets.check\`](secrets.check) — Secret scanning and validation
-:::
-`
-  },
-  parent: 'secrets',
-  order: 3,
-  tags: ['secrets', 'env', 'dotenv', 'encryption', 'configuration'],
-  surfaces: ['cli', 'web', 'in-app'],
-  hardware: ['consumer', 'cloud'],
-  man: {
-    name: 'secrets.env-file — Encrypted environment files',
-    section: 1,
-    synopsis: 'vibes man secrets.env-file',
-    seeAlso: ['secrets.set', 'secrets.reveal', 'config.environment']
-  },
-  enabled: true
-};
-
-export default descriptor;

package/src/index.ts

@@ -1,35 +0,0 @@
-/**
- * @vibesdotdev/secrets
- *
- * Environment-aware secrets management with pluggable backends.
- * Provides the secrets/store runtime kind. Backends live in sibling packages.
- *
- * Hard rule: missing-backend means hard failure. resolve() throws if no
- * backend has registered for the current scope.
- */
-
-export {
-	SecretsStoreDescriptorSchema,
-	EnvironmentTierSchema,
-	SecretsBackendSchema,
-	type SecretsStoreDescriptor,
-	type EnvironmentTier,
-	type SecretsBackend,
-	type SecretEntry,
-	type SecretsStoreImplementation,
-	secretsStoreKind
-} from './kinds/index';
-
-export {
-	SecretsImportManifestSchema,
-	SecretManifestEntrySchema,
-	SecretSourceSchema,
-	SecretCategorySchema,
-	canonicalImportManifest,
-	type SecretsImportManifest,
-	type SecretManifestEntry,
-	type SecretSource,
-	type SecretCategory
-} from './manifest/index';
-
-export { default as secretsPlugin } from './secrets.plugin';

package/src/kinds/index.ts

@@ -1,12 +0,0 @@
-export {
-	SecretsStoreDescriptorSchema,
-	EnvironmentTierSchema,
-	SecretsBackendSchema,
-	type SecretsStoreDescriptor,
-	type EnvironmentTier,
-	type SecretsBackend
-} from './store.schema';
-
-export type { SecretEntry, SecretsStoreImplementation } from './store.interface';
-
-export { secretsStoreKind } from './store.kind';

package/src/kinds/schemas/store.schema.ts

@@ -1,47 +0,0 @@
-/**
- * Secrets Store Descriptor Schema
- *
- * Defines the structure for secrets/store kind descriptors.
- * Each descriptor represents a secrets storage backend
- * (env-file, encrypted-local, cloudflare-api, vault).
- */
-
-import * as z from 'zod/v4';
-
-export const EnvironmentTierSchema = z.enum(['local', 'dev', 'staging', 'production']);
-
-export type EnvironmentTier = z.infer<typeof EnvironmentTierSchema>;
-
-export const SecretsBackendSchema = z.enum([
-	'env-file',
-	'encrypted-local',
-	'cloudflare-api',
-	'cloudflare-secrets-store',
-	'vault'
-]);
-
-export type SecretsBackend = z.infer<typeof SecretsBackendSchema>;
-
-export const SecretsStoreDescriptorSchema = z.object({
-	id: z.string().min(1),
-	kind: z.literal('secrets/store'),
-	name: z.string().optional(),
-	description: z.string().optional(),
-	tags: z.array(z.string()).optional(),
-	enabled: z.boolean().optional(),
-	hardware: z.array(z.string()).optional(),
-
-	/** Backend type for this store */
-	backend: SecretsBackendSchema,
-
-	/** Environment tiers this store operates on */
-	tiers: z.array(EnvironmentTierSchema).min(1),
-
-	/** Resolution priority (higher wins for write ops) */
-	priority: z.number().int().default(0),
-
-	/** Backend-specific configuration key-value pairs */
-	config: z.record(z.string(), z.string()).optional()
-});
-
-export type SecretsStoreDescriptor = z.infer<typeof SecretsStoreDescriptorSchema>;

package/src/kinds/schemas/store.types.ts

@@ -1,35 +0,0 @@
-import type { SecretsStoreDescriptor } from './store.schema';
-
-/** A single entry in a secrets listing */
-export interface SecretEntry {
-	/** Secret key name (e.g., VIBES_AUTH_SECRET) */
-	key: string;
-	/** Whether a value is stored for this key */
-	hasValue: boolean;
-	/** Backend source identifier */
-	source: string;
-}
-
-/** Interface all secrets store backends must implement */
-export interface SecretsStoreImplementation {
-	readonly id: string;
-	readonly descriptor: SecretsStoreDescriptor;
-
-	/** List all secret keys stored for an environment */
-	list(environment: string): Promise<SecretEntry[]>;
-
-	/** Get a single secret value (undefined if not found) */
-	get(environment: string, key: string): Promise<string | undefined>;
-
-	/** Set a secret value for an environment */
-	set(environment: string, key: string, value: string): Promise<void>;
-
-	/** Remove a secret from an environment */
-	unset(environment: string, key: string): Promise<void>;
-
-	/** Get all secret key-value pairs for an environment */
-	getAll(environment: string): Promise<Record<string, string>>;
-
-	/** Set multiple secrets at once (merges with existing) */
-	setAll(environment: string, secrets: Record<string, string>): Promise<void>;
-}

package/src/kinds/store.interface.ts

@@ -1 +0,0 @@
-export type { SecretEntry, SecretsStoreImplementation } from './schemas/store.types';