spec.bs

<pre class='metadata'>
Title: Private State Token API
H1: Private State Token API
Shortname: private-state-token-api
Level: None
Status: CG-DRAFT
Group: WICG
Repository: WICG/trust-token-api
URL: https://wicg.github.io/trust-token-api/
Editor: Aykut Bulut, Google https://www.google.com/, aykutb@google.com
Editor: Steven Valdez, Google https://www.google.com/, svaldez@google.com
Abstract: The Private State Token API is a web platform API that allows propagating a limited amount of signals across sites, using the Privacy Pass protocol as an underlying primitive.
!Participate: <a href="https://github.com/WICG/trust-token-api">GitHub WICG/trust-token-api</a> (<a href="https://github.com/WICG/trust-token-api/issues/new">new issue</a>, <a href="https://github.com/WICG/trust-token-api/issues?state=open">open issues</a>)
!Commits: <a href="https://github.com/WICG/trust-token-api/commits/main/spec.bs">GitHub spec.bs commits</a>
Markup Shorthands: css no, markdown yes
Complain About: missing-example-ids yes
</pre>

<pre class="link-defaults">
spec:fetch; type:dfn; for:/; text:response
spec:fetch; type:dfn; for:/; text:request
spec:infra; type:dfn; text:list
</pre>

<pre class="anchors">
urlPrefix: https://fetch.spec.whatwg.org/; spec: Fetch
    text: http-network-or-cache fetch; url: #concept-http-network-or-cache-fetch; type: dfn
urlPrefix: https://www.ietf.org/archive/id/draft-irtf-cfrg-voprf-21.html; spec: VOPRF
    text: Blind; url: #section-3.3.1-2; type: dfn
    text: BlindEvaluate; url: #section-3.3.2-2; type: dfn
    text: Finalize; url: #section-3.3.2-5; type: dfn
    text: Evaluate; url: #section-3.3.1-9; type: dfn
    text: P-384; url: #name-oprfp-384-sha-384; type: dfn
urlPrefix: https://www.ietf.org/archive/id/draft-robert-privacypass-batched-tokens-01.html; spec: BatchedToken
    text: BlindEvaluateBatch; url: #section-4-5; type: dfn
    text: FinalizeBatch; url: #section-5-4; type: dfn
</pre>

<pre class='biblio'>
{
    "PRIVACY-PASS-ARCHITECTURE": {
        "authors": ["A. Davidson", "J. Iyengar", "C. A. Wood"],
        "href": "https://www.ietf.org/archive/id/draft-ietf-privacypass-architecture-10.html",
        "publisher": "IETF",
        "title": "Privacy Pass Architectural Framework"
    },
    "PRIVACY-PASS-AUTH-SCHEME": {
        "authors": ["T. Pauly", "S. Valdez", "C. A. Wood"],
        "href" : "https://www.ietf.org/archive/id/draft-ietf-privacypass-auth-scheme-10.html",
        "publisher": "IETF",
        "title": "The Privacy Pass HTTP Authentication Scheme"
    },
    "PRIVACY-PASS-ISSUANCE-PROTOCOL": {
        "authors": ["S. Celi", "A. Davidson", "A. Faz-Hernandez", "S. Valdez", "C. A. Wood"],
        "href": "https://www.ietf.org/archive/id/draft-ietf-privacypass-protocol-10.html",
        "publisher": "IETF",
        "title": "Privacy Pass Issuance Protocol"
    },
    "PRIVACY-PASS-WG": {
        "href": "https://datatracker.ietf.org/wg/privacypass/about/"
    },
    "VOPRF": {
        "authors": ["A. Davidson", "A. Faz-Hernandez",  "N. Sullivan", "C. A. Wood"],
        "href": "https://www.ietf.org/archive/id/draft-irtf-cfrg-voprf-21.html",
        "publisher": "IETF",
        "title": "Oblivious Pseudorandom Functions (OPRFs) using Prime-Order Groups"
    },
    "BatchedTokens": {
        "authors": ["R. Robert", "C. A. Wood"],
        "href": "https://www.ietf.org/archive/id/draft-robert-privacypass-batched-tokens-01.html",
        "publisher": "IETF",
        "title": "Batched Token Issuance Protocol"
    },
    "RFC4648": {
        "href": "https://www.rfc-editor.org/rfc/rfc4648"
    }
}
</pre>
<pre class="anchors">
urlPrefix: https://tools.ietf.org/html/rfc8941; spec: rfc8941
    type: dfn
        text: structured header; url: #name-introduction
    for: structured header
        type: dfn
            text: integer; url: #section-3.3.1
            text: string; url: #section-3.3.3
</pre>

