@haruhimemoe/next-kit 0.1.0

package/dist/server/counter.js

@@ -0,0 +1,76 @@
+/**
+ * @file src/server/counter.ts
+ * @desc Fixed windows and the counter document rate limits and budgets share: one document per
+ *       scope, subject and window (`{scope}:{subject}:{windowStartSeconds}`), bumped with one
+ *       findOneAndUpdate upsert $inc, removed by the TTL index on expiresAt a minute after its
+ *       window ends. Before, each app computed the window three times (rate limits and two osu!
+ *       budget windows). counterTtlIndex is the index that removes them.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { isDuplicateKeyError } from "../mongo/duplicate.js";
+import { ttlIndex } from "../mongo/indexes.js";
+/** The collection both apps keep counters in. */
+export const RATE_LIMITS_COLLECTION = "rate_limits";
+/** MongoDB's TTL monitor runs about once a minute; the grace keeps a live window's counter. */
+export const COUNTER_GRACE_MS = 60_000;
+/**
+ * @function counterTtlIndex
+ * @param collection {string} the counters' collection (default RATE_LIMITS_COLLECTION)
+ * @returns {IndexSpec} the TTL index on expiresAt that removes spent counters (pass it to
+ *          ensureIndexes from @haruhimemoe/next-kit/mongo)
+ */
+export const counterTtlIndex = (collection = RATE_LIMITS_COLLECTION) => ttlIndex(collection, "expiresAt");
+/**
+ * @function windowFor
+ * @param rule {RateLimitRule} the limit
+ * @param nowMs {number} current time (ms)
+ * @returns {RateLimitWindow} the window holding nowMs; resetSeconds is 1 to windowSeconds
+ */
+export const windowFor = (rule, nowMs) => {
+    const size = rule.windowSeconds * 1000;
+    const start = Math.floor(nowMs / size) * size;
+    const end = start + size;
+    return {
+        start,
+        end,
+        resetSeconds: Math.ceil((end - nowMs) / 1000),
+        expiresAt: new Date(end + COUNTER_GRACE_MS),
+    };
+};
+/**
+ * @function rateLimitId
+ * @param rule {RateLimitRule} the limit
+ * @param subject {string} an IP subject, a user subject or a fixed one like "global"
+ * @param nowMs {number} current time (ms)
+ * @returns {string} "{scope}:{subject}:{windowStartSeconds}"
+ */
+export const rateLimitId = (rule, subject, nowMs) => `${rule.scope}:${subject}:${windowFor(rule, nowMs).start / 1000}`;
+/**
+ * @function counters
+ * @param store {CounterStore} database and collection
+ * @returns {Promise<Collection<CounterDoc>>} the counter collection
+ */
+export const counters = async ({ db, collection = RATE_LIMITS_COLLECTION, }) => (await db()).collection(collection);
+/**
+ * @function bumpCounter
+ * @param store {CounterStore} database and collection
+ * @param rule {RateLimitRule} the limit
+ * @param subject {string} who is counted
+ * @param nowMs {number} current time (ms)
+ * @param cost {number} how much to add
+ * @returns {Promise<number>} the count after this bump
+ * @throws when the counter can't be written
+ */
+export const bumpCounter = async (store, rule, subject, nowMs, cost) => {
+    const collection = await counters(store);
+    const bump = () => collection.findOneAndUpdate({ _id: rateLimitId(rule, subject, nowMs) }, { $inc: { count: cost }, $setOnInsert: { expiresAt: windowFor(rule, nowMs).expiresAt } }, { upsert: true, returnDocument: "after" });
+    // Two first hits in a window can race to insert; the loser's retry finds the document.
+    const doc = await bump().catch((error) => {
+        if (!isDuplicateKeyError(error))
+            throw error;
+        return bump();
+    });
+    return doc?.count ?? cost;
+};

package/dist/server/cross-site.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @file src/server/cross-site.ts
+ * @desc The same-origin guard every cookie-authenticated write runs: a request whose Origin is
+ *       neither its own nor the site's, or whose Sec-Fetch-Site says cross-site or same-site (a
+ *       sibling *.haruhime.moe host is another site here), gets a 403. Moved from pools
+ *       (src/lib/api.ts); the site's URL and name come from the caller.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** refuseCrossSite's options. */
+export type CrossSiteOptions = {
+    /** The site's canonical URL; its origin is allowed besides the request's own. */
+    siteUrl: string;
+    /** The site's name, for the 403 message. */
+    siteTitle: string;
+};
+/**
+ * @function crossSiteMessage
+ * @param siteTitle {string} the site's name
+ * @returns {string} the 403 message refuseCrossSite sends
+ */
+export declare const crossSiteMessage: (siteTitle: string) => string;
+/**
+ * @function refuseCrossSite
+ * @param request {Request} a cookie-authenticated mutation
+ * @param options {CrossSiteOptions} the site's URL and name
+ * @returns {Response | null} 403 forbidden when Origin is present and isn't the request's own
+ *          origin or the site's, or when Sec-Fetch-Site says cross-site or same-site; otherwise
+ *          null
+ */
+export declare const refuseCrossSite: (request: Request, { siteUrl, siteTitle }: CrossSiteOptions) => Response | null;

package/dist/server/cross-site.js

@@ -0,0 +1,36 @@
+/**
+ * @file src/server/cross-site.ts
+ * @desc The same-origin guard every cookie-authenticated write runs: a request whose Origin is
+ *       neither its own nor the site's, or whose Sec-Fetch-Site says cross-site or same-site (a
+ *       sibling *.haruhime.moe host is another site here), gets a 403. Moved from pools
+ *       (src/lib/api.ts); the site's URL and name come from the caller.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { jsonError } from "./errors.js";
+/** Sec-Fetch-Site values that mean another site (or a sibling host) sent the request. */
+const FOREIGN_FETCH_SITES = new Set(["cross-site", "same-site"]);
+/**
+ * @function crossSiteMessage
+ * @param siteTitle {string} the site's name
+ * @returns {string} the 403 message refuseCrossSite sends
+ */
+export const crossSiteMessage = (siteTitle) => `This request has to come from ${siteTitle} itself.`;
+/**
+ * @function refuseCrossSite
+ * @param request {Request} a cookie-authenticated mutation
+ * @param options {CrossSiteOptions} the site's URL and name
+ * @returns {Response | null} 403 forbidden when Origin is present and isn't the request's own
+ *          origin or the site's, or when Sec-Fetch-Site says cross-site or same-site; otherwise
+ *          null
+ */
+export const refuseCrossSite = (request, { siteUrl, siteTitle }) => {
+    const origin = request.headers.get("origin");
+    const ownOrigin = new URL(request.url).origin;
+    const siteOrigin = new URL(siteUrl).origin;
+    const foreignOrigin = origin !== null && origin !== ownOrigin && origin !== siteOrigin;
+    const fetchSite = request.headers.get("sec-fetch-site");
+    const foreignFetch = fetchSite !== null && FOREIGN_FETCH_SITES.has(fetchSite);
+    return foreignOrigin || foreignFetch ? jsonError(403, crossSiteMessage(siteTitle)) : null;
+};

package/dist/server/errors.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @file src/server/errors.ts
+ * @desc The JSON error answer every route sends ({ error: { code, message } }), the stable code
+ *       per status, and two small header helpers (no-store, set several headers at once).
+ *       Moved from packs and pools (src/lib/api.ts, src/lib/rate-limit.ts).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** Stable machine codes per status. Messages are for people and may change; codes don't. */
+export declare const ERROR_CODES: Readonly<{
+    readonly 400: "bad_request";
+    readonly 401: "unauthorized";
+    readonly 403: "forbidden";
+    readonly 404: "not_found";
+    readonly 409: "conflict";
+    readonly 413: "too_large";
+    readonly 415: "unsupported_media_type";
+    readonly 429: "rate_limited";
+    readonly 500: "internal_error";
+    readonly 502: "upstream_error";
+    readonly 503: "unavailable";
+}>;
+/** The body of every error answer. */
+export type ApiErrorBody = {
+    error: {
+        code: string;
+        message: string;
+    };
+};
+/**
+ * @function errorCodeFor
+ * @param status {number} HTTP status
+ * @returns {string} its code from ERROR_CODES; otherwise "internal_error" for 5xx, "bad_request"
+ */
+export declare const errorCodeFor: (status: number) => string;
+/**
+ * @function jsonError
+ * @param status {number} HTTP status
+ * @param message {string} shown to the person
+ * @param code {string} machine code (default: from the status)
+ * @returns {Response} `{ error: { code, message } }` JSON
+ */
+export declare const jsonError: (status: number, message: string, code?: string) => Response;
+/**
+ * @function withHeaders
+ * @param response {Response} a response with mutable headers
+ * @param headers {Record<string, string>} headers to set
+ * @returns {Response} the same response
+ */
+export declare const withHeaders: (response: Response, headers: Record<string, string>) => Response;
+/**
+ * @function noStore
+ * @param response {Response} a response with mutable headers
+ * @returns {Response} the same response, never cached
+ */
+export declare const noStore: (response: Response) => Response;

