targeting

type AgeResolver interface {
	ResolveRequiredAge(ctx context.Context, pkgID, country string) (claim tmproto.AttestationClaim, ok bool)
}

type AttestationVerifier interface {
	Verify(ctx context.Context, att *tmproto.Attestation, vctx VerifyContext) (VerifiedIdentity, error)
}

type Bitmap interface {
	Contains(v string) bool
}

type ContextEngine struct {
	// contains filtered or unexported fields
}

type ContextEngineConfig struct {
	// ProviderID is the publisher-assigned identifier for this provider
	// registration. Used in logs, metrics, and suppression keys (see
	// tmproto.ProviderRegistration.ProviderID). Stable for the engine's
	// lifetime; rotate by restarting with a new value.
	ProviderID string

	// Properties is the registry-derived global (and optionally
	// per-package) property bitmap. Requests whose property_rid is not
	// in Properties.Global short-circuit before any storage lookup.
	Properties PropertyList

	// Storage is the read surface for media-buy resolution, package
	// configs, topic data, signal targeting, and suppression. Required.
	Storage ContextStorage

	// AcceptedTaxonomies enumerates the topic taxonomies this deployment
	// trusts on inbound ContextSignals and consults on storage artifact
	// / package topic lookups. Empty disables topic targeting: every
	// TopicTargets package fails the topic check (fail-closed) — a
	// deployment that wants topic targeting MUST declare at least one
	// accepted taxonomy.
	//
	// A publisher who sends ContextSignals.Topics with an empty
	// TaxonomySource gets a Taxonomy{Source: ""} key that
	// Taxonomy.Validate rejects and that no deployment can configure as
	// accepted. Those topics are silently dropped.
	AcceptedTaxonomies []topicstore.Taxonomy

	// Now is the clock the engine uses for media-buy date filtering.
	// Defaults to time.Now; overridable for tests.
	Now func() time.Time

	Metrics Metrics // nil = noop
}

type ContextResult struct {
	RequestID string
	Offers    []tmproto.Offer
	Signals   map[string]any
}

type ContextStorage interface {
	// ActivePackages returns the package IDs the deployment offers for
	// the given (sellerAgentURL, propertyID, country, placementID)
	// tuple at `now` — i.e., every package whose media buy is active
	// (date / geo / property) and that itself is willing to serve the
	// placement.
	//
	// The engine consults this on every request, not only when
	// req.PackageIDs is omitted. When req.PackageIDs IS present the
	// engine intersects this set with the inbound list, per the TMP
	// spec's "intersection of registered active set and package_ids"
	// rule (see IdentityMatchRequest.PackageIDs docstring in
	// tmproto/types_gen.go — the principle applies to context-match
	// too). Skipping this step would let a stale PackageContextConfig
	// for an expired media buy still produce offers if a publisher
	// names it explicitly.
	ActivePackages(ctx context.Context, sellerAgentURL, propertyID, country, placementID string, now time.Time) ([]string, error)

	// ContextConfig returns the package's context-side configuration.
	// `ok == false` (with err == nil) means no config is stored for that
	// package — the engine skips it.
	//
	// Storage implementations MAY also implement an optional
	// `ContextConfigs(ctx, []string) ([]*PackageContextConfig, error)`
	// method that returns every requested package's config in a
	// single round-trip; the engine feature-detects that method to
	// collapse per-package fetches into one MGet when planning
	// signal-targeting lookups. Implementations that do not provide
	// it fall back to repeated ContextConfig calls.
	ContextConfig(ctx context.Context, packageID string) (cfg *PackageContextConfig, ok bool, err error)

	// ArtifactTopics returns the raw topic ids stored for `ref` under
	// `tax`. The engine namespaces them via topicstore.NamespaceTopic
	// before joining; storage returns the un-namespaced ids it has on
	// hand. nil (with err == nil) means no topics are stored.
	ArtifactTopics(ctx context.Context, tax topicstore.Taxonomy, ref string) ([]string, error)

	// PackageTopics returns the raw topic ids `packageID` targets under
	// `tax`. Same shape as ArtifactTopics.
	PackageTopics(ctx context.Context, tax topicstore.Taxonomy, packageID string) ([]string, error)

	// IsPropertySuppressed reports whether `propertyRID` is currently
	// suppressed for `providerID`. Suppressions are deployment-scoped
	// kill switches; a true return short-circuits the entire request.
	IsPropertySuppressed(ctx context.Context, providerID, propertyRID string) (bool, error)

	// IsGeoSuppressed reports whether `country` is currently suppressed
	// for `providerID`. Same kill-switch semantics as
	// IsPropertySuppressed.
	IsGeoSuppressed(ctx context.Context, providerID, country string) (bool, error)

	// SignalMGet fetches the raw CSV-encoded signal-id strings stored
	// at each requested signal:* key. The returned slice is aligned 1:1
	// with the input; empty string at index i means "missing key".
	// Used by the engine to evaluate context-attribute signal targeting
	// in a single round-trip across every candidate package per request.
	SignalMGet(ctx context.Context, keys ...string) ([]string, error)
}

