The site-embed — a webGCP extension for participant websites¶

Extension identifier: org.webgcp/site-embed · Version: 0.1 (draft) Anchors — three, all published elsewhere:

⚠ WebMCP is cited accurately on purpose. It is an actively incubating community-group draft with a real implementation — a strong position, but not a ratified standard, and this document does not describe it as one. Its surface has already moved once (the API migrated from navigator to document, and most secondary documentation has not caught up), so implementers should feature-detect and re-verify rather than trust any explainer, including this one, on a fixed date.

This extension invents no identity scheme, no payment scheme, and no tool-registration API. It composes three published surfaces and adds only the participant shape that none of them defines.

WebMCP declares what a site can do. webGCP declares what a network knows. This extension is the packaged thing a webmaster installs to join the second without giving up the first: a descriptor entry that says the site participates, a domain-bound identity it can be held to, and a client split so that no credential capable of spending money ever reaches a browser.

Nothing here is new machinery. Every part rides a v0.1 surface that already exists.

1. The anchor, as published¶

Framing note — what this extension does to role. v0.1 names exactly one role value, in one place: the spec host carries role: "specification_authority" instead of a conformance_level. There is no role enumeration in v0.1, and knowledge servers are discriminated by conformance_level, not by a role value. So this extension does something slightly larger than add a second value — it generalizes role into a document-class discriminator for hosts that are neither the specification authority nor a conforming knowledge server, with participant meaning consumer. That is an extension and not a spec change (there is no enum to violate), but implementers should understand it as a generalization rather than assume v0.1 already shipped a role vocabulary.

What the anchor deliberately does not cover¶

The anchor holds on extension point plus governance, not coverage — which is what an extension wants.

2. The delta¶

Four properties:

1. The participant descriptor — a site declares participation in the document it already knows how to serve. (SE-1)
2. Domain-bound identity — did:web:<domain>, proven by control of the well-known path. The site is an agent; receipts carry it; credibility accrues to the domain. (SE-2)
3. Two halves, one rule — a public browser half confined to the free lane, a credentialed server half for metered lanes, and no metered credential in the page, ever. (SE-3, SE-4)
4. Materialization, not replacement — matched network skills may surface in the site's own WebMCP card, each labeled with its provenance so a visiting agent can always tell a local tool from a network skill. (SE-5)

3. Normative requirements¶

Key words MUST / MUST NOT / SHOULD / MAY per BCP 14.

SE-1 — The participant descriptor¶

• A participant MUST publish /.well-known/webgcp per §5.1 (HTTPS, application/json, cacheable 1–24 h) carrying role: "participant".
• It MUST carry consumes: a non-empty array of absolute HTTPS origins of the network host(s) it consumes.
• It MUST NOT carry conformance_level. A participant serves no knowledge surface and has no level to claim; it follows the spec-host precedent of carrying role in that field's place.
• It MUST NOT advertise endpoints it does not serve.
• The roles are not exclusive, but the claims are separate. A host that is also a knowledge server publishes a server descriptor and is bound by §5.1 and §5.1.1 as a server, unchanged by this extension. Participation never softens a server obligation.

{
  "role": "participant",
  "spec_version": "0.1",
  "extensions": ["org.webgcp/site-embed@0.1"],
  "identity": "did:web:example.com",
  "consumes": ["https://catalog.example-network.org"],
  "svcb_status": "live 2026-08-23"
}

SE-2 — Domain-bound identity¶

• The participant's identity MUST be did:web:<domain>, where <domain> is the host serving the descriptor, per the W3C did:web method.
• Proof of identity is control of the well-known path under that domain — the trust primitive the protocol already rests on. No issued token, no registration authority, no allocation step.
• A participant MUST NOT mint an alternate identifier scheme for the same purpose. Where an identifier is needed for a domain-bound party, did:web is it.
• Network hosts MUST treat the identity as a claim about a domain, verified by fetching the descriptor at that domain — never as an assertion carried in a request header alone.
• Credibility accrues to the identity over time. A fresh domain starts cold; see Known Limitations.

SE-3 — The two halves, and the credential rule¶

