admin library

The admin side of the Tom Secrets Manager's local protocol (protocol.md 6): the admin client with its mutual challenge and claim, the runtime directory, starting the service with its admin-key handover, and where the product keeps its data. Used by the manager app, tsm and the service itself; a client that only reads secrets needs none of it.

Classes

TomSecretsAdminClient
An authenticated admin connection.
TomSecretsAdminKeyring
The admin keys in a keychain reached through read, write and delete (the keychain's own operations; their failures pass through).
TomSecretsAlreadyStarted
A service was already running: attach to it (with the key held, or by claim).
TomSecretsBrowserHosts
The host's manifests of this user: installed, removed, checked.
TomSecretsBrowserHostState
Where the host stands for one browser.
TomSecretsHandover
The handover line the service reads from its standard input.
TomSecretsIntegrations
The integrations of one user on this machine.
TomSecretsIntegrationState
Where an integration stands.
TomSecretsPairingHandover
The pairing mode's handover line.
TomSecretsPairingReport
What a pairing gave, as the pairing mode reports it (no key, no token).
TomSecretsRegExe
TomSecretsRegistry through Windows' own reg.exe.
TomSecretsRegistry
The Windows registry, as far as the manifests need it (HKCU keys and their default value).
TomSecretsRuntime
The runtime directory of this OS user.
TomSecretsServicePairing
A conversation with the service in its pairing mode.
TomSecretsStarted
A new service runs with adminKey.
TomSecretsStartFailed
The service could not start, for code.
TomSecretsStartResult
What a start found.
TomSecretsUnlockBundle
The key material of one vault's OS unlock: its compositeKey and, for a vault with the outer encryption, its outerKey (the repository key as the keychain keeps it).

Enums

TomSecretsBrowser
A browser the host can be installed for.
TomSecretsIntegration
An integration of a developer tool.
TomSecretsTransport
How the endpoints are offered: Unix domain sockets (Linux, macOS) or localhost TCP ports with a client token (Windows).

Constants

tomSecretsAdminKeyIndexHandle → const String
The handle of the index of the starts whose admin key is kept: their start times, comma-separated.
tomSecretsAdminLabel → const String
The admin's label.
tomSecretsAppExecutable → const String
The manager app's executable name, without .exe.
tomSecretsBlockBegin → const String
The first line of a block the product writes.
tomSecretsBlockEnd → const String
The last line of a block the product writes.
tomSecretsBrowserHostId → const String
The native-messaging host's name (the manifest's name, its file name and the Windows registry key).
tomSecretsBundleInfo → const String
The HKDF info of the bundle key.
tomSecretsBundleNonceBytes → const int
The length of a bundle's nonce.
tomSecretsChromiumDevelopmentId → const String
The Chromium development build's extension id (the first 32 hex digits of the SHA-256 of tomSecretsChromiumDevelopmentKey, each mapped to a–p).
tomSecretsChromiumDevelopmentKey → const String
The public key of the Chromium development build (the extension manifest's key, base64 of its SubjectPublicKeyInfo), which fixes its id to tomSecretsChromiumDevelopmentId; its private key is not kept (an unpacked build needs none).
tomSecretsChromiumExtensionIds → const List<String>
The Chromium extension ids the host serves and the manifests allow: the development build's; the Chrome Web Store's and Edge Add-ons' ids join when the extension is published there (part-browser, Publishing).
tomSecretsCompositeKeyBytes → const int
The length of a composite key.
tomSecretsFirefoxExtensionId → const String
The Firefox extension's id (browser_specific_settings.gecko.id).
tomSecretsKeyBytes → const int
The length of an admin key and of a nonce.
tomSecretsKeychainService → const String
The service name of the product's items in the OS keychain.
tomSecretsPairingPasswordTries → const int
How many master passwords the pairing mode takes.
tomSecretsPairingWrongPassword → const String
The code of a wrong master password; another may be sent.
tomSecretsServiceExecutable → const String
The service's executable name, without .exe.
tomSecretsServiceLabel → const String
The service's label.
tomSecretsToolsFolder → const String
The folder of the distribution holding the command-line tools.

Properties

tomSecretsChromiumExtensionOrigins → List<String>
The origins of tomSecretsChromiumExtensionIds (allowed_origins).
no setter

Functions

tomSecretsAdminKeyHandle(int serviceStart) → String
The handle of the admin key of the service started at serviceStart (service.json's start, milliseconds since the epoch): the app and tsm keep the key there between invocations; a new start has a new key.
tomSecretsApprovalLinkProblem(String text, {bool anyPort = false}) → String?
Why text cannot be the device setting approvalLink (the address the approval link listens on, protocol.md 9.7), or null: host:port, an IPv6 address in brackets ([fd00::1]:47731), a port 1–65535 (with anyPort also 0, the system picks one), and never every interface (0.0.0.0, ::): the link listens on a VPN or LAN address only.
tomSecretsAuthDelay(int failures) → Duration
The delay before the next authentication after failures failed ones: 0, then 1 s, 2 s, 4 s … up to 60 s (protocol.md 6.1).
tomSecretsBlockOf(String text) → List<String>?
The lines between the marks of text's block, or null when it has none.
tomSecretsBootstrapPath({Map<String, String>? environment, String? operatingSystem}) → String
The default bootstrap file: bootstrap.yaml in tomSecretsDataDirectory.
tomSecretsBrowserHostBeside(String serviceExecutable, {required String operatingSystem}) → String
The browser host tsm-browser-host beside the service whose executable is serviceExecutable (where the service recognises it, protocol.md 5.5, and where the distribution carries it).
tomSecretsBundleAad(String vault, int serviceStart) → Uint8List
The associated data of vault's bundle: its name's UTF-8 bytes and serviceStart as 8 bytes big-endian.
tomSecretsBundleKey(List<int> adminKey, List<int> serviceNonce, List<int> adminNonce) → Uint8List
The bundle key of one admin connection: HKDF-SHA256(adminKey, salt = serviceNonce || adminNonce, info = "tsm-bundle-v1"), 32 bytes.
tomSecretsChallengeInput(String label, List<int> serviceNonce, List<int> adminNonce, int serviceStart) → Uint8List
The MAC input: label's ASCII, both nonces, serviceStart as 8 bytes big-endian.
tomSecretsChallengeMac(List<int> adminKey, String label, List<int> serviceNonce, List<int> adminNonce, int serviceStart) → Uint8List
The MAC of label over the challenge under adminKey.
tomSecretsConstantTimeEquals(List<int> a, List<int> b) → bool
Whether a equals b, in time independent of where they differ.
tomSecretsDataDirectory({Map<String, String>? environment, String? operatingSystem}) → String
The data directory: TSM_DATA_DIR when set; on macOS ~/Library/Application Support/TomSecretsManager; on Windows %LOCALAPPDATA%\TomSecretsManager (the runtime directory is its run\); elsewhere $XDG_DATA_HOME/tom-secrets-manager, else ~/.local/share/tom-secrets-manager. environment and operatingSystem default to this process's.
tomSecretsDistributionApp(String serviceDirectory, {required String operatingSystem}) → String
The app of the distribution around a service whose executable is in serviceDirectory (…/tsm/bin): the path its executable has when the service is the distribution's, which the service admits as an admin besides tsm and the app beside itself.
tomSecretsOpenBundle({required List<int> bundleKey, required String vault, required int serviceStart, required Map<String, Object?> bundle}) → Future<Uint8List>
Opens the bundle object of unlock for vault: the plaintext bytes, which the caller wipes after use. Throws TomSecretsBundleException when it is malformed or does not open (another key, vault or service start).
tomSecretsRandomBytes([int count = tomSecretsKeyBytes]) → Uint8List
count bytes from the OS's secure generator.
tomSecretsSealBundle({required List<int> bundleKey, required String vault, required int serviceStart, required List<int> plaintext, List<int>? nonce}) → Future<Map<String, String>>
Seals plaintext for vault under bundleKey: the bundle object of unlock (nonce, ciphertext with the tag, both base64). nonce is random unless given (test vectors).
tomSecretsServiceCandidates(String appDirectory, {required String operatingSystem}) → List<String>
Where the app whose executable is in appDirectory looks for the service, in order: beside itself (a development build, or a fleet install), then in its distribution's tools folder (operatingSystem as Platform.operatingSystem names it).
tomSecretsStartService({required String executable, List<String> arguments = const [], required String bootstrap, Map<String, String>? environment, Duration timeout = const Duration(seconds: 60)}) → Future<TomSecretsStartResult>
Starts the service executable (with arguments) for bootstrap, detached; waits up to timeout for its answer line.
tomSecretsWithBlock(String text, List<String>? block, {bool atTop = false}) → String
text with its block's lines replaced by block (marks added), or the block removed when block is null. A new block goes at the top when atTop, else at the end; an existing one stays where it is. Every line outside the block is kept as it was (line ends as text has them).

Typedefs

TomSecretsPairedVault = ({String locator, String name, bool primary})
One vault a pairing gave, as the pairing mode reports it.

Exceptions / Errors

TomSecretsAdminException
The admin endpoint refused or broke the conversation.
TomSecretsAlreadyRunning
Another service already holds the lock: the starter attaches to it.
TomSecretsBundleException
A sealed bundle did not open, or its plaintext is no bundle. Carries no key material.
TomSecretsPairingModeException
The pairing mode answered an error.
TomSecretsRuntimeException
A runtime directory that is not the user's alone, or cannot be made.