sealedwebhook

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: MPL-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package sealedwebhook is the generic HTTPS push adapter. It delivers recipient-encrypted, signed envelopes to an instance-admin configured receiver (docs/spec/sealed-webhook.md) and accepts only acknowledgements signed by the pinned acknowledgement key and bound to the exact envelope.

Its provider interface can express exactly one operation, a POST of an envelope to the fixed protocol path. There is no read, no GET, and no callback: nothing a receiver returns can move the configured trust boundary.

Index

Constants

View Source
const (
	// MaxTimeout bounds one delivery round trip.
	MaxTimeout = 10 * time.Second
	// MaxResponseBytes bounds an acknowledgement body.
	MaxResponseBytes = sealedhook.MaxAck
)
View Source
const (
	ReasonUnauthorized  = "unauthorized"
	ReasonExistsUnowned = "exists_unowned"
)

Receiver reasons with a defined Hikyo meaning (docs/spec/sealed-webhook.md).

View Source
const ConnectionVersion = "sealed-webhook/v1"

ConnectionVersion is reported by TestConnection.

Variables

View Source
var (
	// ErrNoAck marks a delivery whose outcome is ambiguous: the receiver may
	// or may not have applied it. The effect stays unknown and is retried
	// under the same idempotency key.
	ErrNoAck = errors.New("sealed-webhook: no valid acknowledgement")
	// ErrOversizedResponse is an ErrNoAck whose body exceeded the bound.
	ErrOversizedResponse = errors.New("sealed-webhook: acknowledgement exceeded the configured size bound")
)
View Source
var ErrFingerprintUnconfirmed = errors.New("sealed-webhook: endpoint fingerprint was not confirmed; verify it out of band and set the confirmed fingerprint")

ErrFingerprintUnconfirmed refuses activation without an exact match.

Functions

func CanonicalOrigin

func CanonicalOrigin(raw string) (string, error)

CanonicalOrigin accepts only a bare https origin: no userinfo, path, query, or fragment. The protocol path is fixed and appended by the client.

func Namespace

func Namespace(d adapter.Destination) (string, error)

Namespace validates the only destination shape: an organization-kind destination whose owner names the receiver namespace.

Types

type API

type API interface {
	Deliver(context.Context, Delivery) (sealedhook.Ack, error)
}

API is the closed provider surface. The structural test pins it.

type Client

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

Client is the hand-rolled receiver transport.

func NewClient

func NewClient(cfg ClientConfig) (*Client, error)

NewClient builds the transport with the shared public-egress dialer.

func (*Client) Deliver

func (c *Client) Deliver(ctx context.Context, d Delivery) (sealedhook.Ack, error)

Deliver posts one envelope and verifies the answer. Classification:

  • transport error, non-200, wrong media type, oversized or malformed body: ErrNoAck (ambiguous, retry with the same idempotency key);
  • well-formed ack that fails signature, key, digest, or idempotency binding: adapter.ErrAckForged (terminal, attention);
  • verified ack: returned, whatever its status.

func (*Client) Forget

func (c *Client) Forget()

Forget drops pooled connections when one outbox attempt ends.

type ClientConfig

type ClientConfig struct {
	Origin           string
	AckKey           sealedhook.PublicKey
	AllowedCIDRs     []netip.Prefix
	Timeout          time.Duration
	MaxResponseBytes int64
}

ClientConfig is the transport half of an Endpoint.

type Delivery

type Delivery struct {
	Body           []byte
	Digest         string
	IdempotencyKey string
}

Delivery is one exact request body and the binding its ack must carry.

type Endpoint

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

Endpoint is an activated receiver: its origin, keys, and generation were confirmed by an instance admin typing the independently verified fingerprint. Trust-on-first-use is refused.

func NewEndpoint

func NewEndpoint(cfg EndpointConfig) (*Endpoint, error)

NewEndpoint validates and activates one receiver.

func (*Endpoint) ClientConfig

func (e *Endpoint) ClientConfig() ClientConfig

ClientConfig derives the transport configuration.

func (*Endpoint) Fingerprint

func (e *Endpoint) Fingerprint() string

Fingerprint is the confirmed trust-boundary fingerprint.

func (*Endpoint) ID

func (e *Endpoint) ID() string

ID is the instance-admin endpoint identity.

func (*Endpoint) Origin

func (e *Endpoint) Origin() string

Origin is the canonical configured origin.

type EndpointConfig

type EndpointConfig struct {
	ID                   string
	InstanceID           string
	Origin               string
	RecipientKey         string
	AckKey               string
	Generation           int64
	Timeout              time.Duration
	MaxResponseBytes     int64
	ConfirmedFingerprint string
	Signer               *sealedhook.Signer
}

EndpointConfig is one instance-admin configured receiver. It is never tenant-supplied: tenants may only bind an adapter to an existing origin.

type Module

type Module struct {
	API      API
	Endpoint *Endpoint
	// Binding is the tenant's write-only adapter credential. It travels only
	// inside the recipient-encrypted payload.
	Binding string
	Now     func() time.Time
}

Module implements the four-operation adapter seam for one endpoint.

func (*Module) Plan

func (m *Module) Plan(ctx context.Context, req adapter.PlanRequest) (adapter.Plan, error)

Plan is value-blind and network-free: a receiver exposes no read, so an unclaimed name's existence is unknown until the receiver answers a sync.

func (*Module) Sync

Sync converges the full manifest one effect at a time. Every effect is sealed before Prepare, so no plaintext-bearing work happens after the provider-write fence is taken except the single POST.

func (*Module) TestConnection

func (m *Module) TestConnection(ctx context.Context, req adapter.ConnectionRequest) (adapter.Connection, error)

TestConnection sends a probe envelope and requires a verified ack.

func (*Module) ValidateConfig

func (m *Module) ValidateConfig(cfg adapter.Config) error

ValidateConfig accepts only the activated endpoint's exact origin.

type ResponseError

type ResponseError struct{ Status int }

ResponseError is a non-200 receiver answer. Bodies are never surfaced.

func (*ResponseError) Error

func (e *ResponseError) Error() string

Jump to

Keyboard shortcuts

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