package/dist/server/errors.js

@@ -0,0 +1,55 @@
+/**
+ * @file src/server/errors.ts
+ * @desc The JSON error answer every route sends ({ error: { code, message } }), the stable code
+ *       per status, and two small header helpers (no-store, set several headers at once).
+ *       Moved from packs and pools (src/lib/api.ts, src/lib/rate-limit.ts).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** Stable machine codes per status. Messages are for people and may change; codes don't. */
+export const ERROR_CODES = Object.freeze({
+    400: "bad_request",
+    401: "unauthorized",
+    403: "forbidden",
+    404: "not_found",
+    409: "conflict",
+    413: "too_large",
+    415: "unsupported_media_type",
+    429: "rate_limited",
+    500: "internal_error",
+    502: "upstream_error",
+    503: "unavailable",
+});
+/**
+ * @function errorCodeFor
+ * @param status {number} HTTP status
+ * @returns {string} its code from ERROR_CODES; otherwise "internal_error" for 5xx, "bad_request"
+ */
+export const errorCodeFor = (status) => ERROR_CODES[status] ??
+    (status >= 500 ? "internal_error" : "bad_request");
+/**
+ * @function jsonError
+ * @param status {number} HTTP status
+ * @param message {string} shown to the person
+ * @param code {string} machine code (default: from the status)
+ * @returns {Response} `{ error: { code, message } }` JSON
+ */
+export const jsonError = (status, message, code = errorCodeFor(status)) => Response.json({ error: { code, message } }, { status });
+/**
+ * @function withHeaders
+ * @param response {Response} a response with mutable headers
+ * @param headers {Record<string, string>} headers to set
+ * @returns {Response} the same response
+ */
+export const withHeaders = (response, headers) => {
+    for (const [name, value] of Object.entries(headers))
+        response.headers.set(name, value);
+    return response;
+};
+/**
+ * @function noStore
+ * @param response {Response} a response with mutable headers
+ * @returns {Response} the same response, never cached
+ */
+export const noStore = (response) => withHeaders(response, { "Cache-Control": "no-store" });

package/dist/server/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file src/server/index.ts
+ * @desc @haruhimemoe/next-kit/server: route handler helpers. JSON errors and headers, the body
+ *       parser and id lists, the cross-site guard, the client IP and its rate-limit subject,
+ *       fixed-window rate limits and call budgets in MongoDB, bearer machine auth, where to go
+ *       after sign-in, and security.txt. Server only: machine-auth loads node:crypto.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+export { MAX_BODY_BYTES, MAX_ID, type ParsedBody, type ParseIdListOptions, type ParseJsonBodyOptions, parseIdList, parseJsonBody, } from "./body.js";
+export { type Budget, type BudgetOptions, createBudget } from "./budget.js";
+export { clientIp, MAX_IP_LENGTH, rateLimitSubject } from "./client-ip.js";
+export { COUNTER_GRACE_MS, type CounterDoc, type CounterStore, counterTtlIndex, RATE_LIMITS_COLLECTION, type RateLimitRule, type RateLimitWindow, rateLimitId, windowFor, } from "./counter.js";
+export { type CrossSiteOptions, crossSiteMessage, refuseCrossSite } from "./cross-site.js";
+export { type ApiErrorBody, ERROR_CODES, errorCodeFor, jsonError, noStore, withHeaders, } from "./errors.js";
+export { type BearerFailureLimit, type BearerGuardOptions, bearerToken, refuseWithoutBearer, sameSecret, } from "./machine-auth.js";
+export { createRateLimiter, type RateLimiter, type RateLimiterOptions, type RateLimitResult, rateLimitHeaders, retryText, tooManyRequests, unlimited, userSubject, } from "./rate-limit.js";
+export { DEFAULT_SIGN_IN_PATH, MAX_NEXT_LENGTH, type SafeNextOptions, safeNextPath, signInHref, } from "./safe-next.js";
+export { buildSecurityTxt, SECURITY_TXT_LIFETIME_DAYS, SECURITY_TXT_PATH, type SecurityTxtOptions, } from "./security-txt.js";

