Go: package webbotauth

Generated from the Go source by scripts/gen-docs.sh — do not edit; run it to regenerate. Canonical deep reference: pkg.go.dev/github.com/dnsid-ai/dnsid-go/webbotauth. Guides and account setup: https://docs.dnsid.ai.

import "github.com/dnsid-ai/dnsid-go/webbotauth"

Package webbotauth implements the Web Bot Auth profile (draft-meunier-webbotauth-httpsig-protocol) on top of package httpsig: it signs HTTP requests with RFC 9421 HTTP Message Signatures tagged “web-bot-auth” so an origin can verify the caller is a specific DNSid agent. The signing key must be Ed25519.

The main entry type is Profile. A Profile holds the agent’s domain and its dnsid.KeyProvider; Config controls the Signature-Agent header, the key directory URL, and signature lifetimes, and its zero value applies the profile defaults.

A typical caller signs a request and lets the origin discover its key through the Signature-Agent header:

profile := webbotauth.NewFromIdentityManager(idm, webbotauth.Config{})

req, _ := http.NewRequest(http.MethodGet, "https://target.example/search?q=dnsid", nil)
signed, err := profile.CreateWebBotAuthSignedRequest(req, webbotauth.SigningOptions{})
// signed carries Signature-Agent, Signature-Input, and Signature headers.

ServeHttpMessageSignaturesDirectory produces the signed key directory response that origins fetch from DirectoryPath to obtain the agent’s public key.

See https://docs.dnsid.ai for protocol guides and account setup.

Example

Example creates a Web Bot Auth signed request. The signing key must be Ed25519.

package main

import (
  "fmt"
  "net/http"

  dnsid "github.com/dnsid-ai/dnsid-go"
  "github.com/dnsid-ai/dnsid-go/webbotauth"
)

func main() {
  key := dnsid.GenerateEd25519KeyProvider()
  profile := webbotauth.New("bot.example", key, webbotauth.Config{})

  req, err := http.NewRequest(http.MethodGet, "https://target.example/search?q=dnsid", nil)
  if err != nil {
    panic(err)
  }
  signed, err := profile.CreateWebBotAuthSignedRequest(req, webbotauth.SigningOptions{})
  if err != nil {
    panic(err)
  }

  // Signature-Input and Signature vary per run; Signature-Agent tells the
  // origin where to fetch this agent's key directory.
  fmt.Println("Signature-Agent:", signed.Header.Get("Signature-Agent"))
  fmt.Println("signature present:", signed.Header.Get("Signature") != "")
}

Output

Signature-Agent: sig1="https://bot.example";type=directory
signature present: true

Index

• Constants
• type Config
• type Profile
  • func New(domain string, kp dnsid.KeyProvider, cfg Config) *Profile
  • func NewFromIdentityManager(manager identityManager, cfg Config) *Profile
  • func (p *Profile) CreateWebBotAuthSignedRequest(req *http.Request, opts SigningOptions) (*http.Request, error)
  • func (p *Profile) ServeHttpMessageSignaturesDirectory(req *http.Request) (*http.Response, error)
• type SigningOptions

Constants

const (
    // DirectoryPath is the well-known HTTP path where a Web Bot Auth key
    // directory is served.
    DirectoryPath = "/.well-known/http-message-signatures-directory"

    // DirectoryContentType is the media type of a Web Bot Auth key
    // directory response.
    DirectoryContentType = "application/http-message-signatures-directory+json"
)

type Config

Config contains Web Bot Auth profile defaults. The zero value applies the profile defaults.

type Config struct {
    // DirectoryURL overrides the URI advertised in Signature-Agent. Empty
    // means "https://<domain>". Directory discovery requires an origin URI;
    // jwks_uri discovery uses this as the direct endpoint.
    DirectoryURL string

    // SignatureAgentType controls discovery interpretation. Empty means
    // "directory" unless a legacy DirectoryURL contains a non-root path, in
    // which case it means "jwks_uri" for source compatibility.
    SignatureAgentType string

    // SignatureTTL is the default request signature lifetime (the distance
    // from the created to the expires parameter). Zero means the default of
    // 1 minute; negative or greater than 5 minutes is invalid.
    SignatureTTL time.Duration

    // IncludeSignatureAgent controls whether signed requests carry a
    // Signature-Agent header covered by the signature. Nil means true.
    IncludeSignatureAgent *bool

    // DirectorySignatureTTL is the signature lifetime for key directory
    // responses. Zero means the default of 5 minutes; negative or greater
    // than 5 minutes is invalid.
    DirectorySignatureTTL time.Duration

    // ClockSkew is reserved for future WBA verification. Negative values are
    // invalid. Zero applies the profile default of 5 seconds.
    ClockSkew time.Duration
}

type Profile

Profile implements the Web Bot Auth profile: it signs HTTP requests as a DNSid agent and serves the agent’s key directory. The signing key must be Ed25519.

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

func New

func New(domain string, kp dnsid.KeyProvider, cfg Config) *Profile

New constructs a Web Bot Auth profile that signs as domain using kp. The domain is normalized to a FQDN when possible. Signing fails unless kp’s active key is Ed25519.

func NewFromIdentityManager

func NewFromIdentityManager(manager identityManager, cfg Config) *Profile

NewFromIdentityManager constructs a Web Bot Auth profile from an IdentityManager-like core manager, using its domain and KeyProvider. A nil manager yields a profile whose signing operations fail.

func (*Profile) CreateWebBotAuthSignedRequest

func (p *Profile) CreateWebBotAuthSignedRequest(req *http.Request, opts SigningOptions) (*http.Request, error)

CreateWebBotAuthSignedRequest returns a signed clone of req carrying Signature-Input and Signature headers tagged “web-bot-auth”, plus a Signature-Agent header unless disabled by configuration. Requests with a body also gain a covered Content-Digest header. The profile’s active key must be Ed25519.

func (*Profile) ServeHttpMessageSignaturesDirectory

func (p *Profile) ServeHttpMessageSignaturesDirectory(req *http.Request) (*http.Response, error)

ServeHttpMessageSignaturesDirectory builds the signed key directory response containing the profile’s active public key. req is recorded as the response’s originating request so the signature can cover @authority.

type SigningOptions

SigningOptions configures Web Bot Auth request signing.

type SigningOptions struct {
    // AdditionalComponents lists extra component names to cover beyond the
    // profile's defaults. Unknown names cause signing to fail.
    AdditionalComponents []string

    // AdditionalComponentIDs lists extra components, with parameters, to
    // cover beyond the profile's defaults.
    AdditionalComponentIDs []httpsig.ComponentIdentifier

    // SignatureAgent, when non-nil, overrides Config.IncludeSignatureAgent
    // for this request.
    SignatureAgent *bool

    // TTL, when positive, overrides Config.SignatureTTL for this request.
    TTL time.Duration
}

Generated by gomarkdoc