@peanut-admin/admin 0.1.0-alpha.5 → 0.1.0-alpha.6

package/admin-core/src/access/permission-policy.ts

@@ -0,0 +1,37 @@
+import { hasPermission } from './access'
+import { defineAdminOverrideSlot } from '../runtime/overrides'
+
+export type PermissionEvaluator = (
+  permissions: ReadonlySet<string>,
+  permission: string,
+) => boolean
+
+export const PERMISSION_EVALUATOR_OVERRIDE_KEY =
+  'authorization.permission.service.evaluator' as const
+
+const isPermissionEvaluator = (candidate: unknown): candidate is PermissionEvaluator => (
+  typeof candidate === 'function'
+)
+
+export const permissionEvaluatorSlot = defineAdminOverrideSlot({
+  key: PERMISSION_EVALUATOR_OVERRIDE_KEY,
+  kind: 'service' as const,
+  contractVersion: '1.0.0',
+  defaultValue: hasPermission as PermissionEvaluator,
+  validate: isPermissionEvaluator,
+})
+
+export const evaluateRequiredPermissions = (
+  requiredPermissions: string | string[],
+  grantedPermissions: readonly string[],
+  evaluator: PermissionEvaluator,
+): boolean => {
+  const required = (Array.isArray(requiredPermissions) ? requiredPermissions : [requiredPermissions])
+    .filter(Boolean)
+  if (required.length === 0) return true
+
+  const permissionSet = new Set(grantedPermissions)
+  return permissionSet.has('*') || required.some(
+    permission => permission !== '*' && evaluator(permissionSet, permission),
+  )
+}

package/admin-core/src/auth/tenant-session.ts

@@ -0,0 +1,32 @@
+export interface TenantChoice {
+  tenant_id: number
+  tenant_code: string
+  tenant_name: string
+  member_id: number
+  member_display_name: string
+}
+
+export interface TenantSelection {
+  state: 'tenant_selection_required'
+  challenge_token: string
+  expires_at: string
+  tenants: TenantChoice[]
+}
+
+export interface TenantAuthentication {
+  state: 'authenticated'
+  access_token: string
+  token_type: 'Bearer'
+  expires_in: number
+  context: {
+    tenant_id: string
+    account_id: string
+    tenant_member_id: string
+  }
+}
+
+export type TenantSessionOutcome = TenantSelection | TenantAuthentication
+
+export const isMultiTenantDeployment = (value: unknown): boolean => value === 'multi-tenant'
+
+export const isTenantAccessToken = (token: string | null): boolean => token?.startsWith('pa_tat_') === true

package/admin-core/src/index.ts

@@ -14,6 +14,12 @@ export { isProblemCode, parseProblemDetails } from './api/problem'
 export type { ProblemDetails, ProblemFieldError } from './api/problem'
 export { hasAllPermissions, hasPermission, useAccess } from './access/access'
 export type { AccessHints } from './access/access'
+export {
+  evaluateRequiredPermissions,
+  permissionEvaluatorSlot,
+  PERMISSION_EVALUATOR_OVERRIDE_KEY,
+} from './access/permission-policy'
+export type { PermissionEvaluator } from './access/permission-policy'
 export {
   usePlatformAuth,
   usePlatformContext,
@@ -21,10 +27,19 @@ export {
   useTenantContext,
 } from './auth/stores'
 export type { PlatformContextData, TenantContextData } from './auth/stores'
+export { isMultiTenantDeployment, isTenantAccessToken } from './auth/tenant-session'
+export type {
+  TenantAuthentication,
+  TenantChoice,
+  TenantSelection,
+  TenantSessionOutcome,
+} from './auth/tenant-session'
 export { disposeTenantState, registerTenantDisposer } from './lifecycle/tenant'
 export { createTenantLifecycle } from './lifecycle/tenant'
 export type { TenantDisposer, TenantLifecycle, TenantLifecycleTicket } from './lifecycle/tenant'
 export { createMenuRouteRegistry, defineAdminModule } from './module/contribution'
+export { collectPluginContributions, routesForTenantModules } from './module/plugin-contribution-policy'
+export { enabledTenantModulesFromRoutes } from './module/tenant-modules'
 export type {
   AdminModuleContribution,
   AdminModuleLocaleContribution,
@@ -35,6 +50,8 @@ export type {
   AdminRouteAccess,
   MenuRouteRegistry,
 } from './module/contribution'
+export type { PluginFrontendContribution, PluginFrontendRoute } from './module/plugin-contribution-policy'
+export type { TenantModuleRoute } from './module/tenant-modules'
 export { defineAdminHostConfig } from './runtime/config'
 export type { AdminAudienceHostConfig, AdminHostConfig } from './runtime/config'
 export { mapAdminRuntimeError } from './runtime/errors'

package/admin-core/src/module/plugin-contribution-policy.ts

@@ -0,0 +1,51 @@
+import type { PermissionEvaluator } from '../access/permission-policy'
+import { evaluateRequiredPermissions } from '../access/permission-policy'
+
+/**
+ * Minimal router contract shared by host applications without coupling to a
+ * particular Vue Router major version.
+ */
+export interface PluginFrontendRoute {
+  path: string
+  name?: unknown
+  component?: unknown
+  meta?: {
+    requiredPermissions?: string | string[]
+    [key: string]: unknown
+  }
+  children?: PluginFrontendRoute[]
+}
+
+export interface PluginFrontendContribution<T extends PluginFrontendRoute = PluginFrontendRoute> {
+  moduleKey: string
+  routes: T[]
+}
+
+export const collectPluginContributions = (
+  modules: Record<string, { default?: PluginFrontendContribution }>,
+): PluginFrontendContribution[] => Object.keys(modules)
+  .sort()
+  .map(path => modules[path]?.default)
+  .filter((contribution): contribution is PluginFrontendContribution => (
+    typeof contribution?.moduleKey === 'string'
+      && contribution.moduleKey.length > 0
+      && Array.isArray(contribution.routes)
+  ))
+
+/** Deployment presence alone never exposes a Tenant Module route. */
+export const routesForTenantModules = <T extends PluginFrontendRoute>(
+  contributions: PluginFrontendContribution<T>[],
+  enabledModules: readonly string[],
+  grantedPermissions: readonly string[],
+  evaluator: PermissionEvaluator,
+): T[] => {
+  const enabled = new Set(enabledModules)
+  return contributions.flatMap((contribution) => {
+    if (!enabled.has(contribution.moduleKey)) return []
+    return contribution.routes.filter((route) => {
+      const required = route.meta?.requiredPermissions
+      return (typeof required === 'string' || Array.isArray(required))
+        && evaluateRequiredPermissions(required, grantedPermissions, evaluator)
+    })
+  })
+}

package/admin-core/src/module/tenant-modules.ts

@@ -0,0 +1,20 @@
+/** Minimal route shape needed to derive Tenant module availability. */
+export interface TenantModuleRoute {
+  meta?: {
+    tenantModuleKey?: unknown
+  }
+  children?: readonly TenantModuleRoute[]
+}
+
+/**
+ * Derive the distinct Tenant module keys exposed by a server-authorized route
+ * tree. The host owns fetching and route-to-component resolution.
+ */
+export const enabledTenantModulesFromRoutes = (
+  routes: readonly TenantModuleRoute[],
+): string[] => Array.from(new Set(
+  routes
+    .flatMap(route => [route, ...(route.children ?? [])])
+    .map(route => route.meta?.tenantModuleKey)
+    .filter((key): key is string => typeof key === 'string'),
+))

package/admin-shell/src/deployment-mode.ts

@@ -0,0 +1,36 @@
+export type DeploymentMode = 'standalone' | 'multi-tenant'
+
+/**
+ * Minimal router contract shared by host applications without coupling to a
+ * particular Vue Router major version.
+ */
+export interface DeploymentRoute {
+  meta?: {
+    controlPlane?: unknown
+    instanceTool?: boolean
+    [key: string]: unknown
+  }
+  children?: DeploymentRoute[]
+}
+
+export const deploymentMode = (value: unknown): DeploymentMode => (
+  value === 'multi-tenant' ? 'multi-tenant' : 'standalone'
+)
+
+export const allowsInstanceTools = (value: unknown): boolean => value === 'standalone'
+
+export const routesForDeployment = <T extends DeploymentRoute>(
+  routes: T[],
+  mode: DeploymentMode,
+  instanceToolsAllowed = mode === 'standalone',
+): T[] => routes.reduce<T[]>((visible, route) => {
+  if (mode !== 'multi-tenant' && route.meta?.controlPlane !== undefined) return visible
+  if (!instanceToolsAllowed && route.meta?.instanceTool === true) return visible
+  visible.push({
+    ...route,
+    children: route.children
+      ? routesForDeployment(route.children, mode, instanceToolsAllowed)
+      : route.children,
+  } as T)
+  return visible
+}, [])

package/admin-shell/src/index.ts

@@ -29,6 +29,10 @@ export { TargetScopeSummary, TargetSelector } from './targets'
 export type { TargetScopeMode } from './targets'
 export { SHELL_THEME_TOKENS } from './theme'
 export type { ShellSlotName, ShellThemeToken } from './theme'
+export { allowsInstanceTools, deploymentMode, routesForDeployment } from './deployment-mode'
+export type { DeploymentMode, DeploymentRoute } from './deployment-mode'
+export { tabFromRoute } from './tabs'
+export type { ShellTab, ShellTabRoute, ShellTabState } from './tabs'
 export {
   ADMIN_SHELL_OVERRIDE_SLOTS,
   resolveWorkspaceShell,

package/admin-shell/src/tabs.ts

@@ -0,0 +1,31 @@
+/** Framework-neutral route data required by an admin workspace tab. */
+export interface ShellTabRoute {
+  name: unknown
+  fullPath: string
+  query?: any
+  meta?: {
+    locale?: string
+    ignoreCache?: boolean | undefined
+  }
+}
+
+export interface ShellTab {
+  title: string
+  name: string
+  fullPath: string
+  query?: any
+  ignoreCache?: boolean | undefined
+}
+
+export interface ShellTabState {
+  tagList: ShellTab[]
+  cacheTabList: Set<string>
+}
+
+export const tabFromRoute = (route: ShellTabRoute): ShellTab => ({
+  title: route.meta?.locale || '',
+  name: String(route.name),
+  fullPath: route.fullPath,
+  query: route.query,
+  ignoreCache: route.meta?.ignoreCache,
+})

package/package.json

@@ -1,17 +1,14 @@
 {
   "name": "@peanut-admin/admin",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.6",
   "description": "Reusable Peanut Admin Web services and module contributions",
   "type": "module",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/peanut-opensource/peanut-admin.git",
-    "directory": "packages/web"
+    "url": "https://github.com/peanut-opensource/peanut-admin-core"
   },
-  "sideEffects": [
-    "*.vue"
-  ],
+  "sideEffects": ["*.vue"],
   "files": [
     "admin-core/src",
     "admin-shell/src",
@@ -23,7 +20,6 @@
     "import-export/src",
     "ops-console/src",
     "integration-security/src",
-    "collaboration/src",
     "testing/src",
     "client-core/src",
     "client-nuxt/src",
@@ -70,10 +66,6 @@
       "types": "./integration-security/src/index.ts",
       "import": "./integration-security/src/index.ts"
     },
-    "./collaboration": {
-      "types": "./collaboration/src/index.ts",
-      "import": "./collaboration/src/index.ts"
-    },
     "./testing": {
       "development": {
         "types": "./testing/src/index.ts",
@@ -95,57 +87,24 @@
   },
   "typesVersions": {
     "*": {
-      "core": [
-        "admin-core/src/index.ts"
-      ],
-      "shell": [
-        "admin-shell/src/index.ts"
-      ],
-      "settings": [
-        "settings/src/index.ts"
-      ],
-      "reference-codes": [
-        "reference-codes/src/index.ts"
-      ],
-      "file-media": [
-        "file-media/src/index.ts"
-      ],
-      "task-job": [
-        "task-job/src/index.ts"
-      ],
-      "notification-sms": [
-        "notification-sms/src/index.ts"
-      ],
-      "import-export": [
-        "import-export/src/index.ts"
-      ],
-      "ops-console": [
-        "ops-console/src/index.ts"
-      ],
-      "integration-security": [
-        "integration-security/src/index.ts"
-      ],
-      "collaboration": [
-        "collaboration/src/index.ts"
-      ],
-      "testing": [
-        "testing/src/index.ts"
-      ],
-      "client": [
-        "client-core/src/index.ts"
-      ],
-      "client/nuxt": [
-        "client-nuxt/src/index.ts"
-      ],
-      "client/uniapp": [
-        "client-uniapp/src/index.ts"
-      ]
+      "core": ["admin-core/src/index.ts"],
+      "shell": ["admin-shell/src/index.ts"],
+      "settings": ["settings/src/index.ts"],
+      "reference-codes": ["reference-codes/src/index.ts"],
+      "file-media": ["file-media/src/index.ts"],
+      "task-job": ["task-job/src/index.ts"],
+      "notification-sms": ["notification-sms/src/index.ts"],
+      "import-export": ["import-export/src/index.ts"],
+      "ops-console": ["ops-console/src/index.ts"],
+      "integration-security": ["integration-security/src/index.ts"],
+      "testing": ["testing/src/index.ts"],
+      "client": ["client-core/src/index.ts"],
+      "client/nuxt": ["client-nuxt/src/index.ts"],
+      "client/uniapp": ["client-uniapp/src/index.ts"]
     }
   },
   "dependencies": {
-    "openapi-fetch": "0.17.0",
-    "y-websocket": "3.1.0",
-    "yjs": "13.6.32"
+    "openapi-fetch": "0.17.0"
   },
   "devDependencies": {
     "@vue/test-utils": "2.4.11",
@@ -162,7 +121,8 @@
   "peerDependencies": {
     "element-plus": "^2.14.3",
     "pinia": ">=2.0.23 <5",
-    "vue": "^3.4.21"
+    "vue": "^3.4.21",
+    "vue-router": ">=4.0.0 <6"
   },
   "peerDependenciesMeta": {
     "element-plus": {
@@ -173,7 +133,7 @@
     }
   },
   "scripts": {
-    "test": "vitest run admin-core/tests admin-shell/tests collaboration/tests file-media/tests import-export/tests integration-security/tests notification-sms/tests ops-console/tests reference-codes/tests settings/tests testing/tests client-core/tests client-nuxt/tests client-uniapp/tests",
-    "typecheck": "tsc --noEmit -p admin-core/tsconfig.json && tsc --noEmit -p admin-shell/tsconfig.json && tsc --noEmit -p collaboration/tsconfig.json && vue-tsc --noEmit -p file-media/tsconfig.json && vue-tsc --noEmit -p import-export/tsconfig.json && vue-tsc --noEmit -p integration-security/tsconfig.json && vue-tsc --noEmit -p notification-sms/tsconfig.json && vue-tsc --noEmit -p ops-console/tsconfig.json && vue-tsc --noEmit -p reference-codes/tsconfig.json && vue-tsc --noEmit -p settings/tsconfig.json && vue-tsc --noEmit -p task-job/tsconfig.json && tsc --noEmit -p testing/tsconfig.json && tsc --noEmit -p client-core/tsconfig.json && tsc --noEmit -p client-nuxt/tsconfig.json && tsc --noEmit -p client-uniapp/tsconfig.json"
+    "test": "vitest run admin-core/tests admin-shell/tests file-media/tests import-export/tests integration-security/tests notification-sms/tests ops-console/tests reference-codes/tests settings/tests testing/tests client-core/tests client-nuxt/tests client-uniapp/tests",
+    "typecheck": "tsc --noEmit -p admin-core/tsconfig.json && tsc --noEmit -p admin-shell/tsconfig.json && vue-tsc --noEmit -p file-media/tsconfig.json && vue-tsc --noEmit -p import-export/tsconfig.json && vue-tsc --noEmit -p integration-security/tsconfig.json && vue-tsc --noEmit -p notification-sms/tsconfig.json && vue-tsc --noEmit -p ops-console/tsconfig.json && vue-tsc --noEmit -p reference-codes/tsconfig.json && vue-tsc --noEmit -p settings/tsconfig.json && vue-tsc --noEmit -p task-job/tsconfig.json && tsc --noEmit -p testing/tsconfig.json && tsc --noEmit -p client-core/tsconfig.json && tsc --noEmit -p client-nuxt/tsconfig.json && tsc --noEmit -p client-uniapp/tsconfig.json"
   }
-}
+}

package/collaboration/src/contracts.ts

@@ -1,207 +0,0 @@
-export const COLLABORATION_ENGINE_NAME = 'yjs' as const
-export const COLLABORATION_ENGINE_VERSION = '13.6.32' as const
-
-export type CollaborationCapability = 'read' | 'write'
-export type CollaborationSessionState = 'active' | 'published' | 'closed' | 'expired'
-export type CollaborationConnectionStatus = 'idle' | 'admitting' | 'hydrating' | 'connecting' | 'connected' | 'disconnected' | 'error' | 'disposed'
-export type CollaborationUpdateOrigin = 'local' | 'remote' | 'replay'
-export type CollaborationTransportStatus = 'connecting' | 'connected' | 'disconnected'
-export type CollaborationErrorCode =
-  | 'COLLABORATION_INVALID'
-  | 'COLLABORATION_NOT_FOUND'
-  | 'COLLABORATION_DENIED'
-  | 'COLLABORATION_CONFLICT'
-  | 'COLLABORATION_LEASE_EXPIRED'
-  | 'COLLABORATION_PAYLOAD_TOO_LARGE'
-  | 'COLLABORATION_BACKPRESSURE'
-  | 'COLLABORATION_PROVIDER_UNAVAILABLE'
-  | 'COLLABORATION_INTEGRITY_FAILURE'
-  | 'COLLABORATION_INTERNAL_ERROR'
-
-export interface CollaborationSession {
-  readonly sessionKey: string
-  readonly artifactType: string
-  readonly artifactKey: string
-  readonly engineName: typeof COLLABORATION_ENGINE_NAME
-  readonly engineVersion: typeof COLLABORATION_ENGINE_VERSION
-  readonly baseRevisionKey: string
-  readonly baseRevisionDigest: string
-  readonly latestSequence: number
-  readonly state: CollaborationSessionState
-  readonly expiresAt: string
-}
-
-export interface CollaborationLease {
-  readonly leaseKey: string
-  readonly clientKey: string
-  readonly capability: CollaborationCapability
-  readonly expiresAt: string
-}
-
-export interface CollaborationTransportAdmission {
-  readonly websocketUrl: string
-  readonly roomName: string
-}
-
-export interface CollaborationAdmission {
-  readonly session: CollaborationSession
-  readonly lease: CollaborationLease
-  readonly transport: CollaborationTransportAdmission
-}
-
-export interface CollaborationUpdateEnvelope {
-  readonly updateKey: string
-  readonly sequence: number
-  readonly engineName: typeof COLLABORATION_ENGINE_NAME
-  readonly engineVersion: typeof COLLABORATION_ENGINE_VERSION
-  readonly digest: string
-  readonly payload: Uint8Array
-}
-
-export interface CollaborationSnapshotEnvelope {
-  readonly snapshotKey: string
-  readonly coveredSequence: number
-  readonly engineName: typeof COLLABORATION_ENGINE_NAME
-  readonly engineVersion: typeof COLLABORATION_ENGINE_VERSION
-  readonly snapshotDigest: string
-  readonly stateVectorDigest: string
-  readonly snapshot: Uint8Array
-  readonly stateVector: Uint8Array
-}
-
-export interface CollaborationStatePage {
-  readonly snapshot: CollaborationSnapshotEnvelope | null
-  readonly updates: readonly CollaborationUpdateEnvelope[]
-  readonly latestSequence: number
-  readonly nextAfterSequence: number | null
-}
-
-export interface CollaborationSafeError {
-  readonly code: CollaborationErrorCode
-  readonly message: string
-  readonly requestId: string | null
-  readonly status: number
-}
-
-export interface CollaborationEngine<TDocument = unknown> {
-  readonly document: TDocument
-  applyUpdate: (update: Uint8Array, origin?: Exclude<CollaborationUpdateOrigin, 'local'>) => void
-  encodeStateVector: () => Uint8Array
-  encodeSnapshot: () => Uint8Array
-  onUpdate: (listener: (update: Uint8Array, origin: CollaborationUpdateOrigin) => void) => () => void
-  dispose: () => void
-}
-
-export interface CollaborationTransport {
-  connect: (admission: CollaborationTransportAdmission, initialSnapshot: Uint8Array) => void
-  disconnect: () => void
-  sendUpdate: (update: Uint8Array) => void
-  onStatus: (listener: (status: CollaborationTransportStatus) => void) => () => void
-  onUpdate: (listener: (update: Uint8Array) => void) => () => void
-  dispose: () => void
-}
-
-export interface CollaborationHostApi {
-  admit: (signal: AbortSignal) => Promise<CollaborationAdmission>
-  state: (sessionKey: string, afterSequence: number, signal: AbortSignal) => Promise<CollaborationStatePage>
-}
-
-export interface CollaborationRuntimeState {
-  readonly status: CollaborationConnectionStatus
-  readonly session: CollaborationSession | null
-  readonly lease: CollaborationLease | null
-  readonly latestSequence: number
-  readonly error: CollaborationSafeError | null
-}
-
-const stableKey = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/
-const opaqueKey = /^[a-z][a-z0-9]*_[0-9a-f]{32}$/
-const sha256 = /^[0-9a-f]{64}$/
-const instant = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/
-
-const printable = (value: string, maximum: number): boolean => value.length >= 1 && value.length <= maximum && /^[\x20-\x7e]+$/.test(value)
-const validInstant = (value: string): boolean => instant.test(value) && Number.isFinite(Date.parse(value))
-const sequence = (value: number): boolean => Number.isSafeInteger(value) && value >= 0
-const bytes = (value: Uint8Array, maximum: number): boolean => value.byteLength >= 1 && value.byteLength <= maximum
-
-export const assertCollaborationAdmission = (admission: CollaborationAdmission): void => {
-  const { session, lease, transport } = admission
-  if (!opaqueKey.test(session.sessionKey) || !stableKey.test(session.artifactType) || session.artifactType.length > 64
-    || !printable(session.artifactKey, 128) || session.engineName !== COLLABORATION_ENGINE_NAME
-    || session.engineVersion !== COLLABORATION_ENGINE_VERSION || !printable(session.baseRevisionKey, 128)
-    || !sha256.test(session.baseRevisionDigest) || !sequence(session.latestSequence) || session.state !== 'active'
-    || !validInstant(session.expiresAt) || !opaqueKey.test(lease.leaseKey) || !printable(lease.clientKey, 128)
-    || (lease.capability !== 'read' && lease.capability !== 'write') || !validInstant(lease.expiresAt)
-    || typeof transport.websocketUrl !== 'string' || !printable(transport.roomName, 128)) {
-    throw new Error('COLLABORATION_RESPONSE_INVALID')
-  }
-}
-
-export const assertCollaborationStatePage = (page: CollaborationStatePage, afterSequence: number): void => {
-  if (!sequence(page.latestSequence) || page.latestSequence < afterSequence
-    || (page.nextAfterSequence !== null && (!sequence(page.nextAfterSequence) || page.nextAfterSequence <= afterSequence || page.nextAfterSequence > page.latestSequence))) {
-    throw new Error('COLLABORATION_RESPONSE_INVALID')
-  }
-  let cursor = afterSequence
-  if (page.snapshot !== null) {
-    const snapshot = page.snapshot
-    if (!opaqueKey.test(snapshot.snapshotKey) || !sequence(snapshot.coveredSequence) || snapshot.coveredSequence < afterSequence
-      || snapshot.coveredSequence > page.latestSequence || snapshot.engineName !== COLLABORATION_ENGINE_NAME
-      || snapshot.engineVersion !== COLLABORATION_ENGINE_VERSION || !sha256.test(snapshot.snapshotDigest)
-      || !sha256.test(snapshot.stateVectorDigest) || !bytes(snapshot.snapshot, 8_388_608) || !bytes(snapshot.stateVector, 8_388_608)) {
-      throw new Error('COLLABORATION_RESPONSE_INVALID')
-    }
-    cursor = snapshot.coveredSequence
-  }
-  for (const update of page.updates) {
-    if (!opaqueKey.test(update.updateKey) || update.sequence !== cursor + 1 || update.sequence > page.latestSequence
-      || update.engineName !== COLLABORATION_ENGINE_NAME || update.engineVersion !== COLLABORATION_ENGINE_VERSION
-      || !sha256.test(update.digest) || !bytes(update.payload, 262_144)) {
-      throw new Error('COLLABORATION_RESPONSE_INVALID')
-    }
-    cursor = update.sequence
-  }
-  if (page.nextAfterSequence !== null && page.nextAfterSequence !== cursor) throw new Error('COLLABORATION_RESPONSE_INVALID')
-  if (page.nextAfterSequence === null && cursor !== page.latestSequence) throw new Error('COLLABORATION_RESPONSE_INVALID')
-}
-
-const messages: Readonly<Record<CollaborationErrorCode, string>> = {
-  COLLABORATION_INVALID: 'The collaboration request was rejected.',
-  COLLABORATION_NOT_FOUND: 'The collaboration session was not found.',
-  COLLABORATION_DENIED: 'You do not have access to this collaboration session.',
-  COLLABORATION_CONFLICT: 'The collaboration session changed. Reopen it and try again.',
-  COLLABORATION_LEASE_EXPIRED: 'The collaboration lease expired. Reconnect to continue.',
-  COLLABORATION_PAYLOAD_TOO_LARGE: 'The collaboration update is too large.',
-  COLLABORATION_BACKPRESSURE: 'The collaboration session must be saved before more updates can be accepted.',
-  COLLABORATION_PROVIDER_UNAVAILABLE: 'The collaboration service is temporarily unavailable.',
-  COLLABORATION_INTEGRITY_FAILURE: 'The collaboration update could not be verified.',
-  COLLABORATION_INTERNAL_ERROR: 'The collaboration request could not be completed.',
-}
-
-const statuses: Readonly<Record<CollaborationErrorCode, number>> = {
-  COLLABORATION_INVALID: 422,
-  COLLABORATION_NOT_FOUND: 404,
-  COLLABORATION_DENIED: 403,
-  COLLABORATION_CONFLICT: 409,
-  COLLABORATION_LEASE_EXPIRED: 409,
-  COLLABORATION_PAYLOAD_TOO_LARGE: 413,
-  COLLABORATION_BACKPRESSURE: 429,
-  COLLABORATION_PROVIDER_UNAVAILABLE: 503,
-  COLLABORATION_INTEGRITY_FAILURE: 500,
-  COLLABORATION_INTERNAL_ERROR: 500,
-}
-
-export class CollaborationRequestError extends Error {
-  readonly safe: CollaborationSafeError
-
-  constructor(code: CollaborationErrorCode, requestId: string | null = null) {
-    super(messages[code])
-    this.name = 'CollaborationRequestError'
-    const safeRequestId = requestId !== null && /^[A-Za-z0-9._-]{1,128}$/.test(requestId) ? requestId : null
-    this.safe = { code, message: messages[code], requestId: safeRequestId, status: statuses[code] }
-  }
-}
-
-export const safeCollaborationError = (error: unknown): CollaborationSafeError => error instanceof CollaborationRequestError
-  ? error.safe
-  : new CollaborationRequestError('COLLABORATION_INTERNAL_ERROR').safe

package/collaboration/src/engine.ts

@@ -1,46 +0,0 @@
-import * as Y from 'yjs'
-import type { CollaborationEngine, CollaborationUpdateOrigin } from './contracts'
-
-const remoteOrigin = Symbol('peanut.collaboration.remote')
-const replayOrigin = Symbol('peanut.collaboration.replay')
-
-export type YjsCollaborationEngine = CollaborationEngine<Y.Doc>
-
-export const createYjsCollaborationEngine = (options: { readonly gc?: boolean; readonly guid?: string } = {}): YjsCollaborationEngine => {
-  const document = new Y.Doc(options)
-  const listeners = new Set<(update: Uint8Array, origin: CollaborationUpdateOrigin) => void>()
-  let disposed = false
-  const updated = (update: Uint8Array, origin: unknown): void => {
-    if (disposed) return
-    const kind: CollaborationUpdateOrigin = origin === remoteOrigin ? 'remote' : origin === replayOrigin ? 'replay' : 'local'
-    for (const listener of listeners) listener(update.slice(), kind)
-  }
-  document.on('update', updated)
-  return {
-    document,
-    applyUpdate(update, origin = 'remote') {
-      if (disposed) throw new Error('COLLABORATION_ENGINE_DISPOSED')
-      Y.applyUpdate(document, update, origin === 'replay' ? replayOrigin : remoteOrigin)
-    },
-    encodeStateVector() {
-      if (disposed) throw new Error('COLLABORATION_ENGINE_DISPOSED')
-      return Y.encodeStateVector(document)
-    },
-    encodeSnapshot() {
-      if (disposed) throw new Error('COLLABORATION_ENGINE_DISPOSED')
-      return Y.encodeStateAsUpdate(document)
-    },
-    onUpdate(listener) {
-      if (disposed) throw new Error('COLLABORATION_ENGINE_DISPOSED')
-      listeners.add(listener)
-      return () => { listeners.delete(listener) }
-    },
-    dispose() {
-      if (disposed) return
-      disposed = true
-      listeners.clear()
-      document.off('update', updated)
-      document.destroy()
-    },
-  }
-}

package/collaboration/src/index.ts

@@ -1,4 +0,0 @@
-export * from './contracts'
-export * from './engine'
-export * from './runtime'
-export * from './transport'

package/collaboration/src/runtime.ts

@@ -1,157 +0,0 @@
-import {
-  CollaborationRequestError,
-  assertCollaborationAdmission,
-  assertCollaborationStatePage,
-  safeCollaborationError,
-} from './contracts'
-import type {
-  CollaborationEngine,
-  CollaborationHostApi,
-  CollaborationRuntimeState,
-  CollaborationTransport,
-} from './contracts'
-
-export interface CollaborationRuntime {
-  readonly state: CollaborationRuntimeState
-  connect: () => Promise<void>
-  reconnect: () => Promise<void>
-  disconnect: () => void
-  onState: (listener: (state: CollaborationRuntimeState) => void) => () => void
-  encodeSnapshot: () => Uint8Array
-  encodeStateVector: () => Uint8Array
-  dispose: () => void
-}
-
-export interface CollaborationRuntimeOptions<TDocument = unknown> {
-  readonly host: CollaborationHostApi
-  readonly engine: CollaborationEngine<TDocument>
-  readonly transport: CollaborationTransport
-}
-
-const aborted = (error: unknown): boolean => error instanceof DOMException && error.name === 'AbortError'
-
-export const createCollaborationRuntime = <TDocument>(options: CollaborationRuntimeOptions<TDocument>): CollaborationRuntime => {
-  const listeners = new Set<(state: CollaborationRuntimeState) => void>()
-  let current: CollaborationRuntimeState = { status: 'idle', session: null, lease: null, latestSequence: 0, error: null }
-  let controller: AbortController | null = null
-  let generation = 0
-  let disposed = false
-  let establishedSessionKey: string | null = null
-
-  const publish = (patch: Partial<CollaborationRuntimeState>): void => {
-    current = { ...current, ...patch }
-    for (const listener of listeners) listener(current)
-  }
-  const disconnect = (): void => {
-    if (disposed) return
-    generation += 1
-    controller?.abort()
-    controller = null
-    options.transport.disconnect()
-    publish({ status: 'disconnected', lease: null, error: null })
-  }
-  const hydrate = async (sessionKey: string, firstSequence: number, signal: AbortSignal, run: number): Promise<number> => {
-    let cursor = firstSequence
-    for (let pages = 0; pages < 1000; pages += 1) {
-      const page = await options.host.state(sessionKey, cursor, signal)
-      if (run !== generation) return cursor
-      assertCollaborationStatePage(page, cursor)
-      if (page.snapshot !== null) {
-        options.engine.applyUpdate(page.snapshot.snapshot, 'replay')
-        cursor = page.snapshot.coveredSequence
-      }
-      for (const update of page.updates) {
-        options.engine.applyUpdate(update.payload, 'replay')
-        cursor = update.sequence
-      }
-      if (page.nextAfterSequence === null) return page.latestSequence
-      cursor = page.nextAfterSequence
-    }
-    throw new CollaborationRequestError('COLLABORATION_INTERNAL_ERROR')
-  }
-  const connect = async (): Promise<void> => {
-    if (disposed) throw new Error('COLLABORATION_RUNTIME_DISPOSED')
-    const run = ++generation
-    controller?.abort()
-    options.transport.disconnect()
-    const nextController = new AbortController()
-    controller = nextController
-    publish({ status: 'admitting', lease: null, error: null })
-    try {
-      const admission = await options.host.admit(nextController.signal)
-      if (run !== generation) return
-      assertCollaborationAdmission(admission)
-      if (establishedSessionKey !== null && establishedSessionKey !== admission.session.sessionKey) {
-        throw new CollaborationRequestError('COLLABORATION_CONFLICT')
-      }
-      const initialSequence = establishedSessionKey === null ? 0 : current.latestSequence
-      publish({ status: 'hydrating', session: admission.session, lease: admission.lease, latestSequence: initialSequence })
-      const latestSequence = await hydrate(admission.session.sessionKey, initialSequence, nextController.signal, run)
-      if (run !== generation) return
-      if (latestSequence !== admission.session.latestSequence) throw new CollaborationRequestError('COLLABORATION_INTEGRITY_FAILURE')
-      establishedSessionKey = admission.session.sessionKey
-      publish({ status: 'connecting', latestSequence })
-      options.transport.connect(admission.transport, options.engine.encodeSnapshot())
-    } catch (error) {
-      if (run !== generation || aborted(error)) return
-      options.transport.disconnect()
-      publish({ status: 'error', lease: null, error: safeCollaborationError(error) })
-    } finally {
-      if (controller === nextController) controller = null
-    }
-  }
-
-  const removeEngineListener = options.engine.onUpdate((update, origin) => {
-    if ((current.status === 'connecting' || current.status === 'connected') && origin === 'local') {
-      try {
-        if (update.byteLength > 262_144) throw new CollaborationRequestError('COLLABORATION_PAYLOAD_TOO_LARGE')
-        options.transport.sendUpdate(update)
-      } catch (error) {
-        options.transport.disconnect()
-        publish({ status: 'error', lease: null, error: safeCollaborationError(error) })
-      }
-    }
-  })
-  const removeTransportUpdateListener = options.transport.onUpdate(update => {
-    if (current.status !== 'connecting' && current.status !== 'connected') return
-    try { options.engine.applyUpdate(update, 'remote') } catch (error) {
-      options.transport.disconnect()
-      publish({ status: 'error', lease: null, error: safeCollaborationError(error) })
-    }
-  })
-  const removeTransportStatusListener = options.transport.onStatus(status => {
-    if (disposed || current.status === 'disposed' || current.status === 'error') return
-    if (status === 'connected') publish({ status: 'connected', error: null })
-    else if (status === 'connecting') publish({ status: 'connecting' })
-    else publish({ status: 'disconnected', lease: null })
-  })
-
-  return {
-    get state() { return current },
-    connect,
-    async reconnect() { disconnect(); await connect() },
-    disconnect,
-    onState(listener) {
-      if (disposed) throw new Error('COLLABORATION_RUNTIME_DISPOSED')
-      listeners.add(listener)
-      return () => { listeners.delete(listener) }
-    },
-    encodeSnapshot: () => options.engine.encodeSnapshot(),
-    encodeStateVector: () => options.engine.encodeStateVector(),
-    dispose() {
-      if (disposed) return
-      generation += 1
-      controller?.abort()
-      controller = null
-      removeEngineListener()
-      removeTransportUpdateListener()
-      removeTransportStatusListener()
-      options.transport.dispose()
-      options.engine.dispose()
-      disposed = true
-      current = { ...current, status: 'disposed', lease: null, error: null }
-      for (const listener of listeners) listener(current)
-      listeners.clear()
-    },
-  }
-}

package/collaboration/src/transport.ts

@@ -1,142 +0,0 @@
-import * as Y from 'yjs'
-import { WebsocketProvider } from 'y-websocket'
-import type { CollaborationTransport, CollaborationTransportAdmission, CollaborationTransportStatus } from './contracts'
-
-interface ProviderStatusEvent { readonly status: CollaborationTransportStatus }
-interface CollaborationWebsocketProvider {
-  connect: () => void
-  disconnect: () => void
-  destroy: () => void
-  on: (event: 'status', listener: (event: ProviderStatusEvent) => void) => void
-  off: (event: 'status', listener: (event: ProviderStatusEvent) => void) => void
-}
-
-export interface CollaborationWebsocketProviderOptions {
-  readonly connect: false
-  readonly disableBc: true
-}
-
-export type CollaborationWebsocketProviderFactory = (
-  websocketUrl: string,
-  roomName: string,
-  document: Y.Doc,
-  options: CollaborationWebsocketProviderOptions,
-) => CollaborationWebsocketProvider
-
-export interface YWebsocketCollaborationTransportOptions {
-  readonly hostOrigin?: string
-  readonly providerFactory?: CollaborationWebsocketProviderFactory
-}
-
-const providerFactory: CollaborationWebsocketProviderFactory = (websocketUrl, roomName, document, options) => new WebsocketProvider(
-  websocketUrl,
-  roomName,
-  document,
-  options,
-)
-
-const loopback = (hostname: string): boolean => hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]'
-
-const validateAdmission = (admission: CollaborationTransportAdmission, hostOrigin: string): URL => {
-  let websocket: URL
-  let host: URL
-  try {
-    websocket = new URL(admission.websocketUrl)
-    host = new URL(hostOrigin)
-  } catch {
-    throw new Error('COLLABORATION_TRANSPORT_INVALID')
-  }
-  const expectedProtocol = host.protocol === 'https:' ? 'wss:' : host.protocol === 'http:' ? 'ws:' : ''
-  if ((websocket.protocol !== 'wss:' && websocket.protocol !== 'ws:') || websocket.protocol !== expectedProtocol
-    || websocket.hostname !== host.hostname || websocket.port !== host.port || websocket.username !== '' || websocket.password !== ''
-    || websocket.search !== '' || websocket.hash !== '' || (websocket.protocol === 'ws:' && !loopback(websocket.hostname))
-    || !/^[a-z0-9][a-z0-9._-]{0,127}$/.test(admission.roomName)) {
-    throw new Error('COLLABORATION_TRANSPORT_INVALID')
-  }
-  return websocket
-}
-
-export const createYWebsocketCollaborationTransport = (options: YWebsocketCollaborationTransportOptions = {}): CollaborationTransport => {
-  const statusListeners = new Set<(status: CollaborationTransportStatus) => void>()
-  const updateListeners = new Set<(update: Uint8Array) => void>()
-  const createProvider = options.providerFactory ?? providerFactory
-  let provider: CollaborationWebsocketProvider | null = null
-  let document: Y.Doc | null = null
-  let statusHandler: ((event: ProviderStatusEvent) => void) | null = null
-  let updateHandler: ((update: Uint8Array, origin: unknown) => void) | null = null
-  let disposed = false
-
-  const notifyStatus = (status: CollaborationTransportStatus): void => {
-    for (const listener of statusListeners) listener(status)
-  }
-  const release = (): void => {
-    if (provider !== null && statusHandler !== null) provider.off('status', statusHandler)
-    if (document !== null && updateHandler !== null) document.off('update', updateHandler)
-    provider?.disconnect()
-    provider?.destroy()
-    document?.destroy()
-    provider = null
-    document = null
-    statusHandler = null
-    updateHandler = null
-  }
-
-  return {
-    connect(admission, initialSnapshot) {
-      if (disposed) throw new Error('COLLABORATION_TRANSPORT_DISPOSED')
-      if (initialSnapshot.byteLength < 1 || initialSnapshot.byteLength > 8_388_608) throw new Error('COLLABORATION_TRANSPORT_INVALID')
-      const origin = options.hostOrigin ?? globalThis.location?.origin
-      if (origin === undefined) throw new Error('COLLABORATION_TRANSPORT_ORIGIN_REQUIRED')
-      const websocket = validateAdmission(admission, origin)
-      release()
-      const syncDocument = new Y.Doc()
-      Y.applyUpdate(syncDocument, initialSnapshot)
-      const nextProvider = createProvider(websocket.toString(), admission.roomName, syncDocument, { connect: false, disableBc: true })
-      const nextStatusHandler = (event: ProviderStatusEvent): void => {
-        if (provider !== nextProvider || !['connecting', 'connected', 'disconnected'].includes(event.status)) return
-        if (event.status === 'disconnected') nextProvider.disconnect()
-        notifyStatus(event.status)
-      }
-      const nextUpdateHandler = (update: Uint8Array, updateOrigin: unknown): void => {
-        if (provider !== nextProvider || updateOrigin !== nextProvider) return
-        for (const listener of updateListeners) listener(update.slice())
-      }
-      provider = nextProvider
-      document = syncDocument
-      statusHandler = nextStatusHandler
-      updateHandler = nextUpdateHandler
-      syncDocument.on('update', nextUpdateHandler)
-      nextProvider.on('status', nextStatusHandler)
-      notifyStatus('connecting')
-      nextProvider.connect()
-    },
-    disconnect() {
-      if (disposed) return
-      release()
-      notifyStatus('disconnected')
-    },
-    sendUpdate(update) {
-      if (disposed) throw new Error('COLLABORATION_TRANSPORT_DISPOSED')
-      if (document === null) throw new Error('COLLABORATION_TRANSPORT_DISCONNECTED')
-      if (update.byteLength < 1 || update.byteLength > 262_144) throw new Error('COLLABORATION_TRANSPORT_UPDATE_INVALID')
-      Y.applyUpdate(document, update)
-    },
-    onStatus(listener) {
-      if (disposed) throw new Error('COLLABORATION_TRANSPORT_DISPOSED')
-      statusListeners.add(listener)
-      return () => { statusListeners.delete(listener) }
-    },
-    onUpdate(listener) {
-      if (disposed) throw new Error('COLLABORATION_TRANSPORT_DISPOSED')
-      updateListeners.add(listener)
-      return () => { updateListeners.delete(listener) }
-    },
-    dispose() {
-      if (disposed) return
-      release()
-      disposed = true
-      statusListeners.clear()
-      updateListeners.clear()
-    },
-  }
-}