Developer SDK

Python examples

Install the SDK · View source on GitHub ↗

provider/state.py

python
"""Installation state for one provider install, kept in one private directory
named by URNETWORK_PROVIDER_STATE_DIR (PROVIDER_CONTRACT.md, "Installation
state"):

- client.jwt: the scoped client credential that the developer's backend issued
  for this installation. The developer writes it; the app rewrites it whenever
  the SDK refreshes the token.
- instance-id: this installation's UUID, created on first run.
- identity.json: the provider identity (client key seed, provide TLS
  certificate and key, extender seed), created on first run so the provider
  keeps one identity across restarts.

Every file is replaced atomically with owner-only permissions, and a symlinked
file is refused. On POSIX the directory and its files must not be accessible to
group or others; Windows relies on the access control of the user's profile
directory. Pure Python: the self-test runs it without the native SDK."""

import base64
from dataclasses import dataclass
import json
import os
import re
import secrets
import stat
import uuid

CLIENT_JWT_FILE_NAME = "client.jwt"
INSTANCE_ID_FILE_NAME = "instance-id"
IDENTITY_FILE_NAME = "identity.json"

# the largest state file the app reads
STATE_FILE_BYTE_LIMIT = 64 * 1024

PROVIDER_IDENTITY_VERSION = 1

# a uuid in its canonical 8-4-4-4-12 form, or as 32 hex digits
UUID_PATTERN = re.compile(r"\A(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[0-9a-fA-F]{32})\Z")

# unpadded base64url, the encoding of a JWT segment
BASE64URL_PATTERN = re.compile(r"\A[A-Za-z0-9_-]*\Z")

POSIX = os.name != "nt"


class ConfigError(Exception):
    """A configuration or credential problem that restarting does not fix (exit 78)."""


class StateFileError(Exception):
    """A state file that the app must not read: not a regular file, too large or
    accessible to others."""


@dataclass(frozen=True)
class ProviderIdentity:
    """identity.json. Byte fields are standard base64 in JSON. An identity belongs
    to one client: a newly provisioned client gets a new identity."""

    client_id: str
    client_key_seed: bytes
    provide_tls_certificate_pem: bytes
    provide_tls_private_key_pem: bytes
    extender_key_seed: bytes = b""


@dataclass(frozen=True)
class ProviderKeyMaterial:
    """The byte fields of the SDK's device key material: the client key seed, the
    provide TLS certificate and key in the order urnet_new_device_local_key_material
    takes them, and the extender seed for urnet_device_local_key_material_set_extender_key_seed."""

    client_key_seed: bytes
    provide_tls_certificate_pem: bytes
    provide_tls_private_key_pem: bytes
    extender_key_seed: bytes


@dataclass(frozen=True)
class ProviderConfig:
    """The installation state loaded at start."""

    state_dir: str
    client_jwt: str
    # the client_id claim of client_jwt
    client_id: str
    instance_id: str
    # None on first run, and when the stored identity belongs to another client
    identity: ProviderIdentity | None


def load_provider_config(state_dir: str) -> ProviderConfig:
    """Loads the installation state, creating instance-id on first run. Every error
    is a ConfigError: restarting does not fix it."""
    check_state_dir(state_dir)
    try:
        client_jwt_bytes = read_private_file(os.path.join(state_dir, CLIENT_JWT_FILE_NAME))
    except (OSError, StateFileError) as error:
        raise ConfigError(f"read {CLIENT_JWT_FILE_NAME} from the state directory: {error}") from None
    client_jwt = client_jwt_bytes.decode("utf-8", errors="replace").strip()
    client_id = parse_client_jwt_client_id(client_jwt)
    instance_id = load_or_create_instance_id(state_dir)
    identity = load_provider_identity(state_dir, client_id)
    return ProviderConfig(
        state_dir=state_dir,
        client_jwt=client_jwt,
        client_id=client_id,
        instance_id=instance_id,
        identity=identity,
    )


