
== Visited by end-user after they have been granted access to AHAP:

server.php
?action=show_account
&ticket_id=[ID]

Shows end-user info about their account, including their Steam key and
off-Steam download links.




== Called by either game client or game server:

server.php
?action=get_sequence_number
&email=[email address]

Return:
sequence number
OK

Gets next valid sequence number associated with email.  Note that even if
email is unknown to server, 0 will be returned so that initial grant can be
submitted.





== Called by trusted game server only:

server.php
?action=grant
&email=[email address]
&sequence_number=[int]
&hash_value=[hash value]

Return:
assigned_steam_key
view_account_url
OK
-or-
DENIED

Used by game servers to indicate that a given email has been granted access to
Another Planet.  An assigned steam key is returned, along with a URL
that the end-user can use to view their account details.

Note that the assigned steam key can be a NO-KEYS-LEFT if we run out of keys



hash_value is computed on both ends with:

  HMAC_SHA1( $shared_secret, $sequence_number$email )

  (sequence number concatonated with email)

Where $shared_secret is a secret string known to both the ahapGate server and
the game servers that have permission to manipulate the ahapGate.

If sequence number is <= previously used sequence number for this email address,
request will be rejected.

Secure against replay attacks and modification of submitted email.




== Called by trusted game server only


server.php
?action=register_vote
&email=[email address]
&leader_github=[account_name]
&sequence_number=[int]
&hash_value=[hash value]

Return:
OK
-or-
DENIED

Used by game servers to indicate a user's vote for content leader.
This should be called every time a user logs into an Another Planet server,
re-submitting the vote for each log-in.  Thus, ahapGate can track votes from
currently-active users.

DENIED is returned if the user's email isn't known


hash_value is computed on both ends with:

  HMAC_SHA1( $shared_secret, $sequence_number$email$leaderGithub )

  (sequence number concatonated with email and github)
  (github forced to all lower-case for hashing)

Secure against replay attacks and modification of submitted github vote.





== Called by game client only


server.php
?action=register_github
&email=[email address]
&github_username=[username]
&sequence_number=[int]
&hash_value=[hash value]

Return:
OK
-or-
DENIED

Used by game clients to update user's github account username.

DENIED is returned if the user's email isn't known


hash_value is computed on both ends with:

  HMAC_SHA1( $ticket_id, $sequence_number$github_username )

  (sequence number concatonated with github username)
  (github forced to all lower-case for hashing)

Secure against replay attacks and modification of submitted username.





== Called by game client only


server.php
?action=register_github_and_paypal
&email=[email address]
&github_username=[username]
&paypal_email=[paypal_email]
&sequence_number=[int]
&hash_value=[hash value]

Return:
OK
-or-
DENIED

Used by game clients to update user's github account username AND their
PayPal email address.

DENIED is returned if the user's email isn't known


hash_value is computed on both ends with:

  HMAC_SHA1( $ticket_id, $sequence_number$github_username$paypal_email_sha1 )

  (sequence number concatonated with github username and SHA1 hash of paypal
   email address)
  
  (github forced to all lower-case for hashing)
  
  (SHA1 hash of paypal email is all upper-case, but email is preserved
   however user entered it, potentially mixed case)

Secure against replay attacks and modification of submitted username and email.


NOTE: the SHA1 of the PayPal email is used in the hash, instead of the email
      itself, becasue of the limited character set supported by the
      ticketServer for check_ticket_hash.
      The full character set of email addresses is not supported.




== Called by game client only


server.php
?action=get_content_leader
&email=[email address]
&sequence_number=[int]
&hash_value=[hash value]

Return:
leader_github
OK
-or-
DENIED

Used by game clients to get the current content leader's github account name.
This is not who they are currently voting for, but who is the current winner
of the vote.

DENIED is returned if the user's email isn't known


hash_value is computed on both ends with:

  HMAC_SHA1( $ticket_id, $sequence_number )

Secure against replay attacks.
