reference

type ClearReferenceIn struct {
	// Set is the set to clear in, from the path.
	Set string `json:"-" url:"set"`
	// Key is the exact override key to remove.
	Key string `json:"-" url:"key"`
}

type ClearReferenceOut struct {
	// Set is the set cleared in.
	Set string `json:"set"`
	// Key is the entry named.
	Key string `json:"key"`
	// Cleared is false when your org held no such override — which is not an
	// error, it is the honest answer to a removal that had nothing to remove.
	Cleared bool `json:"cleared"`
	// Overrides is how many your org still holds in this set.
	Overrides int `json:"overrides"`
}

type Entry struct {
	// Key is the normalised member: a domain, a CIDR, an IIN prefix, a digest.
	Key string
	// Value is what the publisher says about it — class, operator, region,
	// scheme. Facts, never a verdict: the verdict is the caller's policy, and a
	// baseline that shipped verdicts would be making every tenant's policy for it.
	Value map[string]string
	// Score is a risk weight in [0,1] where the source expresses one, else zero.
	Score float64
	// Orgs and N are the k-anonymity evidence for a derived entry: how many
	// distinct organisations and how many observations produced it. Zero for a
	// published source, where the evidence is the licence instead.
	Orgs uint32
	N    uint64
}

type Grant string

type Kind string

type Match string

type ReferenceAnswer struct {
	// Set is the set consulted.
	Set string `json:"set"`
	// Key is the key as asked.
	Key string `json:"key"`
	// Hit is whether the key is a member. It is meaningful ONLY when Refusal is
	// empty: false with a refusal means the set could not be consulted, which is
	// not the same as the key being clean.
	Hit bool `json:"hit"`
	// From is override or baseline — which plane answered.
	From string `json:"from,omitempty"`
	// Matched is the member that covered the key, which for a domain or a network
	// is the enclosing entry rather than the key itself.
	Matched string `json:"matched,omitempty"`
	// Verdict is the tenant's own allow or deny, present only for an override.
	// The baseline never carries one: it states facts and leaves the decision to
	// the caller's policy.
	Verdict string `json:"verdict,omitempty"`
	// Value is what the publisher says about the member — class, operator,
	// scheme, region.
	Value map[string]string `json:"value,omitempty"`
	// Score is the published risk weight where the source expresses one.
	Score float64 `json:"score,omitempty"`
	// Version is the exact baseline version consulted, composed of each
	// contributing publisher and its content digest. It is what makes a decision
	// reproducible: an auditor takes this string and knows precisely what was
	// consulted.
	Version string `json:"version,omitempty"`
	// AsOf is when the oldest contributing publisher was current, RFC 3339.
	AsOf string `json:"asOf,omitempty"`
	// Age is how old that is, as a duration.
	Age string `json:"age,omitempty"`
	// Stale is whether the set is past its freshness bound. A stale set still
	// answers — yesterday's list beats none — and this is how a decision knows it
	// leaned on one.
	Stale bool `json:"stale,omitempty"`
	// Refusal is why the set could not be consulted, when it could not: never
	// loaded, held elsewhere, or a source we hold no licence for. Non-empty means
	// Hit must not be read as an answer.
	Refusal string `json:"refusal,omitempty"`
}

type ReferenceIn struct {
	// Set is the set to describe, from the path.
	Set string `json:"-" url:"set"`
	// After pages the override listing: the last key of the previous page.
	After string `json:"after"`
	// Limit caps the override listing: default 200, maximum 1000.
	Limit int `json:"limit"`
}

type ReferenceOut struct {
	// Set is the published set: its version, its freshness and its sources.
	Set ReferenceSet `json:"set"`
	// Overrides is YOUR org's entries over that baseline, in key order. They are
	// held in your organisation's own store and are not visible to any other.
	Overrides []ReferenceOverride `json:"overrides"`
	// Next is the key to page from, empty when this is the last page.
	Next string `json:"next,omitempty"`
}

type ReferenceOverride struct {
	// Key is the member this organisation is speaking about.
	Key string `json:"key"`
	// Verdict is allow or deny.
	Verdict string `json:"verdict"`
	// Note is why, in the operator's own words. Optional, and bounded.
	Note string `json:"note,omitempty"`
	// At is when it was written, RFC 3339.
	At string `json:"at"`
	// By is who wrote it.
	By string `json:"by,omitempty"`
}

type ReferenceOverrideIn struct {
	// Key is the member: a domain, a CIDR or address, an issuer prefix, a
	// device digest. It is matched the same way the baseline is, so a deny on
	// tempbox.example also covers mail.tempbox.example.
	Key string `json:"key"`
	// Verdict is allow or deny, and nothing else. An override is a decision —
	// unlike a baseline entry, which states facts and leaves the decision to your
	// policy — because your organisation is the only party entitled to say "for
	// us, this one is fine".
	Verdict string `json:"verdict"`
	// Note is why, in your own words. Optional, bounded to 512 bytes.
	Note string `json:"note,omitempty"`
}

