Define the interface through which a client stores a session secret

[iderex]

The session record in #5 says the core never writes a credential to its own cache
or log, and that a platform keychain is the only acceptable place at rest. That
makes storage a client responsibility, and a responsibility with no interface is
a responsibility nobody has.

What this produces

A named interface with two operations, storing and retrieving a secret for a
named server, and one for forgetting it.

Documentation stating that the implementation has to be the platform's own
protected storage, and naming what each platform family offers, so that a client
author does not reach for a file.

Behaviour when the client supplies no implementation at all: the core works and
the session lives only as long as the process. This is the correct default,
because a core that silently falls back to a file has made the decision the
record forbids.

A test double for the suite that keeps secrets in memory and is never written to
disk.

Done when

The interface exists, the core compiles and passes its suite with no
implementation supplied, and a test proves that with none supplied nothing
secret reaches the cache directory or any log. Blocked on #5.

[iderex]

The interface landed as docs/decisions/0033-the-secret-store-interface.md, on cf9705d.

Three operations and no fourth: keep a secret under one name, read it back, forget it. Forgetting one that is not there succeeds, for the reason 0040 already gives about a caller that has to ask first.

The operation this issue does not name and somebody will reach for is enumeration, so the record says what replaces it. A client that wants to restore a session at start already knows which sessions it configured, because 0005 makes the whole of a session except the token ordinary data that may be cached and shown, and the core reads the secret for a session the caller names. The keychain is asked one question about one name and never asked what it holds. What that costs is an orphan: a client that loses its own list has secrets in the platform store that nothing will name again. That is smaller than its alternative, since enumeration over a platform keychain differs most between platforms, several of them return items other applications wrote, and a core that enumerated would be reading entries it did not create to decide which are its own.

The three things this issue asks the interface to settle are settled. Storing, retrieving and forgetting are the surface. Behaviour with no implementation supplied is that the core works, the session lives as long as the process, and it says so through a capability that is a call which cannot wait in the terms of 0009, so a client can decide when to ask somebody to sign in rather than being surprised at the moment they press play. The absence never degrades to a file, which 0005 and 0101 both already refuse.

Three answers the issue did not ask for, each because the convenient handling is wrong in a way nothing would report.

The name handed to the store is derived the way #41 derives a cache key rather than written out. A keychain item is protected in its value and frequently not in its label, and a label appears in the platform's own listing, in a device backup, and in the view a person opens to see what an application stored. A label reading as an address and an account is the leak 0072 describes, written by the part of the system that is supposed to be careful.

A failed read is not an absence. An absence means sign in again; a failure means the secret may still be there, and a new one may not be written under that name until a read succeeds. The convenient handling treats a failed read as empty and carries on, which on a device locked during a background start replaces a working session's secret.

What comes back is validated before use: non-empty, within a length bound, and composed only of bytes that can be placed in the header it is going into without escaping. The last is the one that is not decoration, since a value carrying a line ending is a request the core would assemble on somebody else's behalf. A value failing any of the three is not repaired or trimmed. The session is signed out and the value forgotten.

The platform facilities are named in the record as a claim rather than as a measurement, because nothing in this tree reads a platform and no command in this repository produces that list. What a client author applies is the property, which is the facility whose contents are protected by the platform rather than by file permissions the application chose.

All three conditions here are untouched. The interface existing, the core compiling and passing its suite with none supplied, and a test proving nothing secret reaches the cache directory or any log are statements about running code, and there is no language chosen, no build and no test command in this tree to assert them against. This stays open on all three.