Skip to content

docs(lodging): make the booking signed examples conformant - #934

Open
vishkaty wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/lodging-booking-signed-examples
Open

vishkaty wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/lodging-booking-signed-examples

Conversation

@vishkaty

@vishkaty vishkaty commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

docs(lodging): make the booking signed examples conformant

signatures.md, Signature Encoding (L494 to L499 on main at ad9950b),
requires ECDSA signatures to use fixed-width raw r||s encoding and says
explicitly not ASN.1/DER, with 64 bytes for P-256 and 96 for P-384. Four
example values in the lodging booking pages are DER: their base64 decodes
to an ASN.1 SEQUENCE of INTEGERs.

lodging/booking/mcp.md:1072 30 45 02 21
lodging/booking/mcp.md:1100 30 54 02 20
lodging/booking/rest.md:1590 30 45 02 21
lodging/booking/rest.md:1615 30 54 02 20

The two beginning 30 54 announce an 86 byte SEQUENCE, which matches
neither P-256 DER (70 to 72 bytes) nor P-384 (102 to 104), so those two
were never a signature of any curve the specification supports.

All four now carry the truncated raw-shaped placeholder #590 used,
6G4i8TS6oUkGrx8KnCFUpsSPwd74..., which is the canonical one at
signatures.md L516, L534, L564, L823 and L904, so no value here is a
fabricated complete signature.

On how they got here: #590 did not overlook these. The lodging booking
capability arrived with #780 on 2026-09-24, two months after #590 merged,
and brought with it the DER strings that #590 had already replaced in the
shopping pages. No file under lodging/booking existed in the tree at the
merge commit of #590.

Correcting my own note on #659: I reported there that the DER values
remaining were rest.md:1590 and mcp.md:1072, the only two left in the
tree. That count was wrong. It came from grepping MEUCI, which finds
the two request-signing values and not the two response-signing values
whose base64 begins MFQCI. Four is the count in these two files.

One more DER value exists on main, shopping/order/index.md:752, the order
event webhook example. It is already replaced, with its Signature-Input
line, by #659, so it is left to that PR rather than duplicated here. A
trial merge of this branch with #659 is clean and the merged tree holds no
DER value. #782 also edits lodging/booking/mcp.md and merges clean with
this branch in both orders.

The same block carries a second defect of a different class, fixed here
because splitting them would make two PRs collide on adjacent lines. The
Signature-Input at rest.md:1589 omitted ucp-agent although the request
carries a UCP-Agent header, which signatures.md L434 and L442 make a
required covered component, so the verifier pseudocode at L715 to L721
reaches coverage_insufficient and skips the example. Swept that class too:
of the 9 signed blocks in docs/specification carrying a UCP-Agent header,
3 omitted the component on main. This closes the lodging one; #795 closes
the checkout one and #659 the order one, so the class reaches zero when
all three land.

One thing seen and deliberately not changed: keyid="platform-2025" sits
on that same line, against the 2026 convention elsewhere. #590 set the
precedent of leaving it, so it stays for a separate decision.

Found by base64 decoding the leading bytes of every Signature: byte
sequence in docs/specification, at any indentation and in every file type,
rather than grepping one prefix, which is what finds both shapes. Sixteen
such occurrences exist; the one at signatures.md:271 is the symbolic
base64_ed25519_signature_value and is not base64, leaving 15 decodable
values, 5 DER on main and 1 on this branch. Kill tested by restoring one
value, which the decoder catches again.

Worth flagging separately: nothing in CI inspects a signature value.
scripts/validate_examples.py unwrap_http_envelope splits on the first
blank line and discards every header, and these blocks are unannotated
fences the validator never opens, which is how the class regenerated from
a stale copy. The published v2026-08-25 tag also still carries the DER
value at shopping/order/index.md:752, and that branch takes backports in
the form used by #838, #878 and #886. Happy to open either as its own
change.

Gates on this branch: validate_examples 398 passed, 0 failed, 0 errors,
53 skipped, unchanged from the control on main; ucp-schema lint source/
145 files all passed; pre-commit on the changed files all Passed;
markdownlint-cli 0.47.0, the pre-commit pin, and 0.49.0, the version
super-linter pins, both exit 0 on the changed files and on main as the
control. DOCS_MODE=spec mkdocs build --strict exits 0 with 0 warnings
here, on a machine with ucp-schema on PATH and DYLD_FALLBACK_LIBRARY_PATH
set so cairosvg can load libcairo; the rendered lodging pages carry the
raw placeholder twice each and no DER value.

signatures.md, Signature Encoding (L494 to L499 on main at ad9950b),
requires ECDSA signatures to use fixed-width raw `r||s` encoding and says
explicitly not ASN.1/DER, with 64 bytes for P-256 and 96 for P-384. Four
example values in the lodging booking pages are DER: their base64 decodes
to an ASN.1 SEQUENCE of INTEGERs.

  lodging/booking/mcp.md:1072    30 45 02 21
  lodging/booking/mcp.md:1100    30 54 02 20
  lodging/booking/rest.md:1590   30 45 02 21
  lodging/booking/rest.md:1615   30 54 02 20

