@shieldfive/mcp 0.2.0 → 0.3.0

package/src/vault/api.mjs

@@ -0,0 +1,190 @@
+// The grant-authenticated ShieldFive API (/api/agent/v1).
+//
+// Every call goes to the server: nothing here caches a response, so an expired
+// or revoked grant fails on the very next tool call (the server re-checks it on
+// every request). Scope checks in this process are a courtesy that produces a
+// clearer error; the server is the boundary.
+
+import { grantBearerToken } from '@shieldfive/crypto/vault'
+
+import { ToolError } from '../roots.mjs'
+
+export const DEFAULT_API_URL = 'https://shieldfive.com'
+const TIMEOUT_MS = 30_000
+
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(resolve, ms)
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(t)
+        reject(signal.reason)
+      },
+      { once: true },
+    )
+  })
+}
+
+export function createVaultApi({ credential, baseUrl = DEFAULT_API_URL, fetchImpl = fetch }) {
+  const bearer = grantBearerToken(credential)
+  const origin = new URL(baseUrl)
+  if (origin.protocol !== 'https:' && !['localhost', '127.0.0.1'].includes(origin.hostname)) {
+    throw new Error('SHIELDFIVE_API_URL must be https (or localhost for development).')
+  }
+
+  // A rate-limited request waits and retries (at most 3 times, honouring
+  // Retry-After and cancellation). A quota refusal does not: it will not clear
+  // by waiting, so it surfaces at once.
+  async function call(method, path, body, signal) {
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return await once(method, path, body, signal)
+      } catch (err) {
+        if (err?.code !== 'rate_limited' || attempt >= 3 || signal?.aborted) throw err
+        await sleep(Math.min(60_000, (err.retryAfterSeconds ?? 15 * (attempt + 1)) * 1000), signal)
+      }
+    }
+  }
+
+  async function once(method, path, body, signal) {
+    const url = new URL(`/api/agent/v1${path}`, origin)
+    const timeout = AbortSignal.timeout(TIMEOUT_MS)
+    let res
+    try {
+      res = await fetchImpl(url, {
+        method,
+        headers: {
+          authorization: `Bearer ${bearer}`,
+          ...(body ? { 'content-type': 'application/json' } : {}),
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+        cache: 'no-store',
+      })
+    } catch (err) {
+      if (signal?.aborted) throw err
+      throw new ToolError('network_error', 'Could not reach ShieldFive. Nothing was changed.')
+    }
+    if (res.ok) return res.json().catch(() => ({}))
+    return failure(res)
+  }
+
+  async function failure(res) {
+    const data = await res.json().catch(() => ({}))
+    // The server's code is echoed to the model, so only a plain identifier passes.
+    const code =
+      typeof data.code === 'string' && /^[a-z_]{1,40}$/.test(data.code) ? data.code : `http_${res.status}`
+    if (res.status === 401) {
+      throw new ToolError(
+        'grant_invalid',
+        'This ShieldFive connection is expired or has been revoked. Create a new one in ' +
+          'ShieldFive → Settings → AI assistants and run `npx @shieldfive/mcp login`.',
+      )
+    }
+    if (res.status === 403 && code === 'missing_scope') {
+      throw new ToolError(
+        'missing_scope',
+        `This connection does not include the "${data.scope === 'read' ? 'read' : 'organize'}" permission. ` +
+          'The vault owner can create a connection with it in Settings → AI assistants.',
+      )
+    }
+    if (res.status === 404) {
+      throw new ToolError('not_found', 'That item is not in this connection’s scope, or no longer exists.')
+    }
+    if (res.status === 409) {
+      throw new ToolError('conflict', 'That item changed since it was listed. List again and retry.')
+    }
+    if (res.status === 429 && (code === 'transfer_limit' || code === 'egress_cap' || data.reason === 'egress_cap')) {
+      throw new ToolError(
+        'quota_exceeded',
+        'The vault owner’s download quota is used up for now (daily egress or monthly transfer). ' +
+          'Downloads resume when it resets; listing and organizing still work.',
+      )
+    }
+    if (res.status === 429) {
+      const err = new ToolError('rate_limited', 'ShieldFive is rate-limiting this connection. Wait a minute and retry.')
+      const retry = Number(res.headers.get('retry-after'))
+      if (Number.isFinite(retry) && retry > 0) err.retryAfterSeconds = retry
+      throw err
+    }
+    throw new ToolError(code, `ShieldFive refused the request (${res.status}). Nothing was changed.`)
+  }
+
+  // A download that fails is reported through the same error mapping as every
+  // other call (401 revoked, 429 quota, …); a success is the byte stream.
+  async function rawDownload(id, signal) {
+    for (let attempt = 0; ; attempt++) {
+      const url = new URL(`/api/agent/v1/files/${id}/download`, origin)
+      const res = await fetchImpl(url, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${bearer}` },
+        signal,
+        cache: 'no-store',
+      }).catch((err) => {
+        if (signal?.aborted) throw err
+        throw new ToolError('network_error', 'Could not reach ShieldFive.')
+      })
+      if (res.ok && res.body) return res
+      try {
+        await failure(res)
+      } catch (err) {
+        if (err?.code !== 'rate_limited' || attempt >= 3 || signal?.aborted) throw err
+        await sleep(Math.min(60_000, (err.retryAfterSeconds ?? 15 * (attempt + 1)) * 1000), signal)
+      }
+    }
+  }
+
+  async function listAll(path, key, signal) {
+    const out = []
+    let after = null
+    for (let page = 0; page < 1000; page++) {
+      const q = `?limit=1000${after ? `&after=${after}` : ''}`
+      const data = await call('GET', `${path}${q}`, undefined, signal)
+      out.push(...(data[key] ?? []))
+      if (!data.next) return out
+      after = data.next
+    }
+    throw new ToolError('too_large', 'The listing did not finish within 1,000 pages.')
+  }
+
+  return {
+    grant: (signal) => call('GET', '/grant', undefined, signal),
+    folders: (signal) => listAll('/folders', 'folders', signal),
+    files: (signal) => listAll('/files', 'files', signal),
+    stats: (signal) => call('GET', '/stats', undefined, signal),
+    /**
+     * The file's ciphertext, streamed through ShieldFive (no storage URL is ever
+     * handed out). Refused past `maxBytes` without buffering the rest.
+     */
+    async download(id, maxBytes, signal) {
+      const res = await rawDownload(id, signal)
+      const len = Number(res.headers.get('content-length') ?? 0)
+      if (len && len > maxBytes) throw new ToolError('too_large', 'File exceeds the size cap.')
+      const reader = res.body.getReader()
+      const parts = []
+      let total = 0
+      for (;;) {
+        const { done, value } = await reader.read()
+        if (done) break
+        total += value.length
+        if (total > maxBytes) {
+          await reader.cancel()
+          throw new ToolError('too_large', 'File exceeds the size cap.')
+        }
+        parts.push(value)
+      }
+      const out = new Uint8Array(total)
+      let off = 0
+      for (const p of parts) {
+        out.set(p, off)
+        off += p.length
+      }
+      return out
+    },
+    patchFile: (id, body, signal) => call('PATCH', `/files/${id}`, body, signal),
+    patchFolder: (id, body, signal) => call('PATCH', `/folders/${id}`, body, signal),
+    createFolder: (body, signal) => call('POST', '/folders', body, signal),
+    trash: (items, signal) => call('POST', '/trash', { items }, signal),
+  }
+}

package/src/vault/cli.mjs

@@ -0,0 +1,115 @@
+// `npx @shieldfive/mcp login | logout | status`
+//
+// login reads the connection string without echoing it, checks it against the
+// server (so a typo or a revoked grant is caught now, not in the middle of a
+// conversation), and stores it in the OS keychain. Nothing is written to a
+// file and the value is never printed.
+
+import { parseConnectionString } from '@shieldfive/crypto/vault'
+
+import { createVaultApi, DEFAULT_API_URL } from './api.mjs'
+import { deleteKeychain, loadGrantCredential, writeKeychain } from './credential.mjs'
+
+const out = (s) => process.stderr.write(`${s}\n`)
+
+function readHidden(prompt) {
+  return new Promise((resolve, reject) => {
+    const stdin = process.stdin
+    if (!stdin.isTTY) {
+      let data = ''
+      stdin.setEncoding('utf8')
+      stdin.on('data', (c) => (data += c))
+      stdin.on('end', () => resolve(data.trim()))
+      stdin.on('error', reject)
+      return
+    }
+    process.stderr.write(prompt)
+    let value = ''
+    stdin.setRawMode(true)
+    stdin.resume()
+    stdin.setEncoding('utf8')
+    const onData = (chunk) => {
+      for (const ch of chunk) {
+        const code = ch.charCodeAt(0)
+        if (ch === '\r' || ch === '\n') {
+          stdin.setRawMode(false)
+          stdin.pause()
+          stdin.off('data', onData)
+          process.stderr.write('\n')
+          resolve(value.trim())
+          return
+        }
+        if (code === 3) {
+          stdin.setRawMode(false)
+          process.stderr.write('\n')
+          reject(new Error('cancelled'))
+          return
+        }
+        if (code === 127 || code === 8) value = value.slice(0, -1)
+        else if (code >= 32) value += ch
+      }
+    }
+    stdin.on('data', onData)
+  })
+}
+
+async function describe(credential, env) {
+  const api = createVaultApi({ credential, baseUrl: env.SHIELDFIVE_API_URL || DEFAULT_API_URL })
+  const { grant } = await api.grant()
+  const scope = grant.scopeAll ? 'whole vault' : `${grant.scopeFolderIds.length} folder(s)`
+  return `connection ${grant.id.slice(0, 8)}…: ${grant.scopes.join(' + ')}, ${scope}, expires ${grant.expiresAt}`
+}
+
+export async function runCli(command, env = process.env) {
+  if (command === 'login') {
+    const raw = await readHidden('Paste the ShieldFive connection string (input hidden): ')
+    let credential
+    try {
+      credential = parseConnectionString(raw)
+    } catch {
+      out('That is not a ShieldFive connection string. Copy it again from Settings → AI assistants.')
+      return 1
+    }
+    try {
+      out(`Checking with ShieldFive… ${await describe(credential, env)}`)
+    } catch (err) {
+      out(`ShieldFive did not accept it: ${err?.message ?? 'unknown error'}`)
+      return 1
+    }
+    try {
+      await writeKeychain(raw)
+    } catch {
+      out(
+        'No system keychain is available here. Set SHIELDFIVE_GRANT in the MCP server’s ' +
+          'environment instead (anything that can read that environment can read the connection).',
+      )
+      return 1
+    }
+    out('Saved to the system keychain. Restart your AI assistant to pick it up.')
+    return 0
+  }
+  if (command === 'logout') {
+    const removed = await deleteKeychain()
+    out(removed ? 'Removed the connection from the system keychain.' : 'No connection was stored in the keychain.')
+    out('To cut off access everywhere, revoke the connection in ShieldFive → Settings → AI assistants.')
+    return 0
+  }
+  if (command === 'status') {
+    const credential = await loadGrantCredential(env).catch((e) => {
+      out(e.message)
+      return null
+    })
+    if (!credential) {
+      out('No ShieldFive connection configured. Vault tools are off; local tools work as before.')
+      return 0
+    }
+    try {
+      out(`Configured from ${credential.source}: ${await describe(credential, env)}`)
+    } catch (err) {
+      out(`Configured from ${credential.source}, but ShieldFive refused it: ${err?.message ?? 'unknown error'}`)
+      return 1
+    }
+    return 0
+  }
+  return null
+}

package/src/vault/content.mjs

@@ -0,0 +1,89 @@
+// Opening a file's contents in memory. Nothing here writes plaintext, keys or
+// ciphertext to disk; buffers are dropped when the call returns.
+
+import { createHash } from 'node:crypto'
+
+import { base64ToBytes } from '@shieldfive/crypto'
+import { decryptToBytes as decryptV1 } from '@shieldfive/crypto/aes-gcm-v1'
+import { decryptV0 } from '@shieldfive/crypto/legacy-v0'
+import { decryptStreamPqHybridV1 } from '@shieldfive/crypto/streams/pq-hybrid-v1'
+import { unwrapChainKey } from '@shieldfive/crypto/vault'
+
+import { ToolError } from '../roots.mjs'
+
+/**
+ * The key that opens a file's content, from the keys this grant holds:
+ *   cipher_version 3 (suite 0x03): the combined key K, from the aux wrap under
+ *     the parent folder key, or the grant's file_pq wrap for a root-level file;
+ *   cipher_version 1/2: the content key under the parent folder key, or the
+ *     grant's file wrap for a root-level file.
+ */
+export async function contentKey(file, view) {
+  const row = file.raw
+  if (row.folderId) {
+    const fk = view.folderKeys.get(row.folderId)
+    if (!fk) return null
+    if (row.cipherVersion === 3) {
+      if (!row.pqkFkWrapped) return null
+      return unwrapChainKey(fk, { wrapped: row.pqkFkWrapped, iv: row.pqkFkIv })
+    }
+    if (!row.cskWrapped) return null
+    return unwrapChainKey(fk, { wrapped: row.cskWrapped, iv: row.cskIv })
+  }
+  return (row.cipherVersion === 3 ? view.wraps.file_pq : view.wraps.file).get(row.id) ?? null
+}
+
+/** The key csk_wrapped holds (classical envelope key for v3) — what a move re-wraps. */
+export async function classicalKey(file, view) {
+  const row = file.raw
+  if (!row.folderId) return view.wraps.file.get(row.id) ?? null
+  const fk = view.folderKeys.get(row.folderId)
+  if (!fk || !row.cskWrapped) return null
+  return unwrapChainKey(fk, { wrapped: row.cskWrapped, iv: row.cskIv })
+}
+
+export async function decryptContent(file, view, api, { maxBytes, signal }) {
+  const key = await contentKey(file, view)
+  if (!key) {
+    throw new ToolError(
+      'pending_owner_unlock',
+      'This file cannot be opened by this connection yet. Post-quantum files become ' +
+        'readable after the owner next opens ShieldFive on a device with their full keys.',
+    )
+  }
+  // Ciphertext is a little larger than plaintext (header + per-chunk tags).
+  const ciphertext = await api.download(file.id, maxBytes + 1024 * 1024, signal)
+  const blob = new Blob([ciphertext])
+  const row = file.raw
+  let out
+  try {
+    if (row.cipherVersion === 3) {
+      const { plaintext } = decryptStreamPqHybridV1(blob.stream(), { combinedKey: key })
+      out = new Uint8Array(await new Response(plaintext).arrayBuffer())
+    } else if (row.cipherVersion === 2) {
+      out = await decryptV1({ blob, contentKey: key })
+    } else if (row.cipherVersion === 1) {
+      const plain = await decryptV0({
+        blob,
+        contentKey: key,
+        noncePrefix: base64ToBytes(row.cipherNoncePrefix),
+        chunkSize: row.cipherChunkSize,
+      })
+      out = new Uint8Array(await plain.arrayBuffer())
+    }
+  } catch {
+    throw new ToolError(
+      'decrypt_failed',
+      'The file did not decrypt. It may be damaged or tampered with; nothing was changed.',
+    )
+  }
+  if (!out) {
+    throw new ToolError('unsupported', `Unsupported file format (cipher_version ${row.cipherVersion}).`)
+  }
+  if (out.length > maxBytes) throw new ToolError('too_large', 'File exceeds the size cap.')
+  return out
+}
+
+export function sha256Hex(bytes) {
+  return createHash('sha256').update(bytes).digest('hex')
+}

package/src/vault/credential.mjs

@@ -0,0 +1,69 @@
+// 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.
+ */
+export async function loadGrantCredential(env = process.env, readStore = readKeychain) {
+  const raw = env.SHIELDFIVE_GRANT?.trim() || (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 and 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 })
+  }
+})