@vibesdotdev/secrets 0.0.1

package/src/cli/shared/resolve-environment.ts

@@ -0,0 +1,57 @@
+import type { UIContext } from '@vibesdotdev/cli/providers';
+import { resolveCurrentEnvironmentConfig } from '@vibesdotdev/config/environment/current';
+import type { EnvironmentTier } from '../../kinds/store.schema';
+
+export interface ResolvedSecretsEnvironment {
+	name: string;
+	tier: EnvironmentTier;
+}
+
+const ENVIRONMENT_TIERS = new Set<EnvironmentTier>([
+	'local',
+	'dev',
+	'staging',
+	'production'
+]);
+
+/**
+ * Resolve the active environment for secrets commands.
+ *
+ * Falls back to local when the environment config manifest/plugin graph is
+ * unavailable so end-users can still run local secrets workflows.
+ */
+export async function resolveSecretsEnvironment(
+	ui: UIContext,
+	environmentOverride?: string
+): Promise<ResolvedSecretsEnvironment> {
+	if (environmentOverride && environmentOverride.length > 0) {
+		if (ENVIRONMENT_TIERS.has(environmentOverride as EnvironmentTier)) {
+			return {
+				name: environmentOverride,
+				tier: environmentOverride as EnvironmentTier
+			};
+		}
+		try {
+			const envConfig = await resolveCurrentEnvironmentConfig();
+			return {
+				name: environmentOverride,
+				tier: (envConfig.tier ?? 'local') as EnvironmentTier
+			};
+		} catch {
+			return { name: environmentOverride, tier: 'local' };
+		}
+	}
+
+	try {
+		const envConfig = await resolveCurrentEnvironmentConfig();
+		return {
+			name: envConfig.name,
+			tier: (envConfig.tier ?? 'local') as EnvironmentTier
+		};
+	} catch {
+		ui.warn(
+			"Environment config manifest is unavailable; defaulting to 'local'. Register @vibesdotdev/config/environment/plugin to enable named environment selection."
+		);
+		return { name: 'local', tier: 'local' };
+	}
+}

package/src/cli/unset/secrets.unset.cli-command.descriptor.ts

@@ -0,0 +1,22 @@
+import type { CLICommandAssetDescriptor } from '@vibesdotdev/cli/schemas/types';
+
+const descriptor: CLICommandAssetDescriptor = {
+	kind: 'cli/command',
+	id: 'secrets.unset',
+	name: 'unset',
+	description: 'Remove a secret from the current environment',
+	group: 'secrets',
+	arguments: [
+		{ name: 'key', description: 'Secret key name to remove', required: true }
+	],
+	options: [
+		{ flags: '--environment <name>', description: 'Target environment (default: current)' },
+		{ flags: '--backend <id>', description: 'Target backend (default: primary for tier)' }
+	],
+	surfaces: ['cli'],
+	hardware: ['consumer'],
+	enabled: true,
+	order: 30
+};
+
+export default descriptor;

package/src/cli/unset/secrets.unset.cli-command.impl.ts

@@ -0,0 +1,41 @@
+import { getVibesRuntime } from '@vibesdotdev/runtime';
+import type { UIContext } from '@vibesdotdev/cli/providers';
+import type { SecretsStoreImplementation } from '../../kinds/store.interface';
+import type { SecretsStoreDescriptor } from '../../kinds/store.schema';
+import { resolveSecretsEnvironment } from '../shared/resolve-environment';
+
+export default {
+	async execute(args: Record<string, unknown>, opts: Record<string, unknown>): Promise<void> {
+		const runtime = getVibesRuntime();
+		const ui = (await runtime.context('cli/ui')) as UIContext;
+		const key = args.key as string;
+		const options = opts as { environment?: string; backend?: string };
+
+		const { name: envName, tier: envTier } = await resolveSecretsEnvironment(
+			ui,
+			options.environment
+		);
+
+		const descriptors = runtime.assets('secrets/store').descriptors() as SecretsStoreDescriptor[];
+		const tierStores = descriptors
+			.filter((d) => {
+				if (options.backend) return d.id === options.backend;
+				return d.tiers.includes(envTier);
+			})
+			.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+
+		const target = tierStores[0];
+		if (!target) {
+			ui.error(`No secrets store available for tier: ${envTier}`);
+			process.exit(1);
+		}
+
+		const impl = (await runtime
+			.query('secrets/store')
+			.withId(target.id)
+			.resolve()) as SecretsStoreImplementation;
+		await impl.unset(envName, key);
+
+		ui.success(`Removed ${key} from [${target.id}] for environment: ${envName}`);
+	}
+};

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

@@ -0,0 +1,151 @@
+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

@@ -0,0 +1,165 @@
+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

@@ -0,0 +1,209 @@
+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

@@ -0,0 +1,35 @@
+/**
+ * @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

@@ -0,0 +1,12 @@
+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';