feat!: introduce new administrative capabilities

packages/capabilities/src/consumer.js

@@ -24,3 +24,21 @@ export const has = capability({
     )
   },
 })
+
+/**
+ * Capability can be invoked by a provider to get information about a consumer.
+ */
+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({})
+    )
+  },
+})

packages/capabilities/src/index.js

@@ -9,6 +9,8 @@ import * as Utils from './utils.js'
 import * as Consumer from './consumer.js'
 import * as Customer from './customer.js'
 import * as Console from './console.js'
+import * as RateLimit from './rate-limit.js'
+import * as Subscription from './subscription.js'
 import * as Filecoin from './filecoin.js'
 
 export {
@@ -23,6 +25,8 @@ export {
   Customer,
   Console,
   Utils,
+  RateLimit,
+  Subscription,
   Filecoin,
 }
 
@@ -47,6 +51,13 @@ export const abilitiesAsStrings = [
   Access.access.can,
   Access.authorize.can,
   Access.session.can,
+  Customer.get.can,
+  Consumer.has.can,
+  Consumer.get.can,
+  Subscription.get.can,
+  RateLimit.add.can,
+  RateLimit.remove.can,
+  RateLimit.list.can,
   Filecoin.filecoinAdd.can,
   Filecoin.aggregateAdd.can,
   Filecoin.dealAdd.can,

packages/capabilities/src/rate-limit.js

@@ -0,0 +1,71 @@
+/**
+ * Rate Limit Capabilities
+ *
+ * These can be imported directly with:
+ * ```js
+ * import * as RateLimit from '@web3-storage/capabilities/rate-limit'
+ * ```
+ *
+ * @module
+ */
+import { capability, DID, struct, Schema, ok } from '@ucanto/validator'
+import { equalWith, and, equal } from './utils.js'
+
+// e.g. did:web:web3.storage or did:web:staging.web3.storage
+export const Provider = DID
+
+/**
+ * Capability can be invoked by the provider or an authorized delegate to add a rate limit to a subject.
+ */
+export const add = capability({
+  can: 'rate-limit/add',
+  with: Provider,
+  nb: struct({
+    subject: Schema.string(),
+    rate: Schema.number(),
+  }),
+  derives: (child, parent) => {
+    return (
+      and(equalWith(child, parent)) ||
+      and(equal(child.nb.subject, parent.nb.subject, 'subject')) ||
+      and(equal(child.nb.rate, parent.nb.rate, 'rate')) ||
+      ok({})
+    )
+  },
+})
+
+/**
+ * Capability can be invoked by the provider are an authorized delegate to remove rate limits from a subject.
+ */
+export const remove = capability({
+  can: 'rate-limit/remove',
+  with: Provider,
+  nb: struct({
+    id: Schema.string(),
+  }),
+  derives: (child, parent) => {
+    return (
+      and(equalWith(child, parent)) ||
+      and(equal(child.nb.id, parent.nb.id, 'id')) ||
+      ok({})
+    )
+  },
+})
+
+/**
+ * Capability can be invoked by the provider or an authorized delegate to list rate limits on the given subject
+ */
+export const list = capability({
+  can: 'rate-limit/list',
+  with: Provider,
+  nb: struct({
+    subject: Schema.string(),
+  }),
+  derives: (child, parent) => {
+    return (
+      and(equalWith(child, parent)) ||
+      and(equal(child.nb.subject, parent.nb.subject, 'subject')) ||
+      ok({})
+    )
+  },
+})

packages/capabilities/src/subscription.js

@@ -0,0 +1,23 @@
+import { capability, DID, struct, ok, Schema } from '@ucanto/validator'
+import { equalWith, and, equal } from './utils.js'
+
+// e.g. did:web:web3.storage or did:web:staging.web3.storage
+export const ProviderDID = DID.match({ method: 'web' })
+
+/**
+ * Capability can be invoked by a provider to get information about a subscription.
+ */
+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({})
+    )
+  },
+})

packages/capabilities/src/types.ts

@@ -1,7 +1,7 @@
 import type { TupleToUnion } from 'type-fest'
 import * as Ucanto from '@ucanto/interface'
 import type { Schema } from '@ucanto/core'
-import { InferInvokedCapability, Unit, DID } from '@ucanto/interface'
+import { InferInvokedCapability, Unit, DID, DIDKey } from '@ucanto/interface'
 import type { PieceLink } from '@web3-storage/data-segment'
 import { space, info, recover, recoverValidation } from './space.js'
 import * as provider from './provider.js'
