spec.bs

<pre class="metadata">
Title: Device Bound Session Credentials
Shortname: dbsc
Level: 1
Indent: 2
Status: ED
Group: webappsec
ED: https://w3c.github.io/webappsec-dbsc/
Editor: Kristian Monsen 76841, Google, kristianm@google.com
Editor: Daniel Rubery 162789, Google, drubery@google.com
Editor: thefrog@chromium.org 164860, Google, thefrog@chromium.org
Abstract: Device Bound Sessions Credentials (DBSC) aims to prevent hijacking via cookie theft by building a protocol and infrastructure that allows a user agent to assert possession of a securely-stored private key. DBSC is a Web API and a protocol between user agents and servers to achieve this binding.
Repository: https://github.com/w3c/webappsec-dbsc/
Markup Shorthands: css no, markdown yes
Mailing List:
</pre>

<pre class="link-defaults">
spec:dom; type:interface; for:/; text:Document
spec:dom; type:dfn; for:/; text:element
spec:url; type:dfn; for:/; text:url
spec:fetch; type:dfn; for:Response; text:response
spec:fetch; type:dfn; for:Request; text:request
spec:html; type:element; text:script
spec:html; type:element; text:link
spec:fetch; type:dfn; text:name
spec:fetch; type:dfn; text:value
spec:infra; type:dfn; text:list
spec:infra; type:dfn; text:tuple
spec:permissions; type:dfn; text:feature
</pre>

<pre class="anchors">
spec: RFC9651;urlPrefix:https://datatracker.ietf.org/doc/html/rfc9651#;type:dfn
  text: sf-dictionary; url: dictionary
  text: sf-inner-list; url: inner-list
  text: sf-item; url: item
  text: sf-list; url: list
  text: sf-string; url: string
  text: sf-token; url: token
  text: sf-parameter; url: name-parameters
  url:text-parse;text:parsing structured fields
</pre>

# Introduction # {#intro}

<em>This section is not normative.</em><br/>
<em>Note this is a very early drafting for writing collaboration only</em>

The web is built on a stateless protocol. To provide required functionality, web
applications store data locally on a user's computer. This is used for logged in
user sessions that can last for a long time.

In general user agents do not have a secure way of storing data supporting these
activities across commonly used operating systems, and actions authenticated by
this data may have serious consequences, for example transferring money from a
bank account.

This document defines a new API, Device Bound Sessions Credentials (DBSC), that
enables the server to verify that a session cannot be exported from a device by
using commonly available TPMs, or similar APIs, that are designed for this
purpose.

The goal is to provide users with a safe and secure experience, while offering
the use cases users are already used to. At the same time we want to ensure that
the users privacy is respected with no new privacy identifiers being leaked by
this protocol.

## Examples ## {#examples}
Device Bound Session Credentials are designed to make users more secure in
different situations. Some of the use cases of DBSC are:

### Signed in session ### {#example-signin}
<div class="example" id="signin-example">
  A user logs in to his social account. To protect the user's private data the
  site protects his logged in session with a DBSC session. If the user tries to
  log in with the same cookie file on a different device, the site can detect and
  refuse this as an unauthorized user.
</div>

### Device integrity ### {#example-device-integrity}
<div class="example" id="device-integrity-example">
  A commercial site has different ways of detecting unauthorized login attempts.
  A DBSC session on the device could be used to see which users have logged on to
  this device before.
</div>

### Device reputation ### {#example-device-reputation}
<div class="example" id="device-reputation-example">
  A payment company hosted at site `payment.example.com` could create a session
  bound to when users visit commercial site `shopping.example.com`. It could
  track the reliability of the device over time to decide how likely a
  transaction is legitimate.
</div>

# Security Considerations # {#security-considerations}
The goal of DBSC is to reduce session theft by offering an alternative to
long-lived cookie bearer tokens, that allows session authentication that is
bound to the user's device. This makes the internet safer for users in that it
is less likely their identity is abused, as malware is forced to act locally and
thus becomes easier to detect and mitigate. At the same time the goal is to
disrupt the cookie theft ecosystem and force it to adapt to new protections long
term.

As long as the session is valid a host can know with cryptographic certainty
that it is on the same device as the session was originally bound to if the
session was registered to a secure device.

In order to ensure this, session private keys should be stored in a way
that cannot be exfiltrated by locally running malware, whenever possible.

## Non-goals ## {#non-goals}
DBSC will not prevent temporary access to the browser session while the attacker
is resident on the user's device. The private key should be stored as safely as
modern operating systems allow, preventing exfiltration of the session private
key, but the signing capability will still be available for any program running
as the user on the user's device.

DBSC will also not prevent an attack if the attacker is replacing or injecting
into the user agent at the time of session registration as the attacker can bind
the session either to keys that are not TPM bound, or to a TPM that the attacker
controls permanently.

DBSC is not designed to give hosts any sort of guarantee about the device a
session is registered to, or the state of this device.

# Privacy Considerations # {#privacy-considerations}
The goal of the DBSC protocol is to introduce no additional surface for user
tracking: implementing this API (for a browser) or enabling it (for a website)
should not entail any significant user privacy tradeoffs.

Some of the consideration taken to ensure this:

- Lifetime of a session/key material: This should provide no additional client
  data storage (i.e., a pseudo-cookie). As such, we require that browsers MUST
  clear sessions and keys when clearing other site data (like cookies).
- Implementing this API should not meaningfully increase the entropy of
  heuristic device fingerprinting signals. Unless allowed by user policy, DBSC
  should not leak any stable TPM-based device identifier.
- As this API MAY allow background "pings" for performance, this must not enable
  long-term tracking of a user when they have navigated away from the connected
  site.
- Each session has a separate new key created, and it should not be possible to
  detect that different sessions are from the same device unless the user allows
  this by policy.

