celerp 2.3.6__tar.gz → 2.4.0__tar.gz

{celerp-2.3.6 → celerp-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: celerp
-Version: 2.3.6
+Version: 2.4.0
 Summary: Free, self-hosted ERP for small businesses
 License: Business Source License 1.1
         

{celerp-2.3.6 → celerp-2.4.0}/celerp/config.py

@@ -42,6 +42,26 @@ class Settings(BaseSettings):
     # No `[gateway_token]` means no gateway connection, no product telemetry, and
     # no cloud dependency, except a startup subscription check.
     gateway_token: str = ""
+    # Reusable partner deployment credential. A one-time registration input sent
+    # only on the first relay `hello` of a partner-provisioned install, distinct
+    # from the live-session gateway_token: it associates the instance with the
+    # partner and is removed from bootstrap state once the relay accepts it.
+    # Env CELERP_DEPLOYMENT_CREDENTIAL or [cloud] deployment_credential.
+    deployment_credential: str = Field(
+        default="",
+        validation_alias=AliasChoices("CELERP_DEPLOYMENT_CREDENTIAL", "deployment_credential"),
+    )
+    # True once the relay has accepted the deployment credential and associated
+    # this instance. Suppresses any re-send of the credential (an env-sourced
+    # credential cannot be erased from the environment). Persisted as
+    # [cloud] deployment_associated.
+    deployment_associated: bool = False
+    # Idempotency nonce for the partner deployment association. Generated once,
+    # persisted before the first associate call, and reused on every retry and
+    # restart so a lost response cannot create a duplicate association: the relay
+    # keys the relationship on (partner, nonce). Dropped once consumed on a
+    # successful association. Persisted as [cloud] deployment_nonce.
+    deployment_nonce: str = ""
     # True after an explicit Cloud disconnect: the startup probe must not
     # re-link the install. Cleared when the user reconnects (settings or a
     # sign-in flow applies a fresh token). Persisted as [cloud] disconnected.
@@ -67,6 +87,19 @@ class Settings(BaseSettings):
     storage_s3_bucket: str = ""
     storage_s3_access_key: str = ""
     storage_s3_secret_key: str = ""
+    # Self-hosted only: the operator declares that this install runs on a
+    # customer-owned external database covered by the Team subscription. Default
+    # off; set true via EXTERNAL_DB / [cloud] external_db. It gates Team-infra
+    # visibility and the post-lapse "restore backup" recovery UI, so it is an
+    # explicit, durable opt-in and is never inferred from database_url (every
+    # ordinary self-hosted install points database_url at its own Postgres, which
+    # is not the same as opting into customer-owned Team infrastructure).
+    # Packaged builds detect the external database from celerp-config.json instead
+    # and never read this field.
+    external_db: bool = Field(
+        default=False,
+        validation_alias=AliasChoices("EXTERNAL_DB", "external_db"),
+    )
     # Data directory for runtime artifacts (uploads, caches).
     # Accepts CELERP_DATA_DIR (Electron) or DATA_DIR (legacy). Defaults to ./data.
     data_dir: Path = Field(
@@ -152,6 +185,51 @@ def persist_cloud_settings(**values: str) -> None:
     write_config(cfg)
 
 
+def ensure_deployment_nonce() -> str:
+    """Return the deployment association nonce, generating and persisting one when
+    absent.
+
+    The nonce must be persisted before the association call so a lost response
+    plus a retry reuses the same value and resolves to the same association
+    (idempotency keyed on partner + nonce). A persist failure propagates so the
+    caller can abort before any network call rather than send an unpersisted
+    nonce that a later boot could not reproduce.
+    """
+    if settings.deployment_nonce:
+        return settings.deployment_nonce
+    import uuid as _uuid
+    nonce = _uuid.uuid4().hex
+    settings.deployment_nonce = nonce
+    persist_cloud_settings(deployment_nonce=nonce)
+    return nonce
+
+
+def record_deployment_association(gateway_token: str, instance_id: str) -> None:
+    """Record a successful partner deployment association durably in one write.
+
+    Persists the relay-issued gateway_token and instance_id, sets the sticky
+    deployment_associated marker, and removes the now-consumed deployment
+    credential and nonce from [cloud]. persist_cloud_settings never erases a key,
+    so this dedicated helper is what drops them. The disk write precedes the
+    in-memory updates: if the write raises, the caller sees the failure and no
+    live-but-unpersisted identity is carried, so the next boot's idempotent retry
+    can recover.
+    """
+    cfg = read_config()
+    cloud = cfg.setdefault("cloud", {})
+    cloud["token"] = gateway_token
+    cloud["instance_id"] = instance_id
+    cloud["deployment_associated"] = True
+    cloud.pop("deployment_credential", None)
+    cloud.pop("deployment_nonce", None)
+    write_config(cfg)
+    settings.gateway_token = gateway_token
+    settings.gateway_instance_id = instance_id
+    settings.deployment_credential = ""
+    settings.deployment_nonce = ""
+    settings.deployment_associated = True
+
+
 def load_cloud_config() -> None:
     """Load cloud settings from config.toml into the Settings object.
 
@@ -190,6 +268,21 @@ def load_cloud_config() -> None:
         settings.celerp_public_url = cloud["public_url"]
     if cloud.get("backup_encryption_key") and not settings.backup_encryption_key:
         settings.backup_encryption_key = cloud["backup_encryption_key"]
+    # Deployment credential + association marker. The credential is only consumed
+    # on the first hello, so a config value loads unless env already supplied one;
+    # the marker is sticky (an associated install must never re-offer it).
+    if cloud.get("deployment_credential") and not settings.deployment_credential:
+        settings.deployment_credential = cloud["deployment_credential"]
+    if cloud.get("deployment_associated"):
+        settings.deployment_associated = True
+    # The association nonce is reused across boots: reload it so a retry after a
+    # lost response resolves to the same association rather than minting a new one.
+    if cloud.get("deployment_nonce") and not settings.deployment_nonce:
+        settings.deployment_nonce = cloud["deployment_nonce"]
+    # Self-hosted external-database opt-in. Durable [cloud] key so the operator's
+    # declaration survives restarts; loads unless the environment already set it.
+    if cloud.get("external_db") and not settings.external_db:
+        settings.external_db = True
     # Auto-enable secure cookies when relay-connected (HTTPS via Caddy/Cloudflare)
     if settings.gateway_token and not os.environ.get("COOKIE_SECURE"):
         settings.cookie_secure = True
@@ -313,6 +406,32 @@ def write_config(cfg: dict) -> None:
         # before this shipped), matching the embedded/headless idiom.
         if cloud.get("disconnected"):
             lines.append("disconnected = true")
+        # Self-hosted last-known-good commercial context, compact JSON of the
+        # already-validated envelope, so a partner-managed install presents its
+        # partner identity across an offline restart instead of defaulting to
+        # celerp_direct. Emitted only when set (a direct install that has never
+        # cached one carries no key); serialised through the JSON string encoder
+        # so embedded quotes survive the TOML round-trip.
+        if cloud.get("commercial_context_json"):
+            import json as _json
+            lines.append(
+                f"commercial_context_json = {_json.dumps(cloud['commercial_context_json'])}")
+        # Deployment credential survives every [cloud] write until the relay
+        # accepts it: emitted only while non-empty, and the association marker
+        # only once set. A direct install carries neither key. Without this, the
+        # fixed-key serializer would drop the credential before the first hello.
+        if cloud.get("deployment_credential"):
+            lines.append(f'deployment_credential = {_str(cloud["deployment_credential"])}')
+        # The association nonce persists across boots until an association
+        # consumes it, so a retry reuses it; emitted only while set.
+        if cloud.get("deployment_nonce"):
+            lines.append(f'deployment_nonce = {_str(cloud["deployment_nonce"])}')
+        if cloud.get("deployment_associated"):
+            lines.append("deployment_associated = true")
+        # Self-hosted external-database opt-in, emitted only when set. A direct
+        # local install carries no key and reads as off.
+        if cloud.get("external_db"):
+            lines.append("external_db = true")
         lines.append("")
 
     if "storage" in cfg:

celerp-2.4.0/celerp/config_store.py

@@ -0,0 +1,203 @@
+# Copyright (c) 2026 Noah Severs
+# SPDX-License-Identifier: BUSL-1.1
+
+"""Atomic reads and writes for Electron's packaged celerp-config.json.
+
+A single writer that merges any number of top-level keys into the packaged
+config in one atomic operation, so a save that touches several related keys
+(a database URL plus its backup, a storage backend plus its credentials)
+never leaves the file with only some of them applied. Callers outside this
+module never open or replace celerp-config.json directly.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+import uuid
+
+log = logging.getLogger(__name__)
+
+# Cross-process lock protocol for celerp-config.json, identical on both writers
+# (this module and electron/config-writer.js): the lock is an O_EXCL-created
+# sidecar file `celerp-config.json.lock`. A writer acquires by exclusive create,
+# writing a unique owner token as the whole file body, retrying every
+# _LOCK_RETRY_S for up to _LOCK_BUDGET_S; a lock whose mtime has aged past
+# _LOCK_STALE_S is presumed abandoned. Both unlink sites are token-verified:
+# a writer removes the lock only while the file still holds the token it wrote,
+# so a stale-takeover cannot delete a faster successor's lock and a superseded
+# owner's release becomes a no-op. Exactly one writer is elected. The token is
+# read for control, so it must be written and re-read as the exact file body.
+#
+# Honest residual: a path-based read-then-unlink is not atomic, so a sub-operation
+# TOCTOU window remains between the token re-read and the unlink. It is bounded by
+# _LOCK_STALE_S (a takeover requires a >10s stall) and is far narrower than an
+# unconditional unlink.
+_LOCK_BUDGET_S = 5.0
+_LOCK_RETRY_S = 0.05
+_LOCK_STALE_S = 10.0
+
+
+def _lock_token() -> bytes:
+    """A unique owner token for one lock acquisition: pid plus a random suffix,
+    so two acquisitions (even in the same process) never collide."""
+    return f"{os.getpid()} {uuid.uuid4().hex}".encode()
+
+
+def _read_lock_token(lock_path: str) -> bytes | None:
+    """Return the current lock file body, or None when it cannot be read."""
+    try:
+        with open(lock_path, "rb") as f:
+            return f.read()
+    except OSError:
+        return None
+
+
+def _acquire_lock(lock_path: str):
+    """Acquire the config lock by exclusive create, returning (fd, token), or
+    None when the budget expires while another writer holds it. The token is the
+    exact bytes written into the lock; the caller passes it to _release_lock so
+    only the electing writer ever removes this lock."""
+    deadline = time.monotonic() + _LOCK_BUDGET_S
+    while True:
+        try:
+            fd = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+            token = _lock_token()
+            os.write(fd, token)
+            os.fsync(fd)
+            return fd, token
+        except FileExistsError:
+            try:
+                age = time.time() - os.path.getmtime(lock_path)
+            except OSError:
+                age = 0.0
+            if age > _LOCK_STALE_S:
+                # Abandoned lock: re-read the token immediately before removing
+                # and unlink only that same stale token, so a faster successor
+                # that already replaced the lock is never deleted. Then loop
+                # back to the exclusive create, which stays the only way to win.
+                stale_token = _read_lock_token(lock_path)
+                if stale_token is not None:
+                    try:
+                        if _read_lock_token(lock_path) == stale_token:
+                            os.unlink(lock_path)
+                    except OSError:
+                        pass
+                continue
+            if time.monotonic() >= deadline:
+                return None
+            time.sleep(_LOCK_RETRY_S)
+
+
+def _release_lock(fd: int, lock_path: str, token: bytes) -> None:
+    """Close the lock fd and unlink the lock file only while it still holds this
+    owner's token; a lock a stale takeover already replaced is left untouched."""
+    try:
+        os.close(fd)
+    except OSError:
+        pass
+    try:
+        if _read_lock_token(lock_path) == token:
+            os.unlink(lock_path)
+    except OSError:
+        pass
+
+
+def _fsync_dir(dir_path: str) -> None:
+    """Fsync the directory so a preceding atomic rename is durable, not only the
+    renamed file's contents. A crash after os.replace but before the directory
+    entry reaches disk could otherwise lose the rename. No-op on platforms that
+    cannot fsync a directory fd (Windows), and any OSError is swallowed because
+    the rename itself already committed the write."""
+    if os.name != "posix":
+        return
+    try:
+        dir_fd = os.open(dir_path, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
+    except OSError:
+        return
+    try:
+        os.fsync(dir_fd)
+    except OSError:
+        pass
+    finally:
+        try:
+            os.close(dir_fd)
+        except OSError:
+            pass
+
+
+def merge_packaged_config(updates: dict) -> bool:
+    """Merge every key in `updates` into Electron's celerp-config.json in one
+    atomic write, forcing mode 0600 so the co-resident secrets (external_db_url,
+    S3 keys) are never broadened. Returns True when the updates were persisted,
+    False when they could not be (no packaged data dir, the lock could not be
+    acquired within its budget, or a write error).
+
+    A no-op returning False in dev/server mode where CELERP_DATA_DIR is unset.
+    The whole read-merge-write runs under the cross-process lock so a concurrent
+    Electron writer never races: the existing config is re-read inside the lock,
+    every key is merged, the result is written to a unique temp file created
+    0600, fsync'd, then os.replace swaps it in (os.replace adopts the temp inode,
+    so the target's mode becomes 0600 regardless of the prior mode or the process
+    umask). Any failure logs the keys and exception (never the values), removes
+    the temp file, and leaves the prior config on disk untouched, so a multi-key
+    save either lands in full or not at all. The lock is always released.
+    """
+    if not updates:
+        return True
+    data_dir = os.environ.get("CELERP_DATA_DIR", "")
+    if not data_dir:
+        return False
+    config_path = os.path.join(data_dir, "celerp-config.json")
+    lock_path = f"{config_path}.lock"
+    acquired = _acquire_lock(lock_path)
+    if acquired is None:
+        log.warning("Config: could not acquire lock for %s within %ss; not persisted.",
+                    sorted(updates.keys()), _LOCK_BUDGET_S)
+        return False
+    lock_fd, lock_token = acquired
+    tmp_path = f"{config_path}.{uuid.uuid4().hex}.tmp"
+    try:
+        existing: dict = {}
+        if os.path.exists(config_path):
+            with open(config_path) as f:
+                loaded = json.load(f)
+            if isinstance(loaded, dict):
+                existing = loaded
+        existing.update(updates)
+        fd = os.open(tmp_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w") as f:
+            json.dump(existing, f, indent=2)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp_path, config_path)
+        _fsync_dir(data_dir)
+        log.debug("Config: %s persisted.", sorted(updates.keys()))
+        return True
+    except Exception as exc:
+        log.warning("Config: failed to persist %s: %s", sorted(updates.keys()), exc)
+        try:
+            if os.path.exists(tmp_path):
+                os.remove(tmp_path)
+        except OSError:
+            pass
+        return False
+    finally:
+        _release_lock(lock_fd, lock_path, lock_token)
+
+
+def read_packaged_config() -> dict:
+    """Return the packaged celerp-config.json as a dict, or {} when it is
+    absent, unreadable, or not an object."""
+    data_dir = os.environ.get("CELERP_DATA_DIR", "")
+    if not data_dir:
+        return {}
+    config_path = os.path.join(data_dir, "celerp-config.json")
+    try:
+        with open(config_path) as f:
+            loaded = json.load(f)
+        return loaded if isinstance(loaded, dict) else {}
+    except (OSError, ValueError):
+        return {}

celerp-2.4.0/celerp/entitlement_preflight.py

@@ -0,0 +1,168 @@
+# Copyright (c) 2026 Noah Severs
+# SPDX-License-Identifier: BUSL-1.1
+
+"""Pre-boot entitlement preflight for the packaged app.
+
+Electron spawns this one-shot before it decides whether to open a previously
+selected external database. It refreshes the subscription entitlement from the
+relay and reports a tri-state exit code so the boot path never silently forks
+data between an external and a local store:
+
+    RENEWED (0)     the refreshed flags allow external; continue external.
+    EXPIRED (2)     the subscription lapsed; fall back to local.
+    UNREACHABLE (3) the relay could not authoritatively answer; ask, never guess.
+
+Only a well-formed HTTP 200 body is authoritative. Every transport error,
+timeout, 5xx, 401/403, malformed body, or failed locked write maps to
+UNREACHABLE, so a rotated credential or a half-refreshed config never reads as
+an expiry and never diverts the running database.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import sys
+
+from celerp.config import load_cloud_config, settings
+from celerp.config_store import merge_packaged_config
+
+log = logging.getLogger(__name__)
+
+RENEWED = 0
+EXPIRED = 2
+UNREACHABLE = 3
+
+# Boot-path bounds: short per-attempt timeout, at most two attempts, well under
+# the gateway's own (0, 5, 30) reconnect ladder, which would stall startup.
+_PREFLIGHT_TIMEOUT_S = 5.0
+_PREFLIGHT_ATTEMPTS = 2
+
+
+async def _request_subscription():
+    """Fetch the current subscription entitlement from the relay.
+
+    Exchanges the instance token for a short-lived bearer, then GETs
+    /billing/subscription, reusing one client for both. Returns the httpx
+    Response of any status on the first attempt that produced one, or None when
+    every attempt hit a transport error. Only transport failures are retried; a
+    response of any status is final and interpreted by the caller.
+    """
+    import httpx
+
+    from celerp.gateway.state import fetch_relay_bearer, relay_http_url
+
+    url = f"{relay_http_url()}/billing/subscription"
+    for attempt in range(_PREFLIGHT_ATTEMPTS):
+        try:
+            async with httpx.AsyncClient(timeout=_PREFLIGHT_TIMEOUT_S) as client:
+                bearer = await fetch_relay_bearer(client)
+                return await client.get(
+                    url, headers={"Authorization": f"Bearer {bearer}"})
+        except httpx.HTTPError:
+            if attempt + 1 >= _PREFLIGHT_ATTEMPTS:
+                return None
+    return None
+
+
+# The canonical feature-flags contract: every relay entitlement body carries
+# exactly these three boolean flags, always present, plus a grace_period_ends
+# that is null or a tz-aware ISO-8601 string. The app consumes the same bytes
+# the cloud emits (celerp/gateway/fixtures/entitlement_flags_fixture.json), so
+# validation is field-by-field against this shape, never a shape-agnostic
+# all-bool heuristic that a nested grace value would fail.
+_REQUIRED_BOOL_FLAGS = ("payments_enabled", "external_db", "external_storage")
+
+
+def _valid_grace(value) -> bool:
+    """A grace_period_ends field is authoritative only when it is None or a
+    tz-aware ISO-8601 string; a naive timestamp is a malformed body.
+
+    The relay always emits an offset-bearing timestamp; a value without a
+    timezone is ambiguous and would compare wrongly against a tz-aware now, so
+    it is rejected rather than silently assumed to be UTC.
+    """
+    if value is None:
+        return True
+    if not isinstance(value, str):
+        return False
+    from datetime import datetime
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError:
+        return False
+    return parsed.tzinfo is not None
+
+
+def _valid_feature_flags(flags) -> bool:
+    """Validate the feature_flags object field-by-field against the canonical
+    contract: the three required flags each present and a real bool, and a
+    grace_period_ends that is null or a tz-aware ISO-8601 string. A missing
+    required flag, a non-bool flag, or a naive grace is a malformed body.
+    """
+    if not isinstance(flags, dict):
+        return False
+    for key in _REQUIRED_BOOL_FLAGS:
+        value = flags.get(key)
+        if not isinstance(value, bool):
+            return False
+    return _valid_grace(flags.get("grace_period_ends"))
+
+
+def run_preflight() -> int:
+    """Refresh the entitlement and return one of RENEWED / EXPIRED / UNREACHABLE."""
+    load_cloud_config()
+    if not settings.gateway_token:
+        # An install that never associated has no entitlement to confirm; there
+        # is nothing to refresh, so fall back to local without a relay call.
+        return EXPIRED
+
+    try:
+        resp = asyncio.run(_request_subscription())
+    except Exception:
+        return UNREACHABLE
+    if resp is None or getattr(resp, "status_code", None) != 200:
+        return UNREACHABLE
+
+    try:
+        body = resp.json()
+    except Exception:
+        return UNREACHABLE
+    if not isinstance(body, dict):
+        return UNREACHABLE
+
+    flags = body.get("feature_flags")
+    if not _valid_feature_flags(flags):
+        return UNREACHABLE
+
+    # The nested grace inside feature_flags is the authoritative contract value.
+    # The relay also mirrors it at the top level; when both are present they must
+    # agree, else the body is internally inconsistent and cannot be trusted.
+    nested_grace = flags.get("grace_period_ends")
+    top_level_grace = body.get("grace_period_ends")
+    if not _valid_grace(top_level_grace):
+        return UNREACHABLE
+    if (nested_grace is not None and top_level_grace is not None
+            and nested_grace != top_level_grace):
+        return UNREACHABLE
+
+    # Persist the refreshed entitlement through the one locked writer. The
+    # canonical shape already carries grace_period_ends nested where every
+    # reader expects it. A failed write is UNREACHABLE, never a half-refreshed
+    # RENEWED.
+    if not merge_packaged_config({"feature_flags": dict(flags)}):
+        return UNREACHABLE
+
+    from celerp.gateway.state import grace_ends_in_future
+
+    external_allowed = bool(flags.get("external_db")) or grace_ends_in_future(nested_grace)
+    return RENEWED if external_allowed else EXPIRED
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.WARNING)
+    sys.exit(run_preflight())
+
+
+if __name__ == "__main__":
+    main()

celerp-2.4.0/celerp/gateway/bootstrap.py

@@ -0,0 +1,101 @@
+# Copyright (c) 2026 Noah Severs
+# SPDX-License-Identifier: LicenseRef-Proprietary
+# celerp.gateway is a protected BSL internal - 3P modules must not import it.
+"""Boot-time partner deployment association.
+
+A partner-packaged install carries a one-time deployment credential. Before the
+gateway starts, this seam exchanges that credential for the relay-created
+identity (instance_id + api_key) through the explicit relay HTTP endpoint, then
+persists the identity so the existing boot gate brings the tunnel up under it.
+
+The relay gateway handshake never consumes the credential, so the association is
+recorded only after a positive response from this dedicated call - never as a
+side effect of an ordinary hello_ack.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from celerp.config import (
+    ensure_deployment_nonce,
+    record_deployment_association,
+    settings,
+)
+
+log = logging.getLogger(__name__)
+
+
+async def associate_partner_deployment() -> bool:
+    """Associate a partner-packaged install with its partner via the relay.
+
+    No-op (returns False) unless a deployment credential is set, the install is
+    not already associated, and Cloud is not disconnected. On a positive response
+    it persists the relay-issued identity, marks the install associated, erases
+    the credential, and returns True. Every failure preserves the credential and
+    returns False without raising, so a lifespan boot is never crashed.
+    """
+    credential = (settings.deployment_credential or "").strip()
+    if not credential or settings.deployment_associated or settings.cloud_disconnected:
+        return False
+
+    from celerp.gateway.state import relay_http_url, relay_post_with_retry
+
+    try:
+        # Persist the nonce before any network call: an unpersisted nonce could
+        # not be reproduced on a later boot, risking a duplicate association.
+        nonce = ensure_deployment_nonce()
+    except Exception as exc:
+        log.warning(
+            "Deployment association skipped: could not persist the nonce (%s).",
+            type(exc).__name__,
+        )
+        return False
+
+    url = f"{relay_http_url()}/partners/deployments/associate"
+    body = {"deployment_credential": credential, "deployment_nonce": nonce}
+
+    # The shared helper retries only transient transport failures and quiets
+    # httpx's own logger for the duration (the credential travels in this body).
+    resp = await relay_post_with_retry(url, body)
+
+    if resp is None:
+        log.warning("Deployment association could not reach the relay; will retry next boot.")
+        return False
+
+    if resp.status_code != 200:
+        if resp.status_code == 403:
+            log.warning("Deployment association rejected: invalid or ineligible credential.")
+        elif resp.status_code == 409:
+            log.warning("Deployment association rejected: instance already owned.")
+        else:
+            log.warning("Deployment association failed (status %s); will retry next boot.",
+                        resp.status_code)
+        return False
+
+    try:
+        data = resp.json()
+    except Exception:
+        log.warning("Deployment association returned a malformed response body.")
+        return False
+
+    instance_id = (data.get("instance_id") or "").strip() if isinstance(data, dict) else ""
+    api_key = (data.get("api_key") or "").strip() if isinstance(data, dict) else ""
+    if not instance_id or not api_key:
+        log.warning("Deployment association response missing the instance identity.")
+        return False
+
+    try:
+        record_deployment_association(gateway_token=api_key, instance_id=instance_id)
+    except Exception as exc:
+        # The durable write failed after a positive response. The credential is
+        # preserved and no live-but-unpersisted identity is carried; the persisted
+        # nonce makes the next boot's retry resolve to the same association.
+        log.warning(
+            "Deployment association could not be persisted (%s); will retry next boot.",
+            type(exc).__name__,
+        )
+        return False
+
+    log.info("Partner deployment associated (instance_id=%s).", instance_id)
+    return True