Secrets Contract

link-secret-contract, the library every program that keeps or gives a secret reads it through: the store, its grants, the keeper's protocol and the secret route's types. lnk-secret is its command line (Secrets).

The store

A user's secrets are kept as files, secrets.toml (mode 600) and its lock beside it: yours in Link's settings (~/.lnk/safe/secrets/secrets.toml, path), or one the keeper keeps for a user (Store). Each secret is kept under its ID ([entry.<id>]), written secret:<id> (SECRET_KIND, resource), minted under the store's lock and retired when it's deleted (retired), never given again. Each value is in the Keychain where there is one, its account secret/<id> (KEYCHAIN). A store of the shape before IDs, each secret under its name, is refused.

Reading it

list gives each secret kept for you, by ID (Listed): its kind (SecretKind), named or own, its name, or for an own secret whose it is (Owner), how it's given and where, never its value, and those no longer kept but with copies left elsewhere, by their copies alone. A command names a secret by its name or secret:<id> (Called), never told apart by an ID's shape. for_service gives what a service is granted, by its ID, its own or what lnk secret add gave it; a value the Keychain should hold and doesn't is an error, naming it.

Read as you

for_you gives your own named secrets of the IDs asked, read as their holder, for what you run yourself: an environment module gives an environment the secrets you approved for it this way, and the secret module names no environment. One deleted since is left out.

Writing it

add keeps a secret under a new ID, sealed when it's sealed, given where its grant says, replacing whatever was kept by that name, whose ID it retires; it gives the new ID. grant adds and takes grants of a secret named by name or ID. keep_own keeps a service's own secrets, dropping one no longer its own, and is written only when something changed. clear removes every secret kept for you, and their store, for lnk uninstall.

Own secrets

A service's own secret has no name: it is found by its service and its Use, Use::Own with a purpose the module that keeps it names (model, connection:telegram:bot_token), so a rename changes none of it, and grant refuses it. The contract checks a purpose's shape and never reads its meaning. Use::flag writes a use for a command line, and Use::from_flag reads it back.

Grants

Grant is a principal, an action and a resource, the secret it's kept under. The principal is the service a workload acts as, service:<id> (a link_principal::Principal), never the workload. The action follows how the secret is kept, Action::Pass for a sealed one and Action::Read for a plain one. Beside them are the workload, <kind>:<id>, and the name it was granted by, to show, and Use, how it's given. A grant to anything but a service, or of another action, is refused as the store is read. Grant::new makes one for a Grantee, and service_principal names a service.

Who a grant names

lnk secret add --to <kind>:<name> asks the modules that keep workloads where the one of that kind and name is (GRANTEE, the question secret.grantee, answered with a GranteeAt in this contract's types, at protocol 2).

Its answers

Its answers are Stable IDs': here, with the workload's ID and the principal it acts as, service:<id>; unstarted, with the command that gives it an ID; on, the machine it's on; none, of a kind the module keeps but nothing of that name; and unkept, a kind it doesn't keep.

The grantee

grantee gives the Grantee, the service it acts as and its workload, or an error naming the machine it's on, where its secrets are given it, or the command that gives it an ID. The kind is the answering module's word, and the contract names none.

Copies a move gives

copied notes a place (Place, a box or an account by its name) for each of a service's own secrets before its owner sends them there, never a secret lnk secret add gave it. Once its entry is gone from here, the copies stay under the secret's retired ID with the service's ID and the use ([left.<id>]). gone_from takes the note off once the service has left that place, and forget takes back every grant to a service whose workload leaves or is removed.

Secrets kept while away

retain_own parks selected own uses in the keeper while the service's workload is away. forget removes its live grants but keeps those values, and keep_own restores them for the same stable ID. remove deletes retained values too. copied_without omits uses the place never receives, so they are never listed as copied there.

Following a copy away

gone_from_without preserves those uses at the source after the service leaves it. Copy records keep each own use, so an owner can follow some uses away while leaving others at their source box.

Removing a secret

remove takes a Removal: a secret by its name or ID, here and at each copy, its ID retired; or, on a box a copy reached, a service's own secret by its Owner, here alone. It notes every copy as left before any is tried, and takes each reached off after, so nothing is forgotten if it's cut short. It reaches copies by asking the modules that gave them (COPIES, each Copy its place and Owner, answered per copy with a Reached); with none answering, each is unreached.

Listed for lnk secret list

held gives the secrets kept for you as lnk secret list shows them: where each is kept, where it's given and where a copy was left, never its value. One no longer kept here is listed by the copies left elsewhere. A store that can't be read, or a keeper that doesn't answer, is one entry saying so.

The keeper

The keeper runs as lnk-secrets (KEEPER_USER), which holds secrets and runs nothing else, and answers on /run/lnk-secrets/keeper.sock (SOCKET) and, for sealed routes, /run/lnk-secrets/secret.sock (ROUTE_SOCKET). here says whether there's a keeper on this machine, and running_as_keeper whether this process is it.

Its protocol

A call to whoever holds your secrets is a Request, answered with a Reply; Holder is who holds them, the keeper or your own file. The keeper never takes your file: while it holds a secret, a keeper here is refused (yours_held). serve and serve_with_routes are the keeper's side. A debug build's tests point it at a keeper of their own with LNK_TEST_KEEPER (TEST_KEEPER).

Its version

On the socket, each call is one line of JSON each way, {"protocol", "request"} and {"protocol", "reply"}, each stating the keeper protocol's version its sender speaks. The keeper is a system service, upgraded apart from your lnk, so each side refuses the other when it speaks a version older than the oldest it accepts, naming the upgrade. The versions are declared in keeper/protocol.toml (Protocol versions).

At rest

at_rest::has_tpm says whether there's a TPM. at_rest::write seals first, then atomically replaces and syncs the file and its directories; without a TPM the file is the keeper's private fallback, never the working user's. at_rest::read opens a private file, and migrates plaintext when asked.

The secret route

The route adds a sealed secret to its service's calls on their way out of a sandbox, served at /_link/secret/ on the proxy (PREFIX) by lnk secret bridge (bridge). route builds one from the secrets handed with their values and those granted by name, none named twice.

How a secret is given

Sealing is how a sealed secret is given, set with its value: the one host it's sent to, over HTTPS, the header it goes in, and that header's value. SecretRule is where a secret may go and how, which a module that owns the service gives (a connection module's rule --json) and the proxy enforces, knowing nothing of the service: its paths (SecretPath, SecretRest) and header (SecretHeader).

Names on the proxy

proxy_name gives a sealed secret's name on the proxy (stripe-key for STRIPE_KEY), which check_secret_name holds to 1 to 40 lowercase letters, digits and -, not starting with -. sealed_url_var gives the variable what runs calls its service at, LNK_SEALED_<NAME>_URL, and url that address on a proxy's port.

Placeholders

placeholder gives what a program holds in place of a secret: a tag, none of the secret, after the part a rule says isn't secret, which a client may read (secret_prefix).

Bindings

A workload's binding proves its calls to every bridge (Binding). keeper::RouteRevoker is the Revoker a keyring is given when it unbinds a workload: it asks the keeper to revoke the routes granted to that binding (unbind_route) before the key is removed.

Isolated TPM Tests

LNK_TEST_TPM substitutes the TPM (Trusted Platform Module) utility for an isolated storage fixture. LNK_TEST_TPM_RUN selects that fixture's private operation folder. Both are debug-only inputs and ignored by release builds. These stand-ins exercise storage orchestration without proving hardware sealing or recovery on another machine.