officerdev/platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

step 1/4: the permission engine is called permissions, not capabilities

Browse Source 
The word meant four different things in this repo, not the three the offscale
doc records:

  1. the permission registry              → RENAMED here
  2. $OFFICER_ROOT/capabilities/ items    → kept; this is what capabilities are
  3. sidecar routing keys                 → step 3, becoming `handles`
  4. Lightning wallet features            → kept; a domain term, and on the wire
                                            to the mobile apps

The fourth was not in the doc and a global find-and-replace would have broken
the mobile wallet, which reads `{ kind, capabilities: Capability[] }` from the
wallet sidecar. So this renamed against an explicit file allowlist rather than
by sweeping the tree, and `CapabilityPage.tsx` — the UI for the item store, and
correctly named already — was left alone.

Moved: servers/capabilities/ → servers/permissions/, capability-gate.ts →
permission-gate.ts, users/capabilities-routes.ts → permissions-routes.ts,
hooks/useCapabilities.ts → usePermissions.ts. Identifiers follow.

Three breaks the typechecker could not see, all found by exercising it live.

The route paths moved with the prose sweep, so the server served
/user/permissions while the frontend still called /user/capabilities. A 404 on
every page load, and tsgo clean throughout.

The response FIELD moved too. `client.get<SelfPermissions>()` is an unchecked
cast, so `data.capabilities` became `undefined` at runtime with no compile
error — `can()` would have answered "no" to everything and the dock would have
emptied itself.

And the grants list was passed straight out of the database, so it arrived as
`{ role, capability, level }` while the screen read `grant.permission`. Every
role would have rendered as holding nothing. It is now mapped in the route:
the wire says `permission`, the column still says `capability`, and step 2
therefore changes nothing any client can see.

The stale react-query keys were the quiet one: two files still invalidated
['self-capabilities'] after the hook moved to ['self-permissions'], so
installing a plugin would have silently stopped refreshing the dock.

The database is untouched — `role_capabilities` and its `capability` column are
step 2, and the two call sites that cross that boundary say so in a comment.
Round-tripped the 9 live grants through the admin endpoint to prove the PUT
contract survived: 9 before, 9 after, Member's three intact.

Also reverted prettier churn on five landing-page files that a broad --write
picked up. Second time today; the lesson is not sticking.

