@vibesdotdev/secrets 0.0.1 → 1.0.0-rc.3

package/dist/docs/encryption.docs.descriptor.js

@@ -14,141 +14,135 @@ parent: secrets
 order: 2
 surfaces: [cli, web, in-app]
 hardware: [consumer, cloud]
+id: secrets.encryption
 ---
 
-Secrets are **encrypted at rest** using industry-standard algorithms. Encryption is handled automatically by backends — applications never see plaintext encryption keys.
+Secrets are **encrypted at rest** with AES-256-GCM. Encryption is handled by the
+backend — applications interact with the \`secrets/store\` runtime kind and never
+touch ciphertext, keys, or crypto primitives directly.
 
-## Encryption algorithms
+The \`@vibesdotdev/secrets\` package itself exposes **no encryption API**. The
+cryptography lives in the shared \`@vibesdotdev/security/encryption\` module, and
+each secrets backend decides whether and how to use it.
 
-### AES-256-GCM (symmetric)
+## How a backend encrypts
 
-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
+The \`encrypted-local\` backend (\`@vibesdotdev/secrets/backends/encrypted-local\`)
+stores all secrets in a single AES-256-GCM encrypted JSON vault at
+\`<vibesHome>/config/secrets.enc.json\`. On every read/write it round-trips the
+vault with the key co-located with that home, resolved from the runtime it was
+created with:
 
 \`\`\`ts
-import { encrypt, decrypt } from '@vibesdotdev/secrets/encryption';
-
-const key = await deriveKeyFromMasterKey(masterKey, salt);
-const ciphertext = await encrypt(plaintext, key);
-// ciphertext = { iv, tag, data }
+import {
+	decryptToStringWithKey,
+	encryptStringWithKey,
+	resolveEncryptionKeyHexForBase
+} from '@vibesdotdev/security/encryption';
+
+const keyHex = resolveEncryptionKeyHexForBase(runtime, roots.vibesHome);
+// Encrypt a JSON vault to raw bytes (IV + ciphertext + auth tag), then base64.
+const fileContents = Buffer.from(encryptStringWithKey(JSON.stringify(vault), keyHex)).toString('base64');
+// Decrypt on load.
+const vault = JSON.parse(decryptToStringWithKey(new Uint8Array(Buffer.from(fileContents, 'base64')), keyHex));
 \`\`\`
 
-### Key derivation (PBKDF2)
+Encryption failures are **hard failures** — there is no plaintext fallback. If
+the vault cannot be decrypted (wrong key, corruption), \`resolve()\`-backed reads
+throw rather than returning partial data.
+
+## The encryption algorithm
 
-Master keys are derived from user-provided passphrases:
+\`@vibesdotdev/security/encryption\` is the single source of truth for secret
+encryption across the repository-collection:
 
-- **Algorithm:** PBKDF2-HMAC-SHA256
-- **Iterations:** 100,000 (adjusts with hardware)
-- **Salt:** 32-byte random per key
+- **Algorithm:** AES-256-GCM (authenticated encryption)
+- **Key:** 32 bytes, hex-encoded: the \`SECRET_ENCRYPTION_KEY\` credential bound in the secrets/store (\`runtime.resolveCredential\`), or the key a consumer host persists.
+- **IV:** 16-byte random value per encryption
+- **Tag:** 16-byte GCM authentication tag
+
+Every operation runs with the key of the runtime it is handed
+(\`new SecretEncryption(runtime)\`); the key is resolved once per runtime and
+never shared process-wide. Every method is asynchronous. It offers two output shapes. The raw-binary methods
+concatenate \`IV + ciphertext + tag\`:
 
 \`\`\`ts
-import { deriveKeyFromPassphrase } from '@vibesdotdev/secrets/encryption';
+import { SecretEncryption } from '@vibesdotdev/security/encryption';
 
-const masterKey = await deriveKeyFromPassphrase(passphrase, salt, {
-  iterations: 100_000,
-  keyLength: 32
-});
+const encryption = new SecretEncryption(context.runtime);
+const blob = await encryption.encryptString('plaintext'); // Uint8Array
+const text = await encryption.decryptToString(blob);
 \`\`\`
 
-## Key management
+The storage-format methods produce a colon-delimited base64 string
+(\`base64(iv):base64(tag):base64(ciphertext)\`) with AAD \`'secret'\`, intended for
+database columns:
 
-### Master key storage
+\`\`\`ts
+const stored = await encryption.encryptForStorage('plaintext'); // "iv:tag:ciphertext"
+const value = await encryption.decryptFromStorage(stored);
+\`\`\`
 
-Master keys are stored **separately** from encrypted data:
+## Key management
 
-1. **Hardware security module (HSM)** — Production cloud
-2. **OS keychain** — Local development (macOS Keychain, Windows Credential Manager)
-3. **Environment variable** — CI/CD (never committed)
+Each runtime has one symmetric key, resolved by
+\`resolveEncryptionKeyHex(runtime)\` inside \`@vibesdotdev/security\`:
 
-### Key rotation
+1. **\`SECRET_ENCRYPTION_KEY\`** (hex, 64 chars), the credential bound in the
+   secrets/store (\`boundEncryptionKeyHex\`: \`{ source: 'secret', key: 'SECRET_ENCRYPTION_KEY' }\`),
+   never the host environment. A cloud host must bind it; without it the call
+   fails \`UNAVAILABLE\` \`encryption-key-unconfigured\`. (An encrypted store's own
+   key, \`resolveEncryptionKeyHexForBase\`, is its root of trust and the one
+   host-bound read: it cannot resolve through the store it unlocks.)
+2. **Persisted key** — a consumer host creates \`<configDir>/encryption.key\`
+   (mode \`0600\`) exactly once: an exclusive create, so two hosts booting at
+   once keep the one key that wins. Any read or write failure other than a
+   missing file fails typed; nothing falls back to a process-ephemeral key.
 
-Keys can be rotated without decrypting data:
+Generate a fresh key with:
 
 \`\`\`ts
-import { rotateKey, reEncryptSecrets } from '@vibesdotdev/secrets/encryption';
-
-// Generate new key
-const newKey = await generateRandomKey(32);
+import { generateEncryptionKey } from '@vibesdotdev/security/encryption';
 
-// Re-encrypt all secrets with new key
-await reEncryptSecrets(oldKey, newKey);
-
-// Update key storage
-await storeMasterKey(newKey);
+const hex = generateEncryptionKey(); // 64-char hex, set as SECRET_ENCRYPTION_KEY
 \`\`\`
 
-**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"
-}
-\`\`\`
+> There is **no key-rotation or re-encryption API** in these packages. Rotating
+> the key today means decrypting with the old key and re-writing with the new
+> one at the application level.
 
-## WRONG: Manual encryption
+## WRONG: encrypting secrets by hand
 
 \`\`\`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));
-\`\`\`
+// ❌ Don't hand-roll vault files or call the crypto helpers directly to
+//    persist application secrets — go through the secrets/store backend.
+import { SecretEncryption } from '@vibesdotdev/security/encryption';
 
-## 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
+const blob = await new SecretEncryption(runtime).encryptString(JSON.stringify({ API_KEY: '<api-key>' }));
+await fs.writeFile('.secrets.enc.json', Buffer.from(blob).toString('base64'));
 \`\`\`
 
-## Compliance considerations
-
-### SOC 2 Type II
+## RIGHT: backend-managed encryption
 
-- ✅ Encryption at rest (AES-256)
-- ✅ Key rotation policies
-- ✅ Access logging and auditing
-- ✅ Separation of duties (key custodians)
+Resolve the active store from the runtime and let the backend handle encryption.
+Store methods are environment-scoped:
 
-### GDPR
-
-- ✅ Data minimization (encrypt only what's needed)
-- ✅ Right to erasure (delete keys = delete data)
-- ✅ Data processing records (audit logs)
-
-## Key backup
+\`\`\`ts
+import { resolveSecretsStore } from '@vibesdotdev/secrets';
 
-**Critical:** Losing the master key means **permanent data loss**. Backups are essential:
+const store = await resolveSecretsStore(runtime, 'local');
+if (store) {
+  await store.set('local', 'API_KEY', '<api-key>');
+  const value = await store.get('local', 'API_KEY');
+}
+\`\`\`
 
-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
+\`resolveSecretsStore\` returns the highest-priority backend registered for the
+given tier, or \`null\` when no \`secrets/store\` kind/backend is present.
 
 :::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
+- [\`secrets.env-file\`](secrets.env-file) — .env file backend
 :::
 `
     },

