AMP Cache SXG Requirements

April 12, 2021 ยท View on GitHub

Audience

The audience for this document is people intending on implementing their own AMP signed exchange generator, independent of amppackager, and those implementing their own AMP SXG cache for the purposes of privacy-preserving prefetch. Users of amppkg need not read this, as the tool should automatically guarantee the following requirements are met.

Google AMP cache

The Google AMP cache sets some requirements in addition to the ones set by the SXG spec. These include:

  • The signed fallback URL must equal the URL at which the SXG was delivered.
  • The signed cert-url must be https.
  • The signature header must contain only:
    • One parameterised identifier.
    • Parameter values of type string, binary, or identifier.
  • The payload must be:
    • non-empty.
    • valid transformed AMP. The canonical definition of transformed AMP is the return value of transform.Process(). If given a valid AMP doc as input, it should produce a valid transformed AMP doc. There may be other ways of achieving this, but they are unsupported (i.e. may arbitrarily break in the future).
    • matching one of the versions requested by the AMP-Cache-Transform header. Note that this version range will increase over time, at a cadence TBD (likely 6-8 weeks with 2 or 3 supported latest versions).
  • If the signed cache-control header has a no-cache or private directive, it cannot have a value (i.e. no-cache=some-header is disallowed).
  • The signed content-security-policy header must be present and comply with these rules:
    • default-src, script-src, object-src, and style-src must equal those from the AMP cache CSP.
    • base-uri, block-all-mixed-content, font-src, form-action, manifest-src, referrer, report-uri and upgrade-insecure-requests may be omitted or have any value.
    • All other directives are disallowed.
  • The signed content-type header must be present. Its media type must be text/html. Its charset parameter, if present, must case-insensitively equal utf-8.
  • The signed link header, if present, must have limits like this (e.g. max 20 urls, rel=preload only, as=script|style only). URLs must be limited to cdn.ampproject.org and the allowlisted font provider URLs.
  • There must not be a signed variant-key-04 or variants-04 header.
  • The signature's lifetime (expires minus request time) must be >= 3 days; given AMP Packager's behavior of backdating by 1 day, this effectively means a minimum duration (expires minus date) of 4 days.

The above is an attempt at a complete list of SXG-related requirements, but it is not guaranteed to be complete.

If a document does not meet all of the above requirements, Google may still use its payload in an AMP viewer. The requirements for this are approximately as follows (but should not be relied upon by publishers):

  • magic string is correct
  • prologue length fields are correct
  • fallback URL matches request URL
  • MICE encoding and Digest header are valid
  • payload is valid AMP

Some of the above limitations are overly strict for an AMP SXG cache's needs, and were implemented as such for the sake of expediency. They may be loosened over time, especially in response to publisher feedback.

Other AMP caches

As other AMP caches adopt support for signed exchanges, they could define their own set of requirements. It would be most useful for publishers and users, however, if the requirements were the same across all caches. If you see a need for a different requirement on your cache, please contact the AMP Caching working group, for example via Slack on the #signed-exchanges channel, via one of these methods.

Testing

There is no known publicly available tool for validating an SXG against the above requirements, though one is certainly welcome. In the interim, one may issue a request against the Google AMP Cache and see if the response is a valid SXG.

Meets requirements:

$ curl -s -i -H 'Accept: application/signed-exchange;v=b3' https://amppackageexample-com.cdn.ampproject.org/wp/s/amppackageexample.com/ | grep -a -i content-type:
content-type: application/signed-exchange;v=b3

Does not meet requirements:

$ curl -s -i -H 'Accept: application/signed-exchange;v=b3' https://amppackageexample-com.cdn.ampproject.org/wp/s/amppackageexample.com/gen/invalid.sxg | grep -i warning:
warning: 199 - "inner != outer; fallback url https://azei-package-test.com/gen/unwrap2.sxg != https://amppackageexample.com/gen/invalid.sxg"