fixplesk 0.6.1__py3-none-any.whl

fixplesk/__init__.py

@@ -0,0 +1,5 @@
+"""Plesk and WordPress diagnostics. No I/O or provider imports on package import."""
+from .models import Event, Plan, Snapshot
+
+__all__ = ["Event", "Plan", "Snapshot", "__version__"]
+__version__ = "0.6.1"

fixplesk/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

fixplesk/assurance/__init__.py

@@ -0,0 +1 @@
+"""Evidence-based local assurance. Importing this package performs no I/O."""

fixplesk/assurance/breaches.py

@@ -0,0 +1,149 @@
+"""Opt-in breach checks. Never crack hashes, authenticate to accounts, or expose passwords."""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import re
+import time
+from pathlib import Path
+
+import httpx
+
+from .common import anchored_file, fresh, now
+from .feeds import get_bytes
+
+
+def _sha(value: str) -> str:
+    if not isinstance(value, str) or not 1 <= len(value) <= 4096:
+        raise ValueError('Nieprawidłowy rozmiar wartości; treść nie jest rejestrowana')
+    return hashlib.sha1(value.encode('utf-8'), usedforsecurity=False).hexdigest().upper()
+
+
+def password_range_result(password: str, response: str) -> dict:
+    suffix = _sha(password)[5:]
+    matches = []
+    rows = response.splitlines()
+    if not rows or len(rows) > 100000:
+        raise ValueError('Nieprawidłowa odpowiedź Pwned Passwords; wynik nieznany')
+    seen = set()
+    for row in rows:
+        match = re.fullmatch(r'([A-Fa-f0-9]{35}):(\d{1,18})', row.strip())
+        if match is None or match[1].upper() in seen:
+            raise ValueError('Niejednoznaczna odpowiedź Pwned Passwords; wynik nieznany')
+        seen.add(match[1].upper())
+        if hmac.compare_digest(match[1].upper(), suffix):
+            matches.append(int(match[2]))
+    count = max(matches, default=0)
+    return {'kind': 'password_exposure', 'checked_at': now(),
+            'status': 'found_in_password_corpus' if count else 'not_found_in_queried_corpus',
+            'occurrences': count, 'account_password_verified': False, 'email_linkage_proven': False,
+            'plaintext_stored': False, 'hash_stored': False,
+            'notice': 'Sprawdzono podaną wartość, nie hasło konta. Trafienie nie wskazuje e-maila ani źródła wycieku; brak trafienia nie certyfikuje hasła.'}
+
+
+def check_password_online(password: str, *, consent: bool = False, allow_network: bool = False,
+                          client: httpx.Client | None = None) -> dict:
+    if not consent or not allow_network:
+        raise ValueError('Wymagana świadoma zgoda i --allow-network')
+    prefix = _sha(password)[:5]
+    data, _ = get_bytes('https://api.pwnedpasswords.com/range/' + prefix, limit=5_000_000,
+                        headers={'Add-Padding': 'true'}, client=client)
+    result = password_range_result(password, data.decode('ascii'))
+    result.update({'source': 'HIBP-PwnedPasswords', 'mode': 'sha1_prefix_5_padding',
+                   'network_disclosure': '5 znaków prefiksu SHA-1; nie pełne hasło ani pełny hash'})
+    return result
+
+
+def check_password_file(password: str, path: Path, *, corpus_date: str,
+                        max_seconds: float = 60, max_bytes: int = 2_000_000_000) -> dict:
+    """Streaming SHA1:count input, not email:password. A partial scan never returns clean."""
+    if not fresh(corpus_date, 10 * 365 * 86400):
+        raise ValueError('Podaj prawdziwą datę pochodzenia korpusu; nie datę importu')
+    target = _sha(password)
+    path = path.absolute()
+    consumed = 0
+    count = 0
+    rows = 0
+    started = time.monotonic()
+    complete = True
+    with anchored_file(path.parent, path.name) as fd:
+        import os
+        before = os.fstat(fd)
+        with os.fdopen(os.dup(fd), 'rb') as stream:
+            while True:
+                if consumed >= max_bytes or time.monotonic() - started > max_seconds:
+                    complete = False
+                    break
+                line = stream.readline(128)
+                if not line:
+                    break
+                consumed += len(line)
+                found = re.fullmatch(rb'([A-Fa-f0-9]{40}):(\d{1,18})\r?\n?', line)
+                if found is None:
+                    raise ValueError('Oczekiwany korpus SHA1:count, bez adresów i haseł jawnych')
+                rows += 1
+                if hmac.compare_digest(found[1].decode().upper(), target):
+                    count = max(count, int(found[2]))
+            after = os.fstat(fd)
+            if (before.st_size, before.st_mtime_ns, before.st_ctime_ns) != (after.st_size, after.st_mtime_ns, after.st_ctime_ns):
+                complete = False
+    if rows == 0:
+        raise ValueError('Pusty korpus; nie można wnioskować o braku hasła')
+    return {'kind': 'password_exposure', 'checked_at': now(), 'mode': 'offline_sha1_corpus',
+            'status': 'found_in_password_corpus' if count else 'not_found_in_queried_corpus' if complete else 'unknown_incomplete_scan',
+            'occurrences': count, 'complete_scan': complete, 'corpus_date': corpus_date,
+            'corpus_fresh_24h': fresh(corpus_date), 'rows_scanned': rows,
+            'account_password_verified': False, 'email_linkage_proven': False,
+            'plaintext_stored': False, 'hash_stored': False,
+            'notice': 'Wynik dotyczy tylko dostarczonego korpusu; autentyczność korpusu nie została potwierdzona.'}
+
+
+def normalize_email(email: str) -> str:
+    email = email.strip().lower()
+    if (len(email) > 254 or not re.fullmatch(r'[^\s@\x00-\x1f]+@[^\s@\x00-\x1f]+\.[^\s@\x00-\x1f]+', email)):
+        raise ValueError('Nieprawidłowy adres; wartość nie jest rejestrowana')
+    return email
+
+
+def email_range_result(email: str, records: list, *, account_ref: str) -> dict:
+    if not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.:-]{0,95}', account_ref):
+        raise ValueError('Użyj lokalnego identyfikatora konta, bez danych osobowych')
+    suffix = _sha(normalize_email(email))[6:]
+    if not isinstance(records, list) or len(records) > 100000:
+        raise ValueError('Nieprawidłowa odpowiedź zakresu HIBP')
+    sites = []
+    seen = set()
+    for record in records:
+        if not isinstance(record, dict) or set(record) != {'hashSuffix', 'websites'}:
+            raise ValueError('Nieznany format HIBP; bez przetwarzania dodatkowych pól')
+        value = record['hashSuffix']
+        websites = record['websites']
+        if (not isinstance(value, str) or not re.fullmatch(r'[A-Fa-f0-9]{34}', value)
+                or value.upper() in seen or not isinstance(websites, list) or len(websites) > 5000
+                or any(not isinstance(s, str) or len(s) > 256 or any(ord(c) < 32 for c in s) for s in websites)):
+            raise ValueError('Nieprawidłowy rekord zakresu HIBP')
+        seen.add(value.upper())
+        if hmac.compare_digest(value.upper(), suffix):
+            sites = websites
+        # Other identities and their breach names are deliberately not returned/persisted.
+    return {'kind': 'email_exposure', 'account_ref': account_ref, 'checked_at': now(),
+            'status': 'address_reported_in_breaches' if sites else 'not_found_in_returned_breaches',
+            'breach_names': sites, 'raw_email_stored': False, 'unrelated_accounts_stored': False,
+            'current_password_exposed': 'unknown', 'account_taken_over': 'unknown',
+            'notice': 'Adres w bazie wycieków nie dowodzi wycieku obecnego hasła ani włamania na tę skrzynkę. Zakres API nie obejmuje wszystkich wycieków.'}
+
+
+def check_email_online(email: str, api_key: str, *, account_ref: str, consent: bool = False,
+                       allow_network: bool = False, client: httpx.Client | None = None) -> dict:
+    if not consent or not allow_network:
+        raise ValueError('Wymagana zgoda na kontrolę własnego lub powierzonego konta i --allow-network')
+    if not re.fullmatch(r'[a-fA-F0-9]{32}', api_key):
+        raise ValueError('Brak prawidłowego HIBP_API_KEY')
+    import json
+    prefix = _sha(normalize_email(email))[:6]
+    data, _ = get_bytes('https://haveibeenpwned.com/api/v3/breachedaccount/range/' + prefix,
+                        limit=8_000_000, headers={'hibp-api-key': api_key}, client=client)
+    result = email_range_result(email, json.loads(data), account_ref=account_ref)
+    result.update({'source': 'HIBP', 'mode': 'email_sha1_prefix_6',
+                   'network_disclosure': '6 znaków SHA-1 adresu; wymagana usługa obsługująca tę funkcję, bez fallback do jawnego adresu'})
+    return result

