Software Updates & Client Integration

persistent installation UUID + normalized domain

POST /wp-json/woonoow/v1/software/package
Content-Type: application/json

{
  "slug": "crm-connector",
  "purpose": "install",
  "license_key": "WNW-7712-8823-9934",
  "site_url": "https://client-site.example",
  "installation_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "slug": "crm-connector",
  "purpose": "reinstall",
  "license_key": "WNW-7712-8823-9934",
  "site_url": "https://client-site.example",
  "installation_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "slug": "crm-connector",
  "purpose": "update",
  "current_version": "1.2.0",
  "license_key": "WNW-7712-8823-9934",
  "site_url": "https://client-site.example",
  "installation_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "success": true,
  "purpose": "update",
  "product": {
    "id": 1042,
    "name": "CRM Connector",
    "slug": "crm-connector"
  },
  "version_id": 88,
  "version": "1.3.0",
  "artifact_download_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "file_name": "crm-connector_v_1.3.0.zip",
  "file_size": 1548291,
  "file_sha256": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945",
  "signature": null,
  "signing_key_id": null,
  "signed_at": null,
  "release_date": "2026-09-08 10:00:00",
  "manual_download_only": false,
  "download_url": "https://store.example/wp-json/woonoow/v1/software/download?token=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "token_expires_at": "2026-09-08 10:05:00",
  "token_binding_version": 1,
  "entitlement": {
    "license_required": true,
    "license_active": true,
    "update_entitled": true,
    "support_active": true,
    "usage_expires_at": "2027-09-08 10:00:00",
    "updates_expires_at": "2027-09-08 10:00:00",
    "support_expires_at": "2027-09-08 10:00:00",
    "policy_mode": "explicit",
    "historical_downloads": true
  }
}

GET /wp-json/woonoow/v1/software/download?token={bearer-token}

POST /wp-json/woonoow/v1/software/check
Content-Type: application/json

{
  "slug": "my-plugin",
  "version": "1.2.0",
  "license_key": "XXXX-YYYY-ZZZZ-WWWW",
  "site_url": "https://client-site.example",
  "installation_id": "550e8400-e29b-41d4-a716-446655440000"
}

import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
import { once } from 'node:events';
import { createWriteStream } from 'node:fs';
import { readFile, unlink, writeFile } from 'node:fs/promises';
import { join } from 'node:path';
import { finished } from 'node:stream/promises';
import { homedir } from 'node:os';

const API_BASE = 'https://store.example/wp-json/woonoow/v1';
const SHA256_REGEX = /^[0-9a-f]{64}$/;

/**
 * Persist or retrieve a canonical installation UUID.
 */
async function getOrCreateInstallationId(slug) {
  const scope = createHash('sha256').update(`${API_BASE}|${slug}`).digest('hex').slice(0, 16);
  const identityFile = join(homedir(), `.woonoow-${scope}-installation-id`);

  try {
    const existing = (await readFile(identityFile, 'utf8')).trim().toLowerCase();
    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(existing)) {
      return existing;
    }
  } catch {
    // Identity file does not exist yet; generate below.
  }

  const newId = randomUUID();
  await writeFile(identityFile, newId, { mode: 0o600 });
  return newId;
}

/**
 * Request a purpose-aware package payload from WooNooW.
 */
async function requestPackage({ slug, purpose, currentVersion, licenseKey, siteUrl, installationId }) {
  const payload = {
    slug,
    purpose,
    license_key: licenseKey,
    site_url: siteUrl,
    installation_id: installationId,
  };

  // current_version is strictly required for 'update' and forbidden for 'install'/'reinstall'
  if (purpose === 'update') {
    if (!currentVersion) throw new Error('current_version_required');
    payload.current_version = currentVersion;
  }

  const response = await fetch(`${API_BASE}/software/package`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
    body: JSON.stringify(payload),
  });

  const data = await response.json().catch(() => ({}));
  if (!response.ok) {
    const err = new Error(data.message || `HTTP ${response.status}`);
    err.code = data.code ?? data.error ?? `http_${response.status}`;
    err.status = response.status;
    err.retryAfter = data.data?.retry_after;
    throw err;
  }

  if (!data || typeof data !== 'object' || !SHA256_REGEX.test(String(data.file_sha256 || '').toLowerCase())) {
    throw new Error('invalid_package_response');
  }
  if (data.manual_download_only ? !data.external_link_url : !data.download_url) {
    throw new Error('invalid_package_response');
  }

  return data;
}

