Device-bound Edge Runtime Identity

1. Goal

Edge Runtime identity must represent one installed device, not a copyable secret.

A deployment token authorizes enrollment. It does not become the runtime identity.

2. Decisions

• Device identity is generated on the Edge Runtime host.
• Device identity is long-lived across deployment token expiration.
• Deployment token authorizes first enrollment and later re-enrollment.
• Same device can re-enroll with a new deployment token and keep the same identity.
• Different devices cannot reuse an existing identity.
• edge_secret is removed from the target design. No compatibility layer is required.
• Runtime API authentication uses asymmetric request signing.

3. Terms

DeploymentToken

Temporary enrollment authorization created from Control Plane.

Node

Tenant-visible host or device joined to OrbitMesh.

EdgeRuntime

The installed runtime record bound to one Node and one device identity.

DeviceIdentity

Stable device identity generated and stored on the Edge Runtime host.

InstallationID

Stable UUID generated by the Edge Runtime on first install.

DeviceKey

Ed25519 private key generated locally. The public key is registered with Control Plane.

DeviceFingerprint

A non-secret hash derived from stable host signals. It is used as an additional copy-detection signal, not as the primary credential.

4. Identity Files

The Edge Runtime stores identity outside the main config file:

/var/lib/orbitmesh/edge-runtime/identity.json
/var/lib/orbitmesh/edge-runtime/identity.key

Permissions:

identity.json 0600 root:root
identity.key  0600 root:root

identity.key is the root of device identity. If it is lost, the host can no longer prove it is the same device.

/etc/orbitmesh/edge-runtime.yaml may contain operational config such as Control Plane URL, Node ID, and sync intervals. It must not contain a long-lived shared secret.

5. Device Identity Document

identity.json:

{
  "identity_version": 1,
  "installation_id": "uuid",
  "edge_runtime_id": "uuid",
  "node_id": "uuid",
  "public_key": "base64url-ed25519-public-key",
  "device_fingerprint_hash": "sha256-hex",
  "created_at": "2026-06-18T00:00:00Z"
}

The private key is stored separately in identity.key.

6. Enrollment Flow

First install:

1. User creates a deployment token.
2. Installer downloads orbitmesh and orbitmeshd.
3. Edge Runtime generates installation_id and Ed25519 keypair locally.
4. Edge Runtime computes device_fingerprint_hash.
5. Edge Runtime calls Register with deployment token, public key, installation ID, and fingerprint hash.
6. Control Plane consumes the deployment token.
7. Control Plane creates Node and EdgeRuntime records.
8. Control Plane returns Node ID and EdgeRuntime ID.
9. Agent persists identity and runtime config.

No edge_secret is returned.

7. Re-enrollment Flow

Same device re-enrollment:

1. User creates a new deployment token.
2. Agent loads existing identity.key and identity.json.
3. Agent calls Register with the new deployment token and existing device identity.
4. Control Plane verifies the public key, installation ID, and fingerprint match an existing EdgeRuntime.
5. Control Plane consumes the new deployment token.
6. Control Plane refreshes metadata such as hostname, version, OS, arch, and last enrollment time.
7. Node ID and EdgeRuntime ID remain unchanged.

This supports token expiration and reinstallation without creating duplicate Node resources.

8. Different Device Handling

If a request attempts to re-enroll an existing identity from another device:

409 DEVICE_IDENTITY_MISMATCH

Reasons include:

• installation ID matches but public key differs.
• public key matches but fingerprint differs.
• requested Node already has an active device identity and no replace/reset operation was approved.

The MVP does not allow implicit replacement. A new device must use a new identity and normally creates a new Node.

9. Runtime Request Authentication

Every Runtime API except Register uses Ed25519 request signing.

Headers:

X-OrbitMesh-Node-Id
X-OrbitMesh-Edge-Runtime-Id
X-OrbitMesh-Installation-Id
X-OrbitMesh-Timestamp
X-OrbitMesh-Nonce
X-OrbitMesh-Body-SHA256
X-OrbitMesh-Signature

Canonical payload:

method + "\n" +
path_and_query + "\n" +
body_sha256 + "\n" +
timestamp + "\n" +
nonce + "\n" +
node_id + "\n" +
edge_runtime_id + "\n" +
installation_id

Server validation:

• Validate timestamp skew.
• Reject replayed nonce.
• Load EdgeRuntime by Node ID, EdgeRuntime ID, and Installation ID.
• Verify signature with stored public key.
• Reject disabled, deleted, revoked, or replaced identities.

10. Register API Changes

RegisterRequest target fields:

deployment_token
installation_id
public_key
device_fingerprint_hash
hostname
reported_address
os
arch
edge_runtime_version

EdgeRuntimeRegisterResponse target fields:

node_id
edge_runtime_id
control_plane_url

Removed:

edge_secret

11. Database Model

edge_runtimes target fields:

id
node_id
installation_id
public_key
device_fingerprint_hash
identity_status
edge_runtime_version
status
last_enrolled_at
last_heartbeat_at
created_at
updated_at

Constraints:

• node_id unique.
• installation_id unique.
• public_key unique.

Removed:

edge_secret_hash

deployment_tokens remains temporary authorization:

• token hash is stored.
• token has expiration.
• token may be single-use or same-device re-enrollment capable.

12. Current Cutover Rules

The current implementation uses the node identity model only:

• local identity is stored in node.json.
• request signing uses X-OrbitMesh-Node-Id.
• application code should reject unknown identity headers and config keys.