feat: access-api handles provider/add invocations

packages/access-api/migrations/0006_add_storage_provider_consumer_schema.sql

@@ -0,0 +1,21 @@
+-- Migration number: 0006 	 2023-03-02T16:40:04.407Z
+
+/*
+goal: add a table to keep track of the storage provider for a space.
+to enable https://github.com/web3-storage/w3protocol/issues/459
+*/
+
+CREATE TABLE
+    -- provision: the action of providing or supplying something for use
+    -- use case: representing the registration of a storage provider to a space
+    IF NOT EXISTS provisions (
+        id INTEGER NOT NULL PRIMARY KEY,
+        -- DID of the actor that is consuming the provider. e.g. a space DID
+        consumer TEXT NOT NULL,
+        -- DID of the provider e.g. a storage provider
+        provider TEXT NOT NULL,
+        -- DID of the actor that issued this provision
+        issuer TEXT NOT NULL,
+        inserted_at TEXT NOT NULL DEFAULT (strftime ('%Y-%m-%dT%H:%M:%fZ', 'now')),
+        updated_at TEXT NOT NULL DEFAULT (strftime ('%Y-%m-%dT%H:%M:%fZ', 'now'))
+    );

packages/access-api/src/bindings.d.ts

@@ -63,10 +63,11 @@ export interface RouteContext {
   url: URL
   email: Email
   models: {
-    spaces: Spaces
-    validations: Validations
     accounts: Accounts
     delegations: Delegations
+    spaces: Spaces
+    storageProvisions: StorageProvisions
+    validations: Validations
   }
   uploadApi: ConnectionView
 }

packages/access-api/src/models/provisions.js

@@ -0,0 +1,99 @@
+/* eslint-disable no-void */
+
+/**
+ * @typedef {import("../types/provisions").StorageProvisions} StorageProvisions
+ */
+
+/**
+ * @param {Array<import("../types/provisions").StorageProvisionCreation>} storage
+ * @returns {StorageProvisions}
+ */
+export function createStorageProvisions(storage = []) {
+  /** @type {StorageProvisions['hasStorageProvider']} */
+  const hasStorageProvider = async (consumerId) => {
+    const hasRowWithSpace = storage.some(({ space }) => space === consumerId)
+    return hasRowWithSpace
+  }
+  /** @type {StorageProvisions['putMany']} */
+  const putMany = async (...items) => {
+    storage.push(...items)
+  }
+  /** @type {StorageProvisions['count']} */
+  const count = async () => {
+    return BigInt(storage.length)
+  }
+  return {
+    count,
+    putMany,
+    hasStorageProvider,
+  }
+}
+
+/**
+ * @typedef ProvsionsRow
+ * @property {string} consumer
+ * @property {string} provider
+ * @property {string} issuer - did of actor who did the provisioning
+ */
+
+/**
+ * @typedef {import("../types/database").Database<{ provisions: ProvsionsRow }>} ProvisionsDatabase
+ */
+
+/**
+ * StorageProvisions backed by a kyseli database (e.g. sqlite or cloudflare d1)
+ */
+export class DbStorageProvisions {
+  /** @type {ProvisionsDatabase} */
+  #db
+
+  /**
+   * @param {ProvisionsDatabase} db
+   */
+  constructor(db) {
+    this.#db = db
+    this.tableNames = {
+      provisions: /** @type {const} */ ('provisions'),
+    }
+    void (/** @type {StorageProvisions} */ (this))
+  }
+
+  /** @type {StorageProvisions['count']} */
+  async count(...items) {
+    const { size } = await this.#db
+      .selectFrom(this.tableNames.provisions)
+      .select((e) => e.fn.count('provider').as('size'))
+      .executeTakeFirstOrThrow()
+    return BigInt(size)
+  }
+
+  /** @type {StorageProvisions['putMany']} */
+  async putMany(...items) {
+    if (items.length === 0) {
+      return
+    }
+    /** @type {ProvsionsRow[]} */
+    const rows = items.map((item) => {
+      return {
+        consumer: item.space,
+        provider: item.provider,
+        issuer: item.account,
+      }
+    })
+    await this.#db
+      .insertInto(this.tableNames.provisions)
+      .values(rows)
+      .executeTakeFirstOrThrow()
+  }
+
+  /** @type {StorageProvisions['hasStorageProvider']} */
+  async hasStorageProvider(consumerDid) {
+    const { provisions } = this.tableNames
+    const { size } = await this.#db
+      .selectFrom(provisions)
+      .select((e) => e.fn.count('provider').as('size'))
+      .where(`${provisions}.consumer`, '=', consumerDid)
+      .executeTakeFirstOrThrow()
+    return size > 0
+  }
+}

