securitymanifest

Documentation

Overview

Package securitymanifest projects the stable compiler IR into a declarative, machine-readable security posture (gowdk-security.json). It records what the generated app actually exposes — every route, backend endpoint, and contract with its guards, CSRF state, body limit, and source location, plus the frontend surface (raw-HTML sinks, secret scan, header configuration, and client route-guard coverage).

The manifest is "what is": it never decides whether the posture is acceptable. Policy evaluation and findings live in internal/auditspec, which consumes this manifest. Keeping the projection free of policy keeps gowdk-security.json stable and equally auditable by a human or an LLM regardless of which policies are declared.

Index

• Constants
• func RawHTMLFingerprint(ownerKind, ownerID, field, source string, ordinal int) string
• func RelativizeSourceRef(ref, root string) string
• type BundleLeak
• type CORSPosture
• type ConfiguredHeader
• type ContractEntry
• type EndpointEntry
• type EvidenceState
  • func (state EvidenceState) Valid() bool
• type FrontendSurface
• type GuardEvidence
• type ObligationEntry
• type ObservabilityEntry
• type RawHTMLSink
• type RequestLimitPosture
• type RouteEntry
• type SecurityManifest
  • func Build(config gowdk.Config, ir gwdkir.Program) SecurityManifest
  • func (manifest SecurityManifest) Relativize(root string) SecurityManifest
• type UnguardedRoute
• type WaiverDeclaration

Constants

const PublicGuardID = "public"

PublicGuardID is the guard ID that marks an intentionally public target.

const SchemaVersion = 1

SchemaVersion is the gowdk-security.json schema version.

Functions

func RawHTMLFingerprint

func RawHTMLFingerprint(ownerKind, ownerID, field, source string, ordinal int) string

RawHTMLFingerprint derives the stable identity of one raw-HTML sink. It is exported so tooling and tests can compute the value a policy exception must pin. The source location is part of the identity, so moving the sink (or changing its expression) produces a new fingerprint and stops a stale exception from suppressing a different sink.

func RelativizeSourceRef

func RelativizeSourceRef(ref, root string) string

RelativizeSourceRef rewrites a "file" or "file:line" source reference so the file portion is relative to root and uses forward slashes. It returns the reference unchanged when root is empty, the file portion is not absolute, or it cannot be made relative to root, so non-file references (for example "config:Build.X") and already-relative paths pass through untouched. It is exported so audit policy sources can be relativized with the same rule.

Types

type BundleLeak

type BundleLeak struct {
	Source string `json:"source"`
	Kind   string `json:"kind"`
}

BundleLeak records a secret-shaped value found in embedded output or build-time data.

type CORSPosture

type CORSPosture struct {
	Enabled          bool     `json:"enabled"`
	AllowsAnyOrigin  bool     `json:"allowsAnyOrigin"`
	AllowedOrigins   []string `json:"allowedOrigins,omitempty"`
	AllowCredentials bool     `json:"allowCredentials"`
	MaxAgeSeconds    int      `json:"maxAgeSeconds,omitempty"`
	Origin           string   `json:"origin,omitempty"`
}

CORSPosture records the generated cross-origin policy for API and web contract endpoints. The zero value means CORS is disabled and endpoints stay same-origin.

type ConfiguredHeader

type ConfiguredHeader struct {
	Name  string `json:"name"`
	Value string `json:"value,omitempty"`
}

ConfiguredHeader records one header configured for generated runtime output. Value carries the normalized effective value so audit policy can distinguish a weak configuration (for example Content-Security-Policy: *) from a meaningful one. Secret-shaped values are redacted so the posture stays safe to publish.

type ContractEntry

type ContractEntry struct {
	Name              string   `json:"name"`
	Kind              string   `json:"kind"`
	Roles             []string `json:"roles,omitempty"`
	Status            string   `json:"status,omitempty"`
	DeclarationSource string   `json:"declarationSource,omitempty"`
	ExposureSource    string   `json:"exposureSource,omitempty"`
	SourceAttribution string   `json:"sourceAttribution"`
}

ContractEntry is the posture of one command/query contract reference.

type EndpointEntry

type EndpointEntry struct {
	ID             string              `json:"id"`
	Kind           string              `json:"kind"`
	Method         string              `json:"method,omitempty"`
	Path           string              `json:"path,omitempty"`
	Guards         []string            `json:"guards,omitempty"`
	GuardEvidence  []GuardEvidence     `json:"guardEvidence,omitempty"`
	CSRF           bool                `json:"csrf"`
	BodyLimitBytes int64               `json:"bodyLimitBytes,omitempty"`
	RequestLimits  RequestLimitPosture `json:"requestLimits"`
	Public         bool                `json:"public"`
	DefaultDeny    bool                `json:"defaultDeny"`
	PageID         string              `json:"pageId,omitempty"`
	Source         string              `json:"source,omitempty"`
}