Goals {#goals}
==============

The goal of the Private State Tokens is to transfer a limited amount of signals across
sites through time in a privacy preserving manner. It achieves this using a variant of the
privacy pass protocol [[!PRIVACY-PASS-ISSUANCE-PROTOCOL]] specified in the working
documents of the IETF Privacy Pass Working Group [[PRIVACY-PASS-WG]]. Private
State Tokens can be considered to be a web platform implementation of a variant of
Privacy Pass.

The spec introduces a new field in request dictionary to support token
operations. It describes how Private State Tokens are utilized through this new
dictionary.

<!--

In a real-world
system relying on anonymous tokens without private metadata bit, if the issuer stops providing
malicious users with tokens, the attacker will know that they have been detected as malicious.
In fact, this information could serve as an incentive to corrupt more users, or to train machine
learning models that detect which malicious behavior goes un-noticed.

https://eprint.iacr.org/2020/072.pdf

-->


Background {#background}
========================

The Private State Token API provides a mechanism for anonymous authentication. The
API provided by the user agent does not authenticate clients, instead it facilitates
transfer of authentication information.

Authentication of the clients and token signing are both carried by the same
entity referred to as the **issuer**. This is the joint attester and issuer
architecture described in [[!PRIVACY-PASS-ARCHITECTURE]],
[[!PRIVACY-PASS-AUTH-SCHEME]].

User agents store tokens in persistent storage. Navigated origins might fetch/spend
tokens in first party contexts or include third party code that fetch/spend
tokens. Spending tokens is called **redeeming**.

Origins may ask the user agent to fetch tokens from the issuers of their
choice. Tokens can be redeemed from a different origin than the fetching one.

Private State Tokens API performs cross site anonymous authentication without
using linkable state carrying cookies [[RFC6265]]. Cookies do provide cross
site authentication, however, they fail to provide anonymity.

Cookies store large amounts of information. [[RFC6265]] requires at least 4096
bytes per cookie and 50 cookies per domain. This means an origin has
50 x 4096 x 2^8 unique identifiers at its disposal. When backed with back end
databases, a server can store arbitrary data for that many unique
users/sessions.

Compared to a cookie, the amount of data stored in a Private State Token is very
limited. A token stores a value from a set of six values (think of a value of
an enum type of six possible values). Hence a token stores data between 2 and 3
bits (4 < 6 < 8). This is very small compared to 4096 bytes a cookie can store.

Moreover, Private State Tokens API use cryptographic protocols that prevents
origins from tracking which tokens they issue to which user. When presented with
their tokens, issuers can verify they issued them but cannot link the
tokens to the context of their issuance. Cookies do not have this property.

Unlike cookies, storing multiple tokens from an issuer does not deteriorate
privacy of the user due to the unlinkability of the tokens. The Private
State Token API allows at most 2 different issuers in a top level origin. This
is to limit the information stored for a user when the issuers are
collaborating.

Private State Token operations rely on [[!FETCH]]. A fetch request corresponding to a
specific Private State Token operation can be created and used as a parameter to the
fetch function.

<!--
* how this is not as powerful like cookies, privacy guarantees?
* Between first and second para there is some gap. We should fill in.
* Level of details in privacy is good and important. A high level approach of this before API details.
* Start with use case and scenarios. This would help with people confused with API.
* how do we refer to unsigned/signed bind/clear tokens?
-->


Issuer Public Keys {#issuer-public-keys}
========================================

This section describes the public interfaces that an issuer is required to
support to provide public keys to be used by Private State Token protocols.

An issuer needs to maintain a set of keys and implement the **Issue** and
**Redeem** cryptographic functions to sign and validate tokens. Issuers are
required to serve a **key commitment** endpoint. Key commitments are
collections of cryptographic keys and associated metadata necessary for
executing the issuance and redemption operations. Issuers make these available
through secure HTTP [[!RFC8446]] endpoints. User agents should fetch the key
commitments periodically. A <dfn>key commitment</dfn> is a [=map=] representing
a collection of cryptographic keys and associated metadata necessary for executing
the issuance and redemption operations.


Requests to key commitment endpoints should result in a JSON response
[[!RFC8259]] of the following format with a media type of
`"application/pst-issuer-directory"`:

```javascript
{
  <cryptographic protocol_version>: {
    "protocol_version": <cryptographic protocol version>,
    "id": <key commitment identifier>
    "batchsize": <batch size>,
    "keys": {
      <keyID>: { "Y": <base64-encoded public key>,
                 "expiry": <key expiration date>},
      <keyID>: { "Y": <base64-encoded public key>,
                 "expiry": <key expiration date>}, ...
    }
  },
  ...
}
```

* `<cryptographic protocol version>` is a string identifier for the Private State Token
    protocol version used. The same string is used as a value of the inner
    `"protocol_version"` field. Protocol version string identifier is
    `"PrivateStateTokenV1VOPRF"`.

    * Protocol version `“PrivateStateTokenV1VOPRF”` implements [[!VOPRF]] cryptographic
               protocol. Issuers can use up to six valid token signing keys.

* `"id"` field provides the identifier of the key commitment. It is a string
         representation of a non-negative integer that is within the range of
         an unsigned 32 bit integer type. Values should be montonically
         increasing.

* `"batchsize"` specifies the maximum number of masked tokens that the issuer
                supports for each token issuance operation. Its value is a
                string representation of a positive integer. The user agent might send
                fewer tokens in a single operation, but will generally default to
                sending `batchsize` many tokens per operation.

* `"keys"` field is a dictionary of public keys listed by their identifiers.

         * `<keyID>` is a string representation of a non-negative integer that
               is within the range of an unsigned 32 bit integer type.

         * Each key has a `"Y"` field which is a string representation of a
                big-endian base64 encoding [[!RFC4648]] of the byte string of
                the key.

         * `"expiry"` field specifies how long the underlying key is valid. It
                      is a string representation of a nonnegative integer that
                      is within the range of an unsigned 64 bit integer type.
                      Underlying key expires if this amount many or more
                      microseconds are elapsed since the POSIX epoch
                      [[!RFC8536]].

All field names and their values are strings. When new key commitments are
fetched for an issuer, previous commitments are discarded.

Issuer Key Fetching/Registration {#issuer-registration}
----------------------------

To maintain the privacy of this API and avoid user-specific keys, issuers should present the same keys to all clients that issue and redeem tokens against them.

To ensure this property, it is recommended that user agents fetch the key commitments in an user-agnostic manner, through some sort of proxied mechanism or centralized mechanism for fetching the keys and distributing them to individual clients.

If using a centralized mechanism for fetching keys, user agents should have a registration process to allow for issuers to register to have their key commitments fetched and sent to clients at a regular client. The requirements and mechanisms for registering are [=implementation-defined=].

When using a registration process, it is recommended that user agents apply an expiration date to registration requests, to allow for the removal of deprecated or no longer active issuers.

VOPRF Methods {#voprf-methods}
====================================

This document encodes protocol messages in the TLS presentation language from section 3 of [[!RFC8446]].

To <dfn>serialize protocol messages</dfn> and  <dfn>deserialize protocol messages</dfn>, protocol messages are encoded and interpreted as described in section 3 of [[!RFC8446]].

For Private State Tokens, the VOPRF protocol is initialized using [=P-384=] for the curve (`G` in the functions described below) and `nonce_size` is defined as 64. 

Note: The use of X9.62 uncompressed points for the inputs/outputs in the current version of PST is a historical divergence from the existing [[!VOPRF]] specification. The selection of nonce_size is a historical divergence from the current draft of [[!BatchedTokens]].

When the server is performing an Issuance, the server performs the [=BlindEvaluateBatch=] function of the [[!BatchedTokens]] protocol, where the input <dfn>IssueRequest</dfn> and output <dfn>IssueResponse</dfn> are serialized as:

```
// Scalars are elliptic curve scalars of length Ns (determined by the curve, 48 for P-384).
// ECPoints are elliptic curve points encoded using the X9.62 Uncompressed point representation (determined by the curve, 97 for P-384).

struct {
  uint16 count;
  ECPoint nonces[count]; // Corresponding to blindedElements
} IssueRequest;

struct {
  ECPoint blinded; // Note: We diverge from the BlindEvaluateBatch specification by including this field along with each evaluatedElement.
  ECPoint evaluated; // Corresponding to evaluatedElements
} SignedNonce;

struct {
  Scalar c;
  Scalar s;
} DLEQProof;

struct {
  uint16 issued;
  uint32 key_id;
  SignedNonce signed[issued];
  opaque proof<1..2^16-1>; // Bytestring containing a serialized DLEQProof struct.
} IssueResponse;
```

When the server is performing a Redemption, the server performs [=PSTEvaluate=] on the `Token`, the input <dfn>RedeemRequest</dfn> and output <dfn>RedeemResponse</dfn> are serialized as:

```
struct {
  uint32 key_id;
  opaque nonce[nonce_size];
  ECPoint W;
} Token;

struct {
  opaque token<1..2^16-1>; // Bytestring containing a serialized Token struct.
  opaque client_data<1..2^16-1>;
} RedeemRequest;

struct {
  opaque rr<1..2^16-1>;
} RedeemResponse;
```

Private State Tokens defines <dfn>PSTFinalize</dfn> which is a variation of the [=FinalizeBatch=] function of the [[!BatchedTokens]] protocol as follows:

```
def PSTFinalize(input, blinds, evaluatedElements,
               blindedElements, pkS, proof):
  if VerifyProof(G.Generator(), pkS, blindedElements,
                 evaluatedElements, proof) == false:
    raise VerifyError

  // PST: Use batched construction.
  unblindedElements = []
  for index in range(evaluatedElements.length):
    N = G.ScalarInverse(blinds[index]) * evaluatedElements[index]
    unblindedElements.append(G.SerializeElement(N))

  // PST: Return unblindedElements rather than hash output.
  return unblindedElements
```

Private State Tokens defines <dfn>PSTEvaluate</dfn> which is a variation of the [=Evaluate=] function of the [[!VOPRF]] protocol as follows:

```
// skS is determined by the server by using key_id to lookup the corresponding private key.

def PSTEvaluate(skS, nonce, W, client_data):
  inputElement = G.HashToGroup(nonce)
  if inputElement == G.Identity():
    raise InvalidInputError
  evaluatedElement = skS * inputElement
  issuedElement = G.SerializeElement(evaluatedElement)

  // PST: Checks issuedElement rather than hash output.
  if issuedElement != W:
    raise InvalidInputError

  // PST: The server may use client_data and other information to construct a redemptionRecord to return to the client.
  return redemptionRecord
```

Algorithms {#algorithms}
====================================

A user agent has <dfn>issuerAssociations</dfn>, which is a [=map=] where the keys are [=/origin=] |topLevel|, and the values are a [=list=] of [=/origins=].

To <dfn>determine whether associating an issuer would exceed the top-level limit</dfn> given an [=/origin=] |issuer| and an [=/origin=] |topLevel|, run the following steps:

1. If [=issuerAssociations=][|topLevel|] does not [=map/exist=], return false.
1. If [=issuerAssociations=][|topLevel|] [=list/contains=] |issuer|, return false.
1. If the [=issuerAssociations=][|topLevel|] [=list/size=] is less than 2, return false.
1. Return true.

To <dfn>associate the issuer</dfn> |issuer| (an [=/origin=]) with the [=/origin=] |topLevel|, run the following steps:

1. If [=issuerAssociations=][|topLevel|] does not [=map/exist=], [=map/set=] [=issuerAssociations=][|topLevel|] to an empty [=list=].
1. [=list/Append=] |issuer| to [=issuerAssociations=][|topLevel|].

To determine whether an [=/origin=] |issuer| <dfn>is associated with</dfn> a given [=/origin=] |topLevel|, run the following steps:

1. If [=issuerAssociations=][|topLevel|] does not [=map/exist=], return false.
1. If [=issuerAssociations=][|topLevel|] [=list/contains=] |issuer|, return true.
1. Return false.

A user agent has <dfn>redemptionTimes</dfn>, a [=map=] where the keys are a [=tuple=] (|issuer|, |topLevel|), and the values are a [=tuple=] (|lastRedemption|, |penultimateRedemption|).

To <dfn>record redemption timestamp</dfn> given an [=/origin=] |issuer| and an [=/origin=] |topLevel|, run the following steps:

1. Let |currentTime| be the current date and time.
1. Let |previousRedemption| be the earliest representable date and time.
1. If [=redemptionTimes=][(|issuer|,|topLevel|)] [=map/exists=], let |previousRedemption| be the |lastRedemption| field of the tuple [=redemptionTimes=][(|issuer|,|topLevel|)].
1. [=map/set=] [=redemptionTimes=][(|issuer|,|topLevel|)] to the tuple (|currentTime|, |previousRedemption|).

To <dfn>look up penultimate redemption</dfn> given an [=/origin=] |issuer| and an [=/origin=] |topLevel|, run the following steps:

1. Let |penultimateRedemption| be the earliest representable date and time.
1. If [=redemptionTimes=][(|issuer|,|topLevel|)] [=map/exists=], let |penultimateRedemption| be the |penultimateRedemption| field of the tuple [=redemptionTimes=][(|issuer|,|topLevel|)].
1. Return |penultimateRedemption|.

A user agent has <dfn>redemptionRecords</dfn>, a [=map=] where the keys are a [=tuple=] (|issuer|, |topLevel|), and the values are a [=tuple=] (|record|, |expiration|, |signingKeys|).

To <dfn>record a redemption record</dfn> given an [=/origin=] |issuer|, an [=/origin=] |topLevel|, a [=byte sequence=] |header|, and a [=duration=] |lifetime|, run the following steps:

1. If |lifetime| is zero, return.
1. Let |currentTime| be the current date and time in milliseconds since 01 January, 1970 UTC.
1. Let |expiration| be the sum of |currentTime| and |lifetime|.
1. Let |signingKeys| be the result of [=look up the latest keys|looking up of the latest keys=] for |issuer|.
1. Set [=redemptionRecords=][(|issuer|, |topLevel|))] to the tuple (|header|, |expiration|, |signingKeys|).

To <dfn>retrieve a redemption record</dfn> given an [=/origin=] |issuer| and an [=/origin=] |topLevel|, run the following steps:

1. Let |currentTime| be the current date and time in milliseconds since 01 January, 1970 UTC.
1. If [=redemptionTimes=][(|issuer|,|topLevel|)] [=map/exists|does not exist=], return null.
1. Let (|record|, |expiration|, |signingKeys|) be [=redemptionTimes=][(|issuer|,|topLevel|)].
1. If |expiration| is less than |currentTime|, return null.
1. Let |currentSigningKeys| be the result of [=look up the latest keys|looking up of the latest keys=] for |issuer|.
1. If |currentSigningKeys| does not equal |signingKeys|, return null.
1. Return |record|.

A user agent has <dfn>pstKeyCommitments</dfn>, a [=map=] where the keys are an [=/origin=], and the values are [=key commitments=].

Note: It is recommended that each user agent fetches the key commitments from issuers at a regular cadence and through trusted infrastructure, and then sends the concatenated map of issuers and key commitments to the client to ensure consistency between the keys different user agent instances use.

To <dfn>look up the key commitments</dfn> for a given [=/origin=] |issuer|, run the following steps:

1. If [=pstKeyCommitments=][|issuer|] does not [=map/exist=], return null.
1. Let |issuerKeys| be [=pstKeyCommitments=][|issuer|].
1. For each |cryptoProtocolVersion| that the user agent supports for this API in an [=implementation-defined=] order, run the following steps:
    1. Return |issuerKeys|[|cryptoProtocolVersion|], if it [=map/exists=].
1. Return null.

Note: |cryptoProtocolVersion| is a string identifier representing different cryptographic versions of tokens that can be used with this API. User agents should only select keys for versions they support, ordered by which versions they prefer based on performance and any user defined preferences.

To <dfn>look up the latest keys</dfn> for a given [=/origin=] |issuer|, run the following steps:

1. Let |commitment| be the result of [=look up the key commitments|looking up the key commitments=] for |issuer|.
1. If |commitment| is null, return null.
1. Let |chosenKey| be null.
1. Let |currentTime| be the current date and time.
1. [=list/For each=] |key| of |commitment|["keys"], run the following steps:
    1. If |key|["expiry"] is less than |currentTime|, continue.
    1. If |chosenKey| is null, set |chosenKey| to |key|.
    1. If |key|["expiry"] is less than |chosenKey|["expiry"], set |chosenKey| to |key|.
1. Return |chosenKey|.

A user agent has a <dfn>tokenStore</dfn>, a [=map=] where the keys are [=/origins=] and the values are [=lists=] of  [=storedTokens=]. A <dfn>storedToken</dfn> is a [=tuple=] of ([=byte sequence=], [=byte sequence=]).

To <dfn>insert a token</dfn> for an [=/origin=] |issuer|, [=byte sequence=] |token|, and [=byte sequence=] |signingKey|, run the following steps:

1. Create a new [=tuple=] |storedToken| consisting of (|token|, |signingKey|).
1. If [=tokenStore=][|issuer|] does not [=map/exist=], set [=tokenStore=][|issuer|] to an empty [=list=].
1. [=list/Append=] |storedToken| to [=tokenStore=][|issuer|].

To <dfn>retrieve a token</dfn> for an [=/origin=] |issuer|, run the following steps:

1. If [=tokenStore=][|issuer|] does not [=map/exist=], return null.
1. If the [=list/size=] of [=tokenStore=][|issuer|] is zero, return null.
1. [=list/Remove=] a random element of [=tokenStore=][|issuer|] and return the removed element.

To <dfn>discard tokens</dfn> from an [=/origin=] |issuer| and [=byte sequence=] |signingKey|, run the following steps:

1. If [=tokenStore=][|issuer|] does not [=map/exist=], return.
1. [=list/Remove=] all elements of [=tokenStore=][|issuer|] whose second element is not equal to |signingKey|.

To get the <dfn>number of tokens</dfn> from an [=/origin=] |issuer|, run the following steps:

1. If [=tokenStore=][|issuer|] does not [=map/exist=], return 0.
1. Return the [=list/size=] of [=tokenStore=][|issuer|].

To get the <dfn>max batch size</dfn> for an [=/origin=] |issuer|, run the following steps:

1. Let |issuerKey| be the result of running [=look up the key commitments=] on |issuer|.
1. If |issuerKey| is null, return 0.
1. Return |issuerKey|["batchsize"].

To <dfn>generate masked tokens</dfn> given [=key commitments=] |issuerKeys| and number |numTokens|, run the following steps. They return a [=tuple=] ([=byte sequence=], [=byte sequence=]).

1. Let |issueRequest| be an empty [=IssueRequest=].
1. Set |issueRequest|["count"] to |numTokens|.
1. Let |blinds| be an empty [=byte sequence=].
1. Repeat the following steps, |numTokens| times:
    1. Let |input| be a random [=byte sequence=].
    1. Let (|blind|, |blindedElement|) ([=tuple=] ([=byte sequence=], [=byte sequence=])) be the result of running the [=Blind=] function of the [[!VOPRF]] protocol on |input|, where |blindedElement| is encoded as a X9.62 uncompressed point.
    1. Append |blind| to |blinds|.
    1. Append |blindedElement| to |issueRequest|["nonces"].
1. Let |issueHeader| be the result of [=serialize protocol message|serializing protocol message=] |issueRequest|.
1. Return [=tuple=] (|issueHeader|, |blinds|).

To <dfn>unmask tokens</dfn> given [=key commitments=] |issuerKeys|, byte string |blinds|, and a [=byte sequence=] |response|, run the following steps. They return a [=list=] of [=byte sequence=].

1. Let |input| be an empty [=byte sequence=].
1. Let |evaluatedElements| be an empty [=list=].
1. Let |blindedElements| be an empty [=list=].
1. Let |issueResponse| be the result of [=deserialize protocol message|deserializing protocol message=] |response| as an [=IssueResponse=].
1. [=list/For each=] |nonce| of |issueResponse|["signed"]:
    1. [=list/Append=] |nonce|["blinded"] to |blindedElements|.
    1. [=list/Append=] |nonce|["evaluated"] to |evaluatedElements|.
1. Let |pkS| be |issuerKeys|["keys"][|issueResponse|["key_id"]]["Y"].
1. Let |proof| be |issueResponse|["proof"].
1. Let |blindsList| be an empty [=list=].
1. While the [=byte sequence/length=] of |blinds| is greater than 0:
    1. Let |blind| be the first N elements of |blinds| and |blinds| be the remainder, where N is the length of a X9.62 uncompressed point.
    1. [=list/Append=] |blind| to |blindsList|.
1. Let |result| ([=list=] of byte strings) be the result of running [=PSTFinalize=] on |input|, |blindsList|, |evaluatedElements|, |blindedElements|, |pkS|, and |proof|.
1. Return |result|.

To <dfn>set private token properties for request from private token</dfn>, given a {{PrivateToken}} |privateToken| and a [=request=] |request|, run the following steps:

1. Set |request|'s [=request/private token operation=]</a> to |privateToken|["{{PrivateToken/operation}}"].
1. If |privateToken|["{{PrivateToken/operation}}"] is {{OperationType/"token-request"}}:
    1. If [$Should request be allowed to use feature?$] on "<code>[=policy-controlled feature/private-state-token-issuance=]</code>" and |request| returns <code>false</code>, then throw a "{{NotAllowedError}}" {{DOMException}}.
    1. Abort the remaining steps.
1. Assert: |privateToken|["{{PrivateToken/operation}}"] is {{OperationType/"token-redemption"}} or {{OperationType/"send-redemption-record"}}.
1. If [$Should request be allowed to use feature?$] on "<code>[=policy-controlled feature/private-state-token-redemption=]</code>" and |request| returns <code>false</code>, then throw a "{{NotAllowedError}}" {{DOMException}}.
1. If |privateToken|["{{PrivateToken/operation}}"] is <code>"token-redemption"</code>:
    1. Set |request|'s [=request/private token refresh policy=]</a> to |privateToken|["{{PrivateToken/refreshPolicy}}"].
    1. Abort the remaining steps.
1. If |privateToken|["{{PrivateToken/issuers}}"] does not [=map/exists|exist=], then throw {{TypeError}}.
1. If |privateToken|["{{PrivateToken/issuers}}"] is [=list/empty=], then throw {{TypeError}}.
1. [=list/For each=] |issuer| of |privateToken|["{{PrivateToken/issuers}}"]:
    1. Let |issuerURL| be the the result of running the [=URL parser=] on |issuer|.
    1. If |issuerURL| is failure, then throw {{TypeError}}.
    1. If |issuerURL|'s [=url/scheme=] is not an [=HTTP(S) scheme=], then throw {{TypeError}}.
    1. Let |issuerOrigin| be |issuerURL|'s [=/origin=].
    1. If |issuerOrigin| is not a [=potentially trustworthy origin=], then throw {{TypeError}}.
    1. [=list/Append=] |issuerURL| to <var ignore>request</var>'s [=request/private token issuers=].


Integration with Fetch {#fetch-integration}
====================================

Definitions {#definitions}
---------------------------------------------------------------

The {{RefreshPolicy}} is attached to a redemption request, determining whether or not the
redemption should result in a previously returned, unexpired [=redemption record=] or a
new one.

<pre class=idl>
enum RefreshPolicy { "none", "refresh" };
</pre>

The {{TokenVersion}} is currently set to `1`, as this is the only version that the
specification supports at this time.

<pre class=idl>
enum TokenVersion { "1" };
</pre>

The {{OperationType}} refers to which operation the user agent is attempting to complete.

<pre class=idl>
enum OperationType { "token-request", "send-redemption-record", "token-redemption" };
</pre>

The {{PrivateToken}} contains the information required to make a fetch request.

<pre class=idl>
dictionary PrivateToken {
  required TokenVersion version;
  required OperationType operation;
  RefreshPolicy refreshPolicy = "none";
  sequence&lt;USVString> issuers;
};
</pre>

This specification adds a new property to the {{RequestInit}} dictionary:

<pre class=idl>
partial dictionary RequestInit {
  PrivateToken privateToken;
};
</pre>

Modifications to request {#fetch-request}
---------------------------------------------------------------

A [=/request=] has an associated <dfn for=request>private token refresh policy</dfn>, which is of type {{RefreshPolicy}} with default value of <code>"none"</code>.

A [=/request=] has an associated <dfn for=request>private token operation</dfn>, which is of type {{OperationType}}.

A [=/request=] has an associated <dfn for=request>private token issuers</dfn>, which is a list of strings.

Note: [=request/Private token refresh policy=] is ignored unless [=request/private token operation=] is <code>"token-redemption"</code>. [=request/Private token issuers=] is ignored unless [=request/private token operation=] is <code>"send-redemption-record"</code>. [=request/Private token issuers=] must be specified and non-empty when [=request/private token operation=] is <code>"send-redemption-record"</code>.

This specification defines two new [=policy-controlled features=]. Exactly one of these policy features applies for a given Private State Token operation.

The [=policy-controlled feature=] identified by "<dfn data-dfn-for="policy-controlled feature"><code>private-state-token-issuance</code></dfn>" applies for the <code>"token-request"</code> operation. The [=default allowlist=] for this feature is <code>["self"]</code>.

The [=policy-controlled feature=] identified by "<dfn data-dfn-for="policy-controlled feature"><code>private-state-token-redemption</code></dfn>" applies for the <code>"send-redemption-record"</code> and <code>"token-redemption"</code> operations. The [=default allowlist=] for this feature is <code>["self"]</code>.

A [=request=] has an associated <dfn for="request">pstPretokens</dfn>, which is null or a [=byte sequence=].

Add the following steps to the <code><a constructor lt="Request()">new Request (<var ignore>input</var>, |init|)</a></code> constructor, before step 28 ("<code>Set [=this=]'s [=Request/request=] to |request|</code>"):

Given a {{RequestInit}} |init| and a {{Request}} |request| run the following steps:
1. If |init|["{{RequestInit/privateToken}}"] [=map/exists=]:
    1. Let |privateToken| be |init|["{{RequestInit/privateToken}}"].
    1. Run [=set private token properties for request from private token=] on |privateToken| and |request|.


Modifications to http-network-or-cache fetch {#http-network-or-cache-fetch}
---------------------------------------------------------------

This specification adds the following steps to the [=http-network-or-cache fetch=] algorithm, before modifying the header list:

    1. If |request|'s [=request/private token operation=] is null, abort remaining steps.
    1. If |request|'s [=request/private token operation=] is <code>"token-request"</code>:
        1. [=Append private state token issue request headers=] on |httpRequest|.
        1. Abort the remaining steps.
    1. If |request|'s [=request/private token operation=] is <code>"token-redemption"</code>:
        1. [=Append private state token redemption request headers=] on |httpRequest|.
        1. Abort the remaining steps.
    1. [=Assert=]: |request|'s [=request/private token operation=] is <code>"send-redemption-record"</code>.
    1. [=Append private state token redemption record headers=] on |httpRequest|.

Modifications to HTTP fetch steps {#http-fetch}
---------------------------------------------------------------

The specification adds the following steps to the [=HTTP fetch=] algorithm, before checking the redirect status (i.e. "7. If |actualResponse|'s status is a redirect status, ..."):

1. Let |issue response result| be the result of [=handle an issue response|handling an issue response=], given [=request=] |request| and [=response=] |actualResponse| as input.
1. If |issue response result| is a [=network error=], return |issue response result|.
1. Let |redeem response result| be the result of [=handle a redeem response|handling a redeem response=], given [=request=] |request| and [=response=] |actualResponse| as input.
1. If |redeem response result| is a [=network error=], return |issue response result|.


Integration with iframe {#iframe-integration}
====================================

privateToken content attribute for HTMLIframeElement {#iframe-private-token}
---------------------------------------------------------------

The <{iframe}> element contains a <dfn element-attr for="iframe">privateToken</dfn> <a spec=html>content attribute</a>. The IDL attribute {{HTMLIFrameElement/privateToken}} <a spec=html>reflects</a> the <{iframe/privateToken}> <a spec=html>content attribute</a>.

  <pre class=idl>
  partial interface HTMLIFrameElement {
    [SecureContext] attribute DOMString privateToken;
  };
  </pre>

Modification to "create navigation params by fetching" steps {#navigation-params-modifications}
---------------------------------------------------------------

The following step is added to the <a href="https://html.spec.whatwg.org/multipage/browsing-the-web.html#create-navigation-params-by-fetching">create navigation params by fetching</a>, before step "25. Return a new <a href="https://html.spec.whatwg.org/multipage/browsing-the-web.html#navigation-params">navigation params</a>, with ...":

  1. If <var ignore=''>navigable</var>'s [=container=] is an <{iframe}> element, and if it has a <{iframe/privateToken}> <a spec=html>content attribute</a>, then run [=set private token properties for request from private token=] on <var ignore=''>navigable</var>'s <var ignore=''>privateToken</var> and |request|.


Integration with XMLHttpRequest {#xhr}
====================================

Attach PrivateToken {#xhr-set-private-token}
---------------------------------------------------------------

An {{XMLHttpRequest}} has an associated <dfn for="XMLHttpRequest">private state token</dfn>,
a {{PrivateToken}} object that specifies the {{OperationType}} to execute against the request.

<xmp class="idl">
partial interface XMLHttpRequest {
  undefined setPrivateToken(PrivateToken privateToken);
};
</xmp>
The <dfn method for="XMLHttpRequest">setPrivateToken(PrivateToken privateToken)</dfn> method steps are:
<ol>
 <li><p>If [=this=]'s <a spec="xhr">state</a> is not "opened", then throw an
 "{{InvalidStateError}}" {{DOMException}}.
 <li> If <a>this</a>'s
    <a spec="xhr">`send()` flag</a> is set,
    then [=throw=] an "{{InvalidStateError}}" {{DOMException}}.
 <li> Set [=this=]'s [=XMLHttpRequest/private state token=] to |privateToken|.
</ol>

send() monkeypatch {#xhr-send-monkeypatch}
---------------------------------------------------------------
Modify {{XMLHttpRequest/send(body)}} as follows:

After the step:

> Let |req| be a new [=request=], initialized as follows...

Add the step:

1. Run [=set private token properties for request from private token=] with <a>this</a>'s [=XMLHttpRequest/private state token=] and |req|.


Issuing Protocol {#issuing-protocol}
====================================

This section explains the issuing protocol. It has two sections that explains
the issuing protocol steps for user agents and issuers.

Creating An Issue Request {#issue-request}
---------------------------------------------------------------

<div class=example id="example-issue-request">
An issue request is created and fetched as demonstrated in the following snippet.

```javascript
let issueRequest = new Request("https://example.issuer:1234/issuer_path", {
  privateToken: {
    version: 1,
    operation: "token-request",
  }
});
fetch(issueRequest);
```
</div>

To <dfn>append private state token issue request headers</dfn> given a [=/request=] |request|, run the following steps:

 1. If |request|'s [=request/client=] is not a [=secure context=], return.
 1. Let |issuer| be |request|'s [=request/URL=]'s [=url/origin=].
 1. Let |topLevel| be |request|'s [=request/client=]'s [=environment/top-level origin=].
 1. If associating |issuer| with |topLevel| [=determine whether associating an issuer would exceed the top-level limit|would exceed the top level’s number-of-issuers limit=], return.
 1. [=Associate the issuer=] |issuer| with |topLevel|.
 1. If the [=number of tokens=] for |issuer| is at least 500, return.
 1. Let |issuerKeys| be the result of [=look up the key commitments|looking up the key commitments=] for |issuer|.
 1. If |issuerKeys| is null,  return.
 1. Let |signingKey| be the result of [=look up the latest keys|looking up of the latest keys=] for |issuer|.
 1. Run [=discard tokens=] with |issuer| and |signingKey|.
 1. Let |numTokens| be |issuer|'s [=max batch size=] or an [=implementation-defined=] limit on the number of tokens (which is recommended to be 100), whichever is smaller.

 1. Let (|issueHeader|, |pretokens|) be the result of [=generate masked tokens|generating masked tokens=] with |issuerKeys| and |numTokens|.
 1. Set |request|'s [=cache mode=] to `"no-store"`.
 1. Set |request|'s [=pstPretokens=] to |pretokens|.
 1. Let |base64EncodedTokens| be the base64-encoded [[!RFC4648]] version of |issueHeader|.
 1. Let |cryptoProtocolVersion| be the version of the cryptographic protocol used.
 1. [=header list/Set a structured field value=] given (<a http-header>`Sec-Private-State-Token`</a>, |base64EncodedTokens|)
                in |request|'s header list.
 1. [=header list/Set a structured field value=] given (<a http-header>`Sec-Private-State-Token-Crypto-Version`</a>, |cryptoProtocolVersion|)
                in |request|'s header list.

<div class=example id="example-pst-request-headers">
Private State Token HTTP request headers created for a typical fetch is as follows.

```
Sec-Private-State-Token: <masked tokens encoded as base64 string>
Sec-Private-State-Token-Crypto-Version: <cryptographic protocol version, VOPRF>
```
</div>

Issuer Signing Tokens {#issuer-signing-tokens}
----------------------------------------------

This section explains the signing of tokens that happens in the issuer
servers. VOPRF can only encode one of six values by the selection of which
key to use.

Using its private keys, issuer signs the masked tokens obtained in the
<a http-header>Sec-Private-State-Token</a> request header value with a value
dependent on other information passed as part of the issuance request. Issuer uses the cryptographic protocol
specified in the request <a http-header>Sec-Private-State-Token-Crypto-Version</a> header. Issuer returns
the signed tokens in the <a http-header>Sec-Private-State-Token</a> response header
value encoded as a base64 [[!RFC4648]] byte string.

<div class=example id="example-pst-response">
The following snippet displays a typical response demonstrating the Private State Token
header.

```
Sec-Private-State-Token: <token encoded as base64 string>
```
</div>

Handling Issue Responses {#issue-response}
----------------------------------------------------------

To <dfn>handle an issue response</dfn>, given [=request=] |request| and [=response=] |response|, run the following steps:

1. If |request|'s [=request/header list=] [=header list/contains|does not contain=] <a http-header>Sec-Private-State-Token</a>, return null.
1. If |response|'s [=response/header list=] [=header list/contains|does not contain=] <a http-header>Sec-Private-State-Token</a>, return a [=network error=].
1. Let |header| be the result of [=header list/get|getting=] <a http-header>Sec-Private-State-Token</a> from |response|'s [=response/header list=].
1. If |header| is empty, return.
1. [=header list/delete|Delete=] <a http-header>Sec-Private-State-Token</a> from |response|'s [=response/header list=].
1. Let |issuer| be |request|'s [=request/URL=]'s [=url/origin=].
1. Let |issuerKeys| be the result of [=look up the key commitments|looking up the key commitments=] for |issuer|.
1. If |issuerKeys| is null, return.
1. Let |pretokens| be |request|'s [=pstPretokens=].
1. If |pretokens| is null, return.
1. Let |rawResponse| be the base64-decoded [[!RFC4648]] version of |header|.
1. Let |unmasked tokens| be the result of [=unmask tokens|unmasking response tokens=] given |issuerKeys|, |pretokens|, and |rawResponse|.
1. If |unmasked tokens| is null, return a [=network error=].
1. Let |signingKey| be the result [=look up the latest keys|looking up the latest keys=] for |issuer|.
1. For each |token| in |unmasked tokens|, run the following steps:
    1. [=Insert a token=] for |issuer|, |token|, and |signingKey|.
1. Return.

Redeeming Tokens {#redeeming-tokens}
====================================

When the user agent navigates to a top-level origin, this top-level origin or a third party site
embedded on the top level origin may redeem tokens stored in the user agent from a
specific issuer to learn the data encoded in the tokens.

<div class=example id="example-redemption-request">
Redemption is carried through fetch as demonstrated in the following
snippet. The default value for refreshPolicy is `'none'`.

```javascript
let redemptionRequest = new Request('https://example.issuer:1234/redemption_path', {
  privateToken: {
    version: 1,
    operation: 'token-redemption',
    refreshPolicy: {'none', 'refresh'}
  }
});
```
</div>

To <dfn>set redemption headers</dfn> with [=/request=] |request| and a [=RedeemRequest=] |record|:
 1. Let |redemptionRequest| be the result of [=serialize protocol message|serializing protocol message=] |record|.
 1. Let |cryptoProtocolVersion| be the version of the cryptographic protocol used.
 1. Let |token-lifetime| be the expiration time of the [=redemption record=] in seconds.
 1. [=header list/Set a structured field value=] given (<a http-header>`Sec-Private-State-Token`</a>, |redemptionRequest|)
                in |request|'s header list.
 1. [=header list/Set a structured field value=] given (<a http-header>`Sec-Private-State-Token-Crypto-Version`</a>, |cryptoProtocolVersion|)
                in |request|'s header list.
 1. Optionally, [=header list/set a structured field value=] given (<a http-header>`Sec-Private-State-Token-Lifetime`</a>, |token-lifetime|)
                in |request|'s header list.
 1. Set |request|'s [=cache mode=] to `"no-store"`.

To <dfn>append private state token redemption request headers</dfn> given a [=/request=] |request|, run the following steps:

 1. Let |issuer| be |request|'s [=request/URL=]'s [=url/origin=].
 1. Let |topLevel| be |request|'s [=request/client=]'s [=environment/top-level origin=].
 1. If |request|'s [=request/client=] is not a [=secure context=], return.
 1. If associating |issuer| with |topLevel| [=determine whether associating an issuer would exceed the top-level limit|would exceed the top level’s number-of-issuers limit=], return.
 1. [=Associate the issuer=] |issuer| with |topLevel|.
 1. If |request|'s [=request/private token refresh policy=] is `"none"`:
     1. Let |record| be the result of performing [=retrieve a redemption record=] with |issuer| and |topLevel|.
     1. If |record| is not null, [=set redemption headers=] with |request| and |record| and return.
 1. Let |penultimateRedemption| be the result of [=look up penultimate redemption =] with |issuer| and |topLevel|
 1. If |penultimateRedemption| is less than an [=implementation-defined=] time period (which is recommended to be 48 hours), return error.

 1. Let |commitments| be the result of [=look up the key commitments|looking up the key commitments=] for |issuer|.
 1. If |commitments| is null, return.
 1. [=Discard tokens=] from |issuer| that are signed with keys other than those from
            the issuer's most recent commitments.
 1. Let |token| be the result of [=retrieve a token|retrieving a token=] for |issuer|.
 1. If |token| is null, return.
 1. Let |redeemRequest| be an empty [=RedeemRequest=].
 1. Set |redeemRequest|["token"] to |token|.
 1. [=Set redemption headers=] with |request| and |record|.


Handling Redeem Responses {#redeem-response}
----------------------------------------------------------

To <dfn>handle a redeem response</dfn>, given [=request=] |request| and [=response=] |response|, run the following steps:

1. If |request|'s [=request/header list=] [=header list/contains|does not contain=] <a http-header>Sec-Private-State-Token</a>, return null.
1. If |response|'s [=response/header list=] [=header list/contains|does not contain=] <a http-header>Sec-Private-State-Token</a>, return a [=network error=].
1. Let |rawHeader| be the result of [=header list/get|getting=] <a http-header>Sec-Private-State-Token</a> from |response|'s [=response/header list=].
1. If |rawHeader| is empty, return null.
1. Let |rawResponse| be the base64-decoded [[!RFC4648]] version of |rawHeader|.
1. Let |header| be the result of [=deserialize protocol message|deserializing protocol message=] |rawHeader| as a [=RedeemResponse=].
1. [=header list/delete|Delete=] <a http-header>Sec-Private-State-Token</a> from |response|'s [=response/header list=].
1. Set |lifetime| to be the largest representable duration.
1. If |response|'s [=response/header list=] [=header list/contains=] <a http-header>Sec-Private-State-Token-Lifetime</a> response header, set |lifetime| to that value.
1. [=header list/delete|Delete=] <a http-header>Sec-Private-State-Token-Lifetime</a> from |response|'s [=response/header list=].
1. Let |issuer| be |request|'s [=request/URL=]'s [=url/origin=].
1. Let |topLevel| be |request|'s [=request/client=]'s [=environment/top-level origin=].
1. Perform [=record redemption timestamp=] with |issuer| and |topLevel|.
1. Perform [=record a redemption record=] with |issuer|, |topLevel|, |header|, and |lifetime|.

Note: The [=redemption record=] is HTTP-only and JavaScript is only able to
access/send the [=redemption record=] via Private State Token Fetch APIs. The [=redemption record=] is treated as an
arbitrary blob of bytes from the issuer, that may have semantic meaning to
downstream consumers.

Redemption Records {#redemption-records}
----------------------------------------

To reduce communication overhead, the user agent might cache blobs returned in
<a http-header>Sec-Private-State-Token</a> header value in redemption responses. These blobs are
referred as [=Redemption Records=]. User agents might choose to store these records
to include them in subsequent requests to the origins that can verify its
validity. An issuer might choose to include an optional <a http-header>Sec-Private-State-Token-Lifetime</a>
header in the redemption response. The value of this header indicates the
expiration time for the [=redemption record=] provided. This expiration is
specified as number of seconds in the <a http-header>`Sec-Private-State-Token-Lifetime`</a> HTTP response
header value.

A <dfn>Redemption Record</dfn> is a [=byte sequence=].

The Private State Tokens API provides a `'send-redemption-record'` operation to [=append private state token redemption record headers=]. This operation attaches a previously [=record a redemption record|recorded redemption record=] from [=handle a redeem response=].

To <dfn>append private state token redemption record headers</dfn> given a [=/request=] |request|, run the following steps:

  1. If |request|'s [=request/client=] is not a [=secure context=], then abort these steps.
  1. Let |topLevel| be |request|'s [=request/client=]'s [=environment/top-level origin=].
  1. [=list/For each=] |issuer| of [=request/private token issuers=]:
    1. Let |issuerURL| be the the result of running the [=URL parser=] on |issuer|.
    1. If |issuerURL| is failure, then abort these steps.
    1. If |issuerURL|'s [=url/scheme=] is not an [=HTTP(S) scheme=], then abort these steps.
    1. Let |issuerOrigin| be |issuerURL|'s [=/origin=].
    1. If |issuerOrigin| is not a [=potentially trustworthy origin=], then abort these steps.
  1. Let |records_per_issuer| be a [=map=] where keys are USVString and values are [=redemption records=].
  1. [=list/For each=] |issuer| of [=request/private token issuers=]:
    1. Let |record| be the result of performing [=retrieve a redemption record=] with |issuer| and |topLevel|.
    1. If |record| is null, then [=iteration/continue=].
    1. [=map/Set=] |records_per_issuer|[|issuer|] to |record|.
  1. If |records_per_issuer| is empty, then abort these steps.
  1. Let |headerItems| be a structured headers list [[RFC8941]].
  1. [=map/For each=] |issuer| -> |record| of |records_per_issuer|:
    1. Let |serializedIssuer| be result of serializing |issuer|.
    1. Let |serializedRecord| be result of serializing |record|.
    1. [=list/Append=] |serializedIssuer| and |serializedRecord| pairs to |headerItems|.
  1. Let |serializedHeaderItems| be result of serializing |headerItems|.
  1. If |serializedHeaderItems| is null, then abort these steps.
  1. Set <a http-header>`Sec-Redemption-Record`</a> to |serializedHeaderItems|.


<h3 id="the-document-object">Changes to {{Document}}</h3>

<pre class="idl">
partial interface Document {
  Promise&lt;boolean> hasPrivateTokens(USVString issuer);
  Promise&lt;boolean> hasRedemptionRecord(USVString issuer);
};
</pre>

Query APIs {#query-apis}
========================

Token Query {#token-query}
--------------------------

When invoked on {{Document}} |doc| with {{USVString}} |issuer|, the <dfn export method for=Document><code>hasPrivateTokens(issuer)</code></dfn> method must run these steps:
1. Let |p| be [=a new promise=].
1. If |doc| is not [=Document/fully active=], then [=reject=] |p| with an "{{InvalidStateError}}" {{DOMException}} and return |p|.
1. Let |global| be |doc|'s [=relevant global object=].
1. If |global| is not a [=secure context=], then [=reject=] |p| with a "{{NotAllowedError}}" {{DOMException}} and return |p|.
1. Let |parsedURL| be the the result of running the [=URL parser=] on |issuer|.
1. If |parsedURL| is failure, [=reject=] |p| with a "{{TypeError}}" {{DOMException}} and return |p|.
1. Let |origin| be |parsedURL|'s [=/origin=].
1. Let |topLevel| be the [=top-level origin=] of |doc|'s [=relevant settings object=].
1. Run the following steps [=in parallel=]:
    1. If associating |issuer| with |topLevel| [=determine whether associating an issuer would exceed the top-level limit|would exceed the top level’s number-of-issuers limit=], [=queue a global task=] on the [=networking task source=] given |global| to [=reject=] |p| with a "{{NotAllowedError}}" {{DOMException}} and return.
    1. [=Associate the issuer=] |origin| with |topLevel|.
    1. [=Look up the key commitments=] for |origin|. If there are key commitments,
             [=discard tokens=] from |origin| that are signed with keys other than those
             from the issuer's most recent commitments.
    1. [=Queue a global task=] on the [=networking task source=] given |global| to [=resolve=] |p| with true if there are tokens stored for the given issuer, with false otherwise.
1. Return |p|.

Note: This query modifies the user agent state. It associates the issuer
argument with the current origin. The specification allows at most 2 issuers associated
with an origin. This is to prevent leaking information through the issuers a
user has tokens from. Note that querying tokens triggers removal of stale tokens.

Redemption Record Query {#redemption-record-query}
--------------------------------------------------

When invoked on {{Document}} |doc| with {{USVString}} |issuer|, the <dfn export method for=Document><code>hasRedemptionRecord(issuer)</code></dfn> method must run these steps:

1. Let |p| be [=a new promise=].
1. If |doc| is not [=Document/fully active=], then [=reject=] |p| with an "{{InvalidStateError}}" {{DOMException}} and return |p|.
1. Let |global| be |doc|'s [=relevant global object=].
1. If |global| is not a [=secure context=], then [=reject=] |p| with a "{{NotAllowedError}}" {{DOMException}} and return |p|.
1. Let |parsedURL| be the the result of running the [=URL parser=] on |issuer|.
1. If |parsedURL| is failure, [=reject=] |p| with a "{{TypeError}}" {{DOMException}} and return |p|.
1. Let |origin| be |parsedURL|'s [=/origin=].
1. Let |topLevel| be the [=top-level origin=] of |doc|'s [=relevant settings object=].
1. Run the following steps [=in parallel=]:
    1. If |origin| [=is associated with|is not associated with=] |topLevel|, [=queue a global task=] on the [=networking task source=] given |global| to [=resolve=] |p| with false and return.
    1. [=Look up the key commitments=] for |origin|. If there are key commitments,
             [=discard tokens=] from |origin| that are signed with keys other than those
             from the issuer's most recent commitments.
    1. [=Queue a global task=] on the [=networking task source=] given |global| to [=resolve=] |p| with true if there is a [=redemption record=] for the issuer and top level pair, with false otherwise.
1. Return |p|.

Note: Similar to token query, redemption query might modify the user agent state. Unlike
token query, redemption query does not associate issuer with the top level
origin. There is no need to associate the issuer queried with the top level
origin, because the answer to the redemption query does not leak information about
the issuers of the currently stored tokens. Similar to token query, redemption
query clears stale tokens.

Private State Token HTTP Header Fields {#pst-http-header-fields}
=================================

The 'Sec-Private-State-Token' Header Field {#sec-private-state-token}
----------------------------

The <dfn http-header>Sec-Private-State-Token</dfn> *request* header field sends
a collection of unsigned, masked tokens during issuance. During redemption, it
sends a singled signed, unmasked token along with associated redemption
metadata.

The <a http-header>Sec-Private-State-Token</a> *response* header field sends
a collection of signed, masked tokens. During redemption it sends the
just-created signed [=redemption record=].

It is a [=Structured Header=] whose value MUST be an [=structured header/string=]
[[!RFC8941]].

The header’s ABNF is:

``` abnf
Sec-Private-State-Token = sf-string
```


The 'Sec-Private-State-Token-Lifetime' Header Field {#sec-private-state-token-lifetime}
----------------------------

The <dfn http-header>`Sec-Private-State-Token-Lifetime`</dfn> response header
field gives the expiration for the [=redemption record=]
given in the associated <a http-header>`Sec-Private-State-Token`</a>
response header. The expiration is given in seconds.

It is a [=Structured Header=] whose value MUST be an [=structured header/integer=]
[[!RFC8941]].

The header’s ABNF is:

``` abnf
Sec-Private-State-Token-Lifetime = sf-integer
```


The 'Sec-Private-State-Token-Crypto-Version' Header Field {#sec-private-state-token-crypto-version}
----------------------------

The <dfn http-header>`Sec-Private-State-Token-Crypto-Version`</dfn> header field gives
the cryptographic protocol version of the Private State Token.

It is a [=Structured Header=] whose value MUST be an [=structured header/string=]
[[!RFC8941]].

The header’s ABNF is:

``` abnf
Sec-Private-State-Token-Crypto-Version = sf-string
```

The 'Sec-Redemption-Record' Header Field {#sec-redemption-record}
----------------------------

The <dfn http-header>`Sec-Redemption-Record`</dfn> *request* header field sends
a cached [=redemption record=] of a previous redemption operation.

It is a [=Structured Header=] whose value MUST be an [=structured header/string=]
[[!RFC8941]].

The header’s ABNF is:

``` abnf
Sec-Redemption-Record = sf-string
```

Privacy Considerations {#privacy}
=================================

Unlinkability {#unlinkability}
------------------------------

Cryptographic protocols [[!VOPRF]] provide masked signatures. At
redemption time, issuers can recognize their signature on the provided token,
however they can not determine at what time or in which context they signed the token.
This prevents issuers from correlating their issuances on an origin with
redemptions on another origin. Issuers learn only the aggregate information
about the origins users visit.


Limiting Encoded Information {#limit-encoded-info}
--------------------------------------------------

User agents should enforce limits on the number of unique keys an issuer can have
at any point in time, to preserve client privacy.  Without limits, an issuer could
de-anonymize clients by simply using a unique key for each client. For [[!VOPRF]], the
number of keys is limited to six.

Issuers can utilize different keys to represent different "labels", which correspond
to an arbritrary client state, such as client trust level or some other useful
anti-fraud signal. Issuers are responsible for understanding this designation and
sharing the key "labels" with token redeemers so they know how to interpret the
significance of each token. This helps reduce reverse engineering from malicious
actors and preserves client privacy over human-readable labels. When using [[!VOPRF]],
the issuer's 6 keys can effectively represent six labels.

<h4 id="side-channel-fingerprinting">Potential Attack: Side Channel Fingerprinting</h4>

Unlinkability is lost if the issuer is able to use network-level fingerprinting
or any other side-channel and can associate the user agent at redemption time with
the user agent at token issuance time, even though the Private State Token API
itself has only stored and revealed limited amount of information about the
user agent.

Cross-site Information Transfer {#cross-site-info}
--------------------------------------------------

Private State Tokens transfer limited information between first-party contexts.
Underlying cryptographic protocols guarantee that each token only contains a
small amount of information. Still, if we allow many token redemptions on a
single page, the first-party cookie for user U on domain A can be encoded in
the Private State Token information channel and decoded on domain B, allowing
domain B to learn the user's domain A cookie until either 1p cookie is cleared.
Separate from the concern of channels allowing arbitrary communication between
domains, some identification attacks---for instance, a malicious redeemer
attempting to learn the exact set of issuers that have granted tokens to a
particular user, which could be identifying---have similar mitigations.

<h4 id="api-usage-limits">Mitigation: Dynamic Issuance/Redemption Limits</h4>

To mitigate this attack, the specification places limits on both issuance and redemption.
User activation with the issuing site is required in the issuing operation. The
specification does not allow a third redemption in an [=implementation-defined=] time window,
usually 48 hours.

<h4 id="per-issuer-limits">Mitigation: Per-Site Issuer Limits</h4>

The rate of identity leakage from one origin to another increases with the
number of issuers allowed in an origin. To avoid abuse, the user agent allows
association of at most two issuers per top level origin. Issuers are associated
with top level origins for token query API as well, see [[#token-query]].

Security Considerations {#security}
===================================

Preventing Token Exhaustion {#token-exhaustion}
-----------------------------------------------

Malicious origins might attempt to exhaust all tokens stored in the user agent by
redeeming them all. To prevent this, the specification limits the number of redemption
operations. In the context of a given origin, two redemptions are allowed initially. However,
the third redemption is only allowed once more than an [=implementation-defined=] amount of time,
usually 48 hours, have elapsed since the first redemption.

Preventing Double Spending {#preventing-double-spend}
-----------------------------------------------------

Issuers can verify that each token is seen only once, because every redemption
is sent to the same token issuer. This means that even if a malicious piece of
malware exfiltrates all of a user's tokens, the tokens will run out over time.
Issuers can sign fewer tokens at a time to mitigate the risk.

IANA Considerations {#iana-considerations}
==========================================

This document intends to define the <a http-header>Sec-Private-State-Token</a>,
<a http-header>Sec-Private-State-Token-Lifetime</a>, <a http-header>Sec-Private-State-Token-Crypto-Version</a>,
HTTP request header fields, and register them in the permanent message
header field registry ([[!RFC9110]]).

'Sec-Private-State-Token' Header Field {#iana-sec-private-state-token}
------------------------

Header field name: Sec-Private-State-Token

Applicable protocol: http

Status: standard

Author/Change controller: IETF

Specification document: this specification ([[#sec-private-state-token]])


'Sec-Private-State-Token-Lifetime' Header Field {#iana-sec-private-state-token-lifetime}
------------------------

Header field name: Sec-Private-State-Token-Lifetime

Applicable protocol: http

Status: standard

Author/Change controller: IETF

Specification document: this specification ([[#sec-private-state-token-lifetime]])


'Sec-Private-State-Token-Crypto-Version' Header Field {#iana-sec-private-state-token-crypto-version}
------------------------

Header field name: Sec-Private-State-Token-Crypto-Version

Applicable protocol: http

Status: standard

Author/Change controller: IETF

Specification document: this specification ([[#sec-private-state-token-crypto-version]])


'Sec-Redemption-Record' Header Field {#iana-sec-redemption-record}
------------------------

Header field name: Sec-Redemption-Record

Applicable protocol: http

Status: standard

Author/Change controller: IETF

Specification document: this specification ([[#sec-redemption-record]])


<h2 id=acknowledgments class=no-num>Acknowledgments</h2>

Thanks to Alex Kallam, Charlie Harrison, Chris Fredrickson, David Van Cleve, Dylan Cutler,
Eric Trouton, Johann Hofmann, Kaustubha Govind, Mike Taylor, Ryan Kalla, and Sam
Schlesinger for their contributions. Thanks to Chris Wilson for reviewing and mentoring this spec.