package/dist/server/index.js

@@ -0,0 +1,20 @@
+/**
+ * @file src/server/index.ts
+ * @desc @haruhimemoe/next-kit/server: route handler helpers. JSON errors and headers, the body
+ *       parser and id lists, the cross-site guard, the client IP and its rate-limit subject,
+ *       fixed-window rate limits and call budgets in MongoDB, bearer machine auth, where to go
+ *       after sign-in, and security.txt. Server only: machine-auth loads node:crypto.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+export { MAX_BODY_BYTES, MAX_ID, parseIdList, parseJsonBody, } from "./body.js";
+export { createBudget } from "./budget.js";
+export { clientIp, MAX_IP_LENGTH, rateLimitSubject } from "./client-ip.js";
+export { COUNTER_GRACE_MS, counterTtlIndex, RATE_LIMITS_COLLECTION, rateLimitId, windowFor, } from "./counter.js";
+export { crossSiteMessage, refuseCrossSite } from "./cross-site.js";
+export { ERROR_CODES, errorCodeFor, jsonError, noStore, withHeaders, } from "./errors.js";
+export { bearerToken, refuseWithoutBearer, sameSecret, } from "./machine-auth.js";
+export { createRateLimiter, rateLimitHeaders, retryText, tooManyRequests, unlimited, userSubject, } from "./rate-limit.js";
+export { DEFAULT_SIGN_IN_PATH, MAX_NEXT_LENGTH, safeNextPath, signInHref, } from "./safe-next.js";
+export { buildSecurityTxt, SECURITY_TXT_LIFETIME_DAYS, SECURITY_TXT_PATH, } from "./security-txt.js";

package/dist/server/machine-auth.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @file src/server/machine-auth.ts
+ * @desc Bearer secrets for machine-only routes (a cron job, another app's service calls), which
+ *       read no session or cookies. They fail closed: 503 not_configured while the secret isn't
+ *       set or is invalid (logged by name, never by value), 401 for a missing or wrong one. The
+ *       comparison hashes both sides with SHA-256 and compares the digests with timingSafeEqual,
+ *       so the time taken says nothing about the secret's length or content. The secret is
+ *       compared before any failure is counted, so the right one always gets through, even from
+ *       an IP past its failure limit. Moved from packs (src/lib/machine-auth.ts).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import type { RateLimitRule } from "./counter.js";
+import { type RateLimiter } from "./rate-limit.js";
+/**
+ * @function sameSecret
+ * @param given {string} what the request sent
+ * @param secret {string} the configured secret
+ * @returns {boolean} whether they're equal, compared as SHA-256 digests with timingSafeEqual
+ */
+export declare const sameSecret: (given: string, secret: string) => boolean;
+/**
+ * @function bearerToken
+ * @param headers {Headers} request headers
+ * @returns {string | null} what follows `Authorization: Bearer `, or null when there is none
+ */
+export declare const bearerToken: (headers: Headers) => string | null;
+/** Counting a caller's failures: the limiter and the rule (per IP subject). */
+export type BearerFailureLimit = {
+    limiter: Pick<RateLimiter, "hit">;
+    rule: RateLimitRule;
+};
+/** refuseWithoutBearer's options. */
+export type BearerGuardOptions = {
+    /** Reads the secret now; undefined while unset. An EnvError means set but invalid. */
+    secret: () => string | undefined;
+    /** Names the secret in the log line, like "cron" or "pools". */
+    label: string;
+    /** The 503 message while the secret isn't set up. */
+    notConfigured: string;
+    /** Counts a missing or wrong secret against the caller's IP: past the limit, 429 not 401. */
+    failures?: BearerFailureLimit;
+    /** Every refusal is no-store (default false). */
+    noStore?: boolean;
+};
+/**
+ * @function refuseWithoutBearer
+ * @param request {Request} the incoming request
+ * @param options {BearerGuardOptions} the secret, its label, the 503 message, failure counting
+ * @returns {Promise<Response | null>} null when the request carries `Authorization: Bearer
+ *          <secret>`, however often its IP failed; otherwise a 503 not_configured, a 401, or a
+ *          429 when failures are counted and that IP is past the limit
+ */
+export declare const refuseWithoutBearer: (request: Request, options: BearerGuardOptions) => Promise<Response | null>;