type ReferenceReceipt struct {
	// Source is the publisher this receipt is for.
	Source string `json:"source"`
	// Version is the digest of what that publisher supplied, so a refresh that
	// changed nothing can be told from a refresh that did not run.
	Version string `json:"version"`
	// AsOf is when the load happened, RFC 3339. Absent is dated on arrival, which
	// can only make the list look older than it is.
	AsOf string `json:"asOf,omitempty"`
	// Keys is how many designations that load carried. Zero from a publisher who
	// designates somebody is a failed load wearing a successful one's clothes,
	// and belongs in Refusal instead.
	Keys int `json:"keys"`
	// Refusal is why the load failed, when it did.
	Refusal string `json:"refusal,omitempty"`
}

type ReferenceSet struct {
	// Set is the name this set is addressed by.
	Set string `json:"set"`
	// Kind is how the baseline comes to exist: fetch (downloaded from a
	// publisher), local (computed here), attest (held by the component that
	// screens against it, freshness reported), or seam (declared and NOT held,
	// because the source needs a licence we do not have).
	Kind string `json:"kind"`
	// What the set holds, in one sentence.
	What string `json:"what"`
	// Match is how a key is tested: exact, domain, net, digits, pattern or range.
	Match string `json:"match"`
	// Version is the exact baseline consulted — every contributing publisher and
	// its content digest. A decision records this and an auditor resolves it back.
	Version string `json:"version,omitempty"`
	// AsOf is when the OLDEST contributing publisher was current, RFC 3339. The
	// oldest and not the newest: a set is exactly as fresh as its weakest source.
	AsOf string `json:"asOf,omitempty"`
	// Age is how long ago that was.
	Age string `json:"age,omitempty"`
	// MaxAge is how old this set may be before it is stale.
	MaxAge string `json:"maxAge"`
	// Stale is whether it is past that bound. A stale set still answers and says
	// so, because yesterday's list beats none.
	Stale bool `json:"stale"`
	// Keys is how many members the baseline carries.
	Keys int `json:"keys"`
	// Overrides is how many entries YOUR org has laid over this baseline.
	Overrides int `json:"overrides"`
	// Sources is each contributing publisher, its licence and its own freshness.
	Sources []ReferenceSource `json:"sources,omitempty"`
	// Refusal names why the set cannot be relied on, when it cannot: never
	// loaded, held elsewhere, or a licence we do not hold. Non-empty means a
	// lookup against this set will not answer, rather than answering clean.
	Refusal string `json:"refusal,omitempty"`
}

type ReferenceSetsOut struct {
	// Sets is the whole catalog, in a stable order.
	Sets []ReferenceSet `json:"sets"`
	// Stale names the sets past their freshness bound — the list to alarm on.
	Stale []string `json:"stale,omitempty"`
	// Refused names the sets that cannot be consulted at all. A key checked
	// against one of these is UNKNOWN, not clean.
	Refused []string `json:"refused,omitempty"`
}

type ReferenceSource struct {
	// Source is the publisher.
	Source string `json:"source"`
	// Origin is exactly where it was taken from, so it can be taken again.
	Origin string `json:"origin"`
	// Basis is the KIND of permission this publisher's data reaches you under:
	// licence (an explicit grant), registry (the registry of record publishing for
	// anyone to consult), operator (an operator's own machine-readable statement
	// about its own network, published for third parties to filter by — not a
	// licence, and not claimed as one), own (computed here), or none (nothing
	// reaches you: the membership is held by the component that screens against
	// it). It is on the wire so the licence position is an audit you can run.
	Basis string `json:"basis"`
	// Terms is the CITATION that basis points at — the licence identifier, the
	// registry, or the operator publication. A source with no stated terms is not
	// in the catalog.
	Terms string `json:"terms"`
	// Version is the content digest of what this publisher last supplied. Two
	// refreshes that agree on it took the same data.
	Version string `json:"version,omitempty"`
	// AsOf is when this publisher was current, RFC 3339.
	AsOf string `json:"asOf,omitempty"`
	// Keys is how many members this publisher contributed.
	Keys int `json:"keys"`
	// Refusal is why this publisher's last take failed, if it did. The set keeps
	// its previous version of this source and ages out visibly rather than
	// silently shrinking.
	Refusal string `json:"refusal,omitempty"`
}

type ReferenceTaken struct {
	// Source is the publisher.
	Source string `json:"source"`
	// Version is the content digest that landed.
	Version string `json:"version,omitempty"`
	// Keys is how many members it carries.
	Keys int `json:"keys"`
	// Wrote is how many rows this run actually wrote. Zero with Unchanged means
	// the publisher served the same set again.
	Wrote int `json:"wrote"`
	// Unchanged is true when the publisher's data was byte-for-byte the set we
	// already held.
	Unchanged bool `json:"unchanged,omitempty"`
	// Resumed is true when this run continued a version a previous run left
	// half-landed.
	Resumed bool `json:"resumed,omitempty"`
	// Refusal is why this publisher contributed nothing, if it did not. The set
	// keeps its previous version of this source rather than shrinking.
	Refusal string `json:"refusal,omitempty"`
}