• The client ships in two halves. The browser half is public and confined to the free discovery lane (SE-4). The server half holds the participant's credential and originates every metered call.
• A metered-lane credential MUST NOT be shipped to, stored in, or transited through the browser half. This includes bearer tokens, service-account keys, and signed URLs that grant metered access. A deployment that does so is non-conformant regardless of obfuscation, minification, short expiry, or referrer restriction.
• What this rule does not forbid. A public identifier that authorizes nothing on its own — a project id, a public origin, a site's own did:web — is not a credential and MAY ship in the page. The test is capability, not secrecy: if presenting this value alone can cause a metered call to succeed, it is a credential.
• Rationale: an authorization gate decides who finds a resource, not who can read one that has already been served to a browser. Anything in the bundle is public the moment it is served.

SE-4 — Lanes, and the payment anchor¶

• The default lane is free discovery. Installing the embed MUST cost nothing and MUST charge nothing.
• Metered lanes MUST be an explicit server-side opt-in. A participant MUST NOT be able to incur a charge as a side effect of installing, of a page view, or of any browser-half call.
• Where fees apply, a network host takes them only on rails it operates; quoted prices are advisory until the operator's estimator is calibrated against settled cost; and every paid event MUST be receipted to the participant's identity.

The payment mechanism is x402 — not a webGCP invention. Internet-native machine payments already have an open, neutral standard built on HTTP's own 402 Payment Required, and this extension anchors on it rather than defining a parallel scheme. The same reasoning that made site identity did:web instead of a bespoke URN applies here with more force: payments are precisely where a private scheme costs an ecosystem the most.

• A metered lane that requires payment MUST respond 402 Payment Required with the payment requirements, and MUST accept the client's payment payload in the X-PAYMENT request header on retry.
• 402, never 429. A rate limit and a price are different refusals; conflating them makes a free-lane throttle indistinguishable from a charge, and an agent cannot choose correctly between waiting and paying.
• Settled-only semantics. Verification without settlement MAY unlock a call; it MUST NOT mint spendable balance. An unsettled verification is permission to proceed, never money.
• Nanopayment granularity is expected, not exceptional. Per-invocation prices below one cent are the normal case for discovery-adjacent work, so amounts MUST be carried at nano precision on the wire and MUST NOT be rounded to a currency's minor unit for transport.

The lane cascade. A participant's server half SHOULD resolve payment in fixed priority — free → session budget → x402 → 402 — falling through to a 402 refusal rather than failing open. The free lane sits first by construction: the common case costs nothing and never reaches a payment rail at all.

⚠ What this extension does NOT do: take a percentage of every transaction. Fees attach to operated rails by scope, not as a tax on each call. A participant that installs the embed and stays on the free lane pays nothing, forever, and that is the intended common case — the metered lanes price work performed, not access granted.

SE-5 — WebMCP composition is materialization¶

• A participant MAY surface matched network skills into its own WebMCP card.
• Every materialized entry MUST carry authority: "derived" and a source naming the network skill it materializes.
• Every materialized entry MUST additionally set WebMCP's own untrustedContentHint annotation. The two labels answer different questions and an agent needs both: untrustedContentHint warns about a tool's output, our authority/source pair states a tool's origin. Where the platform ships an annotation for the concern, use it rather than relying only on vocabulary this extension minted.
• A materialized entry that reaches only the free discovery lane SHOULD set readOnlyHint, giving an agent a native signal that the call neither costs nor changes anything.
• Tool registration is via document.modelContext — note the spelling. The API lives on the document, not on navigator; most secondary documentation still carries the older form, and code written from it does not run.
• A materialized entry MUST NOT be presented as a tool the site itself implements.
• Complement, never replace: removing the embed MUST leave the site's own WebMCP card intact and valid. A card MUST remain valid WebMCP with the materialized entries stripped — the composition is additive.

Why this is composition and not the disintermediation WebMCP guards against. The WebMCP proposal names an explicit aim of preventing disintermediation of web apps by backend integrations, and surfacing another party's tools into a site's card superficially resembles exactly that. It is worth answering directly rather than leaving the reader to wonder. Four properties, each required above, distinguish the two:

1. The site opts in. Nothing materializes without the operator installing the embed; the network never reaches into a card it was not invited into.
2. Entries are provenance-labeled. A visiting agent can always tell a local tool from a network skill — the opposite of disintermediation, which works by being invisible.
3. Removal is clean. Uninstalling leaves the site's own card intact and valid; the site's surface is extended, never replaced.
4. The site keeps its role in the transaction. Calls carry the site's identity and receipts accrue to its domain. The site is a party to the exchange, not an intermediary routed around.

Note also that WebMCP is "primarily designed for local browser workflows with a human in the loop", and names fully autonomous workflows an explicit non-goal. The browser half of SE-3 sits inside that model deliberately; nothing in this extension asks WebMCP to carry unattended execution.

