credentialfile

package
v0.12.0 Latest Latest
Warning

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

 Go to latest Published: Sep 12, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Overview

Package credentialfile implements offline encrypted vaults, sessions and maintenance. Composition roots inject prompting and explicitly own Runtime cleanup.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrUnsupported indicates an unimplemented platform, unavailable filesystem
	// operation or a directory crossing the vault's device/mount boundary.
	ErrUnsupported = errors.New("offline vault platform or required filesystem operation is unsupported")
	// ErrConflict indicates an immutable item already exists with a different value.
	ErrConflict = errors.New("offline credential item conflict")
	// ErrRevisionChanged indicates publication changed while unlocking.
	ErrRevisionChanged = errors.New("offline vault publication changed")
	// ErrMaintenanceRequired indicates unresolved maintenance or temporary state.
	ErrMaintenanceRequired = errors.New("offline vault requires maintenance recovery")
	// ErrKeyUsageExhausted prevents encryption after its durable reservation budget.
	ErrKeyUsageExhausted = errors.New("offline vault key usage exhausted")
	// ErrClosed indicates the file store has been closed.
	ErrClosed = errors.New("offline vault is closed")
	// ErrResourceBusy rejects admission beyond one running and eight queued KDF tasks.
	ErrResourceBusy = errors.New("offline KDF queue is full")
)

Functions

This section is empty.

Types

type CompatibilityReport 

type CompatibilityReport struct {
	Platform  string   `json:"platform"`
	Directory string   `json:"directory"`
	Checks    []string `json:"checks"`
}

CompatibilityReport describes an explicit disposable filesystem probe. It verifies operations, not resistance to physical power loss or future I/O stalls.

func ProbeCompatibility 

func ProbeCompatibility(ctx context.Context, path string) (report CompatibilityReport, err error)

ProbeCompatibility tests the actual target filesystem in a private scratch directory. Existing vaults are locked while probing; an absent target uses its parent. Credential contents and key files are never read or changed.

type DurabilityError 

type DurabilityError struct {
	Op      string
	Applied bool
	Durable bool
	Cause   error
}

DurabilityError preserves publication outcome for the named file operation. In particular Op="budget" describes a reservation, not a saved secret.

func (*DurabilityError) Error 

func (e *DurabilityError) Error() string

func (*DurabilityError) Unwrap 

func (e *DurabilityError) Unwrap() error

Unwrap preserves cancellation and underlying I/O classifications.

type Inspection 

type Inspection struct {
	Limit         uint64  `json:"limit"`
	Version       uint16  `json:"version"`
	Suite         string  `json:"suite"`
	Revision      uint64  `json:"revision"`
	Generation    uint64  `json:"generation"`
	Unlock        string  `json:"unlock"`
	Authenticated bool    `json:"authenticated"`
	OperationID   string  `json:"operation_id,omitempty"`
	NeedsSource   bool    `json:"needs_source,omitempty"`
	Consumed      *uint64 `json:"consumed,omitempty"`
}

Inspection contains bounded public metadata; Authenticated marks verified data.

type KeySource 

type KeySource interface {
	Unlock(ctx context.Context, metadata []byte) ([]byte, error)
}

KeySource must authenticate the complete metadata (including its wrapping tag) before returning an independently owned 32-byte DEK. The store clears that copy. Unlock is called without any vault lock and must honor cancellation/deadlines. Nil is fail-closed. Stage C supplies the process-owned session implementation.

type LayoutPresence 

type LayoutPresence struct{ Vault, Key bool }

LayoutPresence is a read-only snapshot, never authorization to initialize. Actual writes must repeat validation under the native vault lock.

func InspectLayout 

func InspectLayout(ctx context.Context, vaultPath, keyPath string) (LayoutPresence, error)

InspectLayout checks both paths without following symlinks or creating files. Existing vault contents must still be inspected using Store.Inspect.

type MaintenanceResult 

type MaintenanceResult struct {
	OperationID string       `json:"operation_id"`
	Revision    uint64       `json:"revision"`
	Generation  uint64       `json:"generation"`
	Stage       format.Stage `json:"stage"`
	Applied     bool         `json:"applied"`
	Durable     bool         `json:"durable"`
	// Changed reports cleanup deletions; Applied reports CURRENT publication only.
	Changed bool `json:"changed"`
}

MaintenanceResult reports publication separately from journal/finalization errors.

type Options 

type Options struct {
	Keys          KeySource
	ReadOnly      bool
	Timeout       time.Duration
	UnlockTimeout time.Duration
}

Options configures file operations without introducing terminal interaction.

type PromptProvider 

type PromptProvider interface {
	Password(context.Context, string) ([]byte, error)
}

PromptProvider owns presentation; returned password bytes transfer to Runtime. Implementations must honor cancellation and never log supplied material.

type PruneResult 

type PruneResult struct {
	Revisions   []uint64
	Maintenance MaintenanceResult
}

PruneResult contains the authenticated obsolete revisions selected under the lock. At most 256 are processed per call; subsequent plans select the next batch.

type Runtime 

type Runtime struct {
	// contains filtered or unexported fields
}

Runtime owns process-local sessions, KDF admission and all opened Store handles. A composition root must share one Runtime and wait for Close before exiting.

func NewRuntime 

func NewRuntime(ctx context.Context, prompt PromptProvider, derive kdfhelper.Deriver) *Runtime

NewRuntime defaults to the current-binary process runner; nil prompt fails closed.

func (*Runtime) Close 

func (r *Runtime) Close() error

Close cancels all tasks and leases and waits for files, timers and workers.

func (*Runtime) EnsureInitialized 

