@haruhimemoe/next-kit 0.1.0

package/dist/server/safe-next.js

@@ -0,0 +1,42 @@
+/**
+ * @file src/server/safe-next.ts
+ * @desc Where to go after sign-in. Only same-site absolute paths pass; anything else (other
+ *       hosts, protocol-relative, backslashes, control characters, the sign-in page itself)
+ *       becomes the caller's fallback, a page every signed-in user can open. Browser-safe, so
+ *       @haruhimemoe/next-kit/auth-react exports it too. Moved from pools (src/utils/safe-next.ts);
+ *       packs' copy let /signin through.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** The sign-in page both sites use. */
+export const DEFAULT_SIGN_IN_PATH = "/signin";
+/** A `next` longer than this is refused unread. */
+export const MAX_NEXT_LENGTH = 512;
+const hasControlCharacter = (value) => [...value].some((char) => char.charCodeAt(0) < 0x20 || char.charCodeAt(0) === 0x7f);
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * @function safeNextPath
+ * @param raw {string | null | undefined} untrusted ?next= value
+ * @param options {SafeNextOptions} the fallback and the sign-in page
+ * @returns {string} a same-site path, or the fallback
+ */
+export const safeNextPath = (raw, { fallback, signInPath = DEFAULT_SIGN_IN_PATH }) => {
+    if (!raw || raw.length > MAX_NEXT_LENGTH)
+        return fallback;
+    if (!raw.startsWith("/") || raw.startsWith("//"))
+        return fallback;
+    if (raw.includes("\\") || hasControlCharacter(raw))
+        return fallback;
+    // The sign-in page with a session goes on to `next`: back to itself would never end.
+    if (new RegExp(`^${escapeRegExp(signInPath)}(?:[/?#]|$)`).test(raw))
+        return fallback;
+    return raw;
+};
+/**
+ * @function signInHref
+ * @param next {string} where to land after signing in
+ * @param signInPath {string} the sign-in page (default DEFAULT_SIGN_IN_PATH)
+ * @returns {string} the sign-in link carrying it, like /signin?next=%2Fpacks
+ */
+export const signInHref = (next, signInPath = DEFAULT_SIGN_IN_PATH) => `${signInPath}?next=${encodeURIComponent(next)}`;

package/dist/server/security-txt.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @file src/server/security-txt.ts
+ * @desc /.well-known/security.txt (RFC 9116): where to report a vulnerability, when the file goes
+ *       stale (a year after it was built, so a deploy rebuilds it), and the policy. Byte-identical
+ *       in packs and pools (src/utils/security-txt.ts), which read their SITE constants; the
+ *       caller passes them here.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** RFC 9116 asks for an Expires less than a year out. */
+export declare const SECURITY_TXT_LIFETIME_DAYS = 365;
+/** Where the file is served. */
+export declare const SECURITY_TXT_PATH = "/.well-known/security.txt";
+/** buildSecurityTxt's input. */
+export type SecurityTxtOptions = {
+    /** Where to report, as an email address (becomes a mailto: Contact). */
+    contactEmail: string;
+    /** The site's origin, like https://pools.haruhime.moe (no trailing slash). */
+    siteUrl: string;
+    /** The security policy, like the repo's SECURITY.md. */
+    policyUrl: string;
+    /** When the file is built (build time for a static route). */
+    now: Date;
+};
+/**
+ * @function buildSecurityTxt
+ * @param options {SecurityTxtOptions} contact, site, policy and build time
+ * @returns {string} the security.txt body: Contact, Expires, Preferred-Languages, Canonical,
+ *          Policy, one field per line, ending in one newline
+ */
+export declare const buildSecurityTxt: ({ contactEmail, siteUrl, policyUrl, now, }: SecurityTxtOptions) => string;

package/dist/server/security-txt.js

@@ -0,0 +1,31 @@
+/**
+ * @file src/server/security-txt.ts
+ * @desc /.well-known/security.txt (RFC 9116): where to report a vulnerability, when the file goes
+ *       stale (a year after it was built, so a deploy rebuilds it), and the policy. Byte-identical
+ *       in packs and pools (src/utils/security-txt.ts), which read their SITE constants; the
+ *       caller passes them here.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** RFC 9116 asks for an Expires less than a year out. */
+export const SECURITY_TXT_LIFETIME_DAYS = 365;
+/** Where the file is served. */
+export const SECURITY_TXT_PATH = "/.well-known/security.txt";
+/**
+ * @function buildSecurityTxt
+ * @param options {SecurityTxtOptions} contact, site, policy and build time
+ * @returns {string} the security.txt body: Contact, Expires, Preferred-Languages, Canonical,
+ *          Policy, one field per line, ending in one newline
+ */
+export const buildSecurityTxt = ({ contactEmail, siteUrl, policyUrl, now, }) => {
+    const expires = new Date(now.getTime() + SECURITY_TXT_LIFETIME_DAYS * 86_400_000);
+    const lines = [
+        `Contact: mailto:${contactEmail}`,
+        `Expires: ${expires.toISOString()}`,
+        "Preferred-Languages: en",
+        `Canonical: ${siteUrl}${SECURITY_TXT_PATH}`,
+        `Policy: ${policyUrl}`,
+    ];
+    return `${lines.join("\n")}\n`;
+};

