w3-admin.md

Admin Protocol

Editors

• Travis Vachon, Protocol Labs

Authors

• Travis Vachon, Protocol Labs

Abstract

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
  • consumer/get
  • customer/get
  • subscription/get
  • admin/upload/inspect
  • admin/store/inspect

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.

Capabilities

consumer/get

Get information about a consumer (i.e., a space).

A consumer MAY be associated with a subscription. Customers are charged data storage and egress fees for spaces that are consuming their subscriptions.

inputs

consumer: SpaceDID

returns

{
  did: SpaceDID
  allocated: number
  limit: number
  subscription: string
}

errors

ConsumerNotFound

capability definition

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({})
    )
  },
})

Implementations

• @web3-storage/capabilities: capability in consumer.js
• @web3-storage/upload-api: invocation handler in consumer/get.js

customer/get

Get information about a customer.

Customers MAY have 0 or more subscriptions. Subscriptions are consumable by spaces. Customers are charged data storage and egress fees for spaces that are consuming their subscriptions.

inputs

customer: DID<mailto>

returns

{
  did: AccountDID
  subscriptions: string[]
}

errors

CustomerNotFound

capability definition

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({})
    )
  },
})

Implementations

• @web3-storage/capabilities: capability in customer.js
• @web3-storage/upload-api: invocation handler in customer/get.js

subscription/get

Get information about a subscription.

Subscriptions are owned by customers and consumed by spaces. Customers are charged data storage and egress fees for spaces that are consuming their subscriptions.

inputs

subscription: string

returns

{
  customer: DID<mailto>
  consumer?: SpaceDID
}

errors

SubscriptionNotFound

capability definition

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({})
    )
  },
})

Implementations

• @web3-storage/capabilities: capability in subscription.js
• @web3-storage/upload-api: invocation handler in subscription/get.js

admin/upload/inspect

Get information about a content CID. This does not return the actual data identified by the CID, just metadata our system tracks, e.g. the spaces the content identified by a given CID has been uploaded to and the dates the uploads happened.

inputs

root: CID

returns

The uploads property will be a list of spaces the given root CID's content has been uploaded to, along with the date it was uploaded.

{
  uploads: Array<{space: SpaceDID, insertedAt: Date}>
}

Implementations

• @web3-storage/capabilities: capability in admin.js
• @web3-storage/upload-api: invocation handler in admin/upload/inspect.js

admin/store/inspect

Get information about a shard (i.e., a CAR that contains part of an upload) CID. This does not return the actual data identified by the CID, just metadata our system tracks, e.g. the spaces the CAR identified by a given CID has been stored in and the date it was stored.

inputs

link: CID

returns

The stores property will be a list of spaces the specified shard was stored in, along with the date on which it was stored.

{
  stores: Array<{space: SpaceDID, insertedAt: Date}>
}

Implementations

• @web3-storage/capabilities: capability in admin.js
• @web3-storage/upload-api: invocation handler in admin/store/inspect.js