Elysia

Mount Ownfold in an Elysia backend on Bun or compatible Web runtimes with explicit origin, authentication, storage, and error boundaries.

@ownfold/elysia passes Elysia’s native Web Request directly to Ownfold. It has no React, browser-storage, or UI dependency.

Database and identity are separate choices. Select both in the framework recipe builder, including private single-user mode, then pass the resulting VaultServer to Elysia.

Install

pnpm add @ownfold/elysia@beta @ownfold/server@beta elysia

Add a runtime-compatible database adapter and authentication resolver.

Create the vault server

import { createVaultServer } from "@ownfold/server"

export const vaultServer = createVaultServer({
  adapter,
  getUserId,
})

Mount the handler

import { createElysiaVaultHandler } from "@ownfold/elysia"
import { Elysia } from "elysia"

const origin = "https://app.example.com"

export const app = new Elysia().all(
  "/api/ownfold/*",
  createElysiaVaultHandler({
    server: vaultServer,
    isOriginAllowed: ({ request }) => {
      if (request.headers.get("sec-fetch-site") === "cross-site") return false
      const requestOrigin = request.headers.get("origin")
      return requestOrigin === null || requestOrigin === origin
    },
  }),
)

The adapter returns Ownfold’s Response unchanged, including status, JSON error structure, Cache-Control: no-store, and method headers.

CORS and origins

Same-origin checks and CORS solve different problems. If a separate browser origin calls the API:

1. allow only explicit application origins in Elysia’s CORS configuration;
2. configure credential handling intentionally;
3. make isOriginAllowed enforce the same set for mutations; and
4. never use * with cookie credentials.

Bearer-token API clients may omit Origin. Authentication and ownership checks still apply.

Authentication

getUserId receives the same request Elysia received. Integrate a verified session or token:

const getUserId = async ({ request }: { readonly request: Request }) => {
  const authorization = request.headers.get("authorization")
  const identity = await tokens.verify(authorization)
  return identity?.subject ?? null
}

Return an immutable application user ID. Do not use email, display name, or a body field as the vault owner.

Database compatibility

Elysia commonly runs on Bun. Adapter compatibility depends on the selected database driver:

The framework adapter itself does not choose or initialize storage.

Application ciphertext

Create separate Elysia routes for domain records. Authenticate the request, parse route fields, and pass only the encrypted write object to validateEncryptedRecordWrite before persistence. Do not add decryption to the Ownfold handler.

Errors

Ownfold expected failures are returned as structured HTTP responses. Avoid wrapping a successful Response in an Elysia JSON object, which changes status and headers. Log internal operation codes without logging ciphertext bodies, Recovery Kit contents, secrets, or session tokens.

Testing

Elysia exposes a Fetch-compatible handle method, so tests can use Web requests directly:

const response = await app.handle(
  new Request("https://app.example.com/api/ownfold/vault", {
    headers: { authorization: "Bearer test-session" },
  }),
)

Test unauthenticated requests, disallowed origins, invalid bodies, stale revisions, and real adapter transactions. The repository’s Elysia + PostgreSQL example is the executable reference.

Production checklist

• Verify Bun/runtime support for the selected database and authentication libraries.
• Restrict CORS and mutation origins independently.
• Keep the original request intact for authentication.
• Configure rate-limit and audit hooks on VaultServer.
• Store application ciphertext in application-owned tables.
• Close database connections on shutdown.