mcpdrives
Documentation menu

Security model

Security

mcpdrives holds keys to your storage and decides what agents may do with them. This page describes how, and the limits you should know about.

Storage keys

  • Each secret is encrypted with AES-256-GCM under a fresh data key. The data key is encrypted with a key derived with HKDF-SHA-256 from the service's master secret.
  • The encryption is bound to your account and to that connection, so a stored secret cannot be moved to another record or account.
  • Secrets are decrypted only inside your account's own storage object, held in memory for the request that needs them, and never returned by any API. Agents never receive them.
  • A key is checked against its bucket before it is saved. One-time links let a person, or a script with environment variables, submit a key without it passing through a conversation with a model.

Agent access

  • Every call is checked against the folder it touches. Folders outside a connection are invisible, and mount points and the drive's root cannot be deleted.
  • Tokens are 256-bit random values, stored only as SHA-256 hashes, and bound to one drive and one connection.
  • Access tokens expire after 60 minutes by default. Refresh tokens rotate on every use; reusing an old refresh token revokes the whole connection, and so does reusing an authorization code.
  • Revoking a connection cancels its background jobs. Revoking a share link revokes every connection it approved. Pausing a drive refuses all of its agents at once.

Sign-in for agents

  • OAuth 2.1 with PKCE using S256 only. Each drive is its own protected resource, and a token request must name the drive.
  • Return addresses must match what the client registered exactly. Local clients on 127.0.0.1 may use any port, as RFC 8252 allows. An unregistered address gets an error page and never a redirect.
  • Authorization responses include the iss parameter, so a client can check which server answered.
  • Client ID Metadata Documents are fetched with a 3-second deadline, no redirects and a 5 KB size limit, must repeat their own client ID, and are cached for at most 5 minutes.
  • The approval form carries a token bound to the request and to the person approving it, and the page allows form submissions only to mcpdrives and the client's return address.

Owner sessions

  • Sign-in codes have six digits, are stored as HMACs, expire after 10 minutes and allow six attempts. Requests are rate limited per address, per network and in total.
  • Session and form-protection cookies use the __Host- prefix, Secure and SameSite. Every change needs a matching protection header, a same-site Origin header and a valid session.
  • During early access, only addresses on the access list can create an account.

Shell and Code Mode

Shell commands and Code Mode programs are code an agent wrote, so they run in separate isolates created for the purpose, with outbound network turned off and no bindings to the service's data. Their only capability is a connection back to the drive, which applies the caller's permissions to every call. A command line is limited to 30 seconds, and a program to 45 seconds and 1,000 drive calls.

Storage endpoints

The service accepts only https storage endpoints on public hosts. Literal private and loopback addresses are refused before any request, and the runtime cannot reach private networks.

Pages

The website and the dashboard load only their own scripts and stylesheets under a content security policy with no inline code, and they cannot be framed by other sites. Neither uses analytics, advertising or third-party scripts.

Logs

The activity log records operations, paths, byte counts and the names of connections. It never stores file contents, shell commands, programs, prompts or secrets. Unexpected errors are logged by name, message and stack trace, without request bodies.

Known limits

  • Signed download and upload links work for whoever holds them until they expire, 15 minutes by default. Revoking a connection does not cancel links it already received.
  • Providers other than Cloudflare R2, Amazon S3 and MinIO do not enforce create-only writes in the same request, so mcpdrives checks first and then writes.
  • One master secret protects every stored key. Rotating it means re-encrypting every connection, which is not automated yet.
  • A key you give mcpdrives can do whatever its own policy allows. mcpdrives enforces each mount's access, and a narrow key adds a second limit.