The two beginning `30 54` announce an 86 byte SEQUENCE, which matches
neither P-256 DER (70 to 72 bytes) nor P-384 (102 to 104), so those two
were never a signature of any curve the specification supports.

All four now carry the truncated raw-shaped placeholder Universal-Commerce-Protocol#590 used,
`6G4i8TS6oUkGrx8KnCFUpsSPwd74...`, which is the canonical one at
signatures.md L516, L534, L564, L823 and L904, so no value here is a
fabricated complete signature.

On how they got here: Universal-Commerce-Protocol#590 did not overlook these. The lodging booking
capability arrived with Universal-Commerce-Protocol#780 on 2026-09-24, two months after Universal-Commerce-Protocol#590 merged,
and brought with it the DER strings that Universal-Commerce-Protocol#590 had already replaced in the
shopping pages. No file under lodging/booking existed in the tree at the
merge commit of Universal-Commerce-Protocol#590.

Correcting my own note on Universal-Commerce-Protocol#659: I reported there that the DER values
remaining were rest.md:1590 and mcp.md:1072, the only two left in the
tree. That count was wrong. It came from grepping `MEUCI`, which finds
the two request-signing values and not the two response-signing values
whose base64 begins `MFQCI`. Four is the count in these two files.

One more DER value exists on main, shopping/order/index.md:752, the order
event webhook example. It is already replaced, with its Signature-Input
line, by Universal-Commerce-Protocol#659, so it is left to that PR rather than duplicated here. A
trial merge of this branch with Universal-Commerce-Protocol#659 is clean and the merged tree holds no
DER value. Universal-Commerce-Protocol#782 also edits lodging/booking/mcp.md and merges clean with
this branch in both orders.

The same block carries a second defect of a different class, fixed here
because splitting them would make two PRs collide on adjacent lines. The
`Signature-Input` at rest.md:1589 omitted `ucp-agent` although the request
carries a `UCP-Agent` header, which signatures.md L434 and L442 make a
required covered component, so the verifier pseudocode at L715 to L721
reaches coverage_insufficient and skips the example. Swept that class too:
of the 9 signed blocks in docs/specification carrying a `UCP-Agent` header,
3 omitted the component on main. This closes the lodging one; Universal-Commerce-Protocol#795 closes
the checkout one and Universal-Commerce-Protocol#659 the order one, so the class reaches zero when
all three land.

One thing seen and deliberately not changed: `keyid="platform-2025"` sits
on that same line, against the 2026 convention elsewhere. Universal-Commerce-Protocol#590 set the
precedent of leaving it, so it stays for a separate decision.

Found by base64 decoding the leading bytes of every `Signature:` byte
sequence in docs/specification, at any indentation and in every file type,
rather than grepping one prefix, which is what finds both shapes. Sixteen
such occurrences exist; the one at signatures.md:271 is the symbolic
`base64_ed25519_signature_value` and is not base64, leaving 15 decodable
values, 5 DER on main and 1 on this branch. Kill tested by restoring one
value, which the decoder catches again.

Worth flagging separately: nothing in CI inspects a signature value.
scripts/validate_examples.py unwrap_http_envelope splits on the first
blank line and discards every header, and these blocks are unannotated
fences the validator never opens, which is how the class regenerated from
a stale copy. The published v2026-08-25 tag also still carries the DER
value at shopping/order/index.md:752, and that branch takes backports in
the form used by Universal-Commerce-Protocol#838, Universal-Commerce-Protocol#878 and Universal-Commerce-Protocol#886. Happy to open either as its own
change.

Gates on this branch: validate_examples 398 passed, 0 failed, 0 errors,
53 skipped, unchanged from the control on main; `ucp-schema lint source/`
145 files all passed; pre-commit on the changed files all Passed;
markdownlint-cli 0.47.0, the pre-commit pin, and 0.49.0, the version
super-linter pins, both exit 0 on the changed files and on main as the
control. DOCS_MODE=spec mkdocs build --strict exits 0 with 0 warnings and
2 social cards here, on a machine with ucp-schema on PATH and
DYLD_FALLBACK_LIBRARY_PATH set so cairosvg can load libcairo; the rendered
lodging pages carry the raw placeholder twice each and no DER value.
@damaz91 damaz91 added status:needs-triage Signal that the PR is ready for human triage area:lodging Issues and pull requests related to the Lodging vertical labels Oct 12, 2026
@dandemel dandemel removed the status:needs-triage Signal that the PR is ready for human triage label Oct 19, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:lodging Issues and pull requests related to the Lodging vertical

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants