@comapeo/core 1.0.0

package/src/roles.js

@@ -0,0 +1,412 @@
+import { currentSchemaVersions } from '@comapeo/schema'
+import mapObject from 'map-obj'
+import { kCreateWithDocId, kDataStore } from './datatype/index.js'
+import { assert, setHas } from './utils.js'
+import { TypedEmitter } from 'tiny-typed-emitter'
+/** @import { Namespace } from './types.js' */
+
+// Randomly generated 8-byte encoded as hex
+export const CREATOR_ROLE_ID = 'a12a6702b93bd7ff'
+export const COORDINATOR_ROLE_ID = 'f7c150f5a3a9a855'
+export const MEMBER_ROLE_ID = '012fd2d431c0bf60'
+export const BLOCKED_ROLE_ID = '9e6d29263cba36c9'
+export const LEFT_ROLE_ID = '8ced989b1904606b'
+export const NO_ROLE_ID = '08e4251e36f6e7ed'
+
+/**
+ * @typedef {T extends Iterable<infer U> ? U : never} ElementOf
+ * @template T
+ */
+
+/** @typedef {ElementOf<typeof ROLE_IDS>} RoleId */
+const ROLE_IDS = new Set(
+  /** @type {const} */ ([
+    CREATOR_ROLE_ID,
+    COORDINATOR_ROLE_ID,
+    MEMBER_ROLE_ID,
+    BLOCKED_ROLE_ID,
+    LEFT_ROLE_ID,
+    NO_ROLE_ID,
+  ])
+)
+const isRoleId = setHas(ROLE_IDS)
+
+/** @typedef {ElementOf<typeof ROLE_IDS_FOR_NEW_INVITE>} RoleIdForNewInvite */
+const ROLE_IDS_FOR_NEW_INVITE = new Set(
+  /** @type {const} */ ([COORDINATOR_ROLE_ID, MEMBER_ROLE_ID, BLOCKED_ROLE_ID])
+)
+export const isRoleIdForNewInvite = setHas(ROLE_IDS_FOR_NEW_INVITE)
+
+/** @typedef {ElementOf<typeof ROLE_IDS_ASSIGNABLE_TO_OTHERS>} RoleIdAssignableToOthers */
+const ROLE_IDS_ASSIGNABLE_TO_OTHERS = new Set(
+  /** @type {const} */ ([COORDINATOR_ROLE_ID, MEMBER_ROLE_ID, BLOCKED_ROLE_ID])
+)
+export const isRoleIdAssignableToOthers = setHas(ROLE_IDS_ASSIGNABLE_TO_OTHERS)
+
+/** @typedef {ElementOf<typeof ROLE_IDS_ASSIGNABLE_TO_ANYONE>} RoleIdAssignableToAnyone */
+const ROLE_IDS_ASSIGNABLE_TO_ANYONE = new Set(
+  /** @type {const} */ ([
+    COORDINATOR_ROLE_ID,
+    MEMBER_ROLE_ID,
+    BLOCKED_ROLE_ID,
+    LEFT_ROLE_ID,
+  ])
+)
+const isRoleIdAssignableToAnyone = setHas(ROLE_IDS_ASSIGNABLE_TO_ANYONE)
+
+/**
+ * @typedef {object} DocCapability
+ * @property {boolean} readOwn - can read own data
+ * @property {boolean} writeOwn - can write own data
+ * @property {boolean} readOthers - can read other's data
+ * @property {boolean} writeOthers - can edit or delete other's data
+ */
+
+/**
+ * @template {RoleId} [T=RoleId]
+ * @typedef {object} Role
+ * @property {T} roleId
+ * @property {string} name
+ * @property {Record<import('@comapeo/schema').MapeoDoc['schemaName'], DocCapability>} docs
+ * @property {RoleIdAssignableToOthers[]} roleAssignment
+ * @property {Record<Namespace, 'allowed' | 'blocked'>} sync
+ */
+
+/**
+ * This is currently the same as 'Coordinator' role, but defined separately
+ * because the creator should always have ALL powers, but we could edit the
+ * 'Coordinator' powers in the future.
+ *
+ * @type {Role<typeof CREATOR_ROLE_ID>}
+ */
+export const CREATOR_ROLE = {
+  roleId: CREATOR_ROLE_ID,
+  name: 'Project Creator',
+  docs: mapObject(currentSchemaVersions, (key) => {
+    return [
+      key,
+      { readOwn: true, writeOwn: true, readOthers: true, writeOthers: true },
+    ]
+  }),
+  roleAssignment: [COORDINATOR_ROLE_ID, MEMBER_ROLE_ID, BLOCKED_ROLE_ID],
+  sync: {
+    auth: 'allowed',
+    config: 'allowed',
+    data: 'allowed',
+    blobIndex: 'allowed',
+    blob: 'allowed',
+  },
+}
+
+/**
+ * This is the role assumed for a device when no role record can be found. This
+ * can happen when an invited device did not manage to sync with the device that
+ * invited them, and they then try to sync with someone else. We want them to be
+ * able to sync the auth and config store, because that way they may be able to
+ * receive their role record, and they can get the project config so that they
+ * can start collecting data.
+ *
+ * @type {Role<typeof NO_ROLE_ID>}
+ */
+export const NO_ROLE = {
+  roleId: NO_ROLE_ID,
+  name: 'No Role',
+  docs: mapObject(currentSchemaVersions, (key) => {
+    return [
+      key,
+      { readOwn: true, writeOwn: true, readOthers: false, writeOthers: false },
+    ]
+  }),
+  roleAssignment: [],
+  sync: {
+    auth: 'allowed',
+    config: 'allowed',
+    data: 'blocked',
+    blobIndex: 'blocked',
+    blob: 'blocked',
+  },
+}
+
+/** @type {{ [K in RoleId]: Role<K> }} */
+export const ROLES = {
+  [CREATOR_ROLE_ID]: CREATOR_ROLE,
+  [MEMBER_ROLE_ID]: {
+    roleId: MEMBER_ROLE_ID,
+    name: 'Member',
+    docs: mapObject(currentSchemaVersions, (key) => {
+      return [
+        key,
+        { readOwn: true, writeOwn: true, readOthers: true, writeOthers: false },
+      ]
+    }),
+    roleAssignment: [],
+    sync: {
+      auth: 'allowed',
+      config: 'allowed',
+      data: 'allowed',
+      blobIndex: 'allowed',
+      blob: 'allowed',
+    },
+  },
+  [COORDINATOR_ROLE_ID]: {
+    roleId: COORDINATOR_ROLE_ID,
+    name: 'Coordinator',
+    docs: mapObject(currentSchemaVersions, (key) => {
+      return [
+        key,
+        { readOwn: true, writeOwn: true, readOthers: true, writeOthers: true },
+      ]
+    }),
+    roleAssignment: [COORDINATOR_ROLE_ID, MEMBER_ROLE_ID, BLOCKED_ROLE_ID],
+    sync: {
+      auth: 'allowed',
+      config: 'allowed',
+      data: 'allowed',
+      blobIndex: 'allowed',
+      blob: 'allowed',
+    },
+  },
+  [BLOCKED_ROLE_ID]: {
+    roleId: BLOCKED_ROLE_ID,
+    name: 'Blocked',
+    docs: mapObject(currentSchemaVersions, (key) => {
+      return [
+        key,
+        {
+          readOwn: false,
+          writeOwn: false,
+          readOthers: false,
+          writeOthers: false,
+        },
+      ]
+    }),
+    roleAssignment: [],
+    sync: {
+      auth: 'blocked',
+      config: 'blocked',
+      data: 'blocked',
+      blobIndex: 'blocked',
+      blob: 'blocked',
+    },
+  },
+  [LEFT_ROLE_ID]: {
+    roleId: LEFT_ROLE_ID,
+    name: 'Left',
+    docs: mapObject(currentSchemaVersions, (key) => {
+      return [
+        key,
+        {
+          readOwn: false,
+          writeOwn: false,
+          readOthers: false,
+          writeOthers: false,
+        },
+      ]
+    }),
+    roleAssignment: [],
+    sync: {
+      auth: 'allowed',
+      config: 'blocked',
+      data: 'blocked',
+      blobIndex: 'blocked',
+      blob: 'blocked',
+    },
+  },
+  [NO_ROLE_ID]: NO_ROLE,
+}
+
+/**
+ * @typedef {object} RolesEvents
+ * @property {(docIds: Set<string>) => void} update Emitted when new role records are indexed
+ */
+
+/**
+ * @extends {TypedEmitter<RolesEvents>}
+ */
+export class Roles extends TypedEmitter {
+  #dataType
+  #coreOwnership
+  #coreManager
+  #projectCreatorAuthCoreId
+  #ownDeviceId
+
+  static NO_ROLE = NO_ROLE
+
+  /**
+   *
+   * @param {object} opts
+   * @param {import('./datatype/index.js').DataType<
+   *   import('./datastore/index.js').DataStore<'auth'>,
+   *   typeof import('./schema/project.js').roleTable,
+   *   'role',
+   *   import('@comapeo/schema').Role,
+   *   import('@comapeo/schema').RoleValue
+   * >} opts.dataType
+   * @param {import('./core-ownership.js').CoreOwnership} opts.coreOwnership
+   * @param {import('./core-manager/index.js').CoreManager} opts.coreManager
+   * @param {Buffer} opts.projectKey
+   * @param {Buffer} opts.deviceKey public key of this device
+   */
+  constructor({ dataType, coreOwnership, coreManager, projectKey, deviceKey }) {
+    super()
+    this.#dataType = dataType
+    this.#coreOwnership = coreOwnership
+    this.#coreManager = coreManager
+    this.#projectCreatorAuthCoreId = projectKey.toString('hex')
+    this.#ownDeviceId = deviceKey.toString('hex')
+    dataType[kDataStore].on('role', this.emit.bind(this, 'update'))
+  }
+
+  /**
+   * Get the role for device `deviceId`.
+   *
+   * @param {string} deviceId
+   * @returns {Promise<Role>}
+   */
+  async getRole(deviceId) {
+    /** @type {string} */
+    let roleId
+    try {
+      const roleAssignment = await this.#dataType.getByDocId(deviceId)
+      roleId = roleAssignment.roleId
+    } catch (e) {
+      // The project creator will have the creator role
+      const authCoreId = await this.#coreOwnership.getCoreId(deviceId, 'auth')
+      if (authCoreId === this.#projectCreatorAuthCoreId) {
+        return CREATOR_ROLE
+      } else {
+        // When no role assignment exists, e.g. a newly added device which has
+        // not yet synced role records.
+        return NO_ROLE
+      }
+    }
+    if (!isRoleId(roleId)) {
+      return ROLES[BLOCKED_ROLE_ID]
+    }
+    return ROLES[roleId]
+  }
+
+  /**
+   * Get roles of all devices in the project. For your own device, if you have
+   * not yet synced your own role record, the "no role" capabilties is
+   * returned. The project creator will have the creator role unless a
+   * different one has been assigned.
+   *
+   * @returns {Promise<Map<string, Role>>} Map of deviceId to Role
+   */
+  async getAll() {
+    const roles = await this.#dataType.getMany()
+    /** @type {Map<string, Role>} */
+    const result = new Map()
+    /** @type {undefined | string} */
+    let projectCreatorDeviceId
+    try {
+      projectCreatorDeviceId = await this.#coreOwnership.getOwner(
+        this.#projectCreatorAuthCoreId
+      )
+      // Default to creator role, but can be overwritten if a different role is
+      // set below
+      result.set(projectCreatorDeviceId, CREATOR_ROLE)
+    } catch (e) {
+      // Not found, we don't know who the project creator is so we can't include
+      // them in the returned map
+    }
+
+    for (const role of roles) {
+      if (!isRoleId(role.roleId)) {
+        console.error("Found a value that wasn't a role ID")
+        continue
+      }
+      if (role.roleId === CREATOR_ROLE_ID) {
+        console.error('Unexpected creator role')
+        continue
+      }
+      const deviceId = role.docId
+      result.set(deviceId, ROLES[role.roleId])
+    }
+    const includesSelf = result.has(this.#ownDeviceId)
+    if (!includesSelf) {
+      const isProjectCreator = this.#ownDeviceId === projectCreatorDeviceId
+      result.set(this.#ownDeviceId, isProjectCreator ? CREATOR_ROLE : NO_ROLE)
+    }
+    return result
+  }
+
+  /**
+   * Assign a role to the specified `deviceId`. Devices without an assigned role
+   * are unable to sync, except the project creator who can do anything. Only
+   * the project creator can assign their own role. Will throw if the device's
+   * role cannot assign the role by consulting `roleAssignment`.
+   *
+   * @param {string} deviceId
+   * @param {RoleIdAssignableToAnyone} roleId
+   */
+  async assignRole(deviceId, roleId) {
+    assert(
+      isRoleIdAssignableToAnyone(roleId),
+      `Role ID should be assignable to anyone but got ${roleId}`
+    )
+
+    let fromIndex = 0
+    let authCoreId
+    try {
+      authCoreId = await this.#coreOwnership.getCoreId(deviceId, 'auth')
+      const authCoreKey = Buffer.from(authCoreId, 'hex')
+      const authCore = this.#coreManager.getCoreByKey(authCoreKey)
+      if (authCore) {
+        await authCore.ready()
+        fromIndex = authCore.length
+      }
+    } catch {
+      // This will usually happen when assigning a role to a newly invited
+      // device that has not yet synced (so we do not yet have a replica of
+      // their authCore). In this case we want fromIndex to be 0
+    }
+    const isAssigningProjectCreatorRole =
+      authCoreId === this.#projectCreatorAuthCoreId
+    if (isAssigningProjectCreatorRole && !this.#isProjectCreator()) {
+      throw new Error(
+        "Only the project creator can assign the project creator's role"
+      )
+    }
+
+    if (roleId === LEFT_ROLE_ID) {
+      if (deviceId !== this.#ownDeviceId) {
+        throw new Error('Cannot assign LEFT role to another device')
+      }
+    } else {
+      const ownRole = await this.getRole(this.#ownDeviceId)
+      if (!ownRole.roleAssignment.includes(roleId)) {
+        throw new Error('Lacks permission to assign role ' + roleId)
+      }
+    }
+
+    const existingRoleDoc = await this.#dataType
+      .getByDocId(deviceId)
+      .catch(() => null)
+
+    if (existingRoleDoc) {
+      await this.#dataType.update(
+        [existingRoleDoc.versionId, ...existingRoleDoc.forks],
+        {
+          schemaName: 'role',
+          roleId,
+          fromIndex,
+        }
+      )
+    } else {
+      await this.#dataType[kCreateWithDocId](deviceId, {
+        schemaName: 'role',
+        roleId,
+        fromIndex,
+      })
+    }
+  }
+
+  async #isProjectCreator() {
+    const ownAuthCoreId = this.#coreManager
+      .getWriterCore('auth')
+      .key.toString('hex')
+    return ownAuthCoreId === this.#projectCreatorAuthCoreId
+  }
+}

package/src/schema/client.js

@@ -0,0 +1,55 @@
+// These schemas are all in a "client" database. There is only one client
+// database and it contains information that is shared across all projects on a
+// device
+import { blob, sqliteTable, text } from 'drizzle-orm/sqlite-core'
+import { dereferencedDocSchemas as schemas } from '@comapeo/schema'
+import { jsonSchemaToDrizzleColumns as toColumns } from './schema-to-drizzle.js'
+import { backlinkTable, customJson } from './utils.js'
+
+/**
+ * @internal
+ * @typedef {object} ProjectInfo
+ * @prop {string} [name]
+ */
+
+const projectInfoColumn =
+  /** @type {ReturnType<typeof import('drizzle-orm/sqlite-core').customType<{data: ProjectInfo}>>} */ (
+    customJson
+  )
+
+/** @type {ProjectInfo} */
+const PROJECT_INFO_DEFAULT_VALUE = {}
+
+export const projectSettingsTable = sqliteTable(
+  'projectSettings',
+  toColumns(schemas.projectSettings)
+)
+export const projectBacklinkTable = backlinkTable(projectSettingsTable)
+export const projectKeysTable = sqliteTable('projectKeys', {
+  projectId: text('projectId').notNull().primaryKey(),
+  projectPublicId: text('projectPublicId').notNull(),
+  projectInviteId: blob('projectInviteId').notNull(),
+  keysCipher: blob('keysCipher', { mode: 'buffer' }).notNull(),
+  projectInfo: projectInfoColumn('projectInfo')
+    .default(
+      // TODO: There's a bug in Drizzle where the default value does not get transformed by the custom type
+      // @ts-expect-error
+      JSON.stringify(PROJECT_INFO_DEFAULT_VALUE)
+    )
+    .notNull(),
+})
+
+/**
+ * @typedef {Omit<import('@comapeo/schema').DeviceInfoValue, 'schemaName'>} DeviceInfoParam
+ */
+
+const deviceInfoColumn =
+  /** @type {ReturnType<typeof import('drizzle-orm/sqlite-core').customType<{data: DeviceInfoParam }>>} */ (
+    customJson
+  )
+
+// This table only ever has one row in it.
+export const localDeviceInfoTable = sqliteTable('localDeviceInfo', {
+  deviceId: text('deviceId').notNull().unique(),
+  deviceInfo: deviceInfoColumn('deviceInfo').notNull(),
+})

package/src/schema/project.js

@@ -0,0 +1,44 @@
+// These schemas are all in a "project" database. Each project in Mapeo has an
+// independent "project" database.
+import { blob, sqliteTable, text } from 'drizzle-orm/sqlite-core'
+import { dereferencedDocSchemas as schemas } from '@comapeo/schema'
+import { NAMESPACES } from '../constants.js'
+import { jsonSchemaToDrizzleColumns as toColumns } from './schema-to-drizzle.js'
+import { backlinkTable } from './utils.js'
+
+export const translationTable = sqliteTable(
+  'translation',
+  toColumns(schemas.translation)
+)
+export const observationTable = sqliteTable(
+  'observation',
+  toColumns(schemas.observation)
+)
+export const trackTable = sqliteTable('track', toColumns(schemas.track))
+export const presetTable = sqliteTable('preset', toColumns(schemas.preset))
+export const fieldTable = sqliteTable('field', toColumns(schemas.field))
+export const coreOwnershipTable = sqliteTable(
+  'coreOwnership',
+  toColumns(schemas.coreOwnership)
+)
+export const roleTable = sqliteTable('role', toColumns(schemas.role))
+export const deviceInfoTable = sqliteTable(
+  'deviceInfo',
+  toColumns(schemas.deviceInfo)
+)
+export const iconTable = sqliteTable('icon', toColumns(schemas.icon))
+
+export const translationBacklinkTable = backlinkTable(translationTable)
+export const observationBacklinkTable = backlinkTable(observationTable)
+export const trackBacklinkTable = backlinkTable(trackTable)
+export const presetBacklinkTable = backlinkTable(presetTable)
+export const fieldBacklinkTable = backlinkTable(fieldTable)
+export const coreOwnershipBacklinkTable = backlinkTable(coreOwnershipTable)
+export const roleBacklinkTable = backlinkTable(roleTable)
+export const deviceInfoBacklinkTable = backlinkTable(deviceInfoTable)
+export const iconBacklinkTable = backlinkTable(iconTable)
+
+export const coresTable = sqliteTable('cores', {
+  publicKey: blob('publicKey', { mode: 'buffer' }).notNull(),
+  namespace: text('namespace', { enum: NAMESPACES }).notNull(),
+})

package/src/schema/schema-to-drizzle.js

@@ -0,0 +1,118 @@
+import { text, integer, real } from 'drizzle-orm/sqlite-core'
+import { ExhaustivenessError } from '../utils.js'
+import { customJson } from './utils.js'
+/** @import { MapeoDoc } from '@comapeo/schema' */
+/** @import { MapeoDocMap } from '../types.js' */
+
+/**
+Convert a JSONSchema definition to a Drizzle Columns Map (the parameter for
+`sqliteTable()`).
+
+**NOTE**: The return of this function is _not_ type-checked (it is coerced with
+`as`, because it's not possible to type-check what this function is doing), but
+the return type _should_ be correct when using this function.
+@template {import('./types.js').JSONSchema7WithProps} TSchema
+NB: The inline typescript checker often marks this next line as an error, but this seems to be a bug with JSDoc parsing - running `tsc` does not show this as an error.
+@template {import('type-fest').Get<TSchema, 'properties.schemaName.const'>} TSchemaName
+@template {TSchemaName extends MapeoDoc['schemaName'] ? MapeoDocMap[TSchemaName] : any} TObjectType
+@param {TSchema} schema
+@returns {import('./types.js').SchemaToDrizzleColumns<TSchema, TObjectType>}
+ */
+export function jsonSchemaToDrizzleColumns(schema) {
+  if (schema.type !== 'object' || !schema.properties) {
+    throw new Error('Cannot process JSONSchema as SQL table')
+  }
+  /** @type {Record<string, any>} */
+  const columns = {}
+  for (const [key, value] of Object.entries(schema.properties)) {
+    if (typeof value !== 'object') continue
+    if (isArray(value.type) || typeof value.type === 'undefined') {
+      throw new Error('Cannot process JSONSchema as SQL table')
+    }
+    switch (value.type) {
+      case 'boolean':
+        columns[key] = integer(key, { mode: 'boolean' })
+        break
+      case 'number':
+        columns[key] = real(key)
+        break
+      case 'integer':
+        columns[key] = integer(key)
+        break
+      case 'string': {
+        const enumValue = isStringArray(value.enum)
+          ? value.enum
+          : typeof value.const === 'string'
+          ? /** @type {[typeof value.const]} */ ([value.const])
+          : undefined
+        columns[key] = text(key, { enum: enumValue })
+        if (key === 'docId') {
+          columns[key] = columns[key].primaryKey()
+        }
+        break
+      }
+      case 'array':
+      case 'object':
+        columns[key] = customJson(key)
+        break
+      case 'null':
+        // Skip handling this right now
+        continue
+      default:
+        throw new ExhaustivenessError(value.type)
+    }
+    if (isRequired(schema, key)) {
+      columns[key] = columns[key].notNull()
+      // Only set defaults for required fields
+      const defaultValue = getDefault(value)
+      if (typeof defaultValue !== 'undefined') {
+        columns[key] = columns[key].default(defaultValue)
+      }
+    }
+  }
+  // Not yet in @comapeo/schema
+  columns.forks = customJson('forks').notNull()
+  return /** @type {any} */ (columns)
+}
+
+/**
+ * @template {import('./types.js').JSONSchema7} T
+ * @param {T} value
+ * @returns {T['default']}
+ */
+function getDefault(value) {
+  return value.default
+}
+
+/**
+ * @param {import('./types.js').JSONSchema7WithProps} schema
+ * @param {string} key
+ * @returns {boolean}
+ */
+function isRequired(schema, key) {
+  if (!isArray(schema.required)) return false
+  return schema.required.includes(key)
+}
+
+/**
+ * Tests whether a value is an array.
+ * @param {any} value
+ * @returns {value is readonly unknown[]}
+ */
+function isArray(value) {
+  // See: https://github.com/microsoft/TypeScript/issues/17002
+  return Array.isArray(value)
+}
+
+/**
+ * Check if a value is an array of strings of length at least one
+ * @param {any} value
+ * @returns {value is [string, ...string[]]}
+ */
+function isStringArray(value) {
+  return (
+    isArray(value) &&
+    value.every((v) => typeof v === 'string') &&
+    value.length > 0
+  )
+}