mirror of https://github.com/dirtbags/moth.git
Golang port is now MOTHv3
This commit is contained in:
Neale Pickett
parent
11939e7ce6
commit
fbb0a9b0ba
215
docs/api.md
215
docs/api.md
|
|
@ -1,215 +0,0 @@
|
|||
MOTHv3 API
|
||||
==========
|
||||
|
||||
MOTH, by design, uses a small number of API endpoints.
|
||||
|
||||
Whenever possible,
|
||||
we decided to push complexity into the client,
|
||||
keeping the server as simple as we could make it.
|
||||
After all,
|
||||
this is a hacking contest.
|
||||
If a participant finds a vulnerability in code running on their own machine,
|
||||
the people running the server don't care.
|
||||
|
||||
Specification
|
||||
=============
|
||||
|
||||
You make requests as HTTP GET query arguments:
|
||||
|
||||
https://server/path/elements/api/v3/endpoint?var1=val1&var2=val2
|
||||
|
||||
The server returns a
|
||||
[JSend](https://labs.omniti.com/labs/jsend) response:
|
||||
|
||||
{
|
||||
"status": "success",
|
||||
"data": "Any JS data type here"
|
||||
}
|
||||
|
||||
|
||||
Client State
|
||||
============
|
||||
|
||||
The client (or user interacting with the client) needs to remember only one thing:
|
||||
|
||||
* teamId: the team ID used to register
|
||||
|
||||
A naive client,
|
||||
like the one we used from 2009-2018,
|
||||
can ask the user to type in the team ID for every submission.
|
||||
This is fine.
|
||||
|
||||
|
||||
Endpoints
|
||||
=========
|
||||
|
||||
RegisterTeam(teamId, teamName)
|
||||
-------------------------------
|
||||
|
||||
Register a team name with a team hash.
|
||||
|
||||
### Parameters
|
||||
|
||||
* teamId: Team's unique identifier (usually a hex value)
|
||||
* teamName: Team's human-readable name
|
||||
|
||||
On success, no data is returned.
|
||||
On failure, message contains an English explanation of why.
|
||||
|
||||
|
||||
### Example
|
||||
|
||||
https://server/api/v3/RegisterTeam?teamId=8b1292ca&teamName=Lexical+Pedants
|
||||
|
||||
{
|
||||
"status": "success",
|
||||
"data": null
|
||||
}
|
||||
|
||||
|
||||
GetState()
|
||||
----------
|
||||
|
||||
Return all current state of the puzzle server.
|
||||
|
||||
### Parameters
|
||||
|
||||
None
|
||||
|
||||
|
||||
### Return data
|
||||
|
||||
* puzzles: dictionary mapping from category to one of the following:
|
||||
* list of point values currently open
|
||||
* URL to puzzle root (intended for token-based puzzles)
|
||||
* teams: mapping from anonymized team ID to team name
|
||||
* log: list of (timestamp, team number, category, points)
|
||||
* notices: list of HTML broadcast notices to display to the user
|
||||
* now: current server time (unix epoch)
|
||||
|
||||
|
||||
### Example
|
||||
|
||||
https://server/api/v3/GetState
|
||||
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"puzzles": {
|
||||
"sequence": [1, 2],
|
||||
"codebreaking": [10],
|
||||
"wopr": "https://appspot.com/dooted-bagel-8372/entry"
|
||||
},
|
||||
"teams": {
|
||||
"0": "Zelda",
|
||||
"1": "Defender"
|
||||
},
|
||||
"log": [
|
||||
[1526478368, "0", "sequence", 1],
|
||||
[1526478524, "1", "sequence", 1],
|
||||
[1526478536, "0", "nocode", 1]
|
||||
],
|
||||
"notices": [
|
||||
"<a href=\"https://appspot.com/dooted-bagel-8372/entry\">WOPR category</a> is now open",
|
||||
"Event closes at 18:00 today, and will resume tomorrow at 08:00"
|
||||
],
|
||||
"now": 1527170088
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
GetPuzzle(category, points)
|
||||
--------------------
|
||||
|
||||
Return a puzzle.
|
||||
|
||||
### Parameters
|
||||
|
||||
* category: name of category to fetch from
|
||||
* points: point value of the puzzle to fetch
|
||||
|
||||
|
||||
### Return data
|
||||
|
||||
* authors: List of puzzle authors
|
||||
* hashes: list of djbhash values of acceptable answers
|
||||
* files: dictionary of puzzle-associated filenames and their URLs
|
||||
* body: HTML body of the puzzle
|
||||
|
||||
|
||||
### Example
|
||||
|
||||
https://server/api/v3/GetPuzzle?category=sequence&points=1
|
||||
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"authors": ["neale"],
|
||||
"hashes": [177627],
|
||||
"files": {
|
||||
"happy.png": "https://cdn/assets/0904cf3a437a348bea2c49d56a3087c26a01a63c.png"
|
||||
},
|
||||
"body": "<pre><code>1 2 3 4 5 _\n</code></pre>\n"
|
||||
}
|
||||
|
||||
|
||||
|
||||
SubmitAnswer(teamId, category, points, answer)
|
||||
----------------------
|
||||
|
||||
Submit an answer to a puzzle.
|
||||
|
||||
### Parameters
|
||||
|
||||
* teamId: Team ID (optional: if ommitted, answer is verified but no points are awarded)
|
||||
* category: category name of puzzle
|
||||
* points: point value of puzzle
|
||||
* answer: attempted answer
|
||||
|
||||
|
||||
### Return Data
|
||||
|
||||
* epilog: HTML to display upon successfully answering the puzzle
|
||||
|
||||
|
||||
### Example
|
||||
|
||||
https://server/api/v3/SubmitAnswer?teamId=8b1292ca&category=sequence&points=1&answer=6
|
||||
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"epilog": "That's right: in base 10, 5 + 1 = 6."
|
||||
}
|
||||
}
|
||||
|
||||
SubmitToken(teamId, token)
|
||||
---------------------
|
||||
|
||||
Submit a token for points
|
||||
|
||||
### Parameters
|
||||
|
||||
* teamId: Team ID
|
||||
* token: Token being submitted
|
||||
|
||||
|
||||
### Return data
|
||||
|
||||
* category: category for which this token awarded points
|
||||
* points: number of points awarded
|
||||
* epilog: HTML to display upon successfully answering the puzzle
|
||||
|
||||
|
||||
### Example
|
||||
|
||||
https://server/api/v3/SubmitToken?teamId=8b1292ca&token=wat:30:xylep-radar-nanox
|
||||
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"category": "wat",
|
||||
"points": 30,
|
||||
"epilog": ""
|
||||
}
|
||||
}
|
||||
|
|
@ -1,135 +0,0 @@
|
|||
#! /usr/bin/python3
|
||||
|
||||
from aiohttp import web
|
||||
import time
|
||||
|
||||
async def fake_register(request):
|
||||
teamId = request.query.get("teamId")
|
||||
teamName = request.query.get("teamName")
|
||||
if teamId == "ffff" and teamName == "dirtbags":
|
||||
resp = {
|
||||
"status": "success",
|
||||
"data": None,
|
||||
}
|
||||
elif teamId and teamName:
|
||||
resp = {
|
||||
"status": "error",
|
||||
"message": "Query was correctly formed but I'm feeling cranky"
|
||||
}
|
||||
else:
|
||||
resp = {
|
||||
"status": "fail",
|
||||
"data": "You must send teamId and teamName",
|
||||
}
|
||||
return web.json_response(resp)
|
||||
|
||||
async def fake_state(request):
|
||||
resp = {
|
||||
"status": "success",
|
||||
"data": {
|
||||
"puzzles": {
|
||||
"sequence": [1, 2],
|
||||
"codebreaking": [10],
|
||||
"wopr": "https://appspot.com/dooted-bagel-8372/entry"
|
||||
},
|
||||
"teams": {
|
||||
"0": "Zelda",
|
||||
"1": "Defender"
|
||||
},
|
||||
"log": [
|
||||
[1526478368, "0", "sequence", 1],
|
||||
[1526478524, "1", "sequence", 1],
|
||||
[1526478536, "0", "nocode", 1]
|
||||
],
|
||||
"notices": [
|
||||
"<a href=\"https://appspot.com/dooted-bagel-8372/entry\">WOPR category</a> is now open",
|
||||
"Event closes at 18:00 today, and will resume tomorrow at 08:00"
|
||||
],
|
||||
"now": int(time.time()),
|
||||
}
|
||||
}
|
||||
return web.json_response(resp)
|
||||
|
||||
async def fake_getpuzzle(request):
|
||||
category = request.query.get("category")
|
||||
points = request.query.get("points")
|
||||
if category == "sequence" and points == "1":
|
||||
resp = {
|
||||
"status": "success",
|
||||
"data": {
|
||||
"authors": ["neale"],
|
||||
"hashes": [177627],
|
||||
"files": {
|
||||
"happy.png": "https://cdn/assets/0904cf3a437a348bea2c49d56a3087c26a01a63c.png"
|
||||
},
|
||||
"body": "<pre><code>1 2 3 4 5 _\n</code></pre>\n",
|
||||
}
|
||||
}
|
||||
elif category and points:
|
||||
resp = {
|
||||
"status": "error",
|
||||
"message": "Query was correctly formed but I'm feeling cranky"
|
||||
}
|
||||
else:
|
||||
resp = {
|
||||
"status": "fail",
|
||||
"data": "You must send category and points"
|
||||
}
|
||||
return web.json_response(resp)
|
||||
|
||||
async def fake_submitanswer(request):
|
||||
teamId = request.query.get("teamId")
|
||||
category = request.query.get("category")
|
||||
points = request.query.get("points")
|
||||
answer = request.query.get("answer")
|
||||
if category == "sequence" and points == "1" and answer == "6":
|
||||
resp = {
|
||||
"status": "success",
|
||||
"data": {
|
||||
"epilog": "Now you know the answer, and knowing is half the battle. Go Joe!"
|
||||
}
|
||||
}
|
||||
elif category and points and answer:
|
||||
resp = {
|
||||
"status": "error",
|
||||
"message": "Query was correctly formed but I'm feeling cranky"
|
||||
}
|
||||
else:
|
||||
resp = {
|
||||
"status": "fail",
|
||||
"data": "You must send category and points"
|
||||
}
|
||||
return web.json_response(resp)
|
||||
|
||||
async def fake_submittoken(request):
|
||||
teamId = request.query.get("teamId")
|
||||
token = request.query.get("token")
|
||||
if token == "wat:30:xylep-radar-nanox":
|
||||
resp = {
|
||||
"status": "success",
|
||||
"data": {
|
||||
"category": "wat",
|
||||
"points": 30,
|
||||
"epilog": ""
|
||||
}
|
||||
}
|
||||
elif category and points and answer:
|
||||
resp = {
|
||||
"status": "error",
|
||||
"message": "Query was correctly formed but I'm feeling cranky"
|
||||
}
|
||||
else:
|
||||
resp = {
|
||||
"status": "fail",
|
||||
"data": "You must send category and points"
|
||||
}
|
||||
return web.json_response(resp)
|
||||
|
||||
if __name__ == "__main__":
|
||||
app = web.Application()
|
||||
app.router.add_route("GET", "/api/v3/RegisterTeam", fake_register)
|
||||
app.router.add_route("GET", "/api/v3/GetState", fake_state)
|
||||
app.router.add_route("GET", "/api/v3/GetPuzzle", fake_getpuzzle)
|
||||
app.router.add_route("GET", "/api/v3/SubmitAnswer", fake_submitanswer)
|
||||
app.router.add_route("GET", "/api/v3/SubmitToken", fake_submittoken)
|
||||
web.run_app(app)
|
||||
Loading…
Reference in New Issue