rewraptask

package
v0.0.0-...-df0d7b6 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: AGPL-3.0 Imports: 22 Imported by: 0

Documentation

Overview

Package rewraptask re-seals a check's sealed secrets for the current recipients of its private regions, on an agent that can open them (spec 2026-11-10-03, peer re-wrap).

A new agent in a per-agent region, or a region key rotation, leaves every sealed blob of the region flagged needsReseal. The server cannot open those blobs, so it sends one worker_tasks row of kind "rewrap" per check, targeted at one online agent that is a recipient of the blob. The agent opens the blob with its own key or a region key it holds, seals the plaintext to the recipient list the server sent, and returns only the new ciphertext. The server validates it like a sealedSecrets write and stores it, keeping the blob's origin. The server relays ciphertext only.

Two checks keep an agent from replacing a blob it cannot open (spec 2026-11-11-02):

  • possession: the task carries a random value sealed to the one key the agent was picked for (its own, or a region key it advertises). The agent sends it back with the new ciphertext; the server keeps only its hash and refuses a result without it;
  • confirmation: before the swap, a second online agent holding a current recipient key opens the new blob (a "rewrap_verify" task, with its own possession challenge), checks it carries only secret fields of the check type (and the same plaintext as the old blob when it can open that one too), and answers. With no second holder online, the blob is stored marked unconfirmed, and the check stays flagged.

One task per check keeps a payload under 100 KiB (a blob is at most 64 KiB of age file, base64-encoded), far below the 1 MiB request and 4 MiB claim caps of the worker task transport: nothing needs chunking.

Index

Constants

View Source
const (
	// Kind is the worker_tasks.kind of a re-wrap.
	Kind = "rewrap"
	// Capability is what an agent running the executor reports. The server
	// only targets agents reporting it: an older agent would never claim.
	Capability = "rewrap"
	// VerifyKind is the worker_tasks.kind of the confirmation of a re-wrap
	// by a second agent.
	VerifyKind = "rewrap_verify"
	// VerifyCapability is what an agent running the confirmation reports.
	VerifyCapability = "rewrap-verify"
)

Names of the kind.

View Source
const (
	// CodeCannotOpen is a blob none of the agent's keys opens.
	CodeCannotOpen = "REWRAP_CANNOT_OPEN"
	// CodeInvalidInput is a malformed task input.
	CodeInvalidInput = "REWRAP_INVALID_INPUT"
	// CodeSealFailed is a recipient list the agent could not seal to.
	CodeSealFailed = "REWRAP_SEAL_FAILED"
	// CodeNotSecret is a plaintext carrying a key that is not a secret field
	// of the check type, or bound to another target: never re-sealed nor
	// confirmed.
	CodeNotSecret = "REWRAP_NOT_SECRET"
	// CodeVerifyCannotOpen is a re-sealed blob the confirming agent cannot
	// open with its current key.
	CodeVerifyCannotOpen = "REWRAP_VERIFY_CANNOT_OPEN"
	// CodeVerifyMismatch is a re-sealed blob whose plaintext differs from the
	// old blob's.
	CodeVerifyMismatch = "REWRAP_VERIFY_MISMATCH"
)

Codes an agent finishes a refused re-wrap with.

View Source
const (
	// CodeInvalidResult is a returned blob that fails validation (stanza
	// count, size, encoding), or a result without the possession challenge.
	CodeInvalidResult = "invalid_result"
	// CodeNoProvableKey is a check whose online key holders all hold it by
	// a region key the server has no public key for (rotated away before
	// the server kept retired keys): none can prove it holds it.
	CodeNoProvableKey = "no_provable_key"
	// CodeNotConfirmed is the outcome code of a re-wrap stored without a
	// second agent to confirm it: done, but the check stays flagged.
	CodeNotConfirmed = "not_confirmed"
	// CodeRecipientsChanged is a returned blob sealed to a recipient set that
	// is not (or no longer) the current one.
	CodeRecipientsChanged = "recipients_changed"
	// CodeCheckChanged is a check whose blob changed while the re-wrap ran.
	CodeCheckChanged = "check_changed"
	// CodeTimedOut is a re-wrap no agent finished within Timeout.
	CodeTimedOut = "timed_out"
	// CodeNoOnlineRecipient is a check no online agent can open.
	CodeNoOnlineRecipient = "no_online_recipient"
	// CodeRewrapNotOffered is a check an online agent could open, but none of
	// those agents runs the re-wrap: older than 0.48 (no possession
	// challenge, spec 2026-11-11-02), or its operator set
	// SP_AGENT_REWRAP_ENABLED=false (spec 2026-11-10-04).
	CodeRewrapNotOffered = "rewrap_not_offered"
	// CodeNotSealed is a check without a sealed blob to re-wrap.
	CodeNotSealed = "not_sealed"
	// CodeUpToDate is a check already sealed to the current recipients.
	CodeUpToDate = "up_to_date"
	// CodeNoRecipients is a check whose regions have nothing to seal to.
	CodeNoRecipients = "no_recipients"
	// CodeAlreadyRunning is a check with another active worker task.
	CodeAlreadyRunning = "already_running"
)

