@nano-app/plugins 0.2.0 → 0.3.0

package/README.md

@@ -1,14 +1,16 @@
 # @nano-app/plugins
 
+[![plugins](https://img.shields.io/npm/v/@nano-app/plugins?label=plugins)](https://www.npmjs.com/package/@nano-app/plugins)
+
 Official plugins for [`@nano-app/backend`](https://www.npmjs.com/package/@nano-app/backend). One import path per plugin: `@nano-app/plugins/<name>`. Nothing is mounted unless you list it.
 
 ```bash
-npm install @nano-app/backend @nano-app/plugins
+pnpm add @nano-app/backend @nano-app/plugins
 ```
 
 ```ts
-import { createNanoApp } from "@nano-app/backend";
-import health from "@nano-app/plugins/health";
+import { createNanoApp } from '@nano-app/backend';
+import health from '@nano-app/plugins/health';
 
 createNanoApp({ plugins: [health()] });
 ```
@@ -17,62 +19,7 @@ createNanoApp({ plugins: [health()] });
 
 | Plugin | Import | Endpoints | Options |
 |---|---|---|---|
-| `health` | `import health from "@nano-app/plugins/health"` | `GET /health` → `{ status: "ok" }` | `basePath` (default `"/health"`) |
-| `auth` | `import auth from "@nano-app/plugins/auth"` | `/api-keys`, and an API key guard on every route after it | see [auth](#auth) |
-
-## auth
-
-API keys. Every route mounted after the plugin needs a valid key in the `x-api-key` header; the routes of the plugins listed before it and `publicPaths` stay public. The keys are managed with the master key, created on the first startup.
-
-```ts
-import { createNanoApp } from "@nano-app/backend";
-import health from "@nano-app/plugins/health";
-import auth from "@nano-app/plugins/auth";
-
-// health is listed before auth: it stays public
-createNanoApp({ plugins: [health(), auth({ publicPaths: ["/webhooks/telegram"] })] });
-```
-
-| Option | Default | |
-|---|---|---|
-| `basePath` | `"/api-keys"` | Base path of the endpoints that manage the keys |
-| `publicPaths` | `[]` | Exact paths that need no key |
-
-### Table
-
-The keys live in `nano_auth.api_key`, through the app's Prisma (`DATABASE_URL`). Only the SHA-256 of each key is stored. nano-app creates and migrates the table at startup: there is nothing to run.
-
-### Master key
-
-The first startup creates it and prints it **once** in the console: keep it. A unique index allows a single master, also when several instances start together. It cannot be deleted. If it is lost, delete its row (`isMaster = true`) and restart: a new one is created and printed.
-
-### Endpoints
-
-Only the master key reaches them (403 with any other key).
-
-| Request | Answer |
-|---|---|
-| `GET /api-keys` | The keys: `id`, `name`, `isMaster`, `createdAt`. Never the key |
-| `POST /api-keys` `{ name }` | A new key, with its `key` only in this response |
-| `DELETE /api-keys/:id` | Deletes it; it stops working at once. 403 on the master |
-| `POST /api-keys/:id/renew` | Same id, a new `key`; the old one stops working at once |
-| `POST /api-keys/master/renew` | Renews the master |
-
-### Guard
-
-| Request | Answer |
-|---|---|
-| Path in `publicPaths`, or served before the plugin | passes |
-| No key, or a key that does not exist | 401 |
-| Any valid key, the master included | passes |
-
-### Users and sessions
-
-The plugin covers API keys only: it has no users, login or sessions. If your app needs them, we recommend integrating [Better Auth](https://www.better-auth.com) yourself:
-
-- Wrap its handler in a plugin of your own and list it **before** `auth()`, so its endpoints (sign-in, sign-up, ...) stay public.
-- Give its tables their own PostgreSQL schema, outside `nano_*`, and apply its migrations with its CLI: nano-app does not migrate them.
-- To protect your routes with a session instead of a key, check it in your handlers or in an `onBefore` of your own.
+| `health` | `import health from '@nano-app/plugins/health'` | `GET /health` → `{ status: "ok" }` | `basePath` (default `"/health"`) |
 
 ## Layout
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nano-app/plugins",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Official plugins for @nano-app/backend",
   "type": "module",
   "exports": {

package/build/auth/index.d.ts

@@ -1,9 +0,0 @@
-import { AuthOptions } from "../types/auth.js";
-//#region auth/index.d.ts
-/**
- * API keys: every route mounted after this plugin needs a valid `x-api-key`.
- * The master key, created on the first startup, manages the rest under `basePath`
- */
-declare const _default: (options?: AuthOptions | undefined) => import("@nano-app/backend").PluginConfig<AuthOptions>;
-//#endregion
-export { _default as default };

package/build/auth/index.js

@@ -1,36 +0,0 @@
-import { ensureMaster, findKey } from "./keys.js";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { createPlugin, createPluginCallbacks } from "@nano-app/backend";
-//#region auth/index.ts
-/** Folder of this file, from the sources and from the build */
-const DIR = dirname(fileURLToPath(import.meta.url));
-/**
-* API keys: every route mounted after this plugin needs a valid `x-api-key`.
-* The master key, created on the first startup, manages the rest under `basePath`
-*/
-var auth_default = createPlugin((options) => {
-	const { basePath = "/api-keys", publicPaths = [] } = options ?? {};
-	return {
-		name: "auth",
-		basePath,
-		stage: "before",
-		routesDir: resolve(DIR, "routes"),
-		database: {
-			enabled: true,
-			schemaPath: resolve(DIR, "schema.prisma")
-		},
-		callbacks: createPluginCallbacks({ onMount: async (oApp, { db }) => {
-			await ensureMaster(db);
-			oApp.use((oReq, _oRes, fnNext) => {
-				if (publicPaths.includes(oReq.path)) return fnNext();
-				findKey(db, oReq.get("x-api-key")).then((oKey) => fnNext(oKey ? void 0 : {
-					status: 401,
-					message: "Invalid or missing API key"
-				})).catch(fnNext);
-			});
-		} })
-	};
-});
-//#endregion
-export { auth_default as default };

package/build/auth/keys.js

@@ -1,36 +0,0 @@
-import { createHash, randomBytes } from "node:crypto";
-//#region auth/keys.ts
-/** Name of the master key */
-const MASTER = "master";
-/** A new random key: 32 bytes, URL-safe */
-function generateKey() {
-	return randomBytes(32).toString("base64url");
-}
-/** SHA-256 of a key, as the table stores it */
-function hashKey(sKey) {
-	return createHash("sha256").update(sKey).digest("hex");
-}
-/** The stored key that matches the `x-api-key` header, or null */
-async function findKey(oDb, sKey) {
-	if (!sKey) return null;
-	return oDb.apiKey.findUnique({ where: { hash: hashKey(sKey) } });
-}
-/**
-* Creates the master key when there is none, and prints it once.
-* The unique index on isMaster lets a single instance insert it when several start together
-*/
-async function ensureMaster(oDb) {
-	const sKey = generateKey();
-	const { count } = await oDb.apiKey.createMany({
-		data: [{
-			name: MASTER,
-			hash: hashKey(sKey),
-			isMaster: true
-		}],
-		skipDuplicates: true
-	});
-	if (!count) return;
-	console.warn(["[nano-app] [WARNING] auth: master API key created. It is shown only once, keep it:", sKey].join("\n"));
-}
-//#endregion
-export { MASTER, ensureMaster, findKey, generateKey, hashKey };

package/build/auth/migrations/20261019000000_init/migration.sql

@@ -1,20 +0,0 @@
--- CreateSchema
-CREATE SCHEMA IF NOT EXISTS "nano_auth";
-
--- CreateTable
-CREATE TABLE "nano_auth"."api_key" (
-    "id" TEXT NOT NULL,
-    "name" TEXT NOT NULL,
-    "hash" TEXT NOT NULL,
-    "isMaster" BOOLEAN,
-    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
-
-    CONSTRAINT "api_key_pkey" PRIMARY KEY ("id")
-);
-
--- CreateIndex
-CREATE UNIQUE INDEX "api_key_hash_key" ON "nano_auth"."api_key"("hash");
-
--- CreateIndex
-CREATE UNIQUE INDEX "api_key_isMaster_key" ON "nano_auth"."api_key"("isMaster");
-

package/build/auth/migrations/migration_lock.toml

@@ -1,3 +0,0 @@
-# Please do not edit this file manually
-# It should be added in your version-control system (e.g., Git)
-provider = "postgresql"

package/build/auth/routes/index.route.js

@@ -1,96 +0,0 @@
-import { findKey, generateKey, hashKey } from "../keys.js";
-import { createRoute } from "@nano-app/backend";
-//#region auth/routes/index.route.ts
-/** Columns the endpoints return: never the hash */
-const SELECT = {
-	id: true,
-	name: true,
-	isMaster: true,
-	createdAt: true
-};
-/** 404 of an id or an action that does not exist */
-function notFound(oReq) {
-	return {
-		status: 404,
-		message: `${oReq.path} not found`
-	};
-}
-/**
-* API keys, managed only with the master key:
-*   GET    /                list them
-*   POST   /                create one { name }; the key is returned only now
-*   DELETE /:id             delete one (not the master)
-*   POST   /:id/renew       new key, same id ("master" renews the master)
-*/
-var index_route_default = createRoute({
-	expression: "{/:id}{/:action}",
-	callbacks: { onBefore: async (oReq, _sMethod, { db }) => {
-		if (!(await findKey(db, oReq.get("x-api-key")))?.isMaster) throw {
-			status: 403,
-			message: "Only the master API key manages API keys"
-		};
-		return {};
-	} },
-	GET: async (oReq, { db }) => {
-		if (oReq.params.id) throw notFound(oReq);
-		return {
-			success: true,
-			result: await db.apiKey.findMany({ select: SELECT })
-		};
-	},
-	POST: async (oReq, { db }) => {
-		const { id, action } = oReq.params;
-		if (id && action === "renew") {
-			const oWhere = id === "master" ? { isMaster: true } : { id };
-			const oKey = await db.apiKey.findFirst({ where: oWhere });
-			if (!oKey) throw notFound(oReq);
-			const sKey = generateKey();
-			await db.apiKey.update({
-				where: { id: oKey.id },
-				data: { hash: hashKey(sKey) }
-			});
-			return {
-				success: true,
-				result: {
-					id: oKey.id,
-					name: oKey.name,
-					key: sKey
-				}
-			};
-		}
-		if (id) throw notFound(oReq);
-		const { name } = oReq.body ?? {};
-		if (typeof name !== "string" || !name.trim()) throw "The API key needs a name";
-		const sKey = generateKey();
-		return {
-			success: true,
-			result: {
-				...await db.apiKey.create({
-					data: {
-						name,
-						hash: hashKey(sKey)
-					},
-					select: SELECT
-				}),
-				key: sKey
-			}
-		};
-	},
-	DELETE: async (oReq, { db }) => {
-		const { id, action } = oReq.params;
-		if (!id || action) throw notFound(oReq);
-		const oKey = await db.apiKey.findUnique({ where: { id } });
-		if (!oKey) throw notFound(oReq);
-		if (oKey.isMaster) throw {
-			status: 403,
-			message: "The master API key cannot be deleted"
-		};
-		await db.apiKey.delete({ where: { id } });
-		return {
-			success: true,
-			result: { id }
-		};
-	}
-});
-//#endregion
-export { index_route_default as default };

package/build/auth/schema.prisma

@@ -1,23 +0,0 @@
-// API keys of the auth plugin, in the nano_auth schema
-datasource db {
-  provider = "postgresql"
-  schemas  = ["nano_auth"]
-}
-
-generator client {
-  provider = "prisma-client"
-  output   = "./generated"
-}
-
-model ApiKey {
-  id        String   @id @default(uuid())
-  name      String
-  /// SHA-256 of the key: the key itself is never stored
-  hash      String   @unique
-  /// true on the master key, null on the rest: the unique index allows a single master
-  isMaster  Boolean? @unique
-  createdAt DateTime @default(now())
-
-  @@map("api_key")
-  @@schema("nano_auth")
-}

package/build/types/auth.d.ts

@@ -1,9 +0,0 @@
-//#region types/auth.d.ts
-/** Options of the auth plugin */
-export type AuthOptions = {
-  /** Base path of the API key endpoints. Defaults to "/api-keys" */
-  basePath?: string;
-  /** Exact paths that need no API key, e.g. "/webhooks/telegram". Defaults to [] */
-  publicPaths?: string[];
-};
-//#endregion