@muninmd/munin-sdk 0.0.0-stage → 1.1.0

package/plugin-package.d.ts

@@ -0,0 +1,121 @@
+/**
+ * What a plugin package is, and the one rule for accepting it.
+ *
+ * A package is a single JSON file (`.mnp`): a manifest and the plugin's text
+ * files. One file because it has to mean the same thing on the desktop and in
+ * the Android WebView, where there is no `fs` and no unzip — and because a
+ * single file is installed whole or not at all, never half-unpacked.
+ *
+ * This module is the only place that decides whether a package is well formed.
+ * The app runs it when it installs, and the registry service runs a copy of it
+ * when an author publishes, so a package one side would refuse never reaches
+ * the other. The copy is checked against the same fixtures
+ * (`__tests__/fixtures/plugin-package-cases.json`) on both sides.
+ *
+ * Pure but for {@link sha256Hex}, which uses Web Crypto — present in the
+ * Electron renderer, the Android WebView and Node alike.
+ */
+/** What a plugin may ask to do. Disclosure to the person, not a sandbox. */
+export type Permission = 'vault:read' | 'vault:write' | 'network'
+export declare const PERMISSIONS: readonly Permission[]
+export type PluginPlatform = 'desktop' | 'android'
+export declare const PLATFORMS: readonly PluginPlatform[]
+/** The plugin API versions this app can hand a context for. */
+export declare const SUPPORTED_API_VERSIONS: readonly number[]
+/** A package over this size is refused before it is looked at. */
+export declare const MAX_PACKAGE_BYTES: number
+export interface PluginManifest {
+  /** `<author>.<name>`, the same for every version of the plugin. */
+  id: string
+  name: string
+  /** `major.minor.patch`. */
+  version: string
+  description: string
+  /** The author's handle: the part of `id` before the dot. */
+  author: string
+  /** The file in the package that holds the plugin's code. */
+  entry: string
+  apiVersion: number
+  /** The oldest app version the plugin runs on. */
+  minAppVersion: string
+  platforms: PluginPlatform[]
+  permissions: Permission[]
+  tags: string[]
+  /** False when the plugin cannot take everything it did back out of the app on
+   *  disable (listeners on `window`, patched prototypes). The person is told a
+   *  restart finishes the job. Defaults to true. */
+  unloadSafe: boolean
+  /** Plugins this one needs, by id, with the oldest version of each it works
+   *  with. They are switched on before it and off after it. Empty when none. */
+  dependencies: Record<string, string>
+}
+/** A plugin may need this many others at most. */
+export declare const MAX_DEPENDENCIES = 16
+export interface PluginPackage {
+  manifest: PluginManifest
+  /** Path inside the package → UTF-8 text. */
+  files: Record<string, string>
+}
+export type PackageErrorCode =
+  | 'package-too-large'
+  | 'package-not-json'
+  | 'manifest-missing'
+  | 'manifest-invalid'
+  | 'entry-missing'
+  | 'files-invalid'
+export interface PackageError {
+  code: PackageErrorCode
+  /** Which rule, in words an author can act on. */
+  message: string
+}
+export type ParsedPackage =
+  | {
+      ok: true
+      pkg: PluginPackage
+    }
+  | {
+      ok: false
+      error: PackageError
+    }
+/** An author handle: what registers with the registry and prefixes every id. */
+export declare function isAuthorHandle(text: string): boolean
+/** `a` is strictly above `b`, part by part as numbers (0.10.0 is above 0.9.0).
+ *  Both are `major.minor.patch`; anything else is not above anything. */
+export declare function versionAbove(a: string, b: string): boolean
+/** The id's two halves, or null when it is not `<author>.<name>`. */
+export declare function splitPluginId(id: string): {
+  author: string
+  name: string
+} | null
+/**
+ * Read the text of a package and decide whether to accept it. Total: never
+ * throws, and a package that breaks any rule is refused whole with the rule
+ * named, so an author sees what to fix and nothing is kept half-way.
+ *
+ * Unknown manifest fields are ignored rather than refused, so a newer author
+ * toolchain does not break packages for an older app.
+ */
+export declare function parsePackage(text: string): ParsedPackage
+export type Incompatibility = 'platform' | 'app-version' | 'api-version'
+export interface Host {
+  platform: PluginPlatform
+  appVersion: string
+  apiVersions?: readonly number[]
+}
+/**
+ * Why a plugin cannot run here, or null when it can. Checked on the way in (so
+ * an incompatible plugin is not installed from the catalog) and again at enable
+ * time (the app may have been downgraded, or the package sideloaded).
+ */
+export declare function incompatibility(
+  manifest: PluginManifest,
+  host: Host
+): Incompatibility | null
+/** Lower-case hex SHA-256 of a string's UTF-8 bytes. */
+export declare function sha256Hex(text: string): Promise<string>
+/**
+ * The checksum remembered at install time and compared before every load. It
+ * covers the whole package text as the registry served it, so any edit to any
+ * file — or to the manifest — changes it.
+ */
+export declare function packageDigest(packageText: string): Promise<string>

