Documentation
¶
Index ¶
- Constants
- Variables
- func ConstantTimeTokenHashEqual(a, b string) bool
- func DBFileName(packageName string) (string, error)
- func HashPublishToken(rawToken string) string
- func NormalizeTokenHash(tokenHash string) (string, error)
- func PackageVersionDBPath(packageName, version string) (string, error)
- func PackageVersionDir(packageName, version string) (string, error)
- func ValidatePackageName(name string) error
- func ValidatePackageVersion(packageName, version string) error
- func ValidateVersion(version string) error
- type DirectoryPackageStore
- type FilePublisherCatalogSource
- type JWTPublisherAuth
- type PackageCatalog
- type PackageStore
- type PublishRequest
- type PublishedPackage
- type PublisherAuth
- type PublisherCatalogSource
- type PublisherIdentity
- type PublisherTokenRecord
- type RegistryHandler
- type ReloadablePublisherCatalog
- type SQLiteValidationOptions
- type SQLiteValidationResult
- type StaticPublisherCatalogSource
- type StaticPublisherToken
- type StaticTokenAuth
Constants ¶
const CatalogFileName = "catalog.json"
Variables ¶
var ( 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 ¶
ConstantTimeTokenHashEqual compares canonical token hash strings without leaking which byte differed.
func DBFileName ¶
DBFileName returns the canonical SQLite export file name for packageName.
func HashPublishToken ¶
HashPublishToken returns the canonical hash form stored for a raw publish token.
func NormalizeTokenHash ¶
NormalizeTokenHash validates and normalizes a stored token hash.
func PackageVersionDBPath ¶
PackageVersionDBPath returns the relative canonical DB path for a package version, e.g. pinocchio/v1.2.3/pinocchio.db.
func PackageVersionDir ¶
PackageVersionDir returns the relative directory for a package/version pair.
func ValidatePackageName ¶
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 ¶
ValidatePackageVersion validates the package/version pair used by publish APIs and filesystem materialization.
func ValidateVersion ¶
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 ¶
func NewDirectoryPackageStore ¶
func NewDirectoryPackageStore(root string) *DirectoryPackageStore
func (*DirectoryPackageStore) List ¶
func (s *DirectoryPackageStore) List(ctx context.Context) ([]PublishedPackage, error)
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 ¶
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 ¶
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.
type SQLiteValidationOptions ¶
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 ¶
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.