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 explainer to final version of the API #294

Closed
wants to merge 1 commit into from
Closed

Update explainer to final version of the API #294

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
17 changes: 6 additions & 11 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>
}
}).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,10 +96,8 @@ 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'}
}
}).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 Down Expand Up @@ -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: ['https://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