Skip to content

armgit / ODS

Public Imported from GitHub
0

ODS V3 Pre-Release: Public testing and refinement ahead of the official V3 launch. Turn your PC, Mac, or Linux box into a private AI server.

19.3 KB
Raw Blame
"""Fail-closed file custody for the forthcoming macOS service adapter.

This verifies deployment files, not a running process or its isolation. Callers
must still verify the loaded launchd job and qualify the host access controls.
"""
import ctypes
from contextlib import contextmanager
import errno
import hashlib
import os
import plistlib
import re
import stat
import sys
from xml.parsers.expat import ExpatError


class CustodyError(ValueError):
    pass


def verify_loaded_launchd_definition(raw, target, filename, expected):
    """Compare a launchctl print snapshot with a trusted deployment definition.

    This supplements on-disk custody: kickstart does not reload a changed plist.
    It proves neither process identity nor absence of surviving descendants.
    Unknown launchctl formatting fails closed; never parse untrusted output as
    a deployment specification.
    """
    def fail():
        raise CustodyError('launchd-loaded-definition-mismatch')

    if (not isinstance(raw, str) or not isinstance(expected, dict)
            or not isinstance(target, str) or not re.fullmatch(
                r'(?:system|gui/[0-9]+)/[A-Za-z0-9][A-Za-z0-9.-]{0,127}', target)):
        fail()
    lines = raw.splitlines()
    if not lines or lines[0] != target + ' = {' or lines[-1] != '}':
        fail()

    def scalar(name):
        values = re.findall(r'^\t' + re.escape(name) + r' = ([^\n]*)$', raw, re.M)
        if len(values) != 1:
            fail()
        return values[0]

    def block(name, *, optional=False):
        start = '\t' + name + ' = {'
        positions = [i for i, line in enumerate(lines) if line == start]
        if not positions and optional:
            return []
        if len(positions) != 1:
            fail()
        values = []
        for line in lines[positions[0] + 1:]:
            if line == '\t}':
                return values
            if not line.startswith('\t\t') or line.startswith('\t\t\t'):
                fail()
            values.append(line[2:])
        fail()

    args = expected.get('ProgramArguments')
    environment = expected.get('EnvironmentVariables', {})
    if (expected.get('Label') != target.split('/')[-1]
            or not isinstance(args, list) or not args
            or any(not isinstance(a, str) or not a or any(c in a for c in '\n\r\t') for a in args)
            or not isinstance(environment, dict)
            or any(not isinstance(k, str) or not isinstance(v, str)
                   or any(c in k + v for c in '\n\r\t') for k, v in environment.items())):
        fail()
    for key, value in {'path': os.fspath(filename),
                       'program': expected.get('Program', args[0]),
                       'working directory': expected.get('WorkingDirectory'),
                       'stdout path': expected.get('StandardOutPath'),
                       'stderr path': expected.get('StandardErrorPath')}.items():
        if not isinstance(value, str) or scalar(key) != value:
            fail()
    # env -i is an explicit process boundary: launchd still lists session
    # variables, but they are cleared before executing the approved arguments.
    clean_environment = args[:2] == ['/usr/bin/env', '-i'] and len(args) > 2
    if (block('arguments') != args
            or block('inherited environment', optional=True) and not clean_environment):
        fail()
    loaded = {}
    for line in block('environment'):
        key, separator, value = line.partition(' => ')
        if not separator or not key or key in loaded:
            fail()
        loaded[key] = value
    # launchd injects these independently of EnvironmentVariables.
    if loaded.pop('XPC_SERVICE_NAME', None) != expected['Label']:
        fail()
    rate = loaded.pop('OSLogRateLimit', None)
    if rate is not None and not rate.isdecimal():
        fail()
    if loaded != environment:
        fail()


