public class SecureStorage

Configures the iOS keychain access group for sharing entries between the main app and its extensions. The argument must include the Team ID prefix (e.g. "ABCDE12345.group.com.example.app"). Pass null or empty to clear. Ignored on non-iOS platforms and on the fallback base class.

The ios.keychainAccessGroup build hint must declare the same group in the app’s entitlements for this to work.

The entry is there. Stores a value only if this account has none, and reports what the store ended up holding.

The operation a first-time key needs. Reading, generating and storing as three steps is safe within one process and not between two: synchronized covers threads in one VM, while an application can be opened from more than one – Android components declared with their own android:process, or simply two runs of a desktop build – and both can see nothing stored, generate different keys, and each overwrite the other. The database is then encrypted with whichever key did not survive, and nothing can open it again.

The return value is what makes racing callers agree: a caller that lost stores nothing and is handed the value that won, so both go on to open the database with the same key.

This default is the best a store with no create-if-absent of its own can do – the check and the write are still two operations, so a second process can land between them, and what it prevents is the divergence rather than the race. A port whose store can do this in one step overrides it; iOS does, because the keychain’s own add fails when the item exists.

A name unique to this application, for a store the platform shares between applications.

The mobile ports do not need this: an OS sandbox already separates one application’s keychain or keystore from another’s. A native desktop build has no sandbox – its storage is a plain directory under the user account – so two applications that ask for the same account name reach the same entry. For a managed database key that means one application reading another’s key, and forgetting it in either one removing the other’s only copy.

The package is what the installer, the store and the build all treat as the application’s identity. A display name is the fallback because a build without a package still has one, though it is weaker: two vendors can both ship “Notes”.

The same identifier, for a port that knows the application before Display can say.

The simulator is that case: it builds its store while the port is still coming up, so Display cannot answer yet – and it has the launcher’s main class in hand, which is where its package_name comes from in the first place.

The file name a port uses to gate the creation of one account, for the ports whose create-if-absent is a file.

Derived from the account itself rather than from its hash, because a hash is not a name: Aa and BB hash alike, so two aliases would share one gate and whichever asked second could never create its key – it would find no value of its own and no gate to take. The escape is the one #applicationNamespace() uses, so the result is reversible and two accounts that differ keep different gates.

A name too long to be a file gets its first part plus a hash of the whole, which is the one place a hash is the right answer: the alternative is a name the filesystem refuses.

Whether an entry exists, as distinct from whether it can be read.

#get(String) cannot answer this: it returns null for an entry that is not there and for one it could not read, and a caller that treats those alike will eventually treat a store that is briefly unavailable as a store that is empty. Where that caller then writes – a managed database key is the case this was added for – it overwrites a key that was there all along, and the database encrypted under the old one can never be opened again.

A port answers #ENTRY_PRESENT for an entry it can see even if it cannot decrypt it: the question is existence, not readability. The default is #ENTRY_UNKNOWN, which is the honest answer for a platform with no non-prompting store, and callers must treat it as “do not write”.