Skip to content

docs(permalink): require explicit buyer action before cart merge - #789

Open
vishkaty wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/permalink-explicit-action
Open

docs(permalink): require explicit buyer action before cart merge#789
vishkaty wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/permalink-explicit-action

Conversation

@vishkaty

Copy link
Copy Markdown
Contributor

Description

Adds a normative rule to the permalink specification that closes the CSRF-class
gap raised in #666. A permalink is an unauthenticated browser GET, and the spec
already notes that browsers, prefetchers, link-preview bots, and security
scanners load permalink URLs without buyer intent. When a Business merges
permalink-initiated state into the existing cart of an authenticated buyer
automatically, on page load, on redirect, or through a pre-filled submission,
that merge carries no evidence the buyer ever saw or intended it. A hostile
link can then mutate the cart of a signed-in buyer with no attacker
interaction beyond getting the link loaded.

The added rule requires a Business to obtain an explicit buyer action on the
rendered permalink state before performing that merge. This is scoped
narrowly: it leaves the existing irreversible-action rule untouched (a
Business MUST NOT treat loading a permalink as authorization to place an
order, charge payment, or complete checkout), and it adds no friction to the
legitimate flow, since a buyer confirming what they can already see is a
normal step, not an extra one.

As discussed in #666, this is the tightened form of the rule agreed in that
thread: an automatic merge on load, on redirect, or through a pre-filled
submit does not satisfy the requirement. Only an action the buyer takes on
state they can see does.

Verification & Testing

  • Linted the changed file with markdownlint using the repo config
    (.github/linters/.markdownlint.json): 0 issues.
  • Spell-checked with cspell using the repo config (.cspell.json): 0 issues.
  • Ran uv run python scripts/validate_examples.py --schema-base source/schemas/:
    343 passed, 0 failed (unchanged from before this diff).
  • Ran uv run python scripts/test_validate_examples.py: 52 passed.
  • Ran uv run yamllint -c .github/linters/.yamllint.yml .: clean (pre-existing
    warnings only, unrelated to this file).
  • Ran DOCS_MODE=spec uv run mkdocs build --strict: aborts locally only on
    cairosvg social-card generation, which requires a system libcairo not
    present on this machine; confirmed identical on unmodified upstream/main
    before this diff, so this is an environment gap, not a regression.
  • Grepped docs/specification/ for other merge or authenticated-cart language
    that could contradict or duplicate this rule: none found. The only other
    permalink construct that constructs shopping state is the
    checkout/index.md Checkout Permalink, a separate, stateless, REST-specific
    reconstruction mechanism with no merge-into-cart semantics of its own; it is
    unaffected by this change.

Category (Required)

  • Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
  • Governance/Contributing: Updates to GOVERNANCE.md, CONTRIBUTING.md, or CODEOWNERS. (Requires Governance Council approval)
  • Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
  • Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
  • Infrastructure: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
  • Maintenance: Version bumps, lockfile updates, or minor bug fixes. (Requires DevOps Maintainer approval)
  • SDK: Language-specific SDK updates and releases. (Requires DevOps Maintainer approval)
  • Samples / Conformance: Maintaining samples and the conformance suite. (Requires Maintainer approval)
  • UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)
  • Community Health (.github): Updates to templates, workflows, or org-level configs. (Requires DevOps Maintainer approval)

Related Issues

Fixes #666

Checklist

  • I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
  • I have updated the documentation (if applicable).
  • My changes pass all local linting and formatting checks.
  • I have added tests that prove my fix is effective or that my feature works.
  • New and existing unit tests pass locally with my changes.
  • (For Core/Capability) I have included/updated the relevant JSON schemas.
  • I have regenerated Python Pydantic models by running generate_models.sh under python_sdk.

Screenshots / Logs (if applicable)

None. This is a text-only specification change.

Closes the CSRF-class gap identified in ucp#666: merging rendered
permalink state into the existing cart of an authenticated buyer must
now follow an explicit buyer action on that rendered state. Automatic
merges on load, on redirect, or through a pre-filled submission do not
satisfy this requirement.

Rule proposed in the issue thread and tightened with westonale-facet
on 2026-08-14.

Fixes Universal-Commerce-Protocol#666
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Permalink can attach state changes to an authenticated buyer session on an unauthenticated GET: what protects against CSRF?

4 participants