docs: reorder & testing

pkg/model/user/user.go

@@ -16,6 +16,19 @@ const (
 	// MessageTypeUpdateMySettings is the authenticated gateway message type used
 	// to mutate self-service settings fields.
 	MessageTypeUpdateMySettings = "user.settings.update"
+
+	// MessageTypeListMySessions is the authenticated gateway message type used
+	// to read the caller's active device sessions.
+	MessageTypeListMySessions = "user.sessions.list"
+
+	// MessageTypeRevokeMySession is the authenticated gateway message type used
+	// to revoke one of the caller's device sessions.
+	MessageTypeRevokeMySession = "user.sessions.revoke"
+
+	// MessageTypeRevokeAllMySessions is the authenticated gateway message type
+	// used to revoke every device session belonging to the caller (logout
+	// everywhere).
+	MessageTypeRevokeAllMySessions = "user.sessions.revoke_all"
 )
 
 // GetMyAccountRequest stores the authenticated self-service read request for
@@ -198,3 +211,78 @@ type ErrorResponse struct {
 	// Error stores the mirrored error envelope body.
 	Error ErrorBody `json:"error"`
 }
+
+// DeviceSession stores the transport-ready snapshot of one device session
+// served by the authenticated user-surface session endpoints.
+type DeviceSession struct {
+	// DeviceSessionID stores the durable device-session identifier.
+	DeviceSessionID string `json:"device_session_id"`
+
+	// UserID stores the authenticated user identity bound to the session.
+	UserID string `json:"user_id"`
+
+	// Status stores the lifecycle state of the session
+	// (`active` or `revoked`).
+	Status string `json:"status"`
+
+	// ClientPublicKey stores the standard base64-encoded raw 32-byte
+	// Ed25519 client public key, when populated.
+	ClientPublicKey string `json:"client_public_key,omitempty"`
+
+	// CreatedAt stores when the session was created.
+	CreatedAt time.Time `json:"created_at"`
+
+	// RevokedAt stores when the session was revoked, if revoked.
+	RevokedAt *time.Time `json:"revoked_at,omitempty"`
+
+	// LastSeenAt stores when gateway last resolved this session.
+	LastSeenAt *time.Time `json:"last_seen_at,omitempty"`
+}
+
+// ListMySessionsRequest stores the authenticated self-service "list my
+// active sessions" command. The body is intentionally empty.
+type ListMySessionsRequest struct{}
+
+// ListMySessionsResponse stores the success payload of MessageTypeListMySessions.
+type ListMySessionsResponse struct {
+	// Items stores the caller's currently active device sessions.
+	Items []DeviceSession `json:"items"`
+}
+
+// RevokeMySessionRequest stores the authenticated self-service single
+// session revocation request.
+type RevokeMySessionRequest struct {
+	// DeviceSessionID identifies the device session to revoke. The
+	// session must belong to the caller; otherwise the response carries
+	// the same error shape as a missing session so foreign session ids
+	// cannot be probed.
+	DeviceSessionID string `json:"device_session_id"`
+}
+
+// RevokeMySessionResponse stores the success payload of
+// MessageTypeRevokeMySession.
+type RevokeMySessionResponse struct {
+	// Session stores the post-revoke snapshot of the affected session.
+	Session DeviceSession `json:"session"`
+}
+
+// RevokeAllMySessionsRequest stores the authenticated self-service
+// "logout everywhere" command. The body is intentionally empty.
+type RevokeAllMySessionsRequest struct{}
+
+// DeviceSessionRevocationSummary stores the count of sessions revoked by a
+// bulk operation.
+type DeviceSessionRevocationSummary struct {
+	// UserID identifies the user whose sessions were affected.
+	UserID string `json:"user_id"`
+
+	// RevokedCount stores how many sessions transitioned to revoked.
+	RevokedCount int `json:"revoked_count"`
+}
+
+// RevokeAllMySessionsResponse stores the success payload of
+// MessageTypeRevokeAllMySessions.
+type RevokeAllMySessionsResponse struct {
+	// Summary stores the user_id and revoked_count snapshot.
+	Summary DeviceSessionRevocationSummary `json:"summary"`
+}