auth

func LowerSecurityRequirements ¶

func LowerSecurityRequirements(c lowering.Ctx, reqs []*soa.SecurityRequirement, base string) ([]ir.AuthRequirement, []ir.Diagnostic)

LowerSecurityRequirements lowers an OR-of-ANDs security list (ir-design §9) declared under base — the pointer of the node carrying the list, which is "" at the document root and an operation's own declaration pointer, never its mount, otherwise: a nil list inherits the enclosing default; a non-nil list yields one AuthRequirement per surviving option, each diagnosed if need be at its own base+/security/<index> pointer. An empty option object {} means "no auth is one acceptable choice".

An entry the source wrote as something other than an object is not an option at all, and is dropped whole on the same terms — see writtenAsObject, which is what tells it from the {} above. It draws no report from here, on the grounds LowerSecuritySchemes states for the same shape: the loader's type-mismatch already names both the entry and what was wrong with it.

A requirement is a conjunction: every member must resolve for the option to mean anything, so an option naming even one undeclared scheme is dropped in full rather than surviving with just that member gone (issue #41) — the latter would silently rewrite "this option requires an undeclared scheme" as "no auth is also fine", the empty-option encoding above. When every option in an originally non-empty list drops this way, the list itself collapses to nil — "inherits the enclosing default" — rather than surfacing as [], which ir-design §9 reserves for a deliberate "explicitly public" declaration. A list the source declared empty to begin with is left untouched: that [] is real, not a byproduct of dropping.

What that collapse costs, deliberately: a carrier whose every option drops becomes indistinguishable from one that never declared security, so an operation reads as requiring whatever the service default requires — a scheme it never named — or as unauthenticated where there is no default. Both misstate the source, because the IR has no encoding for "auth is required but its scheme is undeclared" and issue #14 forbids minting an AuthID nothing backs. nil is chosen because it is the only spelling that never reduces a demanded requirement to explicitly public, and every collapse carries an error diagnostic. The dropped text is not kept under Unmodeled: a name that resolves to nothing is a defect in the document rather than a construct the IR declines to model, which is the call an unresolvable $ref in a schema position and an unresolvable discriminator mapping already get here.

func LowerSecuritySchemes ¶

func LowerSecuritySchemes(c lowering.Ctx) (map[ir.AuthID]ir.AuthScheme, []ir.Diagnostic)

LowerSecuritySchemes interns every declared security scheme into the auth registry keyed by ids.Auth(name) (ir-design §9). Run before the service walk so operation- and document-level requirements reference registered IDs.

An entry whose $ref resolves to nothing is reported at its own components pointer and interned nowhere. It is reported here rather than left to the requirements that name it, because nothing has to name it: the load phase's report of the same failure carries no pointer at all (issue #235), so an unreferenced entry would otherwise be a scheme the document declares, the IR silently drops, and no diagnostic sites.

An entry that resolves to an object but names no mechanism is refused for the same reason and reported the same way — see mechanismRefusalDiag. Those two are the only entries reported as interning nothing; every other diagnostic from here is about a scheme that did intern (see preserveUnreadFields).