def _require_no_acl(fd):
    if sys.platform != 'darwin':
        raise CustodyError('macos-custody-platform-required')
    libc = ctypes.CDLL('/usr/lib/libSystem.B.dylib', use_errno=True)
    libc.acl_get_fd_np.argtypes = [ctypes.c_int, ctypes.c_int]
    libc.acl_get_fd_np.restype = ctypes.c_void_p
    libc.acl_valid.argtypes = [ctypes.c_void_p]
    libc.acl_valid.restype = ctypes.c_int
    libc.acl_get_entry.argtypes = [ctypes.c_void_p, ctypes.c_int,
                                   ctypes.POINTER(ctypes.c_void_p)]
    libc.acl_get_entry.restype = ctypes.c_int
    libc.acl_free.argtypes = [ctypes.c_void_p]
    libc.acl_free.restype = ctypes.c_int
    ctypes.set_errno(0)
    acl = libc.acl_get_fd_np(fd, 0x100)  # ACL_TYPE_EXTENDED from sys/acl.h.
    if not acl:
        # Apple's filesec_get_property reports absent FILESEC_ACL as ENOENT.
        # This is a descriptor query, not a missing pathname. Other errors fail.
        if ctypes.get_errno() == errno.ENOENT:
            os.fstat(fd)
            return
        raise CustodyError('macos-custody-acl-unavailable')
    try:
        if libc.acl_valid(acl) != 0:
            raise CustodyError('macos-custody-acl-invalid')
        entry = ctypes.c_void_p()
        ctypes.set_errno(0)
        result = libc.acl_get_entry(acl, 0, ctypes.byref(entry))
        # Darwin returns 0 for an entry, -1/EINVAL for an empty valid ACL.
        # Reject even restrictive ACLs: deployment never needs custom entries.
        if result != -1 or ctypes.get_errno() != errno.EINVAL:
            raise CustodyError('macos-custody-acl-present')
    finally:
        libc.acl_free(acl)


def _verify_fd(fd, *, directory):
    info = os.fstat(fd)
    kind = stat.S_ISDIR if directory else stat.S_ISREG
    if (not kind(info.st_mode) or info.st_uid != 0 or info.st_mode & 0o022
            or not directory and info.st_nlink != 1):
        raise CustodyError('macos-root-custody-required')
    _require_no_acl(fd)
    return info


@contextmanager
def protected_directory(filename, *, create=False):
    """Open a canonical root-owned directory, optionally creating missing parts.

    Every component is checked before descending. Creation never changes an
    existing directory's ownership, mode or ACL to make it appear trusted.
    """
    value = os.fspath(filename)
    if (not isinstance(value, str) or not value.startswith('/') or value == '/'
            or any(ord(c) < 32 for c in value)
            or any(part in ('', '.', '..') for part in value.split('/')[1:])):
        raise CustodyError('macos-custody-path-invalid')
    flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
    fd = os.open('/', flags)
    try:
        _verify_fd(fd, directory=True)
        for part in value.split('/')[1:]:
            created = False
            if create:
                try:
                    os.mkdir(part, mode=0o755, dir_fd=fd)
                    created = True
                    os.fsync(fd)
                except FileExistsError:
                    pass
            child = os.open(part, flags, dir_fd=fd)
            os.close(fd)
            fd = child
            _verify_fd(fd, directory=True)
            if created:
                os.fchmod(fd, 0o755)
                os.fsync(fd)
        yield fd
    finally:
        os.close(fd)


def protected_tree_metadata(root):
    """Require root custody of every entry; content/link topology is separate.

    Internal links are allowed only to other entries under this verified tree.
    Target files/directories are checked independently, including their ACLs.
    This does not authorize any executable or verify manifest hashes.
    """
    from pathlib import Path
    root = Path(root)
    with protected_directory(root) as root_fd:
        def visit(directory):
            for name in os.listdir(directory):
                info = os.stat(name, dir_fd=directory, follow_symlinks=False)
                if stat.S_ISLNK(info.st_mode):
                    if info.st_uid != 0 or info.st_nlink != 1:
                        raise CustodyError('macos-root-custody-required')
                    continue
                is_directory = stat.S_ISDIR(info.st_mode)
                flags = os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK
                fd = os.open(name, flags | (os.O_DIRECTORY if is_directory else 0), dir_fd=directory)
                try:
                    _verify_fd(fd, directory=is_directory)
                    if is_directory:
                        visit(fd)
                finally:
                    os.close(fd)
        visit(root_fd)
        # Resolve only after all directories are root verified. The publication
        # caller holds the root deployment lock while checking this tree.
        for directory, folders, files in os.walk(root, followlinks=False):
            for name in folders + files:
                path = Path(directory) / name
                if path.is_symlink():
                    try:
                        target = path.resolve(strict=True)
                    except (OSError, RuntimeError):
                        raise CustodyError('macos-custody-link-invalid') from None
                    if os.readlink(path).startswith('/') or (target != root and root not in target.parents):
                        raise CustodyError('macos-custody-link-invalid')


