Extension security
Aperture runs code written by other people next to your camera footage, so extensions are confined twice: by Deno’s permission system, and by the operating system around the Deno process. UI panels are confined by the browser. This page describes each layer exactly, lists what an extension can and cannot reach, states plainly what the sandbox does not stop, and lists the tests that check it. Read it before you grant network access or install an extension nobody has reviewed.
The layers at a glance
Section titled “The layers at a glance”| Layer | Confines | Enforced by |
|---|---|---|
| Manifest and consent | What the extension is allowed to ask for | internal/ext/manifest.go, the install handlers |
| API scopes and camera grants | What its token, or its panel, can do through the API | The same per-route checks as every API token, plus a rule that only the extension’s own token or a signed-in session may use the routes that act as the extension (internal/api/access.go) |
| Deno permissions | What backend code can touch: files, network, environment, subprocesses | Deno, with flags built in internal/ext/spec.go |
| Process confinement | What an escape from Deno could reach | A per-extension user, resource limits and the systemd unit (internal/ext/supervisor.go) |
| Browser sandbox | What panel code can touch | The iframe sandbox and a strict content security policy (internal/api/ext_static.go) |
Layer one: Deno permissions
Section titled “Layer one: Deno permissions”BuildSpec in internal/ext/spec.go is the only place where a manifest becomes Deno flags. Everything is denied unless a flag allows it. A backend is started as:
deno run --v8-flags=--max-old-space-size=256 \ --no-prompt \ --deny-run --deny-ffi --deny-sys --deny-import \ --allow-env=APERTURE_TOKEN,APERTURE_API,APERTURE_EXT_ID \ --allow-read=<ext dir>,<sdk dir>,<ext dir>/.import-map.json \ --allow-write=<ext dir> \ --import-map=<ext dir>/.import-map.json \ --allow-net=<declared hosts>,<api host> \ <ext dir>/<backend.entry><ext dir> is the extension’s own folder, ext/<id> in the data directory (/var/lib/aperture/data/ext/<id> on a standard install). <sdk dir> is the folder holding the SDK, /usr/lib/aperture/sdk.
| Flag | Effect |
|---|---|
--no-prompt |
A missing permission fails at once instead of waiting for an answer nobody will give |
--deny-run |
No subprocesses |
--deny-ffi |
No native libraries |
--deny-sys |
No system information such as hostname, network interfaces or OS release |
--deny-import |
No modules loaded from URLs; only local files through the import map |
--allow-env=… |
Only these three variables can be read; see below |
--allow-read=… |
Its own folder, the SDK folder and the import map, nothing else |
--allow-write=… |
Its own folder only |
--import-map=… |
Resolves @aperture/sdk to the local SDK file |
--allow-net=… |
The hosts in its network permission, resolved from settings at start, plus the Aperture API host. With neither, --deny-net |
--max-old-space-size=256 |
The JavaScript heap is capped at 256 MB, so a leak ends in a clean out-of-memory exit of that one process |
The environment exception
Section titled “The environment exception”The original design denied environment access entirely. That cannot work: the SDK reads its token and API address with Deno.env.get, which throws NotCapable under --deny-env, so no backend could authenticate. Instead, --allow-env names exactly APERTURE_TOKEN, APERTURE_API and APERTURE_EXT_ID, and the process’s environment is replaced wholesale with those three plus HOME, DENO_DIR and NO_COLOR. Nothing from Aperture’s own environment reaches the extension. Some comments and the flag test in the repository still describe the allow-list as the first two names; the flag in spec.go has all three.
The SDK folder
Section titled “The SDK folder”--allow-read covers the whole folder that holds the SDK, not only the SDK file. aperture-harden, which runs before every start of the service, refuses to start Aperture if that folder holds anything besides the SDK, so nothing else can become readable to every extension by being placed there.
Layer two: process confinement
Section titled “Layer two: process confinement”If code ever escaped Deno’s permission checks, it would land in a process confined like this:
- Its own user.
nvrdruns as root only so it can drop privileges. Each backend runs under its own user and group id, starting at 65600 and assigned at install. The extension’s folder belongs to that user with mode0700, so extensions cannot read each other’s files. - Aperture’s files closed off.
aperture-hardensets the data directory and itsext/folder to0711(passable but not listable) andsecrets.json,cli.token,aperture.dband its journal files, andgo2rtc.yamlto0600, on every start. - Resource limits. Deno is launched through
nvrd __ext-spawn, which, already running as the extension’s user, sets at most 256 open files (RLIMIT_NOFILE) and 64 processes and threads for that user (RLIMIT_NPROC), and raises the process’soom_score_adjto 800 so the kernel kills it beforenvrdor a recorder when memory runs out. Then it replaces itself with Deno. - Tied to Aperture. Each backend runs in its own process group with a parent-death signal of SIGKILL, so it dies if
nvrddies. A normal stop is SIGTERM to the group and SIGKILL 5 seconds later. - The service unit. Backends run inside
aperture.service(deploy/systemd/aperture.service) and share its limits withnvrdand the recorders:MemoryHigh,MemoryMax,TasksMaxandCPUQuota.OOMPolicy=continuekeeps the service running when the kernel kills an extension. The unit also setsNoNewPrivileges=yes(an escaped process cannot gain privileges through set-user-id programs),ProtectSystem=strictwith only/var/lib/aperturewritable,ProtectHome,PrivateTmp,ProtectKernelTunables,ProtectKernelModules,ProtectKernelLogs,ProtectControlGroups,RestrictSUIDSGID,RestrictNamespaces,LockPersonality, and limits sockets to Unix, IPv4, IPv6 and netlink.
The unit file explains what it deliberately leaves out and why: a non-root User= (Aperture must drop privileges for each extension), PrivateUsers= (it would break the per-extension users), MemoryDenyWriteExecute= (Deno’s compiler needs it), and a system-call filter and capability bounding set (not yet worked out).
In the Docker deployment the container’s entrypoint applies the same file modes, and the compose file’s memory, process and CPU limits play the role of the unit’s.
UI panels: the browser sandbox
Section titled “UI panels: the browser sandbox”A panel runs in <iframe sandbox="allow-scripts"> without allow-same-origin, so the browser treats it as a unique, opaque origin. Its files are served with:
default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:;font-src data:; connect-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'self'Together these mean a panel cannot read cookies, reach into the Aperture page, open any network connection, load code from anywhere, or be framed by another site. Its only way to Aperture is the message bridge, and every call through it is checked on the server with the extension’s scopes intersected with the viewer’s rights; see Permissions. The extension’s token never reaches the browser.
Two more rules keep panels out of Aperture’s own page:
- Only the
ui/folder is served. The manifest, the backend code and the import map never are. - An extension icon must be a real PNG of at most 64 KiB and 256 × 256 pixels, checked by decoding it at install, and it is always shown as an image, never inserted as markup. A file named
icon.pngthat is really an SVG with a script in it is rejected.
What an extension can reach
Section titled “What an extension can reach”| Backend | Panel | |
|---|---|---|
| Aperture API | With its token, within its scopes and camera grant | Through the broker, within its scopes, its grant and the viewer’s rights |
| Session-only operations (users, tokens, backup, restore, restart, extension management) | No | No |
| Its own files | Read and write | Its ui/ files only, as served pages |
| Other extensions’ files | No | No |
Database, recordings, secrets.json, cli.token |
No | No |
| Its own private store | Yes, secrets included | Administrators only, without secrets |
| Network | Declared hosts and the API host, through Deno | Declared hosts, through Aperture’s server |
| Other programs, native code, system information | No | No |
| Aperture’s environment | Only its own three variables | No |
| Cookies and the Aperture page | Not applicable | No |
What the sandbox does not stop
Section titled “What the sandbox does not stop”The sandbox limits an extension to what you approved. It cannot make a trusted extension trustworthy. Know these limits:
- Network access can carry your data away. A backend allowed to reach a host can send that host anything it can read. That is what backends are for, and no sandbox can tell a legitimate request from a leak. Grant
networkonly to extensions and hosts you trust. - Sideloaded extensions are reviewed by nobody. When you install from a file or a link, you vouch for the author. The Reviewed label on store items only means the item came from the store index you configured.
- Anyone who can see a panel can use its network access. A panel’s
net.fetchworks for every signed-in user who can see the panel, carries any secret the extension injects, and returns the host’s reply. It works only while the extension is enabled, and for an extension granted specific cameras only for users who may see one of them. No other API token, and not the CLI token, can call it; see Routes that act as the extension. - Panel files are public. While an extension is enabled, anyone who can reach the server can download its
ui/files without signing in. - A loopback service is reachable by the machine. A backend that serves an API on
127.0.0.1, as the Tapo and Eufy examples do, can be called by any program on the server, and by any other extension that declared the same address. - A host without a port allows every port for a backend, because that is how Deno reads
--allow-net. Declare the port to narrow it. - Consent covers permissions, not behaviour. An update that asks for nothing new is applied without a dialog and runs new code with the access already granted. An update that adds an API scope, a network host, a camera request, storage or a backend asks again; see Updates and consent.
- Secrets are not encrypted at rest. They are write-only through Aperture, but stored as plain text in the database, readable by root and present in backups.
- Administrators can change extension code. Edit files changes what an installed extension runs, with all of its permissions. Saving a file restarts the backend with the new code.
- CPU is shared. There is no per-extension CPU limit. A busy extension competes for the service’s CPU quota with the recorders and the web server.
- Layer one is Deno. The first layer is only as strong as Deno’s permission checks; layer two exists for the case where they fail.
How it is tested
Section titled “How it is tested”These tests exist in the repository. Run the Go tests with go test ./internal/ext/ ./internal/api/ and the web tests with npm test in web/; make test runs both.
| Test | What it checks |
|---|---|
TestBuildSpecDenyByDefault (internal/ext/spec_test.go) |
The flag set: --deny-run, --deny-ffi, --deny-sys, --deny-import, the env allow-list, read and write limited to the extension’s folder, the declared host and the API host in --allow-net, --deny-net with no hosts, the user id, heap cap and OOM bias, and the environment |
TestBackendExtensionRunsEndToEnd (internal/api/ext_backend_e2e_test.go) |
Runs the real motion-webhook example through the real start path: the import map, the drop to user 65600, the __ext-spawn trampoline and Deno itself. It passes when the backend reaches running, stays running and prints its ready line. It needs Deno and root, and skips otherwise. It proves a confined backend works; it does not try forbidden operations. |
Supervisor tests (internal/ext/supervisor_test.go) |
Start, stop and logs; giving up after repeated crashes; the heap flag; the trampoline being used when limits are set; draining on shutdown; restarting during a stop. These run a stand-in shell command, not Deno. |
TestBrokerConfusedDeputy, TestBrokerDisabledExtension (internal/api/ext_broker_test.go) |
A panel’s calls get the extension’s scopes intersected with the caller’s cameras and role; a disabled extension’s broker refuses |
TestCSRFGuard |
A cross-site write with a session cookie is refused |
TestExtKVNamespaceIsolation |
A token reaches only its own extension’s store, and only if it declared storage |
TestExtFetch, TestExtFetchNetworkFromSetting, TestExtFetchLegibleError, TestExtFetchSecretsAreNamespaceScoped |
The fetch allow-list, hosts from settings, readable connection errors, and that {{secret:…}} resolves only against the route extension’s own declared secrets |
TestExtFetchRefusesForeignCredentials, TestExtFetchIntendedCallers, TestExtFetchSessionRules, TestExtSettingsGetCallers, TestExtSettingsGetCameraValuesNarrowed, TestExtKVRefusesCLI (internal/api/ext_self_access_test.go) |
The routes that act as the extension refuse personal tokens, other extensions’ tokens and the CLI; a session needs the extension enabled and a shared camera; a viewer’s settings read leaves out cameras they may not see |
TestBackendRestartsWhenItsTokenIsReissued, TestGateOffStartsNoBackend, TestUpdateConsentCoversHostsCamerasStorageBackend, TestUpdateClampsCameraGrant (internal/api/ext_lifecycle_test.go), TestNewPermissions (internal/ext/perms_test.go) |
A new token always comes with a restart; nothing starts while the gate is off; updates ask again for new hosts, cameras, storage or a backend; an update fits the camera grant to the new request |
TestExtAssetServing, TestExtGateDisableGuardsAndLatch |
Only ui/ is served, with the security policy; disabled extensions and a closed gate serve nothing |
TestExtInstallRejectsTraversal |
A bundle with ../ paths is refused |
TestCheckNoRemoteImports, TestManifestRejections, TestCameraDataWithoutRequestGate |
The install-time checks on imports, manifests and camera requests |
TestValidateIcon |
Non-PNG and oversized icons are refused |
TestExtScopesAreKnown |
Every scope a manifest can produce is one the API enforces |
panels.test.ts, ExtensionSlot.render.test.tsx (web/src/ext/) |
With no extensions every slot renders nothing; camera slots follow the grant; a panel’s resize messages are accepted only from its own frame |
updateConsent.test.ts, exampleJogPanels.test.ts (web/src/ext/) |
The update button asks for consent when either the published manifest or the downloaded bundle asks for more; the example jog wheels work for viewers, whose storage calls are refused |
Two parts are not covered by an automated test: no test runs a hostile backend to show that a forbidden operation fails inside Deno, and no test loads a panel in a real browser to show that the sandbox holds. For the browser, the repository has a manual check in test/fixtures/sandbox-probe: a dashboard card that tries to read the session cookie, read the Aperture page and call the API directly, reports each attempt as blocked or leaked, and then confirms that the broker works. Build the bundle from the repository root with go run ./tools/mkbundles -src test/fixtures -out /tmp/sandbox-probe (a zip made by hand must have manifest.json at its root), install it with Upload file, accept the consent screen, which asks to see your cameras, and read the verdict on the dashboard card. Uninstall it afterwards.