secrets

Documentation

Overview

Package secrets — rotation scheduling, dual-key windows, and expiry alerts.

Package secrets implements encrypted secrets management for nSelf projects using age encryption (https://age-encryption.org).

Secrets are stored as age-encrypted JSON files per environment:

.secrets/dev.age, .secrets/staging.age, .secrets/prod.age

Each file encrypts to one or more age recipients (public keys), allowing team-based access control.

Index

• Constants
• func AddSchedule(projectRoot, secretName string, cadenceDays, windowDays int) error
• func AppendRotationEvent(projectRoot, secretName, status, note string) error
• func DecryptForDeploy(projectRoot, env string) (string, error)
• func EnsureAgeInstalled() error
• func Get(projectRoot, env, key string) (string, error)
• func GetPublicKey(keyPath string) (string, error)
• func Init(projectRoot string) error
• func InitSchedules(projectRoot string) error
• func List(projectRoot, env string) ([]string, map[string]SecretEntry, error)
• func Rekey(projectRoot, removePubKey string) error
• func RetireOldKey(projectRoot, env, key string) error
• func Rotate(projectRoot, env, key string) (string, error)
• func RotateDualWindow(projectRoot, env, key string) error
• func SaveRotationState(projectRoot string, state *RotationState) error
• func Set(projectRoot, env, key, value string) error
• func VerifySecretExists(projectRoot, env, secretName string) error
• type AuditFinding
  • func Audit(projectRoot, env string) ([]AuditFinding, error)
• type LintFinding
  • func LintSecrets(projectRoot string) ([]LintFinding, error)
• type RotationLog
  • func LoadRotationLog(projectRoot string) (*RotationLog, error)
• type RotationLogEntry
• type RotationSchedule
  • func DefaultSchedules() []RotationSchedule
• type RotationState
  • func LoadRotationState(projectRoot string) (*RotationState, error)
• type ScheduleCheck
  • func CheckSchedule(projectRoot string) ([]ScheduleCheck, error)
• type SecretEntry
• type SecretStore

Constants

const SecretsDir = ".secrets"

SecretsDir is the directory name under the project root.

Functions

func AddSchedule

func AddSchedule(projectRoot, secretName string, cadenceDays, windowDays int) error

AddSchedule adds or updates a named rotation schedule entry.

func AppendRotationEvent

func AppendRotationEvent(projectRoot, secretName, status, note string) error

AppendRotationEvent adds a rotation event to the log.

func DecryptForDeploy

func DecryptForDeploy(projectRoot, env string) (string, error)

DecryptForDeploy decrypts secrets and outputs them as KEY=VALUE lines suitable for .env.computed or CI/CD injection.

func EnsureAgeInstalled

func EnsureAgeInstalled() error

EnsureAgeInstalled checks that the age CLI is available.

func Get

func Get(projectRoot, env, key string) (string, error)

Get retrieves a secret value.

func GetPublicKey

func GetPublicKey(keyPath string) (string, error)

GetPublicKey extracts the public key from an age key file.

func Init

func Init(projectRoot string) error

Init generates an age keypair if one does not exist and sets up the .secrets directory with a .gitignore.

func InitSchedules

func InitSchedules(projectRoot string) error

InitSchedules ensures all default schedules are present in the rotation state, computing NextDue from LastRotated or setting to now if never rotated.

func List

func List(projectRoot, env string) ([]string, map[string]SecretEntry, error)

List returns all secret keys with metadata for an environment.

func Rekey

func Rekey(projectRoot, removePubKey string) error

Rekey re-encrypts all secret files, removing the specified public key from the recipients list. Used when a team member leaves.

func RetireOldKey

func RetireOldKey(projectRoot, env, key string) error

RetireOldKey removes the _PREVIOUS variant of a secret after the dual-key window.

func Rotate

func Rotate(projectRoot, env, key string) (string, error)

Rotate generates a new value for a secret based on its type/name pattern.

func RotateDualWindow

func RotateDualWindow(projectRoot, env, key string) error

RotateDualWindow generates a new key while keeping the old one as _PREVIOUS. The current value moves to KEY_PREVIOUS, and a new value is set as KEY_CURRENT.

func SaveRotationState

func SaveRotationState(projectRoot string, state *RotationState) error

SaveRotationState persists the rotation schedule state to disk.

func Set

func Set(projectRoot, env, key, value string) error

Set adds or updates a secret.

func VerifySecretExists

func VerifySecretExists(projectRoot, env, secretName string) error

VerifySecretExists checks whether a named secret is present in the store for an environment. It returns nil when the secret is found; an error when it is missing or the store cannot be read. This provides a lightweight "verify" surface (value check without decrypting to stdout).

Types

type AuditFinding

type AuditFinding struct {
	Key      string
	Issue    string
	Severity string
}

AuditFinding represents a single audit finding.

func Audit

func Audit(projectRoot, env string) ([]AuditFinding, error)

Audit checks for secrets that haven't been rotated in over 90 days.

type LintFinding

type LintFinding struct {
	File    string `json:"File"`
	Rule    string `json:"RuleID"`
	Message string `json:"Description"`
	Line    int    `json:"StartLine"`
}

LintFinding represents a detected secret in source code.

func LintSecrets

func LintSecrets(projectRoot string) ([]LintFinding, error)

LintSecrets checks for plaintext secrets in git-tracked files.

type RotationLog

type RotationLog struct {
	Events    []RotationLogEntry `json:"events"`
	UpdatedAt string             `json:"updated_at"`
}

RotationLog represents all recorded rotation events.

func LoadRotationLog

func LoadRotationLog(projectRoot string) (*RotationLog, error)

LoadRotationLog reads the rotation event log from disk.

type RotationLogEntry

type RotationLogEntry struct {
	SecretName string `json:"secret_name"`
	RotatedAt  string `json:"rotated_at"`
	Status     string `json:"status"` // ok|failed|rolled_back
	Note       string `json:"note,omitempty"`
}

RotationLogEntry is a single event in the rotation event log.

type RotationSchedule

type RotationSchedule struct {
	SecretName  string `json:"secret_name"`
	CadenceDays int    `json:"cadence_days"`
	WindowDays  int    `json:"window_days"` // dual-key overlap window
	LastRotated string `json:"last_rotated,omitempty"`
	NextDue     string `json:"next_due,omitempty"`
}

RotationSchedule defines when and how a secret should be rotated.

func DefaultSchedules

func DefaultSchedules() []RotationSchedule

DefaultSchedules returns the minimum set of tracked secrets per the spec.

type RotationState

type RotationState struct {
	Schedules []RotationSchedule `json:"schedules"`
	UpdatedAt string             `json:"updated_at"`
}

RotationState is the persisted state for all tracked secret schedules.

func LoadRotationState

func LoadRotationState(projectRoot string) (*RotationState, error)

LoadRotationState reads the rotation schedule state from disk.

type ScheduleCheck

type ScheduleCheck struct {
	SecretName  string        `json:"secret_name"`
	CadenceDays int           `json:"cadence_days"`
	WindowDays  int           `json:"window_days"`
	LastRotated string        `json:"last_rotated"`
	NextDue     string        `json:"next_due"`
	DueIn       time.Duration `json:"-"`
	DueInDays   int           `json:"due_in_days"`
	Status      string        `json:"status"` // ok, warning, overdue, missing
}

ScheduleCheck represents the result of checking one secret's rotation schedule.

func CheckSchedule

func CheckSchedule(projectRoot string) ([]ScheduleCheck, error)

CheckSchedule validates all rotation schedules and returns findings.

type SecretEntry

type SecretEntry struct {
	Value     string `json:"value"`
	CreatedAt string `json:"created_at"`
	UpdatedAt string `json:"updated_at"`
	RotatedAt string `json:"rotated_at,omitempty"`
}

SecretEntry represents a single secret with metadata.

type SecretStore

type SecretStore struct {
	Secrets    map[string]SecretEntry `json:"secrets"`
	Recipients []string               `json:"recipients"`
	UpdatedAt  string                 `json:"updated_at"`
}

SecretStore is the full set of secrets for one environment.