def check_state_dir(state_dir: str):
    """The state directory must be an existing absolute directory, private to its
    owner on POSIX."""
    if not state_dir:
        raise ConfigError("set URNETWORK_PROVIDER_STATE_DIR to this installation's private state directory")
    if not os.path.isabs(state_dir):
        raise ConfigError("URNETWORK_PROVIDER_STATE_DIR must be an absolute path")
    try:
        info = os.stat(state_dir)
    except OSError as error:
        raise ConfigError(f"state directory: {error}") from None
    if not stat.S_ISDIR(info.st_mode):
        raise ConfigError("URNETWORK_PROVIDER_STATE_DIR is not a directory")
    if POSIX and info.st_mode & 0o077:
        raise ConfigError("the state directory must be private to its owner (chmod 700)")


def read_private_file(path: str) -> bytes:
    """Reads a regular, private state file of bounded size. A symlink is refused so
    that the credential cannot be redirected to another file. Raises
    FileNotFoundError when the file does not exist."""
    info = os.lstat(path)
    if not stat.S_ISREG(info.st_mode):
        raise StateFileError("not a regular file")
    if STATE_FILE_BYTE_LIMIT < info.st_size:
        raise StateFileError("file is too large")
    if POSIX and info.st_mode & 0o077:
        raise StateFileError("file must be private to its owner (chmod 600)")
    # no-follow closes the window between the check and the open where POSIX has it
    fd = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0))
    with os.fdopen(fd, "rb") as file:
        data = file.read(STATE_FILE_BYTE_LIMIT + 1)
    if STATE_FILE_BYTE_LIMIT < len(data):
        raise StateFileError("file is too large")
    return data


def write_private_file(path: str, data: bytes):
    """Replaces a state file atomically: a private temporary file in the same
    directory is written, synced and renamed over the old file."""
    temp_path = os.path.join(os.path.dirname(path), f".{os.path.basename(path)}.{secrets.token_hex(8)}")
    fd = os.open(temp_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0), 0o600)
    try:
        with os.fdopen(fd, "wb") as file:
            if POSIX:
                # the umask can only narrow 0o600; this keeps it exact
                os.fchmod(file.fileno(), 0o600)
            file.write(data)
            file.flush()
            os.fsync(file.fileno())
        os.replace(temp_path, path)
    except BaseException:
        try:
            os.remove(temp_path)
        except OSError:
            pass
        raise


def parse_uuid(text: str) -> str | None:
    """The canonical lowercase form of a UUID, or None when text is not one."""
    if not isinstance(text, str) or not UUID_PATTERN.match(text):
        return None
    return str(uuid.UUID(hex=text))


def parse_client_jwt_client_id(client_jwt: str) -> str:
    """The client_id claim of a scoped client JWT. This checks the token's shape and
    claim only; the SDK and the server verify the token itself."""
    not_jwt = ConfigError("client.jwt does not hold a JWT; write the scoped client JWT from your backend")
    parts = client_jwt.split(".")
    if len(parts) != 3 or not all(parts):
        raise not_jwt
    payload_text = parts[1].rstrip("=")
    if not BASE64URL_PATTERN.match(payload_text) or len(payload_text) % 4 == 1:
        raise not_jwt
    payload = base64.urlsafe_b64decode(payload_text + "=" * (-len(payload_text) % 4))
    try:
        claims = json.loads(payload)
    except ValueError:
        claims = None
    if not isinstance(claims, dict) or not isinstance(claims.get("client_id"), str) or not claims["client_id"]:
        raise ConfigError("client.jwt has no client_id claim; write a scoped client JWT, not a network JWT")
    client_id = parse_uuid(claims["client_id"])
    if client_id is None:
        raise ConfigError("client.jwt has an invalid client_id claim")
    return client_id


def load_or_create_instance_id(state_dir: str) -> str:
    """Reads instance-id, creating it on first run. An installation keeps one
    instance id for its lifetime."""
    path = os.path.join(state_dir, INSTANCE_ID_FILE_NAME)
    try:
        data = read_private_file(path)
    except FileNotFoundError:
        data = None
    except (OSError, StateFileError) as error:
        raise ConfigError(f"read {INSTANCE_ID_FILE_NAME} from the state directory: {error}") from None
    if data is not None:
        instance_id = parse_uuid(data.decode("utf-8", errors="replace").strip())
        if instance_id is None:
            raise ConfigError(f"{INSTANCE_ID_FILE_NAME} does not hold a UUID")
        return instance_id
    instance_id = str(uuid.uuid4())
    try:
        write_private_file(path, (instance_id + "\n").encode())
    except OSError as error:
        raise ConfigError(f"write {INSTANCE_ID_FILE_NAME}: {error}") from None
    return instance_id


