@adcp/sdk 5.23.0 → 5.25.0

package/compliance/cache/3.0.0/specialisms/signal-owned/index.yaml

@@ -1,316 +0,0 @@
-id: signal_owned
-version: "1.0.0"
-title: "Owned signal agent"
-protocol: signals
-category: signal_owned
-summary: "Signal agent serving first-party or proprietary audience data without external catalog verification."
-track: signals
-required_tools:
-  - get_signals
-
-narrative: |
-  You operate a first-party data platform — a retailer CDP, publisher contextual data
-  provider, or proprietary audience platform. Your signals are agent-native: they come
-  from your own data, not from third-party catalogs.
-
-  Buyers trust your agent directly. There's no external adagents.json to verify against —
-  provenance is the agent itself. This simplifies the flow: discovery and activation,
-  without the verification step that marketplace agents require.
-
-  Owned signal agents often have richer signal types. A retailer might expose purchase
-  frequency as a numeric signal (0-30 visits/month) or loyalty tier as categorical
-  (platinum/gold/silver/bronze). A publisher might expose content category, subscriber
-  tenure, or engagement scores.
-
-  This storyboard walks through discovery and both activation patterns.
-
-  Pricing is hard-required here for the same reason as signal marketplaces: signals
-  are rate-carded goods. Buyers cannot activate without a pricing_option_id to anchor
-  billing. Agents distributing first-party signals without commercial terms belong on
-  list_authorized_properties or a different specialism, not this one.
-
-agent:
-  interaction_model: owned_signals
-  capabilities: []
-  examples:
-    - "Retailer CDPs (e.g., loyalty and purchase data)"
-    - "Publisher contextual platforms (e.g., content category, subscriber data)"
-    - "First-party audience platforms (e.g., CRM-derived segments)"
-
-caller:
-  role: buyer_agent
-  example: "Scope3 (DSP)"
-
-prerequisites:
-  description: |
-    The buyer has a campaign brief with targeting objectives. The test kit provides
-    sample owned signal definitions with various value types (binary, categorical,
-    numeric) and pricing models.
-  test_kit: "test-kits/nova-motors.yaml"
-
-phases:
-  - id: capability_discovery
-    title: "Capability discovery"
-    narrative: |
-      The buyer calls get_adcp_capabilities to confirm the agent supports signals before discovering or activating audience data.
-
-    steps:
-      - id: get_capabilities
-        title: "Check agent capabilities"
-        narrative: |
-          Verify that the agent declares the expected protocol support before
-          proceeding with domain-specific operations.
-        task: get_adcp_capabilities
-        schema_ref: "protocol/get-adcp-capabilities-request.json"
-        response_schema_ref: "protocol/get-adcp-capabilities-response.json"
-        doc_ref: "/protocol/get_adcp_capabilities"
-        comply_scenario: capability_discovery
-        stateful: false
-        expected: |
-          Return capabilities declaring signals in supported_protocols, confirming the agent serves audience signals.
-        sample_request:
-          context:
-            correlation_id: "signal_owned--get_capabilities"
-        validations:
-          - check: response_schema
-            description: "Response matches get-adcp-capabilities-response.json schema"
-          - check: field_present
-            path: "supported_protocols"
-            description: "Agent declares supported protocols"
-
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "signal_owned--get_capabilities"
-            description: "Context correlation_id returned unchanged"
-  - id: discovery
-    title: "Signal discovery"
-    narrative: |
-      The buyer describes targeting objectives and your agent returns matching signals
-      from your proprietary data. Unlike marketplace agents, these signals have
-      signal_type "owned" — provenance is the agent itself.
-
-      Owned signals often include richer value types. A retailer can expose loyalty
-      tiers as categorical signals and purchase frequency as numeric signals, giving
-      buyers more precise targeting than binary include/exclude.
-
-    steps:
-      - id: search_owned_signals
-        title: "Discover owned signals"
-        narrative: |
-          The buyer searches for audience segments using a natural language description.
-          Your agent returns signals from your proprietary data — loyalty tiers, purchase
-          history, engagement scores, contextual categories.
-        task: get_signals
-        schema_ref: "signals/get-signals-request.json"
-        response_schema_ref: "signals/get-signals-response.json"
-        doc_ref: "/signals/tasks/get_signals"
-        comply_scenario: signals_flow
-        stateful: false
-        expected: |
-          Return matching signals from your proprietary data. Each signal must include:
-          - signal_agent_segment_id for activation
-          - signal_id with source: "agent_native"
-          - name, description, and value_type
-          - coverage_percentage
-          - pricing_options
-          - signal_type: "owned"
-
-          For categorical signals, include the allowed_values.
-          For numeric signals, include the range (min/max).
-
-        sample_request:
-          account:
-            brand:
-              domain: "novamotors.example"
-            operator: "pinnacle-agency.example"
-          signal_spec: "High-value customers likely to purchase electronics, with loyalty program data"
-
-          context:
-            correlation_id: "signal_owned--search_owned_signals"
-        validations:
-          - check: response_schema
-            description: "Response matches get-signals-response.json schema"
-          - check: field_present
-            path: "signals[0].signal_agent_segment_id"
-            description: "Each signal has a signal_agent_segment_id"
-          - check: field_present
-            path: "signals[0].pricing_options"
-            description: "Each signal has pricing options"
-
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "signal_owned--search_owned_signals"
-            description: "Context correlation_id returned unchanged"
-          - check: field_present
-            path: "signals[0].signal_id.source"
-            description: "Signal ID includes source discriminator"
-      - id: filter_by_criteria
-        title: "Filter signals by criteria"
-        narrative: |
-          The buyer narrows the search using filters — maximum CPM, specific signal
-          types, or coverage thresholds. This tests that your agent handles filter
-          parameters correctly and returns only matching signals.
-        task: get_signals
-        schema_ref: "signals/get-signals-request.json"
-        response_schema_ref: "signals/get-signals-response.json"
-        doc_ref: "/signals/tasks/get_signals"
-        comply_scenario: signals_flow
-        stateful: false
-        expected: |
-          Return only signals matching the filter criteria. If no signals match,
-          return an empty signals array — not an error.
-
-        sample_request:
-          account:
-            brand:
-              domain: "novamotors.example"
-            operator: "pinnacle-agency.example"
-          signal_spec: "Purchase behavior signals"
-          filters:
-            max_cpm: 5.00
-
-          context:
-            correlation_id: "signal_owned--filter_by_criteria"
-        validations:
-          - check: response_schema
-            description: "Response matches schema"
-          - check: field_present
-            path: "signals"
-            description: "Response contains a signals array"
-
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "signal_owned--filter_by_criteria"
-            description: "Context correlation_id returned unchanged"
-  - id: platform_activation
-    title: "Activate on a DSP"
-    narrative: |
-      The buyer activates a signal directly on a DSP. Your agent pushes the segment
-      to the platform and returns a segment_id the buyer uses for campaign targeting.
-
-      Use platform destinations when the buyer manages DSP campaigns directly.
-
-    steps:
-      - id: activate_on_platform
-        title: "Activate owned signal on a DSP"
-        narrative: |
-          The buyer selects a signal and activates it on a DSP. For owned signals,
-          this means your platform pushes first-party segment data to the DSP. The
-          buyer gets back a segment_id for targeting.
-        task: activate_signal
-        schema_ref: "signals/activate-signal-request.json"
-        response_schema_ref: "signals/activate-signal-response.json"
-        doc_ref: "/signals/tasks/activate_signal"
-        comply_scenario: signals_flow
-        stateful: true
-        expected: |
-          Return a deployment with:
-          - type: "platform"
-          - is_live status (may be async)
-          - activation_key with type: "segment_id" when live
-          - estimated_activation_duration_minutes if not immediately live
-
-        sample_request:
-          account:
-            brand:
-              domain: "novamotors.example"
-            operator: "pinnacle-agency.example"
-          signal_agent_segment_id: "prism_high_ltv"
-          pricing_option_id: "po_prism_flat_monthly"
-          destinations:
-            - type: "platform"
-              platform: "the-trade-desk"
-              account: "agency-123-ttd"
-          idempotency_key: "$generate:uuid_v4#signal_owned_activate_platform"
-          context:
-            correlation_id: "signal_owned--activate_on_platform"
-          ext:
-            test_platform:
-              test_run: true
-        validations:
-          - check: response_schema
-            description: "Response matches activate-signal-response.json schema"
-          - check: field_present
-            path: "deployments[0].type"
-            description: "Deployment includes type"
-
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "signal_owned--activate_on_platform"
-            description: "Context correlation_id returned unchanged"
-  - id: agent_activation
-    title: "Activate on a sales agent"
-    narrative: |
-      The buyer activates a signal on a sales agent. The SA records the activation
-      and handles downstream DSP coordination — the buyer doesn't need to know which
-      platform the SA uses.
-
-      This is the right pattern when buying media through a sales agent.
-
-    steps:
-      - id: activate_on_agent
-        title: "Activate owned signal on a sales agent"
-        narrative: |
-          The buyer activates a signal with the SA's URL as the destination. The
-          activation is typically synchronous. The SA records it internally and
-          applies the targeting when the buyer later calls create_media_buy.
-        task: activate_signal
-        schema_ref: "signals/activate-signal-request.json"
-        response_schema_ref: "signals/activate-signal-response.json"
-        doc_ref: "/signals/tasks/activate_signal"
-        comply_scenario: signals_flow
-        stateful: true
-        expected: |
-          Return a deployment with:
-          - type: "agent"
-          - agent_url matching the SA
-          - is_live: true (sync activation)
-          - activation_key with type: "key_value"
-          - deployed_at timestamp
-
-        sample_request:
-          account:
-            brand:
-              domain: "novamotors.example"
-            operator: "pinnacle-agency.example"
-          signal_agent_segment_id: "prism_cart_abandoner"
-          pricing_option_id: "po_prism_abandoner_cpm"
-          destinations:
-            - type: "agent"
-              agent_url: "https://wonderstruck.salesagents.example"
-          idempotency_key: "$generate:uuid_v4#signal_owned_activate_agent"
-          context:
-            correlation_id: "signal_owned--activate_on_agent"
-          ext:
-            test_platform:
-              test_run: true
-        validations:
-          - check: response_schema
-            description: "Response matches activate-signal-response.json schema"
-          - check: field_present
-            path: "deployments[0].activation_key"
-            description: "Deployment includes activation key"
-          - check: field_value
-            path: "deployments[0].type"
-            value: "agent"
-            description: "Deployment type is 'agent'"
-
-          - check: field_present
-            path: "context"
-            description: "Response echoes back the context object"
-          - check: field_value
-            path: "context.correlation_id"
-            value: "signal_owned--activate_on_agent"
-            description: "Context correlation_id returned unchanged"