package/dist/server/machine-auth.js

@@ -0,0 +1,74 @@
+/**
+ * @file src/server/machine-auth.ts
+ * @desc Bearer secrets for machine-only routes (a cron job, another app's service calls), which
+ *       read no session or cookies. They fail closed: 503 not_configured while the secret isn't
+ *       set or is invalid (logged by name, never by value), 401 for a missing or wrong one. The
+ *       comparison hashes both sides with SHA-256 and compares the digests with timingSafeEqual,
+ *       so the time taken says nothing about the secret's length or content. The secret is
+ *       compared before any failure is counted, so the right one always gets through, even from
+ *       an IP past its failure limit. Moved from packs (src/lib/machine-auth.ts).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { createHash, timingSafeEqual } from "node:crypto";
+import { EnvError } from "../env/errors.js";
+import { clientIp, rateLimitSubject } from "./client-ip.js";
+import { jsonError, noStore } from "./errors.js";
+import { tooManyRequests } from "./rate-limit.js";
+const BEARER = "Bearer ";
+const digest = (value) => createHash("sha256").update(value, "utf8").digest();
+/**
+ * @function sameSecret
+ * @param given {string} what the request sent
+ * @param secret {string} the configured secret
+ * @returns {boolean} whether they're equal, compared as SHA-256 digests with timingSafeEqual
+ */
+export const sameSecret = (given, secret) => timingSafeEqual(digest(given), digest(secret));
+/**
+ * @function bearerToken
+ * @param headers {Headers} request headers
+ * @returns {string | null} what follows `Authorization: Bearer `, or null when there is none
+ */
+export const bearerToken = (headers) => {
+    const header = headers.get("authorization") ?? "";
+    return header.startsWith(BEARER) && header.length > BEARER.length
+        ? header.slice(BEARER.length)
+        : null;
+};
+/** The secret, or undefined when it's unset or invalid (logged by name, never by value). */
+const configured = (read, label) => {
+    try {
+        return read();
+    }
+    catch (error) {
+        if (!(error instanceof EnvError))
+            throw error;
+        console.error(`[${label}] ${error.message}`);
+        return undefined;
+    }
+};
+/**
+ * @function refuseWithoutBearer
+ * @param request {Request} the incoming request
+ * @param options {BearerGuardOptions} the secret, its label, the 503 message, failure counting
+ * @returns {Promise<Response | null>} null when the request carries `Authorization: Bearer
+ *          <secret>`, however often its IP failed; otherwise a 503 not_configured, a 401, or a
+ *          429 when failures are counted and that IP is past the limit
+ */
+export const refuseWithoutBearer = async (request, options) => {
+    const finish = (response) => (options.noStore ? noStore(response) : response);
+    const secret = configured(options.secret, options.label);
+    if (!secret)
+        return finish(jsonError(503, options.notConfigured, "not_configured"));
+    const given = bearerToken(request.headers);
+    if (given !== null && sameSecret(given, secret))
+        return null;
+    if (options.failures) {
+        const { limiter, rule } = options.failures;
+        const result = await limiter.hit(rule, rateLimitSubject(clientIp(request.headers)));
+        if (!result.allowed)
+            return finish(tooManyRequests(result));
+    }
+    return finish(jsonError(401, "Not authorized."));
+};

