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
- Variables
- func CanonicalOrigin(raw string) (string, error)
- func Namespace(d adapter.Destination) (string, error)
- type API
- type Client
- type ClientConfig
- type Delivery
- type Endpoint
- type EndpointConfig
- type Module
- func (m *Module) Plan(ctx context.Context, req adapter.PlanRequest) (adapter.Plan, error)
- func (m *Module) Sync(ctx context.Context, req adapter.SyncRequest, journal adapter.Journal) (adapter.SyncResult, error)
- func (m *Module) TestConnection(ctx context.Context, req adapter.ConnectionRequest) (adapter.Connection, error)
- func (m *Module) ValidateConfig(cfg adapter.Config) error
- type ResponseError
Constants ¶
const ( // MaxTimeout bounds one delivery round trip. MaxTimeout = 10 * time.Second // MaxResponseBytes bounds an acknowledgement body. MaxResponseBytes = sealedhook.MaxAck )
const ( ReasonExistsUnowned = "exists_unowned" )
Receiver reasons with a defined Hikyo meaning (docs/spec/sealed-webhook.md).
const ConnectionVersion = "sealed-webhook/v1"
ConnectionVersion is reported by TestConnection.
Variables ¶
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") )
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 ¶
CanonicalOrigin accepts only a bare https origin: no userinfo, path, query, or fragment. The protocol path is fixed and appended by the client.
Types ¶
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 ¶
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.
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 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 ¶
Fingerprint is the confirmed trust-boundary fingerprint.
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 ¶
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 ¶
func (m *Module) Sync(ctx context.Context, req adapter.SyncRequest, journal adapter.Journal) (adapter.SyncResult, error)
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.
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