func (r *Runtime) EnsureInitialized(ctx context.Context, path, id string, target Wrapping) (MaintenanceResult, error)

EnsureInitialized prepares an empty store for a write or reuses a published store. Existing CURRENT is checked under the vault lock before key creation. Incomplete transactions require explicit recovery; no material is replaced.

func (*Runtime) Init 

func (r *Runtime) Init(ctx context.Context, path, id string, target Wrapping) (MaintenanceResult, error)

Init creates only an absent or empty private root. It never overwrites an existing vault.

func (*Runtime) OpenStore 

func (r *Runtime) OpenStore(ctx context.Context, path, id string, options Options, sessionOptions SessionOptions) (*Store, error)

OpenStore joins the physical vault session without holding Runtime's map lock over I/O.

type SessionOptions 

type SessionOptions struct {
	Mode           string
	KeyFile        string
	IdleTTL        time.Duration
	CacheTTL       time.Duration
	PromptTimeout  time.Duration
	UnlockTimeout  time.Duration
	NonInteractive bool
}

SessionOptions fixes the policy shared by all handles of one physical vault.

type Store 

type Store struct {
	// contains filtered or unexported fields
}

Store owns a verified root handle. Close cancels and waits for active operations. It has no secret cache or background unlock worker and is not registered yet.

func Open 

func Open(ctx context.Context, path, storeID string, options Options) (*Store, error)

Open opens an existing private vault on Linux amd64. The caller selects storage with reliable locking, atomic publication and sync semantics. It never creates directories, keys, locks or configuration. ctx governs the store's lifetime.

func (*Store) Clone 

func (s *Store) Clone(ctx context.Context, path, id string, target Wrapping) (MaintenanceResult, error)

Clone creates an independent vault, preserving ItemIDs under the explicit target StoreID.

func (*Store) Close 

func (s *Store) Close() error

Close is waitable and idempotent; it does not return before active I/O is reaped.

func (*Store) Delete 

func (s *Store) Delete(ctx context.Context, ref credential.Ref) error

Delete assumes the credential service has durably removed all configuration references. It authenticates the target, is idempotent, and never refunds budget.

func (*Store) Get 

func (s *Store) Get(ctx context.Context, ref credential.Ref) (secret credential.Secret, err error)

Get reads only the requested authenticated item; no metadata load decrypts all items.

func (*Store) Inspect 

func (s *Store) Inspect(ctx context.Context, verify bool) (result Inspection, err error)

Inspect reads metadata without unlocking unless verify is explicitly requested.

func (*Store) Lock 

func (s *Store) Lock(ctx context.Context) error

Lock waits for this Store's shared session to revoke and reap all live leases. A canceled wait does not claim completion; Runtime still owns ongoing cleanup.

func (*Store) Prune 

func (s *Store) Prune(ctx context.Context, apply bool) (result PruneResult, err error)

Prune defaults to a read-only plan. Apply revalidates provenance and records intent.

func (*Store) Put 

func (s *Store) Put(ctx context.Context, ref credential.Ref, secret credential.Secret) error

Put is immutable and durable: equal value AND expiry succeeds, different data conflicts.

func (*Store) RecoveryNeedsSource 

func (s *Store) RecoveryNeedsSource(ctx context.Context) (needed bool, err error)

RecoveryNeedsSource inspects bounded public recovery hints, including targets without CURRENT. It only selects material acquisition; Resume authenticates and rechecks the operation before any mutation.

func (*Store) Reencrypt 

func (s *Store) Reencrypt(ctx context.Context, target Wrapping) (MaintenanceResult, error)

Reencrypt writes a complete new revision and DEK before switching CURRENT.

func (*Store) Restore 

func (s *Store) Restore(ctx context.Context, path string, target Wrapping, required []credential.Ref) (MaintenanceResult, error)

Restore copies a trusted stopped backup into a fresh root with a new DEK. required must contain the backup configuration's references to this StoreID. The caller owns the trusted backup/configuration selection; this method does not edit it.

func (*Store) Resume 

func (s *Store) Resume(ctx context.Context, source, target Wrapping) (MaintenanceResult, error)

Resume authenticates an existing maintenance task with explicitly supplied material. Both materials are needed before publication; an already-published task only needs target.

func (*Store) ResumeFrom 

func (s *Store) ResumeFrom(ctx context.Context, source *Store, sourceMaterial, targetMaterial Wrapping) (result MaintenanceResult, err error)

ResumeFrom resumes clone/restore with an explicit source handle, never a journal path.

func (*Store) ResumeOperation 

func (s *Store) ResumeOperation(ctx context.Context, id string, source *Store, from, to Wrapping) (MaintenanceResult, error)

ResumeOperation requires the named operation when nonempty, under recovery locks. source is explicit for clone/restore and must be s for single-root operations.

func (*Store) Rewrap 

func (s *Store) Rewrap(ctx context.Context, target Wrapping) (MaintenanceResult, error)

Rewrap copies authenticated ciphertext into a new revision with new wrapping material.

func (*Store) Unlock 

func (s *Store) Unlock(ctx context.Context) (err error)

Unlock explicitly unlocks this process's session without returning any secret. It does not create an IPC service or unlock another process.

type Wrapping 

type Wrapping struct {
	Mode     string
	Password []byte
	KeyFile  string
}

Wrapping supplies explicit maintenance material. Password is borrowed only for the call and never logged. New wrapping material may create a missing KeyFile as 32 random bytes with mode 0600; existing files are validated and reused. Unlock and resume require the original file. Published key files are never deleted.

Source Files

View all Source files

Directories

Path Synopsis
Package format implements the frozen v1 offline-vault binary formats.
 Package format implements the frozen v1 offline-vault binary formats.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.