@otwdesign/db-node 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+OTW DB
+Copyright 2026 OTW SRL

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# @otwdesign/db-node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+OTW DB in Node servers: node:http, Express, Connect, Fastify and Koa.
+
+```sh
+npm install @otwdesign/db-node @otwdesign/db-core pg pg-cursor
+```
+
+```ts
+import { fastifyPlugin, koaMiddleware, toNodeHandler } from '@otwdesign/db-node'
+
+app.use('/db', toNodeHandler(dbAdmin)) // Express or Connect
+http.createServer(toNodeHandler(dbAdmin)) // node:http
+await fastify.register(fastifyPlugin(dbAdmin)) // Fastify
+koa.use(koaMiddleware(dbAdmin)) // Koa
+```
+
+`dbAdmin` comes from `createDbAdmin()` in `@otwdesign/db-core`. The whole guide:
+[github.com/OTWSRL/otw-db](https://github.com/OTWSRL/otw-db#readme).

package/dist/cli.d.ts

@@ -0,0 +1,23 @@
+import { type ConnectionConfig } from '@otwdesign/db-core';
+export interface ServerOptions {
+    connections: readonly ConnectionConfig[];
+    /** Default 4010; 0 picks a free port. */
+    port?: number;
+    /** Default 127.0.0.1: only this machine. */
+    host?: string;
+    /** Generated when not given. */
+    token?: string;
+}
+export interface RunningServer {
+    /** Opening it signs the browser in. */
+    url: string;
+    token: string;
+    close(): Promise<void>;
+}
+/**
+ * OTW DB on its own HTTP server. Anyone with the token may use it, so it listens on this machine
+ * only unless told otherwise; the link it prints signs the browser in with an HttpOnly cookie.
+ */
+export declare function startServer(options: ServerOptions): Promise<RunningServer>;
+/** The `otw-db` command. */
+export declare function main(argv?: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,114 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { parseArgs } from 'node:util';
+import { connectionsFromEnv, createDbAdmin } from '@otwdesign/db-core';
+import { toNodeHandler } from "./index.js";
+const COOKIE = 'otw_db_token';
+/**
+ * OTW DB on its own HTTP server. Anyone with the token may use it, so it listens on this machine
+ * only unless told otherwise; the link it prints signs the browser in with an HttpOnly cookie.
+ */
+export async function startServer(options) {
+    const token = options.token ?? randomBytes(24).toString('base64url');
+    const admin = createDbAdmin({
+        connections: options.connections,
+        authorize: (request) => (holdsToken(request, token) ? { id: 'local' } : null),
+    });
+    const handle = toNodeHandler(admin);
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        const given = url.searchParams.get('token');
+        if (given !== null) {
+            url.searchParams.delete('token');
+            const back = `${url.pathname}${url.search}`;
+            res.statusCode = 303;
+            res.setHeader('location', back);
+            if (same(given, token)) {
+                res.setHeader('set-cookie', `${COOKIE}=${token}; HttpOnly; SameSite=Strict; Path=/`);
+            }
+            res.end();
+            return;
+        }
+        void handle(req, res);
+    });
+    await listen(server, options.port ?? 4010, options.host ?? '127.0.0.1');
+    const { port, address } = server.address();
+    const host = address.includes(':') ? `[${address}]` : address;
+    return {
+        url: `http://${host}:${port}/?token=${token}`,
+        token,
+        async close() {
+            await new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())));
+            await admin.close();
+        },
+    };
+}
+function listen(server, port, host) {
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, host, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+}
+function holdsToken(request, token) {
+    const bearer = request.headers.get('authorization')?.match(/^Bearer (.+)$/)?.[1];
+    const cookie = request.headers
+        .get('cookie')
+        ?.split(';')
+        .map((part) => part.trim().split('='))
+        .find(([name]) => name === COOKIE)?.[1];
+    return [bearer, cookie].some((given) => given !== undefined && same(given, token));
+}
+function same(given, token) {
+    const a = Buffer.from(given);
+    const b = Buffer.from(token);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+const HELP = `otw-db: a database manager in your browser
+
+Usage: otw-db [--port 4010] [--host 127.0.0.1] [--env-file .env]
+
+Connections come from the environment (and .env, when there is one):
+  DB_ADMIN_<NAME>_URL     postgres://user:password@host:5432/db
+  DB_ADMIN_<NAME>_ACCESS  read (default) or write
+  DB_ADMIN_<NAME>_LABEL   shown instead of the name
+  DB_ADMIN_<NAME>_TAG     local, development, testing, staging or production
+`;
+/** The `otw-db` command. */
+export async function main(argv = process.argv.slice(2)) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            port: { type: 'string', default: '4010' },
+            host: { type: 'string', default: '127.0.0.1' },
+            'env-file': { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    if (values.help) {
+        process.stdout.write(HELP);
+        return;
+    }
+    const envFile = values['env-file'] ?? (existsSync('.env') ? '.env' : undefined);
+    if (envFile)
+        process.loadEnvFile(envFile);
+    const connections = connectionsFromEnv();
+    if (!connections.length) {
+        process.stderr.write(`No connections: set DB_ADMIN_<NAME>_URL.\n\n${HELP}`);
+        process.exitCode = 1;
+        return;
+    }
+    const port = Number(values.port);
+    if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+        throw new Error(`--port is a port number, not "${values.port}".`);
+    }
+    const server = await startServer({ connections, port, host: values.host });
+    process.stdout.write(`OTW DB is running. Open ${server.url}\n`);
+    const stop = () => void server.close().then(() => process.exit(0));
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { DbAdmin } from '@otwdesign/db-core';
+/** Express's and Connect's `next`: called for paths outside the base path, and with errors. */
+export type Next = (error?: unknown) => void;
+/** A node:http-style handler, as Express, Connect and `http.createServer` take. It resolves once the response is sent. */
+export type NodeHandler = (request: IncomingMessage, response: ServerResponse, next?: Next) => Promise<void>;
+/**
+ * The Fetch handler for node:http servers. Paths outside the admin's base path go to `next`
+ * when there is one (Express, Connect), and get a 404 otherwise. A body a body-parser already
+ * read (`express.json()`) is passed on as it parsed it.
+ */
+export declare function toNodeHandler(admin: Pick<DbAdmin, 'fetch' | 'basePath'>): NodeHandler;
+/** A Fetch Request for the Node one: its URL, headers and body, aborted if the browser leaves. */
+export declare function toRequest(req: IncomingMessage, res: ServerResponse, path?: string): Request;
+/** Writes a Fetch Response to a Node one, streaming its body. */
+export declare function send(res: ServerResponse, response: Response): Promise<void>;
+/** What the Fastify plugin uses of Fastify: shapes only, so this package needs no fastify. */
+interface FastifyLike {
+    removeAllContentTypeParsers(): void;
+    addContentTypeParser(type: string, parser: (request: unknown, payload: unknown, done: (error: Error | null, body?: unknown) => void) => void): void;
+    all(path: string, handler: (request: {
+        raw: IncomingMessage;
+    }, reply: {
+        raw: ServerResponse;
+        hijack(): void;
+    }) => Promise<void>): void;
+}
+/**
+ * A Fastify plugin: `app.register(fastifyPlugin(dbAdmin))`. Its routes leave the body unread,
+ * as Fastify's own parsers would read it first, and answer through Node's response. Register it
+ * as it is, not through fastify-plugin, so its parser settings stay inside it.
+ */
+export declare function fastifyPlugin(admin: Pick<DbAdmin, 'fetch' | 'basePath'>): (fastify: FastifyLike) => Promise<void>;
+/** What the Koa middleware uses of Koa's context. */
+interface KoaContext {
+    path: string;
+    req: IncomingMessage;
+    res: ServerResponse;
+    respond?: boolean;
+    request: {
+        body?: unknown;
+    };
+}
+/**
+ * Koa middleware: `app.use(koaMiddleware(dbAdmin))`. Paths outside the base path go on to the
+ * next middleware. A body a parser before it read (koa-bodyparser) is handed over.
+ */
+export declare function koaMiddleware(admin: Pick<DbAdmin, 'fetch' | 'basePath'>): (ctx: KoaContext, next: () => Promise<unknown>) => Promise<unknown>;
+export {};

package/dist/index.js

@@ -0,0 +1,131 @@
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+/**
+ * The Fetch handler for node:http servers. Paths outside the admin's base path go to `next`
+ * when there is one (Express, Connect), and get a 404 otherwise. A body a body-parser already
+ * read (`express.json()`) is passed on as it parsed it.
+ */
+export function toNodeHandler(admin) {
+    return async (req, res, next) => {
+        try {
+            // Express strips its mount path from `url` and keeps the whole one in `originalUrl`.
+            const path = req.originalUrl ?? req.url ?? '/';
+            if (!within(path, admin.basePath)) {
+                if (next)
+                    return next();
+                res.statusCode = 404;
+                res.end();
+                return;
+            }
+            await send(res, await admin.fetch(toRequest(req, res, path)));
+        }
+        catch (error) {
+            // The browser went away mid-response: nothing left to tell it.
+            if (res.destroyed)
+                return;
+            if (next)
+                return next(error);
+            console.error('otw-db: a request failed', error);
+            if (res.headersSent)
+                res.destroy(error);
+            else {
+                res.statusCode = 500;
+                res.end();
+            }
+        }
+    };
+}
+function within(path, basePath) {
+    if (!basePath)
+        return true;
+    const pathname = path.split('?', 1)[0];
+    return pathname === basePath || pathname.startsWith(`${basePath}/`);
+}
+/** A Fetch Request for the Node one: its URL, headers and body, aborted if the browser leaves. */
+export function toRequest(req, res, path = req.url ?? '/') {
+    const protocol = req.socket.encrypted ? 'https' : 'http';
+    const url = new URL(path, `${protocol}://${req.headers.host ?? 'localhost'}`);
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (value === undefined)
+            continue;
+        for (const one of Array.isArray(value) ? value : [value])
+            headers.append(name, one);
+    }
+    const controller = new AbortController();
+    res.once('close', () => {
+        if (!res.writableFinished)
+            controller.abort();
+    });
+    const method = req.method ?? 'GET';
+    const init = { method, headers, signal: controller.signal };
+    if (method !== 'GET' && method !== 'HEAD') {
+        if (req.readableEnded) {
+            // Read already, by a body parser: what it parsed is all there is.
+            const parsed = req.body;
+            headers.delete('content-length');
+            if (parsed !== undefined) {
+                init.body =
+                    typeof parsed === 'string' || parsed instanceof Uint8Array
+                        ? parsed
+                        : JSON.stringify(parsed);
+            }
+        }
+        else {
+            init.body = Readable.toWeb(req);
+            init.duplex = 'half';
+        }
+    }
+    return new Request(url, init);
+}
+/** Writes a Fetch Response to a Node one, streaming its body. */
+export async function send(res, response) {
+    res.statusCode = response.status;
+    for (const [name, value] of response.headers) {
+        if (name !== 'set-cookie')
+            res.setHeader(name, value);
+    }
+    const cookies = response.headers.getSetCookie();
+    if (cookies.length)
+        res.setHeader('set-cookie', cookies);
+    if (!response.body) {
+        res.end();
+        return;
+    }
+    await pipeline(Readable.fromWeb(response.body), res);
+}
+/**
+ * A Fastify plugin: `app.register(fastifyPlugin(dbAdmin))`. Its routes leave the body unread,
+ * as Fastify's own parsers would read it first, and answer through Node's response. Register it
+ * as it is, not through fastify-plugin, so its parser settings stay inside it.
+ */
+export function fastifyPlugin(admin) {
+    const handle = toNodeHandler(admin);
+    return async function otwDb(fastify) {
+        fastify.removeAllContentTypeParsers();
+        fastify.addContentTypeParser('*', (_request, _payload, done) => done(null));
+        const route = async (request, reply) => {
+            reply.hijack();
+            await handle(request.raw, reply.raw);
+        };
+        fastify.all(admin.basePath || '/', route);
+        fastify.all(`${admin.basePath}/*`, route);
+    };
+}
+/**
+ * Koa middleware: `app.use(koaMiddleware(dbAdmin))`. Paths outside the base path go on to the
+ * next middleware. A body a parser before it read (koa-bodyparser) is handed over.
+ */
+export function koaMiddleware(admin) {
+    const handle = toNodeHandler(admin);
+    return async (ctx, next) => {
+        if (!within(ctx.path, admin.basePath))
+            return next();
+        const req = ctx.req;
+        if (req.readableEnded && req.body === undefined)
+            req.body = ctx.request.body;
+        ctx.respond = false;
+        await handle(ctx.req, ctx.res);
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@otwdesign/db-node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.1",
+  "description": "OTW DB for Node servers: node:http, Express, Connect, Fastify and Koa; Hono, Bun and Deno take db-core's Fetch handler as it is.",
+  "license": "Apache-2.0",
+  "author": "OTW SRL",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OTWSRL/otw-db.git",
+    "directory": "packages/node"
+  },
+  "homepage": "https://github.com/OTWSRL/otw-db/tree/main/packages/node#readme",
+  "bugs": {
+    "url": "https://github.com/OTWSRL/otw-db/issues"
+  },
+  "keywords": [
+    "database",
+    "admin",
+    "express",
+    "fastify",
+    "koa"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    ".": {
+      "@otwdesign/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cli": {
+      "@otwdesign/source": "./src/cli.ts",
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "@otwdesign/db-core": "1.0.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "express": "^5.3.0",
+    "fastify": "^5.12.8",
+    "koa": "^3.3.0",
+    "@types/koa": "^3.0.3",
+    "koa-bodyparser": "^4.4.1",
+    "@types/koa-bodyparser": "^4.3.13",
+    "hono": "^4.13.16",
+    "@hono/node-server": "^2.1.6"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }

package/src/cli.ts

@@ -0,0 +1,139 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { createServer, type Server } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { parseArgs } from 'node:util'
+import { connectionsFromEnv, createDbAdmin, type ConnectionConfig } from '@otwdesign/db-core'
+import { toNodeHandler } from './index.ts'
+
+const COOKIE = 'otw_db_token'
+
+export interface ServerOptions {
+  connections: readonly ConnectionConfig[]
+  /** Default 4010; 0 picks a free port. */
+  port?: number
+  /** Default 127.0.0.1: only this machine. */
+  host?: string
+  /** Generated when not given. */
+  token?: string
+}
+
+export interface RunningServer {
+  /** Opening it signs the browser in. */
+  url: string
+  token: string
+  close(): Promise<void>
+}
+
+/**
+ * OTW DB on its own HTTP server. Anyone with the token may use it, so it listens on this machine
+ * only unless told otherwise; the link it prints signs the browser in with an HttpOnly cookie.
+ */
+export async function startServer(options: ServerOptions): Promise<RunningServer> {
+  const token = options.token ?? randomBytes(24).toString('base64url')
+  const admin = createDbAdmin({
+    connections: options.connections,
+    authorize: (request) => (holdsToken(request, token) ? { id: 'local' } : null),
+  })
+  const handle = toNodeHandler(admin)
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? '/', 'http://localhost')
+    const given = url.searchParams.get('token')
+    if (given !== null) {
+      url.searchParams.delete('token')
+      const back = `${url.pathname}${url.search}`
+      res.statusCode = 303
+      res.setHeader('location', back)
+      if (same(given, token)) {
+        res.setHeader('set-cookie', `${COOKIE}=${token}; HttpOnly; SameSite=Strict; Path=/`)
+      }
+      res.end()
+      return
+    }
+    void handle(req, res)
+  })
+  await listen(server, options.port ?? 4010, options.host ?? '127.0.0.1')
+  const { port, address } = server.address() as AddressInfo
+  const host = address.includes(':') ? `[${address}]` : address
+  return {
+    url: `http://${host}:${port}/?token=${token}`,
+    token,
+    async close() {
+      await new Promise<void>((resolve, reject) =>
+        server.close((error) => (error ? reject(error) : resolve())),
+      )
+      await admin.close()
+    },
+  }
+}
+
+function listen(server: Server, port: number, host: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(port, host, () => {
+      server.off('error', reject)
+      resolve()
+    })
+  })
+}
+
+function holdsToken(request: Request, token: string): boolean {
+  const bearer = request.headers.get('authorization')?.match(/^Bearer (.+)$/)?.[1]
+  const cookie = request.headers
+    .get('cookie')
+    ?.split(';')
+    .map((part) => part.trim().split('='))
+    .find(([name]) => name === COOKIE)?.[1]
+  return [bearer, cookie].some((given) => given !== undefined && same(given, token))
+}
+
+function same(given: string, token: string): boolean {
+  const a = Buffer.from(given)
+  const b = Buffer.from(token)
+  return a.length === b.length && timingSafeEqual(a, b)
+}
+
+const HELP = `otw-db: a database manager in your browser
+
+Usage: otw-db [--port 4010] [--host 127.0.0.1] [--env-file .env]
+
+Connections come from the environment (and .env, when there is one):
+  DB_ADMIN_<NAME>_URL     postgres://user:password@host:5432/db
+  DB_ADMIN_<NAME>_ACCESS  read (default) or write
+  DB_ADMIN_<NAME>_LABEL   shown instead of the name
+  DB_ADMIN_<NAME>_TAG     local, development, testing, staging or production
+`
+
+/** The `otw-db` command. */
+export async function main(argv = process.argv.slice(2)): Promise<void> {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      port: { type: 'string', default: '4010' },
+      host: { type: 'string', default: '127.0.0.1' },
+      'env-file': { type: 'string' },
+      help: { type: 'boolean', short: 'h' },
+    },
+  })
+  if (values.help) {
+    process.stdout.write(HELP)
+    return
+  }
+  const envFile = values['env-file'] ?? (existsSync('.env') ? '.env' : undefined)
+  if (envFile) process.loadEnvFile(envFile)
+  const connections = connectionsFromEnv()
+  if (!connections.length) {
+    process.stderr.write(`No connections: set DB_ADMIN_<NAME>_URL.\n\n${HELP}`)
+    process.exitCode = 1
+    return
+  }
+  const port = Number(values.port)
+  if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+    throw new Error(`--port is a port number, not "${values.port}".`)
+  }
+  const server = await startServer({ connections, port, host: values.host })
+  process.stdout.write(`OTW DB is running. Open ${server.url}\n`)
+  const stop = () => void server.close().then(() => process.exit(0))
+  process.once('SIGINT', stop)
+  process.once('SIGTERM', stop)
+}

