openlinktoken 2.0.0__py3-none-any.whl

openlinktoken/ec_key_utils.py

@@ -0,0 +1,207 @@
+# SPDX-License-Identifier: MIT
+"""
+Shared utilities for ECDH key management used by initiate-exchange and
+exchange-config consumers.
+
+Note: The exchange-config workflow is Python-CLI only. The Java counterpart
+(``EcKeyUtils.java``) is a placeholder stub that references this module.
+"""
+
+import logging
+import os
+import stat
+from datetime import date
+from pathlib import Path, PureWindowsPath
+from typing import Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+SUPPORTED_CURVES = ["P-256", "P-384", "P-521"]
+
+
+def get_curve_class(curve: str):
+    """Return the cryptography EC curve class for the named curve.
+
+    Args:
+        curve: One of ``P-256``, ``P-384``, or ``P-521``.
+
+    Returns:
+        An EC curve instance from ``cryptography.hazmat.primitives.asymmetric.ec``.
+
+    Raises:
+        ValueError: If the curve name is not supported.
+    """
+    from cryptography.hazmat.primitives.asymmetric.ec import SECP256R1, SECP384R1, SECP521R1
+
+    curve_map = {
+        "P-256": SECP256R1,
+        "P-384": SECP384R1,
+        "P-521": SECP521R1,
+    }
+
+    if curve not in curve_map:
+        raise ValueError(f"Unsupported curve '{curve}'. Valid options are: {', '.join(SUPPORTED_CURVES)}")
+
+    return curve_map[curve]()
+
+
+def resolve_key_name(name: Optional[str]) -> str:
+    """Resolve and validate the requested key basename.
+
+    Args:
+        name: Caller-supplied name, or ``None`` / empty to use the default.
+
+    Returns:
+        A validated simple file basename.
+
+    Raises:
+        ValueError: If the supplied name contains path separators, traversal components, or drive prefixes.
+    """
+    if not name or not name.strip():
+        return f"openlinktoken-{date.today().isoformat()}"
+
+    candidate = name.strip()
+    if (
+        candidate in {".", ".."}
+        or "/" in candidate
+        or "\\" in candidate
+        or ":" in candidate
+        or candidate != Path(candidate).name
+        or PureWindowsPath(candidate).drive
+    ):
+        raise ValueError(
+            "Key name must be a simple file basename without path separators, traversal, or drive prefixes."
+        )
+
+    return candidate
+
+
+def generate_key_pair(curve: str) -> Tuple[bytes, bytes]:
+    """Generate an EC key pair for the specified curve.
+
+    Args:
+        curve: One of ``P-256``, ``P-384``, or ``P-521``.
+
+    Returns:
+        A tuple of ``(private_pem, public_pem)`` as bytes.
+
+    Raises:
+        ValueError: If the curve name is unsupported.
+    """
+    from cryptography.hazmat.primitives.asymmetric.ec import generate_private_key
+    from cryptography.hazmat.primitives.serialization import Encoding, NoEncryption, PrivateFormat, PublicFormat
+
+    curve_instance = get_curve_class(curve)
+    private_key = generate_private_key(curve_instance)
+
+    private_pem = private_key.private_bytes(
+        encoding=Encoding.PEM,
+        format=PrivateFormat.PKCS8,
+        encryption_algorithm=NoEncryption(),
+    )
+    public_pem = private_key.public_key().public_bytes(
+        encoding=Encoding.PEM,
+        format=PublicFormat.SubjectPublicKeyInfo,
+    )
+
+    return private_pem, public_pem
+
+
+def _curve_name_from_private_key(private_key) -> str:
+    """Map a cryptography EC private key's curve to an Open Link Token curve name."""
+    curve_name_map = {
+        "secp256r1": "P-256",
+        "secp384r1": "P-384",
+        "secp521r1": "P-521",
+    }
+    curve_name = curve_name_map.get(private_key.curve.name)
+    if curve_name is None:
+        raise ValueError(f"Unsupported EC private key curve '{private_key.curve.name}'.")
+    return curve_name
+
+
+def derive_public_key_from_private_pem(private_pem: bytes) -> Tuple[bytes, str]:
+    """Load an EC private key PEM and return its public key PEM plus Open Link Token curve name."""
+    from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat, load_pem_private_key
+
+    private_key = load_pem_private_key(private_pem, password=None)
+    public_pem = private_key.public_key().public_bytes(
+        encoding=Encoding.PEM,
+        format=PublicFormat.SubjectPublicKeyInfo,
+    )
+    return public_pem, _curve_name_from_private_key(private_key)
+
+
+def ensure_directory(directory: Path) -> None:
+    """Ensure the directory exists, is not a symlink, and has 700 permissions.
+
+    Args:
+        directory: The directory path to create or validate.
+
+    Raises:
+        OSError: If the path is a symbolic link.
+        NotADirectoryError: If the path exists but is not a directory.
+    """
+    if not directory.exists():
+        directory.mkdir(parents=True, exist_ok=True)
+
+    if directory.is_symlink():
+        raise OSError(f"Key directory {directory} must not be a symbolic link.")
+
+    if not directory.is_dir():
+        raise NotADirectoryError(f"Key directory path {directory} exists and is not a directory.")
+
+    try:
+        os.chmod(directory, stat.S_IRWXU)
+    except (NotImplementedError, PermissionError) as error:
+        logger.warning("Could not set directory permissions on %s: %s", directory, error)
+
+
+def write_key(path: Path, pem_bytes: bytes, mode: int, overwrite: bool = True) -> None:
+    """Write PEM bytes to a file using secure creation flags and set the specified permissions.
+
+    Args:
+        path: The target file path.
+        pem_bytes: The PEM-encoded key bytes.
+        mode: Octal file permission mode (for example, ``0o600``).
+        overwrite: When false, require exclusive creation instead of truncating an existing file.
+
+    Raises:
+        OSError: If the path is a symbolic link.
+    """
+    if path.is_symlink():
+        raise OSError(f"Key file path {path} must not be a symbolic link.")
+
+    flags = os.O_WRONLY | os.O_CREAT
+    flags |= os.O_TRUNC if overwrite else os.O_EXCL
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+
+    file_descriptor = os.open(path, flags, mode)
+    try:
+        with os.fdopen(file_descriptor, "wb") as file_handle:
+            file_handle.write(pem_bytes)
+        os.chmod(path, mode)
+    except (NotImplementedError, PermissionError) as error:
+        logger.warning("Could not set file permissions on %s: %s", path, error)
+
+
+def public_key_fingerprint(public_pem: bytes) -> str:
+    """Compute a SHA-256 fingerprint of a SubjectPublicKeyInfo PEM public key."""
+    import hashlib
+
+    from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat, load_pem_public_key
+
+    key = load_pem_public_key(public_pem)
+    der = key.public_bytes(encoding=Encoding.DER, format=PublicFormat.SubjectPublicKeyInfo)
+    digest = hashlib.sha256(der).hexdigest().upper()
+    return ":".join(digest[index : index + 2] for index in range(0, len(digest), 2))
+
+
+def fingerprint_to_kid(fingerprint: str) -> str:
+    """Convert a SHA-256 public-key fingerprint into the portable JWE recipient id."""
+    normalized = fingerprint.strip()
+    if not normalized:
+        raise ValueError("Fingerprint must not be empty.")
+
+    return f"sha256:{normalized.lower().replace(':', '-')}"

