@camstack/server 1.2.604 → 1.2.606

package/dist/api/trpc/trpc.middleware.js

@@ -14,6 +14,7 @@ const cap_route_error_formatter_js_1 = require("./cap-route-error-formatter.js")
 const device_config_secret_redaction_js_1 = require("./device-config-secret-redaction.js");
 const principal_visibility_js_1 = require("./principal-visibility.js");
 const localized_schema_paths_js_1 = require("./localized-schema-paths.js");
+const principal_authorization_js_1 = require("./principal-authorization.js");
 const scope_access_js_1 = require("./scope-access.js");
 const share_view_access_js_1 = require("./share-view-access.js");
 const user_error_js_1 = require("./user-error.js");
@@ -91,24 +92,20 @@ exports.publicProcedure = t.procedure;
  */
 exports.createCallerFactory = t.createCallerFactory;
 /**
- * Caps-only authenticated procedure (v2).
+ * The authenticated procedure (D892).
  *
- *   - `isAdmin: true` → pass-through. Admin's `scopes` field is ignored.
- *   - `isAdmin: false` → `METHOD_ACCESS_MAP[path]` lookup + scope match.
- *     The caller's scope set must grant the required (capName, access)
- *     pair via one of the three forms (`category`/`capability`/`addon`).
+ * The principal's `scopes` decide, through ONE matcher
+ * (`authorizeProcedure`, `principal-authorization.ts`):
  *
- * Hand-written core routers (`auth.*`, `system.info`, etc.) are not
- * codegen'd from cap definitions and therefore not in
- * `METHOD_ACCESS_MAP`. Those routes carry their own gating via
- * `adminProcedure` when destructive; the bare `protectedProcedure`
- * authentication check is the only gate. The middleware skips the
- * scope-check for unknown paths so the SDK boot probe (`auth.me`) and
- * `system.info` reach non-admin / scoped-token callers — without
- * pulling every core route into the codegen map.
+ *   - a `share-view` grant restricts it to the fail-closed embed allowlist
+ *     (`share-view-access.ts`) — enumerated methods, in-scope devices only —
+ *     and its answers are projected to that perimeter;
+ *   - `'*'` passes;
+ *   - otherwise a cap route (`METHOD_ACCESS_MAP`) is scope-matched, and a
+ *     hand-written core route (`auth.*`, `system.info` …) needs authentication
+ *     only — `adminProcedure` on top gates what is destructive.
  *
- * Single source of authority for caps: `isAdmin`. The legacy role enum
- * collapsed onto this boolean in v2.
+ * What kind of credential the principal came from is never read here.
  */
 exports.protectedProcedure = localized.use(async ({ ctx, next, path, getRawInput }) => {
     if (!ctx.user) {
@@ -120,93 +117,55 @@ exports.protectedProcedure = localized.use(async ({ ctx, next, path, getRawInput
     if (ctx.sessionLive !== undefined && !ctx.sessionLive()) {
         throw (0, user_error_js_1.trpcUserError)('UNAUTHORIZED', 'auth.session-ended', undefined, 'Session ended — sign in again');
     }
-    // Share-view principals (`csv_*` tokens) NEVER reach the admin bypass,
-    // the hand-written-route pass-through, or the scope matcher below —
-    // they are gated exclusively by the fail-closed embed-surface allowlist
-    // (`share-view-access.ts`): enumerated methods only, in-scope devices only.
-    if (ctx.user.shareView) {
-        const rawInput = await getRawInput();
-        const result = (0, share_view_access_js_1.checkShareViewAccess)(ctx.user.shareView.scope, path, rawInput);
-        if (!result.ok) {
-            throw new server_1.TRPCError({ code: 'FORBIDDEN', message: result.reason });
-        }
-        // `deviceManager.listAll` is allowlisted for the embed's tile names,
-        // but its raw rows describe EVERY device (config incl. credentials).
-        // Project the output down to the in-scope whitelisted rows.
+    const user = ctx.user;
+    const verdict = (0, principal_authorization_js_1.authorizeProcedure)(user.scopes ?? [], path, await getRawInput(), ctx.deviceScopeLookup);
+    if (!verdict.ok) {
+        throw new server_1.TRPCError({ code: 'FORBIDDEN', message: verdict.reason });
+    }
+    // Spread+reassign of `user` narrows downstream ctx from `User | null` to
+    // `User` so `adminProcedure` can read fields without re-checking.
+    if (verdict.mode === 'all') {
+        return next({ ctx: { ...ctx, user } });
+    }
+    if (verdict.mode === 'share') {
+        const grant = verdict.grant;
+        // `deviceManager.listAll` is allowlisted for the embed's tile names, but
+        // its raw rows describe EVERY device (config incl. credentials): project
+        // it down to the in-scope whitelisted rows. The events surface answers
+        // with ROWS carrying a `deviceId`, and two of its methods can reach
+        // devices outside the scope — this is where that answer is cut.
         if (path === 'deviceManager.listAll') {
-            const out = await next({ ctx: { ...ctx, user: ctx.user } });
-            if (out.ok) {
-                return { ...out, data: (0, share_view_access_js_1.projectListAllForShareScope)(out.data, ctx.user.shareView.scope) };
-            }
-            return out;
+            const out = await next({ ctx: { ...ctx, user } });
+            return out.ok ? { ...out, data: (0, share_view_access_js_1.projectListAllForShareScope)(out.data, grant) } : out;
         }
-        // The events surface answers with ROWS carrying a `deviceId`, and two of
-        // its three methods can legitimately reach devices outside the scope: a
-        // partially in-scope `listRecentTracks`, and a `searchObjectEvents` with
-        // no `deviceId` at all (which means EVERY camera). The enumeration lets
-        // those calls through — this is where the answer is cut. Without it the
-        // allowlist would be a doorman who checks the ticket and then hands over
-        // the whole building.
         if (share_view_access_js_1.SHARE_SCOPE_PROJECTED_METHODS.has(path)) {
-            const out = await next({ ctx: { ...ctx, user: ctx.user } });
-            if (out.ok) {
-                return { ...out, data: (0, share_view_access_js_1.projectShareScopeRows)(out.data, ctx.user.shareView.scope) };
-            }
-            return out;
-        }
-        return next({ ctx: { ...ctx, user: ctx.user } });
-    }
-    // Spread+reassign of `user` narrows downstream ctx from `User | null`
-    // to `User` so `adminProcedure` can read fields
-    // without re-checking.
-    if (ctx.user.isAdmin) {
-        return next({ ctx: { ...ctx, user: ctx.user } });
-    }
-    // Everything below this line is a NON-ADMIN principal.
-    //
-    // A hand-written core route has no cap entry. Authentication has
-    // already passed; defer further gating to any explicit
-    // `adminProcedure` chained on top of this one. A cap route is
-    // scope-matched first.
-    if (path in system_1.METHOD_ACCESS_MAP) {
-        // Device-scope caps may be gated by a `device:N` scope. Resolve the
-        // raw input once so the matcher can read `input.deviceId` without
-        // re-doing the Zod parse (tRPC caches the parsed input downstream).
-        // The `getDeviceAncestors` hook lets the matcher walk parent → child
-        // accessory inheritance (grant on Reolink also covers its siren / PIR).
-        const rawInput = await getRawInput();
-        const result = (0, scope_access_js_1.checkScopeAccess)(ctx.user.scopes ?? [], path, rawInput, ctx.deviceScopeLookup);
-        if (!result.ok) {
-            throw new server_1.TRPCError({ code: 'FORBIDDEN', message: result.reason });
+            const out = await next({ ctx: { ...ctx, user } });
+            return out.ok ? { ...out, data: (0, share_view_access_js_1.projectShareScopeRows)(out.data, grant) } : out;
         }
+        return next({ ctx: { ...ctx, user } });
     }
     // A non-admin who is allowed to READ a device is not thereby allowed to
     // read the credential that opens it. `deviceManager.getDevice` &co. are
     // `auth: 'protected'`, so a read-only `category:system` grant reaches
-    // them — and the raw row carries `config.password` in plaintext for
-    // every camera in the deployment. The value is withheld HERE, at the
-    // transport boundary, so in-process callers (`ctx.api`, the pipeline
-    // orchestrator, the drivers that must actually connect) are unaffected.
+    // them — and the raw row carries `config.password` in plaintext. The value
+    // is withheld HERE, at the transport boundary, so in-process callers
+    // (`ctx.api`, the drivers that must actually connect) are unaffected.
     const redactConfigSecrets = device_config_secret_redaction_js_1.NON_ADMIN_CONFIG_REDACTED_METHODS.get(path);
-    const out = await next({ ctx: { ...ctx, user: ctx.user } });
+    const out = await next({ ctx: { ...ctx, user } });
     if (!out.ok)
         return out;
     // A device-scoped principal ENUMERATES only its own devices (F1 #4). The
     // matcher lets a `device`-selector grant reach `deviceManager.listAll`
-    // precisely because the answer is cut here; without this the grant would
-    // hand back the whole fleet — names, locations, online state.
+    // precisely because the answer is cut here.
     if (scope_access_js_1.DEVICE_ENUMERATION_METHODS.has(path)) {
-        const projected = (0, principal_visibility_js_1.projectListAllForPrincipal)(out.data, ctx.user.isAdmin, ctx.user.scopes ?? [], ctx.deviceFleet?.() ?? []);
+        const projected = (0, principal_visibility_js_1.projectListAllForPrincipal)(out.data, false, verdict.scopes, ctx.deviceFleet?.() ?? []);
         return {
             ...out,
             data: redactConfigSecrets ? redactConfigSecrets(projected) : projected,
         };
     }
-    // Batch device methods (`deviceIds[]` / `targets[].deviceId` inputs — the
-    // snapshot overview/links and the merged events feed) need no response
-    // projection: the matcher already required EVERY device the request names
-    // to be covered (see `referencedDeviceIds`), so the answer can only
-    // contain rows the caller is entitled to.
+    // Batch device methods need no response projection: the matcher already
+    // required EVERY device the request names to be covered.
     if (redactConfigSecrets) {
         return { ...out, data: redactConfigSecrets(out.data) };
     }

package/dist/api/trpc/trpc.router.js

@@ -54,6 +54,7 @@ const hwaccel_router_js_1 = require("../core/hwaccel.router.js");
 const live_events_router_js_1 = require("../core/live-events.router.js");
 const logs_router_js_1 = require("../core/logs.router.js");
 const notifications_router_js_1 = require("../core/notifications.router.js");
+const preferences_router_js_1 = require("../core/preferences.router.js");
 const repl_router_js_1 = require("../core/repl.router.js");
 const server_management_provider_js_1 = require("../core/server-management.provider.js");
 const stream_probe_router_js_1 = require("../core/stream-probe.router.js");
@@ -351,17 +352,22 @@ function buildCapabilityRouters(services) {
             hubDataDir: path.resolve(services.configService.get('server.dataPath') ?? 'camstack-data'),
             log: services.loggingService.createLogger('certificates'),
         }),
+        // preferences - the caller's own account preferences, synced across their devices (D894).
+        preferences: (0, preferences_router_js_1.createPreferencesRouter)({
+            preferences: (0, preferences_router_js_1.preferencesFromRegistry)(services.capabilityRegistry),
+        }),
         // agentPairing - hub-initiated pairing of agents, unpairing (D857).
         agentPairing: (0, agent_pairing_router_js_1.createAgentPairingRouter)({
             registry: services.capabilityRegistry,
             nodeClient: (nodeId) => (0, node_certificates_client_js_1.createNodeCertificatesClient)(services.moleculer, nodeId),
             log: services.loggingService.createLogger('agent-pairing'),
         }),
-        auth: (0, auth_router_js_1.createAuthRouter)(services.authService, services.capabilityRegistry, services.moleculer, services.shareTokenService, services.handoffCodeService, services.externalLinkIntents, services.nativeLink ?? null, {
+        auth: (0, auth_router_js_1.createAuthRouter)(services.authService, services.capabilityRegistry, services.moleculer, services.handoffCodeService, services.externalLinkIntents, services.nativeLink ?? null, {
             ...(services.authNetworkPolicy !== undefined
                 ? { network: services.authNetworkPolicy }
                 : {}),
             ...(services.sessionBacking !== undefined ? { sessions: services.sessionBacking } : {}),
+            credentialTokens: services.credentialTokenService ?? null,
             logger: services.loggingService.createLogger('auth'),
         }),
         // NOT MOUNTED — `mount: { kind: 'skip' }` legacy provider shapes

package/dist/api/upload-auth.js

@@ -1,32 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UPLOAD_TRPC_PATH = void 0;
 exports.authorizeUploadRequest = authorizeUploadRequest;
-const scope_access_js_1 = require("./trpc/scope-access.js");
-exports.UPLOAD_TRPC_PATH = 'addons.installPackage';
 /**
- * Validate a `cst_*` scoped token via the `user-management` cap singleton.
- * Returns null when the singleton isn't mounted yet (boot race) or the
- * token doesn't validate. Caller treats both as auth failure.
+ * Shared auth guard for the REST upload routes (`/api/addons/upload` and
+ * `/api/server-upload`).
+ *
+ * Every credential goes through the hub's one verifier. An upload installs
+ * code that runs on the hub, so it is ADMIN only: the principal's scopes must
+ * hold `'*'`. A grant of `create` on the `addons` capability is NOT enough —
+ * that reach is a capability permission, and an addon tarball or a server
+ * closure is arbitrary code execution (security review 2026-10-21).
  */
-async function validateScopedTokenViaCap(addonRegistry, token) {
-    const capRegistry = addonRegistry.getCapabilityRegistry();
-    // Documented type boundary: the registry returns the provider untyped; the
-    // `user-management` cap's `validateScopedToken` surface is asserted here
-    // (same shape the tRPC middleware relies on).
-    const userMgmt = capRegistry.getSingleton('user-management');
-    if (!userMgmt)
-        return null;
-    return userMgmt.validateScopedToken({ token });
-}
-function isUploadAllowed(scoped) {
-    return (0, scope_access_js_1.checkScopeAccess)(scoped.scopes, exports.UPLOAD_TRPC_PATH).ok;
-}
+const trpc_context_js_1 = require("./trpc/trpc.context.js");
 /**
- * Run the full upload auth chain. Returns `{ok: true}` on success, or the
- * HTTP status + error message the route should reply with:
- *   - 401 `Unauthorized` when no Authorization header is present,
- *   - 403 `Forbidden: <reason>` for any recognised-but-insufficient token.
+ * The upload gate: the ONE verifier, then `'*'` (D892, D895). Answers:
+ *   - 401 `Unauthorized` when no Authorization header is present, or the
+ *     bearer authenticates nobody (revoked, expired, never issued),
+ *   - 403 `Forbidden: admin only` for a principal that is not an admin.
  */
 async function authorizeUploadRequest(args) {
     const { authHeader, authService, addonRegistry } = args;
@@ -34,36 +24,11 @@ async function authorizeUploadRequest(args) {
         return { ok: false, status: 401, error: 'Unauthorized' };
     }
     const token = authHeader.replace('Bearer ', '');
-    let authReason;
-    // Try JWT first — fastest path + carries the isAdmin flag directly.
-    try {
-        const payload = authService.verifyToken(token);
-        if (payload.isAdmin) {
-            return { ok: true };
-        }
-        authReason = 'JWT is not admin';
-    }
-    catch {
-        // Not a JWT (or invalid signature) — fall through to scoped-token path.
-    }
-    try {
-        const record = await validateScopedTokenViaCap(addonRegistry, token);
-        if (!record) {
-            authReason = authReason ?? 'token not recognised';
-        }
-        else if (isUploadAllowed(record)) {
-            return { ok: true };
-        }
-        else {
-            authReason = `scoped token lacks create access on '${exports.UPLOAD_TRPC_PATH}'`;
-        }
-    }
-    catch (err) {
-        authReason = `scoped token validation failed: ${err instanceof Error ? err.message : String(err)}`;
+    const principal = await (0, trpc_context_js_1.hubCredentialVerifier)({ authService, addonRegistry }).verify(token);
+    if (principal === null) {
+        return { ok: false, status: 401, error: 'Unauthorized: token not recognised' };
     }
-    return {
-        ok: false,
-        status: 403,
-        error: `Forbidden: ${authReason ?? 'admin or upload-scoped token required'}`,
-    };
+    if (!principal.isAdmin)
+        return { ok: false, status: 403, error: 'Forbidden: admin only' };
+    return { ok: true };
 }

package/dist/auth/addon-route-auth.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authorizeAddonBearer = authorizeAddonBearer;
+exports.addonRouteCaller = addonRouteCaller;
+const types_1 = require("@camstack/types");
+const principal_authorization_js_1 = require("../api/trpc/principal-authorization.js");
+async function authorizeAddonBearer(input) {
+    const principal = await input.verifier.verify(input.bearer, input.facts ?? {});
+    if (principal === null) {
+        input.logger.warn('addon route: refused a bearer that authenticates nobody', {
+            meta: { addonId: input.target.addonId, method: input.target.method },
+        });
+        return { ok: false, status: 401, error: 'Invalid token' };
+    }
+    const verdict = (0, principal_authorization_js_1.authorizeAddonRoute)(principal.scopes, input.target);
+    if (!verdict.ok) {
+        input.logger.warn('addon route: refused a principal outside its scopes', {
+            meta: {
+                addonId: input.target.addonId,
+                method: input.target.method,
+                reason: verdict.reason,
+                credential: principal.auditTag,
+                credentialId: principal.credentialId,
+            },
+        });
+        return { ok: false, status: verdict.status, error: verdict.error };
+    }
+    return { ok: true, principal, shareHeaders: verdict.shareHeaders };
+}
+function addonRouteCaller(principal) {
+    const scoped = principal.scopes;
+    return {
+        user: { id: principal.subjectId, username: principal.username, isAdmin: principal.isAdmin },
+        ...(principal.isAdmin || principal.userDelegated
+            ? {}
+            : {
+                scopedToken: {
+                    id: principal.credentialId,
+                    userId: principal.subjectId,
+                    scopes: [...(0, types_1.capabilityScopesOf)(scoped)],
+                },
+            }),
+    };
+}

package/dist/auth/addon-route-share-gate.js

@@ -1,25 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SHARE_DEVICES_HEADER = exports.SHARE_KIND_HEADER = void 0;
-exports.gateAddonShareToken = gateAddonShareToken;
 exports.stripShareHeaders = stripShareHeaders;
+/**
+ * The data-plane gate's answer to a share-link token.
+ *
+ * A share link is a bearer credential for ONE view of a FEW devices, not a
+ * session: the hub's tRPC layer already confines it to a fail-closed method
+ * list per scope kind (`share-view-access.ts`). The data planes are reached
+ * outside tRPC, and until this module the gate resolved session JWTs and
+ * scoped tokens only — so the events embed under a share link listed its events
+ * and got 401 on every thumbnail (`EVENTS-EMBED.md` §7).
+ *
+ * Two rules. The first lives in the one scope matcher
+ * (`authorizeAddonRoute`, D892): a plane serves a share principal only when it
+ * OPTED IN to that kind (`AddonDataPlaneServeOptions.share`) — a plane that
+ * never reads the scope would otherwise serve every device to a link scoped to
+ * two. The second is here: the scope's devices reach the plane in headers the
+ * HUB sets after validation, and whatever the client sent under those names is
+ * stripped first — the gate is the only writer.
+ */
 exports.SHARE_KIND_HEADER = 'x-camstack-share-kind';
 exports.SHARE_DEVICES_HEADER = 'x-camstack-share-devices';
-function gateAddonShareToken(input) {
-    if (input.record === null)
-        return { ok: false, status: 401, error: 'Invalid token' };
-    const kind = input.record.scope.kind;
-    if (!(input.endpoint.share ?? []).includes(kind)) {
-        return { ok: false, status: 403, error: 'Share token not accepted here' };
-    }
-    return {
-        ok: true,
-        headers: {
-            [exports.SHARE_KIND_HEADER]: kind,
-            [exports.SHARE_DEVICES_HEADER]: input.record.scope.deviceIds.join(','),
-        },
-    };
-}
 /** The forwarded header set without any share header the client supplied. */
 function stripShareHeaders(headers) {
     const out = {};

package/dist/auth/credential-verifier.js

@@ -0,0 +1,236 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCredentialVerifier = createCredentialVerifier;
+const types_1 = require("@camstack/types");
+const trpc_error_principal_js_1 = require("../api/trpc/trpc-error-principal.js");
+const scope_escalation_js_1 = require("./scope-escalation.js");
+function stringClaim(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+/** What a non-admin person's session reaches on addon routes: every flavour, as before D892. */
+const SESSION_ADDON_ROUTES = {
+    type: 'addon-routes',
+    access: [...types_1.ALL_METHOD_ACCESS],
+};
+// ── Live scopes for a non-admin session ────────────────────────────────
+/**
+ * The JWT embeds scopes at login, so an admin's scope edit reached a live
+ * session only at the next login (2026-08-15). The store is re-read per user,
+ * memoized: a change propagates within the TTL and a busy session costs one
+ * store read per window. The JWT's copy is the fallback when the store is
+ * unreachable, so a hiccup never locks anybody out mid-request.
+ */
+const SCOPE_REFRESH_TTL_MS = 30_000;
+const SCOPE_REFRESH_MISS_TTL_MS = 5_000;
+const SCOPE_MEMO_MAX = 512;
+/**
+ * The user list, read at most once per {@link USERS_MEMO_TTL_MS}: every token
+ * and account-link verify asks whether its subject still exists and is still
+ * an admin, and that must not cost a full store read per request. A deletion
+ * or a demotion therefore applies within the window.
+ */
+const USERS_MEMO_TTL_MS = 5_000;
+function createCredentialVerifier(deps) {
+    const now = deps.now ?? Date.now;
+    const scopeMemo = deps.scopeMemo ?? new Map();
+    const usersMemo = deps.usersMemo ?? { entry: null };
+    const listUsersOnce = async () => {
+        const at = now();
+        const users = deps.users();
+        if (users === null || typeof users.listUsers !== 'function')
+            return null;
+        const cached = usersMemo.entry;
+        if (cached !== null && cached.source === users && at - cached.at < USERS_MEMO_TTL_MS) {
+            return cached.users;
+        }
+        try {
+            const fresh = await users.listUsers();
+            usersMemo.entry = { at, source: users, users: fresh };
+            return fresh;
+        }
+        catch {
+            return null;
+        }
+    };
+    const liveScopes = async (userId) => {
+        const at = now();
+        const cached = scopeMemo.get(userId);
+        if (cached !== undefined &&
+            at - cached.at < (cached.scopes === null ? SCOPE_REFRESH_MISS_TTL_MS : SCOPE_REFRESH_TTL_MS)) {
+            return cached.scopes;
+        }
+        const fresh = (await listUsersOnce())?.find((u) => u.id === userId);
+        const scopes = fresh === undefined ? null : (0, types_1.normalizeTokenScopes)(fresh.scopes ?? []);
+        scopeMemo.set(userId, { at, scopes });
+        if (scopeMemo.size > SCOPE_MEMO_MAX) {
+            for (const [key, entry] of scopeMemo) {
+                if (at - entry.at > SCOPE_REFRESH_TTL_MS * 4)
+                    scopeMemo.delete(key);
+            }
+        }
+        return scopes;
+    };
+    const subjectFacts = async (userId) => {
+        const all = await listUsersOnce();
+        if (all === null)
+            return null;
+        const user = all.find((u) => u.id === userId);
+        return user === undefined
+            ? { exists: false, isAdmin: false }
+            : { exists: true, isAdmin: user.isAdmin };
+    };
+    const auditAdminUse = (principal, facts, name) => {
+        const internal = deps.internal();
+        if (internal === null)
+            return;
+        void internal.audit
+            .record({
+            action: 'admin-token-used',
+            userId: principal.subjectId,
+            ...(facts.ip !== undefined ? { ip: facts.ip } : {}),
+            detail: {
+                tokenId: principal.credentialId,
+                name,
+                ...(facts.path !== undefined ? { path: facts.path } : {}),
+            },
+        })
+            .catch(() => { });
+    };
+    // ── The unified token ────────────────────────────────────────────────
+    /** `row`'s scopes cut down to what its (non-admin) subject holds now; `null` when unreadable. */
+    const narrowedToSubject = async (row) => {
+        const live = await liveScopes(row.subjectId);
+        if (live === null)
+            return null;
+        return (0, scope_escalation_js_1.intersectScopes)(row.scopes, live, deps.deviceScopeLookup);
+    };
+    const unifiedToken = async (claims, facts) => {
+        const rows = deps.tokenRows();
+        if (rows === null)
+            return null;
+        // Revocation and expiry live on the row, looked up by `jti` every time.
+        const row = await rows.lookupLive(claims.jti).catch(() => null);
+        if (row === null || row.subjectId !== claims.sub)
+            return null;
+        // The subject must still exist; an admin token dies with its subject's admin bit.
+        const subject = await subjectFacts(row.subjectId);
+        if (subject === null || !subject.exists)
+            return null;
+        if ((0, types_1.scopesGrantAdmin)(row.scopes) && !subject.isAdmin)
+            return null;
+        // The ROW's scopes, never the claim's: the row is what the operator listed.
+        // A non-admin's token never outgrows its subject: an admin who narrows the
+        // user narrows every token the user minted, at the next verify.
+        const scopes = subject.isAdmin ? row.scopes : await narrowedToSubject(row);
+        if (scopes === null || scopes.length === 0)
+            return null;
+        const principal = {
+            subjectId: row.subjectId,
+            username: `token:${row.label}`,
+            scopes,
+            isAdmin: (0, types_1.scopesGrantAdmin)(scopes),
+            credentialId: row.id,
+            auditTag: 'token',
+            interactive: false,
+            userDelegated: false,
+        };
+        if (principal.isAdmin)
+            auditAdminUse(principal, facts, row.label);
+        return principal;
+    };
+    // ── Session and account-link JWTs ────────────────────────────────────
+    /** A minted token's claims, or `null` when `token` is not one (D895: its own audience). */
+    const credentialClaims = (token) => {
+        try {
+            return deps.verifyCredentialJwt(token);
+        }
+        catch {
+            return null;
+        }
+    };
+    const hubJwt = async (token, facts) => {
+        let payload;
+        try {
+            payload = deps.verifyJwt(token);
+        }
+        catch {
+            // Not a session-family JWT. A minted token is refused by `verifyJwt` by
+            // construction (its audience), and verifies only through its own door.
+            const claims = credentialClaims(token);
+            return claims === null ? null : unifiedToken(claims, facts);
+        }
+        // A pre-v2 JWT (no `isAdmin`) would degrade into "non-admin, no scopes";
+        // refuse it so the client signs in again.
+        if (typeof payload.isAdmin !== 'boolean')
+            return null;
+        // Every token this hub mints verifies under one key, so a valid signature
+        // means "we minted this", never "this is an API credential" (D103). Only a
+        // session and an `oauth-access` link are credentials; a code, a refresh
+        // token, a bridge, a TOTP challenge are refused.
+        const classified = (0, types_1.classifyBearerPrincipal)(payload);
+        if (classified.kind === 'not-a-credential') {
+            deps.logger?.warn('auth: refused a bearer that is not an API credential', {
+                meta: { reason: classified.reason, userId: stringClaim(payload.userId) ?? 'unknown' },
+            });
+            return null;
+        }
+        const userId = stringClaim(payload.userId) ?? 'unknown';
+        const username = stringClaim(payload.username) ?? 'unknown';
+        if (classified.kind === 'integration') {
+            // An account link is governed by the grant the operator consented to,
+            // never by the linking user's record (2026-08-19), and never admin. Its
+            // subject must still be a user: a link minted for nobody (an empty
+            // `userId`) or for a deleted account authenticates nobody.
+            const subject = userId === 'unknown' || userId === '' ? null : await subjectFacts(userId);
+            if (subject === null || !subject.exists)
+                return null;
+            const identity = (0, trpc_error_principal_js_1.readCredentialIdentity)(payload);
+            return {
+                subjectId: userId,
+                username,
+                scopes: (0, types_1.normalizeTokenScopes)(payload.scopes ?? []),
+                isAdmin: false,
+                credentialId: identity.sessionId ?? `oauth:${userId}`,
+                auditTag: 'integration',
+                interactive: false,
+                userDelegated: true,
+                ...(identity.sessionId !== undefined ? { oauthSessionId: identity.sessionId } : {}),
+                ...(identity.credential !== undefined ? { credential: identity.credential } : {}),
+            };
+        }
+        const sessionId = stringClaim(payload.sid);
+        const base = {
+            subjectId: userId,
+            username,
+            credentialId: sessionId ?? `session:${userId}`,
+            auditTag: 'session',
+            interactive: true,
+            userDelegated: true,
+            ...(sessionId !== undefined ? { sessionId } : {}),
+        };
+        // A person's session always reaches its OWN account preferences (D894);
+        // `'*'` does not imply that grant, so the admin session names it too.
+        if (payload.isAdmin) {
+            return { ...base, scopes: [types_1.ADMIN_SCOPE, types_1.PREFERENCES_SELF_SCOPE], isAdmin: true };
+        }
+        const fresh = await liveScopes(userId);
+        const capability = fresh ?? (0, types_1.normalizeTokenScopes)(payload.scopes ?? []);
+        return {
+            ...base,
+            scopes: [...capability, SESSION_ADDON_ROUTES, types_1.PREFERENCES_SELF_SCOPE],
+            isAdmin: false,
+        };
+    };
+    return {
+        async verify(bearer, facts = {}) {
+            if (bearer === null || bearer === undefined || bearer === '')
+                return null;
+            try {
+                return await hubJwt(bearer, facts);
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}