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ší.

Kód

[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

Kód

/keystone key new <jméno> <scope> [scope ...]
/keystone key list
/keystone key revoke <id>
/keystone key own <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. /keystone key new nedá nic, co by jeho autor sám nemohl dostat.

Authorization: Bearer <klíč> u každého volání. Bez klíče přijde 404, ne 403: route, která řekne „zakázáno", právě nepřihlášenému volajícímu prozradila, že existuje. S pravým klíčem, který nemá scope, jaký ta cesta chce, přijde 403 a věta, který scope chybí — ten volající už o povrchu ví.

Klíč si pamatuje, jestli ho dostal vlastník. /keystone key list vlastníkovy klíče označí a řekne, kdy vznikly. Klíč z doby, kdy se vlastníci nezapisovali (třeba klíč, kterým obchod zapisuje hodnosti), vlastníkův není, dokud vlastník neřekne /keystone key own <id>; log je při každém startu vyjmenuje. Klíč pojmenovaný jako jeden z vlastních klíčů modu se do něj nikdy nerozšíří. API nečte nikoho, než ho zná, a od nikoho víc než megabajt; volání přes MCP prochází stejným limitem, vlastnickou kontrolou a auditem jako každé jiné.

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.
`languages.write`	Překlady, které čtou hráči.
`server.read`	Stroj pod tím.

Některé scopy jsou vlastníkovy: settings.write, permissions.write, perks.write, backup.restore, operations.run, assistant.write a languages.write. Router je hlídá u každého požadavku — i když klíč nese *, i přes MCP — a projdou jen s klíčem vydaným konzoli nebo operátoru úrovně 4. Proto se skupině, která dosáhla na panel, ukáže editor jen ke čtení a moderaci.

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/ungroup, /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.

POST /v1/settings s check=true jen zeptá, jestli by hodnota prošla, a nic nezapíše. Seznam se vrací jako a, b, ne [a, b], tedy tak, jak jde zapsat zpět.
POST /v1/players/ungroup (permissions.write, pole player a group) vezme zpět jen ty členství ve skupině, které zadal volající klíč — co napsal admin, dal Discord nebo jiný klíč, zůstane — a odpoví {player, group, removed}; removed: 0 není chyba. /v1/players/group a /ungroup najdou i hráče, který není online, ale na serveru už byl, protože hodnosti se kupují a končí, zatímco jsou lidé pryč. Jméno, které server nezná, nebo skupina, která neexistuje, je 400.
tick v /v1/metrics je to, co tick stojí teď (z vlastních časů ticku serveru), ne 1000 ÷ TPS.

Ž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.