@fluxfiles/node 0.1.16 → 0.1.18

package/README.md

@@ -68,6 +68,28 @@ The core then accepts `POST /api/fm/import-url` for that token (SSRF-guarded,
 sharing the quota/dedup/variants pipeline). Server-wide defaults come from
 `FLUXFILES_IMPORT_*` env vars on the core service.
 
+### SFTP disk: chmod & SSH terminal
+
+When the token targets a FluxFiles server that has an **SFTP disk** configured
+(`SFTP_*` env on that server — see the
+[core README](https://github.com/thai-pc/fluxfiles#sftp-disk-vps--shared-hosting)),
+you can hand a token the SFTP file-manager tools. `chmod` is on by default for SFTP;
+the **SSH terminal** is opt-in (it grants shell access as the SSH user):
+
+```ts
+const token = createToken({
+  userId: 'admin-7',
+  perms: ['read', 'write'],
+  disks: ['sftp'],          // an SFTP disk configured on the FluxFiles server
+  allowChmod: true,         // cPanel-style permissions (default on for SFTP)
+  allowTerminal: true,      // SSH terminal — opt-in, off by default
+});
+```
+
+These are **standalone-core** features: `@fluxfiles/node` mints for a real
+FluxFiles server (Docker / standalone), which serves them — they aren't available
+behind the WordPress / Laravel-proxy adapters.
+
 ### BYOB — encrypt a user's own bucket credentials
 
 ```ts

package/dist/index.d.mts

@@ -96,17 +96,24 @@ interface BaseTokenOptions {
     /** Allow editing a file's text content (GET/PUT /api/fm/content). Default **false** — editing
      *  config/executable files (wp-config.php, .env, nginx.conf, deploy.sh) is powerful, so it's opt-in. */
     allowCodeEdit?: boolean;
-    /** Allow the paid Optimization module (POST /api/fm/optimize). Default **false** — opt-in.
-     *  Even when true, the optimize module must be installed + licensed on the server. */
+    /** Allow the SSH terminal (POST /api/fm/terminal) on an SFTP disk. Default **false** — grants shell
+     *  access as the SSH user, so it's opt-in. Core-standalone: the token must target a real core
+     *  (this SDK does), not a proxy adapter that doesn't serve /api/fm/terminal. */
+    allowTerminal?: boolean;
+    /** Optional self-hosted PTY terminal URL (ttyd / gotty / wetty, or any PTY-over-WebSocket
+     *  server the operator runs). When set (and `allowTerminal` is true), the UI embeds it for a
+     *  true interactive terminal instead of the built-in command-runner. Free; must be http(s).
+     *  Core-standalone only (like `allowTerminal`). */
+    terminalPtyUrl?: string;
+    /** Allow the Optimization feature (POST /api/fm/optimize) — recompress images to WebP +
+     *  compress PDFs. **Free/core**; default **false** because it replaces/deletes originals, so
+     *  it's an opt-in capability. */
     allowOptimize?: boolean;
-    /** Auto-optimize images on upload (recompress to WebP in the pipeline). Default false;
-     *  only effective when the optimize module is installed + licensed on the server. */
+    /** Auto-optimize images on upload (recompress to WebP in the pipeline). Default false.
+     *  Free/core. */
     autoOptimize?: boolean;
     /** WebP quality for optimization, 40–95. `0`/omitted = inherit the server default (82). */
     optimizeQuality?: number;
-    /** Target format for optimization: `'webp'` (default) or `'avif'` (falls back to
-     *  WebP when the server build lacks AVIF). */
-    optimizeFormat?: 'webp' | 'avif';
     /** Keep the original file when optimizing (default false = replace in place). */
     optimizeKeepOriginal?: boolean;
     /** Skip optimizing a file larger than this many MB (0/omitted = no limit). */
@@ -167,6 +174,11 @@ interface BaseTokenOptions {
     usageTopFoldersCount?: number;
     /** Folder grouping depth for the usage breakdown. `0`/omitted = inherit (1). */
     usageFolderDepth?: number;
+    /** Generic escape hatch: any JWT claim by its raw snake_case name (e.g.
+     *  `{ allow_terminal: true, terminal_pty_url: '…', upload_collision: 'overwrite' }`).
+     *  Merged last so explicit claims win; the server sanitizes on decode. The single
+     *  place to set claims that don't have a typed option here. See docs/CONFIG.md. */
+    claims?: Record<string, unknown>;
 }
 interface CreateTokenOptions extends BaseTokenOptions {
     /** Disk names the token may access. */

package/dist/index.d.ts

@@ -96,17 +96,24 @@ interface BaseTokenOptions {
     /** Allow editing a file's text content (GET/PUT /api/fm/content). Default **false** — editing
      *  config/executable files (wp-config.php, .env, nginx.conf, deploy.sh) is powerful, so it's opt-in. */
     allowCodeEdit?: boolean;
-    /** Allow the paid Optimization module (POST /api/fm/optimize). Default **false** — opt-in.
-     *  Even when true, the optimize module must be installed + licensed on the server. */
+    /** Allow the SSH terminal (POST /api/fm/terminal) on an SFTP disk. Default **false** — grants shell
+     *  access as the SSH user, so it's opt-in. Core-standalone: the token must target a real core
+     *  (this SDK does), not a proxy adapter that doesn't serve /api/fm/terminal. */
+    allowTerminal?: boolean;
+    /** Optional self-hosted PTY terminal URL (ttyd / gotty / wetty, or any PTY-over-WebSocket
+     *  server the operator runs). When set (and `allowTerminal` is true), the UI embeds it for a
+     *  true interactive terminal instead of the built-in command-runner. Free; must be http(s).
+     *  Core-standalone only (like `allowTerminal`). */
+    terminalPtyUrl?: string;
+    /** Allow the Optimization feature (POST /api/fm/optimize) — recompress images to WebP +
+     *  compress PDFs. **Free/core**; default **false** because it replaces/deletes originals, so
+     *  it's an opt-in capability. */
     allowOptimize?: boolean;
-    /** Auto-optimize images on upload (recompress to WebP in the pipeline). Default false;
-     *  only effective when the optimize module is installed + licensed on the server. */
+    /** Auto-optimize images on upload (recompress to WebP in the pipeline). Default false.
+     *  Free/core. */
     autoOptimize?: boolean;
     /** WebP quality for optimization, 40–95. `0`/omitted = inherit the server default (82). */
     optimizeQuality?: number;
-    /** Target format for optimization: `'webp'` (default) or `'avif'` (falls back to
-     *  WebP when the server build lacks AVIF). */
-    optimizeFormat?: 'webp' | 'avif';
     /** Keep the original file when optimizing (default false = replace in place). */
     optimizeKeepOriginal?: boolean;
     /** Skip optimizing a file larger than this many MB (0/omitted = no limit). */
@@ -167,6 +174,11 @@ interface BaseTokenOptions {
     usageTopFoldersCount?: number;
     /** Folder grouping depth for the usage breakdown. `0`/omitted = inherit (1). */
     usageFolderDepth?: number;
+    /** Generic escape hatch: any JWT claim by its raw snake_case name (e.g.
+     *  `{ allow_terminal: true, terminal_pty_url: '…', upload_collision: 'overwrite' }`).
+     *  Merged last so explicit claims win; the server sanitizes on decode. The single
+     *  place to set claims that don't have a typed option here. See docs/CONFIG.md. */
+    claims?: Record<string, unknown>;
 }
 interface CreateTokenOptions extends BaseTokenOptions {
     /** Disk names the token may access. */

package/dist/index.js

@@ -171,6 +171,8 @@ function applyTenantOverrides(payload, opts) {
   if (opts.allowDownload !== void 0) payload.allow_download = !!opts.allowDownload;
   if (opts.allowChmod !== void 0) payload.allow_chmod = !!opts.allowChmod;
   if (opts.allowCodeEdit !== void 0) payload.allow_code_edit = !!opts.allowCodeEdit;
+  if (opts.allowTerminal !== void 0) payload.allow_terminal = !!opts.allowTerminal;
+  if (opts.terminalPtyUrl) payload.terminal_pty_url = String(opts.terminalPtyUrl);
   if (opts.allowOptimize !== void 0) payload.allow_optimize = !!opts.allowOptimize;
   if (opts.allowShare !== void 0) payload.allow_share = !!opts.allowShare;
   if (opts.allowAiVision !== void 0) payload.allow_ai_vision = !!opts.allowAiVision;
@@ -180,7 +182,6 @@ function applyTenantOverrides(payload, opts) {
   if (opts.allowC2pa !== void 0) payload.allow_c2pa = !!opts.allowC2pa;
   if (opts.autoOptimize !== void 0) payload.auto_optimize = !!opts.autoOptimize;
   if (opts.optimizeQuality && opts.optimizeQuality > 0) payload.optimize_quality = Math.trunc(opts.optimizeQuality);
-  if (opts.optimizeFormat === "avif") payload.optimize_format = "avif";
   if (opts.optimizeKeepOriginal !== void 0) payload.optimize_keep_original = !!opts.optimizeKeepOriginal;
   if (opts.optimizeMaxMb && opts.optimizeMaxMb > 0) payload.optimize_max_mb = Math.trunc(opts.optimizeMaxMb);
   if (opts.pdfLevel && ["screen", "ebook", "printer", "prepress", "default"].includes(opts.pdfLevel)) {
@@ -209,6 +210,9 @@ function applyTenantOverrides(payload, opts) {
   if (opts.usageCriticalThreshold && opts.usageCriticalThreshold > 0) payload.usage_critical_threshold = Math.trunc(opts.usageCriticalThreshold);
   if (opts.usageTopFoldersCount && opts.usageTopFoldersCount > 0) payload.usage_top_folders_count = Math.trunc(opts.usageTopFoldersCount);
   if (opts.usageFolderDepth && opts.usageFolderDepth > 0) payload.usage_folder_depth = Math.trunc(opts.usageFolderDepth);
+  if (opts.claims) {
+    for (const [k, v] of Object.entries(opts.claims)) if (v !== void 0 && v !== null) payload[k] = v;
+  }
 }
 function validateByobDisk(name, config) {
   if (!config || config.driver !== "s3" && config.driver !== "sftp") {

package/dist/index.mjs

@@ -149,6 +149,8 @@ function applyTenantOverrides(payload, opts) {
   if (opts.allowDownload !== void 0) payload.allow_download = !!opts.allowDownload;
   if (opts.allowChmod !== void 0) payload.allow_chmod = !!opts.allowChmod;
   if (opts.allowCodeEdit !== void 0) payload.allow_code_edit = !!opts.allowCodeEdit;
+  if (opts.allowTerminal !== void 0) payload.allow_terminal = !!opts.allowTerminal;
+  if (opts.terminalPtyUrl) payload.terminal_pty_url = String(opts.terminalPtyUrl);
   if (opts.allowOptimize !== void 0) payload.allow_optimize = !!opts.allowOptimize;
   if (opts.allowShare !== void 0) payload.allow_share = !!opts.allowShare;
   if (opts.allowAiVision !== void 0) payload.allow_ai_vision = !!opts.allowAiVision;
@@ -158,7 +160,6 @@ function applyTenantOverrides(payload, opts) {
   if (opts.allowC2pa !== void 0) payload.allow_c2pa = !!opts.allowC2pa;
   if (opts.autoOptimize !== void 0) payload.auto_optimize = !!opts.autoOptimize;
   if (opts.optimizeQuality && opts.optimizeQuality > 0) payload.optimize_quality = Math.trunc(opts.optimizeQuality);
-  if (opts.optimizeFormat === "avif") payload.optimize_format = "avif";
   if (opts.optimizeKeepOriginal !== void 0) payload.optimize_keep_original = !!opts.optimizeKeepOriginal;
   if (opts.optimizeMaxMb && opts.optimizeMaxMb > 0) payload.optimize_max_mb = Math.trunc(opts.optimizeMaxMb);
   if (opts.pdfLevel && ["screen", "ebook", "printer", "prepress", "default"].includes(opts.pdfLevel)) {
@@ -187,6 +188,9 @@ function applyTenantOverrides(payload, opts) {
   if (opts.usageCriticalThreshold && opts.usageCriticalThreshold > 0) payload.usage_critical_threshold = Math.trunc(opts.usageCriticalThreshold);
   if (opts.usageTopFoldersCount && opts.usageTopFoldersCount > 0) payload.usage_top_folders_count = Math.trunc(opts.usageTopFoldersCount);
   if (opts.usageFolderDepth && opts.usageFolderDepth > 0) payload.usage_folder_depth = Math.trunc(opts.usageFolderDepth);
+  if (opts.claims) {
+    for (const [k, v] of Object.entries(opts.claims)) if (v !== void 0 && v !== null) payload[k] = v;
+  }
 }
 function validateByobDisk(name, config) {
   if (!config || config.driver !== "s3" && config.driver !== "sftp") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluxfiles/node",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Server-side Node/TypeScript SDK for minting FluxFiles JWTs (plain + BYOB), byte-compatible with the PHP core",
   "license": "MIT",
   "sideEffects": false,

package/src/token.ts

@@ -141,6 +141,10 @@ function applyTenantOverrides(payload: Record<string, unknown>, opts: BaseTokenO
   if (opts.allowDownload !== undefined) payload.allow_download = !!opts.allowDownload;
   if (opts.allowChmod !== undefined) payload.allow_chmod = !!opts.allowChmod;
   if (opts.allowCodeEdit !== undefined) payload.allow_code_edit = !!opts.allowCodeEdit;
+  // SSH terminal (SFTP disks). Core-standalone — the token must target a real core
+  // (Node mints for one), not a proxy adapter that doesn't serve /api/fm/terminal.
+  if (opts.allowTerminal !== undefined) payload.allow_terminal = !!opts.allowTerminal;
+  if (opts.terminalPtyUrl) payload.terminal_pty_url = String(opts.terminalPtyUrl);
   if (opts.allowOptimize !== undefined) payload.allow_optimize = !!opts.allowOptimize;
   // Other paid-module claims (inert unless the module is installed + licensed).
   if (opts.allowShare !== undefined) payload.allow_share = !!opts.allowShare;
@@ -151,7 +155,6 @@ function applyTenantOverrides(payload: Record<string, unknown>, opts: BaseTokenO
   if (opts.allowC2pa !== undefined) payload.allow_c2pa = !!opts.allowC2pa;
   if (opts.autoOptimize !== undefined) payload.auto_optimize = !!opts.autoOptimize;
   if (opts.optimizeQuality && opts.optimizeQuality > 0) payload.optimize_quality = Math.trunc(opts.optimizeQuality);
-  if (opts.optimizeFormat === 'avif') payload.optimize_format = 'avif';
   if (opts.optimizeKeepOriginal !== undefined) payload.optimize_keep_original = !!opts.optimizeKeepOriginal;
   if (opts.optimizeMaxMb && opts.optimizeMaxMb > 0) payload.optimize_max_mb = Math.trunc(opts.optimizeMaxMb);
   if (opts.pdfLevel && ['screen', 'ebook', 'printer', 'prepress', 'default'].includes(opts.pdfLevel)) {
@@ -182,6 +185,11 @@ function applyTenantOverrides(payload: Record<string, unknown>, opts: BaseTokenO
   if (opts.usageCriticalThreshold && opts.usageCriticalThreshold > 0) payload.usage_critical_threshold = Math.trunc(opts.usageCriticalThreshold);
   if (opts.usageTopFoldersCount && opts.usageTopFoldersCount > 0) payload.usage_top_folders_count = Math.trunc(opts.usageTopFoldersCount);
   if (opts.usageFolderDepth && opts.usageFolderDepth > 0) payload.usage_folder_depth = Math.trunc(opts.usageFolderDepth);
+
+  // Generic escape hatch: ANY claim by its raw (snake_case) name. Merged last so an
+  // explicit claim wins over a preset/group default. The server sanitizes on decode.
+  // See docs/CONFIG.md for the full claim list.
+  if (opts.claims) for (const [k, v] of Object.entries(opts.claims)) if (v !== undefined && v !== null) payload[k] = v;
 }
 
 /**

package/src/types.ts

@@ -100,17 +100,24 @@ export interface BaseTokenOptions {
   /** Allow editing a file's text content (GET/PUT /api/fm/content). Default **false** — editing
    *  config/executable files (wp-config.php, .env, nginx.conf, deploy.sh) is powerful, so it's opt-in. */
   allowCodeEdit?: boolean;
-  /** Allow the paid Optimization module (POST /api/fm/optimize). Default **false** — opt-in.
-   *  Even when true, the optimize module must be installed + licensed on the server. */
+  /** Allow the SSH terminal (POST /api/fm/terminal) on an SFTP disk. Default **false** — grants shell
+   *  access as the SSH user, so it's opt-in. Core-standalone: the token must target a real core
+   *  (this SDK does), not a proxy adapter that doesn't serve /api/fm/terminal. */
+  allowTerminal?: boolean;
+  /** Optional self-hosted PTY terminal URL (ttyd / gotty / wetty, or any PTY-over-WebSocket
+   *  server the operator runs). When set (and `allowTerminal` is true), the UI embeds it for a
+   *  true interactive terminal instead of the built-in command-runner. Free; must be http(s).
+   *  Core-standalone only (like `allowTerminal`). */
+  terminalPtyUrl?: string;
+  /** Allow the Optimization feature (POST /api/fm/optimize) — recompress images to WebP +
+   *  compress PDFs. **Free/core**; default **false** because it replaces/deletes originals, so
+   *  it's an opt-in capability. */
   allowOptimize?: boolean;
-  /** Auto-optimize images on upload (recompress to WebP in the pipeline). Default false;
-   *  only effective when the optimize module is installed + licensed on the server. */
+  /** Auto-optimize images on upload (recompress to WebP in the pipeline). Default false.
+   *  Free/core. */
   autoOptimize?: boolean;
   /** WebP quality for optimization, 40–95. `0`/omitted = inherit the server default (82). */
   optimizeQuality?: number;
-  /** Target format for optimization: `'webp'` (default) or `'avif'` (falls back to
-   *  WebP when the server build lacks AVIF). */
-  optimizeFormat?: 'webp' | 'avif';
   /** Keep the original file when optimizing (default false = replace in place). */
   optimizeKeepOriginal?: boolean;
   /** Skip optimizing a file larger than this many MB (0/omitted = no limit). */
@@ -171,6 +178,11 @@ export interface BaseTokenOptions {
   usageTopFoldersCount?: number;
   /** Folder grouping depth for the usage breakdown. `0`/omitted = inherit (1). */
   usageFolderDepth?: number;
+  /** Generic escape hatch: any JWT claim by its raw snake_case name (e.g.
+   *  `{ allow_terminal: true, terminal_pty_url: '…', upload_collision: 'overwrite' }`).
+   *  Merged last so explicit claims win; the server sanitizes on decode. The single
+   *  place to set claims that don't have a typed option here. See docs/CONFIG.md. */
+  claims?: Record<string, unknown>;
 }
 
 export interface CreateTokenOptions extends BaseTokenOptions {