@ystemsrx/cfshare 0.1.0

package/src/policy.ts

@@ -0,0 +1,175 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import ignore from "ignore";
+import type { CfsharePluginConfig, CfsharePolicy } from "./types.js";
+
+export const DEFAULT_POLICY: CfsharePolicy = {
+  defaultTtlSeconds: 3600,
+  maxTtlSeconds: 86400,
+  defaultExposePortAccess: "token",
+  defaultExposeFilesAccess: "none",
+  blockedPorts: [22, 2375, 2376],
+  allowedPathRoots: [],
+  tunnel: {
+    edgeIpVersion: "4",
+    protocol: "http2",
+  },
+  rateLimit: {
+    enabled: true,
+    windowMs: 60_000,
+    maxRequests: 240,
+  },
+};
+
+export type LoadedPolicy = {
+  effective: CfsharePolicy;
+  warnings: string[];
+  matcher: ReturnType<typeof ignore>;
+};
+
+function isAccessMode(value: unknown): value is CfsharePolicy["defaultExposePortAccess"] {
+  return value === "token" || value === "basic" || value === "none";
+}
+
+function normalizeAccess(
+  value: unknown,
+  fallback: CfsharePolicy["defaultExposePortAccess"],
+): CfsharePolicy["defaultExposePortAccess"] {
+  return isAccessMode(value) ? value : fallback;
+}
+
+function asPortArray(input: unknown): number[] | undefined {
+  if (!Array.isArray(input)) {
+    return undefined;
+  }
+  const ports = input
+    .map((value) => (typeof value === "number" ? Math.trunc(value) : Number.NaN))
+    .filter((value) => Number.isInteger(value) && value > 0 && value <= 65535);
+  return Array.from(new Set(ports));
+}
+
+function asStringArray(input: unknown): string[] | undefined {
+  if (!Array.isArray(input)) {
+    return undefined;
+  }
+  return input
+    .filter((entry): entry is string => typeof entry === "string")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+export function mergePolicy(
+  defaults: CfsharePolicy,
+  pluginConfig: CfsharePluginConfig,
+  fileConfig: Record<string, unknown>,
+): CfsharePolicy {
+  const fileTunnel = (fileConfig.tunnel as Record<string, unknown> | undefined) ?? {};
+  const fileRateLimit = (fileConfig.rateLimit as Record<string, unknown> | undefined) ?? {};
+
+  const merged: CfsharePolicy = {
+    defaultTtlSeconds:
+      typeof fileConfig.defaultTtlSeconds === "number"
+        ? fileConfig.defaultTtlSeconds
+        : pluginConfig.defaultTtlSeconds ?? defaults.defaultTtlSeconds,
+    maxTtlSeconds:
+      typeof fileConfig.maxTtlSeconds === "number"
+        ? fileConfig.maxTtlSeconds
+        : pluginConfig.maxTtlSeconds ?? defaults.maxTtlSeconds,
+    defaultExposePortAccess: normalizeAccess(
+      fileConfig.defaultExposePortAccess,
+      normalizeAccess(pluginConfig.defaultExposePortAccess, defaults.defaultExposePortAccess),
+    ),
+    defaultExposeFilesAccess: normalizeAccess(
+      fileConfig.defaultExposeFilesAccess,
+      normalizeAccess(pluginConfig.defaultExposeFilesAccess, defaults.defaultExposeFilesAccess),
+    ),
+    blockedPorts:
+      asPortArray(fileConfig.blockedPorts) ??
+      asPortArray(pluginConfig.blockedPorts) ??
+      defaults.blockedPorts,
+    allowedPathRoots:
+      asStringArray(fileConfig.allowedPathRoots) ??
+      asStringArray(pluginConfig.allowedPathRoots) ??
+      defaults.allowedPathRoots,
+    tunnel: {
+      ...defaults.tunnel,
+      ...(pluginConfig.tunnel ?? {}),
+      ...(fileTunnel as Partial<CfsharePolicy["tunnel"]>),
+    },
+    rateLimit: {
+      ...defaults.rateLimit,
+      ...(pluginConfig.rateLimit ?? {}),
+      ...(fileRateLimit as Partial<CfsharePolicy["rateLimit"]>),
+    },
+  };
+
+  merged.defaultTtlSeconds = Math.max(60, Math.trunc(merged.defaultTtlSeconds));
+  merged.maxTtlSeconds = Math.max(merged.defaultTtlSeconds, Math.trunc(merged.maxTtlSeconds));
+
+  const edge = merged.tunnel.edgeIpVersion;
+  if (edge !== "4" && edge !== "6" && edge !== "auto") {
+    merged.tunnel.edgeIpVersion = defaults.tunnel.edgeIpVersion;
+  }
+  const protocol = merged.tunnel.protocol;
+  if (protocol !== "http2" && protocol !== "quic" && protocol !== "auto") {
+    merged.tunnel.protocol = defaults.tunnel.protocol;
+  }
+
+  merged.rateLimit.enabled = merged.rateLimit.enabled !== false;
+  merged.rateLimit.windowMs = Math.min(3_600_000, Math.max(1000, Math.trunc(merged.rateLimit.windowMs)));
+  merged.rateLimit.maxRequests = Math.min(
+    100_000,
+    Math.max(1, Math.trunc(merged.rateLimit.maxRequests)),
+  );
+
+  return merged;
+}
+
+export async function loadPolicy(params: {
+  policyFile: string;
+  ignoreFile: string;
+  pluginConfig: CfsharePluginConfig;
+}): Promise<LoadedPolicy> {
+  const warnings: string[] = [];
+  let fileConfig: Record<string, unknown> = {};
+
+  try {
+    const raw = await fs.readFile(params.policyFile, "utf8");
+    const parsed = JSON.parse(raw) as unknown;
+    if (parsed && typeof parsed === "object") {
+      fileConfig = parsed as Record<string, unknown>;
+    } else {
+      warnings.push(`policy file is not an object: ${params.policyFile}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") {
+      warnings.push(`failed to read policy file (${params.policyFile}): ${message}`);
+    }
+  }
+
+  const effective = mergePolicy(DEFAULT_POLICY, params.pluginConfig, fileConfig);
+
+  const matcher = ignore();
+  matcher.add([".git/**", ".openclaw/**"]);
+
+  try {
+    const ignoreText = await fs.readFile(params.ignoreFile, "utf8");
+    matcher.add(ignoreText.split(/\r?\n/));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") {
+      const message = error instanceof Error ? error.message : String(error);
+      warnings.push(`failed to read ignore file (${params.ignoreFile}): ${message}`);
+    }
+  }
+
+  const cwdIgnore = path.join(process.cwd(), ".gitignore");
+  try {
+    const ignoreText = await fs.readFile(cwdIgnore, "utf8");
+    matcher.add(ignoreText.split(/\r?\n/));
+  } catch {
+    // ignore missing cwd .gitignore
+  }
+
+  return { effective, warnings, matcher };
+}

package/src/schemas.ts

@@ -0,0 +1,255 @@
+import { Type } from "@sinclair/typebox";
+import { stringEnum } from "openclaw/plugin-sdk";
+
+const AccessMode = stringEnum(["token", "basic", "none"] as const, {
+  description: "Access mode",
+});
+
+const FileMode = stringEnum(["normal", "zip"] as const, {
+  description: "File exposure mode",
+});
+
+const FilePresentationMode = stringEnum(["download", "preview", "raw"] as const, {
+  description: "How files should be served to clients",
+});
+
+const ComponentMode = stringEnum(["tunnel", "origin", "all"] as const, {
+  description: "Log component",
+});
+
+const ExposureType = stringEnum(["port", "files"] as const, {
+  description: "Exposure type",
+});
+
+const ExposureStatus = stringEnum(["starting", "running", "stopped", "error", "expired"] as const, {
+  description: "Exposure status",
+});
+
+const ExposureGetField = stringEnum(
+  [
+    "id",
+    "type",
+    "status",
+    "port",
+    "public_url",
+    "expires_at",
+    "local_url",
+    "stats",
+    "file_sharing",
+    "last_error",
+    "manifest",
+    "created_at",
+  ] as const,
+  {
+    description: "Fields to return",
+  },
+);
+
+const MaintenanceAction = stringEnum(["start_guard", "run_gc", "set_policy"] as const, {
+  description: "Maintenance action",
+});
+
+const PortOptsSchema = Type.Object(
+  {
+    ttl_seconds: Type.Optional(Type.Number({ minimum: 60, maximum: 604800 })),
+    access: Type.Optional(AccessMode),
+    protect_origin: Type.Optional(Type.Boolean()),
+    allowlist_paths: Type.Optional(Type.Array(Type.String(), { minItems: 1, maxItems: 128 })),
+  },
+  { additionalProperties: false },
+);
+
+const FilesOptsSchema = Type.Object(
+  {
+    mode: Type.Optional(FileMode),
+    presentation: Type.Optional(FilePresentationMode),
+    ttl_seconds: Type.Optional(Type.Number({ minimum: 60, maximum: 604800 })),
+    access: Type.Optional(AccessMode),
+    max_downloads: Type.Optional(Type.Number({ minimum: 1, maximum: 1_000_000 })),
+  },
+  { additionalProperties: false },
+);
+
+export const EnvCheckSchema = Type.Object({}, { additionalProperties: false });
+
+export const ExposePortSchema = Type.Object(
+  {
+    port: Type.Number({ minimum: 1, maximum: 65535 }),
+    opts: Type.Optional(PortOptsSchema),
+  },
+  { additionalProperties: false },
+);
+
+export const ExposeFilesSchema = Type.Object(
+  {
+    paths: Type.Array(Type.String(), { minItems: 1, maxItems: 256 }),
+    opts: Type.Optional(FilesOptsSchema),
+  },
+  { additionalProperties: false },
+);
+
+export const ExposureListSchema = Type.Object({}, { additionalProperties: false });
+
+const ExposureGetOptsSchema = Type.Object(
+  {
+    probe_public: Type.Optional(Type.Boolean()),
+  },
+  { additionalProperties: false },
+);
+
+const ExposureGetFieldsSchema = Type.Array(ExposureGetField, {
+  minItems: 1,
+  maxItems: 32,
+  uniqueItems: true,
+});
+
+const ExposureGetFilterSchema = Type.Object(
+  {
+    status: Type.Optional(ExposureStatus),
+    type: Type.Optional(ExposureType),
+  },
+  { additionalProperties: false },
+);
+
+export const ExposureGetSchema = Type.Union(
+  [
+    Type.Object(
+      {
+        id: Type.String({ minLength: 1 }),
+        fields: Type.Optional(ExposureGetFieldsSchema),
+        opts: Type.Optional(ExposureGetOptsSchema),
+      },
+      { additionalProperties: false },
+    ),
+    Type.Object(
+      {
+        ids: Type.Array(Type.String({ minLength: 1 }), { minItems: 1, maxItems: 4096 }),
+        fields: Type.Optional(ExposureGetFieldsSchema),
+        opts: Type.Optional(ExposureGetOptsSchema),
+      },
+      { additionalProperties: false },
+    ),
+    Type.Object(
+      {
+        filter: ExposureGetFilterSchema,
+        fields: Type.Optional(ExposureGetFieldsSchema),
+        opts: Type.Optional(ExposureGetOptsSchema),
+      },
+      { additionalProperties: false },
+    ),
+  ],
+  { description: "Get one/many exposures, or query by filter" },
+);
+
+const ExposureStopOptsSchema = Type.Object(
+  {
+    reason: Type.Optional(Type.String()),
+  },
+  { additionalProperties: false },
+);
+
+export const ExposureStopSchema = Type.Union(
+  [
+    Type.Object(
+      {
+        id: Type.String({
+          minLength: 1,
+          description: `Exposure id or "all"`,
+        }),
+        opts: Type.Optional(ExposureStopOptsSchema),
+      },
+      { additionalProperties: false },
+    ),
+    Type.Object(
+      {
+        ids: Type.Array(Type.String({ minLength: 1 }), { minItems: 1, maxItems: 4096 }),
+        opts: Type.Optional(ExposureStopOptsSchema),
+      },
+      { additionalProperties: false },
+    ),
+  ],
+  { description: "Stop one/many exposures, or all" },
+);
+
+const ExposureLogsOptsSchema = Type.Object(
+  {
+    lines: Type.Optional(Type.Number({ minimum: 1, maximum: 10_000 })),
+    since_seconds: Type.Optional(Type.Number({ minimum: 1, maximum: 365 * 24 * 3600 })),
+    component: Type.Optional(ComponentMode),
+  },
+  { additionalProperties: false },
+);
+
+export const ExposureLogsSchema = Type.Union(
+  [
+    Type.Object(
+      {
+        id: Type.String({ minLength: 1 }),
+        opts: Type.Optional(ExposureLogsOptsSchema),
+      },
+      { additionalProperties: false },
+    ),
+    Type.Object(
+      {
+        ids: Type.Array(Type.String({ minLength: 1 }), { minItems: 1, maxItems: 4096 }),
+        opts: Type.Optional(ExposureLogsOptsSchema),
+      },
+      { additionalProperties: false },
+    ),
+  ],
+  { description: "Read logs for one/many exposures" },
+);
+
+export const MaintenanceSchema = Type.Object(
+  {
+    action: MaintenanceAction,
+    opts: Type.Optional(
+      Type.Object(
+        {
+          policy: Type.Optional(Type.Any({ description: "Policy patch object" })),
+          ignore_patterns: Type.Optional(Type.Array(Type.String(), { minItems: 1, maxItems: 4096 })),
+        },
+        { additionalProperties: false },
+      ),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+export const AuditQuerySchema = Type.Object(
+  {
+    filters: Type.Optional(
+      Type.Object(
+        {
+          id: Type.Optional(Type.String()),
+          event: Type.Optional(Type.String()),
+          type: Type.Optional(ExposureType),
+          from_ts: Type.Optional(Type.String({ description: "ISO timestamp" })),
+          to_ts: Type.Optional(Type.String({ description: "ISO timestamp" })),
+          limit: Type.Optional(Type.Number({ minimum: 1, maximum: 10000 })),
+        },
+        { additionalProperties: false },
+      ),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+export const AuditExportSchema = Type.Object(
+  {
+    range: Type.Optional(
+      Type.Object(
+        {
+          from_ts: Type.Optional(Type.String({ description: "ISO timestamp" })),
+          to_ts: Type.Optional(Type.String({ description: "ISO timestamp" })),
+          id: Type.Optional(Type.String()),
+          event: Type.Optional(Type.String()),
+          type: Type.Optional(ExposureType),
+          output_path: Type.Optional(Type.String()),
+        },
+        { additionalProperties: false },
+      ),
+    ),
+  },
+  { additionalProperties: false },
+);