package/dist/testing/env.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @file src/testing/env.ts
+ * @desc Fake env for tests: a complete, valid set of the osu! app's five variables (no real
+ *       secrets) and stubEnv, which puts values in process.env through Vitest (undo with
+ *       vi.unstubAllEnvs). Moved from packs and pools (tests/helpers/server-env.ts, identical).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** A complete, valid osu! app env. MONGODB_URI equals the placeholder; tests replace it. */
+export declare const TEST_OSU_APP_ENV: Readonly<{
+    MONGODB_URI: "mongodb://127.0.0.1:27017";
+    BETTER_AUTH_SECRET: "t8Vq2Lm5Xr9Kc1Wz4Hn7Pb3Jd6Fs0Gy2Qe5R";
+    BETTER_AUTH_URL: "http://localhost:3000";
+    OSU_CLIENT_ID: "1";
+    OSU_CLIENT_SECRET: "test-osu-client-secret";
+}>;
+/**
+ * @function stubEnv
+ * @param values {Record<string, string>} variables to set
+ * @returns {void} stubs each into process.env with vi.stubEnv
+ */
+export declare const stubEnv: (values: Record<string, string>) => void;
+/**
+ * @function stubOsuAppEnv
+ * @param overrides {Record<string, string>} values to change or add
+ * @returns {void} stubs TEST_OSU_APP_ENV, with the overrides, into process.env
+ */
+export declare const stubOsuAppEnv: (overrides?: Record<string, string>) => void;

package/dist/testing/env.js

@@ -0,0 +1,33 @@
+/**
+ * @file src/testing/env.ts
+ * @desc Fake env for tests: a complete, valid set of the osu! app's five variables (no real
+ *       secrets) and stubEnv, which puts values in process.env through Vitest (undo with
+ *       vi.unstubAllEnvs). Moved from packs and pools (tests/helpers/server-env.ts, identical).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { vi } from "vitest";
+/** A complete, valid osu! app env. MONGODB_URI equals the placeholder; tests replace it. */
+export const TEST_OSU_APP_ENV = Object.freeze({
+    MONGODB_URI: "mongodb://127.0.0.1:27017",
+    BETTER_AUTH_SECRET: "t8Vq2Lm5Xr9Kc1Wz4Hn7Pb3Jd6Fs0Gy2Qe5R",
+    BETTER_AUTH_URL: "http://localhost:3000",
+    OSU_CLIENT_ID: "1",
+    OSU_CLIENT_SECRET: "test-osu-client-secret",
+});
+/**
+ * @function stubEnv
+ * @param values {Record<string, string>} variables to set
+ * @returns {void} stubs each into process.env with vi.stubEnv
+ */
+export const stubEnv = (values) => {
+    for (const [key, value] of Object.entries(values))
+        vi.stubEnv(key, value);
+};
+/**
+ * @function stubOsuAppEnv
+ * @param overrides {Record<string, string>} values to change or add
+ * @returns {void} stubs TEST_OSU_APP_ENV, with the overrides, into process.env
+ */
+export const stubOsuAppEnv = (overrides = {}) => stubEnv({ ...TEST_OSU_APP_ENV, ...overrides });

package/dist/testing/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @file src/testing/index.ts
+ * @desc @haruhimemoe/next-kit/testing: Vitest helpers both apps shared. One in-memory MongoDB per
+ *       run (a globalSetup) and per-file collection clearing, an msw server that refuses unhandled
+ *       requests, and a fake osu! app env. Needs vitest, and msw or mongodb-memory-server for
+ *       their helpers. Never import it from app code.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+export { stubEnv, stubOsuAppEnv, TEST_OSU_APP_ENV } from "./env.js";
+export { BETTER_AUTH_COLLECTIONS, setupTestDb, startMemoryMongo, type TestDbOptions, } from "./mongo.js";
+export { setupMsw } from "./msw.js";

package/dist/testing/index.js

