Version v0.5.1

JSON API Forge v0.5.1

Release date: 29 August 2026

Status: Alpha security and delivery hardening release

License: JSON API Forge Source-Available Self-Host License 1.1 (LicenseRef-JAF-SASH-1.1)

v0.5.1 preserves the v0.5.0 application and visual-authoring contract while tightening untrusted-network, pattern-matching and package-delivery boundaries. main remains an example-free runtime; the python-library, Editor and exampleApps branches remain independently buildable distributions.

Security maintenance

• External JWKS retrieval now uses the same DNS-rebinding-resistant transport as controlled HTTP data sources, blocks private/link-local addresses by default, ignores ambient proxies, refuses redirects and caps response size/key count.
• Request patterns and JSON Schema pattern/patternProperties matching now use Pydantic Core's linear-time regex engine. Unsupported non-linear features fail at configuration load, and pattern-bearing request strings are bounded.
• CORS origins, HTTP header maps, data-source/JWKS URLs and WebRTC ICE settings reject ambiguous authorities, credentials, fragments and control-character injection.
• The TypeScript client rejects non-finite or excessive resource limits, raw/encoded controls, malformed methods and oversized credentials.
• The WebRTC call page declares its media mode before first use, restoring reliable startup.

Runtime and Editor boundary

• The disabled-by-default Editor control plane now supports graphs/*.forgegraph.json only when EDITOR_ALLOW_GRAPHS=true.
• Graph documents have exact fields, bounded node/edge counts, direct config targets, safe identifiers, unique input fan-in and acyclic execution.
• A graph is Editor metadata: compiled configuration must still pass the normal whole-project schema and semantic validation.
• Existing independent editor token, TLS, trusted-proxy/IP, project allowlist, read-only, creation, hook, size, optimistic-concurrency and atomic-write controls remain enforced.

Qt Editor

• C++20/Qt 6 code, typed visual and Unreal-inspired graph modes.
• Draggable nodes, Bézier wires, pan/zoom, selection/deletion, inspector JSON, validation, auto-layout, fit-to-content and compiled operation preview.
• Eight staged/atomic project templates and a Python SDK panel for sync, async, cluster, YoungLion and DDM usage.
• Native Plugin API v2 with explicit enablement, SHA-256 verification, declared permissions and plugin graph-node registration.
• A bounded catalog browser plus explicit ZIP import; archive paths, entry counts, compression ratios, extracted sizes, manifest/library digests and Plugin API compatibility are validated before staging.
• Imported native packages remain disabled until the user reviews and explicitly enables them.
• Native build/test artifacts for Linux, Windows and macOS on x64 and ARM64.

Python library

• Typed sync and async clients with capped retries, stable request IDs, bounded response/pagination behavior and attempt observers.
• Multi-region sync/async clusters with deterministic routing, circuit breaking, health inspection and bounded bulk work.
• Unsafe writes are not retried or failed over without an idempotency key.
• Optional json-api-forge[younglion] and json-api-forge[ddm] installs provide lazy DDM adapters without adding YoungLion to the base wheel.

Example systems

The exampleApps branch now contains 25 named projects. The 20 generated domain systems each include four SQL resources, three meaningful operations, scoped roles, cache/rate/protection policy, realtime events, an Editor graph and an application runbook. The full catalog is deterministically regenerated and tested across schema, CRUD, filtered list, RPC, idempotency and event lifecycles.

Required gates

Python 3.10–3.14, Ruff, branch coverage and critical-module gates, PostgreSQL 17, Redis 8, MongoDB 8, isolated wheel installation, TypeScript/Node 22, Docker, release-manifest verification and CodeQL must pass before an official tag. Editor artifacts additionally require six native CMake/Qt builds and tests; example artifacts require all 25 project smoke scenarios.

Compatibility and limits

Existing explicit app/<Project>/ numbered configurations remain the primary architecture. JSON API Forge remains Alpha: same-database idempotency is not external exactly-once delivery, realtime is not durable, local media is not shared object storage, native plugins are not sandboxed, and declarative SQL is trusted configuration rather than an attacker-safe SQL sandbox.

Official distribution

JSON API Forge is source-available for transparency, auditing, self-hosting and private modification. It is not OSI open source. Alternative distributions remain restricted by LICENSE; official release authority remains with Cavanşir Qurbanzadə (@Cavanshirpro) or a lawful successor/assignee.

Version v0.5.0

JSON API Forge v0.5.0

Release date: 18 August 2026

Status: Alpha visual-authoring and integration release

License: JSON API Forge Source-Available Self-Host License 1.1 (LicenseRef-JAF-SASH-1.1)

v0.5.0 preserves the strict numbered JSON/FastAPI runtime while making large projects easier to author and integrate. main remains an example-free runtime; the python-library, Editor and exampleApps branches are independently buildable distributions.

Runtime and Editor boundary

• The disabled-by-default Editor control plane now supports graphs/*.forgegraph.json only when EDITOR_ALLOW_GRAPHS=true.
• Graph documents have exact fields, bounded node/edge counts, direct config targets, safe identifiers, unique input fan-in and acyclic execution.
• A graph is Editor metadata: compiled configuration must still pass the normal whole-project schema and semantic validation.
• Existing independent editor token, TLS, trusted-proxy/IP, project allowlist, read-only, creation, hook, size, optimistic-concurrency and atomic-write controls remain enforced.

Qt Editor

• C++20/Qt 6 code, typed visual and Unreal-inspired graph modes.
• Draggable nodes, Bézier wires, pan/zoom, selection/deletion, inspector JSON, validation, auto-layout, fit-to-content and compiled operation preview.
• Eight staged/atomic project templates and a Python SDK panel for sync, async, cluster, YoungLion and DDM usage.
• Native Plugin API v2 with explicit enablement, SHA-256 verification, declared permissions and plugin graph-node registration.
• A bounded catalog browser backed by a normal JSON API Forge resource; native packages are never silently downloaded or executed.
• Native build/test artifacts for Linux, Windows and macOS on x64 and ARM64.

Python library

• Typed sync and async clients with capped retries, stable request IDs, bounded response/pagination behavior and attempt observers.
• Multi-region sync/async clusters with deterministic routing, circuit breaking, health inspection and bounded bulk work.
• Unsafe writes are not retried or failed over without an idempotency key.
• Optional json-api-forge[younglion] and json-api-forge[ddm] installs provide lazy DDM adapters without adding YoungLion to the base wheel.

Example systems

The exampleApps branch now contains 25 named projects. The 20 generated domain systems each include four SQL resources, three meaningful operations, scoped roles, cache/rate/protection policy, realtime events, an Editor graph and an application runbook. The full catalog is deterministically regenerated and tested across schema, CRUD, filtered list, RPC, idempotency and event lifecycles.

Required gates

Python 3.11–3.14, Ruff, branch coverage and critical-module gates, PostgreSQL 17, Redis 8, MongoDB 8, isolated wheel installation, TypeScript/Node 22, Docker, release-manifest verification and CodeQL must pass before an official tag. Editor artifacts additionally require six native CMake/Qt builds and tests; example artifacts require all 25 project smoke scenarios.

Compatibility and limits

Existing explicit app/<Project>/ numbered configurations remain the primary architecture. JSON API Forge remains Alpha: same-database idempotency is not external exactly-once delivery, realtime is not durable, local media is not shared object storage, native plugins are not sandboxed, and declarative SQL is trusted configuration rather than an attacker-safe SQL sandbox.

Official distribution

JSON API Forge is source-available for transparency, auditing, self-hosting and private modification. It is not OSI open source. Alternative distributions remain restricted by LICENSE; official release authority remains with Cavanşir Qurbanzadə (@Cavanshirpro) or a lawful successor/assignee.

Version v0.4.0

JSON API Forge v0.4.0

Release date: 8 August 2026
Status: Alpha hardening release
License: JSON API Forge Source-Available Self-Host License 1.1 (LicenseRef-JAF-SASH-1.1)

v0.4.0 is a security, reliability, architecture and developer-experience release. It intentionally slows broad feature expansion and strengthens the config-first FastAPI runtime introduced in v0.1–v0.3.

Why this release exists

An external review of v0.3.0 correctly identified several areas where feature breadth had outpaced production confidence: unsafe placeholder-secret onboarding, idempotency crash semantics, high-cardinality rate-limit keys, permissive defaults for newer endpoint types, limited critical-path test coverage, a monolithic application factory, incomplete request-body enforcement and insufficient release gates.

v0.4.0 addresses those issues directly rather than hiding them behind additional feature packs.

Security and correctness highlights

• No usable default admin/JWT secrets. .env.example contains blank secret slots; forge init generates strong values and writes .env with restrictive permissions where supported.
• Production secret validation. forge doctor --production reports missing/weak secrets and unsafe production choices. Production startup can fail fast on invalid configuration.
• One-time bootstrap administration. Bootstrap consumption and first durable API-key creation share one internal-database transaction; concurrent first-admin attempts cannot both succeed.
• Private by default. SQL/RPC operations, custom endpoints, data sources and event publish/subscribe directions require permissions unless an explicit public opt-in is configured.
• Transactional idempotency. Idempotency records for SQL operations live in the same business database and transaction as the protected side effects. Canonical request fingerprints detect reuse of an idempotency key with a different payload.
• Bounded rate limiting. Principal-global budgets no longer depend on raw high-cardinality URL paths; optional normalized route-template budgets are supported. In-memory buckets expire and are capped.
• WebSocket message throttling. Event channels can enforce limits after connection establishment, not only during handshake.
• Streaming request-size enforcement. ASGI receive chunks are counted even when Content-Length is absent or misleading.
• Route collision diagnostics. forge doctor detects conflicting generated method/path pairs before deployment.
• Strict declarative models. Unknown configuration keys are rejected instead of being silently ignored.
• Project-scoped local JWT secrets. JWT is opt-in by default; local-HS256 apps can use independent signing secrets instead of sharing one process-wide key.
• Safer upstream retries. Permanent 4xx responses are not retried; POST/PATCH mutation retries require explicit opt-in and an upstream idempotency contract.
• Realtime/cache/media edge hardening. Redis listener readiness is synchronized, slow WebSocket clients are isolated by bounded outbound queues, cache single-flight lock state is reclaimed, and media API metadata no longer exposes physical storage keys; dedup defaults to owner scope and owner quotas use an atomic usage ledger.
• Row-level authorization boundaries. SQL and Mongo resources can bind rows to the authenticated principal in addition to tenant scoping; tenant/owner/soft-delete policy fields are server-controlled.
• Credential delegation containment. Child API keys/JWTs cannot exceed the caller's roles, permissions, tenant, expiry, rate budget or subject authority without explicit high-trust delegation/impersonation permission. Revocation follows the same containment model.
• Reverse-proxy trust isolation. Forwarded IP/protocol values are accepted only from configured trusted proxy CIDRs; official Uvicorn launch paths keep independent proxy rewriting disabled.
• Operator trust boundary. Process-wide metrics and detailed readiness use a separate operator token rather than reusing one project's admin credential.
• Bounded API-key lookup cache. Successful key metadata may be cached briefly per worker to reduce internal-DB pressure; same-worker create/revoke invalidates immediately and cross-worker staleness is bounded by the configured TTL.

Architecture

• Added framework/runtime.py to own project-scoped SQL, MongoDB, cache, rate-limit, events, media and lifecycle services, with exception-safe partial-startup cleanup.
• Moved project route construction into framework/routers/ and significantly reduced responsibility in framework/factory.py.
• Added focused CLI, doctor and schema modules so application construction is no longer the only place configuration correctness is discovered.
• Preserved the existing app/App1/config/10-*.json numbered-fragment model and Python hooks as the escape hatch for real business logic.

Developer experience

New/expanded CLI surface:

forge init
forge new MyApp --preset minimal
forge dev
forge validate
forge doctor
forge doctor --production
forge routes
forge openapi
forge schema
forge migrate
forge secrets

v0.4.0 also includes:

• generated JSON Schemas for project manifests and fragments;
• VS Code schema associations;
• stricter typed Pydantic configuration models;
• progressive documentation beginning with docs/00-Start-Here.md;
• starter presets for minimal, PostgreSQL API, Discord bot and game-backend projects;
• a strict TypeScript reference client in addition to the Python client;
• pyproject.toml packaging and console entry points;
• Dockerfile and an example PostgreSQL/Redis/MongoDB Compose stack.

Testing and release gates

The repository now contains substantially broader unit/component/integration coverage for configuration, CRUD helpers, SQL operations, idempotency, rate limiting, request protection, cache behavior, data sources, MongoDB helpers, media, events, audit behavior, CLI/DX and failure paths.

CI is configured to require:

• Python 3.11, 3.12, 3.13 and 3.14 test jobs;

• =75% aggregate branch-aware coverage, >=80% for high-risk critical runtime modules, and an explicit >=75% floor for the large generated project-router assembly surface;

• package build checks;
• PostgreSQL + Redis + MongoDB live-service tests;
• TypeScript client type checking;
• Docker image build;
• a tag-only release gate dependent on all of the above.

A green workflow run is still required before this release should be described as validated on GitHub infrastructure.

Migration notes

This release intentionally changes some permissive v0.3 behavior. Read:

• docs/21-v0.4-Hardening-and-Migration.md
• docs/25-Security-Threat-Model.md
• docs/27-Production-Readiness-Matrix.md

before upgrading a security-sensitive deployment. Production deployments should run forge migrate explicitly and can then use support-schema validate mode to avoid routine runtime DDL.

Known boundaries

• JSON API Forge remains Alpha. This release should not be advertised as universally production-ready.
• Transactional idempotency protects side effects in the selected SQL database; it cannot make an external HTTP API, Discord action, email send or second database atomically exactly-once. Use outbox/inbox or provider idempotency for cross-system workflows.
• v0.4 implements local filesystem media only. Horizontal media deployments require an external/shared storage architecture or a future real object-storage adapter; unsupported backends are not accepted as valid configuration.
• SQL safety checks are trusted-configuration guardrails, not an SQL sandbox for attacker-controlled statements.
• cPanel/Passenger remains useful for conventional HTTP deployments; native ASGI is preferred for sustained WebSocket/SSE workloads.

License

JSON API Forge is source-available for transparency, auditing, self-hosting and private modification. It is not OSI open source. Alternative public or private distributions of the framework are restricted by LICENSE. Official distribution remains centralized under Cavanşir Qurbanzadə (@Cavanshirpro) or a lawful successor/assignee.

Version v0.3.0

JSON API Forge v0.3.0

Release date: 7 August 2026
Status: Current release
License: JSON API Forge Source-Available Self-Host License 1.1 (LicenseRef-JAF-SASH-1.1)

Declarative backend runtime with SQL/RPC operations, data sources, realtime, MongoDB, Supabase Auth and expanded FastAPI surfaces.

Highlights

• Declarative SQL/RPC operations with bind parameters, transactions, row-count guards and idempotency.
• JSON, YAML and CSV file data sources plus controlled outbound HTTP/API gateway sources.
• Expanded declarative FastAPI endpoints, parameters, dependencies, validation, response types and OpenAPI metadata.
• WebSocket and Server-Sent Events channels with memory or Redis pub/sub backends.
• Async MongoDB resources using PyMongo AsyncMongoClient and external JWKS/Supabase Auth validation.
• Distributed cache locks, tiered cache, operation invalidation, rate limits and overload protection.
• Media quotas and signed temporary URLs, Prometheus metrics and stronger readiness checks.
• Generic async Python client SDK plus a Discord economy/PostgreSQL example.

Installation

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env

Generate strong secrets before starting the server. Never use the placeholder values from .env.example in production.

Validate this release

python forge.py validate
python forge.py routes
python -m compileall -q framework app clients examples
pytest -q

Known boundaries

• S3-compatible object-storage adapters are intentionally not claimed as implemented in this release.
• Heavy distributed jobs should use an external queue/worker architecture rather than FastAPI BackgroundTasks.
• Native ASGI deployment is recommended for high-concurrency WebSocket/SSE workloads.
• Security-critical business invariants still require carefully designed operations/hooks and tests.

License model

The source is public for transparency, review and auditing, and official releases may be self-hosted and privately modified. This is not an OSI-approved open-source license: redistribution of JSON API Forge or modified/alternative versions is not permitted except for the narrow contribution-fork exception described in LICENSE.

Read LICENSE, LICENSE-FAQ.md, NOTICE.md and GOVERNANCE.md before redistribution-related use.

GitHub Release asset

Attach the Project-Owner-published JSON-API-Forge-v0.3.0-GitHub.zip archive to the GitHub Release if you want a canonical downloadable artifact in addition to GitHub's automatically generated source archives.

Version v0.2.0

JSON API Forge v0.2.0

Release date: 7 August 2026
Status: Historical release
License: JSON API Forge Source-Available Self-Host License 1.1 (LicenseRef-JAF-SASH-1.1)

Multi-project runtime with production-oriented cache, rate limits, media and application feature packs.

Highlights

• Multiple independent applications under app// with mergeable JSON fragments.
• Per-project API prefixes, databases, credentials, roles, CORS policies and feature packs.
• Memory, Redis and tiered L1/L2 caches with generation-based invalidation.
• Token-bucket rate limiting, per-key traffic budgets and concurrency/backpressure protection.
• Database connection-pool tuning, readiness checks and batched asynchronous audit writes.
• Media APIs with streaming upload, MIME/size policies, hashing and deduplication.
• Messaging, social-media and gaming resource packs.
• Cursor/keyset pagination and resilient outbound HTTP client foundation.

Installation

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env

Generate strong secrets before starting the server. Never use the placeholder values from .env.example in production.

Validate this release

python scripts/validate_config.py
python -m compileall -q framework app
pytest -q

Known boundaries

• The declarative SQL/RPC operation engine and arbitrary JSON/YAML/CSV data sources arrive in v0.3.0.
• Realtime WebSocket/SSE channels and external JWKS/Supabase Auth integration arrive in v0.3.0.
• Local filesystem is the implemented media storage backend in this release.
• For serious WebSocket/realtime scale, use native ASGI rather than the cPanel WSGI bridge.

License model

The source is public for transparency, review and auditing, and official releases may be self-hosted and privately modified. This is not an OSI-approved open-source license: redistribution of JSON API Forge or modified/alternative versions is not permitted except for the narrow contribution-fork exception described in LICENSE.

Read LICENSE, LICENSE-FAQ.md, NOTICE.md and GOVERNANCE.md before redistribution-related use.

GitHub Release asset

Attach the Project-Owner-published JSON-API-Forge-v0.2.0-GitHub.zip archive to the GitHub Release if you want a canonical downloadable artifact in addition to GitHub's automatically generated source archives.

Version v0.1.0

JSON API Forge v0.1.0

Release date: 7 August 2026
Status: Historical release
License: JSON API Forge Source-Available Self-Host License 1.1 (LicenseRef-JAF-SASH-1.1)

Initial configuration-driven FastAPI backend foundation.

Highlights

• Configuration-driven FastAPI application factory and automatic OpenAPI documentation.
• Async SQLAlchemy support for PostgreSQL/Supabase, MySQL/MariaDB and SQLite.
• Multiple database aliases and JSON-declared/reflected resources.
• API-key authentication, bootstrap administrator key, RBAC, wildcard permissions and role inheritance.
• Declarative CRUD policies, filtering, sorting, pagination, tenant columns and optional soft deletion.
• Custom Python hooks for business logic that should not be represented as generic JSON.
• Request IDs, security headers, CORS, in-memory rate limiting and cPanel Passenger compatibility.

Installation

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env

Generate strong secrets before starting the server. Never use the placeholder values from .env.example in production.

Validate this release

python scripts/validate_config.py
python -m compileall -q framework app
pytest -q

Known boundaries

• Single-project configuration model under app/config/.
• Rate limiting is primarily process-local; distributed Redis-based controls arrive in v0.2.0.
• Media, messaging/social/gaming packs, advanced cache layers and multi-project isolation are not part of this release.
• Use Alembic or another explicit migration workflow for long-lived production schemas.

License model

The source is public for transparency, review and auditing, and official releases may be self-hosted and privately modified. This is not an OSI-approved open-source license: redistribution of JSON API Forge or modified/alternative versions is not permitted except for the narrow contribution-fork exception described in LICENSE.

Read LICENSE, LICENSE-FAQ.md, NOTICE.md and GOVERNANCE.md before redistribution-related use.

GitHub Release asset

Attach the Project-Owner-published JSON-API-Forge-v0.1.0-GitHub.zip archive to the GitHub Release if you want a canonical downloadable artifact in addition to GitHub's automatically generated source archives.