tom_secrets_service library

The Tom Secrets Manager's secrets service (part-service, part-protocol): the runtime directory, the client and admin endpoints, the admin challenge and claim, the vaults while unlocked, the device settings container with its key modes, the lock policy; and for its starters the handover, the start and the admin client.

Classes

TomSecretsAccess
A policy's answer.
TomSecretsAccessAllowed
The value may be sent; grantId or approver say why.
TomSecretsAccessBatch
A client request's resolved items, decided together: one prompt for a whole getMany (protocol.md 7.2, once answers the whole batch).
TomSecretsAccessDenied
The value may not be sent: an error of kind (protocol.md 10, default denied) with details.reason reason and further details.
TomSecretsAccessPolicy
Decides whether a client may read its resolved secrets.
TomSecretsAccessRequest
One resolved secret of a client's request.
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).
TomSecretsApprovalAnswer
An answer to a prompt.
TomSecretsApprovalHost
What the approvals need from the service.
TomSecretsApprovals
Approvals and grants of one unlocked service.
The sessions to the paired hosts this device approves for.
TomSecretsAuditLog
The audit log in directory under key (32 bytes).
TomSecretsAuditRecord
One audit record (protocol.md 6.3 audit.query).
TomSecretsBootstrap
The bootstrap file.
TomSecretsBrowserHosts
The host's manifests of this user: installed, removed, checked.
TomSecretsBrowserHostState
Where the host stands for one browser.
TomSecretsCommitted
What TomSecretsVaultOpener.commit wrote.
TomSecretsConnection
A connection to a client or an admin.
TomSecretsCoverage
What a client's grants cover without a prompt (protocol.md 5.5): match lists only the entries an allow grant covers, and propose needs the client to hold an allow grant at all.
TomSecretsDenyAllPolicy
Refuses every value (denied, reason no_approver): the policy of a service with no allow list and no approver.
TomSecretsDeviceCode
A device flow's code, as github.signIn answers it.
TomSecretsDeviceContainer
The device settings container, opened with its key.
TomSecretsDeviceKeys
The container's key, by the mode bootstrap.yaml names (DP-15).
TomSecretsDeviceSettings
What the device settings hold (part-service's configuration table). The keys of later parts (approver and approval-link keys, the audit-log key) are added by their parts.
TomSecretsExpiringKey
A key due for a reminder.
TomSecretsFileHashes
SHA-256 hashes of files, cached by path, size and modification time: computed on demand, for a pinned grant.
TomSecretsFileOpener
file: vaults: read and written on the local disk (a .tsmx file through the outer layer).
TomSecretsGitHubApp
The device's GitHub App sign-in.
TomSecretsGitHubOpener
Opens, reads and writes github: vaults.
TomSecretsGrant
An accepted grant of this host.
TomSecretsHandover
The handover line the service reads from its standard input.
TomSecretsHeldKeys
The key material the service holds for one store while unlocked, masked (part-service, Memory hygiene): what opens it, and what vaultKeySet hands the app (protocol.md 6.4). dispose zeroes it.
TomSecretsIdentity
The identity of a client (protocol.md 7.1): shown, matched and audited.
TomSecretsIdleSource
The user's input idle time on the desktop session.
TomSecretsIntegrations
The integrations of one user on this machine.
TomSecretsIntegrationState
Where an integration stands.
TomSecretsInterpreters
The interpreter table: the default and the user's additions.
TomSecretsKeyDate
A key the service knows the due date of (tsm keys, the keys admin request): kind and key as in TomSecretsExpiringKey, the vault it belongs to, when it expiresAt, and how many days before that its reminders start (firstDays).
TomSecretsLinkServer
The approval link's listener.
TomSecretsLocatorOpener
Each locator to the opener of its kind: file: vaults to file, github: vaults to github.
TomSecretsLockPolicy
A lock policy.
TomSecretsLockTimer
Watches the policy while the service is unlocked and locks it when the policy says so.
TomSecretsLog
The operational log.
TomSecretsLookupPolicy
A policy that can say what a client's grants cover without asking (protocol.md 5.5 match, propose). A policy that is not one covers nothing.
TomSecretsOpenedVault
A vault file as opened.
TomSecretsPairingHandover
The pairing mode's handover line.
TomSecretsPairingReport
What a pairing gave, as the pairing mode reports it (no key, no token).
TomSecretsPairsRotated
What keys.rotate did.
TomSecretsPeerMeasured
The peer was measured.
TomSecretsPeerMeasurement
The outcome of measuring a peer.
TomSecretsPeerMeasurer
Measures the process at the other end of an accepted Socket.
TomSecretsPeerRefused
The peer is refused: other_user (another OS user) or unidentifiable (it could not be measured, or changed under the measurement).
TomSecretsPin
A grant's pin (protocol.md 7.2 pin): hash, off, or relaxed until a time.
TomSecretsPinCheck
What a pin says about a file.
TomSecretsPinHash
On: a changed hash is no grant, and the request goes to approval.
TomSecretsPinOff
Off: the path alone, like an executable.
TomSecretsPinRelaxed
Relaxed until until: before it a changed file is accepted and its new hash recorded; from then on the pin is on with the last recorded hash.
TomSecretsProcessInfo
What a process is, measured by the service (never what it says).
TomSecretsRateLimits
The state of the limits, kept per identity key.
TomSecretsRateLimitSettings
The limits, protocol.md 11's by default.
TomSecretsRefreshReport
What a refresh changed.
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.
TomSecretsSaveResult
What a save did.
TomSecretsSecretSlot
A secret in a message, written into the frame as a JSON string: the text of UTF-8 bytes, escaped, or the base64 of any bytes.
TomSecretsService
A running service.
TomSecretsServiceConfig
What a service is started with.
TomSecretsServicePairing
A conversation with the service in its pairing mode.
TomSecretsSshUse
What an ssh-agent request is about (part-os-integration): shown in the prompt, matched against an agent grant's hosts and forwarding, and audited.
TomSecretsStarted
A new service runs with adminKey.
TomSecretsStartFailed
The service could not start, for code.
TomSecretsStartResult
What a start found.
TomSecretsStoreStatus
A store's status, as status reports it.
TomSecretsSystemPeerMeasurer
The measurer of this OS.
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).
TomSecretsVaultOpener
Reads, decodes, encodes and writes vault files by locator.
TomSecretsVaultSet
The unlocked vaults.

Enums

TomSecretsBrowser
A browser the host can be installed for.
TomSecretsDeviceKeyMode
Where the device settings container's key is kept (DP-15).
TomSecretsGitHubAppState
Where the device's App sign-in stands.
TomSecretsIntegration
An integration of a developer tool.
TomSecretsInterpreterRule
How an interpreter's command line names what it runs.
TomSecretsLockMode
How a lock policy relocks.
TomSecretsLogLevel
How much the log says.
TomSecretsStoreState
A store's state (protocol.md 6.3).
TomSecretsTokenProblem
Why a token was refused.
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).
tomSecretsBrowserHostName → const String
The file name of the browser host (protocol.md 5.5), without .exe.
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.
tomSecretsDefaultInterpreters → const Map<String, TomSecretsInterpreterRule>
The default interpreter table (part-protocol), by the executable's base name (without .exe, any case); python3.* matches every minor version. The user extends it with TomSecretsInterpreters.
tomSecretsFileChunkSize → const int
The size of a getFile chunk (protocol.md 2.5: at most 1 MiB less the 8 id bytes).
tomSecretsFirefoxExtensionId → const String
The Firefox extension's id (browser_specific_settings.gecko.id).
tomSecretsGitHubAppHandle → const String
The keychain handle of the device's GitHub App session.
tomSecretsGitHubAppRenewAhead → const Duration
How long before the access token runs out it is renewed.
tomSecretsHelperNames → const List<String>
The file names the developer-tool helpers run as (protocol.md 5.5), without .exe: tsm and its multi-call names.
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.
tomSecretsLinkRetryMax → const Duration
The longest pause before a session to a host is opened again.
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.
tomSecretsRefusalKinds → const Set<String>
The refusal kinds the slowdown counts.
tomSecretsServiceExecutable → const String
The service's executable name, without .exe.
tomSecretsServiceFeatures → const List<String>
The optional features this service offers (protocol.md 8).
tomSecretsServiceLabel → const String
The service's label.
tomSecretsServiceVersion → const String
The service's version, sent in welcome and challenge.
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

