fluxfiles-token 0.1.0__tar.gz

fluxfiles_token-0.1.0/.gitignore

@@ -0,0 +1,110 @@
+# Dependencies
+vendor/
+node_modules/
+# …but the vendored front-end lib we ship on purpose (xterm.js for the SFTP
+# terminal) must be committed — it's served as a static asset, not installed.
+!packages/core/assets/vendor/
+!packages/core/assets/vendor/**
+
+# Environment
+.env
+# Adapter-e2e .env backup (global-setup restores the real one in teardown)
+packages/core/.env.adapter-e2e.bak
+
+# Storage
+storage/uploads/
+storage/rate_limit.json
+
+# Core package storage (runtime/test artifacts)
+packages/core/storage/uploads/
+packages/core/storage/rate_limit.json
+packages/core/storage/demo_ip.json
+
+# Build output
+packages/react/dist/
+packages/vue/dist/
+packages/node/dist/
+build/
+
+# Python (packages/python)
+packages/python/.venv/
+packages/python/dist/
+packages/python/*.egg-info/
+**/__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Test playground scaffolds (source committed, deps not)
+packages/core/tests/apps/**/node_modules/
+packages/core/tests/apps/node_modules/
+# Generated Laravel proxy e2e app (regenerate: laravel-e2e/setup.sh; source in laravel-e2e/)
+packages/core/tests/apps/laravel-app/
+
+# Playwright runtime artifacts
+.playwright-mcp/
+test-results/
+playwright-report/
+# Ad-hoc QA screenshots taken at the repo root during manual browser testing
+# (never part of the source — they slipped in once; keep them out for good).
+/*.png
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+coverage/
+.phpunit.result.cache
+.phpunit.cache/
+
+# Logs
+*.log
+
+# Project docs (private)
+docs/FLUXFILES-ROADMAP.md
+docs/ROADMAP.md
+# Wrapper lockfiles aren't needed for published libs and break cross-platform
+# npm optional-dep resolution (npm/cli#4828). CI does a fresh install.
+packages/sdk/package-lock.json
+packages/ckeditor4/package-lock.json
+packages/tinymce/package-lock.json
+docs/PHASE2-OPTIMIZATION-PLAN.md
+docs/COMMERCIAL-STRATEGY.md
+docs/LICENSING-PLAN.md
+docs/*.SECRET.txt
+docs/license-signing-key*
+docs/release-signing-key*
+docs/*.key
+
+# Proprietary paid modules (private — not part of the MIT core; each lives in its
+# own private repo for distribution). NEVER commit these to the public monorepo.
+packages/optimize/
+packages/share/
+packages/intake/
+packages/versioning/
+packages/webhooks/
+packages/ai/
+packages/ocr/
+packages/virus/
+packages/backup/
+packages/c2pa/
+packages/audit-export/
+packages/sso/
+packages/dlp/
+packages/legal-hold/
+
+# License server runtime DB (customer records — never commit)
+services/license-server/data/
+*.sqlite
+*.sqlite-*
+
+# Claude subagent working artifacts (plans, review findings)
+.claude/work/

fluxfiles_token-0.1.0/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.

fluxfiles_token-0.1.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.5
+Name: fluxfiles-token
+Version: 0.1.0
+Summary: Server-side Python SDK for minting FluxFiles JWTs (plain + BYOB), byte-compatible with the PHP core and @fluxfiles/node
+Project-URL: Homepage, https://github.com/thai-pc/fluxfiles#python-server-side-token-sdk
+Project-URL: Repository, https://github.com/thai-pc/fluxfiles
+Project-URL: Issues, https://github.com/thai-pc/fluxfiles/issues
+Author: thai-pc
+License: MIT
+License-File: LICENSE
+Keywords: byob,file-manager,fluxfiles,jwt,r2,s3,server,token
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42
+Requires-Dist: pyjwt<3,>=2.8
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# FluxFiles for Python (server-side token SDK)
+
+Mint [FluxFiles](https://github.com/thai-pc/fluxfiles) JWTs from any Python
+backend (Django, FastAPI, Flask, …). 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.
+
+> **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-token` simply removes the need for *your app* to be PHP in order
+> to mint those tokens.
+
+## Requirements
+
+- Python 3.10+
+- 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.
+
+## Installation
+
+```bash
+pip install fluxfiles-token
+```
+
+## Usage
+
+### Mint a token
+
+```python
+from fluxfiles_token import create_token
+
+token = create_token(
+    user_id="user-42",
+    perms=["read", "write"],
+    disks=["local", "s3"],
+    prefix="users/42",       # scope the user to their own directory
+    max_upload_mb=25,
+    allowed_ext=["png", "jpg", "pdf"],
+    ttl=3600,                # seconds
+    # secret=...,            # or omit to read FLUXFILES_SECRET from the environment
+)
+```
+
+### Role & edition presets
+
+Mint-time-only DX sugar — they expand into ordinary claims and are never
+themselves a JWT claim. Explicit kwargs always win over a preset default.
+
+```python
+from fluxfiles_token import create_token
+
+# perms=["read", "write"], owner_only=True, allow_extract=True,
+# allow_chmod=False (the "editor" bundle).
+token = create_token(user_id="user-42", role="editor")
+
+# Every module claim the "enterprise" edition grants — license/module
+# install are still the real gate; a preset just defaults the per-tenant claim.
+token = create_token(user_id="tenant-9", edition="enterprise")
+```
+
+### Enable Import from URL
+
+Import-from-URL is **off by default**. Turn it on for a token by setting the
+import options — no server-side per-tenant config is needed:
+
+```python
+token = create_token(
+    user_id="user-42",
+    perms=["read", "write"],
+    allow_url_import=True,                     # required — enables the feature
+    max_import_mb=20,                          # optional — cap per import (MB)
+    import_url_allowlist=["*.unsplash.com"],   # optional — restrict source hosts
+    # import_path, import_rate_limit, import_concurrency also supported
+)
+```
+
+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):
+
+```python
+token = create_token(
+    user_id="admin-7",
+    perms=["read", "write"],
+    disks=["sftp"],           # an SFTP disk configured on the FluxFiles server
+    allow_chmod=True,         # cPanel-style permissions (default on for SFTP)
+    allow_terminal=True,      # SSH terminal — opt-in, off by default
+)
+```
+
+These are **standalone-core** features: `fluxfiles-token` 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
+
+```python
+import os
+from fluxfiles_token import create_byob_token
+
+token = create_byob_token(
+    user_id="user-42",
+    byob_disks={
+        "my-s3": {
+            "driver": "s3",
+            "key": os.environ["USER_AWS_KEY"],
+            "secret": os.environ["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). `role`/`edition` presets are supported on BYOB tokens too.
+
+### Verify / decode (optional)
+
+```python
+from fluxfiles_token import verify_token, decode_token
+
+claims = verify_token(token)   # checks HS256 signature + expiry, raises on failure
+peek = decode_token(token)     # decode only, NO verification — never trust for auth
+```
+
+### Django view
+
+```python
+from django.http import JsonResponse
+from fluxfiles_token import create_token
+
+def fluxfiles_token_view(request):
+    token = create_token(
+        user_id=str(request.user.id),
+        perms=["read", "write"],
+        prefix=f"users/{request.user.id}",
+    )
+    return JsonResponse({"token": token})
+```
+
+### FastAPI route
+
+```python
+from fastapi import APIRouter, Depends
+from fluxfiles_token import create_token
+
+router = APIRouter()
+
+@router.get("/fluxfiles/token")
+def fluxfiles_token(user=Depends(get_current_user)):
+    return {"token": create_token(user_id=user.id, perms=["read", "write"])}
+```
+
+## API
+
+| Function | Description |
+|----------|-------------|
+| `create_token(**opts)` | Standard token. Mirrors PHP `fluxfiles_token()`. |
+| `create_byob_token(**opts)` | Token with encrypted BYOB disk credentials. Mirrors `fluxfiles_byob_token()`. |
+| `verify_token(token, secret=None)` | Verify HS256 signature + expiry; returns decoded claims or raises. |
+| `decode_token(token)` | Decode without verifying (inspection/logging only). |
+
+`create_token` keyword arguments: `secret=None`, `user_id`, `perms=None`,
+`disks=None`, `prefix=None`, `max_upload_mb=None`, `allowed_ext=None`,
+`ttl=None`, `owner_only=None`, `max_storage_mb=None`, `max_files=None`,
+`edition=None`, `role=None`. Per-tenant overrides (omit to inherit the server
+default): `ai_auto_tag=None` (bool), `rate_read=None` / `rate_write=None`
+(req/min), `variants=None` (`{"thumb": .., "medium": .., "large": ..}` px),
+and every other `allow_*`/module claim documented in
+[`docs/CONFIG.md`](https://github.com/thai-pc/fluxfiles/blob/master/docs/CONFIG.md) —
+plus a `claims: dict` escape hatch for any claim by its raw snake_case name.
+`create_byob_token` replaces `disks` with `byob_disks` (a map of name →
+S3-compatible/SFTP config) and does not take `max_storage_mb`/`max_files`
+(matching the core), but accepts the same `role`/`edition`/per-tenant kwargs.
+
+## Compatibility
+
+Tokens and BYOB blobs are validated against the PHP core in CI: a
+Python-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#python-server-side-token-sdk`
+- Issues: `https://github.com/thai-pc/fluxfiles/issues`

fluxfiles_token-0.1.0/README.md

@@ -0,0 +1,206 @@
+# FluxFiles for Python (server-side token SDK)
+
+Mint [FluxFiles](https://github.com/thai-pc/fluxfiles) JWTs from any Python
+backend (Django, FastAPI, Flask, …). 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.
+
+> **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-token` simply removes the need for *your app* to be PHP in order
+> to mint those tokens.
+
+## Requirements
+
+- Python 3.10+
+- 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.
+
+## Installation
+
+```bash
+pip install fluxfiles-token
+```
+
+## Usage
+
+### Mint a token
+
+```python
+from fluxfiles_token import create_token
+
+token = create_token(
+    user_id="user-42",
+    perms=["read", "write"],
+    disks=["local", "s3"],
+    prefix="users/42",       # scope the user to their own directory
+    max_upload_mb=25,
+    allowed_ext=["png", "jpg", "pdf"],
+    ttl=3600,                # seconds
+    # secret=...,            # or omit to read FLUXFILES_SECRET from the environment
+)
+```
+
+### Role & edition presets
+
+Mint-time-only DX sugar — they expand into ordinary claims and are never
+themselves a JWT claim. Explicit kwargs always win over a preset default.
+
+```python
+from fluxfiles_token import create_token
+
+# perms=["read", "write"], owner_only=True, allow_extract=True,
+# allow_chmod=False (the "editor" bundle).
+token = create_token(user_id="user-42", role="editor")
+
+# Every module claim the "enterprise" edition grants — license/module
+# install are still the real gate; a preset just defaults the per-tenant claim.
+token = create_token(user_id="tenant-9", edition="enterprise")
+```
+
+### Enable Import from URL
+
+Import-from-URL is **off by default**. Turn it on for a token by setting the
+import options — no server-side per-tenant config is needed:
+
+```python
+token = create_token(
+    user_id="user-42",
+    perms=["read", "write"],
+    allow_url_import=True,                     # required — enables the feature
+    max_import_mb=20,                          # optional — cap per import (MB)
+    import_url_allowlist=["*.unsplash.com"],   # optional — restrict source hosts
+    # import_path, import_rate_limit, import_concurrency also supported
+)
+```
+
+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):
+
+```python
+token = create_token(
+    user_id="admin-7",
+    perms=["read", "write"],
+    disks=["sftp"],           # an SFTP disk configured on the FluxFiles server
+    allow_chmod=True,         # cPanel-style permissions (default on for SFTP)
+    allow_terminal=True,      # SSH terminal — opt-in, off by default
+)
+```
+
+These are **standalone-core** features: `fluxfiles-token` 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
+
+```python
+import os
+from fluxfiles_token import create_byob_token
+
+token = create_byob_token(
+    user_id="user-42",
+    byob_disks={
+        "my-s3": {
+            "driver": "s3",
+            "key": os.environ["USER_AWS_KEY"],
+            "secret": os.environ["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). `role`/`edition` presets are supported on BYOB tokens too.
+
+### Verify / decode (optional)
+
+```python
+from fluxfiles_token import verify_token, decode_token
+
+claims = verify_token(token)   # checks HS256 signature + expiry, raises on failure
+peek = decode_token(token)     # decode only, NO verification — never trust for auth
+```
+
+### Django view
+
+```python
+from django.http import JsonResponse
+from fluxfiles_token import create_token
+
+def fluxfiles_token_view(request):
+    token = create_token(
+        user_id=str(request.user.id),
+        perms=["read", "write"],
+        prefix=f"users/{request.user.id}",
+    )
+    return JsonResponse({"token": token})
+```
+
+### FastAPI route
+
+```python
+from fastapi import APIRouter, Depends
+from fluxfiles_token import create_token
+
+router = APIRouter()
+
+@router.get("/fluxfiles/token")
+def fluxfiles_token(user=Depends(get_current_user)):
+    return {"token": create_token(user_id=user.id, perms=["read", "write"])}
+```
+
+## API
+
+| Function | Description |
+|----------|-------------|
+| `create_token(**opts)` | Standard token. Mirrors PHP `fluxfiles_token()`. |
+| `create_byob_token(**opts)` | Token with encrypted BYOB disk credentials. Mirrors `fluxfiles_byob_token()`. |
+| `verify_token(token, secret=None)` | Verify HS256 signature + expiry; returns decoded claims or raises. |
+| `decode_token(token)` | Decode without verifying (inspection/logging only). |
+
+`create_token` keyword arguments: `secret=None`, `user_id`, `perms=None`,
+`disks=None`, `prefix=None`, `max_upload_mb=None`, `allowed_ext=None`,
+`ttl=None`, `owner_only=None`, `max_storage_mb=None`, `max_files=None`,
+`edition=None`, `role=None`. Per-tenant overrides (omit to inherit the server
+default): `ai_auto_tag=None` (bool), `rate_read=None` / `rate_write=None`
+(req/min), `variants=None` (`{"thumb": .., "medium": .., "large": ..}` px),
+and every other `allow_*`/module claim documented in
+[`docs/CONFIG.md`](https://github.com/thai-pc/fluxfiles/blob/master/docs/CONFIG.md) —
+plus a `claims: dict` escape hatch for any claim by its raw snake_case name.
+`create_byob_token` replaces `disks` with `byob_disks` (a map of name →
+S3-compatible/SFTP config) and does not take `max_storage_mb`/`max_files`
+(matching the core), but accepts the same `role`/`edition`/per-tenant kwargs.
+
+## Compatibility
+
+Tokens and BYOB blobs are validated against the PHP core in CI: a
+Python-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#python-server-side-token-sdk`
+- Issues: `https://github.com/thai-pc/fluxfiles/issues`

fluxfiles_token-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "fluxfiles-token"
+version = "0.1.0"
+description = "Server-side Python SDK for minting FluxFiles JWTs (plain + BYOB), byte-compatible with the PHP core and @fluxfiles/node"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "thai-pc" }]
+keywords = ["fluxfiles", "jwt", "token", "file-manager", "s3", "r2", "byob", "server"]
+dependencies = ["PyJWT>=2.8,<3", "cryptography>=42"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "mypy>=1.10", "ruff"]
+
+[project.urls]
+Homepage = "https://github.com/thai-pc/fluxfiles#python-server-side-token-sdk"
+Repository = "https://github.com/thai-pc/fluxfiles"
+Issues = "https://github.com/thai-pc/fluxfiles/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fluxfiles_token"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 110
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

fluxfiles_token-0.1.0/src/fluxfiles_token/__init__.py

@@ -0,0 +1,38 @@
+"""fluxfiles-token: mint and verify FluxFiles JWTs from Python.
+
+Byte-compatible with the PHP core (`packages/core/embed.php`,
+`CredentialEncryptor.php`) and a 1:1 port of `@fluxfiles/node`
+(camelCase -> snake_case). See docs/PYTHON-TOKEN-SDK-DESIGN.md.
+"""
+
+from .crypto import decrypt_byob, encrypt_byob
+from .exceptions import FluxFilesByobError, FluxFilesTokenError
+from .token import EDITION_PRESETS, ROLE_PRESETS, create_byob_token, create_token
+from .types import (
+    ByobDiskConfig,
+    ByobS3DiskConfig,
+    ByobSftpDiskConfig,
+    FluxClaims,
+    FluxPermission,
+)
+from .verify import decode_token, verify_token
+
+__all__ = [
+    "create_token",
+    "create_byob_token",
+    "verify_token",
+    "decode_token",
+    "encrypt_byob",
+    "decrypt_byob",
+    "ROLE_PRESETS",
+    "EDITION_PRESETS",
+    "FluxFilesTokenError",
+    "FluxFilesByobError",
+    "ByobDiskConfig",
+    "ByobS3DiskConfig",
+    "ByobSftpDiskConfig",
+    "FluxClaims",
+    "FluxPermission",
+]
+
+__version__ = "0.1.0"