Skip to content

docs(specs): define the attested-data format X and GitHub pin - #112

Merged
xgreenx merged 5 commits into
mainfrom
specs/attested-data-format
Nov 4, 2026
Merged

xgreenx merged 5 commits into
mainfrom
specs/attested-data-format

Conversation

@xgreenx

@xgreenx xgreenx commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

REQ-COMMON-18 requires a profile with attestations to fix its attestation format. The X and GitHub profiles only named "the pinned attestation format".

Changes

  • §4.1 Attested data (specs/platform-ceremonies.md:797): the 48-byte header, the direction-block encoding, the SHA-256(plaintext || 16-byte blinder) commitment and the EIP-191 secp256k1 signature. The X and GitHub circuits open four commitments: both bearers, and the id and handle (REQ-PLAT-32D, REQ-PLAT-52C).
  • REQ-PLAT-64..69 (:877-930): encoding, field values, commitment construction, signing, recovery, and shape rejection.
  • TEST-PLAT-23 (:2007): a 246-byte conformance vector with its digest, plus negative cases.
  • Profile mentions: the "pinned attestation format" mentions in §5/§6 link to §4.1.

Verified

  • Merged main 2e039e8. lint_spec.py specs/*.md: 108 errors on main and on this branch.
  • Layout, widths, ordering and rejections match CeremonyAttestation.sol, NotaryService.sol:119-128, libid-rs attestation.rs and TS decode.ts.
  • The vector is byte-identical to the Rust, Solidity and TS fixtures; cast keccak reproduces the digest 0x48162f05…95936.
  • The circuit's commitment preimage matches tlsn's (lib.nr:39-56, 16-byte blinder).

Not verified / known issues

  • The docs site build was not run locally.
  • Code comments in libid-rs attestation.rs:169 and libid-contracts CeremonyAttestation.t.sol:15 still call the vector X identity-shaped.
  • REQ-PLAT-64..69 and TEST-PLAT-23 also appear in open feat(ceremony): telegram/1 ceremony #170; the later of the two to merge renumbers.

REQ-COMMON-18 has a profile with attestations fix their format, but the X
and GitHub profiles only named "the pinned attestation format". The bytes
lived in four implementations that agree by fixture alone. Section 4.1 now
fixes the 48-byte header, the direction blocks, the SHA-256 range
commitment and the EIP-191 notary signature, as the contracts verify them.

Assisted-by: Claude Opus 5.5
Signed-off-by: xgreenx <xgreenx9999@gmail.com>
The X token-session text called every unrevealed byte charset-constrained.
The circuit opens and constrains only the bearer range (REQ-PLAT-30); the
status line, headers, scope and token_type stay behind commitments that
nothing opens.

Assisted-by: Claude Opus 5.5
Signed-off-by: xgreenx <xgreenx9999@gmail.com>
The direction-block table listed fields once, so an encoder could read it
as one array per field. State that each range and each commitment is
written whole, count times. Split REQ-PLAT-65's last sentence into one
requirement each, and drop a sentence that restated "opens only the
bearer range".

Assisted-by: Claude Opus 5.5
Signed-off-by: xgreenx <xgreenx9999@gmail.com>
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Oct 5, 2026 •

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://specs-attested-data-format.previews.lib.id, https://specs-attested-data-format-libid.grounded-systems.workers.dev (commit eca3a55)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://669b379c.previews.lib.id, https://669b379c-libid.grounded-systems.workers.dev eca3a55 2026-11-02T20:37:01.408Z Visit the dashboard ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://80ba0682.previews.lib.id, https://80ba0682-libid.grounded-systems.workers.dev 809c042 2026-10-05T13:37:44.592Z Visit the dashboard ↗

Wondertan
Wondertan previously approved these changes Oct 12, 2026

@Wondertan Wondertan left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed at 809c042. No blocking findings.

The byte layout matches the Rust encoder, browser decoder, and Solidity verifier. The 246-byte conformance vector matches the existing cross-language fixture, including its authority hash and digest. The signing construction agrees with EIP-191.

Two non-blocking follow-ups:

  • Fix trailing-dot normalization in libid-rs AttestedData::authority_id_of. It currently lowercases but preserves a trailing dot, so api.x.com. produces an authority ID the verifier rejects. Keep the specification's canonicalization rule.
  • Consider adding a complete signature vector: the EIP-191 signed hash, signature, and expected signer. That would extend the existing encoding vector to cover cross-language signing and recovery.

The Notary Service's structural checks are compatible with its profile-agnostic role: decoding the attestation format is distinct from interpreting platform-specific evidence.

Checks: Markdown/theme tests and git diff --check pass. Spec lint is unchanged from the base: 79 existing errors and 99 warnings.

…ormat

Signed-off-by: xgreenx <xgreenx9999@gmail.com>

# Conflicts:
#	specs/platform-ceremonies.md
Since hidden identities the X and GitHub circuits open the id and handle
commitments as well as both bearers (REQ-PLAT-32D, REQ-PLAT-52C). The
conformance vector's sent direction keeps the identity-request layout;
its received direction no longer matches an identity response.

Signed-off-by: xgreenx <xgreenx9999@gmail.com>
@green-s-ai-agent

Copy link
Copy Markdown

Merged main 2e039e8 (0eb9086). Since hidden identities, the circuit opens the id and handle commitments too, so eca3a55 updates §4.1 (specs/platform-ceremonies.md:851-854) to name all four, and the conformance vector (:934-936) calls only its sent direction identity-request-shaped. The push dismissed your approval. @Wondertan, please re-approve.

@xgreenx
xgreenx merged commit 7168350 into main Nov 4, 2026
12 checks passed
@xgreenx
xgreenx deleted the specs/attested-data-format branch November 4, 2026 02:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants