publish

package
v1.3.4 Latest Latest
Warning

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

Go to latest
Published: May 26, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source
const CatalogFileName = "catalog.json"

Variables

View Source
var (
	// ErrUnauthorized means the caller did not present a recognized publish token.
	ErrUnauthorized = errors.New("unauthorized")
	// ErrForbidden means the token is known but not allowed for the requested package/version.
	ErrForbidden = errors.New("forbidden")
)

Functions

func ConstantTimeTokenHashEqual

func ConstantTimeTokenHashEqual(a, b string) bool

ConstantTimeTokenHashEqual compares canonical token hash strings without leaking which byte differed.

func DBFileName

func DBFileName(packageName string) (string, error)

DBFileName returns the canonical SQLite export file name for packageName.

func HashPublishToken

func HashPublishToken(rawToken string) string

HashPublishToken returns the canonical hash form stored for a raw publish token.

func NormalizeTokenHash

func NormalizeTokenHash(tokenHash string) (string, error)

NormalizeTokenHash validates and normalizes a stored token hash.

func PackageVersionDBPath

func PackageVersionDBPath(packageName, version string) (string, error)

PackageVersionDBPath returns the relative canonical DB path for a package version, e.g. pinocchio/v1.2.3/pinocchio.db.

func PackageVersionDir

func PackageVersionDir(packageName, version string) (string, error)

PackageVersionDir returns the relative directory for a package/version pair.

func ValidatePackageName

func ValidatePackageName(name string) error

ValidatePackageName checks whether name is safe to use as a docs package identity and as one path segment below the package publication root.

func ValidatePackageVersion

func ValidatePackageVersion(packageName, version string) error

ValidatePackageVersion validates the package/version pair used by publish APIs and filesystem materialization.

func ValidateVersion

func ValidateVersion(version string) error

ValidateVersion checks whether version is safe to use as a package version identity and as one path segment below the package publication root.

Types

type DirectoryPackageStore

type DirectoryPackageStore struct {
	Root string
	Now  func() time.Time
}

func NewDirectoryPackageStore

func NewDirectoryPackageStore(root string) *DirectoryPackageStore

func (*DirectoryPackageStore) List

func (*DirectoryPackageStore) Publish

func (s *DirectoryPackageStore) Publish(ctx context.Context, packageName, version, dbPath string, result *SQLiteValidationResult, identity *PublisherIdentity) (*PublishedPackage, error)

type FilePublisherCatalogSource

type FilePublisherCatalogSource struct {
	Path string
}

FilePublisherCatalogSource loads Phase 1 publisher token records from a JSON file. It mirrors the Vault record shape and is useful for local smoke tests and operator-synced Vault exports.

func (FilePublisherCatalogSource) LoadPublisherTokenRecords

func (s FilePublisherCatalogSource) LoadPublisherTokenRecords(ctx context.Context) ([]PublisherTokenRecord, error)

type JWTPublisherAuth added in v1.3.1

type JWTPublisherAuth struct {
	Issuer   string
	ClientID string
	// contains filtered or unexported fields
}

JWTPublisherAuth authorizes package publishes with OIDC-compliant JWTs.

This auth mode is intended for Vault Identity/OIDC publish tokens. Vault signs a short-lived token with audience "docs-registry" and a package claim. The registry validates the token through OIDC discovery/JWKS and then checks that the package claim matches the requested package.

func NewJWTPublisherAuth added in v1.3.1

func NewJWTPublisherAuth(ctx context.Context, issuer, clientID string) (*JWTPublisherAuth, error)

NewJWTPublisherAuth constructs a JWT publisher auth implementation using OIDC discovery from issuer. clientID is the expected JWT audience.

func (*JWTPublisherAuth) AuthorizePublish added in v1.3.1

func (a *JWTPublisherAuth) AuthorizePublish(ctx context.Context, rawToken string, req PublishRequest) (*PublisherIdentity, error)

AuthorizePublish validates rawToken as an OIDC JWT and authorizes it for req.

type PackageCatalog

type PackageCatalog struct {
	UpdatedAt time.Time          `json:"updatedAt"`
	Packages  []PublishedPackage `json:"packages"`
}

type PackageStore

type PackageStore interface {
	Publish(ctx context.Context, packageName, version, dbPath string, result *SQLiteValidationResult, identity *PublisherIdentity) (*PublishedPackage, error)
	List(ctx context.Context) ([]PublishedPackage, error)
}

PackageStore persists a validated package docs DB and can list published packages.

type PublishRequest

type PublishRequest struct {
	PackageName string
	Version     string
}

PublishRequest is the authorization request for publishing one package version.

type PublishedPackage

type PublishedPackage struct {
	PackageName  string    `json:"packageName"`
	Version      string    `json:"version"`
	SectionCount int       `json:"sectionCount"`
	SlugCount    int       `json:"slugCount"`
	Path         string    `json:"path,omitempty"`
	SHA256       string    `json:"sha256,omitempty"`
	PublishedBy  string    `json:"publishedBy,omitempty"`
	PublishedAt  time.Time `json:"publishedAt,omitempty"`
}

PublishedPackage is a lightweight registry catalog entry.

type PublisherAuth

type PublisherAuth interface {
	AuthorizePublish(ctx context.Context, rawToken string, req PublishRequest) (*PublisherIdentity, error)
}

PublisherAuth authorizes package/version publishing requests.

type PublisherCatalogSource

type PublisherCatalogSource interface {
	LoadPublisherTokenRecords(ctx context.Context) ([]PublisherTokenRecord, error)
}

PublisherCatalogSource loads package publisher records from a backing source such as a fixture file, Vault KV path, or later registry database.

type PublisherIdentity

type PublisherIdentity struct {
	Subject     string
	PackageName string
	Method      string
}

PublisherIdentity describes the authenticated publisher after authorization.

type PublisherTokenRecord

type PublisherTokenRecord struct {
	PackageName string    `json:"package" yaml:"package"`
	Subject     string    `json:"subject,omitempty" yaml:"subject,omitempty"`
	TokenHash   string    `json:"tokenHash" yaml:"token_hash"`
	CreatedAt   time.Time `json:"createdAt,omitempty" yaml:"created_at,omitempty"`
	RotatedAt   time.Time `json:"rotatedAt,omitempty" yaml:"rotated_at,omitempty"`
	RevokedAt   time.Time `json:"revokedAt,omitempty" yaml:"revoked_at,omitempty"`
	Notes       string    `json:"notes,omitempty" yaml:"notes,omitempty"`
}

PublisherTokenRecord mirrors the Phase 1 Vault/static catalog record shape. The raw publish token is never represented here; only its hash is stored.

func (PublisherTokenRecord) ToStaticPublisherToken

func (r PublisherTokenRecord) ToStaticPublisherToken() (StaticPublisherToken, bool)

ToStaticPublisherToken converts a non-revoked catalog record into a static auth token entry.

type RegistryHandler

type RegistryHandler struct {
	Auth           PublisherAuth
	Store          PackageStore
	MaxUploadBytes int64
	TempDir        string
}

RegistryHandler serves the Phase 1 docs publishing registry API.

func NewRegistryHandler

func NewRegistryHandler(auth PublisherAuth, store PackageStore) *RegistryHandler

func (*RegistryHandler) Handler

func (h *RegistryHandler) Handler() http.Handler

type ReloadablePublisherCatalog

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

ReloadablePublisherCatalog keeps the active PublisherAuth implementation in memory and can replace it after reloading token records from a source.

func NewReloadablePublisherCatalog

func NewReloadablePublisherCatalog(source PublisherCatalogSource) *ReloadablePublisherCatalog

func (*ReloadablePublisherCatalog) AuthorizePublish

func (c *ReloadablePublisherCatalog) AuthorizePublish(ctx context.Context, rawToken string, req PublishRequest) (*PublisherIdentity, error)

AuthorizePublish delegates to the currently loaded auth implementation.

func (*ReloadablePublisherCatalog) Reload

Reload loads token records from the source and swaps in a new StaticTokenAuth only after all records validate.

type SQLiteValidationOptions

type SQLiteValidationOptions struct {
	PackageName string
	Version     string
}

SQLiteValidationOptions controls validation of a Glazed help SQLite export.

type SQLiteValidationResult

type SQLiteValidationResult struct {
	Path         string   `json:"path"`
	PackageName  string   `json:"packageName,omitempty"`
	Version      string   `json:"version,omitempty"`
	SectionCount int      `json:"sectionCount"`
	SlugCount    int      `json:"slugCount"`
	Warnings     []string `json:"warnings,omitempty"`
}

SQLiteValidationResult summarizes a validated help database.

func ValidateSQLiteHelpDB

func ValidateSQLiteHelpDB(ctx context.Context, path string, opts SQLiteValidationOptions) (*SQLiteValidationResult, error)

ValidateSQLiteHelpDB opens path read-only and verifies that it looks like a Glazed help SQLite export that is safe to publish for the requested package and version.

type StaticPublisherCatalogSource

type StaticPublisherCatalogSource struct {
	Records []PublisherTokenRecord
}

StaticPublisherCatalogSource is an in-memory source useful for tests and local fixtures before direct Vault loading is implemented.

func (StaticPublisherCatalogSource) LoadPublisherTokenRecords

func (s StaticPublisherCatalogSource) LoadPublisherTokenRecords(ctx context.Context) ([]PublisherTokenRecord, error)

type StaticPublisherToken

type StaticPublisherToken struct {
	Subject     string
	PackageName string
	TokenHash   string
}

StaticPublisherToken binds one token hash to exactly one package.

func StaticTokensFromRecords

func StaticTokensFromRecords(records []PublisherTokenRecord) ([]StaticPublisherToken, error)

StaticTokensFromRecords validates catalog records and returns static auth tokens for all non-revoked records.

type StaticTokenAuth

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

StaticTokenAuth authorizes publishes against an in-memory package token list.

func NewStaticTokenAuth

func NewStaticTokenAuth(tokens []StaticPublisherToken) (*StaticTokenAuth, error)

NewStaticTokenAuth validates and constructs static package-token auth.

func (*StaticTokenAuth) AuthorizePublish

func (a *StaticTokenAuth) AuthorizePublish(ctx context.Context, rawToken string, req PublishRequest) (*PublisherIdentity, error)

AuthorizePublish authorizes rawToken for req. It intentionally compares the presented token hash with stored hashes using constant-time comparison.

Jump to

Keyboard shortcuts

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