Skip to content

Security: mirai-engine/miraidb

Security

docs/security.md

Serving a database to other machines

miraidb-server puts one database on a socket. This page states what it trusts, what it refuses, and what it does not defend against, so a deployment does not have to read the source to find out.

The model

Inside one process, the caller is the host: an embedded store_open may ATTACH any file, load an extension, or export a copy, because the code holding the handle already runs with the process's authority. Nothing on this page applies to that use.

A socket changes who the caller is. A client sends a statement and a token, and the server decides. Three statements reach past the database into the machine that owns it:

Statement What it reaches
ATTACH '<path>' AS name any file path the process can read
LOAD EXTENSION name AT 'host:port' host code (a module in another process) or a network peer
VACUUM INTO '<path>' any file path the process can write

A client chooses the path or the module name, so the server refuses all three unless it was started with --allow-host. The refusal is Permission_Denied with a message that says so, it changes nothing, and the commit sequence does not move. An embedded caller, and any statement that names the database rather than the machine (SELECT, INSERT, DDL), is unaffected.

$ miraidb-server data/db --port=8080        # ATTACH / LOAD EXTENSION / VACUUM INTO refused
$ miraidb-server data/db --port=8080 --allow-host   # every client is trusted
$ miraidb-server data/db --port=8080 --statement-timeout-ms=2000 --budget=10000000

Identity and grants

A request runs under the identity its bearer token authenticated, or under none. Policies are checked against that identity when the database has any: CREATE POLICY and GRANT decide who may read or write what.

Grants are opt-in. A database with no grant rows allows everything to everyone, which is the state of a fresh database: create, read, write and drop. A deployment that must not accept anonymous writes creates its grants first, and then the same statements are refused for a client without the right.

WIRE_AUTH inside a request, and SET identity, change the identity of that connection only; two clients never see each other's.

What is not defended

  • Transport. The socket is plain TCP: no TLS, no HTTP/2, no certificate pinning (backlog D15). Anything that must not be read in transit needs a tunnel in front of this server.
  • Work per statement. --statement-timeout-ms cancels a statement that outlives it (the client gets cancelled and the server keeps serving) and --budget caps the work one statement may spend, refusing it after the work is done rather than during. One statement at a time runs per database, so a slow query delays the others. Neither flag is on by default, and the row quota (max_rows_per_query, --row-quota on the CLI) has no server flag yet.
  • Memory. Expression depth is bounded (100 levels, refused by the parser and the evaluator), but an allocation that fails still ends the process instead of failing the statement (backlog D23). Treat the server as one out-of-memory away from a restart.
  • One writer. The server holds the directory lock; a second server on the same directory is refused with the owner's pid. Readers may open beside it with --read-only.
  • The client registry. max_clients, the outbox budget and the per-frame cap bound how much one client can make the server hold. Beyond those, a client that connects and says nothing holds one thread until it leaves.

Connections

Each accepted socket is served on its own thread. A subscription stays open and receives a delta frame per commit that touches its tables, while other clients connect, read and write. Statements are serialised: the store carries the caller's identity while a statement executes, so two statements at once could see each other's. The delta of a commit is written to the subscriber's socket under that socket's lock, never by two threads at once.

A frame may arrive in pieces and a read may carry several frames; the loop waits for the rest of a frame and drains what it has, rather than closing the connection.

Misuse of a handle

A handle the embedding layer hands out is a pointer, and a host may keep one after it stopped being valid. Every entry point checks it against the layer's set of live handles before dereferencing, so a statement used after finalize, a statement whose connection was closed, and a second finalize all answer a misuse error (MIRAIDB_MISUSE, SQLITE_MISUSE) and do nothing. A bind index past the statement's parameters is SQLITE_RANGE, not a silent growth of the list.

What this does not defend against: a pointer that was never handed out by this layer, or a host that keeps a stale handle long enough for the allocator to hand the same address to a new statement — the old handle then names the new one, as it would in any C library. The guarantee is that a handle this layer forgot answers an error instead of touching freed memory.

There aren't any published security advisories