Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update fetch API in explainer #277

Merged
merged 3 commits into from
Mar 27, 2024
+10 −15
Merged

Update fetch API in explainer #277

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8ad4ec4
Update fetch API in explainer
aykutbulut Nov 3, 2023
942cc54
Merge branch 'WICG:main' into fix_fetch_api
aykutbulut Mar 12, 2024
83aa022
Issuer list should have https schemes
aykutbulut Mar 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 10 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,10 +64,8 @@ When an `issuer.example` context wants to provide tokens to a user (i.e. when th
```
fetch('<issuer>/<issuance path>', {
privateToken: {
type: 'private-state-token',
version: 1,
operation: 'token-request',
issuer: <issuer>
operation: 'token-request'
}
}).then(...)
```
Expand All @@ -88,7 +86,7 @@ When the user is browsing another site (```publisher.example```), that site (or


```
document.hasPrivateToken(<issuer>, 'private-state-token')
document.hasPrivateToken(<issuer>)
```


Expand All @@ -98,11 +96,9 @@ This returns whether there are any valid private state tokens for a particular i
```
fetch('<issuer>/<redemption path>', {
privateToken: {
type: 'private-state-token',
version: 1,
operation: 'token-redemption',
issuer: <issuer>,
refreshPolicy: {'none', 'refresh'}
refreshPolicy: 'refresh' // either 'refresh' or 'none', default is 'none'
}
}).then(...)
```
Expand All @@ -115,7 +111,7 @@ The RR is HTTP-only and JavaScript is only able to access/send the RR via Privat
UA stores the RR obtained from the initial redemption. A publisher site can query whether a valid RR exists for a specific issuer using the following method.

```
document.hasRedemptionRecord(<issuer>, 'private-state-token')
document.hasRedemptionRecord(<issuer>)
```

This returns whether there are any valid RRs from the given issuer.
Expand All @@ -133,7 +129,6 @@ Redemption Records are only accessible via a new option to the Fetch API:
fetch(<resource-url>, {
...
privateToken: {
type: 'private-state-token',
version: 1,
operation: 'send-redemption-record',
issuers: [<issuer>, ...]
Expand All @@ -148,9 +143,9 @@ The RRs will be added as a new request header `Sec-Redemption-Record`. The heade

### Extension: Private State Token Versioning

In order to allow multiple versions of Private State Token to be supported in the ecosystem, issuers include the version of the protocol (i.e. "PrivateStateTokenV1") in their key commitments via the ```protocol_version``` field, and that is included in Private State Token requests via the ```Sec-Private-State-Token-Version``` header. Private State Token operations should not be performed with issuers configured with an unknown protocol version.
In order to allow multiple versions of Private State Token to be supported in the ecosystem, issuers include the version of the protocol (i.e. "PrivateStateTokenV1") in their key commitments via the ```protocol_version``` field, and that is included in Private State Token requests via the ```Sec-Private-State-Token-Crypto-Version``` header. Private State Token operations should not be performed with issuers configured with an unknown protocol version.

In addition to the core cryptographic layer, signed requests' formats (see the next section) might change from version to version. In order to make adapting to these changes easier, we could employ a mechanism like the ```Sec-Private-State-Token-Version``` header, or an addition to the requests' payloads, to tell consumers the version of the client that generated the request.
In addition to the core cryptographic layer, signed requests' formats (see the next section) might change from version to version. In order to make adapting to these changes easier, we could employ a mechanism like the ```Sec-Private-State-Token-Crypto-Version``` header, or an addition to the requests' payloads, to tell consumers the version of the client that generated the request.


### Extension: Metadata
Expand All @@ -170,7 +165,7 @@ This can be managed by assigning different keys in the key commitment to have di

### Extension: iframe Activation

Some resources requests are performed via iframes or other non-Fetch-based methods. One extension to support such use cases would be the addition of a `privateToken` attribute to iframes that includes the parameters specified in the Fetch API. This would allow an RR to be sent with an iframe by setting an attribute of `privateToken="{type:'private-state-token',version:1,operation:'send-redemption-record',issuer:<issuer>,refreshPolicy:'refresh'}"`.
Some resources requests are performed via iframes or other non-Fetch-based methods. One extension to support such use cases would be the addition of a `privateToken` attribute to iframes that includes the parameters specified in the Fetch API. This would allow an RR to be sent with an iframe by setting an attribute of `privateToken="{version:1,operation:'send-redemption-record',issuers:[<issuer>]}"`.

## Privacy Considerations

Expand Down Expand Up @@ -280,14 +275,14 @@ foo.example - Site requiring a Private State Token to prove the user is trusted.


1. User visits `areyouahuman.example`.
1. `areyouahuman.example` verifies the user is a human, and calls `fetch('areyouahuman.example/get-human-tokens', {privateToken: {type: 'private-state-token', version: 1, operation: 'token-request', issuer: 'areyouahuman.example'}})`.
1. `areyouahuman.example` verifies the user is a human, and calls `fetch('areyouahuman.example/get-human-tokens', {privateToken: {version: 1, operation: 'token-request'}})`.
1. The browser stores the trust tokens associated with `areyouahuman.example`.
1. Sometime later, the user visits `coolwebsite.example`.
1. `coolwebsite.example` wants to know if the user is a human, by asking `areyouahuman.example` that question, by calling `fetch('areyouahuman.example/redeem-human-token', {privateToken: {type: 'private-state-token', version: 1, operation: 'token-redemption', issuer: 'areyouahuman.example'}})`.
1. `coolwebsite.example` wants to know if the user is a human, by asking `areyouahuman.example` that question, by calling `fetch('areyouahuman.example/redeem-human-token', {privateToken: {version: 1, operation: 'token-redemption'}})`.
1. The browser requests a redemption.
1. The issuer returns an RR (this indicates that `areyouahuman.example` at some point issued a valid token to this browser).
1. When the promise returned by the method resolves, the RR can be used in subsequent resource requests.
1. Script running code in the top level `coolwebsite.example` document can call `fetch('foo.example/get-content', {privateToken: {type: 'private-state-token', version: 1, operation: 'send-redemption-record', issuer: 'areyouahuman.example'}})`
1. Script running code in the top level `coolwebsite.example` document can call `fetch('foo.example/get-content', {privateToken: {version: 1, operation: 'send-redemption-record', issuers: ['areyouahuman.example']}})`
1. The third-party receives the RR, and now has some indication that `areyouahuman.example` thought this user was a human.
1. The third-party responds to this fetch request based on that fact.

Expand Down
Loading