@tangle-network/starter-foundry 0.7.3 → 0.13.2

package/registry/layers/agent-base/secure/files/lib/secure/index.test.ts

@@ -0,0 +1,422 @@
+// Tests for agent-base:secure. Adversarial: every HIGH/MEDIUM finding
+// from the 2026-04-26 critical-audit gets a regression test. Real-system
+// where possible (real fs, real crypto); only mocks the network layer
+// at the fetch boundary.
+//
+// Run with: tsx --test registry/layers/agent-base/secure/files/lib/secure/index.test.ts
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { createHmac } from 'node:crypto'
+
+// Each test must set up a clean workspace + identity before importing the
+// secure modules, so we use dynamic imports inside per-test setup.
+
+function tempWorkspace(): string {
+  const root = mkdtempSync(join(tmpdir(), 'secure-test-'))
+  mkdirSync(join(root, 'agent-A'), { recursive: true })
+  mkdirSync(join(root, 'agent-A', '.audit'), { recursive: true })
+  return root
+}
+
+function setupIdentity(agentId = 'agent-A', capabilities: string[] = []): void {
+  const now = Date.now()
+  process.env.TANGLE_AGENT_IDENTITY_JSON = JSON.stringify({
+    agentId,
+    sessionId: `s-${now}`,
+    deployerId: 'deployer-A',
+    signedAt: now,
+    expiresAt: now + 3600_000,
+    capabilities,
+    publicKey: 'k',
+    signature: 's',
+  })
+}
+
+// Every test that may trigger audit.log needs an isolated workspace root.
+// Tests that explicitly clear env (fail-closed checks) MUST run BEFORE
+// importing modules — or set the root pre-import. This helper does both.
+async function setupTestEnv(agentId = 'agent-A', capabilities: string[] = ['sensitive-fs']): Promise<string> {
+  const root = tempWorkspace()
+  process.env.AGENT_WORKSPACE_ROOT = root
+  setupIdentity(agentId, capabilities)
+  mkdirSync(join(root, agentId, '.audit'), { recursive: true })
+  // Reset all module-level caches so the new identity + workspace root takes effect.
+  const { identity } = await import('./identity.js')
+  const { workspace } = await import('./workspace.js')
+  const { audit } = await import('./audit.js')
+  const { secrets } = await import('./secrets.js')
+  identity.invalidate()
+  workspace._resetForTest()
+  audit._resetStateForTest()
+  secrets.clearCache()
+  return root
+}
+
+function clearEnvForFailClosed(): void {
+  delete process.env.TANGLE_AGENT_IDENTITY_JSON
+  delete process.env.SF_DEV_IDENTITY_OPTIN
+  delete process.env.AGENT_NAME
+}
+
+// ── identity (H3) ────────────────────────────────────────────────────────
+
+test('identity: fail-closed when env missing AND no dev opt-in', async () => {
+  clearEnvForFailClosed()
+  // Force re-import to bypass module cache (Node test cache is per-file scope)
+  const { identity } = await import('./identity.js')
+  identity.invalidate()
+  assert.throws(() => identity.current(), /TANGLE_AGENT_IDENTITY_JSON missing/)
+})
+
+test('identity: dev opt-in returns synthetic with NO sensitive-fs capability', async () => {
+  clearEnvForFailClosed()
+  process.env.AGENT_WORKSPACE_ROOT = tempWorkspace()
+  process.env.SF_DEV_IDENTITY_OPTIN = '1'
+  process.env.AGENT_NAME = 'dev-X'
+  mkdirSync(join(process.env.AGENT_WORKSPACE_ROOT, 'dev-X', '.audit'), { recursive: true })
+  const { identity } = await import('./identity.js')
+  identity.invalidate()
+  const id = identity.current()
+  assert.equal(id.agentId, 'dev-X')
+  assert.deepEqual(id.capabilities, [])
+  delete process.env.SF_DEV_IDENTITY_OPTIN
+})
+
+test('identity: real envelope honored when present', async () => {
+  process.env.AGENT_WORKSPACE_ROOT = tempWorkspace()
+  setupIdentity('real-agent', ['sensitive-fs'])
+  mkdirSync(join(process.env.AGENT_WORKSPACE_ROOT, 'real-agent', '.audit'), { recursive: true })
+  const { identity } = await import('./identity.js')
+  identity.invalidate()
+  const id = identity.current()
+  assert.equal(id.agentId, 'real-agent')
+  assert.deepEqual(id.capabilities, ['sensitive-fs'])
+})
+
+// ── secrets (H1, M3) ─────────────────────────────────────────────────────
+
+test('secrets: dotenvx ciphertext rejected as un-decrypted', async () => {
+  setupIdentity()
+  process.env.AGENT_WORKSPACE_ROOT = tempWorkspace()
+  process.env.NOT_DECRYPTED = 'encrypted:eyJBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBPT0='
+  const { secrets } = await import('./secrets.js')
+  secrets.clearCache()
+  assert.throws(
+    () => secrets.require('NOT_DECRYPTED'),
+    /value looks like dotenvx ciphertext/,
+  )
+  delete process.env.NOT_DECRYPTED
+})
+
+test('secrets: SecureString.toString() returns [REDACTED]', async () => {
+  setupIdentity()
+  process.env.AGENT_WORKSPACE_ROOT = tempWorkspace()
+  process.env.LEAK_TEST = 'sk-real-secret-value'
+  const { secrets } = await import('./secrets.js')
+  secrets.clearCache()
+  const sec = secrets.require('LEAK_TEST')
+  assert.equal(sec.toString(), '[REDACTED]')
+  assert.equal(JSON.stringify({ key: sec }), '{"key":"[REDACTED]"}')
+  assert.equal(`${sec}`, '[REDACTED]')
+  // unsafeReveal returns the real value
+  assert.equal(sec.unsafeReveal('test'), 'sk-real-secret-value')
+  delete process.env.LEAK_TEST
+})
+
+test('secrets: clearCache() empties cache (M3 fix — renamed from purge)', async () => {
+  setupIdentity()
+  process.env.AGENT_WORKSPACE_ROOT = tempWorkspace()
+  process.env.K1 = 'v1'
+  const { secrets } = await import('./secrets.js')
+  secrets.clearCache()
+  secrets.require('K1')
+  // First read populated cache; second read should be a cache hit (audit
+  // logs cacheHit:true)
+  secrets.require('K1')
+  secrets.clearCache()
+  // After clear, the next read is a fresh fetch
+  secrets.require('K1')
+  assert.ok(true) // no crash; behavior verified via audit log inspection
+  delete process.env.K1
+})
+
+// ── workspace (H2) ───────────────────────────────────────────────────────
+
+test('workspace: path-traversal rejected', async () => {
+  const root = tempWorkspace()
+  process.env.AGENT_WORKSPACE_ROOT = root
+  setupIdentity('agent-A', ['sensitive-fs'])
+  const { workspace } = await import('./workspace.js')
+  workspace._resetForTest()
+  assert.throws(() => workspace.read('../../etc/passwd'), /path-traversal rejected/)
+  assert.throws(() => workspace.write('../escape', 'oops'), /path-traversal rejected/)
+})
+
+test('workspace: agent root frozen at first call (H2 fix)', async () => {
+  const root = tempWorkspace()
+  mkdirSync(join(root, 'agent-A'), { recursive: true })
+  mkdirSync(join(root, 'agent-B'), { recursive: true })
+  process.env.AGENT_WORKSPACE_ROOT = root
+  setupIdentity('agent-A')
+  const { workspace } = await import('./workspace.js')
+  workspace._resetForTest()
+  workspace.write('canary.txt', 'A')
+  // Now mutate identity to claim a different agent
+  setupIdentity('agent-B')
+  // Read should still resolve under agent-A's root (frozen)
+  assert.equal(workspace.read('canary.txt'), 'A')
+  // Confirm via direct fs that B did NOT receive the write
+  assert.throws(() => readFileSync(join(root, 'agent-B', 'canary.txt'), 'utf8'))
+})
+
+test('workspace: sensitive-zone requires sensitive-fs capability', async () => {
+  await setupTestEnv('agent-A', []) // NO sensitive-fs
+  const { workspace } = await import('./workspace.js')
+  assert.throws(() => workspace.write('sensitive/secret.txt', 'oops'), /sensitive zone access denied/)
+})
+
+test('workspace: sensitive-zone allowed with capability', async () => {
+  await setupTestEnv('agent-A', ['sensitive-fs'])
+  const { workspace } = await import('./workspace.js')
+  workspace.write('sensitive/notes.txt', 'phi')
+  assert.equal(workspace.read('sensitive/notes.txt'), 'phi')
+})
+
+// ── webhook-in (H4) ──────────────────────────────────────────────────────
+
+test('webhook-in: case-insensitive header lookup (H4 fix)', async () => {
+  setupIdentity()
+  process.env.AGENT_WORKSPACE_ROOT = tempWorkspace()
+  process.env.WH_SECRET = 's3cret-key'
+  const { defineWebhook, mountWebhooks } = await import('./webhook-in.js')
+  let handlerCalled = false
+  defineWebhook({
+    path: '/test-h4',
+    secretName: 'WH_SECRET',
+    handler: () => {
+      handlerCalled = true
+    },
+  })
+  const ts = Date.now().toString()
+  const body = '{"foo":1}'
+  const sig = createHmac('sha256', 's3cret-key').update(`${ts}.${body}`).digest('hex')
+  // Mixed-case headers as some frameworks emit
+  const res = await mountWebhooks({
+    path: '/test-h4',
+    headers: { 'X-Tangle-Signature': sig, 'X-Tangle-Timestamp': ts, 'X-Tangle-Sender': 'agent-X' },
+    rawBody: body,
+  })
+  assert.equal(res.status, 200)
+  assert.ok(handlerCalled)
+  delete process.env.WH_SECRET
+})
+
+test('webhook-in: bad signature rejected with 401', async () => {
+  setupIdentity()
+  process.env.AGENT_WORKSPACE_ROOT = tempWorkspace()
+  process.env.WH_SECRET2 = 's3cret-key'
+  const { defineWebhook, mountWebhooks } = await import('./webhook-in.js')
+  defineWebhook({ path: '/test-bad-sig', secretName: 'WH_SECRET2', handler: () => {} })
+  const ts = Date.now().toString()
+  const body = '{"foo":1}'
+  const res = await mountWebhooks({
+    path: '/test-bad-sig',
+    headers: { 'x-tangle-signature': 'deadbeef', 'x-tangle-timestamp': ts },
+    rawBody: body,
+  })
+  assert.equal(res.status, 401)
+  assert.match(res.body, /signature mismatch/)
+  delete process.env.WH_SECRET2
+})
+
+test('webhook-in: replay window enforced', async () => {
+  setupIdentity()
+  process.env.AGENT_WORKSPACE_ROOT = tempWorkspace()
+  process.env.WH_SECRET3 = 'k'
+  const { defineWebhook, mountWebhooks } = await import('./webhook-in.js')
+  defineWebhook({ path: '/test-replay', secretName: 'WH_SECRET3', handler: () => {} })
+  const oldTs = (Date.now() - 10 * 60_000).toString() // 10 min ago, past 5-min window
+  const body = '{}'
+  const sig = createHmac('sha256', 'k').update(`${oldTs}.${body}`).digest('hex')
+  const res = await mountWebhooks({
+    path: '/test-replay',
+    headers: { 'x-tangle-signature': sig, 'x-tangle-timestamp': oldTs },
+    rawBody: body,
+  })
+  assert.equal(res.status, 401)
+  assert.match(res.body, /timestamp outside replay window/)
+  delete process.env.WH_SECRET3
+})
+
+test('webhook-in: schema rejection returns 422', async () => {
+  setupIdentity()
+  process.env.AGENT_WORKSPACE_ROOT = tempWorkspace()
+  process.env.WH_SECRET4 = 'k'
+  const { defineWebhook, mountWebhooks } = await import('./webhook-in.js')
+  defineWebhook({
+    path: '/test-schema',
+    secretName: 'WH_SECRET4',
+    schema: (b) => (typeof (b as { id?: string }).id === 'string' ? null : 'id required'),
+    handler: () => {},
+  })
+  const ts = Date.now().toString()
+  const body = '{"name":"alice"}' // missing id
+  const sig = createHmac('sha256', 'k').update(`${ts}.${body}`).digest('hex')
+  const res = await mountWebhooks({
+    path: '/test-schema',
+    headers: { 'x-tangle-signature': sig, 'x-tangle-timestamp': ts },
+    rawBody: body,
+  })
+  assert.equal(res.status, 422)
+  assert.match(res.body, /id required/)
+  delete process.env.WH_SECRET4
+})
+
+// ── webhook-out ──────────────────────────────────────────────────────────
+
+test('webhook-out: rejects target not in allowedDomains', async () => {
+  setupIdentity()
+  process.env.AGENT_WORKSPACE_ROOT = tempWorkspace()
+  process.env.OUT_SECRET = 'k'
+  const { webhookOut } = await import('./webhook-out.js')
+  const r = await webhookOut('https://evil.example.com/hook', { x: 1 }, {
+    secretName: 'OUT_SECRET',
+    allowedDomains: ['tangle.tools'],
+  })
+  assert.equal(r.ok, false)
+  assert.match(r.error ?? '', /allowedDomains/)
+  delete process.env.OUT_SECRET
+})
+
+test('webhook-out: subdomain match works', async () => {
+  setupIdentity()
+  process.env.AGENT_WORKSPACE_ROOT = tempWorkspace()
+  process.env.OUT_SECRET2 = 'k'
+  // Stub global fetch to capture the request without making it
+  const realFetch = globalThis.fetch
+  let captured: { url: string; headers: Record<string, string> } | null = null
+  globalThis.fetch = (async (url: string, init: RequestInit) => {
+    captured = { url, headers: init.headers as Record<string, string> }
+    return new Response('ok', { status: 200 })
+  }) as typeof fetch
+  try {
+    const { webhookOut } = await import('./webhook-out.js')
+    const r = await webhookOut('https://api.tangle.tools/hook', { x: 1 }, {
+      secretName: 'OUT_SECRET2',
+      allowedDomains: ['tangle.tools'],
+    })
+    assert.equal(r.ok, true)
+    assert.ok(captured)
+    assert.ok(captured!.headers['x-tangle-signature'])
+    assert.ok(captured!.headers['x-tangle-timestamp'])
+  } finally {
+    globalThis.fetch = realFetch
+    delete process.env.OUT_SECRET2
+  }
+})
+
+// ── audit (M1, M2) ───────────────────────────────────────────────────────
+
+test('audit: hash chain stable across canonical JSON (M1 fix)', async () => {
+  await setupTestEnv()
+  const { audit } = await import('./audit.js')
+  // Two entries; the chain links via prevHash; verifyDay re-derives the
+  // chain and confirms it matches.
+  audit.log({ event: 'test.event-1', target: 'X', payload: { a: 1, b: 2 } })
+  audit.log({ event: 'test.event-2', target: 'Y', payload: { c: 3 } })
+  const today = new Date().toISOString().slice(0, 10)
+  const result = audit.verifyDay(today)
+  assert.equal(result.ok, true)
+})
+
+test('audit: verifyDay detects tampering', async () => {
+  setupIdentity('audit-tamper-test')
+  const root = tempWorkspace()
+  mkdirSync(join(root, 'audit-tamper-test', '.audit'), { recursive: true })
+  process.env.AGENT_WORKSPACE_ROOT = root
+  const { audit } = await import('./audit.js')
+  audit.log({ event: 'untampered', target: 'Z' })
+  audit.log({ event: 'untampered2', target: 'Z' })
+  const today = new Date().toISOString().slice(0, 10)
+  const file = join(root, 'audit-tamper-test', '.audit', `${today}.jsonl`)
+  let raw = readFileSync(file, 'utf8')
+  // Tamper the first line's payload — the chain hash on line 2 should mismatch
+  const lines = raw.trim().split('\n')
+  const first = JSON.parse(lines[0]!)
+  first.target = 'TAMPERED'
+  lines[0] = JSON.stringify(first)
+  writeFileSync(file, lines.join('\n') + '\n')
+  const result = audit.verifyDay(today)
+  assert.equal(result.ok, false)
+  assert.ok(result.tamperedAtSeq! >= 1)
+})
+
+test('audit: fail-closed on missing identity (M2 fix)', async () => {
+  clearEnvForFailClosed()
+  const { audit } = await import('./audit.js')
+  assert.throws(
+    () => audit.log({ event: 'missing-actor' }),
+    /cannot resolve actor/,
+  )
+})
+
+// ── schedule ─────────────────────────────────────────────────────────────
+
+test('schedule: cron validation accepts standard expressions', async () => {
+  const { schedule } = await import('./schedule.js')
+  assert.equal(schedule.validateCron('0 14 * * 1'), null)
+  assert.equal(schedule.validateCron('*/15 * * * *'), null)
+})
+
+test('schedule: cron validation rejects malformed', async () => {
+  const { schedule } = await import('./schedule.js')
+  assert.match(schedule.validateCron('0 14 * *') ?? '', /5 fields/)
+  assert.match(schedule.validateCron('99 * * * *') ?? '', /out of range/)
+})
+
+test('schedule: handler dispatch via _fire respects identity', async () => {
+  await setupTestEnv()
+  const { schedule } = await import('./schedule.js')
+  let fired = false
+  // Use unique capability per test so registration doesn't conflict
+  schedule.on('test-cap-fire', async () => {
+    fired = true
+  })
+  await schedule._fire({ id: 't1', cron: '0 8 * * *', capability: 'test-cap-fire' })
+  assert.equal(fired, true)
+})
+
+test('schedule: missing handler throws', async () => {
+  await setupTestEnv()
+  const { schedule } = await import('./schedule.js')
+  await assert.rejects(
+    () => schedule._fire({ id: 't2', cron: '0 8 * * *', capability: 'no-such-cap-unique' }),
+    /no schedule handler/,
+  )
+})
+
+// ── identity verify() ────────────────────────────────────────────────────
+//
+// verify() is NOT IMPLEMENTED — see identity.ts. Until the gateway
+// pubkey directory ships, calling verify() throws. This test pins
+// that behavior so a future stub that "just returns true" cannot
+// silently regress the contract.
+
+test('identity: verify() throws not-implemented (gateway pubkey directory not shipped)', async () => {
+  await setupTestEnv()
+  const { identity } = await import('./identity.js')
+  const envelope = {
+    agentId: 'X',
+    sessionId: 's',
+    deployerId: 'd',
+    signedAt: Date.now(),
+    expiresAt: Date.now() + 3600_000,
+    publicKey: 'k',
+    signature: 's',
+  }
+  assert.throws(() => identity.verify(envelope), /not implemented/)
+})