EndpointEntry is the posture of one backend action/api/fragment/contract endpoint.

type EvidenceState

type EvidenceState string

EvidenceState classifies the kind of proof behind a security posture claim or audit finding. It is the shared vocabulary used by gowdk-security.json and the gowdk audit report so a human or CI can tell a statically proven fact from an app-owned obligation gowdk cannot verify.

const (
	// EvidenceVerifiedStatic marks a fact the compiler proves from generated
	// output or the IR: CSRF wiring, body-limit installation, native guard
	// resolution, configured response headers, raw-HTML sink inventory.
	EvidenceVerifiedStatic EvidenceState = "verified-static"
	// EvidenceVerifiedRuntime marks a fact a generated runtime test exercised
	// against a real generated app (gowdk audit --run).
	EvidenceVerifiedRuntime EvidenceState = "verified-runtime"
	// EvidenceDeclared marks a control the project declared but gowdk has not
	// independently verified.
	EvidenceDeclared EvidenceState = "declared"
	// EvidenceUnverifiedAppOwned marks a control whose decision logic is owned by
	// the application: gowdk generates the call site but cannot prove correctness.
	EvidenceUnverifiedAppOwned EvidenceState = "unverified-app-owned"
	// EvidenceNotApplicable marks a posture item that needs no control: an
	// intentionally public target, or a control the surface does not require.
	EvidenceNotApplicable EvidenceState = "not-applicable"
	// EvidenceWaived marks a finding suppressed by an explicit, justified waiver.
	EvidenceWaived EvidenceState = "waived"
)

func (EvidenceState) Valid

func (state EvidenceState) Valid() bool

Valid reports whether state is a known evidence classification.

type FrontendSurface

type FrontendSurface struct {
	UnguardedRoutes   []UnguardedRoute   `json:"unguardedRoutes"`
	BundleSecrets     []BundleLeak       `json:"bundleSecrets"`
	RawHTMLSinks      []RawHTMLSink      `json:"rawHtmlSinks"`
	ConfiguredHeaders []ConfiguredHeader `json:"configuredHeaders"`
}

FrontendSurface describes the build-time / client-facing security surface. Policy evaluation consumes these posture facts without deciding whether they are acceptable here.

type GuardEvidence

type GuardEvidence struct {
	ID                 string        `json:"id"`
	Kind               string        `json:"kind"`
	BindingStatus      string        `json:"bindingStatus"`
	Owner              string        `json:"owner"`
	Evidence           EvidenceState `json:"evidence"`
	ExecutionPhase     string        `json:"executionPhase"`
	FailureContract    string        `json:"failureContract"`
	RuntimeTestFixture string        `json:"runtimeTestFixture,omitempty"`
}

GuardEvidence records what the compiler can prove about one declared guard. App-owned guards are intentionally classified as unverified unless an application-supplied fixture exercises them outside the synthetic audit hook.

type ObligationEntry

type ObligationEntry struct {
	ID       string        `json:"id"`
	Category string        `json:"category"`
	Claim    string        `json:"claim"`
	Owner    string        `json:"owner"`
	Evidence EvidenceState `json:"evidence"`
	Detail   string        `json:"detail,omitempty"`
}

ObligationEntry records one security obligation and how strongly gowdk can vouch for it. Statically generated controls (CSRF wiring, body limits, security headers, native guards) are verified-static; app-owned controls (authentication, session management, tenant/resource authorization, domain authorization) are unverified-app-owned because gowdk generates the call sites but does not own the decision logic. This list keeps gowdk-security.json honest about what the compiler proves versus what the application must prove itself.

type ObservabilityEntry

type ObservabilityEntry struct {
	ID                         string   `json:"id"`
	Kind                       string   `json:"kind"`
	Path                       string   `json:"path,omitempty"`
	Methods                    []string `json:"methods,omitempty"`
	Mounted                    bool     `json:"mounted"`
	AccessPolicy               string   `json:"accessPolicy"`
	BuildMode                  string   `json:"buildMode"`
	DevOnly                    bool     `json:"devOnly"`
	AllowedOrigins             []string `json:"allowedOrigins,omitempty"`
	ContentTypeRequired        string   `json:"contentTypeRequired,omitempty"`
	BodyLimitBytes             int64    `json:"bodyLimitBytes,omitempty"`
	BatchLimit                 int      `json:"batchLimit,omitempty"`
	SubscriberLimit            int      `json:"subscriberLimit,omitempty"`
	SourceMetadataPolicy       string   `json:"sourceMetadataPolicy,omitempty"`
	ExportsAbsoluteSourcePaths bool     `json:"exportsAbsoluteSourcePaths,omitempty"`
	SpanDataLeavesProcess      bool     `json:"spanDataLeavesProcess"`
}

ObservabilityEntry records one generated trace endpoint or export surface.

type RawHTMLSink

