tom_core_storage 0.1.3
tom_core_storage: ^0.1.3 copied to clipboard
Storage for Tom applications: a compare-and-swap storage port, keyed file media, a device-local cache, a durable offline commit journal, and the local filesystem, browser (IndexedDB) and cache-cipher [...]
Changelog #
0.1.3 #
Added #
TomGatedSecretStore(settings.dart): device secrets released only after the OS's own check (Touch ID, Face ID, a fingerprint, Windows Hello, the passcode) —availability()(TomGatedAvailability: none, biometric, passcode, gate-only),write(handle, secret, {lifetime, reason}),read(handle, reason:)with the prompt,delete; failures asTomGatedSecretStoreExceptionof kind cancelled, lockedOut, invalidated, unavailable or failed, never a miss and never the secret. The port oftom_biometric_storage;TomInMemoryGatedSecretStorefor tests.
0.1.2 #
Added #
TomDesktopSecretStore(io.dart): aTomSecretStoreover the OS keychain for programs without Flutter — the macOS login keychain through/usr/bin/security(the secret goes on its standard input), libsecret throughsecret-tool, the Windows Credential Manager through FFI — with a timeout on every call.TomSecretStoreAvailability:isAvailable()for a store that may be locked or absent in the current session.
0.1.1 #
Added #
TomGitHubStorage.committer: the author and committer its commits name (aGitHubGitIdentity, e.g. a device), instead of the token's owner. Needstom_github_api1.4.0.TomMediumFileStorage: single-file containers on aTomBundleMedium, one per locator under a prefix, with a compare-and-swap on the SHA-256 of the stored bytes — the storage a browser root has for a KDBX container in IndexedDB.
0.1.0 #
Added #
-
Settings and secrets, in
settings.dart. Formerly the packagetom_core_settings, folded in before the first release:- The device settings file.
TomDeviceSettings: plain YAML at a locator, read and committed through aTomStorage; an open registry of keys that is written back whole, so a key this build does not know survives; typed accessors for the settings-key handle, the log's path and level and the cache's quota and sealing; one serialized write queue, so concurrent writers never refuse each other; a malformed file reads as empty. - The settings-key bootstrap.
TomSettingsKeyBootstrap.ensuremints one random secret per device into the platform secret store and records its handle in device settings, idempotently; a wiped keychain re-mints the secret under the same handle. A store that cannot be asked raisesTomSecretStoreExceptionwith itsTomSecretStoreStepand cause. - The secret-store port.
TomSecretStore(aTomCacheKeyStore) andTomInMemorySecretStore. - The key port.
TomKeyMaterial,TomKeyRegistrywithTomMemoryKeyRegistry,TomKeyStorewithTomInMemoryKeyStore. - Identity and locations.
TomIdentity,TomStorageLocation,TomLocationRegistrywithTomInMemoryLocationRegistry, andTomLocationForgettingwithTomLocationTracesandTomForgottenLocation.
These came from the Webwork app, where they carried the
Webworkprefix; the bootstrap there also opened the KDBX settings container, which stays with the container binding. - The device settings file.
-
A git backend.
package:tom_core_storage/git.dart:TomGitStorageover any git server that speaks smart HTTP, throughtom_gitand with no git binary — a local clone as the medium (tomGitMemoryClones, ortomGitDirectoryClonesfromio.dart), a head that is the document's object id in the branch tip, a commit that is a compare-and-swap on it and then a push, a lost race to another document's change rebuilt and pushed again, a lost race to this document's aTomCasConflictException, andTomTokenRequiredException/TomTokenRejectedExceptionwhen the server asks for a credential. Locators areTomGitLocator:git:<repository-url>[#<branch>]::<path>, the repositoryhttp(s):orfile:; an empty path is the repository root, which lists. WithopenLocal(tomGitLocalRepositoriesfromio.dart) afile:locator is a repository in a folder on this device — a working repository, a linked worktree or a bare one — read and written in place, compare-and- swap on the branch under git's ref lock; a branch some working tree has checked out is read and never written. -
A storage contract.
test/support/storage_contract.dart: what a caller may rely on from every backend, run against the local filesystem and the git backend. -
Test support.
package:tom_core_storage/testing.dart:TomMemoryRemote, an in-memory compare-and-swap remote, andTomMemoryStorage, a per-device view onto it whose reads, writes, quota (rateLimitedUntil), key (keyRequiredReason) and replica lag (TomStaleHead) each fail on their own switch. -
The asset store.
TomAssetStore: assets filed under the SHA-256 of their bytes (TomAsset), deduplicated, read on demand and verified then (TomAssetCorruptException), resolved asTomAssetLive,TomAssetHistoricalorTomAssetMissing, ingested under aTomObjectCeiling, revived from history after an undo, copied between stores. The accepted types are the application's (TomAssetTypes: MIME type to extension and kind).TomAssetBundleLayoutkeeps a store in aTomBundleMedium:assets/<id>.<ext>, an append-only history folder, and the metadata map a manifest carries. -
The storage port.
TomStorage: list, read a container's bytes or its files (readBundle, a lazy read-only view),commitaTomChangesetagainst an expected head (compare-and-swap), delete, and read heads one at a time or in a batch. Its failures are typed:TomUnreachableException,TomContainerNotFoundException,TomCasConflictException,TomKeyRequiredException,TomRateLimitException(with itsTomRateLimitKind).TomBackoffPolicystates the waits a backend chooses when the remote names none;TomCommitProgressreports a long commit. -
Keyed file media.
TomBundleMediumwithTomMemoryBundleMedium(and its ZIP form),TomReadOnlyBundleMediumandTomRecordingBundleMedium, which turns writes into one changeset;TomSeededStorage, a read-only view with one container replaced. -
Policies.
TomObjectCeiling(the tighter of a configured and a backend limit), Git-LFS pointer refusal (TomLfsPointer,tomRefuseLfsPointer), access tokens (TomTokenSource,TomInMemoryTokenSource), location prefixes (tomLocationCovers,tomLongestLocationPrefix). -
A device-local cache (
TomStorageCachewithTomCachePolicy,TomCacheSettings,TomCacheScrub) and a durable offline commit journal (TomCommitJournal,TomMemoryCommitJournal,TomMediumCommitJournal). -
A GitHub repository as a backend (
github.dart):TomGitHubStorage— one save is one commit, compare-and-swap on the branch head, conditional reads, rate-limit waits (tomGitHubWaitOf), Git-LFS refusal, progress per object, an optionalcommitMessagePrefix— and its locatorTomGitHubLocatorin the default entry point. -
Entry points of their own:
io.dart(TomLocalFileSystemStorage,TomDirectoryBundleMedium),web.dart(tomOpenBrowserMediumover IndexedDB) andcipher.dart(TomAesGcmCacheCipherover aTomCacheKeyStore). -
A local commit always moves the head. A file's head token is its size and its modification time to the millisecond, so a commit writes only once the clock is past the previous time of every file it replaces. Two same-size commits inside one millisecond otherwise left the head unchanged, and a device holding the older head could commit over the newer write.