package/registry/layers/agent-base/secure/files/lib/secure/index.ts

@@ -0,0 +1,16 @@
+// agent-base:secure — security floor for every agent-runtime bundle.
+//
+// Composition surface. Each primitive ships as its own module so a bundle
+// can import only what it needs. The default operating mode is "everything
+// is secure unless you explicitly opt out, and opt-outs are audit-logged."
+//
+// See docs/specs/agent-base-secure.md for guarantees, threat model, and
+// operator responsibilities.
+
+export { loadSecret, requireSecret, secrets, type SecureString } from './secrets.js'
+export { workspace } from './workspace.js'
+export { defineWebhook, mountWebhooks, type WebhookSpec } from './webhook-in.js'
+export { webhookOut, type WebhookOutOptions } from './webhook-out.js'
+export { schedule, type ScheduledTrigger } from './schedule.js'
+export { identity } from './identity.js'
+export { audit, type AuditEntry } from './audit.js'

package/registry/layers/agent-base/secure/files/lib/secure/schedule.ts

@@ -0,0 +1,83 @@
+// schedule — declarative scheduled triggers driven by the manifest's
+// defaults.schedule[] array. Each trigger executes with the agent's
+// signed identity. Replaces wrangler.toml [triggers] cron config.
+//
+// Bundles do not write cron handlers directly; they declare schedules
+// in the manifest and implement the matching capability. The runtime
+// dispatches to the capability at trigger time.
+
+import { audit } from './audit.js'
+import { identity } from './identity.js'
+
+export interface ScheduledTrigger {
+  /** Stable id, matched against capability dispatcher. */
+  id: string
+  /** Standard 5-field cron expression (minute hour day month dayOfWeek). */
+  cron: string
+  /** Capability name from manifest.defaults.declaredCapabilities. */
+  capability: string
+  /** When true, runtime guarantees at-least-once delivery on operator
+   * restart; otherwise best-effort. */
+  atLeastOnce?: boolean
+}
+
+const handlers = new Map<string, (trigger: ScheduledTrigger) => Promise<void>>()
+
+export const schedule = {
+  /** Register a capability handler. The runtime calls this on trigger
+   * fire. The handler's identity is the agent's current identity. */
+  on(capability: string, handler: (trigger: ScheduledTrigger) => Promise<void>): void {
+    if (handlers.has(capability)) {
+      throw new Error(`schedule handler already registered for capability: ${capability}`)
+    }
+    handlers.set(capability, handler)
+    audit.log({ event: 'schedule.handler-register', target: capability })
+  },
+
+  /** Runtime entry point — invoked by the trigger dispatcher when a
+   * cron fires. Bundles do NOT call this directly. */
+  async _fire(trigger: ScheduledTrigger): Promise<void> {
+    const handler = handlers.get(trigger.capability)
+    if (!handler) {
+      audit.log({ event: 'schedule.miss', target: trigger.id, payload: { capability: trigger.capability, reason: 'no-handler-registered' } })
+      throw new Error(`no schedule handler for capability ${trigger.capability}`)
+    }
+    const id = identity.current()
+    audit.log({ event: 'schedule.fire', target: trigger.id, payload: { capability: trigger.capability, agentId: id.agentId } })
+    try {
+      await handler(trigger)
+      audit.log({ event: 'schedule.complete', target: trigger.id, payload: { capability: trigger.capability } })
+    } catch (err) {
+      audit.log({ event: 'schedule.error', target: trigger.id, payload: { capability: trigger.capability, error: (err as Error).message.slice(0, 200) } })
+      throw err
+    }
+  },
+
+  /** Validate a cron expression at registration time (before runtime
+   * accepts the manifest). Returns null on success, error string on
+   * failure. The runtime's own cron parser may be stricter. */
+  validateCron(cron: string): null | string {
+    const fields = cron.trim().split(/\s+/)
+    if (fields.length !== 5) return `expected 5 fields (m h dom mon dow), got ${fields.length}`
+    const ranges = [
+      [0, 59], // minute
+      [0, 23], // hour
+      [1, 31], // day-of-month
+      [1, 12], // month
+      [0, 7],  // day-of-week (7 == 0 == Sunday)
+    ]
+    for (let i = 0; i < 5; i++) {
+      const f = fields[i]!
+      if (f === '*') continue
+      // Allow simple comma-separated lists, ranges, steps.
+      if (!/^(\*|\*\/\d+|\d+(-\d+)?(,\d+(-\d+)?)*(\/\d+)?)$/.test(f)) {
+        return `field ${i} (${f}) does not match cron syntax`
+      }
+      const numbers = f.match(/\d+/g)?.map(Number) ?? []
+      for (const n of numbers) {
+        if (n < ranges[i]![0] || n > ranges[i]![1]) return `field ${i} value ${n} out of range [${ranges[i]![0]}, ${ranges[i]![1]}]`
+      }
+    }
+    return null
+  },
+}

