Account query methods
Relay RPC protocol · Common method conventions
device.status
device.status queries an account's current home relay for the current authorization status of a specified device, primarily for authorization checks before another relay establishes a device session. A business request already authorized by a device session at the source relay does not call this method again for the same operation.
Request parameters
| Field | Type | Required | Semantics and constraints |
|---|---|---|---|
account |
string | Yes | Account ID; also the target account of this call |
device_id |
string | Yes | Device ID derived from the target device's DeviceCertificate |
Response object
| Field | Type | Required | Semantics and constraints |
|---|---|---|---|
status |
string | Yes | The device's certificate authorization result in the account's current authoritative state; active means the device certificate is currently valid, and inactive means the device currently has no valid authorization |
expires_at |
integer | Conditional | MUST be present when status is active, equal to the expiry Unix seconds of the device's latest certificate in current state; MUST be omitted when status is inactive |
Processing and caching rules
The target relay may answer only from its locally held current AccountDeviceState; another relay's cache MUST NOT serve as an authoritative result. It returns active only when current state contains a latest certificate matching the device ID, both signatures are valid, and the current time falls within its validity period. All other cases return inactive, without distinguishing never-existing, removed, not-yet-valid, or expired certificates.
The caller MUST confirm that the authenticated peer is the account's current home relay and correlate the result with the original request under the response correlation rules.
The calling relay MAY use verified results under a locally bounded caching policy. The cache MUST preserve the binding to the requested account, device, and authenticated peer, and cannot serve as a result for another account, device, or home relay. It MUST expire after that bounded window; a cached active result MUST also expire at its expires_at. Once newer state is learned, use of the old cache MUST stop.
The caller MAY use an old certificate for the same device ID to verify device public-key bindings and signatures in historical or in-flight objects. Current permissions depend only on whether that device ID remains valid in the latest authoritative state; the complete contents of the old and latest certificates need not be identical.
device.state.resolve
device.state.resolve obtains the target account's current complete device state so that the caller can select currently valid recipient devices and generate key boxes.
Request parameters
This method accepts two request forms:
- Public query:
paramsMUST explicitly contain the targetaccount, as defined by reading by account for client–relaydevice.state.resolve; it carries no request certificate, request signature, or access credential. - Signed query: use the complete signed request of client–relay
device.state.resolve, withaccountspecifying the target account. The source relay MUST NOT reconstruct, remove, or rewrite fields.
Query-form recognition and completeness validation follow the client–relay device.state.resolve WebSocket query rules. Self-read is used only between a client and its home relay and does not apply to this method.
Response object
The response object and caller validation requirements both follow the response rules of client–relay device.state.resolve.
Processing and errors
When accepting a client request, the source relay MUST confirm that the device session is still valid.
Public queries
For a public query, the target relay MUST confirm that the current profile enables public discovery; otherwise, it returns forbidden. It does not validate the client session or query the requesting device's status. An inter-relay request carrying only an account ID is always authorized as a public query; it does not inherit self-read permission granted to a client through a device session at its home relay.
Signed queries
For a signed query, the source relay MUST additionally confirm that the request certificate corresponds to the calling device and account, and verify both the request certificate and request signature. This check determines the requesting device's authorization for this read; later device-state changes do not retroactively affect the accepted request. The target relay MUST independently verify the signing device certificate, request signature, and account binding. The request signature is verified using that certificate's signing_public_key. The target relay does not query or determine the requesting device's current status again.
For a signed query, the target relay validates access credentials as specified by client–relay device.state.resolve.
Errors and routing
Errors from business validation and created_at freshness checks follow the processing rules of client–relay device.state.resolve. The source relay returns the target relay's errors to the client using the error mapping for the client's transport. Account-route changes follow the account routing rules; other errors follow the error response rules.
profile.resolve
profile.resolve obtains the specified account's currently valid AccountProfile.
Request parameters
The parameters are the complete request parameters of client–relay profile.resolve, with account specifying the target account.
Response object
The response object and caller validation requirements both follow the response rules of client–relay profile.resolve.
Processing and errors
When accepting a client request, the source relay MUST confirm that the device session is still valid. The target relay does not validate the client session, query the requesting device's status, or validate contact authorization.
Home-relay responsibility checks, parameter errors, nonexistent profiles, and response verification follow the processing rules of client–relay profile.resolve. The source relay returns the target relay's errors using the error mapping for the client's transport. Account-route changes follow the account routing rules; other errors follow the error response rules.