filmopen_keys

A snapshot

This specification is a copy of docs/software/packages/filmopen_keys.md in the application’s repository, taken at commit 0b4fe88 of 11 November 2026. It is imported byte for byte and is not edited here; a change is made there, and arrives with the next snapshot.

Generated by scripts/package_digest.py; regenerate, never edit.

The key cards (Software Specification §6.7, §9.4): KeyCards(owner:) draws an enabled plug-in’s own key slots on its page under Settings → Plugins, where a user stores a key, checks it with the platform and removes it. Every key belongs to a plug-in; GeneralKeysSection on Settings → General explains how keys are kept. HttpKeyVerifier sends the one request that checks a key.

Flutter. 8 files, 2,450 lines under lib/; 136 tests in 7 files. Barrel: lib/filmopen_keys.dart.

Depends on

• filmopen_format — uses Catalogue, ExactDecimal, FileNameParser, PlatformCredential, PlatformFile, UsageBasis, UsageBucket, UsageChain, UsagePurpose, UsageRecord, UsageTotal, VersionStem, computeSessionEntry, conversationCaptionsEntry, conversationEntry, unknownUsageEntry, usageMonth, usageTotals
• filmopen_store — uses AppLog, UsageLog, UsageReading
• filmopen_platform — uses CredentialHealth, CredentialStore, KeyCheck, KeyCheckOutcome, KeyVerifier
• filmopen_state — uses AccountLedger, AccountSnapshots, CreditFunding, LedgerRead, LedgerReading, LedgerRow, LedgerSignedOut, LedgerUnreadable, PluginCallControl, PluginCallFailed, PluginCallOutcome, PluginCatalogueView, PluginInvocation, PluginKeyCheck, PluginKeyOwner, PluginKeySlot, PluginSummary, Settings, catalogueProvider, kFilmOpenDocsUrl, kFilmOpenDomain, kPluginHttpOperation, providerFundingProvider, recordingProvider, sharedPreferencesProvider, valueIdentifiers
• filmopen_ui — uses AppColors, EmptyState, SectionCard, showMessage, showMessageOn
• filmopen_l10n — uses nothing by name the digest could see

Third-party: flutter_riverpod, http, url_launcher, shared_preferences.

Used by

filmopen_app, filmopen_assistant_ui

Public API

What the barrel exports, file by file. A name is class, enum, mixin, extension, typedef, a top-level function, getter, setter or variable; under a class, its public constructors, fields, getters, setters and methods.

lib/src/http_key_verifier.dart

• class HttpKeyVerifier — Checks a key with its platform (Software Specification §6.7): one request, the platform file’s verify.method to exactly its verify URL, over https to one of its hosts.
  • HttpKeyVerifier({http.Client Function()? client, this.timeout = const Duration(seconds: 15)})
  • final Duration timeout — How long the platform has to answer.

lib/src/keyring_line.dart

• variable final platformCreditProvider — Whether the platform has an explicit FilmOpen credit route, refreshed when funding changes.
• class KeyringEmptyLine — Shows keyring health and confirmed recovery, with credit-covered losses as information.
  • const KeyringEmptyLine({super.key, required this.where, this.padding = EdgeInsets.zero, this.creditNoticeElsewhere = false}) — Creates the keyring recovery line for a named surface.
  • final String where — settings or dock, for the log.
  • final bool creditNoticeElsewhere — Whether this surface already displays the credit sentence, so recovery does not duplicate it.
  • final EdgeInsets padding — Around the line where it shows; nothing where it does not.
• function String keyringName(AppLocalizations l10n) — The credential store as the person knows it on this platform (§6.7): Windows’ is a file the plugin encrypts for the user (DPAPI), not the Credential Manager.

lib/src/provider_catalogue.dart

• class ProviderCatalogue — The platforms Provider keys lists.
  • const ProviderCatalogue({required this.platforms, required this.pendingCount, this.models = const {}})
  • factory ProviderCatalogue.from(Catalogue catalogue) — The tab’s platforms out of [catalogue], the one reader’s (catalogueProvider).
  • final List<PlatformFile> platforms
  • final int pendingCount
  • final Map<String, String> models — Each catalogue entry’s name by its id, as the render dialog names the model; an entry with none has no line here.
• function bool takesAKey(PlatformFile file) — Whether [file] takes a key the user copies, kept under a store name.
• function bool identifierTaken(PlatformFile file) — Whether a card of [file] would repeat another control’s identifiers, which are made of its platform’s id and its credentials’ ids (§9.4).
• variable final providerCatalogueProvider — The bundled catalogue’s platforms, from the one reader.

lib/src/provider_keys.dart

• enum KeyStatus — A platform key’s state, as its section says it.
  • values: none, stored, verified, rejected, couldNotCheck
