Configuration System

Kānuka uses two separate configuration files to manage identity and settings: a user configuration that belongs to you, and a project configuration that is shared with your team.

The Two Configuration Files

User Configuration

Location: ~/.config/kanuka/config.toml

Your user configuration contains your personal identity and preferences. This file is stored in your home directory and is never shared with others.

[user]
email = "[email protected]"
name = "Alice Smith"
uuid = "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
default_device_name = "MacBook-Pro"

[projects]
"550e8400-e29b-41d4-a716-446655440000" = "workstation"
"7ba7b810-9dad-11d1-80b4-00c04fd430c8" = "laptop"

Fields:

Field	Description
email	Your email address, used as your identifier across projects.
name	Your display name (optional), for audit log features.
uuid	Your unique user identifier, generated automatically.
default_device_name	The default name for your devices when creating keys.
[projects]	A mapping of project UUIDs to your device names for each project.

Project Configuration

Location: .kanuka/config.toml (in your project root)

The project configuration is stored within your project and is shared with your team via version control. It contains information about the project and all registered users.

[project]
uuid = "550e8400-e29b-41d4-a716-446655440000"
name = "my-awesome-project"

[users]
"6ba7b810-9dad-11d1-80b4-00c04fd430c8" = "[email protected]"
"8ba7b810-9dad-11d1-80b4-00c04fd430c9" = "[email protected]"

[devices]
[devices."6ba7b810-9dad-11d1-80b4-00c04fd430c8"]
workstation = { created_at = "2025-01-06T10:00:00Z" }
laptop = { created_at = "2025-01-07T14:30:00Z" }

[devices."8ba7b810-9dad-11d1-80b4-00c04fd430c9"]
macbook = { created_at = "2025-01-05T09:00:00Z" }

Sections:

Section	Description
[project]	Project metadata including UUID and name.
[users]	Mapping of user UUIDs to their email addresses.
[devices]	Devices registered for each user, with metadata.

The Identity Hierarchy

Kānuka uses a three-level hierarchy to identify encryption keys:

1. Project - Identified by a UUID. Each project has its own set of keys and configuration.

2. User - Identified by a UUID and email. A user can have access to multiple projects.

3. Device - Identified by a name. A user can have multiple devices, each with its own key pair.

This hierarchy allows for flexible key management:

• A user can work on the same project from multiple devices
• Each device has its own key pair for security
• If a device is compromised, only that device’s keys need to be revoked

How the Configs Interact

When you run Kānuka commands, both configuration files work together:

1. During secrets init: Kānuka reads your user config to get your email and device name, then creates entries in the project config.

2. During secrets create: Kānuka uses your user UUID to create a device entry in the project config, and records the project in your user config.

3. During secrets encrypt/decrypt: Kānuka looks up your user UUID in the project config to find your encrypted key file.

4. During config rename-device: If you rename your own device, both configs are updated to stay in sync.

When Configs Are Created

User Configuration

Created when you run:

kanuka config init

Or automatically when you run kanuka secrets init for the first time.

Project Configuration

Created when you run:

kanuka secrets init

This initializes the .kanuka/ directory and creates the project config file.

Viewing Your Configuration

To see your current configuration:

# View user configuration
kanuka config show

# View project configuration
kanuka config show --project

# Output as JSON (useful for scripts)
kanuka config show --json

Continue reading to learn about managing devices in your configuration.