def protected_bytes(filename, *, limit=1024 * 1024):
    """Read a bounded root-owned file through individually verified dirfds.

    No resolve(): that would hide symlinks before checking them. Walking from
    an open root prevents replacement of an unchecked intermediate directory.
    """
    value = os.fspath(filename)
    if (not isinstance(value, str) or not value.startswith('/') or '\0' in value
            or any(part in ('', '.', '..') for part in value.split('/')[1:])
            or type(limit) is not int or limit < 1):
        raise CustodyError('macos-custody-path-invalid')
    parts = value.split('/')[1:]
    opened = []
    flags = os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK
    try:
        parent = os.open('/', flags | os.O_DIRECTORY)
        opened.append(parent)
        _verify_fd(parent, directory=True)
        for part in parts[:-1]:
            parent = os.open(part, flags | os.O_DIRECTORY, dir_fd=parent)
            opened.append(parent)
            _verify_fd(parent, directory=True)
        fd = os.open(parts[-1], flags, dir_fd=parent)
        opened.append(fd)
        before = _verify_fd(fd, directory=False)
        if before.st_size > limit:
            raise CustodyError('macos-custody-file-too-large')
        chunks, length = [], 0
        while length <= limit:
            chunk = os.read(fd, min(65536, limit + 1 - length))
            if not chunk:
                break
            chunks.append(chunk)
            length += len(chunk)
        after = _verify_fd(fd, directory=False)
        identity = lambda s: (s.st_dev, s.st_ino, s.st_size, s.st_mtime_ns, s.st_ctime_ns)
        if identity(before) != identity(after):
            raise CustodyError('macos-custody-file-changed')
        if length > limit:
            raise CustodyError('macos-custody-file-too-large')
        return b''.join(chunks)
    except OSError:
        raise CustodyError('macos-custody-file-unavailable') from None
    finally:
        for fd in reversed(opened):
            os.close(fd)


def replace_protected_bytes(filename, *, expected, replacement, mode, gid=0):
    """Replace an existing protected file while the caller holds its transaction lock.

    No ownership repair, new target creation or symlink resolution is allowed.
    An fsync failure after rename remains an error: callers must inspect the
    target and use their durable rollback journal, not assume no write happened.
    """
    if (type(expected) is not bytes or type(replacement) is not bytes
            or max(len(expected), len(replacement)) > 8 * 1024 * 1024
            or type(mode) is not int or mode not in (0o600, 0o640, 0o644, 0o755)
            or type(gid) is not int or gid < 0):
        raise CustodyError('macos-custody-replacement-invalid')
    value = os.fspath(filename)
    if not isinstance(value, str) or '/' not in value:
        raise CustodyError('macos-custody-path-invalid')
    parent, name = value.rsplit('/', 1)
    if not name or name in ('.', '..') or any(ord(c) < 32 for c in name):
        raise CustodyError('macos-custody-path-invalid')
    identity = lambda s: (s.st_dev, s.st_ino, s.st_size, s.st_mtime_ns, s.st_ctime_ns)
    with protected_directory(parent) as directory:
        fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=directory)
        temporary = None
        try:
            before = _verify_fd(fd, directory=False)
            if stat.S_IMODE(before.st_mode) != mode or before.st_gid != gid:
                raise CustodyError('macos-custody-replacement-metadata-changed')
            chunks, length = [], 0
            while length <= len(expected):
                chunk = os.read(fd, min(65536, len(expected) + 1 - length))
                if not chunk:
                    break
                chunks.append(chunk)
                length += len(chunk)
            if b''.join(chunks) != expected or identity(os.fstat(fd)) != identity(before):
                raise CustodyError('macos-custody-replacement-source-changed')
            candidate = '.ods-replace-' + os.urandom(16).hex()
            out = os.open(candidate, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
                          0o600, dir_fd=directory)
            temporary = candidate
            try:
                os.fchown(out, 0, gid)
                os.fchmod(out, mode)
                _verify_fd(out, directory=False)
                with os.fdopen(os.dup(out), 'wb') as stream:
                    stream.write(replacement)
                    stream.flush()
                os.fsync(out)
            finally:
                os.close(out)
            current = os.stat(name, dir_fd=directory, follow_symlinks=False)
            if (identity(current) != identity(before) or identity(os.fstat(fd)) != identity(before)):
                raise CustodyError('macos-custody-replacement-source-changed')
            os.rename(temporary, name, src_dir_fd=directory, dst_dir_fd=directory)
            temporary = None
            os.fsync(directory)
        finally:
            os.close(fd)
            if temporary is not None:
                os.unlink(temporary, dir_fd=directory)


INSPECTION_ADDITIONS = frozenset('/usr/local/libexec/ods-pixel-services/helpers/' + name for name in (
    'preview_inspection.py', 'preview_inspection_protocol.py', 'workspace_preview.py',
    'unix_peer.py', 'preview-inspection.json'))


