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.

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

link to implementations of w3-session.md #98

Merged
merged 2 commits into from
Jan 19, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
1 change: 1 addition & 0 deletions .github/workflows/words-to-ignore.txt
Original file line number Diff line number Diff line change
Expand Up @@ -134,3 +134,4 @@ Irakli
Gozalishvili
Vasco
invoker
upload-api
35 changes: 35 additions & 0 deletions w3-session.md
Original file line number Diff line number Diff line change
Expand Up @@ -172,6 +172,10 @@ In general, it is RECOMMENDED that [agents] only request the set of capabilities
}
```

### Implementations

- [`{ authorize }` from `@web3-storage/capabilities/access`](https://github.com/web3-storage/w3up/blob/10a1a4bfc5ec79ea0b7b2049fd7d1953ca0810ef/packages/capabilities/src/access.js#L65)

## Authorization

An [oracle] MUST provide `access/authorize` capability. When this capability is invoked, the [oracle] MUST facilitate an out-of-bound authorization flow that allows the [account] holder to select which capabilities they wish to grant. It is RECOMMENDED that the [oracle] by default presents only a subset of capabilities that match the request criteria.
Expand Down Expand Up @@ -202,6 +206,17 @@ If the user denies the authorization request, the corresponding `access/authoriz
}
```

### Implementations

#### @web3-storage/capabilities

- [`access/authorize` capability parser](https://github.com/web3-storage/w3up/blob/e34eed1fa3d6ef24ce2c01982764f2012dbf30d8/packages/capabilities/src/access.js#L65) nb field is [`AuthorizationRequest`](https://github.com/web3-storage/w3up/blob/e34eed1fa3d6ef24ce2c01982764f2012dbf30d8/packages/capabilities/src/access.js#L40) parser

#### @web3-storage/upload-api

- has an [access service](https://github.com/web3-storage/w3up/blob/e34eed1fa3d6ef24ce2c01982764f2012dbf30d8/packages/upload-api/src/access.js#L10) that acts as this authorization oracle and sends authorization request emails in response to `access/authorize` invocations that mention `did:mailto` accounts
- `access/authorize` invocation handler [generates `access/confirm` invocation](https://github.com/web3-storage/w3up/blob/e34eed1fa3d6ef24ce2c01982764f2012dbf30d8/packages/upload-api/src/access/authorize.js#L57), encodes it into a clickable URL, and then includes a link to that URL (with self-signed `access/confirm` invocation) in confirmation email. The `access/confirm` is not invoked unless the confirmation link in the confirmation email is followed.

## Authorization Session

An authorization session is a UCAN delegation from the [authority] to the [agent]. It is an attestation issued by a trusted third party _(such as an [oracle])_ indicating that the [account] holder has authorized a specific delegation (specified by the `nb.proof` field).
Expand Down Expand Up @@ -280,6 +295,26 @@ The value of the `with` field MUST be the DID of the [authority], indicating tha

Authorization sessions only apply to UCANs that have a [proof] linking to them. They are subject to UCAN [time bounds] and [revocation]s. The session only covers UCANs that meet the standard [principal alignment] requirement.

### Implementations

#### @ucanto/validator

- tested in [session.spec.js](https://github.com/web3-storage/ucanto/blob/main/packages/validator/test/session.spec.js)

#### @web3-storage/capabilities

- [`ucan/attest` capability parser](https://github.com/web3-storage/w3up/blob/e34eed1fa3d6ef24ce2c01982764f2012dbf30d8/packages/capabilities/src/ucan.js#L102)

#### @web3-storage/upload-api

- supports w3-session [via `@ucanto/server`](https://github.com/web3-storage/w3up/blob/main/packages/upload-api/src/lib.js#L28)
- deployed to [up.web3.storage](https://up.web3.storage) via [w3infra](https://github.com/web3-storage/w3infra)
- `access/confirm` handler [creates session proofs](https://github.com/web3-storage/w3up/blob/main/packages/upload-api/src/access/confirm.js#L60) and [includes in result](https://github.com/web3-storage/w3up/blob/main/packages/upload-api/src/access/confirm.js#L93)

#### @web3-storage/access

- [Agent.proofs](https://github.com/web3-storage/w3up/blob/e34eed1fa3d6ef24ce2c01982764f2012dbf30d8/packages/access-client/src/agent.js#L275) is aware of w3-session proofs

[`did:mailto`]: https://github.com/ucan-wg/did-mailto/
[`did:key`]: https://w3c-ccg.github.io/did-method-key/
[ucan]: https://github.com/ucan-wg/spec/
Expand Down