package/dist/docs/encryption.docs.descriptor.js.map

@@ -1 +1 @@
-{"version":3,"file":"encryption.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/encryption.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACtC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,oBAAoB;IACxB,KAAK,EAAE,oBAAoB;IAC3B,OAAO,EAAE,4DAA4D;IACrE,IAAI,EAAE;QACJ,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgJX;KACE;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,UAAU,CAAC;IACzE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACd,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"encryption.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/encryption.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,oBAAoB;IACxB,KAAK,EAAE,oBAAoB;IAC3B,OAAO,EAAE,4DAA4D;IACrE,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0IT;KACC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,UAAU,CAAC;IACzE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/env-file.docs.descriptor.d.ts

@@ -1,4 +1,4 @@
-import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
 declare const descriptor: DocsTopicDescriptor;
 export default descriptor;
 //# sourceMappingURL=env-file.docs.descriptor.d.ts.map

package/dist/docs/env-file.docs.descriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env-file.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/env-file.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,QAAA,MAAM,UAAU,EAAE,mBA4MjB,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"env-file.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/env-file.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBA8JjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/env-file.docs.descriptor.js

@@ -1,205 +1,159 @@
 const descriptor = {
     kind: 'docs/topic',
     id: 'secrets.env-file',
-    title: 'Encrypted Environment Files',
-    summary: '.env file encryption, decryption, and secure handling',
+    title: 'Env-File Secrets Backend',
+    summary: 'The env-file backend stores secrets in plaintext .env.{environment} files for local and dev tiers',
     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]
+title: Env-File Secrets Backend
+summary: The env-file backend stores secrets in plaintext .env.{environment} files for local and dev tiers
+tags: [secrets, env, dotenv, backend, configuration]
 parent: secrets
 order: 3
 surfaces: [cli, web, in-app]
-hardware: [consumer, cloud]
+hardware: [consumer]
 man:
-  name: "secrets.env-file — Encrypted environment files"
+  name: "secrets.env-file — Env-file secrets backend"
   section: 1
   synopsis: "vibes man secrets.env-file"
-  seeAlso: ["secrets.set", "secrets.reveal", "config.environment"]
+  seeAlso: ["secrets.backends", "secrets.encryption", "config.environment"]
 ---
 
-Environment files (\`.env\`) can be **encrypted at rest** to protect secrets in version control and local storage.
+The **env-file** backend (\`@vibesdotdev/secrets/backends/env-file\`) is the default \`secrets/store\` backend for the \`local\` and \`dev\` tiers. It reads and writes plaintext \`.env.{environment}\` files (e.g. \`.env.local\`, \`.env.dev\`) in \`KEY=VALUE\` format.
 
-## File formats
+> This backend stores values in **plaintext**. It is for local development only — do not commit its files. For encryption-at-rest, use the \`encrypted-local\` backend instead (see [\`secrets.encryption\`](secrets.encryption)).
 
-### Plaintext .env (development only)
+## File format
+
+Files are named \`.env.{environment}\` and live under the configured \`basePath\`, resolved against the bound workspace root (\`runtime/workspace-path\`; default \`.\`, the workspace root itself):
 
 \`\`\`bash
-# .env (development only — never commit)
+# .env.local
 DATABASE_URL=postgres://localhost/mydb
-API_KEY=sk-test-123456789
+# A value containing spaces or # is automatically quoted on write
+GREETING="hello world"
 \`\`\`
 
-**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": "..."
-}
-\`\`\`
+On write, the backend:
+- Preserves comments, blank lines, and key ordering.
+- Auto-quotes values containing spaces, \`#\`, or \`"\`.
+- Writes atomically (temp file + rename) with file mode \`0600\`.
 
-**Security:** ✅ Encrypted — safe to commit to version control.
+## Backend descriptor
 
-## CLI commands
+The backend registers a \`secrets/store\` descriptor. Its \`config.basePath\` controls where \`.env.{environment}\` files are read/written:
 
-### Encrypt a .env file
+:::descriptor{kind="secrets/store" id="env-file"}
+- **backend** — \`env-file\`
+- **tiers** — \`['local', 'dev']\`
+- **priority** — \`0\`
+- **config.basePath** — directory holding the files (default \`.\`)
+:::
 
-\`\`\`bash
-vibes secrets encrypt .env --output .env.enc
-\`\`\`
+## Registering the backend
 
-Prompts for encryption passphrase (or uses \`VIBES_SECRET_PASSPHRASE\` env var).
+Add the plugin to a runtime. It registers a lazy loader for the \`env-file\` backend under the \`secrets/store\` kind:
 
-### Decrypt a .env.enc file
+\`\`\`ts
+import { secretsBackendEnvFilePlugin } from '@vibesdotdev/secrets/backends/env-file';
 
-\`\`\`bash
-vibes secrets decrypt .env.enc --output .env
+// register secretsBackendEnvFilePlugin with your runtime alongside
+// '@vibesdotdev/secrets' (which provides the secrets/store kind)
 \`\`\`
 
-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>"
-\`\`\`
+This backend is **consumer hardware only** — it statically imports \`node:fs\`, so it must not be reachable from a cloud worker bundle.
 
 ## Programmatic usage
 
-### Load encrypted .env
+Resolve the active store from the runtime, then read or write secrets for an environment tier. The first argument to every store method is the **environment** name:
 
 \`\`\`ts
-import { loadEncryptedEnv } from '@vibesdotdev/secrets/env-file';
-
-const secrets = await loadEncryptedEnv('.env.enc', {
-  passphrase: process.env.VIBES_SECRET_PASSPHRASE
-});
+import { resolveSecretsStore } from '@vibesdotdev/secrets';
 
-// Secrets available in memory only
-console.log(secrets.DATABASE_URL);
-\`\`\`
+const store = await resolveSecretsStore(runtime, 'local');
+if (!store) throw new Error('no secrets backend registered');
 
-### Write encrypted .env
+// Read one value (undefined if absent)
+const dbUrl = await store.get('local', 'DATABASE_URL');
 
-\`\`\`ts
-import { writeEncryptedEnv } from '@vibesdotdev/secrets/env-file';
-
-await writeEncryptedEnv('.env.enc', {
-  DATABASE_URL: 'postgres://...',
-  API_KEY: '<api-key>'
-}, {
-  passphrase: 'your-passphrase'
-});
-\`\`\`
+// Read all values for the environment
+const all = await store.getAll('local'); // Record<string, string>
 
-## Integration with backends
+// Write one value
+await store.set('local', 'API_KEY', 'sk-test-123');
 
-Encrypted .env files can **sync** with secret backends:
+// Write many at once (merges with existing)
+await store.setAll('local', { FOO: '1', BAR: '2' });
 
-### Push to backend
+// List keys (values are not returned)
+const entries = await store.list('local'); // SecretEntry[]: { key, hasValue, source }
 
-\`\`\`bash
-vibes secrets push --from .env.enc
+// Remove a key
+await store.unset('local', 'API_KEY');
 \`\`\`
 
-Decrypts and uploads secrets to the configured backend (Vault, Wrangler, etc.).
+\`resolveSecretsStore\` returns \`null\` only when no \`secrets/store\` backend is registered for the scope. It throws if a backend is registered but its implementation cannot be resolved.
 
-### Pull from backend
+The package also exports \`createEnvFileStore\` (the implementation factory) and \`envFileDescriptor\` for advanced/manual wiring.
 
-\`\`\`bash
-vibes secrets pull --to .env.enc
-\`\`\`
-
-Downloads secrets from backend and writes encrypted file.
+## CLI commands
 
-## WRONG: Committing plaintext .env
+Secrets are managed through the \`vibes secrets\` command group (not encrypt/decrypt — the backend stores plaintext):
 
 \`\`\`bash
-# ❌ NEVER — add to .gitignore immediately
-echo ".env" >> .gitignore
-git add .env  # DON'T DO THIS
-\`\`\`
-
-## RIGHT: Commit encrypted version
+# Import root .env files into a backend, driven by the canonical manifest
+vibes secrets import --to encrypted-local
 
-\`\`\`bash
-# ✅ Safe to commit
-vibes secrets encrypt .env --output .env.enc
-git add .env.enc
-git commit -m "Add encrypted environment"
-\`\`\`
+# Export secrets from a local backend to an env-formatted file (audit-logged)
+vibes secrets export --out ./.env.export --force
 
-## Pre-commit hook
+# Validate stored secrets against infra manifest requirements
+vibes secrets check --environment local
 
-The pre-commit hook **blocks** plaintext secrets:
+# Remove a secret from the current environment
+vibes secrets unset DATABASE_URL
 
-\`\`\`bash
-# .git/hooks/pre-commit
-vibes secrets pre-commit-check
+# Move secrets between local and remote backends
+vibes secrets push --to cloudflare-secrets-store
+vibes secrets pull --from vault
 \`\`\`
 
-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
+## Pre-commit guard
 
-Decrypted secrets are injected as environment variables:
+A pre-commit hook scans staged files for high-risk secret patterns and blocks the commit if any are found:
 
-\`\`\`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;
-  });
-}
+\`\`\`bash
+vibes dev secrets pre-commit-check
 \`\`\`
 
-## File permissions
+It detects: Stripe live keys (\`sk_live_\`, \`pk_live_\`), DigitalOcean API keys (\`do_\`), AWS access key IDs (\`AKIA…\`), and GitHub tokens (\`ghp_\`, \`gho_\`).
 
-Encrypted files should have restrictive permissions:
+## Keep .env files out of version control
 
 \`\`\`bash
-chmod 600 .env.enc      # Owner read/write only
-chmod 600 .vibes/       # Secrets directory
+# ❌ NEVER commit a plaintext .env.{environment} file
+echo ".env.*" >> .gitignore
 \`\`\`
 
 :::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
+- [\`secrets.backends\`](secrets.backends) — Available secrets/store backends
+- [\`secrets.encryption\`](secrets.encryption) — Encryption-at-rest backend
+- [\`config.environment\`](config.environment) — Environment tiers and resolution
 :::
 `
     },
     parent: 'secrets',
     order: 3,
-    tags: ['secrets', 'env', 'dotenv', 'encryption', 'configuration'],
+    tags: ['secrets', 'env', 'dotenv', 'backend', 'configuration'],
     surfaces: ['cli', 'web', 'in-app'],
-    hardware: ['consumer', 'cloud'],
+    hardware: ['consumer'],
     man: {
-        name: 'secrets.env-file — Encrypted environment files',
+        name: 'secrets.env-file — Env-file secrets backend',
         section: 1,
         synopsis: 'vibes man secrets.env-file',
-        seeAlso: ['secrets.set', 'secrets.reveal', 'config.environment']
+        seeAlso: ['secrets.backends', 'secrets.encryption', 'config.environment']
     },
     enabled: true
 };

