signingcli

package module
v0.7.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 31 Imported by: 3

README

signing-cli

gitlab.com/phpboyscout/go/signing-cli provides the shareable sign and keys Cobra command builders that sit on top of gitlab.com/phpboyscout/go/signing.

The real signing and verification logic lives in go/signing; this module owns only the command surface, so both go-tool-base and the standalone sigillum CLI can attach the same commands without a dependency cycle.

Install

This is a library, so there is no binary to install. Add it as a dependency of the CLI you are building:

go get gitlab.com/phpboyscout/go/signing-cli

Then attach the command builders to your Cobra root (see below). It never depends on go-tool-base: its direct dependencies are go/signing, Cobra and pflag, go-crypto, and two small toolkit modules, go/errors and go/errorhandling.

Commands

Constructor Command Purpose
NewCmdSign(log) sign <input-file> Produce a detached signature over a file using a configured backend: armored OpenPGP, or prehashed minisign for release artefacts.
NewCmdKeys(log) keys Parent group for the key-management subcommands below.
NewCmdKeysMint(log) keys mint Wrap an existing signer (KMS or local PEM) in OpenPGP framing and emit the armored public half.
NewCmdKeysGenerate(log) keys generate Generate a fresh keypair locally (Ed25519 or RSA) and emit both halves.
NewCmdKeysWKD(log) keys wkd Generate a Web Key Directory tree from one or more public keys.
NewCmdKeysMinisign(log) keys minisign Emit the minisign public key for an Ed25519 signer: the string release consumers pin.
NewCmdKeysPublish(log) keys publish Stage a minisign public key into a keys site, with a machine-readable manifest.

Every constructor returns a plain *cobra.Command and takes a single signingcli.Logger argument, a minimal four-method logging interface (Debug/Info/Warn/Error) that both a *slog.Logger and go-tool-base's logger.Logger satisfy structurally, so callers pass their logger directly with no adapter.

Backends

Signing backends (AWS KMS, local PEM, …) are registered in the go/signing registry by blank-imports in the consumer's main package. This module deliberately imports no concrete backend. The commands surface whatever backends the host binary compiled in via signing.Names() / signing.Get().

import (
	_ "gitlab.com/phpboyscout/go/signing-aws-kms" // registers "aws-kms"
	_ "gitlab.com/phpboyscout/go/signing/local"   // registers "local"

	signingcli "gitlab.com/phpboyscout/go/signing-cli"
)

root.AddCommand(signingcli.NewCmdSign(logger))
root.AddCommand(signingcli.NewCmdKeys(logger))

--backend also accepts a named instance with inline settings, such as --backend 'aws-kms:prod?kms-region=eu-west-1', for a binary that needs two configurations of the same backend. The grammar and its rules are in the sign reference.

Documentation

License

MIT. See LICENSE.

Documentation

Overview

Package signingcli provides the shareable `sign` and `keys` Cobra commands over gitlab.com/phpboyscout/go/signing. Real signing/verification logic lives in go/signing; this module owns only the command surface so GTB and the standalone `sigillum` CLI can both attach it without a cycle.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrKeyAlreadyPublished is returned when a key is already
	// published at the same path with different content. Published keys
	// are add-only: consumers pin them, so changing one under a
	// consumer's feet is exactly what must never happen.
	ErrKeyAlreadyPublished = errors.NewSentinel("signing-cli.key_already_published", "a different key is already published at this path")

	// ErrInvalidProject is returned when --project is not a safe path
	// segment.
	ErrInvalidProject = errors.NewSentinel("signing-cli.invalid_project", "project name must be lowercase alphanumeric with dots, dashes or underscores")

	// ErrInvalidStatus is returned when --status is not one of the
	// known lifecycle states.
	ErrInvalidStatus = errors.NewSentinel("signing-cli.invalid_status", "unknown status")
)
View Source
var ErrKeyFileExists = errors.NewSentinel("signing-cli.key_file_exists", "output file already exists")

ErrKeyFileExists is returned when a key output file already exists and --force was not supplied. Overwriting a private key in place could silently destroy the only copy of a signing key, so the default is to refuse.

Functions

func NewCmdKeys

func NewCmdKeys(log Logger) *cobra.Command

NewCmdKeys returns the top-level `keys` command group with its subcommands attached, including any a signature format registered.

func NewCmdKeysGenerate

func NewCmdKeysGenerate(log Logger) *cobra.Command

