@fluxfiles/node 0.1.0

package/README.md

@@ -0,0 +1,128 @@
+# FluxFiles for Node (server-side token SDK)
+
+Mint [FluxFiles](https://github.com/thai-pc/fluxfiles) JWTs from any Node.js
+backend (Express, Next.js, Nuxt/Nitro, NestJS, Fastify, …). Tokens are
+**byte-compatible with the PHP core**, so non-PHP apps can issue access tokens —
+including encrypted BYOB (Bring Your Own Bucket) credentials — without running PHP.
+
+Zero runtime dependencies (built on `node:crypto`).
+
+## Requirements
+
+- Node.js 16+
+- The same **`FLUXFILES_SECRET`** your FluxFiles core server uses to verify tokens
+  (HS256, **must be ≥ 32 bytes**). Keep it server-side only.
+
+## Installation
+
+```bash
+npm install @fluxfiles/node
+# or
+yarn add @fluxfiles/node
+```
+
+## Usage
+
+### Mint a token
+
+```ts
+import { createToken } from '@fluxfiles/node';
+
+const token = createToken({
+  secret: process.env.FLUXFILES_SECRET, // or omit to read FLUXFILES_SECRET
+  userId: 'user-42',
+  perms: ['read', 'write'],
+  disks: ['local', 's3'],
+  prefix: 'users/42',     // scope the user to their own directory
+  maxUploadMb: 25,
+  allowedExt: ['png', 'jpg', 'pdf'],
+  ttl: 3600,              // seconds
+});
+```
+
+### BYOB — encrypt a user's own bucket credentials
+
+```ts
+import { createByobToken } from '@fluxfiles/node';
+
+const token = createByobToken({
+  userId: 'user-42',
+  byobDisks: {
+    'my-s3': {
+      driver: 's3',
+      key: process.env.USER_AWS_KEY!,
+      secret: process.env.USER_AWS_SECRET!,
+      bucket: 'user-personal-bucket',
+      region: 'us-east-1',
+      // endpoint: 'https://<acct>.r2.cloudflarestorage.com', // R2/MinIO/Spaces
+    },
+  },
+});
+```
+
+Credentials are AES-256-GCM encrypted into the token and decrypted only at
+runtime by the FluxFiles server (which also re-validates the endpoint for SSRF).
+
+### Verify / decode (optional)
+
+```ts
+import { verifyToken, decodeToken } from '@fluxfiles/node';
+
+const claims = verifyToken(token);   // checks HS256 signature + expiry, throws on failure
+const peek = decodeToken(token);     // decode only, NO verification — never trust for auth
+```
+
+### Next.js (App Router) — Route Handler
+
+```ts
+// app/api/fluxfiles-token/route.ts
+import { createToken } from '@fluxfiles/node';
+import { auth } from '@/lib/auth';
+
+export async function GET() {
+  const user = await auth();
+  const token = createToken({ userId: user.id, perms: ['read', 'write'], prefix: `users/${user.id}` });
+  return Response.json({ token });
+}
+```
+
+### Express middleware
+
+```ts
+import { createToken } from '@fluxfiles/node';
+
+app.get('/fluxfiles/token', (req, res) => {
+  res.json({ token: createToken({ userId: req.user.id, perms: ['read', 'write'] }) });
+});
+```
+
+## API
+
+| Function | Description |
+|----------|-------------|
+| `createToken(opts)` | Standard token. Mirrors PHP `fluxfiles_token()`. |
+| `createByobToken(opts)` | Token with encrypted BYOB disk credentials. Mirrors `fluxfiles_byob_token()`. |
+| `verifyToken(token, secret?)` | Verify HS256 signature + expiry; returns decoded claims or throws. |
+| `decodeToken(token)` | Decode without verifying (inspection/logging only). |
+
+`createToken` options: `secret?`, `userId`, `perms?`, `disks?`, `prefix?`,
+`maxUploadMb?`, `allowedExt?`, `ttl?`, `ownerOnly?`, `maxStorageMb?`, `maxFiles?`.
+`createByobToken` replaces `disks` with `byobDisks` (a map of name → S3-compatible
+config) and does not take `maxStorageMb`/`maxFiles` (matching the core).
+
+## Compatibility
+
+Tokens and BYOB blobs are validated against the PHP core in CI: a Node-minted
+token decodes in `JwtCompat::decode`, and BYOB credentials round-trip both ways
+through `CredentialEncryptor` (HS256 + HKDF-SHA256 + AES-256-GCM). Always mint
+tokens **on the server** — never ship `FLUXFILES_SECRET` to the browser.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+
+## Links
+
+- Main repository: `https://github.com/thai-pc/fluxfiles`
+- Documentation: `https://github.com/thai-pc/fluxfiles#node-server-side-token-sdk`
+- Issues: `https://github.com/thai-pc/fluxfiles/issues`

package/dist/index.d.mts

@@ -0,0 +1,88 @@
+/** A FluxFiles permission. */
+type FluxPermission = 'read' | 'write' | 'delete';
+/**
+ * A BYOB (Bring Your Own Bucket) disk config. Encrypted into the JWT and
+ * decrypted only at runtime by the FluxFiles server. Only S3-compatible
+ * storage is allowed — the server rejects the `local` driver.
+ */
+interface ByobDiskConfig {
+    driver: 's3';
+    key: string;
+    secret: string;
+    bucket: string;
+    region?: string;
+    /** Custom S3 endpoint (R2, MinIO, Spaces, …). Omit for native AWS S3. */
+    endpoint?: string;
+    visibility?: 'private' | 'public';
+    /** Public base URL for direct (unsigned) object links on a public disk. */
+    public_url?: string;
+}
+/** Options shared by all token builders. */
+interface BaseTokenOptions {
+    /** HS256 signing secret. Defaults to `process.env.FLUXFILES_SECRET`. Must be ≥ 32 bytes. */
+    secret?: string;
+    /** Subject — your application's user id. */
+    userId: string;
+    perms?: FluxPermission[];
+    /** Path prefix the user is scoped to (e.g. `users/42`). */
+    prefix?: string;
+    maxUploadMb?: number;
+    /** Allowed extensions (lowercase, no dot). `null`/omitted = all non-dangerous types. */
+    allowedExt?: string[] | null;
+    /** Time-to-live in seconds. */
+    ttl?: number;
+    /** Restrict destructive ops to files the user uploaded. */
+    ownerOnly?: boolean;
+}
+interface CreateTokenOptions extends BaseTokenOptions {
+    /** Disk names the token may access. */
+    disks?: string[];
+    maxStorageMb?: number;
+    /** Total file count cap under the prefix. `0` = unlimited. */
+    maxFiles?: number;
+}
+interface CreateByobTokenOptions extends BaseTokenOptions {
+    /** Map of disk name → S3-compatible credentials, encrypted into the token. */
+    byobDisks: Record<string, ByobDiskConfig>;
+}
+/** Decoded JWT payload (snake_case, as emitted by the PHP core). */
+interface FluxClaims {
+    sub: string;
+    iat: number;
+    exp: number;
+    jti: string;
+    perms: string[];
+    disks: string[];
+    prefix: string;
+    max_upload: number;
+    allowed_ext: string[] | null;
+    max_storage?: number;
+    max_files?: number;
+    owner_only?: boolean;
+    byob_disks?: Record<string, string>;
+}
+
+/**
+ * Mint a standard FluxFiles JWT. The payload mirrors the PHP `fluxfiles_token()`
+ * helper exactly, so the FluxFiles core decodes it natively.
+ */
+declare function createToken(opts: CreateTokenOptions): string;
+/**
+ * Mint a BYOB token. Each disk's S3-compatible credentials are AES-256-GCM
+ * encrypted into the token (decrypted only at runtime by the server). Mirrors
+ * the PHP `fluxfiles_byob_token()` helper.
+ */
+declare function createByobToken(opts: CreateByobTokenOptions): string;
+
+/**
+ * Decode a token WITHOUT verifying the signature. Useful for inspection/logging;
+ * never trust the result for authorization — use {@link verifyToken}.
+ */
+declare function decodeToken(token: string): FluxClaims;
+/**
+ * Verify an HS256 FluxFiles token: signature + expiry. Returns the decoded
+ * claims, or throws on a bad signature, wrong algorithm, or an expired token.
+ */
+declare function verifyToken(token: string, secret?: string): FluxClaims;
+
+export { type BaseTokenOptions, type ByobDiskConfig, type CreateByobTokenOptions, type CreateTokenOptions, type FluxClaims, type FluxPermission, createByobToken, createToken, decodeToken, verifyToken };

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+/** A FluxFiles permission. */
+type FluxPermission = 'read' | 'write' | 'delete';
+/**
+ * A BYOB (Bring Your Own Bucket) disk config. Encrypted into the JWT and
+ * decrypted only at runtime by the FluxFiles server. Only S3-compatible
+ * storage is allowed — the server rejects the `local` driver.
+ */
+interface ByobDiskConfig {
+    driver: 's3';
+    key: string;
+    secret: string;
+    bucket: string;
+    region?: string;
+    /** Custom S3 endpoint (R2, MinIO, Spaces, …). Omit for native AWS S3. */
+    endpoint?: string;
+    visibility?: 'private' | 'public';
+    /** Public base URL for direct (unsigned) object links on a public disk. */
+    public_url?: string;
+}
+/** Options shared by all token builders. */
+interface BaseTokenOptions {
+    /** HS256 signing secret. Defaults to `process.env.FLUXFILES_SECRET`. Must be ≥ 32 bytes. */
+    secret?: string;
+    /** Subject — your application's user id. */
+    userId: string;
+    perms?: FluxPermission[];
+    /** Path prefix the user is scoped to (e.g. `users/42`). */
+    prefix?: string;
+    maxUploadMb?: number;
+    /** Allowed extensions (lowercase, no dot). `null`/omitted = all non-dangerous types. */
+    allowedExt?: string[] | null;
+    /** Time-to-live in seconds. */
+    ttl?: number;
+    /** Restrict destructive ops to files the user uploaded. */
+    ownerOnly?: boolean;
+}
+interface CreateTokenOptions extends BaseTokenOptions {
+    /** Disk names the token may access. */
+    disks?: string[];
+    maxStorageMb?: number;
+    /** Total file count cap under the prefix. `0` = unlimited. */
+    maxFiles?: number;
+}
+interface CreateByobTokenOptions extends BaseTokenOptions {
+    /** Map of disk name → S3-compatible credentials, encrypted into the token. */
+    byobDisks: Record<string, ByobDiskConfig>;
+}
+/** Decoded JWT payload (snake_case, as emitted by the PHP core). */
+interface FluxClaims {
+    sub: string;
+    iat: number;
+    exp: number;
+    jti: string;
+    perms: string[];
+    disks: string[];
+    prefix: string;
+    max_upload: number;
+    allowed_ext: string[] | null;
+    max_storage?: number;
+    max_files?: number;
+    owner_only?: boolean;
+    byob_disks?: Record<string, string>;
+}
+
+/**
+ * Mint a standard FluxFiles JWT. The payload mirrors the PHP `fluxfiles_token()`
+ * helper exactly, so the FluxFiles core decodes it natively.
+ */
+declare function createToken(opts: CreateTokenOptions): string;
+/**
+ * Mint a BYOB token. Each disk's S3-compatible credentials are AES-256-GCM
+ * encrypted into the token (decrypted only at runtime by the server). Mirrors
+ * the PHP `fluxfiles_byob_token()` helper.
+ */
+declare function createByobToken(opts: CreateByobTokenOptions): string;
+
+/**
+ * Decode a token WITHOUT verifying the signature. Useful for inspection/logging;
+ * never trust the result for authorization — use {@link verifyToken}.
+ */
+declare function decodeToken(token: string): FluxClaims;
+/**
+ * Verify an HS256 FluxFiles token: signature + expiry. Returns the decoded
+ * claims, or throws on a bad signature, wrong algorithm, or an expired token.
+ */
+declare function verifyToken(token: string, secret?: string): FluxClaims;
+
+export { type BaseTokenOptions, type ByobDiskConfig, type CreateByobTokenOptions, type CreateTokenOptions, type FluxClaims, type FluxPermission, createByobToken, createToken, decodeToken, verifyToken };

package/dist/index.js

@@ -0,0 +1,170 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createByobToken: () => createByobToken,
+  createToken: () => createToken,
+  decodeToken: () => decodeToken,
+  verifyToken: () => verifyToken
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/token.ts
+var import_node_crypto2 = require("crypto");
+
+// src/crypto.ts
+var import_node_crypto = require("crypto");
+function base64url(input) {
+  return Buffer.from(input).toString("base64url");
+}
+function hmacSha256(data, secret) {
+  return (0, import_node_crypto.createHmac)("sha256", secret).update(data).digest();
+}
+function safeEqual(a, b) {
+  const ba = Buffer.from(a);
+  const bb = Buffer.from(b);
+  return ba.length === bb.length && (0, import_node_crypto.timingSafeEqual)(ba, bb);
+}
+var BYOB_INFO = "fluxfiles-byob-enc";
+var NONCE_LEN = 12;
+var TAG_LEN = 16;
+function deriveByobKey(secret) {
+  const salt = Buffer.alloc(32, 0);
+  const dk = (0, import_node_crypto.hkdfSync)("sha256", Buffer.from(secret, "utf8"), salt, Buffer.from(BYOB_INFO, "utf8"), 32);
+  return Buffer.from(dk);
+}
+function encryptByob(config, secret) {
+  const key = deriveByobKey(secret);
+  const nonce = (0, import_node_crypto.randomBytes)(NONCE_LEN);
+  const cipher = (0, import_node_crypto.createCipheriv)("aes-256-gcm", key, nonce, { authTagLength: TAG_LEN });
+  const plaintext = JSON.stringify(config);
+  const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([nonce, ct, tag]).toString("base64");
+}
+
+// src/token.ts
+var MIN_SECRET_BYTES = 32;
+function resolveSecret(explicit) {
+  const secret = explicit ?? process.env.FLUXFILES_SECRET ?? "";
+  if (Buffer.byteLength(secret, "utf8") < MIN_SECRET_BYTES) {
+    throw new Error(
+      `FluxFiles: signing secret must be at least ${MIN_SECRET_BYTES} bytes (HS256 key requirement). Set \`secret\` or FLUXFILES_SECRET.`
+    );
+  }
+  return secret;
+}
+function sign(payload, secret) {
+  const header = base64url(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+  const body = base64url(JSON.stringify(payload));
+  const sig = base64url(hmacSha256(`${header}.${body}`, secret));
+  return `${header}.${body}.${sig}`;
+}
+function newJti() {
+  return (0, import_node_crypto2.randomBytes)(12).toString("hex");
+}
+function createToken(opts) {
+  const secret = resolveSecret(opts.secret);
+  const now = Math.floor(Date.now() / 1e3);
+  const payload = {
+    sub: opts.userId,
+    iat: now,
+    exp: now + (opts.ttl ?? 3600),
+    jti: newJti(),
+    perms: opts.perms ?? ["read"],
+    disks: opts.disks ?? ["local"],
+    prefix: opts.prefix ?? "",
+    max_upload: opts.maxUploadMb ?? 10,
+    allowed_ext: opts.allowedExt ?? null,
+    max_storage: opts.maxStorageMb ?? 0,
+    max_files: opts.maxFiles ?? 0
+  };
+  if (opts.ownerOnly) payload.owner_only = true;
+  return sign(payload, secret);
+}
+function createByobToken(opts) {
+  const secret = resolveSecret(opts.secret);
+  const now = Math.floor(Date.now() / 1e3);
+  const encrypted = {};
+  const names = [];
+  for (const [name, config] of Object.entries(opts.byobDisks)) {
+    validateByobDisk(name, config);
+    encrypted[name] = encryptByob(config, secret);
+    names.push(name);
+  }
+  const payload = {
+    sub: opts.userId,
+    iat: now,
+    exp: now + (opts.ttl ?? 1800),
+    jti: newJti(),
+    perms: opts.perms ?? ["read", "write"],
+    disks: names,
+    prefix: opts.prefix ?? "",
+    max_upload: opts.maxUploadMb ?? 10,
+    allowed_ext: opts.allowedExt ?? null,
+    byob_disks: encrypted
+  };
+  if (opts.ownerOnly) payload.owner_only = true;
+  return sign(payload, secret);
+}
+function validateByobDisk(name, config) {
+  if (!config || config.driver !== "s3") {
+    throw new Error(`FluxFiles BYOB disk "${name}": driver must be "s3" (the server rejects "local").`);
+  }
+  for (const field of ["key", "secret", "bucket"]) {
+    if (!config[field]) {
+      throw new Error(`FluxFiles BYOB disk "${name}": missing required "${field}".`);
+    }
+  }
+}
+
+// src/verify.ts
+function decodeSegment(seg) {
+  return JSON.parse(Buffer.from(seg, "base64url").toString("utf8"));
+}
+function decodeToken(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) throw new Error("FluxFiles: malformed token");
+  return decodeSegment(parts[1]);
+}
+function verifyToken(token, secret) {
+  const key = secret ?? process.env.FLUXFILES_SECRET ?? "";
+  if (!key) throw new Error("FluxFiles: no secret provided to verifyToken");
+  const parts = token.split(".");
+  if (parts.length !== 3) throw new Error("FluxFiles: malformed token");
+  const [header, body, sig] = parts;
+  const alg = decodeSegment(header).alg;
+  if (alg !== "HS256") throw new Error(`FluxFiles: unexpected JWT alg "${alg}"`);
+  const expected = base64url(hmacSha256(`${header}.${body}`, key));
+  if (!safeEqual(sig, expected)) throw new Error("FluxFiles: invalid token signature");
+  const claims = decodeSegment(body);
+  if (typeof claims.exp === "number" && claims.exp < Math.floor(Date.now() / 1e3)) {
+    throw new Error("FluxFiles: token has expired");
+  }
+  return claims;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createByobToken,
+  createToken,
+  decodeToken,
+  verifyToken
+});

