Key Management

Managing Ed25519 keys, file permissions, and identity lifecycle.

Overview

Starweft's security model is based on Ed25519 key pairs. Each node has at least one key pair (actor_key) and signs all protocol messages with it. Principal nodes additionally have a key pair for stop authority (stop_authority_key).

Key Types

Key Name	Description
`actor_key`	The node's primary identity key. Used to sign all messages. Required for all roles.
`stop_authority_key`	A dedicated key used to sign stop orders (StopOrder). Generated on principal nodes.

actor_key

The actor_key is the node's main identity. All protocol messages (VisionIntent, TaskDelegated, TaskResultSubmitted, etc.) are signed with this key. The public key is shared among peers and used for signature verification.

stop_authority_key

The stop_authority_key is a key that represents the authority to issue stop orders (StopOrder) for projects and task trees. Only actors registered in the stop_authority_actor_id field of the ProjectCharter can issue valid stop orders.

Key Generation

Use the identity create command to generate Ed25519 key pairs.

bash

# worker / owner / relay node: generates actor_key only
starweft identity create

The generation process works as follows.

Key Pair Generation

An Ed25519 key pair is generated using ed25519-dalek's SigningKey::generate() with the OS's cryptographically secure random number generator (OsRng).

Saving to File

The key pair is written to a file in JSON format.

json

{
  "key_id": "key_01JXYZ...",
  "created_at": "2026-03-15T10:00:00Z",
  "secret_key": "<base64-encoded 32 bytes>",
  "public_key": "<base64-encoded 32 bytes>"
}

Setting Permissions

The secret key file is protected with permissions that allow only the owner to read and write (detailed below).

Identity Registration

An ActorId and NodeId are automatically generated and registered in the local_identity table of the SQLite store. The identity.actor_key_path in the configuration file (config.toml) is also automatically updated.

Key Overwriting

If an existing key is present, it can be overwritten using the --force flag.

bash

starweft identity create --force

File Storage Location

Key files are stored in the identity/ subdirectory of the data directory.

plaintext

~/.starweft/
├── config.toml
└── identity/
    ├── actor_key              # Main identity key
    └── stop_authority_key     # Stop authority key (principal only)

Path Configuration in config.toml

Key file paths can be specified in the [identity] section of the configuration file.

toml

[identity]
actor_key_path = "~/.starweft/identity/actor_key"
stop_authority_key_path = "~/.starweft/identity/stop_authority_key"

The identity create command generates keys at the path specified in the configuration. If no path is configured, it uses the default path (<data_dir>/identity/actor_key) and automatically updates the configuration.

File Permissions

To prevent unauthorized access to secret key files, appropriate permissions are set for each platform.

Unix

Public Key Exchange

There are two methods for sharing public keys between peers.

Manual Exchange: `peer add`

Retrieve the public key using identity show, then register it on the other node using the peer add command.

bash

# Check Node A's public key
starweft identity show
# Example output: public_key: dGVzdC1wdWJsaWMta2V5...
 
# Register Node A on Node B
starweft peer add /ip4/192.168.1.10/tcp/9000 \
  --public-key "dGVzdC1wdWJsaWMta2V5..." \
  --stop-public-key "c3RvcC1wdWJsaWMta2V5..." \
  --actor-id "actor_01ABC..." \
  --node-id "node_01DEF..."

Public keys can also be loaded from a file.

bash

starweft peer add /ip4/192.168.1.10/tcp/9000 \
  --public-key-file ./peer_a_pubkey.txt \
  --stop-public-key-file ./peer_a_stop_pubkey.txt

Automatic Exchange: CapabilityQuery / CapabilityAdvertisement

At node startup, a CapabilityQuery message is broadcast, and public keys are automatically exchanged when a CapabilityAdvertisement response is received.

json

{
  "msg_type": "CapabilityQuery",
  "body": {
    "node_id": "node_01ABC...",
    "public_key": "<base64 actor public key>",
    "stop_public_key": "<base64 stop public key or null>",
    "capabilities": ["openclaw.execution.v1"],
    "listen_addresses": ["/ip4/192.168.1.10/tcp/9000"]
  }
}

Exchanged public keys are stored in the peer_identities table of the SQLite store and used for subsequent message signature verification.

Key Backup

Key files can be backed up along with the entire data directory using the backup create command.

bash

starweft backup create --output ~/starweft-backup

The backup includes the following.

identity/actor_key -- Main identity key
identity/stop_authority_key -- Stop authority key (if present)
config.toml -- Configuration file including key path settings
ledger/node.db -- SQLite database containing event logs and peer information

For more details on backups, see the Audit page.

Message Signing

Integrity guarantees through Ed25519 signing and Canonical JSON

Audit

Signature verification and backup integrity checks for event logs