Project Configuration

Every Kānuka project has a configuration file that tracks the project identity and all registered users. Unlike your user configuration, this file is shared with your team via version control.

Location

The project configuration is stored at:

your-project/
└── .kanuka/
    └── config.toml

File Structure

[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"]
email = "[email protected]"
name = "workstation"
created_at = 2025-01-06T10:00:00Z

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

Sections Explained

Project Section

Field	Description
uuid	A unique identifier for this project, generated when you run kanuka secrets init.
name	The project name, defaulting to the directory name.

The project UUID is used to:

• Organize your local keys by project
• Link your user configuration to specific projects
• Ensure uniqueness across all Kānuka projects

Users Section

Maps user UUIDs to their email addresses:

[users]
"6ba7b810-..." = "[email protected]"
"8ba7b810-..." = "[email protected]"

This provides a human-readable way to identify who has access, while the actual key files use UUIDs for naming.

Devices Section

Tracks metadata for each registered device:

Field	Description
email	The user’s email address (for display purposes).
name	The device name chosen by the user.
created_at	When this device was registered.

Note that each user UUID represents a single device. If a user has multiple devices, they have multiple UUIDs in the project config.

How Users Are Represented

Each device a user registers gets its own UUID. For example, if Alice has two devices:

[users]
"uuid-alice-workstation" = "[email protected]"
"uuid-alice-laptop" = "[email protected]"

[devices."uuid-alice-workstation"]
email = "[email protected]"
name = "workstation"
created_at = 2025-01-06T10:00:00Z

[devices."uuid-alice-laptop"]
email = "[email protected]"
name = "laptop"
created_at = 2025-01-07T14:30:00Z

This design allows:

• Per-device key management
• Revoking a single device without affecting others
• Clear audit trail of when devices were added

How It’s Created

The project configuration is created when you run:

kanuka secrets init

This command:

1. Creates the .kanuka/ directory structure
2. Generates a project UUID
3. Creates the config.toml with your user as the first registered member

Viewing Project Configuration

# Show project configuration
kanuka config show --project

# List all devices in the project
kanuka config list-devices

# Show as JSON (for scripts)
kanuka config show --project --json

What Gets Committed

The entire .kanuka/ directory should be committed to version control, including:

• config.toml - The project configuration
• public_keys/ - Public keys for all registered users
• secrets/ - Encrypted symmetric keys for all registered users

This allows your team to:

• See who has access to the project
• Grant access to new team members
• Revoke access when needed

Relationship to User Configuration

The project and user configurations work together:

Action	Project Config	User Config
secrets init	Created with your user entry	Updated with project entry
secrets create	Updated with new device	Updated with project entry
secrets register	Updated with new user/device	(Their config, not yours)
secrets revoke	User/device removed	(Their config, not yours)
config set-project-device	Device name updated	Your entry updated
config set-default-device	Not affected	Default device name updated

Security Considerations

The project configuration contains:

• User email addresses (visible to anyone with repo access)
• Device names and creation dates
• UUIDs linking to encryption key files

It does not contain:

• Private keys (stored locally on each user’s machine)
• Actual secrets (stored in encrypted .env.kanuka files)
• Symmetric keys (encrypted per-user in .kanuka/secrets/)

Related Configuration

• User Configuration - Your personal config
• Configuration Commands - All available config commands
• File Structure - Where all Kānuka files are stored