package/src/index.ts

@@ -0,0 +1,172 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { TLSSocket } from 'node:tls'
+import { Readable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import type { ReadableStream as NodeReadableStream } from 'node:stream/web'
+import type { DbAdmin } from '@otwdesign/db-core'
+
+/** Express's and Connect's `next`: called for paths outside the base path, and with errors. */
+export type Next = (error?: unknown) => void
+
+/** A node:http-style handler, as Express, Connect and `http.createServer` take. It resolves once the response is sent. */
+export type NodeHandler = (
+  request: IncomingMessage,
+  response: ServerResponse,
+  next?: Next,
+) => Promise<void>
+
+/**
+ * The Fetch handler for node:http servers. Paths outside the admin's base path go to `next`
+ * when there is one (Express, Connect), and get a 404 otherwise. A body a body-parser already
+ * read (`express.json()`) is passed on as it parsed it.
+ */
+export function toNodeHandler(admin: Pick<DbAdmin, 'fetch' | 'basePath'>): NodeHandler {
+  return async (req, res, next) => {
+    try {
+      // Express strips its mount path from `url` and keeps the whole one in `originalUrl`.
+      const path = (req as IncomingMessage & { originalUrl?: string }).originalUrl ?? req.url ?? '/'
+      if (!within(path, admin.basePath)) {
+        if (next) return next()
+        res.statusCode = 404
+        res.end()
+        return
+      }
+      await send(res, await admin.fetch(toRequest(req, res, path)))
+    } catch (error) {
+      // The browser went away mid-response: nothing left to tell it.
+      if (res.destroyed) return
+      if (next) return next(error)
+      console.error('otw-db: a request failed', error)
+      if (res.headersSent) res.destroy(error as Error)
+      else {
+        res.statusCode = 500
+        res.end()
+      }
+    }
+  }
+}
+
+function within(path: string, basePath: string): boolean {
+  if (!basePath) return true
+  const pathname = path.split('?', 1)[0]!
+  return pathname === basePath || pathname.startsWith(`${basePath}/`)
+}
+
+/** A Fetch Request for the Node one: its URL, headers and body, aborted if the browser leaves. */
+export function toRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  path = req.url ?? '/',
+): Request {
+  const protocol = (req.socket as TLSSocket).encrypted ? 'https' : 'http'
+  const url = new URL(path, `${protocol}://${req.headers.host ?? 'localhost'}`)
+  const headers = new Headers()
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (value === undefined) continue
+    for (const one of Array.isArray(value) ? value : [value]) headers.append(name, one)
+  }
+  const controller = new AbortController()
+  res.once('close', () => {
+    if (!res.writableFinished) controller.abort()
+  })
+  const method = req.method ?? 'GET'
+  const init: RequestInit & { duplex?: 'half' } = { method, headers, signal: controller.signal }
+  if (method !== 'GET' && method !== 'HEAD') {
+    if (req.readableEnded) {
+      // Read already, by a body parser: what it parsed is all there is.
+      const parsed = (req as IncomingMessage & { body?: unknown }).body
+      headers.delete('content-length')
+      if (parsed !== undefined) {
+        init.body =
+          typeof parsed === 'string' || parsed instanceof Uint8Array
+            ? (parsed as BodyInit)
+            : JSON.stringify(parsed)
+      }
+    } else {
+      init.body = Readable.toWeb(req) as ReadableStream<Uint8Array>
+      init.duplex = 'half'
+    }
+  }
+  return new Request(url, init)
+}
+
+/** Writes a Fetch Response to a Node one, streaming its body. */
+export async function send(res: ServerResponse, response: Response): Promise<void> {
+  res.statusCode = response.status
+  for (const [name, value] of response.headers) {
+    if (name !== 'set-cookie') res.setHeader(name, value)
+  }
+  const cookies = response.headers.getSetCookie()
+  if (cookies.length) res.setHeader('set-cookie', cookies)
+  if (!response.body) {
+    res.end()
+    return
+  }
+  await pipeline(Readable.fromWeb(response.body as NodeReadableStream), res)
+}
+
+/** What the Fastify plugin uses of Fastify: shapes only, so this package needs no fastify. */
+interface FastifyLike {
+  removeAllContentTypeParsers(): void
+  addContentTypeParser(
+    type: string,
+    parser: (
+      request: unknown,
+      payload: unknown,
+      done: (error: Error | null, body?: unknown) => void,
+    ) => void,
+  ): void
+  all(
+    path: string,
+    handler: (
+      request: { raw: IncomingMessage },
+      reply: { raw: ServerResponse; hijack(): void },
+    ) => Promise<void>,
+  ): void
+}
+
+/**
+ * A Fastify plugin: `app.register(fastifyPlugin(dbAdmin))`. Its routes leave the body unread,
+ * as Fastify's own parsers would read it first, and answer through Node's response. Register it
+ * as it is, not through fastify-plugin, so its parser settings stay inside it.
+ */
+export function fastifyPlugin(admin: Pick<DbAdmin, 'fetch' | 'basePath'>) {
+  const handle = toNodeHandler(admin)
+  return async function otwDb(fastify: FastifyLike): Promise<void> {
+    fastify.removeAllContentTypeParsers()
+    fastify.addContentTypeParser('*', (_request, _payload, done) => done(null))
+    const route = async (
+      request: { raw: IncomingMessage },
+      reply: { raw: ServerResponse; hijack(): void },
+    ) => {
+      reply.hijack()
+      await handle(request.raw, reply.raw)
+    }
+    fastify.all(admin.basePath || '/', route)
+    fastify.all(`${admin.basePath}/*`, route)
+  }
+}
+
+/** What the Koa middleware uses of Koa's context. */
+interface KoaContext {
+  path: string
+  req: IncomingMessage
+  res: ServerResponse
+  respond?: boolean
+  request: { body?: unknown }
+}
+
+/**
+ * Koa middleware: `app.use(koaMiddleware(dbAdmin))`. Paths outside the base path go on to the
+ * next middleware. A body a parser before it read (koa-bodyparser) is handed over.
+ */
+export function koaMiddleware(admin: Pick<DbAdmin, 'fetch' | 'basePath'>) {
+  const handle = toNodeHandler(admin)
+  return async (ctx: KoaContext, next: () => Promise<unknown>): Promise<unknown> => {
+    if (!within(ctx.path, admin.basePath)) return next()
+    const req = ctx.req as IncomingMessage & { body?: unknown }
+    if (req.readableEnded && req.body === undefined) req.body = ctx.request.body
+    ctx.respond = false
+    await handle(ctx.req, ctx.res)
+  }
+}