NewCmdKeysGenerate returns the `keys generate` subcommand. Generates a fresh keypair entirely in-process (no shell-out, no external dependencies) and writes both halves to disk. Used during onboarding for the rotation-authority key and the tutorial / local signing key.

func NewCmdKeysMinisign added in v0.2.0

func NewCmdKeysMinisign(log Logger) *cobra.Command

NewCmdKeysMinisign returns the `keys minisign` subcommand: emit the minisign public key for an Ed25519 signer.

This is the counterpart to `keys mint`, which emits an armored OpenPGP public key. The consumers of an artefact signature do not speak OpenPGP, so they need this form instead.

func NewCmdKeysMint

func NewCmdKeysMint(log Logger) *cobra.Command

NewCmdKeysMint returns the `keys mint` subcommand. Wraps an existing signer (KMS or local PEM file) in OpenPGP framing and writes the armored public half to a file.

func NewCmdKeysPublish added in v0.3.0

func NewCmdKeysPublish(log Logger) *cobra.Command

NewCmdKeysPublish returns the `keys publish` subcommand.

func NewCmdKeysWKD

func NewCmdKeysWKD(log Logger) *cobra.Command

NewCmdKeysWKD returns the `keys wkd` subcommand. Reads one or more armored OpenPGP public keys and emits a Web Key Directory tree (per draft-koch-openpgp-webkey-service §3.1) ready to upload to a static host.

Spec: https://gitlab.com/phpboyscout/go-tool-base/-/wikis/specs/0069-keys-wkd-command

func NewCmdSign

func NewCmdSign(log Logger) *cobra.Command

NewCmdSign returns the top-level `sign` command, with a --format lane for each registered signature format and any command a format attaches beneath it.

func RegisterBackendFlags added in v0.7.0

func RegisterBackendFlags(fs *pflag.FlagSet)

RegisterBackendFlags adds the flags of every compiled-in backend that has its own, such as aws-kms's --kms-region, to fs. A format command that takes --backend calls it so its backends are configured as sign's are.

func RegisterKeysCommand added in v0.7.0

func RegisterKeysCommand(ctor CommandConstructor)

RegisterKeysCommand attaches a command under keys, such as a format's own key generator. Call it from init().

func RegisterSignCommand added in v0.7.0

func RegisterSignCommand(ctor CommandConstructor)

RegisterSignCommand attaches a command under sign, such as sign image. Call it from init().

func RegisterSignLane added in v0.7.0

func RegisterSignLane(lane SignLane)

RegisterSignLane adds a --format lane to the sign command. Call it from init().

Panics on an empty Format, a nil Sign, a Format already registered, or a second Default lane. Each is a programmer error that should never reach a deployed binary.

func ResolveSigner added in v0.7.0

func ResolveSigner(ctx context.Context, fs *pflag.FlagSet, selector, keyID string) (crypto.Signer, string, error)

ResolveSigner resolves a --backend selector and constructs its signer for keyID. fs is the flag set RegisterBackendFlags populated. The returned string identifies the backend in log lines.

Types

type CommandConstructor added in v0.7.0

type CommandConstructor func(log Logger) *cobra.Command

CommandConstructor builds a command a format attaches to the tree.

type Logger

type Logger interface {
	Debug(msg string, args ...any)
	Info(msg string, args ...any)
	Warn(msg string, args ...any)
	Error(msg string, args ...any)
}

Logger is the minimal logging surface the commands need. Both a *slog.Logger and GTB's logger.Logger satisfy it structurally, so callers pass their logger directly — no adapter.

type SignLane added in v0.7.0

type SignLane struct {
	// Format is the --format value that selects the lane.
	Format string

	// Summary describes what the lane writes, in the --format help.
	Summary string

	// Default makes the lane the --format default when several are
	// registered. At most one lane may set it.
	Default bool

	// Flags adds the flags only this lane uses. Choosing another lane while
	// one of them is set is refused. Nil when the lane has none.
	Flags func(fs *pflag.FlagSet)

	// Sign writes the signature. The lane reads its own flags from
	// cmd.Flags().
	Sign func(cmd *cobra.Command, log Logger, req SignRequest) error
}

SignLane is one --format value of the sign command.

type SignRequest added in v0.7.0

type SignRequest struct {
	Format  string
	Backend string
	KeyID   string
	Input   string
	Output  string
	Created string
}

SignRequest carries the flags every sign lane shares.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL