Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

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.md
index 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 scope
The internal `SetupOrchestrator(orgID string)` callback binds only an already
diff --git a/docs/release-control/v6/internal/subsystems/security-privacy.md b/docs/release-control/v6/internal/subsystems/security-privacy.md
index 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 verifier
OIDC discovery, remote JWKS and signed ID tokens use go-oidc's real verifier
diff --git a/frontend-modern/src/api/__tests__/security.test.ts b/frontend-modern/src/api/__tests__/security.test.ts
index 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.ts
index 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.tsx
index 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>
<p
class={`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}>
<Card
tone="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()}>
<Card
tone="warning"
padding="sm"
diff --git a/frontend-modern/src/components/Settings/__tests__/APITokenManager.test.tsx b/frontend-modern/src/components/Settings/__tests__/APITokenManager.test.tsx
index 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.ts
index 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,