tokenseal

package
v0.74.0 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package tokenseal seals and opens a byte slice as an "enc:v1" envelope (AES-256-GCM, random 96-bit nonce, HKDF-derived record key and key id) for values stored at rest, such as the upstream OAuth records in config.db.

Envelope: enc:v1:<kid>:<base64(nonce[12] || ciphertext || tag[16])>

kid = 16 lower-case hex characters, derived from the configured key
AAD = "mcpproxy-oauth-token" 0x00 "v1" 0x00 kid 0x00 bucket 0x00 bucketKey

The AAD binds the version, the key id, the bucket and the bucket key, so an envelope copied under another key or bucket fails authentication.

The package is a leaf: it imports only the standard library (Spec 123, FR-006) and must stay that way so internal/storage can depend on it.

Index

Constants

View Source
const MaxPlaintextLen = 1 << 20

MaxPlaintextLen is the largest plaintext Seal accepts. An OAuth record is a few kilobytes of JSON; the bound keeps Seal's buffer sizes from overflowing.

Variables

View Source
var ErrContextNUL = errors.New("tokenseal: bucket and bucket key must not contain NUL")

ErrContextNUL is returned by Seal for a bucket or bucket key containing a NUL byte: the AAD is NUL-separated, so such a pair could collide with a different (bucket, key) pair.

View Source
var ErrInvalidKey = errors.New("is not a base64-encoded 32-byte key")

ErrInvalidKey is the only error ParseKey returns. Its text is fixed so that no input, path or reference can leak through it.

View Source
var ErrPlaintextTooLarge = errors.New("tokenseal: plaintext is larger than 1 MiB")

ErrPlaintextTooLarge is returned by Seal for a plaintext over MaxPlaintextLen.

Functions

This section is empty.

Types

type Key

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

Key is a configured sealing key. It has no exported field and never prints key material. A nil *Key means "no key configured".

func ParseKey

func ParseKey(b64 string) (*Key, error)

ParseKey parses a standard-alphabet base64 string (padding optional, surrounding whitespace ignored) that decodes to exactly 32 bytes.

func (*Key) GoString

func (k *Key) GoString() string

GoString implements fmt.GoStringer.

func (*Key) ID

func (k *Key) ID() string

ID returns the 16-hex-character key id, or "" for a nil key.

func (*Key) Open

func (k *Key) Open(bucket, bucketKey string, value []byte) ([]byte, error)

Open authenticates and decrypts an enc:v1 envelope. A nil key is allowed and yields ReasonNoKey for a well-formed envelope. Every failure is an *OpenError. Open does not accept plaintext values: callers Classify first.

func (*Key) Seal

func (k *Key) Seal(bucket, bucketKey string, plaintext []byte) ([]byte, error)

Seal returns the enc:v1 envelope for plaintext. A nil key is an error: a caller that wants plaintext must not call Seal.

func (*Key) String

func (k *Key) String() string

String and GoString keep %v / %+v / %#v / %s from printing anything but the key id.

type OpenError

type OpenError struct {
	Reason Reason
	RowKID string // kid found in the stored value's prefix ("" if none)
	KeyKID string // kid of the configured key ("" if none)
}

OpenError is the error Open returns. It carries key ids only, never key material or payload bytes.

func (*OpenError) Error

func (e *OpenError) Error() string

type Reason

type Reason string

Reason says why a value could not be opened.

const (
	ReasonNoKey              Reason = "no_key"
	ReasonKeyMismatch        Reason = "key_mismatch"
	ReasonAuthFailed         Reason = "auth_failed"
	ReasonUnsupportedVersion Reason = "unsupported_version"
	ReasonMalformed          Reason = "malformed"
)

Open failure reasons.

type Shape

type Shape int

Shape is the outer form of a stored value.

const (
	ShapeMalformed   Shape = iota // empty, unknown prefix or damaged enc:v1 header
	ShapePlaintext                // first byte '{' (a JSON object)
	ShapeSealedV1                 // enc:v1:<kid>:<payload>
	ShapeUnsupported              // enc:<other version>:...
)

Value shapes returned by Classify.

func Classify

func Classify(value []byte) (Shape, string)

Classify reports the shape of a stored value and, for ShapeSealedV1, the key id in its prefix. It does not decode the payload.

func (Shape) String

func (s Shape) String() string

Jump to

Keyboard shortcuts

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