Skip to content

docs(specs): observation allowance and Google signing-key lifecycle - #115

Merged
xgreenx merged 13 commits into
mainfrom
specs/observation-allowance-and-google-key-rotation
Nov 4, 2026
Merged

xgreenx merged 13 commits into
mainfrom
specs/observation-allowance-and-google-key-rotation

Conversation

@xgreenx

@xgreenx xgreenx commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

The specs lagged the deployed verifiers on evidence time and on how Google signing keys become trusted.

Changes

  • futureObservationAllowance: third per-profile parameter (google 7200, x/github 300) in libid.md, §2.2, REQ-PLAT-09A/22, TEST-PLAT-07.
  • Watermark: metadataObservedAt is evidence time minus the allowance, saturating at zero: a conservative watermark at or below Block Time, ordered within a profile. It is public alongside a binding's existence, platform and Transaction Author.
  • Ceiling: evidence more than the allowance ahead of Block Time is rejected, so Google needs exp <= Block Time + 7200.
  • REQ-PLAT-09: bounds only the token attestation's creation time.
  • REQ-PARAM-02: the saturating subtraction is the one exception to checked arithmetic.
  • §3.4 Signing-key lifecycle (specs/platform-ceremonies.md:767): permissionless notarized readings, their constants, two generations, trust for at most 30 days while either generation lists the key, upgrade carve-out (REQ-PLAT-24 rewritten, REQ-PLAT-70..73, TEST-PLAT-08/24/25).
  • Liveness: an unpayable Notary Fee, or 30 days without a reading, stops Google ceremonies. Availability assumes Google lists a key before signing with it.
  • ASM-NOTARY-01 names REQ-PLAT-09 and REQ-PLAT-71 as the enforced skew bounds.