package/compliance/cache/3.0.0/specialisms/signed-requests/index.yaml

@@ -1,192 +0,0 @@
-id: signed_requests
-version: "1.0.0"
-title: "Signed requests — RFC 9421 transport-layer verification"
-protocol: media-buy
-status: preview
-category: signed_requests
-summary: "Agent verifies RFC 9421 HTTP Signatures on incoming AdCP requests per the transport-layer profile. Graded against conformance vectors covering every checklist step and canonicalization-edge rule."
-track: security_transport
-required_tools:
-  - get_adcp_capabilities
-  # Additional tool families are exercised transport-layer only — the runner signs
-  # requests targeting any mutating AdCP operation (create_media_buy, update_media_buy,
-  # acquire_*, activate_signal, sync_creatives) and grades the verifier's response. The
-  # specialism is preview status pending runner implementation at adcontextprotocol/adcp#2331;
-  # when the runner ships, required_tools will expand to the concrete list of operations
-  # exercised.
-
-narrative: |
-  The signed-requests specialism certifies that an agent correctly implements the AdCP
-  RFC 9421 request-signing verifier per `docs/building/implementation/security.mdx#signed-requests-transport-layer`.
-
-  This is a transport-layer claim, not a protocol-specific one. A signed request can target
-  any mutating operation — most commonly `create_media_buy`, `update_media_buy`, `acquire_*`,
-  `activate_signal`, and `sync_creatives`. The claim is scoped to `media-buy` because that
-  is where the financial stake is highest, but the verifier behavior is the same across all
-  mutating operations.
-
-  The claim is certifiable only when the agent advertises `request_signing.supported: true`
-  in `get_adcp_capabilities`. An agent that does not advertise support is not tested against
-  this specialism — absence of advertisement is not a failure, it is a declaration that the
-  agent does not offer verified signed requests.
-
-  Grading is observable-behavior only. The runner constructs signed HTTP requests exactly
-  as documented in the conformance vectors at
-  `/compliance/{version}/test-vectors/request-signing/` and sends them to the agent. The
-  agent's responses are compared against the vectors' `expected_outcome`:
-
-  - Positive vectors MUST produce a non-4xx response — the agent accepted the signed request.
-  - Negative vectors MUST produce `401` with `WWW-Authenticate: Signature error="<code>"`,
-    where the `<code>` matches the vector's `expected_outcome.error_code` byte-for-byte.
-    The checklist step number is informational; grading is on the stable error code only.
-
-  The runner supplies signed requests; the agent is the verifier. A separate signer-side
-  storyboard may follow but is out of scope for this specialism — signers are easier to get
-  right, and a signer that produces valid signatures is proven correct by a conformant
-  verifier accepting them.
-
-  Three negative vectors — 016 (replayed nonce), 017 (key revoked), and 020 (per-keyid cap) —
-  assert verifier state the runner cannot set from the outside. Those vectors declare
-  `requires_contract` and are gated on the `signed_requests_runner` test-kit contract
-  at `test-kits/signed-requests-runner.yaml`, which specifies the runner's signing keyids,
-  a dedicated pre-revoked keyid (`test-revoked-2026`), and the grading-time per-keyid cap
-  the runner will target. Agents claiming the specialism MUST pre-configure their verifier
-  per that contract before the negative phase runs. If the agent does not satisfy the
-  contract (e.g., the runner can't coordinate the pre-state), the affected vectors grade
-  as FAIL, never as SKIP — the contract is a prerequisite for the claim, not an optional
-  extension.
-
-agent:
-  interaction_model: request_verifier
-  capabilities:
-    - verifies_request_signatures
-  examples:
-    - "AdCP seller implementing request verification"
-    - "Any agent advertising `request_signing.supported: true`"
-
-caller:
-  role: compliance_runner
-  example: "AdCP Verified runner (or equivalent signed-request grader)"
-
-prerequisites:
-  description: |
-    The agent MUST advertise `request_signing.supported: true` in `get_adcp_capabilities`.
-    The agent's verifier MUST be configured to accept requests signed by the test keypairs
-    published in `keys.json` alongside the conformance vectors — specifically, the runner's
-    signing keys (`test-ed25519-2026`, `test-es256-2026`) should be treated as coming from
-    a registered test counterparty whose JWKS contains those public keys with
-    `adcp_use: "request-signing"`.
-  test_kit: "test-kits/signed-requests-runner.yaml"
-
-phases:
-  - id: capability_discovery
-    title: "Capability discovery"
-    narrative: |
-      Confirm the agent advertises request-signing support before grading the verifier.
-
-    steps:
-      - id: get_capabilities
-        title: "Verify the agent declares request_signing.supported"
-        narrative: |
-          The runner calls `get_adcp_capabilities` and confirms that the agent declares
-          support for this specialism. Absence of `request_signing.supported: true` means
-          the agent has not opted into the claim; the runner SHOULD skip the remaining
-          phases.
-        task: get_adcp_capabilities
-        schema_ref: "protocol/get-adcp-capabilities-request.json"
-        response_schema_ref: "protocol/get-adcp-capabilities-response.json"
-        doc_ref: "/protocol/get_adcp_capabilities"
-        comply_scenario: capability_discovery
-        stateful: false
-        expected: |
-          Return capabilities declaring request_signing.supported: true. If false or absent,
-          the specialism does not apply and grading skips to a non-applicable outcome.
-        sample_request:
-          context:
-            correlation_id: "signed_requests--get_capabilities"
-        validations:
-          - check: field_present
-            path: "request_signing"
-            description: "Agent declares request_signing capability block"
-          - check: field_value
-            path: "request_signing.supported"
-            value: true
-            description: "Agent verifies request signatures"
-
-  - id: positive_vectors
-    title: "Positive conformance vectors"
-    narrative: |
-      The runner sends each positive vector as a signed HTTP request to the agent and
-      expects the agent to accept it. Vectors exercise the happy path plus every
-      canonicalization-edge rule in the profile:
-
-        001 basic Ed25519 POST
-        002 Ed25519 POST with content-digest covered
-        003 ES256 POST (edge-runtime profile)
-        004 multiple Signature-Input labels (verifier processes sig1 only)
-        005 default-port strip (URL has :443)
-        006 dot-segment path normalization
-        007 query-string byte preservation (no alphabetization)
-        008 percent-encoded path normalization (lowercase → uppercase hex)
-
-      Vectors and test keys live at
-      `/compliance/{version}/test-vectors/request-signing/positive/` and
-      `/compliance/{version}/test-vectors/request-signing/keys.json`.
-
-    $comment: |
-      Step-level YAML entries for each positive vector will be generated from the vector
-      fixtures at runtime by the compliance runner; we do not duplicate them in this file.
-      The runner loads the vector, constructs the HTTP request, sends it to the agent,
-      and validates the response against expected_outcome.success. Runner implementation
-      tracked at adcontextprotocol/adcp#2331.
-
-  - id: negative_vectors
-    title: "Negative conformance vectors"
-    narrative: |
-      The runner sends each negative vector and expects the agent to reject with the
-      stable error code in `expected_outcome.error_code`. Negative vectors cover every
-      failure mode in the verifier checklist (13 numbered steps plus sub-step 9a for
-      the per-keyid cap) plus the pre-check:
-
-        001 unsigned + required_for           → request_signature_required
-        002 wrong tag                         → request_signature_tag_invalid
-        003 expired signature                 → request_signature_window_invalid
-        004 window > 300s                     → request_signature_window_invalid
-        005 alg not allowed                   → request_signature_alg_not_allowed
-        006 missing covered component         → request_signature_components_incomplete
-        007 missing content-digest (required) → request_signature_components_incomplete
-        008 unknown keyid                     → request_signature_key_unknown
-        009 wrong adcp_use                    → request_signature_key_purpose_invalid
-        010 content-digest mismatch           → request_signature_digest_mismatch
-        011 malformed Signature-Input         → request_signature_header_malformed
-        012 missing expires param             → request_signature_params_incomplete
-        013 expires ≤ created                 → request_signature_window_invalid
-        014 missing nonce param               → request_signature_params_incomplete
-        015 signature cryptographically invalid → request_signature_invalid
-        016 replayed nonce                    → request_signature_replayed
-        017 key revoked                       → request_signature_key_revoked
-        018 content-digest when forbidden     → request_signature_components_unexpected
-        019 Signature without Signature-Input → request_signature_header_malformed
-        020 per-keyid replay cache cap        → request_signature_rate_abuse
-
-      Vectors live at `/compliance/{version}/test-vectors/request-signing/negative/`.
-      Grading requires byte-for-byte match on the error code; the failed_step value is
-      informational. The runner reads the error code from the agent's
-      `WWW-Authenticate: Signature error="<code>"` response header on 401.
-
-    $comment: |
-      As with positive_vectors, step-level entries are synthesized by the runner from
-      the vector fixtures. Runner implementation at adcontextprotocol/adcp#2331.
-
-grading:
-  pass_criteria: |
-    All vectors in positive/ produce 2xx, and all vectors in negative/ produce 401 with
-    the expected error code byte-for-byte. Any single vector's failure to produce its
-    expected outcome fails the specialism. Vectors that declare `requires_contract`
-    whose contract the runner cannot satisfy grade as FAIL, never as SKIP — the
-    signed-requests-runner contract is a prerequisite for the claim, not an optional
-    extension.
-  report_format: |
-    Pass/fail per vector, with the response's error code (if any) and a diff against
-    the vector's expected_outcome. Operators receive specific per-vector diagnostics
-    so they can debug without re-running the full suite.