tomSecretsAdminExecutables(String serviceExecutable, TomSecretsBootstrap bootstrap) → Set<String>
The executables that may administer a service started from serviceExecutable with bootstrap (protocol.md 6.1), as real paths: tsm and the manager app (tom_secrets_desktop, tom_secrets_app) beside the service's executable, the app of the distribution the service is part of (tomSecretsDistributionApp: the app carries tsm and the service in its tsm/bin folder), and the bootstrap's admin_executables.
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.
tomSecretsBootstrapWithPrimary(String yaml, String primary) → String
yaml (a bootstrap.yaml) with its primary: set to primary; every other line, comments included, stays as it is. Throws FormatException when yaml names no primary.
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.
tomSecretsCheckGitHubToken({required String owner, required String repository, required String token, String baseUrl = 'https://api.github.com', Client? client}) → Future<DateTime?>
Checks token against the repository owner/repository on the GitHub API at baseUrl: it sees the repository and can create and delete a branch there. Answers the expiry GitHub reported (null: none, a token that does not expire). Throws TomSecretsTokenCheckException.
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.
tomSecretsDefaultKnownHosts() → String?
~/.ssh/known_hosts of this user, or null when no home is set.
Sends messages (each without id, which is added) to the host at address (host:port) over a link session initiated with this device's link key me, the host's recorded key hostKey and this device's name; each must be answered ok. Throws TomSecretsLinkDeliveryException; timeout bounds the connection and each answer.
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.
tomSecretsFetchFailureOf(Object error) → Object?
The failure behind error a held or cached copy stands in for, or null: error itself, or the cause a storage failure wraps.
tomSecretsGrantSecrets(TomSecretsApprovalAnswer a, {required List<String> refs, required List<String> stores, Map<String, Object?>? ssh}) → Set<String>
The secrets a lasting answer a writes grants for: of a value request with refs (canonical) resolved in stores, its references, stores or all; of an ssh-agent request (ssh, approval_needed.ssh) the agent secret of the key, its vault or all keys, limited to the destination host when TomSecretsApprovalAnswer.sshHost asks and the request has one.
tomSecretsGrantSubject(TomSecretsIdentity i, TomSecretsApprovalAnswer a, {bool browser = false}) → String
The subject a lasting answer a to a request of i is granted for: a folder decision its folder (with the interpreter), a tsm run its command line, else the script, the interpreter or the executable. The browser host's grants (browser, a browser prompt) always name the browser that started it (exe-from, DP-44: one grant per browser), as do the helpers' and an answer TomSecretsApprovalAnswer.withParent.
tomSecretsHardenProcess() → Map<String, bool>
Applies the hardening of this OS to the running process and answers what it achieved, by measure. Never throws: a measure that fails is false.
tomSecretsIdentityOf(TomSecretsProcessInfo process, {TomSecretsProcessInfo? parent, TomSecretsInterpreters interpreters = const TomSecretsInterpreters(), TomSecretsFileHashes? hashes}) → TomSecretsIdentity
The identity of process (the client) with its parent, classified by interpreters; a script's hash from hashes.
tomSecretsIsFetchFailure(Object error) → bool
Whether error is a failure to reach the remote, or a refusal of the token, that a held or cached copy stands in for (and the refresh backs off from).
tomSecretsIsHelperCall(TomSecretsIdentity i) → bool
Whether i is a developer-tool helper's call (git-credential-tsm get, docker-credential-tsm list, ...): tsm or one of its multi-call names with one helper verb. Its lasting grants name the tool that started it (exe-from git => tsm, part-os-integration: "one grant covers git"), so they never cover tsm get typed in a shell.
tomSecretsLauncherOf(TomSecretsProcessInfo process, TomSecretsProcessInfo? parent, TomSecretsProcessInfo? infoOf(int pid)) → TomSecretsProcessInfo?
The process whose child process counts as, for its grants: its parent, except for the browser host (an executable named tsm-browser-host) started through a shell, cmd.exe (Chrome and the other Chromium browsers start a native-messaging host on Windows with cmd /c): then the shell's parent, the browser, read with infoOf. A grant of the browser host names its browser (exe-from, DP-44), which the shell alone would not tell apart.
tomSecretsLookupExecutables(String serviceExecutable) → ({Set<String> browserHosts, Set<String> helpers})
The browser host and the helpers of a service started from serviceExecutable, as real paths beside it (protocol.md 5.5).
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).
tomSecretsOwnUid() → Object?
This process's OS user: a number on Linux and macOS, a SID string on Windows; null when it cannot be read.
tomSecretsPeerOf(Socket socket) → ({int pid, Object? uid})?
The PID (and, on Linux and macOS, the uid) of socket's peer, or null.
tomSecretsProcessInfo(int pid) → TomSecretsProcessInfo?
What process pid is, or null when it cannot be read.
tomSecretsRandomBytes([int count = tomSecretsKeyBytes]) → Uint8List
count bytes from the OS's secure generator.
tomSecretsRealPath(String path, String? cwd) → String
path resolved against cwd to its real path (symbolic links followed); unresolved when it is relative and cwd is unknown.
tomSecretsRunPairingMode(TomSecretsPairingHandover handover, {required StreamIterator<String> lines, required void answer(Map<String, Object?> line), required TomSecretStore? keychain}) → Future<int>
Runs the pairing mode for handover: reads tsm's lines from lines, answers through answer, keeps keys in keychain (null: none on this machine). Answers the exit code: 0 set up, 2 the handover cannot be used, 6 the pairing failed, 7 the setup failed or no password came.
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).
tomSecretsSecretFrame(Map<String, Object?> message, {int maxPayload = tomSecretsMaxAnswerPayload}) → Uint8List?
A message's frame (protocol.md 2): the compact JSON of message, every TomSecretsSecretSlot in it written from its bytes. Byte for byte what tomSecretsJsonFrame writes for the same message with the secrets as strings. Returns null when the payload exceeds maxPayload; nothing of a secret is then left in memory.
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).
tomSecretsSettingsProblem(Map<String, Object?> device) → String?
What makes device unacceptable as device settings (settings.set), or null: the types and ranges a setting must have. Members it does not know are ignored, as every reader does (protocol.md 8).
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.
tomSecretsStartTimeOf(int pid) → int?
The start time of process pid as the OS gives it, or null.
tomSecretsSystemIdleSource() → TomSecretsIdleSource
The idle source of this OS: CoreGraphics on macOS, GetLastInputInfo on Windows, logind's idle hint on Linux (none without a desktop session).
tomSecretsTakeHostLinkKey(TomSecretsLinkSession session, Map<String, Object?> message, Future<void> onHostLinkKey(TomSecretsLinkPublicKey key)?) → Future<void>
Records the host's new link key of message through onHostLinkKey and answers it: ok, or error for a key of another device or that cannot be read.
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