fixplesk/assurance/cli.py

@@ -0,0 +1,293 @@
+"""Explicit guard commands: no background downloads or implicit model execution."""
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import os
+import sys
+import zipfile
+from pathlib import Path
+
+from fixplesk.config import load_config
+
+from .common import digest, read_bytes, read_json, write_json
+from .feeds import SOURCES, FeedCache, enrich_priorities, match_wordpress
+from .filesystem import ScanLimits, compare, scan
+from .observe import ObservationPolicy, observe
+from .permissions import PermissionPlan, checked_target, dry_run, execute, make_plan, reconcile
+from .runtime import ScriptSpec, Session
+
+
+def register(commands) -> None:
+    root = commands.add_parser('guard', help='Wersja 0.5: pliki, bazy dowodów, wycieki, jawne skrypty i kontrola zmian')
+    groups = root.add_subparsers(dest='guard_group', required=True)
+    feeds = groups.add_parser('feeds').add_subparsers(dest='guard_action', required=True)
+    for action in ('list', 'sync', 'import', 'status'):
+        p = feeds.add_parser(action)
+        p.add_argument('--output', type=Path)
+        if action == 'list':
+            continue
+        p.add_argument('--source', required=True, choices=sorted(SOURCES))
+        p.add_argument('--cache', type=Path, default=Path.home() / '.cache/fixplesk/feeds')
+        p.add_argument('--version')
+        p.add_argument('--locale')
+        if action == 'sync':
+            p.add_argument('--allow-network', action='store_true')
+        if action == 'import':
+            p.add_argument('--input', required=True, type=Path)
+            p.add_argument('--obtained-at', required=True, help='Rzeczywista data pozyskania, ISO8601 ze strefą')
+    p = groups.add_parser('wp-match', help='Dopasuj zapisane komponenty do Wordfence; niczego nie aktualizuje')
+    p.add_argument('--inventory', type=Path, required=True)
+    p.add_argument('--cache', type=Path, default=Path.home() / '.cache/fixplesk/feeds')
+    p.add_argument('--output', type=Path)
+    f = groups.add_parser('files').add_subparsers(dest='guard_action', required=True)
+    p = f.add_parser('scan')
+    s = p.add_mutually_exclusive_group(required=True)
+    s.add_argument('--domain')
+    s.add_argument('--all', action='store_true', help='Tylko jawne widoczne cele inventory; nie całe /var/www')
+    p.add_argument('--limits', type=Path)
+    p.add_argument('--indicators', type=Path)
+    p.add_argument('--checksum-version')
+    p.add_argument('--checksum-locale')
+    p.add_argument('--cache', type=Path, default=Path.home() / '.cache/fixplesk/feeds')
+    p.add_argument('--output', type=Path)
+    p = f.add_parser('compare')
+    p.add_argument('--before', type=Path, required=True)
+    p.add_argument('--after', type=Path, required=True)
+    p.add_argument('--output', type=Path)
+    breach = groups.add_parser('breach').add_subparsers(dest='guard_action', required=True)
+    p = breach.add_parser('email', help='HIBP k-anon: ukryty prompt e-mail, bez jawnego adresu w argv')
+    p.add_argument('--account-ref', required=True)
+    p.add_argument('--response', type=Path, help='Opcjonalny lokalny JSON odpowiedzi range do kontroli offline')
+    p.add_argument('--consent', action='store_true')
+    p.add_argument('--allow-network', action='store_true')
+    p.add_argument('--output', type=Path)
+    p = breach.add_parser('password', help='Ukryty prompt; nigdy argument, log ani dane LLM')
+    modes = p.add_mutually_exclusive_group(required=True)
+    modes.add_argument('--online', action='store_true')
+    modes.add_argument('--offline-hashes', type=Path)
+    p.add_argument('--corpus-date')
+    p.add_argument('--assert-current', action='store_true', help='Deklaracja użytkownika, nie uwierzytelnienie hasła')
+    p.add_argument('--consent', action='store_true')
+    p.add_argument('--allow-network', action='store_true')
+    p.add_argument('--output', type=Path)
+    p = groups.add_parser('wp-data', help='Odczytowy audyt jawnego eksportu wybranych pól WP')
+    p.add_argument('--input', type=Path, required=True)
+    p.add_argument('--output', type=Path)
+    session = groups.add_parser('session').add_subparsers(dest='guard_action', required=True)
+    for action in ('create', 'list', 'stage', 'run', 'capture', 'export'):
+        p = session.add_parser(action)
+        p.add_argument('--domain', required=True)
+        p.add_argument('--output', type=Path, required=action == 'export')
+        if action != 'create':
+            p.add_argument('--session', type=Path, required=True)
+        if action == 'stage':
+            p.add_argument('--spec', type=Path, required=True)
+        if action == 'run':
+            p.add_argument('--script', required=True)
+            p.add_argument('--approve', required=True)
+            p.add_argument('--execute', action='store_true')
+        if action == 'capture':
+            p.add_argument('--policy', type=Path, required=True)
+            p.add_argument('--allow-network', action='store_true')
+    perms = groups.add_parser('permissions').add_subparsers(dest='guard_action', required=True)
+    p = perms.add_parser('plan')
+    p.add_argument('--domain', required=True)
+    p.add_argument('--path', required=True, help='Ścieżka względna w document_root')
+    p.add_argument('--mode', required=True, help='Węższe prawa, np. 0640')
+    p.add_argument('--policy', type=Path, required=True)
+    p.add_argument('--why', required=True)
+    p.add_argument('--allow-restore-previous-mode', action='store_true')
+    p.add_argument('--output', type=Path, required=True)
+    p = perms.add_parser('run')
+    p.add_argument('--plan', required=True, type=Path)
+    p.add_argument('--approve', default='')
+    p.add_argument('--execute', action='store_true')
+    p.add_argument('--allow-network', action='store_true')
+    p.add_argument('--output', type=Path)
+    p = perms.add_parser('reconcile')
+    p.add_argument('--digest', required=True)
+    p.add_argument('--acknowledge', action='store_true')
+    p.add_argument('--allow-network', action='store_true')
+    p.add_argument('--output', type=Path)
+    p = groups.add_parser('schema')
+    p.add_argument('--kind', choices=['script', 'policy', 'permission-plan', 'wp-data', 'hash-indicator', 'scan-limits'], required=True)
+    p.add_argument('--output', type=Path)
+
+
+def _hidden(prompt: str) -> str:
+    if not sys.stdin.isatty():
+        raise ValueError('Wymagany lokalny TTY. Nie podawaj hasła/adresu w argv, potoku ani pliku')
+    return getpass.getpass(prompt)
+
+
+def _safe_output(path: Path | None, targets: list) -> None:
+    if path is None:
+        return
+    # Reports/scripts contain local identities; do not publish them inside a web root.
+    candidate = path.absolute()
+    for target in targets:
+        if target.document_root:
+            try:
+                candidate.relative_to(target.document_root.absolute())
+            except ValueError:
+                continue
+            raise ValueError('Raport/plan/archiwum nie może być zapisywany pod document_root')
+
+
+def run(args: argparse.Namespace, emit) -> int:
+    def emit(value, output=None):
+        if output is not None:
+            write_json(output, value)
+        else:
+            print(json.dumps(value, ensure_ascii=True, indent=2, allow_nan=False))
+    group, action = args.guard_group, getattr(args, 'guard_action', None)
+    out = getattr(args, 'output', None)
+    if group == 'schema':
+        from .indicators import HashIndicator
+        from .wpdata import WPDataExport
+        models = {'script': ScriptSpec, 'policy': ObservationPolicy, 'permission-plan': PermissionPlan,
+                  'wp-data': WPDataExport, 'hash-indicator': HashIndicator, 'scan-limits': ScanLimits}
+        emit(models[args.kind].model_json_schema(), out)
+    elif group == 'feeds':
+        if action == 'list':
+            emit(SOURCES, out)
+        else:
+            cache = FeedCache(args.cache)
+            params = {'version': args.version, 'locale': args.locale}
+            if action == 'sync':
+                value = cache.sync(args.source, allow_network=args.allow_network, **params)
+            elif action == 'import':
+                value = cache.save(args.source, read_bytes(args.input, SOURCES[args.source]['max_bytes']),
+                                   obtained_at=args.obtained_at, **params)
+            else:
+                _, value = cache.load(args.source, **params)
+            emit(value, out)
+    elif group == 'wp-match':
+        records, metadata = FeedCache(args.cache).load('wordfence')
+        report = match_wordpress(read_json(args.inventory), records, metadata)
+        emit(enrich_priorities(report, FeedCache(args.cache)), out)
+    elif group == 'wp-data':
+        from .wpdata import WPDataExport, inspect_wp_data
+        emit(inspect_wp_data(WPDataExport.model_validate(read_json(args.input))), out)
+    elif group == 'breach':
+        from .breaches import (
+            check_email_online,
+            check_password_file,
+            check_password_online,
+            email_range_result,
+        )
+        if not args.consent:
+            raise ValueError('Wymagana zgoda właściciela lub uprawnionego administratora (--consent)')
+        if action == 'email':
+            value = _hidden('Adres własnego/powierzonego konta (ukryty): ')
+            try:
+                if args.response:
+                    result = email_range_result(value, read_json(args.response), account_ref=args.account_ref)
+                    result['source'] = 'unattested_local_range_response'
+                else:
+                    result = check_email_online(value, os.environ.get('HIBP_API_KEY', ''), account_ref=args.account_ref,
+                                                consent=True, allow_network=args.allow_network)
+            finally:
+                del value
+        else:
+            value = _hidden('Hasło do sprawdzenia (nie jest zapisywane): ')
+            try:
+                if args.online:
+                    result = check_password_online(value, consent=True, allow_network=args.allow_network)
+                else:
+                    if not args.corpus_date:
+                        raise ValueError('Korpus offline wymaga --corpus-date')
+                    result = check_password_file(value, args.offline_hashes, corpus_date=args.corpus_date)
+                result['current_password_declared_by_user'] = args.assert_current
+            finally:
+                del value  # CPython cannot guarantee secure zeroisation of immutable str.
+        emit(result, out)
+    elif group == 'files' and action == 'compare':
+        emit(compare(read_json(args.before, 96_000_000), read_json(args.after, 96_000_000)), out)
+    elif group == 'permissions' and action == 'run' and not args.execute:
+        emit(dry_run(PermissionPlan.model_validate(read_json(args.plan))), out)
+    else:
+        config = load_config(args.config)
+        _safe_output(out, config.visible_targets())
+        if group == 'files':
+            targets = config.visible_targets() if args.all else [config.target(args.domain)]
+            if args.all and args.checksum_version:
+                raise ValueError('Nie przypisuj jednej wersji sum wszystkim domenom; wybierz pojedynczy cel')
+            limits = ScanLimits.model_validate(read_json(args.limits)) if args.limits else ScanLimits()
+            checksums, context = None, None
+            if args.checksum_version:
+                checksums, meta = FeedCache(args.cache).load('wp-checksums', version=args.checksum_version, locale=args.checksum_locale)
+                context = {'version': args.checksum_version, 'locale': args.checksum_locale,
+                           'source_sha256': meta['sha256'], 'inventory_version_verified': False,
+                           'feed_fresh': meta['fresh_for_policy'], 'notice': 'Wersję wybrał operator; porównaj z lokalnym inventory WP.'}
+            reports = []
+            indicators = None
+            if args.indicators:
+                from .indicators import load_indicators
+                indicators = load_indicators(args.indicators)
+            for target in targets:
+                checked_target(config, target.domain)
+                report = scan(target.document_root, domain=target.domain, tenant=target.tenant_id,
+                              limits=limits, checksums=checksums, checksum_context=context)
+                if indicators:
+                    from .indicators import apply_indicators
+                    report = apply_indicators(report, indicators)
+                reports.append(report)
+            emit({'kind': 'scoped_multi_site_audit', 'reports': reports,
+                  'notice': 'Wyłącznie widoczne skonfigurowane document_root; nie odkryto wszystkich domen serwera.'} if args.all else reports[0], out)
+        elif group == 'session':
+            target = checked_target(config, args.domain)
+            session = Session.create(config, target) if action == 'create' else Session(args.session, config, target)
+            if action == 'create':
+                emit({'session': str(session.path), 'manifest': session.manifest}, out)
+            elif action == 'list':
+                emit(read_json(session.path / 'session.json'), out)
+            elif action == 'stage':
+                emit(session.stage(ScriptSpec.model_validate(read_json(args.spec))), out)
+            elif action == 'run':
+                emit(session.run(args.script, approved_digest=args.approve, execute=args.execute), out)
+            elif action == 'capture':
+                policy = ObservationPolicy.model_validate(read_json(args.policy))
+                value = observe(config, target, policy, allow_network=args.allow_network)
+                name = digest(value) + '.json'
+                write_json(session.path / 'observations' / name, value)
+                write_json(session.archive / 'observations' / name, value)
+                session.event('observation', {'file': name, 'checks_passed': value['checks_passed']})
+                emit(value, out)
+            elif action == 'export':
+                # Create exclusively and read no symlinks. Export contains local sensitive metadata.
+                if out.absolute().is_relative_to(session.path):
+                    raise ValueError('Archiwum musi być poza katalogiem sesji')
+                from .common import open_dir
+                export_parent = open_dir(out.absolute().parent)
+                try:
+                    output_fd = os.open(out.name, os.O_CREAT | os.O_EXCL | os.O_WRONLY | os.O_NOFOLLOW, 0o600, dir_fd=export_parent)
+                finally:
+                    os.close(export_parent)
+                with os.fdopen(output_fd, 'wb') as stream, zipfile.ZipFile(stream, 'w', zipfile.ZIP_DEFLATED) as archive:
+                    for path in sorted(session.path.rglob('*')):
+                        if path.is_symlink():
+                            raise ValueError('Dowiązanie w sesji; odmowa eksportu')
+                        if path.is_file() and path.name != '.lock':
+                            archive.writestr(str(path.relative_to(session.path)), read_bytes(path, 96_000_000))
+                session.event('session_exported', {'export_created': True})
+                emit({'export': str(out), 'private_local_metadata': True}, None)
+        elif group == 'permissions':
+            if action == 'plan':
+                value = make_plan(config, args.domain, args.path, args.mode,
+                                  ObservationPolicy.model_validate(read_json(args.policy)), args.why,
+                                  allow_restore_previous_mode=args.allow_restore_previous_mode)
+                emit(value.model_dump(mode='json'), out)
+            elif action == 'run':
+                value = execute(config, PermissionPlan.model_validate(read_json(args.plan)), approved_digest=args.approve,
+                                execute_changes=True, allow_network=args.allow_network)
+                emit(value, out)
+                if value['status'] not in ('succeeded_within_observed_scope', 'rolled_back'):
+                    return 4
+            elif action == 'reconcile':
+                emit(reconcile(config, args.digest, acknowledge=args.acknowledge, allow_network=args.allow_network), out)
+        else:
+            raise ValueError('Nieznana komenda guard')
+    return 0

