Blueprints

A blueprint is a JSON document that describes an enterprise network. It is applied with one command to provision the network's name, join rule, policies, identity provider, webhooks, audit export, role pre-assignments, and admin token.

Overview

A blueprint is a single JSON document that describes an entire enterprise network: its name, join rule, policies, identity provider, webhooks, audit export, role pre-assignments, and admin token. Applying it with one command causes the registry to provision everything in a deterministic sequence.

Blueprints are designed for infrastructure-as-code workflows. They can be stored in version control, with changes reviewed in pull requests and applied through CI/CD pipelines.

Blueprint format

{
  "name": "prod-fleet",
  "join_rule": "invite_only",
  "enterprise": true,
  "policy": {
    "max_members": 100,
    "allowed_ports": [80, 443, 1001],
    "description": "Production fleet - US East"
  },
  "identity_provider": {
    "type": "oidc",
    "url": "https://accounts.example.com/.well-known/openid-configuration",
    "client_id": "pilot-prod"
  },
  "webhooks": [
    {
      "url": "https://ops.example.com/pilot-events",
      "events": ["member.kicked", "network.policy_changed"]
    }
  ],
  "audit_export": {
    "format": "splunk_hec",
    "endpoint": "https://splunk.example.com:8088/services/collector",
    "token": "hec-token-here"
  },
  "roles": {
    "42": "admin",
    "108": "admin"
  },
  "network_admin_token": "network-specific-secret"
}

Fields reference

name (string, required): Network name. Lowercase alphanumeric with hyphens. Used for idempotent lookup.
join_rule (string): One of `open`, `invite_only`, or `token`. Defaults to `open`.
enterprise (bool): Enable enterprise features. Defaults to `false`.
policy (object): Network policy: `max_members`, `allowed_ports`, `description`.
identity_provider (object): IDP configuration: `type`, `url`, `client_id`.
webhooks (array): Webhook endpoints: `url` and `events` filter.
audit_export (object): Export config: `format`, `endpoint`, `token`.
roles (object): Map of node ID (string) to role (`admin` or `member`). Pre-assigns RBAC roles.
network_admin_token (string): Per-network admin token for delegated administration.

Apply sequence

When a blueprint is applied, the registry executes these steps in order:

Find or create: look up the network by name. If it exists, use it. If not, create it with the specified join rule.
Enable enterprise: if `enterprise: true` and the network is not yet enterprise, enable it.
Set policies: apply the `policy` object using merge-on-update semantics.
Configure IDP: set the identity provider configuration if specified.
Configure audit export: set the audit export endpoint and format if specified.
Configure webhooks: register webhook endpoints if specified.
Assign roles: for each entry in `roles`, set the RBAC role. Nodes must already be members of the network.

Each step is independent. If a later step fails, earlier steps are not rolled back. The result includes which actions were taken and which failed.

Idempotency

Blueprints are idempotent. Applying the same blueprint twice produces the same result. The registry looks up the network by `name`:

If a network with that name exists, it is updated, not duplicated.
If no network with that name exists, a new one is created.

This makes blueprints safe to apply repeatedly in CI/CD pipelines. Re-applying after a partial failure completes the remaining steps without duplicating already-completed ones.

Validation

The registry validates the blueprint before applying any changes:

`name` is required and must match the network name rules (lowercase alphanumeric with hyphens).
`join_rule` must be one of `open`, `invite_only`, or `token`.
`policy.max_members` must be a non-negative integer.
`policy.allowed_ports` must have 100 or fewer entries.
`policy.description` must be 256 or fewer characters.
`identity_provider.type` must be a valid provider type (`oidc`, `saml`, `entra_id`, `ldap`, `webhook`).
`roles` values must be `admin` or `member`. Ownership is assigned to the creator and cannot be set here.

If validation fails, no changes are made and the error is returned immediately.

Protocol command

To apply a blueprint:

{
  "command": "provision_network",
  "blueprint": {
    "name": "prod-fleet",
    "enterprise": true,
    "policy": { "max_members": 100 }
  },
  "admin_token": "your-admin-token"
}

The blueprint is the only payload field besides `admin_token`. Ownership of a newly-created network is assigned to the registry node that the admin token authorizes.

Result format:

{
  "network_id": 5,
  "name": "prod-fleet",
  "created": true,
  "actions": [
    "network created",
    "enterprise enabled",
    "policy set",
    "audit export configured"
  ]
}

The `created` field indicates whether a new network was created (`true`) or an existing one was updated (`false`).

For programmatic use, a blueprint can be loaded from a JSON file using a helper.

// Go SDK — pkg/registry/wire has the typed loader
import "github.com/TeoSlayer/pilotprotocol/pkg/registry/wire"
import "github.com/TeoSlayer/pilotprotocol/pkg/registry"

bp, err := wire.LoadBlueprint("network.json")        // *wire.NetworkBlueprint
result, err := client.ProvisionNetwork(bp.ToMap(), adminToken)

`wire.LoadBlueprint` reads and validates the JSON file, returning a typed struct. `registry.Client.ProvisionNetwork` takes the blueprint as a map and the admin token. The network owner is the node authenticated on the client connection.

Status query

To inspect the provisioning state of a network:

{
  "command": "get_provision_status",
  "network_id": 5,
  "admin_token": "your-admin-token"
}

This command returns the network’s current configuration as seen by the registry. This can be used to verify that a blueprint was applied correctly or to diff the current state against a desired state.