nextpluggable 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,289 @@
-# Temporary Holding Version
+# NextPluggable
 
-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.
+WordPress-style plugins for Next.js. Add one package to a site and its owner gets a
+dashboard where they connect GitHub repositories that hold plugins, then install,
+configure, update and remove those plugins themselves: no developer, no rebuild, no
+redeploy.
+
+Plugins are full features, not UI snippets. One plugin can add server-rendered pages
+that search engines index, HTTP endpoints, stored data, widgets in the site's layout,
+a settings form, and its own screens inside the dashboard.
+
+> **Status: working prototype.** Everything described here is
+> implemented and covered by tests in this repository. See [Limits](#limits) before
+> relying on it, and [docs/research.md](https://github.com/rohittp0/NextPluggable/blob/main/docs/research.md) for why it is built this way.
+
+**Documentation: <https://rohittp0.github.io/NextPluggable/>.** Each guide also exists
+as Markdown written for coding agents: give yours
+[`integrate.md`](https://rohittp0.github.io/NextPluggable/integrate.md) to add
+NextPluggable to a site, or
+[`build.md`](https://rohittp0.github.io/NextPluggable/build.md) to write plugins.
+
+## What the site owner does
+
+1. Opens `/admin/plugins` and signs in.
+2. Pastes the address of a GitHub repository under **Sources**. For a private
+   repository, the dashboard walks them through creating a read-only access token.
+3. Picks a plugin under **Add plugins**. A confirmation lists, in plain language, what
+   it adds and what it is allowed to do.
+4. The plugin is live about a second later. Its settings are an ordinary form; the
+   address of each page it adds can be changed; it can be paused, updated or removed
+   with one click.
+
+## What the developer does, once
+
+```bash
+npm install nextpluggable
+npx nextpluggable init
+```
+
+`init` adds four small files to an App Router project and never overwrites existing
+ones:
+
+| File | Purpose |
+|---|---|
+| `lib/nextpluggable.ts` | Settings: sign-in, storage, site name |
+| `app/admin/plugins/[[...np]]/page.tsx` | The dashboard |
+| `app/api/nextpluggable/[...np]/route.ts` | The dashboard's API, plugin files, and plugins' own endpoints |
+| `app/[...slug]/page.tsx` | Serves the pages plugins add. Your own routes always win; unknown addresses still get your 404 page. Optional page caching is two commented lines in this file |
+
+It also writes a generated dashboard password and secret to `.env.local`.
+
+If the site already has a root catch-all route, `init` leaves it alone. Serve plugin
+pages from it yourself: render `<np.PluginPage params={params} />` where your own lookup
+finds nothing, or, when that route never returns a 404 (a landing page for any address,
+say), ask first:
+
+```tsx
+if (await np.hasPluginPage(`/${segments.join('/')}`)) return <np.PluginPage params={params} />;
+```
+
+Optionally, mark places in your layout that plugins may fill:
+
+```tsx
+import { np } from '@/lib/nextpluggable';
+
+<nav>
+  …
+  <np.Slot name="header.actions" />
+</nav>
+…
+<np.Slot name="body.end" />
+```
+
+### Settings
+
+```ts
+import { createNextPluggable, customAuth, upstashStorage } from 'nextpluggable';
+
+export const np = createNextPluggable({
+  siteName: 'Harbor Lending',
+  // Who may use the dashboard. Default: one password from NEXTPLUGGABLE_PASSWORD.
+  auth: customAuth({
+    getUser: async (request) => {
+      const session = await getSessionSomehow(request); // Auth.js, Clerk, your own…
+      return session?.role === 'admin' ? { id: session.userId, name: session.name } : null;
+    },
+    loginUrl: '/login',
+  }),
+  // Where data lives. Default: a .nextpluggable folder.
+  storage: upstashStorage(),
+});
+```
+
+| Storage | Use it when |
+|---|---|
+| `fileStorage()` (default) | Local development, or one long-running server with a disk. Set `NEXTPLUGGABLE_DATA_DIR` to choose the folder |
+| `postgresStorage({ query })` | You already have Postgres. Pass your client's query function, e.g. `(text, params) => pool.query(text, params)` |
+| `upstashStorage()` | Serverless hosts such as Vercel. Reads `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` |
+| `memoryStorage()` | Tests |
+
+| Environment variable | Meaning |
+|---|---|
+| `NEXTPLUGGABLE_PASSWORD` | Dashboard password (when using the default sign-in) |
+| `NEXTPLUGGABLE_SECRET` | Signs sessions and encrypts stored secrets. Required in production |
+| `NEXT_PUBLIC_SITE_URL` | Public address of the site, used for canonical links |
+| `NEXTPLUGGABLE_GITHUB_TOKEN` | Optional token used for every GitHub source that has none of its own; also lifts GitHub's limit of 60 requests an hour |
+
+## Writing plugins
+
+A plugin is a folder with a manifest, React components and optional server code:
+
+```
+my-plugin/
+  plugin.json      what it adds, its settings form, what it may do
+  src/client.tsx   React components: pages, layout widgets, dashboard screens
+  src/server.ts    page loaders (data + SEO metadata) and HTTP endpoints
+  dist/            built output, committed
+```
+
+```bash
+npm install --save-dev @nextpluggable/plugin esbuild
+npx nextpluggable-plugin build
+```
+
+A repository can hold one plugin at its root, or several listed in a root
+`nextpluggable.json`. Hosts install straight from the repository at an exact commit.
+The full guide is in [docs/build.md](https://github.com/rohittp0/NextPluggable/blob/main/docs/build.md).
+
+This repository is itself a plugin source with two reference plugins:
+
+| Plugin | Shows |
+|---|---|
+| [EMI Calculator](https://github.com/rohittp0/NextPluggable/tree/main/plugins/emi-calculator) | A standalone tool: one server-rendered, interactive page with a dozen settings. 5 kB of JavaScript |
+| [Enquiry Form](https://github.com/rohittp0/NextPluggable/tree/main/plugins/enquiry-form) | A full-stack feature: a page, a public endpoint with validation, stored data, a floating button on every page, an inbox inside the dashboard, and an encrypted webhook setting |
+
+## How it works
+
+- **Loading.** A plugin ships prebuilt bundles that leave React to the host. When a
+  plugin page is requested, the site server-renders the plugin's component inside the
+  page using its own React, then the browser loads the same bundle as a normal script
+  and hydrates. Plugin code is never part of the site's build.
+- **SEO.** Plugin pages are real server-rendered HTML, complete for search engines by
+  default: their own title, description, canonical link, Open Graph and Twitter tags,
+  structured data, and an entry in the sitemap (`np.sitemap()`). A plugin can say more;
+  it never has to say anything. Addresses no plugin owns return a real 404.
+- **Speed and cost.** Sharing the site's React keeps plugin bundles small (the EMI
+  calculator is 5 kB). A plugin's stylesheet is written into the page and its script
+  loads without blocking, so a widget on every page adds no request the browser waits
+  for. By default plugin pages are rendered on each request, which is
+  always correct. They can instead be cached like static pages and refreshed the moment
+  anything changes in the dashboard; see [Caching plugin pages](#caching-plugin-pages).
+- **Safety net.** A plugin that crashes while rendering is contained: a broken widget
+  disappears and a broken page shows a short message, while the rest of the site, and
+  the dashboard needed to remove it, keep working. A plugin that fails to start is not
+  installed, and a failed update leaves the working version in place.
+
+## Caching plugin pages
+
+Uncommenting two lines in the generated `app/[...slug]/page.tsx` makes Next.js render
+each plugin page once and serve it from its cache until something changes in the
+dashboard:
+
+```ts
+export const generateStaticParams = async () => [];
+export const revalidate = 3600;
+```
+
+This is the cheapest way to run, and worth doing on sites that are mostly public
+content. Two things to know first, both measured on Next.js 16.4:
+
+- **Your root layout must not read `cookies()` or `headers()` on the server.** If it
+  does, cached plugin pages and unknown addresses fail with a 500 error in production
+  builds. It does not show up in `next dev`, so check with `next build && next start`.
+- **Next.js stores the address of the request that first generated a cached page,
+  query string included, in that page's inline data**, and serves it to later
+  visitors. This is how Next.js caches any on-demand page, not something specific to
+  plugins. If links to your site can carry private values in the query string, leave
+  caching off.
+
+Do not use `export const dynamic = 'force-static'` for this route: with it, a
+component that reads the query string has the first visitor's value rendered into the
+page everyone receives.
+
+Whatever the mode, plugin components never render the query string on the server: the
+SDK only makes it available in the browser.
+
+## Security
+
+- **Plugins are trusted code.** A plugin's server code runs inside your site and can do
+  anything your site can, exactly like a WordPress plugin or an npm package. There is
+  no sandbox yet. Connect only sources you trust.
+- What protects you today: only sources the owner connects are used; every install is
+  pinned to an exact commit; every file is checked against the fingerprint recorded
+  when the plugin was built; the install dialog states what the plugin does.
+- The dashboard requires a sign-in for everything. Sessions are signed, http-only
+  cookies. Writes are protected against cross-site request forgery. Repeated wrong
+  passwords are slowed down.
+- Access tokens and secret settings are encrypted at rest and never sent back to the
+  browser. Settings marked server-only never reach public pages.
+- Folder-based sources (for plugin development) are off in production.
+
+## Limits
+
+- **Next.js Cache Components mode is not supported yet.** With `cacheComponents: true`
+  the build fails. This is the first item on the roadmap because Next.js plans to make
+  that mode the default in version 17.
+- **Node.js runtime only**, 20.16 or newer. It does not run on Cloudflare Workers or
+  other runtimes that forbid evaluating code.
+- **Serverless hosts need a database adapter**; the default file storage needs a disk.
+- **Several server instances:** a dashboard change reaches the other instances'
+  in-memory plugin list within about five seconds, and cached pages rely on your host
+  propagating Next.js revalidation. This has been tested on a single instance only.
+- **Do not put a `loading.tsx` above the catch-all route** while it is uncached (the
+  default). Next.js would start streaming before the plugin lookup finishes, and
+  unknown addresses would return 200 with `noindex` instead of a 404. With caching
+  switched on they return a real 404 either way.
+- **Plugins cannot read the query string on the server.** Pages that vary for search
+  engines should use address segments (`/shop/page/2`); filters and searches read the
+  query in the browser.
+- **Plugin UI is React**, and plugins cannot use Next.js-only features such as server
+  components or server actions.
+- **Plugin storage is a simple key-value store**: fine for settings, messages and small
+  catalogues, not yet for large or heavily queried data.
+
+## Roadmap
+
+1. Cache Components support.
+2. One-click GitHub connection for private repositories (a GitHub App created from the
+   dashboard) in place of pasted tokens.
+3. Sandboxed execution of plugin server code, with the permissions list enforced.
+4. A shopping cart reference plugin, and richer storage (collections with queries).
+5. A second host adapter (Astro) on the same plugin format.
+
+## Repository
+
+| Path | Contents |
+|---|---|
+| `packages/nextpluggable` | The package sites install: dashboard, sign-in, storage, GitHub sources, installer, runtime |
+| `packages/plugin` | `@nextpluggable/plugin`: the SDK and build tool for plugin authors |
+| `plugins/` | Reference plugins, with their built `dist/` committed |
+| `e2e/` | Browser test of the whole owner journey against a mock GitHub API, and the small Next.js site (`e2e/site`) it runs against |
+| `docs/` | The documentation site, served by GitHub Pages: the guides ([integrate](https://github.com/rohittp0/NextPluggable/blob/main/docs/integrate.md), [build plugins](https://github.com/rohittp0/NextPluggable/blob/main/docs/build.md)) and [research and decisions](https://github.com/rohittp0/NextPluggable/blob/main/docs/research.md) |
+| `scripts/` | The release version script and the documentation site generator |
+
+### Checks
+
+```bash
+pnpm build        # packages, then plugins
+pnpm typecheck
+pnpm test         # unit tests; set TEST_POSTGRES_URL to include the Postgres adapter
+pnpm e2e          # browser test, run twice (pages uncached, then cached); needs Playwright with Chromium
+```
+
+Rebuilding the plugins must leave `plugins/*/dist` unchanged: builds are reproducible,
+and the committed output is what sites install.
+
+### Documentation site
+
+GitHub Pages serves the `docs/` folder as it is. The guides are written once, as
+`docs/integrate.md` and `docs/build.md`: those files are what coding agents read, and
+`pnpm docs:build` renders them to the HTML pages people read. Commit the generated
+pages with the Markdown change; `pnpm test` fails when they are out of date. Changes
+under `docs/` do not publish a release.
+
+### Releases
+
+Every merge to `main` publishes `nextpluggable` and `@nextpluggable/plugin` to npm
+under one shared version ([`release.yml`](.github/workflows/release.yml)), tags the
+commit and creates a GitHub release. The patch number goes up by one each time. For a
+minor or major release, set the new version in both `packages/*/package.json` files in
+the pull request; it is published as it is, and patch releases continue from there.
+
+No npm token is stored in the repository. npm lets the workflow publish because each
+package names it as its [trusted publisher](https://docs.npmjs.com/trusted-publishers),
+which can only be set up once a package exists. So there is a one-time setup:
+
+1. Publish the first version by hand, signed in to npm as yourself:
+
+   ```bash
+   pnpm install && pnpm build
+   (cd packages/plugin && pnpm publish --access public --no-git-checks)
+   (cd packages/nextpluggable && pnpm publish --access public --no-git-checks)
+   ```
+
+2. On npmjs.com, open each package's settings and add a trusted publisher: GitHub
+   Actions, user `rohittp0`, repository `NextPluggable`, workflow `release.yml`, with
+   `npm publish` allowed.
+3. Merge to `main` within two days. npm drops a trusted publisher that has not
+   published by then.

package/bin/nextpluggable.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import('../dist/cli.js')
+  .then((cli) => cli.main())
+  .then(
+    (code) => process.exit(code),
+    (err) => {
+      console.error(`✗ ${err instanceof Error ? err.message : String(err)}`);
+      process.exit(1);
+    },
+  );

package/dist/api/handler.d.ts

@@ -0,0 +1,10 @@
+import type { ResolvedConfig } from '../config.js';
+import { type SessionView } from '../views.js';
+export interface HandlerHooks {
+    /** Called after anything that changes what the public site renders. */
+    onSiteChange?: () => void | Promise<void>;
+}
+/** Header every dashboard/plugin write must carry. Browsers will not send it cross-site without a CORS preflight, which we never grant. */
+export declare const CSRF_HEADER = "x-nextpluggable";
+export declare function sessionView(cfg: ResolvedConfig, request: Request): Promise<SessionView>;
+export declare function createHandler(getConfig: () => ResolvedConfig, hooks?: HandlerHooks): (request: Request) => Promise<Response>;

package/dist/api/handler.js

@@ -0,0 +1,188 @@
+import { addSource, changePlugin, installPlugin, refreshAllSources, removeSource, uninstallPlugin, updatePlugin } from '../core/installer.js';
+import { handlePluginApi } from '../core/runtime.js';
+import { getInstalledPlugins } from '../core/state.js';
+import { getFile, getInstalls } from '../core/store.js';
+import { HttpError, jsonResponse } from '../errors.js';
+import { warnOnce } from '../globals.js';
+import { buildDashboardState } from '../views.js';
+const MUTATING = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+/** Header every dashboard/plugin write must carry. Browsers will not send it cross-site without a CORS preflight, which we never grant. */
+export const CSRF_HEADER = 'x-nextpluggable';
+const hostOf = (value) => {
+    if (!value)
+        return null;
+    try {
+        return new URL(value.includes('://') ? value : `http://${value}`).host.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * A browser states where a write came from in its Origin header. It must be this site: the host
+ * the request was addressed to, the host a proxy says it forwarded, or the site's configured
+ * public address (for proxies that rewrite the host and forward nothing).
+ */
+function sameOrigin(request, cfg) {
+    const origin = request.headers.get('origin');
+    if (!origin)
+        return true; // non-browser clients; the custom header check still applies
+    const from = hostOf(origin);
+    if (!from)
+        return false;
+    const here = [request.headers.get('x-forwarded-host')?.split(',')[0]?.trim(), request.headers.get('host'), new URL(request.url).host, cfg.siteUrl].map(hostOf);
+    if (here.includes(from))
+        return true;
+    warnOnce(`origin:${from}`, `Blocked a write from ${origin}: it does not match this site (addressed to ${request.headers.get('host') ?? 'unknown'}, forwarded host ${request.headers.get('x-forwarded-host') ?? 'none'}, configured address ${cfg.siteUrl}). If the site sits behind a proxy, set NEXT_PUBLIC_SITE_URL (or siteUrl) to its public address.`);
+    return false;
+}
+/** Look a plugin up by an id that came from a URL, ignoring inherited object properties. */
+const own = (map, key) => (Object.hasOwn(map, key) ? map[key] : undefined);
+const csrfOk = (request, cfg) => request.headers.get(CSRF_HEADER) === '1' && sameOrigin(request, cfg);
+async function readBody(request) {
+    const text = await request.text();
+    if (text.length > 200_000)
+        throw new HttpError(413, 'That request is too large.');
+    if (!text)
+        return {};
+    try {
+        const body = JSON.parse(text);
+        return typeof body === 'object' && body !== null && !Array.isArray(body) ? body : {};
+    }
+    catch {
+        throw new HttpError(400, 'Invalid request.');
+    }
+}
+export async function sessionView(cfg, request) {
+    let user = null;
+    try {
+        user = await cfg.auth.getUser(request, { secret: cfg.secret });
+    }
+    catch (e) {
+        console.error('[nextpluggable] auth.getUser failed:', e);
+    }
+    return { user, mode: cfg.auth.kind, configured: cfg.auth.configured, loginUrl: cfg.auth.loginUrl };
+}
+const ASSET_TYPES = {
+    'client.js': { kind: 'client', type: 'text/javascript; charset=utf-8' },
+    'style.css': { kind: 'style', type: 'text/css; charset=utf-8' },
+};
+async function serveAsset(cfg, pluginId, hash, name) {
+    const asset = ASSET_TYPES[name];
+    if (!asset || !/^[0-9a-f]{16}$/.test(hash))
+        return jsonResponse({ error: 'Not found.' }, 404);
+    const install = own(await getInstalledPlugins(cfg), pluginId) ?? own(await getInstalls(cfg.storage), pluginId);
+    // The previous version's files stay available so pages cached before an update still load.
+    const file = [install?.files[asset.kind], install?.previousFiles?.[asset.kind]].find((f) => f?.sha256.startsWith(hash));
+    const content = file ? await getFile(cfg.storage, pluginId, asset.kind, file.sha256) : null;
+    if (content === null)
+        return jsonResponse({ error: 'Not found.' }, 404);
+    const body = asset.kind === 'client'
+        ? // One artifact, two consumers: the server evaluates the module body directly; browsers get it
+            // wrapped in a registration call, so no eval (and no `unsafe-eval` CSP) is needed client-side.
+            `(self.__NP_Q__=self.__NP_Q__||[]).push([${JSON.stringify(`${pluginId}@${hash}`)},function(require,module,exports){${content}\n}]);`
+        : content;
+    return new Response(body, {
+        headers: {
+            'content-type': asset.type,
+            'cache-control': 'public, max-age=31536000, s-maxage=31536000, immutable',
+            'x-content-type-options': 'nosniff',
+        },
+    });
+}
+export function createHandler(getConfig, hooks = {}) {
+    async function route(request) {
+        const cfg = getConfig();
+        const pathname = new URL(request.url).pathname;
+        const at = pathname.indexOf(cfg.apiPath);
+        const sub = at === -1 ? pathname : pathname.slice(at + cfg.apiPath.length);
+        const seg = sub.split('/').filter(Boolean).map((s) => decodeURIComponent(s));
+        const method = request.method.toUpperCase();
+        const env = { secret: cfg.secret };
+        // ---- public: plugin assets
+        if (seg[0] === 'assets' && seg.length === 4 && (method === 'GET' || method === 'HEAD'))
+            return serveAsset(cfg, seg[1], seg[2], seg[3]);
+        // ---- public: plugin APIs
+        if (seg[0] === 'p' && seg[1]) {
+            const install = own(await getInstalledPlugins(cfg), seg[1]);
+            if (!install || !install.enabled)
+                return jsonResponse({ error: 'Not found.' }, 404);
+            // A plugin only sees the dashboard user when the request provably came from this site's own pages.
+            const admin = !MUTATING.has(method) || csrfOk(request, cfg) ? await cfg.auth.getUser(request, env).catch(() => null) : null;
+            const res = await handlePluginApi(cfg, install, request, `/${seg.slice(2).join('/')}`, admin);
+            if (MUTATING.has(method) && admin)
+                await hooks.onSiteChange?.();
+            return res;
+        }
+        // ---- session
+        if (seg[0] === 'session' && method === 'GET')
+            return jsonResponse(await sessionView(cfg, request));
+        if (MUTATING.has(method) && !csrfOk(request, cfg))
+            throw new HttpError(403, 'This request was blocked for security reasons. Reload the page and try again.');
+        if (seg[0] === 'login' && method === 'POST') {
+            if (!cfg.auth.login)
+                throw new HttpError(404, 'This site signs in a different way.');
+            return cfg.auth.login(request, env);
+        }
+        if (seg[0] === 'logout' && method === 'POST')
+            return cfg.auth.logout ? cfg.auth.logout(request, env) : jsonResponse({ ok: true });
+        // ---- dashboard (signed-in only)
+        if (seg[0] !== 'admin')
+            throw new HttpError(404, 'Not found.');
+        const user = await cfg.auth.getUser(request, env);
+        if (!user)
+            throw new HttpError(401, 'Please sign in again.');
+        const state = async (extra) => jsonResponse({ ...(await buildDashboardState(cfg)), ...extra });
+        const changed = async (extra) => {
+            await hooks.onSiteChange?.();
+            return state(extra);
+        };
+        if (seg[1] === 'state' && method === 'GET')
+            return state();
+        if (seg[1] === 'refresh' && method === 'POST')
+            return state({ failures: await refreshAllSources(cfg) });
+        if (seg[1] === 'sources') {
+            if (method === 'POST' && seg.length === 2) {
+                const source = await addSource(cfg, await readBody(request));
+                return state({ added: source.id });
+            }
+            if (method === 'DELETE' && seg[2]) {
+                await removeSource(cfg, seg[2]);
+                return state();
+            }
+        }
+        if (seg[1] === 'install' && method === 'POST') {
+            const record = await installPlugin(cfg, await readBody(request));
+            return changed({ installed: record.id });
+        }
+        if (seg[1] === 'plugins' && seg[2]) {
+            const id = seg[2];
+            if (seg[3] === 'update' && method === 'POST') {
+                await updatePlugin(cfg, id);
+                return changed();
+            }
+            if (seg.length === 3 && method === 'PATCH') {
+                await changePlugin(cfg, id, await readBody(request));
+                return changed();
+            }
+            if (seg.length === 3 && method === 'DELETE') {
+                const body = await readBody(request);
+                await uninstallPlugin(cfg, id, { deleteData: body.deleteData === true });
+                return changed();
+            }
+        }
+        throw new HttpError(404, 'Not found.');
+    }
+    return async function handle(request) {
+        try {
+            return await route(request);
+        }
+        catch (e) {
+            if (e instanceof HttpError)
+                return jsonResponse({ error: e.message, ...(e.fields ? { fields: e.fields } : {}) }, e.status);
+            console.error('[nextpluggable] Unexpected error:', e);
+            const message = e instanceof Error && e.message.startsWith('[nextpluggable]') ? e.message.replace('[nextpluggable] ', '') : 'Something went wrong on the server. Please try again.';
+            return jsonResponse({ error: message }, 500);
+        }
+    };
+}

package/dist/auth/custom.d.ts

@@ -0,0 +1,13 @@
+import type { AdminUser, AuthAdapter } from './types.js';
+export interface CustomAuthOptions {
+    /**
+     * Return the signed-in administrator for this request, or null. Called for the
+     * dashboard page and for every dashboard API request, with the visitor's
+     * cookies and headers on `request`.
+     */
+    getUser: (request: Request) => Promise<AdminUser | null> | AdminUser | null;
+    /** Where to send people who are not signed in, e.g. `/login`. */
+    loginUrl?: string;
+}
+/** Use the site's existing login system (Auth.js, Clerk, Supabase, your own) to protect the dashboard. */
+export declare function customAuth(options: CustomAuthOptions): AuthAdapter;

package/dist/auth/custom.js

@@ -0,0 +1,12 @@
+/** Use the site's existing login system (Auth.js, Clerk, Supabase, your own) to protect the dashboard. */
+export function customAuth(options) {
+    return {
+        kind: 'custom',
+        configured: true,
+        loginUrl: options.loginUrl,
+        async getUser(request) {
+            const user = await options.getUser(request);
+            return user && typeof user.id === 'string' ? { id: user.id, name: user.name } : null;
+        },
+    };
+}

package/dist/auth/password.d.ts

@@ -0,0 +1,10 @@
+import type { AuthAdapter } from './types.js';
+export interface PasswordAuthOptions {
+    /** The dashboard password. Default: the `NEXTPLUGGABLE_PASSWORD` environment variable. */
+    password?: string;
+    /** How long a sign-in lasts. Default 7 days. */
+    sessionDays?: number;
+    cookieName?: string;
+}
+/** One shared password for the dashboard, with a signed, http-only session cookie. */
+export declare function passwordAuth(options?: PasswordAuthOptions): AuthAdapter;

package/dist/auth/password.js

@@ -0,0 +1,66 @@
+import { hmac, safeEqual, signToken, verifyToken } from '../crypto.js';
+import { jsonResponse } from '../errors.js';
+import { globals } from '../globals.js';
+const WINDOW_MS = 10 * 60_000;
+const MAX_ATTEMPTS = 8;
+function clientAddress(request) {
+    return request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() || request.headers.get('x-real-ip') || 'unknown';
+}
+function readCookie(request, name) {
+    for (const part of (request.headers.get('cookie') ?? '').split(';')) {
+        const eq = part.indexOf('=');
+        if (eq !== -1 && part.slice(0, eq).trim() === name)
+            return decodeURIComponent(part.slice(eq + 1).trim());
+    }
+    return undefined;
+}
+function isHttps(request) {
+    const proto = request.headers.get('x-forwarded-proto')?.split(',')[0]?.trim();
+    return proto ? proto === 'https' : new URL(request.url).protocol === 'https:';
+}
+/** One shared password for the dashboard, with a signed, http-only session cookie. */
+export function passwordAuth(options = {}) {
+    const cookieName = options.cookieName ?? 'np_session';
+    const days = options.sessionDays ?? 7;
+    const password = () => options.password ?? process.env.NEXTPLUGGABLE_PASSWORD ?? '';
+    // Sessions carry a fingerprint of the password, so changing it signs everyone out.
+    const fingerprint = (secret) => hmac(secret, `pw:${password()}`).slice(0, 16);
+    const cookie = (request, value, maxAge) => `${cookieName}=${encodeURIComponent(value)}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${maxAge}${isHttps(request) ? '; Secure' : ''}`;
+    return {
+        kind: 'password',
+        get configured() {
+            return password().length > 0;
+        },
+        async getUser(request, env) {
+            if (!password())
+                return null;
+            const session = verifyToken(env.secret, readCookie(request, cookieName));
+            return session && session.fp === fingerprint(env.secret) ? { id: 'admin', name: 'Site owner' } : null;
+        },
+        async login(request, env) {
+            if (!password())
+                return jsonResponse({ error: 'No dashboard password has been set up yet.' }, 503);
+            const attempts = globals().loginAttempts;
+            const who = clientAddress(request);
+            const now = Date.now();
+            const recent = (attempts.get(who) ?? []).filter((t) => now - t < WINDOW_MS);
+            if (recent.length >= MAX_ATTEMPTS) {
+                attempts.set(who, recent);
+                return jsonResponse({ error: 'Too many attempts. Please wait a few minutes and try again.' }, 429);
+            }
+            const body = (await request.json().catch(() => null));
+            const given = typeof body?.password === 'string' ? body.password : '';
+            if (!given || !safeEqual(given, password())) {
+                recent.push(now);
+                attempts.set(who, recent);
+                return jsonResponse({ error: 'That password is not right.' }, 401);
+            }
+            attempts.delete(who);
+            const token = signToken(env.secret, { exp: now + days * 86_400_000, fp: fingerprint(env.secret) });
+            return jsonResponse({ user: { id: 'admin', name: 'Site owner' } }, 200, { 'set-cookie': cookie(request, token, days * 86_400) });
+        },
+        async logout(request) {
+            return jsonResponse({ ok: true }, 200, { 'set-cookie': cookie(request, '', 0) });
+        },
+    };
+}

package/dist/auth/types.d.ts

@@ -0,0 +1,23 @@
+export interface AdminUser {
+    id: string;
+    name?: string;
+}
+export interface AuthEnv {
+    /** The site secret, for signing sessions. */
+    secret: string;
+}
+/**
+ * Decides who may use the dashboard. Use `passwordAuth()` for a single shared
+ * password, or `customAuth()` to defer to the site's own login (Auth.js, Clerk, …).
+ */
+export interface AuthAdapter {
+    kind: 'password' | 'custom';
+    /** False when the adapter cannot work yet (e.g. no password set); the dashboard then shows setup steps. */
+    configured: boolean;
+    getUser(request: Request, env: AuthEnv): Promise<AdminUser | null>;
+    /** Password adapters: handle a sign-in attempt. */
+    login?(request: Request, env: AuthEnv): Promise<Response>;
+    logout?(request: Request, env: AuthEnv): Promise<Response>;
+    /** Custom adapters: where to send someone who is not signed in. */
+    loginUrl?: string;
+}

package/dist/auth/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+export interface InitResult {
+    created: string[];
+    skipped: string[];
+    notes: string[];
+    /** Set when a dashboard password was generated. */
+    password?: string;
+}
+export declare function init(projectDir: string): Promise<InitResult>;
+export declare function main(): Promise<number>;