diff --git a/CHANGELOG.md b/CHANGELOG.md index 97cdddff2..3c5423498 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,10 @@ +# [1.2.0-next.5](https://github.com/rdkcentral/firebolt-apis/compare/v1.2.0-next.4...v1.2.0-next.5) (2024-06-13) + + +### Bug Fixes + +* Remove x-alternatives that don't exist ([#278](https://github.com/rdkcentral/firebolt-apis/issues/278)) ([e38ad5a](https://github.com/rdkcentral/firebolt-apis/commit/e38ad5a508fccb5c724cf0f03cbd67ad4a28378c)) + # [1.2.0-next.4](https://github.com/rdkcentral/firebolt-apis/compare/v1.2.0-next.3...v1.2.0-next.4) (2024-06-06) diff --git a/package-lock.json b/package-lock.json index 80d33f7c0..0a275aa91 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@firebolt-js/sdks", - "version": "1.2.0-next.3", + "version": "1.2.0-next.5", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@firebolt-js/sdks", - "version": "1.2.0-next.3", + "version": "1.2.0-next.5", "license": "Apache-2.0", "workspaces": [ "src/sdks/core", diff --git a/package.json b/package.json index e6863c389..7b0f9a288 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@firebolt-js/sdks", - "version": "1.2.0-next.3", + "version": "1.2.0-next.5", "description": "The Firebolt JS SDK", "type": "module", "bin": { diff --git a/requirements/images/specifications/general/capabilities/image1.png b/requirements/images/specifications/general/capabilities/image1.png new file mode 100644 index 000000000..049fc70bf Binary files /dev/null and b/requirements/images/specifications/general/capabilities/image1.png differ diff --git a/requirements/images/specifications/general/capabilities/image2.png b/requirements/images/specifications/general/capabilities/image2.png new file mode 100644 index 000000000..7c0c10f7c Binary files /dev/null and b/requirements/images/specifications/general/capabilities/image2.png differ diff --git a/requirements/images/specifications/general/capabilities/image4.png b/requirements/images/specifications/general/capabilities/image4.png new file mode 100644 index 000000000..641c26847 Binary files /dev/null and b/requirements/images/specifications/general/capabilities/image4.png differ diff --git a/requirements/images/specifications/general/capabilities/user-grants/image1.png b/requirements/images/specifications/general/capabilities/user-grants/image1.png new file mode 100644 index 000000000..c836daebf Binary files /dev/null and b/requirements/images/specifications/general/capabilities/user-grants/image1.png differ diff --git a/requirements/images/specifications/general/capabilities/user-grants/image2.png b/requirements/images/specifications/general/capabilities/user-grants/image2.png new file mode 100644 index 000000000..bc0c978ea Binary files /dev/null and b/requirements/images/specifications/general/capabilities/user-grants/image2.png differ diff --git a/requirements/images/specifications/general/capabilities/user-grants/image3.png b/requirements/images/specifications/general/capabilities/user-grants/image3.png new file mode 100644 index 000000000..96d73b0ab Binary files /dev/null and b/requirements/images/specifications/general/capabilities/user-grants/image3.png differ diff --git a/requirements/images/specifications/general/capabilities/user-grants/image4.png b/requirements/images/specifications/general/capabilities/user-grants/image4.png new file mode 100644 index 000000000..0c9246bce Binary files /dev/null and b/requirements/images/specifications/general/capabilities/user-grants/image4.png differ diff --git a/requirements/images/specifications/general/capabilities/user-grants/image5.png b/requirements/images/specifications/general/capabilities/user-grants/image5.png new file mode 100644 index 000000000..26c583d2d Binary files /dev/null and b/requirements/images/specifications/general/capabilities/user-grants/image5.png differ diff --git a/requirements/images/specifications/general/capabilities/user-grants/image6.png b/requirements/images/specifications/general/capabilities/user-grants/image6.png new file mode 100644 index 000000000..4761e5ea4 Binary files /dev/null and b/requirements/images/specifications/general/capabilities/user-grants/image6.png differ diff --git a/requirements/images/specifications/general/capabilities/user-grants/image7.png b/requirements/images/specifications/general/capabilities/user-grants/image7.png new file mode 100644 index 000000000..0b09b1b76 Binary files /dev/null and b/requirements/images/specifications/general/capabilities/user-grants/image7.png differ diff --git a/requirements/specifications/general/capabilities/capabilities.md b/requirements/specifications/general/capabilities/capabilities.md new file mode 100644 index 000000000..30430ec06 --- /dev/null +++ b/requirements/specifications/general/capabilities/capabilities.md @@ -0,0 +1,660 @@ +# Capabilities + +Document Status: Candidate Specification + +See [Firebolt Requirements Governance](../../../governance.md) for more info. + +| Contributor | Organization | +| -------------- | -------------- | +| Andrew Bennett | Sky | +| Tim Dibben | Sky | +| Jeremy LaCivita | Comcast | +| Kevin Pearson | Comcast | +| Peter Yu | Comcast | + +## 1. Overview + +This document introduces Firebolt Capabilities, which enable discovery +of supported features, negotiation of App permissions, and end-user +grants for Apps to access sensitive features. + +Apps can detect if Capabilities are supported and available. If so, Apps +can **Use**, **Provide**, or **Manage** capabilities that they are given +access to. + +The most common case is for an App to `use` a Capability, the platform +to `provide` it, and the Distributor\'s Settings App to `manage` it: + +![Diagram Description automatically +generated](../../../images/specifications/general/capabilities/image1.png) + +However, Apps may also provide Capabilities back to the platform: + +![Diagram Description automatically +generated](../../../images/specifications/general/capabilities/image2.png) + +## 2. Table of Contents +- [1. Overview](#1-overview) +- [2. Table of Contents](#2-table-of-contents) +- [3. Introduction to Capabilities](#3-introduction-to-capabilities) + - [3.1. Capabilities](#31-capabilities) + - [3.2. Availability](#32-availability) + - [3.3. Permissions](#33-permissions) + - [3.4. Roles](#34-roles) + - [3.5. User Grants](#35-user-grants) +- [4. How Capabilities Work](#4-how-capabilities-work) + - [4.1. Supported Capabilities](#41-supported-capabilities) + - [4.2. Available Capabilities](#42-available-capabilities) + - [4.3. Permitted Capabilities](#43-permitted-capabilities) + - [4.4. User Granted Capabilities](#44-user-granted-capabilities) + - [4.5. Invoking Capabilities](#45-invoking-capabilities) +- [5. Configuring Device Capabilities](#5-configuring-device-capabilities) + - [5.1. Device Supported Capabilities](#51-device-supported-capabilities) + - [5.2. Device Grant Policy Overrides](#52-device-grant-policy-overrides) +- [6. Capability Schemas](#6-capability-schemas) + - [6.1. Firebolt Specification Manifest](#61-firebolt-specification-manifest) + - [6.2. Firebolt Device Manifest](#62-firebolt-device-manifest) +- [7. Capability to Feature Mapping](#7-capability-to-feature-mapping) + - [7.1. App installation](#71-app-installation) + - [7.2. Firebolt APIs](#72-firebolt-apis) + - [7.3. Extension APIs](#73-extension-apis) + - [7.4. Hidden Permissions](#74-hidden-permissions) +- [8. Firebolt Capability Catalog](#8-firebolt-capability-catalog) +- [9. APIs](#9-apis) + - [9.1. Core SDK APIs](#91-core-sdk-apis) + - [9.2. Manage SDK APIs](#92-manage-sdk-apis) + +## 3. Introduction to Capabilities + +This section is non-normative and defines the key concepts behind the +Firebolt Capabilities system. Each portion of this section provides a +background and conversational definitions of the terms used in the rest +of this document, and through all Firebolt Requirements Specifications. + +### 3.1. Capabilities + +A Capability is a discrete unit of functionality that a Firebolt device +might be able to perform. It is granular enough to enable appropriate +access controls across all Firebolt Apps, but useful enough to be a +meaningful functional unit that an App might care about. Bluetooth is a +good example of a Capability. + +The Firebolt Specification determines the range of possible +Capabilities. + +Firebolt platforms advertise which Capabilities are supported. The set +of capabilities supported by a device is an immutable set and will never +change at runtime. Supporting Wi-Fi and having an active Wi-Fi +connection are two different things. + +Firebolt platforms determine if an App is allowed to invoke the +different aspects of a Capability (see [Roles](#roles), below). + +Firebolt Apps list which Capabilities are required and optional for the +App to be installed. + +Firebolt Apps inspect which Capabilities are supported and active. + +Firebolt Distributors sign off on some, or all, of the App's listed +required and optional Capabilities. + +### 3.2. Availability + +A Capability may rely on intermittently available resources, for example +a network capability requires an Ethernet or Wi-Fi network connection. + +A supported capability is only considered available if those resources +could be used by the App right now (without taking into account any needed permissions or [User Grants](#user-grants)). For example, the needed +resources are not disabled, not tied up by the platform, and not experiencing +any intermittent network, hardware, or signal issues. + +A supported capability is always supported, but it may not always be +*available*. + +Availability of a capability is a global status, not a per-app status. + +If a Capability is available, then it is considered available globally. +Capabilities can not be available to one app, while simultaneously being +unavailable to another app. This is handled by permissions, or by +capability-specific error management, e.g. returning an error to an app that +attempts to use the video pipeline while in the Inactive Lifecycle state. + +### 3.3. Permissions + +A Permission is what allows an App to attempt to invoke an aspect of a +Capability. Permissions to a Capability are assigned to an App with a +[Role](#roles), by a Firebolt Distributor. + +Firebolt documents and APIs will use the term "Permission" +interchangeably with phrases like: + +- An App's Assigned Role for a Capability + +- App + Capability + Role + +- Etc. + +The Firebolt Specification determines which Capabilities require +Permissions. + +The Firebolt Specification determines which Permission requirements may +be overridden by Distributors. + +An App is considered to have Permission to a Capability if it is: + +- Listed with a Role in the App's manifest and signed by the App + provider + +- Listed and signed again by the Distributor on the App's behalf + +- Listed and signed by the App Publisher when running in self-signed developer + mode + +An App can invoke a Capability if: + +- It has permission, which includes a Role, for that capability + +- The capability is supported by the current device + +- The App is invoking aspects of the capability that it has the + appropriate Role for + +- The capability is [Available](#availability) at time of invocation + +See [Permitted Capabilities](#permitted-capabilities) for more info. + +### 3.4. Roles + +Every Firebolt Capability has exactly three roles: + +- Use + +- Manage + +- Provide + +While these roles will be defined on a case-by-case basis for each +capability, they should generally follow the guidelines set here. + +The `Use` role is for providing basic access so that an App can leverage +the standard use cases of the Capability. The `Use` role will not enable +an App to perform management tasks such as turning the Capability on and +off for the entire device. The `Use` role will not enable an App to +perform administrative tasks such as renaming HDMI inputs, etc. + +The `Manage` role is for providing access to a Capability's management +and administrative features. This role may be used to allow an App to +build a Settings UI for the Capability, for example. The `Manage` role +is not for creating tiers of permissions within a Capability, but for +separating out administrative APIs, for example turning a feature on and +off. + +Most Capabilities are provided by the platform, denoted by making the +`Provide` role `private` for that Capability. However, there are use +cases where Apps may provide Capabilities. The `Provide` role allows for +declaring that an App *implements* the Capability and can be registered +with the platform for fulfilling the Capability's features. This could +be used for functionality that needs to be customized from Distributor +to Distributor. The `Provide` role may also be used to allow Apps to +contribute to aggregated functionality, for example a federated search +feature. By providing a capability, an App is signing up to implement +any `Use` or `Manage` APIs required by that capability. + +Each role must be explicitly assigned. An App *never* inherits the +operations from one role by virtue of being granted another. Roles may +have overlapping functionality. + +A [Permission](#permissions) is the combination of a Capability w/ a +Role and determines which specific operations are permitted. + +### 3.5. User Grants + +A User Grant allows some Permissions to depend on the User of the +Firebolt Device to explicitly grant access for one or all Apps to use a +specific Capability. This an additional layer of access control on top +of Permissions. + +The Firebolt Specification determines which Permissions require User +Grants by default. + +It is not possible to require a User Grant for a Capability that is open +to all Apps. + +Distributors may override any User Grant details that are defined by the +Firebolt Specification if that User Grant Policy is set to +`overridable: true`. + +Consumers want to know that their Smart TV platform treats +security as a first-class design principal. As such, table-stakes User +Grant policies, e.g. App access to Bluetooth, may be denoted as +overridable: false in the Firebolt Specification, to remove any +possibility of a security flaw. + +An App is considered to have a User Grant to a Capability if it: + +- Has Permission to the Capability + +- The User Grant is for the same Role as the Permission above + +- The Capability is **securely** approved by the device user + +If an App invokes a Capability but does not have an active User Grant, +then the platform will block invocation, prompt the user for a grant, +and then continue with the original invocation, e.g. the App does not +have to call the originating API again (assuming the user did give their +approval). + +See [User Granted Capabilities](#user-granted-capabilities) for more +info. + +## 4. How Capabilities Work + +A given Capability may or may not be supported or available. +Additionally, a given Role may or may not be permitted or granted for a +given Capability. + +While support and availability of a Capability is static and global, the +permission and grant status may differ from App to App. + +Determining the status of a Role and Capability is fundamental to +both the Platform and the Apps that run on it. + +### 4.1. Supported Capabilities + +Once an App has been launched, it may need to check if a certain +capability is supported to present the appropriate user experience. For +example, an App may want to put Dolby Atmos badges next to its content, +but only if the platform supports Dolby Atmos. + +The Firebolt Specification determines which capabilities **MUST** be +supported by all Firebolt Devices, by listing those Capabilities in the +[Firebolt Specification Schema](#61-firebolt-specification-schema) as `level: "must"` in the Capabilities +array. + +For a capability to be supported, it **MUST** have *one* or *both* of +the following: + +> A supported capability **MUST** have the necessary hardware and +> software to invoke all required aspects of all Roles of the +> capability. +> +> **OR** +> +> A supported capability **MUST** have the necessary hardware and +> software to support a *certified*, after-market peripheral that +> provides the capability. Note that this includes peripherals that have +> not yet been connected to or installed on the device. + +However, a Firebolt device **MUST NOT** be considered to support a +capability if the capability is disabled by the static distributor +configuration. + +The platform **MUST** return accurate responses based on these +requirements to all [APIs](#apis) outlined below. + +### 4.2. Available Capabilities + +Once an App has been launched, it may need to check if a certain +capability is available, to start the appropriate user experience. For +example, an App that uses an external camera may need to check if the +user has set up their camera before proceeding to the main user +experience. + +A Capability is available if **all** the following are true: + +> An available Capability **MUST** be supported. +> +> An available Capability **MUST** have a provider, either an App, an +> Extension SDK, or the OS itself. +> +> The provider of the Capability **MUST** consider it to be available +> +> An available Capability **MUST NOT** be currently disabled by any +> user, account, or device setting. +> +> An available Capability **MUST** be considered available by at least +> one provider of the capability. This is specified by the requirements +> for each feature. + +An available Capability **MAY** be tied to a User Grant, regardless of +whether the user has granted it yet. Secure user grants gate permission, +not availability. + +The platform **MUST** return accurate responses based on these +requirements to all [APIs](#apis) outlined below. + +### 4.3. Permitted Capabilities + +Capabilities may be permitted to *all* Apps by the [Firebolt +Specification Schema](../../firebolt-specification.json), or to individual Apps by the Distributor-signed +App Manifest. + +An App may need to know if a Capability is permitted to it once it has +been launched. For example, it may need to check if a certain capability +is permitted, to enable the correct features for the current +distributor. For example, an App that has just been installed might not +show a Returns true for capability/role combinations that do not r +Sign-up option when running on a distributor that has not allowed it to +`use` the `commerce:subscribe` capability, and only allow existing users +to sign in. + +Determining if a Capability is permitted requires knowing which **Role** +is being leveraged. + +Permitted capabilities **MUST** be denoted as `public` in the Specification Schema](#61-firebolt-specification-schema). + +Additionally, **one** of the following **MUST** be true as well: + +> The Role **MUST** have `negotiable` set to `false` +> +> **OR** +> +> The Role **MUST** be approved for the capability by the distributor in +> the App Manifest + +A permitted Capability **MAY** be tied to a User Grant, regardless of +whether the user has granted it yet. + +The platform **MUST** return accurate responses based on these +requirements to all [APIs](#apis) outlined below. + +### 4.4. User Granted Capabilities + +Some Capabilities may require a User Grant. It is the App's choice +whether it requests these grants at launch or allows the platform to +interrupt the App's experience when User Grant-gated Capabilities are +invoked. + +Determining if a Capability has been granted by the user requires +knowing which Role is being used. + +For a Capability to be considered granted, it **MUST** be supported. + +Additionally, a Capability + Role is granted to an App if **one** of the +following is true: + +> A granted capability **MUST** have the Role securely granted to the +> App by the user and that grant must not be expired. +> +> **OR** +> +> A granted capability **MUST** have the Role permanently granted to the +> App by the App Manifest, e.g., if the user implicitly granted these by +> virtue of an end user license agreement. + +Firebolt platforms **MUST** support acquiring a user grant *at the +moment the Capability is invoked*, without requiring any reinvocation of +the Capability. + +See [User Grants](./user-grants.md), for more info. + +The platform **MUST** return accurate responses based on these +requirements to all [APIs](#apis) outlined below. + +### 4.5. Invoking Capabilities + +When invoking a Capability, there are several factors that determine +whether the calling App will be allowed. The primary factor is which +Role is being leveraged by the invocation. + +A given Capability & Role can be public or not, and it can be negotiable +or not. + +If a Role for a Capability is public and non-negotiable, then all Apps +are allowed to invoke it, without any explicit permission from the +platform distributor. This is subject to support, availability, and any +required User Grants. + +If a Role for a Capability is public and negotiable, then Apps **MUST** +be permitted by each distributor to use it on that distributor\'s +devices. + +If a Role for a Capability is private, then it **MUST NOT** be permitted +or granted to any Apps. + +A Role for a Capability **MUST NOT** be flagged as negotiable if it is +private. + +If a Capability is gated by a User Grant requirement, then any +invocation **MUST** check the grant status for the Role in question, and +potentially re-acquire a User Grant for the App to invoke it. + +The following flow diagrams show the order of operations for determining +if a Firebolt API, that depends on one or more capabilities, may be +invoked. The checks in this diagram **MUST** be executed in this order +to ensure that error codes are consistent and User Grant prompts are not +displayed to end users in situations where the API call will still not +be allowed for other reasons. + +![](../../../images/specifications/general/capabilities/image4.png) + +Note that determining user grants may involve presenting a UX to the end +user. During this time, a necessary capability may become unavailable. +Due to this, necessary Capabilities MUST be reevaluated for availability +after determining user grant status. For a more detailed flow diagram +for evaluating User Grants, see [User Grants](./user-grants.md). + +## 5. Configuring Device Capabilities + +The Firebolt Specification describes all the possible, non-Extension +capabilities that a particular version of Firebolt allows. Individual +Firebolt devices, however, may not support every Capability and may want +to override certain aspects of those Capabilities. + +Every Firebolt-compliant device **MUST** include an official, versioned +Firebolt JSON configuration that conforms to the Specification Schema](#61-firebolt-specification-schema), so that the implementation +knows how to configure each capability, and which aspects are +overridable. + +Additionally, every Firebolt-compliant device **MUST** have a versioned + +Firebolt Device JSON configuration that conforms to the Firebolt Device +Schema, so that the implementation knows how each capability has been +overridden by the Distributor for this device. + +See [Firebolt Device Schema](#firebolt-device-schema) for more info. + +### 5.1. Device Supported Capabilities + +Firebolt-compliant devices **MUST** list all the Capabilities they +support in the Device Capabilities configuration file\'s `supported` +array. + +The `supported` array **MUST** contain a `CapabilityConfig` for every +Firebolt Capability supported by this device. + +The `supported` array **MUST** contain an entry for every Capability +from the Specification Schema](#61-firebolt-specification-schema) that has a level of `must`. + +The `supported` array **MAY** contain entries for any `should` or +`could` Capabilities. + +The supported array **MUST NOT** contain any entries for Capabilities +not found in the Firebolt Specification Schema. + +### 5.2. Device Grant Policy Overrides + +Firebolt-compliant devices **MAY** override any `GrantPolicies` that +have `overridable` set to `true`. + +This can be used to permanently disable a User Grant + +Firebolt-compliant devices **MUST NOT** override any `GrantPolicies` +that have `overridable` set to `false`. + +`GrantOverrides` are included in the `grantOverrides` array of the +`CapabilityConfig` for the Capability in question. + +If both the Firebolt Specification Schema and the Device Schema have +different, valid overrides for the same capability + appId, then the +device config **MUST** be used by that device. + +## 6. Capability Schemas + +This section describes how Capabilities are represented in the static +Firebolt configuration for a device. + +### 6.1. Firebolt Specification Manifest + +Each version of Firebolt **MUST** have a single Firebolt Specification +Manifest that is the source-of-truth for and contains all possible +capabilities provided, used, or managed by Apps or Firebolt platforms. + ++The Firebolt Specification Manifest **MUST** list all capabilities defined by that version of Firebolt. + +The Firebolt Specification Manifest **MUST** specify whether each capability `must`, `should`, or `could` be implemented by Firebolt devices. + +The Firebolt Specification Manifest **MUST** specify whether each role, i.e. `use`, `manage`, and `provide`, is a `public` permission that apps may call. + +See [Invoking Capabilities](#46-invoking-capabilities), for more info on public and negotiable capabilities. + +The Firebolt Specification Manifest **MUST** include the entire Firebolt OpenRPC specification for all APIs in the 'apis` block. + +The Firebolt Specification Manifest **MUST** specify which major versions of the Firebolt RPC APIs are required for backwards compatibility. + +The [Firebolt Version Manifest JSON-Schema](https://github.com/rdkcentral/firebolt-configuration/blob/main/src/schemas/version-manifest/version-manifest.json) defines the JSON semantics for this file. + +The latest version of the firebolt-specification.json **MUST** be available at this URL: + +``` +http://rdkcentral.github.io/firebolt/requirements/latest/specifications/firebolt-specification.json +``` + +The version of the firebolt-specification.json associated with this document **SHOULD** be available at [../../firebolt-specification.json](../../firebolt-specification.json). + +### 6.2. Firebolt Device Manifest + +Each Firebolt device will have a static configuration for overriding +which capabilities are supported, as well as any negotiable Capability +overrides. + +The Device Manifest **MUST** specify which capabilities the device supports. + +The Device Manfiest **MUST** include every capability from the Firebolt Specification Manifest that has a `level` of `must` in its supported list. + +The Device Manifest **MUST** specify which capabilities have distributor define Grant Policy Overrides. + +The Device Manfiest **MUST NOT** have any Grant Policies that override Grant Policies from the Firebolt Specification Manifest that have `overridable` set to `false`. + +The [Firebolt Device Manifest JSON-Schema](https://github.com/rdkcentral/firebolt-configuration/blob/main/src/schemas/device-manifest/device-manifest.json) defines the JSON semantics for this file. + +## 7. Capability to Feature Mapping + +Capabilities denote functionality, and functionality can manifest in several ways. + +### 7.1. App installation + +Some Apps may not be useful, and may even prove counter to their goals, +if installed on a device without certain capabilities. For example, a +Dolby Vision demonstration App that requires it only be installed on +devices that support Dolby Vision, to avoid playing back lower quality +content that users might mistake for Dolby Vision content. + +If an App includes a capability in one of its App Manifest's `required` +Capability lists: + +- `app.capabilities.used.required` + +- `app.capabilities.managed.required` + +- `app.capabilities.provided.required` + +Then that App **MUST NOT** be installable on Firebolt devices that do +not support that capability. + +Apps that have an unsupported capability inside one of its `optional` +lists **SHOULD NOT** be prevented from installation, unless there is +some other reason outside the scope of this document. + +### 7.2. Firebolt APIs + +Some Firebolt APIs may require the use of one or more Capabilities. +These methods **MUST** have all required Capabilities listed in the method's OpenRPC schema. + +Capabilities are listed in one of three OpenRPC extensions attached to +the `'capabilities' `tag on the method: `x-uses`, `x-manages`, +`x-provides`. + +If a method lists more than one Capability for a role, then it may +specify that those capabilities are either all required, any combination +of them is required, or one and only one is required. The platform **MUST parse any `x-uses-operator` values which will have values of either `allOf`, `anyOf`, or `oneOf`. This value defaults to `allOf` if not specified. An example of +this is an API to find and pair remotes, regardless of which connection +protocol is needed. This API requires `anyOf` `bluetooth:scan`, +`rf4ce:scan`, `wifi:scan`. If one or more of these capabilities is +available (and permitted) then the API will execute using the available +and permitted protocols. The same pattern applies to `x-manages-operator`. The `x-provides` extension only supports a single capability, so this pattern does not extend to providers. + +If a method *requires* a capability, and that capability requires a user +grant that the App does not have, then the platform **MUST** block and +initiate a User Grant flow. Once granted, the platform **MUST** return +the expected value without the App having to reinvoke the API. If not +granted after the User Grant flow, the platform **MUST** return an +error. + +Capabilities that enhance an API, but are not fundamentally required, +for example a `play` API optionally uses the `'hdr:dolbyvision'` +capability, **MUST NOT** be listed in the OpenRPC schema. These are considered *optional* capabilities of the method implementation. + +If a method leverages an *optional* Capability that is unavailable or +unpermitted, it **MUST** leave out or defer the optional functionality. + +If a method leverages an *optional* Capability that requires a user +grant the App does not have, it **MUST** leave out the optional +functionality, and it **MUST NOT** request a user grant. + +### 7.3. Extension APIs + +Extension SDKs implement their methods in the cloud but rely on +Firebolt's Permissions and Capabilities model. + +Requirements for Extension SDKS are outside of the scope of this document. + +### 7.4. Hidden Permissions + +A hidden permission arises when an API requires permission to one +Capability which in turn requires another Capability gated by a +different permission. This is not supported by Firebolt, and all +permission dependencies should be validated to avoid this. + +Firebolt Capabilities **MUST NOT** have hidden permissions. + +For example: + +- API `Module.methodOne()` requires permission to `use` the + `'contrived:capability1'` Capability + +- API `Module.methodTwo()` requires permission to `use` the + `'contrived:capability2'` Capability + +- `methodOne`'s implementation calls `methodTwo` + +There is now a hidden permission: `methodOne` requires both +`capability1` and `capabilty2`. + +Note that it's fine for a method to leverage an ungated, but also +unavailable Capability, such as a DIAL API failing because the network +capability is unavailable. + +## 8. Firebolt Capability Catalog + +Firebolt Capabilities are enumeraged in the [Firebolt Specification Manifest](../../firebolt-specification.json). + +## 9. APIs +All of the APIs below have full OpenRPC schemas in the [Firebolt OpenRPC JSON document](../../../specifications/firebolt-open-rpc.json). + +### 9.1. Core SDK APIs + +Several APIs are exposed by the Firebolt Core SDK as part of the +`Capabilities` module. This module is intended for App +developers to have one place to check for all aspects of "can I do +this." Including supported, available, permitted, and granted +Capabilities. It also provides bulk operations for figuring out which +needed Capabilities are unavailable, in order to wait for them, and +which ones are ungranted, in order to request them. + +### 9.2. Manage SDK APIs + +Several APIs are exposed by the Firebolt Manage SDK as part of the +`UserGrants` module. This module is intended for +Management UIs that show a list of grants per App or Capability, and +allow users to revoke them. diff --git a/requirements/specifications/general/capabilities/user-grants.md b/requirements/specifications/general/capabilities/user-grants.md new file mode 100644 index 000000000..f87342a5c --- /dev/null +++ b/requirements/specifications/general/capabilities/user-grants.md @@ -0,0 +1,593 @@ +# User Grants + +Document status: Candidate Specification + +See [Firebolt Requirements Governance](../../../governance.md) for more info. + +| Contributor | Organization | +| -------------- | -------------- | +| Andrew Bennet | Sky | +| Tim Dibben | Sky | +| Jeremy LaCivita | Comcast | +| Kevin Pearson | Comcast | +| Peter Yu | Comcast | + +## 1. Overview + +This document describes the requirements for Firebolt User Grants. User +Grants enable end-user control over which Apps have access to +potentially sensitive Firebolt Capabilities. For example, a user might +want to explicitly approve of any App attempting to purchase new content +by entering an account-holder PIN on the RCU. + +User Grants are also common when two apps need to share data, for +example, Firebolt has a `Discovery.watched` method that allows apps to +inform Firebolt that a user has finished watching some content. This +method allows an app to **provide** the watch history capability and the +aggregated experience to **use** it. See Firebolt +[Capabilities](./capabilities.md) requirements for more info on the `use` and `provide` roles of a +capability. + +This sort of data exchange involves several parties: minimally the user, +the publisher of the OTT app, and the distributor of the Firebolt +device. Additionally, this exchange could also involve privacy laws of +the user\'s home geo-political state, local I.T. best practices around +PII, or even a particular product\'s public position on their privacy +offering to the market. Because of the importance and complexity of +personal data, Firebolt allows each distributor to configure which +Firebolt capabilities require User Grants and what policies should be +applied to acquiring those grants. + +![Diagram Description automatically +generated](../../../images/specifications/general/capabilities/user-grants/image1.png) + +Distributors can configure what kind of user grant is required for a +particular capability, e.g. a simple acknowledgement of an \"OK\" +button, an account-owner PIN entry, an account-owner three-factor +authentication challenge, etc. + +Distributors can also configure whether certain user grants are opt-in +or opt-out, and whether explicit prompting of the user is required. + +## 2. Table of Contents +- [1. Overview](#1-overview) +- [2. Table of Contents](#2-table-of-contents) +- [3. Introduction to User Grants](#3-introduction-to-user-grants) + - [3.1. Active Grant](#31-active-grant) + - [3.2. Denied Grant](#32-denied-grant) + - [3.3. Unset Grant](#33-unset-grant) + - [3.4. Granting Capability](#34-granting-capability) + - [3.5. Grant Policy](#35-grant-policy) + - [3.6. Privacy Setting](#36-privacy-setting) +- [4. User Grant Requirements](#4-user-grant-requirements) + - [4.1. Granting Capability](#41-granting-capability) + - [4.1.1. Acknowledgement](#411-acknowledgement) + - [4.1.2. Pin Challenge](#412-pin-challenge) + - [4.2. Grant Policy](#42-grant-policy) + - [4.2.1. Grant Requirements](#421-grant-requirements) + - [4.2.2. Grant Lifespan](#422-grant-lifespan) + - [4.2.3. Grant Privacy Setting](#423-grant-privacy-setting) + - [4.3. Distributor Overrides](#43-distributor-overrides) + - [4.4. Application Overrides](#44-application-overrides) +- [5. Grant Execution](#5-grant-execution) + - [5.1. Capability Check](#51-capability-check) + - [5.2. Grant Policy Resolution](#52-grant-policy-resolution) + - [5.3. Active Grant Check](#53-active-grant-check) + - [5.4. Grant Prompt and Resolution](#54-grant-prompt-and-resolution) +- [6. Schemas](#6-schemas) + - [6.1. Grant Policy](#61-grant-policy) + - [6.2. GrantRequirements](#62-grantrequirements) + - [6.3. GrantStep](#63-grantstep) + - [6.4. GrantKey](#64-grantkey) + - [6.4.1. GrantScope](#641-grantscope) + - [6.4.2. GrantLifespan](#642-grantlifespan) + - [6.4.3. PrivacySetting](#643-privacysetting) +- [7. APIs](#7-apis) + - [7.1. Manage SDK APIs](#71-manage-sdk-apis) + - [7.1.1. GrantInfo Object](#711-grantinfo-object) + - [7.1.2. App Method](#712-app-method) + - [7.1.3. Device Method](#713-device-method) + - [7.1.4. Capability Method](#714-capability-method) + - [7.1.5. Grant Method](#715-grant-method) + - [7.1.6. Deny Method](#716-deny-method) + - [7.1.7. Clear Method](#717-clear-method) + + +## 3. Introduction to User Grants + +This section defines the key concepts behind the Firebolt User Grant +system. User Grants build on top of [Firebolt +Capabilities](./capabilities.md). +Since Capabilities are fundamental to user grants, it is recommended to +read the Capabilities requirements first before reading this document. + +Each portion of this section provides a background and conversational +definitions of the terms used in the rest of this document, and through +other Firebolt Requirements Specifications. + +As described in the Overview, a User Grant allows an end user to +explicitly allow (or not allow) an app to use certain Firebolt +Capabilities. Firebolt Distributors need flexibility in configuring +which Capabilities require what types of user interaction, PIN vs +password, etc. + +The following concepts inform how the Firebolt User Grant APIs and +architecture are designed. + +### 3.1. Active Grant + +An **Active Grant** is a User Grant that has already been granted by the +user for a Capability to a specific app (if the Grant Policy is per-app) +or all apps. Active Grants do not need to be granted again (until they +expire) and may be revoked or expire. + +### 3.2. Denied Grant + +A **Denied Grant** is a User Grant that has already been explicitly +*denied* by the user for a Capability to a specific app (if the Grant +Policy is per-app) or all apps. Denied Grants do not need to be denied +again (until they expire) and may be revoked or expire. This serves to +allow the Grant Policy lifetime to be applied to explicit denials as +well. + +### 3.3. Unset Grant + +An **Unset Grant** is a User Grant that has no persisted state. This +could be because the user has never granted or denied it, or because it +was previously granted/denied, but has since expired. Additionally, the +user or platform may clear out an active or denied grant, which results +in this state. + +### 3.4. Granting Capability + +User grants typically require some sort of user experience. Firebolt +delegates display of these user experiences to (typically) first-party +apps, which must provide them as **Granting Capabilities**. Therefore, +it\'s quite possible that using a capability such as watch history +initiates a User Grant request which itself requires another capability, +e.g. the \"acknowledge\" capability, to fulfill the original API. + +In the following diagram, an OTT App is calling an API that would share +watch history data with the 1st party aggregated experience on the +device. This capability is configured with a [Grant +Policy](#grant-policy) (see below) that specifies use of an +Acknowledgement Challenge Capability. the \"Watch History\" capability +is what is being accessed, and the \"Acknowledgement Challenge\" +capability is how this device is configured to grant access to that +capability. Said another way, the Acknowledgement Challenge is the +*Granting Capability*. + +![Diagram Description automatically +generated](../../../images/specifications/general/capabilities/user-grants/image2.png) + +Note that the granting capability UI is provided by another app. The +Provider APIs for each granting capability type are out of scope for +this document. + +A granting capability is generally agnostic to the original capability +that it is helping to grant and can be reused by several capabilities +via a Grant Policy. + +### 3.5. Grant Policy + +A **Grant Policy** ties a set of user grant-related configuration values +to a capability. This allows a Firebolt distributor, or the Firebolt +specification itself, to define the business policy of a particular user +grant. + +Grant Policies specify details like how long the grant lasts and what is +the scope of the grant, e.g. a single app, or all apps. + +### 3.6. Privacy Setting + +A **Privacy Setting** is a link between a Grant Policy and any Firebolt API that is tagged with the Property pattern and returns a +`boolean`. This allows User Grant state to be linked to Privacy Settings +on the device or account. + +![Diagram Description automatically +generated](../../../images/specifications/general/capabilities/user-grants/image3.png) + +How Firebolt devices persist Privacy Settings is outside the scope of +this document. + +## 4. User Grant Requirements + +### 4.1. Granting Capability + +A granting capability **MUST** have the category portion of its +capability key set to `usergrant`. For example: + +`xrn:firebolt:capability:usergrant:acknowledge` + +In order for a granting capability to be available, it **MUST** be +provided by some app that is currently loaded. + +Each granting capability **MUST** have a schema, in the Firebolt +Specification Schema, to validate that any configuration associated with +it is valid. + +#### 4.1.1. Acknowledgement + +The Acknowledgement capability enables a user to acknowledge a user +grant by simply clicking a button. + +This capability has the following key: + +`xrn:firebolt:capability:usergrant:acknowledgechallenge` + +The configuration for this capability is always `null`, i.e., there is +no configuration. + +For more info on how an app can provide the acknowledge capability, see +Acknowledge Provider. **TODO**: add link. + +#### 4.1.2. Pin Challenge + +The Pin Challenge capability enables a user to confirm that they are the +account owner, or a delegate of, by responding to a numeric PIN +challenge. + +This capability has the following key: + +`xrn:firebolt:capability:usergrant:pinchallenge` + +For more info on how an app can provide the acknowledge capability, see +Pin Challenge Provider. **TODO**: add link. + +### 4.2. Grant Policy + +If a Capability is configured with a `GrantPolicy` then the User Grants +specified by the Grant Policy **MUST** be evaluated before a GrantPolicy +llowing access to that Capability. + +A Grant Policy **MUST** have a `scope` for the grant, which determines +whether the user will be granting the capability to the current app or +to all apps. + +A Grant Policy **MUST** have an `overridable` flag that determines if it +may be overridden downstream. For Grant Policies in the Firebolt Version +Manifest, the Device Manifest may override if `overridable` is `true`. +For Grant Policies in the Device Manifest, individual [App +Manifests](https://github.com/rdkcentral/firebolt-configuration/src/schemas/app-manifest/app/app.json) may override the grant if `overridable` is `true`. + +#### 4.2.1. Grant Requirements + +A Grant Policy **MUST** have at least one `GrantRequirements` object, +which itself has a list of zero or more [Granting +Capabilities](#granting-capability) and their configurations. If all the +granting capabilities are supported and available, then they all +**MUST** be invoked. This allows for multiple security checks, e.g. +allow watch history data to be collected if the user has opted into +usage data collection **and** they confirm via an acknowledgement +challenge UI. If one or more of the granting capabilities is not +supported or available, then the entire Grant Requirements block is not +valid for acquiring a user grant. + +A Grant Policy **MAY** have more than one `GrantRequirements` object, +which are ranked in order of preference. This allows for low-friction +but high-security methods to be preferred, e.g. allow in-app purchases +with a passive facial recognition scan, with higher-friction fallbacks +to ensure security on devices with less capabilities, e.g. allow in-app +purchases if the account owner performs a multi-factor authentication +flow. This list of `GrantRequirements` objects is stored in the Grant +Policy\'s `options` field. + +If a Grant Policy has more than one `GrantRequirements` option, then the +highest priority list with all its required capabilities supported and +available **MUST** be used. Note that the app which initiated the +original capability check **does not** need to have permission (or a +grant) to any of the granting capabilities that might be invoked. The +app is not using them, the Firebolt device is using them. + +#### 4.2.2. Grant Lifespan + +A Grant Policy **MUST** have a `lifespan`, which determines how long a +grant is valid for. + +> If the lifespan is set to `once`, then any grant resulting from this +> policy **MUST** be active for a single API transaction. +> +> If the lifespan is set to `forever`, then any grant resulting from +> this policy **MUST** be active until explicitly revoked. +> +> If the lifespan is set to `appActive`, then any grant resulting from +> this policy **MUST** be active until the app goes into one of the +> `inactive`, `suspended`, or `unloading` states. +> +> If the lifespan is set to `powerActive`, then any grant resulting from +> this policy **MUST** be active until the device power goes into any +> state other than `active`. +> +> If the lifespan is set to `seconds`, then any grant resulting from +> this policy **MUST** be active until `lifespanTtl` seconds have passed +> since the grant was issued. + +If a Grant Policy has the `lifespan` set to `seconds`, then the +`lifespanTtl` **MUST** be set to a non-zero, positive number of seconds. + +#### 4.2.3. Grant Privacy Setting + +A Grant Policy **MAY** have a `PrivacySetting` object, which +associates any Firebolt `boolean` property API with this Grant Policy. +The Privacy Setting points to the RPC name of the property\'s getter +method. + +The associated property API **MUST** have an `x-allow-value` extension +on the \"property\" tag set to true or false. + +If a Grant Policy has a Privacy Setting, then the `PrivacySetting` +**MUST** be evaluated **before** any `GrantRequirements`. + +> The Privacy Setting **MUST** have an `autoApplyPolicy` which **MUST** +> be one of the following values: +> +> `always` - Silently grant if the getter for the `property` returns the +> property\'s `x-allow-value`. Silently deny if the getter for the +> `property` returns `!x-allow-value`. +> +> `allowed` - Silently grant if the getter for the `property` returns +> the property\'s `x-allow-value`. +> +> `disallowed` - Silently deny if the getter for the `property` returns +> the property\'s `!x-allow-value`. +> +> `never` - Do not silently grant or deny based on this Grant Policy. +> +> If the Privacy Setting has `revokeGrantsOnDisallow` set to `true`, +> then **all active** user grants that resulted from this Grant Policy +> **MUST** be revoked if and when the property value specified by +> `property` ever changes to `!x-allow-value`. This enables +> distributors to decide whether changes to a Privacy Setting affects +> only new User Grants or existing, active User Grants as well. +> +> If the Privacy Setting has `updateProperty` set to `true`, then a +> successful user grant from this Grant Policy **MUST** also result in +> updating the property value specified by `property` to +> `x-allow-value`. +> +> If the Privacy Setting has `updateProperty` set to `true`, then a +> rejected **or expiring** user grant from this Grant Policy **MUST** +> also result in updating the property value specified by `property` to +> `!x-allow-value`. This is considered a \"disallow\" and +> **MUST** initiate evaluation of the `revokeGrantsOnDisallow` value. +> +> If the Grant Policy `scope` is set to `app` then the property +> specified by `property` **MUST** have a single context +> parameter of type `string` and the requesting appId **MUST** be passed +> to all get/set/subscribe calls fulfilling this section of requirements. + +### 4.3. Distributor Overrides + +Capability Grant Policies in the Firebolt Version Manifest are designed +to be overridden by Distributors to allow for different privacy use +cases across businesses and geographic regions. These overrides go in +the Device Manifest under the `grantPolicies` section of the +`capabilities` section. + +Distributor overrides **MUST** be for Grant Policies that are +`overridable`. + +See the [Firebolt Configuration Schemas +repository](https://github.com/rdkcentral/firebolt-configuration/) for +more information on the Firebolt Version Manifest and Device Manifest. + +### 4.4. Application Overrides + +Firebolt supports creating active grants via the App manifest, which +allows distributors and App publishers to decide that a particular app +will already be granted some capability. This is typically used for +first-party apps that come pre-installed but could be used for other +purposes. + +If an app has a role/capability listed in its App Manifest, then it is +considered to have an active grant for that capability if the manifest +has a valid signature. + +App Manifests overrides **MUST** be for Grant Policies that are +`overridable` and scoped to `app`. + +See the [Firebolt Configuration Schemas +repository](https://github.com/rdkcentral/firebolt-configuration/) for +more information on Firebolt App Manifests. + +## 5. Grant Execution + +When a Firebolt API is called the platform **MUST** first collate all +the device User Grant configurations that apply to every capability that +the API uses. This list **MUST** then be filtered to remove any User +Grants that have already been granted for the current capability for +this app and role. + +### 5.1. Capability Check + +First, all capabilities necessary to fulfill the API are collected. + +![](../../../images/specifications/general/capabilities/user-grants/image4.png) + +### 5.2. Grant Policy Resolution + +Next, each capability is checked to see if there is a Firebolt, +Distributor, or App Grant Policy that applies, and that none of them are +invalid, e.g. an override that is now allowed. + +![Diagram Description automatically +generated](../../../images/specifications/general/capabilities/user-grants/image5.png) + +### 5.3. Active Grant Check + +Then, each Grant Policy is evaluated to see if there is already an +active grant, or if it is linked to a Privacy Setting configured to skip +user-prompts. + +![Diagram Description automatically +generated](../../../images/specifications/general/capabilities/user-grants/image6.png) + +### 5.4. Grant Prompt and Resolution + +Finally, each needed Granting Capability is invoked to present a UX to +the end user, and any linked Privacy Settings are updated as +appropriate. If all succeeds, then the API is invoked. + +![Diagram Description automatically +generated](../../../images/specifications/general/capabilities/user-grants/image7.png) + +## 6. Schemas + +The following schemas give an overview of the schemas outlined by this +document. See the [Firebolt Configuration Schemas +repository](https://github.com/rdkcentral/firebolt-configuration/) for +the latest versions of these schemas. + +### 6.1. Grant Policy + +Grant Policies have the following properties. + +| Property | Type | Description | +|-------------|-----------------------|-------------------------------------| +| `options` | `GrantRequirements[]` | An array of GrantRequirements, any one of which could be used to Grant a requested capability/role to an App. The first one that is completely supported by the current device should be used. | +| `scope` | `string` | Whether the resulting user grant applies to all Apps or just the requesting App. | +| `lifespan` | `string` | How long the resulting user grant (or deny) will last. | +| `lifespanTtl` | `integer` | If lifespan is `'seconds'` this represents the number of seconds. | +| `privacySetting` | `PrivacySetting` | Links this Grant Policy to a privacy setting. | +| `overridable` | `boolean` | Whether a distributor may override this GrantPolicy with their own. | + +### 6.2. GrantRequirements + +A list of `GrantSteps` objects describing which capabilities and any +optional configuration needed to fulfill this grant policy. These +capabilities must be from the capability category `usergrant` which +denotes special capabilities that perform user grants, e.g. an +acknowledge challenge capability. + +| Property | Type | Description | +|-------------|-----------------|-------------------------------------------| +| `steps` | `GrantStep[]` | An array of GrantSteps, all of which need to be verified to fulfill this GrantPolicy. | + +### 6.3. GrantStep + +| Property | Type | Description | +|-------------|----------------|-------------------------------------------| +| `capability` | `string` | The Granting Capability to use for this step in the grant flow. | +| `configuration ` | `object` | The configuration for the Granting Capability, which is specific to each type. | + +### 6.4. GrantKey + +A CapabilityKey with the \ set to `usergrant`: + +`/\^xrn:firebolt:capability:usergrant:\[a-zA-Z0-9\\-\]{1,32}\$/` + +#### 6.4.1. GrantScope + +A `string` enumeration. + +| Value | Description | +|----------------|--------------------------------------------------------| +| `device` | The resulting user grant will apply to all Apps on the device. | +| `app` | The resulting user grant will apply to the requesting App only. | + +#### 6.4.2. GrantLifespan + +A `string` enumeration. + +The resulting user grant will only be valid: + +| Value | Description | +|----------------|--------------------------------------------------------| +| `once` | for a single usage, e.g. one API call. | +| `forever` | until the end of time. | +| `appActive` | until the app enters a non-Active Lifecycle state: inactive, suspended | +| `powerActive` | until the device leaves the Active power state. | +| `seconds` | until \ seconds have passed. | + +#### 6.4.3. PrivacySetting + +| Value | | Description | +|--------------------|----------|------------------------------------------| +| `property` | string | The fully qualified RPC method name of the associated property setter, e.g. `Privacy.limitAdTracking` | +| `autoApplyPolicy` | string | Set the auto grant policy to `always`, `allowed`, `disallowed`, `never` | +| `revokeGrantsOnDisallow` | boolean | Any grants made from this policy will be revoked if/when the property is ever set to the deny value | +| `updateProperty` | boolean | Whether to update the property value to match the grant. | + +## 7. APIs + +APIs for User Grants are covered in the [Capabilities Requirements +document](./capabilities.md). + +### 7.1. Manage SDK APIs + +These APIs are intended for trusted apps to expose a UI for end-users to +manage the grants given to the device and various apps. Permission for +these APIs should only be given to a trusted settings app performing +this function. + +#### 7.1.1. GrantInfo Object + +Object describing a persisted active or denied Grant. + +```typescript +type GrantInfo = { + appId: string, + state: "active" | "denied", + capability: string, + role: "use" | "manage" | "provide" + lifespan: "once" | "forever" | "appActive" | " powerActive" | "seconds" + expires: integer +} +``` + +#### 7.1.2. App Method + +Returns all active and denied user grants for the given App, **NOT** +including those granted to all apps via the device. + +```typescript +UserGrants.app(appId: string): GrantInfo[] +``` + +#### 7.1.3. Device Method + +Returns all active and denied user grants for the Device. + +```typescript +UserGrants.device(): GrantInfo[] +``` + +#### 7.1.4. Capability Method + +Returns all active and denied user grants for the given Capability. + +```typescript +UserGrants.capability(capability: string): GrantInfo [] +``` + +#### 7.1.5. Grant Method + +Grants a given Capability, to a specific app if appropriate. Calling +this results in a persisted Active Grant that lasts for the duration of +the Grant Policy lifespan. + + +```typescript +UserGrants.grant(role: string, capability: string, appId?:string): void +``` + +#### 7.1.6. Deny Method + +Denies a given Capability, to a specific app if appropriate. Calling +this results in a persisted Denied Grant that lasts for the duration of +the Grant Policy lifespan. + +```typescript +UserGrants.deny(role: string, capability: string, appId?: string):void +``` + +#### 7.1.7. Clear Method + +Clears any persisted active or denied grant for a Capability, for a +specific app if appropriate. This results in an Unset Grant. This method +may take a wildcard value of `'*'` for role, capability, or appId, in +order to clear grant state in bulk. + +```typescript +UserGrants.clear(role: string, capability: string, appId?:string): void +``` diff --git a/requirements/specifications/localization/language.md b/requirements/specifications/localization/language.md new file mode 100644 index 000000000..0b3df80ef --- /dev/null +++ b/requirements/specifications/localization/language.md @@ -0,0 +1,99 @@ +# Language Settings + +Document Status: Candidate Specification + +See [Firebolt Requirements Governance](../../governance.md) for more info. + +| Contributor | Organization | +| -------------- | -------------- | +| Jeremy LaCivita | Comcast | +| Kevin Pearson | Comcast | +| Tim Dibben | Sky | + +## 1. Overview + +This document describes the requirements that Firebolt platforms must +fulfill when surfacing user language preferences. + +Exposing these settings, e.g. the main device language, or a list of +preferred audio languages, allows Apps to respect the device's current +setting so that the user has a seamless experience when switching from +app to app. + +This document covers how Firebolt platforms manage language settings and +expose to Apps. It does not cover the use cases Apps might apply these +APIs to. + +The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**NOT RECOMMENDED**", "**MAY**", and "**OPTIONAL**" in this document are to be interpreted as described in [BCP 14](https://www.rfc-editor.org/rfc/rfc2119.txt) [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +- [1. Overview](#1-overview) +- [2. Language](#2-language) +- [3. Locale](#3-locale) +- [4. Preferred Audio Languages](#4-preferred-audio-languages) +- [5. Core SDK APIs](#5-core-sdk-apis) +- [6. Manage SDK APIs](#6-manage-sdk-apis) + +## 2. Language + +Language describes the ISO 639 1/2 code for the preferred language on +this device. All Apps **SHOULD** generally render their user experience +in this language. This is a guideline, not an absolute requirement, +since different Apps may have different target audiences with differing +languages prevalent within those audiences. + +This setting is represented by a mutable property which is a string +conforming to the ISO 639 1/2 standard, e.g. `'en'`. + +## 3. Locale + +Locale describes the *full* BCP 47 code, including script, region, +variant, etc., for the preferred language/locale on this device. Apps +**MAY** alter their user experience to match this locale to account for +local differences in the same language. + +This setting is represented by a mutable property which is a string +conforming to the full BCP 47 standard, e.g. `'en-US'`. + +## 4. Preferred Audio Languages + +The preferred audio languages setting provides a ranked list of +languages that the user prefers to be selected on this device. All +values are from the ISO 639 1/2 standard. Apps **MAY** use this list to +influence selection of an initial audio track when playing content with +multiple languages. For example, a bilingual user living in an English +speaking country may have the `language` set to `'en`\' and the +`preferredAudioLanguages` set to `['fr', 'en']`. This +enables them to typically consume content from apps whose catalogs are +mostly filmed in English, but automatically get the French language +track when watching a French movie that has both French and English +tracks. + +This setting is represented by a mutable property which is an array of +strings conforming to the ISO 639 1/2 standard, e.g. `'en'`. + +## 5. Core SDK APIs + +The following APIs are exposed by the Firebolt Core SDK as part of the +`core:localization` domain/module. + +Each of these APIs a read-only property. + +- `Localization.language():Promise` + +- `Localization.locale():Promise` + +- `Localization.preferredAudioLanguages():Promise` + +- `Localization.onLanguageChanged():Promise` + +- `Localization.onLocaleChanged():Promise` + +- `Localization.onPreferredAudioLanguagesChanged():Promise` + +## 6. Manage SDK APIs + +The following APIs are exposed by the Firebolt Manage SDK as part of the +`manage` domain. + +The Manage SDK APIs inclueare identical to the Core SDK, except that all +property APIs are mutable. diff --git a/requirements/specifications/openrpc-extensions/app-passthrough-apis.md b/requirements/specifications/openrpc-extensions/app-passthrough-apis.md index ec23922e6..826f7bed3 100644 --- a/requirements/specifications/openrpc-extensions/app-passthrough-apis.md +++ b/requirements/specifications/openrpc-extensions/app-passthrough-apis.md @@ -216,32 +216,18 @@ If the value was composed into the platform method result under a matching prope Finally the platform **MUST** dispatch the notification to the app that registered for the event via the original platform method, using all but the last parameter as context. ## 5. Provider Candidates -The Firebolt Device Manifist **MUST** have a list of `ProviderPolicy` configurations that map capabilities to policies for determining candidate providers: - -```json -{ - "providerPolicies": [ - { - "inFocus": true, - "capabilities": [ - "xrn:firebolt:capability:foo:bar" - ] - } - ] -} -``` -The policy **MUST** have a list of capabilities that it is applied to. - -A capability **MUST NOT** be included in more than one policy. - -The policy **MAY** have an `inFocus` boolean. - -If the policy has `inFocus` set to `true` then any app without RCU input focus when the capability is invoked **MUST NOT** be considered a candidate. +When a platform method with an `x-provided-by` extension is called, then +all loaded apps that have permission to provide the capability **MUST** be +considered as candidates to fulfill the method. ## 6. Best Candidate -If there is only one candidate then it **MUST** be the best candidate. +Any provider candidates that have not registered to provide the method in +question **MUST NOT** be considered the best candidate and removed from +consideration. + +If there is only one candidate left then it **MUST** be the best candidate. -If there is more than one candidate, then the candidate app that most recently had RCU input focus **MUST** be the best candidate. +If there is more than one candidate left, then the candidate app that most recently had RCU input focus **MUST** be the best candidate. If none of the candidates have had focus yet, then the candidate app that was most recently launched **MUST** be the best candidate. diff --git a/src/openrpc/discovery.json b/src/openrpc/discovery.json index 49b7e20aa..c3706de03 100644 --- a/src/openrpc/discovery.json +++ b/src/openrpc/discovery.json @@ -54,8 +54,7 @@ "x-provides": "xrn:firebolt:capability:discovery:entity-info" }, { - "name": "deprecated", - "x-alternative": "Discovery.details" + "name": "deprecated" } ], "summary": "Provide information about a program entity and its available watchable assets, such as entitlement status and price, via either a push or pull call flow.", @@ -430,8 +429,7 @@ "x-provides": "xrn:firebolt:capability:discovery:purchased-content" }, { - "name": "deprecated", - "x-alternative": "Discovery.purchases" + "name": "deprecated" } ], "summary": "Provide a list of purchased content for the authenticated account, such as rentals and electronic sell through purchases.", diff --git a/src/sdks/core/package.json b/src/sdks/core/package.json index 13c9535b3..7df598348 100644 --- a/src/sdks/core/package.json +++ b/src/sdks/core/package.json @@ -1,6 +1,6 @@ { "name": "@firebolt-js/sdk", - "version": "1.2.0-next.4", + "version": "1.2.0-next.5", "description": "The Firebolt JS SDK", "main": "./dist/lib/firebolt.mjs", "types": "./dist/lib/firebolt.d.ts", diff --git a/src/sdks/manage/package.json b/src/sdks/manage/package.json index 9f3cbc6d3..86fb19a67 100644 --- a/src/sdks/manage/package.json +++ b/src/sdks/manage/package.json @@ -1,6 +1,6 @@ { "name": "@firebolt-js/manage-sdk", - "version": "1.2.0-next.4", + "version": "1.2.0-next.5", "description": "The Firebolt Manage JS SDK", "main": "./dist/lib/firebolt-manage.mjs", "types": "./dist/lib/firebolt-manage.d.ts",