Model oprávnění

Přehled SPC

TOS 7 zavádí systém SPC (System Permission Control), který se řídí zásadou nejmenšího oprávnění a spravuje přístupové chování aplikací k systému:

• Aplikace nemohou přímo upravovat systémové soubory ani získávat oprávnění root; všechny žádosti o oprávnění musí být podávány prostřednictvím API platformy
• Vývojáři musí jasně specifikovat požadavky aplikace na oprávnění v deklaraci oprávnění. Aplikace mohou získat odpovídající přístupová oprávnění až po schválení platformou.
• Jakékoli chování obcházející kontroly oprávnění SPC je zakázáno; takové aplikace selžou při kontrole nebo budou staženy z nabídky.

Přehled

TOS7 se řídí zásadou nejmenšího oprávnění. Aplikace mohou požadovat pouze minimální oprávnění nezbytná pro provoz. Aplikace TOS7 komunikují se systémem SPC (System Permission Control). Aplikace musí:

• Deklarovat požadavky na oprávnění v deklaraci oprávnění (oddíl 10.7)
• Neobcházet kontroly oprávnění SPC
• Používat pro žádosti o oprávnění API platformy místo přímé úpravy systémových souborů

Platforma poskytuje strukturovaný model oprávnění pro aplikace Deb i Docker.

Model uživatele a skupiny

Oprávnění root pro uživatele aplikací je přísně zakázáno. Všechny aplikace musí běžet jako vyhrazený nerootový uživatel.

Aplikace Deb:

Scénář	Uživatel	Popis	Požadavek na konfiguraci
Vyhrazený uživatel	<appid>	Musí být použit. Vytvořen skriptem preinst. Minimální oprávnění.	Povinné

Povinný požadavek: Všechny aplikace Deb musí vytvořit vyhrazeného uživatele (<appid>) a spouštět aplikaci jako tohoto uživatele. Spouštění jako root je přísně zakázáno. Vyhrazený uživatel musí být vytvořen ve skriptu preinst, aby byla za běhu zajištěna minimální oprávnění. Datové adresáře aplikace (jako /Volume*/@apps/<appid>/) musí vlastnit vyhrazený uživatel, aby se předešlo chybám oprávnění nebo neoprávněnému přístupu.

Vytvoření vyhrazeného uživatele:

# In preinst
# The system will automatically assign a unique UID to the new user.
useradd --system --no-create-home --shell /usr/sbin/nologin <appid>

Aplikace Docker:

Scénář	Uživatel	Popis
Nerootový	UID:GID (např. 1000:1000)	Musí být použit. Určen prostřednictvím pole user v compose.

Oprávnění souborového systému

Standardní oprávnění adresářů pro aplikace Deb:

Cesta	Vlastník	Oprávnění	Popis
/Volume*/@apps/<appid>/	<appid>:<appid>	755	Adresář aplikace (pro službu pouze pro čtení)
/Volume*/@apps/<appid>/bin/	<appid>:<appid>	755	Spustitelné soubory
/Volume*/@apps/<appid>/config/	<appid>:<appid>	750	Konfigurační soubory (pro službu pouze pro čtení)
/Volume*/@apps/<appid>/site/	<appid>:<appid>	755	Soubory Web UI
/Volume*/@apps/<appid>/data/	<appid>:<appid>	750	Běhová data (čtení a zápis)
/Volume*/@apps/<appid>/logs/	<appid>:<appid>	750	Protokoly aplikace (čtení a zápis)

Poznámka 1: * v /Volume*/ představuje číslo svazku (např. Volume1, Volume2) zvolené uživatelem při instalaci.

Poznámka 2: Binárky a konfigurace aplikace by měly být pro uživatele služby pouze pro čtení. Zapisovatelné by měly být pouze datové a protokolové adresáře.

Poznámka 3: Typy dat

• Běhová data (/Volume*/@apps/<appid>/data/) — Mezipaměti generované aplikací, dočasné soubory a běhový stav. Tato data spravuje aplikace a lze je bezpečně regenerovat.
• Uživatelská data (sdílená složka vytvořená pomocí ter_share_add) — Perzistentní obchodní data (dokumenty, fotografie, databáze). Tato data musí být uložena ve sdílené složce pod /Volume*/, aby k nim uživatelé měli přístup přes SMB/NFS.

Síťová oprávnění

Oprávnění	Aplikace Deb	Aplikace Docker	Popis
Vazba portu	Vazba určeného portu v konfiguraci služby	Mapování portu v compose	Nesmí být v konfliktu se systémovými porty
Přístup k místním službám	Ve výchozím stavu povolen	Použijte network_mode: host nebo explicitní propojení	Minimalizujte síťovou expozici
Odchozí připojení	Povoleno	Povoleno	Odchozí provoz není omezen

Přístup ke sdíleným složkám

Sdílené složky TOS jsou primárním mechanismem přístupu k datům. Aplikace vyžadující přístup k uživatelským datům musí:

1. Vytvořit sdílenou složku pomocí ter_share_add:

ter_share_add -name <appid>-data -owner <appid>

2. Nebo požádat o přístup k existujícím sdíleným složkám připojením ke skupině allusers:

usermod -aG allusers <appid>

