@haruhimemoe/next-kit 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-04
+
+### Added
+- `docs` entry point: a content registry (`defineContent`, `CONTENT_SECTIONS`, `SECTION_LABELS`) and the path helpers (`contentPath`, `markdownPath`, `findEntry`, `contentParams`) for an app's docs, guides and legal pages, plus app-made extra entries like bb's tag pages. No runtime imports.
+- `mdxToMarkdown` in `docs`: converts bb-flavored MDX to plain Markdown (callouts to blockquotes, import/export lines dropped, capitalized JSX removed, root-relative links and images absolutized, a title heading added when missing). Content inside fenced code blocks is left untouched. Still no runtime imports.
+- `docs/files` entry point: `readContentMarkdown` reads and converts a registered entry's markdown file, and `contentFileDrift` compares a registry against the files on disk. Loads `node:fs`.
+- `contentLlmsTxt`, `contentLlmsFull`, `contentSitemap` and `contentRewrites` in `docs`: llms.txt (sections in order Docs, Guides, API, Legal, empty ones left out), llms-full.txt (each entry's own leading H1 stripped, since `llmsFull` writes the part title), sitemap records per section (an index path, each entry, each extra) and the one rewrite rule for a content page's ".md" mirror. Built on `llmsTxt`/`llmsFull`/`SitemapRecord` from `seo`. Still no runtime imports.
+
+### Changed
+- **Breaking (check only).** `next-kit check` now also checks files under `content/` and adds the `brand` and `legal` standards: `brand/page.tsx` and `legal/page.tsx` plus `legal/[x]/page.tsx`, `legal/[x]/md/route.ts`, `content/legal/terms.mdx` and `content/legal/privacy.mdx` are required on every app. A `docs` standard (`docs/page.tsx`, `docs/[x]/page.tsx`, `docs/[x]/md/route.ts`) joins in once `src/app/api/v1` exists or any `content/docs` file does; a `guides` standard joins in only once a `content/guides` file does. The `api` standard drops its `docs/api/page.tsx` requirement in favor of `content/docs/api.mdx`. `checkStandards` takes a second `contentFiles` argument; `StandardResult.missing` entries now carry their own `src/app/` or `content/` prefix. This is a 0.x minor: an app with no `/brand`, `/legal` route or legal content fails `next-kit check` in CI until it adds them.
+- `@haruhimemoe/ui` peer range also covers 0.10.0 (not yet published).
+
+## [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 +74,9 @@ 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.6.0...HEAD
+[0.6.0]: https://github.com/haruhimemoe/next-kit/compare/v0.5.0...v0.6.0
+[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,8 @@ 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.
+- **`/docs`:** a content registry for an app's docs, guides and legal pages: sections, entries, app-made extra entries (like bb's tag pages), the path helpers a dynamic route needs, and `mdxToMarkdown` to turn bb-flavored MDX into plain Markdown. No runtime imports. **`/docs/files`:** reads the markdown files a registry's entries point at and reports drift between the registry and disk (node:fs).
 
 Every name, path, limit and message comes from the caller. There is no root entry point; import a subpath.
 
@@ -29,9 +31,12 @@ 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 \|\| ^0.10.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 |
+| `docs` | nothing else |
+| `docs/files` | nothing else (`node:fs` is built in) |
 
 ## Use
 
@@ -147,6 +152,91 @@ export default async () => sitemapEntries(SEO_SITE, [["/", "/search"], pools.map
 export const GET = () => textResponse(llmsTxt({ title: "pools.haruhime.moe", summary: SEO_SITE.description, sections }));
 ```
 
+### Docs (./docs)
+
+One registry per app, built from its docs, guides and legal entries; the crawl helpers and a dynamic route are built on top of it.
+
+```ts
+// src/constants/content.ts
+import { defineContent } from "@haruhimemoe/next-kit/docs";
+
+export const CONTENT = defineContent({
+  docs: [{ slug: "api", title: "API", description: "The /api/v1 reference.", lastUpdated: "2026-10-04" }],
+  guides: [{ slug: "make-a-pack", title: "Make a pack", description: "Build your first mappool.", lastUpdated: "2026-10-04" }],
+  legal: [
+    { slug: "terms", title: "Terms of service", description: "The rules for using pools.", lastUpdated: "2026-10-04" },
+    { slug: "privacy", title: "Privacy policy", description: "What pools stores and why.", lastUpdated: "2026-10-04" },
+  ],
+});
+
+// src/app/docs/[slug]/page.tsx (and guides/, legal/, the same shape)
+import { findEntry } from "@haruhimemoe/next-kit/docs";
+import { readContentMarkdown } from "@haruhimemoe/next-kit/docs/files";
+import { CONTENT } from "../../../constants/content";
+
+export default async function DocPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const entry = findEntry(CONTENT, "docs", slug);
+  if (!entry) return notFound();
+  const markdown = await readContentMarkdown(CONTENT, "docs", slug, { siteUrl: SEO_SITE.url });
+  return <Markdown>{markdown}</Markdown>;
+}
+
+// src/app/llms.txt/route.ts
+import { contentLlmsTxt } from "@haruhimemoe/next-kit/docs";
+import { textResponse } from "@haruhimemoe/next-kit/seo";
+
+export const GET = () =>
+  textResponse(contentLlmsTxt({ site: SEO_SITE, title: "pools.haruhime.moe", summary: SEO_SITE.description, content: CONTENT }));
+
+// src/app/llms-full.txt/route.ts
+import { contentLlmsFull } from "@haruhimemoe/next-kit/docs";
+import { readContentMarkdown } from "@haruhimemoe/next-kit/docs/files";
+
+export const GET = async () =>
+  textResponse(
+    await contentLlmsFull({
+      site: SEO_SITE, title: "pools.haruhime.moe", content: CONTENT,
+      read: (section, slug) => readContentMarkdown(CONTENT, section, slug, { siteUrl: SEO_SITE.url }),
+    }),
+  );
+
+// src/app/sitemap.ts
+import { contentSitemap } from "@haruhimemoe/next-kit/docs";
+
+export default async () => sitemapEntries(SEO_SITE, [["/", "/search"], contentSitemap(CONTENT)]);
+
+// next.config.ts
+import { contentRewrites } from "@haruhimemoe/next-kit/docs";
+
+export default { async rewrites() { return contentRewrites(); } };
+```
+
+## Standards check
+
+`next-kit check [dir]` walks `src/app` and, when it exists, `content/` (both under `dir`, default: the current directory) and confirms every standard file exists, so CI catches a missing one before a page does. It checks files only; the content registry itself is never parsed.
+
+```sh
+bunx next-kit check
+```
+
+Every app is checked against:
+
+- **crawl** (always): `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`).
+- **brand** (always): `brand/page.tsx`.
+- **legal** (always): `legal/page.tsx`, `legal/[x]/page.tsx`, `legal/[x]/md/route.ts` (any dynamic segment name), and `content/legal/terms.mdx` plus `content/legal/privacy.mdx`.
+- **docs**, once `src/app/api/v1` exists or any `content/docs` file does: `docs/page.tsx`, `docs/[x]/page.tsx`, `docs/[x]/md/route.ts`.
+- **guides**, only once a `content/guides` file exists: the same three files under `guides/`. An app with no guides is never asked for them.
+- **api**, once `src/app/api/v1` exists: `api/v1/me/route.ts`, `api/v1/openapi.json/route.ts`, `api/me/api-key/route.ts`, and `content/docs/api.mdx`.
+
+Route groups like `(public)/` are ignored, since they don't change the URL. A missing route file prints as `missing src/app/<path>`; a missing content file prints as `missing content/<path>`.
+
+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 +257,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 +341,56 @@ 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. |
+
+### docs
+
+No runtime imports.
+
+| Export | What it does |
+| --- | --- |
+| `CONTENT_SECTIONS`, `ContentSection` | The sections a site can have, in display order: `"docs"`, `"guides"`, `"legal"`. |
+| `SECTION_LABELS` | The nav label for each section, like "Guides". |
+| `defineContent(input)` | Validates and fills in a `Content`: `sections` lists only the non-empty ones, in `CONTENT_SECTIONS` order; `entries` and `extra` hold every section (empty arrays for the ones left out). Throws naming the section and slug (or extra href) for a bad slug (lowercase words, single hyphens), a duplicate slug or extra href, a `lastUpdated` that isn't a real `YYYY-MM-DD` date, or a blank title. |
+| `ContentEntry`, `HowToStep` | A markdown-backed page: `slug`, `title`, `navTitle?`, `description`, `lastUpdated` (`YYYY-MM-DD`), `howTo?` (numbered steps). |
+| `ExtraEntry` | An app-made page shown in a section's nav and search, like bb's tag pages: `href`, `title`, `navTitle?`, `description`, `group`, `badge?`, `lastUpdated?`, `markdownHref?`. |
+| `contentPath(section, slug)`, `markdownPath(section, slug)` | `/section/slug` and `/section/slug.md`. |
+| `findEntry(content, section, slug)` | The matching `ContentEntry`, or undefined. |
+| `contentParams(content, section)` | `{ slug }[]` for a dynamic route's `generateStaticParams`. |
+| `mdxToMarkdown(source, { title, siteUrl, transforms? })` | Converts bb-flavored MDX to plain Markdown, outside fenced code blocks only: CRLF/CR become LF (`transforms` run first, on the whole source); top-level `import`/`export` lines and an `export const x = {` block are dropped; `<Callout type="..." title="...">body</Callout>` becomes a blockquote (`> **Type:** body`, type missing means "Note"); other capitalized JSX tags are removed (text between them stays, lowercase HTML tags stay); a link or image target starting with a single `/` becomes absolute with `siteUrl`; `title` is prepended as a `# ` heading when the first non-blank line isn't one; runs of 3+ blank lines collapse to 2, and the result ends with exactly one newline. |
+| `contentLlmsTxt({ site, title, summary, notes?, content, api? })` | The llms.txt body: sections in order Docs, Guides, API, Legal. Each entry links to its absolute `.md` URL with its description as the note; an extra links to `markdownHref` when set, else `href`. An empty section (no entries, no extras, no `api` links) is left out. |
+| `contentLlmsFull({ site, title, summary?, content, read, before?, after? })` | The llms-full.txt body: `before`, then every registry entry in section order (title, its absolute page URL, and `read(section, slug)`'s Markdown with its own leading `# ` heading stripped, since `llmsFull` writes the part title as the H1), then `after`. `read` is usually `readContentMarkdown` from `docs/files`. |
+| `contentSitemap(content)` | A `SitemapRecord[]` for `seo`'s `sitemapEntries`: one non-empty section's index path (like `/docs`, `lastModified` set to the newest `lastUpdated` among its entries and extras, omitted when none have one), then each entry with its own `lastUpdated`, then each extra with its own `lastUpdated` when set. |
+| `contentRewrites()` | The one Next.js rewrite rule that mirrors a content page's `.md` URL (`/docs/x.md`, `/guides/x.md`, `/legal/x.md`) to its route handler (`/docs/x/md`, ...). Pure, takes no registry. |
+
+### docs/files
+
+`node:fs`. Markdown source for an entry lives at `<root>/content/<section>/<slug>.mdx`.
+
+| Export | What it does |
+| --- | --- |
+| `readContentMarkdown(content, section, slug, { root?, siteUrl, transforms? })` | Reads a registered entry's markdown file and converts it with `mdxToMarkdown` (using the entry's `title`). `root` defaults to `process.cwd()`. Returns null for an unregistered slug; rejects (ENOENT) when the slug is registered but its file is missing. |
+| `contentFileDrift(content, { root? })` | `{ missingFiles, unregistered }`: `missingFiles` lists registered entries with no file on disk (like `"guides/x.mdx"`); `unregistered` lists `.mdx` files on disk with no registry entry. `root` defaults to `process.cwd()`. |
+
 ## 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:
@@ -269,7 +409,7 @@ For pools.haruhime.moe, `createMongo` runs `onConnect` (the privilege check, ind
 
 ## 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`, `next/navigation.js` and `@haruhimemoe/ui`. `server` loads `node:crypto` for machine auth. `seo` loads nothing at runtime (Next's types only), so it runs anywhere.
+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`, `next/navigation.js` and `@haruhimemoe/ui`. `server` loads `node:crypto` for machine auth. `seo` and `docs` load nothing at runtime (Next's types only, or nothing), so they run anywhere; `docs/files` loads `node:fs` and stays server only.
 
 ## License
 

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;