ensure method

Future<TomSettingsKey> ensure({
  1. String? message,
})

The device's settings key, minted and recorded when it has none.

Idempotent: a second run finds the handle and the secret and writes nothing. Device settings are committed only when the handle changed, which keeps an ordinary launch free of a pointless commit — and makes a wiped keychain re-mint only the secret. Re-minting the handle too would orphan a secret a restored keychain might bring back.

A secret store that fails raises TomSecretStoreException, for either call, in place of what the store threw. A miss is an answer the store gives (null) and is handled by minting; a store that could not be asked at all — a locked or denied keychain, a missing entitlement, a channel that errored — is a different situation, and the host needs to know which call failed and what the platform said, without this package naming any platform's exception type.

Implementation

Future<TomSettingsKey> ensure({String? message}) async {
  if (!device.isLoaded) await device.load();

  final storedHandle = device.settingsKeyHandle;
  final handle = storedHandle ?? const Uuid().v4();

  var secret = await _ask(
    TomSecretStoreStep.read,
    () => secrets.read(handle),
  );
  if (secret == null || secret.isEmpty) {
    final minted = _mintSecret();
    await _ask(TomSecretStoreStep.write, () => secrets.write(handle, minted));
    secret = minted;
  }

  if (storedHandle == null) {
    device.settingsKeyHandle = handle;
    await device.save(message: message ?? 'Record the settings key handle');
  }
  return (handle: handle, secret: secret);
}