Documentation
¶
Overview ¶
Package attribution captures immutable human/system and request provenance. It carries no authenticated model, credentials, permissions or database handle.
Index ¶
- Constants
- func SanitizeUserAgent(raw string) string
- func WithContext(ctx context.Context, origin Origin) (context.Context, error)
- func WithRoute(ctx context.Context, route Route) (context.Context, error)
- type GuardName
- type Origin
- func (Origin) Format(state fmt.State, _ rune)
- func (o Origin) Guard() GuardName
- func (o Origin) MarshalJSON() ([]byte, error)
- func (o Origin) Model() (model.Identity, bool)
- func (o Origin) Request() Request
- func (o Origin) System() SystemID
- func (o *Origin) UnmarshalJSON(data []byte) error
- func (o Origin) Validate() error
- func (o Origin) WithGuard(guard GuardName) (Origin, error)
- func (o Origin) WithIdentity(subject model.Identity) (Origin, error)
- func (o Origin) WithModel(subject model.Identifiable) (Origin, error)
- func (o Origin) WithRequest(request Request) (Origin, error)
- func (o Origin) WithSystem(system SystemID) (Origin, error)
- type Request
- type RequestID
- type Route
- type SystemID
Constants ¶
const ( MaxRouteMethodBytes = 16 MaxRouteNameBytes = 256 )
const MaxRequestIDBytes = 128
const MaxUserAgentBytes = 4096
Variables ¶
This section is empty.
Functions ¶
func SanitizeUserAgent ¶
SanitizeUserAgent converts untrusted transport text into valid attribution metadata. Invalid UTF-8 becomes U+FFFD, control characters (including TAB, CR/LF, DEL and C1 controls) are removed, and the result is truncated at MaxUserAgentBytes on a rune boundary. It never fails: a user agent describes a request, it does not authorize or reject it.
func WithContext ¶
WithContext attaches a validated value snapshot and preserves the caller's cancellation. It does not install security credentials or authorization state.
Types ¶
type GuardName ¶
type GuardName string
GuardName is the serialized name of an authentication strategy, never a credential.
type Origin ¶
type Origin struct {
// contains filtered or unexported fields
}
Origin contains at most one model identity or system identity. Zero is valid anonymous provenance. It is metadata, never an authentication/authorization capability; security adapters must resolve their own concrete subject.
func FromContext ¶
FromContext returns anonymous provenance when none is present. Later context derivation or model mutation cannot change a previously returned snapshot.
func (Origin) MarshalJSON ¶
MarshalJSON validates and encodes the origin as JSON.
func (*Origin) UnmarshalJSON ¶
UnmarshalJSON decodes and validates JSON, replacing the receiver only on success.
func (Origin) Validate ¶
Validate checks subject exclusivity, semantic identifiers, and request metadata.
func (Origin) WithGuard ¶
WithGuard captures only a strategy name. A system origin cannot use a guard.
func (Origin) WithIdentity ¶
WithIdentity is the explicit restored-metadata boundary. Supplying a parsed identity grants no authority and does not authenticate the caller.
func (Origin) WithModel ¶
func (o Origin) WithModel(subject model.Identifiable) (Origin, error)
WithModel captures the model's generated stored-key identity immediately. Mutating the original model later cannot change this origin. No lookup or custom read getter runs. A custom metadata adapter must be pure.
func (Origin) WithRequest ¶
WithRequest returns a copy with the supplied request metadata after validation.
type Request ¶
type Request struct {
ID RequestID `json:"id,omitzero"`
IP netip.Addr `json:"ip,omitzero"`
UserAgent string `json:"user_agent,omitzero"`
}
Request is a value snapshot of request metadata. HTTP adapters determine trusted client IPs before attribution is captured; this package trusts no headers.
type RequestID ¶
type RequestID string
RequestID correlates work with its originating request. It is not a secret.
type Route ¶
Route identifies the matched server endpoint of the current request by its method and declared route name. It is request-local context metadata: Origin serialization, queued jobs, events and outbox records do not carry it. Raw URLs, query strings and path values are deliberately excluded because they can contain credentials or personal data.
func RouteFromContext ¶
RouteFromContext returns the matched route, or false outside a routed request.
Source Files