[Bug]: checkout.line_items treats no revealed acceptable_items as wildcard and permits underfilled requirements

[zesttec]

What happened?

TL;DR

A bug happened!

• Version: v0.2.0 / main (e1ea56d)
• Expected behavior:
  • Evaluation should fail when acceptable_items is empty or fully undisclosed.
  • A required quantity should be satisfied exactly (or at least to the required amount, depending on the intended doc semantics).
• Actual behavior:
  - An empty acceptable_items list is treated as a wildcard, and quantity is interpreted only as a capacity limit instead of a required quantity.

Problem

Hi maintainers!

The current Python SDK and the v0.2 documentation appear to be inconsistent in two checkout.line_items cases(the following case 1 & case 2), while the identifier mapping remains underspecified(case 3).

1. Empty or fully undisclosed acceptable_items

The documentation says an item matches a requirement when its ID is present in the revealed acceptable_items; it does not define an empty list as a wildcard. ([documentation])

The schema makes acceptable_items selectively disclosable but does not require at least one element. )

The Python evaluator interprets an empty list as a wildcard, and an existing test explicitly accepts an arbitrary SKU. ([implementation], [test])

This is reachable through selective disclosure: the SDK documents that claims_to_disclose={} reveals nothing. In a local reproduction, withholding the only acceptable SKU produced:

verified acceptable_items: []
violations for a non-disclosed SKU: []

([presentation API], [disclosure filtering])

2. Required quantity versus capacity

The documentation says the maximum flow must equal both the total constraint quantity and the total Checkout quantity. The schema also describes quantity as the “Required quantity of matching items.” ([documentation], [schema])

The SDK only checks whether all Checkout units fit within the requirement capacities; it does not reject unused requirement capacity. Existing tests therefore accept quantity two against a requirement for three, and explicitly state that a cart smaller than the total capacity is valid. ([implementation], [tests])

3. Item identifier mapping

The documentation refers only to an “item ID.” The UCP model contains both a line-instance ID and a nested product ID, while the Python evaluator specifically compares checkout.line_items[].item.id. ([UCP LineItem schema], [evaluator])

For other Checkout profiles, AP2 does not state how their product identifier maps to the constraint ID. The acceptable ID is also described only as “often the SKU,” without stating whether it is globally unique or scoped to a Merchant or catalog. ([Checkout profile extension], [constraint item schema])

Suggested clarification

It would be good to clarify and align the documentation, schema, SDK and tests so that:

• a requirement with no revealed acceptable_items fails closed, unless wildcard authorization is represented explicitly;
• quantity is defined consistently as exact, minimum or maximum;
• the UCP comparison path is explicitly checkout.line_items[].item.id;
• other Checkout profiles define an equivalent product-ID mapping;
• item IDs have a defined Merchant/catalog scope, or use a qualified identifier.

Relevant log output

Code of Conduct

• I agree to follow this project's Code of Conduct

[chopmob-cloud]

Reproduced your three cases against the SDK at e1ea56d, and case 1 is the one I would separate out and treat as security rather than a doc gap, because it fails open along an attacker-influenced path.

The wildcard-from-empty is unconditional in max_flow_helper.py:

req_is_wildcard: list[bool] = [
    not req.acceptable_items for req in requirements
]
has_wildcard = any(req_is_wildcard)
# ...
if not has_wildcard and sku not in all_acceptable:
    violations.append(...)

When any requirement is a wildcard the membership check is skipped entirely, and in the assignment loop if req_is_wildcard[j] or sku in req_acceptable[j] matches any SKU. There is no mode that gates this; mode only selects the max-flow algorithm. test_line_items_wildcard_requirement locks the behavior in, its own docstring calling an empty list "wildcard (any SKU accepted)."