package/dist/docs/env-file.docs.descriptor.js.map

@@ -1 +1 @@
-{"version":3,"file":"env-file.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/env-file.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACtC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,kBAAkB;IACtB,KAAK,EAAE,6BAA6B;IACpC,OAAO,EAAE,uDAAuD;IAChE,IAAI,EAAE;QACJ,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsLX;KACE;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,eAAe,CAAC;IACjE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,GAAG,EAAE;QACH,IAAI,EAAE,gDAAgD;QACtD,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,4BAA4B;QACtC,OAAO,EAAE,CAAC,aAAa,EAAE,gBAAgB,EAAE,oBAAoB,CAAC;KACjE;IACD,OAAO,EAAE,IAAI;CACd,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"env-file.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/env-file.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,kBAAkB;IACtB,KAAK,EAAE,0BAA0B;IACjC,OAAO,EAAE,mGAAmG;IAC5G,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwIT;KACC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,CAAC;IAC9D,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,CAAC;IACtB,GAAG,EAAE;QACJ,IAAI,EAAE,6CAA6C;QACnD,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,4BAA4B;QACtC,OAAO,EAAE,CAAC,kBAAkB,EAAE,oBAAoB,EAAE,oBAAoB,CAAC;KACzE;IACD,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/secrets.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=secrets.docs.descriptor.d.ts.map

package/dist/docs/secrets.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/secrets.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAgCvE,QAAA,MAAM,UAAU,EAAE,mBAWjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/secrets.docs.descriptor.js

@@ -0,0 +1,43 @@
+const secretsMarkdown = `---
+title: Secrets
+summary: Backends, encryption at rest, and plaintext env files.
+order: 12
+---
+
+# Secrets
+
+Backends, encryption at rest, and plaintext env files. Store \`CredentialReference\`s, never resolved plaintext; secrets resolve per scope at use time.
+
+## When to use
+
+Reach for this area whenever an app needs a credential — API keys, OAuth tokens, signing secrets — that must stay out of source and out of plaintext config, and be resolved per scope (org, app, environment) only at the moment of use.
+
+## How it resolves
+
+Secret backends are runtime-resolved capabilities of kind \`secrets/store\`. Resolve the active store for the runtime's tier with \`resolve()\` (a tie between two stores of equal priority is \`store-ambiguous\`, never a silent first), or name one store with \`withId(id)\`:
+
+\`\`\`ts
+const store = await runtime.query('secrets/store').resolve();
+const vault = await runtime.query('secrets/store').withId('vault').resolve();
+\`\`\`
+
+:::card{title="In this section"}
+- [\`secrets.backends\`](secrets.backends) — Secret Backends
+- [\`secrets.encryption\`](secrets.encryption) — Encryption at Rest
+- [\`secrets.env-file\`](secrets.env-file) — Env-File Secrets (plaintext \`.env.<tier>\` files)
+:::
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'secrets',
+    title: 'Secrets',
+    summary: "Backends, encryption at rest, and plaintext env files.",
+    body: { type: 'markdown', sourceType: 'raw', source: secretsMarkdown },
+    order: 12,
+    tags: ['secrets', 'overview'],
+    surfaces: ['web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=secrets.docs.descriptor.js.map

package/dist/docs/secrets.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/secrets.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BvB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,SAAS;IACb,KAAK,EAAE,SAAS;IAChB,OAAO,EAAE,wDAAwD;IACjE,IAAI,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE;IACtE,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC;IAC7B,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC;IAC3B,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/domain/attestation/attestation.d.ts

@@ -0,0 +1,19 @@
+import { type LocalAttestationHandle } from '../../schemas/domain/attestation/provider.schema.ts';
+export type { LocalAttestationHandle } from '../../schemas/domain/attestation/provider.schema.ts';
+export { INSECURE_CLAIM_REASONS, MAX_CLAIM_BYTES, assertRegularClaim, insecureClaim, invalidClaim, isInsecureClaimRefusal, isOversizeClaimRefusal, missingClaim, privately, readClaim, readClaimText, removeClaimIfSecret, removeTemporaryClaim, writeClaim } from "./claim-files.ts";
+import { LocalAttestationToken, type RuntimeRef } from '@vibesdotdev/kernel';
+import { type CreateAttestationOptions } from './schemas.ts';
+export declare function randomSecret(): string;
+/**
+ * Start this server's attestation: generates a fresh secret, written atomically
+ * to a private claim file at `claimPath`, replacing (rotating) any previous start's claim.
+ */
+export declare function createLocalAttestation(options: CreateAttestationOptions, runtime: RuntimeRef): Promise<LocalAttestationHandle>;
+/**
+ * Read the attestation claim written by a same-user server at `claimPath`.
+ * Refuses `local-attestation-claim-insecure` for a non-private claim,
+ * `local-attestation-claim-missing` (UNAVAILABLE, retryable: true) when missing,
+ * and `local-attestation-claim-invalid` for content that is not a secret.
+ */
+export declare function readLocalAttestation(claimPath: string, runtime: RuntimeRef): Promise<LocalAttestationToken>;
+//# sourceMappingURL=attestation.d.ts.map

package/dist/domain/attestation/attestation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attestation.d.ts","sourceRoot":"","sources":["../../../src/domain/attestation/attestation.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,sBAAsB,EAAE,MAAM,qDAAqD,CAAC;AAE/H,YAAY,EAAE,sBAAsB,EAAE,MAAM,qDAAqD,CAAC;AAClG,OAAO,EAAE,sBAAsB,EAAC,eAAe,EAAC,kBAAkB,EAAC,aAAa,EAAC,YAAY,EAAC,sBAAsB,EAAC,sBAAsB,EAAC,YAAY,EAAC,SAAS,EAAC,SAAS,EAAC,aAAa,EAAC,mBAAmB,EAAC,oBAAoB,EAAC,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAYzQ,OAAO,EAGP,qBAAqB,EAErB,KAAK,UAAU,EACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEP,KAAK,wBAAwB,EAC5B,MAAM,cAAc,CAAC;AAsCtB,wBAAgB,YAAY,IAAI,MAAM,CAKrC;AAcD;;;GAGG;AACH,wBAAsB,sBAAsB,CAC3C,OAAO,EAAE,wBAAwB,EACjC,OAAO,EAAE,UAAU,GACjB,OAAO,CAAC,sBAAsB,CAAC,CA2BjC;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACzC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,UAAU,GACjB,OAAO,CAAC,qBAAqB,CAAC,CAOhC"}