3. Aplikace Docker připojují sdílené složky prostřednictvím svazků:

Volumes:
  - /Volume*/<shared_folder>:/data:rw    # Read-write access
  - /Volume*/<shared_folder>:/media:ro   # Read-only access

Důležité

Aplikace nesmějí přímo upravovat oprávnění sdílených složek. Použijte API pro správu sdílených složek TOS nebo nechte uživatele nakonfigurovat přístupová oprávnění ručně.

Proces žádosti o oprávnění

Když aplikace vyžaduje přístup ke sdíleným složkám:

1. Vyhrazená složka aplikace (doporučeno):

   • Vytvořte ji v postinst pomocí ter_share_add
   • Aplikace má plná oprávnění pro čtení a zápis
   • Není vyžadována žádná autorizace uživatele

2. Uživatelské sdílené složky (vyžadována autorizace):

   • Aplikace požádá o členství ve skupině allusers
   • Uživatel autorizuje přístup ke složce prostřednictvím nastavení sdílených složek TOS
   • Aplikace deklaruje požadavky na čtení nebo čtení a zápis v deklaraci oprávnění

3. Formát oprávnění:

   # Docker volumes
   - /Volume*/<shared_folder>:/data:rw   # Read-write access
   - /Volume*/<shared_folder>:/media:ro  # Read-only access

Limity systémových prostředků

Cesta instalace aplikace

Aplikace třetích stran jsou kompletně instalovány na úložné svazky (datové disky) do /Volume*/@apps/<appid>/, nikoli na systémový disk (/).

• * představuje číslo svazku (např. Volume1, Volume2 atd.) zvolené uživatelem při instalaci.
• Všechny soubory aplikace — včetně binárek, konfiguračních souborů, protokolů, skriptů a souborů webového UI — jsou uloženy pod /Volume*/@apps/<appid>/.
• Na systémovém disku se nachází pouze nenáročný registrační/záznamový záznam (používaný TOS k rozpoznání nainstalovaných aplikací). Tento záznam zabírá zanedbatelné místo a nepředstavuje žádný problém s kapacitou.
• Na systémovém disku sídlí pouze aplikace vestavěné do systému (/usr/local/system_app_data/).

✅ Pro vývojáře třetích stran: Protože je celá vaše aplikace (včetně programových souborů, konfigurací a protokolů) nainstalována na datovém disku, kapacita systémového disku není pro vaši aplikaci problémem. Všechna obchodní data by měla být také ukládána na datových discích (/Volume*/), které nemají žádné limity kapacity.

Výchozí kvóty prostředků podle typu aplikace:

Typ aplikace	Limit CPU	Limit paměti	Příklady
Media Server	200% (2 jádra)	2048M	Jellyfin, Plex, Emby
Download Manager	100% (1 jádro)	512M	Aria2, qBittorrent
Utilities	50%	256M	File Manager, Text Editor
Web Service	100% (1 jádro)	512M	CMS, Blog, Wiki
Database	200% (2 jádra)	2048M	MySQL, PostgreSQL, Redis
Security	50%	256M	Firewall, Antivirus

Výše uvedené jsou výchozí hodnoty platformy. Vývojáři mohou v deklaraci oprávnění požádat o vyšší limity s přiměřeným odůvodněním.

Aplikace Deb (prostřednictvím systemd):

[Service]
# Memory limit
MemoryMax=512M
# CPU quota (200% = 2 cores)
CPUQuota=200%
# File descriptor limit
LimitNOFILE=65536
# Process count limit
LimitNPROC=256

Aplikace Docker (prostřednictvím compose):

services:
  myapp:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 128M

Deklarace oprávnění

📝 Poznámka: Následující tabulka je příkladem, který ukazuje, jak zdokumentovat požadavky vaší aplikace na oprávnění. Nahraďte hodnoty (čísla portů, cesty k souborům, uživatelská jména) hodnotami skutečně používanými vaší aplikací.

Pro transparentnost by aplikace měly zdokumentovat své požadavky na oprávnění v README.md:

Oprávnění	Odůvodnění
Síť: Port <your-port>	Přístup k Web UI
Souborový systém: <your-data-path>	Ukládání běhových dat
Uživatel: <your-appid> (systémový uživatel)	Izolované spouštění služby
Sdílená složka: Žádná	Není vyžadován přístup k uživatelským datům

Červené linie oprávnění (automatické zamítnutí)

Následující žádosti o oprávnění povedou k automatickému zamítnutí:

Porušení	Popis
Spouštění jako root	Žádost o spuštění aplikace uživatelem root (včetně nastavení User=root v souborech služeb systemd a neuvedení pole user v Dockeru, což má za následek spuštění jako root)
Privilegovaný režim	Žádost o Docker režim --privileged
Zápis do systémových adresářů	Žádost o přístup k zápisu do systémových adresářů, jako jsou /etc/, /usr/, /boot/
Přístup k datům mezi aplikacemi	Žádost o přístup k datovým adresářům jiných aplikací
Neomezený síťový přístup	Žádost o network_mode: host bez písemného přiměřeného odůvodnění (dostupné pouze síťovým nástrojům na úrovni systému)
Nadměrná expozice portů	Žádost o více portů, než je funkčně nezbytné