Operation authority contract¶

Purpose¶

Defines how an operation declares the authority it requires without making the operation contract depend on the system that supplies that authority.

The shipped contract implements the inventory_ipam capability as an admission gate for operations that depend on trusted inventory and addressing state. Allocation, inventory synchronisation, and authority-system deployment remain owned by their respective lifecycles.

Contract model¶

An authority has two distinct parts:

the logical requirement states what the operation must trust;
the binding selects the authority that will satisfy that requirement in the target environment.

The blueprint MUST declare each binding once at the top level. A dependent step MUST refer to the logical authority and required capability:

authorities:
  primary_ipam:
    capability: inventory_ipam
    provider: netbox
    config:
      live_check: true

steps:
  - id: dependent_operation
    module_ref: platform/onprem/platform-vm
    contracts:
      addressing_mode: ipam
      requires_authority:
        ref: primary_ipam
        capability: inventory_ipam

Changing the binding does not change the step contract:

authorities:
  primary_ipam:
    capability: inventory_ipam
    provider: nautobot

The logical name is local to the blueprint. It SHOULD describe the operational role, such as primary_ipam, rather than repeat a product name.

Resolution¶

Before an authority-dependent step is admitted, HybridOps MUST:

resolve the logical reference to a declared binding;
confirm that the declared and required capabilities match;
resolve the selected provider through the authority registry;
confirm that the provider supports the capability;
validate the provider configuration;
evaluate the authority state; and
issue an authority receipt only when the evaluation is healthy.

Product-specific evaluation MUST remain behind the registered provider interface. Blueprint contract enforcement MUST NOT select products through product-name conditionals.

Blueprint validation checks the declaration structure and reference matching. Blueprint preflight evaluates the selected authority. Deployment repeats the contract enforcement before the dependent step runs.

Failure behaviour¶

Authority enforcement is fail closed. The dependent step MUST be blocked when:

the logical binding is missing;
the selected provider is unknown;
the capability is missing, unsupported, or mismatched;
required configuration is absent or invalid;
the authority is unhealthy or unreachable;
bounded state is stale or its freshness cannot be established; or
authenticated readiness cannot be verified.

A successful web response alone MUST NOT be treated as proof of authority. Provider checks MUST verify the response needed for the declared capability.

Authority receipt¶

An admitted step MUST carry a non-secret authority receipt into blueprint preflight and the step run record. The receipt contains, where available:

logical_authority: primary_ipam
capability: inventory_ipam
provider: netbox
verified_state: ok
result: admitted
instance: shared-inventory
endpoint: https://inventory.example
revision: current-revision
freshness:
  checked_at: 2026-09-14T14:00:00Z

The receipt establishes which authority admitted the operation and what was verified. Tokens, passwords, embedded URL credentials, and other secret values MUST NOT be written to the receipt, preflight result, logs, or module evidence.

Shipped bindings¶

Both shipped bindings implement inventory_ipam admission. Their lifecycle scope differs.

NetBox binding¶

The NetBox binding preserves the established HybridOps authority path. It:

resolves the configured shared or environment authority root;
requires platform/onprem/netbox module state to be ok;
MAY bound that state by max_state_age_s;
MAY perform an authenticated live API check with live_check: true; and
uses the existing runtime environment and vault resolution for endpoint and token values.

Canonical configuration:

authorities:
  primary_ipam:
    capability: inventory_ipam
    provider: netbox
    config:
      live_check: true
      verify_tls: true
      timeout_s: 5
      max_state_age_s: 3600
      instance_id: shared-inventory

Nautobot binding¶

The Nautobot binding is a live authority check. It:

checks /health/ without an authorization header;
performs an authenticated read of /api/ipam/prefixes/?limit=1;
requires a valid paginated JSON response from the IPAM API;
rejects redirects and responses larger than 1 MiB;
verifies TLS by default; and
records the returned API version when available.

Canonical configuration:

authorities:
  primary_ipam:
    capability: inventory_ipam
    provider: nautobot
    config:
      endpoint_env: NAUTOBOT_API_URL
      token_env: NAUTOBOT_API_TOKEN
      api_version: "2.4"
      verify_tls: true
      timeout_s: 5
      instance_id: shared-inventory

endpoint MAY replace endpoint_env. The endpoint MUST be an absolute HTTP or HTTPS URL and MUST NOT contain credentials, query parameters, or fragments. The token value is accepted only through the named environment variable.

The binding follows Nautobot's documented health check, REST authentication, and REST API behaviour.

Compatibility¶

Existing NetBox-specific blueprints remain valid:

policy:
  ipam_authority: netbox
  netbox_live_api_check: false

contracts:
  addressing_mode: ipam
  requires_authority: netbox

HybridOps explicitly translates this form to a logical legacy_netbox authority with capability inventory_ipam. The existing state-only default, optional live check, authority-root resolution, and legacy live-check TLS behaviour remain unchanged.

This syntax is compatibility-only. New and revised blueprints SHOULD use the logical declaration and requirement form.

Capability boundary¶

This contract proves that an operation can require authority independently of the selected binding. It does not imply that every module can consume every authority system.

A module that allocates addresses, imports inventory, or deploys an authority service MAY still have a product-specific lifecycle contract. Such a module MUST state that boundary directly. Provider-neutral operation admission MUST not be described as universal CMDB support or as an arbitrary plugin ecosystem.