tsgo clean. 797 tests, 787 pass, same 7 pre-existing failures — two of which
now read "path → permission" rather than "path → capability".
This commit is contained in:
pastilhas
2026-08-15 16:03:22 +00:00
parent b0fcd8b81b
commit 2e8ec845c8
59 changed files with 454 additions and 442 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/servers/app-store/availability.ts
+17 -17
View File
@@ -4,9 +4,9 @@ import { CATALOGUE, type CatalogueEntry } from './catalogue';
// Which features actually EXIST on this server right now — as opposed to which the account is permitted
// to use.
//
// ── Why this is separate from capabilities ──
// ── Why this is separate from permissions ──
//
// They answer different questions and combining them would get the owner wrong. A capability asks "may
// They answer different questions and combining them would get the owner wrong. A permission asks "may
// this account use Photos"; the owner bypasses that entirely and always may. Installation asks "is there
// a Photos on this machine at all", and the owner is as subject to it as anyone — installing nothing
// leaves nothing to use.
@@ -17,20 +17,20 @@ import { CATALOGUE, type CatalogueEntry } from './catalogue';
//
// ── Why it is computed here and not in the client ──
//
// The dock already reads one list from `/capabilities`. Making it read a second and intersect the two
// The dock already reads one list from `/permissions`. Making it read a second and intersect the two
// puts the rule in the UI, where a member's dock and an owner's dock can drift apart, and where a
// third-party plugin would have to be taught about it. Subtracting server-side keeps one answer.
/**
* Capability key → the sidecar that has to be installed for it to mean anything.
* Permission key → the sidecar that has to be installed for it to mean anything.
*
* Includes `alsoServes`, because one sidecar can back more than one capability: Headscale serves both the
* Includes `alsoServes`, because one sidecar can back more than one permission: Headscale serves both the
* owner's tailnet administration and a member enrolling their own device, and only listing the first left the
* second looking available on a machine that had no Headscale.
*/
const CAPABILITY_TO_SIDECAR = new Map(
const PERMISSION_TO_SIDECAR = new Map(
CATALOGUE.flatMap((entry) =>
[entry.capability, ...(entry.alsoServes ?? [])].filter((key): key is string => !!key).map((key) => [key, entry.id]),
[entry.permission, ...(entry.alsoServes ?? [])].filter((key): key is string => !!key).map((key) => [key, entry.id]),
) as Array<[string, string]>,
);
@@ -38,17 +38,17 @@ export type Availability = {
/**
* UI manifests of the sidecars that ARE usable — what the dock should show beyond the baseline.
*
* Sent with the capability answer rather than fetched separately so the dock has one source. Two
* Sent with the permission answer rather than fetched separately so the dock has one source. Two
* requests would mean two moments, and a dock rendered between them shows either a tile for something
* uninstalled or nothing for something installed.
*/
manifests: Array<{ sidecarId: string; capability: string | null } & NonNullable<CatalogueEntry['ui']>>;
/** Capability keys whose sidecar is not installed, or is installed but disabled. */
manifests: Array<{ sidecarId: string; permission: string | null } & NonNullable<CatalogueEntry['ui']>>;
/** Permission keys whose sidecar is not installed, or is installed but disabled. */
unavailable: Set<string>;
/**
* True when install state could not be read.
*
* The caller then subtracts NOTHING. Same reasoning as `useCapabilities` failing open: a member seeing
* The caller then subtracts NOTHING. Same reasoning as `usePermissions` failing open: a member seeing
* an icon that leads to an unavailable screen is a bad minute, while an owner whose whole dock vanished
* because a query failed is an incident. Absence of evidence is not evidence of absence.
*/
@@ -56,13 +56,13 @@ export type Availability = {
};
/**
* What is missing on this server, by capability key.
* What is missing on this server, by permission key.
*
* A sidecar that is installed but DISABLED counts as unavailable, deliberately. Disable stops the
* process and its container, so the feature genuinely does not work — leaving its icon in place would
* make disable look broken rather than effective.
*/
export async function capabilityAvailability(): Promise<Availability> {
export async function permissionAvailability(): Promise<Availability> {
const unavailable = new Set<string>();
let installs;
@@ -70,7 +70,7 @@ export async function capabilityAvailability(): Promise<Availability> {
installs = await listSidecarInstalls();
} catch {
// Degraded: subtract nothing, and offer no manifests. The dock keeps its baseline rather than
// guessing, which is the same fail-open posture as useCapabilities.
// guessing, which is the same fail-open posture as usePermissions.
return { unavailable, manifests: [], degraded: true };
}
@@ -78,13 +78,13 @@ export async function capabilityAvailability(): Promise<Availability> {
installs.filter((row) => row.status === 'installed' && row.enabled).map((row) => row.sidecarId),
);
for (const [capability, sidecarId] of CAPABILITY_TO_SIDECAR) {
if (!usable.has(sidecarId)) unavailable.add(capability);
for (const [permission, sidecarId] of PERMISSION_TO_SIDECAR) {
if (!usable.has(sidecarId)) unavailable.add(permission);
}
const manifests = CATALOGUE.filter((e) => e.ui && usable.has(e.id)).map((e) => ({
sidecarId: e.id,
capability: e.capability,
permission: e.permission,
...e.ui!,
}));
src/servers/app-store/catalogue.test.ts
+10 -10
View File
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'bun:test';
import { existsSync } from 'node:fs';
import { join } from 'node:path';
import { CATALOGUE, byId } from './catalogue';
import { CAPABILITIES } from '../capabilities/registry';
import { PERMISSIONS } from '../permissions/registry';
// The catalogue is a hand-written list describing machinery that lives elsewhere, which is the shape of
// thing that rots silently. These tests pin it to what it claims to agree with.
@@ -80,14 +80,14 @@ describe('entries are internally coherent', () => {
});
});
describe('capabilities it claims to back', () => {
it('names a capability that exists, or explicitly none', () => {
describe('permissions it claims to back', () => {
it('names a permission that exists, or explicitly none', () => {
// `null` is a real answer — notify has no surface of its own — but a WRONG key would silently
// detach the store entry from the permission that governs the feature.
const keys = new Set(CAPABILITIES.map((c) => c.key));
const keys = new Set(PERMISSIONS.map((c) => c.key));
for (const entry of CATALOGUE) {
if (entry.capability === null) continue;
expect(keys).toContain(entry.capability);
if (entry.permission === null) continue;
expect(keys).toContain(entry.permission);
}
});
});
@@ -148,13 +148,13 @@ describe('the UI manifest each sidecar carries', () => {
}
});
it('claims routes that the capability registry agrees it owns', () => {
it('claims routes that the permission registry agrees it owns', () => {
// The manifest drives the dock; the registry drives the server-side guard. If they disagree, a tile
// appears for a route the account is refused — or worse, a route is guarded by nothing.
const byKey = new Map(CAPABILITIES.map((c) => [c.key, c]));
const byKey = new Map(PERMISSIONS.map((c) => [c.key, c]));
for (const entry of CATALOGUE) {
if (!entry.ui || !entry.capability) continue;
const declared = byKey.get(entry.capability)?.routes ?? [];
if (!entry.ui || !entry.permission) continue;
const declared = byKey.get(entry.permission)?.routes ?? [];
for (const route of entry.ui.routes) expect(declared).toContain(route);
}
});
src/servers/app-store/catalogue.ts
+21 -21
View File
@@ -80,7 +80,7 @@ export type UiManifest = {
/**
* Every frontend route this sidecar owns, `rootRoute` included.
*
* Separate from `rootRoute` because a feature can own more than one path — the capability registry
* Separate from `rootRoute` because a feature can own more than one path — the permission registry
* already lists `/caldav` and `/dav` together — and the guard needs all of them while the dock needs
* exactly one.
*/
@@ -108,18 +108,18 @@ export type CatalogueEntry = {
/** Which of the three shapes this sidecar supports, in the order the UI should offer them. */
modes: InstallMode[];
/**
* The capability this sidecar backs, from `capabilities/registry.ts`. Null where the sidecar has no
* The permission this sidecar backs, from `permissions/registry.ts`. Null where the sidecar has no
* user-facing surface of its own (notify produces notifications for other features).
*
* This is also the key the sidecar's dock manifest is filtered by, which is why it is one value and not a
* list — a tile belongs to one feature.
*/
capability: string | null;
permission: string | null;
/**
* Other capabilities that stop working when this sidecar is absent, for availability only.
* Other permissions that stop working when this sidecar is absent, for availability only.
*
* Headscale is the case: one sidecar serves both `headscale` (administering the tailnet, owner-only) and
* `vpn` (a member enrolling their own device). With only `capability` to go on, `vpn` was never subtracted,
* `vpn` (a member enrolling their own device). With only `permission` to go on, `vpn` was never subtracted,
* so the Permissions screen offered it on a machine with no Headscale at all — a grant that would have
* produced a refusal the owner could not account for.
*/
@@ -171,7 +171,7 @@ export const CATALOGUE: CatalogueEntry[] = [
summary: 'Your Immich library — browse, search, upload from the phone',
members: 'accounts',
modes: ['existing', 'provisioned'],
capability: 'photos',
permission: 'photos',
composeTemplate: 'immich',
existingFields: [
{ key: 'url', label: 'Immich URL', type: 'url', required: true, placeholder: 'https://photos.example.com' },
@@ -192,7 +192,7 @@ export const CATALOGUE: CatalogueEntry[] = [
summary: 'Films and shows, with a player that handles direct, HLS and progressive',
members: 'accounts',
modes: ['existing', 'provisioned'],
capability: 'jellyfin',
permission: 'jellyfin',
composeTemplate: 'jellyfin',
existingFields: [
{ key: 'url', label: 'Jellyfin URL', type: 'url', required: true, placeholder: 'https://jellyfin.example.com' },
@@ -207,7 +207,7 @@ export const CATALOGUE: CatalogueEntry[] = [
summary: 'Quick notes, tagged and searchable',
members: 'accounts',
modes: ['existing', 'provisioned'],
capability: 'memos',
permission: 'memos',
composeTemplate: 'memos',
existingFields: [
{ key: 'url', label: 'Memos URL', type: 'url', required: true },
@@ -222,7 +222,7 @@ export const CATALOGUE: CatalogueEntry[] = [
summary: 'InvoiceShelf — clients, estimates and invoices',
members: 'accounts',
modes: ['existing', 'provisioned'],
capability: 'invoices',
permission: 'invoices',
composeTemplate: 'invoiceshelf',
existingFields: [
{ key: 'url', label: 'InvoiceShelf URL', type: 'url', required: true },
@@ -237,16 +237,16 @@ export const CATALOGUE: CatalogueEntry[] = [
summary: 'Vaultwarden — passwords, reachable by the Bitwarden apps',
members: 'invite',
modes: ['existing', 'provisioned'],
// No capability entry exists for this one, and the reason is about CREDENTIALS, not routing.
// No permission entry exists for this one, and the reason is about CREDENTIALS, not routing.
//
// Every request still goes through us: `/api/vault` is mounted on vaultRouter and forwarded by the
// officer-vault sidecar to Vaultwarden. The Bitwarden clients never reach Vaultwarden directly.
//
// What they do NOT carry is a platform JWT — they present their own Vaultwarden bearer token — so
// `userMiddleware` would 401 them and a capability lookup would have no account to resolve. Hence
// `userMiddleware` would 401 them and a permission lookup would have no account to resolve. Hence
// `/vault` sits in EXEMPT_API_PREFIXES, gated by origin scoping and Vaultwarden's own auth instead.
// The install still governs whether the sidecar runs at all.
capability: null,
permission: null,
composeTemplate: 'vaultwarden',
existingFields: [{ key: 'url', label: 'Vaultwarden URL', type: 'url', required: true }],
},
@@ -264,7 +264,7 @@ export const CATALOGUE: CatalogueEntry[] = [
summary: 'Torrents, with the daemon Officer talks to over RPC',
members: 'none',
modes: ['existing', 'provisioned'],
capability: 'transmission',
permission: 'transmission',
composeTemplate: 'transmission',
existingFields: [
{
@@ -306,7 +306,7 @@ export const CATALOGUE: CatalogueEntry[] = [
summary: 'slskd — search and download from the Soulseek network',
members: 'none',
modes: ['existing', 'provisioned'],
capability: 'soulseek',
permission: 'soulseek',
composeTemplate: 'slskd',
existingFields: [
{ key: 'url', label: 'slskd URL', type: 'url', required: true },
@@ -327,7 +327,7 @@ export const CATALOGUE: CatalogueEntry[] = [
summary: 'Radicale — calendars and contacts over CalDAV/CardDAV',
members: 'accounts',
modes: ['existing', 'provisioned'],
capability: 'calendar',
permission: 'calendar',
composeTemplate: 'radicale',
existingFields: [{ key: 'url', label: 'CalDAV URL', type: 'url', required: true }],
},
@@ -347,7 +347,7 @@ export const CATALOGUE: CatalogueEntry[] = [
// runs — on this machine, on another, or hosted. Provisioning one would mean owning the migration,
// backup and upgrade story for a service that is nobody's side feature.
modes: ['existing'],
capability: 'gitea',
permission: 'gitea',
existingFields: [
{ key: 'url', label: 'Gitea URL', type: 'url', required: true, placeholder: 'https://gitea.example.com' },
{
@@ -381,7 +381,7 @@ export const CATALOGUE: CatalogueEntry[] = [
summary: 'Your IMAP accounts, synced and searchable',
members: 'none',
modes: ['config'],
capability: 'email',
permission: 'email',
// Deliberately empty: accounts are added from /email, which already has a working multi-account
// form. Duplicating it here would be a second place to maintain the same credentials.
configFields: [],
@@ -389,7 +389,7 @@ export const CATALOGUE: CatalogueEntry[] = [
// Music was here until 2026-08-15, when it became `plugins/music/`. Removing it was not tidying — it
// was the headscale bug above, exactly, and it would have fired on the first install.
//
// `capabilityAvailability` reads `sidecar_installs`, and a PLUGIN never gets a row there: its install
// `permissionAvailability` reads `sidecar_installs`, and a PLUGIN never gets a row there: its install
// state lives in `plugin_installs`. So `music` would have been permanently `unavailable`, which puts
// `/music` into `deniedRoutes` — the screen blank and the dock tile withheld on a server where the
// plugin was installed, enabled and healthy. The same shape as headscale, found by reading that note
@@ -410,7 +410,7 @@ export const CATALOGUE: CatalogueEntry[] = [
summary: 'Bitcoin and Lightning, with keys held by the sidecar alone',
members: 'none',
modes: ['config'],
capability: 'wallet',
permission: 'wallet',
configFields: [],
},
{
@@ -420,7 +420,7 @@ export const CATALOGUE: CatalogueEntry[] = [
summary: 'Push to your phone when a job finishes or a turn needs you',
members: 'none',
modes: ['config'],
capability: 'notify',
permission: 'notify',
configFields: [],
},
{
@@ -431,7 +431,7 @@ export const CATALOGUE: CatalogueEntry[] = [
summary: 'Mirror this machine’s display in the browser',
members: 'none',
modes: ['config'],
capability: 'desktop',
permission: 'desktop',
// x11vnc against an Xorg display. There is nothing to mirror on a headless box or on macOS, so the
// store should say so rather than install something that starts and immediately fails.
requires: 'linux-display',
src/servers/app-store/paths.ts
+1 -1
View File
@@ -11,7 +11,7 @@ import { OFFICER_ROOT } from '../data-path';
// platform/ the app
// data/ DATA_PATH — managed homes, attachments, job logs
// dockers/ services the app store provisioned <- this file
// capabilities/ the file-based item store
// permissions/ the file-based item store
//
// One root, everything under it, nothing scattered. `OFFICER_ROOT` is derived from `DATA_PATH` rather
// than configured separately, because a second environment variable that must agree with the first is a