Authentication Data Structures

Version: 1.0.0 Category: authentication Schema: JSON Schema Draft-07 Description: Authentication schemas for webapp, consensus network, and streaming services.

Data Structures

WebappLoginRequest

Webapp login request. Authentication is by Cosmos signature, not username/password. Sign the message LOGIN_GUILD{guildId}ADDRESS{address}DATETIME{unix_timestamp}.

Field Type Required Description
address string Yes Cosmos address logging in
signature string Yes Base64 signature over the login message
pubkey string Yes Base64 public key for address
guild_id string Yes Guild being logged into (type 0, e.g. 0-1)
unix_timestamp string Yes Unix seconds; must be within 600s of server time

WebappLoginResponse

Webapp login response — the standard { success, errors, data } envelope. Success carries a Set-Cookie: PHPSESSID header; there is no JWT/bearer token.

Field Type Required Description
success boolean Yes Login success status
errors object Yes Keyed errors on failure (e.g. signature_validation_failed, player_address_does_not_exists); empty on success
data null Yes No body payload; identity is the session cookie

WebappSession

Webapp session data.

Field Type Required Format Description
cookie string Yes   Session cookie (PHPSESSID)
expires string No date-time Session expiration time
lastUsed string No date-time Last session usage time

ConsensusAccount

Consensus network account information.

Field Type Required Format Description
address string Yes blockchain-address Account address
pub_key object No   Public key
account_number string Yes   Account number
sequence string Yes   Account sequence (nonce)

TransactionSigner

Transaction signer information.

Field Type Required Sensitive Description
address string Yes No Signer address (blockchain-address format)
privateKey string No Yes Private key (never expose in production)
publicKey string No No Public key
sequence string No No Current sequence number

SignedTransaction

Signed transaction ready for submission.

Field Type Required Description
body object Yes Transaction body
auth_info object Yes Authentication information
signatures array of string Yes Transaction signatures

body

Field Type Required Description
messages array Yes Transaction messages
memo string No Transaction memo

auth_info

Field Type Required Description
signer_infos array Yes Signer information
fee object Yes Transaction fee

The fee object:

Field Type Description
amount array Fee amount
gas_limit string Gas limit

NATSConnection

NATS connection configuration.

Field Type Required Description
url string Yes NATS server URL: nats://localhost:4222 or ws://localhost:1443
protocol string Yes Protocol, always NATS
transport string No Transport protocol: tcp or WebSocket
authentication object No NATS authentication (optional, see below)

authentication

Field Type Description
type string Authentication type: token or username_password
token string NATS token (if type is token)
username string NATS username (if type is username_password)
password string NATS password (if type is username_password). Sensitive.

AuthenticationConfig

Complete authentication configuration covering all three services.

webapp

Field Type Sensitive Description
baseURL string No Webapp base URL
address string No Cosmos address used to authenticate
pubkey string No Base64 public key for address
privateKey string Yes Key used to sign the login message (never expose in production)
guild_id string No Guild to authenticate into (type 0)
session WebappSession No Current session data

consensus

Field Type Description
rpcURL string RPC URL
apiURL string API URL
signer TransactionSigner Signer information

streaming

Uses the NATSConnection structure defined above.

Authentication Flows

Webapp Login Flow

ID: webapp-login Status: Verified against Symfony AuthManager::login

Signature-based session authentication for the webapp API.

Steps:

  1. Sign – Build LOGIN_GUILD{guildId}ADDRESS{address}DATETIME{unix_timestamp} and sign it with the address’s key.
  2. POST /api/auth/login – Submit WebappLoginRequest, receive WebappLoginResponse + Set-Cookie: PHPSESSID.
  3. Use session cookie – Include Cookie: on subsequent requests (all /api/ except /api/auth/*, /api/guild/this, /api/timestamp, /api/setting).

Error Handling:

Code Action
401 signature_validation_failed (re-sign with fresh timestamp), player_address_does_not_exists, or expired session — re-authenticate

Consensus Transaction Flow

ID: consensus-transaction Status: Implemented

Transaction signing for consensus network.

Steps:

  1. GET /cosmos/auth/v1beta1/accounts/{address} – Get account information including sequence number. Store as account.
  2. Create transaction – Use account.sequence for replay protection.
  3. Sign transaction – Sign with private key (never expose private key). Produces signedTransaction.
  4. POST /cosmos/tx/v1beta1/txs – Submit signed transaction (SignedTransaction) to network.

Error Handling:

Code Action
400 Invalid transaction format
401 Invalid signature
500 Network error, retry with backoff

NATS Connection Flow

ID: nats-connection Status: Implemented

NATS connection for GRASS streaming (authentication optional).

Steps:

  1. Connect to NATS – Use NATSConnection configuration. Authentication is optional.
  2. Subscribe to subjects – Subscribe to GRASS event subjects (e.g., structs.player.*, structs.planet.*).
  3. Handle messages – Process incoming real-time events via callback.

Error Handling:

Error Action
connection_failed Retry with exponential backoff
authentication_failed Check NATS credentials if authentication enabled

Wallet Signature Flow

ID: wallet-signature Status: Planned

Wallet signature authentication (planned feature).

Steps:

  1. Request signature from wallet – Request wallet to sign authentication message.
  2. POST /api/auth/login – Submit signed message (WebappLoginRequest) for authentication.
  3. Receive authentication token – Store token for subsequent requests.

This flow is planned but not yet implemented. See roadmap.md for status.

API Key Authentication

ID: api-key Status: Planned

API key authentication (planned feature).

Steps:

  1. Include API key in request headers – Include X-API-Key: header in requests.

This flow is planned but not yet implemented. See roadmap.md for status.

Authentication Status Summary

Service Status Description Implementation
Webapp Implemented Session-based authentication for webapp API PHP Symfony application (structs-webapp). Main user-facing API.
Consensus Implemented Transaction signing required for all transactions All transactions must be signed with private key
Streaming Implemented NATS authentication is optional NATS connection works without authentication; optional if configured
Wallet Signature Planned Wallet signature authentication Not yet implemented, see roadmap.md
API Key Planned API key authentication Not yet implemented, see roadmap.md
OAuth Planned OAuth integration Not yet implemented, see roadmap.md

Security Notes

References