openlinktoken/exchange_config.py

@@ -0,0 +1,305 @@
+# SPDX-License-Identifier: MIT
+"""
+Shared helpers for loading and consuming initiate-exchange config files.
+
+Note: The exchange-config workflow is Python-CLI only. The Java counterpart
+(``ExchangeConfig.java``) is a placeholder stub that references this module.
+"""
+
+import base64
+import json
+import os
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+from typing import Any, Mapping
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+from openlinktoken.ec_key_utils import derive_public_key_from_private_pem, public_key_fingerprint
+from openlinktoken.exchange_jwe import decrypt_exchange_envelope, resolve_private_key_by_kid
+
+SUPPORTED_EXCHANGE_CONFIG_VERSIONS = {1}
+TRANSPORT_KEY_INFO = b"openlinktoken:token-encryption:v1"
+
+
+@dataclass(frozen=True)
+class LoadedExchangeConfig:
+    """Validated exchange-config envelope loaded from disk."""
+
+    path: Path
+    version: int
+    config: Mapping[str, Any]
+
+
+@dataclass(frozen=True)
+class ResolvedExchangeConfig:
+    """Resolved exchange-config inputs for consumer commands."""
+
+    path: Path
+    version: int
+    config: Mapping[str, Any]
+    payload: Mapping[str, Any]
+    private_key_pem: bytes
+    private_key_role: str
+    hashing_secret: bytes
+
+
+def default_exchange_config_path() -> Path:
+    """Return the default date-based exchange-config path."""
+    return Path(f"./openlinktoken-{date.today().isoformat()}.exchange.json")
+
+
+def load_exchange_config(
+    exchange_config_path: str | Path | None = None,
+    exchange_config_value: str | bytes | Mapping[str, Any] | None = None,
+) -> LoadedExchangeConfig:
+    """Load and validate an exchange-config envelope from disk or an in-memory value."""
+    if exchange_config_path and exchange_config_value is not None:
+        raise ValueError("Cannot combine an exchange config path and a direct exchange config value.")
+
+    if exchange_config_value is not None:
+        config_path = Path("<provided exchange config>")
+        config = _parse_exchange_config_value(exchange_config_value)
+    else:
+        config_path = Path(exchange_config_path) if exchange_config_path else default_exchange_config_path()
+        if not config_path.exists():
+            raise FileNotFoundError(
+                f"Exchange config '{config_path}' was not found. "
+                "Provide --exchange-config or run 'olt initiate-exchange' to create it."
+            )
+        if not config_path.is_file():
+            raise OSError(f"Exchange config path '{config_path}' is not a readable file.")
+
+        try:
+            config = json.loads(config_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as error:
+            raise ValueError(f"Exchange config '{config_path}' is not valid JSON: {error}") from error
+
+    version = config.get("version")
+    if version not in SUPPORTED_EXCHANGE_CONFIG_VERSIONS:
+        supported_versions = ", ".join(str(item) for item in sorted(SUPPORTED_EXCHANGE_CONFIG_VERSIONS))
+        raise ValueError(f"Unsupported exchange config version '{version}'. Supported versions: {supported_versions}.")
+
+    return LoadedExchangeConfig(path=config_path, version=version, config=config)
+
+
+def resolve_exchange_config(
+    exchange_config_path: str | Path | None,
+    private_key_pem: bytes,
+) -> ResolvedExchangeConfig:
+    """Load, validate, and decrypt an exchange config using the provided private key PEM."""
+    return resolve_loaded_exchange_config(load_exchange_config(exchange_config_path), private_key_pem)
+
+
+def resolve_exchange_config_inputs(
+    exchange_config_path: str | Path | None = None,
+    private_key_path: str | Path | None = None,
+    private_key_env: str | None = None,
+    exchange_config_value: str | bytes | Mapping[str, Any] | None = None,
+    private_key_value: str | bytes | None = None,
+) -> ResolvedExchangeConfig:
+    """Resolve exchange-config inputs into decrypted exchange state."""
+    loaded_exchange = load_exchange_config(
+        exchange_config_path=exchange_config_path,
+        exchange_config_value=exchange_config_value,
+    )
+    private_key_pem = resolve_exchange_config_private_key(
+        loaded_exchange,
+        private_key_path=private_key_path,
+        private_key_env=private_key_env,
+        private_key_value=private_key_value,
+    )
+    return resolve_loaded_exchange_config(loaded_exchange, private_key_pem)
+
+
+def resolve_exchange_config_private_key(
+    exchange_config: LoadedExchangeConfig,
+    private_key_path: str | Path | None = None,
+    private_key_env: str | None = None,
+    private_key_value: str | bytes | None = None,
+    openlinktoken_dir: Path | None = None,
+    environment: Mapping[str, str] | None = None,
+) -> bytes:
+    """Resolve private-key PEM bytes for a loaded exchange config."""
+    provided_private_key_inputs = [
+        private_key_path is not None,
+        private_key_env is not None,
+        private_key_value is not None,
+    ]
+    if sum(provided_private_key_inputs) > 1:
+        raise ValueError("Cannot combine private key path, environment variable, and direct private key value inputs.")
+
+    if private_key_path:
+        return _read_private_key_path(private_key_path)
+
+    if private_key_env:
+        return _read_private_key_env(private_key_env, environment=environment)
+
+    if private_key_value is not None:
+        return _read_private_key_value(private_key_value)
+
+    resolved_openlinktoken_dir = openlinktoken_dir if openlinktoken_dir else Path.home() / ".openlinktoken"
+    for kid in _recipient_kids(exchange_config.config):
+        try:
+            return resolve_private_key_by_kid(resolved_openlinktoken_dir, kid)
+        except FileNotFoundError:
+            continue
+
+    raise FileNotFoundError(
+        f"No private key matching this exchange config was found in {resolved_openlinktoken_dir}. "
+        "Provide a private key path, environment variable, or direct value."
+    )
+
+
+def resolve_loaded_exchange_config(
+    exchange_config: LoadedExchangeConfig, private_key_pem: bytes
+) -> ResolvedExchangeConfig:
+    """Decrypt a validated exchange-config envelope using the provided private key PEM."""
+    try:
+        payload = json.loads(decrypt_exchange_envelope(exchange_config.config, private_key_pem))
+    except Exception as error:
+        raise ValueError(f"Failed to decrypt exchange config '{exchange_config.path}': {error}") from error
+
+    if not isinstance(payload, dict):
+        raise ValueError(f"Exchange config '{exchange_config.path}' decrypted to an invalid payload.")
+
+    return ResolvedExchangeConfig(
+        path=exchange_config.path,
+        version=exchange_config.version,
+        config=exchange_config.config,
+        payload=payload,
+        private_key_pem=private_key_pem,
+        private_key_role=_resolve_private_key_role(private_key_pem, payload),
+        hashing_secret=_decode_hashing_secret(payload),
+    )
+
+
+def derive_transport_encryption_key(exchange: ResolvedExchangeConfig) -> bytes:
+    """Derive the shared 32-byte transport key defined by the exchange config contract."""
+    sender_public_key = exchange.payload.get("senderPublicKey")
+    recipient_public_key = exchange.payload.get("recipientPublicKey")
+    exchange_id = exchange.payload.get("exchangeId")
+    if not sender_public_key or not recipient_public_key:
+        raise ValueError(
+            "This exchange config does not include the public keys required for token encryption/decryption. "
+            "Regenerate it with 'olt initiate-exchange'."
+        )
+    if not exchange_id:
+        raise ValueError("Exchange config payload is missing exchangeId required for key derivation.")
+
+    other_public_key_pem = recipient_public_key if exchange.private_key_role == "sender" else sender_public_key
+
+    try:
+        private_key = serialization.load_pem_private_key(exchange.private_key_pem, password=None)
+        public_key = serialization.load_pem_public_key(other_public_key_pem.encode("utf-8"))
+        shared_secret = private_key.exchange(ec.ECDH(), public_key)
+        return HKDF(
+            algorithm=hashes.SHA256(),
+            length=32,
+            salt=exchange_id.encode("utf-8"),
+            info=TRANSPORT_KEY_INFO,
+        ).derive(shared_secret)
+    except Exception as error:
+        raise ValueError(f"Failed to derive the transport encryption key: {error}") from error
+
+
+def _read_private_key_path(private_key_path: str | Path) -> bytes:
+    """Read private-key PEM bytes from disk."""
+    path = Path(private_key_path)
+    if not path.exists():
+        raise FileNotFoundError(f"Private key file not found: {path}")
+    if not path.is_file():
+        raise OSError(f"Private key path '{path}' is not a readable file.")
+    return path.read_bytes()
+
+
+def _read_private_key_env(
+    private_key_env: str,
+    environment: Mapping[str, str] | None = None,
+) -> bytes:
+    """Read private-key PEM bytes from a named environment variable."""
+    resolved_environment = os.environ if environment is None else environment
+    value = resolved_environment.get(private_key_env)
+    if value is None or not value.strip():
+        raise ValueError(f"Environment variable {private_key_env} does not contain non-empty private key data.")
+    return value.encode("utf-8")
+
+
+def _read_private_key_value(private_key_value: str | bytes) -> bytes:
+    """Read private-key PEM bytes from a direct in-memory value."""
+    if isinstance(private_key_value, bytes):
+        if not private_key_value.strip():
+            raise ValueError("Direct private key value does not contain non-empty private key data.")
+        return private_key_value
+
+    if not private_key_value.strip():
+        raise ValueError("Direct private key value does not contain non-empty private key data.")
+    return private_key_value.encode("utf-8")
+
+
+def _parse_exchange_config_value(exchange_config_value: str | bytes | Mapping[str, Any]) -> Mapping[str, Any]:
+    """Parse an in-memory exchange-config payload."""
+    if isinstance(exchange_config_value, Mapping):
+        return dict(exchange_config_value)
+
+    try:
+        raw_value = (
+            exchange_config_value.decode("utf-8") if isinstance(exchange_config_value, bytes) else exchange_config_value
+        )
+        parsed_value = json.loads(raw_value)
+    except UnicodeDecodeError as error:
+        raise ValueError(f"Provided exchange config value is not valid UTF-8 JSON: {error}") from error
+    except json.JSONDecodeError as error:
+        raise ValueError(f"Provided exchange config value is not valid JSON: {error}") from error
+
+    if not isinstance(parsed_value, dict):
+        raise ValueError("Provided exchange config value must decode to a JSON object.")
+
+    return parsed_value
+
+
+def _recipient_kids(exchange_config: Mapping[str, Any]) -> list[str]:
+    """Extract recipient key identifiers from an exchange-config envelope."""
+    recipients = exchange_config.get("recipients")
+    if not isinstance(recipients, list) or not recipients:
+        raise ValueError("Exchange config is missing recipient entries needed for private-key resolution.")
+
+    kids: list[str] = []
+    for recipient in recipients:
+        if not isinstance(recipient, dict):
+            continue
+        header = recipient.get("header")
+        if isinstance(header, dict) and header.get("kid"):
+            kids.append(header["kid"])
+
+    if not kids:
+        raise ValueError("Exchange config recipients do not include key identifiers for private-key resolution.")
+    return kids
+
+
+def _resolve_private_key_role(private_pem: bytes, payload: Mapping[str, Any]) -> str:
+    public_pem, _ = derive_public_key_from_private_pem(private_pem)
+    fingerprint = public_key_fingerprint(public_pem)
+    if fingerprint == payload.get("senderKeyFingerprint"):
+        return "sender"
+    if fingerprint == payload.get("recipientKeyFingerprint"):
+        return "recipient"
+    raise ValueError("Resolved private key does not match the sender or recipient fingerprint in the exchange config.")
+
+
+def _decode_hashing_secret(payload: Mapping[str, Any]) -> bytes:
+    encoding = payload.get("hashingSecretEncoding")
+    value = payload.get("hashingSecret")
+    if encoding != "base64url":
+        raise ValueError(f"Unsupported hashingSecretEncoding '{encoding}'.")
+    if not isinstance(value, str) or not value:
+        raise ValueError("Exchange config payload is missing hashingSecret.")
+
+    padding = "=" * (-len(value) % 4)
+    try:
+        return base64.urlsafe_b64decode(value + padding)
+    except Exception as error:
+        raise ValueError(f"hashingSecret is not valid base64url data: {error}") from error

openlinktoken/exchange_jwe.py

@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: MIT
+"""
+Shared helpers for building and decrypting exchange-config JWE envelopes.
+
+Note: The exchange-config workflow is Python-CLI only. The Java counterpart
+(``ExchangeJwe.java``) is a placeholder stub that references this module.
+"""
+
+import base64
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+from jwcrypto import jwe, jwk
+
+from openlinktoken.ec_key_utils import fingerprint_to_kid, public_key_fingerprint
+
+EXCHANGE_JWE_VERSION = 1
+EXCHANGE_JWE_TYPE = "openlinktoken-exchange+jwe"
+EXCHANGE_JWE_CONTENT_TYPE = "application/openlinktoken-exchange+json"
+EXCHANGE_JWE_ENCRYPTION = "A256GCM"
+EXCHANGE_JWE_RECIPIENT_ALGORITHM = "ECDH-ES+A256KW"
+
+
+def build_exchange_envelope(
+    exchange_name: str,
+    hashing_secret: bytes,
+    sender_public_pem: bytes,
+    recipient_public_pem: bytes,
+    curve: str,
+    created_at: str,
+    exchange_id: str,
+) -> dict[str, Any]:
+    """Build a multi-recipient JWE exchange envelope."""
+    payload = {
+        "exchangeName": exchange_name,
+        "hashingSecret": _base64url_encode(hashing_secret),
+        "hashingSecretEncoding": "base64url",
+        "senderKeyFingerprint": public_key_fingerprint(sender_public_pem),
+        "recipientKeyFingerprint": public_key_fingerprint(recipient_public_pem),
+        "senderPublicKey": sender_public_pem.decode("utf-8"),
+        "recipientPublicKey": recipient_public_pem.decode("utf-8"),
+        "curve": curve,
+        "createdAt": created_at,
+        "exchangeId": exchange_id,
+    }
+    protected_header = {
+        "typ": EXCHANGE_JWE_TYPE,
+        "cty": EXCHANGE_JWE_CONTENT_TYPE,
+        "enc": EXCHANGE_JWE_ENCRYPTION,
+    }
+
+    envelope = jwe.JWE(
+        json.dumps(payload, separators=(",", ":")).encode("utf-8"),
+        protected=json.dumps(protected_header, separators=(",", ":")),
+    )
+    envelope.add_recipient(
+        jwk.JWK.from_pem(sender_public_pem),
+        header=json.dumps(_recipient_header(sender_public_pem), separators=(",", ":")),
+    )
+    envelope.add_recipient(
+        jwk.JWK.from_pem(recipient_public_pem),
+        header=json.dumps(_recipient_header(recipient_public_pem), separators=(",", ":")),
+    )
+
+    serialized = json.loads(envelope.serialize(compact=False))
+    serialized["version"] = EXCHANGE_JWE_VERSION
+    return serialized
+
+
+def decrypt_exchange_envelope(exchange_config: Mapping[str, Any], private_pem: bytes) -> bytes:
+    """Decrypt an exchange JWE envelope with a matching private key PEM."""
+    envelope = jwe.JWE()
+    envelope.deserialize(json.dumps(dict(exchange_config)))
+    envelope.decrypt(jwk.JWK.from_pem(private_pem))
+    return bytes(envelope.payload)
+
+
+def resolve_private_key_by_kid(openlinktoken_dir: Path, kid: str) -> bytes:
+    """Resolve a private key by matching a fingerprint-derived recipient ``kid``."""
+    for public_key_path in sorted(openlinktoken_dir.glob("*.public.pem")):
+        public_pem = public_key_path.read_bytes()
+        if fingerprint_to_kid(public_key_fingerprint(public_pem)) != kid:
+            continue
+
+        basename = public_key_path.name[: -len(".public.pem")]
+        private_key_path = public_key_path.with_name(f"{basename}.private.pem")
+        if not private_key_path.exists():
+            raise FileNotFoundError(
+                f"Resolved recipient kid '{kid}' to {public_key_path}, but {private_key_path} does not exist."
+            )
+        return private_key_path.read_bytes()
+
+    raise FileNotFoundError(f"No private key found for recipient kid '{kid}' in {openlinktoken_dir}.")
+
+
+def _base64url_encode(value: bytes) -> str:
+    """Encode bytes as unpadded base64url text."""
+    return base64.urlsafe_b64encode(value).decode("utf-8").rstrip("=")
+
+
+def _recipient_header(public_pem: bytes) -> dict[str, str]:
+    """Build the per-recipient JOSE header for the provided public key."""
+    return {
+        "alg": EXCHANGE_JWE_RECIPIENT_ALGORITHM,
+        "kid": fingerprint_to_kid(public_key_fingerprint(public_pem)),
+    }