def load_provider_identity(state_dir: str, client_id: str) -> ProviderIdentity | None:
    """Reads identity.json for client_id. A missing file, or an identity of another
    client, returns None: the device then creates a new identity, which the app
    saves."""
    try:
        data = read_private_file(os.path.join(state_dir, IDENTITY_FILE_NAME))
    except FileNotFoundError:
        return None
    except (OSError, StateFileError) as error:
        raise ConfigError(f"read {IDENTITY_FILE_NAME} from the state directory: {error}") from None
    identity = parse_provider_identity(data)
    if identity is None:
        raise ConfigError(f"{IDENTITY_FILE_NAME} is not a valid provider identity; remove it to create a new one")
    if identity.client_id != client_id:
        return None
    return identity


def parse_provider_identity(data: bytes) -> ProviderIdentity | None:
    """The identity in identity.json, or None when the file does not parse, has
    another version or a client key seed that is not 32 bytes."""

    def decode_bytes(value) -> bytes | None:
        # json null and a missing field are empty, as in the go reference
        if value is None:
            return b""
        if not isinstance(value, str):
            return None
        try:
            return base64.b64decode(value, validate=True)
        except ValueError:
            return None

    try:
        fields = json.loads(data)
    except ValueError:
        return None
    if not isinstance(fields, dict):
        return None
    version = fields.get("version")
    if not isinstance(version, int) or isinstance(version, bool) or version != PROVIDER_IDENTITY_VERSION:
        return None
    # a null client id names no client, as in the go reference
    client_id = fields.get("client_id")
    if client_id is None:
        client_id = ""
    if not isinstance(client_id, str):
        return None
    byte_fields = [
        decode_bytes(fields.get(name))
        for name in (
            "client_key_seed",
            "provide_tls_certificate_pem",
            "provide_tls_private_key_pem",
            "extender_key_seed",
        )
    ]
    if any(value is None for value in byte_fields) or len(byte_fields[0]) != 32:
        return None
    return ProviderIdentity(
        client_id=client_id,
        client_key_seed=byte_fields[0],
        provide_tls_certificate_pem=byte_fields[1],
        provide_tls_private_key_pem=byte_fields[2],
        extender_key_seed=byte_fields[3],
    )


def save_provider_identity(state_dir: str, identity: ProviderIdentity):
    """Writes identity.json."""

    def encode_bytes(value: bytes) -> str:
        return base64.b64encode(value).decode("ascii")

    fields = {
        "version": PROVIDER_IDENTITY_VERSION,
        "client_id": identity.client_id,
        "client_key_seed": encode_bytes(identity.client_key_seed),
        "provide_tls_certificate_pem": encode_bytes(identity.provide_tls_certificate_pem),
        "provide_tls_private_key_pem": encode_bytes(identity.provide_tls_private_key_pem),
    }
    if identity.extender_key_seed:
        fields["extender_key_seed"] = encode_bytes(identity.extender_key_seed)
    write_private_file(
        os.path.join(state_dir, IDENTITY_FILE_NAME),
        json.dumps(fields, separators=(",", ":")).encode(),
    )


def provider_key_material(identity: ProviderIdentity | None) -> ProviderKeyMaterial | None:
    """The key material that recreates the device's identity. None without an
    identity (the first run, or another client's identity): the device then
    makes a new identity, which the app saves."""
    if identity is None:
        return None
    return ProviderKeyMaterial(
        client_key_seed=identity.client_key_seed,
        provide_tls_certificate_pem=identity.provide_tls_certificate_pem,
        provide_tls_private_key_pem=identity.provide_tls_private_key_pem,
        extender_key_seed=identity.extender_key_seed,
    )