Skip to content

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.

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)

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 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.

--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.

If code ever escaped Deno’s permission checks, it would land in a process confined like this:

  • Its own user. nvrd runs 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 mode 0700, so extensions cannot read each other’s files.
  • Aperture’s files closed off. aperture-harden sets the data directory and its ext/ folder to 0711 (passable but not listable) and secrets.json, cli.token, aperture.db and its journal files, and go2rtc.yaml to 0600, 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’s oom_score_adj to 800 so the kernel kills it before nvrd or 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 nvrd dies. 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 with nvrd and the recorders: MemoryHigh, MemoryMax, TasksMax and CPUQuota. OOMPolicy=continue keeps the service running when the kernel kills an extension. The unit also sets NoNewPrivileges=yes (an escaped process cannot gain privileges through set-user-id programs), ProtectSystem=strict with only /var/lib/aperture writable, 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.

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.png that is really an SVG with a script in it is rejected.
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

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 network only 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.fetch works 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.

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.

Extensions · Permissions · UI panels · Security