SE-6 — Receipts and attribution¶

• A network host serving a participant MUST record the participant identity on the served event.
• A metered event MUST produce a receipt naming the identity, the lane, and the amount.
• Free-lane calls are rate-limited, not receipted (see Known Limitations for where that limit currently lives).

SE-7 — DNS-layer discovery¶

Ruled SHOULD by the specification authority, 2026-08-23.

• Where the participant controls authoritative DNS at the descriptor host, it SHOULD publish the §5.1.1 SVCB record and declare svcb_status: "live <date>".
• Where it does not, it MUST declare svcb_status: "unavailable" with an svcb_unavailable_reason naming the platform or registrar.

The question, and why it needed a ruling. §5.1.1 binds its MUST to "a webGCP server"; the frozen text then generalizes it to any host serving the descriptor, spec hosts included. A participant serves the descriptor and is not a server, so the two readings disagree for exactly the class this extension defines. Worse, the spec's restricted-domain escape hatch lands in conformance_level — a field a participant does not carry — so the caveat as written could not be applied here at all.

The case that was weighed. For MUST (uniformity): the DNS signal is what lets an agent ask "does this domain speak webGCP?" without an HTTPS round-trip, and a population-scanning agent would find participants the same way it finds servers; precedent leaned this way, since the spec host carries role instead of conformance_level and is still bound by §5.1.1. For SHOULD (adoption): requiring an RR TYPE 64 to install a script is the difference between a webmaster installing this and a webmaster filing a ticket with a DNS provider that may not support the type at all — and the spec's own restricted-domain caveat exists precisely because that population is large.

What was preserved either way. The disclosure is MUST under both readings. A participant without the record is legible — it says so, in the descriptor, with a reason — rather than silently non-conformant. That was the part worth protecting, and the ruling keeps it.

⚠ Scope of the ruling: it binds this extension, not the frozen spec. v0.1 §5.1.1 is unchanged and, per §10.4 normative immutability, will stay unchanged. A participant conformant to org.webgcp/site-embed@0.1 may therefore still read as non-conformant to a strict application of the frozen text's generalization. Closing that gap is a v0.2 clarification — that the SVCB MUST binds servers, not every host that serves a descriptor — and it is listed as owed below.

4. Conformance¶

The participant conformance profile — assertions, controls, and what is verifiable from the wire versus only by architecture review — is a separate document. The runnable fixture suite is owed, not shipped; until it exists this profile is a specification of tests, not a passing result. The anchor's own §16 is the standard being held to here: a standard without runnable conformance tests is aspirational.

Known limitations¶

• Cold-start credibility is undefined. A fresh participant domain has no history. What a brand-new identity may do — and how fast standing accrues — is deliberately left to the conformance profile, informed by the precedent that standing is gated by credibility and never by contribution volume.
• Free-lane rate limiting is per-instance today. The limit is enforced in the serving process, so it is per-instance rather than global; a horizontally scaled network host enforces N times the nominal limit. An edge WAF is the real front door when participant traffic earns one.
• Materialized skills can be mistaken for endorsements. A visiting agent that ignores the provenance labels will read a network skill as something the site vouches for. The labels are the mitigation and the profile must test their presence — but nothing forces a consumer to read them.
• SE-7 is ruled, but the underlying spec text is not. The authority ruled SHOULD for participants on 2026-08-23; v0.1 §5.1.1 still reads as a MUST generalized to any descriptor-serving host, and it is frozen. So a participant that is conformant to this extension can still be called non-conformant by someone applying the frozen text strictly. The declared svcb_status is what keeps that determinable rather than hidden, and the v0.2 clarification below is the real close-out.
• No participant implementation exists yet. Every requirement here is unexercised. The first real participant site is expected to falsify some of it.

Open items¶

Owed by v0.2 of the anchor spec (not by this extension):

1. A §5.1.1 clarification — that the SVCB MUST binds servers, not every host that serves a descriptor. The SE-7 ruling settles participant behaviour for this extension; only the spec can settle the reading. The clarification should also give the restricted-domain caveat a landing field for hosts that carry role in place of conformance_level, which today it lacks.

Owed by v0.2 of this extension:

2. The cold-start credibility curve, as a testable bound rather than a principle.
3. Whether consumes should carry a per-host lane declaration (free-only vs metered-enabled), which would make the SE-4 opt-in externally verifiable rather than an internal posture.