Codebase

Building blocks

Simply-put, Bind is a SvelteKit server app that runs via Node.js. Other layers are described in more detail below.

layer	description
SvelteKit	framework, UI components, routing, fast builds and reloads with vite
+ adapter-node	build as Node.js app for production
+ bind-glue	Express/SvelteKit middleware for WebFinger and remoteStorage.js
Better Auth	accounts, social sign in, credential encryption
Pico	styles mostly without CSS classes
Vitest	logic or unit tests in *-tests.js
Playwright	interface tests in ui-tests.js

Other dependencies:

• lowdb, js-jsonq: database backed by local JSON
• svelecte: repo selector
• Simple Git: git commands via Node.js
• grid.js: admin users table
• file-type, mime: guessing types

Better Auth

Accounts are woven into much of Bind's features, so it made sense to start on a more robust foundation rather than writing a basic system from scratch.

An authentication framework like Better Auth makes it possible to eventually include magic links, passkeys, two-factor, email one-time passwords, rate-limiting, and other social providers, without all that taking over the codebase.

Bind uses the following integrations (configured in src/lib/auth/config.js:

• Email & Password Authentication
• Username plugin
• Admin plugin to create accounts
• a custom database adapter that bridges to plain JSON objects (see src/lib/auth/generic.js)
• Hooks for logic on account creation and deletion
• Cookies to store and retrieve the current session

Database adapters

Bind is currently built to use the local filesystem because it doesn't require configuring other services (and therefore simpler to self-host). But for many use cases it might make sense to use a real database.

Better Auth is flexibile enough to support MySQL, SQLite, PostgreSQL, MongoDB, Supabase, and others.

At some point, there should be sufficient affordances in the codebase for a host to pick what works best for their situation and simply configure it from an admin panel. Until then, here are some helpful links for anyone who wants to build something themselves:

• Create a Database Adapter
• PocketBase community adapter
• Remult community adapter

Develop

To run the Bind codebase for development, install Node.js and npm, then install the dependencies:

npm i

Run

Now you should be able to start a development server:

npm start

Type o + Enter or visit http://localhost:5173 in your browser.

TIP

Set HOST and PORT in your environment variables to customize this address.

Test

Run logic tests that watch files for changes:

npm run test:unit

Run interface tests once

npm run test:ui

or with Playwright's interactive UI Mode:

npm run test:ui:watch

Run all tests:

npm test

Deploy

Build a production Node.js app in /build that can run on a server:

npm run build

This can be started with node build/index.js or just node build.

Types

table	notes	Bind	Better Auth	remoteStorage
user	primary reference for an account role defaults to user but can be admin	✔︎	✔︎	✔︎
account	owned by user email, social are seperate 'accounts' accountId references a foreign id password or accessToken stores a hashed credential	✔︎	✔︎
account_subsource	owned by account foreignId references the repo id inside a git forge account data stores a normalized payload of the repo object as well as the original	✔︎	✔︎
oauth_connections	stores OAuth Implicit Grant connections owned by user weakly through username to avoid a lookup might merge later into session or Better Auth's OIDC Provider data stores: remoteStorage scope depotId pointing to which provider or account_subsource is linked	✔︎		✔︎
session	currently used only for cookies		✔︎