@camstack/server 1.2.603 → 1.2.605

package/dist/api/upload-auth.js

@@ -2,31 +2,32 @@
 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 (a session, a unified token, a legacy `csa_` / `cst_`)
+ * goes through the hub's one verifier; what may upload is decided by its
+ * scopes alone.
+ *
+ * REST endpoints share the scope-gate of the `addons.installPackage` cap
+ * method (semantically equivalent — both install a tarball under the
+ * system-scope `addons` cap with `create` access). Reusing the shared scope
+ * matcher keeps the gate in sync with the tRPC middleware — no parallel
+ * REST-only ACL. (Why not `addons.upload`? There is no `upload` method on
+ * the cap definition, so `METHOD_ACCESS_MAP` has no row for it and
+ * `checkScopeAccess` would fall through to deny.)
  */
-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");
+const principal_authorization_js_1 = require("./trpc/principal-authorization.js");
+exports.UPLOAD_TRPC_PATH = 'addons.installPackage';
 /**
- * Run the full upload auth chain. Returns `{ok: true}` on success, or the
- * HTTP status + error message the route should reply with:
+ * The upload gate: the ONE verifier, then the ONE scope matcher on the
+ * `addons.installPackage` path (D892) — `'*'`, or a grant of `create` on
+ * `addons`. Answers:
  *   - 401 `Unauthorized` when no Authorization header is present,
- *   - 403 `Forbidden: <reason>` for any recognised-but-insufficient token.
+ *   - 403 `Forbidden: <reason>` for a bearer that authenticates nobody or
+ *     holds no such grant.
  */
 async function authorizeUploadRequest(args) {
     const { authHeader, authService, addonRegistry } = args;
@@ -34,36 +35,12 @@ 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: 403, error: 'Forbidden: token not recognised' };
     }
