Part of Stem. This page defines the Authenticate method of the sync RPC specification. It is the only way a connection acquires an identity beyond its peer id.

The formal schema is attached as the schemaDefinition of this page: a struct {key, input, output} with key pinned to Authenticate.

Binds the calling peer connection to an account or to a bearer secret, so later calls are evaluated with the matching grants. A peer may authenticate as several accounts and present several secrets on one connection.

Input

field	type	required	meaning
`account`	principal	no	The account being proven. Required unless only a bearer secret is presented.
`ts`	timestamp	yes	Now, by the caller's clock; the server allows one minute of skew.
`sig`	signature	no	Signature by the account key over the canonical encoding of {account, caller peer id, server peer id, ts}. Required with `account`.
`bearer`	bytes	no	A bearer secret whose SHA-256 appears in a live bearer Grant. Puts the connection in that grant's audience. May be combined with an account proof.

Output

field	type	required	meaning
`expires`	timestamp	yes	When the binding lapses unless renewed; also lapses when the connection closes.

Rules

The signed payload is the canonical DAG-CBOR of the struct {account, caller, server, ts} where caller and server are the two peer ids as principals. The server reconstructs it from the connection and verifies sig with account.

ts must be within one minute of the server's clock; otherwise invalid-argument. This is the one place a clock is checked.

A connection may be bound to several accounts; each binding is independent and lasts until expires, until Goodbye, or until the connection closes, whichever is first. A client renews by calling again.

Binding changes nothing about what the server stores. It only changes which readers sets the connection is evaluated against from now on.

A failed Authenticate is counted like a failed dial for backoff and leaves no record other than that.

Today (HM24)

HM24's P2P.Authenticate carries {account, timestamp, signature} and signs an unstored Capability blob whose delegate is the caller peer id and whose audience is the server peer id (Network). Stem keeps the construction and drops the Capability vocabulary: the payload is a plain struct. HM24 unlocks the private blobs of every space the account owns or holds a WRITER capability for; Stem unlocks exactly the blobs whose readers include the account.

Example

{"key": "Authenticate", "input": {"account": {"/": {"bytes": "7QEAq1…"}}, "ts": 1759910400000, "sig": {"/": {"bytes": "kJ3f…"}}}}

{"expires": 1759914000000}

Input

Output

Rules

Today (HM24)

Example

See also