@fluxfiles/node 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thai-pc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,9 +7,17 @@ including encrypted BYOB (Bring Your Own Bucket) credentials — without running
 
 Zero runtime dependencies (built on `node:crypto`).
 
+> **This package only issues tokens — it is not a backend.** You still run a
+> FluxFiles **core service** (the file-manager backend that talks to storage; a
+> PHP app, e.g. the Docker image) for the token to authenticate against.
+> `@fluxfiles/node` simply removes the need for *your app* to be PHP in order to
+> mint those tokens.
+
 ## Requirements
 
 - Node.js 16+
+- A running FluxFiles **core service** the issued tokens authenticate against
+  (the SDK/iframe `endpoint` points at it).
 - The same **`FLUXFILES_SECRET`** your FluxFiles core server uses to verify tokens
   (HS256, **must be ≥ 32 bytes**). Keep it server-side only.
 
@@ -107,6 +115,8 @@ app.get('/fluxfiles/token', (req, res) => {
 
 `createToken` options: `secret?`, `userId`, `perms?`, `disks?`, `prefix?`,
 `maxUploadMb?`, `allowedExt?`, `ttl?`, `ownerOnly?`, `maxStorageMb?`, `maxFiles?`.
+Per-tenant overrides (omit to inherit the server default): `aiAutoTag?` (bool),
+`rateRead?` / `rateWrite?` (req/min), `variants?` (`{ thumb?, medium?, large? }` px).
 `createByobToken` replaces `disks` with `byobDisks` (a map of name → S3-compatible
 config) and does not take `maxStorageMb`/`maxFiles` (matching the core).
 

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-/** A FluxFiles permission. */
-type FluxPermission = 'read' | 'write' | 'delete';
+/** A FluxFiles permission. `audit` gates reading the activity log. */
+type FluxPermission = 'read' | 'write' | 'delete' | 'audit';
 /**
  * A BYOB (Bring Your Own Bucket) disk config. Encrypted into the JWT and
  * decrypted only at runtime by the FluxFiles server. Only S3-compatible
@@ -33,6 +33,14 @@ interface BaseTokenOptions {
     ttl?: number;
     /** Restrict destructive ops to files the user uploaded. */
     ownerOnly?: boolean;
+    /** Per-tenant AI auto-tag toggle. Omit to inherit the server default. */
+    aiAutoTag?: boolean;
+    /** Per-tenant read rate limit (requests/min). `0`/omitted = inherit server default. */
+    rateRead?: number;
+    /** Per-tenant write rate limit (requests/min). `0`/omitted = inherit server default. */
+    rateWrite?: number;
+    /** Per-tenant image variant widths, e.g. `{ thumb: 150, medium: 768, large: 1920 }`. Omit to inherit. */
+    variants?: Partial<Record<'thumb' | 'medium' | 'large', number>> | null;
 }
 interface CreateTokenOptions extends BaseTokenOptions {
     /** Disk names the token may access. */

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-/** A FluxFiles permission. */
-type FluxPermission = 'read' | 'write' | 'delete';
+/** A FluxFiles permission. `audit` gates reading the activity log. */
+type FluxPermission = 'read' | 'write' | 'delete' | 'audit';
 /**
  * A BYOB (Bring Your Own Bucket) disk config. Encrypted into the JWT and
  * decrypted only at runtime by the FluxFiles server. Only S3-compatible
@@ -33,6 +33,14 @@ interface BaseTokenOptions {
     ttl?: number;
     /** Restrict destructive ops to files the user uploaded. */
     ownerOnly?: boolean;
+    /** Per-tenant AI auto-tag toggle. Omit to inherit the server default. */
+    aiAutoTag?: boolean;
+    /** Per-tenant read rate limit (requests/min). `0`/omitted = inherit server default. */
+    rateRead?: number;
+    /** Per-tenant write rate limit (requests/min). `0`/omitted = inherit server default. */
+    rateWrite?: number;
+    /** Per-tenant image variant widths, e.g. `{ thumb: 150, medium: 768, large: 1920 }`. Omit to inherit. */
+    variants?: Partial<Record<'thumb' | 'medium' | 'large', number>> | null;
 }
 interface CreateTokenOptions extends BaseTokenOptions {
     /** Disk names the token may access. */

package/dist/index.js

@@ -98,6 +98,7 @@ function createToken(opts) {
     max_files: opts.maxFiles ?? 0
   };
   if (opts.ownerOnly) payload.owner_only = true;
+  applyTenantOverrides(payload, opts);
   return sign(payload, secret);
 }
 function createByobToken(opts) {
@@ -123,8 +124,25 @@ function createByobToken(opts) {
     byob_disks: encrypted
   };
   if (opts.ownerOnly) payload.owner_only = true;
+  applyTenantOverrides(payload, opts);
   return sign(payload, secret);
 }
+function sanitizeVariants(v) {
+  if (!v || typeof v !== "object") return null;
+  const out = {};
+  for (const name of ["thumb", "medium", "large"]) {
+    const w = Math.trunc(Number(v[name]));
+    if (Number.isFinite(w) && w >= 16 && w <= 8e3) out[name] = w;
+  }
+  return Object.keys(out).length ? out : null;
+}
+function applyTenantOverrides(payload, opts) {
+  if (opts.aiAutoTag !== void 0) payload.ai_auto_tag = !!opts.aiAutoTag;
+  if (opts.rateRead && opts.rateRead > 0) payload.rate_read = Math.trunc(opts.rateRead);
+  if (opts.rateWrite && opts.rateWrite > 0) payload.rate_write = Math.trunc(opts.rateWrite);
+  const variants = sanitizeVariants(opts.variants);
+  if (variants) payload.variants = variants;
+}
 function validateByobDisk(name, config) {
   if (!config || config.driver !== "s3") {
     throw new Error(`FluxFiles BYOB disk "${name}": driver must be "s3" (the server rejects "local").`);

package/dist/index.mjs

@@ -76,6 +76,7 @@ function createToken(opts) {
     max_files: opts.maxFiles ?? 0
   };
   if (opts.ownerOnly) payload.owner_only = true;
+  applyTenantOverrides(payload, opts);
   return sign(payload, secret);
 }
 function createByobToken(opts) {
@@ -101,8 +102,25 @@ function createByobToken(opts) {
     byob_disks: encrypted
   };
   if (opts.ownerOnly) payload.owner_only = true;
+  applyTenantOverrides(payload, opts);
   return sign(payload, secret);
 }
+function sanitizeVariants(v) {
+  if (!v || typeof v !== "object") return null;
+  const out = {};
+  for (const name of ["thumb", "medium", "large"]) {
+    const w = Math.trunc(Number(v[name]));
+    if (Number.isFinite(w) && w >= 16 && w <= 8e3) out[name] = w;
+  }
+  return Object.keys(out).length ? out : null;
+}
+function applyTenantOverrides(payload, opts) {
+  if (opts.aiAutoTag !== void 0) payload.ai_auto_tag = !!opts.aiAutoTag;
+  if (opts.rateRead && opts.rateRead > 0) payload.rate_read = Math.trunc(opts.rateRead);
+  if (opts.rateWrite && opts.rateWrite > 0) payload.rate_write = Math.trunc(opts.rateWrite);
+  const variants = sanitizeVariants(opts.variants);
+  if (variants) payload.variants = variants;
+}
 function validateByobDisk(name, config) {
   if (!config || config.driver !== "s3") {
     throw new Error(`FluxFiles BYOB disk "${name}": driver must be "s3" (the server rejects "local").`);

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@fluxfiles/node",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Server-side Node/TypeScript SDK for minting FluxFiles JWTs (plain + BYOB), byte-compatible with the PHP core",
   "license": "MIT",
+  "sideEffects": false,
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",

package/src/token.ts

@@ -1,6 +1,6 @@
 import { randomBytes } from 'node:crypto';
 import { base64url, hmacSha256, encryptByob } from './crypto';
-import type { ByobDiskConfig, CreateByobTokenOptions, CreateTokenOptions } from './types';
+import type { BaseTokenOptions, ByobDiskConfig, CreateByobTokenOptions, CreateTokenOptions } from './types';
 
 const MIN_SECRET_BYTES = 32;
 
@@ -48,6 +48,7 @@ export function createToken(opts: CreateTokenOptions): string {
     max_files: opts.maxFiles ?? 0,
   };
   if (opts.ownerOnly) payload.owner_only = true;
+  applyTenantOverrides(payload, opts);
   return sign(payload, secret);
 }
 
@@ -81,9 +82,30 @@ export function createByobToken(opts: CreateByobTokenOptions): string {
     byob_disks: encrypted,
   };
   if (opts.ownerOnly) payload.owner_only = true;
+  applyTenantOverrides(payload, opts);
   return sign(payload, secret);
 }
 
+/** Sanitize the per-tenant `variants` claim — matches PHP `Claims::sanitizeVariants`. */
+function sanitizeVariants(v: BaseTokenOptions['variants']): Record<string, number> | null {
+  if (!v || typeof v !== 'object') return null;
+  const out: Record<string, number> = {};
+  for (const name of ['thumb', 'medium', 'large'] as const) {
+    const w = Math.trunc(Number((v as Record<string, unknown>)[name]));
+    if (Number.isFinite(w) && w >= 16 && w <= 8000) out[name] = w;
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+/** Copy the optional per-tenant override claims into a payload when set. */
+function applyTenantOverrides(payload: Record<string, unknown>, opts: BaseTokenOptions): void {
+  if (opts.aiAutoTag !== undefined) payload.ai_auto_tag = !!opts.aiAutoTag;
+  if (opts.rateRead && opts.rateRead > 0) payload.rate_read = Math.trunc(opts.rateRead);
+  if (opts.rateWrite && opts.rateWrite > 0) payload.rate_write = Math.trunc(opts.rateWrite);
+  const variants = sanitizeVariants(opts.variants);
+  if (variants) payload.variants = variants;
+}
+
 /**
  * Light client-side validation. The server independently re-validates (incl.
  * SSRF checks on the endpoint), so this only catches obvious mistakes early.

package/src/types.ts

@@ -1,5 +1,5 @@
-/** A FluxFiles permission. */
-export type FluxPermission = 'read' | 'write' | 'delete';
+/** A FluxFiles permission. `audit` gates reading the activity log. */
+export type FluxPermission = 'read' | 'write' | 'delete' | 'audit';
 
 /**
  * A BYOB (Bring Your Own Bucket) disk config. Encrypted into the JWT and
@@ -35,6 +35,14 @@ export interface BaseTokenOptions {
   ttl?: number;
   /** Restrict destructive ops to files the user uploaded. */
   ownerOnly?: boolean;
+  /** Per-tenant AI auto-tag toggle. Omit to inherit the server default. */
+  aiAutoTag?: boolean;
+  /** Per-tenant read rate limit (requests/min). `0`/omitted = inherit server default. */
+  rateRead?: number;
+  /** Per-tenant write rate limit (requests/min). `0`/omitted = inherit server default. */
+  rateWrite?: number;
+  /** Per-tenant image variant widths, e.g. `{ thumb: 150, medium: 768, large: 1920 }`. Omit to inherit. */
+  variants?: Partial<Record<'thumb' | 'medium' | 'large', number>> | null;
 }
 
 export interface CreateTokenOptions extends BaseTokenOptions {