OmniRoute/docs/i18n/hr/docs/security/CLI_TOKEN.md

CLI Machine-ID Token (Hrvatski)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Pregled

Naredbe OmniRoute CLI-ja autentificiraju se na lokalnom API-ju za upravljanje s pomoću tokena HMAC-SHA256(machine-id, salt) poslanog putem zaglavlja zahtjeva x-omniroute-cli-token.

To omogućuje podnaredbama CLI-ja (omniroute status, omniroute providers itd.) pozivanje krajnjih točaka za upravljanje bez potrebe da korisnik pri svakom pokretanju navede JWT ili lozinku.

Kako funkcionira

1. getMachineTokenSync() čita hardverski identifikator računala putem paketa node-machine-id (u slučaju neuspjeha vraća prazan niz, čime se onemogućuje autentifikacija CLI-ja).
2. Izračunava HMAC-SHA256(machine_id, salt) i vraća potpuni heksadecimalni sažetak od 64 znaka — deterministički, nepovratni token povezan s ovim računalom.
3. CLI šalje token kao x-omniroute-cli-token samo kada je razriješeno odredište eksplicitni URL povratne petlje (localhost, 127.0.0.0/8 ili IPv6 adresa povratne petlje). Zahtjevi koji sadržavaju token upotrebljavaju redirect: error, tako da ga lokalno preusmjeravanje ne može proslijediti drugom izvorištu. Udaljeni konteksti umjesto toga upotrebljavaju pristupne tokene ograničenog opsega. Ako izvođenje tokena nije dostupno, CLI izostavlja zaglavlje, a omniroute doctor prijavljuje neuspjeh umjesto da prazan token smatra valjanim.
4. Poslužitelj (src/server/authz/policies/management.ts) ponovno izračunava očekivani token s istom soli i uspoređuje ga putem funkcije timingSafeEqual kako bi spriječio njegovo otkrivanje na temelju vremena izvođenja.

Sigurnosna svojstva

Svojstvo	Pojedinosti
Samo povratna petlja	Prihvaća se samo kada poslužiteljeva pouzdana oznaka lokalnosti ravnopravnog čvora (izvedena iz stvarne TCP adrese čvora) označava povratnu petlju. Klijentski kontrolirano zaglavlje Host nikada se ne smatra pouzdanim za određivanje lokalnosti.
Usporedba u konstantnom vremenu	crypto.timingSafeEqual sprječava napade mjerenjem vremena.
Nepovratno	Iz HMAC izlaza nije moguće dobiti identifikator računala.
Nema zaobilaženja zaštite always	isAlwaysProtectedPath() procjenjuje se prije provjere tokena CLI-ja. /api/shutdown i /api/settings/database uvijek zahtijevaju JWT.
Ne može se izvesti	Token se nikada ne zapisuje na disk niti u zapisnike.

Zadana sol (nasumična za svaku instalaciju)

Kada OMNIROUTE_CLI_SALT nije postavljen, sol je nasumični heksadecimalni niz od 64 znaka koji se generira jednom i trajno sprema u <DATA_DIR>/cli-token-salt.json (način rada 0600) — nije riječ o vrijednosti omniroute-cli-auth-v1 uključenoj u repozitorij. I getActiveSalt() u src/lib/machineToken.ts i njegova zrcalna implementacija u bin/cli/utils/cliToken.mjs čitaju istu datoteku, tako da poslužitelj i svako pokretanje CLI-ja u ovoj instalaciji koriste istu vrijednost; literal uključen u repozitorij upotrebljava se samo kao krajnja pričuvna vrijednost kada još nije moguće uspostaviti trajno spremljenu sol ili sol iz varijable okruženja (primjerice u svježoj instalaciji koja sadržava samo CLI, prije prvog pokretanja poslužitelja). Time se uklanja slabost starog fiksnog zadanog literala: /etc/machine-id obično je dostupan za čitanje svim korisnicima, pa bi svaki lokalni korisnik inače mogao izvesti isti token za svaku instalaciju u kojoj OMNIROUTE_CLI_SALT nikada nije postavljen.

Rotacija soli

Postavite OMNIROUTE_CLI_SALT kako biste rotirali izvedeni token bez promjena koda — ta vrijednost uvijek ima prednost nad trajno spremljenom soli pojedinačne instalacije. Nakon rotacije svi CLI procesi na ovom računalu automatski će upotrebljavati novi token. Korisno nakon curenja popisa procesa koje je možda otkrilo prethodnu izvedenu vrijednost.

# Trajna rotacija (dodajte u profil ljuske)
export OMNIROUTE_CLI_SALT="my-secret-salt-2026"

# Provjerite upotrebljava li se novi token
omniroute status

Naslijeđeni format (SHA-256, 32 znaka) — i dalje je prihvaćen

Prije prethodno opisanog HMAC formata CLI je izvodio svoj token kao SHA-256(machineId + salt).hex[0..32] (prefiks od 32 znaka) u bin/cli/utils/cliToken.mjs (getLegacyCliTokenSync u src/lib/machineToken.ts).

Radi kompatibilnosti sa starijim verzijama poslužitelj prihvaća oba formata: provjera izrađuje expectedTokens = [getMachineTokenSync(), getLegacyCliTokenSync()] i uspoređuje dolazno zaglavlje sa svakim od njih pomoću timingSafeEqual (src/server/authz/policies/management.ts i src/lib/middleware/cliTokenAuth.ts). Stoga je token valjan ako odgovara ili HMAC sažetku od 64 znaka ili naslijeđenom SHA-256 prefiksu od 32 znaka.

Isključivanje: postavite OMNIROUTE_DISABLE_CLI_TOKEN=true (u okruženju ili datoteci .env) kako biste potpuno onemogućili CLI mehanizam tokena; sav pristup tada zahtijeva izričit API ključ. To se preporučuje na računalima s više korisnika jer je machine-id specifičan za uređaj (ne za korisnika), pa bi drugi korisnik na istom računalu mogao izračunati isti token.

Datoteke

Datoteka	Svrha
src/lib/machineToken.ts	Izvođenje tokena (getMachineTokenSync)
bin/cli/utils/cliToken.mjs	CLI preslika istog postupka izvođenja
<DATA_DIR>/cli-token-salt.json	Trajno spremljena nasumična sol pojedinačne instalacije
src/server/authz/headers.ts	Konstanta CLI_TOKEN_HEADER
src/server/authz/policies/management.ts	Provjera na strani poslužitelja
src/server/authz/routeGuard.ts	Provjera lokalnog hosta (isLoopbackHost)

Vidi također

• docs/security/ROUTE_GUARD_TIERS.md — razine zaštite ruta
• docs/architecture/AUTHZ_GUIDE.md — cjelovit proces autorizacije