Permissions
An extension’s permissions block is the complete list of what it may do. This page explains each permission, the API scopes and camera grants it turns into, how network access is bounded, and how a UI panel’s rights combine with those of the person looking at it.
One authority system
Section titled “One authority system”Extension permissions are not a separate system. They become the same API scopes and per-camera grants that any API token carries:
- A backend gets its own scoped API token. Every call it makes is checked like a call from any other token.
- A UI panel never holds a token. Its calls go through Aperture’s broker, which checks them against the extension’s scopes and the viewing user’s own rights together.
Two permissions have no API scope: network (which hosts the extension may reach) and storage (its private key-value store). Everything is denied by default: an absent or empty permissions block grants nothing.
The mapping lives in dataDomainScopes in internal/ext/manifest.go. A test (TestExtScopesAreKnown) fails the build if the mapping ever names a scope the API does not enforce.
Catalogue
Section titled “Catalogue”| Manifest entry | Becomes | Consent wording |
|---|---|---|
data.<domain>: "read" |
the <domain>:read scope |
“Read your …” |
data.<domain>: "write" |
<domain>:read and <domain>:write |
“Read and change your …” |
data.media: "live" |
media:live only |
“Read your media”, plus the camera line “Watch your cameras’ live video” |
alarm: "arm" |
alarm:arm |
“Read and change your alarm” |
system: "read" |
system:read |
“Read your system” |
cameras: "all" or ["id", …] |
the camera grant on the token | A camera section with its own line and picker |
network: [ … ] |
the backend’s Deno --allow-net list and the panel’s net.fetch allow-list |
“Connect over the internet to … — it can send your data there”, and variants below |
storage: true |
a private key-value namespace | “Keep its own settings in a private folder” |
settings: [ … ] |
the same namespace, plus a form | “Store its settings — including any secrets you enter — in a private folder” |
The consent screen joins all API scopes into one line: the domains in alphabetical order, with “Read and change” when any of them is a write (or alarm), and “Read” otherwise. An extension that reads cameras and events and changes the site shows “Read and change your cameras, events, site”. Every consent list ends with “It cannot read your recordings files, your database, or your passwords.”
Data domains
Section titled “Data domains”| Domain | read |
write |
live |
|---|---|---|---|
cameras |
cameras:read |
cameras:read, cameras:write |
|
events |
events:read |
events:read, events:write |
|
coverage |
coverage:read |
||
segments |
segments:read |
||
media |
media:read |
media:read, media:write |
media:live |
storage |
storage:read |
storage:read, storage:write |
|
schedules |
schedules:read |
schedules:read, schedules:write |
|
zones |
zones:read |
zones:read, zones:write |
|
detection |
detection:read |
detection:read, detection:write |
|
site |
site:read |
site:read, site:write |
|
automation |
automation:read |
automation:read, automation:write |
A domain or level that is not in this table fails the install. Scopes lists which API routes each scope opens.
Each domain takes one level, so media is either "read", "write" or "live". An extension that asks for "live" cannot also read recorded media.
data.storage is the scope for Aperture’s own storage locations (where recordings go). It has nothing to do with the top-level storage: true, which is the extension’s private key-value store. You may want either, both or neither.
Administrator-only routes
Section titled “Administrator-only routes”Some routes require an administrator on top of the scope; for example changing a camera needs cameras:write and an administrator. For a backend, the administrator is the token’s owner: the administrator who installed the extension, or, for an install made with the CLI token, the first administrator account. For a panel, it is the person viewing it, so the same panel can change a camera for an administrator and get “administrator access required” for a viewer.
Cameras
Section titled “Cameras”Camera access is the main privacy control, so it is opt-in and explicit. permissions.cameras takes one of:
| Value | Meaning |
|---|---|
| absent | No camera access. The extension cannot read camera data. |
"all" |
Every camera, including cameras added later. |
["front_door", "garage"] |
At most these cameras. The list is a ceiling, written as camera ids. |
An extension that asks for cameras, events, coverage, segments or media under data must also ask for cameras, or the install fails: “this extension reads camera data but does not request cameras”. A panel that only places a control and reads no camera data does not need to ask, and gets no camera section at consent.
A list of ids only means something on a server where those ids exist. Ids that do not exist do not appear in the picker. For an extension you share, "all" is the portable choice; the administrator narrows it at install.
Choosing and changing the grant
Section titled “Choosing and changing the grant”The manifest’s request is a default. At install the administrator chooses:
- for an
"all"request: All cameras (including cameras added later) or Only the cameras I choose (exactly these; a camera added later is not granted); - for a list request: any subset of the listed cameras that exist.
Afterwards the choice lives in the Cameras section of the extension’s row in Settings › Extensions. Saving it stores the new grant, revokes the backend’s token and restarts the backend with a new token limited to the new grant. Nothing starts while the extension is disabled or the extension gate is off. Changing cameras is the administrator’s decision, not a new permission, so it never asks for consent.
An update keeps your choice, fitted to the new version’s request:
- If the new version asks for every camera, or for none, the grant stays as it is.
- If it names specific cameras and your grant was every camera, the grant becomes that list.
- If you had picked cameras, the grant keeps those the new list still names. If the new list names none of them, the grant becomes the new list, and the update asks for consent first.
The server refuses an empty selection (“select at least one camera to grant”) and any camera outside a list request (“camera … was not requested by this extension”). The same check runs when the choice is changed through PUT /api/v1/ext/{id}/cameras.
What the grant controls
Section titled “What the grant controls”One decision controls both what the extension can read and where its panels appear:
- Data: API calls for a camera outside the grant fail with 403, and lists such as
GET /camerasand the change feed leave those cameras out. - Placement: panels in the camera slots (
camera-detail,player-toolbar,player-osd) appear only on granted cameras. An extension granted all cameras, or one that asked for none, shows its camera panels on every camera. - Settings: a
camerafield in the extension’s settings only offers, and only accepts, granted cameras.
How the grant combines
Section titled “How the grant combines”A grant never widens anyone’s access:
- A backend sees the cameras in its grant that its token’s owner may see. An all-cameras grant means everything the owner may see. Since the owner is an administrator, that is normally every camera.
- A panel sees the cameras in the grant that the viewing user may see. A viewer allowed one camera sees one camera in a panel granted all of them.
Network
Section titled “Network”permissions.network lists the hosts an extension may reach. It is the only way an extension reaches anything outside Aperture.
Entry forms
Section titled “Entry forms”| Entry | Allowed host | Consent line |
|---|---|---|
"https://hooks.example.com" |
hooks.example.com |
“Connect over the internet to hooks.example.com — it can send your data there” |
"http://192.168.1.50:2020" |
192.168.1.50:2020 |
“Connect over the internet to 192.168.1.50:2020 — it can send your data there” |
"http://127.0.0.1:8788" |
127.0.0.1:8788 |
“Talk to 127.0.0.1:8788 — a service running on this machine, not over the internet” |
"{{setting:ha_url}}" |
the host and port of the ha_url setting’s current value |
“Connect to a server you configure in its settings — it can send your data there” |
"{{setting:cameras.address}}" |
the host and port in the address column of every row of the cameras group setting |
the same line |
Only localhost, ::1 and 127.x.x.x count as this machine. Everything else, including addresses on your own network, is worded as the internet.
A setting reference lets the user, not the author, choose the host. The allow-list follows the value the administrator saved, and changing the value needs no new consent. An update that adds a host, or refers to a setting the old version did not, does ask again (see Updates and consent). A group reference serves extensions that talk to several devices the user names: each row adds exactly the address typed into it, port included.
Backends
Section titled “Backends”A backend’s hosts become Deno’s --allow-net flag, built when the backend starts. Setting references are resolved at that moment, and saving settings restarts the backend, so the flag always matches the saved values. Aperture also adds its own API host (the host in APERTURE_API) so the SDK works; with no network permission, that is the only host a backend can reach.
Deno decides what each entry allows. An entry with a port allows that port only. An entry without a port (from a URL such as https://hooks.example.com) allows that host on every port. The same flag also governs listening, so a backend can only serve on an address it declared, which is why the Tapo and Eufy examples list their own 127.0.0.1 control ports.
A request to any other host fails inside the backend with Deno’s NotCapable error.
Panels
Section titled “Panels”A panel cannot open network connections itself. window.aperture.net.fetch asks Aperture’s server to make the request (POST /api/v1/ext/{id}/fetch), and the server checks it first:
- The URL’s host and port must equal one allowed entry exactly.
https://hooks.example.com:8443/xdoes not match an entry forhooks.example.com. - Setting references are resolved on every request.
- Methods are
GET,POST,PUT,PATCHandDELETE. AHostheader from the panel is ignored. - Redirects are not followed; the panel gets the 3xx response, so a redirect cannot lead to an undeclared host.
- The request times out after 12 seconds, and at most 256 KiB of the response body is returned.
- All extensions together may make 10 such requests per second, with bursts of 20.
{{secret:key}}in a header value or the body is replaced on the server with the extension’s own secret setting. See Settings and storage.
When a setting a network entry refers to is empty or not a valid URL, a request to an unlisted host fails with “the server address is not set (or is not a valid URL) — configure it in this extension’s settings”. Otherwise an unlisted host fails with “host … is not one this extension may reach”. For a group, one blank or malformed row is enough to report the extension as not configured.
Only two kinds of caller may use this route: a signed-in user’s session, which is how the web app relays a panel, and the extension’s own backend token. For a session, the extension must be enabled (with the gate on), and an extension granted specific cameras serves only a user who may see at least one of them. Any other API token, including another extension’s, and the CLI token get 403 with the code forbidden.extension. See Routes that act as the extension.
Storage
Section titled “Storage”storage: true gives the extension a private key-value store, separate from other extensions and from Aperture’s settings. Declaring settings implies it, because settings are kept in the same store; you never need both. Its backend reads and writes it with its token. In a panel, only administrators can use it. Limits and access rules are on Settings and storage.
Panels act for the person viewing them
Section titled “Panels act for the person viewing them”A UI panel runs in the browser of whoever is looking at it, so it acts with that person’s rights, cut down to the extension’s. Every window.aperture.request, cameras and events call goes to POST /api/v1/ext/{id}/broker. The broker builds a one-off identity from:
| Part | Taken from |
|---|---|
| User and role | The signed-in viewer |
| Camera access | The viewer’s cameras intersected with the extension’s grant |
| Scopes | The extension’s scopes |
| Credential class | API token, so token rules apply |
It then sends the request through Aperture’s normal router, with its normal checks. The consequences:
- A panel can never do more for someone than that person could do unaided, and never more than its manifest declared.
- The same panel may show a viewer less than an administrator. That is correct behaviour.
- Administrator-only routes need the viewer to be an administrator.
- Routes that tokens may never use (see below) are refused here too.
- The extension’s token never reaches the browser; a UI-only extension has no token at all.
The broker accepts GET, POST, PUT, PATCH and DELETE, and a path relative to /api/v1 that starts with /, does not start with /api and contains no ... It is available only to signed-in sessions, only while the gate is on and only for an enabled extension.
| From a panel | Administrator viewing | Viewer viewing |
|---|---|---|
| API calls through the broker | Extension scopes, all granted cameras | Extension scopes, granted cameras the viewer may see; administrator-only routes refused |
settings.get, settings.all |
Non-secret values | Non-secret values; camera values, and list rows tied to a camera, only for granted cameras the viewer may see |
storage.* |
Allowed | Refused: “extension storage is available to administrators only” |
net.fetch |
Allowed | Allowed; for an extension granted specific cameras, only if the viewer may see one of them |
Raw storage is limited to administrators because it has no per-key access control: anything a viewer could read through a panel, they could read from the browser’s developer console as well. Data meant for viewers should come from the extension’s backend through the API, where it is scoped.
Routes that act as the extension
Section titled “Routes that act as the extension”Three routes act as the extension itself: they spend its secrets, reach its declared hosts or read its private data. They are POST /api/v1/ext/{id}/fetch, GET /api/v1/ext/{id}/settings and the storage routes under /api/v1/ext/{id}/kv. Each accepts only:
- the extension’s own backend token, with its full view of its settings and storage, secrets included;
- a signed-in user’s session: the web app relaying one of the extension’s panels, or the extension manager. For
fetchandsettings, a session needs the extension enabled and, for an extension granted specific cameras, a user who may see at least one of them; an administrator’s session reads any extension’s settings form, enabled or not. Storage needs an administrator.
Every other credential is refused with 403 and the code forbidden.extension: a personal API token, another extension’s backend token, and the CLI token. Saving settings (PUT /api/v1/ext/{id}/settings) is a separate route, open only to an administrator’s session. The OpenAPI document marks these routes with x-extension-self.
Updates and consent
Section titled “Updates and consent”An update is applied without a new consent dialog only when it asks for nothing the installed version did not have. Aperture compares the update’s manifest with the installed one (ext.NewPermissions in internal/ext/perms.go) and asks again for any of these:
- a new API scope;
- a new network host, or a host taken from a setting the old version did not refer to;
- cameras where it asked for none before, every camera where it named specific ones, or a camera id the old list did not name;
- private storage it did not have;
- a backend, where the installed version was UI only;
- a camera grant that the new request would change to cameras you did not pick (see Choosing and changing the grant).
The web app checks both the update’s published manifest and the bundle it actually downloaded, and opens the consent dialog if either asks for more. The server enforces the same rule: applying such an update without consent fails with 409 and the code consent_required.
Never grantable
Section titled “Never grantable”Some operations have no scope at all and are open only to a signed-in session or the CLI token. No manifest can reach them, whatever it asks for:
- users and API tokens: listing, creating, changing, deleting;
- your own password, two-factor authentication, passkeys and signed-in devices;
- backup, restore, restart, reindex and purge;
- installing, configuring and managing extensions, and the extension gate;
- the Eufy account integration, which holds a cloud password.
Related
Section titled “Related”The manifest · UI panels · Settings and storage · Extension security · Scopes