The reason this is more than a default-choice question is the one you already point at: emptiness is reachable by withholding, not only by authoring. An issuer signs acceptable_items=[SKU_A]; a holder presents with claims_to_disclose={}; the disclosure filter in mandate.py drops the undisclosed selective-disclosure claims, so the verifier reconstructs acceptable_items: []; case 1 then reads that as "any SKU." So a holder can strip the item constraint off a signed mandate and have an arbitrary SKU clear. That is a privilege escalation on the mandate, and the dangerous direction: absence of the constraint widens authority instead of removing it.

One thing you might want to consider is that intent and absence are different facts here: "the issuer authorized any item" and "the constraint was not disclosed" currently collapse to the same empty list. If it were useful to separate them, failing closed on empty would cover the security case, with a genuine any-item authorization represented explicitly, for example an any: true flag or a sentinel the issuer signs, rather than a state a holder can manufacture by omission. You might also want to check whether SD-JWT here can distinguish "field absent because not disclosed" from "field present and empty," since if the verifier cannot tell those apart, inferring wildcard from either is the part that looks unsafe.

Cases 2 and 3 read as specification-consistency items rather than security. On case 2 the SDK does treat quantity as a capacity ceiling: test_line_items_single_sku_valid accepts cart quantity 2 against a requirement of 3, so the feasibility check only asks whether cart units fit within requirement capacities and never rejects unused capacity. Whether that is a bug turns entirely on whether the schema's "Required quantity" means exact, minimum, or maximum, which is the clarification you are asking for. Case 3 is a real underspecification: the evaluator compares checkout.line_items[].item.id, and nothing states how other Checkout profiles map their product identifier onto the constraint ID, nor the catalog scope of that ID.

One thing you might want to consider for triage is that case 1 is separable from the other two: it is reachable today through normal selective disclosure, whereas cases 2 and 3 wait on a spec decision, so it could be looked at on its own without the others being resolved first.

[chopmob-cloud]

I reproduced both behaviors against current main (e1ea56d) with the SDK evaluator directly, and case 1 is worth treating as a fail-open authorization issue rather than only a documentation gap.

Case 1: empty acceptable_items reads as a wildcard. evaluate_line_items_max_flow derives req_is_wildcard = not req.acceptable_items (max_flow_helper.py:42-44); when has_wildcard is true (line 48) the "not in acceptable items" guard at line 57 is bypassed for every SKU. The part that makes this a security concern is that an empty list is reachable by omission, not only by construction: check_checkout_constraints runs over whatever survived selective disclosure, and the disclosure filter admits a claim only when its key is in claims_to_disclose (mandate.py). A holder can therefore withhold the acceptable_items disclosure and the verifier sees an empty list.

Same requirement and cart, only the disclosure differs:

disclosed  acceptable=['SKU_A'], cart=ATTACKER x1  ->  ["Item ATTACKER not in any requirement's acceptable items"]
withheld   acceptable=[]        , cart=ATTACKER x1  ->  []      # authorized

Withholding the constraint flips the decision from reject to authorize-anything. The verifier cannot distinguish "issuer intended a wildcard" from "holder hid the allow list," and currently resolves that ambiguity as authorize-all. The safer default is to fail closed when acceptable_items is absent or empty after disclosure, and to represent a real wildcard explicitly (a dedicated flag or sentinel) so it exists only when the issuer set it, never as a side effect of omission. Absence of a constraint should not be read as absence of enforcement.

Case 2: quantity behaves as capacity, not a required minimum. Confirmed: req_remaining_capacity = [req.quantity ...] and assigned = min(qty, capacity) (lines 65, 85) only verify that cart items fit within capacities; unused capacity never raises a violation, so a required quantity of 3 satisfied by 1 passes. Whether quantity is exact, minimum, or maximum is a semantics call, but the current behavior is maximum-capacity while the schema describes it as "Required quantity of matching items." Those two are worth reconciling.

Case 3 reads as a spec-clarity item; agreed the UCP item.id and the acceptable-id scope should be pinned.

Of the three, the empty-equals-wildcard default is the one I would prioritize, since a holder can reach it without touching the issuer's signature.