package/dist/index.mjs

@@ -0,0 +1,147 @@
+// src/token.ts
+import { randomBytes as randomBytes2 } from "crypto";
+
+// src/crypto.ts
+import {
+  createHmac,
+  hkdfSync,
+  randomBytes,
+  createCipheriv,
+  createDecipheriv,
+  timingSafeEqual
+} from "crypto";
+function base64url(input) {
+  return Buffer.from(input).toString("base64url");
+}
+function hmacSha256(data, secret) {
+  return createHmac("sha256", secret).update(data).digest();
+}
+function safeEqual(a, b) {
+  const ba = Buffer.from(a);
+  const bb = Buffer.from(b);
+  return ba.length === bb.length && timingSafeEqual(ba, bb);
+}
+var BYOB_INFO = "fluxfiles-byob-enc";
+var NONCE_LEN = 12;
+var TAG_LEN = 16;
+function deriveByobKey(secret) {
+  const salt = Buffer.alloc(32, 0);
+  const dk = hkdfSync("sha256", Buffer.from(secret, "utf8"), salt, Buffer.from(BYOB_INFO, "utf8"), 32);
+  return Buffer.from(dk);
+}
+function encryptByob(config, secret) {
+  const key = deriveByobKey(secret);
+  const nonce = randomBytes(NONCE_LEN);
+  const cipher = createCipheriv("aes-256-gcm", key, nonce, { authTagLength: TAG_LEN });
+  const plaintext = JSON.stringify(config);
+  const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([nonce, ct, tag]).toString("base64");
+}
+
+// src/token.ts
+var MIN_SECRET_BYTES = 32;
+function resolveSecret(explicit) {
+  const secret = explicit ?? process.env.FLUXFILES_SECRET ?? "";
+  if (Buffer.byteLength(secret, "utf8") < MIN_SECRET_BYTES) {
+    throw new Error(
+      `FluxFiles: signing secret must be at least ${MIN_SECRET_BYTES} bytes (HS256 key requirement). Set \`secret\` or FLUXFILES_SECRET.`
+    );
+  }
+  return secret;
+}
+function sign(payload, secret) {
+  const header = base64url(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+  const body = base64url(JSON.stringify(payload));
+  const sig = base64url(hmacSha256(`${header}.${body}`, secret));
+  return `${header}.${body}.${sig}`;
+}
+function newJti() {
+  return randomBytes2(12).toString("hex");
+}
+function createToken(opts) {
+  const secret = resolveSecret(opts.secret);
+  const now = Math.floor(Date.now() / 1e3);
+  const payload = {
+    sub: opts.userId,
+    iat: now,
+    exp: now + (opts.ttl ?? 3600),
+    jti: newJti(),
+    perms: opts.perms ?? ["read"],
+    disks: opts.disks ?? ["local"],
+    prefix: opts.prefix ?? "",
+    max_upload: opts.maxUploadMb ?? 10,
+    allowed_ext: opts.allowedExt ?? null,
+    max_storage: opts.maxStorageMb ?? 0,
+    max_files: opts.maxFiles ?? 0
+  };
+  if (opts.ownerOnly) payload.owner_only = true;
+  return sign(payload, secret);
+}
+function createByobToken(opts) {
+  const secret = resolveSecret(opts.secret);
+  const now = Math.floor(Date.now() / 1e3);
+  const encrypted = {};
+  const names = [];
+  for (const [name, config] of Object.entries(opts.byobDisks)) {
+    validateByobDisk(name, config);
+    encrypted[name] = encryptByob(config, secret);
+    names.push(name);
+  }
+  const payload = {
+    sub: opts.userId,
+    iat: now,
+    exp: now + (opts.ttl ?? 1800),
+    jti: newJti(),
+    perms: opts.perms ?? ["read", "write"],
+    disks: names,
+    prefix: opts.prefix ?? "",
+    max_upload: opts.maxUploadMb ?? 10,
+    allowed_ext: opts.allowedExt ?? null,
+    byob_disks: encrypted
+  };
+  if (opts.ownerOnly) payload.owner_only = true;
+  return sign(payload, secret);
+}
+function validateByobDisk(name, config) {
+  if (!config || config.driver !== "s3") {
+    throw new Error(`FluxFiles BYOB disk "${name}": driver must be "s3" (the server rejects "local").`);
+  }
+  for (const field of ["key", "secret", "bucket"]) {
+    if (!config[field]) {
+      throw new Error(`FluxFiles BYOB disk "${name}": missing required "${field}".`);
+    }
+  }
+}
+
+// src/verify.ts
+function decodeSegment(seg) {
+  return JSON.parse(Buffer.from(seg, "base64url").toString("utf8"));
+}
+function decodeToken(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) throw new Error("FluxFiles: malformed token");
+  return decodeSegment(parts[1]);
+}
+function verifyToken(token, secret) {
+  const key = secret ?? process.env.FLUXFILES_SECRET ?? "";
+  if (!key) throw new Error("FluxFiles: no secret provided to verifyToken");
+  const parts = token.split(".");
+  if (parts.length !== 3) throw new Error("FluxFiles: malformed token");
+  const [header, body, sig] = parts;
+  const alg = decodeSegment(header).alg;
+  if (alg !== "HS256") throw new Error(`FluxFiles: unexpected JWT alg "${alg}"`);
+  const expected = base64url(hmacSha256(`${header}.${body}`, key));
+  if (!safeEqual(sig, expected)) throw new Error("FluxFiles: invalid token signature");
+  const claims = decodeSegment(body);
+  if (typeof claims.exp === "number" && claims.exp < Math.floor(Date.now() / 1e3)) {
+    throw new Error("FluxFiles: token has expired");
+  }
+  return claims;
+}
+export {
+  createByobToken,
+  createToken,
+  decodeToken,
+  verifyToken
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@fluxfiles/node",
+  "version": "0.1.0",
+  "description": "Server-side Node/TypeScript SDK for minting FluxFiles JWTs (plain + BYOB), byte-compatible with the PHP core",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.8"
+  },
+  "author": "thai-pc",
+  "homepage": "https://github.com/thai-pc/fluxfiles#node-server-side-token-sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thai-pc/fluxfiles.git",
+    "directory": "packages/node"
+  },
+  "bugs": {
+    "url": "https://github.com/thai-pc/fluxfiles/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "fluxfiles",
+    "jwt",
+    "token",
+    "file-manager",
+    "s3",
+    "r2",
+    "byob",
+    "server"
+  ]
+}

