Technical Aspects

freezr is an open-source open-protocol personal server built on Node.js. It provides a thin layer of functionality - providing identity, permissions, and data routing — connecting apps to the data owner's files, database, compute, and LLM resources!

Architecture (Protocols)

At its core, a freezr app is just a static front-end bundle — HTML, CSS, ES-module JavaScript — served from the user's freezr server. To ensure security, app logic runs in the browser and no server-side code can run directly on freezr. Data, files, permissions, messaging, LLM calls, and serverless invocations go through the freezr JavaScript API, which is auto-injected into every app page as a global object. Server-side code can run on serverless instances connected to each user and given the appropriate permisisonsas described below.

The server is organised into three layers of protocols:

Every API call carries two identities: the logged-in user (a session on the global / cookie) and the calling app (a path-scoped bearer token, issued when the user visits the app's page). Permission checks run against the pair — an app can only touch data it is authorised to touch for the current user. See security below for more details or review the href="/security">security deepdive.

Security model

freezr runs third-party apps on the same origin as the user's own data. Isolation is built from four complementary mechanisms: path-scoped cookies, token-bound API calls, a strict Content Security Policy,< and per-user permission checks on every request. Below is a summary of the security model - a deeper dive into security can be found here.

Also of note: pubicly accessible pages do NOT use cookies and have less strict CSP.

Isolation model

The core trick: each app is served from its own URL path (/apps/<app_id>/*) and receives a bearer token in a path-scoped cookie. The browser only delivers that cookie on requests inside the app's path, so one app literally cannot see another app's token. The API then ties each token to both the app and the user, so a stolen token from app A is useless against app B's data.

Set-Cookie: app_token_<user_id>=<random>;
    Path=/apps/com.you.notes;
    Secure; SameSite=Strict
// httpOnly=false — JavaScript must read this to build the
// Authorization header; see the path-scope protection above

Additional mechanisms layered on top:

• Session cookie — httpOnly, SameSite=Strict, 30-day TTL. JavaScript cannot read or forge it.
• Sec-Fetch-Mode check — server-rendered pages with sensitive data require Sec-Fetch-Mode: navigate; fetch() of another app's HTML is blocked.
• App-name validation — app_table access is checked with a dot-boundary comparison; com.example.my cannot read com.example.myapp.posts.
• Grantee validation — for any cross-user access the requesting user must appear in the record's permission grantees list.
• Token type — tokens are explicitly typed 'browser' (session-bound) or 'oauth' (cookieless, for programmatic access). Browser tokens are invalidated when the session ends.

Content Security Policy

App pages are served with a strict CSP. The default header is:

default-src 'self';
script-src  'self' 'nonce-<per-request>';
style-src   'self' 'unsafe-inline';
img-src     * data:;
connect-src 'self';
form-action 'self';
frame-src   'none';
object-src  'none';

The nonce is crypto.randomBytes(16) generated per request — only scripts explicitly listed in the app manifest and injected by the renderer receive it. Inline <script> tags, onclick="..." handlers, and HTML-injected scripts are blocked even if the page is otherwise compromised.

Apps may request CSP relaxations via manifest permissions. These are user-grantable at install time and currently include:

Tokens & sessions

Server-side protections

• Rate limiting — 300 requests/minute per authenticated user across CEPS + FEPS routes, with graduated throttling and a 429 Retry-After response when exceeded.
• Per-record size limit — 2 MB max per record on create / update / replace.
• Regex safety — $regex values validated to reject nested-quantifier catastrophic patterns; alternatively, operator can be disabled per deployment.
• Operator blocking — $where, $function, $accumulator, $expr stripped from user queries before they reach MongoDB.
• Input validation — permission names, function names, and table ids are all restricted to [a-zA-Z0-9._-]+. Zip extraction enforces zip-slip protection.
• Public routes — path-isolated from the app cookie namespace. preventCookiesOnPublicRoutes middleware ensures public pages never see auth credentials.
• Reserved prefixes — publicids starting with /app, /admin, /account etc. are blocked, even for admins.

File Structure

A quick tour of what lives where in the freezr checkout.

Folders

The top-level folders in the freezr repo:

Inside users_freezr/, each user (including the admin) has a folder with the same three sub-folders:

A number userIds are reservede - eg fradmin (the built-in "freezr admin" system user) and public/ where pulished items live.

Node modules

freezr tries to keep its dependency list small. The sections below split the runtime modules into the Express core, general-purpose utilities, and the back-end adapter SDKs.

Core

The Express stack every request passes through.

Utilities

Cross-cutting helpers used throughout the server.

Adapters

SDKs for the pluggable databases, file systems, and LLM providers. Each is only loaded when the corresponding adapter is active.

Dev-only (devDependencies) adds mocha + chai for tests, standard for linting, and the @codemirror/* and rollup packages that power the in-browser code editor bundles used by the built-in creator app.

You can learn more about how to connect to these adapters on the install page.

HTTP endpoints

To use freezr, the API provides all you need. The freezr API itself is a wrapper over two HTTP surfaces. CEPS (Common Endpoints) is the portable layer any CEPS-compatible server speaks. FEPS (freezr Extensions) is the freezr-specific layer: bulk operations, uploads, permissions, messaging, LLM, and serverless.

These endpoints are listed here for reference, but they should not normally be used by apps. Apps should access these via the freezr API.

CEPS — data

POST /ceps/write/com.you.notes.entries
{
  "title": "Hello",
  "body":  "First note"
}

{
  "_id": "abc123"
}

GET /ceps/read/com.you.notes.entries/abc123

{
  "_id": "abc123",
  "title": "Hello",
  "body":  "First note",
  "_date_modified": 1740000000000
}

POST /ceps/query/com.you.notes.entries
{
  "q":    { "archived": false },
  "sort": { "_date_modified": -1 },
  "count": 20
}

[
  { "_id": "abc123", "title": "Hello", ... }
]

PUT /ceps/update/com.you.notes.entries/abc123
{ "title": "Updated", "body": "New" }

DELETE /ceps/delete/com.you.notes.entries/abc123

CEPS — permissions & messaging

FEPS — freezr extensions

FEPS endpoints cover operations beyond the portable baseline: upserts with forced ids, field-level updates, bulk delete, file upload, LLM, and serverless invocation. They also carry permission context in the body (permission_name, owner_id, requestee_app) for cross-app access.

Account API