documents

type AuthorizeRequest ¶

type AuthorizeRequest func(*http.Request) error

AuthorizeRequest either authenticates an incoming publisher request or adds existing machine credentials to an outgoing resolver request. Nil always denies; AuthKit does not define a document-specific credential.

type DocumentVerifier ¶

type DocumentVerifier interface {
	ValidateDocumentIssuer(context.Context, string) error
	VerifyDocument(context.Context, SignedDocument, VerifyOptions) (Envelope, error)
}

DocumentVerifier is implemented by verify.Verifier. The preflight trust check prevents an untrusted issuer from becoming a network destination.

type Envelope ¶

type Envelope struct {
	Issuer    string          `json:"iss"`
	Audiences []string        `json:"aud"`
	Type      string          `json:"type"`
	Payload   json.RawMessage `json:"payload"`
}

Envelope is the signed JWS payload. Payload is intentionally opaque to AuthKit and may contain any valid JSON value.

func DecodeEnvelope(payload []byte) (Envelope, error)

func NormalizeEnvelope(in Envelope) (Envelope, error)

func (e Envelope) HasAudience(audience string) bool

func (e Envelope) Validate() error

type Header ¶

type Header struct {
	Algorithm string
	KeyID     string
	Type      string
}

Header is the security-relevant subset of an inspected compact JWS header. Inspecting a header or payload does not verify its signature.

func DecodeCompact(compact string) (Header, []byte, error)

type LookupDocument ¶

type LookupDocument func(context.Context, string) (SignedDocument, error)

LookupDocument returns a retained document by its immutable payload digest. Its compact JWS representation may change when the payload is re-signed.

type Reference ¶

type Reference struct {
	Type   string `json:"type"`
	Digest string `json:"digest"`
}

Reference identifies one exact signed envelope. Type carries the application schema version (for example, example.catalog/v1); Digest covers the exact JWS payload bytes, not a decoded/re-encoded JSON value.

func NormalizeReference(r Reference) (Reference, error)

func ReferenceFor(documentType string, signedPayload []byte) (Reference, error)

func (r Reference) Validate() error

type Resolver ¶

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

package main

import (
	"context"
	"crypto"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"

	"github.com/open-rails/authkit/documents"
	"github.com/open-rails/authkit/jwtkit"
	"github.com/open-rails/authkit/verify"
)

const machineAuthorization = "Bearer existing-machine-credential"

func requireMachine(request *http.Request) error {
	if request.Header.Get("Authorization") != machineAuthorization {
		return errors.New("unauthorized")
	}
	return nil
}

func addMachine(request *http.Request) error {
	request.Header.Set("Authorization", machineAuthorization)
	return nil
}

func main() {
	signer, _ := jwtkit.NewRSASigner(2048, "site-a-key")
	var document documents.SignedDocument
	siteA := httptest.NewServer(documents.NewPublisher(func(context.Context, string) (documents.SignedDocument, error) {
		return document, nil
	}, requireMachine))
	defer siteA.Close()
	document, _ = documents.Sign(context.Background(), signer, documents.Envelope{
		Issuer: siteA.URL, Audiences: []string{"site-b"}, Type: "example.entitlements/v1", Payload: json.RawMessage(`{"plan":"starter"}`),
	})

	v := verify.NewVerifier()
	_ = v.AddIssuer(siteA.URL, nil, verify.IssuerOptions{RawKeys: map[string]crypto.PublicKey{signer.KID(): signer.PublicKey()}})
	resolver := documents.NewResolver(v, siteA.Client(), addMachine, documents.ResolverOptions{AllowHTTP: true})
	siteB := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		payload, err := resolver.Resolve(r.Context(), siteA.URL, document.Reference, "site-b")
		if err != nil {
			http.Error(w, err.Error(), http.StatusUnauthorized)
			return
		}
		_, _ = w.Write(payload) // site B owns schema/processing from here.
	}))
	defer siteB.Close()

	response, _ := siteB.Client().Get(siteB.URL)
	body, _ := io.ReadAll(response.Body)
	response.Body.Close()
	fmt.Println(string(body))
}

