arca/PLAN.md

arca — Implementation Plan

Overview

A Go CLI that manages LUKS volumes. Uses udisks2 D-Bus for passphrase/keyfile unlock (no root needed), and falls back to cryptsetup for FIDO2/TPM2 tokens (requires root/doas). Three subcommands: mount, unmount, status.

Dependencies

• github.com/spf13/cobra — CLI framework
• github.com/godbus/dbus/v5 — D-Bus client
• gopkg.in/yaml.v3 — config file parsing

Project Structure

arca/
├── main.go
├── cmd/
│   ├── root.go          # root command, global flags
│   ├── mount.go         # mount subcommand
│   ├── unmount.go       # unmount subcommand
│   └── status.go        # status subcommand
├── internal/
│   ├── udisks/          # udisks2 D-Bus client
│   │   ├── client.go    # connection + device discovery
│   │   ├── encrypt.go   # Unlock / Lock operations
│   │   ├── mount.go     # Mount / Unmount operations
│   │   └── types.go     # object path helpers, constants
│   ├── cryptsetup/      # cryptsetup CLI wrapper (FIDO2/TPM2)
│   │   └── cryptsetup.go
│   ├── unlock/          # method sequencing logic
│   │   └── unlock.go
│   └── config/
│       └── config.go    # YAML config loading + device resolution
├── flake.nix
├── go.mod
├── go.sum
├── README.md
└── PLAN.md

Phase 1: Core Unlock/Lock Backend

Build internal/udisks/ for D-Bus operations and internal/cryptsetup/ for FIDO2/TPM2 fallback.

udisks2 D-Bus (passphrase + keyfile)

1. Connect to the system bus.
2. Enumerate block devices under /org/freedesktop/UDisks2/block_devices/.
3. Find a block device by device path or UUID.
4. Unlock(passphrase) — call org.freedesktop.UDisks2.Encrypted.Unlock on the LUKS partition. Returns the cleartext device object path.
5. Mount() — call org.freedesktop.UDisks2.Filesystem.Mount on the cleartext device. Returns the mount point path.
6. Unmount() + Lock() — reverse operations.

Key D-Bus details:

• Bus name: org.freedesktop.UDisks2
• Object paths: /org/freedesktop/UDisks2/block_devices/<name>
• Interfaces: org.freedesktop.UDisks2.Encrypted (Unlock, Lock), org.freedesktop.UDisks2.Filesystem (Mount, Unmount), org.freedesktop.UDisks2.Block (device properties, UUID lookup)

cryptsetup fallback (FIDO2 + TPM2)

udisks2 does not support FIDO2/TPM2 token-based keyslots. For these, fall back to invoking cryptsetup (via doas/sudo):

• FIDO2: cryptsetup open --token-type systemd-fido2 <device> <name>
• TPM2: cryptsetup open --token-type systemd-tpm2 <device> <name>
• --token-only can attempt all enrolled tokens automatically.

After cryptsetup open, mount via udisks2 D-Bus or plain mount.

Unlock method sequencing

Each device has an ordered list of methods to try. The unlock logic walks the list in order, stopping at the first success:

1. Try the first method (e.g., fido2).
2. If it fails (device not plugged in, timeout, etc.), try the next.
3. Continue until one succeeds or all are exhausted.

Default when no config exists: [passphrase].

Phase 2: Config File

Build internal/config/:

1. Load ~/.config/arca/config.yaml (respect $XDG_CONFIG_HOME).
2. Resolve an alias to a UUID and unlock methods.
3. If no config file exists, that's fine — device path arguments still work with the default method sequence [passphrase].

Config schema:

devices:
  backup:
    uuid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    mountpoint: "/mnt/backup"        # optional
    methods:                         # optional, default: [passphrase]
      - fido2
      - passphrase
  media:
    uuid: "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
    methods:
      - keyfile
      - passphrase
    keyfile: "/path/to/media.key"    # required if keyfile is in methods

Supported methods: passphrase, keyfile, fido2, tpm2.

Phase 3: CLI Commands

Wire up cobra subcommands:

arca mount <device|alias>

1. Resolve argument: if it matches a config alias, look up UUID and methods list; otherwise treat as a device path with default methods.
2. Find the block device via udisks2.
3. Walk the methods list in order, attempting each unlock strategy:
   • passphrase / keyfile: via udisks2 D-Bus (no root).
   • fido2 / tpm2: via cryptsetup CLI (requires doas/sudo).
   • Stop at the first success; if all fail, report each error.
4. Mount the resulting cleartext device via udisks2.
5. Print the mount point.

arca unmount <device|alias>

1. Resolve argument to the LUKS block device.
2. Find the associated cleartext (mapped) device.
3. Call Unmount on the cleartext device.
4. Call Lock on the LUKS device.

arca status

1. Enumerate all block devices with the Encrypted interface.
2. For each, check if unlocked (has a cleartext device).
3. If mounted, show mount point.
4. Print a table: device, UUID, alias (if configured), state, mount point.

Phase 4: Credential Input

• Passphrase: read from terminal with echo disabled (golang.org/x/term). Alternatively, accept from stdin for scripting.
• Keyfile: read path from config, pass contents to udisks2.
• FIDO2: cryptsetup handles the token interaction (tap prompt comes from libfido2).
• TPM2: cryptsetup handles TPM unsealing automatically.

Phase 5: Packaging

• flake.nix with buildGoModule.
• Add as a flake input to the NixOS config repo.

Open Questions

• Should mount accept a --mountpoint flag to override the default?
• Should there be a --dry-run flag that shows what D-Bus calls would be made?
• Is there value in a --json output flag for status?