package/src/crypto.ts

@@ -0,0 +1,69 @@
+import {
+  createHmac,
+  hkdfSync,
+  randomBytes,
+  createCipheriv,
+  createDecipheriv,
+  timingSafeEqual,
+} from 'node:crypto';
+
+/** base64url-encode without padding (JWT segment encoding). */
+export function base64url(input: Buffer | string): string {
+  return Buffer.from(input).toString('base64url');
+}
+
+export function hmacSha256(data: string, secret: string): Buffer {
+  return createHmac('sha256', secret).update(data).digest();
+}
+
+/** Constant-time comparison of two base64url signatures. */
+export function safeEqual(a: string, b: string): boolean {
+  const ba = Buffer.from(a);
+  const bb = Buffer.from(b);
+  return ba.length === bb.length && timingSafeEqual(ba, bb);
+}
+
+// ── BYOB credential encryption (matches PHP CredentialEncryptor) ──────────────
+// AES-256-GCM. Key = HKDF-SHA256(ikm = secret, salt = 32 zero bytes,
+// info = "fluxfiles-byob-enc", len = 32). Blob = base64(nonce[12] | ct | tag[16]).
+const BYOB_INFO = 'fluxfiles-byob-enc';
+const NONCE_LEN = 12;
+const TAG_LEN = 16;
+
+/**
+ * Derive the BYOB key exactly like PHP `hash_hkdf('sha256', $secret, 32, $info)`.
+ * PHP's empty HKDF salt means "HashLen zero bytes" (RFC 5869), so we pass an
+ * explicit 32-byte zero salt — passing an empty Buffer to Node's hkdfSync would
+ * NOT match.
+ */
+function deriveByobKey(secret: string): Buffer {
+  const salt = Buffer.alloc(32, 0);
+  const dk = hkdfSync('sha256', Buffer.from(secret, 'utf8'), salt, Buffer.from(BYOB_INFO, 'utf8'), 32);
+  return Buffer.from(dk);
+}
+
+export function encryptByob(config: unknown, secret: string): string {
+  const key = deriveByobKey(secret);
+  const nonce = randomBytes(NONCE_LEN);
+  const cipher = createCipheriv('aes-256-gcm', key, nonce, { authTagLength: TAG_LEN });
+  // JSON.stringify does not escape "/", matching PHP's JSON_UNESCAPED_SLASHES.
+  const plaintext = JSON.stringify(config);
+  const ct = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([nonce, ct, tag]).toString('base64');
+}
+
+export function decryptByob<T = unknown>(blob: string, secret: string): T {
+  const key = deriveByobKey(secret);
+  const raw = Buffer.from(blob, 'base64');
+  if (raw.length < NONCE_LEN + TAG_LEN + 1) {
+    throw new Error('FluxFiles: invalid BYOB credential blob');
+  }
+  const nonce = raw.subarray(0, NONCE_LEN);
+  const tag = raw.subarray(raw.length - TAG_LEN);
+  const ct = raw.subarray(NONCE_LEN, raw.length - TAG_LEN);
+  const decipher = createDecipheriv('aes-256-gcm', key, nonce, { authTagLength: TAG_LEN });
+  decipher.setAuthTag(tag);
+  const pt = Buffer.concat([decipher.update(ct), decipher.final()]).toString('utf8');
+  return JSON.parse(pt) as T;
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export { createToken, createByobToken } from './token';
+export { verifyToken, decodeToken } from './verify';
+export type {
+  CreateTokenOptions,
+  CreateByobTokenOptions,
+  ByobDiskConfig,
+  BaseTokenOptions,
+  FluxPermission,
+  FluxClaims,
+} from './types';

package/src/token.ts

@@ -0,0 +1,100 @@
+import { randomBytes } from 'node:crypto';
+import { base64url, hmacSha256, encryptByob } from './crypto';
+import type { ByobDiskConfig, CreateByobTokenOptions, CreateTokenOptions } from './types';
+
+const MIN_SECRET_BYTES = 32;
+
+function resolveSecret(explicit?: string): string {
+  const secret = explicit ?? process.env.FLUXFILES_SECRET ?? '';
+  if (Buffer.byteLength(secret, 'utf8') < MIN_SECRET_BYTES) {
+    throw new Error(
+      `FluxFiles: signing secret must be at least ${MIN_SECRET_BYTES} bytes ` +
+        '(HS256 key requirement). Set `secret` or FLUXFILES_SECRET.',
+    );
+  }
+  return secret;
+}
+
+/** Sign a payload as a compact HS256 JWT. */
+function sign(payload: Record<string, unknown>, secret: string): string {
+  const header = base64url(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+  const body = base64url(JSON.stringify(payload));
+  const sig = base64url(hmacSha256(`${header}.${body}`, secret));
+  return `${header}.${body}.${sig}`;
+}
+
+function newJti(): string {
+  return randomBytes(12).toString('hex');
+}
+
+/**
+ * Mint a standard FluxFiles JWT. The payload mirrors the PHP `fluxfiles_token()`
+ * helper exactly, so the FluxFiles core decodes it natively.
+ */
+export function createToken(opts: CreateTokenOptions): string {
+  const secret = resolveSecret(opts.secret);
+  const now = Math.floor(Date.now() / 1000);
+  const payload: Record<string, unknown> = {
+    sub: opts.userId,
+    iat: now,
+    exp: now + (opts.ttl ?? 3600),
+    jti: newJti(),
+    perms: opts.perms ?? ['read'],
+    disks: opts.disks ?? ['local'],
+    prefix: opts.prefix ?? '',
+    max_upload: opts.maxUploadMb ?? 10,
+    allowed_ext: opts.allowedExt ?? null,
+    max_storage: opts.maxStorageMb ?? 0,
+    max_files: opts.maxFiles ?? 0,
+  };
+  if (opts.ownerOnly) payload.owner_only = true;
+  return sign(payload, secret);
+}
+
+/**
+ * Mint a BYOB token. Each disk's S3-compatible credentials are AES-256-GCM
+ * encrypted into the token (decrypted only at runtime by the server). Mirrors
+ * the PHP `fluxfiles_byob_token()` helper.
+ */
+export function createByobToken(opts: CreateByobTokenOptions): string {
+  const secret = resolveSecret(opts.secret);
+  const now = Math.floor(Date.now() / 1000);
+
+  const encrypted: Record<string, string> = {};
+  const names: string[] = [];
+  for (const [name, config] of Object.entries(opts.byobDisks)) {
+    validateByobDisk(name, config);
+    encrypted[name] = encryptByob(config, secret);
+    names.push(name);
+  }
+
+  const payload: Record<string, unknown> = {
+    sub: opts.userId,
+    iat: now,
+    exp: now + (opts.ttl ?? 1800),
+    jti: newJti(),
+    perms: opts.perms ?? ['read', 'write'],
+    disks: names,
+    prefix: opts.prefix ?? '',
+    max_upload: opts.maxUploadMb ?? 10,
+    allowed_ext: opts.allowedExt ?? null,
+    byob_disks: encrypted,
+  };
+  if (opts.ownerOnly) payload.owner_only = true;
+  return sign(payload, secret);
+}
+
+/**
+ * Light client-side validation. The server independently re-validates (incl.
+ * SSRF checks on the endpoint), so this only catches obvious mistakes early.
+ */
+function validateByobDisk(name: string, config: ByobDiskConfig): void {
+  if (!config || config.driver !== 's3') {
+    throw new Error(`FluxFiles BYOB disk "${name}": driver must be "s3" (the server rejects "local").`);
+  }
+  for (const field of ['key', 'secret', 'bucket'] as const) {
+    if (!config[field]) {
+      throw new Error(`FluxFiles BYOB disk "${name}": missing required "${field}".`);
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,68 @@
+/** A FluxFiles permission. */
+export type FluxPermission = 'read' | 'write' | 'delete';
+
+/**
+ * A BYOB (Bring Your Own Bucket) disk config. Encrypted into the JWT and
+ * decrypted only at runtime by the FluxFiles server. Only S3-compatible
+ * storage is allowed — the server rejects the `local` driver.
+ */
+export interface ByobDiskConfig {
+  driver: 's3';
+  key: string;
+  secret: string;
+  bucket: string;
+  region?: string;
+  /** Custom S3 endpoint (R2, MinIO, Spaces, …). Omit for native AWS S3. */
+  endpoint?: string;
+  visibility?: 'private' | 'public';
+  /** Public base URL for direct (unsigned) object links on a public disk. */
+  public_url?: string;
+}
+
+/** Options shared by all token builders. */
+export interface BaseTokenOptions {
+  /** HS256 signing secret. Defaults to `process.env.FLUXFILES_SECRET`. Must be ≥ 32 bytes. */
+  secret?: string;
+  /** Subject — your application's user id. */
+  userId: string;
+  perms?: FluxPermission[];
+  /** Path prefix the user is scoped to (e.g. `users/42`). */
+  prefix?: string;
+  maxUploadMb?: number;
+  /** Allowed extensions (lowercase, no dot). `null`/omitted = all non-dangerous types. */
+  allowedExt?: string[] | null;
+  /** Time-to-live in seconds. */
+  ttl?: number;
+  /** Restrict destructive ops to files the user uploaded. */
+  ownerOnly?: boolean;
+}
+
+export interface CreateTokenOptions extends BaseTokenOptions {
+  /** Disk names the token may access. */
+  disks?: string[];
+  maxStorageMb?: number;
+  /** Total file count cap under the prefix. `0` = unlimited. */
+  maxFiles?: number;
+}
+
+export interface CreateByobTokenOptions extends BaseTokenOptions {
+  /** Map of disk name → S3-compatible credentials, encrypted into the token. */
+  byobDisks: Record<string, ByobDiskConfig>;
+}
+
+/** Decoded JWT payload (snake_case, as emitted by the PHP core). */
+export interface FluxClaims {
+  sub: string;
+  iat: number;
+  exp: number;
+  jti: string;
+  perms: string[];
+  disks: string[];
+  prefix: string;
+  max_upload: number;
+  allowed_ext: string[] | null;
+  max_storage?: number;
+  max_files?: number;
+  owner_only?: boolean;
+  byob_disks?: Record<string, string>;
+}

package/src/verify.ts

@@ -0,0 +1,41 @@
+import { base64url, hmacSha256, safeEqual } from './crypto';
+import type { FluxClaims } from './types';
+
+function decodeSegment<T>(seg: string): T {
+  return JSON.parse(Buffer.from(seg, 'base64url').toString('utf8')) as T;
+}
+
+/**
+ * Decode a token WITHOUT verifying the signature. Useful for inspection/logging;
+ * never trust the result for authorization — use {@link verifyToken}.
+ */
+export function decodeToken(token: string): FluxClaims {
+  const parts = token.split('.');
+  if (parts.length !== 3) throw new Error('FluxFiles: malformed token');
+  return decodeSegment<FluxClaims>(parts[1]);
+}
+
+/**
+ * Verify an HS256 FluxFiles token: signature + expiry. Returns the decoded
+ * claims, or throws on a bad signature, wrong algorithm, or an expired token.
+ */
+export function verifyToken(token: string, secret?: string): FluxClaims {
+  const key = secret ?? process.env.FLUXFILES_SECRET ?? '';
+  if (!key) throw new Error('FluxFiles: no secret provided to verifyToken');
+
+  const parts = token.split('.');
+  if (parts.length !== 3) throw new Error('FluxFiles: malformed token');
+  const [header, body, sig] = parts;
+
+  const alg = decodeSegment<{ alg?: string }>(header).alg;
+  if (alg !== 'HS256') throw new Error(`FluxFiles: unexpected JWT alg "${alg}"`);
+
+  const expected = base64url(hmacSha256(`${header}.${body}`, key));
+  if (!safeEqual(sig, expected)) throw new Error('FluxFiles: invalid token signature');
+
+  const claims = decodeSegment<FluxClaims>(body);
+  if (typeof claims.exp === 'number' && claims.exp < Math.floor(Date.now() / 1000)) {
+    throw new Error('FluxFiles: token has expired');
+  }
+  return claims;
+}