type RawHTMLSink struct {
	OwnerKind   string `json:"ownerKind"`
	OwnerID     string `json:"ownerId"`
	Field       string `json:"field"`
	Source      string `json:"source"`
	Ordinal     int    `json:"ordinal"`
	Fingerprint string `json:"fingerprint"`
}

RawHTMLSink records one raw-HTML (g:unsafe-html) render site. Fingerprint is a stable identity derived from the owner, source location, rendered field/expression, and the sink's ordinal within its owner, so a policy exception can target one exact sink and stop suppressing it when the source moves or the expression changes.

type RequestLimitPosture

type RequestLimitPosture struct {
	EndpointKind           string `json:"endpointKind,omitempty"`
	RawBodyBytes           int64  `json:"rawBodyBytes"`
	DecodedObjectBytes     int64  `json:"decodedObjectBytes,omitempty"`
	MultipartEnabled       bool   `json:"multipartEnabled"`
	MultipartMaxBytes      int64  `json:"multipartMaxBytes,omitempty"`
	CompressedBodyHandling string `json:"compressedBodyHandling,omitempty"`
	InstalledBeforeParse   bool   `json:"installedBeforeParse"`
	Phase                  string `json:"phase,omitempty"`
	Origin                 string `json:"origin,omitempty"`
}

RequestLimitPosture is the effective request-limit posture of one generated endpoint. It expresses more than a single byte cap: it distinguishes the raw body cap from decoded-object and multipart caps, records how compressed bodies are bounded, and records whether the cap is installed before the body is parsed (so a body limit precedes generated guards, CSRF token parsing, and handler execution). BodyLimitBytes on the parent entry mirrors RawBodyBytes.

type RouteEntry

type RouteEntry struct {
	PageID        string          `json:"pageId"`
	Route         string          `json:"route"`
	Kind          string          `json:"kind"`
	Method        string          `json:"method,omitempty"`
	Render        string          `json:"render,omitempty"`
	Guards        []string        `json:"guards,omitempty"`
	GuardEvidence []GuardEvidence `json:"guardEvidence,omitempty"`
	Public        bool            `json:"public"`
	DefaultDeny   bool            `json:"defaultDeny"`
	Source        string          `json:"source,omitempty"`
}

RouteEntry is the posture of one page/file route.

type SecurityManifest

type SecurityManifest struct {
	Version       int                  `json:"version"`
	GeneratedFrom string               `json:"generatedFrom"`
	BuildMode     string               `json:"buildMode,omitempty"`
	Routes        []RouteEntry         `json:"routes,omitempty"`
	Endpoints     []EndpointEntry      `json:"endpoints,omitempty"`
	Contracts     []ContractEntry      `json:"contracts,omitempty"`
	Observability []ObservabilityEntry `json:"observability,omitempty"`
	CORS          CORSPosture          `json:"cors"`
	Frontend      FrontendSurface      `json:"frontend"`
	Obligations   []ObligationEntry    `json:"obligations,omitempty"`
	Waivers       []WaiverDeclaration  `json:"waivers,omitempty"`
}

SecurityManifest is the declarative posture of one built module.

func Build

func Build(config gowdk.Config, ir gwdkir.Program) SecurityManifest

Build projects validated IR into a SecurityManifest. It reuses compiler.BuildRouteMetadataFromIR so the posture matches the CLI routes and endpoints reports exactly.

func (SecurityManifest) Relativize

func (manifest SecurityManifest) Relativize(root string) SecurityManifest

Relativize returns a copy of the manifest with every source-location field rewritten relative to root using forward slashes. Absolute discovery paths otherwise embed the checkout location in the posture, so the digests derived from it differ between machines and gowdk audit --check-tests can fail in CI even when the schema, policy, and posture are unchanged. RawHTMLSink fingerprints are recomputed from the relativized source so a pinned policy exception stays portable too. An empty root, or a reference that cannot be made relative to root, leaves the reference unchanged.

type UnguardedRoute

type UnguardedRoute struct {
	Route  string `json:"route"`
	Source string `json:"source,omitempty"`
}

UnguardedRoute records one client-visible route that relies on generated default-deny handling because the source declared no guard.

type WaiverDeclaration

type WaiverDeclaration struct {
	Code          string `json:"code"`
	Target        string `json:"target,omitempty"`
	Owner         string `json:"owner,omitempty"`
	Justification string `json:"justification,omitempty"`
	Expires       string `json:"expires,omitempty"`
	Ticket        string `json:"ticket,omitempty"`
	PolicyDigest  string `json:"policyDigest,omitempty"`
	PostureDigest string `json:"postureDigest,omitempty"`
	Policy        string `json:"policy,omitempty"`
	Source        string `json:"source,omitempty"`
}

WaiverDeclaration records one declared `waive` rule from a *.audit.gwdk file, independent of whether it currently suppresses a finding. Recording the declared waivers in gowdk-security.json keeps every suppression decision visible in the build's security metadata; gowdk audit decides which ones are valid, expired, or stale.