From 2874fb46cf00632a7562c7fbf3e8e84389df30e2 Mon Sep 17 00:00:00 2001 From: Travis Vachon Date: Fri, 8 Sep 2023 12:08:37 -0700 Subject: [PATCH 1/3] feat: add documentation for w3admin related capabilities I think these deserve their own spec (and that we could potentially fold the rate-limits spec into this one) since they all act against the service resource itself. --- w3-admin.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 w3-admin.md diff --git a/w3-admin.md b/w3-admin.md new file mode 100644 index 0000000..583efcc --- /dev/null +++ b/w3-admin.md @@ -0,0 +1,149 @@ +# Admin Protocol + +![status:wip](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) + +## Editors + +- [Travis Vachon](https://github.com/travis), [Protocol Labs](https://protocol.ai/) + +## Authors + +- [Travis Vachon](https://github.com/travis), [Protocol Labs](https://protocol.ai/) + +# Abstract + +Storage providers in the w3 family of protocols need to be able to get information about the customers, subscriptions and "consumers" (ie, spaces) +they work with. The capabilities described in this document all act on the "service" resource (ie, `did:web:web3.storage`) and can be delegated +to administrative users by creating delegations signed with the service signer's private key. + +- [Capabilities](#capabilities) + - [`consumer/get`](#consumer-get) + - [`customer/get`](#customer-get) + - [`subscription/get`](#subscription-get) + +## Language + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119](https://datatracker.ietf.org/doc/html/rfc2119). + +## Capabilities + +### consumer/get + +Get information about a consumer (ie, a space). + +#### inputs + +`consumer: SpaceDID` + +#### returns + +```typescript +{ + did: SpaceDID + allocated: number + limit: number + subscription: string +} +``` + +#### errors + +`ConsumerNotFound` + +#### capability definition + +```javascript= +export const get = capability({ + can: 'consumer/get', + with: ProviderDID, + nb: struct({ + consumer: SpaceDID, + }), + derives: (child, parent) => { + return ( + and(equalWith(child, parent)) || + and(equal(child.nb.consumer, parent.nb.consumer, 'consumer')) || + ok({}) + ) + }, +}) +``` + +### customer/get + +Get information about a customer. + +#### inputs + +`customer: DID` + +#### returns + +```typescript + did: AccountDID + subscriptions: string[] +} +``` + +#### errors + +`CustomerNotFound` + +#### capability definition + +```javascript= +export const get = capability({ + can: 'customer/get', + with: ProviderDID, + nb: struct({ + customer: AccountDID, + }), + derives: (child, parent) => { + return ( + and(equalWith(child, parent)) || + and(equal(child.nb.customer, parent.nb.customer, 'customer')) || + ok({}) + ) + }, +}) +``` + +### subscription/get + +Get information about a subscription. + +#### inputs + +`subscription: string` + +#### returns + +```typescript +{ + customer: DID + consumer?: SpaceDID +} +``` + +#### errors + +`SubscriptionNotFound` + +#### capability definition + +```javascript= +export const get = capability({ + can: 'subscription/get', + with: ProviderDID, + nb: struct({ + subscription: Schema.string(), + }), + derives: (child, parent) => { + return ( + and(equalWith(child, parent)) || + and(equal(child.nb.subscription, parent.nb.subscription, 'consumer')) || + ok({}) + ) + }, +}) +``` From 5d00480312251e4c78ee871bdefe355f9ba9b9da Mon Sep 17 00:00:00 2001 From: Travis Vachon Date: Fri, 8 Sep 2023 12:13:49 -0700 Subject: [PATCH 2/3] fix: spelling and link errors --- w3-admin.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/w3-admin.md b/w3-admin.md index 583efcc..cfe5c67 100644 --- a/w3-admin.md +++ b/w3-admin.md @@ -12,14 +12,14 @@ # Abstract -Storage providers in the w3 family of protocols need to be able to get information about the customers, subscriptions and "consumers" (ie, spaces) -they work with. The capabilities described in this document all act on the "service" resource (ie, `did:web:web3.storage`) and can be delegated +Storage providers in the w3 family of protocols need to be able to get information about the customers, subscriptions and "consumers" (i.e., spaces) +they work with. The capabilities described in this document all act on the "service" resource (i.e., `did:web:web3.storage`) and can be delegated to administrative users by creating delegations signed with the service signer's private key. - [Capabilities](#capabilities) - - [`consumer/get`](#consumer-get) - - [`customer/get`](#customer-get) - - [`subscription/get`](#subscription-get) + - [`consumer/get`](#consumerget) + - [`customer/get`](#customerget) + - [`subscription/get`](#subscriptionget) ## Language @@ -29,7 +29,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S ### consumer/get -Get information about a consumer (ie, a space). +Get information about a consumer (i.e., a space). #### inputs From 1a12b73bbd56f73b5154fc8792e85d7c972a7cc1 Mon Sep 17 00:00:00 2001 From: Travis Vachon Date: Mon, 11 Sep 2023 10:59:56 -0700 Subject: [PATCH 3/3] Apply typo fixes from code review Co-authored-by: Alan Shaw --- w3-admin.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/w3-admin.md b/w3-admin.md index cfe5c67..4fa9538 100644 --- a/w3-admin.md +++ b/w3-admin.md @@ -27,7 +27,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S ## Capabilities -### consumer/get +### `consumer/get` Get information about a consumer (i.e., a space). @@ -52,7 +52,7 @@ Get information about a consumer (i.e., a space). #### capability definition -```javascript= +```javascript export const get = capability({ can: 'consumer/get', with: ProviderDID, @@ -69,7 +69,7 @@ export const get = capability({ }) ``` -### customer/get +### `customer/get` Get information about a customer. @@ -80,6 +80,7 @@ Get information about a customer. #### returns ```typescript +{ did: AccountDID subscriptions: string[] } @@ -91,7 +92,7 @@ Get information about a customer. #### capability definition -```javascript= +```javascript export const get = capability({ can: 'customer/get', with: ProviderDID, @@ -108,7 +109,7 @@ export const get = capability({ }) ``` -### subscription/get +### `subscription/get` Get information about a subscription. @@ -131,7 +132,7 @@ Get information about a subscription. #### capability definition -```javascript= +```javascript export const get = capability({ can: 'subscription/get', with: ProviderDID,