index.bs

<pre class="metadata">
Title: Ambient Light Sensor
Level: none
Status: ED
ED: https://w3c.github.io/ambient-light/
Shortname: ambient-light
TR: https://www.w3.org/TR/ambient-light/
Editor: Anssi Kostiainen 41974, Intel Corporation, https://intel.com/
Editor: Rijubrata Bhaumik 80407, Intel Corporation, https://intel.com/
Former Editor: Tobie Langel 60809, Codespeaks&#44; formerly on behalf of Intel Corporation, https://tobie.me, tobie@codespeaks.com
Former Editor: Doug Turner, Mozilla Corporation, https://mozilla.com/
Group: dap
Abstract:
  This specification defines a concrete sensor interface to monitor
  the ambient light level or illuminance of the device's environment.
Status Text:
  The Devices and Sensors Working Group is pursuing modern security and privacy
  reviews for this specification in consideration of the amount of change in both
  this specification and in privacy and security review practices since the
  horizontal reviews <a
  href="https://github.com/w3c/sensors/issues/299#issue-262392533">took place
  on 3 October 2017</a>. Similarly, the group is pursuing an update to the Technical
  Architecture Group review for this specification to account for the latest
  architectural review practices.
Version History: https://github.com/w3c/ambient-light/commits/main/index.bs
Indent: 2
Repository: w3c/ambient-light
Markup Shorthands: markdown on
Inline Github Issues: off
!Issue Tracking: <a href="https://github.com/w3c/ambient-light/milestones/Level%202">Level 2 Issues</a>
Test Suite: https://github.com/web-platform-tests/wpt/tree/master/ambient-light
Default Biblio Status: current
</pre>
<pre class="anchors">
urlPrefix: https://w3c.github.io/sensors/; spec: GENERIC-SENSOR
  type: dfn
    text: high-level
    text: implementation specific; url: implementation-specific
    text: reporting mode; url: reporting-modes
    text: auto
    text: construct a sensor object; url: construct-sensor-object
    text: limit maximum sampling frequency; url: limit-max-frequency
    text: reduce accuracy; url: reduce-accuracy
    text: mitigation strategies; url: mitigation-strategies
    text: sampling frequency
    text: sensor type
    text: automation
    text: mock sensor type
    text: MockSensorType
    text: mock sensor reading values
    text: latest reading
urlPrefix: https://tc39.es/ecma262/; spec: ECMA-262
  type: abstract-op
    text: abs; url: eqn-abs
</pre>

<pre class=biblio>
{
  "ALSPRIVACYANALYSIS": {
    "title": "Privacy analysis of Ambient Light Sensors",
    "authors": [
      "Lukasz Olejnik"
    ],
    "href": "https://blog.lukaszolejnik.com/privacy-of-ambient-light-sensors/",
    "id": "ALSPRIVACYANALYSIS",
    "date": "31 August 2016"
  },
  "PINSKIMMINGVIASENSOR": {
    "title": "PIN Skimming: Exploiting the Ambient-Light Sensor in Mobile Devices",
    "authors": [
      "Raphael Spreitzer"
    ],
    "href": "https://arxiv.org/abs/1405.3760",
    "id": "PINSKIMMINGVIASENSOR",
    "date": "15 May 2014"
  },
  "STEALINGSENSITIVEDATA": {
    "title": "Stealing sensitive browser data with the W3C Ambient Light Sensor API",
    "authors": [
      "Lukasz Olejnik"
    ],
    "href": "https://blog.lukaszolejnik.com/stealing-sensitive-browser-data-with-the-w3c-ambient-light-sensor-api/",
    "id": "STEALINGSENSITIVEDATA",
    "date": "19 April 2017"
  },
  "VIDEORECOGNITIONAMBIENTLIGHT": {
    "title": "Video recognition using ambient light sensors",
    "authors": [
      "Raphael Spreitzer"
    ],
    "href": "https://doi.org/10.1109/PERCOM.2016.7456511",
    "id": "VIDEORECOGNITIONAMBIENTLIGHT",
    "publisher": "IEEE",
    "date": "21 April 2016"
  }
}
</pre>

