Ajo Engine
Security model
What the engine enforces, and the residuals it documents.
The engine narrows what an application can do: it loads only a verified artifact, exposes only declared capabilities, and checks authority again at each native operation. It is not a sandbox for hostile code. This page states what it assumes, what it enforces, and the limits it documents rather than hides.
Trust model
The runtime executes trusted, precompiled bytecode produced by a build and deployment pipeline you control. Everything else follows from that assumption.
- Hashes detect mismatches between the manifest and the files. They do not authenticate an untrusted publisher.
- Validation does not make arbitrary QuickJS bytecode safe to run.
- The engine is not a native memory-safety sandbox.
- Container isolation and host policy belong to Ajo Server, and they remain necessary around the engine.
Enforced interfaces
| Interface | What the engine enforces |
|---|---|
| Artifacts | The exact schema and engine pin, declared capabilities, bounded metadata, feature evidence and verified files. Bytecode chunks are hashed again at the read used for execution. A missing required variable or data root stops startup. |
| Filesystem | Declared roots are validated at startup, and every native path-taking operation enforces its own authority. Confinement uses openat2, with a validated realpath fallback. Static serving may also read the App’s own artifact directory, without making it a general filesystem or SQLite root. |
| SQLite | Declared-root checks, no-follow final opens and in-memory temporary storage. An authorizer blocks attaching caller-chosen paths, VACUUM INTO, directory overrides and extension loading. Connections start with synchronous=FULL, although application code can still choose another mode. Backup creates its output exclusively and handles durability. |
| Outbound network | A native destination policy runs after name resolution on every request and every redirect hop. Destinations that are not global are refused. Framing and hop-by-hop request headers belong to the transport. TLS verifies peers against the configured CA store, and deadlines use native timers. |
| HTTP and lifecycle | Bounded request and response handling, connection budgets, handling of descriptor exhaustion and protection against stale events. Server-sent events have their own lifetime. Unhandled rejections end the process, and shutdown is deadline-bounded. |
| IPC | The exact declared FIFO path, a nonblocking no-follow open, a check that the target is a FIFO and one bounded atomic write. There is no process-execution capability. |
| Backup primitives | Streaming age encryption, and SQLite page deltas bound to the hash of the entire parent file. |
The backup primitives are building blocks. Publication, retention, remote verification and recovery policy belong to the backup coordinator that uses them; the primitives alone do not prove that data can be recovered off the host.
Deliberate limits and residuals
These limits are known and documented. They are stated here so that nobody describes the engine as stronger than it is.
| Area | Residual |
|---|---|
| SQLite paths | SQLite receives a validated pathname, not an already-open descriptor. A rename race between validation and open remains possible at a leaf the App controls. No custom SQLite VFS is implemented, so this path is not race-free and not equivalent to the descriptor-based filesystem path. |
| Ed25519 keys | Verification rejects invalid encodings and signatures, but public-key validation does not perform a full curve-membership check. Some unusable keys can be registered; they then fail verification. |
| Language profile | The parserless profile is not all of ECMAScript plus browser APIs. Dynamic code is rejected. An uncertain feature scan is not evidence of absence. |
| Web subsets | Intl and fetch are bounded subsets. Neither is a claim of standards compliance. |
| Test networking | The test suite contains test-only networking arrangements. They are not a production policy and must not become an App-controlled bypass. |
The release packages carry checksums and a provenance record of their build inputs. These local records do not authenticate a publisher or prove reproducible builds; a reviewed provenance contract is planned work.
Tests are evidence, not certification
The engine’s verification gates run regression suites, including manifest tampering, HTTP, bindings and lifecycle fixtures, and test262, both with the full parser and as an exact admitted set sealed and run by the parserless profile. Sanitizer runs, consumer acceptance with Ajo Kit and Ajo Server artifacts, and performance measurements are separate checks, recorded when they apply. Each check proves its own scope, and some sanitizer findings in shutdown paths remain open in the roadmap.
Neither a historical audit nor a green test run is a permanent security certification. Changes are reviewed by tracing hostile input to its final native operation, reproducing a finding before fixing it and recording any residual explicitly.
- The artifactWhat loading verifies, and what hashes do not prove.
- Runtime surfaceModules, globals and their bounds.
- The hostThe container and privilege model around the engine.
Source of truth: ajo-js docs/security.md