## Cookies considerations ## {#privacy-cookies}
Cross-site/cross-origin data leakage: It should be impossible for a site to use
this API to circumvent the same origin policy, 3P cookie policies, etc.

Due to the complexity of current and changing cookie behavior and the
interaction between DBSC and cookies the current solution is that each user
agent should use the same policy for DBSC as it uses for cookies. If the DBSC
cookie credential would not apply to a network request, based on user settings,
applied policies or user agent implementation details, neither would any of the
DBSC heuristics. This ensures no new privacy behavior due to implementing DBSC.

## Timing side channel leak ## {#privacy-side-channel-leak}
If third party cookies are enabled it is possible for an attacker to leak
whether or not a user is authenticated by measuring how long the request takes
as the refresh is quite slow, partially due to the latency of TPM operations. 

This is mitigated by requiring user opt-in through the Storage Access
API. The victim site must request access to its first-party state in
order for DBSC to apply within the cross-site context.

# Alternatives considered # {#alternatives}
## WebAuthn and silent mediation ## {#alternatives-webauthn}

# Server considerations # {#server-considerations}

In order to use DBSC, site owners need to establish two new endpoints:
the registration endpoint and the refresh endpoint.

The registration endpoint is contacted asynchronously after receiving
the Sec-Session-Registration header. This endpoint should:
- Serve the session config, including a new session id.
- Persist and associate the request's public key with the session id.

The refresh endpoint is much more sensitive. This endpoint is contacted every
time a request is made with an expired bound cookie, and its response blocks
the original request. Failure to respond or restore the bound cookie may
cause browser agents to begin denial-of-service prevention mechanisms, or even
terminate the session. Both could lead to future requests without bound
cookies. The expected behavior of this endpoint is:
- Look up the public key and recent challenges for the session by id.
- Validate the Sec-Session-Response header has signed a recent challenge with
  the correct key. Note that due to network latency and race conditions, it's
  possible to receive a signature for an old challenge after issuing a new
  challenge.
- Issue new bound cookies.
- Serve the current session config.

# Alternatives considered # {#alternatives}
## WebAuthn and silent mediation ## {#alternatives-webauthn}

# Framework # {#framework}
This document uses ABNF grammar to specify syntax, as defined in [[!RFC5234]]
and updated in [[!RFC7405]], along with the `#rule` extension defined in
<a href="https://tools.ietf.org/html/rfc7230#section-7">Section 7</a> of
[[!RFC9112]], and the `quoted-string` rule defined in
<a href="https://tools.ietf.org/html/rfc7230#section-3.2.6">Section 3.2.6</a>
of the same document.

This document depends on the Infra Standard for a number of foundational
concepts used in its algorithms and prose [[!INFRA]].

## Sessions by registrable domain ## {#framework-sessions-origin}
A <dfn>sessions by registrable domain</dfn> is an [=ordered map=] from
[=host/registrable domain=] to [=session by id=].

## Sessions by id ## {#framework-sessions-id}
A <dfn>session by id</dfn> is an [=ordered map=] from
[=device bound session/session identifier=] to [=device bound session=]s for a
given [=host/registrable domain=].

