JuliusBrussee/caveman · error

envelope: open: %w

Error message

envelope: open: %w

What it means

Fires in open() when gcm.Open fails — AES-GCM authentication rejected the ciphertext+AAD. The data key unwrapped fine, but the payload was modified, corrupted, or is being opened with different additional authenticated data (AAD/scope) than it was sealed with. GCM's tag check is the tamper detector, so this error almost always means integrity failure or AAD/scope mismatch.

Source

Thrown at shared/platform/envelope/envelope.go:163

	if err != nil {
		return nil, fmt.Errorf("envelope: unwrap data key: %w", err)
	}
	block, err := aes.NewCipher(dataKey)
	if err != nil {
		return nil, fmt.Errorf("envelope: aes: %w", err)
	}
	gcm, err := cipher.NewGCM(block)
	if err != nil {
		return nil, fmt.Errorf("envelope: gcm: %w", err)
	}
	ns := gcm.NonceSize()
	if len(ciphertext) < ns {
		return nil, fmt.Errorf("envelope: ciphertext too short")
	}
	nonce, ct := ciphertext[:ns], ciphertext[ns:]
	plaintext, err := gcm.Open(nil, nonce, ct, aad)
	if err != nil {
		return nil, fmt.Errorf("envelope: open: %w", err)
	}
	return plaintext, nil
}

func scopeAAD(scope Scope) ([]byte, string, error) {
	scope.OrganizationID = strings.TrimSpace(scope.OrganizationID)
	scope.ProjectID = strings.TrimSpace(scope.ProjectID)
	scope.Kind = strings.TrimSpace(scope.Kind)
	if scope.OrganizationID == "" {
		return nil, "", fmt.Errorf("envelope: organization scope is required")
	}
	if scope.Kind == "" {
		return nil, "", fmt.Errorf("envelope: object kind is required")
	}
	aad, err := json.Marshal(struct {
		Version        int    `json:"version"`
		OrganizationID string `json:"organization_id"`
		ProjectID      string `json:"project_id"`

View on GitHub (pinned to 766dce6b13)

Solutions

1. Verify the ciphertext bytes were not modified in storage or transit
2. Confirm the same AAD (scope org/project/kind) used at Seal time is supplied at Open time
3. Treat repeated failures as possible tampering and investigate the data source; re-seal from a trusted copy

When it happens

Trigger: Thrown at shared/platform/envelope/envelope.go:163 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of JuliusBrussee/caveman@766dce6b13 (2026-08-18). Data as JSON: /api/errors/0820862275b8091b. Report an issue: GitHub.