/**
 * Download package bytes and verify SHA-256 integrity.
 */
async function downloadAndVerify(downloadUrl, expectedHash, destinationPath) {
  const expected = String(expectedHash || '').toLowerCase();
  if (!SHA256_REGEX.test(expected)) {
    throw new Error('invalid_expected_checksum');
  }

  let response;
  try {
    // Pure GET: no HEAD probe, Range header, or extra query selector.
    response = await fetch(downloadUrl, {
      method: 'GET',
      headers: { 'Accept': 'application/octet-stream' },
    });
  } catch (cause) {
    const err = new Error('package_transport_failed', { cause });
    err.retryWithFreshToken = true;
    throw err;
  }

  if (!response.ok) {
    const errorData = await response.json().catch(() => ({}));
    const err = new Error(errorData.message || `HTTP ${response.status}`);
    err.code = errorData.code ?? errorData.error ?? `http_${response.status}`;
    err.status = response.status;
    throw err;
  }

  const advertised = response.headers.get('X-Package-Sha256')?.trim().toLowerCase();
  if (advertised && advertised !== expected) {
    throw new Error('package_checksum_metadata_mismatch');
  }
  if (!response.body) {
    const err = new Error('package_response_body_missing');
    err.retryWithFreshToken = true;
    throw err;
  }

  const hasher = createHash('sha256');
  const writer = createWriteStream(destinationPath, { flags: 'w', mode: 0o600 });
  const reader = response.body.getReader();

  try {
    while (true) {
      let result;
      try {
        result = await reader.read();
      } catch (cause) {
        const err = new Error('package_transport_interrupted', { cause });
        err.retryWithFreshToken = true;
        throw err;
      }

      if (result.done) break;
      hasher.update(result.value);
      if (!writer.write(result.value)) {
        await once(writer, 'drain');
      }
    }

    writer.end();
    await finished(writer);
  } catch (err) {
    writer.destroy();
    await unlink(destinationPath).catch(() => {});
    throw err;
  }

  const actual = hasher.digest('hex').toLowerCase();
  const expectedBuffer = Buffer.from(expected, 'utf8');
  const actualBuffer = Buffer.from(actual, 'utf8');
  if (expectedBuffer.length !== actualBuffer.length || !timingSafeEqual(expectedBuffer, actualBuffer)) {
    await unlink(destinationPath).catch(() => {});
    throw new Error('package_integrity_failed');
  }

  return destinationPath;
}

/**
 * Main workflow: execute an update or install with one deliberate fresh-token retry.
 */
export async function installOrUpdateSoftware({ slug, purpose, currentVersion, licenseKey, siteUrl, destinationPath }) {
  const installationId = await getOrCreateInstallationId(slug);
  const retryableTokenCodes = new Set(['token_expired', 'token_consumed', 'token_invalidated']);

  for (let attempt = 0; attempt < 2; attempt += 1) {
    const packageInfo = await requestPackage({
      slug,
      purpose,
      currentVersion,
      licenseKey,
      siteUrl,
      installationId,
    });

    if (packageInfo.manual_download_only) {
      const err = new Error('manual_download_required');
      err.externalLinkUrl = packageInfo.external_link_url;
      throw err;
    }

    try {
      return await downloadAndVerify(
        packageInfo.download_url,
        packageInfo.file_sha256,
        destinationPath,
      );
    } catch (err) {
      const mayRefresh = retryableTokenCodes.has(err.code) || err.retryWithFreshToken === true;
      if (attempt === 0 && mayRefresh) {
        continue;
      }
      throw err;
    }
  }

  throw new Error('package_download_failed');
}

import hashlib
import hmac
import os
import re
import tempfile
import uuid
from pathlib import Path

import requests

API_BASE = "https://store.example/wp-json/woonoow/v1"
SHA256_PATTERN = re.compile(r"^[0-9a-f]{64}$")
RETRYABLE_TOKEN_CODES = {"token_expired", "token_consumed", "token_invalidated"}


class WooNooWError(RuntimeError):
    def __init__(self, code: str, message: str, *, retry_with_fresh_token: bool = False):
        super().__init__(message)
        self.code = code
        self.retry_with_fresh_token = retry_with_fresh_token


