Secretive

link-secretive holds every secret Link holds, in one of its types by where it may go, so a wrong way doesn't compile. Beside them are shared HMAC and inbound-post verification, and process guards for programs that hold secrets.

Its types

Each type says where its secret may go: nowhere, to a program by name, into a signature, or sealed to one recipient.

OpaqueSecret

One Link uses and nobody reads, such as an agent's proof secret or a service's signing secret. It signs and checks; there is no way to its bytes.

Secret

A value another program or service must be given, such as a model's API key, a connection's token or a password. It's read only by asking for it by name, Secret::expose, at a place a review sees; it's never serialized but by bare, never copied but by Secret::duplicate.

SigningSecret

An Ed25519 key pair's private half, such as a machine's key, which signs and says its public half. keep returns its private PKCS #8 document as a Secret for reviewed persistence; from_kept reads it back.

Sealed

Either, encrypted to one recipient, the only form that's saved or sent as it is: HPKE (RFC 9180) in its base mode, with X25519, HKDF-SHA256 and ChaCha20-Poly1305. What a sealed value is (About: whose, what kind, which version) is its additional data, so it opens only as what it was sealed as.

A recipient for one transfer

For a session, create a fresh Recipient and drop it when the transfer ends. A captured stream cannot be opened after its private key is gone. keep and from_kept also support durable recipients, such as a machine receiving actions while offline; retaining that key retains the ability to open earlier ciphertext. A sealed stream (stream) seals a fresh ChaCha20-Poly1305 secret in its header; numbered records authenticate their length and order, including a required empty final record, and a failed writer never makes a successful end.

What none of them does

None prints what it holds: Debug writes <redacted>, so a log line, an error or a struct printed with {:?} carries none. None has Display: what takes one would send <redacted> as the value, so it doesn't compile, and the value is exposed there, by name. Secret zeroes its held value on drop; byte secrets and HMAC tags compare in constant time (subtle).

Key Material in Memory

SigningSecret keeps its PKCS #8 bytes in a Secret, but each signing or public-key operation creates a temporary ring key pair whose internal memory is not zeroed on drop. These types cannot erase copies made before wrapping a value or after explicitly exposing it.

hmac

Shared HMAC-SHA256 signing and verification on ring, with one hex encoding for HMAC signatures such as agent proofs and signed webhooks. Ed25519 uses the separate signing module above.

inbound

Every post from outside that a secret vouches for (a connection's webhook, a payment's, a repository's, an agent's own) is checked here, built once. A receiver says how its sender signs, as a value (Scheme); it never writes verification.

What Inbound::verify gives every receiver

The supplied body slice is checked against max_body before signature processing (Refused::TooBig). The HTTP receiver must separately bound its read before buffering that slice. Closed by default, a receiver without a secret refuses every post (Refused::Unconfigured), and nothing builds one that takes anyone; a constant-time compare, of the secret or of its HMAC. A scheme declaring a signed time checks its window (Refused::Stale); a header-secret scheme has no timestamp or delivery ID.

Replays, rolling and answers

The delivery's id, for a Seen store to refuse a replay (Inbound::take); both the current secret and the one before it tried, so any secret rolls with no restart (Secrets); and one answer for each refusal (Refused::status).

process

A process safe to hold secrets, and its children given none but on purpose.

guard

Call first, before reading secrets or starting threads. Check the returned Guarded: protection can fail. On Linux, undumpable records whether PR_SET_DUMPABLE succeeded, restricting same-user access through /proc/<pid>; the core-file soft limit is also set to zero where possible. On macOS it records PT_DENY_ATTACH, with the same core-limit attempt. Other systems return false. memory_locked is Linux-only and requires an unlimited lock limit or CAP_IPC_LOCK; no limit is raised. Debug builds can disable the guard with LNK_SECRET_DUMPABLE for debugger tests.

Secret::from_env

Marks the variable it read as taken, and takes it out of the environment while the process has one thread, since changing the environment with another thread running isn't safe.

command and ours

command starts every child: its environment the parent's but every variable taken and every one whose name says it's a secret's (names_a_secret). ours starts a child that's one of Link's own programs: the same, and every secret this one holds handed to it on a pipe, where its Secret::from_env finds them, so a key you set for lnk reaches the module that reads it.

The pipe

It goes to that child alone: every child started here closes it, so it reaches no program the child starts in turn, but a program of its own not built on this package (a module from outside Link) gets it as Link's own do.

ends_with_parent, stand_in_front and carried

On Linux, ends_with_parent sets the child's parent-death signal; on other systems it adds no such behavior and the caller must own cleanup. stand_in_front runs a child this process waits for, its stop passed on to it; and carried, a program run for the one that started this one, as a wrapper runs it, with the environment it was given for it, whole.

A child that passes on no stop

On Linux, pass_to_group_led_by sends the stops stand_in_front passes instead to the process group a pidfd's process leads, while it has a member, for a child such as bubblewrap that passes on no signal itself. wait_in_front waits for the child and stops passing stops on before reaping it, so no stop reaches a process number it no longer holds.

watched_by_parent

watched_by_parent ends a child that never looks for its parent, such as a third-party server, on every system: when this process ends, however it ends, the child and its process group get its signal. A watcher, forked in the child's place before its program runs, keeps only the read end of a pipe whose write end this process alone holds, and signals the child when the pipe closes, then its group. It leaves once the child ends, and it's in the child's group, so stopping the group stops it; it signals the child first, so a child that left the group is still reached.

give

The one way to hand a child a secret in its environment, for a program that reads one nowhere else: each a reviewed place, with why.

OwnedChild

process::OwnedChild owns a subprocess and its process group on Unix. It observes exit without reaping the leader, stops the group before reaping and refuses numeric group signals if another reaper has taken ownership. Its child borrow is for pipes and identity only, never wait or try_wait. release transfers the complete cleanup obligation to a separate owner, as a durable service controller does. Descendants must remain in the owned group for group cleanup to cover them.

Derive Explicit Copies

Secretive Derive documents the derive macro for types that hold secrets, including how to distinguish secret fields from fields copied through Clone.