TomSecretsBytesReader = T Function<T>(T use(Uint8List bytes))
Reads a secret's bytes for the duration of a callback, zeroing them after.
TomSecretsCommitReaderFor = TomSecretsCommitReader Function(TomSecretsGitHubLocator vault)
The commit reader a compaction reads vault's repository's history with.
TomSecretsGitHubTokens = Future<String?> Function(TomSecretsGitHubLocator vault)
The GitHub token for vault's repository, or null when there is none.
TomSecretsGitRemoteFor = GitHttpRemote Function(TomSecretsGitHubLocator vault, Future<String?> token())
The git remote a compaction pushes vault's repository to, with token its credential.
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.
TomSecretsDeviceKeyException
The device settings container's key could not be had.
TomSecretsGitHubAppException
A sign-in refused by GitHub: kind (denied, expired, device_flow_disabled, bad_client_id, bad_refresh_token, failed).
TomSecretsLinkDeliveryException
A message the host refused (error), or a link that could not be opened or closed before every answer.
TomSecretsPairingModeException
The pairing mode answered an error.
TomSecretsRuntimeException
A runtime directory that is not the user's alone, or cannot be made.
TomSecretsSaveException
A save the service does not take (protocol.md 6.4, 10).
TomSecretsTokenCheckException
A token check refused.