Introduction {#intro}
============

The Ambient Light Sensor extends the Generic Sensor API [[GENERIC-SENSOR]]
to provide information about ambient light levels,
as detected by the device's main light detector, in terms of lux units.

Scope {#scope}
-----

This document specifies an API designed for [[#usecases-requirements|use cases]]
which require fine grained illuminance data, with low latency, and possibly
sampled at high frequencies.

Common use cases relying on a small set of illuminance values, such as styling
webpages according to contrast level or preferred color scheme that may be
influenced by a device's measured ambient light level are best served by the the
`prefers-contrast` and `prefers-color-scheme` CSS media features
[[MEDIAQUERIES-5]] as well as the accompanying `matchMedia` API
[[CSSOM-VIEW-1]] and are out of scope of this API.

Note: The [[MEDIAQUERIES-5]] specification used to contain a `light-level`
media feature that was more directly tied to ambient light readings. It has
since been <a
href="https://github.com/w3c/csswg-drafts/commit/f5b663c27d5a2715239633f4916880563969d770">dropped</a>
from the specification in favor of the higher-level `prefers-color-scheme` and
`prefers-contrast` media features.

Examples {#examples}
========

<div class="example">
    In this simple example, ambient light sensor is created with
    default configuration. Whenever a new [=sensor readings|reading=] is available,
    it is printed to the console.

    <pre highlight="js">
    const sensor = new AmbientLightSensor();
    sensor.onreading = () => console.log(sensor.illuminance);
    sensor.onerror = event => console.log(event.error.name, event.error.message);
    sensor.start();
    </pre>
</div>

<div class="example">
    In this example, the exposure value (EV) at ISO 100 is calculated from
    the ambient light [=sensor readings=]. Initially, we check that the user
    agent has permissions to access ambient light [=sensor readings=]. Then,
    the {{AmbientLightSensor/illuminance!!attribute}} value is converted to the
    closest exposure value.

    <pre highlight="js">
    navigator.permissions.query({ name: 'ambient-light-sensor' }).then(result => {
        if (result.state === 'denied') {
            console.log('Permission to use ambient light sensor is denied.');
            return;
        }

        const als = new AmbientLightSensor({frequency: 20});
        als.addEventListener('activate', () => console.log('Ready to measure EV.'));
        als.addEventListener('error', event => console.log(\`Error: ${event.error.name}\`));
        als.addEventListener('reading', () => {
            // Defaut ISO value.
            const ISO = 100;
            // Incident-light calibration constant.
            const C = 250;

            let EV = Math.round(Math.log2((als.illuminance * ISO) / C));
            console.log(\`Exposure Value (EV) is: ${EV}\`);
        });

        als.start();
    });
    </pre>
</div>

<div class="example">
    This example demonstrates how ambient light [=sensor readings=] can be mapped
    to recommended workplace light levels.

    <pre highlight="js">
    const als = new AmbientLightSensor();

    als.onreading = () => {
        let str = luxToWorkplaceLevel(als.illuminance);
        if (str) {
            console.log(\`Light level is suitable for: ${str}.\`);
        }
    };

    als.start();

    function luxToWorkplaceLevel(lux) {
        if (lux > 20 && lux < 100) {
            return 'public areas, short visits';
        } else if (lux > 100 && lux < 150) {
            return 'occasionally performed visual tasks';
        } else if (lux > 150 && lux < 250) {
            return 'easy office work, classes, homes, theaters';
        } else if (lux > 250 && lux < 500) {
            return 'normal office work, groceries, laboratories';
        } else if (lux > 500 && lux < 1000) {
            return 'mechanical workshops, drawing, supermarkets';
        } else if (lux > 1000 && lux < 5000) {
            return 'detailed drawing work, visual tasks of low contrast';
        }

        return;
    }
    </pre>
</div>

Security and Privacy Considerations {#security-and-privacy}
===================================

<p tracking-vector>Ambient Light Sensor provides information about lighting conditions near
the device environment. Potential privacy risks include:

  - Profiling. Ambient Light Sensor can leak information about user's use
    patterns and surrounding. This information can be used to enhance user
    profiling and behavioral analysis.
  - Cross-device linking. Two devices can access web sites that include the
    same third-party script that correlates lighting levels over time.
  - Cross-device communication. A simple broadcast communication method can
    use device screen or camera LED flashes to broadcast messages read
    out with an Ambient Light Sensor in a close by device.
  - Cross-origin leaks. Light emitted from the screen can be reflected back to
    the sensor from nearby reflective surfaces. Malicious sites can embed
    resources from different origins and scale the content to display
    particular pixels to allow distinguishing the contents, pixel by pixel.
  - Hijacking browsing history. Styling visited links to allow distinguishing
    the light levels associated with visited and unvisited links i.e. visited
    links styled as a block of black screen; white for unvisited.

Works such as [[ALSPRIVACYANALYSIS]], [[PINSKIMMINGVIASENSOR]],
[[STEALINGSENSITIVEDATA]], and [[VIDEORECOGNITIONAMBIENTLIGHT]] delve further
into these issues.

To mitigate these threats specific to Ambient Light Sensor, user agents must
<a>reduce accuracy</a> of sensor readings. User agents may also <a>limit
maximum sampling frequency</a>.

These mitigation strategies complement the [=mitigation strategies|generic mitigations=]
defined in the Generic Sensor API [[!GENERIC-SENSOR]].

Reducing sensor readings accuracy {#reduce-sensor-accuracy}
-----

In order to [=reduce accuracy=] of sensor readings, this specification defines
a [=threshold check algorithm=] (the [=ambient light threshold check
algorithm=]) and a [=reading quantization algorithm=] (the [=ambient light
reading quantization algorithm=]).

These algorithms make use of the [=illuminance rounding multiple=] and the
[=illuminance threshold value=]. Implementations must adhere to the following
requirements for their values:

  - The [=illuminance rounding multiple=] must be at least 50 lux.
  - The [=illuminance threshold value=] should be at least half of the
    [=illuminance rounding multiple=].

Note: Choosing an [=illuminance rounding multiple=] requires balancing not
exposing readouts that are too precise while also providing readouts that are
still useful for API users. The value of 50 lux as a minimum for the
[=illuminance rounding multiple=] was determined in <a
href="https://github.com/w3c/ambient-light/issues/13#issuecomment-302393458">GitHub
issue #13</a> after different ambient light level measurements under different
lighting conditions were <a
href="https://docs.google.com/spreadsheets/d/1vUojkaaif6AmftQmtqra1w9Z7CH00Cn9pb0Ci6v5_Jk">gathered
</a> and shown to thwart the attack described in [[STEALINGSENSITIVEDATA]]. 50
lux is also higher than the 5 lux required to make video recognition using
ambient light sensor readings ([[VIDEORECOGNITIONAMBIENTLIGHT]]) infeasible.

Note: The [=illuminance threshold value=] is used to prevent leaking the fact
that readings are hovering around a particular value but getting quantized to
different values. For example, if [=illuminance rounding multiple=] is 50, this
prevents switching the illuminance value between 0 and 50 if the raw readouts
switch between 24 and 26. The efficacy of the [=threshold check algorithm=] as
an auxiliary fingerprinting mitigation strategy has not been mathematically
proven, but it has been added to this specification based on implementation
experience. <a href="https://crbug.com/1332536">Chromium bug 1332536</a> and <a
href="https://crrev.com/c/3666917">Chromium review 3666917</a> contain more
information about this.

Model {#model}
=====

The <dfn>Ambient Light Sensor</dfn> <a>sensor type</a>'s associated {{Sensor}}
subclass is the {{AmbientLightSensor}} class.

The <a>Ambient Light Sensor</a> has a <a>default sensor</a>,
which is the device's main light detector.

The <a>Ambient Light Sensor</a> is a [=powerful feature=] that is identified by
the [=powerful feature/name=] "<dfn permission export>ambient-light-sensor</dfn>",
which is also its associated [=sensor permission name=]. Its
[=powerful feature/permission revocation algorithm=] is the result of calling
the [=generic sensor permission revocation algorithm=] with
"ambient-light-sensor".

The <a>Ambient Light Sensor</a> is a [=policy-controlled feature=] identified by the string "ambient-light-sensor". Its [=default allowlist=] is `'self'`.

The <dfn>current light level</dfn> or <dfn>illuminance</dfn>
is a value that represents the ambient light level
around the hosting device. Its unit is the lux (lx) [[SI]].

Note: The precise lux value reported by
different devices in the same light can be different,
due to differences in detection method, sensor construction, etc.

The <a>Ambient Light Sensor</a> has an <dfn>illuminance rounding
multiple</dfn>, measured in lux, which represents a number whose multiples the
illuminance readings will be rounded up to.

The <a>Ambient Light Sensor</a> has an <dfn>illuminance threshold value</dfn>,
measured in lux, which is used in the [=ambient light threshold check
algorithm=].

Note: see [[#reduce-sensor-accuracy]] for minimum requirements for the values
described above.

API {#api}
===

The AmbientLightSensor Interface {#ambient-light-sensor-interface}
--------------------------------

<pre class="idl">
  [SecureContext, Exposed=Window]
  interface AmbientLightSensor : Sensor {
    constructor(optional SensorOptions sensorOptions = {});
    readonly attribute double? illuminance;
  };
</pre>

To construct an {{AmbientLightSensor}} object the user agent must invoke the
[=construct an ambient light sensor object=] abstract operation.

### The illuminance attribute ### {#ambient-light-sensor-reading-attribute}

The {{AmbientLightSensor/illuminance}} getter steps are:

1. Let |illuminance| be the result of invoking [=get value from latest
   reading=] with [=this=] and "illuminance" as arguments.
1. Return |illuminance|.

Abstract Operations {#abstract-operations}
===================

<h3 dfn export>Construct an ambient light sensor object</h3>

<div algorithm="construct an ambient light sensor object">

    : input
    :: |options|, a {{SensorOptions}} object.
    : output
    :: An {{AmbientLightSensor}} object.

    1.  Let |allowed| be the result of invoking [=check sensor policy-controlled features=]
        with {{AmbientLightSensor}}.
    1.  If |allowed| is false, then:
        1.  [=Throw=] a {{SecurityError}} {{DOMException}}.
    1.  Let |ambient_light_sensor| be the new {{AmbientLightSensor}} object.
    1.  Invoke [=initialize a sensor object=] with |ambient_light_sensor| and |options|.
    1.  Return |ambient_light_sensor|.
</div>

<h3 dfn>Ambient light threshold check algorithm</h3>

The [=Ambient Light Sensor=] [=sensor type=] defines the following [=threshold
check algorithm=]:

<div algorithm="ambient light threshold check">
  : input
  :: |newReading|, a [=sensor reading=]
  :: |latestReading|, a [=sensor reading=]
  : output
  :: A [=boolean=] indicating whether the difference in readings is
     significant enough.

  1. If |newReading|["illuminance"] is null, return true.
  1. If |latestReading|["illuminance"] is null, return true.
  1. Let |newIlluminance| be |newReading|["illuminance"].
  1. Let |latestIlluminance| be |latestReading|["illuminance"].
  1. If [$abs$](|latestIlluminance| - |newIlluminance|) < [=illuminance
     threshold value=], return false.
  1. Let |roundedNewReading| be the result of invoking the [=ambient light
     reading quantization algorithm=] algorithm with |newIlluminance|.
  1. Let |roundedLatestReading| be the result of invoking the [=ambient
     light reading quantization algorithm=] algorithm with |latestIlluminance|.
  1. If |roundedNewReading|["illuminance"] and |roundedLatestIlluminance|["illuminance"]
     are equal, return false.
  1. Otherwise, return true.
</div>

Note: This algorithm invokes the [=ambient light reading quantization
algorithm=] to ensure that readings that round up to the same value do not
trigger an update in the main [=update latest reading=] algorithm. Not doing so
would indicate to users that the raw illuminance readings are within a range
where they differ by at least the [=illuminance threshold value=] but do not
round up to different [=illuminance rounding multiple=].

<h3 dfn>Ambient light reading quantization algorithm</h3>

The [=Ambient Light Sensor=] [=sensor type=] defines the following [=reading
quantization algorithm=]:

<div algorithm="ambient light reading quantization">
  : input
  :: |reading|, a [=sensor reading=]
  : output
  :: A [=sensor reading=]

  1. Let |quantizedReading| be |reading|.
  1. Set |quantizedReading|["illuminance"] to the multiple of the [=illuminance
     rounding multiple=] that |reading|["illuminance"] is closest to.
  1. Return |quantizedReading|.
</div>

Automation {#automation}
==========
This section extends the [=automation=] section defined in the Generic Sensor API [[GENERIC-SENSOR]]
to provide mocking information about the ambient light levels for the purposes of testing a user agent's
implementation of [=Ambient Light Sensor=].


<h3 id="mock-ambient-light-sensor-type">Mock Sensor Type</h3>

The {{AmbientLightSensor}} class has an associated [=mock sensor type=] which is
<a for="MockSensorType" enum-value>"ambient-light"</a>, its [=mock sensor reading values=]
dictionary is defined as follows:

<pre class="idl">
  dictionary AmbientLightReadingValues {
    required double? illuminance;
  };
</pre>

Use Cases and Requirements {#usecases-requirements}
=========

- A Web application provides input for a smart home system to control lighting.
- A Web application checks whether light level at work space is sufficient.
- A Web application calculates settings for a camera with manual controls (aperture, shutter speed, ISO).
- A Web application checks the current light level to determine whether a
  camera stream will contain data that is accurate enough for its purposes
  (e.g. human presence verification).

While some of the use cases may benefit from obtaining precise ambient light measurements, the use
cases that convert ambient light level fluctuations to user input events would benefit from
higher [=sampling frequency|sampling frequencies=].

Acknowledgements {#acknowledgements}
================

Doug Turner for the initial prototype and
Marcos Caceres for the test suite.

Paul Bakaus for the LightLevelSensor idea.

Mikhail Pozdnyakov and Alexander Shalamov for the use cases and requirements.

Lukasz Olejnik for the privacy risk assessment.