Output:
{"plan":"starter"}

func NewResolver(verifier DocumentVerifier, client *http.Client, authorize AuthorizeRequest, opts ResolverOptions) *Resolver

func (r *Resolver) Resolve(ctx context.Context, issuer string, reference Reference, audience string) (json.RawMessage, error)

type ResolverOptions ¶

type ResolverOptions struct {
	// AllowHTTP is for local tests and development only. Production defaults to
	// HTTPS-only publication endpoints.
	AllowHTTP        bool
	Timeout          time.Duration
	MaxResponseBytes int64
	MaxCacheEntries  int
}

type Service ¶ added in v0.91.0

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

Service owns the publish lifecycle of ONE immutable signed document: sign -> verify -> persist -> re-read -> re-verify at construction, a digest-stable re-signature when the signing key rotates (EnsureSigningKID / CurrentDigest repair), and content-addressed lookups for the publication route. Construct with NewService; the zero value is unusable.

func NewService(ctx context.Context, cfg ServiceConfig) (*Service, error)

func (s *Service) CurrentDigest(ctx context.Context) (string, error)

func (s *Service) EnsureSigningKID(ctx context.Context, tokenKID string) error

func (s *Service) Lookup(ctx context.Context, digest string) (SignedDocument, error)

func (s *Service) Payload() json.RawMessage

func (s *Service) Reference() Reference

type ServiceConfig ¶ added in v0.91.0

type ServiceConfig struct {
	// Type is the versioned application document type (e.g. "example.catalog/v1").
	Type string
	// Payload is the host-compiled application payload. Opaque to AuthKit.
	Payload json.RawMessage
	// Issuer is the signing AuthKit issuer (normally Config.Token.Issuer).
	Issuer string
	// Audiences are the signed envelope audiences readers verify against.
	Audiences []string
	// Signer signs and self-verifies (normally the *embedded.Client).
	Signer Signer
	// Postgres + Schema select AuthKit's own signed_documents table (Schema ""
	// means the default "profiles"). Ignored when Store is set.
	Postgres *pgxpool.Pool
	Schema   string
	// Store overrides the built-in Postgres store (tests / custom backends).
	Store Store
}

ServiceConfig declares one published document (ak#260). The host supplies its compiled payload; AuthKit owns the store, lifecycle, and invariants.

type SignedDocument ¶

type SignedDocument struct {
	CompactJWS    string    `json:"jws"`
	Reference     Reference `json:"reference"`
	SignedPayload []byte    `json:"signed_payload"`
}

SignedDocument retains both the compact JWS and the exact bytes used as its payload so callers can publish them without a parse/re-encode step.

func FromCompact(compact string, reference Reference) (SignedDocument, error)

func Sign(ctx context.Context, signer jwtkit.Signer, envelope Envelope) (SignedDocument, error)

type Signer ¶ added in v0.91.0

type Signer interface {
	SignDocument(ctx context.Context, envelope Envelope) (SignedDocument, error)
	PublicKeysByKID() map[string]crypto.PublicKey
}

Signer signs one envelope with the process's active AuthKit key and exposes the CURRENT public keys for self-verification. *embedded.Client satisfies it.

type Store ¶ added in v0.91.0

type Store interface {
	SaveDocument(ctx context.Context, document SignedDocument) error
	Lookup(ctx context.Context, digest string) (SignedDocument, error)
}

Store persists immutable signed documents by digest. Save may replace ONLY compact_jws for an existing digest (a re-signature of the same payload on key rotation); any payload or type change under an existing digest must fail with ErrDigestCollision. Lookup returns ErrNotFound for unknown digests.

type VerifyOptions ¶

type VerifyOptions struct {
	Issuer    string
	Audience  string
	Type      string
	Reference Reference
}

VerifyOptions are the caller's authenticated expectations. None may be inferred from unsigned request metadata.