## Device bound session ## {#framework-session}
A <dfn>device bound session</dfn> is a [=struct=] with the following
[=struct/items=]:
<dl dfn-for="device bound session">
  : <dfn>session identifier</dfn>
  :: a [=string=] that is a unique identifier of a session on an
    [=host/registrable domain=]
  : <dfn>refresh URL</dfn>
  :: a [=string=] that is representing the [=URL=] to be used to refresh the
    session
  : <dfn>defer requests</dfn>
  :: an OPTIONAL [=boolean=] defining if the browser should defer other
    requests while refreshing a session
  : <dfn>cached challenge</dfn>
  :: a [=string=] that is to be used as the next challenge for this session
  : [=session scope=]
  :: a [=struct=] defining which [=URL=]s are in scope for this session
  : [=session credentials=]
  :: a [=list=] of [=session credential=]s used by the session
  : <dfn>expiration timestamp</dfn>
  :: a [=moment=] when this session should be removed.
  : <dfn>session key</dfn>
  :: a key pair used by the session. The private key
    should be stored in a secure manner, see [[#security-considerations]].
</dl>

## Session scope ## {#framework-scope}
The <dfn>session scope</dfn> is a [=struct=] with the following
[=struct/items=]:
<dl dfn-for="session scope">
  : <dfn>origin</dfn>
  :: The [=/origin=] this session was registered for.
  : <dfn>include site</dfn>
  :: a [=boolean=] indicating if the session applies to an entire site or just an origin.
  : <dfn>scope specifications</dfn>
  :: a [=list=] of [=scope specification=]s used by the session
</dl>

## Scope specification ## {#framework-scope-specification}
The <dfn>scope specification</dfn> is a [=struct=] with the following
[=struct/items=]:
<dl dfn-for="scope specification">
  : <dfn>type</dfn>
  :: a [=string=] to be either "include" or "exclude", defining if the item
    defined in this struct should be added or removed from the scope
  : <dfn>host</dfn>
  :: a [=string=] defining the domain or domain pattern that must match for this scope specification to apply.
  : <dfn>path</dfn>
  :: a [=string=] that defines the path part of this scope specification
</dl>

## Session credential ## {#framework-session-credential}
The <dfn>session credential</dfn> is a [=struct=] with the following
[=struct/items=]:
<dl dfn-for="session credential">
  : <dfn>name</dfn>
  :: a [=string=] that defines the name of the credential cookie
  : <dfn>attributes</dfn>
  :: a [=string=] that defines the other attributes of the credential cookie
</dl>

# Algorithms # {#algorithms}
## Identify session ## {#algo-identify-session}
<div class="algorithm" data-algorithm="identify-session">
  This algorithm describes how to
  <dfn export dfn-for="algorithms">identify a session</dfn> out of all the
  sessions that exist on a user agent. The
  [=device bound session/session identifier=] is unique within a
  [=host/registrable domain=].

  Given a [=URL=] (|url|) and [=device bound session/session identifier=]
  (|session identifier|), this algorithm returns a [=device bound session=] or
  null if no such session exists.

  1. Let |site| be the [=host/registrable domain=] of |url|.
  1. Let |domain sessions| be [=sessions by registrable domain=][|site|] as a
    [=/session by id=]
  1. Return |domain sessions|[|session identifier|]
</div>

## Identify if a URL is in scope of a session ## {#algo-url-in-scope}
<div class="algorithm" data-algorithm="url-in-scope">
  This algorithm describes how to determine if a URL is in scope of a
  device bound session. Given a [=URL=] (|URL|) and [=session=] (|session|), returns
  "include" if |URL| is in scope, and "exclude" otherwise.

  1. Let |scope| be |session|'s [=scope specification=].
  1. If |scope| [=include site=] is true, return "exclude" if any of the
     following hold:
     1. |URL| is not [=/same site=] with |scope| [=session scope/origin=].
     1. |scope| [=session scope/origin=] is not the eTLD+1 and |URL| is not
        [=same origin=] with |scope| [=session scope/origin=].
  1. If |scope| [=include site=] is false, return "exclude" if |URL| is not
     [=same origin=] with |scope| [=session scope/origin=].
  1. [=list/for each=] |scope specification| in |scope|
    1. If the [=scope specification/host=] and [=path=] of |URL| match the
       |scope specification|, return the |scope specification|'s [=scope
       specification/type=].
  1. If the |URL| matches the |session|'s [=refresh URL=], return "exclude".
  1. Return "include".
</div>

## Identify session needing refresh ## {#algo-identify-session-needing-refresh}
<div class="algorithm" data-algorithm="identify-session-needing-refresh">
  Given a [=request=] (|request|) and [=sessions by registrable
  domain=], this algorithm describes how to identify which session, if
  any, should block |request| from proceeding.

  1. Let |site| be the [=host/registrable domain=] of the |request| [=URL=].
  1. Let |domain sessions| be [=sessions by registrable domain=][|site|] as [=/session by id=]
  1. [=list/For each=] |session| of |domain sessions|
    1. The browser MAY skip |session| in order to prevent denial of service for
       the user or site. For example, this might happen if |session| is
       requesting excessive TPM operations (harming the user) or the refresh
       endpoint has recently been unreachable (denial of service risk for the
       site). If the browser chooses to do this, it should perform the steps of
       [[#algo-add-debug-header]] with |request|, an appropriate token (see
       options in [[#header-secure-session-skipped]]), and |session|'s [=device
       bound session/session identifier=] to indicate this to the site.
    1. If |session|'s [=expiration timestamp=] is before the present, [=iteration/continue=].
    1. Let |id| be |session|'s [=device bound session/session identifier=].
    1. If the [=tuple=] (|site|, |id|) is in |request|'s
      [=deferred device bound session ids=], [=iteration/continue=].
    1. Run the steps in [[#algo-url-in-scope]] on the |request|'s URL
       and |session|'s scope. 
    1. If the result does not indicate the request is in scope,
      [=iteration/continue=].
    1. If the result of running [[#algo-identify-missing-session-credential]]
      on |request| and |session|'s [=session credentials=] is false,
      [=iteration/continue=].
    1. Add (|site|, |id|) to |request|'s [=deferred device bound session ids=].
    1. Return |session|.
  1. If no session has been identified, return null.
</div>

## Identify missing session credential ## {#algo-identify-missing-session-credential}
<div class="algorithm" data-algorithm="identify-missing-session-credential">
  Given a [=request=] (|request|) and a [=/list=] of [=session credentials=]
  (|credentials|), returns a [=boolean=] indicating whether any |credential| in
  |credentials| is missing on |request|.
  
  1. [=list/for each=] |credential| in |credentials|
    1. If a cookie with |credential|'s [=session credential/attributes=] would
       not be attached to |request| (see <a
       href=https://httpwg.org/specs/rfc6265.html#cookie>section 5.4</a> of
       [[!COOKIES]]), [=iteration/continue=].
    1. If |request|'s [=request/header list=] contains a |cookie| that
       satisfies all of the following conditions, [=iteration/continue=]:
      1. |cookie|'s name matches |credential|'s [=session credential/name=]
      1. All of the following attributes of |cookie| match those in
         |credential|'s [=session credential/attributes=]: Domain, Path,
         Secure, HttpOnly, SameSite.
      1. |cookie|'s partition key matches that of |credential|.
    1. Return true.
  1. Return false.
</div>

## Cache challenge ## {#algo-process-challenge}
<div class="algorithm" data-algorithm="process-challenge">
  This algorithm describes how to
  <dfn export dfn-for="algorithms">process a challenge</dfn> received in an HTTP
  header.

  Given a [=response=] (|response|) and a [=sessions by registrable domain=], this
  algorithm updates the [=device bound session/cached challenge=] for a
  [=device bound session=].

  1. Let |header name| be "<code>Sec-Session-Challenge</code>".
  1. Let |challenge list| be the result of executing <a>get a structured
    field value</a> given |header name| and "list" from |response|’s
    [=response/header list=].
  1. [=list/For each=] |challenge entry| of |challenge list|:
    1. Parse |challenge entry| according to <a>parsing structured fields</a>.
    1. If the type of |challenge entry| is not an <a>sf-string</a>,
      [=iteration/continue=].
    1. Let |challenge| be the parsed item.
    1. Let |session id| be null.
    1. If params["id"] exists and is an <a>sf-string</a>, set |session id| to
      params["id"].
    1. If |session id| is null, [=iteration/continue=].
    1. Identify session as described in [=identify a session=] given
      |response| and |session id| and store as |session object|.
    1. If |session object| is null, [=iteration/continue=].
    1. Store |challenge| in |session object| to be used next time a
      [=DBSC proof=] is to be sent from this [=device bound session=].
</div>

## Send request ## {#algo-session-request}
<div class="algorithm" data-algorithm="session-request">
  This algorithm describes how to <dfn export dfn-for="algorithms">send
  a request</dfn> for a device bound session registration or refresh. It
  takes as input an |originating request|, |key pair|, |destination|,
  and optional |session id|, |challenge|, and |authorization|.

  1. If |originating request|'s [=request/URL=] is not [=/same site=] with
     |destination|, return.
  1. Let |signed challenge| be null. If |challenge| is non-null, sign it
     with |key pair| and store the result in |signed challenge|.
  1. Create a |request| for use in <a
     href="https://fetch.spec.whatwg.org/#http-network-or-cache-fetch">HTTP-network-or-cache
     fetch</a>.
  1. Set |request|'s [=request/method=] to "POST".
  1. Set |request|'s [=request/URL=] to |destination|.
  1. If |signed challenge| is non-null, [=header list/append=] the header
     ("Sec-Session-Response", |signed challenge|) to |request|'s
     [=request/header list=].
  1. If |authorization| is non-null, [=header list/append=] the header
     ("Authorization", |authorization|) to |request|'s [=request/header list=].
  1. Set |request|'s [=request/initiator=] to |originating request|'s
     [=request/initiator=].
  1. Let |response| be the result of running <a
     href="https://fetch.spec.whatwg.org/#http-network-or-cache-fetch">HTTP-network-or-cache
     fetch</a> for |request|.
  1. If |response| is a [=network error=], or |response|'s
     [=response/status=] is 407, return.
  1. If |response|'s [=response/status=] is a redirect status, and the
     destination does not have the HTTPS scheme and is not localhost, cancel the
     request and return.
  1. If |response|'s [=response/status=] is 401 and has a
     "Sec-Session-Challenge" header, start this algorithm over with a new
     challenge value.
  1. If |response|'s [=response/status=] is below 500, then terminate the
     session and return.
  1. If |response|'s [=response/status=] is at least 500, then
     return. Browsers may choose to trigger a backoff mechanism on
     subsequent refresh requests on this session, to limit the harm of a
     temporary outage on the refresh endpoint.
  1. Parse |response|'s [=response/body=] according to
     [[#format-session-instructions]].
  1. Let |session identifier| be the value of key "session_identifier".
  1. If the |response| JSON contains the key "continue", with value "false":
    1. Run the steps of [[#algo-identify-session]] on |destination| and |session
       identifier|.
    1. If the result is non-null, delete the returned session.
    1. Return from this algorithm.
  1. Otherwise, perform the following validations, returning if any fail:
    1. |session identifier| must be non-empty.
    1. The value of the key "refresh_url" must be non-empty.
    1. Let |origin| be the value of the key "scope.origin", if present, or the
       origin of |destination| if not.
    1. |origin| must be a valid non-opaque origin.
    1. |origin| must be same-site with |destination|.
    1. Let |refresh URL| be the result of resolving |destination| with the value
       of the key "refresh_url".
    1. |refresh URL| must have scheme HTTPS or be localhost.
    1. |refresh URL| must be same-site with |destination|.
  1. If the value of the key "scope.include_site" in |response| is true:
    1. Let |destination site| be the [=host/registrable domain=] of |destination|.
    1. If |destination site| is equal to the [=url/host=] of |destination|, continue to the next step.
    1. Otherwise, let |well known URL| be a copy of |destination|, with the
       [=url/host=] replaced with |destination site|, and the [=url/path=]
       replaced with "/.well-known/device-bound-sessions".
    1. Let |well known response| be the result of fetching |well known URL|.
    1. If |well known response|'s [=response/status=] is not 200, return.
    1. If |well known response|'s [=response/body=] is not a JSON-encoded list of strings, return.
    1. If |well known response|'s [=response/body=] does not include the origin of
       |destination|, return.
  1. If the input |session id| is present, delete the session with site
     |destination|'s site and identifier |session id|.
  1. Create a new session with:
    1. [=device bound session/session identifier=] set to |session identifier|.
    1. [=refresh URL=] set to |refresh URL|.
    1. [=defer requests=] set to true.
    1. [=session scope=] a new scope with [=session scope/origin=] |origin|, [=include
       site=] the value of the key "scope.include_site", and [=scope
       specifications=] the value of the key "scope.scope_specification".
    1. [=session credentials=] the value of the key "credentials".
    1. [=session key=] a newly-generated key pair.

## Create session ## {#algo-create-session}
To <dfn export id="create-session">Create a new session</dfn> due to the
[=response=] (|response|) to a [=request=] (|request|), do the following steps:
<div class="algorithm" data-algorithm="process-registration">
  1. Let |header name| be "<code>Sec-Session-Registration</code>".
  1. Let |registration list| be the result of executing <a>get a structured
    field value</a> given |header name| and "list" from |response|’s
    [=response/header list=].
  1. [=list/For each=] |registration entry|, |params| → |registration list|:
    1. Parse |registration entry| according to <a>parsing structured fields</a>.
    1. If |registration entry| is not an <a>sf-inner-list</a>,
      [=iteration/continue=].
    1. Let |algorithm list| be an empty [=list=].
    1. [=list/For each=] |algorithm| → |registration entry|
      1. If |algorithm| is not an <a>sf-token</a>, [=iteration/continue=].
      1. If |algorithm| represents a crypto algorithm supported in
        [:Sec-Session-Registration:], and is supported on this client, add
        |algorithm| to |algorithm list|
    1. If |algorithm list| is empty, [=iteration/continue=].
    1. If |params|["path"] does not exist, or is not of type <a>sf-string</a>,
      [=iteration/continue=].
    1. Let |path| be |params|["path"].
    1. Let |challenge| be null, and Let |authorization| be null.
    1. If |params|["challenge"] exists and is of type <a>sf-string</a>
      Set |challenge| to |params|["challenge"].
    1. If |params|["authorization"] exists and is a string Set |authorization|
      to |params|["authorization"].
    1. Create a |key pair| for |algorithm list|.
    1. Let |endpoint| be the result of resolving |path| relative to the
       |response|'s URL.
    1. Call [[#algo-session-request]] with |request|, |key pair|, |endpoint|, null
       session identifier, |challenge| and |authorization|.
</div>

## Add debug header ## {#algo-add-debug-header}
In order for sites to understand when the user agent chooses not to
apply a session, user agents should <dfn export
id="add-debug-header">add the debug header</dfn> to a [=request=]
(|request|) with an <a>sf-token</a> (|token|) and [=string=] (|session id|).
<div class="algorithm" data-algorithm="add-debug-header">
  1. Let |value| be an <a>sf-token</a> with value |token|.
  1. Set the <a>sf-parameter</a> "session_identifier" on |value| to |session id|.
  1. Let |skipped header value| be the result of running the steps of [=get a
     structured field value=] with [=header name=]
     "Secure-Session-Skipped", type "list", and |request|'s
     [=request/header list=].
  1. If |skipped header value| is null, set it to an empty <a>sf-list</a>.
  1. Append |value| to |skipped header value|.
  1. Run the steps of [=set a structured field value=] given
    ("Secure-Session-Skipped", |skipped header value|) on |request|'s
    [=request/header list=].
</div>

# DBSC Formats # {#format}
## \``Sec-Session-Registration`\` HTTP header field ## {#header-sec-session-registration}
The \`<dfn export http-header id="sec-session-registration-header">
<code>Sec-Session-Registration</code></dfn>\` header field can be used in a
[=response=] by the server to start a new [=/device bound session=] on the
client.

[:Sec-Session-Registration:] is a List Structured Header [[RFC9651]]. Its ABNF
is:

<pre class="abnf">Sec-Session-Registration = <a>sf-list</a></pre>

Each item in the list must be an inner list, and each item in the inner list
MUST be an <a>sf-token</a> representing a supported algorithm (ES256, RS256).
Only these two values are currently supported.

The following <a>sf-parameter</a>s are defined:
- An <a>sf-parameter</a> whose key is "path", and whose value is an
  <a>sf-string</a>, conveying the path to the registration endpoint. This may be
  relative to the current [=URL=], or a full [=URL=]. Entries without this
  parameter will be ignored in [[#algo-create-session]].
- An <a>sf-parameter</a> whose key is "challenge", and whose value is an
  <a>sf-string</a>, conveying the challenge to be used in the session
  registration.
- An <a>sf-parameter</a> whose key is "authorization", and whose value is an
  <a>sf-string</a>. This <a>sf-parameter</a> will be copied into the
  registration JWT.

<div class="example" id="sec-session-registration-example">
  Some examples of [:Sec-Session-Registration:] from
  https://example.com/login.html:

  ```html
  HTTP/1.1 200 OK
  Sec-Session-Registration: (ES256);path="reg";challenge="cv";authorization="ac"
  ```
  ```html
  HTTP/1.1 200 OK
  Sec-Session-Registration: (ES256 RS256);path="reg";challenge="cv"
  ```
  ```html
  HTTP/1.1 200 OK
  Sec-Session-Registration: (ES256);path="reg1";challenge="cv1";authorization="a"
  Sec-Session-Registration: (RS256);path="reg2";challenge="cv2";authorization="b"
  ```
  ```html
  HTTP/1.1 200 OK
  Sec-Session-Registration: (ES256);path="reg1";challenge="cv1";authorization="a", (RS256);path="reg2";challenge="cv2";authorization="b"
  ```
</div>

## \``Sec-Session-Challenge`\` HTTP Header Field ## {#header-sec-session-challenge}
The \`<dfn export http-header id="sec-session-challenge-header">
<code>Sec-Session-Challenge</code></dfn>\` header field can be used in a
[=response=] by the server to send a challenge to the client that it expects to
be used in future Sec-Session-Response headers inside the [=DBSC proof=], or to
request a newly signed [=DBSC proof=] right away if the [=response/status=] is
401.

[:Sec-Session-Challenge:] is a structured header. Its value must be a string.
Its ABNF is: <pre class="abnf">SecSessionChallenge = <a>sf-string</a></pre>
The semantics of the item are defined in
[[#challenge-structured-header-serialization]].

The processing steps are defined in [[#algo-process-challenge]].

### Sec-Session-Challenge structured header serialization ### {#challenge-structured-header-serialization}
The [:Sec-Session-Challenge:] is represented as a Structured Field.[[!RFC9651]]

In this representation, a challenge is represented by a string.

Challenges MAY have an <a>sf-parameter</a> named `"id"`, whose value MUST be a String
representing a [=device bound session/session identifier=]. Any other
<a>sf-parameter</a>s SHOULD be ignored.

Note: The server might need to use this header to request the [=DBSC proof=] to
be signed with a new challenge before a session id has been assigned. In this
case the session ID is optional.

<div class="example" id="sec-session-challenge-example">
  Some examples of [:Sec-Session-Challenge:] from
  https://example.com/login.html:

  ```html
  HTTP/1.1 401 OK
  Sec-Session-Challenge: "new challenge"
  ```
  ```html
  HTTP/1.1 401 OK
  Sec-Session-Challenge: "new challenge";id="my session"
  ```
  ```html
  HTTP/1.1 200 OK
  Sec-Session-Challenge: "new challenge";id="my session"
  ```
  ```html
  HTTP/1.1 200 OK
  Sec-Session-Challenge: "new challenge";id="my session 1"
  Sec-Session-Challenge: "another challenge";id="my session 2"
  ```
  ```html
  HTTP/1.1 200 OK
  Sec-Session-Challenge: "c1";id="session 1", "c2";id="session 2"
  ```
</div>

## `Sec-Session-Response` HTTP Header Field ## {#header-sec-session-response}
The \`<dfn export http-header id="sec-session-response-header">
<code>Sec-Session-Response</code></dfn>\` header field can be used in the
[=request=] by the user agent to send a [=DBSC proof=] to the server to prove
that the client is still in possession of the private key of the session key.

\`<a http-header><code>Sec-Session-Response</code></a>\` is a structured
header. Its value must be a string. It's ABNF is:
<pre class="abnf">SecSessionChallenge = <a>sf-string</a></pre>
This string MUST only contain the [=DBSC proof=] JWT. Any <a>sf-parameter</a>s SHOULD be
ignored.

<div class="example" id="sec-session-response-example">
  ```html
  POST example.com/refresh
  Sec-Session-Response: "eyJhbGciOiJFUzI1NiIsInR5cCI6ImRic2Mrand0In0.eyJhdWQiOiJodHRwczovL2V4YW1wbGUuY29tL3JlZyIsImp0aSI6ImN2IiwiaWF0IjoiMTcyNTU3OTA1NSIsImp3ayI6eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6IjZfR0Iydm9RMHFyb01oNk9sREZDRlNfU0pyaVFpMVBUdnZCT2hHWjNiSEkiLCJ5IjoiSWVnT0pVTHlFN1N4SF9DZDFLQ0VSN2xXQnZHRkhRLWgweHlqelVqRUlXRSJ9LCJhdXRob3JpemF0aW9uIjoiYWMifQ.6Fb_vVBDmfNghQiBmIGe8o7tBfYPbPCywhQruP0vIhxgmcJmuNTaMHeVn_M8ZnOm1_bzIitbZqCWEn-1Qzmtyw"
  ```
</div>  

## `Sec-Session-Id` HTTP Header Field ## {#header-sec-session-id}
The \`<dfn export http-header id="sec-session-id-header">
<code>Sec-Session-Id</code></dfn>\` header field can be used in the
[=request=] by the user agent to request the current session is refreshed, 
with the current session identifier as a string argument.

\`<a http-header><code>Sec-Session-Id</code></a>\` is a structured header.
Its value must be a string. It's ABNF is:
<pre class="abnf">SecSessionChallenge = <a>sf-string</a></pre>
This string MUST only contain the session identifier. Any parameters SHOULD be
ignored.

<div class="example" id="sec-session-id-example">
  ```html
  POST example.com/refresh
  Sec-Session-Id: "session-id"
  ```
</div>

## `Secure-Session-Skipped` HTTP header field ## {#header-secure-session-skipped}
The \`<dfn export http-header id="secure-session-skipped-header">
<code>Secure-Session-Skipped</code></dfn>\` header field can be used in a
[=request=] to indicate that the request is intentionally missing bound
credentials due to user agent policy.

[:Secure-Session-Skipped:] is a List Structured Header [[RFC9651]]. Its ABNF
is:

<pre class="abnf">Secure-Session-Skipped = <a>sf-list</a></pre>

Each item in the list must be MUST be an <a>sf-token</a> representing a
coarse-grained reason for skipping cookie refresh. The only supported values
are: "unreachable", "server_error", and "quota_exceeded".

One <a>sf-parameter</a> is defined:
- An <a>sf-parameter</a> whose key is "session_identifier", and whose value is an
  <a>sf-string</a>, conveying the identifier of the skipped session.
  
<div class="example" id="sec-session-id-example">
  ```html
  GET example.com/requires_bound_cookie
  Sec-Session-Skipped: unreachable;session_identifier=123, quota_exceeded;session_identifier=456
  ```
</div>


## DBSC Session Instruction Format ## {#format-session-instructions}
The server sends <dfn>session instructions</dfn> during session
registration and optionally during session refresh. If the response
contains session instructions, it MUST be in JSON format.

At the root of the JSON object, the following keys can exist:
<dl dfn-for="session instructions">
  : <dfn>session identifier</dfn>
  :: a [=string=] representing a [=device bound session/session identifier=].
    If this [=session instructions=] is sent during a refresh request this MUST be
    the [=device bound session/session identifier=] for the current session. If
    not these instructions SHOULD be ignored.
    If this [=session instructions=] is sent during a registration it MUST either
    be a unique identifier for this [=host/registrable domain=], or it will
    overwrite the current [=device bound session=] with this identifier for the
    current [=host/registrable domain=].
    This key MUST be present.

  : <dfn>refresh_url</dfn>
  :: a [=string=] representing the [=URL=] used for future refresh requests.
    This can be a full [=URL=], or relative to the current [=request=].
    This key is OPTIONAL; if not present the registration URL will be used for
    future refresh requests.

  : <dfn>defer_requests</dfn>
  :: a [=boolean=] describing the wanted session behavior during a session
    refresh. If this value is true all requests related to this session will be
    deferred while the session is refreshed. If instead the value is false every
    request will instead be sent as normal, but with a [:Sec-Session-Response:]
    header containing the [=DBSC proof=].
    This key is OPTIONAL, and if not present a value of true is default.

  : <dfn>continue</dfn>
  :: a [=boolean=] indicating if the session should continue to apply.
    Registration and refresh endpoints can set this to false to terminate a session.
    This key is OPTIONAL, and if not present, the default value will be true.
    
  : <dfn>scope</dfn>
  :: a [=dictionary=] of [=session scope instructions=] describing the request
    destinations covered by the session. This field MUST be present.

  : <dfn>credentials</dfn>
  :: a [=list=] of [=session credentials=] describing the cookies protected by
    this session. This field MUST be present.
</dl>

<div class="example" id="sec-session-instruction-example">
  ```json
  {
    "session_identifier": "session_id",
    "refresh_url": "/RefreshEndpoint",

    "continue": false,
    "defer_requests": true, // optional and true by default

    "scope": {
      // Origin-scoped by default (i.e. https://example.com)
      // Specifies to include https://*.example.com except excluded subdomains.
      // This can only be true if the origin's host is the root eTLD+1.
      "origin": "https://example.com",
      "include_site": true,

      "scope_specification" : [
        { "type": "include", "domain": "trusted.example.com", "path": "/only_trusted_path" },
        { "type": "exclude", "domain": "untrusted.example.com", "path": "/" },
        { "type": "exclude", "domain": "*.example.com", "path": "/static" }
      ]
    },

    "credentials": [{
      "type": "cookie",
      // This specifies the exact cookie that this config applies to. Attributes
      // match the cookie attributes in RFC 6265bis and are parsed similarly to
      // a normal Set-Cookie line, using the same default values.
      // These SHOULD be equivalent to the Set-Cookie line accompanying this 
      // response.
      "name": "auth_cookie",
      "attributes": "Domain=example.com; Path=/; Secure; HttpOnly; SameSite=None"
      // Attributes Max-Age and Expires are ignored
    }]
  }
  ```
</div>

## DBSC Session Scope Instruction Format ## {#format-session-scope-instructions}
The server sends <dfn>session scope instructions</dfn> in the [=session
instructions=] during registration and optionally during session refresh.

At the root of the JSON object, the following keys can exist:
<dl dfn-for="session scope instructions">
  : <dfn>origin</dfn>
  :: a [=string=] indicating the origin or site that the session applies to.
    This key is OPTIONAL; if not present, the origin of the URL serving the
    instructions will be used. This is the registration URL during registration
    and the refresh URL during refresh.
    
  : <dfn>include_site</dfn>
  :: a [=boolean=] indicating if the session is origin-scoped (false) or
    site-scoped (true). This key is OPTIONAL; if not present, it will be false
    (origin-scoped). Note that this takes precedence over any
    [=session scope rule=]s in [=scope_specification=] (see
    [[#algo-url-in-scope]]).
    
  : <dfn>scope_specification</dfn>
  :: a [=list=] of [=session scope rule=]s describing modifications to the
    default scope (the entire origin or site). This key is OPTIONAL; if not
    present, an empty list will be used.
</dl>

## DBSC Session Scope Rule Format ## {#format-session-scope-rule}
The server sends <dfn>session scope rule</dfn>s in the [=session scope
instructions=] during registration and optionally during session refresh.

At the root of each [=session scope rule=], the following keys can exist:
<dl dfn-for="session scope rule">
  : <dfn>type</dfn>
  :: a [=string=] indicating whether the rule includes or excludes destinations.
    This key MUST be present, and the value MUST be "include" or "exclude".
    
  : <dfn>domain</dfn>
  :: a [=string=] indicating the domains that should match the rule. This key
    MUST be present. This can include wildcards (see [[#algo-url-in-scope]]).
    
  : <dfn>path</dfn>
  :: a [=string=] indicating the path-prefixes that should match the rule. This
    key MUST be present. See [[#algo-url-in-scope]] for the detailed semantics.
</dl>

## DBSC Session Credentials Format ## {#format-session-credentials}
The server sends <dfn>session credentials</dfn> in the [=session
instructions=] during registration and optionally during session refresh.

At the root of the JSON object, the following keys can exist:
<dl dfn-for="session scope instructions">
  : <dfn>type</dfn>
  :: a [=string=] indicating the kind of credential protected by this session.
    This key MUST be present, and the value MUST be "cookie".
    
  : <dfn>name</dfn>
  :: a [=string=] indicating the name of the bound cookie.
    
  : <dfn>attributes</dfn>
  :: a [=string=] containing the expected attributes of the protected cookie.
    See [[#algo-identify-missing-session-credential]] for details on how this
    is used. 
</dl>

## DBSC Proof JWT Syntax ## {#format-jwt}
A <dfn>DBSC proof</dfn> proof is a JWT that is signed (using JSON Web Signature
(JWS)), with a private key chosen by the client. The header of a [=DBSC proof=]
MUST contain at least the following <a>sf-parameter</a>s:
<dl dfn-for="DBSC proof">
  : <dfn>typ</dfn>
  :: a [=string=] MUST be "dbsc+jwt"
  : <dfn>alg</dfn>
  :: a [=string=] defining the algorithm used to sign this JWT. It MUST be
    either "RS256" or "ES256" from [IANA.JOSE.ALGS].
</dl>

The payload of [=DBSC proof=] MUST contain at least the following claims:
<dl dfn-for="DBSC proof">
  : <dfn>aud</dfn>
  :: a [=string=], MUST be the [=URL=] this JWT was originally sent to.
    Example: "https://example.com/refresh.html"
  : <dfn>jti</dfn>
  :: a [=string=], a copy of the challenge value sent in the registration
    header.
  : <dfn>iat</dfn>
  :: a [=string=], this claim identifies the time at which the JWT was
    issued.  This claim can be used to determine the age of the JWT.  Its
    value MUST be a number containing a NumericDate value.
  : <dfn>key</dfn>
  :: a [=string=] defining a JWK as specified in [rfc7517].
</dl>

In addition the following claims MUST be present if present in
[:Sec-Session-Registration:]:
<dl dfn-for="DBSC proof">
  : <dfn>authorization</dfn>
  :: a [=string=], direct copy of the string from
    [:Sec-Session-Registration:], if set there. Note that this string is
    OPTIONAL to include in the header, but if it is present it is
    MANDATORY for clients to add the claim in the [=DBSC proof=].
</dl>

If the DBSC proof is for a refresh request, the following claim MUST be
present:
<dl dfn-for="DBSC proof">
  : <dfn>sub</dfn>
  :: the [=device bound session/session identifier=], a [=string=].
</dl>

<div class="example" id="dbsc-proof-example">
  An example [=DBSC proof=] sent to https://example.com/reg:

  ```json
  // Header
  {
    "alg": "ES256",
    "typ": "dbsc+jwt"
  }
  // Payload
  {
    "aud": "https://example.com/reg",
    "jti": "cv",
    "iat": "1725579055",
    "key": {
      "kty": "EC",
      "crv": "P-256",
      "x": "6_GB2voQ0qroMh6OlDFCFS_SJriQi1PTvvBOhGZ3bHI",
      "y": "IegOJULyE7SxH_Cd1KCER7lWBvGFHQ-h0xyjzUjEIWE"
    },
    "authorization": "ac"
  }
  ```

  Based on this response header from the server:
  ```html
  HTTP/1.1 200 OK
  Sec-Session-Registration: (ES256);path="reg";challenge="cv";authorization="ac"
  ```
  received on a response from ```http://example.com/page.html```
</div>

# Changes to other specifications # {#changes-to-other-specifications}

## Changes to the Fetch specification ## {#changes-to-fetch}

This specification requires an update to the <a
href="https://fetch.spec.whatwg.org/#http-network-or-cache-fetch">HTTP-network-or-cache
fetch</a> algorithm. A [=request=] has a [=list=] of [=tuple=]s
([=host/registrable domain=] |domain|, [=string=] |session id|), <dfn
for="request">deferred device bound session ids</dfn>. This list is initially
empty. At the end of step 8.21
run [[#algo-identify-session-needing-refresh]]. If the resulting |session| is
non-null:
  1. Run [[#algo-session-request]] with the returned |session|'s
    [=session key=], [=refresh URL=], [=device bound session/session
    identifier=], [=cached challenge=], and an empty authorization.
  2. Restart <a
    href="https://fetch.spec.whatwg.org/#http-network-or-cache-fetch">HTTP-network-or-cache
    fetch</a> with the original inputs.
    
## Changes to the Clear Site Data specification ## {#changes-to-clear-site-data}

This specification requires that the Clear Site Data specification
sections 4.2.5 "Clear DOM-accessible storage for origin" clear all
device bound sessions whose scope matches origin. It also requires an
update to 4.2.4 to clear device bound sessions for the site matching the
registered domain.

# IANA Considerations # {#iana-considerations}

The permanent message header field registry should be updated with the following
registrations: [[!RFC3864]]

## Sec-Session-Challenge ## {#iana-ses-session-challenge}
<dl>
  <dt>Header field name</dt>
  <dd>Sec-Session-Challenge</dd>

  <dt>Applicable protocol</dt>
  <dd>http</dd>

  <dt>Status</dt>
  <dd>draft</dd>

  <dt>Author/Change controller</dt>
  <dd>W3C</dd>

  <dt>Specification document</dt>
  <dd>This specification (See [[#header-sec-session-challenge]])</dd>
</dl>

## Sec-Session-Id ## {#iana-ses-session-id}
<dl>
  <dt>Header field name</dt>
  <dd>Sec-Session-Id</dd>

  <dt>Applicable protocol</dt>
  <dd>http</dd>

  <dt>Status</dt>
  <dd>draft</dd>

  <dt>Author/Change controller</dt>
  <dd>W3C</dd>

  <dt>Specification document</dt>
  <dd>This specification (See [[#header-sec-session-id]])</dd>
</dl>

## Sec-Session-Registration ## {#iana-sec-session-registration}
<dl>
  <dt>Header field name</dt>
  <dd>Sec-Session-Registration</dd>

  <dt>Applicable protocol</dt>
  <dd>http</dd>

  <dt>Status</dt>
  <dd>draft</dd>

  <dt>Author/Change controller</dt>
  <dd>W3C</dd>

  <dt>Specification document</dt>
  <dd>This specification (See [[#header-sec-session-registration]])</dd>
</dl>

## Sec-Session-Response ## {#iana-sec-session-response}
<dl>
  <dt>Header field name</dt>
  <dd>Sec-Session-Response</dd>

  <dt>Applicable protocol</dt>
  <dd>http</dd>

  <dt>Status</dt>
  <dd>draft</dd>

  <dt>Author/Change controller</dt>
  <dd>W3C</dd>

  <dt>Specification document</dt>
  <dd>This specification (See [[#header-sec-session-response]])</dd>
</dl>

## Secure-Session-Skipped ## {#iana-secure-session-skipped}
<dl>
  <dt>Header field name</dt>
  <dd>Secure-Session-Skipped</dd>

  <dt>Applicable protocol</dt>
  <dd>http</dd>

  <dt>Status</dt>
  <dd>draft</dd>

  <dt>Author/Change controller</dt>
  <dd>W3C</dd>

  <dt>Specification document</dt>
  <dd>This specification (See [[#header-secure-session-skipped]])</dd>
</dl>

## device-bound-sessions Well Known ## {#well-known}

The Well-Known URI registry should be updated to include
/.well-known/device-bound-sessions.

This endpoint must serve a JSON-encoded list of strings for each origin allowed
to register a session for the entire site.

<div class="example">
  If `https://example.com/.well-known/device-bound-sessions` serves
  ```json
  [
    "https://subdomain.example.com",
    "https://subdomain.example.com:8000",
  ]
  ```
  Then registration requests can define a site-scoped session only if
  one of the following is true:
  - The registration endpoint has host `example.com`
  - The registration endpoint has origin `https://subdomain.example.com`
  - The registration endpoint has origin `https://subdomain.example.com:8000`
</div>

# Changelog # {#changelog}
This is an early draft of the spec.

# Acknowledgements # {#acknowledgements}