publicsurface

Documentation

Overview

Package publicsurface owns Lesser's importable public-surface decision.

Index

• func IsPublic(method, path string) bool
• type Classification
  • func Classify(method, path string) Classification
• type ClassificationKind
• type ContractAuthClass
  • func ContractAuth(method, path string) (ContractAuthClass, bool)
• type ContractAuthRule
  • func ContractAuthRules() []ContractAuthRule
• type PublicRule
  • func PublicRules() []PublicRule
• type RuleMatch

Functions

func IsPublic

func IsPublic(method, path string) bool

IsPublic reports whether the method/path pair is in Lesser's explicitly allowlisted anonymous API surface.

The default is deny: method/path pairs missing from this allowlist are not public.

Types

type Classification

type Classification struct {
	Kind              ClassificationKind
	Public            bool
	Rule              *PublicRule
	ContractAuthClass ContractAuthClass
}

Classification is publicsurface's resolved auth posture for a method/path.

func Classify

func Classify(method, path string) Classification

Classify resolves a method/path through publicsurface so tests and tools can prove every route is intentionally public, contract-auth, or auth-required.

type ClassificationKind

type ClassificationKind string

ClassificationKind identifies how publicsurface resolves a route.

const (
	// ClassificationAnonymous means the route is in the anonymous public surface.
	ClassificationAnonymous ClassificationKind = "anonymous"
	// ClassificationContractAuth means the gate is reachable but handlers enforce
	// a non-anonymous auth class that the generated contract must advertise.
	ClassificationContractAuth ClassificationKind = "contract_auth"
	// ClassificationAuthRequired is the default-deny classification for routes
	// outside the anonymous allowlist.
	ClassificationAuthRequired ClassificationKind = "auth_required"
	// ClassificationUnknown means the route could not be classified because the
	// method or path is empty.
	ClassificationUnknown ClassificationKind = "unknown"
)

type ContractAuthClass

type ContractAuthClass string

ContractAuthClass describes auth requirements that are enforced outside the API gateway public-surface middleware but still need to be reflected in the generated public contract.

const (
	// ContractAuthSetupBearer uses the temporary setup-session bearer token.
	ContractAuthSetupBearer ContractAuthClass = "setup_bearer"
	// ContractAuthBearerRequired uses the normal OAuth bearer-token posture.
	ContractAuthBearerRequired ContractAuthClass = "bearer_required"
	// ContractAuthInternalOnly is handler-enforced with internal instance keys.
	ContractAuthInternalOnly ContractAuthClass = "internal_only"
)

func ContractAuth

func ContractAuth(method, path string) (ContractAuthClass, bool)

ContractAuth returns handler-enforced contract auth requirements for routes that remain gate-reachable through IsPublic but must not be advertised as anonymous in the generated OpenAPI contract.

This is additive contract metadata only. It intentionally does not change IsPublic's gate decision.

type ContractAuthRule

type ContractAuthRule struct {
	Method      string
	Path        string
	Class       ContractAuthClass
	Description string
}

ContractAuthRule is one handler-enforced contract-auth override for a route that remains gate-reachable through IsPublic.

func ContractAuthRules

func ContractAuthRules() []ContractAuthRule

ContractAuthRules returns a copy of Lesser's handler-enforced contract auth overrides.

type PublicRule

type PublicRule struct {
	Methods          []string
	Path             string
	Match            RuleMatch
	Description      string
	ExceptExactPaths []string
	ExceptSuffixes   []string
	RequiredContains []string
}

PublicRule is one source-of-truth entry in Lesser's anonymous public surface. The runtime gate, generated docs, and reconciliation tests all derive from these rules.

func PublicRules

func PublicRules() []PublicRule

PublicRules returns a copy of Lesser's anonymous public-surface rules.

type RuleMatch

type RuleMatch string

RuleMatch describes how a public-surface rule matches paths.

const (
	// RuleMatchExact matches one exact path.
	RuleMatchExact RuleMatch = "exact"
	// RuleMatchPrefix matches every path with the configured prefix.
	RuleMatchPrefix RuleMatch = "prefix"
	// RuleMatchStatusRead matches public status-read paths except sensitive
	// status subresources.
	RuleMatchStatusRead RuleMatch = "status_read"
	// RuleMatchAccountContent matches public account statuses/notes reads.
	RuleMatchAccountContent RuleMatch = "account_content"
	// RuleMatchSkills matches the public skills catalog with one exact exclusion.
	RuleMatchSkills RuleMatch = "skills_catalog"
)