api.lite.fi · v1

Lite.fi-tunnus pelikehittäjille

Näin peli liittyy yhteiseen kirjautumiseen ja Top 100 -listoihin. Pelit pysyvät staattisina: ne eivät koskaan näe OIDC-tokeneita, vain krypta_sid-evästeen, jonka selain lähettää automaattisesti.

Pikaohje

Kopioi krypta-id.js pelisi repoon (esim. js/krypta-id.js) — pelien CSP on script-src 'self'.
Lisää CSP:hen connect-src 'self' https://api.lite.fi (ja img-src https://api.lite.fi, jos näytät avatarit).
Kirjautumislinkki: https://api.lite.fi/login?return=https://mato.lite.fi/ — ei popupeja.
Pelin lopuksi KryptaID.submitScore('matopeli', 'klassikko', 1234).

Kirjasto `krypta-id.js`

<script src="js/krypta-id.js"></script>

const me = await KryptaID.me();          // null = ei kirjautunut
if (!me) loginLink.href = KryptaID.loginUrl();   // palaa tälle sivulle
else nameEl.textContent = me.nickname;

const r = await KryptaID.submitScore('tetris', 'klassikko', 48200, { level: 12 });
// r = { saved: true, best: 48200, previousBest: 30100, rank: 7, pending: false, ... }

const top = await KryptaID.leaderboard('tetris', 'klassikko', 10);
// top.entries = [{ rank: 1, nickname: 'Kalmo', avatar: 'kallo', score: 99100, at: 1761550000000 }, ...]

await KryptaID.myRank('tetris', 'klassikko');    // { score, rank, pending } tai null
KryptaID.avatarUrl(me.avatar);                   // https://api.lite.fi/avatars/kallo.svg
await KryptaID.logout();

Virheissä lupaus hylätään Error-oliolla, jolla on status ja data.error (esim. 401 unauthorized, 403 nickname_required, 429 too_frequent, 422 score_out_of_range). Devissä voit asettaa ennen kirjastoa window.KRYPTA_ID_BASE = 'https://krypta-api.dev.empor.fi'.

API

Kutsu	Kuvaus
`GET /login?return=URL`	Aloittaa Empor ID -kirjautumisen (myös tilin luonti). `return` hyväksytään vain sivustodomaineille (`lite.fi,krypta.gg`) ja niiden alidomaineille. Ensikertalainen valitsee nimimerkin ennen paluuta.
`GET /logout?return=URL`	Uloskirjautumissivu (tai `POST /api/logout`).
`GET /api/me`	`{ id, nickname, avatar, avatarUrl, needsNickname }` tai `401`. `id` on pysyvä julkinen tunniste (ei Empor ID:n sub).
`POST /api/scores`	Runko `{ game, board?, score, meta? }`. Säilyttää paras-tuloksen per (pelaaja, peli, lista). `201` = uusi ennätys, `200` = ei parantunut. Vaatii nimimerkin. `meta` ≤ 1 kt JSON-olio.
`GET /api/leaderboard?game=&board=&limit=100`	Julkinen, välimuisti 30 s. `board` puuttuu → pelin oletuslista.
`GET /api/leaderboard/me?game=&board=`	Oma tulos ja sijoitus (kirjautunut).
`GET /api/users/:nickname`	Julkinen profiili: `{ nickname, avatar, joined, scores: [{ game, board, score, rank, at }] }`.
`GET /api/games`	Pelit ja niiden listat, järjestys (`desc`/`asc`) ja muoto.
`GET /api/boards?game=`	Pelin listat pelaajamäärineen (myös päivän listat).
`POST /api/internal/verify-session`	Palvelinten välinen, ks. Backend.

Listat (board): pienet kirjaimet, numerot ja -, max 40 merkkiä, pelikohtainen regex. Päivän haaste: daily-YYYY-MM-DD (Suomen aikaa) — vastaanotetaan vain tänään ja eilen.

CORS & CSRF

Sallitut originit: https://^https://([a-z0-9-]+\.)?krypta\.gg$ (tasan yksi alidomain-taso, vain https, ei porttia)lt;domain^https://([a-z0-9-]+\.)?krypta\.gg$ (tasan yksi alidomain-taso, vain https, ei porttia)gt; ja https://^https://([a-z0-9-]+\.)?krypta\.gg$ (tasan yksi alidomain-taso, vain https, ei porttia)lt;alidomain^https://([a-z0-9-]+\.)?krypta\.gg$ (tasan yksi alidomain-taso, vain https, ei porttia)gt;.^https://([a-z0-9-]+\.)?krypta\.gg$ (tasan yksi alidomain-taso, vain https, ei porttia)lt;domain^https://([a-z0-9-]+\.)?krypta\.gg$ (tasan yksi alidomain-taso, vain https, ei porttia)gt;, domainit: lite.fi,krypta.gg (tasan yksi alidomain-taso, vain https, ei porttia) + palvelun omat osoitteet. Vastauksessa Access-Control-Allow-Credentials: true.
Kirjoittavat kutsut (POST/PATCH/DELETE) vaativat sallitun Origin-otsakkeen ja otsakkeen X-Krypta: 1 (pakottaa preflightin). Kirjasto hoitaa tämän.
Eväste krypta_sid: Domain=.lite.fi; Path=/; HttpOnly; Secure; SameSite=Lax, 30 pv liukuva. Pelien fetchit ovat samaa sivustoa (same-site), joten eväste kulkee credentials: 'include' -asetuksella.
Rate limit: 30 tulosta / min / pelaaja + pelikohtainen vähimmäisväli ja tuntiraja.

Huijaussuoja — rehellisesti

Selaimesta lähetetty tulos on aina väärennettävissä. Palvelin tekee sen minkä voi: pelikohtaiset ylä- ja alarajat (yli → 422), lähetystiheyden rajat, ja epäilyttävän suuret (tai miinaharavassa pienet) tulokset liputetaan: ne piilotetaan listoilta, kunnes ylläpito hyväksyy ne. Pelaaja näkee oman tuloksensa merkinnällä "tarkistettavana". Rajat ovat tiedostossa games.config.json — uusi peli tarvitsee sinne rivin.

Pelin oma backend (esim. roguelike)

POST https://api.lite.fi/api/internal/verify-session
X-Krypta-Service-Key: <avain .env.krypta-api:n SERVICE_KEYS-listalta>
Content-Type: application/json

{ "sid": "<krypta_sid-evästeen arvo>" }

→ { "valid": true, "user": { "id": "k3x9…", "nickname": "Kalmo", "avatar": "kallo" } }
→ { "valid": false }

Backend lukee krypta_sid-evästeen omasta pyynnöstään (eväste on koko .lite.fi:lle) ja varmistaa sen tällä. Tallenna linkiksi user.id. Avain annetaan ylläpidolta, eikä sitä koskaan laiteta selaimeen.