@agfpd/iapeer 0.2.36 → 0.2.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.36",
+  "version": "0.2.37",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "type": "module",
   "bin": {

package/src/status/index.ts

@@ -6,12 +6,13 @@
 // error (fail-open). The core never acts on heartbeat staleness — it only REPORTS
 // it (healing the provider's daemon is the provider's job, their ADR-010).
 
-import { readFileSync, statSync } from 'fs'
+import { closeSync, openSync, readFileSync, statSync } from 'fs'
 import { join } from 'path'
 import { IAPEER_VERSION } from '../core/version.ts'
 import { resolveGlobalRoot } from '../storage/index.ts'
 import { daemonDiscoveryPath } from '../daemon/index.ts'
 import { waitForDaemonHealthy } from '../update/index.ts'
+import { iapeerBinPath } from '../install/index.ts'
 
 /** The slot-declaration filename in the storage root (next to peers-profiles.json). */
 export const MEMORY_PROVIDER_FILE = 'memory-provider.json'
@@ -135,16 +136,48 @@ export function heartbeatAgeSecs(provider: MemoryProvider, nowMs: number = Date.
   }
 }
 
+/**
+ * Probe whether the iapeer binary holds Full Disk Access (macOS TCC). Reads the
+ * user TCC.db — a canonical FDA-gated resource that is NEVER promptable (silent
+ * EPERM without the grant), so THE PROBE ITSELF raises no dialog (it must not be
+ * the very noise it detects). Byte-free: open+close to prove access, no content
+ * read. Returns:
+ *   true  — readable → FDA granted
+ *   false — EPERM/EACCES → FDA NOT granted (peers will hit TCC prompts on
+ *           protected folders + foreign app containers — see onboard contract)
+ *   null  — not macOS / no HOME / TCC.db absent → cannot determine (no claim)
+ */
+export function probeFullDiskAccess(env: NodeJS.ProcessEnv = process.env): boolean | null {
+  if (process.platform !== 'darwin') return null
+  const home = env.HOME
+  if (!home) return null
+  const marker = join(home, 'Library', 'Application Support', 'com.apple.TCC', 'TCC.db')
+  try {
+    closeSync(openSync(marker, 'r'))
+    return true
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code
+    if (code === 'EPERM' || code === 'EACCES') return false
+    return null // ENOENT / unexpected → undeterminable, never a false claim
+  }
+}
+
 export interface HostStatus {
   version: string
   daemon: { healthy: boolean; url: string | null; sock: string | null }
   memory: { provider: MemoryProvider | null; heartbeatAgeSecs: number | null }
+  /** Full Disk Access of the iapeer binary: true granted / false not-granted /
+   *  null undeterminable (non-macOS or TCC.db unreadable for a non-TCC reason). */
+  fda: boolean | null
 }
 
 export interface HostStatusOptions {
   env?: NodeJS.ProcessEnv
   /** Injectable daemon probe (tests). Default: the real socket probe. */
   probe?: () => Promise<boolean>
+  /** Injectable FDA probe (tests — the default reads the real TCC.db, which a
+   *  hermetic test must not touch). Default: probeFullDiskAccess(env). */
+  fdaProbe?: () => boolean | null
 }
 
 /** Assemble the host snapshot: baked version + daemon probe + memory slot. */
@@ -161,10 +194,12 @@ export async function hostStatus(opts: HostStatusOptions = {}): Promise<HostStat
   }
   const health = await waitForDaemonHealthy({ env, timeoutMs: 2500, needConsecutive: 1, probe: opts.probe })
   const provider = readMemoryProvider(env)
+  const fda = (opts.fdaProbe ?? (() => probeFullDiskAccess(env)))()
   return {
     version: IAPEER_VERSION,
     daemon: { healthy: health.healthy, url, sock },
     memory: { provider, heartbeatAgeSecs: provider ? heartbeatAgeSecs(provider) : null },
+    fda,
   }
 }
 
@@ -184,5 +219,19 @@ export function formatHostStatus(s: HostStatus): string {
       : ' (daemon not running — no heartbeat file)'
   }
   const memory = s.memory.provider ? `${s.memory.provider.provider} ${s.memory.provider.version}${hb}` : 'none'
