Check whether a person has a verified email with GET /status/:webId

Author: mrkvon

.env.sample

@@ -14,6 +14,7 @@ MAILER_IDENTITY_EMAIL=bot@example
 MAILER_IDENTITY_PASSWORD=password
 MAILER_IDENTITY_PROVIDER=http://localhost:3456
 MAILER_IDENTITY_WEBID=http://localhost:3456/bot/profile/card#me
+MAILER_IDENTITY_CSS_VERSION=7 # supported versions are 6 and 7
 
 # link to group of users who are allowed to use the service
 ALLOWED_GROUPS=
@@ -50,3 +51,6 @@ DB_PORT=
 JWT_KEY=./ecdsa-p256-private.pem
 # jwt algorithm
 JWT_ALG=ES256
+
+# type index class by which we find settings with email
+EMAIL_DISCOVERY_TYPE=http://w3id.org/hospex/ns#PersonalHospexDocument

README.md

@@ -1,16 +1,26 @@
 # Simple Solid email notifications
 
-This service sends email from one person within a Solid group to another. It doesn't use native Solid notifications, because there are pods that don't support it.
+This service sends email from one person within a Solid group to another. It doesn't use native Solid notifications, because there are pods that don't support them.
 
 ## How it works
 
-- It's a bot agent with its own identity, which must be provided by arbitrary CommunitySolidServer pod
+- It's a bot agent with its own identity, which must be provided by arbitrary [CommunitySolidServer](https://github.com/CommunitySolidServer/CommunitySolidServer) pod
 - It runs on a server
 - You can check whether another person in the group has set up email notifications.
 - If the other person has set up the notifications, you can send them an email through this service.
 - At the beginning, you need to verify your email, save it into your hospitality exchange settings, and give the mailer a permission to read the email; so the email notifier can access the settings when it sends you an email.
 - When you want to notify other person, the service will check whether both of you belong to the specified group(s). If you both belong, and the other person has email notifications set up, it will send the other person an email.
 