fixplesk/assurance/common.py

@@ -0,0 +1,212 @@
+"""Bounded, no-follow I/O used by the new guard commands (Linux/POSIX)."""
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import os
+import stat
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterator
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def age(value: str, *, clock: datetime | None = None) -> float:
+    stamp = datetime.fromisoformat(value.replace('Z', '+00:00'))
+    if stamp.tzinfo is None:
+        raise ValueError('Czas musi zawierać strefę')
+    return ((clock or datetime.now(timezone.utc)) - stamp).total_seconds()
+
+
+def fresh(value: str | None, ttl: int = 86400) -> bool:
+    if value is None:
+        return False
+    try:
+        return -60 <= age(value) <= ttl
+    except (ValueError, TypeError, OverflowError):
+        return False
+
+
+def digest(value: Any) -> str:
+    return hashlib.sha256(json.dumps(value, sort_keys=True, separators=(',', ':'),
+                                     ensure_ascii=True, allow_nan=False).encode()).hexdigest()
+
+
+def relative(value: str) -> str:
+    if (not value or len(value) > 4096 or value.startswith('/') or '\\' in value
+            or any(ord(c) < 32 or ord(c) == 127 for c in value)
+            or any(p in ('', '.', '..') for p in value.split('/'))):
+        raise ValueError('Wymagana jednoznaczna ścieżka względna, bez dowiązań i ..')
+    return value
+
+
+def open_dir(path: Path) -> int:
+    """Anchor every absolute component with openat/O_NOFOLLOW; no resolve() race."""
+    path = path.absolute()
+    if '..' in path.parts:
+        raise ValueError('Niedozwolona ścieżka katalogu')
+    fd = os.open('/', os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    try:
+        for part in path.parts[1:]:
+            child = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fd)
+            os.close(fd)
+            fd = child
+        return fd
+    except BaseException:
+        os.close(fd)
+        raise
+
+
+@contextlib.contextmanager
+def anchored_file(root: Path, name: str, *, write: bool = False) -> Iterator[int]:
+    """File descriptor remains pinned during checks/mutation. Reject all symlinks."""
+    parts = relative(name).split('/')
+    directory = open_dir(root)
+    fd = -1
+    try:
+        for part in parts[:-1]:
+            child = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=directory)
+            os.close(directory)
+            directory = child
+        flags = (os.O_RDWR if write else os.O_RDONLY) | os.O_NOFOLLOW | os.O_NONBLOCK
+        fd = os.open(parts[-1], flags, dir_fd=directory)
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            raise ValueError('Operacja wymaga zwykłego pliku')
+        yield fd
+    finally:
+        if fd >= 0:
+            os.close(fd)
+        os.close(directory)
+
+
+def read_bytes(path: Path, limit: int = 12_000_000) -> bytes:
+    path = path.absolute()
+    with anchored_file(path.parent, path.name) as fd:
+        out = bytearray()
+        while len(out) <= limit:
+            part = os.read(fd, min(65536, limit + 1 - len(out)))
+            if not part:
+                return bytes(out)
+            out.extend(part)
+        raise ValueError('Przekroczono limit danych wejściowych')
+
+
+def read_json(path: Path, limit: int = 12_000_000) -> Any:
+    def duplicate_check(pairs):
+        result = {}
+        for key, value in pairs:
+            if key in result:
+                raise ValueError('Powtórzony klucz JSON')
+            result[key] = value
+        return result
+    def invalid_number(_):
+        raise ValueError('JSON zawiera niestandardową liczbę')
+    return json.loads(read_bytes(path, limit), object_pairs_hook=duplicate_check,
+                      parse_constant=invalid_number)
+
+
+def write_json(path: Path, value: Any, *, overwrite: bool = True) -> None:
+    """Create private output using pinned parent FDs, without following any symlink."""
+    import secrets
+    path = path.absolute()
+    if '..' in path.parts:
+        raise ValueError('Nieprawidłowa ścieżka wyniku')
+    parent = os.open('/', os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    temp = '.fixplesk-' + secrets.token_hex(12)
+    created = False
+    try:
+        for part in path.parts[1:-1]:
+            try:
+                child = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=parent)
+            except FileNotFoundError:
+                try:
+                    os.mkdir(part, mode=0o700, dir_fd=parent)
+                except FileExistsError:
+                    pass
+                child = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=parent)
+            os.close(parent)
+            parent = child
+        try:
+            dst = os.stat(path.name, dir_fd=parent, follow_symlinks=False)
+            if not stat.S_ISREG(dst.st_mode):
+                raise ValueError('Wynik nie może zastępować dowiązania ani pliku specjalnego')
+        except FileNotFoundError:
+            pass
+        data = (json.dumps(value, ensure_ascii=True, indent=2, allow_nan=False) + '\n').encode()
+        fd = os.open(temp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=parent)
+        created = True
+        try:
+            position = 0
+            while position < len(data):
+                written = os.write(fd, data[position:position+65536])
+                if written <= 0:
+                    raise OSError('Niepełny zapis wyniku')
+                position += written
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        if overwrite:
+            os.replace(temp, path.name, src_dir_fd=parent, dst_dir_fd=parent)
+            created = False
+        else:
+            os.link(temp, path.name, src_dir_fd=parent, dst_dir_fd=parent, follow_symlinks=False)
+        os.fsync(parent)
+    finally:
+        if created:
+            os.unlink(temp, dir_fd=parent)
+        os.close(parent)
+
+
+def private_directory(path: Path) -> Path:
+    path = path.expanduser().absolute()
+    if '..' in path.parts:
+        raise ValueError('Nieprawidłowa ścieżka katalogu prywatnego')
+    fd = os.open('/', os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    try:
+        for part in path.parts[1:]:
+            try:
+                child = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fd)
+            except FileNotFoundError:
+                try:
+                    os.mkdir(part, mode=0o700, dir_fd=fd)
+                except FileExistsError:
+                    pass
+                child = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fd)
+            os.close(fd)
+            fd = child
+        st = os.fstat(fd)
+        if st.st_uid != os.geteuid() or st.st_mode & 0o077:
+            raise ValueError('Katalog prywatny musi należeć do bieżącego UID i mieć prawa 0700')
+    finally:
+        os.close(fd)
+    return path
+
+
+def identity(st: os.stat_result) -> dict[str, int]:
+    return {'device': st.st_dev, 'inode': st.st_ino, 'uid': st.st_uid, 'gid': st.st_gid,
+            'mode': stat.S_IMODE(st.st_mode), 'size': st.st_size, 'mtime_ns': st.st_mtime_ns,
+            'ctime_ns': st.st_ctime_ns, 'nlink': st.st_nlink}
+
+
+def file_hash(fd: int, maximum: int = 16_000_000) -> str:
+    before = identity(os.fstat(fd))
+    if before['size'] > maximum or before['nlink'] != 1:
+        raise ValueError('Plik zbyt duży albo współdzielony hardlink')
+    os.lseek(fd, 0, os.SEEK_SET)
+    total = 0
+    sha = hashlib.sha256()
+    while True:
+        chunk = os.read(fd, min(65536, maximum + 1 - total))
+        if not chunk:
+            break
+        total += len(chunk)
+        if total > maximum:
+            raise ValueError('Plik rośnie podczas odczytu')
+        sha.update(chunk)
+    if identity(os.fstat(fd)) != before:
+        raise ValueError('Plik zmienił się podczas odczytu')
+    return sha.hexdigest()