Module adcp.types.domains.trusted_match.identity_match_request

Classes

class Attestation (**data: Any)

Expand source code

class Attestation(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    issuer: Annotated[
        brand_ref.BrandReference,
        Field(
            description='Attestation authority / identity issuer, referenced as a vendor BrandRef (e.g. {"domain": "world.org"}) — the same vendor-reference shape AdCP uses for measurement and signals vendors. The issuer\'s canonical domain is the anchor; brand.json hosting is optional. `scheme` selects the verifier version within the issuer.'
        ),
    ]
    scheme: Annotated[
        str,
        Field(
            description='Proof scheme and version, e.g. "world_id_v4". Selects how `proof` is verified.'
        ),
    ]
    relying_party_id: Annotated[
        str | None,
        Field(
            description="Relying-party id the proof was minted for. The receiver checks this against the relying_party_id's published owner (brand.json `identity_relying_parties[]`) so a forwarded proof cannot be replayed under a different owner."
        ),
    ] = None
    action: Annotated[
        str | None,
        Field(
            description='Issuer action/scope the proof was bound to (e.g. "humanity-check-for-ads").'
        ),
    ] = None
    claims: Annotated[
        list[attestation_claim.AttestationClaim],
        Field(
            description='Claims this attestation establishes. Closed, issuer-agnostic set.',
            max_length=16,
            min_length=1,
        ),
    ]
    verification_level: Annotated[
        VerificationLevel | None,
        Field(
            description='Credential strength (e.g. World ID Orb = biometric unique-human; Device = weaker; Document = passport/NFC).'
        ),
    ] = None
    signal_binding: Annotated[
        str | None,
        Field(
            description='Hash of the signal the proof commits to. The receiver MUST verify it matches the context the receiver expects (e.g. a buyer-issued nonce or the request_id) and that the attestation is within its freshness window; this, plus nullifier-reuse tracking, is the replay defense.'
        ),
    ] = None
    proof: Annotated[
        dict[str, Any],
        Field(
            description="Scheme-specific verifiable proof material. Opaque to this schema; validated by the scheme's verifier. MUST carry only scheme-defined verification material — never page context or additional user identifiers."
        ),
    ]
    expires_at: Annotated[
        AwareDatetime | None,
        Field(description='Attestation validity horizon. Receivers MUST reject when past.'),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var action : str | None

var claims : list[AttestationClaim]

var expires_at : pydantic.types.AwareDatetime | None

var issuer : BrandReference

var model_config

var proof : dict[str, typing.Any]

var relying_party_id : str | None

var scheme : str

var signal_binding : str | None

var verification_level : VerificationLevel | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Consent (**data: Any)

Expand source code

class Consent(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    gdpr: Annotated[
        StrictBool | None, Field(description='Whether GDPR applies to this request.')
    ] = None
    tcf_consent: Annotated[
        str | None, Field(description='IAB TCF v2.2 consent string. Present when gdpr is true.')
    ] = None
    gpp: Annotated[str | None, Field(description='IAB Global Privacy Platform string.')] = None
    us_privacy: Annotated[
        str | None,
        Field(
            deprecated=True,
            description='US Privacy string (CCPA). Deprecated in favor of GPP but still widely used.',
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var gdpr : bool | None

var gpp : str | None

var model_config

var tcf_consent : str | None

var us_privacy : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Identity (**data: Any)

Expand source code

class Identity(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    user_token: Annotated[
        str,
        Field(
            description='Opaque token from an identity provider (ID5, LiveRamp, UID2) or publisher-generated. Buyer may map to internal identity graph but cannot reverse to PII.'
        ),
    ]
    uid_type: Annotated[
        uid_type_1.UidType,
        Field(
            description='Type of the user identifier. Tells the buyer which identity graph to resolve against, avoiding trial-and-error matching.'
        ),
    ]
    attestation: Annotated[
        Attestation | None,
        Field(
            description="Optional verifiable proof ABOUT this identity (e.g. World ID proof-of-personhood and/or age). The receiver MUST verify it (see conformance) and MUST treat an absent-or-unverifiable attestation as 'no attestation' — never as an asserted-true claim. Issuer-agnostic: World ID is the first scheme; mDL / VC-style issuers use the same shape. Receivers MUST bound attestation size to prevent DoS."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var attestation : Attestation | None

var model_config

var uid_type : UidType

var user_token : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class IdentityMatchRequest (**data: Any)

Expand source code

class IdentityMatchRequest(AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='forbid',
    )
    field_schema: Annotated[
        AnyUrl | None,
        Field(
            alias='$schema', description='Optional schema URI for validation. Ignored at runtime.'
        ),
    ] = None
    type: Annotated[
        Literal['identity_match_request'],
        Field(description='Message type discriminator for deserialization.'),
    ] = 'identity_match_request'
    protocol_version: Annotated[
        str | None,
        Field(
            description='TMP protocol version. Allows receivers to handle semantic differences across versions.'
        ),
    ] = '1.0'
    request_id: Annotated[
        str,
        Field(
            description='Unique request identifier. MUST NOT correlate with any context match request_id.'
        ),
    ]
    seller_agent_url: Annotated[
        AnyUrl,
        Field(
            description="API endpoint URL of the seller agent issuing this request. The buyer's identity-match service uses this to resolve the active package set it has registered for this seller; when `package_ids` is omitted, evaluation occurs against that full set. If `seller_agent_url` does not match any seller for which the buyer has registered active packages, the buyer MUST return an empty `eligible_package_ids` set — it MUST NOT fall back to evaluating against another seller's active set. Compared using the AdCP URL canonicalization rules, not byte-equality — see docs/reference/url-canonicalization. Consistent with `seller_agent.agent_url` on `AvailablePackage` and `agent_url` in `adagents.json`."
        ),
    ]
    identities: Annotated[
        list[Identity],
        Field(
            description='Identity tokens for the user, each tagged with its type. Publishers SHOULD include every token they have available — the buyer resolves on whichever graph matches. Entry order is not semantically significant; buyers use their own preference order when multiple entries resolve. Duplicate `(uid_type, user_token)` pairs MUST NOT appear; routers MAY reject or dedupe. `maxItems: 3` matches the TMPX plaintext budget (~120 bytes after HPKE overhead fits three 32-byte tokens); exceeding it forces buyer-side truncation.',
            max_length=3,
            min_length=1,
        ),
    ]
    consent: Annotated[
        Consent | None,
        Field(
            description='Privacy consent signals. Buyers in regulated jurisdictions MUST NOT process the user token without consent information.'
        ),
    ] = None
    package_ids: Annotated[
        list[str] | None,
        Field(
            description="Optional. When omitted, the buyer evaluates eligibility against the full set of active packages it has registered for `seller_agent_url`. When provided, the composition of `package_ids` MUST be statistically independent of the current placement — sending only the page-specific subset would let the buyer correlate Identity Match with Context Match by comparing package sets. Two acceptable modes: (a) **all-active** — include every active package this buyer has at this publisher; (b) **fuzzed** — include a random sample of active packages, optionally padded with synthetic non-existent IDs, drawn from a distribution that does not depend on the current placement. The buyer's silent-drop behavior on unknown IDs (specified below) is what makes synthetic-ID padding safe — they do not affect the response shape and cannot leak registry membership. When both `seller_agent_url` and `package_ids` are present, the buyer evaluates against the intersection of its registered active set and `package_ids`; IDs in `package_ids` that the buyer has not registered for this seller MUST be silently ignored (not surfaced as errors) to avoid leaking registry membership back to the publisher.",
            min_length=1,
        ),
    ] = None
    country: Annotated[
        str | None,
        Field(
            description='ISO 3166-1 alpha-2 country code. Routing directive for the TMP Router — used to select the correct regional provider. The router MUST strip this field before forwarding the request to the buyer agent. Not an identity signal.',
            pattern='^[A-Z]{2}$',
        ),
    ] = None
    sealed_credentials: Annotated[
        list[SealedCredential] | None,
        Field(
            description='Optional HPKE-sealed credentials addressed to specific audiences — the network-as-RP ("issuer-as-RP"/Mechanism B) carrier. Each payload is opaque to the publisher, who relays it untouched; the inner plaintext is an `attestation` (see identities[].attestation) scoped to the audience\'s relying party. Reuses the TMPX envelope format. Router handling (normative — see docs/trusted-match/specification.mdx): the router forwards each entry only to the provider that owns its `audience_kid` (not broadcast), folds `sealed_credentials` into the per-provider re-signature canonical bytes so an injected/swapped blob breaks the signature, and includes a `sealed_credentials_hash` in the dedup cache key. Receivers decrypt only entries whose `audience_kid` they hold a key for and ignore the rest. Receivers MUST bound count and size to prevent DoS amplification.',
            max_length=8,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var consent : Consent | None

var country : str | None

var field_schema : pydantic.networks.AnyUrl | None

var identities : list[Identity]

var model_config

var package_ids : list[str] | None

var protocol_version : str | None

var request_id : str

var sealed_credentials : list[SealedCredential] | None

var seller_agent_url : pydantic.networks.AnyUrl

var type : Literal['identity_match_request']

Inherited members

• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class SealedCredential (**data: Any)

Expand source code

class SealedCredential(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    audience_kid: Annotated[
        str,
        Field(
            description='Key id identifying the recipient (network / relying party) whose HPKE private key opens `payload`.',
            max_length=128,
        ),
    ]
    payload: Annotated[
        str,
        Field(
            description='HPKE-sealed attestation in the TMPX envelope format: `kid.base64url_nopad(ciphertext)` — unpadded base64url per RFC 4648 §5. Opaque pass-through for the publisher.',
            max_length=8192,
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var audience_kid : str

var model_config

var payload : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class VerificationLevel (*args, **kwds)

Expand source code

class VerificationLevel(StrEnum):
    orb = 'orb'
    device = 'device'
    document = 'document'

Enum where members are also (and must be) strings

Ancestors

• enum.StrEnum
• builtins.str
• enum.ReprEnum
• enum.Enum

Class variables

var device

var document

var orb