Codes the server writes on a failed re-wrap, and reasons it reports for a check it could not start one for.

View Source
const Timeout = 5 * time.Minute

Timeout is how long a re-wrap may stay pending or claimed before it is reported (and recorded) as timed out.

Variables

This section is empty.

Functions

This section is empty.

Types

type Deps

type Deps struct {
	DB    db.Service
	Tasks *workertasks.Service
}

Deps are what the server side of the kind needs.

type Executor

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

Executor is the agent side of the re-wrap kind.

func NewExecutor

func NewExecutor(identities func() []string) *Executor

NewExecutor builds the executor over the agent's age identities: its own key, then the shared region keys it holds.

func (*Executor) Capability

func (*Executor) Capability() string

Capability implements tasks.Executor.

func (*Executor) Kind

func (*Executor) Kind() string

Kind implements tasks.Executor.

func (*Executor) Run

func (e *Executor) Run(ctx context.Context, claim *workertasks.Claim, rep tasks.Reporter) error

Run implements tasks.Executor: prove possession, open the blob, check its plaintext, seal it to the new list, return the new ciphertext and the opened challenge only. A blob the agent cannot open finishes with CodeCannotOpen: the server reports it, retrying cannot help.

type Input

type Input struct {
	Envelope   string         `json:"envelope"`
	Recipients []string       `json:"recipients"`
	Challenge  string         `json:"challenge,omitempty"`
	CheckType  string         `json:"checkType,omitempty"`
	Config     map[string]any `json:"config,omitempty"`
}

Input is the claim input: the sealed blob, the recipients to seal to, the possession challenge, and the check's type and public config (to refuse a plaintext that is not only secret fields of the type).

type Outcome

type Outcome struct {
	CheckUID  string `json:"checkUid"`
	TaskUID   string `json:"taskUid,omitempty"`
	AgentUID  string `json:"agentUid,omitempty"`
	AgentName string `json:"agentName,omitempty"`
	// Status is the worker task's status (models.WorkerTaskStatus), or
	// "refused" when no re-wrap could be started.
	Status    string `json:"status"`
	ErrorCode string `json:"errorCode,omitempty"`
}

Outcome is the state of one check's re-wrap, as the API reports it.

type Result

type Result struct {
	CT           string   `json:"ct,omitempty"`
	Fingerprints []string `json:"fingerprints,omitempty"`
	Challenge    string   `json:"challenge,omitempty"`
	ErrorCode    string   `json:"errorCode,omitempty"`
}

Result is the finish body: the new ciphertext, its fingerprints and the opened challenge, or the code of a refusal.

type Server

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

Server is the server side of the re-wrap kind.

func Register

func Register(deps Deps) *Server

Register registers the re-wrap kind on deps.Tasks and returns its server side.

func (*Server) Start

func (s *Server) Start(ctx context.Context, orgUID string, checks []*models.Check) ([]Outcome, error)

Start sends one re-wrap per check to an online agent that can open its blob. A check that cannot get one is reported with its reason, and keeps its blob and its flag.

func (*Server) Status

func (s *Server) Status(ctx context.Context, orgUID string, checkUIDs []string) ([]Outcome, error)

Status returns the latest re-wrap of each of the checks started within the last hour (every check of the org with one when checkUIDs is empty).

type VerifyExecutor

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

VerifyExecutor is the agent side of the confirmation of a re-wrap: it opens the re-sealed blob with its current key and answers whether it passes.

func NewVerifyExecutor

func NewVerifyExecutor(identities func() []string) *VerifyExecutor

NewVerifyExecutor builds the confirmation executor over the agent's age identities.

func (*VerifyExecutor) Capability

func (*VerifyExecutor) Capability() string

Capability implements tasks.Executor.

func (*VerifyExecutor) Kind

func (*VerifyExecutor) Kind() string

Kind implements tasks.Executor.

func (*VerifyExecutor) Run

Run implements tasks.Executor: prove possession, open the re-sealed blob, check it carries only secret fields of the type, and, when this agent can open the old blob too, the same plaintext. Answers with the opened challenge only: the plaintext never leaves the agent.

type VerifyInput

type VerifyInput struct {
	Envelope  string         `json:"envelope"`
	Previous  string         `json:"previous,omitempty"`
	Challenge string         `json:"challenge"`
	CheckType string         `json:"checkType,omitempty"`
	Config    map[string]any `json:"config,omitempty"`
}

VerifyInput is the claim input of a confirmation: the re-sealed blob, the blob it replaces, the confirming agent's possession challenge, and the check's type and public config.

type VerifyResult

type VerifyResult struct {
	Challenge string `json:"challenge,omitempty"`
	ErrorCode string `json:"errorCode,omitempty"`
}

VerifyResult is the finish body of a confirmation: the opened challenge (the blob opened and passed), or the code of a refusal.

Jump to

Keyboard shortcuts

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