Skip to main content

Authorization table

Every plugin keeps an authz.json at the root of its repo. It says who may call each HTTP route and socket the plugin serves. The shared plugin CI checks it on every push and pull request, and core checks its own table the same way.

What the check does​

The check builds the newest core and your plugin, starts a server on a throwaway database and makes a set of callers:

CallerWhat it is
anonNo login at all
expired, revokedA login that timed out, or was signed out
pendingA login still waiting for its second factor
setupA login that must set up a second factor before anything else
guestA read only session share link, with no login
nopermA user with no permissions at all
otherAnother user, with nothing shared
share-connect, share-view, share-edit, share-manageOne user per host share level
ownerThe user who owns the hosts, credentials and plugin rows
adminAn admin
key-ops-read, key-ops-runThe owner's API keys, scoped to operations

Then it calls every entry as each of them and compares the answer with what the table says.

  • Refused means 401, 403 or 404. A socket counts as refused when the upgrade fails, when it closes with a refusal code, or when its reply to the first message matches refuseReply.
  • A refused caller that gets 400 fails the run: the request never got far enough to be checked, so the entry needs a valid body.
  • Allowed callers are called on reads. Writes are only checked for refusals, unless the entry sets callAllowed.
  • A route the plugin serves with no entry fails the run. So does an entry for a route that is gone.

Writing entries​

Write what a route should allow, not what it happens to do today.

{
"seed": [
{
"as": "owner",
"method": "POST",
"path": "/plugin-api/hello/notes",
"body": { "title": "authz-own-note" },
"capture": { "hello.note": "note.id" }
}
],
"routes": {
"GET /plugin-api/hello/notes/:id": {
"access": "user",
"permission": "hello.use",
"resource": { "kind": "own", "fixture": "hello.note" },
"params": { "id": "hello.note" }
}
}
}
FieldMeaning
accesspublic, user or admin
permissionThe permission or permissions the route needs. One the plain user role does not have means only admins.
resourceWhose thing the route acts on. host and folder follow share levels from min, credential is use or manage, any other kind belongs to the owner alone. key names a body or query field when the id is not in the path.
paramsPath params, by fixture name or =literal
body, query, headersWhat to send
allowSession states let through: pending, setup or guest
expectOverride the worked out answer for one caller
filteredOther callers may get 200, as long as nothing of the owner's is in the reply
scopedOther callers may get a no-op 200; the run then checks the owner's copy is still there
refuse400Why a 400 is a real refusal here, for a body that names something of the owner's
destructiveNever call this as an allowed caller
allowed: "any"Skip the allowed side when the test data can't have it (a real device, desktop only). Refusals are still checked.
send, refuseReplyFor sockets that check the caller on the first message
unlisted, skip, noteWhy a route is not served on a server, why it is not called, or anything a reader needs

seed steps run before the check to make the owner's rows. capture reads a value from the reply (a dotted path, -1 picks the last item of a list) for use in params and as {{name}} in bodies. The fixtures host, host2, credential, folder and user:<caller> always exist. Name the owner's rows with authz-own- at the start, so filtered replies can be checked for them.

The full list of fields is in authz.schema.json.

Running it yourself​

From a core checkout next to your plugin, after npm run build:backend:core in core and npm run build in the plugin:

node ../Termix/scripts/authz/run.mjs --no-core --plugin . --local-plugin . --local-plugins ../Plugins

--local-plugins should hold built copies of TOTP and Login Security (the run uses them to make the pending, setup and expired logins) and of any plugin yours depends on. node ../Termix/scripts/authz/stage-deps.mjs . deps clones and builds them into deps. --only <text> runs just the entries whose key contains the text, and --keep keeps the server log.