package/dist/server/rate-limit.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @file src/server/rate-limit.ts
+ * @desc Fixed-window rate limits in MongoDB (src/server/counter.ts has the document). A hit can
+ *       cost more than one (a call carrying several ops counts each). Subjects are IP subjects
+ *       (client-ip.ts) or, for signed-in users, userSubject(). Counting fails open: if the write
+ *       fails, the request is allowed and the error logged. Moved from pools
+ *       (src/lib/rate-limit.ts, with db injection and cost) plus packs' deleteRateLimitsFor as
+ *       deleteSubject.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { type CounterStore, type RateLimitRule } from "./counter.js";
+/** One counted hit. */
+export type RateLimitResult = {
+    allowed: boolean;
+    limit: number;
+    remaining: number;
+    resetSeconds: number;
+};
+/**
+ * @function rateLimitHeaders
+ * @param result {RateLimitResult} a counted hit
+ * @returns {Record<string, string>} RateLimit-Limit/Remaining/Reset, plus Retry-After when refused
+ */
+export declare const rateLimitHeaders: (result: RateLimitResult) => Record<string, string>;
+/**
+ * @function retryText
+ * @param seconds {number} wait time
+ * @returns {string} "45 seconds", "1 minute", "30 minutes"
+ */
+export declare const retryText: (seconds: number) => string;
+/**
+ * @function tooManyRequests
+ * @param result {RateLimitResult} a refused hit
+ * @returns {Response} 429 rate_limited with every rate-limit header
+ */
+export declare const tooManyRequests: (result: RateLimitResult) => Response;
+/**
+ * @function userSubject
+ * @param user {{ osuId: number }} a signed-in user
+ * @returns {string} "osu:<osuId>", their subject for per-user limits and the osu! budget: it
+ *          outlives their user id, which a deleted and re-made account doesn't keep
+ */
+export declare const userSubject: (user: {
+    osuId: number;
+}) => string;
+/**
+ * @function unlimited
+ * @param rule {RateLimitRule} the limit
+ * @param nowMs {number} current time (ms)
+ * @returns {RateLimitResult} nothing counted: the full limit left (a hit that couldn't be counted,
+ *          or a response that must carry headers before anything was counted)
+ */
+export declare const unlimited: (rule: RateLimitRule, nowMs: number) => RateLimitResult;
+/** createRateLimiter's options: where counters live, and a clock for tests. */
+export type RateLimiterOptions = CounterStore & {
+    now?: () => number;
+};
+/** What createRateLimiter returns. */
+export type RateLimiter = {
+    /** Counts a hit (cost 1 unless given); allowed while count <= limit, and when counting fails. */
+    hit: (rule: RateLimitRule, subject: string, cost?: number) => Promise<RateLimitResult>;
+    /** Counts a hit; a no-store 429 when it's over the limit, otherwise null. */
+    refuseOverLimit: (rule: RateLimitRule, subject: string, cost?: number) => Promise<Response | null>;
+    /** Removes a subject's counters under these rules (account deletion); resolves to how many. */
+    deleteSubject: (rules: readonly RateLimitRule[], subject: string) => Promise<number>;
+};
+/**
+ * @function createRateLimiter
+ * @param options {RateLimiterOptions} the database (resolved per call), the collection (default
+ *        rate_limits) and a clock (default Date.now)
+ * @returns {RateLimiter} hit, refuseOverLimit and deleteSubject over those counters
+ */
+export declare const createRateLimiter: ({ now, ...store }: RateLimiterOptions) => RateLimiter;

package/dist/server/rate-limit.js

