nexocyber-networks-operator-surface 0.3.12

SDK that every SkyDefended-coupled App must integrate to expose its operational plane to NCN operators via outbound-only telemetry and command polling.

@nexocyber-networks/operator-surface — Python runtime

Python port of the TypeScript SDK. Same model, same TTLs, same wire formats — different language idiom (async/await, pydantic v2, contextmanagers).

Status: v0.2.0 — partial parity with TS v0.3.x. 5 modules shipped (bootstrap, bundle sync, credential refresh, infra audit push, app token introspect). Signed envelope App→Engine lands in v0.3.0 (next milestone). See CHANGELOG.md.

Install

pip install nexocyber-networks-operator-surface

(Or with uv add, poetry add, etc.)

Why it exists

If your App is a Python service (FastAPI, Flask, Django, plain asyncio) that gets coupled to a SkyDefended deployment, this SDK is not optional. It encodes the operator-surface contract: outbound-only push, signed envelopes, replay-protected JWTs, audit queue with retry, policy bundle verification.

Reimplementing those locally is anti-pattern Doc 19 §3 — drift between runtimes silently breaks the trust model.

Quick start (bootstrap)

import asyncio
import os
from skydefended_operator_surface import bootstrap_app

async def main() -> None:
    creds = await bootstrap_app(
        control_api_url=os.environ["CONTROL_API_URL"],
        app_slug=os.environ["APP_SLUG"],
        bootstrap_token=os.environ["BOOTSTRAP_TOKEN"],
        node_id=os.environ.get("NODE_ID"),
    )
    # `creds` now has:
    #   appSlug, appId, serviceCredential, credentialVersion,
    #   privateKeyPem, publicKeyPem, kid
    # Persist them (Vault, file, etc.) and pass into the rest of the SDK.
    print(f"bootstrapped {creds.app_slug} kid={creds.kid}")

asyncio.run(main())

See docs/ for the per-module guides.

API parity with TS

TS export	Python export
bootstrapApp()	skydefended_operator_surface.bootstrap_app
createEngineSigner()	skydefended_operator_surface.create_engine_signer
createPolicyBundleSync()	skydefended_operator_surface.create_policy_bundle_sync
createCredentialRefresher()	skydefended_operator_surface.create_credential_refresher
createInfraAuditQueue()	skydefended_operator_surface.create_infra_audit_queue
createAppTokenIntrospector()	skydefended_operator_surface.create_app_token_introspector

TTLs (wrapper 60s, bundle 5min poll / 24h TTL / 7d grace, introspect positive 30s, credential refresh at 80%, jti dedup 60s) are constants exported from the top-level namespace — exactly the same values as the TS runtime. CI runs shared fixtures against both runtimes.

Versioning

Lock-step with the TS SDK at the minor level. When TS ships 0.3.x, Python ships 0.3.x in parallel with the same change set. Patch-level fixes can diverge.

License

UNLICENSED — internal NCN SDK.