Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Keep unread API token inventory distinct from empty
pulse-triage[bot]7993594972d8
diff --git a/docs/release-control/v6/internal/subsystems/api-contracts.md b/docs/release-control/v6/internal/subsystems/api-contracts.mdindex 8711d7d867..a44d211722 100644--- a/docs/release-control/v6/internal/subsystems/api-contracts.md+++ b/docs/release-control/v6/internal/subsystems/api-contracts.md@@ -21,6 +21,30 @@## Purpose+### Token inventory must be read before absence is presented++The API Access consumer distinguishes loading, failed and accepted token+inventories. Pending reads show nonnumeric loading values; rejected reads keep+counts and scope posture unknown, with persistent bounded feedback and an+explicit Retry token inventory action. Only an accepted empty list establishes+zero visible tokens. Counts describe credentials visible to the account, not+instance-wide access. Retry invokes only the existing list read, admits one+consumer request at a time and preserves creation drafts and selected scopes.+It neither grants write authority nor replays a token mutation.++`SecurityAPI.listTokens` rejects missing, malformed or partially unreadable+inventories as a whole, including invalid record identities/scopes and duplicate+IDs. It never drops bad members into a plausible smaller list. Explicit empty+arrays and legacy nil lists remain empty; absent/nil/empty record scopes retain+their legacy full-access meaning and unknown string scopes remain visible.+Unread inventory cannot drive the existing token-absence reconciliation.++Normal-suite `security.test.ts` and `APITokenManager.test.tsx` cover admission,+loading, denial/failure, repeat retry, accepted empty and populated results,+draft preservation, partial local creation and unchanged read-only controls.+Desktop/narrow browser verification exercises the real API Access producer and+consumer using safe HTTP responses, not a replacement component page.+### Lazy investigation setup keeps the resolved service scopeThe internal `SetupOrchestrator(orgID string)` callback binds only an alreadydiff --git a/docs/release-control/v6/internal/subsystems/security-privacy.md b/docs/release-control/v6/internal/subsystems/security-privacy.mdindex 36fd491625..9ff68a50a3 100644--- a/docs/release-control/v6/internal/subsystems/security-privacy.md+++ b/docs/release-control/v6/internal/subsystems/security-privacy.md@@ -18,6 +18,30 @@## Purpose+### Unread token inventory is not a safe access posture++API Access never claims no credentials or no full-access credentials from a+pending, denied, failed or malformed inventory read. Counts remain nonnumeric+until a complete supported response is admitted; inventory totals describe+only credentials visible to the caller. Malformed members and duplicate IDs+reject the whole response rather than inventing absence or a smaller inventory.+Legacy explicit nil lists and missing/nil/empty scope lists retain their existing+empty-inventory and full-access meanings respectively.++Persistent fixed-text feedback does not render server error bodies. Its explicit+retry runs the existing read only, one consumer request at a time; it preserves+token-name/scope drafts and existing read-only write restrictions. Creation of+one known token does not establish a complete inventory after an unread list.+Failed reads do not trigger the existing absent-token revocation reconciliation.+No server authorisation, session, scope, token reveal or mutation rule changes.++Normal-suite `security.test.ts` and `APITokenManager.test.tsx` cover invalid+envelopes/members/scopes, supported legacy shapes, pending and repeated failed+reads, explicit empty recovery, draft and authority preservation. Browser proof+uses safe denied/failed/malformed/populated/empty responses through the real+Settings consumer at desktop and narrow widths; it is not installed account+recovery or a claim about the separate private authoriser repair.+### OIDC retains the bounded JOSE key and token verifierOIDC discovery, remote JWKS and signed ID tokens use go-oidc's real verifierdiff --git a/frontend-modern/src/api/__tests__/security.test.ts b/frontend-modern/src/api/__tests__/security.test.tsindex 43cf24443a..9a217959ba 100644--- a/frontend-modern/src/api/__tests__/security.test.ts+++ b/frontend-modern/src/api/__tests__/security.test.ts@@ -60,6 +60,7 @@ describe('SecurityAPI', () => {});describe('listTokens', () => {+ const record = { id: 't1', name: 'Known', prefix: 'pmp_', suffix: '1234', createdAt: '' };it('fetches all tokens', async () => {const mockTokens: APITokenRecord[] = [{@@ -87,17 +88,22 @@ describe('SecurityAPI', () => {expect(result).toEqual([]);});- it.each([- null,- [],- {},- { tokens: 'bad' },- { tokens: {} },- { tokens: [null] },- { tokens: [{ id: 't1', scopes: 'monitoring:read' }] },- { tokens: [{ id: 't1', scopes: [null] }] },- { tokens: [{ id: '' }] },- ])('rejects an unreadable inventory instead of inventing absence (%j)', async (response) => {+ it.each(+ [+ null,+ [],+ {},+ { tokens: 'bad' },+ { tokens: {} },+ { tokens: [null] },+ { tokens: [{ ...record, scopes: 'monitoring:read' }] },+ { tokens: [{ ...record, scopes: [null] }] },+ { tokens: [{ ...record, scopes: [''] }] },+ { tokens: [{ ...record, id: '' }] },+ { tokens: [{ ...record, name: {} }] },+ { tokens: [record, record] },+ ].map((response) => ({ response })),+ )('rejects an unreadable inventory instead of inventing absence (%j)', async ({ response }) => {vi.mocked(apiFetchJSON).mockResolvedValueOnce(response);await expect(SecurityAPI.listTokens()).rejects.toThrow('Invalid API token inventory.');expect(apiFetchJSON).toHaveBeenCalledTimes(1);@@ -120,9 +126,9 @@ describe('SecurityAPI', () => {await expect(SecurityAPI.listTokens()).rejects.toThrow('Invalid API token inventory.');});- it.each([undefined, null, [], ['*'], ['future:scope']])(+ it.each([undefined, null, [], ['*'], ['future:scope']].map((scopes) => ({ scopes })))('preserves supported and legacy scopes (%j)',- async (scopes) => {+ async ({ scopes }) => {const token = { id: 't1', name: '', prefix: 'pmp_', suffix: '1234', createdAt: '', scopes };vi.mocked(apiFetchJSON).mockResolvedValueOnce({ tokens: [token] });await expect(SecurityAPI.listTokens()).resolves.toEqual([token]);diff --git a/frontend-modern/src/api/security.ts b/frontend-modern/src/api/security.tsindex a72132eeda..98a7381095 100644--- a/frontend-modern/src/api/security.ts+++ b/frontend-modern/src/api/security.ts@@ -1,10 +1,26 @@import { apiFetchJSON } from '@/utils/apiClient';import type { SecurityStatus } from '@/types/config';import type { APITokenRecord as APITokenRecordModel } from '@/types/api';-import { objectArrayFieldOrEmpty } from './responseUtils';export type APITokenRecord = APITokenRecordModel;+function isTokenInventoryRecord(value: unknown): value is APITokenRecord {+ if (!value || typeof value !== 'object' || Array.isArray(value)) return false;+ const record = value as Record<string, unknown>;+ return (+ ['id', 'name', 'prefix', 'suffix', 'createdAt'].every(+ (key) => typeof record[key] === 'string',+ ) &&+ (record.id as string).trim().length > 0 &&+ ['lastUsedAt', 'expiresAt', 'ownerUserId'].every(+ (key) => record[key] == null || typeof record[key] === 'string',+ ) &&+ (record.scopes == null ||+ (Array.isArray(record.scopes) &&+ record.scopes.every((scope) => typeof scope === 'string' && scope.trim().length > 0)))+ );+}+export interface CreateAPITokenResponse {token: string;record: APITokenRecord;@@ -23,8 +39,17 @@ export class SecurityAPI {}static async listTokens(): Promise<APITokenRecord[]> {- const response = await apiFetchJSON<{ tokens: APITokenRecord[] }>('/api/security/tokens');- return objectArrayFieldOrEmpty<APITokenRecord>(response, 'tokens');+ const response = await apiFetchJSON<unknown>('/api/security/tokens');+ if (response && typeof response === 'object' && !Array.isArray(response)) {+ const tokens = (response as { tokens?: unknown }).tokens;+ // A legacy nil list is explicitly empty; a missing or malformed list is not.+ if (tokens === null) return [];+ if (Array.isArray(tokens) && tokens.every(isTokenInventoryRecord)) {+ const ids = new Set(tokens.map((token) => token.id));+ if (ids.size === tokens.length) return tokens;+ }+ }+ throw new Error('Invalid API token inventory.');}static async createToken(name?: string, scopes?: string[]): Promise<CreateAPITokenResponse> {diff --git a/frontend-modern/src/components/Settings/APITokenManager.tsx b/frontend-modern/src/components/Settings/APITokenManager.tsxindex 505e3a70fc..59e61a43b3 100644--- a/frontend-modern/src/components/Settings/APITokenManager.tsx+++ b/frontend-modern/src/components/Settings/APITokenManager.tsx@@ -3,6 +3,7 @@ import { Card } from '@/components/shared/Card';import { ExternalTextLink } from '@/components/shared/ExternalTextLink';import { SectionHeader } from '@/components/shared/SectionHeader';import { LoadingSpinner } from '@/components/shared/LoadingSpinner';+import { InlineNotice } from '@/components/shared/InlineNotice';import { PulseDataGrid } from '@/components/shared/PulseDataGrid';import { SelectablePillButton } from '@/components/shared/SelectablePillButton';import BadgeCheck from 'lucide-solid/icons/badge-check';@@ -64,6 +65,9 @@ export const APITokenManager: Component<APITokenManagerProps> = (props) => {isRenaming,isRevealActiveForCurrentToken,loading,+ loadError,+ loadTokens,+ tokensLoaded,nameInput,newMonitoringKioskLink,newTokenRecord,@@ -375,14 +379,18 @@ export const APITokenManager: Component<APITokenManagerProps> = (props) => {<div class="text-[0.7rem] font-semibold uppercase tracking-wide text-muted">Total tokens</div>- <div class="mt-1 text-2xl font-semibold text-base-content">{totalTokens()}</div>- <p class="mt-1 text-xs text-muted">Stored credentials across all agents</p>+ <div class="mt-1 text-2xl font-semibold text-base-content">+ {tokensLoaded() ? totalTokens() : loading() ? 'Loading…' : 'Unknown'}+ </div>+ <p class="mt-1 text-xs text-muted">Credentials visible to this account</p></div><div class="rounded-md border border-border p-4 text-sm shadow-xs"><div class="text-[0.7rem] font-semibold uppercase tracking-wide text-muted">Scoped tokens</div>- <div class="mt-1 text-2xl font-semibold text-base-content">{scopedTokenCount()}</div>+ <div class="mt-1 text-2xl font-semibold text-base-content">+ {tokensLoaded() ? scopedTokenCount() : loading() ? 'Loading…' : 'Unknown'}+ </div><p class="mt-1 text-xs text-muted">Limited access tokens with defined scopes</p></div><div@@ -400,22 +408,50 @@ export const APITokenManager: Component<APITokenManagerProps> = (props) => {hasWildcardTokens() ? 'text-amber-800 dark:text-amber-100' : 'text-base-content'}`}>- {wildcardCount()}+ {tokensLoaded() ? wildcardCount() : loading() ? 'Loading…' : 'Unknown'}</div><pclass={`mt-1 text-xs ${hasWildcardTokens() ? 'text-amber-700 dark:text-amber-200' : 'text-muted'}`}>- {hasWildcardTokens()- ? 'Legacy wildcard tokens – rotate into scoped presets when possible.'- : 'All tokens scoped – no wildcard credentials detected.'}+ {!tokensLoaded()+ ? 'Token scopes have not been checked.'+ : hasWildcardTokens()+ ? 'Legacy wildcard tokens – rotate into scoped presets when possible.'+ : 'No full access tokens in this inventory.'}</p></div></div></div></Card>+ <Show when={loading()}>+ <Card+ padding="md"+ class="flex items-center gap-2"+ role="status"+ aria-label="Loading token inventory"+ >+ <LoadingSpinner size="md" tone="info" />+ <span class="text-sm text-muted">Loading token inventory…</span>+ </Card>+ </Show>++ <Show when={!loading() && loadError()}>+ {(message) => (+ <InlineNotice+ role="alert"+ tone="danger"+ actionLabel="Retry token inventory"+ actionOnClick={() => void loadTokens()}+ >+ <p>{message()}</p>+ <p>Existing credentials have not been changed. Retry to check their scopes.</p>+ </InlineNotice>+ )}+ </Show>+<Show when={props.refreshing}><Cardtone="info"@@ -487,23 +523,25 @@ export const APITokenManager: Component<APITokenManagerProps> = (props) => {</Show><Show- when={!loading() && totalTokens() > 0}+ when={tokensLoaded() && totalTokens() > 0}fallback={- <Card- tone="muted"- padding="md"- class="border border-dashed border-border text-sm text-muted"- >- No tokens yet.{' '}- <button- onClick={focusCreateSection}- disabled={!canManage()}- class="font-medium text-blue-600 underline-offset-2 hover:underline dark:text-blue-400"+ <Show when={tokensLoaded()}>+ <Card+ tone="muted"+ padding="md"+ class="border border-dashed border-border text-sm text-muted">- Create one- </button>{' '}- to authenticate agents and integrations.- </Card>+ No tokens yet.{' '}+ <button+ onClick={focusCreateSection}+ disabled={!canManage()}+ class="font-medium text-blue-600 underline-offset-2 hover:underline dark:text-blue-400"+ >+ Create one+ </button>{' '}+ to authenticate agents and integrations.+ </Card>+ </Show>}><Card padding="none" tone="card" class="overflow-hidden">@@ -771,7 +809,7 @@ export const APITokenManager: Component<APITokenManagerProps> = (props) => {</div></Card>- <Show when={!loading() && hasWildcardTokens()}>+ <Show when={tokensLoaded() && hasWildcardTokens()}><Cardtone="warning"padding="sm"diff --git a/frontend-modern/src/components/Settings/__tests__/APITokenManager.test.tsx b/frontend-modern/src/components/Settings/__tests__/APITokenManager.test.tsxindex 9a419cc955..5ebb6970f2 100644--- a/frontend-modern/src/components/Settings/__tests__/APITokenManager.test.tsx+++ b/frontend-modern/src/components/Settings/__tests__/APITokenManager.test.tsx@@ -421,6 +421,35 @@ describe('APITokenManager', () => {expect(renameTokenMock).not.toHaveBeenCalled();});+ it('keeps inventory recovery explicit across repeated failures before accepting empty', async () => {+ listTokensMock+ .mockRejectedValueOnce(new Error('unavailable'))+ .mockRejectedValueOnce(new Error('still unavailable'))+ .mockResolvedValueOnce([]);+ mockResources = [+ makeResource({+ platformData: { agent: { agentId: 'agent-1', tokenId: 'unread-token' } },+ }),+ ];+ render(() => <APITokenManager canManage />);+ fireEvent.click(await screen.findByRole('button', { name: 'Retry token inventory' }));+ await screen.findByRole('button', { name: 'Retry token inventory' });+ expect(listTokensMock).toHaveBeenCalledTimes(2);+ expect(screen.getAllByText('Unknown')).toHaveLength(3);+ expect(screen.queryByText(/No tokens yet/)).not.toBeInTheDocument();+ expect(markAgentsTokenRevokedMock).not.toHaveBeenCalled();+ fireEvent.click(screen.getByRole('button', { name: 'Retry token inventory' }));+ await screen.findByText(/No tokens yet/);+ expect(listTokensMock).toHaveBeenCalledTimes(3);+ expect(screen.getAllByText('0')).toHaveLength(3);+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();+ expect(markAgentsTokenRevokedMock).toHaveBeenCalledWith('unread-token', ['agent-1']);+ expect(createTokenMock).not.toHaveBeenCalled();+ expect(deleteTokenMock).not.toHaveBeenCalled();+ expect(updateTokenScopesMock).not.toHaveBeenCalled();+ expect(renameTokenMock).not.toHaveBeenCalled();+ });+it('does not call a partially known inventory complete after creating a token', async () => {listTokensMock.mockRejectedValueOnce(new Error('unavailable'));render(() => <APITokenManager canManage />);diff --git a/frontend-modern/src/components/Settings/useAPITokenManagerState.ts b/frontend-modern/src/components/Settings/useAPITokenManagerState.tsindex 2902383fc0..f94473d4b3 100644--- a/frontend-modern/src/components/Settings/useAPITokenManagerState.ts+++ b/frontend-modern/src/components/Settings/useAPITokenManagerState.ts@@ -73,6 +73,7 @@ export const useAPITokenManagerState = (props: APITokenManagerProps) => {const [tokens, setTokens] = createSignal<APITokenRecord[]>([]);const [tokensLoaded, setTokensLoaded] = createSignal(false);const [loading, setLoading] = createSignal(true);+ const [loadError, setLoadError] = createSignal<string | null>(null);const [isGenerating, setIsGenerating] = createSignal(false);const [updatingTokenId, setUpdatingTokenId] = createSignal<string | null>(null);const [isRenaming, setIsRenaming] = createSignal(false);@@ -160,17 +161,23 @@ export const useAPITokenManagerState = (props: APITokenManagerProps) => {if (routeFocusTimer) window.clearTimeout(routeFocusTimer);});+ let tokenReadInFlight = false;const loadTokens = async () => {+ if (tokenReadInFlight) return;+ tokenReadInFlight = true;setLoading(true);setTokensLoaded(false);+ setLoadError(null);try {const list = await SecurityAPI.listTokens();setTokens(list);setTokensLoaded(true);} catch (err) {+ setLoadError(getAPITokensLoadErrorMessage());logger.error('Failed to load API tokens', err);notificationStore.error(getAPITokensLoadErrorMessage());} finally {+ tokenReadInFlight = false;setLoading(false);}};@@ -507,6 +514,9 @@ export const useAPITokenManagerState = (props: APITokenManagerProps) => {isRenaming,isRevealActiveForCurrentToken,loading,+ loadError,+ loadTokens,+ tokensLoaded,nameInput,newMonitoringKioskLink,newTokenRecord,