@kaperkunde/auth 0.1.1 → 0.2.1

package/README.md

@@ -6,6 +6,7 @@ connector, plus the rules and words the sign-in forms share.
 | Import                    | What it gives                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@kaperkunde/auth/preset` | `mcpAuthPreset({ urls, scopes })` to spread into `betterAuth({…})`: jwt (its `/token` closed, no set-auth-jwt header), mcp (code + refresh only, open registration, an hour's access token), cimd, and the production rate limit with room for the OAuth endpoints. `discoveryRoute(auth.handler)` for the root `.well-known` routes                                                                                                                                            |
+| `@kaperkunde/auth/forms`  | The form helpers alone, safe in a client component: `validatePassword`, `withResetPasswordEmail`, `authErrorMessage`, `oauthRedirectFrom`, `RESET_PASSWORD_EMAIL_PARAM`, `UNEXPECTED_ERROR`                                                                                                                                                                                                                                                                                     |
 | `@kaperkunde/auth`        | `mcpUrls` (issuer, resource, JWKS over loopback, resource metadata); `parseScopeList`, `effectiveScopes` (token ∩ live consent, null once disconnected); `bearerChallenge`, `mcpAuthError`, `withCors`, `bearerTokenFrom`, `calledToolNames`; `hashOpaqueToken` + `opaqueTokenClaims` (refuses revoked, expired, DPoP-bound, disabled-client, expired-session and other-resource tokens); `validatePassword`, `withResetPasswordEmail`, `authErrorMessage`, `oauthRedirectFrom` |
 
 The app keeps what is its own: the database adapter, its hooks, the scope

package/dist/forms.d.mts

@@ -0,0 +1,29 @@
+/** One password rule for sign-up, reset and change-password forms. */
+export declare function validatePassword(password: string, verify: string, { minLength }?: {
+  minLength?: number;
+}): string | null;
+/** Query parameter carrying the account's address on the password-reset link. */
+export declare const RESET_PASSWORD_EMAIL_PARAM = "email";
+/**
+ * Adds the account's address to the callback on a Better Auth reset link,
+ * so the form can sign the person in once the new password is set. The
+ * address comes from the user row Better Auth resolved, never from whoever
+ * asked, so a caller's redirectTo cannot put someone else's address on it.
+ */
+export declare function withResetPasswordEmail(url: string, email: string): string;
+export declare const UNEXPECTED_ERROR = "Something went wrong on our side. Try again in a minute.";
+type AuthError = {
+  code?: string;
+  message?: string;
+  status?: number;
+  error?: string;
+};
+/**
+ * Better Auth answers with codes; people read sentences. A server error is
+ * always the unexpected-error sentence, never Better Auth's own message.
+ * `overrides` lets an app word a code its own way.
+ */
+export declare function authErrorMessage(error: AuthError | null | undefined, fallback: string, overrides?: Readonly<Record<string, string>>): string;
+/** Where an authorization continues after signing in for a connecting app, if it does. */
+export declare function oauthRedirectFrom(data: unknown): string | null;
+export {};

package/dist/forms.mjs

@@ -0,0 +1,62 @@
+// src/forms.ts
+/** One password rule for sign-up, reset and change-password forms. */
+function validatePassword(password, verify, { minLength = 8 } = {}) {
+	if (password.length < minLength) return `Password must be at least ${minLength} characters.`;
+	if (password !== verify) return "Passwords do not match.";
+	return null;
+}
+/** Query parameter carrying the account's address on the password-reset link. */
+const RESET_PASSWORD_EMAIL_PARAM = "email";
+/**
+* Adds the account's address to the callback on a Better Auth reset link,
+* so the form can sign the person in once the new password is set. The
+* address comes from the user row Better Auth resolved, never from whoever
+* asked, so a caller's redirectTo cannot put someone else's address on it.
+*/
+function withResetPasswordEmail(url, email) {
+	try {
+		const link = new URL(url);
+		const callback = new URL(link.searchParams.get("callbackURL") || "/reset-password", link.origin);
+		callback.searchParams.set(RESET_PASSWORD_EMAIL_PARAM, email);
+		link.searchParams.set("callbackURL", `${callback.pathname}${callback.search}`);
+		return link.toString();
+	} catch {
+		return url;
+	}
+}
+const UNEXPECTED_ERROR = "Something went wrong on our side. Try again in a minute.";
+const MESSAGES = {
+	INVALID_EMAIL_OR_PASSWORD: "Wrong email or password.",
+	USER_ALREADY_EXISTS: "An account with this email already exists. Sign in instead.",
+	USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL: "An account with this email already exists. Sign in instead.",
+	PASSWORD_TOO_SHORT: "Use at least 8 characters for your password.",
+	PASSWORD_TOO_LONG: "That password is too long. Use at most 128 characters.",
+	INVALID_EMAIL: "Enter a valid email address.",
+	INVALID_PASSWORD: "Your current password is wrong.",
+	CREDENTIAL_ACCOUNT_NOT_FOUND: "This account has no password to change.",
+	INVALID_TOKEN: "This link has expired or was already used. Ask for a new one.",
+	EMAIL_NOT_VERIFIED: "Confirm your email address first: we sent you a link."
+};
+/**
+* Better Auth answers with codes; people read sentences. A server error is
+* always the unexpected-error sentence, never Better Auth's own message.
+* `overrides` lets an app word a code its own way.
+*/
+function authErrorMessage(error, fallback, overrides = {}) {
+	if (!error) return fallback;
+	if (error.status === 429) return "Too many attempts. Wait a minute and try again.";
+	if (error.status !== void 0 && error.status >= 500) return UNEXPECTED_ERROR;
+	const code = error.code ?? "";
+	if (overrides[code]) return overrides[code];
+	if (MESSAGES[code]) return MESSAGES[code];
+	if (error.error === "invalid_signature" || code === "INVALID_SIGNATURE") return "This request to connect an app has expired. Go back to the app and start connecting again.";
+	return fallback;
+}
+/** Where an authorization continues after signing in for a connecting app, if it does. */
+function oauthRedirectFrom(data) {
+	if (!data || typeof data !== "object") return null;
+	const record = data;
+	const url = typeof record.url === "string" ? record.url : record.redirect_uri;
+	return typeof url === "string" && (record.redirect === true || record.redirect_uri) ? url : null;
+}
+export { RESET_PASSWORD_EMAIL_PARAM, UNEXPECTED_ERROR, authErrorMessage, oauthRedirectFrom, validatePassword, withResetPasswordEmail };

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import { n as mcpUrls, t as McpUrls } from "./urls-Cbyx1eIp.mjs";
+import { RESET_PASSWORD_EMAIL_PARAM, UNEXPECTED_ERROR, authErrorMessage, oauthRedirectFrom, validatePassword, withResetPasswordEmail } from "./forms.mjs";
 /** The headers an MCP route answers with, for clients in the browser too. */
 export declare const MCP_CORS_HEADERS: Readonly<Record<string, string>>;
 /** A response with CORS headers set over its own. */
@@ -28,34 +29,6 @@ export declare function mcpAuthError({ status, message, challenge }: {
 export declare function bearerTokenFrom(request: Request): string | null;
 /** Tool names a JSON-RPC body calls (one request or a batch), for scope checks and rate buckets. */
 export declare function calledToolNames(request: Request): Promise<string[]>;
-/** One password rule for sign-up, reset and change-password forms. */
-export declare function validatePassword(password: string, verify: string, { minLength }?: {
-  minLength?: number;
-}): string | null;
-/** Query parameter carrying the account's address on the password-reset link. */
-export declare const RESET_PASSWORD_EMAIL_PARAM = "email";
-/**
- * Adds the account's address to the callback on a Better Auth reset link,
- * so the form can sign the person in once the new password is set. The
- * address comes from the user row Better Auth resolved, never from whoever
- * asked, so a caller's redirectTo cannot put someone else's address on it.
- */
-export declare function withResetPasswordEmail(url: string, email: string): string;
-export declare const UNEXPECTED_ERROR = "Something went wrong on our side. Try again in a minute.";
-type AuthError = {
-  code?: string;
-  message?: string;
-  status?: number;
-  error?: string;
-};
-/**
- * Better Auth answers with codes; people read sentences. A server error is
- * always the unexpected-error sentence, never Better Auth's own message.
- * `overrides` lets an app word a code its own way.
- */
-export declare function authErrorMessage(error: AuthError | null | undefined, fallback: string, overrides?: Readonly<Record<string, string>>): string;
-/** Where an authorization continues after signing in for a connecting app, if it does. */
-export declare function oauthRedirectFrom(data: unknown): string | null;
 /**
  * Access tokens for clients that did not name the resource they wanted (RFC
  * 8707). The authorization server issues an opaque token then, rather than a
@@ -96,4 +69,4 @@ export declare function parseScopeList(value: unknown): string[];
  * (`consented` null), and intersecting makes a downgrade take effect too.
  */
 export declare function effectiveScopes(tokenScopes: unknown, consented: unknown | null): string[] | null;
-export { type McpUrls, type OpaqueTokenRow, mcpUrls };
+export { type McpUrls, type OpaqueTokenRow, RESET_PASSWORD_EMAIL_PARAM, UNEXPECTED_ERROR, authErrorMessage, mcpUrls, oauthRedirectFrom, validatePassword, withResetPasswordEmail };

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { RESET_PASSWORD_EMAIL_PARAM, UNEXPECTED_ERROR, authErrorMessage, oauthRedirectFrom, validatePassword, withResetPasswordEmail } from "./forms.mjs";
 import { createHash } from "node:crypto";
 // src/challenge.ts
 /** The headers an MCP route answers with, for clients in the browser too. */
@@ -72,67 +73,6 @@ async function calledToolNames(request) {
 		return m?.method === "tools/call" && typeof m.params?.name === "string" ? [m.params.name] : [];
 	});
 }
-// src/forms.ts
-/** One password rule for sign-up, reset and change-password forms. */
-function validatePassword(password, verify, { minLength = 8 } = {}) {
-	if (password.length < minLength) return `Password must be at least ${minLength} characters.`;
-	if (password !== verify) return "Passwords do not match.";
-	return null;
-}
-/** Query parameter carrying the account's address on the password-reset link. */
-const RESET_PASSWORD_EMAIL_PARAM = "email";
-/**
-* Adds the account's address to the callback on a Better Auth reset link,
-* so the form can sign the person in once the new password is set. The
-* address comes from the user row Better Auth resolved, never from whoever
-* asked, so a caller's redirectTo cannot put someone else's address on it.
-*/
-function withResetPasswordEmail(url, email) {
-	try {
-		const link = new URL(url);
-		const callback = new URL(link.searchParams.get("callbackURL") || "/reset-password", link.origin);
-		callback.searchParams.set(RESET_PASSWORD_EMAIL_PARAM, email);
-		link.searchParams.set("callbackURL", `${callback.pathname}${callback.search}`);
-		return link.toString();
-	} catch {
-		return url;
-	}
-}
-const UNEXPECTED_ERROR = "Something went wrong on our side. Try again in a minute.";
-const MESSAGES = {
-	INVALID_EMAIL_OR_PASSWORD: "Wrong email or password.",
-	USER_ALREADY_EXISTS: "An account with this email already exists. Sign in instead.",
-	USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL: "An account with this email already exists. Sign in instead.",
-	PASSWORD_TOO_SHORT: "Use at least 8 characters for your password.",
-	PASSWORD_TOO_LONG: "That password is too long. Use at most 128 characters.",
-	INVALID_EMAIL: "Enter a valid email address.",
-	INVALID_PASSWORD: "Your current password is wrong.",
-	CREDENTIAL_ACCOUNT_NOT_FOUND: "This account has no password to change.",
-	INVALID_TOKEN: "This link has expired or was already used. Ask for a new one.",
-	EMAIL_NOT_VERIFIED: "Confirm your email address first: we sent you a link."
-};
-/**
-* Better Auth answers with codes; people read sentences. A server error is
-* always the unexpected-error sentence, never Better Auth's own message.
-* `overrides` lets an app word a code its own way.
-*/
-function authErrorMessage(error, fallback, overrides = {}) {
-	if (!error) return fallback;
-	if (error.status === 429) return "Too many attempts. Wait a minute and try again.";
-	if (error.status !== void 0 && error.status >= 500) return UNEXPECTED_ERROR;
-	const code = error.code ?? "";
-	if (overrides[code]) return overrides[code];
-	if (MESSAGES[code]) return MESSAGES[code];
-	if (error.error === "invalid_signature" || code === "INVALID_SIGNATURE") return "This request to connect an app has expired. Go back to the app and start connecting again.";
-	return fallback;
-}
-/** Where an authorization continues after signing in for a connecting app, if it does. */
-function oauthRedirectFrom(data) {
-	if (!data || typeof data !== "object") return null;
-	const record = data;
-	const url = typeof record.url === "string" ? record.url : record.redirect_uri;
-	return typeof url === "string" && (record.redirect === true || record.redirect_uri) ? url : null;
-}
 // src/scopes.ts
 /**
 * Scopes as Better Auth stores them (an array, a space- or comma-separated

package/dist/preset.d.mts

@@ -1,4 +1,5 @@
 import { t as McpUrls } from "./urls-Cbyx1eIp.mjs";
+import { BetterAuthPlugin } from "better-auth";
 /**
  * The Better Auth options an app needs to be an OAuth 2.1 authorization
  * server for its MCP connector, as one object spread into `betterAuth({…})`:
@@ -24,7 +25,7 @@ export declare function mcpAuthPreset({ urls, scopes, loginPage, consentPage, re
   consentPage?: string;
   refreshDays?: number;
   rateLimited?: boolean;
-  extraPlugins?: readonly unknown[];
+  extraPlugins?: readonly BetterAuthPlugin[];
   disabledPaths?: readonly string[];
 }): {
   disabledPaths: string[];
@@ -44,7 +45,7 @@ export declare function mcpAuthPreset({ urls, scopes, loginPage, consentPage, re
       "/jwks": false;
     };
   };
-  plugins: unknown[];
+  plugins: BetterAuthPlugin[];
 };
 /**
  * Route handlers for the OAuth discovery documents at the site root. Better

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaperkunde/auth",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Better Auth as the OAuth 2.1 server for an MCP connector: the preset, discovery routes, scope and consent checks, challenges, opaque tokens, and the auth forms' rules and messages.",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,11 @@
       "import": "./dist/index.mjs",
       "default": "./dist/index.mjs"
     },
+    "./forms": {
+      "types": "./dist/forms.d.mts",
+      "import": "./dist/forms.mjs",
+      "default": "./dist/forms.mjs"
+    },
     "./preset": {
       "types": "./dist/preset.d.mts",
       "import": "./dist/preset.mjs",
@@ -52,7 +57,7 @@
     "provenance": true
   },
   "scripts": {
-    "build": "tsdown src/index.ts src/preset.ts --format esm --dts --clean",
+    "build": "tsdown src/index.ts src/preset.ts src/forms.ts --format esm --dts --clean",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   }
 }