Skip to content

Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.

Add silent vault mutation scope support (#2159)

Leendert de Borst43aa9beb1499
diff --git a/apps/browser-extension/src/entrypoints/background/VaultMessageHandler.ts b/apps/browser-extension/src/entrypoints/background/VaultMessageHandler.ts
index c1ce8987d..b8d886bdc 100644
--- a/apps/browser-extension/src/entrypoints/background/VaultMessageHandler.ts
+++ b/apps/browser-extension/src/entrypoints/background/VaultMessageHandler.ts
@@ -38,8 +38,9 @@ import type { SaveLoginResponse } from '@/utils/types/messaging/SaveLoginRespons
import type { StringResponse as stringResponse } from '@/utils/types/messaging/StringResponse';
import type { VaultResponse as messageVaultResponse } from '@/utils/types/messaging/VaultResponse';
import type { VaultUploadResponse as messageVaultUploadResponse } from '@/utils/types/messaging/VaultUploadResponse';
-import { type VaultMutationScope, ALL_VAULT_MUTATION_SCOPES, DEFAULT_VAULT_MUTATION_SCOPE, isManifestScope } from '@/utils/types/VaultMutationScope';
+import { type VaultMutationScope, DEFAULT_VAULT_MUTATION_SCOPE, hasUserVisibleScope, isManifestScope } from '@/utils/types/VaultMutationScope';
import { VaultCodec } from '@/utils/VaultCodec';
+import { clearDirtyScopes, getDirtyScopes } from '@/utils/VaultDirtyState';
import { VaultKeyService } from '@/utils/VaultKeyService';
import { vaultRequiresManifestMigration } from '@/utils/VaultManifestMigration';
import { vaultMergeService } from '@/utils/VaultMergeService';
@@ -712,27 +713,6 @@ export async function handleGetEncryptionKeyDerivationParams(
return await getStorageItem<EncryptionKeyDerivationParams>(StorageKeys.ENCRYPTION_KEY_DERIVATION_PARAMS);
}
-/**
- * Read the set of currently-dirty mutation scopes from their independent per-scope flags. Each scope is a
- * separate idempotent boolean key (see {@link dirtyScopeStorageKey}), so concurrent mutations can never
- * clobber each other's scope the way pushing onto one shared array could. Returns the dirty scopes in the
- * stable {@link ALL_VAULT_MUTATION_SCOPES} order.
- */
-async function getDirtyScopes(): Promise<VaultMutationScope[]> {
- const flags = await Promise.all(
- ALL_VAULT_MUTATION_SCOPES.map(async scope => ((await storage.getItem(dirtyScopeStorageKey(scope))) === true ? scope : null))
- );
- return flags.filter((s): s is VaultMutationScope => s !== null);
-}
-
-/**
- * Clear every per-scope dirty flag. Called once a sync has confirmed all pending changes are on the server
- * (guarded by the mutation-sequence check in {@link handleMarkVaultClean}).
- */
-async function clearDirtyScopes(): Promise<void> {
- await storage.removeItems(ALL_VAULT_MUTATION_SCOPES.map(scope => dirtyScopeStorageKey(scope)));
-}
-
/**
* Push only the data buckets named by the dirty scopes, no manifest upload. Used when every pending local
* mutation since the last sync is bucket-scoped (e.g. a settings toggle): the server's vault content manifest
@@ -1509,11 +1489,13 @@ async function handleFullVaultSyncInternal(): Promise<FullVaultSyncResult> {
}
/*
- * Announce the sync phase to the popup so it can show the right indicator.
+ * Announce the sync phase to the popup so it can show the right indicator. A push that carries nothing but
+ * silent scopes (item usage statistics) stays unannounced: it is bookkeeping the user never initiated, so a
+ * spinner for it would only imply something is at stake.
*/
if (needsPull) {
broadcastSyncPhase('pull');
- } else if (syncState.isDirty) {
+ } else if (syncState.isDirty && hasUserVisibleScope(await getDirtyScopes())) {
broadcastSyncPhase('push');
}
diff --git a/apps/browser-extension/src/entrypoints/popup/components/Dialogs/LogoutConfirmModal.tsx b/apps/browser-extension/src/entrypoints/popup/components/Dialogs/LogoutConfirmModal.tsx
index 5438da306..be2b1231d 100644
--- a/apps/browser-extension/src/entrypoints/popup/components/Dialogs/LogoutConfirmModal.tsx
+++ b/apps/browser-extension/src/entrypoints/popup/components/Dialogs/LogoutConfirmModal.tsx
@@ -3,9 +3,7 @@ import { useTranslation } from 'react-i18next';
import ModalWrapper from '@/entrypoints/popup/components/Dialogs/ModalWrapper';
-import { StorageKeys } from '@/utils/constants/storageKeys';
-
-import { storage } from '#imports';
+import { hasUnsyncedUserChanges } from '@/utils/VaultDirtyState';
interface ILogoutConfirmModalProps {
isOpen: boolean;
@@ -23,35 +21,37 @@ const LogoutConfirmModal: React.FC<ILogoutConfirmModalProps> = ({
onConfirm
}) => {
const { t } = useTranslation();
- const [isDirty, setIsDirty] = useState<boolean | null>(null);
+ const [hasPendingChanges, setHasPendingChanges] = useState<boolean | null>(null);
/**
- * Check sync state every time the modal opens. The dirty flag lives in
+ * Check sync state every time the modal opens. The dirty flags live in
* local storage, so a direct read is equivalent to (and faster than) a
* round-trip through the background script. The cancellation flag prevents
* a stale response from overwriting state if the modal is closed and
- * reopened before this read resolves.
+ * reopened before this read resolves. Silent scopes (e.g. item usage
+ * statistics) are excluded: warning about losing a last-used timestamp only
+ * makes the user doubt a logout that costs them nothing.
*/
useEffect(() => {
if (!isOpen) {
- setIsDirty(null);
+ setHasPendingChanges(null);
return;
}
let cancelled = false;
- setIsDirty(null);
+ setHasPendingChanges(null);
(async () : Promise<void> => {
try {
- const dirty = await storage.getItem(StorageKeys.IS_DIRTY) as boolean | null;
+ const pending = await hasUnsyncedUserChanges();
if (!cancelled) {
- setIsDirty(dirty ?? false);
+ setHasPendingChanges(pending);
}
} catch (error) {
console.error('Failed to check sync state:', error);
if (!cancelled) {
// Default to showing the simple logout confirmation on error
- setIsDirty(false);
+ setHasPendingChanges(false);
}
}
})();
@@ -62,12 +62,12 @@ const LogoutConfirmModal: React.FC<ILogoutConfirmModalProps> = ({
}, [isOpen]);
// Don't render anything if not open or still loading
- if (!isOpen || isDirty === null) {
+ if (!isOpen || hasPendingChanges === null) {
return null;
}
// Render dirty logout warning modal
- if (isDirty) {
+ if (hasPendingChanges) {
return (
<ModalWrapper
isOpen={isOpen}
diff --git a/apps/browser-extension/src/entrypoints/popup/components/Layout/ServerSyncIndicator.tsx b/apps/browser-extension/src/entrypoints/popup/components/Layout/ServerSyncIndicator.tsx
index 37c8422a9..e2f8aa42e 100644
--- a/apps/browser-extension/src/entrypoints/popup/components/Layout/ServerSyncIndicator.tsx
+++ b/apps/browser-extension/src/entrypoints/popup/components/Layout/ServerSyncIndicator.tsx
@@ -50,13 +50,13 @@ const ServerSyncIndicator: React.FC = () => {
* Only surface the pending indicator when the vault has stayed dirty for the grace period.
*/
useEffect(() => {
- if (!dbContext.isDirty) {
+ if (!dbContext.hasUnsyncedUserChanges) {
setShowPending(false);
return;
}
const timer = setTimeout((): void => setShowPending(true), PENDING_DISPLAY_DELAY);
return (): void => clearTimeout(timer);
- }, [dbContext.isDirty]);
+ }, [dbContext.hasUnsyncedUserChanges]);
/**
* Handle syncing state changes with minimum display time.
@@ -168,7 +168,7 @@ const ServerSyncIndicator: React.FC = () => {
d="M18.364 5.636a9 9 0 010 12.728m0 0l-2.829-2.829m2.829 2.829L21 21M15.536 8.464a5 5 0 010 7.072m0 0l-2.829-2.829m-4.243 2.829a4.978 4.978 0 01-1.414-2.83m-1.414 5.658a9 9 0 01-2.167-9.238m7.824 2.167a1 1 0 111.414 1.414m-1.414-1.414L3 3m8.293 8.293l1.414 1.414"
/>
</svg>
- {dbContext.isDirty && (
+ {dbContext.hasUnsyncedUserChanges && (
<span className="absolute -top-0.5 -right-0.5 w-2 h-2 bg-red-500 rounded-full" />
)}
</>
diff --git a/apps/browser-extension/src/entrypoints/popup/context/DbContext.tsx b/apps/browser-extension/src/entrypoints/popup/context/DbContext.tsx
index 96a2404a4..5862a2a1a 100644
--- a/apps/browser-extension/src/entrypoints/popup/context/DbContext.tsx
+++ b/apps/browser-extension/src/entrypoints/popup/context/DbContext.tsx
@@ -8,6 +8,7 @@ import SqliteClient from '@/utils/SqliteClient';
import { getStorageItem } from '@/utils/StorageUtility';
import { AppErrorCode, formatErrorWithCode } from '@/utils/types/errors/AppErrorCodes';
import type { VaultResponse as messageVaultResponse } from '@/utils/types/messaging/VaultResponse';
+import { hasUnsyncedUserChanges as hasUnsyncedUserChangesInStorage } from '@/utils/VaultDirtyState';
import { vaultRequiresManifestMigration } from '@/utils/VaultManifestMigration';
import { markOwnEncryptionKey, vaultStateEvents } from '@/events/VaultStateEvents';
@@ -39,9 +40,11 @@ type DbContextType = {
*/
getIsOffline: () => boolean;
/**
- * True if local vault has changes not yet synced to server.
+ * True if the local vault has user-initiated changes not yet synced to the server. Changes from silent
+ * scopes (e.g. item usage statistics) sync just the same but are not reported here, so the UI stays quiet
+ * about data the user never asked to save.
*/
- isDirty: boolean;
+ hasUnsyncedUserChanges: boolean;
/**
* True if a background sync (download) is in progress.
*/
@@ -125,9 +128,9 @@ export const DbProvider: React.FC<{ children: React.ReactNode }> = ({ children }
const isOfflineRef = useRef(false);
/**
- * Dirty state - true if local vault has unsynced changes.
+ * Dirty state - true if the local vault has unsynced changes the user expects to get feedback on.
*/
- const [isDirty, setIsDirty] = useState(false);
+ const [hasUnsyncedUserChanges, setHasUnsyncedUserChanges] = useState(false);
/**
* Syncing state - true if a background sync (download) is in progress.
@@ -151,8 +154,8 @@ export const DbProvider: React.FC<{ children: React.ReactNode }> = ({ children }
* as the server may not know about newly created items/aliases yet.
*/
const shouldSuppressEmailErrors = useCallback(() => {
- return isDirty || isSyncing;
- }, [isDirty, isSyncing]);
+ return hasUnsyncedUserChanges || isSyncing;
+ }, [hasUnsyncedUserChanges, isSyncing]);
/**
* Set the offline mode state and persist it to local storage.
@@ -172,14 +175,14 @@ export const DbProvider: React.FC<{ children: React.ReactNode }> = ({ children }
* Load the offline mode and sync state from local storage.
*/
const loadSyncState = async (): Promise<void> => {
- const [offlineMode, dirty, lastError] = await Promise.all([
+ const [offlineMode, pendingUserChanges, lastError] = await Promise.all([
storage.getItem(StorageKeys.IS_OFFLINE_MODE) as Promise<boolean | null>,
- storage.getItem(StorageKeys.IS_DIRTY) as Promise<boolean | null>,
+ hasUnsyncedUserChangesInStorage(),
storage.getItem(StorageKeys.LAST_SYNC_ERROR) as Promise<string | null>
]);
isOfflineRef.current = offlineMode ?? false;
setIsOfflineState(offlineMode ?? false);
- setIsDirty(dirty ?? false);
+ setHasUnsyncedUserChanges(pendingUserChanges);
setSyncError(lastError ?? null);
};
loadSyncState();
@@ -330,7 +333,7 @@ export const DbProvider: React.FC<{ children: React.ReactNode }> = ({ children }
* Refresh sync state from storage (called after background updates it).
*/
const refreshSyncState = useCallback(async (): Promise<void> => {
- setIsDirty((await storage.getItem(StorageKeys.IS_DIRTY) as boolean | null) ?? false);
+ setHasUnsyncedUserChanges(await hasUnsyncedUserChangesInStorage());
}, []);
/**
@@ -403,7 +406,7 @@ export const DbProvider: React.FC<{ children: React.ReactNode }> = ({ children }
dbAvailable,
isOffline,
getIsOffline,
- isDirty,
+ hasUnsyncedUserChanges,
isSyncing,
isUploading,
setIsOffline,
@@ -421,7 +424,7 @@ export const DbProvider: React.FC<{ children: React.ReactNode }> = ({ children }
requiresManifestMigration,
syncError,
clearSyncError,
- }), [sqliteClient, dbInitialized, dbAvailable, isOffline, getIsOffline, isDirty, isSyncing, isUploading, setIsOffline, shouldSuppressEmailErrors, loadDatabase, loadStoredDatabase, storeEncryptionKey, storeEncryptionKeyDerivationParams, clearDatabase, getVaultMetadata, refreshSyncState, requiresLegacySqliteBlobMigration, requiresManifestMigration, syncError, clearSyncError]);
+ }), [sqliteClient, dbInitialized, dbAvailable, isOffline, getIsOffline, hasUnsyncedUserChanges, isSyncing, isUploading, setIsOffline, shouldSuppressEmailErrors, loadDatabase, loadStoredDatabase, storeEncryptionKey, storeEncryptionKeyDerivationParams, clearDatabase, getVaultMetadata, refreshSyncState, requiresLegacySqliteBlobMigration, requiresManifestMigration, syncError, clearSyncError]);
return (
<DbContext.Provider value={contextValue}>
diff --git a/apps/browser-extension/src/entrypoints/popup/hooks/useVaultMutate.ts b/apps/browser-extension/src/entrypoints/popup/hooks/useVaultMutate.ts
index 68b58115a..6ca732db9 100644
--- a/apps/browser-extension/src/entrypoints/popup/hooks/useVaultMutate.ts
+++ b/apps/browser-extension/src/entrypoints/popup/hooks/useVaultMutate.ts
@@ -5,7 +5,7 @@ import { useDb } from '@/entrypoints/popup/context/DbContext';
import { devLog } from '@/utils/devLogger/DevLogger';
import { EncryptionUtility } from '@/utils/EncryptionUtility';
import { sendMessage } from '@/utils/messaging/ExtensionMessaging';
-import type { VaultMutationOptions, VaultMutationScope } from '@/utils/types/VaultMutationScope';
+import { isSilentScope, type VaultMutationOptions, type VaultMutationScope } from '@/utils/types/VaultMutationScope';
/**
* Hook to execute a vault mutation.
@@ -114,10 +114,17 @@ export function useVaultMutate(): {
* and continues even if the popup closes.
*
* Always polls to detect completion since background sync may queue additional
- * syncs that we cannot directly observe from the popup context.
+ * syncs that we cannot directly observe from the popup context. A silent scope
+ * (e.g. item usage statistics) syncs the same way but shows no indicator: the
+ * user did not ask for that write and expects no feedback on it.
+ * @param scope - what the mutation touched
*/
- const triggerBackgroundSync = useCallback((): void => {
- dbContext.setIsUploading(true);
+ const triggerBackgroundSync = useCallback((scope?: VaultMutationScope): void => {
+ const silent = scope !== undefined && isSilentScope(scope);
+
+ if (!silent) {
+ dbContext.setIsUploading(true);
+ }
/*
* Fire-and-forget: send message to background without awaiting.
@@ -127,10 +134,11 @@ export function useVaultMutate(): {
* After sending message, we start polling to detect completion.
*/
void sendMessage('FULL_VAULT_SYNC').then(async (syncResult) => {
- if (!syncResult.success && (syncResult.error || syncResult.errorKey)) {
+ if (!silent && !syncResult.success && (syncResult.error || syncResult.errorKey)) {
/*
* Permanent failure (e.g. HTTP 413 vault too large). Stop polling and clear the upload
- * spinner.
+ * spinner. Skipped for a silent scope: it owns neither the poll nor the spinner, both of
+ * which may belong to a visible mutation still in flight.
*/
if (pollIntervalRef.current) {
clearInterval(pollIntervalRef.current);
@@ -146,8 +154,10 @@ export function useVaultMutate(): {
console.error('Background sync error:', error);
});
- // Start polling for completion
- startPollingForCompletion();
+ // Start polling for completion (nothing to clear when no indicator was shown)
+ if (!silent) {
+ startPollingForCompletion();
+ }
}, [dbContext, startPollingForCompletion]);
/**
@@ -164,7 +174,7 @@ export function useVaultMutate(): {
await saveLocally(operation, options?.scope);
// 2. Trigger sync in background (fire-and-forget, continues even if popup closes)
- triggerBackgroundSync();
+ triggerBackgroundSync(options?.scope);
}, [saveLocally, triggerBackgroundSync]);
return {
diff --git a/apps/browser-extension/src/utils/VaultDirtyState.ts b/apps/browser-extension/src/utils/VaultDirtyState.ts
new file mode 100644
index 000000000..874e483e1
--- /dev/null
+++ b/apps/browser-extension/src/utils/VaultDirtyState.ts
@@ -0,0 +1,41 @@
+/**
+ * VaultDirtyState.
+ *
+ * The local vault's pending-sync state: whether it holds changes the server does not have yet, and which
+ * mutation scopes those changes belong to. Shared between the background sync (which decides what to push) and
+ * the popup (which decides what to show).
+ */
+
+import { storage } from 'wxt/utils/storage';
+
+import { dirtyScopeStorageKey, StorageKeys } from '@/utils/constants/storageKeys';
+import { ALL_VAULT_MUTATION_SCOPES, hasUserVisibleScope, type VaultMutationScope } from '@/utils/types/VaultMutationScope';
+
+/**
+ * Read the set of currently-dirty mutation scopes from their independent per-scope flags.
+ */
+export async function getDirtyScopes(): Promise<VaultMutationScope[]> {
+ const flags = await Promise.all(
+ ALL_VAULT_MUTATION_SCOPES.map(async scope => ((await storage.getItem(dirtyScopeStorageKey(scope))) === true ? scope : null))
+ );
+ return flags.filter((s): s is VaultMutationScope => s !== null);
+}
+
+/**
+ * Clear every per-scope dirty flag. Called once a sync has confirmed all pending changes are on the server.
+ */
+export async function clearDirtyScopes(): Promise<void> {
+ await storage.removeItems(ALL_VAULT_MUTATION_SCOPES.map(scope => dirtyScopeStorageKey(scope)));
+}
+
+/**
+ * Whether the vault holds unsynced changes the user should see an indicator for. A vault that is only dirty
+ * from silent scopes (e.g. item usage statistics) syncs exactly like any other, but reports clean here so the
+ * UI stays quiet about mutations the user did not explicitly request.
+ */
+export async function hasUnsyncedUserChanges(): Promise<boolean> {
+ if (await storage.getItem(StorageKeys.IS_DIRTY) !== true) {
+ return false;
+ }
+ return hasUserVisibleScope(await getDirtyScopes());
+}
diff --git a/apps/browser-extension/src/utils/types/VaultMutationScope.ts b/apps/browser-extension/src/utils/types/VaultMutationScope.ts
index f4e101bd5..c3f7f6f32 100644
--- a/apps/browser-extension/src/utils/types/VaultMutationScope.ts
+++ b/apps/browser-extension/src/utils/types/VaultMutationScope.ts
@@ -20,6 +20,15 @@ export const ALL_VAULT_MUTATION_SCOPES: readonly VaultMutationScope[] = [...ALL_
export const DEFAULT_VAULT_MUTATION_SCOPE: VaultMutationScope = 'Main';
+/**
+ * Scopes whose sync is deliberately kept out of the UI. These hold housekeeping data the user never asked to
+ * save (per-item usage statistics are written as a side effect of autofilling or copying a field), so a spinner
+ * or pending badge for them would only suggest that something important is in flight. The sync indicator is
+ * reserved for user-initiated changes, where a confirmation that the change reached the server is the feedback
+ * the user expects to get.
+ */
+export const SILENT_VAULT_MUTATION_SCOPES: readonly VaultMutationScope[] = [VaultDataBucketCategory.Stats];
+
/**
* True when a scope is a manifest category (i.e. a dirty flag on it requires a full manifest push, not a
* bucket-only push).
@@ -28,6 +37,22 @@ export const DEFAULT_VAULT_MUTATION_SCOPE: VaultMutationScope = 'Main';
export const isManifestScope = (scope: VaultMutationScope): scope is VaultManifestScope =>
(ALL_VAULT_MANIFEST_SCOPES as readonly string[]).includes(scope);
+/**
+ * True when a scope's sync must stay invisible in the UI. It still syncs like any other scope; only the
+ * indicators ignore it.
+ * @param scope - the mutation scope
+ */
+export const isSilentScope = (scope: VaultMutationScope): boolean => SILENT_VAULT_MUTATION_SCOPES.includes(scope);
+
+/**
+ * True when the pending scopes hold at least one change worth showing an indicator for. An empty list counts as
+ * visible: a vault marked dirty without any recorded scope predates per-scope tracking, and hiding a real
+ * pending change is worse than showing a badge too many.
+ * @param scopes - the currently pending mutation scopes
+ */
+export const hasUserVisibleScope = (scopes: readonly VaultMutationScope[]): boolean =>
+ scopes.length === 0 || scopes.some(scope => !isSilentScope(scope));
+
/**
* Options for executing a vault mutation.
*/
diff --git a/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/Manifest.cs b/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/Manifest.cs
index c7a52f9ac..3320984e9 100644
--- a/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/Manifest.cs
+++ b/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/Manifest.cs
@@ -41,7 +41,7 @@ public class Manifest
public bool CanAdminister { get; set; }
/// <summary>
- /// Gets or sets how the caller's access to this manifest's VEK is encrypted.
+ /// Gets or sets how the caller's access to this manifest's VEK is encrypted, as a ManifestKeyType token.
/// </summary>
public string? KeyType { get; set; }
@@ -50,7 +50,7 @@ public class Manifest
/// </summary>
public string? EncryptedVek { get; set; }
- /// <summary>Gets or sets the algorithm of <see cref="EncryptedVek"/> (e.g. "rsa-oaep-sha256"). Null when <see cref="EncryptedVek"/> is null.</summary>
+ /// <summary>Gets or sets the algorithm of <see cref="EncryptedVek"/>, as a VaultKeyAlgorithm token. Null when <see cref="EncryptedVek"/> is null.</summary>
public string? Algorithm { get; set; }
/// <summary>
diff --git a/core/models/README.md b/core/models/README.md
index 324d6413a..526e0ceda 100644
--- a/core/models/README.md
+++ b/core/models/README.md
@@ -21,3 +21,19 @@ Automatically generates platform-specific models from TypeScript sources:
| `src/vault/FieldKey.ts` | `apps/server/Databases/AliasClientDb/Models/FieldKey.cs` | C# |
| `src/vault/FieldKey.ts` | `apps/mobile-app/ios/AliasVault/VaultModels/FieldKey.swift` | Swift |
| `src/vault/FieldKey.ts` | `apps/mobile-app/android/.../vaultstore/models/FieldKey.kt` | Kotlin |
+
+### 3. Generated Vocabularies (Not TypeScript-Sourced)
+
+Two generators own a vocabulary outright and emit **all four** platforms, TypeScript included. Their outputs
+under `src/` are generated files: edit the generator, not the output.
+
+| Generator | Source of truth | Emits |
+|-----------|-----------------|-------|
+| `scripts/generate-bucket-categories.cjs` | `core/rust/src/vault_codec/types.rs` (`BUCKET_TABLES`) | `VaultDataBucketCategory` |
+| `scripts/generate-key-vocabulary.cjs` | the `VOCABULARIES` table inside the script | `UnlockMethodType`, `ManifestKeyType`, `VaultKeyAlgorithm` |
+
+The key vocabulary is the set of tokens naming how a vault key is protected — which unlock method encrypts a
+user's Account Key, how a manifest's VEK reaches a given user, and which algorithm a piece of key ciphertext
+uses. Each token is a contract shared by the API, the database and every client, so it is declared once and
+emitted per platform. A member's `token` is the only identifier that is persisted or transmitted; the C# enum
+ordinals follow declaration order and are cosmetic, so members can be reordered freely.