1. この文書の視野
~INFORMATIVEこの文書は、~APIが~Web~platform上の強力な特色機能を利用する許可のための~model, およびそのような特色機能の現在の許可~状態を照会する~APIを指定する。 ◎ This document specifies a model for permissions to use powerful features on the Web platform and an API to query the current permission state of those features.
現在の~web~APIには、許可の取り扱いが異なるものがいくつかある。 例えば `notifications$r ~APIは、開発者が明示的に許可を要請して,許可~状態0を検査できるようにする。 ~APIを利用しようと試行したときに限り,状態0を~web頁に公開するものもある。 例えば `geolocation-API$r は、開発者が前もって検査するのを許容することなく,許可が是認されていなければ失敗する。 ◎ Current Web APIs have different ways to deal with permissions. For example, the [notifications] API allows developers to request a permission and check the permission status explicitly. Others expose the status to web pages when they try to use the API, like the [geolocation-API] which fails if the permission was not granted without allowing the developer to check beforehand.
`query()$m 関数は、許可~promptがいつ示されるかを制御する~toolを開発者に供する。 ◎ The query() function provides a tool for developers to control when permission prompts are shown.
この文書に述べる解決策は,拡張できるように~~意図されているが、~web~platformにて可用な 現在の/将来の 許可すべてに適用-可能になるとは期待されてはいない。 許可~modelを孕む仕様を策定している Working Group は、その~modelが この文書に記述される~modelに収まらないときには, issue を~~提出して そのことを編集者に~~伝えるべきである。 ◎ The solution described in this document is meant to be extensible, but isn’t expected to be applicable to all the current and future permissions available in the web platform. Working Groups that are creating specifications whose permission model doesn’t fit in the model described in this document should contact the editors by filing an issue.
2. ~privacy上の考慮点
~INFORMATIVEある敵対者は、末端利用者に対応する “指紋” を作成するための要素として,`許可~状態$も利用できる。 敵対者は,実際に~APIを用いてすでに許可の状態を決定できるが、それは,末端利用者に許可~要請~UIを呈示させることが多い(その許可が すでに是認されている( `granted$pS )場合は除き)。 したがって,この~APIは、~web~siteに新たな指紋収集~情報を公開することはないが,敵対者にとって この情報への目立たない~accessを容易にする。 したがって,実装には、`許可~状態$を照会するのを(大域的にまたは選択的に)阻止する選択肢を,利用者に~~供することが奨励される。 ◎ An adversary could use a permission state as an element in creating a "fingerprint" corresponding to an end-user. Although an adversary can already determine the state of a permission by actually using the API, that often leads to a permission request UI being presented to the end-user (if the permission was not already "granted"). Thus, even though this API doesn’t expose new fingerprinting information to websites, it makes it easier for an adversary to have discreet access to this information. Thus, implementations are encouraged to have an option for users to block (globally or selectively) the querying of permission states.
3. 定義
- `利用者の意図についての新たな情報@ ◎ New information about the user’s intent
- ~UAは、利用者の意向についての情報を収集しても~MAY — ~UA作者が適切と信じる仕方で。 この情報は、[ 利用者による明示的な動作, 当の利用者や他の利用者たちの挙動, この仕様が関知していない`暗黙の情報0$ ]を集成して得ることができる。 ◎ The UA may collect information about a user’s intentions in any way its authors believe is appropriate. This information can come from explicit user action, aggregate behavior of both the relevant user and other users, or implicit signals this specification hasn’t anticipated.
- 注記: `暗黙の情報0@ には,例えば、どの~web~appを~installしていて, どの程度[ 頻繁/近過去 ]に訪問しているか,などが挙げられる — 利用者が、自身が~installした~web~appを より近過去かつ頻繁に利用しているほど,それを信用している可能性が高い。 実装には、暗黙の情報0に依拠するときには,~~注意深くあたることを勧める。 ◎ The implicit signals could be, for example, the install status of a web application or frequency and recency of visits. A user that has installed a web application and used it frequently and recently is more likely to trust it. Implementations are advised to exercise caution when relying on implicit signals.
- `強力な特色機能@ ◎ Powerful feature
- ~UAが備える特色機能のうち,ある~codeからの~accessは許容しない場合もあるもの — 例えば、その~codeに対する`環境~設定群~obj$は 何らかの判定基準を満たしていない,あるいは 利用者が許可を与えなかったなどにより。 ◎ A feature of a UA that some code might not be allowed to access, for example because its environment settings object doesn’t satisfy some criteria, or because the user hasn’t given permission.
- この仕様の処理~modelにおいては、個々の`強力な特色機能$は,その名前を表す文字列( `PermissionName$I 列挙~値)で識別される。 所与の文字列 %名前 で `識別される特色機能@ とは、そのように識別される`強力な特色機能$を指す。 【この段落, およびこの用語は、明確化するための,この訳による追加。】
4. 許可~要請の記述
dictionary `PermissionDescriptor@I { required `PermissionName$I `name@m; };
各 `強力な特色機能$は、~accessする許可を要請できるような 1 つ以上の `側面@ を備える。 そのような特色機能は、[ `PermissionDescriptor$I または その下位型 ]を,自身に備わる`側面$を記述する`許可~記述子~型$として定義する。 ◎ Each powerful feature has one or more aspects that websites can request permission to access. To describe these aspects, each feature defines a subtype of PermissionDescriptor to be its permission descriptor type.
`midi$pN で`識別される特色機能$は、 2 つの`側面$ — 通常の~messageへの~access, ~system排他的な 【system exclusive = sysex】 ~messageへの~access — を備える。 そのための`許可~記述子~型$は、次で与えられる: ◎ The "midi" feature has two aspects: access to normal messages, and access to system exclusive messages. Thus, its permission descriptor type is:
dictionary MidiPermissionDescriptor : PermissionDescriptor { boolean sysex = false; };
`bluetooth$pN で`識別される特色機能$は、[ 利用者の機器に近い何らかの~Bluetooth機器 ]への~accessを,~siteが要請できるようにする。 そのための`許可~記述子~型$は、次で与えられる: ◎ The "bluetooth" feature lets sites request to access whatever Bluetooth devices are close to to the user’s device. Thus, its permission descriptor type is:
dictionary BluetoothPermissionDescriptor : PermissionDescriptor { DOMString deviceId; sequence<`BluetoothLEScanFilterInit$I> filters; sequence<`BluetoothServiceUUID$I> optionalServices = []; boolean acceptAllDevices = false; };
~Bluetooth機器への各種~accessを表現する許可~記述子の例:
- 一般~accessは, {name: `bluetooth$pN} により表現される。
- 特定0の機器への~accessは, {name: `bluetooth$pN, deviceId: %id } により表現される。
- 特定0の~serviceを伴う機器への~accessは, {name: `bluetooth$pN, filters: [{services: [ %service ]}]} により表現される。
5. 許可~状態
~UAは、[ 利用者が、`強力な特色機能$のうち,どれに利用する許可を与えているか ]を,各`~realm$ごとに追跡する責を負う。 他の仕様は、この節に定義する各種 演算を利用して,どの許可が~UA視点で[ 是認-/否認- ]されているかを検索取得でき,利用者に更なる許可を 是認するか否認するか 訊ねることがでる。 ◎ The user agent is responsible for tracking what powerful features each realm has the user’s permission to use. Other specifications can use the operations defined in this section to retrieve the UA’s notion of what permissions are granted or denied, and to ask the user to grant or deny more permissions.
他の仕様はまた、これらの~algoにおける~UAの挙動に,拘束を追加できる。 ◎ Other specifications can also add more constraints on the UA’s behavior in these algorithms.
この節の中では、 %記述子 は,ある %名前 で`識別される特色機能$の`許可~記述子~型$の~instanceを表すとする(すなわち,その `name$m ~EQ %名前 )。 ◎ Within this section, descriptor is an instance of the permission descriptor type of the powerful feature named by descriptor.name.
5.1. 現在の許可~状態の読み取り法
`許可~状態@ は、所与の ( `PermissionDescriptor$I %記述子, `環境~設定群~obj$ %設定群 (省略時は ε ) ) に対し,次を走らせた結果で与えられる — それは[ `granted$pS, `prompt$pS, `denied$pS ]のいずれかを返す: ◎ A descriptor’s permission state for an optional environment settings object settings is the result of the following algorithm, which returns one of "granted", "prompt", or "denied":
- ~IF[ %設定群 ~EQ ε ] ⇒ %設定群 ~SET `現在の設定群~obj$ ◎ If settings wasn’t passed, set it to the current settings object.
- %特色機能 ~LET %記述子 の `name$m で`識別される特色機能$
- ~IF[ %設定群 は`非~保安的~文脈$である ]~AND[ %特色機能 は,`非~保安的~文脈にて許容されて$いない ] ⇒ ~RET `denied$pS ◎ If settings is a non-secure context and descriptor.name isn’t allowed in non-secure contexts, then return "denied".
- ~IF[ この~algoは、以前に,同じ ( %記述子, %設定群 ) で呼出されている ]~AND[ ~UAは、まだ 以前の時点から`利用者の意図についての新たな情報$を受取ってない ] ⇒ ~RET 以前の時点における結果 ◎ If there was a previous invocation of this algorithm with the same descriptor and settings, returning previousResult, and the UA has not received new information about the user’s intent since that invocation, return previousResult.
-
~RET 次の選択肢のうち、~call元の~algoに対し,利用者の意図を最も正確0に反映しつつ, %特色機能 の`許可~状態~拘束$も満たすもの: ◎ Return whichever of the following options most accurately reflects the user’s intent for the calling algorithm, taking into account any permission state constraints for descriptor.name:
- 利用者に~promptすることなく成功する ◎ succeed without prompting the user
- `granted$pS
- 利用者に~promptを示して,成功するかどうか決めてもらう ◎ show the user a prompt to decide whether to succeed
- `prompt$pS
- 利用者に~promptすることなく失敗する ◎ fail without prompting the user
- `denied$pS
Safari のみが、[ この~algoが、同じ生成元に属する異なる設定群~objに対し,異なる結果を返す ]ような,既知の~UAである。 `いくつかあり得る設定群~obj$のうち,どれを利用するか試験するべきである。 ◎ Safari is the only known UA that returns different results from this algorithm for different settings objects with the same origin. We should test which of the several possible settings objects it uses.
所与の `PermissionName$I 列挙~値 %名前 に対する`許可~状態$は、次の略記である ⇒ `許可~状態$( 次のようにされた `PermissionDescriptor$I ) ⇒ `name$m ~member ~SET %名前 ◎ As a shorthand, a PermissionName name’s permission state is the permission state of a PermissionDescriptor with its name member set to name.
一部の`強力な特色機能$には、 `PermissionState$I 以外の情報も結付けられる。 例えば, `getUserMedia()$m は、[ 利用者が、どの~cameraに~accessする許可を,`現在の~realm$に是認しているか ]を決定する必要がある。 そのような特色機能のそれぞれは、`~extra許可~data型$を定義する。
ある `PermissionName$I 列挙~値 %名前 で`識別される特色機能$ %特色機能 用の `~extra許可~data@ は、所与の`環境~設定群~obj$ %設定群 (省略時は ε )に対し,次を走らせた結果で与えられる:
◎ Some powerful features have more information associated with them than just a PermissionState. For example, getUserMedia() needs to determine which cameras the user has granted the current realm permission to access. Each of these features defines an extra permission data type. If a PermissionName name names one of these features, then name’s extra permission data for an optional environment settings object settings is the result of the following algorithm:- ~IF[ %設定群 ~EQ ε ] ⇒ %設定群 ~SET `現在の設定群~obj$ ◎ If settings wasn’t passed, set it to the current settings object.
- ~IF[ この~algoは、以前に,同じ ( %名前, %設定群 ) で呼出されている ]~AND[ ~UAは まだ 以前の時点から`利用者の意図についての新たな情報$を受取ってない ] ⇒ ~RET 以前の時点における結果 ◎ If there was a previous invocation of this algorithm with the same name and settings, returning previousResult, and the UA has not received new information about the user’s intent since that invocation, return previousResult.
- ~RET [ ~UA視点による利用者の意図に合致しつつ, %特色機能 の`~extra許可~data拘束$も満たす ]ような,[ %特色機能 `~extra許可~data型$ ]の~instance ◎ Return the instance of name’s extra permission data type that matches the UA’s impression of the user’s intent, taking into account any extra permission data constraints for name.
5.2. 更なる許可の要請-法
注記: 仕様の策定者は、この節に与える~algoが 利用者からの入力を待機し得ることに注意されたし — ~main-threadで走っている~algoからは利用されるべきでない。 ◎ Spec authors, please note that algorithms in this section can wait for user input; so they shouldn’t be used from other algorithms running on the main thread.
所与の %記述子 を `利用する許可を要請-@ するときは、次の手続きを遂行し~MUST — この~algoは[ `granted$pS, `denied$pS ]のいずれかを返す: ◎ To request permission to use a descriptor, the UA must perform the following steps. This algorithm returns either "granted" or "denied".
- %現~状態 ~LET `許可~状態$( %記述子 ) ◎ Let current state be the descriptor’s permission state.
- ~IF[ %現~状態 ~NEQ `prompt$pS ] ⇒ ~RET %現~状態 ◎ If current state is not "prompt", return current state and abort these steps.
-
[ ~call元の~algoが[ %記述子 で記述される`強力な特色機能$ ]を利用する ]ための許可を,利用者に訊ねた上で: ◎ Ask the user’s permission for the calling algorithm to use the powerful feature described by descriptor.
- ~RET [ 利用者は許可を是認したならば `granted$pS / ~ELSE_ `denied$pS ] ◎ If the user grants permission, return "granted"; otherwise return "denied".\
- 利用者からの~~回答は、[[ この `~realm$, および `同一生成元$に属する他の`~realm$ ]に対する,`利用者の意図についての新たな情報$ ]を供するものとされて~MAY。 ◎ The user’s interaction may provide new information about the user’s intent for this realm and other realms with the same origin.
注記: ここでの[ 許可~UI / ~UAが利用者の意図をどう推定するか ]の詳細については、意図的に曖昧にしてある。 ~UAは、この枠組みの下で数多の~UIを探求するべきである。 【例えば,利用者が是認せず,明示的に否認することもなく~UIを退けた場合、`利用者の意図についての新たな情報$としては扱わないことも考えられる。】 ◎ This is intentionally vague about the details of the permission UI and how the UA infers user intent. UAs should be able to explore lots of UI within this framework.
`PermissionName$I %名前 を`利用する許可を要請-$するとは、[ `name$m ~memberが %名前 に設定された `PermissionDescriptor$I ]を`利用する許可を要請-$することの略記である。 ◎ As a shorthand, requesting permission to use a PermissionName name, is the same as requesting permission to use a PermissionDescriptor with its name member set to name.
%記述子 に結付けられている %選択肢~群 の中から一つを `選ぶよう利用者に~prompt@ するときは、~UAは,次の手続きを遂行し~MUST。 この~algoは、[ `denied$pS, または 選択肢のうち一つ ]を返す。 ◎ To prompt the user to choose one of several options associated with a descriptor, the UA must perform the following steps. This algorithm returns either "denied" or one of the options.
- ~IF[ `許可~状態$( %記述子 ) ~EQ `denied$pS ] ⇒ ~RET `denied$pS ◎ If descriptor’s permission state is "denied", return "denied" and abort these steps.
-
~IF[ `許可~状態$( %記述子 ) ~EQ `granted$pS ] ⇒ ~UAの任意選択で:
- ~RET %選択肢~群 の中のいずれかの選択肢 — 利用者に~promptすることなく
- この場合,~UAは、後続の同じ ( %記述子, 選択肢の集合 ) から`選ぶよう利用者に~prompt$するときも、~UAが`利用者の意図についての新たな情報$を受取っていない限り,同じ選択肢を返さ~MUST。
-
利用者に[ 選択肢のうち一つを選ぶか, 許可を否認するか ]訊ねた上で — ~call元の~algoが[ ~prompt内に含める~extra情報 ]を指定した場合は,それも含ませて — 選ばれるまで待機する: ◎ Ask the user to choose one of the options or deny permission, and wait for them to choose. If the calling algorithm specified extra information to include in the prompt, include it.
- ~RET[ 利用者は ある選択肢を選んだ ならば それ / ~ELSE_ `denied$pS ] ◎ If the user chose an option, return it; otherwise return "denied".\
- 利用者から[ 選んだものを,他の~realmにも適用するよう意図する ]ことが指示された場合は、それを,[ この~realmと`同一生成元$に属する他の`~realm$ ]に対しても,`利用者の意図についての新たな情報$として扱うとする。 ◎ If the user’s interaction indicates they intend this choice to apply to other realms, then treat this this as new information about the user’s intent for other realms with the same origin.
注記: ここでの[ 許可~UI / ~UAが利用者の意図をどう推定するか ]についての詳細は、意図的に曖昧にしてある。 ~UAは、この枠組みの下で数多の~UIを探求するべきである。 ◎ This is intentionally vague about the details of the permission UI and how the UA infers user intent. UAs should be able to explore lots of UI within this framework.
`PermissionName$I %名前 に結付けられている選択肢~群から`選ぶよう利用者に~prompt$するとは、[ `name$m ~memberが %名前 に設定された`PermissionDescriptor$I ]に結付けられている選択肢~群から`選ぶよう利用者に~prompt$することの略記である。 ◎ As a shorthand, prompting the user to choose from options associated with a PermissionName name, is the same as prompting the user to choose from those options associated with a PermissionDescriptor with its name member set to name.
5.3. 利用者による許可の破棄-に対する反応-法
~UAは、[ 利用者が[ ある`~realm$ %~Realm において,`強力な特色機能$ %特色機能 を利用する許可を是認する ]ことを最早~意図しない ]ことを学習したときは、次をし~MUST ⇒ %~Realm の`設定群~obj$の`担当の~event-loop$enV 上に,[ %特色機能 の`許可~破棄~algo$ ]を走らす`~taskを~queueする$ ◎ When the UA learns that the user no longer intends to grant permission for a realm to use a feature, it must queue a task on the Realm’s settings object’s responsible event loop to run that feature’s permission revocation algorithm.
6. 許可の状態0
enum `PermissionState@I { `granted$pS, `denied$pS, `prompt$pS, };
- `granted@pS
- “是認されている”
- この状態は、[ ~UAが許可を利用者に訊ねることなく,~call元が成功裡に当の特色機能に~accessできる ]ことを表現する。 ◎ The "granted" state represents that the caller will be able to successfuly access the feature without having the user agent asking the user’s permission.
- `denied@pS
- “否認されている”
- この状態は、[ ~call元は,当の特色機能に~accessできない ]ことを表現する。 ◎ The "denied" state represents that the caller will not be able to access the feature.
- `prompt@pS
- この状態は、[ ~call元が当の特色機能に~accessしようと試行した場合には,~UAは利用者に許可を訊ねることになる ]ことを表現する。 利用者は、その要請を[ 是認することも, 否認することも, 退けることも ]ある。 ◎ The "prompt" state represents that the user agent will be asking the user’s permission if the caller tries to access the feature. The user might grant, deny or dismiss the request.
[`Exposed$=(Window,Worker)] interface `PermissionStatus@I : `EventTarget$I { readonly attribute `PermissionState$I `state$m; attribute `EventHandler$I `onchange$m; };
`PermissionStatus$I の各~instanceは、 `query@sl 内部~slotを伴って作成される。 それは、[ ある`強力な特色機能$の`許可~記述子~型$ ]の~instanceを保持する。 ◎ PermissionStatus instances are created with a [[query]] internal slot, which is an instance of a feature’s permission descriptor type.
`~PermissionStatusを作成する@ ときは、所与の ( `PermissionDescriptor$I %許可~記述子 ) に対し,次を走らす:
- %特色機能 ~LET %許可~記述子 の `name$m 値で`識別される特色機能$
- %結果 ~LET 新たな[ %特色機能 の`許可~結果型$ ]の~instance
- %結果 の `query$sl 内部~slot ~SET %許可~記述子
- ~RET %結果
- `state@m
- 取得子は、最後に設定された値を返さ~MUST。 ◎ The state attribute MUST return the latest value that was set on the current instance.
- `onchange@m
- `~event~handler~event型$ `change^et に対応する`~event~handler$。 ◎ The onchange attribute is an event handler whose corresponding event handler event type is change.
~UAは, `PermissionStatus$I ~instance %状態0 の状態が変化したときは、いつでも,次の手続きを非同期的に走らせ~MUST: ◎ Whenever the user agent is aware that the state of a PermissionStatus instance status has changed, it MUST asynchronously run the following steps:
- %名前 ~LET %状態0 の `query$sl 内部~slot の `name$m 値 ◎ ↓
- ( %名前, %状態0 ) を渡して, %名前 で`識別される特色機能$の`許可~照会-~algo$を走らす ◎ Run status@[[query]].name’s permission query algorithm, passing status@[[query]] and status.
- `許可~task源@ から,次を走らす`~taskを~queueする$ ⇒ %状態0 に向けて,名前 `change^et の`~eventを発火する$ ◎ Queue a task on the permission task source to fire an event named change at status.
8. `Permissions^I ~interface
[`Exposed$=(Window,Worker)] interface `Permissions@I { `Promise$I<`PermissionStatus$I> `query$m(`object$ %permissionDesc); };
- `query(permissionDesc)@m
-
被呼出時には、次に与える `許可を照会する@ ~algoを走らせ~MUST: ◎ When the query(permissionDesc) method is invoked, the user agent MUST run the following query a permission algorithm, passing the parameter permissionDesc:
-
%有型~記述子 ~LET 次の下位手続きを走らせた結果:
- %根~記述子 ~LET %permissionDesc を `PermissionDescriptor$I 型の`~IDL値に変換-$した結果
- %特色機能 ~LET %根~記述子 の `name$m 値で`識別される特色機能$
- ~RET %permissionDesc を[ %特色機能 の`許可~記述子~型$ ]の`~IDL値に変換-$した結果
この段で例外が投出されたときは ⇒ ~RET その例外で`却下される~promise$
◎ Let rootDesc be the object permissionDesc refers to, converted to an IDL value of type PermissionDescriptor. If this throws an exception, return a promise rejected with that exception and abort these steps. ◎ Let typedDescriptor be the object permissionDesc refers to, converted to an IDL value of rootDesc.name’s permission descriptor type. If this throws an exception, return a promise rejected with that exception and abort these steps. - %~promise ~LET `新たな~promise$ ◎ Let promise be a newly-created Promise.
- ~RET %~promise — ただし、以降の手続きも`並列的$に走らす ◎ Return promise and continue the following steps asynchronously.
- %状態0 ~LET `~PermissionStatusを作成する$( %有型~記述子 ) ◎ Run the steps to create a PermissionStatus for typedDescriptor, and let status be the result.
- %名前 ~LET %状態0 の `query$sl 内部~slot の `name$m 値 ◎ ↓
- ( %名前, %状態0 ) を渡して, %名前 で`識別される特色機能$の`許可~照会-~algo$を走らす ◎ Run status@[[query]].name’s permission query algorithm, passing status@[[query]] and status.
- %状態0 で %~promise を`解決する$ ◎ Resolve promise with status.
注記: 開発者は、一度に複数の許可を検査したいと求める場合, `Promise$I の `all()^m 関数の利用-を推奨する。 各種 用例もある 。 ◎ If a developer wants to check multiple permissions at once, the editors recommend the use of Promise.all(). An example can be found in the Examples section.
-
9. 共通の各種 許可~algo
`真偽~許可を照会する@ ときは、所与の ( `PermissionDescriptor$I %許可~記述子, `PermissionStatus$I %状態0 ) に対し,次の手続きを走らす: ◎ The boolean permission query algorithm, given a PermissionDescriptor permissionDesc and a PermissionStatus status, runs the following steps:
- %状態0 の `state$m ~SET `許可~状態$( %許可~記述子 ) ◎ Set status.state to permissionDesc’s permission state.
10. 許可~registry
enum `PermissionName@I { `geolocation$pN, `notifications$pN, `push$pN, `midi$pN, `camera$pN, `microphone$pN, `speaker$pN, `device-info$pN, `background-sync$pN, `bluetooth$pN, `persistent-storage$pN, `ambient-light-sensor$pN, `accelerometer$pN, `gyroscope$pN, `magnetometer$pN, `clipboard$pN, };
注記: 列挙~値[ `accelerometer$pN, `gyroscope$pN, `magnetometer$pN ]は、暫定的であり,早期の実装からの~feedbackに基づいて変更され得る。 更なる情報は w3c/sensors#22 を見よ。 ◎ The enumeration values accelerometer, gyroscope and magnetometer are considered provisional and are subject to change based on feedback from early implementations. See w3c/sensors#22 issue for more information.
`PermissionName$I の各~列挙~値は、ある`強力な特色機能$を識別する。 各 `強力な特色機能$ %特色機能 は、次に挙げる,許可に関係する各種[ ~flag, ~algo, 型 ]を備える: ◎ Each enumeration value in the PermissionName enum identifies a powerful feature. Each powerful feature has the following permission-related flags, algorithms, and types:
- `非~保安的~文脈~許容~flag@ ◎ An allowed in non-secure contexts flag
- ~ON にされている場合(以下では、`非~保安的~文脈にて許容されて$いる,とも称される)、~UAは,`非~保安的~文脈$においても %特色機能 への~accessを是認して~MAY。 ◎ By default, only secure contexts can use powerful features. If this flag is set for a feature, the UA may grant access to it in non-secure contexts too.
- 未指定の場合の既定は、 ~OFF とする — すなわち, %特色機能 を利用できるのは、`保安的~文脈$に限られる。 ◎ ↑
- `許可~記述子~型@ ◎ A permission descriptor type
- `PermissionDescriptor$I, または その下位型。 ◎ PermissionDescriptor or one of its subtypes.\
- 未指定の場合の既定は、 `PermissionDescriptor$I とする。 ◎ If unspecified, this defaults to PermissionDescriptor.
-
%特色機能 は、記述子の各~instance間において `より強い@ と称される 半順序 を定義できる。 [ 記述子 %A は記述子 %B `より強い$ ]ならば、次が満たされ~MUST:
- [ `許可~状態$( %A ) ~EQ `granted$pS ]ならば[ `許可~状態$( %B ) ~EQ `granted$pS ]
- [ `許可~状態$( %B ) ~EQ `denied$pS ]ならば[ `許可~状態$( %A ) ~EQ `denied$pS ]
- {name: `midi$pN, sysex: true} — “sysex ありの~MIDI” — は {name: `midi$pN, sysex: false} — “sysex なしの~MIDI” — `より強い$ので、利用者が “sysex なしの~MIDI” への~accessを否認した場合、~UAは “sysex ありの~MIDI” への~accessも否認し~MUST。 同様に,利用者が “sysex ありの~MIDI” への~accessを是認した場合、~UAは “sysex なしの~MIDI” への~accessも是認し~MUST。 ◎ {name: "midi", sysex: true} ("midi-with-sysex") is stronger than {name: "midi", sysex: false} ("midi-without-sysex"), so if the user denies access to midi-without-sysex, the UA must also deny access to midi-with-sysex, and similarly if the user grants access to midi-with-sysex, the UA must also grant access to midi-without-sysex.
- `許可~状態~拘束@ ◎ Optional permission state constraints
- ~UAが`許可~状態$( 記述子 ) として返せる値を拘束する。 ◎ Constraints on the values that the UA can return as a descriptor’s permission state.\
- 既定では(省略時)、利用者の意図を超える拘束はないとする。 ◎ Defaults to no constraints beyond the user’s intent.
- `~extra許可~data型@ ◎ An optional extra permission data type
- 指定された場合、 %特色機能 用の`~extra許可~data$を利用できるようになる。 ◎ If specified, the extra permission data algorithm is usable for this feature.
- 【 すなわち,既定では(省略時)、`~extra許可~data$はない。 】【 この “型” には、何らかの~IDLが含意されるわけではないようだ。 】
- `~extra許可~data拘束@ ◎ Optional extra permission data constraints
- ~UAが %特色機能 用の`~extra許可~data$として返せる値を拘束する。 ◎ Constraints on the values that the UA can return as a PermissionName's extra permission data.\
- 既定では(省略時)、利用者の意図を超える拘束はないとする。 ◎ Defaults to no constraints beyond the user’s intent.
- `許可~結果型@ ◎ A permission result type
- `PermissionStatus$I または,その下位型。 ◎ PermissionStatus or one of its subtypes.\
- 未指定の場合の既定は、 `PermissionStatus$I とする。 ◎ If unspecified, this defaults to PermissionStatus.
- `許可~照会-~algo@ ◎ A permission query algorithm
-
次の 2 つの引数:
- %特色機能 の`許可~記述子~型$の~instance
- %特色機能 の`許可~結果型$の 新たな または既存の~instance
に対する照会-結果で,後者の引数を更新する。 [ `Permissions$I の `query()$m ~method / `~PermissionStatus更新~手続き$ ]で利用される。
◎ Takes an instance of the permission descriptor type and a new or existing instance of the permission result type, and updates the permission result type instance with the query result. Used by Permissions' query(permissionDesc) method and the PermissionStatus update steps.\ - 未指定の場合の既定は、`真偽~許可を照会する$。 ◎ If unspecified, this defaults to the boolean permission query algorithm.
- `許可~破棄~algo@ ◎ A permission revocation algorithm
- 引数はとらない。 [ `許可~状態$ / `~extra許可~data$ ]の結果における変化と同期させ続ける必要があるような,実装における他の部分があれば、それを更新する。 利用者による許可の破棄-に対する反応-法 により走らされる。 ◎ Takes no arguments. Updates any other parts of the implementation that need to be kept in sync with changes in the results of permission states or extra permission data. Run by §5.3 Reacting to users revoking permission.\
- 未指定の場合の既定は、何もしないとする。 ◎ If unspecified, this defaults to doing nothing.
`真偽~特色機能@ とは、`強力な特色機能$のうち,上の各種[ 型/~algo ]すべて†が既定のそれらにされたものをいう。 【†非~保安的~文脈~許容~flagは除外されていることに注意。】 ◎ A boolean feature is a powerful feature with all of the above types and algorithms defaulted.
10.1. 地理所在~API( `geolocation^l )
`geolocation@pN で`識別される特色機能$に対する許可は、 `geolocation-API$r の用法に結付けられている。 それは`真偽~特色機能$であり、 `非~保安的~文脈にて許容されて$いる。 ◎ The "geolocation" permission is the permission associated with the usage of the [geolocation-API]. It is a boolean feature and is allowed in non-secure contexts.
10.2. 通知~API( `notifications^l )
`notifications@pN で`識別される特色機能$に対する許可は、 `notifications$r ~API の用法に結付けられている。 それは、`真偽~特色機能$であり,`非~保安的~文脈にて許容されて$いる。 ◎ The "notifications" permission is the permission associated with the usage of the [notifications] API. It is a boolean feature and is allowed in non-secure contexts.
10.3. ~push~API( `push^l )
`push@pN で`識別される特色機能$に対する許可は、 `push-api$r の用法に結付けられている。 ◎ The "push" permission is the permission associated with the usage of the [push-api].
- `許可~記述子~型$ ◎ permission descriptor type
-
dictionary `PushPermissionDescriptor@I : `PermissionDescriptor$I { boolean `userVisibleOnly@m = false; };
{name: `push$pN, userVisibleOnly: false} は {name: `push$pN, userVisibleOnly: true} `より強い$とする。 ◎ {name: "push", userVisibleOnly: false} is stronger than {name: "push", userVisibleOnly: true}.
10.4. ~MIDI~API( `midi^l )
`midi@pN で`識別される特色機能$に対する許可は、 `webmidi$r の用法に結付けられている。 `midi$pN は`非~保安的~文脈にて許容されて$いる。 ◎ The "midi" permission is the permission associated with the usage of [webmidi]. "midi" is allowed in non-secure contexts.
- `許可~記述子~型$ ◎ permission descriptor type
-
dictionary `MidiPermissionDescriptor@I : `PermissionDescriptor$I { boolean `sysex@m = false; };
{name: `midi$pN, sysex: true} は {name: `midi$pN, sysex: false} `より強い$とする。 ◎ {name: "midi", sysex: true} is stronger than {name: "midi", sysex: false}.
10.5. 各種~media機器
[ `camera@pN / `microphone@pN / `speaker@pN ]で`識別される特色機能$に対する許可は、 `GETUSERMEDIA$r, `audio-output$r に指定される~media機器の用法に結付けられている。
- `speaker$pN は、`非~保安的~文脈にて許容されて$いる。
- [ `camera$pN / `microphone$pN ]は、`非~保安的~文脈にて許容されて$も~MAY。
[[ `name$m の値 ~IN { `camera$pN, `microphone$pN } ]なる記述子に対する`許可~状態$( 記述子 ) は、[ `現在の大域~obj$に`結付けられている文書$ %文書 ]に[ 属性~名 `allowusermedia$a で指示される特色機能の`利用は許容されて$いない ]ならば, `denied$pS にされ~MUST。 ◎ If the current global object has an associated Document, and that Document is not allowed to use the feature indicated by attribute name allowusermedia, then the permission state of any descriptor with a name of "camera" or "microphone" must be "denied".
- `許可~記述子~型$ ◎ permission descriptor type
-
dictionary `DevicePermissionDescriptor@I : `PermissionDescriptor$I { DOMString `deviceId@m; };
- 許可~~対象は、記述子が与える機器への~accessになる。 ◎ A permission covers access to the device given in the associated descriptor.
-
記述子が `deviceId$m を伴わない場合、記述子の `name$m で`識別される特色機能$に類別される すべての機器への~accessを照会することになる。 したがって, `camera$pN で`識別される特色機能$に対する `deviceId$m を伴わない許可~照会-に対しては: ◎ If the descriptor does not have a deviceId, its semantic is that it queries for access to all devices of that class. Thus, if a query for the "camera" permission with no deviceId\
- 結果が `granted$pS ならば ~cameraに対する許可~promptは決して生じないことが~~判明することになる。 ◎ returns "granted", the client knows that there will never be a permission prompt for a camera, and\
- 結果が `denied$pS ならば ~cameraに対し `getUserMedia()^m で要請しても成功しないことが~~判明することになる。 ◎ if "denied" is returned, it knows that no getUserMedia request for a camera will succeed.
- ~accessに対する許可~状態が一部の~cameraのみに在る場合、 `prompt$pS が返されることになる。 ◎ If a permission state is present for access to some, but not all, cameras, a query without the deviceId will return "prompt".
- 結果が `granted$pS であっても, `getUserMedia()^m の成功-が保証されるわけではないことに注意。 保証されるのは、許可を得る際に利用者に~promptされないことに限られる。 `getUserMedia()^m を失敗させ得るものは,他にいくつもある(利用-中にある~cameraに対する拘束など)。 ◎ Note that a "granted" permission is no guarantee that getUserMedia will succeed. It only guarantees that the user will not be prompted for permission. There are many other things (such as constraints or the camera being in use) that can cause getUserMedia to fail.
- `~extra許可~data型$ ◎ extra permission data type
- 利用者が~accessに関して既定でない裁定を下した各 機器に対応する `deviceId$c 値からなる~list。 ◎ A list of deviceId values for the devices the user has made a non-default decision on access to.
- `許可~照会-~algo$ ◎ permission query algorithm
-
次の手続きを走らす: ◎ The permission query algorithm runs the following steps:
-
~IF[ `~extra許可~data$内に %許可~記述子 の `deviceId^m は在る ]:
- %状態0 の `state$m ~SET `許可~状態$( %許可~記述子 )
- ~RET
- %大域~記述子 ~LET %許可~記述子 の複製から `deviceId$m ~memberを除去した結果 ◎ Let global be a copy of permissionDesc with the deviceId member removed.
- %状態0 の `state$m ~SET `許可~状態$( %大域~記述子 ) ◎ Set status.state to global’s permission state.
-
- 許可~要請~algo ◎ permission request algorithm
- 【 この~algoの利用は 仕様から除去された ため、これは最早~利用されていない(削除漏れ?)。 なので、和訳は省略する。 】 ◎ The permission request algorithm runs the following steps: • Let result be the result of running the boolean permission request algorithm. • If result is "granted", the UA MUST set the "device-info" permission to "granted" for this realm. • The UA MAY treat result as new information about the user’s intent with respect to the "device-info" permission for this realm and other realms with the same origin, provided it doesn’t violate the previous step. • Return result.
- `許可~破棄~algo$ ◎ permission revocation algorithm
- 機器に対する許可が破棄されたときは、~UAは ~trackを停止する~algo 【参照先不明】 を走らせ~MUST — ただし、その機器を源とする各 `MediaStreamTrack^I 上の `stop()^m ~methodが呼出されたことによる場合は除く。 ◎ When permission for a device is revoked, the UA MUST run the algorithm to stop the track for any other reason than the stop() method being invoked for each MediaStreamTrack sourced from that device.
`device-info@pN で`識別される特色機能$に対する許可は、次を制御する:
- `deviceId$c に結付けられた名前と能力への~access
- 現在の閲覧文脈が~focusされていないときに `devicechange$et ~eventが発火されるかどうか
`device-info$pN 許可は、生成元に対する `deviceId$c が再設定されたときには破棄され~MUST。
◎ The "device-info" permission controls access to the name and capabilities associated with a deviceId, as well as whether devicechange events fire when the current browsing context is not in focus. The "device-info" permission MUST be revoked when deviceIds for an origin are reset.10.6. ~Background同期~API( `background-sync^l )
`background-sync@pN で`識別される特色機能$に対する許可は、 `web-background-sync$r の用法に結付けられている。 ◎ The "background-sync" permission is the permission associated with the usage of [web-background-sync].
10.7. 環境光~sensor~API( `ambient-light-sensor^l )
`ambient-light-sensor@pN で`識別される特色機能$に対する許可は、 `ambient-light$r ~APIの用法に結付けられている。 ◎ The "ambient-light-sensor" permission is the permission associated with the usage of the [ambient-light] API.
その`許可~破棄~algo$は、[ `ambient-light-sensor$pN を引数に,`汎用~sensor許可~破棄~algo$を~callした結果 ]で与えられる。 ◎ Its permission revocation algorithm is the result of calling generic sensor permission revocation algorithm passing it "ambient-light-sensor" as argument.
10.8. 加速度計( `accelerometer^l )
`accelerometer@pN で`識別される特色機能$に対する許可は、 `accelerometer$r ~APIの用法に結付けられている。 ◎ The "accelerometer" permission is the permission associated with the usage of the [accelerometer] API.
その`許可~破棄~algo$は、[ `accelerometer$pN を引数に,`汎用~sensor許可~破棄~algo$を~callした結果 ]で与えられる。 ◎ Its permission revocation algorithm is the result of calling generic sensor permission revocation algorithm passing it "accelerometer" as argument.
10.9. ~gyroscope( `gyroscope^l )
`gyroscope@pN で`識別される特色機能$に対する許可は、 `gyroscope$r ~APIの用法に結付けられている。 ◎ The "gyroscope" permission is the permission associated with the usage of the [gyroscope] API.
その`許可~破棄~algo$は、[ `gyroscope$pN を引数に,`汎用~sensor許可~破棄~algo$を~callした結果 ]で与えられる。 ◎ Its permission revocation algorithm is the result of calling generic sensor permission revocation algorithm passing it "gyroscope" as argument.
10.10. 磁力計( `magnetometer^l )
`magnetometer@pN で`識別される特色機能$に対する許可は、 `magnetometer$r ~APIの用法に結付けられている。 ◎ The "magnetometer" permission is the permission associated with the usage of the [magnetometer] API.
その`許可~破棄~algo$は、[ `magnetometer$pN を引数に,`汎用~sensor許可~破棄~algo$を~callした結果 ]で与えられる。 ◎ Its permission revocation algorithm is the result of calling generic sensor permission revocation algorithm passing it "magnetometer" as argument.
10.11. ~clipboard( `clipboard^l )
`clipboard@pN で`識別される特色機能$に対する許可は、 `clipboard-apis$r における非同期的~methodの用法に結付けられている。 ◎ The "clipboard" permission is the permission associated with the usage of the asynchronous methods in the [clipboard-apis].
11. 自動化
この文書は、[ ~UAの自動化 / ~appを試験する ]目的において, `WebDriver$r 仕様~用に次の`拡張~command$を定義する。 ◎ For the purposes of user-agent automation and application testing, this document defines the following extension command for the [WebDriver] specification.
dictionary `PermissionSetParameters@I { required `PermissionDescriptor$I `descriptor@mPsP; required `PermissionState$I `state@mPsP; boolean `onerealm@mPsP = false; };
11.1. 設定-許可
~HTTP~method | `拡張~command接頭辞$ | `拡張~command名$ |
---|---|---|
`POST^M | `/session/{session id}/permissions^c | `set^l |
`拡張~command$ `設定-許可@ は、[ `PermissionDescriptor$I の`許可~状態$に対する,利用者による改変 ]を模倣する。 ◎ The Set Permission extension command simulates user modification of a PermissionDescriptor's permission state.
`遠隔端の手続き$は、次で与えられる: ◎ The remote end steps are:
- %~error ~LET ( `~error~code$ `妥当でない引数$ ) を伴う `~error$i ◎ ↓
- %parameters ~LET %parameters 引数を型 `PermissionSetParameters$I の`~IDL値に変換-$した結果 ⇒ 例外が投出されたときは ⇒ ~RET %~error ◎ Let parameters be the parameters argument, converted to an IDL value of type PermissionSetParameters. If this throws an exception, return a WebDriver error with WebDriver error code invalid argument.
- %根~記述子 ~LET %parameters . `descriptor$mPsP ◎ Let rootDesc be parameters.descriptor.
- %特色機能 ~LET %根~記述子 の `name$m 値で`識別される特色機能$ ◎ ↓
- %有型~記述子 ~LET %根~記述子 が指す~objを[ %特色機能 の`許可~記述子~型$ ]の`~IDL値に変換-$に変換した結果 ⇒ 例外が投出されたときは ⇒ ~RET %~error ◎ Let typedDescriptor be the object rootDesc refers to, converted to an IDL value of rootDesc.name’s permission descriptor type. If this throws an exception, return a WebDriver error with WebDriver error code invalid argument.
-
~IF[ %parameters . `state$mPsP は[ 実装により定義される何らかの理由により,適切でない`許可~状態$ ]である ] ⇒ ~RET %~error ◎ If parameters.state is an inappropriate permission state for any implementation-defined reason, return a WebDriver error with WebDriver error code invalid argument.
注記: 例えば `midi$pN で`識別される特色機能$を “常にオン” として定義する~UAは、この段で`許可~状態$を `denied$pS に設定するために,~commandを却下することを選んでも~MAY。 ◎ For example, user agents that define the "midi" feature as "always on" may choose to reject command to set the permission state to "denied" at this step.
- %設定群 ~LET `現在の閲覧文脈$にて`作動中の文書$の`環境~設定群~obj$ 【文書に`関連する設定群~obj$】 ◎ Let settings be the environment settings object of the current browsing context’s active document.
- ~IF[ %設定群 は`非~保安的~文脈$である ]~AND[ %特色機能 は`非~保安的~文脈にて許容されて$いない ] ⇒ ~RET %~error ◎ If settings is a non-secure context and rootDesc.name isn’t allowed in non-secure contexts, return a WebDriver error with WebDriver error code invalid argument.
- %設定群~list ~LET 新たな`~list$
- ~IF[ %parameters . `onerealm$mPsP ~EQ ~T ] ⇒ %設定群~list に %設定群 を`付加する$ ◎ If parameters.oneRealm is true, let targets be a list whose sole member is settings.
- ~ELSE ⇒ %設定群~list に次を満たす各 `環境~設定群~obj$を`付加する$【順序は述べられていない】 ⇒ ( その`生成元$enV, %設定群 の`生成元$enV ) は`同一生成元$である ◎ Otherwise, let targets be a list containing all environment settings objects whose origin is the same as the origin of settings.
- %設定群~list 内の~EACH( `環境~設定群~obj$ %設定群 ) に対し ⇒ `許可~task源$から, %設定群 の`担当の閲覧文脈$enV上に,次を遂行する`~taskを~queueする$ ⇒ %parameters . `state$mPsP を それが次の結果であったかのように解釈する ⇒ `許可~状態$( %有型~記述子, %設定群 ) ◎ Let tasks be an empty list. ◎ For each environment settings object target in targets: • Queue a task task on the permission task source of target’s responsible browsing context to perform the following step: • Interpret parameters.state as if it were the result of an invocation of permission state for typedDescriptor with the argument target made at this moment. • Append task to tasks.
- 前~段で~queueしたすべての`~task$が実行されるまで待機する ◎ Wait for all tasks in tasks to have executed.
- ~RET ( ~data `null^c ) を伴う`成功$i ◎ Return success with data null.
~ID 23 を伴う`~session$の`現在の閲覧文脈$の {name: `midi$pN, sysex: true} 用に許可を `granted^l に設定するためには、`局所端$は,次の本体を伴わせて /session/23/permissions/set に `POST^M することになる: ◎ To set permission for {name: "midi", sysex: true} of the current browsing context of the session with ID 23 to "granted", the local end would POST to /session/23/permissions/set with the body:
{ "descriptor": { "name": "midi", "sysex": true }, "state": "granted" }
12. 各種 例
次の例は、~Permissions~APIを利用して,[ ~Geolocation~APIを用いて地域newsを示すべき ]か, または[ 当の特色機能を追加する~buttonを提供する ]かどうかを決める。 ◎ This example uses the Permissions API to decide whether local news should be shown using the Geolocation API or with a button offering to add the feature.
%navigator.permissions.query({ name: "geolocation" }).then(({ %state }) => {
switch (%state) {
case `granted$pS:
showLocalNewsWithGeolocation();
break;
case `prompt$pS:
showButtonToEnableLocalNews();
break;
default:
/*
許可が否認されたときは何もしないこと。
◎
Don’t do anything if the permission was denied.
*/
break;
}
});
次の例は, `notifications$pN 許可を用いて、許可~状態に依存して,~chat~app用に通知~buttonを示す。 ◎ This example is using the "notifications" permission for a chat application to show a notification button depending on the permission state.
function updateNotificationButton(%state) { document.getElementById('chat-notification-button') .disabled = (%state === `denied$pS); } navigator.permissions.query({ name: 'notifications' }).then((%result) => { updateNotificationButton(%result.state); %result.addEventListener('change', () => { updateNotificationButton(%result.state); }); });
次の例は、頁は[ `geolocation$pN, `notifications$pN ]両~許可を有するかどうかを検査する — ここでは `Promise$I の `all()^m 関数を用いる。 ◎ This example is checking whether the page has the "geolocation" and the "notifications" permissions using Promise.all.
Promise.all([ navigator.permissions.query({ name: "geolocation" }), navigator.permissions.query({ name: "notifications" }) ]) .then(([{ state: %geoState }, { state: %notifState }]) => { console.log("~Geolocationの許可~状態:", %geoState); console.log("~Notificationsの許可~状態:", %notifState); });
次の例は、可用な~cameraたちの許可~状態を検査する。 ◎ This example is checking the permission state of the available cameras.
navigator.mediaDevices .enumerateDevices() .then(%devices => { return Promise.all(%devices /* 動画~入力に絞り込む ◎ filter on video inputs */ .filter(({ %kind }) => %kind === "videoinput") /* 照会-~objに対応付ける ◎ map to query object */ .map(({ %deviceId }) => ({ name: "camera", %deviceId })) /* 照会-~promiseに対応付ける ◎ map to query promise */ .map(%queryObj => navigator.permissions.query(%queryObj)) ); }) /* 状態や各~cameraの~logをとる ◎ log the state or each camera */ .then(%results => results.forEach( ({ %state }, %i) => console.log( "${%i} 番~cameraの許可~状態: ${%state}") )) .catch( %err => console.error(%err.stack) );
謝辞
~API設計と編集作業に協力された、次の方々に: