@2en/clawly-plugins 0.1.0

package/README.md

@@ -0,0 +1,3 @@
+# @2en/clawly-plugins
+
+OpenClaw plugin providing Clawly utility RPC methods (`clawly.*`).

package/file.ts

@@ -0,0 +1,161 @@
+/**
+ * clawly.file.get — read a file from the local filesystem and return it as base64.
+ *
+ * Validates: absolute path, no traversal, MIME whitelist, 50 MB size limit.
+ */
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import {fileTypeFromBuffer} from 'file-type'
+
+import type {PluginApi} from './index'
+
+const MAX_FILE_SIZE = 50 * 1024 * 1024 // 50 MB
+
+const ALLOWED_MIME_PREFIXES = ['image/', 'video/', 'audio/']
+
+/** Extensions allowed via fallback when file-type cannot detect MIME (e.g. plain text). */
+const DOCUMENT_EXT_WHITELIST = new Set([
+  'pdf',
+  'doc',
+  'docx',
+  'xls',
+  'xlsx',
+  'ppt',
+  'pptx',
+  'txt',
+  'csv',
+  'rtf',
+])
+
+const EXT_TO_MIME: Record<string, string> = {
+  pdf: 'application/pdf',
+  doc: 'application/msword',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xls: 'application/vnd.ms-excel',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  ppt: 'application/vnd.ms-powerpoint',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  txt: 'text/plain',
+  csv: 'text/csv',
+  rtf: 'application/rtf',
+}
+
+function getExtension(filePath: string): string {
+  const dot = filePath.lastIndexOf('.')
+  return dot === -1 ? '' : filePath.slice(dot + 1).toLowerCase()
+}
+
+function getFilename(filePath: string): string {
+  return path.basename(filePath)
+}
+
+export function registerFileMethods(api: PluginApi) {
+  api.registerGatewayMethod('clawly.file.get', async ({params, respond}) => {
+    const rawPath = typeof params.path === 'string' ? params.path.trim() : ''
+
+    // ── Validate path ──────────────────────────────────────────────
+    if (!rawPath) {
+      respond(false, undefined, {code: 'invalid_params', message: 'path is required'})
+      return
+    }
+
+    if (!path.isAbsolute(rawPath)) {
+      respond(false, undefined, {code: 'invalid_params', message: 'path must be absolute'})
+      return
+    }
+
+    const normalized = path.normalize(rawPath)
+
+    // Resolve symlinks and verify the real path matches the normalized expectation
+    let realPath: string
+    try {
+      realPath = await fs.realpath(normalized)
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code
+      if (code === 'ENOENT') {
+        respond(false, undefined, {code: 'not_found', message: 'file not found'})
+        return
+      }
+      api.logger.error(
+        `clawly.file.get realpath failed: ${err instanceof Error ? err.message : String(err)}`,
+      )
+      respond(false, undefined, {code: 'error', message: 'failed to resolve path'})
+      return
+    }
+
+    // ── Size check ─────────────────────────────────────────────────
+    let stat: Awaited<ReturnType<typeof fs.stat>>
+    try {
+      stat = await fs.stat(realPath)
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code
+      if (code === 'ENOENT') {
+        respond(false, undefined, {code: 'not_found', message: 'file not found'})
+        return
+      }
+      api.logger.error(
+        `clawly.file.get stat failed: ${err instanceof Error ? err.message : String(err)}`,
+      )
+      respond(false, undefined, {code: 'error', message: 'failed to stat file'})
+      return
+    }
+
+    if (!stat.isFile()) {
+      respond(false, undefined, {code: 'invalid_params', message: 'path is not a regular file'})
+      return
+    }
+
+    if (stat.size > MAX_FILE_SIZE) {
+      respond(false, undefined, {
+        code: 'file_too_large',
+        message: `file exceeds ${MAX_FILE_SIZE / 1024 / 1024} MB limit`,
+      })
+      return
+    }
+
+    // ── Read file ──────────────────────────────────────────────────
+    let buffer: Buffer
+    try {
+      buffer = await fs.readFile(realPath)
+    } catch (err) {
+      api.logger.error(
+        `clawly.file.get readFile failed: ${err instanceof Error ? err.message : String(err)}`,
+      )
+      respond(false, undefined, {code: 'error', message: 'failed to read file'})
+      return
+    }
+
+    // ── MIME detection ─────────────────────────────────────────────
+    let mimeType: string | undefined
+
+    const detected = await fileTypeFromBuffer(buffer)
+    if (detected) {
+      mimeType = detected.mime
+    }
+
+    // Check against allowed MIME prefixes
+    if (mimeType && ALLOWED_MIME_PREFIXES.some((prefix) => mimeType!.startsWith(prefix))) {
+      // Allowed media type
+    } else {
+      // Fallback: check document extension whitelist
+      const ext = getExtension(realPath)
+      if (DOCUMENT_EXT_WHITELIST.has(ext)) {
+        mimeType = EXT_TO_MIME[ext] ?? 'application/octet-stream'
+      } else {
+        respond(false, undefined, {
+          code: 'unsupported_type',
+          message: `file type not allowed: ${mimeType ?? `unknown (ext: .${ext || '?'})`}`,
+        })
+        return
+      }
+    }
+
+    // ── Respond ────────────────────────────────────────────────────
+    const base64 = buffer.toString('base64')
+    const filename = getFilename(realPath)
+
+    api.logger.info(`clawly.file.get: served ${filename} (${mimeType}, ${buffer.length} bytes)`)
+    respond(true, {base64, mimeType, filename})
+  })
+}

package/index.ts

@@ -0,0 +1,43 @@
+/**
+ * OpenClaw plugin: Clawly utility RPC methods (clawly.*).
+ *
+ * Gateway methods:
+ * - clawly.file.get — read a local file and return base64-encoded content
+ */
+
+import {registerFileMethods} from './file'
+
+type PluginRuntime = {
+  state?: {
+    resolveStateDir?: (env?: NodeJS.ProcessEnv) => string
+  }
+}
+
+export type PluginApi = {
+  id: string
+  name: string
+  pluginConfig?: Record<string, unknown>
+  logger: {
+    info: (msg: string) => void
+    warn: (msg: string) => void
+    error: (msg: string) => void
+  }
+  runtime: PluginRuntime
+  registerGatewayMethod: (
+    method: string,
+    handler: (opts: {
+      params: Record<string, unknown>
+      respond: (ok: boolean, payload?: unknown, error?: {code?: string; message?: string}) => void
+    }) => Promise<void> | void,
+  ) => void
+}
+
+export default {
+  id: 'clawly-plugins',
+  name: 'Clawly Plugins',
+  description: 'Clawly utility RPC methods (clawly.*).',
+  register(api: PluginApi) {
+    registerFileMethods(api)
+    api.logger.info(`Loaded ${api.id} plugin.`)
+  },
+}

package/openclaw.plugin.json

@@ -0,0 +1,12 @@
+{
+  "id": "clawly-plugins",
+  "name": "Clawly Plugins",
+  "description": "Clawly utility RPC methods (clawly.*): file access.",
+  "version": "0.1.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {},
+    "required": []
+  }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@2en/clawly-plugins",
+  "version": "0.1.0",
+  "module": "index.ts",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/2enai/clawly",
+    "directory": "plugins/clawly-plugins"
+  },
+  "files": [
+    "index.ts",
+    "file.ts",
+    "openclaw.plugin.json"
+  ],
+  "dependencies": {
+    "file-type": "^19.6.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}