-    return {
-        ok: false,
-        status: 403,
-        error: `Forbidden: ${authReason ?? 'admin or upload-scoped token required'}`,
-    };
+    const verdict = (0, principal_authorization_js_1.authorizeProcedure)(principal.scopes, exports.UPLOAD_TRPC_PATH, undefined);
+    if (verdict.ok)
+        return { ok: true };
+    return { ok: false, status: 403, error: `Forbidden: ${verdict.reason}` };
 }

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 `csv_*` share 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
+ * `cst_*` 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,277 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_SHARE_TOKEN_PREFIX = exports.LEGACY_SCOPED_TOKEN_PREFIX = exports.LEGACY_ADMIN_TOKEN_PREFIX = void 0;
+exports.createCredentialVerifier = createCredentialVerifier;
+const types_1 = require("@camstack/types");
+const trpc_error_principal_js_1 = require("../api/trpc/trpc-error-principal.js");
+/** Legacy wire prefixes — only to choose an adapter. */
+exports.LEGACY_ADMIN_TOKEN_PREFIX = 'csa_';
+exports.LEGACY_SCOPED_TOKEN_PREFIX = 'cst_';
+exports.LEGACY_SHARE_TOKEN_PREFIX = 'csv_';
+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;
+function createCredentialVerifier(deps) {
+    const now = deps.now ?? Date.now;
+    const scopeMemo = deps.scopeMemo ?? new Map();
+    const listUsersOnce = async () => {
+        const users = deps.users();
+        if (users === null || typeof users.listUsers !== 'function')
+            return null;
+        try {
+            return await users.listUsers();
+        }
+        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,
+                format: principal.legacy ? 'legacy' : 'token',
+                ...(facts.path !== undefined ? { path: facts.path } : {}),
+            },
+        })
+            .catch(() => { });
+    };
+    // ── Legacy adapters ──────────────────────────────────────────────────
+    const legacyAdminToken = async (token, facts) => {
+        const internal = deps.internal();
+        if (internal === null)
+            return null;
+        // Validation (creator still exists and is still an admin, not revoked, not
+        // expired) is local-auth's.
+        const record = await internal.adminTokens.validate(token).catch(() => null);
+        if (record === null)
+            return null;
+        const principal = {
+            subjectId: record.createdBy,
+            username: `admin-token:${record.name}`,
+            scopes: [types_1.ADMIN_SCOPE],
+            isAdmin: true,
+            credentialId: record.id,
+            auditTag: 'legacy-admin-token',
+            interactive: false,
+            userDelegated: false,
+            legacy: true,
+        };
+        auditAdminUse(principal, facts, record.name);
+        return principal;
+    };
+    const legacyScopedToken = async (token) => {
+        const users = deps.users();
+        if (users === null)
+            return null;
+        const record = await users.validateScopedToken({ token }).catch(() => null);
+        if (record === null)
+            return null;
+        return {
+            subjectId: record.userId,
+            username: `scoped:${record.tokenPrefix}`,
+            // A v2 `device:targets` grant migrates to a v3 selector here, so the
+            // matcher only ever sees v3.
+            scopes: (0, types_1.normalizeTokenScopes)(record.scopes),
+            isAdmin: false,
+            credentialId: record.id,
+            auditTag: 'legacy-scoped-token',
+            interactive: false,
+            userDelegated: false,
+            legacy: true,
+        };
+    };
+    const legacyShareToken = async (token) => {
+        const shares = deps.shareTokens();
+        if (shares === null)
+            return null;
+        const record = await shares.validate(token).catch(() => null);
+        if (record === null)
+            return null;
+        return {
+            subjectId: record.userId,
+            username: `share:${record.tokenPrefix}`,
+            scopes: [
+                {
+                    type: 'share-view',
+                    grant: {
+                        kind: record.scope.kind,
+                        deviceIds: [...record.scope.deviceIds],
+                        ...(record.scope.talk !== undefined ? { talk: record.scope.talk } : {}),
+                    },
+                },
+            ],
+            isAdmin: false,
+            credentialId: record.id,
+            auditTag: 'legacy-share-token',
+            interactive: false,
+            userDelegated: false,
+            legacy: true,
+        };
+    };
+    // ── The unified token ────────────────────────────────────────────────
+    const unifiedToken = async (payload, facts) => {
+        const claims = types_1.CredentialTokenClaimsSchema.safeParse(payload);
+        if (!claims.success)
+            return null;
+        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.data.jti).catch(() => null);
+        if (row === null || row.subjectId !== claims.data.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;
+        const principal = {
+            subjectId: row.subjectId,
+            username: `token:${row.label}`,
+            // The ROW's scopes, never the claim's: the row is what the operator listed.
+            scopes: row.scopes,
+            isAdmin: (0, types_1.scopesGrantAdmin)(row.scopes),
+            credentialId: row.id,
+            auditTag: 'token',
+            interactive: false,
+            userDelegated: false,
+            legacy: false,
+        };
+        if (principal.isAdmin)
+            auditAdminUse(principal, facts, row.label);
+        return principal;
+    };
+    // ── Session and account-link JWTs ────────────────────────────────────
+    const hubJwt = async (token, facts) => {
+        let payload;
+        try {
+            payload = deps.verifyJwt(token);
+        }
+        catch {
+            return null;
+        }
+        if (payload.kind === types_1.CREDENTIAL_TOKEN_KIND)
+            return unifiedToken(payload, 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.
+            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,
+                legacy: false,
+                ...(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,
+            legacy: false,
+            ...(sessionId !== undefined ? { sessionId } : {}),
+        };
+        if (payload.isAdmin)
+            return { ...base, scopes: [types_1.ADMIN_SCOPE], isAdmin: true };
+        const fresh = await liveScopes(userId);
+        const capability = fresh ?? (0, types_1.normalizeTokenScopes)(payload.scopes ?? []);
+        return { ...base, scopes: [...capability, SESSION_ADDON_ROUTES], isAdmin: false };
+    };
+    return {
+        async verify(bearer, facts = {}) {
+            if (bearer === null || bearer === undefined || bearer === '')
+                return null;
+            try {
+                if (bearer.startsWith(exports.LEGACY_ADMIN_TOKEN_PREFIX))
+                    return await legacyAdminToken(bearer, facts);
+                if (bearer.startsWith(exports.LEGACY_SHARE_TOKEN_PREFIX))
+                    return await legacyShareToken(bearer);
+                if (bearer.startsWith(exports.LEGACY_SCOPED_TOKEN_PREFIX))
+                    return await legacyScopedToken(bearer);
+                return await hubJwt(bearer, facts);
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}

package/dist/auth/scope-escalation.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scopesWithin = scopesWithin;
+const types_1 = require("@camstack/types");
+const principal_visibility_js_1 = require("../api/trpc/principal-visibility.js");
+function accessCovered(asked, held) {
+    return asked.every((a) => held.includes(a));
+}
+/** The grant without its access list, as a comparable key. */
+function grantKey(scope) {
+    if (scope.type === 'device') {
+        return JSON.stringify({
+            type: scope.type,
+            selector: scope.selector,
+            includeLinked: scope.includeLinked ?? null,
+        });
+    }
+    return JSON.stringify({ type: scope.type, target: scope.target });
+}
+function describe(scope) {
+    if (scope === types_1.ADMIN_SCOPE)
+        return "'*'";
+    if (scope.type === 'share-view')
+        return `share-view:${scope.grant.kind}`;
+    if (scope.type === 'addon-routes')
+        return `addon-routes[${scope.access.join(',')}]`;
+    if (scope.type === 'device')
+        return `device[${scope.access.join(',')}]`;
+    return `${scope.type}:${scope.target}[${scope.access.join(',')}]`;
+}
+function scopesWithin(requested, held, lookup) {
+    if ((0, types_1.scopesGrantAdmin)(held))
+        return { ok: true };
+    const heldCapability = (0, types_1.capabilityScopesOf)(held);
+    for (const scope of requested) {
+        if (scope === types_1.ADMIN_SCOPE) {
+            return { ok: false, reason: "only an admin can mint '*'" };
+        }
+        if (scope.type === 'share-view') {
+            const viewable = (0, principal_visibility_js_1.filterViewableDeviceIds)(heldCapability, scope.grant.deviceIds, lookup);
+            if (viewable.length !== scope.grant.deviceIds.length) {
+                return { ok: false, reason: 'a share-view grant names a device you cannot view' };
+            }
+            continue;
+        }
+        if (scope.type === 'addon-routes') {
+            const covered = held.some((h) => h !== types_1.ADMIN_SCOPE && h.type === 'addon-routes' && accessCovered(scope.access, h.access));
+            if (!covered)
+                return { ok: false, reason: `you do not hold ${describe(scope)}` };
+            continue;
+        }
+        const key = grantKey(scope);
+        const covered = heldCapability.some((h) => grantKey(h) === key && accessCovered(scope.access, h.access));
+        if (!covered)
+            return { ok: false, reason: `you do not hold ${describe(scope)}` };
+    }
+    return { ok: true };
+}

package/dist/core/addon/addon-registry.service.js

@@ -391,6 +391,7 @@ class AddonRegistryService {
     clusterNodeHistoryStore = null;
     clusterAgentRecords = null;
     shareTokenService = null;
+    credentialTokenService = null;
     // Device architecture — in-memory registry of live IDevice instances.
     // Persistence is owned by the `device-manager` capability addon.
     deviceRegistry = new system_1.DeviceRegistry();
@@ -1381,6 +1382,10 @@ class AddonRegistryService {
     setShareTokenService(service) {
         this.shareTokenService = service;
     }
+    /** The unified token store (D892), bound to its `core-auth` records with the share links. */
+    setCredentialTokenService(service) {
+        this.credentialTokenService = service;
+    }
     async wireHubMainOrphanRecords(store) {
         const recordsCap = this.capabilityRegistry.getSingleton('records');
         if (recordsCap === null || recordsCap === undefined)
@@ -1400,6 +1405,18 @@ class AddonRegistryService {
             await coreRecords.declare(record_kinds_js_1.coreAuthRecordKinds);
             const shareKind = coreRecords.kind(record_kinds_js_1.coreAuthRecordKinds['share-view-tokens']);
             shareTokens.bindShareTokensKind(() => shareKind);
+            const credentialTokens = this.credentialTokenService;
+            if (credentialTokens !== null) {
+                const tokenKind = coreRecords.kind(record_kinds_js_1.coreAuthRecordKinds['credential-tokens']);
+                credentialTokens.bindKind(() => tokenKind);
+                // Dead rows (expired or revoked > 30 days) go at boot; the verifier
+                // already refuses them, so this is housekeeping, never a gate.
+                void credentialTokens.reap().catch((error) => {
+                    this.logger.warn('Token reap failed', {
+                        meta: { error: error instanceof Error ? error.message : String(error) },
+                    });
+                });
+            }
         }
     }
     /**