def get_or_create_installation_id(slug: str) -> str:
    """Retrieve a UUID scoped by WooNooW API base and software slug."""
    scope = hashlib.sha256(f"{API_BASE}|{slug}".encode()).hexdigest()[:16]
    identity_file = Path.home() / f".woonoow-{scope}-installation-id"

    if identity_file.exists():
        saved = identity_file.read_text(encoding="utf-8").strip().lower()
        try:
            return str(uuid.UUID(saved))
        except ValueError:
            pass

    new_id = str(uuid.uuid4())
    identity_file.write_text(new_id, encoding="utf-8")
    identity_file.chmod(0o600)
    return new_id


def response_error(response: requests.Response) -> WooNooWError:
    try:
        body = response.json()
    except ValueError:
        body = {}

    code = body.get("code") or body.get("error") or f"http_{response.status_code}"
    message = body.get("message") or f"HTTP {response.status_code}"
    return WooNooWError(code, message)


def request_package(
    slug: str,
    purpose: str,
    license_key: str,
    site_url: str,
    current_version: str | None = None,
) -> dict:
    """Fetch protected-product metadata via POST /software/package."""
    payload = {
        "slug": slug,
        "purpose": purpose,
        "license_key": license_key,
        "site_url": site_url,
        "installation_id": get_or_create_installation_id(slug),
    }

    if purpose == "update":
        if not current_version:
            raise ValueError("current_version is required for update purpose")
        payload["current_version"] = current_version

    response = requests.post(
        f"{API_BASE}/software/package",
        json=payload,
        headers={"Accept": "application/json"},
        timeout=20,
    )
    if not response.ok:
        raise response_error(response)

    try:
        body = response.json()
    except ValueError as cause:
        raise WooNooWError("invalid_package_response", "Package response was not JSON.") from cause

    checksum = str(body.get("file_sha256", "")).lower()
    expected_link = body.get("external_link_url") if body.get("manual_download_only") else body.get("download_url")
    if not SHA256_PATTERN.fullmatch(checksum) or not expected_link:
        raise WooNooWError("invalid_package_response", "Package response metadata is incomplete.")
    return body


def download_package(download_url: str, expected_hash: str, output_path: Path) -> Path:
    """Perform one full GET and verify SHA-256 before returning the file."""
    expected = expected_hash.strip().lower()
    if not SHA256_PATTERN.fullmatch(expected):
        raise ValueError("Invalid expected SHA-256 checksum")

    digest = hashlib.sha256()
    try:
        try:
            response = requests.get(download_url, stream=True, timeout=60)
        except requests.RequestException as cause:
            raise WooNooWError(
                "package_transport_failed",
                str(cause),
                retry_with_fresh_token=True,
            ) from cause

        with response:
            if not response.ok:
                raise response_error(response)

            advertised = response.headers.get("X-Package-Sha256", "").strip().lower()
            if advertised and not hmac.compare_digest(advertised, expected):
                raise WooNooWError(
                    "package_checksum_metadata_mismatch",
                    "The download header does not match package metadata.",
                )

            try:
                with output_path.open("wb") as package:
                    for chunk in response.iter_content(chunk_size=1024 * 1024):
                        if chunk:
                            digest.update(chunk)
                            package.write(chunk)
            except requests.RequestException as cause:
                raise WooNooWError(
                    "package_transport_interrupted",
                    str(cause),
                    retry_with_fresh_token=True,
                ) from cause
    except Exception:
        output_path.unlink(missing_ok=True)
        raise

    actual = digest.hexdigest().lower()
    if not hmac.compare_digest(actual, expected):
        output_path.unlink(missing_ok=True)
        raise WooNooWError("package_integrity_failed", "Downloaded bytes failed SHA-256 verification.")

    return output_path


def get_software_package(
    slug: str,
    purpose: str,
    license_key: str,
    site_url: str,
    current_version: str | None = None,
) -> Path:
    """Download with at most one deliberate fresh-token retry."""
    for attempt in range(2):
        info = request_package(slug, purpose, license_key, site_url, current_version)
        if info.get("manual_download_only"):
            raise WooNooWError(
                "manual_download_required",
                f"Use the gated route: {info.get('external_link_url')}",
            )

        descriptor, name = tempfile.mkstemp(prefix="woonoow-", suffix=".zip")
        os.close(descriptor)
        destination = Path(name)

        try:
            return download_package(info["download_url"], info["file_sha256"], destination)
        except WooNooWError as error:
            may_refresh = error.code in RETRYABLE_TOKEN_CODES or error.retry_with_fresh_token
            if attempt == 0 and may_refresh:
                continue
            raise

    raise WooNooWError("package_download_failed", "Package download failed.")