+### Verified email address discovery
+
+Email address and verification token should be stored in (webId) - space:preferencesFile -> (email settings file) to which the mailer identity has read (and maybe write) access. It can be in the main webId file, or it can be in some document discovered via publicTypeIndex. In case of hospitality exchange, it can be in hospex:PersonalHospexDocument.
+
+1. Go to person's webId
+1. Find public type index `(webId) - solid:publicTypeIndex -> (publicTypeIndex)``
+1. Find instances of hospex:PersonalHospexDocument
+1. Find settings in the relevant instance (webId) - space:preferencesFile -> (settings)
+1. In the settings, find (webId) - foaf:mbox -> (email) and (webId) - example:emailVerificationToken -> (JWT)
+
 ## Usage
 
 ### Configure

package.json

@@ -53,6 +53,7 @@
     "@koa/bodyparser": "^5.0.0",
     "@koa/cors": "^4.0.0",
     "@koa/router": "^12.0.0",
+    "@ldhop/core": "^0.0.0-alpha.0",
     "@solid/access-token-verifier": "^2.0.5",
     "ajv": "^8.12.0",
     "ajv-formats": "^2.1.1",

src/app.ts

@@ -12,7 +12,10 @@ import {
 } from './controllers/integration'
 import { getStatus } from './controllers/status'
 import { webhookReceiver } from './controllers/webhookReceiver'
-import { authorizeGroups } from './middlewares/authorizeGroup'
+import {
+  authorizeGroups,
+  checkParamGroupMembership,
+} from './middlewares/authorizeGroup'
 import { solidAuth } from './middlewares/solidAuth'
 import { validateBody } from './middlewares/validate'
 
@@ -90,7 +93,13 @@ router
   )
   .get('/verify-email', checkVerificationLink, finishIntegration)
   .post('/webhook-receiver', webhookReceiver)
-  .get('/status', solidAuth, getStatus)
+  .get(
+    '/status/:webId',
+    solidAuth,
+    authorizeGroups(allowedGroups),
+    checkParamGroupMembership(allowedGroups, 'webId' as const),
+    getStatus,
+  )
 
 app
   .use(helmet())

src/config/index.ts

@@ -16,6 +16,8 @@ export const mailerCredentials = {
   webId:
     process.env.MAILER_IDENTITY_WEBID ??
     'http://localhost:3456/bot/profile/card#me',
+  // version of CommunitySolidServer that provides identity for mailer
+  cssVersion: <6 | 7>+(process.env.MAILER_IDENTITY_CSS_VERSION ?? 7), // 6 or 7
 }
 
 const stringToBoolean = (value: string | undefined): boolean => {
@@ -71,3 +73,7 @@ export const jwt = {
   key: process.env.JWT_KEY ?? './ecdsa-p256-private.pem',
   alg: process.env.JWT_ALG ?? 'ES256',
 }
+
+export const emailDiscoveryType =
+  process.env.EMAIL_DISCOVERY_TYPE ??
+  'http://w3id.org/hospex/ns#PersonalHospexDocument'

src/controllers/status.ts

@@ -1,27 +1,159 @@
-import { Middleware } from 'koa'
-import { EmailVerification, Integration } from '../config/sequelize'
-
-export const getStatus: Middleware = async ctx => {
-  const webId = ctx.state.user
-
-  const verified = await Integration.findAll({ where: { webId } })
-
-  const unverified = await EmailVerification.findAll({ where: { webId } })
-
-  ctx.response.body = {
-    actor: webId,
-    integrations: [
-      ...verified.map(s => ({
-        object: s.inbox,
-        target: s.email,
-        verified: true,
-      })),
-      ...unverified.map(s => ({
-        object: s.inbox,
-        target: s.email,
-        verified: false,
-      })),
-    ],
-  }
+import { RdfQuery } from '@ldhop/core/dist/src'
+import { QueryAndStore } from '@ldhop/core/dist/src/QueryAndStore'
+import { fetchRdfDocument } from '@ldhop/core/dist/src/utils/helpers'
+import { getAuthenticatedFetch as getAuthenticatedFetch6x } from 'css-authn/dist/6.x'
+import { getAuthenticatedFetch as getAuthenticatedFetch7x } from 'css-authn/dist/7.x'
+import { readFile } from 'fs-extra'
+import { verify } from 'jsonwebtoken'
+import type { DefaultContext, DefaultState, Middleware } from 'koa'
+import { NamedNode, Quad } from 'n3'
+import { dct, rdfs, solid, space } from 'rdf-namespaces'
+import * as config from '../config'
+
+export const getVerifiedEmails = async (webId: string) => {
+  const tokens = await findEmailVerificationTokens(webId)
+
+  const pem = await readFile(config.jwt.key, { encoding: 'utf-8' })
+
+  const verifiedEmails = tokens
+    .map(token => {
+      try {
+        return verify(token, pem) as {
+          webId: string
+          email: string
+          emailVerified: boolean
+          iss: string
+          iat: number
+        }
+      } catch {
+        return null
+      }
+    })
+    .filter(a => a?.emailVerified && a.webId === webId)
+    .map(a => a!.email)
+
+  return verifiedEmails
+}
+
+export const getStatus: Middleware<
+  DefaultState,
+  DefaultContext & { params: { webId: string } }
+> = async ctx => {
+  const webId = ctx.params.webId
+
+  const verifiedEmails = await getVerifiedEmails(webId)
+
+  ctx.response.body = { emailVerified: verifiedEmails.length > 0 }
   ctx.response.status = 200
 }
+
+/**
+ * To find verified email of a person
+ *
+ * - Go to person's webId
+ * - Find public type index `(webId) - solid:publicTypeIndex -> (publicTypeIndex)``
+ * - Find instances of specific class defined in config (EMAIL_DISCOVERY_TYPE defaults to hospex:PersonalHospexDocument)
+ * - Find settings in the relevant instance (webId) - space:preferencesFile -> (settings)
+ * - In the settings, find (webId) - example:emailVerificationToken -> (JWT)
+ */
+const findEmailQuery: RdfQuery = [
+  // Go to person's webId and fetch extended profile documents, too
+  {
+    type: 'match',
+    subject: '?person',
+    predicate: rdfs.seeAlso,
+    pick: 'object',
+    target: '?extendedDocument',
+  },
+  { type: 'add resources', variable: '?extendedDocument' },
+  // Find public type index
+  {
+    type: 'match',
+    subject: '?person',
+    predicate: solid.publicTypeIndex,
+    pick: 'object',
+    target: '?publicTypeIndex',
+  },
+  // Find instances of specific class defined in config (EMAIL_DISCOVERY_TYPE)
+  {
+    type: 'match',
+    subject: '?publicTypeIndex',
+    predicate: dct.references,
+    pick: 'object',
+    target: '?typeRegistration',
+  },
+  {
+    type: 'match',
+    subject: '?typeRegistration',
+    predicate: solid.forClass,
+    object: config.emailDiscoveryType,
+    pick: 'subject',
+    target: '?typeRegistrationForClass',
+  },
+  {
+    type: 'match',
+    subject: '?typeRegistrationForClass',
+    predicate: solid.instance,
+    pick: 'object',
+    target: `?classDocument`,
+  },
+  { type: 'add resources', variable: '?classDocument' },
+  // Find settings
+  {
+    type: 'match',
+    subject: '?person',
+    predicate: space.preferencesFile,
+    pick: 'object',
+    target: '?settings',
+  },
+  { type: 'add resources', variable: '?settings' },
+]
+
+const findEmailVerificationTokens = async (webId: string) => {
+  // initialize knowledge graph and follow your nose through it
+  // according to the query
+  const qas = new QueryAndStore(findEmailQuery, { person: new Set([webId]) })
+  await run(qas)
+
+  // Find email verification tokens
+  const objects = qas.store.getObjects(
+    new NamedNode(webId),
+    new NamedNode('https://example.com/emailVerificationToken'),
+    null,
+  )
+
+  return objects.map(o => o.value)
+}
+
+const fetchRdf = async (uri: string) => {
+  const getAuthenticatedFetch =
+    config.mailerCredentials.cssVersion === 6
+      ? getAuthenticatedFetch6x
+      : getAuthenticatedFetch7x
+  const authBotFetch = await getAuthenticatedFetch(config.mailerCredentials)
+
+  const { data: quads } = await fetchRdfDocument(uri, authBotFetch)
+
+  return quads
+}
+
+/**
+ * Follow your nose through the linked data graph by query
+ */
+const run = async (qas: QueryAndStore) => {
+  let missingResources = qas.getMissingResources()
+
+  while (missingResources.length > 0) {
+    let quads: Quad[] = []
+    const res = missingResources[0]
+    try {
+      quads = await fetchRdf(missingResources[0])
+    } catch (e) {
+      // eslint-disable-next-line no-console
+      console.error(e)
+    } finally {
+      qas.addResource(res, quads)
+      missingResources = qas.getMissingResources()
+    }
+  }
+}

