lumiverse-spindle-types 0.4.76 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.4.76",
+  "version": "0.5.0",
   "types": "./src/index.ts",
   "keywords": [
     "lumiverse",

package/src/capabilities.ts

@@ -0,0 +1,41 @@
+/**
+ * Declared backend capabilities that opt an extension out of specific
+ * Spindle heuristic-scanner blocks. Unlike permissions (runtime gates),
+ * capabilities are install-time declarations that survive scanner checks.
+ *
+ * Only patterns with a meaningful false-positive rate get a capability —
+ * truly dangerous modules (fs, child_process, raw sockets, sqlite, workers)
+ * remain hard-blocked with no opt-in.
+ */
+export type SpindleCapability =
+  /**
+   * Bypass the `dynamic code execution` heuristic: `eval(...)`,
+   * `Function(...)` / `new Function(...)`. Required for extensions that:
+   *   - embed Zod / Handlebars / similar libs that probe `new Function("")`
+   *     to feature-detect Cloudflare-Workers-style environments;
+   *   - ship a regex literal whose source contains `Function\s*\(` (e.g.
+   *     a security check that itself bans the Function constructor);
+   *   - intentionally execute user-supplied code in a sandboxed runtime
+   *     (lumiscript's AsyncFunction sandbox is the canonical example).
+   *
+   * Extensions declaring this still cannot reach fs / child_process / net /
+   * etc. — those remain blocked by independent heuristics.
+   */
+  | "dynamic_code_execution"
+  /**
+   * Bypass the `base64 decoding` heuristic: `Buffer.from(s, "base64")`.
+   * The pattern is commonly used to smuggle code past static scanners
+   * (decode + eval the payload), but it has plenty of legitimate uses
+   * (image bytes, binary asset I/O). Pair with `dynamic_code_execution`
+   * only when the extension actually needs both.
+   */
+  | "base64_decode";
+
+export const ALL_CAPABILITIES: readonly SpindleCapability[] = [
+  "dynamic_code_execution",
+  "base64_decode",
+] as const;
+
+export function isValidCapability(c: string): c is SpindleCapability {
+  return (ALL_CAPABILITIES as readonly string[]).includes(c);
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 export type {
   SpindleManifest,
   SpindlePermission,
+  SpindleCapability,
 } from "./manifest";
 export {
   IDENTIFIER_PATTERN,
@@ -10,6 +11,9 @@ export {
 export type { SpindlePermission as SpindlePermissionType } from "./permissions";
 export { ALL_PERMISSIONS, isValidPermission } from "./permissions";
 
+export type { SpindleCapability as SpindleCapabilityType } from "./capabilities";
+export { ALL_CAPABILITIES, isValidCapability } from "./capabilities";
+
 export { SpindleEvent, CoreEventType } from "./events";
 
 export type {

package/src/manifest.ts

@@ -15,6 +15,14 @@ export interface SpindleManifest {
   description?: string;
   /** Requested permissions (gated capabilities) */
   permissions: SpindlePermission[];
+  /**
+   * Declared backend capabilities that opt this extension out of specific
+   * Spindle heuristic-scanner blocks. See `SpindleCapability` for the
+   * available values. Distinct from `permissions`: permissions gate runtime
+   * API surfaces; capabilities suppress install-time scanner false positives
+   * for patterns the extension legitimately needs.
+   */
+  requested_capabilities?: SpindleCapability[];
   /** Backend entry point (default: "dist/backend.js") */
   entry_backend?: string;
   /** Frontend entry point (default: "dist/frontend.js") */
@@ -44,6 +52,7 @@ export interface SpindleStorageSeedFile {
 }
 
 export type SpindlePermission = import("./permissions").SpindlePermission;
+export type SpindleCapability = import("./capabilities").SpindleCapability;
 
 /** Regex for validating extension identifiers */
 export const IDENTIFIER_PATTERN = /^[a-z][a-z0-9_]*$/;