type ReferenceVersion struct {
	// Set is the set.
	Set string `json:"set"`
	// Version is every contributing publisher and its content digest.
	Version string `json:"version,omitempty"`
	// AsOf is when the oldest of them was current, RFC 3339.
	AsOf string `json:"asOf,omitempty"`
	// Stale is whether it is past its freshness bound.
	Stale bool `json:"stale"`
	// Refusal is why it could not be consulted, when it could not.
	Refusal string `json:"refusal,omitempty"`
}

type RefreshReferenceIn struct {
	// Set is the set to refresh.
	Set string `json:"set"`
	// Receipts are supplied by the component that holds the membership, for a set
	// of kind attest. They are refused on any other kind, and a set of kind attest
	// is refused without them: this plane never invents a freshness it did not
	// observe.
	Receipts []ReferenceReceipt `json:"receipts,omitempty" url:"-"`
	// Force accepts a take whose size moved past the change bound. A publisher
	// serving a tenth or ten times its previous list is refused by default and the
	// previous version is left standing; this is the operator saying the change is
	// real. It cannot make an empty, truncated or unparseable take land — those are
	// errors, not magnitudes.
	Force bool `json:"force,omitempty"`
}

type RefreshReferenceOut struct {
	// Set is the set refreshed.
	Set string `json:"set"`
	// Took is what each publisher contributed.
	Took []ReferenceTaken `json:"took"`
	// Version is the set's new composed version.
	Version string `json:"version,omitempty"`
	// Stale is whether it is STILL past its freshness bound after the refresh,
	// which is what a publisher that has stopped answering looks like.
	Stale bool `json:"stale"`
}

type ResolveReferenceIn struct {
	// Sets narrows which sets to consult. Empty consults every set whose matcher
	// can read the keys given.
	Sets []string `json:"sets,omitempty" url:"-"`
	// Keys are the values to look up, at most 100 per call: email addresses or
	// domains, IP addresses, card prefixes, user-agent strings, autonomous system
	// numbers, device digests.
	Keys []string `json:"keys" url:"-"`
}

type ResolveReferenceOut struct {
	// Answers is one entry per (set, key) consulted.
	Answers []ReferenceAnswer `json:"answers"`
	// Consulted names the version of every set that took part, so a decision can
	// record precisely what it leaned on. Record this with the decision: it is
	// what makes the decision reproducible a year later.
	Consulted []ReferenceVersion `json:"consulted"`
	// Stale names the consulted sets past their freshness bound. Staleness is
	// itself a risk signal — a decision taken against a three-week-old list is a
	// weaker decision, and this is how it knows.
	Stale []string `json:"stale,omitempty"`
	// Refused names the consulted sets that could not answer at all. A key that
	// missed in one of these is UNKNOWN, not clean.
	Refused []string `json:"refused,omitempty"`
}

type Set struct {
	// Name is the address: /v1/risk/reference/<name>. One word, lower case.
	Name string
	// Kind decides what an empty set means and whether membership is held here.
	Kind Kind
	// What is one sentence an operator can read.
	What string
	// Match is how a key is tested against this set's entries.
	Match Match
	// MaxAge is how old a source's newest successful load may be before this set
	// is STALE. Past it the set still answers, and every answer says so — a stale
	// list answers "not listed" for everything and reads exactly like a clean
	// world, which is the failure this whole plane exists to make visible.
	MaxAge time.Duration
	// Sources are the publishers this set draws on. Empty for local and seam sets.
	Sources []Source
	// Refusal is why a seam set cannot be consulted. Non-empty ONLY for KindSeam,
	// and it names the licence we do not hold rather than saying "unavailable".
	Refusal string
}

type SetReferenceIn struct {
	// Set is the set to write in, from the path.
	Set string `json:"-" url:"set"`
	// Entries are the overrides to write, up to 1000 per call.
	Entries []ReferenceOverrideIn `json:"entries" url:"-"`
}

type SetReferenceOut struct {
	// Set is the set written in.
	Set string `json:"set"`
	// Written is how many entries this call wrote.
	Written int `json:"written"`
	// Overrides is how many your org now holds in this set.
	Overrides int `json:"overrides"`
}

type Source struct {
	// Name is the publisher, stable across versions — it is the key freshness is
	// tracked per.
	Name string
	// Origin is the exact URL fetched, so an auditor can take the same bytes.
	Origin string
	// Basis is the KIND of permission this data reaches a tenant under, from a
	// closed vocabulary. Required: the zero value is not a basis, and the catalog
	// gate refuses it.
	Basis Grant
	// Terms is the CITATION the basis points at — the licence identifier, the
	// registry, or the operator publication. Required: a basis with nothing behind
	// it is an assertion.
	Terms string
	// contains filtered or unexported fields
}