feat!: add did mailto package, replacing createDidMailtoFromEmail (#…

…722)

Motivation:
* #682 

Breaking Changes
* remove `createDidMailtoFromEmail` export from
`@web3-storage/access/agent`
93e29c6#diff-69a4efe733b2d7920dc103a0370eb1a285403e39c41e1b5e9a0718ea66b5a32fL33
* no dependencies under our org:
https://github.com/search?q=org%3Aweb3-storage%20createDidMailtoFromEmail&type=code
* Motivation: encouragement [from
@Gozala](#722 (comment))
and
[@travis](#722 (comment))
in review

.github/release-please-config.json

@@ -5,6 +5,7 @@
     "packages/access-client": {},
     "packages/access-api": {},
     "packages/capabilities": {},
+    "packages/did-mailto": {},
     "packages/upload-api": {},
     "packages/upload-client": {},
     "packages/w3up-client": {}

.github/workflows/did-mailto.yml

@@ -0,0 +1,37 @@
+name: did-mailto
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'packages/did-mailto/**'
+      - '.github/workflows/did-mailto.yml'
+      - 'pnpm-lock.yaml'
+  pull_request:
+    paths:
+      - 'packages/did-mailto/**'
+      - '.github/workflows/did-mailto.yml'
+      - 'pnpm-lock.yaml'
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./packages/did-mailto
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Install
+        uses: pnpm/action-setup@v2.2.3
+        with:
+          version: 7
+      - name: Setup
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          registry-url: https://registry.npmjs.org/
+          cache: 'pnpm'
+      - run: pnpm --filter '@web3-storage/did-mailto...' install
+      - run: pnpm --filter '@web3-storage/did-mailto' lint
+      - run: pnpm --filter '@web3-storage/did-mailto' test

.github/workflows/release.yml

@@ -34,6 +34,7 @@ jobs:
     if: |
       contains(fromJson(needs.release.outputs.paths_released), 'packages/access-client') ||
       contains(fromJson(needs.release.outputs.paths_released), 'packages/capabilities') ||
+      contains(fromJson(needs.release.outputs.paths_released), 'packages/did-mailto') ||
       contains(fromJson(needs.release.outputs.paths_released), 'packages/upload-client') ||
       contains(fromJson(needs.release.outputs.paths_released), 'packages/upload-api') ||
       contains(fromJson(needs.release.outputs.paths_released), 'packages/w3up-client')

packages/access-api/package.json

@@ -27,6 +27,7 @@
     "@ucanto/validator": "^6.1.0",
     "@web3-storage/access": "workspace:^",
     "@web3-storage/capabilities": "workspace:^",
+    "@web3-storage/did-mailto": "workspace:^",
     "@web3-storage/worker-utils": "0.4.3-dev",
     "dotenv": "^16.0.3",
     "kysely": "^0.23.4",

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

@@ -4,7 +4,7 @@ import {
 } from '@web3-storage/access/encoding'
 import * as Access from '@web3-storage/capabilities/access'
 import QRCode from 'qrcode'
-import { toEmail } from '../utils/did-mailto.js'
+import * as DidMailto from '@web3-storage/did-mailto'
 import {
   HtmlResponse,
   ValidateEmail,
@@ -173,7 +173,7 @@ async function authorize(req, env) {
     return new HtmlResponse(
       (
         <ValidateEmail
-          email={toEmail(account.did())}
+          email={DidMailto.toEmail(DidMailto.fromString(account.did()))}
           audience={agent.did()}
           ucan={delegationsToString(confirmDelegations)}
         />

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

@@ -1,6 +1,6 @@
 import * as Server from '@ucanto/server'
 import * as Access from '@web3-storage/capabilities/access'
-import * as Mailto from '../utils/did-mailto.js'
+import * as DidMailto from '@web3-storage/did-mailto'
 import { delegationToString } from '@web3-storage/access/encoding'
 
 /**
@@ -52,7 +52,7 @@ export function accessAuthorizeProvider(ctx) {
     const url = `${ctx.url.protocol}//${ctx.url.host}/validate-email?ucan=${encoded}&mode=authorize`
 
     await ctx.email.sendValidation({
-      to: Mailto.toEmail(capability.nb.iss),
+      to: DidMailto.toEmail(DidMailto.fromString(capability.nb.iss)),
       url,
     })
 

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

@@ -10,7 +10,7 @@ import { Accounts } from '../src/models/accounts.js'
 import { context } from './helpers/context.js'
 // @ts-ignore
 import isSubset from 'is-subset'
-import { toEmail } from '../src/utils/did-mailto.js'
+import * as DidMailto from '@web3-storage/did-mailto'
 import {
   warnOnErrorResult,
   registerSpaces,
@@ -126,7 +126,7 @@ describe('access/authorize', function () {
 
     const html = await rsp.text()
     assert(html.includes('Email Validated'))
-    assert(html.includes(toEmail(accountDID)))
+    assert(html.includes(DidMailto.toEmail(accountDID)))
     assert(html.includes(issuer.did()))
   })
 

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

@@ -16,7 +16,9 @@ for (const handlerVariant of /** @type {const} */ ([
         spaceWithStorageProvider,
         ...createTesterFromContext(() => context(), {
           registerSpaces: [spaceWithStorageProvider],
-          account: { did: () => /** @type {const} */ ('did:mailto:foo') },
+          account: {
+            did: () => /** @type {const} */ ('did:mailto:example.com:foo'),
+          },
         }),
       }
     })(),

packages/access-api/test/access-client-agent.test.js

@@ -4,14 +4,14 @@ import {
   assertNotError,
   createTesterFromContext,
 } from './helpers/ucanto-test-utils.js'
+import * as DidMailto from '@web3-storage/did-mailto'
 import * as principal from '@ucanto/principal'
 import {
   addProvider,
   addSpacesFromDelegations,
   Agent as AccessAgent,
   authorizeAndWait,
   claimAccess,
-  createDidMailtoFromEmail,
   delegationsIncludeSessionProof,
   pollAccessClaimUntil,
   requestAccess,
@@ -80,7 +80,7 @@ for (const accessApiVariant of /** @type {const} */ ([
       const abort = new AbortController()
       after(() => abort.abort())
       const account = {
-        did: () => createDidMailtoFromEmail('example@dag.house'),
+        did: () => DidMailto.fromEmail(DidMailto.email('example@dag.house')),
       }
       await requestAccess(accessAgent, account, [{ can: '*' }])
       assert.deepEqual(emails.length, emailCount + 1)
@@ -184,8 +184,8 @@ for (const accessApiVariant of /** @type {const} */ ([
 
     it('can registerSpace', async () => {
       const { connection, emails } = await accessApiVariant.create()
-      const accountEmail = 'foo@dag.house'
-      const account = { did: () => createDidMailtoFromEmail(accountEmail) }
+      const accountEmail = DidMailto.email('foo@dag.house')
+      const account = { did: () => DidMailto.fromEmail(accountEmail) }
       const accessAgent = await AccessAgent.create(undefined, {
         connection,
       })
@@ -615,7 +615,7 @@ async function testSessionAuthorization(service, access, account, emails) {
  * @returns {Ucanto.DID<'mailto'>}
  */
 function thisEmailDidMailto() {
-  return createDidMailtoFromEmail(this.email)
+  return DidMailto.fromEmail(DidMailto.email(this.email))
 }
 
 /**

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

@@ -26,7 +26,9 @@ for (const handlerVariant of /** @type {const} */ ([
     name: 'handled by access-api in miniflare',
     ...(() => {
       const spaceWithStorageProvider = principal.ed25519.generate()
-      const account = { did: () => /** @type {const} */ ('did:mailto:foo') }
+      const account = {
+        did: () => /** @type {const} */ ('did:mailto:example.com:foo'),
+      }
       return {
         spaceWithStorageProvider,
         ...createTesterFromContext(() => context(), {
@@ -125,7 +127,9 @@ for (const variant of /** @type {const} */ ([
     name: 'handled by access-api in miniflare',
     ...(() => {
       const spaceWithStorageProvider = principal.ed25519.generate()
-      const account = { did: () => /** @type {const} */ ('did:mailto:foo') }
+      const account = {
+        did: () => /** @type {const} */ ('did:mailto:example.com:foo'),
+      }
       return {
         spaceWithStorageProvider,
         ...createTesterFromContext(() => context(), {

packages/access-api/test/provider-add.test.js

@@ -270,7 +270,7 @@ const setup = async (options = {}) => {
   const context = await createContextWithMailbox(options)
   const space = await principal.ed25519.generate()
   const agent = await principal.ed25519.generate()
-  const account = principal.Absentee.from({ id: 'did:mailto:foo' })
+  const account = principal.Absentee.from({ id: 'did:mailto:example.com:foo' })
 
   return { ...context, space, agent, account }
 }

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

@@ -65,7 +65,7 @@ describe('DbProvisions', () => {
     const modifiedFirstProvision = {
       ...firstProvision,
       space: /** @type {const} */ ('did:key:foo'),
-      account: /** @type {const} */ ('did:mailto:foo'),
+      account: /** @type {const} */ ('did:mailto:example.com:foo'),
       // note this type assertion is wrong, but useful to set up the test
       provider: /** @type {import('@ucanto/interface').DID<'web'>} */ (
         'did:provider:foo'

packages/access-api/tsconfig.json

@@ -8,5 +8,9 @@
   },
   "include": ["src", "scripts", "test", "package.json", "sql"],
   "exclude": ["**/node_modules/**"],
-  "references": [{ "path": "../access-client" }, { "path": "../capabilities" }]
+  "references": [
+    { "path": "../access-client" },
+    { "path": "../capabilities" },
+    { "path": "../did-mailto" }
+  ]
 }

packages/access-client/package.json

@@ -67,6 +67,7 @@
     "@ucanto/transport": "^5.1.1",
     "@ucanto/validator": "^6.1.0",
     "@web3-storage/capabilities": "workspace:^",
+    "@web3-storage/did-mailto": "workspace:^",
     "bigint-mod-arith": "^3.1.2",
     "conf": "10.2.0",
     "inquirer": "^9.1.4",

packages/access-client/src/agent-use-cases.js

@@ -1,8 +1,4 @@
-import {
-  addSpacesFromDelegations,
-  Agent as AccessAgent,
-  createDidMailtoFromEmail,
-} from './agent.js'
+import { addSpacesFromDelegations, Agent as AccessAgent } from './agent.js'
 import * as Ucanto from '@ucanto/interface'
 import * as Access from '@web3-storage/capabilities/access'
 import { bytesToDelegations, stringToDelegation } from './encoding.js'
@@ -12,6 +8,7 @@ import { Websocket, AbortError } from './utils/ws.js'
 import { AgentData, isSessionProof } from './agent-data.js'
 import * as ucanto from '@ucanto/core'
 import { DID as DIDValidator } from '@ucanto/validator'
+import * as DidMailto from '@web3-storage/did-mailto'
 
 /**
  * Request access by a session allowing this agent to issue UCANs
@@ -242,7 +239,7 @@ export async function waitForAuthorizationByPolling(access, opts = {}) {
 export async function authorizeAndWait(access, email, opts = {}) {
   const expectAuthorization =
     opts.expectAuthorization || waitForAuthorizationByPolling
-  const account = { did: () => createDidMailtoFromEmail(email) }
+  const account = { did: () => DidMailto.fromEmail(email) }
   await requestAccess(
     access,
     account,
@@ -337,7 +334,7 @@ export async function addProviderAndDelegateToAccount(
   if (spaceMeta && spaceMeta.isRegistered) {
     throw new Error('Space already registered with web3.storage.')
   }
-  const account = { did: () => createDidMailtoFromEmail(email) }
+  const account = { did: () => DidMailto.fromEmail(DidMailto.email(email)) }
   await addProvider({ access, space, account, provider })
   const delegateSpaceAccessResult = await delegateSpaceAccessToAccount(
     access,

packages/access-client/src/agent.js

@@ -24,13 +24,12 @@ import {
   canDelegateCapability,
 } from './delegations.js'
 import { AgentData, getSessionProofs } from './agent-data.js'
-import { createDidMailtoFromEmail } from './utils/did-mailto.js'
 import {
   addProviderAndDelegateToAccount,
   waitForDelegationOnSocket,
 } from './agent-use-cases.js'
 
-export { AgentData, createDidMailtoFromEmail }
+export { AgentData }
 export * from './agent-use-cases.js'
 
 const HOST = 'https://access.web3.storage'

packages/access-client/test/agent.test.js

@@ -1,6 +1,6 @@
 import assert from 'assert'
 import { URI } from '@ucanto/validator'
-import { Agent, connection, createDidMailtoFromEmail } from '../src/agent.js'
+import { Agent, connection } from '../src/agent.js'
 import * as Space from '@web3-storage/capabilities/space'
 import { createServer } from './helpers/utils.js'
 import * as fixtures from './helpers/fixtures.js'
@@ -253,11 +253,4 @@ describe('Agent', function () {
       /cannot delegate capability store\/remove/
     )
   })
-
-  it('exports createDidMailtoFromEmail', async () => {
-    assert.deepEqual(
-      createDidMailtoFromEmail('foo@dag.house'),
-      'did:mailto:dag.house:foo'
-    )
-  })
 })

packages/access-client/tsconfig.json

@@ -7,5 +7,5 @@
   },
   "include": ["src", "scripts", "test", "package.json"],
   "exclude": ["**/node_modules/**"],
-  "references": [{ "path": "../capabilities" }]
+  "references": [{ "path": "../capabilities" }, { "path": "../did-mailto" }]
 }