diff --git a/README.md b/README.md index eaddd7f..54fa499 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,9 @@ # Rotom Protos -This repository contains the protobuf definitions for Rotom. +This repository contains the protobuf definitions for Rotom. It also contains some documentation, with the idea being to add more documentation later on. + +## Documentation +- `documentation/ROTOMPROTOS.md`: History and full explanation of the `rotom.proto` file. ## Connecting to Rotom diff --git a/documentation/ROTOMPROTOS.md b/documentation/ROTOMPROTOS.md new file mode 100644 index 0000000..8a7e57a --- /dev/null +++ b/documentation/ROTOMPROTOS.md @@ -0,0 +1,236 @@ +# Rotom Protos - `rotom.proto` Explanation/History + +This document will go over the `rotom.proto` file. It will be a more in-depth explanation that should solve some oftenly misinterpreted things. + +The document will contain both a changelog and a full guide explanation of the protos on a per-block basis. + +## Changelog/Update Log + +- [30-10-2023 - bb03987:](https://github.com/UnownHash/RotomProtos/commit/bb0398733bcd1571d34ea809a7daf142e9bd9dd3) Initial `rotom.proto` file creation. + +- [16-11-2023 - 90eb80d:](https://github.com/UnownHash/RotomProtos/commit/90eb80dfe89b6af718b2b0816242e961c294f470) Add `ptc_oauth` as a method of authentication, to counter PTCs new anti-botting implementations. + +- [16-11-2023 - 816030b:](https://github.com/UnownHash/RotomProtos/commit/816030b71dae538ebce06cf7d30a12880bf2af9a) Add a new `RPC_STATUS_MITM_DISALLOWED_REQUEST` RPC status in a attempt to cope with the new anti-botting implementation(s). + +- [19-11-2023 - f8bb08a:](https://github.com/UnownHash/RotomProtos/commit/f8bb08a5a2dbd83d75ec33f8a3ab05d3ae133214) Change `MitmResponse.LoginResponse.device_id` to `MitmResponse.LoginResponse.worker_id`, to align with a new controller update. + +- [20-2-2024 - 8342c0d:](https://github.com/UnownHash/RotomProtos/commit/8342c0dd1a307ed676da8d132a87eecc22b5f235) Change `MitmResponse.Status` to allow for more abstract custom MITM error messages. + +- [06-04-2024 - d75499f:](https://github.com/UnownHash/RotomProtos/commit/d75499fea7524f939fb693a2c866ab1b246ae26d) Add a `useragent` field to `MitmResponse.LoginResponse` to align with new controller updates. + +- [14-04-2024 - ef1ccce:](https://github.com/UnownHash/RotomProtos/commit/ef1ccce6e1fc40bdec36335857cd95ad2876a18f) Add Facebook/Google as login sources to `MitmRequest.LoginRequest.LoginSource` as controllers start accepting Facebook/Google accounts. + +- [29-05-2024 - 2ee6d0f:](https://github.com/UnownHash/RotomProtos/commit/2ee6d0f2809cc42e1e714f7179f289d5b4512645) Add `N_KIDS` to `MitmRequest.LoginRequest.LoginSource` since controllers started adapting Niantic Kids as a new way to map without relying on PTC. It was later learned that the login source is actually `SUPER_AWESOME`, not `N_KIDS`. + +- [23-09-2024 - 4677808:](https://github.com/UnownHash/RotomProtos/commit/46778084df2593d4281075c93d30f55594681c38) Add two new RPC response methods to be able to counter Google Play (Google Play Integrity/Google SafetyNet)-related methods. + +- [28-08-2026 - XXXXXXX:](https://github.com/UnownHash/RotomProtos/blob/main/rotom.proto) **Will be updated on next PR, as the commit hash is unobtainable now.** Add new `NIANTIC_JWT` login method to align with the new Niantic Kids authentication flow and to support the (most likely to happen) upcoming authentication flow changes. + +## Full `rotom.proto` Explanation + +Protos will be explained in the following format: `### MitmRequest => LoginRequest => LoginSource` + +--- + +### Message - MitmRequest + +#### Enum - Method: + +- `0 - UNSET`: Unhandled/out of scope method. +- `1 - LOGIN`: Method to request a MITM login. +- `2 - RPC_REQUEST`: Method to ask the MITM to send a RPC request. + +#### Message - LoginRequest: + +##### Enum - LoginSource: + +- `0 - UNSET`: Unhandled/out of scope login source. +- `1 - PTC [deprecated = true]`: DEPRECATED - Old PTC login method, pre-update. +- `2 - PTC_OAUTH`: Updated PTC OAuth flow login source. +- `3 - FB`: Facebook OAuth login method. +- `4 - GOOGLE`: Google OAuth login method. +- `5 - SUPER_AWESOME [deprecated = true]`: DEPRECATED - Old Niantic Kids login method, now deprecated and using the new `NIANTIC_JWT` login method. +- `6 - NIANTIC_JWT`: New auth flow, will (most likely) eventually replace all other login methods. + +##### Fields: + +- `string username = 1`: Account username. +- `LoginSource source = 2`: The `LoginSource` enum containing the selected login method. +- `bytes token_proto = 3`: The pre-encoded proto (encoded by the controller) containing the token in the game-required format. +- `string worker_id = 4`: The worker ID the controller assigned. +- `bool enable_compression = 5`: Whether to enable Rotom's compression or not. + +#### Message - RpcRequest: + +##### Message - SingleRpcRequest: + +###### Fields: + +- `int32 method = 1`: RPC method ID. +- `bytes payload = 2`: Pre-encoded (encoded by the controller) protobuf payload. +- `bool is_compressed = 3`: Whether it's compressed or not. + +##### Fields: + +- `repeated SingleRpcRequest request = 1`: The single RPC request proto mentioned above. +- `double lat = 2`: Latitude of the location the RPC should be sent from. +- `double lon = 3`: Longitude of the location the RPC should be sent from. + +#### Fields: + +- `uint32 id = 1`: Unique request ID used to associate the request with its response. +- `Method method = 2`: The `Method` enum containing the requested MITM method. + +#### Oneof - payload: + +- `LoginRequest login_request = 3`: The login request payload when requesting a MITM login. +- `RpcRequest rpc_request = 4`: The RPC request payload when requesting the MITM to send one or more RPC requests. + +--- + +### Message - MitmResponse + +#### Enum - Status: + +- `0 - UNSET`: Unhandled/out of scope response status. +- `200 - SUCCESS`: Request successfully completed. +- `500 - ERROR_UNKNOWN`: Unknown MITM error. +- `501 - ERROR_RETRY_LATER`: Temporary error where the controller should retry later. +- `502 - ERROR_WORKER_STOPPED`: The assigned worker has stopped. +- `503 - ERROR_RECONNECT`: The controller should reconnect to the MITM. +- `504 - ERROR_RESTART_SESSION`: The controller should restart the current worker session. + +#### Message - LoginResponse: + +##### Fields: + +- `string worker_id = 1`: Worker ID associated with the login/session. +- `AuthStatus status = 2`: The authentication status returned by the worker. +- `bool supports_compression = 3`: Whether the MITM supports Rotom compression. +- `string useragent = 4`: User agent used by the worker. + +#### Message - RpcResponse: + +##### Message - SingleRpcResponse: + +###### Fields: + +- `int32 method = 1`: RPC method ID. +- `bytes payload = 2`: Pre-encoded protobuf response payload. +- `bool is_compressed = 3`: Whether the response payload is compressed or not. + +##### Fields: + +- `RpcStatus rpc_status = 1`: The status of the RPC request. +- `repeated SingleRpcResponse response = 2`: The returned single RPC responses. + +#### Fields: + +- `uint32 id = 1`: Request ID matching the corresponding `MitmRequest`. +- `Status status = 2`: General MITM response status. + +#### Oneof - payload: + +- `LoginResponse login_response = 3`: Response payload for a login request. +- `RpcResponse rpc_response = 4`: Response payload for a RPC request. + +#### Fields: + +- `string mitm_error = 100`: Optional custom MITM error message containing more detailed error information. + +--- + +### Message - WelcomeMessage + +#### Enum - Platform: + +- `0 - UNSET`: Unknown/unset worker platform. +- `1 - IOS`: Worker is running on iOS. +- `2 - ANDROID`: Worker is running on Android. + +#### Fields: + +- `string worker_id = 1`: Unique worker ID. +- `string origin = 2`: Origin/implementation of the worker. +- `int32 version_code = 3`: Numeric game version code running on the worker. +- `string version_name = 4`: Human-readable game version running on the worker. +- `string useragent = 5`: User agent used by the worker. +- `string device_id = 6`: Device ID of the worker device. +- `Platform platform = 7`: The platform the worker is running on. +- `bool reserved1 = 8`: Reserved field. +- `string reserved2 = 9`: Reserved field. + +--- + +### Enum - AuthStatus + +- `0 - AUTH_STATUS_UNSET`: Authentication status is unset or unknown. +- `1 - AUTH_STATUS_AUTH_TOKEN_REQUEST_FAILED`: Requesting an authentication token failed. +- `2 - AUTH_STATUS_AUTH_TOKEN_REQUESTED`: An authentication token has been requested. +- `3 - AUTH_STATUS_GOT_AUTH_TOKEN`: An authentication token was successfully received. +- `4 - AUTH_STATUS_DEVICE_INCOMPATIBLE`: The device is incompatible. +- `5 - AUTH_STATUS_USER_NOT_FOUND`: The requested user/account could not be found. +- `6 - AUTH_STATUS_ACCESS_DENIED`: Access was denied. +- `7 - AUTH_STATUS_ACCESS_SUSPENDED`: Access to the account has been suspended. +- `8 - AUTH_STATUS_ACCESS_RATE_LIMITED`: Access has been rate limited. +- `9 - AUTH_STATUS_SESSION_TERMINATED`: The current session was terminated. +- `10 - AUTH_STATUS_SESSION_FAILED`: The current session failed. +- `20 - AUTH_STATUS_LOGIN_TIMEOUT`: The login attempt timed out. + +--- + +### Enum - RpcStatus + +- `0 - RPC_STATUS_UNDEFINED`: RPC status is undefined or unset. +- `1 - RPC_STATUS_SUCCESS`: RPC request completed successfully. +- `3 - RPC_STATUS_BAD_RESPONSE`: An invalid/bad RPC response was received. +- `4 - RPC_STATUS_ACTION_ERROR`: An error occurred while handling the requested action. +- `5 - RPC_STATUS_DISPATCH_ERROR`: The RPC request could not be dispatched. +- `6 - RPC_STATUS_SERVER_ERROR`: A server-side RPC error occurred. +- `7 - RPC_STATUS_ASSIGNMENT_ERROR`: An error occurred while assigning the RPC request. +- `8 - RPC_STATUS_PROTOCOL_ERROR`: A protocol-related error occurred. +- `9 - RPC_STATUS_AUTHENTICATION_ERROR`: An authentication-related RPC error occurred. +- `10 - RPC_STATUS_CANCELLED_REQUEST`: The RPC request was cancelled. +- `11 - RPC_STATUS_UNKNOWN_ERROR`: An unknown RPC error occurred. +- `12 - RPC_STATUS_NO_RETRIES_ERROR`: The RPC failed and should not be retried. +- `13 - RPC_STATUS_UNAUTHORIZED_ERROR`: The RPC request was unauthorized. +- `14 - RPC_STATUS_PARSING_ERROR`: The RPC request or response could not be parsed. +- `15 - RPC_STATUS_ACCESS_DENIED`: RPC access was denied. +- `16 - RPC_STATUS_ACCESS_SUSPENDED`: RPC access was suspended. +- `17 - RPC_STATUS_DEVICE_INCOMPATIBLE`: The device was considered incompatible. +- `18 - RPC_STATUS_ACCESS_RATE_LIMITED`: RPC access was rate limited. +- `19 - RPC_STATUS_GOOGLE_PLAY_NOT_READY`: Required Google Play functionality is not ready. +- `20 - RPC_STATUS_LOGIN_ERROR_BAIL`: A login error occurred and the current flow should be abandoned. +- `99 - RPC_STATUS_MITM_DISALLOWED_REQUEST`: The MITM disallowed the requested RPC. + +--- + +### Message - RegisterControllerRequest + +#### Fields: + +- `string id = 1`: Unique controller ID. +- `int32 proto_major_version = 2`: Major Rotom protocol version supported by the controller. +- `int32 proto_minor_version = 3`: Minor Rotom protocol version supported by the controller. +- `int32 weight = 4`: Controller weight used when distributing workers between controllers. + +--- + +### Message - RegisterControllerResponse + +#### Enum - RegisterControllerResponseStatus: + +- `0 - UNSET`: Registration status is unset or unknown. +- `1 - SUCCESS`: Controller registration succeeded. +- `2 - NO_WORKERS_AVAILABLE`: There are currently no workers available to assign. +- `3 - ERROR`: An error occurred while registering the controller. + +#### Fields: + +- `RegisterControllerResponseStatus status = 1`: Status of the controller registration attempt. +- `string status_reason = 2`: Additional human-readable information about the registration status. +- `string user_agent = 3`: User agent associated with the assigned worker. +- `int32 proto_major_version = 4`: Major Rotom protocol version supported by the MITM. +- `int32 proto_minor_version = 5`: Minor Rotom protocol version supported by the MITM. +- `string assigned_worker_id = 7`: Worker ID assigned to the controller. +- `int64 retry_after = 8`: Value indicating when the controller should retry after a temporary registration failure. diff --git a/rotom.proto b/rotom.proto index db1eb8f..029cbcd 100644 --- a/rotom.proto +++ b/rotom.proto @@ -12,11 +12,12 @@ message MitmRequest { message LoginRequest { enum LoginSource { UNSET = 0; - PTC = 1; + PTC = 1 [deprecated = true]; PTC_OAUTH = 2; FB = 3; GOOGLE = 4; - N_KIDS = 5; + SUPER_AWESOME = 5 [deprecated = true]; + NIANTIC_JWT = 6; } string username = 1; @@ -47,7 +48,6 @@ message MitmRequest { } message MitmResponse { - enum Status { UNSET = 0; SUCCESS = 200; @@ -55,6 +55,7 @@ message MitmResponse { ERROR_RETRY_LATER = 501; ERROR_WORKER_STOPPED = 502; ERROR_RECONNECT = 503; + ERROR_RESTART_SESSION = 504; } message LoginResponse { @@ -85,12 +86,21 @@ message MitmResponse { } message WelcomeMessage { + enum Platform { + UNSET = 0; + IOS = 1; + ANDROID = 2; + } + string worker_id = 1; string origin = 2; int32 version_code = 3; string version_name = 4; string useragent = 5; string device_id = 6; + Platform platform = 7; + bool reserved1 = 8; + string reserved2 = 9; } enum AuthStatus { @@ -131,3 +141,27 @@ enum RpcStatus { RPC_STATUS_LOGIN_ERROR_BAIL = 20; RPC_STATUS_MITM_DISALLOWED_REQUEST = 99; } + +message RegisterControllerRequest { + string id = 1; + int32 proto_major_version = 2; + int32 proto_minor_version = 3; + int32 weight = 4; +} + +message RegisterControllerResponse { + enum RegisterControllerResponseStatus { + UNSET = 0; + SUCCESS = 1; + NO_WORKERS_AVAILABLE = 2; + ERROR = 3; + } + + RegisterControllerResponseStatus status = 1; + string status_reason = 2; + string user_agent = 3; + int32 proto_major_version = 4; + int32 proto_minor_version = 5; + string assigned_worker_id = 7; + int64 retry_after = 8; +} \ No newline at end of file