@shieldfive/mcp 0.2.0 → 0.4.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. Call vault_connect to ' +
+          'connect again (it opens ShieldFive in the browser to authorize).',
+      )
+    }
+    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,150 @@
+// `npx @shieldfive/mcp login [--paste] | logout | status`
+//
+// login opens ShieldFive in the browser, where the owner chooses the scope and
+// clicks Authorize; the connection string comes back to this process over
+// 127.0.0.1 (connect.mjs). `login --paste` reads it from the terminal instead,
+// without echoing it. Either way it is checked against the server (so a
+// revoked grant is caught now, not in the middle of a conversation) and stored
+// 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 { openBrowser, startConnectFlow } from './connect.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)
+  })
+}
+
+export function describeGrant(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}`
+}
+
+async function describe(credential, env) {
+  const api = createVaultApi({ credential, baseUrl: env.SHIELDFIVE_API_URL || DEFAULT_API_URL })
+  const { grant } = await api.grant()
+  return describeGrant(grant)
+}
+
+async function authorizeInBrowser(env, open) {
+  const flow = await startConnectFlow({ baseUrl: env.SHIELDFIVE_API_URL || DEFAULT_API_URL, client: 'other' })
+  const opened = await open(flow.url)
+  out(
+    opened
+      ? 'Opened ShieldFive in your browser. Choose what the assistant may reach and click Authorize.'
+      : 'Open this link in your browser, choose what the assistant may reach and click Authorize:',
+  )
+  out(`  ${flow.url}`)
+  out('Waiting (up to 10 minutes; Ctrl+C to stop)…')
+  return flow.result
+}
+
+export async function runCli(command, env = process.env, args = [], { open = openBrowser } = {}) {
+  if (command === 'login') {
+    let raw
+    if (args.includes('--paste')) {
+      raw = await readHidden('Paste the ShieldFive connection string (input hidden): ')
+    } else {
+      try {
+        raw = await authorizeInBrowser(env, open)
+      } catch (err) {
+        out(
+          err?.code === 'cancelled'
+            ? 'The request was denied in ShieldFive. Nothing was connected.'
+            : 'Nobody authorized the connection in time. Run the command again, or use --paste.',
+        )
+        return 1
+      }
+    }
+    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/connect.mjs

@@ -0,0 +1,227 @@
+// Browser authorization: the connection string arrives without anyone copying it.
+//
+// This process listens on a random port on 127.0.0.1 and opens
+//
+//   https://shieldfive.com/files?settings=agents&connect=<state>&port=<port>&client=<hint>
+//
+// The owner signs in, unlocks, chooses the scope and clicks Authorize. The page
+// creates the grant in the browser as it always does, then submits a form to
+// http://127.0.0.1:<port>/callback carrying the state and the connection
+// string. The page builds that address itself from the port; it accepts no
+// callback URL, so a link someone else crafted can only deliver to the machine
+// the browser runs on.
+//
+// What this listener accepts, and nothing else: one POST to /callback, Host
+// exactly 127.0.0.1:<port> (defeats DNS rebinding), no Origin other than
+// ShieldFive's (a POST from any other site is refused before its body is read),
+// and a state that matches in constant time. The first valid delivery closes
+// the listener.
+
+import { randomBytes, timingSafeEqual } from 'node:crypto'
+import { spawn } from 'node:child_process'
+import { createServer } from 'node:http'
+
+import { parseConnectionString } from '@shieldfive/crypto/vault'
+
+const MAX_BODY = 16 * 1024
+export const CONNECT_TIMEOUT_MS = 10 * 60 * 1000
+
+export const CLIENT_HINTS = ['claude-desktop', 'claude-code', 'cursor', 'chatgpt', 'local', 'other']
+
+/** Map an MCP clientInfo.name to the hint the settings page understands. */
+export function clientHintFor(name) {
+  const n = String(name ?? '').toLowerCase()
+  if (n.includes('claude-code') || n.includes('claude code')) return 'claude-code'
+  if (n.includes('claude')) return 'claude-desktop'
+  if (n.includes('cursor')) return 'cursor'
+  if (n.includes('chatgpt') || n.includes('openai')) return 'chatgpt'
+  return 'other'
+}
+
+/** Open a URL in the default browser without a shell. Resolves false on failure. */
+export function openBrowser(url, platform = process.platform, spawnImpl = spawn) {
+  const [cmd, args] =
+    platform === 'darwin'
+      ? ['open', [url]]
+      : platform === 'win32'
+        ? ['rundll32', ['url.dll,FileProtocolHandler', url]]
+        : ['xdg-open', [url]]
+  return new Promise((resolve) => {
+    try {
+      const child = spawnImpl(cmd, args, { stdio: 'ignore', detached: true })
+      child.on('error', () => resolve(false))
+      child.on('spawn', () => {
+        child.unref()
+        resolve(true)
+      })
+    } catch {
+      resolve(false)
+    }
+  })
+}
+
+const PAGE_CSP = "default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'"
+
+function page(title, body) {
+  return (
+    '<!doctype html><html lang="en"><head><meta charset="utf-8">' +
+    '<meta name="viewport" content="width=device-width,initial-scale=1">' +
+    `<title>${title}</title><style>` +
+    'body{font:16px/1.5 system-ui,sans-serif;margin:0;display:grid;place-items:center;min-height:100vh;' +
+    'background:#f7f7f8;color:#111}main{max-width:32rem;padding:2rem}h1{font-size:1.4rem;margin:0 0 .5rem}' +
+    '@media (prefers-color-scheme:dark){body{background:#111;color:#eee}}' +
+    `</style></head><body><main><h1>${title}</h1><p>${body}</p></main></body></html>`
+  )
+}
+
+function send(res, status, title, body, onSent) {
+  res.writeHead(status, {
+    'content-type': 'text/html; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-security-policy': PAGE_CSP,
+    'referrer-policy': 'no-referrer',
+    'x-content-type-options': 'nosniff',
+  })
+  res.end(page(title, body), onSent)
+}
+
+function sameSecret(a, b) {
+  const x = Buffer.from(String(a))
+  const y = Buffer.from(String(b))
+  return x.length === y.length && timingSafeEqual(x, y)
+}
+
+export class ConnectError extends Error {
+  constructor(code, message) {
+    super(message)
+    this.name = 'ConnectError'
+    this.code = code
+  }
+}
+
+/**
+ * Start listening and build the authorization URL. `result` resolves with the
+ * raw connection string, or rejects with a ConnectError (cancelled, timeout).
+ */
+export async function startConnectFlow({
+  baseUrl,
+  client = 'other',
+  timeoutMs = CONNECT_TIMEOUT_MS,
+  onDelivered,
+} = {}) {
+  const origin = new URL(baseUrl).origin
+  const state = randomBytes(32).toString('base64url')
+  let settle
+  const result = new Promise((resolve, reject) => {
+    settle = { resolve, reject }
+  })
+  // A flow can end (timeout) with nobody awaiting it; that is not a crash.
+  result.catch(() => {})
+  let done = false
+  let port = 0
+
+  const server = createServer((req, res) => {
+    if (req.headers.host !== `127.0.0.1:${port}`) {
+      send(res, 400, 'Not here', 'This address only accepts ShieldFive connections.')
+      return
+    }
+    const path = new URL(req.url ?? '/', `http://127.0.0.1:${port}`).pathname
+    if (path !== '/callback' || req.method !== 'POST') {
+      send(res, 404, 'Not found', 'Return to your assistant.')
+      return
+    }
+    // Browsers send ShieldFive's origin here; a few send "null" for a
+    // navigation to plain http. Any OTHER site's origin is refused outright;
+    // the 256-bit state is what actually authenticates the delivery.
+    const from = req.headers.origin
+    if (from !== undefined && from !== origin && from !== 'null') {
+      send(res, 403, 'Refused', 'This connection did not come from ShieldFive.')
+      return
+    }
+    if (done) {
+      send(res, 409, 'Already connected', 'This request has already been used. Return to your assistant.')
+      return
+    }
+    let size = 0
+    const chunks = []
+    req.on('data', (c) => {
+      size += c.length
+      if (size > MAX_BODY) req.destroy()
+      else chunks.push(c)
+    })
+    req.on('end', () => {
+      const form = new URLSearchParams(Buffer.concat(chunks).toString('utf8'))
+      if (!sameSecret(form.get('state') ?? '', state)) {
+        send(res, 403, 'Refused', 'This connection was meant for a different request.')
+        return
+      }
+      if (form.get('error')) {
+        done = true
+        send(res, 200, 'Request denied', 'No connection was created. You can close this tab.', finish)
+        settle.reject(new ConnectError('cancelled', 'The owner denied the connection request.'))
+        return
+      }
+      const raw = (form.get('connection_string') ?? '').trim()
+      try {
+        parseConnectionString(raw)
+      } catch {
+        send(res, 400, 'Something went wrong', 'The connection could not be read. Try connecting again.')
+        return
+      }
+      done = true
+      send(
+        res,
+        200,
+        'Connected',
+        'Your assistant can now reach the folders you chose. You can close this tab and go back to it. ' +
+          'Revoke the connection any time in ShieldFive → Settings → AI assistants.',
+        finish,
+      )
+      onDelivered?.()
+      settle.resolve(raw)
+    })
+  })
+  server.headersTimeout = 10_000
+  server.requestTimeout = 15_000
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', resolve)
+  })
+  port = server.address().port
+
+  const timer = setTimeout(() => {
+    if (done) return
+    done = true
+    finish()
+    settle.reject(new ConnectError('timeout', 'Nobody authorized the connection in time.'))
+  }, timeoutMs)
+  timer.unref?.()
+
+  function finish() {
+    clearTimeout(timer)
+    server.close()
+    server.closeAllConnections?.()
+  }
+
+  // Settings is an overlay on /files opened with ?settings=<section>; there is
+  // no page at /files/settings/agents (opening one is how this first shipped,
+  // and it 404s).
+  const url = new URL('/files', origin)
+  url.searchParams.set('settings', 'agents')
+  url.searchParams.set('connect', state)
+  url.searchParams.set('port', String(port))
+  url.searchParams.set('client', CLIENT_HINTS.includes(client) ? client : 'other')
+
+  return {
+    url: url.toString(),
+    port,
+    result,
+    cancel() {
+      if (done) return
+      done = true
+      finish()
+      settle.reject(new ConnectError('cancelled', 'Connection request cancelled.'))
+    },
+  }
+}

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')
+}