Module formation_credentials 

Who in a formation may call whom: the credential a formation launcher issues for each roster edge, the check every member’s door makes, and the channel a member’s runtime is handed its credentials and its callees’ addresses on.

There is one principal per formation, and it is the launcher. After minting the FormationId, the launcher generates one Ed25519 key pair (FormationAuthority) and signs one FormationToken for every roster edge from → to:

mft1 "." base64url-nopad(payload JSON) "." base64url-nopad(Ed25519 signature)
payload: {"formation":"frm_…","from":"<member>","to":"<member>"}
signed:  FORMATION_TOKEN_DOMAIN ‖ 0x1f ‖ "mft1" ‖ 0x1f ‖ <payload base64url>

The signing key exists only in the launcher’s memory: it is never written, never put in an environment variable and never sent anywhere. Every member is handed the 32-byte public key (FormationVerifyKey) and nothing that signs, so no member can mint a token.

A token is bound to its audience. to is signed, so a token presented at any door but the one it was issued for is refused there (FormationRefusal::NotPermitted) and reaches nothing. Verification order is fixed: tag → signature → payload → formation id, and every failure among them is the one FormationRefusal::Invalid. Only a token that passed all four is looked at for its audience, so a forged or foreign token learns nothing about which members exist.

There is no expiry, rotation or revocation list. One formation is one task. The launcher drops the key when the formation is torn down, and a new launch of the same roster has a new id and a new key, so no token outlives what it was issued for.

Tokens reach a member’s runtime and nothing else. The launcher writes each member’s FormationBundle as the first line of a pipe only that member’s mur run inherits, named by FORMATION_CHANNEL_ENV, and later lines carry callees’ door URLs as they become known. FormationMember reads the channel. A guest sees its callees’ names and the virtual address http://<name>.formation.invalid under the reserved .invalid domain; the runtime’s egress resolves that to the real door and attaches the token. No token reaches an environment variable, argv, a file, stdout, the trace, an error or Debug output: FormationToken has no Display and no Serialize, and FormationToken::expose is the one way to read it.

Structs

FormationAuthority

A formation’s signing key: generated by the launcher for one formation and held in its memory alone. Dropping it — at teardown — leaves nothing that can mint for that formation again.

FormationBundle

One member’s credentials, as its channel’s first line carries them:

FormationCaller

The member a verified formation token was issued to.

FormationMember

One member’s live formation state: who it is, what its door accepts, the tokens for the members it may call, and the door URLs of those members as the channel delivers them.

FormationToken

One formation token’s text.

FormationVerifier

What one member’s door holds to check a formation token: its formation, its own name, and the formation’s public key.

FormationVerifyKey

A formation’s 32-byte Ed25519 public key.

Enums

FormationRefusal

Why a formation token was not let in.

Constants

FORMATION_ADDRESS_WAIT

How long a guest’s request to a callee waits for that callee’s address to arrive on the channel before it is refused.

FORMATION_CALL_SCOPES

Exactly what a valid formation token reaches at the door it was issued for: starting a task, and reading, listing, cancelling and subscribing to the tasks this member started. The door answers every other task as it does an id it never held. No SendStreamingMessage, since SendMessage and SubscribeToTask together reach everything it would, and nothing that watches or stops the session or reads files.

FORMATION_CHANNEL_ENV

The variable a formation launcher sets in each member’s environment, naming the inherited file descriptor its formation channel is read from. Set by mur run --roster and nothing else.

FORMATION_CHANNEL_FIRST_LINE_DEADLINE

How long a member waits for its channel’s first line before its launch is refused.

FORMATION_CREDENTIAL_PREFIX

The prefix of the door credential a formation token is let in as: member:<from>. A declared credential name cannot contain :, so the two never collide.

FORMATION_PEER_DOMAIN

The reserved domain every virtual callee address sits under. .invalid never resolves (RFC 6761), so a request that escaped the runtime’s egress reaches nobody.

FORMATION_TOKEN_DOMAIN

The signature domain of a formation token. Distinct from every MAC domain, so no other token family’s bytes are ever a formation token’s signed input.

FORMATION_TOKEN_TAG

The version tag of a formation token.

Functions

is_formation_host

Whether host lies under FORMATION_PEER_DOMAIN, in any letter case. Every such request is the runtime’s to route or to refuse; none is ever sent as written.

parse_address_line

Read an address line. Every URL must be http://host:port. The error never quotes the line.

render_address_line

One address line: {"addresses":[{"name":"coder","url":"http://127.0.0.1:41873"}]}.

virtual_member

The member authority names when it is exactly <name>.formation.invalid — one label, no port, no user info — or None.

virtual_url

The virtual address a guest calls name at: http://<name>.formation.invalid.