feat: access-api handles provider/add invocations

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

@@ -57,10 +57,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/storage-provisions.js

@@ -0,0 +1,18 @@
+/**
+ * @param {Array<import("../types/provisions").StorageProvisionCreation>} storage
+ * @returns {import("../types/provisions").StorageProvisions}
+ */
+export function createStorageProvisions(storage = []) {
+  /** @type {import("../types/provisions").StorageProvisions['hasStorageProvider']} */
+  const hasStorageProvider = (consumerId) => {
+    return Boolean(storage.some(({ space }) => space === consumerId))
+  }
+  /** @type {import("../types/provisions").StorageProvisions['create']} */
+  const create = async (storageProvision) => {
+    storage.push(storageProvision)
+  }
+  return {
+    create,
+    hasStorageProvider,
+  }
+}

packages/access-api/src/routes/validate-email.js

@@ -151,7 +151,7 @@ async function session(req, env) {
     }
     const account = accessSessionResult.audience
     const agentPubkey = accessSessionResult.capability.nb.key
-    const wrappedKeyCanAsignForAccount = await ucanto.delegate({
+    const wrappedKeyCanSignForAccount = await ucanto.delegate({
       issuer: env.signer,
       audience: { did: () => agentPubkey },
       capabilities: [
@@ -176,7 +176,7 @@ async function session(req, env) {
         }),
       ],
     })
-    await env.models.delegations.putMany(wrappedKeyCanAsignForAccount)
+    await env.models.delegations.putMany(wrappedKeyCanSignForAccount)
   }
 
   try {

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,15 @@ 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
+        return {
+          hasStorageProvider: await hasStorageProvider(spaceId),
+        }
+      },
     },
   }
 }

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.create({
+      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,17 @@
+import * as Ucanto from '@ucanto/interface'
+
+export type AlphaStorageProvider = 'did:web:web3.storage:providers:w3up-alpha'
+
+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'>) => boolean
+  create: (provision: StorageProvisionCreation) => Promise<void>
+}

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 { createStorageProvisions } from '../models/storage-provisions.js'
 
 /**
  * Obtains a route context object.
@@ -60,6 +61,7 @@ export function getContext(request, env, ctx) {
       spaces: new Spaces(config.DB),
       validations: new Validations(config.VALIDATIONS),
       accounts: new Accounts(config.DB),
+      storageProvisions: createStorageProvisions([]),
     },
     email: new Email({
       token: config.POSTMARK_TOKEN,

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>
  *

packages/access-api/test/helpers/ucanto-test-utils.js

@@ -1,11 +1,20 @@
 import * as Ucanto from '@ucanto/interface'
 import { Voucher } from '@web3-storage/capabilities'
 import * as assert from 'assert'
+import * as principal from '@ucanto/principal'
+
+/**
+ * @typedef HelperTestContext
+ * @property {Ucanto.Signer<Ucanto.DID<'key'>>} issuer
+ * @property {Ucanto.Signer<Ucanto.DID>} service
+ * @property {Ucanto.ConnectionView<Record<string, any>>} conn
+ * @property {import('miniflare').Miniflare} mf
+ */
 
 /**
  * Tests using context from "./helpers/context.js", which sets up a testable access-api inside miniflare.
  *
- * @param {() => Promise<{ issuer: Ucanto.Signer<Ucanto.DID<'key'>>, service: Ucanto.Signer<Ucanto.DID>, conn: Ucanto.ConnectionView<Record<string, any>> }>} createContext
+ * @param {() => Promise<HelperTestContext>} createContext
  * @param {object} [options]
  * @param {Iterable<Promise<Ucanto.Principal>>} options.registerSpaces - spaces to register in access-api. Some access-api functionality on a space requires it to be registered.
  */
@@ -16,6 +25,7 @@ export function createTesterFromContext(createContext, options) {
   })
   const issuer = context.then(({ issuer }) => issuer)
   const audience = context.then(({ service }) => service)
+  const miniflare = context.then(({ mf }) => mf)
   /**
    * @template {Ucanto.Capability} Capability
    * @param {Ucanto.Invocation<Capability>} invocation
@@ -25,7 +35,7 @@ export function createTesterFromContext(createContext, options) {
     const [result] = await conn.execute(invocation)
     return result
   }
-  return { issuer, audience, invoke }
+  return { issuer, audience, invoke, miniflare }
 }
 
 /**
@@ -114,3 +124,34 @@ export function warnOnErrorResult(
     warn(message, result)
   }
 }
+
+/**
+ * @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.Signer<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>}
+ */
+export 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 }
+}