Lokální API a klíče

Keystone odpovídá na HTTP na 127.0.0.1:25586. Panel je jeden volající, tvoje vlastní nástroje můžou být další.

[api]
enabled = true
address = "127.0.0.1"
port = 25586
reachable-at = ""     # od 0.1.1

Loopback je výchozí a je to ta bezpečná volba. Cokoliv jiného je dostupné každému, kdo dosáhne na ten stroj, a API umí všechno, co umí mod. Když ho potřebuješ z jiného stroje, dej ho za SSH tunel, ne na adresu do světa.

reachable-at neřídí, kde se poslouchá — řídí, jakou adresu si mod napíše do odkazu na editor a do openapi.json. Podrobně na stránce Panel.

Klíče

/keystone key new <jméno> <scope> [scope ...]
/keystone key list
/keystone key revoke <id>

Klíč se vypíše jednou, když vznikne, a nikdy víc — stejně jako člověk vidí heslo. Každý klíč má jméno, takže auditní stopa říká, kdo co udělal, a limit na minutu.

Authorization: Bearer <klíč> u každého volání. Bez klíče, nebo s klíčem bez toho scopu, přijde 404, ne 403: route, která řekne „zakázáno", právě nepřihlášenému volajícímu prozradila, že existuje.

Scopy

Klíč nese jen to, co jsi mu dal. Žádost o scope, za kterým na tomhle serveru nic není, se odmítne — a v tom odmítnutí je vypsané, co existuje, takže se překlep chytí při výrobě klíče, ne až při použití.

Scope	Dosáhne na
status.read	Jestli server běží, kdo je na něm, jak mu je.
players.read	Lidi — a taky na to, které herní účty má propojený jeden Discord účet.
permissions.read · permissions.write	Skupiny a co smí.
operations.read · operations.run	Rozvrh a spuštění ručně.
settings.read · settings.write	Každé nastavení.
console.read	Log serveru.
chat.read	Co se říká.
events.read	Živý proud (níž).
audit.read	Kdo co změnil.
keys.read	Které klíče existují — nikdy jejich tajemství.
backup.read · backup.restore	Zálohy a jejich vrácení.
perks.read · perks.write	Co si kdo zasloužil.
assistant.read · assistant.write	Asistent ve hře.
server.read	Stroj pod tím.

Dej klíči tu nejužší sadu, která odvede práci. Monitorovací skript chce status.read a nic dalšího.

Co tam je

GET /v1/openapi.json vypíše každou cestu, kterou tenhle server doopravdy má — mod si ten dokument píše ze svých vlastních rout, takže se nemůže mýlit v tom, co existuje. Když chceš seznam, ptej se serveru, ne téhle stránky.

Zhruba: /v1/status, /v1/players (a /v1/players/group, /v1/players/perk, /v1/players/check, /v1/players/grants), /v1/groups, /v1/operations (/run, /cancel, /history), /v1/backups (/restore), /v1/settings (/history, /rollback), /v1/console, /v1/chat, /v1/events, /v1/audit, /v1/keys, /v1/bans, /v1/tickets, /v1/votes, /v1/skins, /v1/progress, /v1/metrics (/history), /v1/bench, /v1/catalog, /v1/entities, /v1/gate (/maintenance), /v1/accounts, /v1/discord (/links), /v1/assistant/* a /v1/reload.

Živý proud

GET /v1/events se scopem events.read drží spojení otevřené a píše do něj události, jak se dějí — díky tomu je panel panel, a ne stránka, kterou musíš obnovovat. Ověřuje se stejně jako všechno ostatní a bez klíče odpovídá 404.

Addony na JVM

Když stavíš addon v Javě, nemluvíš přes HTTP — kompiluješ proti keystone-api, který jede uvnitř toho samého jaru (META-INF/jarjar/) a nemá žádné vlastní závislosti, ani logovací. Registruje se přes něj vlastní modul, příkaz, oprávnění nebo zdroj hodností.

Co se zapisuje

Každá změna přes API je auditní řádek: kdo, co, kdy. Citlivé příkazy se z něj, z konzole i z logu maskují — vlastní automaticky, cizí ty, které pojmenuješ v keystone.mask-commands.