【この訳に特有な表記規約】
この訳の,~algoの記述に利用されている各種記号(ε, コレ, ~LET, ~IF, ~RET, 等々)の意味や定義の詳細は、 ~SYMBOL_DEF_REFを~~参照されたし。
一部の箇所では、 既存の用語を利用して記述を簡約している。
(原文には明示的に定義されていないが、) 所与の ( `~navigable$ %~navigable ) に対し, %~navigable に `属する文書@ とは、 次を満たす`文書$たちを指す ⇒ その`~node~navigable$ ~EQ %~navigable
1. 序論
~web~platformは、 絶えず発展し続ける一連の[ 特能や~API ]を供して,より[ 多彩な機能性, 開発者にとって使い勝手の良さ, 改善された処理能 ]を提供する。 しかしながら、 開発者が,~browserに備わるこれらの[ 特能や~API ]のうち一部の挙動を 自身の~appの中で選択的に[ 可能化- / 不能化- / 改変- ]する能は、 これまで無かった: ◎ The web platform provides an ever-expanding set of features and APIs, offering richer functionality, better developer ergonomics, and improved performance. However, a missing piece is the ability for the developer to selectively enable, disable, or modify the behavior of some of these browser features and APIs within their application:
- 開発者は、 ~browserに備わる ある種の[ 特能や~API ]への~accessを 選択的に`不能化-^emしたいと求めることもある — ~securityや処理能のための予防策として,自身の~appの中で実行されている[ 自前の/第三者-主体の ]内容が[ 求まれない/期待されない ]挙動を導入するのを防止して,自身の~appを “監禁する” ために。 ◎ The developer may want to selectively disable access to certain browser features and APIs to "lock down" their application, as a security or performance precaution, to prevent own and third-party content executing within their application from introducing unwanted or unexpected behaviors within their application.
- 開発者は、[ 既定では不能化され得るような,~browserに備わる ある種の[ 特能や~API ]]への~accessを,選択的に`可能化-^emしたいと求めることもある — 例:一部の特能は、[ 埋込まれた文脈においては、 明示的に可能化されない限り,既定で不能化される ]こともあれば[ 他の施策~要件の~subjectになる ]こともある。 ◎ The developer may want to selectively enable access to certain browser features and APIs which may be disabled by default - e.g. some features may be disabled by default in embedded context unless explicitly enabled; some features may be subject to other policy requirements.
-
開発者は、[ ある種の[ 特能や~API ]の[ 利用, または欠如 ]について,自身の~app[ の~client/を埋込む側 ]に約束する ]ことを表明するような施策を利用したいと求めることもある。 例えば:
- ~browserにおいて ある種の “`fast path^en”† 最適化を可能化するため。 【†よくある事例~用の “優先路”(観光客専用の入出国手続きの様な)】
- 埋込む側 — 例:様々な~social~network, 探索~engine, 等々 — が設定した一部の要件に対する適合性についての約束を表明するため。
この仕様は、 上の利用事例に取組む施策の仕組みを定義する。 ◎ This specification defines a policy mechanism that addresses the above use cases.
注記: この仕様は、 以前は “`Feature Policy^en” ( “特能~施策” )と命名されていた†。 ◎ This specification used to be named Feature Policy.
【† “`Feature Policy^en” を名前の一部に含む[ 用語, ~IDL構成子, ~header, 原文の~URL, GitHub 内の関連な~pageの~URL, 等々 ]も,すべて “`Permissions Policy^en (許可~施策)” に改称された (文字大小は問わず,文字大小や約物はそのままに)。 】
2. 例
~SecureCorp社は、 自身の~appの中では[ ~Fullscreen/~Geolocation ]~APIの利用を不能化したいと求めているとする。 次のような許可~施策を定義する~HTTP応答~headerを送達すれば、 それを行える: ◎ SecureCorp Inc. wants to disable use of Fullscreen and Geolocation APIs within their application. It can do so by delivering the following HTTP response header to define a permissions policy:
`Permissions-Policy$h: fullscreen=(), geolocation=()
空な生成元~listを指定することにより、 指定された特能は — 入子なものも含め,どの文書においても、 その生成元に関わらず — 不能化されることになる。 ◎ By specifying an empty origin list, the specified features will be disabled for all documents, including nested documents, regardless of their origin.
地理所在( `geolocation^en )は、 非同一-生成元に属する どの~frame内でも,既定では不能化される。 ~FastCorp社の~siteは、 特定の非同一-生成元 `iframe$e 内では地理所在を可能化したいと求めているとする。 そうするためには、 `iframe^e 要素に "`allow^a" 属性を含ませる: ◎ Geolocation is disabled by default in all cross-origin frames. FastCorp Inc. has a specific cross-origin iframe on their site for which it wants to enable geolocation. It can do so by including an "allow" attribute on the iframe element:
<iframe src="https://other.com/map" `allow$a="geolocation"></iframe>
各種 `iframe^e 用の属性は、 一定の~frame内に限り,選択的に特能を可能化できる — 他では,同じ生成元からの文書を包含する場合でも可能化しないように。 ◎ Iframe attributes can selectively enable features in certain frames, and not in others, even if those contain documents from the same origin.
~SecureCorp社は、[ 自前の生成元/ 生成元 `https://example.com^l ]用を除くどの`子孫~navigable群$の中でも — ~SecureCorp社の~pageに自前の `iframe$e を埋込める攻撃者が居たとしても — ~Geolocation~APIの利用を完全に不能化したいと求めているとする。 次のような[ 制約された許可~施策を~Geolocation用に定義する,~HTTP応答~header ]を送達すれば、 それを行える: ◎ SecureCorp Inc. wants to completely disable use of the Geolocation API within all descendant navigables except for its own origin and those whose origin is "https://example.com", even in the presence of an attacker who can embed their own iframes on SecureCorp’s pages. It can do this by delivering the following HTTP response header to define a restricted permissions policy for Geolocation:
`Permissions-Policy$h: geolocation=(self "https://example.com")
`許容list$は、 1 個~以上の生成元からなる~listである — その各~生成元には、 次のいずれかを与えれる ⇒# 任意選択で~keyword `self$P を伴う,~appの生成元 / 任意の第三者-主体~生成元 ◎ The allowlist is a list of one or more origins, which can include the application’s origin, optionally with the keyword "self", and any third-party origin.
この施策の効果がある下では、[ 通例通り `allow$a `iframe^e 属性を利用して,一定の~frameに対し地理所在を是認できる ]が、 その~APIを利用する能が実際に是認されるのは,[ `http://example.com^l / ~SecureCorp自身 ]からの内容を~hostしている~frameに限られることになる。 ◎ With this policy in effect, it can then use the "allow" iframe attribute as usual to grant geolocation to certain frames, but only those frames hosting content from http://example.com or SecureCorp itself will actually be granted the ability to use that API.
4. ~framework
4.1. 施策により制御される特能
`施策により制御される特能@ は、 `許可~施策$を~~参照することにより,文書において[ 可能化-/不能化- ]できる[ ~APIや挙動 ]である。 ◎ A policy-controlled feature is an API or behaviour which can be enabled or disabled in a document by referring to it in a permissions policy.
注記: 簡潔にするため,この文書においては、 施策により制御される特能は “特能” と略称されることが多い。 他が指示されない限り,用語 “特能” は`施策により制御される特能$を指す。 そのような特能を定義する他の仕様は、 多義性を避けるため,長い方の用語を利用するべきである。 ◎ For brevity, policy-controlled features will often be referred to in this document simply as "Features". Unless otherwise indicated, the term "feature" refers to policy-controlled features. Other specifications, defining such features, should use the longer term to avoid any ambiguity.
この仕様は、 現時点では,文書~内に定義される特能しか対処していない。 これについて,~Workerや~Worklet内の[ 特能/許可~施策 ]の可能性も含みにする言い回しを見つけるべきである。 ◎ This spec currently only deals with features defined in Documents. We should figure out how to word this to include the possibility of features and permissions policies in Workers and Worklets as well.
`施策により制御される特能$は、[ `施策~指令$内で利用される,文字列による~token ]により識別される。 ◎ Policy-controlled features are identified by tokens, which are character strings used in policy directives.
各 `特能$ %特能 には、 `既定の許容list$がある — それは、 次の 2 つを定義する: ◎ Each policy-controlled feature has a default allowlist, which defines\
- %特能 は,`~top-level辿可能$に`属する文書$内で可用になるかどうか ◎ whether that feature is available in documents in top-level traversables,\
- %特能 への~accessは,`子~navigable$へ どう継承されるか ◎ and how access to that feature is inherited in child navigables.
`特能$のうち,~UAが施策を通して制御することを許容するものは、 `~support済み特能@ と呼ばれる。 ~UAには、 あらゆる`特能$を~supportすることは要求されない。 ◎ A user agent has a set of supported features, which is the set of features which it allows to be controlled through policies. User agents are not required to support every feature.
注記: `施策により制御される特能$自体は、 この~frameworkの一部を成すものではない。 現時点で定義されている規範的でない特能の~listは、 この仕様とは別に, `姉妹~文書@https://github.com/w3c/webappsec-permissions-policy/blob/main/features.md$ にて保守されている。 ◎ The policy-controlled features themselves are not themselves part of this framework. A non-normative list of currently-defined features is maintained as a companion document alongside this specification.
4.2. 施策
`許可~施策@ は、 次の~itemからなる`構造体$である ⇒# `継承した施策$, `宣言-済み施策$ ◎ A permissions policy is a struct with the following items: • An inherited policy. • A declared policy.
`空な許可~施策@ は、 次のようにされた`許可~施策$である:
- どの`~support済み特能$ %特能 に対しても ⇒ `継承した施策$[ %特能 ] ~EQ `可能化される^i
- `宣言-済み施策$は空~map
4.3. 継承した施策
`継承した施策@ は、 各 `特能$を[ ある施策 ~IN { `可能化される^i, `不能化される^i } ]に対応付ける`有順序~map$である。 ◎ An inherited policy is an ordered map from features to either "Enabled" or "Disabled".
`特能~用に継承される施策@ は、 所与の %特能 に対し,`継承した施策$[ %特能 ] で与えられる。 `許可~施策$が初期化された後には、 それが`継承した施策$は,各`~support済み特能$用に何らかの値を包含することになる。 ◎ The inherited policy for a feature feature is the value in the inherited policy whose key is feature. After a permissions policy has been initialized, its inherited policy will contain a value for each supported feature.
注記: ~frame~treeを成す各 文書は、 一連の施策を継承する — [ ~top-level文書は 各`特能$用に定義される既定~のものから / 他の文書は その親~frameから ]。 この継承した施策は、 次を決定する ⇒# 各~特能の初期~状態( `可能化される^i / `不能化される^i ) / 文書~内の`宣言-済み施策$により制御できるかどうか。 ◎ Each document in a frame tree inherits a set of policies from its parent frame, or in the case of the top-level document, from the defined defaults for each policy-controlled feature. This inherited policy determines the initial state ("Enabled" or "Disabled") of each feature, and whether it can be controlled by a declared policy in the document.
`~top-level辿可能$に`属する文書$に継承される施策は、 各~特能~用に定義される既定の施策に基づく。 ◎ In a Document in a top-level traversable, the inherited policy is based on defined defaults for each feature.
`子~navigable$に`属する文書$に継承される施策は、[ 親~文書の`許可~施策$doc, 当の`子~navigable$の`容器~施策$ ]に基づく。 ◎ In a Document in a child navigable, the inherited policy is based on the parent document’s permissions policy, as well as the child navigable's container policy.
4.4. 宣言-済み施策
`宣言-済み施策@ は、 各 `特能$を ある`許容list$に対応付ける`有順序~map$である。 ◎ A declared policy is an ordered map from features to allowlists.
4.5. ~header施策
`~header施策@ は、 文書に伴う~HTTP~headerを介して送達された`施策~指令$からなる~listである。 これは、 文書の`許可~施策$の`宣言-済み施策$を形成する。 ◎ A header policy is a list of policy directives delivered via an HTTP header with a document. This forms the document’s permissions policy’s declared policy.
4.6. 容器~施策
各 `子~navigable$は、 `~header施策$に加えて, `容器~施策@ を持つ。 それは、 `施策~指令$であり,空にもなり得る。 `容器~施策$は、 `~navigable容器$上の属性により設定できる。 ◎ In addition to the header policy, each child navigable has a container policy, which is a policy directive, which may be empty. The container policy can set by attributes on the navigable container.
`子~navigable$用の`容器~施策$は、 その~navigableの中に読込まれる文書に`継承される施策$に波及する (`生成元に属する容器~内の特能~用に継承される施策を定義する$を見よ)。 ◎ The container policy for a child navigable influences the inherited policy of any document loaded into that navigable. (See § 9.7 Define an inherited policy for feature in container at origin)
注記: 現時点では,`容器~施策$は直には設定できないが、 `iframe^e 要素の `allowfullscreen@#iframe-allowfullscreen-attribute$a, `allow@#iframe-allow-attribute$a 属性により,間接的に設定される。 この仕様の将来の改訂は、 全部的な`容器~施策$を明示的に宣言する仕組みを導入し得る。 ◎ Currently, the container policy cannot be set directly, but is indirectly set by iframe "allowfullscreen", "and allow" attributes. Future revisions to this spec may introduce a mechanism to explicitly declare the full container policy.
4.7. 施策~指令
`施策~指令@ は、 各 `特能$を ある`許容list$に対応付ける`有順序~map$である。 ◎ A policy directive is an ordered map, mapping policy-controlled features to corresponding allowlists of origins.
`施策~指令$は ⇒# ~HTTP~header内では`辞書$sfの直列化として表現される/ ~HTML属性~内では`~ASCII直列化@#ascii-serialization$として表現される ◎ A policy directive is represented in HTTP headers as the serialization of an sh-dictionary structure, and in and HTML attributes as its ASCII serialization.
4.8. 許容list
許可~施策 `許容list@ は、 概念的には,いくつかの`生成元$からなる集合である。 `許容list$は、 次のいずれかをとり得る: ◎ A permissions policy allowlist is conceptually a set of origins. An allowlist may be either:
- あらゆる生成元を表現する,特別な値 "`*@P" 。 この仕様における `全~生成元@i は、 この値を表す別名として利用される。 【 この別名は、表記的/意味的に明快にするために,この訳に導入している。】 ◎ The special value *, which represents every origin, or
- `生成元$たちが成す`有順序~集合$ 【集合を成す~itemどうしの比較は、`同一-生成元$に基づくことになる。】 ◎ An ordered set of origins
注記: [ ~headerや属性 ]内の文字列による許容listの~text表現には、 ~keyword[ `'self'^l, `'src'^l, `'none'^l ]も現れ得る。 【~header内では、 `self^l に限り,一重引用符 `'^l で括られずに現れ得る。】 これらの各~keywordは,常に構文解析の間に その文脈において解釈され、 それぞれが指す生成元のみが,許容list~内に格納される。 ~keyword自身は、 許容listの一部を成すことはない。 ◎ The keywords 'self', 'src', and 'none' can appear in the text representation of allowlists in headers and attribute strings. These keywords are always interpreted in context during parsing, and only the origins which they refer to are stored in the allowlist. The keywords themselves are not part of the allowlist.
`許容listは生成元に合致する@ かどうか決定するときは、 所与の ( `許容list$ %許容list, 生成元 %生成元 ) に対し,次の手続きを走らす: ◎ To determine whether an allowlist matches an origin origin, run these steps:
- ~IF[ %許容list ~EQ `全~生成元$i ] ⇒ ~RET ~T ◎ If the allowlist is the special value *, then return true.
- %許容list 内の ~EACH( %~item ) に対し ⇒ ~IF[ ( %~item, %生成元 ) は`同じ生成元~domain$である ] ⇒ ~RET ~T ◎ Otherwise, for each item in the allowlist: • If item is same origin-domain with origin, then return true.
- ~RET ~F ◎ return false.
4.9. 既定の許容list
各 `特能$ %特能 には、 `既定の許容list@ がある。 `既定の許容list$は、 次を決定する: ◎ Every policy-controlled feature has a default allowlist. The default allowlist determines\
- `~top-level辿可能$内に宣言された施策は無い下で、 %特能 は,文書において許容されるかどうか ◎ whether the feature is allowed in a document with no declared policy in a top-level traversable,\
- %特能 への~accessは、 自動的に`子~navigable$に`属する文書$に委任されるかどうか ◎ and also whether access to the feature is automatically delegated to documents in child navigables.
所与の`特能$ %特能 用の`既定の許容list$は、 次に挙げる いずれかの値をとる: ◎ The default allowlist for a feature is one of these values:
- `全~生成元$i
- %特能 は、 既定では,`~top-level辿可能$に`属する文書$において許容される。 加えて,許容されるときは、 `子~navigable$に`属する文書$においても既定で許容される。 ◎ The feature is allowed in documents in top-level traversables by default, and when allowed, is allowed by default to documents in child navigables.
- `'self'@l
- %特能 は、 既定では,`~top-level辿可能$に`属する文書$において許容される。 加えて,許容されるときは、 `子~navigable$に`属する文書$のうち, `同じ生成元~domain$に属する文書においては既定で許容されるが、 非同一-生成元に属する文書においては,既定では許容されない。 ◎ The feature is allowed in documents in top-level traversables by default, and when allowed, is allowed by default to same-origin domain documents in child navigables, but is disallowed by default in cross-origin documents in child navigables.
5. 許可~施策の直列化
5.1. ~HTML属性の直列化
`施策~指令$は、 ~HTML属性~内では,次の~ABNFによる~ASCII直列化として表現される: ◎ Policy Directives in HTML attributes are represented as their ASCII serialization, with the following ABNF:
`serialized-permissions-policy@P = `serialized-policy-directive$P *(";" `serialized-policy-directive$P) `serialized-policy-directive@P = `feature-identifier$P RWS `allow-list$P `feature-identifier@P = 1*( ALPHA / DIGIT / "-") `allow-list@P = `allow-list-value$P *(RWS `allow-list-value$P) `allow-list-value@P = `serialized-origin$P / "*" / "'self'" / "'src'" / "'none'"
`serialized-origin@P は、 `生成元の直列化$である。 しかしながら,符号位置[ `0027^U (') / `0021^U (*) / `002C^U (,) / `003B^U (;) ]は、 直列化~内に現れてはナラナイ — それらが要求される場合には、[ `%27^l / `%2A^l / `%2C^l / `%3B^l ]として~percent-符号化されなければナラナイ。 ◎ serialized-origin is the serialization of an origin. However, the code points U+0027 ('), U+0021 (*), U+002C (,) and U+003B (;) MUST NOT appear in the serialization. If they are required, they must be percent-encoded as "%27", "%2A", "%2C" or "%3B", respectively.
注記: 文字列 `'self'^l は、 許容list内の生成元として利用されてもヨイ。 この仕方で利用されたときは、 当の許可~施策を包含する文書の生成元を指すことになる。 ◎ The string "'self'" may be used as an origin in an allowlist. When it is used in this way, it will refer to the origin of the document which contains the permissions policy.
5.2. 有構造~headerの直列化
~HTTP~header内の`施策~指令$は、 `有構造~field$として表現される。 `HEADER-STRUCTURE$r ◎ Policy Directives in HTTP headers are represented as Structured Fields. [HEADER-STRUCTURE]
この表現においては、 `施策~指令$は,`辞書$sfにより表現される。 ◎ In this representation, a policy directive is represented by a Dictionary.
`辞書$sfの各~memberは、 ある`特能$をある`許容list$に結付ける。 ~memberの名前は、 ~tokenでなければナラナイ 【と記されているが、これは`~token$sfではなく,`~key$sfでなければならないはず】 。 ~tokenが~supportされる特能の名前でない場合、 当の辞書~memberは,処理~手続きにより無視されることになる。 ◎ Each Dictionary Member associates a feature with an allowlist. The Member Names must be Tokens. If a token does not name a supported feature, then the Dictionary Member will be ignored by the processing steps.
各~memberの値は、 `許容list$を表現する — 次に挙げるいずれかでなければナラナイ: ◎ The Member Values represent allowlists, and must be one of:
- ある`生成元の直列化$を包含する`文字列$sf ◎ a String containing the ASCII serialization of an origin
- `~token$sf `全~生成元$i( `*^P ) ◎ the Token *
- `~token$sf `self@P ◎ the Token self
- 上に挙げた 0 個以上の`~item$sfを包含している`内縁~list$sf — この~list内にある他の`~item$sfは、 処理~手続きにより無視され,当の~itemは無かったかのように処理されることになる。 ◎ an Inner List containing zero or more of the above items. ◎ Any other items inside of an Inner List will be ignored by the processing steps, and\
`辞書$sfの~memberが他の形による値をとる場合、 処理~手続きにより,当の~member全体が無視されることになる。 ◎ the Member Value will be processed as if they were not present. Member Values of any other form will cause the entire Dictionary Member to be ignored by the processing steps.
6. 送達
6.1. `Permissions-Policy^h ~HTTP~header
[ ~clientにより施行されるべきである`許可~施策$ ]を( ~serverから~clientへ )通信するときには、 ~HTTP応答~内に `Permissions-Policy@h ~headerを利用できる。 【旧 `Feature-Policy^h ~headerから改称された。】 ◎ The `Permissions-Policy` HTTP header field can be used in the response (server to client) to communicate the permissions policy that should be enforced by the client.
`Permissions-Policy$h は、 `有構造~header$である。 その値は、 `辞書$sfでなければナラナイ。 その~ABNFは: ◎ Permissions-Policy is a structured header. Its value must be a dictionary. It’s ABNF is:
PermissionsPolicy = `sf-dictionary$P
この辞書の意味論は、 `§ 有構造~headerの直列化@#structured-header-serialization$にて定義される。 ◎ The semantics of the dictionary are defined in § 5.2 Structured header serialization.
この辞書の処理は、 `辞書と生成元から施策を構築する$手続きにて定義される。 ◎ The processing steps are defined in § 9.2 Construct policy from dictionary and origin.
6.2. `iframe^e 要素の `allow^a 属性
`iframe$e 要素の `allow$aF 属性は、 `直列形の許可~施策$を包含する。 ◎ iframe elements have an "allow" attribute, which contains an ASCII-serialized policy directive.
`allow^aF 属性~内に挙げられた各 名前の特能~用の`許容list$は: ◎ ↓
- 空になることもある。 その事例では、 当の許容list用の既定の値は `'src'^l とする — この値は、 `iframe$e 要素の `src$aF 属性に与えられた~URLの`生成元$urlを表現する。 ◎ The allowlist for the features named in the attribute may be empty; in that case, the default value for the allowlist is 'src', which represents the origin of the URL in the iframe’s src attribute.
- 空でないときは、 当の `allow^aF 属性を有する `iframe$e 要素の`内容~navigable$が構築されるときに, その`容器~施策$に[ 認識される各`特能$用の`許容list$ ]が追加されることになる。 ◎ When not empty, the "allow" attribute will result in adding an allowlist for each recognized feature to the iframe element’s content navigable's container policy, when it is constructed.
6.3. 旧来の特能を~supportする追加的な属性
この仕様により制御される一部の`特能$に対しては、 それ用の既存の属性が `iframe^e 要素~上に定義されている。 この仕様は、 これらの属性を `iframe^e 要素~用に宣言された施策として動作するように定義し直す。 ◎ Some features controlled by Permissions Policy have existing iframe attributes defined. This specification redefines these attributes to act as declared policies for the iframe element.
6.3.1. `allowfullscreen^a
`iframe$e 要素 %要素 上の `allowfullscreen$aF 属性は、 `requestFullscreen()$m への~accessを制御する: ◎ The "allowfullscreen" iframe attribute controls access to requestFullscreen().
- %要素 が `allow$aF 属性を有していて,その値は ~token `fullscreen^l を包含する場合、 `allowfullscreen$aF 属性による効果は無いモノトスル。 ◎ If the iframe element has an "allow" attribute whose value contains the token "fullscreen", then the "allowfullscreen" attribute must have no effect.
- 他の場合, %要素 が `allowfullscreen$aF 属性を有するならば、 %要素 の`内容~navigable$が構築されるときに, その`容器~施策$に `fullscreen^l 特能~用の`許容list$として `全~生成元$i が追加されることになる。 ◎ Otherwise, the presence of an "allowfullscreen" attribute on an iframe will result in adding an allowlist of * for the "fullscreen" feature to the iframe element’s content navigable's container policy, when it is constructed.
注記: これは、 `<iframe allow="fullscreen">^c の挙動とは異なるが、 既存の `allowfullscreen^a の利用と互換性を得るためにある。 `iframe^e 要素が[ `allow="fullscreen"^c, `allowfullscreen^a ]どちらも有する場合、 より制約的な方の許容listを成す `allow="fullscreen"^c が利用されることになる。 ◎ This is different from the behaviour of <iframe allow="fullscreen">, and is for compatibility with existing uses of allowfullscreen. If allow="fullscreen" and allowfullscreen are both present on an iframe element, then the more restrictive allowlist of allow="fullscreen" will be used.
7. ~scriptからの施策の自己検分
7.1. 概観
文書~内で効果を発揮している現在の施策は、 ~scriptから観測できる。 これは、[ ある特能が可能化されているかどうか判らない限り,何かを決定するのが — 一例として, どの~UIを表示するかなど — アリでない事例 ]で,裁定を下すときに利用できる。 (特能には、 観測-可能な失敗~modeが無いものや, 特能~検出に際し求まれない副作用を伴うものもあるかもしれない。) ◎ The current policy which is in effect in a document can be observed by scripts. This can be used to make decisions, for instance, about what user interface to display, in cases where it is not possible to determine otherwise whether a feature is enabled or not. (Some features may not have any observable failure mode, or may have unwanted side effects to feature detection.)
`文書$, `iframe^e の両者とも, `PermissionsPolicy$I ~objを供する — それを利用すれば、 自身に適用される許可~施策を検分できる。 ◎ Documents and iframes both provide a PermissionsPolicy object which can be used to inspect the permissions policies which apply to them.
7.1.1. 文書~施策
現在~有効な施策を検索取得するときは、 `document.permissionsPolicy$m を利用する。 これは、 次に利用できる `PermissionsPolicy$I ~objを返す: ◎ To retreive the currently effective policy, use document.permissionsPolicy. This returns a PermissionsPolicy object, which can be used to:
- 現在の文書に対し,所与の特能~用の状態(許容されるか/否認されるか)を~queryする ◎ query the state (allowed or denied) in the current document for a given feature,
- 現在の文書にて可用な特能すべて(許容されないものも含む)からなる~listを取得する ◎ get a list of all available features (allowed or not) in the current document,
- 現在の文書にて許容される特能すべてからなる~listを取得する ◎ get a list of all allowed features in the current document, or
- 現在の文書における,所与の特能~用の許容listを取得する。 ◎ get the allowlist for a given feature in the current document.
<!doctype html> <script> const %policy = document.permissionsPolicy; /* この文書が~WebUSBを利用できるならば、 次の結果は ~T になる。 ◎ This will be true if this document can use WebUSB. */ const %can_use_usb = %policy.allowsFeature('usb'); /* `https://example.com^s にある新たな~frameには,~WebXRの利用は許容されるならば、 次の結果は ~T になる。 ◎ True if a new frame at https://example.com will be allowed to use WebXR. */ if (%policy.allowsFeature('xr-spatial-tracking', 'https://example.com')) { /* `https://example.com^s にある~frameを作成する~UIを示す。 ◎ Show UI to create frame at https://example.com. */ } else { /* 代替~UIを示す。 ◎ Show an alternative UI. */ } /* `payment^l (支払い)要請が許容される生成元たちの~listを取得する。 結果は、 すべての生成元に許容される場合は `全~生成元$i のみからなる~list( `['*']^c )になり,他の場合は 明示的な生成元の~listになる。 ◎ Get the list of origins which are allowed to request payment. The result will be a list of explicit origins, or the single element ['*'] if all origins are allowed. */ const %allowed_payment_origins = %policy.getAllowlistForFeature('payment'); /* この文書にて~supportされるすべての特能の~listを(許容されないものも含めて)取得する。 結果は文字列の配列になり、 各~文字列は,ある特能を表現する。 ◎ Get the list of all features supported in this document (even those which are not allowed). The result will be an array of strings, each representing a feature. */ const %all_features = policy.features(); if (%all_features.includes('geolocation')) { /* 第三者-主体の地図~serviceに子~frameを付加する ◎ Append a child frame to a third-party map service. */ } </script>
7.1.2. ~frame施策
`iframe^e 要素~上の施策を,それを包含する文書から検分することもアリである。 この事例における施策~objは、 その~frame用の`観測-可能な施策$を表現する — それは、 現在の文書と `iframe^e 要素の属性のみに依存し,[ ~frame内で,ある特能が実際に現在~許容されているかどうか ]を露呈することはない。 ~frame内の文書は、 ~HTTP~headerを介して自前の施策を適用していることもあれば,初期の所在から新たな生成元へ~navigateされることもある。 そのような事例で[ `iframe$e 要素の`内容~navigable$【!nested navigable】内で有効な施策 ]が露呈されれば、 非同一-生成元~文書の挙動について情報を漏洩することになり得る。 ◎ It is also possible to inspect the policy on an iframe element, from the document which contains it. The policy object in this case represents the observable policy for the frame, which depends only on the current document and the attributes of the iframe element. It does not reveal whether a feature is actually currently allowed in the frame, as the document in the frame may have applied its own policy via an HTTP header, or may have navigated away from its initial location to a new origin. Revealing the effective policy in the iframe element’s nested navigable in that case could leak information about the behaviour of a cross-origin document.
<!doctype html> <iframe id="frame" allow="fullscreen; xr-spatial-tracking"></iframe> <script> const %iframe_element = document.getElementById("frame"); const %iframe_policy = %iframe_element.permissionsPolicy; /* ~frame化された文書にて~WebXRの利用は許容されるならば、 次の結果は ~T になる。 ◎ True if the framed document will be allowed to use WebXR */ if (%iframe_policy.allowsFeature('xr-spatial-tracking')) { /* 仮想現実~controlを表示する ◎ display virtual reality controls */ } </script>
`iframe^e 要素~用の`観測-可能な施策$は、 ~frameの中に読込まれた実際の内容には依存しない (非同一-生成元への情報~漏洩eを避けるため) — また、 要素が文書~tree内にあるかどうかにも依存しない。 ◎ The observable policy on an iframe element is independent of any actual content loaded into the frame (to avoid cross-origin information leakage,) or even whether it is in a document tree.
<!doctype html> <!-- 次の~frameの `src^a 属性に与えた文書が読込まれるときは、 その~frameには,~fullscreenを利用することは許容されるべきでない。 ◎ this frame should not be allowed to use fullscreen when the document in its src attribute is loaded in it --> <iframe id="frame" allow="fullscreen https://example.com" src="https://example.net/" ></iframe> <script> const %iframe_element = document.getElementById("frame"); const %iframe_policy = %iframe_element.permissionsPolicy; /* 次の結果は、 ~F になる — 施策により、 `src^a 属性~内に挙げられた~URLには,~fullscreenの利用は許容されないので。 ◎ This will be false, as the URL listed in the src attribute is not allowed by policy to use fullscreen. */ const %is_fullscreen_allowed_in_frame = iframe_policy.allowsFeature('fullscreen'); const %new_frame = document.createElement('iframe'); %new_frame.allow = 'sync-xhr'; /* 次の結果は、 ~T になる。 すなわち、 この `iframe^e には `sync-xhr^l 【同期的 `XMLHttpRequest$I 】の利用-は許容される — `src^a 属性に挙げられた~URLが何であれ,属性がまだ設定されてなくとも。 ◎ This will be true, as the iframe is allowed to use sync-xhr at whatever URL is mentioned in its src attribute, even though that attribute is not yet set. */ const %is_sync_xhr_allowed = %new_frame.permissionsPolicy.allowsFeature('sync-xhr'); </script>
7.2. `PermissionsPolicy^I ~obj
[`Exposed$=Window] interface `PermissionsPolicy@I { `boolean$ `allowsFeature$m(`DOMString$ %feature, optional `DOMString$ %origin); `sequence$<`DOMString$> `features$m(); `sequence$<`DOMString$> `allowedFeatures$m(); `sequence$<`DOMString$> `getAllowlistForFeature$m(`DOMString$ %feature); }; partial interface `Document$I { [`SameObject$] readonly attribute `PermissionsPolicy$I `~permissionsPolicyD$m; }; partial interface `HTMLIFrameElement$I { [`SameObject$] readonly attribute `PermissionsPolicy$I `~permissionsPolicyF$m; };
各 `PermissionsPolicy$I ~obj %P には、 ある`~node$が結付けられる — それは, %P に `結付けられている~node@ と称され、 %P の作成-時に設定される。 ◎ A PermissionsPolicy object has an associated node, which is a Node. The associated node is set when the PermissionsPolicy object is created.
各 `PermissionsPolicy$I ~obj %P の `既定の生成元@ は、 %P に`結付けられている~node$ %~node に応じて,次で与えられる`生成元$になる ⇒# `文書$であるならば %~node の`生成元$doc【!`生成元$】 / `要素$であるならば %~node 用に`宣言された生成元$ ◎ A PermissionsPolicy object has a default origin, which is an origin, whose value depends on the state of the PermissionsPolicy object’s associated node: • If the PermissionsPolicy object’s associated node is a Document, then its default origin is the Document's origin. • If the PermissionsPolicy object’s associated node is an Element, then its default origin is the Element's declared origin.
各`文書$ %文書 には、 %文書 の `施策~obj@doc と称される,次を満たす `PermissionsPolicy$I ~obj %P がただ一つ在る ⇒ %P に`結付けられている~node$ ~EQ %文書 ◎ Each Document has a policy object, which is a PermissionsPolicy instance whose associated node is that Document.
各 `iframe$e 要素 %要素 には、 %要素 の `施策~obj@iF と称される,次を満たす `PermissionsPolicy$I ~obj %P がただ一つ在る ⇒ %P に`結付けられている~node$ ~EQ %要素 ◎ Each iframe element has a policy object, which is a PermissionsPolicy instance whose associated node is that element.
`allowsFeature(feature, origin)@m ~method~手続きは: ◎ The allowsFeature(feature, origin) method must run the following steps:
- ~IF[ %origin ~EQ ε ] ⇒ %origin ~SET コレの`既定の生成元$ ◎ If origin is omitted, set origin to this PermissionsPolicy object’s default origin.
- %施策 ~LET コレに`結付けられている~node$用の`観測-可能な施策$ ◎ Let policy be the observable policy for this PermissionsPolicy object’s associated node.
- ~IF[ %施策 により, %特能 は %origin 用に許容される【具体的な~algoは指定されていない】 ] ⇒ ~RET ~T ◎ If feature is allowed by policy for origin, return true.
- ~RET ~F ◎ Otherwise, return false.
`features()@m ~method~手続きは: ◎ The features() method must run the following steps:
- %結果 ~LET 新たな`有順序~集合$ ◎ Set result to an empty ordered set.
- ~EACH( `~support済み特能$ %特能 ) に対し ⇒ %特能 を %結果 に`付加する$set ◎ For each supported feature feature: • Append feature to result.
- ~RET %結果 ◎ return result
`allowedFeatures()@m ~method~手続きは: ◎ The allowedFeatures() method must run the following steps:
- %結果 ~SET 新たな`有順序~集合$ ◎ Set result to an empty ordered set.
- %生成元 ~LET コレの`既定の生成元$ ◎ Let origin be this PermissionsPolicy object’s default origin.
- %施策 ~LET コレに`結付けられている~node$用の`観測-可能な施策$ ◎ Let policy be the observable policy for this PermissionsPolicy object’s associated node.
- ~EACH( `~support済み特能$ %特能 ) に対し ⇒ ~IF[ %施策 により, %特能 は %生成元 用に許容される ] ⇒ %結果 に %特能 を`付加する$set ◎ For each supported feature feature: • If feature is allowed by policy for origin, append feature to result.
- ~RET %結果 ◎ return result
`getAllowlistForFeature(feature)@m ~method~手続きは: ◎ The getAllowlistForFeature(feature) method must run the following steps:
- %結果 ~SET 空~list ◎ Set result to an empty list
- %生成元 ~LET コレの`既定の生成元$ ◎ Let origin be this PermissionsPolicy object’s default origin.
- %施策 ~LET コレに`結付けられている~node$用の`観測-可能な施策$ ◎ Let policy be the observable policy for this PermissionsPolicy object’s associated node.
- ~IF[ %施策 により, %特能 は %生成元 用には許容されない ] ⇒ ~RET %結果 ◎ If feature is not allowed in policy for origin, return result
- %許容list ~LET %施策 の宣言-済み施策[ %特能 ] ◎ Let allowlist be policy’s declared policy[feature]
- ~IF[ %許容list ~EQ `全~生成元$i ] ⇒ %結果 に`全~生成元$iを`付加する$set ◎ If allowlist is the special value *, append "*" to result
- ~ELSE ⇒ %許容list 内の ~EACH( %生成元 ) に対し ⇒ %結果 に次の結果を`付加する$set ⇒ `生成元を直列化する$( %生成元 ) ◎ Otherwise, for each origin in allowlist: • Append the serialization of origin to result
- ~RET %結果 ◎ Return result.
所与の[ `要素$/`文書$ ]【!Node】 %~node 用の `観測-可能な施策@ は、[ %~node の`~node~navigable$【!the navigable represented by that Node】内の施策についての情報のうち, %~node の`~node文書$【!現在の文書】から可視なもの ]を包含する`許可~施策$であり, 次を走らせた結果になる: ◎ The observable policy for any Node is a permissions policy, which contains the information about the policy in the navigable represented by that Node which is visible from the current document. ◎ ↓ To get the observable policy for a Document document, return document’s permissions policy. ◎ To get the observable policy for an Element node, run the following steps:
- ~IF[ %~node は`文書$である ] ⇒ ~RET %~node の`許可~施策$doc ◎ ↑
- %継承した施策 ~LET 新たな有順序~map ◎ Let inherited policy be a new ordered map.
- %宣言-済み施策 ~LET 新たな有順序~map ◎ Let declared policy be a new ordered map.
- ~EACH( `~support済み特能$ %特能 ) に対し ⇒ %継承した施策[ %特能 ] ~SET `生成元に属する容器~内の特能~用に継承される施策を定義する$( %特能, %~node, %~node 用に`宣言された生成元$ ) ◎ For each supported feature feature: • Let isInherited be the result of running Define an inherited policy for feature in container at origin on feature, node and node’s declared origin. • Set inherited policy[feature] to isInherited.
- ~RET 次のようにされた新たな`許可~施策$ ⇒# `継承した施策$ ~SET %継承した施策, `宣言-済み施策$ ~SET %宣言-済み施策 ◎ Return a new permissions policy with inherited policy inherited policy and declared policy declared policy.
所与の ( `要素$ %要素 ) 用に `宣言された生成元@ を取得するときは、 次を走らす: ◎ To get the declared origin for an Element node, run the following steps:
- %文書 ~LET %要素 の`~node文書$ ◎ ↓
- ~IF[ `閲覧~文脈~sandbox化( 生成元 )~flag$ ~IN %文書 にて`作動中の~sandbox法~flag集合$ ] ⇒ ~RET 一意かつ不透明な生成元 ◎ If node’s node document’s sandboxed origin browsing context flag is set, then return a unique opaque origin.
- ~IF[ %要素 は `sandbox$aF 属性を有していて,その値は `allow-same-origin^v ~keywordを包含しない ] ⇒ ~RET 一意かつ不透明な生成元 ◎ If node’s sandbox attribute is set, and does not contain the allow-same-origin keyword, then return a unique opaque origin.
- ~IF[ %要素 は `srcdoc$aF 属性を有する ] ⇒ ~RET %文書 の`生成元$doc ◎ If node’s srcdoc attribute is set, then return node’s node document’s origin.
-
~IF[ %要素 は `src^a 属性を有する ]: ◎ If node’s src attribute is set:
- %~URL ~LET `相対的に~URL構文解析する$( %要素 の `src$aF 属性の値, %文書 ) ◎ Let url be the result of parsing node’s src attribute, relative to node’s node document.
- ~IF[ %~URL ~NEQ `失敗^i ] ⇒ ~RET %~URL の`生成元$url ◎ If url is not failure, return url’s origin.
- ~RET %文書 の`生成元$doc ◎ Return node’s node document’s origin.
注記: `宣言された生成元$の概念は、[ ~pageが~frameの中へ読込もうと意図している文書 ]の生成元を表現することが意図されている。 これは、 一例として,[ `sandbox^a / `srcdoc^a ]属性を~supportしない~browserは、[ 宣言された生成元を算出するときには, その属性を織り込まないべきである ]ことを意味する。 ◎ The declared origin concept is intended to represent the origin of the document which the embedding page intends to load into a frame. This means, for instance, that if the browser does not support the sandbox or srcdoc attributes, it should not take those attributes into account when computing the declared origin.
8. 報告-法
`許可~施策~違反~報告@ は、[ `文書$内のある挙動が,許可~施策に`違反-$している ]ことを指示する。 [ その施策に `違反-@ するとは何を意味するのか定義すること ],および[ そのような`違反$は,いつ生じたとされるか決定する方法 ]は、 個々の`施策により制御される特能$の仕様に委ねられる。 ◎ Permissions policy violation reports indicate that some behavior of the Document has violated a permissions policy. It is up to the specification of each individual policy-controlled feature to define what it means to violate that policy, and how to determine when such a violation has occurred.
`許可~施策~違反~報告$の`報告~種別$は、 `permissions-policy-violation^l とする。 ◎ Permissions policy violation reports have the report type "permissions-policy-violation".
`許可~施策~違反~報告$は、 `報告用~観測器から可視$になるとする。 ◎ Permissions policy violation reports are visible to ReportingObservers.
[`Exposed$=Window] interface `PermissionsPolicyViolationReportBody@I : `ReportBody$I { readonly attribute `DOMString$ `featureId$m; readonly attribute `DOMString$? `sourceFile$m; readonly attribute `long$? `lineNumber$m; readonly attribute `long$? `columnNumber$m; readonly attribute `DOMString$ `disposition$m; };
`許可~施策~違反~報告$の`本体$rPは、 ~JSにおいては,次の~fieldを包含する `PermissionsPolicyViolationReportBody$I により表現される: ◎ A permissions policy violation report’s body, represented in JavaScript by PermissionsPolicyViolationReportBody, contains the following fields:
- `featureId@m
- 施策に`違反-$した`特能$を識別する文字列。 この文字列は、 関係する報告を~group化する/数えるときに利用できる。 ◎ featureId: The string identifying the policy-controlled feature whose policy has been violated. This string can be used for grouping and counting related reports.
- `sourceFile@m
- 既知ならば,`違反$が生じた~file — 他の場合は ~NULL 。 ◎ sourceFile: If known, the file where the violation occured, or null otherwise.
- `lineNumber@m
- 既知ならば, `sourceFile$m において`違反$が生じた箇所の行番号 — 他の場合は ~NULL 。 ◎ lineNumber: If known, the line number in sourceFile where the violation occured, or null otherwise.
- `columnNumber@m
- 既知ならば, `sourceFile$m において`違反$が生じた箇所の列番号 — 他の場合は ~NULL 。 ◎ columnNumber: If known, the column number in sourceFile where the violation occured, or null otherwise.
- `disposition@m
- `違反-$された許可~施策は、 この事例にて施行されたかどうかを指示する文字列。 施策は施行されたなら `enforce^l に設定される。 `違反$は この報告を生成させるだけであったなら `report^l に設定される (~UAは、 違反に呼応してそれ以上の動作はとらなかった)。 ◎ disposition: A string indicating whether the violated permissions policy was enforced in this case. disposition will be set to "enforce" if the policy was enforced, or "report" if the violation resulted only in this report being generated (with no further action taken by the user agent in response to the violation).
- 注記: 現時点では、 報告のみ行う~modeを可能化する仕組みは無いので、 これは,常に `enforce^l に設定されることになる。 ◎ Note: There is currently no mechanism in place for enabling report-only mode, so disposition will always be set to "enforce".
9. 各種~algo
9.1. `応答~施策を処理する@
この~algoは、 所与の ( `応答$ %応答, `生成元$ %生成元 ) に対し,`宣言-済み施策$を返す: ◎ Given a response (response) and an origin (origin), this algorithm returns a declared permissions policy.
- %構文解析した~header ~LET %応答 の`~header~list$rsから`有構造~field値を取得する$( `Permissions-Policy$h, `辞書^i ) ◎ Let parsed header be the result of executing get a structured field value given "Permissions-Policy" and "dictionary" from response’s header list.
- ~IF[ %構文解析した~header ~EQ ~NULL ] ⇒ ~RET 新たな`有順序~map$ 【原文は,この場合に何も返していないが、空な`宣言-済み施策$を表現する値を返すべきであろう。】 ◎ If parsed header is null, abort these steps.
- ~RET `辞書と生成元から施策を構築する$( %構文解析した~header, %生成元 ) ◎ Let policy be the result of executing Construct policy from dictionary and origin on parsed header and origin. ◎ Return policy.
9.2. `辞書と生成元から施策を構築する@
この~algoは、 所与の ( `有順序~map$ %辞書, `生成元$ %生成元 ) に対し,`宣言-済み施策$を返す: ◎ Given an ordered map (dictionary) and an origin (origin), this algorithm will return a declared permissions policy.
- %施策 ~LET 新たな`有順序~map$ ◎ Let policy be an empty ordered map.
-
%辞書 を成す ~EACH( %特能~名 → %値 ) に対し: ◎ For each feature-name → value of dictionary:
- %特能 ~LET [ %特能~名 は ある`施策により制御される特能$を識別するものであって,~UAは それを認識するならば その特能/ ~ELSE_ ε ] ◎ If feature-name does not identify any recognized policy-controlled feature, then continue. ◎ Let feature be the policy-controlled feature identified by feature-name.
- ~IF[ %特能 ~EQ ε ] ⇒ ~CONTINUE ◎ ↑
-
%施策[ %特能 ] ~SET [ 次の手続きを走らせた結果 ]として与えられる新たな`許容list$: ◎ Let allowlist be a new allowlist.
- ~IF[ %値 ~EQ `全~生成元$i ] ⇒ ~RET `全~生成元$i ◎ If value is the token *, or\
- ~IF[ %値 は`~list$である ]~AND[ `全~生成元$i ~IN %値 ] ⇒ ~RET `全~生成元$i ◎ if value is a list which contains the token *, set allowlist to the special value *. ◎ Otherwise:
- %許容list ~SET 新たな`有順序~集合$ ◎ Set allowlist to an new ordered set.
- ~IF[ %値 ~EQ `self$P ] ⇒# %許容list に %生成元 を`付加する$set; ~RET %許容list ◎ If value is the token self, append origin to allowlist.
- ~IF[ %値 は`~list$でない ] ⇒ ~RET %許容list ◎ If value is a list, then\
-
%値 を成す ~EACH( %~item ) に対し: ◎ for each element in value:
- ~IF[ %~item ~EQ `self$P ] ⇒# %許容list に %生成元 を`付加する$set; ~CONTINUE ◎ If element is the token self, append origin to allowlist. ◎ Otherwise,\
- %結果 ~LET `~URL構文解析する$( %~item ) ◎ let result be the result of executing the URL parser on element.
- ~IF[ %結果 ~EQ `失敗^i ] ⇒ ~CONTINUE ◎ If result is not failure:
- %~target ~LET %結果 の`生成元$url ◎ Let target be the origin of result.
- ~IF[ %~target は`不透明な生成元$でない ] ⇒ %許容list に %~target を`付加する$set ◎ If target is not an opaque origin, append target to allowlist.
- ~RET %許容list ◎ Set policy[feature] to allowlist.
- ~RET %施策 ◎ Return policy.
9.3. `施策~指令を構文解析する@
この~algoは、 所与の ( 文字列 %値, `生成元$ %容器~生成元, `生成元$ %~target生成元(省略時は ε ) ) に対し,`施策~指令$を返す: ◎ Given a string (value), an origin (container origin), and an optional origin (target origin), this algorithm returns a policy directive.
- %指令 ~LET 新たな`有順序~map$ ◎ Let directive be an empty ordered map.
-
`区切子で厳密に分割する$( %値, `003B^U (;) ) の結果を成す ~EACH( %直列形の宣言 ) に対し: ◎ For each serialized-declaration returned by strictly splitting value on the delimiter U+003B (;):
- %~token~list ~LET `~ASCII空白で分割する$( %直列形の宣言 ) ◎ Let tokens be the result of splitting serialized-declaration on ASCII whitespace.
- ~IF[ %~token~list は空である ] ⇒ ~CONTINUE ◎ If tokens is an empty list, then continue.
- %特能~名 ~LET %~token~list[0] ◎ Let feature-name be the first element of tokens.
- %特能 ~LET %特能~名 により識別される`~support済み特能$が[ 在るならば それ / 無いならば ε ] ◎ If feature-name does not identify any recognized policy-controlled feature, then continue.
- ~IF[ %特能 ~EQ ε ] ⇒ ~CONTINUE ◎ Let feature be the policy-controlled feature identified by feature-name.
- %~target~list ~LET %~token~list から最初の~itemを除去して得られる~list ◎ Let targetlist be the remaining elements, if any, of tokens.
- %許容list ~LET `全~生成元$i ◎ ↓
-
~IF[ `全~生成元$i ~NIN %~target~list ] ◎ Let allowlist be a new allowlist. ◎ If any element of targetlist is the string "*", set allowlist to the special value *. ◎ Otherwise:
- %許容list ~SET 新たな`有順序~集合$ ◎ Set allowlist to an new ordered set.
- ~IF[ %~target~list は空である ]~AND[ %~target生成元 ~NEQ ε ] ⇒ %許容list に %~target生成元 を`付加する$set ◎ If targetlist is empty and target origin is given, append target origin to allowlist.
-
%~target~list 内の ~EACH( %~target ) に対し: ◎ For each element in targetlist:
- ~IF[ %~target は `'self'^l に`~ASCII大小無視$で合致する ] ⇒ %~target ~SET %容器~生成元 ◎ If element is an ASCII case-insensitive match for "'self'", let result be container origin.
- ~ELIF[ %~target は `'src'^l に`~ASCII大小無視$で合致する ]~AND[ %~target生成元 ~NEQ ε ] ⇒ %~target ~SET %~target生成元 ◎ If target origin is given, and element is an ASCII case-insensitive match for "'src'", let result be target origin.
-
~ELSE:
- %~target ~SET `~URL構文解析する$( %~target ) ◎ Otherwise, let result be the result of executing the URL parser on element.
- ~IF[ %~target ~EQ `失敗^i ] ⇒ ~CONTINUE ◎ If result is not failure:
- %~target ~SET %~target の`生成元$url ◎ Let target be the origin of result.
- ~IF[ %~target は`不透明な生成元$でない ] ⇒ %許容list に %~target を`付加する$set ◎ If target is not an opaque origin, append target to allowlist.
- %指令[ %特能 ] ~SET %許容list ◎ Set directive[feature] to allowlist.
- ~RET %指令 ◎ Return directive
9.4. `許可~施策~属性を処理する@
この~algoは、 所与の ( 要素 %要素 ) に対し,`容器~施策$を返す(空にもなり得る): ◎ Given an element (element), this algorithm returns a container policy, which may be empty.
- %容器~施策 ~LET `施策~指令を構文解析する$( %要素 の `allow$aF 属性の値, %要素 の`~node文書$の`生成元$doc, %要素 用に`宣言された生成元$ ) ◎ Let container policy be the result of running Parse policy directive on the value of element’s allow attribute, with container origin set to the origin of element’s node document, and target origin set to element’s declared origin.
- ~IF[ %要素 は `iframe$e 要素でない ] ⇒ ~RET %容器~施策 【 `allow^a 属性が定義されているのは `iframe^e しかないので、この記述はおかしい。】 ◎ If element is an iframe element:
- ~IF[ %要素 は `allowfullscreen$aF 属性を有する ]~AND[ %容器~施策[ `fullscreen^l ] ~EQ ε ] ⇒ %容器~施策[ `fullscreen^l ] ~SET `全~生成元$i ◎ If element’s allowfullscreen attribute is specified, and container policy does not contain an allowlist for fullscreen: • Let declaration be a new declaration for fullscreen, whose allowlist is the special value *. • Add declaration to container policy.
- ~RET %容器~施策 ◎ Return container policy.
9.6. `応答から~navigable用の許可~施策を作成する@
この~algoは、 所与の ( [ ~NULL / `~navigable容器$ ] %容器, `生成元$ %生成元, `応答$ %応答 ) に対し,新たな`許可~施策$を返す: ◎ Given null or a navigable container (container), an origin (origin), and a response (response), this algorithm returns a new Permissions Policy.
- %施策 ~LET `~navigable用の許可~施策を作成する$( %容器, %生成元 ) ◎ Let policy be the result of running Create a Permissions Policy for a navigable given container and origin.
- %d ~LET `応答~施策を処理する$( %応答, %生成元 ) ◎ Let d be the result of running Process response policy on response and origin.
- %d を成す ~EACH( %特能 → %許容list ) に対し ⇒ ~IF[ %施策 が`継承した施策$[ %特能 ] ~EQ ~T ] ⇒ %施策 の`宣言-済み施策$[ %特能 ] ~SET %許容list ◎ For each feature → allowlist of d: • If policy’s inherited policy[feature] is true, then set policy’s declared policy[feature] to allowlist.
- ~RET %施策 ◎ Return policy.
9.7. `生成元に属する容器~内の特能~用に継承される施策を定義する@
この~algoは、 所与の ( `特能$ %特能, [ ~NULL / `~navigable容器$ ] %容器, %容器 内の文書~用の`生成元$ %生成元 ) に対し, %容器 が %特能 用に`継承した施策$を返す: ◎ Given a feature (feature), null or a navigable container (container), and an origin for a document in that container (origin), this algorithm returns the inherited policy for that feature.
- ~IF[ %容器 ~EQ ~NULL ] ⇒ ~RET `可能化される^i ◎ If container is null, return "Enabled".
- %文書 ~LET %容器 の`~node文書$ ◎ ↓
- ~IF[ `文書~内の特能は生成元~用に可能化されるか?$( %特能, %文書, %文書 の`生成元$doc ) ~EQ `不能化される^i ] ⇒ ~RET `不能化される^i ◎ If the result of executing Is feature enabled in document for origin? on feature, container’s node document, and container’s node document''s origin is "Disabled", return "Disabled".
- ~IF[ `文書~内の特能は生成元~用に可能化されるか?$( %特能, %文書, %生成元 ) ~EQ `不能化される^i ] ⇒ ~RET `不能化される^i ◎ If the result of executing Is feature enabled in document for origin? on feature, container’s node document, and origin is "Disabled", return "Disabled".
- %容器~施策 ~LET `許可~施策~属性を処理する$( %容器 ) ◎ Let container policy be the result of running Process permissions policy attributes on container.
-
~IF[ %容器~施策[ %特能 ] ~NEQ ε ]: ◎ If feature is a key in container policy:
- ~IF[ `許容listは生成元に合致する$( %容器~施策[ %特能 ], %生成元 ) ~EQ ~T ] ⇒ ~RET `可能化される^i ◎ If the allowlist for feature in container policy matches origin, return "Enabled".
- ~RET `不能化される^i ◎ Otherwise return "Disabled".
- ~IF[ %特能 の`既定の許容list$ ~EQ `全~生成元$i ] ⇒ ~RET `可能化される^i ◎ If feature’s default allowlist is *, return "Enabled".
- ~IF[ %特能 の`既定の許容list$ ~EQ `'self'^l ]~AND[ ( %生成元, %容器 の`~node文書$の`生成元$doc ) は`同一-生成元$である ] ⇒ ~RET `可能化される^i ◎ If feature’s default allowlist is 'self', and origin is same origin with container’s node document’s origin, return "Enabled".
- ~RET `不能化される^i ◎ Otherwise return "Disabled".
9.8. `文書~内の特能は生成元~用に可能化されるか?@
この~algoは、 所与の ( 特能 %特能, `文書$ %文書, `生成元$ %生成元 ) に対し,[ %特能 は不能化されるべきと見なされるならば `不能化される^i / ~ELSE_ `可能化される^i ]を返す: ◎ Given a feature (feature), a Document object (document), and an origin (origin), this algorithm returns "Disabled" if feature should be considered disabled, and "Enabled" otherwise.
- %施策 ~LET %文書 の`許可~施策$ ◎ Let policy be document’s Permissions Policy
- ~IF[ %施策 が`継承した施策$[ %特能 ] ~EQ `不能化される^i ] ⇒ ~RET `不能化される^i ◎ If policy’s inherited policy for feature is Disabled, return "Disabled".
-
~IF[ %施策 の`宣言-済み施策$[ %特能 ] ~NEQ ε ]: ◎ If feature is present in policy’s declared policy:
- ~IF[ `許容listは生成元に合致する$( %施策 の`宣言-済み施策$[ %特能 ], %生成元 ) ~EQ ~T ] ⇒ ~RET `可能化される^i ◎ If the allowlist for feature in policy’s declared policy matches origin, then return "Enabled".
- ~RET `不能化される^i ◎ Otherwise return "Disabled".
- ~IF[ %特能 の`既定の許容list$ ~EQ `全~生成元$i ] ⇒ ~RET `可能化される^i ◎ If feature’s default allowlist is *, return "Enabled".
- ~IF[ %特能 の`既定の許容list$ ~EQ `'self'^l ]~AND[ ( %生成元, %文書 の`生成元$doc ) は`同一-生成元$である ] ⇒ ~RET `可能化される^i ◎ If feature’s default allowlist is 'self', and origin is same origin with document’s origin, return "Enabled".
- ~RET `不能化される^i ◎ Return "Disabled".
9.9. `設定群~上で許可~施策の違反~用に報告を生成する@
この~algoは、 所与の ( `特能$ %特能, `環境~設定群~obj$ %設定群, 文字列 %~group (省略時は `default^l ) ) に対し,%特能 用の施策に対する`違反$についての`報告$を生成する: ◎ Given a feature (feature), an environment settings object (settings), and an optional string (group), this algorithm generates a report about the violation of the policy for feature.
- %本体 ~LET 次のように初期化された新たな `PermissionsPolicyViolationReportBody$I ⇒# `featureId$m ~SET %特能 の文字列~表現, `sourceFile$m ~SET ~NULL, `lineNumber$m ~SET ~NULL, `columnNumber$m ~SET ~NULL, `disposition$m ~SET `enforce^l ◎ Let body be a new PermissionsPolicyViolationReportBody, initialized as follows: ◎ featureId • feature’s string representation. sourceFile • null lineNumber • null columnNumber • null disposition • "enforce"
- ~IF[ ~UAは現在~scriptを実行している ]~AND[ %設定群 から~source~fileの[ ~URL, 行番号, 列番号 ]を抽出できる† ] ⇒ それに則って, %本体 の[ `sourceFile$m, `lineNumber$m, `columnNumber$m ]を設定する 【† ~URLのみ抽出できる場合もあるかもしれない。その場合、 `sourceFile^m のみ設定されることになりそうだが,何もしないようにも読める。】 ◎ If the user agent is currently executing script, and can extract the source file’s URL, line number, and column number from settings, then set body’s sourceFile, lineNumber, and columnNumber accordingly.
- `報告を生成して~queueする$( %設定群 の`大域~obj$enV, `permissions-policy-violation^l, %~group, %本体 ) ◎ ↑↑If group is omitted, set group to "default". ◎ Execute generate and queue a report with body, "permissions-policy-violation", group, and settings.
注記: 許可~施策が`違反-$されたときには、 この~algoが~callされるべきである。 ◎ Note: This algorithm should be called when a permissions policy has been violated.
9.10. `要請には特能の利用は許容されるべきか?@
この~algoは、 所与の ( 特能 %特能, `要請$ %要請 ) に対し,[ %要請 に %特能 の利用は許容されるべきならば ~T / ~ELSE_ ~F ]を返す: ◎ Given a feature (feature) and a request (request), this algorithm returns true if the request should be allowed to use feature, and false otherwise.
- %~window ~SET %要請 の`~window$rq ◎ Set window to request’s window.
-
~IF[ %~window は `Window$I でない ] ⇒ ~RET ~F ◎ If window is not a Window, return false.
`Window^I でない文脈 ( `WorkerGlobalScope$I / `WorkletGlobalScope$I ) の中の許可~施策については、 `課題 #207@https://github.com/w3c/webappsec-permissions-policy/issues/207$ にて模索中にある。 それが解決されたなら、[ これらの文脈の中で起動される~fetchに,施策により制御される特能の利用を許容する ]よう,この~algoを更新することになる。 `解決されるまでは^em、 施策により制御される特能 (例: 第三者-主体に `Client Hints^en 【`参照@~HTTPch#client-hint$】を送信するなど) は,これらの文脈においては許容されない。 ◎ Permissions Policy within non-Window contexts (WorkerGlobalScope or WorkletGlobalScope) is being figured out in issue #207. After that’s resolved, update this algorithm to allow fetches initiated within these contexts to use policy-controlled features. Until that’s resolved, disallow all policy-controlled features (e.g., sending Client Hints to third parties) in these contexts.
- %文書 ~SET %~window に`結付けられている文書$ ◎ Set document to window’s associated Document.
- %生成元 ~LET %要請 の`生成元$rq ◎ Let origin be request’s origin.
- ~RET [ 次が満たされるならば ~T / ~ELSE_ ~F ] ⇒ `文書~内の特能は生成元~用に可能化されるか?$( %特能, %文書, %生成元 ) ~EQ `可能化される^i ◎ Let result be the result of executing Is feature enabled in document for origin? on feature, document, and origin. ◎ If result is "Enabled", return true. ◎ Otherwise, return false.
10. ~IANA 考慮点
恒久的~message~header~registryは、 次の登録で更新されるべきである `RFC3864$r : ◎ The permanent message header field registry should be updated with the following registration [RFC3864]:
- ~header名
- `Permissions-Policy^h
- 適用-可能な~protocol
- http
- 位置付け
- 標準
- 著作者/変更~制御者
- W3C
- 仕様~文書
- `Permissions Policy@~TR/permissions-policy-1/$cite 【この仕様】
11. ~privacyと~security
この仕様は、 埋込まれる~page上で施行することになる施策を設定するための仕組みを標準~化する。 `iframe^e 要素の `sandbox$aF 属性と類似に、 これは,埋込まれる~pageから許可が明示されなくとも行える。 それは、 すでに公表された~web~site内に存在している特能の挙動を変更できることを意味する — 別の文書~内で、 それらの~pageを,適切な容器~施策を伴わせて埋込むことにより。 ◎ This specification standardizes a mechanism for an embedding page to set a policy which will be enforced on an embedded page. Similar to iframe sandbox, this can be done without the express permission of the embedded page, which means that behaviors of existing features can be changed in published web sites, by embedding them in another document with an appropriate container policy.
そのようなわけで、 最も重大な ~privacy/~security 上の懸念は: ◎ As such, the biggest privacy and security concerns are:
- 非同一-生成元 下位frame内の挙動が,それを埋込んでいる側に公開されること ◎ Exposure of behavior in a cross-origin subframe to its embedder
- 埋込んだ側が制御することによる、 下位frameにおける挙動の予想外の変化 ◎ Unanticipated behavior changes in subframes controlled by the embedder
これらの懸念は、 すでにある程度~web~platformに在る。 この仕様は、 少なくとも それを無用に悪化させないよう試みる。 ◎ To a degree, these concerns are already present in the web platform, and this specification attempts to at least not make them needlessly worse.
個々の特能の設計も,~securityと~privacyの課題をもたらし得るので、 この仕様と統合するときには,~careされなければナラナイ。 この節は、 どの種類の挙動がそのような課題をもたらし得るかについて,いくつかの指導を供することを試みる。 ◎ Security and privacy issues may also be caused by the design of individual features, so care must be taken when integrating with this specification. This section attempts to provide some guidance as to what kinds of behaviors could cause such issues.
11.1. 埋込まれた非同一-生成元の挙動の公開
特能は、[ ~frame化された文書における施策の`違反$は、 他の~frame内の文書からは観測-可能にならない ]ように,設計されるべきである。 一例として、 仮に,ある特能が[ 施策により不能化されている下で利用されたときは、 当の~frameを埋込んでいる文書に向けて~eventを発火させる ]となると、 埋込まれた文書の状態についての情報を抽出することにも利用できることになる。 一例として,[ その特能は,利用者が~siteに~log-inしている間に限り利用される ]ことが既知である場合、 埋込んだ側は — その特能を当の~frameに対し不能化した上で,結果の~eventを~listenすることにより — 利用者が~log-inしているかどうか決定することもできる。 ◎ Features should be designed such that a violation of the policy in a framed document is not observable by documents in other frames. For instance, a hypothetical feature which caused a event to be fired in the embedding document if it is used while disabled by policy, could be used to extract information about the state of an embedded document. If the feature is known only to be used while a user is logged in to the site, for instance, then the embedder could disable that feature for the frame, and then listen for the resulting events to determine whether or not the user is logged in.
自己検分~APIは、[ 下位frameの施策について、 埋込んでいる文書から,すでに演繹できる情報 ]のみを示すように設計されている。 この`観測-可能な施策$は、 ~frame化された文書に伴って送達された どの~HTTP~headerからも影響されない。 加えて、 ~frame自身が他へ~navigateされても — その先が,異なる施策が適用される異なる生成元であっても — 変化しない。 `観測-可能な施策$を更新させるのは、 `iframe^e 要素の `src$aF 属性を設定して生じる~naviに限られる。 ◎ The introspection API is designed to only show information about a subframe’s policy which could already be deduced by the embedding document. This observable policy is not affected by any HTTP headers delivered with the framed document, and does not change when the frame navigates itself, even if such navigation is to a different origin, where a different policy applies. Only navigations caused by setting the src attribute of the <iframe> element will cause the observable policy to be updated.
11.2. 挙動の予想外の変化
許可~施策の仕組みは、[ ある下位frameが読込まれる時点で,[ その~frame内で,どの特能が可用になるか, ならないか ]を制御する能 ]を,文書に是認する。 当の特能が,~web~platformに長期に存在していた挙動を表現しているならば、 このことは[ ~web上に公表された既存の内容において,特定0の~APIが失敗し得る ]ことを意味する (内容がそれを予期することなく書かれたならば)。 ◎ The Permissions Policy mechanism grants a document the ability to control which features will and will not be availble in a subframe at the time it is loaded. When a feature represents an existing, long-standing behavior of the web platform, this may mean that existing published content on the web was not written with the expectation that a particular API could fail.
(不自然だが)実用的な例として、[ 利用者が~pageに~accessするに足る特権を有するかどうか ]を,同期的 `XMLHttpRequest$I を利用して決定している文書を考える: ◎ As a practical (though contrived) example, consider a document which uses synchronous XMLHttpRequest to determine whether a user has sufficient privileges to access the page:
<!DOCTYPE html> <h1>Welcome to SecureCorp!</h1> <script> var %req = new XMLHttpRequest(); %req.open("GET", "/api/security_check.json", false); %req.send(); if (%req.response == "untrusted user") { /* 利用者は~log-inしていない — 安全な~pageへ~redirectする ◎ User is not logged in; redirect to a safe page */ location.href = "/security_check_failed.html"; } </script> <!-- ~pageは、 利用者が~log-inした前提の下で継続する ◎ Page continues with assumption that user is logged in -->
この文書がある~pageに埋込まれ,その~pageが `sync-xhr^l 特能を不能化した場合、 `XMLHttpRequest.open()^m の~callは失敗して,~security検査は迂回されることになる。 ◎ If this document is embedded by a page which disables the "sync-xhr" feature, the call to XMLHttpRequest.open() would fail, and the security check would be bypassed.
~web上では、 この類の挙動の強制-法はすでにアリなことに注意。 特能には、 `iframe^e には許容されず,~top-level文書~内に限り許容されるものもある。 また, `iframe^e ~sandbox法は、 類似な仕方で,~frameを — それが依存し得る特能に~accessすることなく — 埋込むときに利用できる。 ◎ Note that this sort of behavior forcing is already possible on the web: some features are only allowed in top-level documents, and not in any iframes, and iframe sandboxing can be used in a similar way to embed a frame without access to features which it may be depending on.
一般に,この懸念を軽減するには、 2 つの仕方がある: ◎ In general, this concern is mitigated in two ways:
- 脆弱な~pageは、 `X-Frame-Options^h ~HTTP~headerを伴わせて ~serveできる — そうすれば、 攻撃者が~frame化するのは許容されなくなるので。 ◎ The vulnerable page may be served with an X-Frame-Options HTTP header which does not allow it to be framed by an attacker.
- ~siteは、 ~APIや挙動を利用しようと試みる前に,それが可用かどうかを特能~検出を利用して決定した上で、 ~callした~APIから[ 返された~error/投出された例外 ]を取扱うべきである。 ◎ Sites should use feature detection to determine whether an API or behavior is available before attempting to use it, and should handle any documented errors returned or exceptions thrown by the APIs they call.
- 特能~検出がアリでない事例では、 新たな~web内容は[ `PermissionsPolicy$I ~objを利用して,現在~施行されている許可~施策を検分した上で、 それに則って挙動や~UIを調整する ]ように書ける。 ◎ In the case where feature detection is not possible, new web content can be written to use the policy object to inspect the permissions policy which is currently enforced, and adjust behaviour or user interface accordingly.
自身による特能を この仕様と統合している策定者は、[ 当の特能が不能化されている下で,文書がそれを利用しようと試みたとき、 それが いつどのように失敗することになるか ]を裁定できる。 策定者は、 既存の失敗~mode【既存の例外~名など】が存在するならば,それを用立てようと試みるべきである — そうすれば、 そのような失敗をすでに正しく取扱っている既存の内容への~~影響は抑えられるので。 ◎ Authors integrating their features with Permissions Policy can decide when and how the feature will fail when a document attempts to use it while it is disabled. Authors should attempt to make use of existing failure modes, when they exist, to increase the chance that existing content will already be correctly handling such failures.
11.3. 埋込んでいる側の施策の公開
ある~pageが非同一-生成元~pageを埋込んでいるとき — 埋込んだ側が,埋込まれた側の挙動について推定できる情報を制限するよう~careされていたとしても — 局面によっては、 埋込まれた側が,埋込んだ側の情報について推定することも — [ 自身に対し,埋込んだ側が施行した施策 ]を精査することにより — アリになり得る。 ◎ Care has been taken to limit the information which an page can infer about the behavior of cross-origin pages which it embeds. It may be possible in some scenarios however, for the embedded page to infer information about its embedder, by examining the policy which the embedder has enforced on it.
これは既存の `document.fullscreenEnabled$m に類似する。 それは、 埋込まれた側の文書が[ 埋込んだ側は、 埋込まれた側に~Fullscreen~APIを利用する能を是認したかどうか ]を推定するために利用できる。 これが ある種の事例 — 一例として,利用者が埋込んだ側の~siteに~log-inしたとき — に限り是認される場合、 埋込まれた側の~siteは,埋込んだ側の状態について何かを知り得るようになる。 ◎ This is similar to the existing document.fullscreenEnabled property, which can be used by the embedded document to infer whether its embedder has granted it the ability to use the Fullscreen API. If this is only granted in certain cases — when the user is logged in to the embedding site, for instance — then the embedded site can learn something about the state of its embedder.
12. 変更~log
- 最初の公な草案からの変更点: ◎ 12.1. Changes since FPWD
- 文書が作成される前に 特能~施策を作成する新たな~algoを公開した。 ( `324$pull ) ◎ Expose new algorithms to create a Feature Policy before document is created. Link
- もはや必要でない~algoを除去した。 ( `325$pull ) ◎ Remove algorithms no longer needed. Link
- `同じ生成元~domain$の検査を`同一-生成元$のそれに変更した。 ( `326$pull ) ◎ Change same-origin-domain check to same-origin. Link
- ~headerと属性の組合nにおける意味論を ~OR から ~AND に変更した。 ( `378$pull ) ◎ Change Header and attribute combination from OR to AND semantics. Link
- “特能~施策” を “許可~施策” に改称した。 ( `379$pull ) ◎ Rename to "Permissions Policy". Link
- `Permissions-Policy$h を有構造~headerとして定義した。 ( `383$pull ) ◎ Define "Permissions-Policy" as a structured header. Link
- 編集上の修正点。 ◎ Editorial fixes.
- `allowpaymentrequest^a 属性を除去した — Payment Request API, HTML にて非推奨にされたことに因り。 ( `402$pull ) ◎ The allowpaymentrequest attribute was removed due to deprecation by Payment Request API and HTML. Link