JavaScript API for Device Bound Session Credentials

1. Introduction

For now, see the explainer.

This spec is an early-stage draft. Missing details and remaining TODOs are called out with Issue: blocks.

2. Security considerations

3. Privacy considerations

4. Framework

4.1. Observer store

The user agent maintains an observer store. It is a set of weak references to DeviceBoundSessionsObserver objects. The store is initially empty.

When an observer has been reclaimed by garbage collection, it must be removed from the store.

4.2. Registration buffer and store

The user agent maintains a registration attempts store. It is a map from storage key to registration buffer. The store is initially empty.

Should we make this a formal storage endpoint?

A registration buffer is a list of DeviceBoundSessionRegistrationReports. Each buffer is initially empty.

User agents should put a reasonable limit on the number of attempts stored in each buffer and their time-to-live.

5. The DeviceBoundSessionsObserver interface

This interface can be used to observe device bound sessions and registration attempts.

[Exposed=Window, SecureContext]
interface DeviceBoundSessionsObserver {
  constructor(
    DeviceBoundSessionsObserverCallback callback,
    optional DeviceBoundSessionsObserverOptions options = {}
  );
  undefined observe();
  undefined disconnect();
  sequence<DeviceBoundSessionsReport> takeRecords();
};

callback DeviceBoundSessionsObserverCallback = undefined (
  sequence<DeviceBoundSessionsReport> reports,
  DeviceBoundSessionsObserver observer
);

A DeviceBoundSessionsObserver has an associated callback (a DeviceBoundSessionsObserverCallback) and an associated options (a DeviceBoundSessionsObserverOptions).

5.1. DeviceBoundSessionsObserverOptions dictionary

dictionary DeviceBoundSessionsObserverOptions {
  AbortSignal signal;
};

signal, of type AbortSignal

The abort event stops the observer from receiving further reports.

5.2. observe() method

5.3. disconnect() method

5.4. takeRecords() method

5.5. Report types

enum DeviceBoundSessionsReportKind {
  "session",
  "registration"
};

dictionary DeviceBoundEstablishedSessionReport {
  required DeviceBoundSessionsReportKind type;
  required DOMString sessionOrigin;
  required DOMString sessionId;
  required DOMString refreshUrl;
  required DOMHighResTimeStamp creationTime;
};

dictionary DeviceBoundSessionRegistrationReport {
  required DeviceBoundSessionsReportKind type;
  required DOMString registrationUrl;
  required boolean success;
  required DOMHighResTimeStamp endTime;
  DeviceBoundEstablishedSessionReport session;
  DOMString reason;
  unsigned short code;
  DOMString providerUrl;
  DOMString providerSessionId;
};

typedef (
  DeviceBoundSessionRegistrationReport
  or DeviceBoundEstablishedSessionReport) DeviceBoundSessionsReport;

5.5.1. Registration attempt report

A DeviceBoundSessionRegistrationReport represents the outcome of the multi-stage process started by process a session registration. See § 7.1 Changes to the DBSC specification.

type, of type DeviceBoundSessionsReportKind

Must be "registration".

registrationUrl, of type DOMString

The serialized registration endpoint URL to which the registration request was sent.

success, of type boolean

True if the registration attempt resulted in an established device bound session; false otherwise.

endTime, of type DOMHighResTimeStamp

The duration from the Unix epoch to the coarsened wall time when the registration process concluded.

Using the wall clock means endTime is not monotonic across registration reports. For example, system clock changes could modify the apparent order of reports.

An alternative would be to compute these timestamps using the estimated monotonic time of the Unix epoch here.

This would in turn have the drawback of inconsistent timestamps between a successful registration report’s endTime and its session[creationTime].

session, of type DeviceBoundEstablishedSessionReport

The DeviceBoundEstablishedSessionReport for the newly created device bound session, present when success is true.

reason, of type DOMString

A human-readable or categorical description of why the registration attempt failed, present when success is false.

Replace the free-form string with a WebIDL enum of standardized failure reasons.

code, of type unsigned short

The HTTP status code received from the registration endpoint, present when the attempt failed due to an HTTP response status.

providerUrl, of type DOMString

For a federated session registration attempt, the serialized provider URL specified in the `Secure-Session-Registration` header.

providerSessionId, of type DOMString

For a federated session registration attempt, the provider session identifier specified in the `Secure-Session-Registration` header.

5.5.2. Established session report

A DeviceBoundEstablishedSessionReport represents a device bound session. Note that DeviceBoundSessionRegistrationReport also contains a session: if an observer is informed of an established session via a (buffered) DeviceBoundSessionRegistrationReport, it must not be informed of the same session a second time via a DeviceBoundEstablishedSessionReport.

type, of type DeviceBoundSessionsReportKind

Must be "session".

sessionOrigin, of type DOMString

The serialized origin of the device bound session’s session scope.

sessionId, of type DOMString

The device bound session’s session identifier.

refreshUrl, of type DOMString

The serialized refresh URL of the device bound session.

creationTime, of type DOMHighResTimeStamp

The duration from the Unix epoch to the device bound session’s creation time.

6. Session reports visibility

{
  "session_identifier": "session_id",
  "refresh_url": "/refresh",
  "scope": {
    "origin": "https://example.com",
    "include_site": true,
    "scope_specification" : [
      { "type": "exclude", "domain": "sites.example.com", "path": "/" },
      { "type": "exclude", "domain": "*.example.com", "path": "/static" }
    ]
  },
  "credentials": [{
    "type": "cookie",
    "name": "auth_cookie",
    "attributes": "Domain=example.com; Path=/; Secure; HttpOnly; SameSite=Strict"
  }]
}

7. Changes to other specifications

7.1. Changes to the DBSC specification

Avoid deep monkey-patching here: open a PR against [dbsc-1], then remove this section.

In device bound session, add the following item:

creation time

The current coarsened wall time at which this session was created.

In process a session registration:

1. Modify the step that checks if key pair is "failure" to record a registration attempt on failure.

2. Pass provider URL and provider session id as additional optional inputs to send a request.

Note: The next two changes mention "if session id is null" to send a report only when send a request creates a new session. When that algorithm runs for a refresh, session id is known.

In send a request:

1. Accept an optional provider URL and an optional provider session id to adequately construct a federation attempt report when applicable.

2. If session id is null, then:

   1. Whenever returning early due to a network error or an invalid HTTP status code, record a registration attempt.

   2. Pass provider URL and provider session id to create a session.

In create a session:

1. Accept an optional provider URL and an optional provider session id.

2. After setting the expiration timestamp, also set creation time.

3. Whenever invoking terminate the session and returning (cf. the last "credential" loop), if session id is null, then record a registration attempt with an appropriate failure reason, code, etc.

4. When adding a session to the session store, if session id is null, then record a registration attempt (successful, passing session).