Skip to content

Commit

Permalink
clean up pinning service spec (#87)
Browse files Browse the repository at this point in the history
Motivation:
* update after no updates for some time
* make name consistent with other filenames
* clarify that this is implemented fully, but point to w3-store.md for
implementations of the underlying store protocol
* update links to `store/*` capabilities to be latest in w3-store.md
  • Loading branch information
gobengo authored Jan 17, 2024
1 parent 32806f9 commit 47bf3c4
Showing 1 changed file with 28 additions and 22 deletions.
50 changes: 28 additions & 22 deletions Pinning Service.md → w3-store-ipfs-pinning.md
Original file line number Diff line number Diff line change
@@ -1,39 +1,43 @@
# Web3 Pinning Service
# w3-store Authorization + IPFS Pinning Service API

![wip](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square)

We reimagine IPFS [pinning service][] as web3 service, where:
## Implementations

- Users delegate necessary capabilities to the pinning service as opposed to getting [access token][]s from the service which must be kept secret.
- As an API layer on top of core upload v2 protocol.
There are no known implementations of w3-store Authorization + IPFS Pinning Service API.

Below table maps [IPFS pinning service API][pinning service] operations to capabilities necessary to execute them
See [w3-store](./w3-store.md) for implementations of the storage protocol that this refers to.

## Description

We reimagine IPFS [pinning service][] as a web3 service, where:

- Users delegate necessary capabilities to the pinning service as [UCAN][]s opposed to sharing powerful bearer [access token][]s that must be kept secret by both client and pinning service, and client must trust pinning service to only use as intended
- As a layer on top of [w3-store](./w3-store.md) protocol

The following table maps [IPFS pinning service API][pinning service] operations to capabilities necessary to execute them

| Operation | Capabilities |
| ----------------------------------------------------------------------------------------------------- | ---------------------------------- |
| [add](https://ipfs.github.io/pinning-services-api-spec/#tag/pins/paths/~1pins/post) | [`store/add`][] |
| [remove](https://ipfs.github.io/pinning-services-api-spec/#tag/pins/paths/~1pins~1{requestid}/delete) | [`store/remove`][] |
| [list](https://ipfs.github.io/pinning-services-api-spec/#tag/pins/paths/~1pins/get) | [`store/list`][] |
| [replace](https://ipfs.github.io/pinning-services-api-spec/#tag/pins/paths/~1pins~1{requestid}/post) | [`store/add`][] [`store/remove`][] |
| [get](https://ipfs.github.io/pinning-services-api-spec/#tag/pins/paths/~1pins~1{requestid}/get) | [`store/list`][] |
| [get](https://ipfs.github.io/pinning-services-api-spec/#tag/pins/paths/~1pins~1{requestid}/get) | [`store/get`][] |

Our pinning service implementation will accept [access token] that are valid JWT formatted [UCAN][]s where:
a w3 pinning service accepts requests whose access token is a [UCAN JWT][] where:

1. Root issuer is the same DID as one in `with` field of the delegated capabilities.
2. DID in `with` field is associated with some account.
3. Where all the provided [proofs are embedded](https://github.com/ipld/js-dag-ucan#embedding-proofs) inline.

> ⚠️ It is worth calling out that just like typical [access token][]s these do not need to be kept secret as well, since if compromised they could be used to pin arbitrary data.
2. DID in `with` field is associated with some account on the Pinning Service.
3. All the linked [proofs are embedded](https://github.com/ipld/js-dag-ucan#embedding-proofs) inline.

This offers following advantages to typical bearer tokens:
Using UCANs for authorization offers following advantages to typical [bearer tokens](https://oauth.net/2/bearer-tokens/):

1. Users are able to delegate access to [pinning service] to others.
2. Users could tokens with subset of capabilities and consequently restricting access to desired operations.
3. Users could revoke and rotate tokens as they wish.
1. Users are able to delegate access to [pinning service] to other DIDs.
2. Users can delegate access to only a subset of their authorizations, restricting access to desired operations.
3. Users can revoke and rotate tokens as they wish.

> This also creates an opportunity for implementing better [pinning service][] clients issue short lived tokens per operation and remove the need for keeping tokens secret.
>
> [@ipld/dag-ucan](https://www.npmjs.com/package/@ipld/dag-ucan) library could be used to issue such tokens
This also creates an opportunity for implementing better [pinning service][] clients that issue short lived tokens for each operation and remove the need for keeping tokens secret. [@ipld/dag-ucan](https://www.npmjs.com/package/@ipld/dag-ucan) library could be used to issue such tokens

## Request ID

Expand Down Expand Up @@ -77,7 +81,9 @@ While UCAN validation is not strictly necessary (as they get verified downstream
[pinning service]: https://ipfs.github.io/pinning-services-api-spec/
[link-type]: https://github.com/ipld/js-dag-ucan/blob/364379b54cae383198fcf6a9c0016b497e62d422/src/ucan.ts#L227-L242
[access token]: https://ipfs.github.io/pinning-services-api-spec/#section/Authentication/accessToken
[`store/add`]: https://github.com/web3-storage/ucanto/blob/w3/w3/store/src/type/store.ts#L76-L78
[`store/remove`]: https://github.com/web3-storage/ucanto/blob/w3/w3/store/src/type/store.ts#L80-L82
[`store/list`]: https://github.com/web3-storage/ucanto/blob/w3/w3/store/src/type/store.ts#L84
[ucan]: https://github.com/ucan-wg/spec/
[`store/add`]: https://github.com/web3-storage/specs/blob/main/w3-store.md#storeadd
[`store/remove`]: https://github.com/web3-storage/specs/blob/main/w3-store.md#storeremove
[`store/list`]: https://github.com/web3-storage/specs/blob/main/w3-store.md#storelist
[`store/get`]: https://github.com/web3-storage/specs/blob/main/w3-store.md#storeget
[UCAN]: https://github.com/ucan-wg/spec/
[UCAN JWT]: https://github.com/ucan-wg/spec/tree/692e8aab59b763a783fe1484131c3f40d997b69a#3-jwt-structure

0 comments on commit 47bf3c4

Please sign in to comment.