type CredentialObserver interface {
	// Dropped fires once per credential treated as absent, with a PreCheck* or
	// Drop* reason label.
	Dropped(ctx context.Context, reason string)
	// VerifierFailed fires when the verifier itself returned an error — kept
	// distinct from Dropped so a down/misconfigured verifier is observable, not
	// mistaken for organic "no humans verified".
	VerifierFailed(ctx context.Context)
}

type IdentityEngine struct {
	// contains filtered or unexported fields
}

type IdentityEngineConfig struct {
	Audience *audience.Service // nil = identity evaluation is segment-blind
	Metrics  Metrics           // nil = noop
}

type IdentityResult struct {
	RequestID   string
	Eligibility []tmproto.PackageEligibility

	// Verified carries the identities the verified-identity stage validated
	// (verify-before-trust). The TMPX seal step encodes their nullifiers onto
	// the wire so the buyer can frequency-cap / unique-human gate on its own
	// relying-party-scoped pseudonym. Empty when no verifier is wired or no
	// attestation passed verification — the audience-only engine never sets
	// it. Never populated from sender-asserted inbound identities.
	Verified []VerifiedIdentity
}

type MapBitmap map[string]struct{}

type Metrics interface {
	ContextEvaluated(ctx context.Context, stage string, passed bool)
	IdentityEvaluated(ctx context.Context, stage string, passed bool)
	StoreError(ctx context.Context, operation string, err error)
	Latency(ctx context.Context, stage string, d time.Duration)
}

type OfferConfigJSON struct {
	DealID       string             `json:"deal_id,omitempty"`
	Brand        json.RawMessage    `json:"brand,omitempty"`
	Price        tmproto.OfferPrice `json:"price"`
	Summary      string             `json:"summary,omitempty"`
	ManifestType string             `json:"manifest_type,omitempty"`
	Macros       map[string]string  `json:"macros,omitempty"`
}

type PackageContextConfig struct {
	PackageID    string   `json:"package_id"`
	MediaBuyID   string   `json:"media_buy_id,omitempty"`
	TopicTargets bool     `json:"topic_targets,omitempty"`
	PropertyRIDs []string `json:"property_rids,omitempty"`
	EmitSegments []string `json:"emit_segments,omitempty"`

	// ContextSignals gates the package on context-attribute signal
	// targeting. Nil or empty profile passes vacuously. Restricted to
	// context attributes — see signalstore.AllowedKeyTypes;
	// identity-keyed cfgs are rejected by signalstore.Profile.Validate.
	//
	// Topic cfgs key on a namespaced value, NOT the bare topic id: the
	// engine prefixes each topic with its taxonomy as
	// "{taxonomy_source}:{taxonomy_id}:{topic_id}" (the
	// topicstore.Taxonomy.String() form) so the same topic id under
	// different taxonomies stays distinct. The spec carries the
	// taxonomy once on the ContextSignals envelope rather than per
	// topic, so anyone authoring these cfgs out-of-band MUST apply the
	// same prefix to a topic cfg's stored signal value.
	ContextSignals *signalstore.Profile `json:"context_signals,omitempty"`

	Offers           []OfferConfigJSON  `json:"offers,omitempty"`
	Brand            json.RawMessage    `json:"brand,omitempty"`
	Price            tmproto.OfferPrice `json:"price"`
	Summary          string             `json:"summary,omitempty"`
	ManifestType     string             `json:"manifest_type,omitempty"`
	CreativeManifest json.RawMessage    `json:"creative_manifest,omitempty"`
	Macros           map[string]string  `json:"macros,omitempty"`
	// contains filtered or unexported fields
}

