feat!: introduce new administrative capabilities

packages/aggregate-api/src/aggregate/offer.js

@@ -1,6 +1,10 @@
 import * as Server from '@ucanto/server'
 import { CBOR } from '@ucanto/core'
-import { Node, Piece, Aggregate as AggregateBuilder } from '@web3-storage/data-segment'
+import {
+  Node,
+  Piece,
+  Aggregate as AggregateBuilder,
+} from '@web3-storage/data-segment'
 import * as Aggregate from '@web3-storage/capabilities/aggregate'
 import * as Offer from '@web3-storage/capabilities/offer'
 import * as API from '../types.js'
@@ -62,10 +66,12 @@ export const claim = async (
   // Validate commP of commPs
   const aggregateBuild = AggregateBuilder.build({
     size: aggregateSize,
-    pieces: offers.map(offer => Piece.fromJSON({
-      height: offer.height,
-      link: { '/': offer.link.toString() }
-    }))
+    pieces: offers.map((offer) =>
+      Piece.fromJSON({
+        height: offer.height,
+        link: { '/': offer.link.toString() },
+      })
+    ),
   })
   if (!aggregateBuild.link.equals(piece.link)) {
     return {

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

@@ -11,6 +11,8 @@ import * as Customer from './customer.js'
 import * as Console from './console.js'
 import * as Offer from './offer.js'
 import * as Aggregate from './aggregate.js'
+import * as RateLimit from './rate-limit.js'
+import * as Subscription from './subscription.js'
 
 export {
   Access,
@@ -26,6 +28,8 @@ export {
   Utils,
   Aggregate,
   Offer,
+  RateLimit,
+  Subscription,
 }
 
 /** @type {import('./types.js').AbilitiesArray} */
@@ -52,4 +56,11 @@ export const abilitiesAsStrings = [
   Aggregate.offer.can,
   Aggregate.get.can,
   Offer.arrange.can,
+  Customer.get.can,
+  Consumer.has.can,
+  Consumer.get.can,
+  Subscription.get.can,
+  RateLimit.add.can,
+  RateLimit.remove.can,
+  RateLimit.list.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 an agent 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 an agent 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 an agent to list rate limits on a 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'
@@ -12,8 +12,15 @@ import { claim, redeem } from './voucher.js'
 import * as AccessCaps from './access.js'
 import * as AggregateCaps from './aggregate.js'
 import * as OfferCaps from './offer.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'
 
 export type { Unit }
+
+export type AccountDID = DID<'mailto'>
+
 /**
  * failure due to a resource not having enough storage capacity.
  */
@@ -22,6 +29,11 @@ export interface InsufficientStorage {
   message: string
 }
 
+export interface UnknownProvider extends Ucanto.Failure {
+  name: 'UnknownProvider'
+  did: DID
+}
+
 export type PieceLinkSchema = Schema.Schema<PieceLink>
 
 // Access
@@ -68,6 +80,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>
@@ -147,5 +228,12 @@ export type AbilitiesArray = [
   AccessSession['can'],
   AggregateOffer['can'],
   AggregateGet['can'],
-  OfferArrange['can']
+  OfferArrange['can'],
+  CustomerGet['can'],
+  ConsumerHas['can'],
+  ConsumerGet['can'],
+  SubscriptionGet['can'],
+  RateLimitAdd['can'],
+  RateLimitRemove['can'],
+  RateLimitList['can']
 ]