src/helpers.ts

@@ -1,23 +1,16 @@
-import { Middleware } from 'koa'
+import { DefaultContext, DefaultState, Middleware } from 'koa'
 import { Parser } from 'n3'
 import { vcard } from 'rdf-namespaces'
 
 export const authorizeGroups =
-  (groups: string[]): Middleware =>
+  (groups: string[]): Middleware<{ user: string }> =>
   async (ctx, next) => {
     // if array of groups are empty, we allow everybody (default)
     if (groups.length === 0) return await next()
 
-    const user = <string>ctx.state.user
+    const user = ctx.state.user
 
-    const memberships = await Promise.allSettled(
-      groups.map(group => isGroupMember(user, group)),
-    )
-
-    const isAllowed = memberships.some(
-      membership =>
-        membership.status === 'fulfilled' && membership.value === true,
-    )
+    const isAllowed = await isSomeGroupMember(user, groups)
 
     if (!isAllowed) {
       return ctx.throw(
@@ -29,6 +22,46 @@ export const authorizeGroups =
     await next()
   }
 
+const isSomeGroupMember = async (user: string, groups: string[]) => {
+  const memberships = await Promise.allSettled(
+    groups.map(group => isGroupMember(user, group)),
+  )
+
+  const isMember = memberships.some(
+    membership =>
+      membership.status === 'fulfilled' && membership.value === true,
+  )
+  return isMember
+}
+
+/**
+ * Check whether a user specified in param is member of any of the given groups
+ */
+export const checkParamGroupMembership =
+  <T extends string>(
+    groups: string[],
+    param: T,
+  ): Middleware<
+    DefaultState,
+    DefaultContext & { params: { [K in T]: string } }
+  > =>
+  async (ctx, next) => {
+    // if array of groups are empty, we allow everybody (default)
+    if (groups.length === 0) return await next()
+    const webId = ctx.params[param]
+    const isAllowed = await isSomeGroupMember(webId, groups)
+
+    if (!isAllowed) {
+      return ctx.throw(400, {
+        error: 'Person is not a member of any allowed group',
+        person: webId,
+        groups,
+      })
+    }
+
+    await next()
+  }
+
 const isGroupMember = async (user: string, group: string) => {
   const groupDocumentResponse = await fetch(group)
   if (!groupDocumentResponse.ok) return false

src/middlewares/authorizeGroup.ts

@@ -5,7 +5,10 @@ import type {
 import * as verifier from '@solid/access-token-verifier'
 import type { Middleware } from 'koa'
 
-export const solidAuth: Middleware = async (ctx, next) => {
+export const solidAuth: Middleware<{
+  user: string
+  client: string | undefined
+}> = async (ctx, next) => {
   const authorizationHeader = ctx.request.headers.authorization
   const dpopHeader = ctx.request.headers.dpop
   const solidOidcAccessTokenVerifier: SolidTokenVerifierFunction =