@@ -0,0 +1,13 @@
+/**
+ * @file src/testing/index.ts
+ * @desc @haruhimemoe/next-kit/testing: Vitest helpers both apps shared. One in-memory MongoDB per
+ *       run (a globalSetup) and per-file collection clearing, an msw server that refuses unhandled
+ *       requests, and a fake osu! app env. Needs vitest, and msw or mongodb-memory-server for
+ *       their helpers. Never import it from app code.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+export { stubEnv, stubOsuAppEnv, TEST_OSU_APP_ENV } from "./env.js";
+export { BETTER_AUTH_COLLECTIONS, setupTestDb, startMemoryMongo, } from "./mongo.js";
+export { setupMsw } from "./msw.js";

package/dist/testing/mongo.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @file src/testing/mongo.ts
+ * @desc Test databases: a Vitest global setup that starts one in-memory MongoDB for the run and
+ *       hands its URI to test files (inject("mongoUri")), and setupTestDb, which empties the
+ *       given collections before each test and closes the client after the file. Moved from
+ *       packs and pools (tests/setup/integration-global.ts, identical, and tests/helpers/db.ts).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import type { Db } from "mongodb";
+import type { TestProject } from "vitest/node";
+declare module "vitest" {
+    interface ProvidedContext {
+        /** The in-memory MongoDB's URI, from startMemoryMongo. */
+        mongoUri: string;
+    }
+}
+/** The collections better-auth's MongoDB adapter creates (with its default names). */
+export declare const BETTER_AUTH_COLLECTIONS: readonly string[];
+/**
+ * @function startMemoryMongo
+ * @param project {TestProject} the Vitest project (a globalSetup's argument)
+ * @returns {Promise<() => Promise<void>>} provides "mongoUri"; the returned teardown stops the
+ *          server. Use it as a globalSetup's default export.
+ */
+export declare const startMemoryMongo: (project: TestProject) => Promise<() => Promise<void>>;
+/** setupTestDb's options: how the app connects, reaches and closes its database. */
+export type TestDbOptions = {
+    /** Connects (and runs the app's start-up work, like index builds). */
+    connect: () => Promise<unknown>;
+    /** The connected database. */
+    db: () => Db;
+    /** Closes and forgets the client. */
+    close: () => Promise<unknown>;
+    /** Every collection a test may write to; emptied before each test. */
+    collections: readonly string[];
+};
+/**
+ * @function setupTestDb
+ * @param options {TestDbOptions} connect, db, close and the collections to empty
+ * @returns {void} registers beforeEach (connect, then empty) and afterAll (close) hooks
+ */
+export declare const setupTestDb: ({ connect, db, close, collections }: TestDbOptions) => void;

package/dist/testing/mongo.js

@@ -0,0 +1,46 @@
+/**
+ * @file src/testing/mongo.ts
+ * @desc Test databases: a Vitest global setup that starts one in-memory MongoDB for the run and
+ *       hands its URI to test files (inject("mongoUri")), and setupTestDb, which empties the
+ *       given collections before each test and closes the client after the file. Moved from
+ *       packs and pools (tests/setup/integration-global.ts, identical, and tests/helpers/db.ts).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { MongoMemoryServer } from "mongodb-memory-server";
+import { afterAll, beforeEach } from "vitest";
+/** The collections better-auth's MongoDB adapter creates (with its default names). */
+export const BETTER_AUTH_COLLECTIONS = Object.freeze([
+    "user",
+    "session",
+    "account",
+    "verification",
+]);
+/**
+ * @function startMemoryMongo
+ * @param project {TestProject} the Vitest project (a globalSetup's argument)
+ * @returns {Promise<() => Promise<void>>} provides "mongoUri"; the returned teardown stops the
+ *          server. Use it as a globalSetup's default export.
+ */
+export const startMemoryMongo = async (project) => {
+    const server = await MongoMemoryServer.create();
+    project.provide("mongoUri", server.getUri());
+    return async () => {
+        await server.stop();
+    };
+};
+/**
+ * @function setupTestDb
+ * @param options {TestDbOptions} connect, db, close and the collections to empty
+ * @returns {void} registers beforeEach (connect, then empty) and afterAll (close) hooks
+ */
+export const setupTestDb = ({ connect, db, close, collections }) => {
+    beforeEach(async () => {
+        await connect();
+        await Promise.all(collections.map((name) => db().collection(name).deleteMany({})));
+    });
+    afterAll(async () => {
+        await close();
+    });
+};

