astro-altcha 0.4.0 → 0.5.0

package/README.md

@@ -1,12 +1,10 @@
 # `astro-altcha`
 
-![CI](https://codeberg.org/Trombach/astro-altcha/badges/workflows/ci.yml/badge.svg)
+![CI](https://codeberg.org/Trombach/astro-altcha/badges/workflows/ci.yml/badge.svg?branch=main)
 ![Release](https://codeberg.org/Trombach/astro-altcha/badges/release.svg)
 ![NPM Version](https://img.shields.io/npm/v/astro-altcha)
 
 
-> **Warning** Early development. Expect bugs and breaking changes.
-
 This is an [Astro integration](https://docs.astro.build/en/guides/integrations-guide/) that helps setting up altcha for Astro. It includes some optimizations and convenience features that should make it really easy to use altcha in your application. The main features are:
 
 - automatic middleware and challenge endpoint creation
@@ -67,16 +65,20 @@ export default defineConfig({
 
 ### Configuration
 
+All configuration options are optional. Default values are documented in this README and in the Typescript declarations for each option.
+
 #### Integration Options
 
 - `defaultName`: the global default name of the `altcha-widget` or the name of the cookie when using cookie mode. Must contain the string "astro-altcha" (this is so that the middleware can find the challenge solution). Defaults to `astro-altcha`
 - `challengePath`: the path under which the challenge creation API is made available. Defaults to `/api/altcha/challenge`
-- `challengeOptions`: can be used to change challange algorithm and parameters. See [challenge creation](https://altcha.org/docs/integration/server/#challenge-generation) for more info
+- `challengeOptions`: can be used to change challange algorithm and parameters. See [challenge creation](https://altcha.org/docs/integration/server/#challenge-generation) for more info. Defaults to `{ name: "astro-altcha", maxAge: 1200, path: "/", sameSite: "lax", secure: command !== "dev" }`
+- `verifyPath`: the path under wich the challenge verification API is made available. Defaults to `/api/altcha/verify`
 - `challengeExpiresAfterMinutes`: time in minutes for a challenge to remain valid. Defaults to 20m
 - `setCookie`: set a cookie instead of using an invisible form field in `AltchaForm`. Can be set to `true` to use default options: `{ name: "astro-altcha", maxAge: 1200, path: "/", sameSite: "lax", secure: command !== "dev" }`
-- `storage`: custom path for a storage module. See [Customize Storage](#customize-storage)
+- `storage`: custom path for a storage module. See [Customize Storage](#customize-storage). By default a `CappedMap` with `maxSize: 499` is used.
+- `features`: enable or disable middleware and endpoint injection. By default middleware and challenge endpoints are injected.
 
-#### Customize sSorage
+#### Customize Storage
 
 `astro-altcha` prevents replay attacks by always configuring a storage to remember already issued challenges. By default it uses `altcha-lib`'s `CappedMap`, but this can be changed by creating a `.ts/.js` file which default exports a custom storage implementation in `src/astro-altcha/storage.ts`. This path can be customized via the `storage` global option. For typings the library provides a `defineStorage` helper function.
 

package/dist/api/altcha-challenge.d.ts

@@ -1,4 +1,4 @@
 import { Algorithm, ResolvedAstroAltchaConfig } from "../types/index.js";
-import { DeriveKeyFunction } from "altcha/lib";
+import { DeriveKeyFunction } from "altcha/types";
 import { APIRoute } from "astro";
 export declare function createChallengeHandler(hmacSecret: string, { challengeOptions, challengeExpiresAfterMinutes, setCookie }: ResolvedAstroAltchaConfig<Algorithm>, deriveKeyFunc: DeriveKeyFunction): APIRoute;

package/dist/api/altcha-middleware.d.ts

@@ -1,28 +1,5 @@
 import { Algorithm, ResolvedAstroAltchaConfig } from "../types/index.js";
 import { DeriveKeyFunction } from "altcha-lib";
-import { z } from "astro/zod";
 import { MiddlewareHandler } from "astro";
 import { Store } from "altcha-lib/frameworks/types";
-declare const altchaPayloadSchema: z.ZodObject<{
-  challenge: z.ZodObject<{
-    parameters: z.ZodObject<{
-      algorithm: z.ZodString;
-      cost: z.ZodNumber;
-      keyLength: z.ZodNumber;
-      keyPrefix: z.ZodString;
-      keySignature: z.ZodOptional<z.ZodString>;
-      nonce: z.ZodString;
-      salt: z.ZodString;
-      expiresAt: z.ZodOptional<z.ZodInt>;
-    }, z.core.$loose>;
-    signature: z.ZodString;
-  }, z.core.$loose>;
-  solution: z.ZodObject<{
-    counter: z.ZodNumber;
-    derivedKey: z.ZodString;
-    time: z.ZodNumber;
-  }, z.core.$loose>;
-}, z.core.$loose>;
-export type AltchaPayload = z.infer<typeof altchaPayloadSchema>;
-export declare function createAltchaMiddlewareHandler(hmacSecret: string, deriveKeyFunc: DeriveKeyFunction, { setCookie }: ResolvedAstroAltchaConfig<Algorithm>, store: Store): MiddlewareHandler;
-export {};
+export declare function createAltchaMiddlewareHandler(hmacSecret: string, deriveKeyFunc: DeriveKeyFunction, { setCookie }: ResolvedAstroAltchaConfig<Algorithm>, store: Store): MiddlewareHandler;

package/dist/api/altcha-middleware.js

@@ -1,28 +1,9 @@
+import { altchaPayloadSchema } from "./payload-schema.js";
 import { deriveHmacKeySecret, verify } from "altcha-lib/frameworks/shared";
 import { z } from "astro/zod";
 import { base64ToString } from "uint8array-extras";
 
 // src/api/altcha-middleware.ts
-const altchaPayloadSchema = z.looseObject({
-	challenge: z.looseObject({
-		parameters: z.looseObject({
-			algorithm: z.string(),
-			cost: z.number(),
-			keyLength: z.number(),
-			keyPrefix: z.string(),
-			keySignature: z.string().optional(),
-			nonce: z.string(),
-			salt: z.string(),
-			expiresAt: z.int().optional()
-		}),
-		signature: z.string()
-	}),
-	solution: z.looseObject({
-		counter: z.number(),
-		derivedKey: z.string(),
-		time: z.number()
-	})
-});
 const keyRegexp = /.*astro-altcha.*/;
 function createAltchaMiddlewareHandler(hmacSecret, deriveKeyFunc, { setCookie }, store) {
 	return async (context, next) => {

package/dist/api/altcha-verify.d.ts

@@ -0,0 +1,4 @@
+import { DeriveKeyFunction } from "altcha-lib/types";
+import { APIRoute } from "astro";
+import { Store } from "altcha-lib/frameworks/types";
+export declare function createVerifyHandler(hmacSecret: string, deriveKeyFunc: DeriveKeyFunction, store: Store): APIRoute;

package/dist/api/altcha-verify.js

@@ -0,0 +1,23 @@
+import { altchaPayloadSchema } from "./payload-schema.js";
+import { deriveHmacKeySecret, verify } from "altcha-lib/frameworks/shared";
+import { z } from "astro/zod";
+
+// src/api/altcha-verify.ts
+function createVerifyHandler(hmacSecret, deriveKeyFunc, store) {
+	return async (context) => {
+		if (context.cache.enabled) context.cache.set(false);
+		const { success, data: payload, error } = altchaPayloadSchema.safeParse(await context.request.json());
+		if (!success) {
+			const e = `Error parsing altcha payload: ${z.prettifyError(error)}`;
+			context.logger?.error(e);
+			return new Response(e, {
+				status: 400,
+				statusText: "Bad Request"
+			});
+		}
+		const result = await verify(payload, deriveKeyFunc, hmacSecret, await deriveHmacKeySecret(hmacSecret), store);
+		return Response.json(result, { headers: { "Cache-Control": "no-store" } });
+	};
+}
+
+export { createVerifyHandler };

package/dist/api/payload-schema.d.ts

@@ -0,0 +1,22 @@
+import { z } from "astro/zod";
+export declare const altchaPayloadSchema: z.ZodObject<{
+  challenge: z.ZodObject<{
+    parameters: z.ZodObject<{
+      algorithm: z.ZodString;
+      cost: z.ZodNumber;
+      keyLength: z.ZodNumber;
+      keyPrefix: z.ZodString;
+      keySignature: z.ZodOptional<z.ZodString>;
+      nonce: z.ZodString;
+      salt: z.ZodString;
+      expiresAt: z.ZodOptional<z.ZodInt>;
+    }, z.core.$loose>;
+    signature: z.ZodString;
+  }, z.core.$loose>;
+  solution: z.ZodObject<{
+    counter: z.ZodNumber;
+    derivedKey: z.ZodString;
+    time: z.ZodNumber;
+  }, z.core.$loose>;
+}, z.core.$loose>;
+export type AltchaPayload = z.infer<typeof altchaPayloadSchema>;

package/dist/api/payload-schema.js

@@ -0,0 +1,25 @@
+import { z } from "astro/zod";
+
+// src/api/payload-schema.ts
+const altchaPayloadSchema = z.looseObject({
+	challenge: z.looseObject({
+		parameters: z.looseObject({
+			algorithm: z.string(),
+			cost: z.number(),
+			keyLength: z.number(),
+			keyPrefix: z.string(),
+			keySignature: z.string().optional(),
+			nonce: z.string(),
+			salt: z.string(),
+			expiresAt: z.int().optional()
+		}),
+		signature: z.string()
+	}),
+	solution: z.looseObject({
+		counter: z.number(),
+		derivedKey: z.string(),
+		time: z.number()
+	})
+});
+
+export { altchaPayloadSchema };

package/dist/api/verify.d.ts

@@ -0,0 +1 @@
+export declare const POST: import("astro").APIRoute;

package/dist/api/verify.js

@@ -0,0 +1,12 @@
+import { createVerifyHandler } from "./altcha-verify.js";
+import { pickDeriveKeyFunc } from "./pickDeriveKey.js";
+import { getSecret } from "astro:env/server";
+import { config } from "astro-altcha:config";
+import store from "astro-altcha:storage";
+
+// src/api/verify.ts
+const ALTCHA_HMAC_SIGNATURE = getSecret("ALTCHA_HMAC_SIGNATURE");
+if (!ALTCHA_HMAC_SIGNATURE) throw new Error("ALTCHA_HMAC_SIGNATURE not set");
+const POST = createVerifyHandler(ALTCHA_HMAC_SIGNATURE, await pickDeriveKeyFunc(config.challengeOptions.algorithm), store);
+
+export { POST };

package/dist/integration.d.ts

@@ -2,12 +2,17 @@ import { Algorithm, AstroAltchaConfig } from "./types/index.js";
 import { AstroIntegration } from "astro";
 export declare function integration(options?: AstroAltchaConfig): AstroIntegration;
 export declare function mergeDefaultConfig(command: "dev" | "build" | "preview" | "sync", options?: AstroAltchaConfig): {
+  readonly features: {
+    middleware: boolean;
+    challengeEndpoint: boolean;
+    verifyEndpoint: boolean;
+  };
   readonly setCookie?: {
     domain?: string;
     name: string;
     maxAge: number;
     path: string;
-    sameSite: "lax" | "strict" | "none";
+    sameSite: "none" | "strict" | "lax";
     secure: boolean;
   };
   readonly challengeOptions: {
@@ -16,29 +21,30 @@ export declare function mergeDefaultConfig(command: "dev" | "build" | "preview"
     readonly counter: number;
   } | {
     readonly algorithm: Exclude<Algorithm, "Argon2id" | "Scrypt">;
+    readonly keyLength?: number;
+    readonly keyPrefix?: string;
     counter: number;
     readonly counterMode?: "uint32" | "string";
     readonly data?: Record<string, string | number | boolean | null>;
     readonly hmacAlgorithm?: import("altcha-lib").HmacAlgorithm;
-    readonly keyLength?: number;
-    readonly keyPrefix?: string;
     readonly keyPrefixLength?: number;
     readonly memoryCost?: number;
     readonly parallelism?: number;
     cost: number;
   } | {
     readonly algorithm: "Argon2id" | "Scrypt";
+    readonly keyLength?: number;
+    readonly keyPrefix?: string;
     counter: number;
     readonly counterMode?: "uint32" | "string";
     readonly data?: Record<string, string | number | boolean | null>;
     readonly hmacAlgorithm?: import("altcha-lib").HmacAlgorithm;
-    readonly keyLength?: number;
-    readonly keyPrefix?: string;
     readonly keyPrefixLength?: number;
     readonly memoryCost: number;
     readonly parallelism?: number;
     cost: number;
   };
+  readonly verifyPath: string;
   readonly storage?: string;
   readonly defaultName: `${string}astro-altcha${string}`;
   readonly challengePath: string;

package/dist/integration.js

@@ -8,21 +8,28 @@ function integration(options = {}) {
 	return {
 		name: "astro-altcha",
 		hooks: {
-			"astro:config:setup": ({ injectRoute, updateConfig, addMiddleware, command }) => {
-				const config = mergeDefaultConfig(command, options);
+			"astro:config:setup": ({ injectRoute, updateConfig, addMiddleware, command, logger }) => {
+				const resolvedConfig = mergeDefaultConfig(command, options);
+				if (options.challengePath && resolvedConfig.features.challengeEndpoint === false) logger.warn(`A custom challenge endpoint path was configured but the feature is disabled. The challenge endpoint at ${options.challengePath} will not be created unless the feature flag is set to enabled.`);
+				if (options.verifyPath && resolvedConfig.features.verifyEndpoint === false) logger.warn(`A custom verify endpoint path was configured but the feature is disabled. The verify endpoint at ${options.verifyPath} will not be created unless the feature flag is set to enabled.`);
 				updateConfig({
-					vite: { plugins: [plugin(config), plugin$1(config.storage)] },
+					vite: { plugins: [plugin(resolvedConfig), plugin$1(resolvedConfig.storage)] },
 					env: { schema: { ALTCHA_HMAC_SIGNATURE: envField.string({
 						context: "server",
 						access: "secret"
 					}) } }
 				});
-				injectRoute({
-					pattern: config.challengePath,
+				if (resolvedConfig.features.challengeEndpoint) injectRoute({
+					pattern: resolvedConfig.challengePath,
 					entrypoint: new URL("./api/challenge.js", import.meta.url),
 					prerender: false
 				});
-				addMiddleware({
+				if (resolvedConfig.features.verifyEndpoint) injectRoute({
+					pattern: resolvedConfig.verifyPath,
+					entrypoint: new URL("./api/verify.js", import.meta.url),
+					prerender: false
+				});
+				if (resolvedConfig.features.middleware) addMiddleware({
 					order: "pre",
 					entrypoint: new URL("./api/middleware.js", import.meta.url)
 				});
@@ -84,6 +91,12 @@ function mergeDefaultConfig(command, options = {}) {
 		secure: command !== "dev",
 		...options.setCookie === true ? {} : options.setCookie
 	};
+	const features = {
+		middleware: true,
+		challengeEndpoint: true,
+		verifyEndpoint: false,
+		...options.features
+	};
 	return {
 		defaultName,
 		challengePath: options.challengePath ?? "/api/altcha/challenge",
@@ -95,7 +108,9 @@ function mergeDefaultConfig(command, options = {}) {
 			counter: randomInt(5e3, 1e4),
 			...options.challengeOptions
 		},
-		...setCookie ? { setCookie } : {}
+		verifyPath: options.verifyPath ?? "/api/altcha/verify",
+		...setCookie ? { setCookie } : {},
+		features
 	};
 }
 

package/dist/types/index.d.ts

@@ -24,6 +24,12 @@ export type AstroAltchaConfig = {
    *
    */
   challengeOptions?: WithOptional<AltchaChallengeOptions<Algorithm>, "cost">;
+  /**
+   * Path of the verify API endpoint.
+
+   * @default /api/altcha/verify
+   */
+  verifyPath?: string;
   /**
    * Challenge expiration in minutes
    *
@@ -44,6 +50,16 @@ export type AstroAltchaConfig = {
    * @default "./src/astro-altcha/storage.ts"
    */
   storage?: string | URL;
+  /**
+   * Enable or disable integration features.
+   *
+   * @default { middleware: true, challengeEndpoint: true, verifyEndpoint: false }
+   */
+  features?: {
+    middleware?: boolean;
+    challengeEndpoint?: boolean;
+    verifyEndpoint?: boolean;
+  };
 };
 export type ResolvedSetCookieOptions = WithRequired<SetCookieOptions & {
   sameSite?: "lax" | "strict" | "none";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-altcha",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Altcha integration for Astro",
   "type": "module",
   "sideEffects": false,
@@ -50,7 +50,7 @@
   },
   "devDependencies": {
     "@astrojs/check": "0.9.12",
-    "tsdown": "0.23.5",
+    "tsdown": "0.23.7",
     "vite": "^8.3.4"
   },
   "dependencies": {