@shieldfive/mcp 0.2.0 → 0.4.0

package/src/vault/credential.mjs

@@ -0,0 +1,75 @@
+// Where the grant's connection string comes from, and nothing else.
+//
+// A connection string holds the bearer token AND the grant secret that opens
+// the grant's keys. It is looked up in this order:
+//
+//   1. SHIELDFIVE_GRANT in the environment — for CI and headless use. Anything
+//      that can read this process's environment can read it; say so in docs.
+//   2. The OS keychain (macOS Keychain, Windows Credential Manager, the Secret
+//      Service on Linux), written by `npx @shieldfive/mcp login`.
+//
+// It is never written to a file by this package, never logged, and never
+// included in a tool result or an error message. parseConnectionString's
+// errors describe the shape, not the value.
+
+import { parseConnectionString, VaultCryptoError } from '@shieldfive/crypto/vault'
+
+export const KEYCHAIN_SERVICE = 'shieldfive-mcp'
+export const KEYCHAIN_ACCOUNT = 'grant'
+
+async function keychainEntry() {
+  const { Entry } = await import('@napi-rs/keyring')
+  return new Entry(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT)
+}
+
+export async function readKeychain() {
+  try {
+    const entry = await keychainEntry()
+    return entry.getPassword() ?? null
+  } catch {
+    // No keychain on this machine (headless Linux without a Secret Service),
+    // or no entry: both mean "not configured here".
+    return null
+  }
+}
+
+export async function writeKeychain(connectionString) {
+  const entry = await keychainEntry()
+  entry.setPassword(connectionString)
+}
+
+export async function deleteKeychain() {
+  try {
+    const entry = await keychainEntry()
+    return entry.deletePassword()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The configured grant, parsed, or null when none is configured. A malformed
+ * value is an error with a fixed message; the value itself never appears.
+ *
+ * SHIELDFIVE_GRANT=none means "no vault here": the keychain is not read at all.
+ * That is how one client stays local-only on a machine where another client is
+ * connected, and how the tests avoid depending on the developer's keychain.
+ */
+export async function loadGrantCredential(env = process.env, readStore = readKeychain) {
+  const configured = env.SHIELDFIVE_GRANT?.trim()
+  if (configured === 'none') return null
+  const raw = configured || (await readStore())?.trim() || null
+  if (!raw) return null
+  try {
+    return { ...parseConnectionString(raw), source: env.SHIELDFIVE_GRANT ? 'env' : 'keychain' }
+  } catch (err) {
+    if (err instanceof VaultCryptoError) {
+      throw new Error(
+        'The configured ShieldFive connection string is not valid. Create a new ' +
+          'connection in ShieldFive → Settings → AI assistants, or run ' +
+          '`npx @shieldfive/mcp login` again.',
+      )
+    }
+    throw err
+  }
+}

package/src/vault/namePool.mjs

@@ -0,0 +1,90 @@
+// A fixed pool of name-decryption workers with an in-memory cache keyed by the
+// envelope itself: a renamed item has a new envelope and is decrypted again;
+// an unchanged one never is. The cache dies with the process.
+
+import { availableParallelism } from 'node:os'
+import { Worker } from 'node:worker_threads'
+
+export function createNamePool({ size = Math.max(1, Math.min(8, availableParallelism() - 1)) } = {}) {
+  const workers = []
+  const idle = []
+  const queue = []
+  const pending = new Map()
+  const cache = new Map()
+  let seq = 0
+
+  function startWorker() {
+    const w = new Worker(new URL('./nameWorker.mjs', import.meta.url))
+    w.unref()
+    w.on('message', ({ id, ok, name }) => {
+      const p = pending.get(id)
+      pending.delete(id)
+      p?.resolve(ok ? name : null)
+      idle.push(w)
+      pump()
+    })
+    // A crashed worker must not strand its job: fail that name (it shows as
+    // unavailable), drop the worker and start a replacement.
+    w.on('error', () => {})
+    w.on('exit', () => {
+      for (const [id, job] of pending) {
+        if (job.worker === w) {
+          pending.delete(id)
+          job.resolve(null)
+        }
+      }
+      const i = workers.indexOf(w)
+      if (i >= 0) workers.splice(i, 1)
+      const j = idle.indexOf(w)
+      if (j >= 0) idle.splice(j, 1)
+      if (!closing) {
+        startWorker()
+        pump()
+      }
+    })
+    workers.push(w)
+    idle.push(w)
+  }
+
+  function pump() {
+    while (idle.length && queue.length) {
+      const w = idle.pop()
+      const job = queue.shift()
+      job.worker = w
+      pending.set(job.msg.id, job)
+      w.postMessage(job.msg)
+    }
+  }
+
+  /**
+   * Decrypt one name. `key` is the parent folder key, or with direct: true the
+   * already-derived name key from a grant `name` wrap. Resolves to null when
+   * the envelope does not open — callers show it as unavailable, never guess.
+   */
+  function decrypt({ raw, key, rowId, direct = false }) {
+    const cacheKey = `${rowId}|${raw}`
+    if (cache.has(cacheKey)) return Promise.resolve(cache.get(cacheKey))
+    if (!workers.length) for (let i = 0; i < size; i++) startWorker()
+    return new Promise((resolve) => {
+      const id = ++seq
+      queue.push({
+        msg: { id, raw, key, rowId, direct },
+        resolve: (name) => {
+          if (name !== null) cache.set(cacheKey, name)
+          resolve(name)
+        },
+      })
+      pump()
+    })
+  }
+
+  let closing = false
+  async function close() {
+    closing = true
+    await Promise.all(workers.map((w) => w.terminate()))
+    workers.length = 0
+    idle.length = 0
+  }
+
+  return { decrypt, close, get cached() { return cache.size } }
+}

package/src/vault/nameWorker.mjs

@@ -0,0 +1,23 @@
+// Worker for name decryption. Argon2id costs ~70 ms per name at the web app's
+// "interactive" level, so names are opened on a small pool of threads. Keys
+// arrive over the in-process message channel; nothing touches disk.
+
+import { parentPort } from 'node:worker_threads'
+
+import { decryptName, decryptNameWithKey, parseNameEnvelope } from '@shieldfive/crypto/vault'
+
+parentPort.on('message', async ({ id, raw, key, rowId, direct }) => {
+  try {
+    const envelope = parseNameEnvelope(raw)
+    if (!envelope) {
+      parentPort.postMessage({ id, ok: false })
+      return
+    }
+    const name = direct
+      ? await decryptNameWithKey({ envelope, nameKey: key, rowId })
+      : await decryptName({ envelope, folderKey: key, rowId })
+    parentPort.postMessage({ id, ok: true, name })
+  } catch {
+    parentPort.postMessage({ id, ok: false })
+  }
+})

package/src/vault/session.mjs

@@ -0,0 +1,170 @@
+// One view of the vault as this grant can see it, rebuilt on every tool call.
+//
+// Every call re-fetches the grant, its wraps and the in-scope listing from the
+// server. That is what makes revocation and expiry take effect on the next
+// call: nothing here outlives a request except (a) the grant wrap key derived
+// from the connection string and (b) decrypted names, cached by envelope. Both
+// live only in this process's memory.
+//
+// Keys come from exactly two places: the grant's own wraps (opened with the
+// grant secret) and the folder-key chain below them. Nothing here can derive a
+// key the grant was not given; a folder or file whose key does not open is
+// reported as unreadable, never guessed.
+
+import {
+  deriveGrantWrapKey,
+  unwrapChainKey,
+  unwrapKeyForGrant,
+} from '@shieldfive/crypto/vault'
+
+import { ToolError } from '../roots.mjs'
+
+// C0/C1 controls, line/paragraph separators and bidi overrides/isolates: a
+// decrypted name is attacker-influenced text headed for a model's context.
+const UNSAFE = new RegExp('[\\u0000-\\u001f\\u007f-\\u009f\\u2028-\\u2029\\u202a-\\u202e\\u2066-\\u2069]', 'g')
+
+/** A name as it may be shown to a model: no control or bidi characters, bounded. */
+export function displayName(name) {
+  if (typeof name !== 'string') return null
+  const clean = name.replace(UNSAFE, String.fromCharCode(0xfffd))
+  return clean.length > 255 ? `${clean.slice(0, 255)}…` : clean
+}
+
+export const TRASH_LABEL = 'ShieldFive Bin (this connection)'
+
+export function createVaultSession({ credential, api, names }) {
+  let wrapKey = null
+
+  async function grantWrapKey() {
+    wrapKey ??= await deriveGrantWrapKey(credential.secret, credential.grantId)
+    return wrapKey
+  }
+
+  /** Fetch and open everything this grant can see right now. */
+  async function load(signal, onProgress) {
+    const { grant, keys } = await api.grant(signal)
+    if (grant.id !== credential.grantId) {
+      throw new ToolError(
+        'grant_mismatch',
+        'The server answered for a different connection. Nothing was read.',
+      )
+    }
+    const gk = await grantWrapKey()
+    const wraps = { folder: new Map(), file: new Map(), file_pq: new Map(), name: new Map() }
+    for (const k of keys) {
+      if (!wraps[k.kind]) continue
+      try {
+        wraps[k.kind].set(
+          k.objectId,
+          await unwrapKeyForGrant({
+            grantWrapKey: gk,
+            grantId: grant.id,
+            kind: k.kind,
+            objectId: k.objectId,
+            wrapped: k,
+          }),
+        )
+      } catch {
+        // A wrap that does not open under this grant's key was not made for
+        // this grant, or was tampered with. Ignored, never trusted.
+      }
+    }
+
+    const [folderRows, fileRows] = await Promise.all([api.folders(signal), api.files(signal)])
+
+    // Folder keys: the grant's wraps for its roots, then the chain downwards.
+    const folderKeys = new Map(wraps.folder)
+    let grew = true
+    while (grew) {
+      grew = false
+      for (const f of folderRows) {
+        if (folderKeys.has(f.id) || f.isScopeRoot || !f.parentId || !f.fkWrapped) continue
+        const parentKey = folderKeys.get(f.parentId)
+        if (!parentKey) continue
+        try {
+          folderKeys.set(f.id, await unwrapChainKey(parentKey, { wrapped: f.fkWrapped, iv: f.fkIv }))
+          grew = true
+        } catch {
+          // Unopenable branch; its contents are reported as unreadable.
+        }
+      }
+    }
+
+    // Names, in parallel on the worker pool.
+    const total = folderRows.length + fileRows.length
+    let done = 0
+    // Raw names are what writes re-seal; display names are what the model sees.
+    const nameOf = async (row, parentId, isRoot) => {
+      let name = null
+      if (row.id === grant.trashFolderId) name = TRASH_LABEL
+      else if (isRoot || !parentId) {
+        const k = wraps.name.get(row.id)
+        if (k) name = await names.decrypt({ raw: row.name, key: k, rowId: row.id, direct: true })
+      } else {
+        const k = folderKeys.get(parentId)
+        if (k) name = await names.decrypt({ raw: row.name, key: k, rowId: row.id })
+      }
+      onProgress?.(++done, total)
+      return name
+    }
+    const folderNames = await Promise.all(folderRows.map((f) => nameOf(f, f.parentId, f.isScopeRoot)))
+    const fileNames = await Promise.all(fileRows.map((f) => nameOf(f, f.folderId, false)))
+
+    const folders = new Map()
+    folderRows.forEach((f, i) => {
+      folders.set(f.id, {
+        id: f.id,
+        name: displayName(folderNames[i]),
+        rawName: folderNames[i],
+        parentId: f.isScopeRoot ? null : f.parentId,
+        isScopeRoot: f.isScopeRoot,
+        inTrash: f.inTrash,
+        updatedAt: f.updatedAt,
+        raw: f,
+      })
+    })
+    const pathOf = (folderId) => {
+      const parts = []
+      let cur = folderId ? folders.get(folderId) : null
+      for (let depth = 0; cur && depth < 256; depth++) {
+        parts.unshift(cur.name ?? '[name unavailable]')
+        cur = cur.parentId ? folders.get(cur.parentId) : null
+      }
+      return `/${parts.join('/')}`
+    }
+    for (const f of folders.values()) f.path = pathOf(f.id)
+
+    const files = new Map()
+    fileRows.forEach((f, i) => {
+      const name = displayName(fileNames[i])
+      files.set(f.id, {
+        id: f.id,
+        name,
+        rawName: fileNames[i],
+        path: `${f.folderId ? pathOf(f.folderId) : ''}/${name ?? '[name unavailable]'}`,
+        folderId: f.folderId,
+        size: f.size ?? null,
+        ciphertextSize: f.ciphertextSize ?? null,
+        createdAt: f.createdAt,
+        updatedAt: f.updatedAt,
+        contentType: typeof f.contentType === 'string' ? displayName(f.contentType.slice(0, 100)) : null,
+        cipherVersion: f.cipherVersion,
+        inTrash: f.inTrash,
+        readable: contentKeyAvailable(f, folderKeys, wraps),
+        raw: f,
+      })
+    })
+
+    return { grant, folders, files, folderKeys, wraps }
+  }
+
+  return { load, grantWrapKey }
+}
+
+function contentKeyAvailable(f, folderKeys, wraps) {
+  if (f.folderId) {
+    if (!folderKeys.has(f.folderId)) return false
+    return f.cipherVersion === 3 ? Boolean(f.pqkFkWrapped) : Boolean(f.cskWrapped)
+  }
+  return f.cipherVersion === 3 ? wraps.file_pq.has(f.id) : wraps.file.has(f.id)
+}