packages/access-api/src/service/index.js

@@ -1,4 +1,5 @@
 import * as ucanto from '@ucanto/core'
+import * as Ucanto from '@ucanto/interface'
 import * as Server from '@ucanto/server'
 import { Failure } from '@ucanto/server'
 import * as Space from '@web3-storage/capabilities/space'
@@ -13,6 +14,7 @@ import * as uploadApi from './upload-api-proxy.js'
 import { accessAuthorizeProvider } from './access-authorize.js'
 import { accessDelegateProvider } from './access-delegate.js'
 import { accessClaimProvider } from './access-claim.js'
+import { providerAddProvider } from './provider-add.js'
 
 /**
  * @param {import('../bindings').RouteContext} ctx
@@ -22,6 +24,12 @@ import { accessClaimProvider } from './access-claim.js'
  * }
  */
 export function service(ctx) {
+  /**
+   * @param {Ucanto.DID<'key'>} uri
+   */
+  const hasStorageProvider = async (uri) => {
+    return Boolean(await ctx.models.spaces.get(uri))
+  }
   return {
     store: uploadApi.createStoreProxy(ctx),
     upload: uploadApi.createUploadProxy(ctx),
@@ -45,12 +53,21 @@ export function service(ctx) {
         }
         return accessDelegateProvider({
           delegations: ctx.models.delegations,
-          hasStorageProvider: async (uri) => {
-            return Boolean(await ctx.models.spaces.get(uri))
-          },
+          hasStorageProvider,
         })(...args)
       },
     },
+
+    provider: {
+      add: (...args) => {
+        // disable until hardened in test/staging
+        if (ctx.config.ENV === 'production') {
+          throw new Error(`provider/add invocation handling is not enabled`)
+        }
+        return providerAddProvider(ctx)(...args)
+      },
+    },
+
     voucher: {
       claim: voucherClaimProvider(ctx),
       redeem: voucherRedeemProvider(ctx),
@@ -181,6 +198,18 @@ export function service(ctx) {
       fail() {
         throw new Error('test fail')
       },
+      /**
+       * @param {Ucanto.Invocation<Ucanto.Capability<'testing/space-storage', Ucanto.DID<'key'>, Ucanto.Failure>>} invocation
+       */
+      'space-storage': async (invocation) => {
+        const spaceId = invocation.capabilities[0].with
+        const hasStorageProvider =
+          await ctx.models.storageProvisions.hasStorageProvider(spaceId)
+        return {
+          hasStorageProvider,
+          foo: 'ben',
+        }
+      },
     },
   }
 }

packages/access-api/src/service/provider-add.js

@@ -0,0 +1,58 @@
+import * as Ucanto from '@ucanto/interface'
+import * as Server from '@ucanto/server'
+import { Provider } from '@web3-storage/capabilities'
+import * as validator from '@ucanto/validator'
+
+/**
+ * @typedef {import('@web3-storage/capabilities/types').ProviderAdd} ProviderAdd
+ * @typedef {import('@web3-storage/capabilities/types').ProviderAddSuccess} ProviderAddSuccess
+ * @typedef {import('@web3-storage/capabilities/types').ProviderAddFailure} ProviderAddFailure
+ */
+
+/**
+ * @callback ProviderAddHandler
+ * @param {Ucanto.Invocation<import('@web3-storage/capabilities/types').ProviderAdd>} invocation
+ * @returns {Promise<Ucanto.Result<ProviderAddSuccess, ProviderAddFailure>>}
+ */
+
+/**
+ * @param {object} options
+ * @param {import('../types/provisions').StorageProvisions} options.storageProvisions
+ * @returns {ProviderAddHandler}
+ */
+export function createProviderAddHandler(options) {
+  /** @type {ProviderAddHandler} */
+  return async (invocation) => {
+    const [providerAddCap] = invocation.capabilities
+    const {
+      nb: { consumer, provider },
+      with: accountDID,
+    } = providerAddCap
+    if (!validator.DID.match({ method: 'mailto' }).is(accountDID)) {
+      return {
+        error: true,
+        name: 'Unauthorized',
+        message: 'Issuer must be a mailto DID',
+      }
+    }
+    await options.storageProvisions.putMany({
+      space: consumer,
+      provider,
+      account: accountDID,
+    })
+    return {}
+  }
+}
+
+/**
+ * @param {object} ctx
+ * @param {Pick<import('../bindings').RouteContext['models'], 'storageProvisions'>} ctx.models
+ */
+export function providerAddProvider(ctx) {
+  return Server.provide(Provider.add, async ({ invocation }) => {
+    const handler = createProviderAddHandler({
+      storageProvisions: ctx.models.storageProvisions,
+    })
+    return handler(/** @type {Ucanto.Invocation<ProviderAdd>} */ (invocation))
+  })
+}