Verified

  • Merged main 2e039e8. lint_spec.py specs/*.md: 108 errors on main and on this branch.
  • Every constant re-read in libid-contracts main 0a79aa7 (GoogleJwtRoots.sol:125-138, CeremonyProfile.sol:127).

Not verified / known issues

  • Common §12 fixes an unbounded fee by selecting another Notary Service. For Google, the Google Key List's notary must also be repointed.
  • REQ-PLAT-16A claims a stricter canonical encoding than _b64urlDecode checks.
  • TEST-PLAT-24 also appears in open feat(ceremony): telegram/1 ceremony #170; the later of the two to merge renumbers.

The deployed verifiers (libid-contracts 0.17.0) fix a third per-profile
parameter: Google 7200 s, X and GitHub 300 s. They return
metadataObservedAt as evidence time minus it, saturating at zero, and
refuse evidence further ahead of Block Time. The shared scale lets
profiles compare; the ceiling stops a long-lived token from locking a
name. REQ-PLAT-09 bounds only the token attestation, as the code does.

Assisted-by: Claude Opus 5.5
Signed-off-by: xgreenx <xgreenx9999@gmail.com>
Deployed Google moduli enter GoogleJwtRoots by permissionless,
notary-attested readings of www.googleapis.com/oauth2/v3/certs and lapse
30 days after the reading; governance adds none. The spec still had
governance adding each modulus. REQ-PLAT-24 and REQ-PLAT-70..73 now pin
the reading, the two generations, the lapse and the levers left. The
notary key is a Google trust root, and the reading fee makes Google
ceremonies depend on a paid reading every 30 days.

Assisted-by: Claude Opus 5.5
Signed-off-by: xgreenx <xgreenx9999@gmail.com>
With futureObservationAllowance in the table, "names neither" no longer
says which parameters Google leaves out; Google does name the allowance.

Assisted-by: Claude Opus 5.5
Signed-off-by: xgreenx <xgreenx9999@gmail.com>
GoogleJwtRoots and GooglePlatformVerifier are both owner-upgradable
through UUPS, and an upgrade can drop or add a single modulus. The spec
said governance could end trust in Google moduli only all at once, and
REQ-PLAT-73 forbade every non-reading operation without that carve-out.

Assisted-by: Claude Opus 5.5
Signed-off-by: xgreenx <xgreenx9999@gmail.com>
A bug in the Google Key List, or an upgrade of it, admits any modulus,
the same reach as a compromised Platform Verifier. The trust-root list,
the compromise sentence and the §2.2 Google note still pointed at an
active set inside the Platform Verifier.

Assisted-by: Claude Opus 5.5
Signed-off-by: xgreenx <xgreenx9999@gmail.com>
_readKeys checks that "keys" occurs once and what follows it, not the
bytes before it, so REQ-PLAT-70 now states that check. A refused
rotate() reverts and pays nothing, so only admitted readings pay the
fee. SP-CLIENT-01 is the browser Prover's client-identifier property and
does not fit a ledger key list; SP-BIND-01 remains.

Assisted-by: Claude Opus 5.5
Signed-off-by: xgreenx <xgreenx9999@gmail.com>
REQ-PARAM-02 requires checked arithmetic, while §2.2 subtracts the
allowance with saturation at zero, as _onSharedScale does. The Google
allowance rationale also drew a conclusion the contracts never derive;
it now states the hour lead and the two-hour allowance as two facts.

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-observation-allowance-and-google-key-rotation.previews.lib.id, https://specs-observation-allowance-and-google-key-rotation-libid.grounded-systems.workers.dev (commit e05795d)

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://5d781eae.previews.lib.id, https://5d781eae-libid.grounded-systems.workers.dev e05795d 2026-11-04T02:15:00.955Z Visit the dashboard ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://9ba41394.previews.lib.id, https://9ba41394-libid.grounded-systems.workers.dev 047acf4 2026-11-02T20:37:22.511Z Visit the dashboard ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://0ec4324d.previews.lib.id, https://0ec4324d-libid.grounded-systems.workers.dev bbd13ea 2026-10-19T15:52:25.075Z Visit the dashboard ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://0a65077c.previews.lib.id, https://0a65077c-libid.grounded-systems.workers.dev 9c19fd1 2026-10-05T13:42:33.112Z Visit the dashboard ↗

@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.

Directionally right. The timestamp arithmetic, parameter constants, and key-list transitions match the pinned contracts. Three documentation findings are inline: qualify the 30-day trust window, make the advance-publication assumption explicit, and avoid claiming the adjusted timestamps represent equivalent observation times.

Checks: Markdown/theme tests and git diff --check pass. Spec lint is unchanged from the base: 79 existing errors and 99 warnings. These findings call for documentation clarification, not changes to the deployed arithmetic or two-generation design.

Comment thread specs/platform-ceremonies.md Outdated
make the current generation the previous one, discard the generation that
was previous, and make the reading the current generation. The Google Key
List MUST trust a modulus until one generation lifetime after the creation
time of the latest generation that lists it. The Google Key List MUST NOT

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.

P2 — Qualify the 30-day window by retained-generation membership.

This promises trust until one generation lifetime after the reading, but the preceding rotation rule can discard that generation sooner. Two subsequent distinct key sets can evict a modulus while its 30-day window is still open. The contract explicitly acknowledges that overlapping rotation responses can temporarily evict a still-live key.

State that a modulus is trusted only while present in either retained generation and before that generation's expiry; 30 days is an upper bound, not guaranteed retention. Carry that qualification into the summary/test wording and document the existing availability tradeoff, rather than changing the two-generation implementation.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in aa550be. REQ-PLAT-72 (specs/platform-ceremonies.md:497) now trusts a modulus only while either generation lists it, for at most one generation lifetime, and its Necessity names the cost: the second set-changing reading after the latest one listing a key discards it, so valid proofs under it fail when Google's servers serve three sets at once. The constants table (:450), the §3.4 summary, TEST-PLAT-24 (:1578) and libid.md:246 give 30 days as an upper bound.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Still holds after merging main (c0dffee). REQ-PLAT-72 is now at specs/platform-ceremonies.md:836. 047acf4 also names REQ-PLAT-71's reading lead among the enforced skew bounds in ASM-NOTARY-01 (specs/ceremony-common.md:224).

Comment thread specs/platform-ceremonies.md Outdated
Rotation is permissionless, so Google ceremonies stay live while some party
pays the Notary Fee for a reading after each change to Google's published
set and at least once per generation lifetime. Google lists a key before it
signs with it, so a reading taken in that interval trusts the key in time.

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.

P2 — Make advance publication an explicit liveness assumption, not a guarantee.

This assumes Google publishes a new key sufficiently early for a notarized reading to land on chain before signing starts. That lead-time guarantee is not established here. OIDC §10.1.1 permits signing to begin at the signer's discretion and describes refreshing the JWKS when an unfamiliar kid arrives.

Qualify the advance-publication claim as an assumption or observed behavior, and acknowledge the possible interval in which otherwise valid Google proofs are rejected until a reading admitting the new modulus lands. Permissionless rotation permits recovery; it does not itself guarantee uninterrupted availability.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in 6f6b1a3. The paragraph at specs/platform-ceremonies.md:531 now states advance publication as an assumption, cites OIDC Core §10.1.1, and says valid Google proofs under a newly signing key are rejected until a reading listing it lands; a reading permits recovery, not uninterrupted availability. ceremony-common.md:1554 says Google ceremonies stop sooner once Google signs with a key the Google Key List does not trust.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Still holds after merging main (c0dffee). The assumption paragraph is now at specs/platform-ceremonies.md:870-881.

Comment thread specs/platform-ceremonies.md Outdated
hour ahead of the token's issue, while a notary stamps its own clock.
Subtracting each profile's `futureObservationAllowance` puts
`metadataObservedAt` on one scale every profile shares, so comparing two
profiles' values does not let one of them always win. The allowance is also a

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.

P3 — Describe conservative watermarks rather than equivalent observation times.

Subtracting the maximum allowances does not remove the cross-profile offset described here. For evidence produced at the same moment, a Google token expiring an hour later yields approximately now - 3600, while an X/GitHub attestation yields now - 300.

The useful invariant is that the evidence-time ceiling plus subtraction bounds the returned watermark by Block Time and preserves ordering within a profile. Describe that invariant without claiming the values are normalized to equivalent observation times or eliminate cross-profile ordering bias. The arithmetic can stay unchanged.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in bbd13ea. §2.2 (specs/platform-ceremonies.md:217) now states the invariant: the allowance caps how far evidence time leads Block Time, so metadataObservedAt stays at or below Block Time and keeps order within a profile; it calls the value a conservative watermark and gives the ~3600 s vs ~300 s offset. libid.md:201 and REQ-COMMON-05E (ceremony-common.md:585) drop the shared-scale and observation-time wording.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Still holds after merging main (c0dffee). §2.2's watermark paragraph is now at specs/platform-ceremonies.md:536-546. 047acf4 also calls the public field the metadataObservedAt watermark in specs/ceremony-common.md:1676.

xgreenx and others added 5 commits October 19, 2026 16:50
REQ-PLAT-72 trusts a modulus that either generation lists until one
generation lifetime after the later generation listing it. The second
set-changing reading after the latest one listing a modulus discards it
sooner, and the Necessity names that availability cost. The constants
table, the §3.4 summary, TEST-PLAT-24 and libid.md give 30 days as an
upper bound.

Assisted-by: Claude Opus 5.5
Signed-off-by: Green Baneling <XgreenX9999@gmail.com>
Google ceremonies stay available only if Google lists a key before
signing with it and a reading lands in between; OIDC Core §10.1.1 lets a
signer start a new key at its discretion. Until such a reading lands,
valid Google proofs under the new key are rejected. A permissionless
reading permits recovery, not uninterrupted availability.

Assisted-by: Claude Opus 5.5
Signed-off-by: Green Baneling <XgreenX9999@gmail.com>
The allowance caps how far evidence time may lead Block Time, so the
subtraction keeps metadataObservedAt at or below Block Time and never
reverses the order of two evidence times under one profile. For evidence
produced at one moment, a Google value falls about 3600 s before it and an
X or GitHub value about 300 s before it.

Assisted-by: Claude Opus 5.5
Signed-off-by: Green Baneling <XgreenX9999@gmail.com>
…owance-and-google-key-rotation

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

# Conflicts:
#	specs/ceremony-common.md
#	specs/libid.md
#	specs/platform-ceremonies.md
- The metadataObservedAt watermark is public with a binding's
  existence, platform and Transaction Author; id and handle values
  are not.
- ASM-NOTARY-01 names REQ-PLAT-09 and REQ-PLAT-71 as the enforced
  future-skew bounds.

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

Copy link
Copy Markdown

Merged main 2e039e8 (c0dffee) and rechecked every constant against libid-contracts main 0a79aa7; all hold. Your three threads are answered at the new lines. @Wondertan, please re-review.

Wondertan
Wondertan previously approved these changes Nov 2, 2026
…owance-and-google-key-rotation

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

# Conflicts:
#	specs/platform-ceremonies.md
@xgreenx
xgreenx merged commit 7bbf74a into main Nov 4, 2026
11 checks passed
@xgreenx
xgreenx deleted the specs/observation-allowance-and-google-key-rotation branch November 4, 2026 02:18
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