package/plugin-package.js

@@ -0,0 +1,214 @@
+/**
+ * What a plugin package is, and the one rule for accepting it.
+ *
+ * A package is a single JSON file (`.mnp`): a manifest and the plugin's text
+ * files. One file because it has to mean the same thing on the desktop and in
+ * the Android WebView, where there is no `fs` and no unzip — and because a
+ * single file is installed whole or not at all, never half-unpacked.
+ *
+ * This module is the only place that decides whether a package is well formed.
+ * The app runs it when it installs, and the registry service runs a copy of it
+ * when an author publishes, so a package one side would refuse never reaches
+ * the other. The copy is checked against the same fixtures
+ * (`__tests__/fixtures/plugin-package-cases.json`) on both sides.
+ *
+ * Pure but for {@link sha256Hex}, which uses Web Crypto — present in the
+ * Electron renderer, the Android WebView and Node alike.
+ */
+export const PERMISSIONS = ['vault:read', 'vault:write', 'network']
+export const PLATFORMS = ['desktop', 'android']
+/** The plugin API versions this app can hand a context for. */
+export const SUPPORTED_API_VERSIONS = [1]
+/** A package over this size is refused before it is looked at. */
+export const MAX_PACKAGE_BYTES = 2 * 1024 * 1024
+/** A plugin may need this many others at most. */
+export const MAX_DEPENDENCIES = 16
+// ---- Rules ------------------------------------------------------------------
+const AUTHOR = /^[a-z0-9][a-z0-9-]{1,29}$/
+const NAME = /^[a-z0-9][a-z0-9-]{0,39}$/
+const VERSION = /^\d+\.\d+\.\d+$/
+const FILE_PATH = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,100}$/
+const TAG = /^[a-z0-9][a-z0-9-]{0,23}$/
+/** An author handle: what registers with the registry and prefixes every id. */
+export function isAuthorHandle(text) {
+  return AUTHOR.test(text)
+}
+/** `a` is strictly above `b`, part by part as numbers (0.10.0 is above 0.9.0).
+ *  Both are `major.minor.patch`; anything else is not above anything. */
+export function versionAbove(a, b) {
+  if (!VERSION.test(a) || !VERSION.test(b)) return false
+  const pa = a.split('.').map(Number)
+  const pb = b.split('.').map(Number)
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] !== pb[i]) return pa[i] > pb[i]
+  }
+  return false
+}
+/** The id's two halves, or null when it is not `<author>.<name>`. */
+export function splitPluginId(id) {
+  const dot = id.indexOf('.')
+  if (dot === -1) return null
+  const author = id.slice(0, dot)
+  const name = id.slice(dot + 1)
+  return AUTHOR.test(author) && NAME.test(name) ? { author, name } : null
+}
+function fail(code, message) {
+  return { ok: false, error: { code, message } }
+}
+function asRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : null
+}
+function textField(m, key, max) {
+  const value = m[key]
+  return typeof value === 'string' && value.trim() !== '' && value.length <= max ? value : null
+}
+function subsetOf(value, allowed) {
+  if (!Array.isArray(value)) return null
+  const out = []
+  for (const item of value) {
+    if (typeof item !== 'string' || !allowed.includes(item)) return null
+    if (!out.includes(item)) out.push(item)
+  }
+  return out
+}
+function parseManifest(raw) {
+  const m = asRecord(raw)
+  if (!m) return { problem: 'the manifest is not an object' }
+  const id = textField(m, 'id', 80)
+  const parts = id ? splitPluginId(id) : null
+  if (!id || !parts)
+    return { problem: 'id must look like "author.name" (lower case, digits, dashes)' }
+  const author = textField(m, 'author', 30)
+  if (author !== parts.author) return { problem: 'author must be the part of id before the dot' }
+  const name = textField(m, 'name', 60)
+  if (!name) return { problem: 'name is required (up to 60 characters)' }
+  const description = textField(m, 'description', 280)
+  if (!description) return { problem: 'description is required (up to 280 characters)' }
+  const version = textField(m, 'version', 20)
+  if (!version || !VERSION.test(version)) return { problem: 'version must be major.minor.patch' }
+  const minAppVersion = textField(m, 'minAppVersion', 20)
+  if (!minAppVersion || !VERSION.test(minAppVersion)) {
+    return { problem: 'minAppVersion must be major.minor.patch' }
+  }
+  const entry = textField(m, 'entry', 101)
+  if (!entry || !FILE_PATH.test(entry) || entry.includes('..')) {
+    return { problem: 'entry must be a plain file path inside the package' }
+  }
+  const apiVersion = m.apiVersion
+  if (typeof apiVersion !== 'number' || !Number.isInteger(apiVersion) || apiVersion < 1) {
+    return { problem: 'apiVersion must be a whole number from 1' }
+  }
+  const platforms = subsetOf(m.platforms, PLATFORMS)
+  if (!platforms || platforms.length === 0) {
+    return { problem: 'platforms must list "desktop" and/or "android"' }
+  }
+  const permissions = subsetOf(m.permissions ?? [], PERMISSIONS)
+  if (!permissions) return { problem: `permissions may only be: ${PERMISSIONS.join(', ')}` }
+  const rawTags = m.tags ?? []
+  if (!Array.isArray(rawTags) || rawTags.length > 8) return { problem: 'tags: up to 8' }
+  const tags = []
+  for (const tag of rawTags) {
+    if (typeof tag !== 'string' || !TAG.test(tag)) return { problem: `bad tag: ${String(tag)}` }
+    if (!tags.includes(tag)) tags.push(tag)
+  }
+  const unloadSafe = m.unloadSafe === undefined ? true : m.unloadSafe
+  if (typeof unloadSafe !== 'boolean') return { problem: 'unloadSafe must be true or false' }
+  const rawDeps = m.dependencies ?? {}
+  const depsRecord = asRecord(rawDeps)
+  if (!depsRecord) return { problem: 'dependencies must map plugin ids to versions' }
+  const depIds = Object.keys(depsRecord)
+  if (depIds.length > MAX_DEPENDENCIES) {
+    return { problem: `dependencies: up to ${MAX_DEPENDENCIES}` }
+  }
+  const dependencies = {}
+  for (const dep of depIds) {
+    if (!splitPluginId(dep)) return { problem: `dependency "${dep}" is not a plugin id` }
+    if (dep === id) return { problem: 'a plugin cannot depend on itself' }
+    const min = depsRecord[dep]
+    if (typeof min !== 'string' || !VERSION.test(min)) {
+      return { problem: `dependency "${dep}" must name a version, major.minor.patch` }
+    }
+    dependencies[dep] = min
+  }
+  return {
+    manifest: {
+      id,
+      name,
+      version,
+      description,
+      author,
+      entry,
+      apiVersion,
+      minAppVersion,
+      platforms,
+      permissions,
+      tags,
+      unloadSafe,
+      dependencies
+    }
+  }
+}
+/**
+ * Read the text of a package and decide whether to accept it. Total: never
+ * throws, and a package that breaks any rule is refused whole with the rule
+ * named, so an author sees what to fix and nothing is kept half-way.
+ *
+ * Unknown manifest fields are ignored rather than refused, so a newer author
+ * toolchain does not break packages for an older app.
+ */
+export function parsePackage(text) {
+  if (new TextEncoder().encode(text).length > MAX_PACKAGE_BYTES) {
+    return fail('package-too-large', `a package is at most ${MAX_PACKAGE_BYTES} bytes`)
+  }
+  let raw
+  try {
+    raw = JSON.parse(text)
+  } catch {
+    return fail('package-not-json', 'the package is not JSON')
+  }
+  const pkg = asRecord(raw)
+  if (!pkg || !('manifest' in pkg)) return fail('manifest-missing', 'the package has no manifest')
+  const parsed = parseManifest(pkg.manifest)
+  if ('problem' in parsed) return fail('manifest-invalid', parsed.problem)
+  const rawFiles = asRecord(pkg.files)
+  if (!rawFiles) return fail('files-invalid', 'files must be an object of path → text')
+  const files = {}
+  for (const [path, content] of Object.entries(rawFiles)) {
+    if (!FILE_PATH.test(path) || path.includes('..') || path.includes('//')) {
+      return fail('files-invalid', `bad file path: ${path}`)
+    }
+    if (typeof content !== 'string') return fail('files-invalid', `${path} is not text`)
+    files[path] = content
+  }
+  if (!(parsed.manifest.entry in files)) {
+    return fail('entry-missing', `entry "${parsed.manifest.entry}" is not among the files`)
+  }
+  return { ok: true, pkg: { manifest: parsed.manifest, files } }
+}
+/**
+ * Why a plugin cannot run here, or null when it can. Checked on the way in (so
+ * an incompatible plugin is not installed from the catalog) and again at enable
+ * time (the app may have been downgraded, or the package sideloaded).
+ */
+export function incompatibility(manifest, host) {
+  if (!manifest.platforms.includes(host.platform)) return 'platform'
+  if (versionAbove(manifest.minAppVersion, host.appVersion)) return 'app-version'
+  if (!(host.apiVersions ?? SUPPORTED_API_VERSIONS).includes(manifest.apiVersion)) {
+    return 'api-version'
+  }
+  return null
+}
+// ---- Integrity --------------------------------------------------------------
+/** Lower-case hex SHA-256 of a string's UTF-8 bytes. */
+export async function sha256Hex(text) {
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text))
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('')
+}
+/**
+ * The checksum remembered at install time and compared before every load. It
+ * covers the whole package text as the registry served it, so any edit to any
+ * file — or to the manifest — changes it.
+ */
+export function packageDigest(packageText) {
+  return sha256Hex(packageText)
+}