Repository navigation
Releases
v2.5.0: Native Multi-Database Support (PostgreSQL, MSSQL, SQLite) and Security Hardening
NodeStack v2.5.0
NodeStack v2.5.0 introduces native multi-database support, extending the runtime beyond embedded SQLite to include first-class PostgreSQL and Microsoft SQL Server (MSSQL) engines. This release features dynamic driver switching, zero-downtime live migrations, multi-engine Full-Text Search (FTS), dual-mode background queues, and a comprehensive security hardening overhaul covering PRs #32 through #39.
Major Features
1. Multi-Database Architecture (PostgreSQL, MSSQL, SQLite)
- Unified Dialect Abstraction (
ISqlDialect,DriverRegistry): Introduced an engine-agnostic SQL layer (SqliteDialect,PostgresDialect,MssqlDialect) handling identifier quoting, boolean record normalization, and dialect-specific upsert semantics. - Per-Tenant Data Stores: Control plane system tables remain embedded on SQLite, while application tenants can independently target SQLite, PostgreSQL, or MSSQL.
- Live Migrations: Transition between database engines in-place via the Admin UI or
nodestack db switch, featuring automated schema cloning, batched record transfer, index reconstruction, and transaction rollback on failure. - Per-Schema Storage Metrics: Live tracking and inspection of disk and table usage per collection across all database engines.
2. Multi-Engine Full-Text Search (FTS)
- Implemented dedicated FTS drivers across all supported backends:
- SQLite: Embedded FTS5 with porter stemming and BM25 ranking.
- PostgreSQL: Native
to_tsvectorandts_rank_cdscoring. - MSSQL: Native
CONTAINSTABLEfull-text search.
- Standardized search syntax, snippets, and pagination across engines.
3. Dual Queue Engine Architecture
SyncQueueEngine: Synchronous, in-process transaction handling for SQLite.AsyncQueueEngine: Asynchronous pooled connection workers for PostgreSQL and MSSQL.- Retains partition FIFO guarantees, atomic claiming, lease extensions, and dead-letter queue (DLQ) isolation across all storage backends.
4. Database Management (Admin UI & CLI)
- Admin UI Database View: Connection status, active provider, latency monitoring, per-schema storage gauges, and pre-cutover connection testing.
nodestack dbCLI: Management commands forstatus,test,configure, andswitch.
Security Hardening Overhaul
- Initial Setup Authorization (PR #34): Resolved an authorization bypass and eliminated race conditions on
/api/setupduring initial admin account provisioning. - Tenant Isolation & Privilege Boundary (PR #33): Enforced strict tenant boundary validation to prevent tenant-scoped admins and API keys from accessing global superuser privileges.
- HMAC-SHA256 API Key Hashing & Granular Scopes (PR #37,
0ac15f3): Replaced reversible key storage with salted HMAC-SHA256 hashing. Added granular scopes for queue operations (queues:send,queues:write) and serverless functions (functions:invoke,functions:<name>). - OAuth2 State Validation & SSRF Guard (PR #36): Added session-scoped OAuth state cookie validation with synchronized store cleanup, and blocked SSRF vectors during OAuth avatar fetching.
- CORS Credential Protection (PR #32): Prevented credential reflection on wildcard origin requests and excluded
*from trusted credentialed origin lists. - Realtime SSE Privacy & Subscription Hardening (PR #35): Redacted user email addresses and sensitive profile attributes from realtime SSE payloads, with dynamic session revocation on active streams.
- PostgreSQL SSL Enforcement (PR #38): Enforced strict SSL certificate verification with CA validation by default.
- Filesystem & Sandbox Containment: Confined SQLite database file paths strictly within project data directories, prevented path traversal in file uploads/downloads, and enforced execution timeouts for QuickJS functions.
Fixes & Improvements
- Atomic Database Migrations (PR #39): Wrapped all schema and data migrations inside atomic database transactions with concurrency safety gates.
- Query Normalization: Standardized boolean representations, camelCase column quoting, and queue polling queries across PostgreSQL and MSSQL.
- Relation Expansion: Fixed record expansion on multi-select relation fields.
- Snapshot Driver: Fixed restore routines when restoring onto empty target schemas.
- SEA Standalone Binaries: Marked optional peer dependencies (
mssql,pg) as external in esbuild to ensure standalone binary builds succeed across platforms.
Installation & Upgrades
Global Server & CLI
npm install -g @nodestackapp/server@latestClient SDK
npm install nodestack-client@latestStandalone Executable Binaries (SEA)
Standalone, zero-dependency binaries for each platform are attached below:
nodestack-windows-x64.exe(Windows x64)nodestack-linux-x64(Linux x64)nodestack-macos-arm64(macOS Apple Silicon)nodestack-macos-x64(macOS Intel)
NodeStack v2.4.0 — Transactional Queues, Strict FIFO Partitions & Flow Concurrency Throttling
NodeStack v2.4.0
Release v2.4.0 introduces NodeStack Queues—an embedded, transactional background message queue and worker engine backed by SQLite with atomic claiming, lease renewal, retries, dead-letter queues (DLQ), strict partition FIFO ordering, and direct serverless function binding. It delivers Flow Execution Concurrency Throttling backed by system queues, an interactive Admin UI Queues Manager, first-party Client SDK queue support via client.queue(name), and an Agent OpenWiki Evidence Index for AI developer tooling.
Features & Enhancements
Transactional Queues Subsystem (QueueService & SqliteQueueDriver)
- Embedded SQLite Queue Engine: Persistent background message queuing backed by SQLite tables (
_queues,_queue_messages) with full ACID transaction guarantees and zero external infrastructure dependencies. - Lock-Free Atomic Claiming & Leases: Workers claim messages atomically with configurable visibility timeouts (
visibilityTimeoutSeconds). Abandoned and dead worker leases are automatically recovered on startup. - Strict FIFO Partition Ordering (
partitionKey/groupKey): Guarantees messages sharing the same partition key process strictly in chronological order without blocking across independent partitions. IncludesforceSkipAPI to unblock partitions on poison messages. - Worker Leases & Claim Tokens: Cryptographic
claimTokengenerated per lease prevents split-brain execution and unauthorized mutations. Workers can extend active leases usingtouch(). - Retries & Dead-Letter Queues (DLQ): Configurable exponential retry backoff (
backoffDelayMs) and Dead-Letter Queue isolation whenmaxAttemptsis reached, with manual re-drive support.
Serverless Function Queue Binding & QuickJS Bridge
- Automated Event Consumers (
targetFunction): Direct queue-to-function binding for automatic message execution in sandboxed QuickJS WebAssembly runtimes. NodeStack automatically claims messages, executes the function, markscompletedon clean returns (saving return values inresult), and handles retries on exceptions. - Function Capacity Coordination: Queue claiming coordinates dynamically with function concurrency capacity to prevent worker starvation or overload.
- QuickJS Sandbox Bridge: Exposes
core.sdk.queue(name)andcore.queuemethods (enqueue,getMessage, etc.) inside function guest sandboxes while protecting internal system queues.
Flow Concurrency Throttling & Lifecycle Safety
- Queue-Backed Flow Execution Limits: Bounded flow concurrency throttling using internal system queues (
_flow_{flowId}). Automatically drains queued executions when limits are removed or expanded. - Queue-Backed Resumption: Resumed and delayed flows are routed transparently through the queue worker pipeline.
- Execution State Integrity: Aborts pending queued executions prior to deleting execution history, suppresses writes for already-deleted running executions, and preserves causal subflow error identity on failure.
- Path Traversal Security: Hardened
FlowPathMapperagainst path traversal and unsafe path manipulation.
Admin UI Queues Manager & Overview Dashboards
- Interactive Queues Manager (
/_/queues): Live metrics for active, queued, processing, completed
v2.3.0 - Serverless Function Flows & State Machine Engine
Release v2.3.0 introduces Serverless Function Flows—an embedded, high-performance workflow orchestration and state machine subsystem executing directly within the NodeStack engine without external dependencies; delivers a dedicated Visual Flow Designer & Declarative Code DSL with real-time two-way synchronization in the Admin Portal; adds Referential Integrity Enforcement between flows and serverless functions; upgrades nodestack-client with full flow execution support; and enhances Admin UI accessibility and light theme contrast across all confirmation dialogs.
Added
1. Serverless Function Flows Orchestration Engine
- Embedded QuickJS State Machine Engine (
FlowEngine.ts,FlowService.ts):- Implemented an in-engine workflow orchestrator executing state machines defined in a clean, JSON-compatible DSL.
- Sub-millisecond state transitions running in-process without AWS Step Functions, Temporal, or external cloud workers.
- 9 Supported State Types:
Task: Executes QuickJS WebAssembly serverless functions with parameter mapping,elevateddatabase permissions, andserviceRoleprivileges.Choice: Conditional branching evaluating comparisons (stringEquals,numericEquals,numericGreaterThan,numericLessThan,numericGreaterThanEquals,numericLessThanEquals,booleanEquals,isPresent) and compound logic (and,or,not).Map: High-throughput array iteration with configurablemaxConcurrencyover dynamic item paths.Parallel: Concurrent multi-branch execution with synchronized output aggregation.Loop: Bounded while/until iterations with safety loop guards (maxIterations).Pass: Payload injection, shaping, and mock state testing.Wait: Configurable time delays before subsequent step dispatch.Succeed&Fail: Explicit terminal status nodes with error classification and cause reporting.
- JSONPath Data Filtering & Mapping:
- Granular state context transformations using
inputPath(input extraction),resultPath(result injection), andoutputPath(output shaping).
- Granular state context transformations using
- Declarative Error Handling & Retries:
- Automatic retries with exponential backoff (
intervalSeconds,maxAttempts,backoffRate,errorEquals). - Structured
catchblocks routing matching errors to dedicated fallback recovery states.
- Automatic retries with exponential backoff (
2. Dual-Mode Flow Designer (Visual Canvas & Code DSL)
- Interactive Visual Graph (
src/admin/ui/js/flows-designer.js,flows.css):- Interactive canvas with directional step connectors, state type color badges (
Task,Choice,Map,Parallel, etc.), and step drag-and-drop reordering. - State inspector for configuring target serverless functions, retry policies, catch handlers, wait times, and branching rules.
- Interactive canvas with directional step connectors, state type color badges (
- Code DSL Editor (
src/admin/ui/js/flows.js):- Built-in CodeMirror JSON state machine editor with real-time schema validation and instantaneous two-way sync with the visual designer.
- Live Test Runner & Step Waterfall:
- Dedicated runner to execute flows with custom test payloads and inspect step latency, duration waterfalls, input/output diffs, and execution logs.
3. Dual Triggering System & Observability
- Database Lifecycle Event Triggers:
- Automatically dispatch flows on collection events:
<collection>:afterCreate,<collection>:afterUpdate,<collection>:afterDelete, with full pre- and post-mutation record context.
- Automatically dispatch flows on collection events:
- REST Execution API & Multi-Tenancy:
- Added
/api/flowsendpoints for flow management and executions (POST /api/flows/:id/execute), fully isolated per tenant application (/api/apps/:slug/flows).
- Added
- Persistent Execution Audit Logs:
- Stored in SQLite (
_flow_executionstable) with granular step-by-step logs (stepLogs), input snapshots, output payloads, actor identity, and duration metrics.
- Stored in SQLite (
4. Function-Flow Referential Integrity Protection
- Fail-Closed Dependency Inspection (
FunctionService.deleteFunction):- Protects active production workflows by scanning all registered flows before deleting any serverless function.
- Rejects deletions with
HTTP 409 Conflictand details all referencing flow names and IDs. - Supports explicit override via
DELETE /api/functions/:id?force=true. - Warns users in the Admin UI with a high-contrast modal detailing dependent flows and requiring explicit confirmation before force-deletion.
5. First-Party Client SDK Support (nodestack-client)
- Typed Flow Service (
packages/client/src/services/FlowService.ts):- Added
client.flows.execute(flowIdOrName, input, options)supporting synchronous and background dispatch. - Added
client.flows.getList(),client.flows.getOne(), andclient.flows.getExecutions().
- Added
6. Official Documentation
- Comprehensive Function Flows Guides:
- Published Function Flows Overview, State Machine Specification, Triggers & Observability, and Serverless Function Integration.
- Added Function Flows to the documentation sidebar navigation (
docs/sidebars.ts). - Updated REST API Reference (
docs/docs/api-reference/rest-api.md) with the complete/api/flowsspecification.
Changed
- Accessible Confirmation Dialogs (
src/admin/ui/js/state.js,main.css):- Replaced native browser
alert()andconfirm()dialogs across all Admin UI views (webhooks, functions, flows, snapshots, logs) with accessible, theme-aware HTML confirmation dialogs (showConfirmDialog).
- Replaced native browser
- Light Theme High-Contrast Polish:
- Enhanced WCAG AAA color contrast tokens in light mode for callout banners, error boxes, and danger action buttons.
Fixed
- Security & Inline JS Hardening:
- Eliminated inline JavaScript handler string breakout vulnerabilities by binding click listeners dynamically with raw in-memory values instead of interpolated HTML attributes.
- Fail-Closed Integrity Error Handling:
- Fixed flow dependency checks in
FunctionServiceandFlowServiceto fail closed on malformed flow JSON or query failures instead of falling open.
- Fixed flow dependency checks in
v2.2.0 — Standalone Binaries (SEA), 1-Click Cloud Deployments & Concurrency Hardening
NodeStack v2.2.0 is a major feature and reliability release introducing Zero-Dependency Standalone Binaries via Node.js Single Executable Applications (SEA), official 1-Click Cloud & Browser Deployments (Docker, Railway, and Dev Containers), an in-depth Platform Comparison Matrix, and critical concurrency, security, and session caching hardening across the core stack.
🚀 Highlights & New Capabilities
1. Cross-Platform Standalone Binaries (Node.js SEA)
- Zero-Dependency Executables: Run NodeStack without needing Node.js or npm installed on the target machine. Compiles directly into native executables for:
- Linux (
x64) - macOS Apple Silicon (
arm64) - macOS Intel (
x64) - Windows (
x64.exe)
- Linux (
- Embedded Admin UI: The Admin UI bundle is embedded directly within the executable binary with automatic runtime virtual asset extraction.
2. 1-Click Cloud & In-Browser Deployments
- Production Containerization: Multi-stage production
Dockerfileand.dockerignorefor minimal, ultra-lightweight container images. - 1-Click Cloud Templates: Added instant deployment blueprints for Railway (
railway.json) and Render. - Dev Containers & Codespaces: Added full VS Code Remote Containers / GitHub Codespaces integration (
.devcontainer/devcontainer.json). - Environment Detection: Dynamic
PORTandHOSTresolution for seamless cloud hosting across container platforms.
3. Architecture & Ecosystem Comparison Matrix
- Platform Comparison Guide: Comprehensive architectural evaluation comparing NodeStack against PocketBase, Supabase, Strapi, and Firebase across runtime models, language support, RLS rule engines, reactivity, plugin extensibility, and binary footprint.
🛡️ Security, Concurrency & Reliability Fixes
- Security & Anti-SSRF Guardrails:
- Hardened
WebhookServicedelivery with pinned DNS resolution and redirect-awareSsrfGuardvalidation to prevent DNS rebinding or redirect bypasses to private networks and cloud metadata endpoints (169.254.169.254). - Hardened file storage path containment against directory traversal escapes, and strictly preserved record IDs during multipart uploads and ingestion flows.
- Added centralized abort timeout signals across secondary OAuth email retrieval endpoints.
- Hardened
- Database Concurrency & Transactions:
- Enforced
BEGIN IMMEDIATEwrite transactions in SQLite to eliminate busy contention under concurrent load. - Added nested transaction support utilizing SQLite savepoints (
SAVEPOINT nodestack_tx_*). - Enforced synchronous transaction contracts by rejecting async Promise-returning callbacks before invocation to prevent out-of-transaction query leaks.
- Properly escaped
%and_wildcards in SQLLIKEfilter queries.
- Enforced
- Authentication & Token Caching:
- Promoted token cache entries on read hits for true LRU eviction under high identity counts.
- Canonical session invalidation: immediately evicts revoked tokens upon email-based session revocation (
revokeAdminSessions).
- Performance & Scalability:
- Streamed JSON and CSV exports in 500-record chunks to eliminate memory spikes and event loop blockage on large collections.
- Switched batch record import password hashing to non-blocking async bcrypt routines.
- Protected request logging against circular references and
BigIntvalues.
- HTTP Validation & OpenAPI 3.0 Alignment:
- Guarded
olderThanDaysparameter with finite-number validation (Number.isFinite()) in log pruning to prevent unhandled date parsingRangeErrors. - Updated OpenAPI definition for
DELETE /api/logsto document query parameters and status codes.
- Guarded
📦 Packages Published
- Core Server & CLI:
@nodestackapp/server@2.2.0 - TypeScript Client SDK:
nodestack-client@2.2.0
💻 Quick Install
# Run standalone binary (no Node.js required)
./nodestack-linux-x64 start
./nodestack-macos-arm64 start
./nodestack-windows-x64.exe start
# Or install via npm
npm install -g @nodestackapp/server
nodestack startv2.1.0 — Embedded Serverless Functions, OAuth 2.0 PKCE & M2M API Keys
Release v2.1.0 introduces Embedded Serverless Functions ("NodeStack Functions") with QuickJS-Wasm isolation, Anti-SSRF guardrails, database lifecycle hooks, and a dedicated 4-tab Admin UI Workbench; adds OAuth 2.0 & Social Sign-In with PKCE across 5 major identity providers; delivers Machine-to-Machine (M2M) API Key Authentication; and resolves platform stability issues with Windows SQLite connection teardown locks and test resource cleanup leaks.
Added
1. Embedded Serverless Functions ("NodeStack Functions")
- QuickJS-Wasm Sandboxed Execution Runtime:
- Lightweight WebAssembly-based QuickJS engine (
QuickJsWasmRuntime) providing isolated in-engine execution of JavaScript and TypeScript functions. - Deterministic execution limits: strictly enforced CPU execution timeouts and memory limit caps without blocking the Node.js event loop.
- Isolated global scope: prevents access to Node.js
process,fs,child_process, and hostrequire.
- Lightweight WebAssembly-based QuickJS engine (
- Anti-SSRF Security Guardrails (
SsrfGuard):- Comprehensive URL and IP validation for outbound requests (
ctx.fetch). - Blocks loopback, private IPv4 ranges (
10.0.0.0/8,172.16.0.0/12,192.168.0.0/16), cloud metadata endpoints (169.254.169.254), and IPv6 Unique Local Address ranges (fc00::/7, link-local, and IPv4-mapped addresses). - Enforces HTTP/HTTPS protocol restrictions and configurable per-function domain allowlists.
- Comprehensive URL and IP validation for outbound requests (
- Context API (
ctx):ctx.request: Parsed HTTP request body, query parameters, headers, method, and authenticated caller identity (auth).ctx.records: Scoped database operations (get,list,create,update,delete) with automaticRuleEnginerow-level security enforcement or elevated service-role bypass (elevated: true).ctx.env: Injected application environment secrets without exposing host environment variables.ctx.log: In-sandbox console logging captured directly into execution traces.
- Database Lifecycle Event Hooks:
- Execute functions automatically before or after record mutations (e.g.
orders:beforeCreate,users:afterUpdate). - Validation and data enrichment: cancel operations by returning
{ cancel: true, reason: "..." }or mutate records in-flight. - Circular recursion guardrails and concurrency admission limits.
- Execute functions automatically before or after record mutations (e.g.
- Functions REST & Admin API:
ANY /api/functions/:name/invoke: Dynamic invocation supportingpublic,auth, oradminauthentication policies.POST /api/functions/:id/test: Real-time sandboxed test execution with mock context.GET /api/functions/stats: Aggregate execution metrics, success rates, and latency stats.GET /api/functions/logs&DELETE /api/functions/logs: Execution audit logging and payload retention.
2. Admin UI Dedicated Functions Workbench
- 4-Tab Workbench Interface:
- Code & Context Reference: Full-width minified CodeMirror editor with JavaScript/TypeScript syntax highlighting, automatic theme synchronization (Dark / Light), Ctrl+S save shortcut, starter recipes, and a collapsible Context Reference panel (
ctx.*) with 1-click code snippets. - Live Test Runner: Real-time QuickJS sandbox execution runner with mock payload editor, header builder, caller auth selector, latency badges, and formatted response viewer.
- Configuration & Triggers: General settings, authentication policies (
public,auth,admin), hook trigger definitions, execution timeout/memory limits, domain allowlists, and scoped environment secrets. - Function Logs & History: Function-scoped invocation history table with formatted timestamps, status badges, latency metrics, and modal payload inspector for request/response bodies and console output.
- Code & Context Reference: Full-width minified CodeMirror editor with JavaScript/TypeScript syntax highlighting, automatic theme synchronization (Dark / Light), Ctrl+S save shortcut, starter recipes, and a collapsible Context Reference panel (
- Modular Component Architecture:
- Organized across dedicated companion modules:
functions.js(overview table & state),functions-workbench.js(editor & configuration), andfunctions-tester.js(live sandbox tester & logs).
- Organized across dedicated companion modules:
3. OAuth 2.0 & Social Sign-In (Multi-Provider with PKCE)
- Identity Provider Integrations:
- Built-in support for Google, GitHub, Microsoft, Apple, and Discord OAuth 2.0 providers.
- RFC 7636 Proof Key for Code Exchange (PKCE) with SHA-256 code challenge generation.
- Security & Verification Hardening:
- Strict email verification validation for GitHub and Microsoft providers.
- Cryptographic Apple ID token claim verification.
- Session-bound OAuth state and PKCE verifier protection.
- Allowed collection authorization enforcement and disabled-provider filtering.
- Client SDK Integration (
nodestack-clientv2.1.0):- Added
PkceUtilfor cryptographic verifier and challenge generation. - Added
client.collection(col).getOAuthUrl(provider, options)and popup/redirect authentication handlers.
- Added
4. Machine-to-Machine (M2M) Authentication & Scoped API Keys
ApiKeyService& Management API (/api/api-keys):- High-entropy SHA-256 hashed API keys with prefix identification (
nsk_live_*). - Granular scope definitions, collection-level read/write permissions, role emulation, and expiration controls.
- Integrated into Fastify
AuthMiddlewarefor transparent header-based authentication (Authorization: Bearer nsk_live_*).
- High-entropy SHA-256 hashed API keys with prefix identification (
5. Documentation
- Functions Documentation Suite (
docs/docs/functions/):- Complete developer guides covering Architecture & Overview, Context API reference, Lifecycle hooks, and Security / Anti-SSRF guardrails.
- Authentication Guides (
docs/docs/auth-and-security/):- Detailed setup guides for OAuth 2.0 social sign-in and M2M API Keys.
- Updated Docusaurus sidebar navigation and REST API references.
Changed
- Plugin Architecture: Packaged
@nodestackapp/plugin-chat-notificationsas its own dedicated official plugin workspace, replacing@nodestackapp/plugin-webhooksto eliminate naming ambiguity and route collisions with the native Webhooks Manager.
Deprecated
@nodestackapp/plugin-webhooks: Formally deprecated in favor of@nodestackapp/plugin-chat-notificationsfor Discord/Slack chat notifications, and native core Webhooks (/api/webhooks) for generic HTTP webhook dispatching.
Fixed
- Windows SQLite Database Lock & Resource Leaks:
- Resolved
EBUSY: resource busy or lockederrors on Windows caused by danglingAppRegistryandsystem.dbconnections. - Added
NodeStack.prototype.close()which cascades toAppManager.closeAll()to cleanly release both tenant database handles andsystem.db. - Replaced unclosed
app.db.close()across CLI commands and test teardowns.
- Resolved
- Temporary Directory Cleanup:
- Resolved unpurged test directories, completely eliminating leftover
tmp_typegen_test_*and.test_*folders during CLI typegen operations and test runs.
- Resolved unpurged test directories, completely eliminating leftover
📦 Published Packages
v2.0.0: Multi-Application Platform, Snapshots, Admin Theming, and TypeScript 7 / Node 24
Release v2.0.0 is a milestone major release introducing complete Multi-Application Support across the entire NodeStack ecosystem, upgrading to TypeScript 7.0 and Node.js 24+, introducing generic Application Snapshots & Checkpoints, complete System, Light, and Dark Theming in the Admin Portal, and delivering a 1-click application lifecycle in the Web Admin Dashboard.
⚠️ Breaking Changes
- Package Scope & Version: The server package is published under
@nodestackapp/serverat major version2.0.0(alongsidenodestack-client@2.0.0and official plugins@nodestackapp/plugin-*@2.0.0). - Runtime Requirement: Node.js 24+: NodeStack now requires Node.js v24.0.0 or higher to leverage native modern V8 features and
node:sqliteenhancements ("engines": { "node": ">=24.0.0" }). - Toolchain: TypeScript 7.0: Upgraded core, client SDK, and official plugins to TypeScript
^7.0.2targetingES2024.
Highlights & New Features
1. Multi-Application Platform Architecture
- Tenant Isolation Across All Subsystems:
- Physical database file isolation: Every hosted application receives its own embedded SQLite database at
data/<app-id>/data.db. - Physical file storage isolation: Uploaded media and assets are isolated in
data/<app-id>/storage/. - Scoped Authentication: Dedicated user pools, password hashes, and JWT signatures per application.
- Realtime SSE Isolation: Event streams (
/api/realtime?app=:slug) deliver collection mutations exclusively to connected clients of that application. - Independent Audit Logs & Webhooks: Mutation diff histories and outbound webhook dispatchers are scoped per tenant.
- Physical database file isolation: Every hosted application receives its own embedded SQLite database at
- App Routing & Dynamic Dispatch:
- Subpath routing via
/api/apps/:appId/...for collections, auth, files, search, and realtime. - Request header routing via
x-nodestack-app: <appId-or-slug>for transparent multi-tenancy without modifying API paths. - Query parameter routing via
?app=<appId-or-slug>for browser EventSource SSE streams. - Backward compatibility: Existing single-app instances automatically migrate to the
defaultapp with zero breaking changes or migration scripts.
- Subpath routing via
- Application Management REST API (
/api/apps):- Full administrative CRUD for listing, provisioning, updating, and deleting application instances.
- Template-based application initialization supporting
saas,blog,ecommerce, orblank. - Safety guards: The
defaultapplication is protected and cannot be deleted.
2. Web Admin Dashboard Multi-App Experience
- App Switcher & Navigation: Reactive application switcher dropdown in the top navigation bar.
- 1-Click Application Deletion: Integrated delete button with safety confirmation modal, automatic SQLite WAL flush, storage cleanup, and redirection to
default. - Command Palette Integration (
Ctrl + K/Cmd + K): Instant keyboard shortcuts to switch, create, or delete apps. - Drawer & Modal Stacking: Fixed z-index hierarchy preventing record drawers from overlapping dialogs.
3. Client SDK (nodestack-client v2.0.0)
- Application Scoping (
client.app(slug)): Returns an app-scoped instance with automaticx-nodestack-appheader injection, scoped SSE streams, and scoped file URL generation. - Application Management Service (
client.apps): Administrative CRUD methods for programmatic tenant management. - Application Snapshots Service (
client.snapshots): Programmatic multi-snapshot management with FIFO eviction support.
4. Official React E-Commerce Storefront Demo (examples/ecommerce-react)
- Production-ready modern storefront built with React 18, Vite, Tailwind CSS, and
nodestack-client. - User registration, login, and 1-click demo customer account (
alex.vance@nodestack.dev). - Dynamic reviews, live rating aggregation, and 'Verified Buyer' badging.
- Persistent database-backed favorites using the
favoritescollection with row-level security. - Slide-out cart drawer, free shipping progress meter, and order checkout writing to
orders. - Visual order status timeline tracker (
Pending→Processing→Shipped→Delivered). - Multi-App scoping via
VITE_NODESTACK_APPin.env.local.
5. Generic Application Snapshots & Multi-Checkpoint Restoration
- Atomic transactional SQLite database snapshots (
VACUUM INTO) paired with uploaded file storage backups, schema definitions, and cryptographic content hashes. - Multi-snapshot history: Non-destructive restore traversing forward and backward across checkpoints.
- 10-snapshot capacity cap with FIFO eviction safeguard (
evictOldest: true). - Admin Dashboard Snapshots Manager view with live drift monitoring.
- CLI commands:
nodestack snapshots [list|create|restore|delete|clear].
6. Security & Row-Level Access Rule Enforcement
- Dynamic server-side SQL parameterized WHERE clause resolution (
RuleEngine.buildListFilter). - Strict boundary enforcement blocking unauthenticated callers and preventing cross-user record exposure.
- Hardened e-commerce starter templates (
orders,favorites,reviews).
7. Admin Portal Appearance & Theming (System, Light, Dark)
- Runtime tri-state switcher between Light (☀️), Dark (🌙), and System (💻 Auto) modes.
- Zero-Flicker (Anti-FOUC)
<head>resolution script. - Dual semantic CSS variable token palette with WCAG-compliant high contrast across all components.
- Theme-reactive SVG Analytics charts dynamically updating without page reloads.
v1.3.0: SQLite FTS5 Full-Text Search, Outbound Webhooks & Audit Logs
Release v1.3.0 delivers three major backend subsystems: Native SQLite FTS5 Full-Text Search (FTSS), an Outbound Webhooks & Delivery Log Engine, and an Immutable Audit Logging subsystem with visual record timeline diffs. It also introduces an official Docusaurus-powered developer documentation site, in-server static docs serving, and Client SDK integrations for webhooks and search.
Highlights
- Native SQLite FTS5 Search: In-process BM25 relevance scoring, prefix matching, and highlighted snippet excerpts without external search services.
- Outbound Webhooks Subsystem: Automated HTTP callbacks on record mutations, HMAC-SHA256 signature verification (
x-nodestack-signature), delivery retry tracking, and Admin UI manager. - Immutable Audit Logging: Field-level
{ old, new }diff computation, actor attribution, sensitive data masking, and chronological record timeline drawer in Admin UI. - Documentation Portal: Official Docusaurus documentation portal deployed to GitHub Pages and served directly from NodeStack at
/documentation/. - Client SDK (
nodestack-client@1.3.0): Full-text search querying, webhooks service, and cryptographic signature verification helper.
Documentation: https://satya-jugran.github.io/nodestack/
Full Changelog: See CHANGELOG.md
v1.2.0 — Official Plugin Architecture, Extensions Hub & Workbench
What's New in v1.2.0
- Formal Plugin Architecture: Mount extensions with
app.use(plugin)chaining and full lifecycle hooks. - Official @nodestackapp Extensions:
@nodestackapp/plugin-stripe— Checkout sessions, billing portal, and verified webhook signatures.@nodestackapp/plugin-s3— SigV4 presigned upload URLs and bucket file tracking.@nodestackapp/plugin-resend— Transactional email delivery with dry-run mode and SQLite audit logs.@nodestackapp/plugin-webhooks— Realtime Discord & Slack outbound dispatch on mutations.@nodestackapp/plugin-algolia— Realtime mutation queueing and full collection reindexing.
- Option B Plugin Configuration Precedence: Server
.envlocks override credentials, while unconfigured settings can be edited live via the Admin UI. - Slide-Over Plugin Tester Drawer: In-context developer workbench for testing checkouts, presigned URLs, mock webhooks, and email dispatch.
- Admin UI Modularization: Refactored
app.jsinto modular files (collections.js,plugins.js,plugin-tester.js,command-palette.js).