-  return `iapeer ${s.version}\ndaemon: ${daemon}\nmemory: ${memory}\n`
+  // FDA line: granted → terse OK; NOT granted → the actionable hint (a fresh host
+  // without FDA silently meets TCC prompts on every new protected class — peers
+  // read protected folders + foreign app containers, attributed to this binary;
+  // see onboard contract §INSTALL). undeterminable → say so, never a false claim.
+  let fda: string
+  if (s.fda === true) {
+    fda = 'fda: granted'
+  } else if (s.fda === false) {
+    fda =
+      `fda: NOT granted — peers will hit TCC prompts on protected paths.\n` +
+      `  grant: System Settings → Privacy & Security → Full Disk Access → + → ⇧⌘G → ${iapeerBinPath()}`
+  } else {
+    fda = 'fda: unknown (not macOS / undeterminable)'
+  }
+  return `iapeer ${s.version}\ndaemon: ${daemon}\nmemory: ${memory}\n${fda}\n`
 }

package/src/status/status.test.ts

@@ -128,7 +128,7 @@ describe('heartbeatAgeSecs', () => {
 describe('hostStatus + formatHostStatus', () => {
   test('empty slot → memory: none; daemon health from the injected probe', async () => {
     const root = mkTmp()
-    const s = await hostStatus({ env: envFor(root), probe: async () => true })
+    const s = await hostStatus({ env: envFor(root), probe: async () => true, fdaProbe: () => null })
     expect(s.daemon.healthy).toBe(true)
     expect(s.memory.provider).toBeNull()
     expect(formatHostStatus(s)).toContain('memory: none')
@@ -140,7 +140,7 @@ describe('hostStatus + formatHostStatus', () => {
     const hb = join(root, 'memoryd.heartbeat')
     writeFileSync(hb, '')
     writeFileSync(memoryProviderPath(env), JSON.stringify({ ...VALID, heartbeat: hb }))
-    const s = await hostStatus({ env, probe: async () => true })
+    const s = await hostStatus({ env, probe: async () => true, fdaProbe: () => null })
     expect(formatHostStatus(s)).toMatch(/memory: iapeer-memory 0\.1\.0 \(heartbeat \d+s ago\)/)
   })
 
@@ -152,6 +152,7 @@ describe('hostStatus + formatHostStatus', () => {
         provider: { ...VALID, heartbeat: '/nope/hb' } as MemoryProvider,
         heartbeatAgeSecs: null,
       },
+      fda: null,
     }
     const text = formatHostStatus(s)
     expect(text).toContain('memory: iapeer-memory 0.1.0 (daemon not running — no heartbeat file)')
@@ -164,9 +165,48 @@ describe('hostStatus + formatHostStatus', () => {
     const stateDir = join(root, 'state', 'iapeer')
     mkdirSync(stateDir, { recursive: true })
     writeFileSync(join(stateDir, 'router.json'), JSON.stringify({ sock: '/x/router.sock', tcp: 'http://127.0.0.1:8765/mcp' }))
-    const s = await hostStatus({ env, probe: async () => true })
+    const s = await hostStatus({ env, probe: async () => true, fdaProbe: () => null })
     const text = formatHostStatus(s)
     expect(text).toContain('@ http://127.0.0.1:8765/mcp')
     expect(text).toContain('+ /x/router.sock')
   })
 })
+
+describe('FDA detection (iapeer status — fresh-host observability)', () => {
+  function base(fda: boolean | null): HostStatus {
+    return {
+      version: '0.0.0',
+      daemon: { healthy: true, url: null, sock: null },
+      memory: { provider: null, heartbeatAgeSecs: null },
+      fda,
+    }
+  }
+
+  test('granted → terse OK line, no instruction', () => {
+    const text = formatHostStatus(base(true))
+    expect(text).toContain('fda: granted')
+    expect(text).not.toContain('NOT granted')
+    expect(text).not.toContain('Full Disk Access')
+  })
+
+  test('NOT granted → actionable hint with the binary path', () => {
+    const text = formatHostStatus(base(false))
+    expect(text).toContain('fda: NOT granted')
+    expect(text).toContain('Full Disk Access')
+    expect(text).toMatch(/iapeer$|iapeer\n/m) // the grant path ends at the binary
+  })
+
+  test('undeterminable → explicit unknown, never a false claim', () => {
+    const text = formatHostStatus(base(null))
+    expect(text).toContain('fda: unknown')
+    expect(text).not.toContain('NOT granted')
+    expect(text).not.toContain('granted\n') // not the bare "granted" either
+  })
+
+  test('hostStatus threads the injected fdaProbe verbatim', async () => {
+    const root = mkTmp()
+    const s = await hostStatus({ env: envFor(root), probe: async () => true, fdaProbe: () => false })
+    expect(s.fda).toBe(false)
+    expect(formatHostStatus(s)).toContain('fda: NOT granted')
+  })
+})