@@ -0,0 +1,101 @@
+/**
+ * @file src/server/rate-limit.ts
+ * @desc Fixed-window rate limits in MongoDB (src/server/counter.ts has the document). A hit can
+ *       cost more than one (a call carrying several ops counts each). Subjects are IP subjects
+ *       (client-ip.ts) or, for signed-in users, userSubject(). Counting fails open: if the write
+ *       fails, the request is allowed and the error logged. Moved from pools
+ *       (src/lib/rate-limit.ts, with db injection and cost) plus packs' deleteRateLimitsFor as
+ *       deleteSubject.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { bumpCounter, counters, windowFor, } from "./counter.js";
+import { jsonError, noStore, withHeaders } from "./errors.js";
+/**
+ * @function rateLimitHeaders
+ * @param result {RateLimitResult} a counted hit
+ * @returns {Record<string, string>} RateLimit-Limit/Remaining/Reset, plus Retry-After when refused
+ */
+export const rateLimitHeaders = (result) => ({
+    "RateLimit-Limit": String(result.limit),
+    "RateLimit-Remaining": String(result.remaining),
+    "RateLimit-Reset": String(result.resetSeconds),
+    ...(result.allowed ? {} : { "Retry-After": String(result.resetSeconds) }),
+});
+/**
+ * @function retryText
+ * @param seconds {number} wait time
+ * @returns {string} "45 seconds", "1 minute", "30 minutes"
+ */
+export const retryText = (seconds) => {
+    if (seconds < 60)
+        return `${seconds} second${seconds === 1 ? "" : "s"}`;
+    const minutes = Math.ceil(seconds / 60);
+    return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+};
+/**
+ * @function tooManyRequests
+ * @param result {RateLimitResult} a refused hit
+ * @returns {Response} 429 rate_limited with every rate-limit header
+ */
+export const tooManyRequests = (result) => withHeaders(jsonError(429, `Too many requests. Try again in ${retryText(result.resetSeconds)}.`), rateLimitHeaders(result));
+/**
+ * @function userSubject
+ * @param user {{ osuId: number }} a signed-in user
+ * @returns {string} "osu:<osuId>", their subject for per-user limits and the osu! budget: it
+ *          outlives their user id, which a deleted and re-made account doesn't keep
+ */
+export const userSubject = (user) => `osu:${user.osuId}`;
+/**
+ * @function unlimited
+ * @param rule {RateLimitRule} the limit
+ * @param nowMs {number} current time (ms)
+ * @returns {RateLimitResult} nothing counted: the full limit left (a hit that couldn't be counted,
+ *          or a response that must carry headers before anything was counted)
+ */
+export const unlimited = (rule, nowMs) => ({
+    allowed: true,
+    limit: rule.limit,
+    remaining: rule.limit,
+    resetSeconds: windowFor(rule, nowMs).resetSeconds,
+});
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * @function createRateLimiter
+ * @param options {RateLimiterOptions} the database (resolved per call), the collection (default
+ *        rate_limits) and a clock (default Date.now)
+ * @returns {RateLimiter} hit, refuseOverLimit and deleteSubject over those counters
+ */
+export const createRateLimiter = ({ now = Date.now, ...store }) => {
+    const hit = async (rule, subject, cost = 1) => {
+        const nowMs = now();
+        const base = unlimited(rule, nowMs);
+        try {
+            const count = await bumpCounter(store, rule, subject, nowMs, cost);
+            return { ...base, allowed: count <= rule.limit, remaining: Math.max(0, rule.limit - count) };
+        }
+        catch (error) {
+            console.error(`rate limit: couldn't count ${rule.scope}`, error);
+            return base;
+        }
+    };
+    return {
+        hit,
+        refuseOverLimit: async (rule, subject, cost = 1) => {
+            const result = await hit(rule, subject, cost);
+            return result.allowed ? null : noStore(tooManyRequests(result));
+        },
+        deleteSubject: async (rules, subject) => {
+            if (rules.length === 0)
+                return 0;
+            const scopes = rules.map((rule) => escapeRegExp(rule.scope)).join("|");
+            // Anchored on both ends: a subject can't widen the pattern to another scope or subject.
+            const pattern = `^(?:${scopes}):${escapeRegExp(subject)}:\\d+$`;
+            const { deletedCount } = await (await counters(store)).deleteMany({
+                _id: { $regex: pattern },
+            });
+            return deletedCount;
+        },
+    };
+};

package/dist/server/safe-next.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file src/server/safe-next.ts
+ * @desc Where to go after sign-in. Only same-site absolute paths pass; anything else (other
+ *       hosts, protocol-relative, backslashes, control characters, the sign-in page itself)
+ *       becomes the caller's fallback, a page every signed-in user can open. Browser-safe, so
+ *       @haruhimemoe/next-kit/auth-react exports it too. Moved from pools (src/utils/safe-next.ts);
+ *       packs' copy let /signin through.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** The sign-in page both sites use. */
+export declare const DEFAULT_SIGN_IN_PATH = "/signin";
+/** A `next` longer than this is refused unread. */
+export declare const MAX_NEXT_LENGTH = 512;
+/** safeNextPath's options. */
+export type SafeNextOptions = {
+    /** Where to go when `next` isn't safe (pools: /account, packs: /me). */
+    fallback: string;
+    /** The sign-in page, never a `next` (default DEFAULT_SIGN_IN_PATH). */
+    signInPath?: string;
+};
+/**
+ * @function safeNextPath
+ * @param raw {string | null | undefined} untrusted ?next= value
+ * @param options {SafeNextOptions} the fallback and the sign-in page
+ * @returns {string} a same-site path, or the fallback
+ */
+export declare const safeNextPath: (raw: string | null | undefined, { fallback, signInPath }: SafeNextOptions) => string;
+/**
+ * @function signInHref
+ * @param next {string} where to land after signing in
+ * @param signInPath {string} the sign-in page (default DEFAULT_SIGN_IN_PATH)
+ * @returns {string} the sign-in link carrying it, like /signin?next=%2Fpacks
+ */
+export declare const signInHref: (next: string, signInPath?: string) => string;