aetheris-protocol 0.2.0

High-performance binary contracts and communication traits for the Aetheris Engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

syntax = "proto3";
package aetheris.auth.v1;

service AuthService {
    // ── Email OTP path ──
    rpc RequestOtp(OtpRequest) returns (OtpRequestAck);

    // ── Unified Login path ──
    rpc Login(LoginRequest) returns (LoginResponse);
    rpc CreateGoogleLoginNonce(GoogleLoginNonceRequest) returns (GoogleLoginNonceResponse);

    // ── Session lifecycle (unchanged) ──
    rpc Logout(LogoutRequest) returns (LogoutResponse);
    rpc RefreshToken(RefreshRequest) returns (RefreshResponse);
    rpc IssueConnectToken(ConnectTokenRequest) returns (ConnectTokenResponse);
}

// ── Email OTP ──────────────────────────────────────────────────────

message OtpRequest {
    // RFC-5321-compatible email. Server normalizes (lowercase, trim).
    string email = 1;
}

message OtpRequestAck {
    // Opaque server-chosen handle for this OTP attempt.
    string request_id = 1;
    // Unix timestamp in milliseconds when the request expires.
    uint64 expires_at_unix_ms = 2;
    // populated if the email is rate-limited.
    optional uint32 retry_after_seconds = 3;
}

// ── Unified Login ──────────────────────────────────────────────────

message LoginRequest {
    oneof method {
        OtpLoginRequest    otp    = 1;
        GoogleLoginRequest google = 2;
    }
    ClientMetadata metadata = 3;
}

message ClientMetadata {
    string client_version = 1;
    string platform       = 2; // e.g., "wasm", "ios", "windows"
}

message OtpLoginRequest {
    string request_id = 1;
    string code       = 2;  // 6-digit numeric, ASCII "000000".."999999"
}

message GoogleLoginRequest {
    string google_id_token = 1;
    string nonce_handle    = 2; // Handle returned by CreateGoogleLoginNonce
}

message GoogleLoginNonceRequest {}
message GoogleLoginNonceResponse {
    string nonce_handle = 1;
    string nonce        = 2; // To be passed to Google OIDC by the client
    // Unix timestamp in milliseconds when the nonce expires.
    uint64 expires_at_unix_ms = 3;
}

// ── Shared response shape ──────────────────────────────────────────

message LoginResponse {
    string session_token = 1;
    // Unix timestamp in milliseconds when the session expires.
    uint64 expires_at_unix_ms = 2;
    string player_id     = 3;
    bool   is_new_player = 4;
    LoginMethod login_method = 5;
}

enum LoginMethod {
    LOGIN_METHOD_UNSPECIFIED = 0;
    LOGIN_METHOD_EMAIL_OTP = 1;
    LOGIN_METHOD_GOOGLE_OIDC = 2;
}

// ── Session lifecycle (unchanged) ─────────────────────────────────

message LogoutRequest  { string session_token = 1; }
message LogoutResponse { bool revoked = 1; }

message RefreshRequest  { string session_token = 1; }
message RefreshResponse {
    string session_token = 1;  // fresh PASETO; old token's jti added to deny-list
    // Unix timestamp in milliseconds when the session expires.
    uint64 expires_at_unix_ms = 2;
}

message ConnectTokenRequest {
    string session_token  = 1;
    string server_address = 2;  // "host:4433"
}

message ConnectTokenResponse {
    QuicConnectToken token = 1;
}

message QuicConnectToken {
    // PASETO v4.local, footer = key id (kid) for rotation, payload = claims below.
    string paseto             = 1;
    string server_address     = 2;
    uint64 expires_at_unix_ms = 3;
    uint64 client_id          = 4;  // u64, randomly assigned at issuance
}