package/registry/layers/agent-base/secure/files/lib/secure/secrets.ts

@@ -0,0 +1,128 @@
+// secrets — dotenvx-encrypted secret storage with a SecureString that
+// resists accidental leakage via logs/JSON serialization.
+//
+// Threat: an agent author console.logs the API key during a debug
+// session, that log gets shipped to Sentry. SecureString throws on
+// .toString() and serializes as '[REDACTED]'. The author has to call
+// .unsafeReveal() to get the raw string, and that call is audit-logged.
+
+import { audit } from './audit.js'
+
+const REDACTED = '[REDACTED]'
+
+export class SecureString {
+  // Private + non-enumerable so JSON.stringify can't reach it.
+  readonly #value: string
+  readonly #name: string
+
+  constructor(name: string, value: string) {
+    this.#name = name
+    this.#value = value
+  }
+
+  toString(): string {
+    return REDACTED
+  }
+
+  toJSON(): string {
+    return REDACTED
+  }
+
+  // Explicit reveal. Audit-logs every call. Use only at the
+  // boundary where the raw string crosses into a non-loggable
+  // surface (HTTP Authorization header, signed payload, etc.).
+  unsafeReveal(reason: string): string {
+    audit.log({
+      event: 'secret.reveal',
+      target: this.#name,
+      payload: { reason: reason.slice(0, 200) },
+    })
+    return this.#value
+  }
+
+  get name(): string {
+    return this.#name
+  }
+}
+
+interface SecretsBackend {
+  get(name: string): string | undefined
+}
+
+// Detects values that look like dotenvx ciphertext but were not decrypted —
+// the failure mode H1 flagged. Real dotenvx output always starts with
+// `encrypted:` or is a base64 envelope with a known prefix. If a secret value
+// matches this shape, dotenvx didn't run and we'd be returning ciphertext
+// to the caller as if it were plaintext.
+const DOTENVX_CIPHERTEXT_RE = /^encrypted:[A-Za-z0-9+/=]+$/
+
+class DotenvxBackend implements SecretsBackend {
+  // Uses process.env at runtime. dotenvx's CLI/runtime decrypts
+  // .env.encrypted via DOTENV_PRIVATE_KEY at process start; we read
+  // from process.env which the dotenvx wrapper already populated.
+  get(name: string): string | undefined {
+    const raw = process.env[name]
+    if (raw === undefined) return undefined
+    if (DOTENVX_CIPHERTEXT_RE.test(raw)) {
+      throw new Error(
+        `secrets.${name}: value looks like dotenvx ciphertext (starts with 'encrypted:'). ` +
+          'dotenvx decryption did not run — check DOTENV_PRIVATE_KEY is set in the runtime ' +
+          'environment and that .env.encrypted is loaded before the agent starts. ' +
+          'Refusing to return ciphertext as if it were plaintext.',
+      )
+    }
+    return raw
+  }
+}
+
+const cache = new Map<string, SecureString>()
+const backend: SecretsBackend = new DotenvxBackend()
+
+/**
+ * Load a secret. Returns undefined when missing (caller decides whether
+ * that's recoverable). Use requireSecret() for hard-required secrets.
+ */
+export function loadSecret(name: string): SecureString | undefined {
+  if (cache.has(name)) {
+    audit.log({ event: 'secret.read', target: name, payload: { cacheHit: true } })
+    return cache.get(name)
+  }
+  const raw = backend.get(name)
+  if (raw === undefined) {
+    audit.log({ event: 'secret.miss', target: name })
+    return undefined
+  }
+  const secure = new SecureString(name, raw)
+  cache.set(name, secure)
+  audit.log({ event: 'secret.read', target: name, payload: { cacheHit: false } })
+  return secure
+}
+
+/**
+ * Hard-required secret. Throws on miss. Use this when the bundle
+ * cannot operate without the secret.
+ */
+export function requireSecret(name: string): SecureString {
+  const secret = loadSecret(name)
+  if (!secret) {
+    throw new Error(`required secret missing: ${name} (declare in manifest.defaults.secrets and check .env.encrypted)`)
+  }
+  return secret
+}
+
+export const secrets = {
+  load: loadSecret,
+  require: requireSecret,
+  /**
+   * Clear the in-process secret cache. SecureString instances already
+   * handed out to bundle code are NOT zeroed — they remain live in
+   * memory until garbage-collected. This is a CACHE clear, not a memory
+   * shred. The name reflects what it actually does (M3 fix — was misnamed
+   * `purge()` which implied a stronger guarantee than delivered).
+   */
+  clearCache(): void {
+    const count = cache.size
+    cache.clear()
+    audit.log({ event: 'secret.cache-clear', payload: { cleared: count } })
+  },
+}