def protected_inspection_bytes(filename, *, limit=8 * 1024 * 1024):
    """Allow true absence only at the five fixed, journaled migration paths."""
    value = os.fspath(filename)
    try:
        return protected_bytes(filename, limit=limit)
    except CustodyError:
        if value not in INSPECTION_ADDITIONS:
            raise
        parent, name = value.rsplit('/', 1)
        with protected_directory(parent) as directory:
            try:
                os.stat(name, dir_fd=directory, follow_symlinks=False)
            except FileNotFoundError:
                return None
        raise


def replace_protected_inspection_bytes(filename, *, expected, replacement, mode, gid=0):
    """Create/remove only journaled inspection additions under the deployment lock.

    Existing-file replacements retain the original custody contract. An absent
    target is published by atomic rename only after rechecking absence in its
    root-protected parent; untrusted users cannot race this namespace. An fsync
    failure can follow a completed mutation, so recovery must inspect the bytes.
    """
    if expected is not None and replacement is not None:
        return replace_protected_bytes(filename, expected=expected, replacement=replacement, mode=mode, gid=gid)
    value = os.fspath(filename)
    body = replacement if expected is None else expected
    if (value not in INSPECTION_ADDITIONS or type(body) is not bytes or len(body) > 8 * 1024 * 1024
            or mode != 0o644 or gid != 0 or (expected is None and replacement is None)):
        raise CustodyError('macos-custody-inspection-addition-invalid')
    parent, name = value.rsplit('/', 1)
    identity = lambda s: (s.st_dev, s.st_ino, s.st_size, s.st_mtime_ns, s.st_ctime_ns)
    with protected_directory(parent) as directory:
        if replacement is None:
            fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=directory)
            try:
                before = _verify_fd(fd, directory=False)
                if stat.S_IMODE(before.st_mode) != mode or before.st_gid != gid:
                    raise CustodyError('macos-custody-replacement-metadata-changed')
                with os.fdopen(os.dup(fd), 'rb') as stream:
                    actual = stream.read(len(expected) + 1)
                current = os.stat(name, dir_fd=directory, follow_symlinks=False)
                if actual != expected or identity(before) != identity(current) or identity(before) != identity(os.fstat(fd)):
                    raise CustodyError('macos-custody-replacement-source-changed')
                os.unlink(name, dir_fd=directory)
                os.fsync(directory)
            finally:
                os.close(fd)
            return
        def absent():
            try:
                os.stat(name, dir_fd=directory, follow_symlinks=False)
            except FileNotFoundError:
                return
            raise CustodyError('macos-custody-replacement-source-changed')
        absent()
        temporary = '.ods-inspection-add-' + os.urandom(16).hex()
        out = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=directory)
        try:
            os.fchown(out, 0, gid)
            os.fchmod(out, mode)
            _verify_fd(out, directory=False)
            with os.fdopen(os.dup(out), 'wb') as stream:
                stream.write(replacement)
                stream.flush()
            os.fsync(out)
            absent()
            os.rename(temporary, name, src_dir_fd=directory, dst_dir_fd=directory)
            temporary = None
            os.fsync(directory)
        finally:
            os.close(out)
            if temporary is not None:
                os.unlink(temporary, dir_fd=directory)


def launchd_document_binding(filename, expected):
    """Pin a complete approved plist; never infer approval from its label alone.

    expected must come from the trusted deployment specification, not the
    candidate file. This does not prove executable/plugin/config file custody.
    """
    if not isinstance(expected, dict) or not expected:
        raise CustodyError('launchd-specification-required')
    body = protected_bytes(filename)
    try:
        document = plistlib.loads(body)
        # Canonical bytes also distinguish plist booleans from integer values.
        actual = plistlib.dumps(document, fmt=plistlib.FMT_BINARY, sort_keys=True)
        wanted = plistlib.dumps(expected, fmt=plistlib.FMT_BINARY, sort_keys=True)
    except (ValueError, TypeError, OverflowError, plistlib.InvalidFileException, ExpatError):
        raise CustodyError('launchd-document-invalid') from None
    if actual != wanted:
        raise CustodyError('launchd-document-changed')
    # Only installer-generated encodings are accepted, avoiding duplicate XML
    # keys or other parser ambiguities between plistlib and launchd.
    if body not in (wanted, plistlib.dumps(expected, sort_keys=True)):
        raise CustodyError('launchd-document-noncanonical')
    return {'schemaVersion': 1, 'path': os.fspath(filename),
            'sha256': hashlib.sha256(body).hexdigest()}