@haruhimemoe/next-kit 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-04
+
+### Added
+- `buildSecurityTxt` takes `contactUrl`, listed before the email.
+- `api-keys` entry point: the shared key format (`h` + two letters + `_`, then 32 random bytes), `createApiKeyStore` over `api_keys`, and `createApiKeyGuard` with `API_LIMITS` for `/api/v1` routes. Moved from packs.
+- `next-kit check` bin: fails when an app is missing a standard route.
+
+### Changed
+- `@haruhimemoe/ui` peer range now covers 0.5 through 0.9.
+
 ## [0.4.0] - 2026-09-28
 
 ### Added
@@ -52,7 +62,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `@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.4.0...HEAD
+[unreleased]: https://github.com/haruhimemoe/next-kit/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/haruhimemoe/next-kit/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/haruhimemoe/next-kit/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/haruhimemoe/next-kit/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/haruhimemoe/next-kit/compare/v0.2.0...v0.2.1

package/README.md

@@ -11,6 +11,7 @@ The Next.js server plumbing the haruhime.moe tools share. [packs.haruhime.moe](h
 - **`/auth-react`:** the browser half: the signed-in marker cookie, the account store and `useAccount`, `RestoreSignedIn`, and the account components (Sign in with osu!, Sign out, the header's account menu, Delete my account) styled with `@haruhimemoe/ui`.
 - **`/seo`:** Next.js metadata that keeps each page's canonical, og:url and preview image together, robots.txt with the AI crawler stance written down, sitemap entries with honest lastmod, schema.org JSON-LD builders, and llms.txt. No runtime imports; all four haruhime.moe sites use it.
 - **`/testing`:** Vitest helpers: one in-memory MongoDB per run, an msw server that refuses unhandled requests, and a fake env.
+- **`/api-keys`:** the shared key format (an app prefix like `hpk_` plus 32 random bytes), a key store over `api_keys`, and the `/api/v1` guard with the standard limits.
 
 Every name, path, limit and message comes from the caller. There is no root entry point; import a subpath.
 
@@ -29,9 +30,10 @@ bun add @haruhimemoe/next-kit zod
 | `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, `@haruhimemoe/ui` ^0.5.0 (with its theme set up) |
+| `auth-react` | `react` ^19.3.0, `next` ^16.3.6, `@haruhimemoe/ui` ^0.5.0 \|\| ^0.6.0 \|\| ^0.7.0 \|\| ^0.8.0 \|\| ^0.9.0 (with its theme set up) |
 | `seo` | `next` ^16.3.6 types only (nothing loads at runtime) |
 | `testing` | `vitest` ^5.0.1, `msw` ^2.15.0, `mongodb-memory-server` ^11.3.0 |
+| `api-keys` | `mongodb` ^7.6.0 |
 
 ## Use
 
