@haruhimemoe/next-kit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to `@haruhimemoe/next-kit` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-28
+
+### Added
+
+- `@haruhimemoe/next-kit/server`: `jsonError`, `ERROR_CODES`, `noStore`, `parseJsonBody` with a per-route cap, `parseIdList`, `refuseCrossSite`, `clientIp` and `rateLimitSubject`, `createRateLimiter` and `createBudget` over one MongoDB counter shape, `refuseWithoutBearer` and `sameSecret` for machine routes, `safeNextPath`, `signInHref` and `buildSecurityTxt`. Moved from packs.haruhime.moe and pools.haruhime.moe, taking pools' behavior where they differed.
+- `@haruhimemoe/next-kit/env`: `createServerEnv` with SKIP_ENV_VALIDATION and the production placeholder guard, the osu! app's five variables, and per-call readers (`optionalSecret`, `readIdSet`, `readFlag`, `readOrigin`).
+- `@haruhimemoe/next-kit/mongo`: `createMongo` (one client per process, Mongoose on the same client, an `onConnect` hook), `ensureIndexes` that skips and logs an index existing duplicates break, `ttlIndex` and `defineCollections`.
+- `@haruhimemoe/next-kit/auth`: `createOsuAuth` (better-auth with osu! genericOAuth, no stored osu! tokens, trusted account linking, errors to the sign-in page, the signed-in marker cookie, guard hooks and extra user fields), `AUTH_INDEX_SPECS` and `getOsuUser`.
+- `@haruhimemoe/next-kit/auth-react`: `createSignedInMarker`, `createAccountStore`, `useAccount`, `createAccount`, `RestoreSignedIn` and `osuSignIn`.
+- `@haruhimemoe/next-kit/testing`: `startMemoryMongo`, `setupTestDb`, `setupMsw` and the fake osu! app env.
+
+[unreleased]: https://github.com/haruhimemoe/next-kit/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/haruhimemoe/next-kit/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David (@dvhsh)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+<p align="center"><a href="https://github.com/haruhimemoe/next-kit"><picture><source media="(prefers-color-scheme: light)" srcset="https://www.haruhime.moe/brand/repos/next-kit-banner-on-light.svg"><img alt="@haruhimemoe/next-kit" src="https://www.haruhime.moe/brand/repos/next-kit-banner.svg" width="640"></picture></a></p>
+
+# @haruhimemoe/next-kit
+
+The Next.js server plumbing the haruhime.moe tools share. [packs.haruhime.moe](https://packs.haruhime.moe) and [pools.haruhime.moe](https://pools.haruhime.moe) (in beta) each had their own copy, and the copies had started to drift.
+
+- **`/server`:** route helpers. JSON error answers, a JSON body parser with a size cap, a cross-site guard, the client IP, fixed-window rate limits and call budgets in MongoDB, bearer machine auth, where to go after sign-in, and security.txt.
+- **`/env`:** zod env parsing that runs on first use, with SKIP_ENV_VALIDATION for CI and a guard that refuses placeholder secrets on a production server.
+- **`/mongo`:** one MongoClient per process with Mongoose on the same client, index builds that never take the site down, and frozen collection names.
+- **`/auth`:** better-auth with osu! as the only way in, the indexes its collections need, and reading the caller.
+- **`/auth-react`:** the browser half: the signed-in marker cookie, the account store and `useAccount`, and `RestoreSignedIn`.
+- **`/testing`:** Vitest helpers: one in-memory MongoDB per run, an msw server that refuses unhandled requests, and a fake env.
+
+Every name, path, limit and message comes from the caller. There is no root entry point; import a subpath.
+
+## Install
+
+```sh
+bun add @haruhimemoe/next-kit zod
+# or: npm install @haruhimemoe/next-kit zod
+```
+
+`zod` 4.6.5 or later in 4.x is a peer dependency. The other peers are optional, and each subpath needs only its own:
+
+| Subpath | Needs |
+| --- | --- |
+| `server` | `mongodb` types for the rate limiter and budget |
+| `env` | nothing else |
+| `mongo` | `mongodb` ^7.6.0, `mongoose` ^9.10.2 |
+| `auth` | `better-auth` ^1.7.5, `mongodb`, `@haruhimemoe/osu` 0.2 or 0.3 |
+| `auth-react` | `react` ^19.3.0, `next` ^16.3.6 |
+| `testing` | `vitest` ^5.0.1, `msw` ^2.15.0, `mongodb-memory-server` ^11.3.0 |
+
+## Use
+
+One file per app wires each piece to its own names.
+
+```ts
+// src/env.ts
+import { createServerEnv, OSU_APP_PLACEHOLDERS, OSU_APP_SECRET_KEYS, osuAppEnvSchema, readIdSet } from "@haruhimemoe/next-kit/env";
+
+export const serverEnv = createServerEnv({ schema: osuAppEnvSchema, placeholders: OSU_APP_PLACEHOLDERS, secretKeys: OSU_APP_SECRET_KEYS });
+export const getServerEnv = serverEnv.get;
+export const getDatabaseUri = () => serverEnv.pick(process.env, ["MONGODB_URI"]).MONGODB_URI;
+export const getAdminOsuIds = () => readIdSet("ADMIN_OSU_IDS");
+
+// src/lib/db.ts
+import { createMongo, ensureIndexes } from "@haruhimemoe/next-kit/mongo";
+import { AUTH_INDEX_SPECS } from "@haruhimemoe/next-kit/auth";
+import { counterTtlIndex } from "@haruhimemoe/next-kit/server";
+
+export const { getDb, getMongoClient, getModelConnection, connectDb, connectedDb, closeDb } = createMongo({
+  dbName: "pools",
+  globalKey: "__poolsMongo",
+  uri: getDatabaseUri,
+  onConnect: async (db) => {
+    await ensureIndexes(db, [...AUTH_INDEX_SPECS, counterTtlIndex()]);
+  },
+});
+
+// src/lib/rate-limit.ts
+import { createRateLimiter } from "@haruhimemoe/next-kit/server";
+
+export const limiter = createRateLimiter({ db: connectedDb });
+```
+
+A route handler then reads like this:
+
+```ts
+import { clientIp, jsonError, parseJsonBody, rateLimitSubject, refuseCrossSite } from "@haruhimemoe/next-kit/server";
+
+export async function POST(request: Request) {
+  const foreign = refuseCrossSite(request, { siteUrl: SITE.url, siteTitle: SITE.title });
+  if (foreign) return foreign;
+  const limited = await limiter.refuseOverLimit(RATE_LIMITS.save, rateLimitSubject(clientIp(request.headers)));
+  if (limited) return limited;
+  const body = await parseJsonBody(request, saveBodySchema);
+  if (!body.ok) return body.response;
+  // ...
+  return jsonError(404, "Pack not found.");
+}
+```
+
+Sign-in takes a server file and a client file:
+
+```ts
+// src/lib/auth.ts (server)
+import { createOsuAuth, getOsuUser } from "@haruhimemoe/next-kit/auth";
+
+export const getAuth = () => {
+  const env = getServerEnv();
+  return createOsuAuth({
+    clientId: env.OSU_CLIENT_ID, clientSecret: env.OSU_CLIENT_SECRET,
+    baseURL: env.BETTER_AUTH_URL, secret: env.BETTER_AUTH_SECRET,
+    db: getDb(), client: getMongoClient(),
+    markerCookie: "pools-signed-in",
+    hooks: { afterUserCreate: linkNewEditor },
+  });
+};
+
+// src/lib/account.ts (browser)
+"use client";
+import { createAccount, createSignedInMarker } from "@haruhimemoe/next-kit/auth-react";
+
+export const marker = createSignedInMarker("pools-signed-in");
+export const { store, useAccount, markSignedOut, RestoreSignedIn } = createAccount(authClient, marker);
+```
+
+Build the auth instance once (memoize `getAuth`), and use the same cookie name on both sides.
+
+## API
+
+### server
+
+| Export | What it does |
+| --- | --- |
+| `jsonError(status, message, code?)` | `{ error: { code, message } }` JSON; the code comes from `ERROR_CODES` unless given. |
+| `ERROR_CODES`, `errorCodeFor(status)` | Stable machine codes per status; unknown statuses fall back to `internal_error` (5xx) or `bad_request`. |
+| `noStore(response)`, `withHeaders(response, headers)` | Set `Cache-Control: no-store`, or any headers, on the same response. |
+| `parseJsonBody(request, schema, { maxBytes?, tooLarge? })` | `{ ok: true, data }` or `{ ok: false, response }`: 415 unless JSON, 413 past the cap (16 KB by default, `MAX_BODY_BYTES`), 400 for bad JSON or a schema refusal. A refinement's `params.code` becomes the error code. Pass `z.strictObject` to refuse unknown keys. |
+| `parseIdList(raw, { max, isValid? })` | `?ids=1,2,3` as numbers, or null. Each part is 1 to 10 plain digits; the default check is 1 to `MAX_ID`. |
+| `refuseCrossSite(request, { siteUrl, siteTitle })` | A 403 when Origin is foreign or Sec-Fetch-Site says cross-site or same-site, else null. |
+| `clientIp(headers)`, `rateLimitSubject(ip)` | Vercel's x-real-ip or first x-forwarded-for, and the counter subject (IPv6 by its /64). |
+| `createRateLimiter({ db, collection?, now? })` | `hit(rule, subject, cost?)`, `refuseOverLimit(rule, subject, cost?)` (a no-store 429 or null) and `deleteSubject(rules, subject)`. Counting fails open and logs. |
+| `createBudget({ db, global, perSubject?, globalSubject? })` | `take(subject?, nowMs?)` and `gate(subject?)`, a `beforeCall` for `@haruhimemoe/osu` that stays no after its first no. |
+| `windowFor`, `rateLimitId`, `rateLimitHeaders`, `retryText`, `tooManyRequests`, `unlimited`, `userSubject` | The fixed-window math, the counter id, RateLimit-* headers, the 429, a result with nothing counted, and `osu:<osuId>`. |
+| `counterTtlIndex(collection?)`, `RATE_LIMITS_COLLECTION` | The TTL index that removes spent counters, and the default collection. |
+| `refuseWithoutBearer(request, { secret, label, notConfigured, failures?, noStore? })` | Machine auth: null for the right `Bearer` secret, else 503 `not_configured`, 401, or 429 when failures are counted. |
+| `sameSecret(given, secret)`, `bearerToken(headers)` | SHA-256 digests compared with `timingSafeEqual`, and the token after `Bearer `. |
+| `safeNextPath(raw, { fallback, signInPath? })`, `signInHref(next, signInPath?)` | A same-site path to go to after sign-in (never the sign-in page), and the link carrying it. |
+| `buildSecurityTxt({ contactEmail, siteUrl, policyUrl, now })` | The RFC 9116 body, expiring a year after `now`. |
+
+### env
+
+| Export | What it does |
+| --- | --- |
+| `createServerEnv({ schema, placeholders, secretKeys })` | `parse(source)`, `pick(source, keys)`, `get()` (memoized), `reset()` and `assertNoPlaceholderSecrets(source, keys?)`. Errors name variables and never print values. |
+| `osuAppEnvSchema`, `OSU_APP_PLACEHOLDERS`, `OSU_APP_SECRET_KEYS` | The five variables both apps need: `MONGODB_URI`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, `OSU_CLIENT_ID`, `OSU_CLIENT_SECRET`. |
+| `optionalSecret(key, minLength)`, `readIdSet(key)`, `readFlag(key)`, `readOrigin(key, fallback)`, `readOptional(key)` | Read on every call, never memoized, so a bad value breaks only what uses it. |
+| `isProductionServer(source)`, `isEnvValidationSkipped(source?)`, `EnvError`, `invalidEnv(keys)`, `BUILD_PHASE` | The production rule (VERCEL_ENV when set, else NODE_ENV, never during `next build`) and the error. |
+
+### mongo
+
+| Export | What it does |
+| --- | --- |
+| `createMongo({ dbName, globalKey, uri, maxPoolSize?, serverSelectionTimeoutMS?, onConnect? })` | `getMongoClient`, `getDb`, `getModelConnection`, `connectDb`, `connectedDb`, `closeDb`. 5 connections and a 5 s timeout by default; a failed connect is retried next call. |
+| `ensureIndexes(db, specs)` | Builds each `IndexSpec` on its own and returns `{ built, skipped }`. A unique index that existing duplicates break is skipped and logged with the duplicate keys (never for `secret: true`). Never throws. |
+| `ttlIndex(collection, field, seconds?, name?)`, `indexName(spec)` | A TTL index spec, and the name MongoDB gives an index. |
+| `defineCollections(names)` | Frozen collection-name constants; throws on an invalid or repeated name. |
+| `isDuplicateKeyError(error)`, `DUPLICATE_KEY` | E11000. |
+
+### auth
+
+| Export | What it does |
+| --- | --- |
+| `createOsuAuth({ clientId, clientSecret, baseURL, secret, db, client, markerCookie, signInPath?, hooks?, userFields? })` | better-auth on MongoDB with osu! genericOAuth (identify + public, PKCE). `/update-user` is off, osu! tokens are never stored, osu! is trusted for account linking, API errors land on `/signin?error=<code>`, and the marker cookie follows the session. |
+| `hooks` | `beforeUserCreate`, `beforeAccountCreate` and `beforeSessionCreate` refuse a write by returning false; `afterUserCreate` runs after a new user and never fails the sign-in. |
+| `AUTH_INDEX_SPECS`, `AUTH_INDEXES` | One user per osu! id, one account per osu! link, one session per token, sessions by user, and the session TTL. Pass them to `ensureIndexes`. |
+| `getOsuUser(auth, headers)`, `toSessionUser(session)` | `{ id, osuId, username, avatarUrl }` for the caller, or null. |
+| `osuProvider`, `osuProfileToUser`, `withoutTokens`, `OSU_PROVIDER_ID`, `OSU_USER_FIELDS` | The pieces `createOsuAuth` is built from. |
+
+### auth-react
+
+| Export | What it does |
+| --- | --- |
+| `createSignedInMarker(name)`, `markerMaxAge(expiresAt)` | `has(cookieHeader)` and `clear()` for the readable marker cookie. It holds no secret. |
+| `createAccount(authClient, marker)` | A page-wide store, `useAccount()`, `markSignedOut()` and a `RestoreSignedIn` with both bound. Export them from a `"use client"` module. |
+| `createAccountStore(deps)`, `useAccount(store)`, `sessionFetcher(client)` | The store underneath: one session request per page load, only with the marker, and other tabs caught up when this one is shown again. |
+| `RestoreSignedIn({ store, hasMarker, next?, pending? })` | Asks for the session once when the marker is missing; with `next`, goes there after. |
+| `osuSignIn(next, signInPath?)` | The body for `authClient.signIn.social`: an error comes back to `/signin?next=<next>`. |
+| `safeNextPath`, `signInHref`, `OSU_PROVIDER_ID` | The same as in `server` and `auth`, safe in the browser. |
+
+### testing
+
+| Export | What it does |
+| --- | --- |
+| `startMemoryMongo(project)` | A Vitest globalSetup: one mongodb-memory-server for the run, its URI as `inject("mongoUri")`. |
+| `setupTestDb({ connect, db, close, collections })` | Empties the collections before each test, closes after the file. `BETTER_AUTH_COLLECTIONS` lists better-auth's. |
+| `setupMsw(...handlers)` | An msw server for the file; an unhandled request is an error. |
+| `TEST_OSU_APP_ENV`, `stubOsuAppEnv(overrides?)`, `stubEnv(values)` | A valid fake env and `vi.stubEnv` helpers. |
+
+## Migration
+
+Both apps can drop their copies for the subpaths above. Where the copies differed, this package keeps pools.haruhime.moe's behavior. What changes for packs.haruhime.moe:
+
+- A 503 answers `unavailable`, not `internal_error`.
+- `parseJsonBody` says "That request is too large." and "That request isn't valid." by default (pass `tooLarge` to keep "That pack is too large."), and sends a refinement's `params.code` as the error code.
+- `?ids=` parsing is strict: `1,,2`, ` 5`, `0x10` and `1e3` are refused.
+- `safeNextPath` sends `/signin` as `next` to the fallback.
+- `ADMIN_OSU_IDS` is read on every call (`readIdSet`), not memoized with the server env, so a removed admin loses access at the next request.
+- Sign-in gains account linking for osu! (a half-deleted account relinks), `onAPIError` to `/signin?error=<code>`, and an `errorCallbackURL` that keeps `next` (`osuSignIn`).
+- better-auth's collections get their indexes. The first start after the upgrade builds them; existing duplicate users or links are logged and that index is skipped until they're merged.
+- The cron guard is async: `await refuseWithoutBearer(...)`.
+- `deleteRateLimitsFor(userId)` becomes `limiter.deleteSubject(rules, userId)`, which escapes the subject instead of requiring an ObjectId.
+
+For pools.haruhime.moe, `createMongo` runs `onConnect` (the privilege check, index builds and backfill) after Mongoose is attached; `connectDb` still rejects when the check fails. Budget counters retry once on a duplicate key, as rate limits already did.
+
+## Compatibility
+
+ES modules for Node 22.12+ on the server. `auth-react` also runs in browsers; its hook and component files keep `"use client"`, and it loads only `react` and `next/navigation.js`. `server` loads `node:crypto` for machine auth.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Contributing
+
+Questions and feedback are welcome on the haruhime.moe [Discord server](https://discord.gg/bKy9kjMV4y). Bugs and ideas go in [issues](https://github.com/haruhimemoe/next-kit/issues).
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) to work on the package. Changes are logged in [CHANGELOG.md](CHANGELOG.md). Report a vulnerability as [SECURITY.md](SECURITY.md) describes.

package/dist/auth/create.d.ts

@@ -0,0 +1,204 @@
+/**
+ * @file src/auth/create.ts
+ * @desc createOsuAuth: better-auth on MongoDB with osu! as the only way in. Identity only ever
+ *       comes from osu! (/update-user is disabled), osu! tokens are never kept, and osu! is a
+ *       trusted provider for account linking: a user row whose osu! link is gone (a deletion
+ *       that stopped halfway) is relinked on the next osu! sign-in, which is safe because the
+ *       only way to a user row is osu! itself. A failure with no page to return to lands on the
+ *       sign-in page with ?error=<code>. The readable signed-in marker cookie follows the
+ *       session: set with it, cleared on sign-out or a get-session that finds none. The app's
+ *       hooks guard user, account and session creation. Moved from pools (src/lib/auth.ts);
+ *       packs lacked accountLinking and onAPIError.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { type BetterAuthOptions } from "better-auth";
+import type { Db, MongoClient } from "mongodb";
+import { OSU_USER_FIELDS } from "./osu.js";
+/** Extra fields on user rows, as better-auth's user.additionalFields takes them. */
+export type UserFields = NonNullable<NonNullable<BetterAuthOptions["user"]>["additionalFields"]>;
+/** No extra user fields. */
+type NoFields = Record<never, never>;
+/** A database row as a hook sees it. */
+export type AuthRow = Record<string, unknown>;
+/** Guards and follow-ups on better-auth's writes. A guard returning false refuses the write. */
+export type OsuAuthHooks = {
+    /** Before a user row is written (osu! profile already mapped). */
+    beforeUserCreate?: (user: AuthRow) => Promise<boolean | undefined>;
+    /** After a user row is written; a throw is logged and never fails the sign-in. */
+    afterUserCreate?: (user: AuthRow) => Promise<void>;
+    /** Before an osu! account link is written (tokens already dropped). */
+    beforeAccountCreate?: (account: AuthRow) => Promise<boolean | undefined>;
+    /** Before a session is written (packs: system accounts never sign in). */
+    beforeSessionCreate?: (session: AuthRow) => Promise<boolean | undefined>;
+};
+/** createOsuAuth's options. */
+export type OsuAuthOptions<F extends UserFields = NoFields> = {
+    /** The osu! OAuth app. */
+    clientId: string;
+    clientSecret: string;
+    /** BETTER_AUTH_URL and BETTER_AUTH_SECRET. */
+    baseURL: string;
+    secret: string;
+    /** The app's database, and the client it's on (for the adapter). */
+    db: Db;
+    client: MongoClient;
+    /** The signed-in marker cookie's name, like "pools-signed-in". */
+    markerCookie: string;
+    /** Where errors with no page to return to land (default /signin). */
+    signInPath?: string;
+    hooks?: OsuAuthHooks;
+    /** Fields of the app's own on user rows (packs: `system`, set only by the server). */
+    userFields?: F;
+};
+/**
+ * @function createOsuAuth
+ * @param options {OsuAuthOptions<F>} osu! credentials, better-auth URL and secret, the
+ *        database, the marker cookie, the sign-in page, the hooks and extra user fields
+ * @returns the better-auth instance (use `typeof` it with inferAdditionalFields on the client)
+ */
+export declare const createOsuAuth: <F extends UserFields = NoFields>({ clientId, clientSecret, baseURL, secret, db, client, markerCookie, signInPath, hooks, userFields, }: OsuAuthOptions<F>) => import("better-auth").Auth<{
+    baseURL: string;
+    secret: string;
+    database: (options: BetterAuthOptions) => import("better-auth").DBAdapter<BetterAuthOptions>;
+    disabledPaths: string[];
+    account: {
+        accountLinking: {
+            trustedProviders: "osu"[];
+            requireLocalEmailVerified: false;
+        };
+    };
+    onAPIError: {
+        errorURL: string;
+    };
+    user: {
+        additionalFields: typeof OSU_USER_FIELDS & F;
+    };
+    databaseHooks: {
+        user: {
+            create: {
+                before: (user: {
+                    id: string;
+                    createdAt: Date;
+                    updatedAt: Date;
+                    email: string;
+                    emailVerified: boolean;
+                    name: string;
+                    image?: string | null | undefined;
+                } & Record<string, unknown>) => Promise<false | undefined>;
+                after: (user: {
+                    id: string;
+                    createdAt: Date;
+                    updatedAt: Date;
+                    email: string;
+                    emailVerified: boolean;
+                    name: string;
+                    image?: string | null | undefined;
+                } & Record<string, unknown>) => Promise<void>;
+            };
+        };
+        account: {
+            create: {
+                before: (account: {
+                    id: string;
+                    createdAt: Date;
+                    updatedAt: Date;
+                    providerId: string;
+                    accountId: string;
+                    userId: string;
+                    accessToken?: string | null | undefined;
+                    refreshToken?: string | null | undefined;
+                    idToken?: string | null | undefined;
+                    accessTokenExpiresAt?: Date | null | undefined;
+                    refreshTokenExpiresAt?: Date | null | undefined;
+                    scope?: string | null | undefined;
+                    password?: string | null | undefined;
+                }) => Promise<false | {
+                    data: {
+                        id: string;
+                        createdAt: Date;
+                        updatedAt: Date;
+                        providerId: string;
+                        accountId: string;
+                        userId: string;
+                        accessToken?: string | null | undefined;
+                        refreshToken?: string | null | undefined;
+                        idToken?: string | null | undefined;
+                        accessTokenExpiresAt?: Date | null | undefined;
+                        refreshTokenExpiresAt?: Date | null | undefined;
+                        scope?: string | null | undefined;
+                        password?: string | null | undefined;
+                    };
+                }>;
+            };
+            update: {
+                before: (account: Partial<{
+                    id: string;
+                    createdAt: Date;
+                    updatedAt: Date;
+                    providerId: string;
+                    accountId: string;
+                    userId: string;
+                    accessToken?: string | null | undefined;
+                    refreshToken?: string | null | undefined;
+                    idToken?: string | null | undefined;
+                    accessTokenExpiresAt?: Date | null | undefined;
+                    refreshTokenExpiresAt?: Date | null | undefined;
+                    scope?: string | null | undefined;
+                    password?: string | null | undefined;
+                }> & Record<string, unknown>) => Promise<{
+                    data: Partial<{
+                        id: string;
+                        createdAt: Date;
+                        updatedAt: Date;
+                        providerId: string;
+                        accountId: string;
+                        userId: string;
+                        accessToken?: string | null | undefined;
+                        refreshToken?: string | null | undefined;
+                        idToken?: string | null | undefined;
+                        accessTokenExpiresAt?: Date | null | undefined;
+                        refreshTokenExpiresAt?: Date | null | undefined;
+                        scope?: string | null | undefined;
+                        password?: string | null | undefined;
+                    }> & Record<string, unknown>;
+                }>;
+            };
+        };
+        session: {
+            create: {
+                before: (session: {
+                    id: string;
+                    createdAt: Date;
+                    updatedAt: Date;
+                    userId: string;
+                    expiresAt: Date;
+                    token: string;
+                    ipAddress?: string | null | undefined;
+                    userAgent?: string | null | undefined;
+                } & Record<string, unknown>) => Promise<false | undefined>;
+            };
+        };
+    };
+    hooks: {
+        after: import("better-auth").Middleware<import("better-auth").MiddlewareOptions, (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<void>>;
+    };
+    plugins: [{
+        id: "generic-oauth";
+        version: string;
+        init: (ctx: import("better-auth").AuthContext) => Promise<{
+            context: {
+                socialProviders: import("better-auth").OAuthProvider<object, Partial<import("better-auth").ProviderOptions<object>>>[];
+            };
+        }>;
+        options: import("better-auth/plugins").GenericOAuthOptions<string>;
+        $ERROR_CODES: {
+            INVALID_OAUTH_CONFIGURATION: import("better-auth").RawError<"INVALID_OAUTH_CONFIGURATION">;
+            TOKEN_URL_NOT_FOUND: import("better-auth").RawError<"TOKEN_URL_NOT_FOUND">;
+        };
+    }];
+}>;
+/** The instance createOsuAuth builds (with no extra user fields). */
+export type OsuAuth = ReturnType<typeof createOsuAuth<NoFields>>;
+export {};

package/dist/auth/create.js

@@ -0,0 +1,102 @@
+/**
+ * @file src/auth/create.ts
+ * @desc createOsuAuth: better-auth on MongoDB with osu! as the only way in. Identity only ever
+ *       comes from osu! (/update-user is disabled), osu! tokens are never kept, and osu! is a
+ *       trusted provider for account linking: a user row whose osu! link is gone (a deletion
+ *       that stopped halfway) is relinked on the next osu! sign-in, which is safe because the
+ *       only way to a user row is osu! itself. A failure with no page to return to lands on the
+ *       sign-in page with ?error=<code>. The readable signed-in marker cookie follows the
+ *       session: set with it, cleared on sign-out or a get-session that finds none. The app's
+ *       hooks guard user, account and session creation. Moved from pools (src/lib/auth.ts);
+ *       packs lacked accountLinking and onAPIError.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { betterAuth } from "better-auth";
+import { mongodbAdapter } from "better-auth/adapters/mongodb";
+import { createAuthMiddleware } from "better-auth/api";
+import { genericOAuth } from "better-auth/plugins";
+import { markerMaxAge } from "../auth-react/marker.js";
+import { DEFAULT_SIGN_IN_PATH } from "../server/safe-next.js";
+import { OSU_PROVIDER_ID, OSU_USER_FIELDS, osuProvider, withoutTokens } from "./osu.js";
+/** Runs a guard: false refuses the write, anything else lets it through unchanged. */
+const guard = (check) => async (row) => check && (await check(row)) === false ? false : undefined;
+/**
+ * @function createOsuAuth
+ * @param options {OsuAuthOptions<F>} osu! credentials, better-auth URL and secret, the
+ *        database, the marker cookie, the sign-in page, the hooks and extra user fields
+ * @returns the better-auth instance (use `typeof` it with inferAdditionalFields on the client)
+ */
+export const createOsuAuth = ({ clientId, clientSecret, baseURL, secret, db, client, markerCookie, signInPath = DEFAULT_SIGN_IN_PATH, hooks = {}, userFields, }) => {
+    const markerOptions = {
+        path: "/",
+        sameSite: "lax",
+        secure: baseURL.startsWith("https://"),
+        httpOnly: false,
+    };
+    const beforeUser = guard(hooks.beforeUserCreate);
+    const beforeAccount = guard(hooks.beforeAccountCreate);
+    const beforeSession = guard(hooks.beforeSessionCreate);
+    return betterAuth({
+        baseURL,
+        secret,
+        database: mongodbAdapter(db, { client, transaction: false }),
+        // These fields must accept input: better-auth 1.7 drops `input: false` fields from the OAuth
+        // profile too. So no client may call /update-user: identity only ever comes from osu!.
+        disabledPaths: ["/update-user"],
+        account: {
+            // `<osuId>@osu.local` belongs to whoever osu! says has that id.
+            accountLinking: { trustedProviders: [OSU_PROVIDER_ID], requireLocalEmailVerified: false },
+        },
+        onAPIError: { errorURL: new URL(signInPath, baseURL).toString() },
+        user: {
+            additionalFields: { ...OSU_USER_FIELDS, ...userFields },
+        },
+        databaseHooks: {
+            user: {
+                create: {
+                    before: async (user) => beforeUser(user),
+                    after: async (user) => {
+                        try {
+                            await hooks.afterUserCreate?.(user);
+                        }
+                        catch (error) {
+                            console.error("[auth] afterUserCreate failed", error);
+                        }
+                    },
+                },
+            },
+            account: {
+                create: {
+                    before: async (account) => (await beforeAccount(account)) === false ? false : { data: withoutTokens(account) },
+                },
+                update: { before: async (account) => ({ data: withoutTokens(account) }) },
+            },
+            session: { create: { before: async (session) => beforeSession(session) } },
+        },
+        hooks: {
+            // Keep the readable marker in step with the session, so pages without it never ask for
+            // the session at all.
+            after: createAuthMiddleware(async (ctx) => {
+                const set = (expiresAt) => ctx.setCookie(markerCookie, "1", { ...markerOptions, maxAge: markerMaxAge(expiresAt) });
+                const clear = () => ctx.setCookie(markerCookie, "", { ...markerOptions, maxAge: 0 });
+                const created = ctx.context.newSession;
+                if (created) {
+                    set(created.session.expiresAt);
+                }
+                else if (ctx.path === "/sign-out") {
+                    clear();
+                }
+                else if (ctx.path === "/get-session") {
+                    const returned = ctx.context.returned;
+                    if (returned?.session)
+                        set(returned.session.expiresAt);
+                    else
+                        clear();
+                }
+            }),
+        },
+        plugins: [genericOAuth({ config: [osuProvider({ clientId, clientSecret })] })],
+    });
+};

package/dist/auth/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @file src/auth/index.ts
+ * @desc @haruhimemoe/next-kit/auth: better-auth with osu! sign-in. createOsuAuth, the osu!
+ *       provider pieces, the indexes better-auth's collections need, and reading the caller.
+ *       Server only.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+export { type AuthRow, createOsuAuth, type OsuAuth, type OsuAuthHooks, type OsuAuthOptions, type UserFields, } from "./create.js";
+export { AUTH_INDEX_SPECS, AUTH_INDEXES } from "./indexes.js";
+export { OSU_PROVIDER_ID, OSU_USER_FIELDS, type OsuProviderOptions, osuProfileToUser, osuProvider, withoutTokens, } from "./osu.js";
+export { getOsuUser, type OsuSession, type OsuSessionUser, type SessionReader, toSessionUser, } from "./session.js";

package/dist/auth/index.js

@@ -0,0 +1,13 @@
+/**
+ * @file src/auth/index.ts
+ * @desc @haruhimemoe/next-kit/auth: better-auth with osu! sign-in. createOsuAuth, the osu!
+ *       provider pieces, the indexes better-auth's collections need, and reading the caller.
+ *       Server only.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+export { createOsuAuth, } from "./create.js";
+export { AUTH_INDEX_SPECS, AUTH_INDEXES } from "./indexes.js";
+export { OSU_PROVIDER_ID, OSU_USER_FIELDS, osuProfileToUser, osuProvider, withoutTokens, } from "./osu.js";
+export { getOsuUser, toSessionUser, } from "./session.js";

package/dist/auth/indexes.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @file src/auth/indexes.ts
+ * @desc The indexes better-auth's MongoDB collections need and don't get on their own: one user
+ *       per osu! id (two sign-ins racing can't make two), one account row per osu! link, one
+ *       session per token (every signed-in request looks it up; a secret, so never logged), and
+ *       sessions by user, plus the TTL index that deletes a session about a minute after it
+ *       expires. Pass AUTH_INDEX_SPECS to ensureIndexes. Moved from pools (src/lib/db-indexes.ts,
+ *       src/constants/db.ts); packs had only the session TTL, so its session lookups scanned.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import type { IndexSpec } from "../mongo/indexes.js";
+/** Index names on better-auth's collections. */
+export declare const AUTH_INDEXES: Readonly<{
+    userOsuId: "user_osuId_unique";
+    accountKey: "account_providerId_accountId_unique";
+    sessionToken: "session_token_unique";
+    sessionUser: "session_userId";
+    sessionTtl: "session_expiresAt_ttl";
+}>;
+/** The five indexes, for ensureIndexes from @haruhimemoe/next-kit/mongo. */
+export declare const AUTH_INDEX_SPECS: readonly IndexSpec[];

package/dist/auth/indexes.js

@@ -0,0 +1,44 @@
+/**
+ * @file src/auth/indexes.ts
+ * @desc The indexes better-auth's MongoDB collections need and don't get on their own: one user
+ *       per osu! id (two sign-ins racing can't make two), one account row per osu! link, one
+ *       session per token (every signed-in request looks it up; a secret, so never logged), and
+ *       sessions by user, plus the TTL index that deletes a session about a minute after it
+ *       expires. Pass AUTH_INDEX_SPECS to ensureIndexes. Moved from pools (src/lib/db-indexes.ts,
+ *       src/constants/db.ts); packs had only the session TTL, so its session lookups scanned.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** Index names on better-auth's collections. */
+export const AUTH_INDEXES = Object.freeze({
+    userOsuId: "user_osuId_unique",
+    accountKey: "account_providerId_accountId_unique",
+    sessionToken: "session_token_unique",
+    sessionUser: "session_userId",
+    sessionTtl: "session_expiresAt_ttl",
+});
+/** The five indexes, for ensureIndexes from @haruhimemoe/next-kit/mongo. */
+export const AUTH_INDEX_SPECS = Object.freeze([
+    { collection: "user", key: { osuId: 1 }, name: AUTH_INDEXES.userOsuId, unique: true },
+    {
+        collection: "account",
+        key: { providerId: 1, accountId: 1 },
+        name: AUTH_INDEXES.accountKey,
+        unique: true,
+    },
+    {
+        collection: "session",
+        key: { token: 1 },
+        name: AUTH_INDEXES.sessionToken,
+        unique: true,
+        secret: true,
+    },
+    { collection: "session", key: { userId: 1 }, name: AUTH_INDEXES.sessionUser },
+    {
+        collection: "session",
+        key: { expiresAt: 1 },
+        name: AUTH_INDEXES.sessionTtl,
+        expireAfterSeconds: 0,
+    },
+]);