• class KeyState — A platform key’s display state and durable record identity, without opening the credential store.
  • const KeyState({this.status = KeyStatus.none, this.at, this.lastFour, this.checkCode, this.id}) — A key’s display state and durable credential record identity.
  • final String? id — The identity of this stored credential record, absent until a Save stores one.
  • final KeyStatus status — The last stored or checked status.
  • final DateTime? at — When this state was stored or checked.
  • final String? lastFour — The key’s last four characters: the only part of it anything shows.
  • final String? checkCode — The last check’s code (http_403, timeout, http_503), when it refused the key or could not check.
  • Map<String, Object?> toJson() — The preference record, including its identity when this build saved one.
  • static KeyState fromJson(Object? json) — Anything this cannot read is no key.
• enum KeyActionResult — What Save or Remove came to.
  • values: saved, verified, rejected, couldNotCheck, noKey, removed, storeUnavailable, busy, badValue
• class TypedCheck — What checking a value came to: the platform’s answer, or why nothing was sent.
  • const TypedCheck(this.result, {this.code})
  • final KeyActionResult result — verified, rejected, couldNotCheck, noKey, badValue or busy.
  • final String? code — The check’s code, where the platform answered.
• class KeyCard — A card of Provider keys: a key slot, <owner>:<slot>, and the platform file that says how its key is entered, checked and sent.
  • const KeyCard({required this.slot, required this.platform})
  • final PluginKeySlot slot
  • final PlatformFile platform
  • String get name — <owner>/<slot>: the key’s name in the preferences and in the store’s name (filmopen/<owner>/<slot>), and the card’s in [providerKeysProvider].
• variable final providerKeysProvider — The keys’ states, by key name, <owner>/<slot>.
• enum KeyActivity — What a platform’s key is doing while an action runs.
  • values: saving, checking, removing
• variable final keyActivityProvider — The actions running, by key name.
• class KeyActivityController — Kept by [ProviderKeysController] alone.
• class ProviderKeysController — The only code that opens the credential store for Provider keys, and only on a gesture: Save and Remove.
  • KeyState stateOf(String name) — The state of the key named [name], <owner>/<slot>.
  • Future<TypedCheck> save(KeyCard card, Map<String, String> typed) — Checks [typed] with the platform and stores it where the platform accepts it.
  • Future<KeyActionResult> remove(KeyCard card) — Deletes the value under the slot’s store name and its preference record, and nothing else; either failing answers [KeyActionResult.storeUnavailable].

lib/src/provider_keys_tab.dart

• function Uri guideAddress(String route) — Where the documentation site serves a platform’s guide.
• typedef typedef LinkOpener — Opens a page in the user’s browser, and answers whether it did.
• function Future<bool> openExternalLink(Uri uri) — The browser, through url_launcher.
• class GeneralKeysSection — The keys section of Settings → General (Software Specification §6.7, §9.4): how keys are kept, the cards of whoever uses the keys, then a line on the pending platforms.
  • const GeneralKeysSection({super.key, this.webBuild = kIsWeb, this.openLink = openExternalLink, this.leading = const []})
  • final bool webBuild — The web build keeps no keys (§6.7): the section is one sentence there.
  • final LinkOpener openLink — How a guide or a keys page is opened; a test passes its own, so no test reaches the browser.
  • final List<Widget> leading — Cards of whoever uses the keys, drawn above them with their own spacing, such as dictation’s choice of engine.
• class KeyCards — An enabled plug-in’s key cards on its page, one per key slot, spaced as a page’s cards are, with no space after the last; nothing for an owner with no slot to show.
  • const KeyCards({super.key, required this.owner, this.openLink = openExternalLink})
  • final String owner — The plug-in’s tag.
  • final LinkOpener openLink — How a guide or a keys page is opened.
• function List<KeyCard> keyCardsOf(PluginKeyOwner owner, List<PlatformFile> platforms) — Builds [owner]’s key cards from the catalogue or its own eligible platform files.

lib/src/usage_providers.dart

• variable final usageReadingProvider — Everything the log holds, read again on each append of this app’s own (another copy of the app writing is seen the next time the Activity page is opened, since readers take no lock).
• variable final usageChainsProvider — The calls the log holds, newest first: what Usage lists.
• variable final usageMonthProvider — Which month Usage shows, or null for every month.
• class UsageMonthController — The month chosen in Usage’s filter; filtering happens on the device.
  • void show(String? month) — Shows [month] (2026-09), or every month when null.
• variable final usageLedgerProvider — The account’s ledger for the month Usage shows (every month when none is chosen), read live and kept nowhere: when Usage is shown, when the month changes, on [UsageSection.refresh] and when the sign-in changes — never…
• typedef typedef SharedMoney — The shared plug-ins’ money among a reading’s rows, and what it adds up to, in US cents.
• function SharedMoney sharedMoney(List<LedgerRow> rows) — The rows of [rows] a shared plug-in moved money on, and their totals: the lending settlements and earnings — a row of kind settlement or earning that names a lending job and moved an amount — earned the credits,…

lib/src/usage_tab.dart

• class UsageSection — Activity’s Usage section lists this device’s work on keys, credit, plans and local models.
  • const UsageSection({super.key, this.webBuild = kIsWeb})
  • final bool webBuild — The web build keeps no usage log, as it keeps no keys (§6.7).
  • static void refresh(WidgetRef ref) — Reads the log again: another copy of the app may have written since (§6.4), which no change of this app’s announces, and readers take no lock.