sync

Documentation

Overview

Package sync provides vault synchronization with Sync Envelope encryption.

Index

• Constants
• func Checksum(data []byte) []byte
• func DeriveSyncKey(masterKey []byte) ([]byte, error)
• func ExtractKeyMetadata(vaultDBPath string) *domain.VaultMetadataPayload
• func FormatConflict(c *ConflictInfo) string
• func Open(syncKey, envelope []byte, projectID, environment string) ([]byte, error)
• func Seal(syncKey, plaintext []byte, projectID, environment string) ([]byte, error)
• type ConflictInfo
  • func DetectConflict(localVersion, remoteVersion int64) *ConflictInfo
• type ConflictStrategy
• type Engine
  • func NewEngine() *Engine
  • func (e *Engine) Pull(ctx context.Context, opts PullOptions) (*PullResult, error)
  • func (e *Engine) Push(ctx context.Context, opts PushOptions) (*PushResult, error)
• type MergeConflict
• type MergeResult
  • func ThreeWayMerge(base, local, remote []SecretEntry) *MergeResult
• type PullOptions
• type PullResult
• type PushOptions
• type PushResult
• type QueueEntry
• type SecretEntry
• type SyncQueue
  • func NewSyncQueue(projectDir string) *SyncQueue
  • func (q *SyncQueue) Clear() error
  • func (q *SyncQueue) Dequeue() (*QueueEntry, error)
  • func (q *SyncQueue) Enqueue(entry QueueEntry) error
  • func (q *SyncQueue) IsEmpty() bool
  • func (q *SyncQueue) List() ([]QueueEntry, error)

Constants

const (
	// SyncKeyPurpose is the HKDF purpose string for deriving the Sync Envelope key.
	SyncKeyPurpose = "tene-sync-envelope"
)

Functions

func Checksum

func Checksum(data []byte) []byte

Checksum returns the SHA-256 hash of data.

func DeriveSyncKey

func DeriveSyncKey(masterKey []byte) ([]byte, error)

DeriveSyncKey derives the L2 Sync Envelope encryption key from a master key.

func ExtractKeyMetadata

func ExtractKeyMetadata(vaultDBPath string) *domain.VaultMetadataPayload

ExtractKeyMetadata opens the local vault.db and extracts key name metadata for all environments. This metadata is sent alongside the encrypted blob so the dashboard can display key names without accessing values.

func FormatConflict

func FormatConflict(c *ConflictInfo) string

FormatConflict returns a human-readable description of the conflict.

func Open

func Open(syncKey, envelope []byte, projectID, environment string) ([]byte, error)

Open decrypts a Sync Envelope back to the original vault blob.

func Seal

func Seal(syncKey, plaintext []byte, projectID, environment string) ([]byte, error)

Seal encrypts a vault blob (vault.db bytes) into a Sync Envelope. The AAD binds the envelope to a specific project and environment.

Envelope binary format:

┌────────┬──────────┬─────────────────────────┬──────────────────┐
│ Header │  Nonce   │       Ciphertext        │      Tag         │
│ 8 bytes│ 24 bytes │     variable length     │    16 bytes      │
└────────┴──────────┴─────────────────────────┴──────────────────┘

Header: magic(4 bytes) + version(2 bytes) + reserved(2 bytes) AAD: projectID + ":" + environment

Types

type ConflictInfo

type ConflictInfo struct {
	LocalVersion  int64  `json:"local_version"`
	RemoteVersion int64  `json:"remote_version"`
	LocalHash     string `json:"local_hash"`
	RemoteHash    string `json:"remote_hash"`
}

ConflictInfo describes a version conflict between local and remote vaults.

func DetectConflict

func DetectConflict(localVersion, remoteVersion int64) *ConflictInfo

DetectConflict checks if a push would cause a version conflict. Returns nil if no conflict (local version matches expected remote version).

type ConflictStrategy

type ConflictStrategy int

ConflictStrategy defines how to resolve sync conflicts.

const (
	// StrategyServerWins pulls remote first, merges, then pushes (default).
	StrategyServerWins ConflictStrategy = iota
	// StrategyForcePush overwrites remote with local.
	StrategyForcePush
	// StrategyForcePull overwrites local with remote.
	StrategyForcePull
)

type Engine

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

Engine orchestrates vault sync operations.

func NewEngine

func NewEngine() *Engine

NewEngine creates a new sync engine.

func (*Engine) Pull

func (e *Engine) Pull(ctx context.Context, opts PullOptions) (*PullResult, error)

Pull downloads and decrypts the remote vault blob.