type PackageIdentityConfig struct {
	TargetSegments *SegmentRule

	// RequiresVerifiedIdentity, when true, makes the package ineligible
	// unless a verified attestation is present for the request (fail-closed).
	// This is a presence gate only; the required age threshold (if any) is
	// resolved per (package, geo) through the Service's AgeResolver, not
	// stored here, so age policy can change without re-publishing package
	// config.
	//
	// The eligibility engine honors this field today. Populating it from the
	// identityconfig snapshot (a new identityconfig.Entry field + carrying it
	// through Lookup/GetBySeller, which currently index only *SegmentRule) is
	// a follow-up; until then the age gate via AgeResolver is the live
	// verified-identity gate.
	RequiresVerifiedIdentity bool
}

type PropertyList struct {
	// Global is the set of all property RIDs this agent handles.
	// A request for a property not in Global is rejected immediately.
	// Nil means no global filter (all properties pass).
	Global Bitmap

	// ByPackage maps package_id to a property RID bitmap.
	// If a package has an entry, only those properties are eligible.
	// If a package has no entry, all properties are eligible for it.
	ByPackage map[string]Bitmap
}

type RecipientKey struct {
	PrivateKey     *ecdh.PrivateKey
	RelyingPartyID string
}

type ResolvedPackages struct {
	IdentityConfigs map[string]*PackageIdentityConfig // pkgID → config
}

type SegmentRule struct {
	AllOf  []string
	AnyOf  []string
	NoneOf []string
}

type UserIdentity struct {
	UserToken string `json:"user_token"`
	UIDType   string `json:"uid_type"`
}

type VerifiedIdentity struct {
	// Nullifier is the relying-party-scoped, Sybil-resistant pseudonym. It is
	// the frequency-cap key (namespaced by RelyingPartyID, see CapKey) — never
	// used raw, so it cannot collide across relying parties.
	Nullifier string
	// RelyingPartyID is the RP scope this nullifier and these claims belong
	// to. The receiver confirmed it matches the RP this receiver acts as.
	RelyingPartyID string
	// Claims is the verified claim set, normalised to the closed
	// attestation-claim vocabulary.
	Claims map[tmproto.AttestationClaim]struct{}
}

type VerifiedIdentityRequirement struct {
	// RequiresVerifiedHuman gates the package on at least one present verified
	// identity (a verified unique human).
	RequiresVerifiedHuman bool
	// RequiresAge gates the package on a verified age threshold. When set, a
	// verified identity must satisfy RequiredAge. RequiredAge may be empty even
	// when RequiresAge is set (the policy applies but resolved no closed-set
	// claim); no verified identity can satisfy an empty claim, so the package
	// is then rejected — fail-closed. Carried separately from RequiredAge so
	// "age required, threshold empty" is not collapsed into "no age
	// requirement".
	RequiresAge bool
	// RequiredAge is the age claim a verified identity must satisfy when
	// RequiresAge is set.
	RequiredAge tmproto.AttestationClaim
}

type VerifyContext struct {
	// RequestID is the anchor the attestation's signal_binding must commit to.
	RequestID string
	// Country is ISO-3166-1 alpha-2, for geo-scoped verifier/age logic.
	Country string
	// ExpectedRelyingPartyID is the relying party THIS receiver acts as for
	// the audience that selected the recipient key. The attestation's
	// relying_party_id must equal it (enforced SDK-side before Verify) so a
	// proof minted for another RP cannot be replayed here.
	ExpectedRelyingPartyID string
	// Now is the reference time for expiry checks.
	Now time.Time
}