@@ -10,9 +10,16 @@ import { add, list, remove, store } from './store.js'
 import * as UploadCaps from './upload.js'
 import { claim, redeem } from './voucher.js'
 import * as AccessCaps from './access.js'
+import * as CustomerCaps from './customer.js'
+import * as ConsumerCaps from './consumer.js'
+import * as SubscriptionCaps from './subscription.js'
+import * as RateLimitCaps from './rate-limit.js'
 import * as FilecoinCaps from './filecoin.js'
 
 export type { Unit }
+
+export type AccountDID = DID<'mailto'>
+
 /**
  * failure due to a resource not having enough storage capacity.
  */
@@ -21,6 +28,11 @@ export interface InsufficientStorage {
   message: string
 }
 
+export interface UnknownProvider extends Ucanto.Failure {
+  name: 'UnknownProvider'
+  did: DID
+}
+
 export type PieceLinkSchema = Schema.Schema<PieceLink>
 
 // Access
@@ -67,6 +79,75 @@ export interface InvalidProvider extends Ucanto.Failure {
   name: 'InvalidProvider'
 }
 
+// Customer
+export type CustomerGet = InferInvokedCapability<typeof CustomerCaps.get>
+export interface CustomerGetSuccess {
+  did: AccountDID
+}
+export interface CustomerNotFound extends Ucanto.Failure {
+  name: 'CustomerNotFound'
+}
+export type CustomerGetFailure = CustomerNotFound | Ucanto.Failure
+
+// Consumer
+export type ConsumerHas = InferInvokedCapability<typeof ConsumerCaps.has>
+export type ConsumerHasSuccess = boolean
+export type ConsumerHasFailure = Ucanto.Failure
+export type ConsumerGet = InferInvokedCapability<typeof ConsumerCaps.get>
+export interface ConsumerGetSuccess {
+  did: DIDKey
+  allocated: number
+  total: number
+  subscription: string
+}
+export interface ConsumerNotFound extends Ucanto.Failure {
+  name: 'ConsumerNotFound'
+}
+export type ConsumerGetFailure = ConsumerNotFound | Ucanto.Failure
+
+// Subscription
+export type SubscriptionGet = InferInvokedCapability<
+  typeof SubscriptionCaps.get
+>
+export interface SubscriptionGetSuccess {
+  customer: AccountDID
+  consumer: DIDKey
+}
+export interface SubscriptionNotFound extends Ucanto.Failure {
+  name: 'SubscriptionNotFound'
+}
+export type SubscriptionGetFailure =
+  | SubscriptionNotFound
+  | UnknownProvider
+  | Ucanto.Failure
+
+// Rate Limit
+export type RateLimitAdd = InferInvokedCapability<typeof RateLimitCaps.add>
+export interface RateLimitAddSuccess {
+  id: string
+}
+export type RateLimitAddFailure = Ucanto.Failure
+
+export type RateLimitRemove = InferInvokedCapability<
+  typeof RateLimitCaps.remove
+>
+export type RateLimitRemoveSuccess = Unit
+
+export interface RateLimitsNotFound extends Ucanto.Failure {
+  name: 'RateLimitsNotFound'
+}
+export type RateLimitRemoveFailure = RateLimitsNotFound | Ucanto.Failure
+
+export type RateLimitList = InferInvokedCapability<typeof RateLimitCaps.list>
+export interface RateLimitSubject {
+  id: string
+  rate: number
+}
+export interface RateLimitListSuccess {
+  limits: RateLimitSubject[]
+}
+export type RateLimitListFailure = Ucanto.Failure
+
 // Space
 export type Space = InferInvokedCapability<typeof space>
 export type SpaceInfo = InferInvokedCapability<typeof info>
@@ -170,6 +251,13 @@ export type AbilitiesArray = [
   Access['can'],
   AccessAuthorize['can'],
   AccessSession['can'],
+  CustomerGet['can'],
+  ConsumerHas['can'],
+  ConsumerGet['can'],
+  SubscriptionGet['can'],
+  RateLimitAdd['can'],
+  RateLimitRemove['can'],
+  RateLimitList['can'],
   FilecoinAdd['can'],
   AggregateAdd['can'],
   DealAdd['can'],