func (*Engine) Push

func (e *Engine) Push(ctx context.Context, opts PushOptions) (*PushResult, error)

Push encrypts the local vault.db into a Sync Envelope and uploads it.

type MergeConflict

type MergeConflict struct {
	Key         string       `json:"key"`
	Env         string       `json:"env"`
	BaseValue   *SecretEntry `json:"base,omitempty"`
	LocalValue  *SecretEntry `json:"local"`
	RemoteValue *SecretEntry `json:"remote"`
}

MergeConflict represents a key where local and remote both changed differently.

type MergeResult

type MergeResult struct {
	// Merged is the final set of secrets after merge.
	Merged []SecretEntry `json:"merged"`
	// AutoResolved lists keys that were auto-merged without conflict.
	AutoResolved []string `json:"auto_resolved,omitempty"`
	// Conflicts lists keys that require manual resolution.
	Conflicts []MergeConflict `json:"conflicts,omitempty"`
}

MergeResult describes the outcome of a 3-way merge.

func ThreeWayMerge

func ThreeWayMerge(base, local, remote []SecretEntry) *MergeResult

ThreeWayMerge performs a 3-way merge of secrets.

Rules (per design spec §5.4):

Base=A, Local=B, Remote=A → use Local (only local changed)
Base=A, Local=A, Remote=B → use Remote (only remote changed)
Base=A, Local=B, Remote=C → CONFLICT (both changed differently)
Base=nil, Local=A, Remote=nil → use Local (local addition)
Base=nil, Remote=A, Local=nil → use Remote (remote addition)
Base=A, Local=nil, Remote=B → CONFLICT (local deleted, remote modified)
Base=A, Local=B, Remote=nil → CONFLICT (local modified, remote deleted)

type PullOptions

type PullOptions struct {
	APIBaseURL  string
	AccessToken string
	VaultID     string
	ProjectName string
	Environment string
	VaultDBPath string
	MasterKey   []byte
	Force       bool // --force-pull: overwrite local without merge
}

PullOptions configures a pull operation.

type PullResult

type PullResult struct {
	VaultID  string `json:"vault_id"`
	Version  int64  `json:"vault_version"`
	Hash     string `json:"vault_hash"`
	PulledAt string `json:"pulled_at"`
}

PullResult contains the result of a pull operation.

type PushOptions

type PushOptions struct {
	APIBaseURL  string
	AccessToken string
	VaultID     string
	ProjectName string
	Environment string
	VaultDBPath string
	MasterKey   []byte
	Force       bool // --force: skip conflict check
}

PushOptions configures a push operation.

type PushResult

type PushResult struct {
	VaultID  string `json:"vault_id"`
	Version  int64  `json:"vault_version"`
	Hash     string `json:"vault_hash"`
	Size     int    `json:"size"`
	PushedAt string `json:"pushed_at"`
}

PushResult contains the result of a push operation.

type QueueEntry

type QueueEntry struct {
	Action    string    `json:"action"` // "push" or "pull"
	VaultID   string    `json:"vault_id"`
	Project   string    `json:"project"`
	Env       string    `json:"env"`
	QueuedAt  time.Time `json:"queued_at"`
	VaultPath string    `json:"vault_path"`
}

QueueEntry represents a pending sync operation queued for offline retry.

type SecretEntry

type SecretEntry struct {
	Key       string `json:"key"`
	Value     []byte `json:"value"` // encrypted value
	Env       string `json:"env"`
	UpdatedAt int64  `json:"updated_at"` // unix timestamp
}

SecretEntry represents a single secret for merge comparison.

type SyncQueue

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

SyncQueue manages offline sync operations in .tene/sync_queue.json.

func NewSyncQueue

func NewSyncQueue(projectDir string) *SyncQueue

NewSyncQueue creates a queue backed by the project's .tene directory.

func (*SyncQueue) Clear

func (q *SyncQueue) Clear() error

Clear removes all entries from the queue.

func (*SyncQueue) Dequeue

func (q *SyncQueue) Dequeue() (*QueueEntry, error)

Dequeue removes the first entry from the queue.

func (*SyncQueue) Enqueue

func (q *SyncQueue) Enqueue(entry QueueEntry) error

Enqueue adds a sync operation to the offline queue.

func (*SyncQueue) IsEmpty

func (q *SyncQueue) IsEmpty() bool

IsEmpty returns true if the queue has no pending entries.

func (*SyncQueue) List

func (q *SyncQueue) List() ([]QueueEntry, error)

List returns all pending queue entries.