packages/access-api/src/types/provisions.ts

@@ -0,0 +1,30 @@
+import * as Ucanto from '@ucanto/interface'
+
+export type AlphaStorageProvider = 'did:web:web3.storage:providers:w3up-alpha'
+
+/**
+ * action which results in provisionment of a space consuming a storage provider
+ */
+export interface StorageProvisionCreation {
+  space: Ucanto.DID<'key'>
+  account: Ucanto.DID<'mailto'>
+  provider: AlphaStorageProvider
+}
+
+/**
+ * stores instances of a storage provider being consumed by a consumer
+ */
+export interface StorageProvisions {
+  hasStorageProvider: (consumer: Ucanto.DID<'key'>) => Promise<boolean>
+  /**
+   * write several items into storage
+   *
+   * @param items - provisions to store
+   */
+  putMany: (...items: StorageProvisionCreation[]) => Promise<void>
+
+  /**
+   * get number of stored items
+   */
+  count: () => Promise<bigint>
+}

packages/access-api/src/utils/context.js

@@ -11,6 +11,7 @@ import { createUploadApiConnection } from '../service/upload-api-proxy.js'
 import { DID } from '@ucanto/core'
 import { DbDelegationsStorage } from '../models/delegations.js'
 import { createD1Database } from './d1.js'
+import { DbStorageProvisions } from '../models/provisions.js'
 
 /**
  * Obtains a route context object.
@@ -68,6 +69,7 @@ export function getContext(request, env, ctx) {
       spaces: new Spaces(config.DB),
       validations: new Validations(config.VALIDATIONS),
       accounts: new Accounts(config.DB),
+      storageProvisions: new DbStorageProvisions(createD1Database(config.DB)),
     },
     email,
     uploadApi: createUploadApiConnection({

packages/access-api/src/utils/email.js

@@ -1,5 +1,11 @@
 export const debug = () => new DebugEmail()
 
+/**
+ * @typedef ValidationEmailSend
+ * @property {string} to
+ * @property {string} url
+ */
+
 /**
  * @param {{token:string, sender?:string}} opts
  */
@@ -23,7 +29,7 @@ export class Email {
   /**
    * Send validation email with ucan to register
    *
-   * @param {{ to: string; url: string }} opts
+   * @param {ValidationEmailSend} opts
    */
   async sendValidation(opts) {
     const rsp = await fetch('https://api.postmarkapp.com/email/withTemplate', {
@@ -90,7 +96,7 @@ export class DebugEmail {
   /**
    * Send validation email with ucan to register
    *
-   * @param {{ to: string; url: string }} opts
+   * @param {ValidationEmailSend} opts
    */
   async sendValidation(opts) {
     try {

packages/access-api/test/access-delegate.test.js

@@ -17,6 +17,7 @@ import * as delegationsResponse from '../src/utils/delegations-response.js'
 import {
   assertNotError,
   createTesterFromContext,
+  createTesterFromHandler,
   warnOnErrorResult,
 } from './helpers/ucanto-test-utils.js'
 
@@ -210,37 +211,6 @@ for (const variant of /** @type {const} */ ([
   })
 }
 
-/**
- * @template {Ucanto.Capability} Capability
- * @template Result
- * @typedef {object} InvokeTester
- * @property {(invocation: Ucanto.Invocation<Capability>) => Promise<Result>} invoke
- * @property {Resolvable<Ucanto.Signer<Ucanto.DID<'key'>>>} issuer
- * @property {Resolvable<Ucanto.Verifier<Ucanto.DID>>} audience
- */
-
-/**
- * Tests using simple function invocation -> result
- *
- * @template {Ucanto.Capability} Capability
- * @template Result
- * @param {() => (invocation: Ucanto.Invocation<Capability>) => Promise<Result>} createHandler
- * @returns {InvokeTester<Capability, Result>}
- */
-function createTesterFromHandler(createHandler) {
-  const issuer = principal.ed25519.generate()
-  const audience = principal.ed25519.generate()
-  /**
-   * @param {Ucanto.Invocation<Capability>} invocation
-   */
-  const invoke = async (invocation) => {
-    const handle = createHandler()
-    const result = await handle(invocation)
-    return result
-  }
-  return { issuer, audience, invoke }
-}
-
 /**
  * a value that can be passed to Promise.resolve() to get Promise<T>
  *