package/dist/testing/msw.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file src/testing/msw.ts
+ * @desc setupMsw(...handlers): an msw server for the test file, listening before the tests with
+ *       every unhandled request an error (so nothing reaches osu!, the mirror or another app),
+ *       reset after each test, closed after the file. Moved from packs and pools
+ *       (tests/helpers/msw.ts).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import type { RequestHandler } from "msw";
+import { type SetupServer } from "msw/node";
+/**
+ * @function setupMsw
+ * @param handlers {RequestHandler[]} the file's default handlers
+ * @returns {SetupServer} the server (use server.use() to add handlers in a test)
+ */
+export declare const setupMsw: (...handlers: RequestHandler[]) => SetupServer;

package/dist/testing/msw.js

@@ -0,0 +1,24 @@
+/**
+ * @file src/testing/msw.ts
+ * @desc setupMsw(...handlers): an msw server for the test file, listening before the tests with
+ *       every unhandled request an error (so nothing reaches osu!, the mirror or another app),
+ *       reset after each test, closed after the file. Moved from packs and pools
+ *       (tests/helpers/msw.ts).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { setupServer } from "msw/node";
+import { afterAll, afterEach, beforeAll } from "vitest";
+/**
+ * @function setupMsw
+ * @param handlers {RequestHandler[]} the file's default handlers
+ * @returns {SetupServer} the server (use server.use() to add handlers in a test)
+ */
+export const setupMsw = (...handlers) => {
+    const server = setupServer(...handlers);
+    beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
+    afterEach(() => server.resetHandlers());
+    afterAll(() => server.close());
+    return server;
+};

package/package.json

@@ -0,0 +1,140 @@
+{
+  "name": "@haruhimemoe/next-kit",
+  "version": "0.1.0",
+  "description": "The Next.js server plumbing packs.haruhime.moe and pools.haruhime.moe share: JSON route helpers, rate limits and budgets in MongoDB, bearer machine auth, zod env parsing, a connect-once MongoDB client with safe index builds, better-auth with osu! sign-in, and the signed-in marker and account store for the browser.",
+  "keywords": [
+    "nextjs",
+    "next.js",
+    "better-auth",
+    "osu",
+    "osu!",
+    "mongodb",
+    "rate limit",
+    "zod"
+  ],
+  "homepage": "https://github.com/haruhimemoe/next-kit#readme",
+  "bugs": "https://github.com/haruhimemoe/next-kit/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/haruhimemoe/next-kit.git"
+  },
+  "license": "MIT",
+  "author": "David (https://dvh.sh)",
+  "type": "module",
+  "exports": {
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
+    },
+    "./env": {
+      "types": "./dist/env/index.d.ts",
+      "default": "./dist/env/index.js"
+    },
+    "./mongo": {
+      "types": "./dist/mongo/index.d.ts",
+      "default": "./dist/mongo/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "default": "./dist/auth/index.js"
+    },
+    "./auth-react": {
+      "types": "./dist/auth-react/index.d.ts",
+      "default": "./dist/auth-react/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.12"
+  },
+  "packageManager": "bun@1.4.2",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "bun run clean && tsc -p tsconfig.build.json",
+    "check": "biome check .",
+    "check:fix": "biome check --write .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "test:dist": "bun run build && node scripts/smoke.mjs",
+    "prepublishOnly": "bun run check && bun run typecheck && bun run test && bun run test:dist",
+    "check:consumer": "bun run build && node scripts/check-consumer.mjs"
+  },
+  "peerDependencies": {
+    "@haruhimemoe/osu": "^0.2.0 || ^0.3.0",
+    "better-auth": "^1.7.5",
+    "mongodb": "^7.6.0",
+    "mongodb-memory-server": "^11.3.0",
+    "mongoose": "^9.10.2",
+    "msw": "^2.15.0",
+    "next": "^16.3.6",
+    "react": "^19.3.0",
+    "vitest": "^5.0.1",
+    "zod": "^4.6.5"
+  },
+  "peerDependenciesMeta": {
+    "@haruhimemoe/osu": {
+      "optional": true
+    },
+    "better-auth": {
+      "optional": true
+    },
+    "mongodb": {
+      "optional": true
+    },
+    "mongodb-memory-server": {
+      "optional": true
+    },
+    "mongoose": {
+      "optional": true
+    },
+    "msw": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.14",
+    "@haruhimemoe/osu": "0.2.0",
+    "@testing-library/dom": "10.4.2",
+    "@testing-library/react": "16.3.3",
+    "@types/node": "26.6.2",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitest/coverage-v8": "5.0.1",
+    "better-auth": "1.7.5",
+    "jsdom": "30.1.1",
+    "mongodb": "7.6.0",
+    "mongodb-memory-server": "11.3.0",
+    "mongoose": "9.10.2",
+    "msw": "2.15.0",
+    "next": "16.3.6",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.1",
+    "zod": "4.6.5"
+  }
+}