User Agent client hintsのJavaScript APIとHTTP Header

ua-client-hints.md

User Agent client hintsのJavaScript APIとHTTP Headerについてのメモ

Demo

Tested: Chrome Canary 86.0.4231.0

• Demo: https://client-hint-different-origin.glitch.me/
  • Allow Cross Origin version via Feature-Policy HTTP Header
  • https://client-hint-different-origin.glitch.me/allow-cross-origin/?uach=UA-Arch&uach=UA-Full-Version&uach=UA-Mobile&uach=UA-Model&uach=UA-Platform-Version&uach=UA-Platform&uach=UA

Soure Code:

• Host(⬇️Response): https://glitch.com/edit/#!/client-hint-different-origin
• 3rd party(cross origin): https://glitch.com/edit/#!/third-party-client-hint

Table

⬇️Response Accept-CH	⬆️Request header	⬆️ Request Example value	Description	JavaScript	Server
UA	Sec-CH-UA	"Chromium";v="84", "Google Chrome";v="84"	List of browser brands and their significant version.	Sync API	Default
UA-Mobile	Sec-CH-UA-Mobile	?1	Boolean indicating if the browser is on a mobile device (?1 for true) or not (?0 for false).	Sync API	Default
UA-Full-Version	Sec-CH-UA-Full-Version	"84.0.4143.2"	The complete version for the browser.	Async API	Accept-CH + Feature Policy
UA-Platform	Sec-CH-UA-Platform	"Android"	The platform for the device, usually the operating system (OS).	Async API	Accept-CH + Feature Policy
UA-Platform-Version	Sec-CH-UA-Platform-Version	"10"	The version for the platform or OS.	Async API	Accept-CH + Feature Policy
UA-Arch	Sec-CH-UA-Arch	"ARM64"	The underlying architecture for the device. While this may not be relevant to displaying the page, the site may want to offer a download which defaults to the right format.	Async API	Accept-CH + Feature Policy
UA-Model	Sec-CH-UA-Model	"Pixel 3"	The device model.	Async API	Accept-CH + Feature Policy

• JavaScript

  • Sync API: navigator.userAgentData.brandsとnavigator.userAgentData.mobileプロパティ
  • Async API: navigator.userAgentData.getHighEntropyValues()(Promise)

• Server

  • Default: デフォルトで送られる
  • Accept-CH: ⬇️ResponseでAccept-CHを指定していれば、同一オリジンからの⬆️RequestにはSec-CH-*が含まれる
  • Feature Policy(Permission Policy): ⬇️Responseと⬆️Request先のオリジンが異なる場合には、⬇️ResponseヘッダにFeature-Policyヘッダが必要
    • Feature-Policyヘッダでどのオリジンに対してどのClient-Hintを送っていいのかを指定する
    • ch-ua-* ヘッダのデフォルト値はselfであるため、⬇️Responseと⬆️Requestのオリジンが同じ場合はFeature Policyの指定がいらない
    • Feature Policyを指定するのは⬇️Responseを返すウェブサイト側
      • ⬆️Request をするときの Origin ヘッダの値となるサイトがFeature Policyを指定してないと行けない。
      • 3rd partyのjs自体にFeature Policyヘッダを指定しても、Originヘッダは⬇️Responseのサイトになるので意味はない

すべてのorigin(*)に対して、全てのch-ua-*を送って良いと許可する⬇️Responseの例(express)

// https://wicg.github.io/client-hints-infrastructure/#policy-controlled-features
const ALLOW_ORIGIN = "*"
res.set("accept-ch", "UA-Arch, UA-Full-Version, UA-Mobile, UA-Model, UA-Platform-Version, UA-Platform, UA");
res.set("Feature-Policy", `ch-ua-arch ${ALLOW_ORIGIN};ch-ua-model ${ALLOW_ORIGIN};ch-ua-platform ${ALLOW_ORIGIN};ch-ua-platform-version ${ALLOW_ORIGIN};ch-ua-full-version ${ALLOW_ORIGIN};`);

📝 self を指定すると同一originに対しても送らなくなるバグがある気がする

参考

• Improving user privacy and developer experience with User-Agent Client Hints
• WICG/ua-client-hints: Wouldn't it be nice if User-Agent was a (set of) client hints?
• helmetjs/feature-policy: Middleware for setting the Feature-Policy HTTP response header
• Client Hints and Feature Policies - mpulp
• User-Agent Client Hints