@@ -147,6 +149,22 @@ export default async () => sitemapEntries(SEO_SITE, [["/", "/search"], pools.map
 export const GET = () => textResponse(llmsTxt({ title: "pools.haruhime.moe", summary: SEO_SITE.description, sections }));
 ```
 
+## Standards check
+
+`next-kit check [dir]` walks `src/app` (default: the current directory) and confirms every standard route exists, so CI catches a missing one before a page does:
+
+```sh
+bunx next-kit check
+```
+
+It always checks the crawl files: `robots.ts`, `sitemap.ts`, `llms.txt/route.ts`, `llms-full.txt/route.ts`, and `.well-known/security.txt/route.ts` (each also accepted as a route handler, like `robots.txt/route.ts`). Once an app has `src/app/api/v1/`, it also checks the public API: `api/v1/me/route.ts`, `api/v1/openapi.json/route.ts`, `api/me/api-key/route.ts`, and a `docs/api` page (a dynamic `docs/[slug]/page.tsx` counts too). Route groups like `(public)/` are ignored, since they don't change the URL.
+
+The command prints one `pass` or `FAIL` line per standard, names each missing file, and exits 1 on a failure (or when `src/app` is missing). Add it to CI:
+
+```yaml
+- run: bunx next-kit check
+```
+
 ## API
 
 ### server
@@ -167,7 +185,7 @@ export const GET = () => textResponse(llmsTxt({ title: "pools.haruhime.moe", sum
 | `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`. |
+| `buildSecurityTxt({ contactEmail, siteUrl, policyUrl, now, contactUrl? })` | The RFC 9116 body, expiring a year after `now`, with optional `contactUrl` listed before the email. |
 
 ### env
 
@@ -251,6 +269,27 @@ Since 0.3.0. Every helper takes the app's `Site`: `name`, `url` (the canonical o
 | `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. |
 
+### api-keys
+
+| Export | What it does |
+| --- | --- |
+| `API_KEY_BYTES` | Random bytes in a key: 32, shown as 43 base64url characters. |
+| `API_KEY_DISPLAY_LENGTH` | Characters of a key shown on account pages and in data exports (prefix + 8): 12. |
+| `API_KEY_PREFIX_PATTERN` | Every app prefix: `h`, two lowercase letters, `_`. |
+| `generateApiKey(prefix)` | A new key for that prefix; show it once and store only `hashApiKey(key)`. Throws `TypeError` on a bad prefix. |
+| `hashApiKey(key)` | A key's SHA-256 hex digest, the only form ever stored. |
+| `apiKeyDisplay(key)` | A key's first `API_KEY_DISPLAY_LENGTH` characters. |
+| `isApiKeyFormat(prefix, value)` | True only for that prefix plus 43 base64url characters; checked before hashing an untrusted token. |
+| `apiKeyToken(headers)` | The single token after `Bearer ` (any case, extra spaces ignored) in a request's `authorization` header, or null. |
+| `assertApiKeyPrefix(prefix)` | Throws `TypeError` unless the prefix matches `API_KEY_PREFIX_PATTERN`. |
+| `API_KEYS_COLLECTION` | The collection every app keeps its keys in: `api_keys`. |
+| `LAST_USED_INTERVAL_MS` | `lastUsedAt` is written at most this often (an hour), to save writes. |
+| `apiKeyIndexSpecs(collection?)` | Unique `userId` and unique `hash` (`secret: true`, never logged), for the app's own index list. |
+| `createApiKeyStore({ prefix, db, collection?, now? })` | One key per user over MongoDB: `issue(userId)`, `info(userId)`, `revoke(userId)`, `authenticate(key)` (the owner's user id and a `stamp()` to record the use), `deleteFor(userId)` and `ensureIndexes()`. Throws `TypeError` on a bad prefix. |
+| `API_LIMITS` | The standard fixed-window limits every haruhime API uses: `api` (60/min per user), `apiWrite` (10/min per user, also counted by `api`), `authFail` (20/min per IP), `keyCreate` (10/hour per user). |
+| `API_SERVER_ERROR` | The 500 message when a key lookup or handler throws. |
+| `createApiKeyGuard({ store, limiter, resolveCaller, messages, limits?, now? })` | Returns `withApiKey(handler)`: a `/api/v1` route handler that runs `handler(request, caller, context)` only for a good key under `API_LIMITS`, with `RateLimit-*` headers, `Cache-Control: no-store`, a 401 with `WWW-Authenticate: Bearer` for a missing or bad key (counted per IP), and a JSON 500 for a thrown error. No CORS headers: the API is for servers and bots. |
+
 ## 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:

package/dist/api-keys/format.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @file src/api-keys/format.ts
+ * @desc The haruhime API key format: an app prefix ("h" + two letters + "_", like hpk_ for packs)
+ *       plus 32 random bytes in base64url. Only the SHA-256 hex digest is stored; the first 12
+ *       characters are kept for display. Moved from packs (src/lib/api-key.ts) with the prefix
+ *       passed in.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+/** Random bytes in a key: 43 base64url characters. */
+export declare const API_KEY_BYTES = 32;
+/** Characters of a key shown on account pages and in data exports (prefix + 8). */
+export declare const API_KEY_DISPLAY_LENGTH = 12;
+/** Every app prefix: "h", two lowercase letters, "_". */
+export declare const API_KEY_PREFIX_PATTERN: RegExp;
+/**
+ * @function assertApiKeyPrefix
+ * @param prefix {string} an app prefix, like "hpl_"
+ * @returns {void}
+ * @throws {TypeError} when the prefix isn't "h" + two lowercase letters + "_"
+ */
+export declare const assertApiKeyPrefix: (prefix: string) => void;
+/**
+ * @function generateApiKey
+ * @param prefix {string} the app prefix
+ * @returns {string} a new key; show it once and store only hashApiKey(key)
+ * @throws {TypeError} on a bad prefix
+ */
+export declare const generateApiKey: (prefix: string) => string;
+/**
+ * @function hashApiKey
+ * @param key {string} a full key
+ * @returns {string} its SHA-256 hex digest
+ */
+export declare const hashApiKey: (key: string) => string;
+/**
+ * @function apiKeyDisplay
+ * @param key {string} a full key
+ * @returns {string} its first API_KEY_DISPLAY_LENGTH characters
+ */
+export declare const apiKeyDisplay: (key: string) => string;
+/**
+ * @function isApiKeyFormat
+ * @param prefix {string} the app prefix
+ * @param value {string} an untrusted token
+ * @returns {boolean} true only for this prefix plus 43 base64url characters
+ */
+export declare const isApiKeyFormat: (prefix: string, value: string) => boolean;
+/**
+ * @function apiKeyToken
+ * @param headers {Headers} request headers
+ * @returns {string | null} the single token after "Bearer " (any case, extra spaces ignored),
+ *          or null
+ */
+export declare const apiKeyToken: (headers: Headers) => string | null;

package/dist/api-keys/format.js

@@ -0,0 +1,67 @@
+/**
+ * @file src/api-keys/format.ts
+ * @desc The haruhime API key format: an app prefix ("h" + two letters + "_", like hpk_ for packs)
+ *       plus 32 random bytes in base64url. Only the SHA-256 hex digest is stored; the first 12
+ *       characters are kept for display. Moved from packs (src/lib/api-key.ts) with the prefix
+ *       passed in.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { createHash, randomBytes } from "node:crypto";
+/** Random bytes in a key: 43 base64url characters. */
+export const API_KEY_BYTES = 32;
+/** Characters of a key shown on account pages and in data exports (prefix + 8). */
+export const API_KEY_DISPLAY_LENGTH = 12;
+/** Every app prefix: "h", two lowercase letters, "_". */
+export const API_KEY_PREFIX_PATTERN = /^h[a-z]{2}_$/;
+const SECRET_LENGTH = Math.ceil((API_KEY_BYTES * 4) / 3);
+const SECRET = new RegExp(`^[A-Za-z0-9_-]{${SECRET_LENGTH}}$`);
+const BEARER = /^Bearer[ \t]+(\S+)$/i;
+/**
+ * @function assertApiKeyPrefix
+ * @param prefix {string} an app prefix, like "hpl_"
+ * @returns {void}
+ * @throws {TypeError} when the prefix isn't "h" + two lowercase letters + "_"
+ */
+export const assertApiKeyPrefix = (prefix) => {
+    if (!API_KEY_PREFIX_PATTERN.test(prefix)) {
+        throw new TypeError(`API key prefix must look like "hpk_", got ${JSON.stringify(prefix)}`);
+    }
+};
+/**
+ * @function generateApiKey
+ * @param prefix {string} the app prefix
+ * @returns {string} a new key; show it once and store only hashApiKey(key)
+ * @throws {TypeError} on a bad prefix
+ */
+export const generateApiKey = (prefix) => {
+    assertApiKeyPrefix(prefix);
+    return `${prefix}${randomBytes(API_KEY_BYTES).toString("base64url")}`;
+};
+/**
+ * @function hashApiKey
+ * @param key {string} a full key
+ * @returns {string} its SHA-256 hex digest
+ */
+export const hashApiKey = (key) => createHash("sha256").update(key, "utf8").digest("hex");
+/**
+ * @function apiKeyDisplay
+ * @param key {string} a full key
+ * @returns {string} its first API_KEY_DISPLAY_LENGTH characters
+ */
+export const apiKeyDisplay = (key) => key.slice(0, API_KEY_DISPLAY_LENGTH);
+/**
+ * @function isApiKeyFormat
+ * @param prefix {string} the app prefix
+ * @param value {string} an untrusted token
+ * @returns {boolean} true only for this prefix plus 43 base64url characters
+ */
+export const isApiKeyFormat = (prefix, value) => value.startsWith(prefix) && SECRET.test(value.slice(prefix.length));
+/**
+ * @function apiKeyToken
+ * @param headers {Headers} request headers
+ * @returns {string | null} the single token after "Bearer " (any case, extra spaces ignored),
+ *          or null
+ */
+export const apiKeyToken = (headers) => BEARER.exec(headers.get("authorization")?.trim() ?? "")?.[1] ?? null;

package/dist/api-keys/guard.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @file src/api-keys/guard.ts
+ * @desc The /api/v1 guard every haruhime app uses: looks the Bearer key up; a missing or bad key
+ *       counts against the caller's IP (auth-fail, 429 past it) and answers 401 with
+ *       WWW-Authenticate: Bearer; a good key counts per user (api, and api-write for writes),
+ *       showing whichever runs out first. Every answer gets RateLimit-* headers and no-store, a
+ *       thrown error included (JSON 500). No CORS headers: the API is for servers and bots.
+ *       Moved from packs (src/lib/api-auth.ts) with the user lookup and messages passed in.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { RateLimitRule } from "../server/counter.js";
+import { type RateLimiter } from "../server/rate-limit.js";
+import type { ApiKeyStore } from "./store.js";
+/** The standard limits every haruhime API uses (fixed windows). */
+export declare const API_LIMITS: {
+    /** Every /api/v1 request, per user. */
+    readonly api: {
+        readonly scope: "api";
+        readonly limit: 60;
+        readonly windowSeconds: 60;
+    };
+    /** POST/PUT/PATCH/DELETE on /api/v1, per user (also counted by api). */
+    readonly apiWrite: {
+        readonly scope: "api-write";
+        readonly limit: 10;
+        readonly windowSeconds: 60;
+    };
+    /** Missing, bad or revoked keys, per IP. */
+    readonly authFail: {
+        readonly scope: "auth-fail";
+        readonly limit: 20;
+        readonly windowSeconds: 60;
+    };
+    /** Creating or regenerating a key on the account page, per user. */
+    readonly keyCreate: {
+        readonly scope: "key-create";
+        readonly limit: 10;
+        readonly windowSeconds: 3600;
+    };
+};
+/** The rules the guard counts. */
+export type ApiLimits = {
+    api: RateLimitRule;
+    apiWrite: RateLimitRule;
+    authFail: RateLimitRule;
+};
+/** The 500 message when a key lookup or handler throws. */
+export declare const API_SERVER_ERROR = "Something went wrong on our end. Try again in a minute.";
+/** createApiKeyGuard's options. */
+export type ApiKeyGuardOptions<Caller> = {
+    store: Pick<ApiKeyStore, "authenticate">;
+    limiter: Pick<RateLimiter, "hit">;
+    /** Who a key's user is; null for a deleted or system account (answers 401). */
+    resolveCaller: (userId: string) => Promise<Caller | null>;
+    /** missing: no key sent (name the prefix); invalid: a bad, revoked or replaced key. */
+    messages: {
+        missing: string;
+        invalid: string;
+        serverError?: string;
+    };
+    limits?: ApiLimits;
+    now?: () => number;
+};
+/**
+ * @function createApiKeyGuard
+ * @param options {ApiKeyGuardOptions<Caller>} store, limiter, caller lookup, messages
+ * @returns {Function} withApiKey(handler): a route handler that runs handler(request, caller,
+ *          context) only for a good key under its limits
+ */
+export declare const createApiKeyGuard: <Caller extends {
+    id: string;
+}>({ store, limiter, resolveCaller, messages, limits, now, }: ApiKeyGuardOptions<Caller>) => <C = unknown>(handler: (request: Request, caller: Caller, context: C) => Promise<Response>) => (request: Request, context: C) => Promise<Response>;

package/dist/api-keys/guard.js

@@ -0,0 +1,90 @@
+/**
+ * @file src/api-keys/guard.ts
+ * @desc The /api/v1 guard every haruhime app uses: looks the Bearer key up; a missing or bad key
+ *       counts against the caller's IP (auth-fail, 429 past it) and answers 401 with
+ *       WWW-Authenticate: Bearer; a good key counts per user (api, and api-write for writes),
+ *       showing whichever runs out first. Every answer gets RateLimit-* headers and no-store, a
+ *       thrown error included (JSON 500). No CORS headers: the API is for servers and bots.
+ *       Moved from packs (src/lib/api-auth.ts) with the user lookup and messages passed in.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { clientIp, rateLimitSubject } from "../server/client-ip.js";
+import { jsonError, withHeaders } from "../server/errors.js";
+import { rateLimitHeaders, tooManyRequests, unlimited, } from "../server/rate-limit.js";
+import { apiKeyToken } from "./format.js";
+/** The standard limits every haruhime API uses (fixed windows). */
+export const API_LIMITS = {
+    /** Every /api/v1 request, per user. */
+    api: { scope: "api", limit: 60, windowSeconds: 60 },
+    /** POST/PUT/PATCH/DELETE on /api/v1, per user (also counted by api). */
+    apiWrite: { scope: "api-write", limit: 10, windowSeconds: 60 },
+    /** Missing, bad or revoked keys, per IP. */
+    authFail: { scope: "auth-fail", limit: 20, windowSeconds: 60 },
+    /** Creating or regenerating a key on the account page, per user. */
+    keyCreate: { scope: "key-create", limit: 10, windowSeconds: 3600 },
+};
+/** The 500 message when a key lookup or handler throws. */
+export const API_SERVER_ERROR = "Something went wrong on our end. Try again in a minute.";
+const WRITE_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+const finish = (response, limit) => withHeaders(response, { ...rateLimitHeaders(limit), "Cache-Control": "no-store" });
+/**
+ * @function createApiKeyGuard
+ * @param options {ApiKeyGuardOptions<Caller>} store, limiter, caller lookup, messages
+ * @returns {Function} withApiKey(handler): a route handler that runs handler(request, caller,
+ *          context) only for a good key under its limits
+ */
+export const createApiKeyGuard = ({ store, limiter, resolveCaller, messages, limits = API_LIMITS, now = () => Date.now(), }) => {
+    /** Nothing counted yet (the key lookup threw): the per-user limit, untouched. */
+    const uncounted = () => unlimited(limits.api, now());
+    const serverError = (error, limit) => {
+        console.error("api: request failed", error);
+        return finish(jsonError(500, messages.serverError ?? API_SERVER_ERROR), limit);
+    };
+    const lookUp = async (token) => {
+        const match = token ? await store.authenticate(token) : null;
+        const caller = match ? await resolveCaller(match.userId) : null;
+        // Stamp only a key whose owner checks out (packs' order).
+        if (caller)
+            await match?.stamp();
+        return caller;
+    };
+    return (handler) => async (request, context) => {
+        const token = apiKeyToken(request.headers);
+        let caller;
+        try {
+            caller = await lookUp(token);
+        }
+        catch (error) {
+            return serverError(error, uncounted());
+        }
+        if (!caller) {
+            const failures = await limiter.hit(limits.authFail, rateLimitSubject(clientIp(request.headers)));
+            if (!failures.allowed)
+                return finish(tooManyRequests(failures), failures);
+            const body = token
+                ? jsonError(401, messages.invalid, "invalid_api_key")
+                : jsonError(401, messages.missing);
+            return finish(withHeaders(body, { "WWW-Authenticate": "Bearer" }), failures);
+        }
+        const requests = await limiter.hit(limits.api, caller.id);
+        if (!requests.allowed)
+            return finish(tooManyRequests(requests), requests);
+        let shown = requests;
+        if (WRITE_METHODS.has(request.method)) {
+            const writes = await limiter.hit(limits.apiWrite, caller.id);
+            if (!writes.allowed)
+                return finish(tooManyRequests(writes), writes);
+            // Show whichever counter runs out first.
+            if (writes.remaining < requests.remaining)
+                shown = writes;
+        }
+        try {
+            return finish(await handler(request, caller, context), shown);
+        }
+        catch (error) {
+            return serverError(error, shown);
+        }
+    };
+};

package/dist/api-keys/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @file src/api-keys/index.ts
+ * @desc @haruhimemoe/next-kit/api-keys: the API key format every haruhime app shares (an app
+ *       prefix like hpk_ plus 32 random bytes), the key store over api_keys, and the /api/v1
+ *       guard with the standard limits. Server only: loads node:crypto and mongodb.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+export { API_KEY_BYTES, API_KEY_DISPLAY_LENGTH, API_KEY_PREFIX_PATTERN, apiKeyDisplay, apiKeyToken, assertApiKeyPrefix, generateApiKey, hashApiKey, isApiKeyFormat, } from "./format.js";
+export { API_LIMITS, API_SERVER_ERROR, type ApiKeyGuardOptions, type ApiLimits, createApiKeyGuard, } from "./guard.js";
+export { API_KEYS_COLLECTION, type ApiKeyCreated, type ApiKeyInfo, type ApiKeyMatch, type ApiKeyStore, type ApiKeyStoreOptions, apiKeyIndexSpecs, createApiKeyStore, LAST_USED_INTERVAL_MS, } from "./store.js";

package/dist/api-keys/index.js

@@ -0,0 +1,12 @@
+/**
+ * @file src/api-keys/index.ts
+ * @desc @haruhimemoe/next-kit/api-keys: the API key format every haruhime app shares (an app
+ *       prefix like hpk_ plus 32 random bytes), the key store over api_keys, and the /api/v1
+ *       guard with the standard limits. Server only: loads node:crypto and mongodb.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+export { API_KEY_BYTES, API_KEY_DISPLAY_LENGTH, API_KEY_PREFIX_PATTERN, apiKeyDisplay, apiKeyToken, assertApiKeyPrefix, generateApiKey, hashApiKey, isApiKeyFormat, } from "./format.js";
+export { API_LIMITS, API_SERVER_ERROR, createApiKeyGuard, } from "./guard.js";
+export { API_KEYS_COLLECTION, apiKeyIndexSpecs, createApiKeyStore, LAST_USED_INTERVAL_MS, } from "./store.js";

package/dist/api-keys/store.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @file src/api-keys/store.ts
+ * @desc One API key per user in MongoDB (collection api_keys): issue (replaces), info, revoke,
+ *       authenticate and account deletion. Only the SHA-256 hash and a display prefix are
+ *       stored. Two issues racing still leave one key (unique userId; the loser updates).
+ *       authenticate gives the owner's user id; who that user is stays the app's call.
+ *       lastUsedAt is written at most once an hour. Moved from packs (src/services/api-keys.ts).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { type Db } from "mongodb";
+import { type IndexSpec } from "../mongo/indexes.js";
+/** The collection every app keeps its keys in. */
+export declare const API_KEYS_COLLECTION = "api_keys";
+/** lastUsedAt is written at most this often, to save writes. */
+export declare const LAST_USED_INTERVAL_MS: number;
+/** A key as account pages show it. */
+export type ApiKeyInfo = {
+    prefix: string;
+    createdAt: string;
+    lastUsedAt: string | null;
+};
+/** A freshly issued key: the full key, shown once, and its info. */
+export type ApiKeyCreated = {
+    key: string;
+    apiKey: ApiKeyInfo;
+};
+/** A key that matched: its owner, and stamp() to record the use once the owner checks out. */
+export type ApiKeyMatch = {
+    userId: string;
+    stamp: () => Promise<void>;
+};
+/** createApiKeyStore's options. */
+export type ApiKeyStoreOptions = {
+    prefix: string;
+    db: () => Promise<Db>;
+    collection?: string;
+    now?: () => number;
+};
+/** What createApiKeyStore returns. */
+export type ApiKeyStore = {
+    prefix: string;
+    issue: (userId: string) => Promise<ApiKeyCreated>;
+    info: (userId: string) => Promise<ApiKeyInfo | null>;
+    revoke: (userId: string) => Promise<boolean>;
+    authenticate: (key: string) => Promise<ApiKeyMatch | null>;
+    deleteFor: (userId: string) => Promise<number>;
+    ensureIndexes: () => Promise<void>;
+};
+/**
+ * @function apiKeyIndexSpecs
+ * @param collection {string} the keys collection (default api_keys)
+ * @returns {IndexSpec[]} unique userId and unique hash, for the app's own index list
+ */
+export declare const apiKeyIndexSpecs: (collection?: string) => IndexSpec[];
+/**
+ * @function createApiKeyStore
+ * @param options {ApiKeyStoreOptions} the app prefix, the database, the collection (default
+ *        api_keys) and a clock (default Date.now)
+ * @returns {ApiKeyStore} the key operations for that app
+ * @throws {TypeError} on a bad prefix
+ */
+export declare const createApiKeyStore: ({ prefix, db, collection, now, }: ApiKeyStoreOptions) => ApiKeyStore;

package/dist/api-keys/store.js

@@ -0,0 +1,95 @@
+/**
+ * @file src/api-keys/store.ts
+ * @desc One API key per user in MongoDB (collection api_keys): issue (replaces), info, revoke,
+ *       authenticate and account deletion. Only the SHA-256 hash and a display prefix are
+ *       stored. Two issues racing still leave one key (unique userId; the loser updates).
+ *       authenticate gives the owner's user id; who that user is stays the app's call.
+ *       lastUsedAt is written at most once an hour. Moved from packs (src/services/api-keys.ts).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { ObjectId } from "mongodb";
+import { isDuplicateKeyError } from "../mongo/duplicate.js";
+import { ensureIndexes as buildIndexes } from "../mongo/indexes.js";
+import { apiKeyDisplay, assertApiKeyPrefix, generateApiKey, hashApiKey, isApiKeyFormat, } from "./format.js";
+/** The collection every app keeps its keys in. */
+export const API_KEYS_COLLECTION = "api_keys";
+/** lastUsedAt is written at most this often, to save writes. */
+export const LAST_USED_INTERVAL_MS = 60 * 60 * 1000;
+const toInfo = (doc) => ({
+    prefix: doc.prefix,
+    createdAt: doc.createdAt.toISOString(),
+    lastUsedAt: doc.lastUsedAt ? doc.lastUsedAt.toISOString() : null,
+});
+/**
+ * @function apiKeyIndexSpecs
+ * @param collection {string} the keys collection (default api_keys)
+ * @returns {IndexSpec[]} unique userId and unique hash, for the app's own index list
+ */
+export const apiKeyIndexSpecs = (collection = API_KEYS_COLLECTION) => [
+    { collection, key: { userId: 1 }, unique: true },
+    // The hash is a credential digest: never log its values.
+    { collection, key: { hash: 1 }, unique: true, secret: true },
+];
+/**
+ * @function createApiKeyStore
+ * @param options {ApiKeyStoreOptions} the app prefix, the database, the collection (default
+ *        api_keys) and a clock (default Date.now)
+ * @returns {ApiKeyStore} the key operations for that app
+ * @throws {TypeError} on a bad prefix
+ */
+export const createApiKeyStore = ({ prefix, db, collection = API_KEYS_COLLECTION, 
+// Read per call, so fake timers in app tests move it.
+now = () => Date.now(), }) => {
+    assertApiKeyPrefix(prefix);
+    const keys = async () => (await db()).collection(collection);
+    const issue = async (userId) => {
+        const key = generateApiKey(prefix);
+        const filter = { userId: new ObjectId(userId) };
+        const update = {
+            $set: { prefix: apiKeyDisplay(key), hash: hashApiKey(key), createdAt: new Date(now()) },
+            $unset: { lastUsedAt: 1 },
+        };
+        const upsert = async () => (await keys()).findOneAndUpdate(filter, update, { upsert: true, returnDocument: "after" });
+        const doc = await upsert().catch((error) => {
+            if (!isDuplicateKeyError(error))
+                throw error;
+            return upsert();
+        });
+        if (!doc)
+            throw new Error("api key upsert returned no document");
+        return { key, apiKey: toInfo(doc) };
+    };
+    const authenticate = async (key) => {
+        if (!isApiKeyFormat(prefix, key))
+            return null;
+        const hash = hashApiKey(key);
+        const collectionRef = await keys();
+        const doc = await collectionRef.findOne({ hash });
+        if (!doc)
+            return null;
+        const stamp = async () => {
+            const at = now();
+            if (doc.lastUsedAt && at - doc.lastUsedAt.getTime() < LAST_USED_INTERVAL_MS)
+                return;
+            // Filter on the hash too, so a regenerate in between isn't stamped with this use.
+            await collectionRef.updateOne({ _id: doc._id, hash }, { $set: { lastUsedAt: new Date(at) } });
+        };
+        return { userId: doc.userId.toString(), stamp };
+    };
+    return {
+        prefix,
+        issue,
+        authenticate,
+        info: async (userId) => {
+            const doc = await (await keys()).findOne({ userId: new ObjectId(userId) });
+            return doc ? toInfo(doc) : null;
+        },
+        revoke: async (userId) => (await (await keys()).deleteOne({ userId: new ObjectId(userId) })).deletedCount === 1,
+        deleteFor: async (userId) => (await (await keys()).deleteMany({ userId: new ObjectId(userId) })).deletedCount,
+        ensureIndexes: async () => {
+            await buildIndexes(await db(), apiKeyIndexSpecs(collection));
+        },
+    };
+};

package/dist/check/cli.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * @file src/check/cli.ts
+ * @desc `next-kit check [dir]`: lists src/app under dir (default: the working directory), runs
+ *       checkStandards and prints one line per standard. Exits 1 when one fails or src/app is
+ *       missing.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+/**
+ * @function runCheck
+ * @param root {string} the app's root (holds src/app)
+ * @param log {(line: string) => void} where lines go (default console.log)
+ * @returns {number} 0 when every standard passes, otherwise 1
+ */
+export declare const runCheck: (root: string, log?: (line: string) => void) => number;

package/dist/check/cli.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * @file src/check/cli.ts
+ * @desc `next-kit check [dir]`: lists src/app under dir (default: the working directory), runs
+ *       checkStandards and prints one line per standard. Exits 1 when one fails or src/app is
+ *       missing.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { existsSync, readdirSync, realpathSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { argv, cwd, exit } from "node:process";
+import { pathToFileURL } from "node:url";
+import { checkStandards } from "./standards.js";
+const walk = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((entry) => entry.isDirectory() ? walk(join(dir, entry.name)) : [join(dir, entry.name)]);
+/**
+ * @function runCheck
+ * @param root {string} the app's root (holds src/app)
+ * @param log {(line: string) => void} where lines go (default console.log)
+ * @returns {number} 0 when every standard passes, otherwise 1
+ */
+export const runCheck = (root, log = console.log) => {
+    const app = join(root, "src", "app");
+    if (!existsSync(app)) {
+        log(`next-kit check: no src/app in ${root}`);
+        return 1;
+    }
+    const files = walk(app).map((file) => relative(app, file).split(sep).join("/"));
+    const results = checkStandards(files);
+    for (const result of results) {
+        log(`${result.ok ? "pass" : "FAIL"}  ${result.label}`);
+        for (const name of result.missing)
+            log(`      missing src/app/${name}`);
+    }
+    return results.every((result) => result.ok) ? 0 : 1;
+};
+/* v8 ignore start */
+/** True when this file is the one Node was asked to run, even through a symlinked bin: a
+ * symlinked `next-kit` resolves argv[1] to the link, while import.meta.url is the realpath. */
+const isMainEntry = () => {
+    const entry = argv[1];
+    if (!entry || !existsSync(entry))
+        return false;
+    return pathToFileURL(realpathSync(entry)).href === import.meta.url;
+};
+if (isMainEntry()) {
+    const [command, dir] = argv.slice(2);
+    if (command !== "check") {
+        console.log("usage: next-kit check [dir]");
+        exit(2);
+    }
+    exit(runCheck(dir ?? cwd()));
+}
+/* v8 ignore stop */

package/dist/check/standards.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file src/check/standards.ts
+ * @desc The routes every haruhime app serves, checked against an app's file list (paths under
+ *       src/app). Crawl files always; the API standard once api/v1 exists. Brand and guides
+ *       join in phase 2.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+/** One standard's outcome. */
+export type StandardResult = {
+    id: string;
+    label: string;
+    ok: boolean;
+    missing: string[];
+};
+/**
+ * @function checkStandards
+ * @param files {readonly string[]} every file under src/app, relative, "/"-separated
+ * @returns {StandardResult[]} crawl files always, the API standard when api/v1 exists
+ */
+export declare const checkStandards: (files: readonly string[]) => StandardResult[];

package/dist/check/standards.js

@@ -0,0 +1,51 @@
+/**
+ * @file src/check/standards.ts
+ * @desc The routes every haruhime app serves, checked against an app's file list (paths under
+ *       src/app). Crawl files always; the API standard once api/v1 exists. Brand and guides
+ *       join in phase 2.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+const has = (...patterns) => (files) => files.some((file) => patterns.some((pattern) => pattern.test(file)));
+const CRAWL = [
+    { name: "robots.ts", matches: has(/^robots\.(ts|js)$/, /^robots\.txt\/route\.(ts|js)$/) },
+    { name: "sitemap.ts", matches: has(/^sitemap\.(ts|js)$/, /^sitemap\.xml\/route\.(ts|js)$/) },
+    { name: "llms.txt/route.ts", matches: has(/^llms\.txt\/route\.(ts|js)$/) },
+    { name: "llms-full.txt/route.ts", matches: has(/^llms-full\.txt\/route\.(ts|js)$/) },
+    {
+        name: ".well-known/security.txt/route.ts",
+        matches: has(/^\.well-known\/security\.txt\/route\.(ts|js)$/),
+    },
+];
+const API = [
+    { name: "api/v1/me/route.ts", matches: has(/^api\/v1\/me\/route\.(ts|js)$/) },
+    {
+        name: "api/v1/openapi.json/route.ts",
+        matches: has(/^api\/v1\/openapi\.json\/route\.(ts|js)$/),
+    },
+    { name: "api/me/api-key/route.ts", matches: has(/^api\/me\/api-key\/route\.(ts|js)$/) },
+    {
+        name: "docs/api/page.tsx",
+        matches: has(/^(\([^)]+\)\/)?docs\/(api|\[[^\]]+\])\/page\.(tsx|jsx|ts|js)$/),
+    },
+];
+const evaluate = (id, label, reqs, files) => {
+    const missing = reqs.filter((req) => !req.matches(files)).map((req) => req.name);
+    return { id, label, ok: missing.length === 0, missing };
+};
+/** Route groups like (public)/ don't change the URL, so they are dropped before matching. */
+const ungrouped = (file) => file.replace(/(^|\/)\([^)]+\)(?=\/)/g, "").replace(/^\//, "");
+/**
+ * @function checkStandards
+ * @param files {readonly string[]} every file under src/app, relative, "/"-separated
+ * @returns {StandardResult[]} crawl files always, the API standard when api/v1 exists
+ */
+export const checkStandards = (files) => {
+    const flat = files.map(ungrouped);
+    const results = [evaluate("crawl", "Crawl files", CRAWL, flat)];
+    if (flat.some((file) => file.startsWith("api/v1/"))) {
+        results.push(evaluate("api", "Public API", API, flat));
+    }
+    return results;
+};

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

@@ -6,7 +6,7 @@
  *       caller passes them here.
  * @author David @dvhsh (https://dvh.sh)
  * @created Mon Sep 28, 2026
- * @modified Mon Sep 28, 2026
+ * @modified Sat Oct 3, 2026
  */
 /** RFC 9116 asks for an Expires less than a year out. */
 export declare const SECURITY_TXT_LIFETIME_DAYS = 365;
@@ -22,11 +22,13 @@ export type SecurityTxtOptions = {
     policyUrl: string;
     /** When the file is built (build time for a static route). */
     now: Date;
+    /** A preferred report URL (like a GitHub advisory form), listed before the email. */
+    contactUrl?: string;
 };
 /**
  * @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
+ * @param options {SecurityTxtOptions} contact, site, policy, build time, and optional contact URL
+ * @returns {string} the security.txt body: Contact (URL first if present), Contact (mailto),
+ *          Expires, Preferred-Languages, Canonical, Policy, one field per line, ending in one newline
  */
-export declare const buildSecurityTxt: ({ contactEmail, siteUrl, policyUrl, now, }: SecurityTxtOptions) => string;
+export declare const buildSecurityTxt: ({ contactEmail, siteUrl, policyUrl, now, contactUrl, }: SecurityTxtOptions) => string;

package/dist/server/security-txt.js

@@ -6,7 +6,7 @@
  *       caller passes them here.
  * @author David @dvhsh (https://dvh.sh)
  * @created Mon Sep 28, 2026
- * @modified Mon Sep 28, 2026
+ * @modified Sat Oct 3, 2026
  */
 /** RFC 9116 asks for an Expires less than a year out. */
 export const SECURITY_TXT_LIFETIME_DAYS = 365;
@@ -14,13 +14,14 @@ export const SECURITY_TXT_LIFETIME_DAYS = 365;
 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
+ * @param options {SecurityTxtOptions} contact, site, policy, build time, and optional contact URL
+ * @returns {string} the security.txt body: Contact (URL first if present), Contact (mailto),
+ *          Expires, Preferred-Languages, Canonical, Policy, one field per line, ending in one newline
  */
-export const buildSecurityTxt = ({ contactEmail, siteUrl, policyUrl, now, }) => {
+export const buildSecurityTxt = ({ contactEmail, siteUrl, policyUrl, now, contactUrl, }) => {
     const expires = new Date(now.getTime() + SECURITY_TXT_LIFETIME_DAYS * 86_400_000);
     const lines = [
+        ...(contactUrl ? [`Contact: ${contactUrl}`] : []),
         `Contact: mailto:${contactEmail}`,
         `Expires: ${expires.toISOString()}`,
         "Preferred-Languages: en",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@haruhimemoe/next-kit",
-  "version": "0.4.0",
-  "description": "The Next.js plumbing the haruhime.moe tools 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, the signed-in marker and account store for the browser, and SEO: metadata, robots.txt, sitemaps, JSON-LD and llms.txt.",
+  "version": "0.5.0",
+  "description": "The Next.js plumbing the haruhime.moe tools 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, the signed-in marker and account store for the browser, SEO: metadata, robots.txt, sitemaps, JSON-LD and llms.txt, and per-app API keys and the /api/v1 guard.",
   "keywords": [
     "nextjs",
     "next.js",
@@ -14,7 +14,8 @@
     "seo",
     "json-ld",
     "sitemap",
-    "llms.txt"
+    "llms.txt",
+    "api keys"
   ],
   "homepage": "https://github.com/haruhimemoe/next-kit#readme",
   "bugs": "https://github.com/haruhimemoe/next-kit/issues",
@@ -25,6 +26,9 @@
   "license": "MIT",
   "author": "David (https://dvh.sh)",
   "type": "module",
+  "bin": {
+    "next-kit": "./dist/check/cli.js"
+  },
   "exports": {
     "./server": {
       "types": "./dist/server/index.d.ts",
@@ -54,6 +58,10 @@
       "types": "./dist/seo/index.d.ts",
       "default": "./dist/seo/index.js"
     },
+    "./api-keys": {
+      "types": "./dist/api-keys/index.d.ts",
+      "default": "./dist/api-keys/index.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -84,7 +92,7 @@
   },
   "peerDependencies": {
     "@haruhimemoe/osu": "^0.2.0 || ^0.3.0 || ^0.4.0",
-    "@haruhimemoe/ui": "^0.5.0",
+    "@haruhimemoe/ui": "^0.5.0 || ^0.6.0 || ^0.7.0 || ^0.8.0 || ^0.9.0",
     "better-auth": "^1.7.5",
     "mongodb": "^7.6.0",
     "mongodb-memory-server": "^11.3.0",