astro-altcha 0.2.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,18 @@
+Copyright 2026 Lukas Trombach
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -5,15 +5,19 @@
 ![NPM Version](https://img.shields.io/npm/v/astro-altcha)
 
 
-> **Warning** Early development. Expect bugs and frequent breaking changes.
+> **Warning** Early development. Expect bugs and breaking changes.
 
-This is an [Astro integration](https://docs.astro.build/en/guides/integrations-guide/) that sets up altcha for Astro. 
+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
+- preconfigured challenge storage to prevent replay attacks
+- `AltchaForm` and `AltchaObfuscationWidget` Astro components, optimized for speed; only load altcha's javascript when it's actually needed
 
 ## Usage
 
 ### Prerequisites
 
-TODO:
+Since `astro-altcha` requires middleware and an endpoint to create and verify challenges at runtime it does not work in a fully static build. At least Astro version 6 is required.
 
 ### Installation
 
@@ -59,9 +63,132 @@ export default defineConfig({
 });
 ```
 
+4. Set `ALTCHA_HMAC_SIGNATURE` in your local .env file and in your deployment environment. This is the signing key for your altcha challenges and should be kept secret. `astro-altcha` currently does not (and might never) support unsigned challenge generation so this value must be provided.
+
 ### Configuration
 
-TODO:configuration
+#### 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
+- `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)
+
+#### Customize sSorage
+
+`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.
+
+```ts
+// src/astro-altcha/storage.ts
+import { defineStorage } from "astro-altcha";
+
+const storage = defineStorage({
+	get: (key: string) => console.log(`getting ${key}`),
+	set: (key: string, value: boolean) =>
+		console.log(`setting ${key} with ${value}`),
+});
+export default storage;
+````
+
+This can be useful if you want to want to use an external storage provider such as redis or if you simply want to provide your own custom implementation.
+
+### Components
+
+While you can just use the provided middleware and challenge handlers on their own, the easiest way to get started with `astro-altcha` are the bundled astro components. They are designed to work with the injected challenge endpoint and middleware without further configuration.
+
+#### AltchaForm
+
+A form component, which includes an `altcha-widget` and handles its initialisation for you.
+
+```astro
+---
+import { AltchaForm } from "astro-altcha/components";
+import { actions } from "astro:actions";
+---
+
+<AltchaForm action={actions.submitForm}>
+    <input name="firstname">
+    <input name="lastname">
+    <button type="submit">Submit</button>
+</AltchaForm>
+```
+
+With the default integration configuration this will render a standard altcha-widget element on page load. The result of the verification can be easily checked via the Astro locals object either in an Astro action or any other route handler that runs after middleware. 
+
+```ts
+// src/actions/index.ts
+import { type ActionAPIContext, defineAction } from "astro:actions";
+
+export const server = {
+	submitForm: defineAction({
+		accept: "form",
+		handler: async (input, context: ActionAPIContext) =>
+			console.log("is verified?", context.locals.altcha.verified),
+	}),
+};
+````
+
+The `AltchaForm` component exposes the raw [Altcha widget configuration options](https://altcha.org/docs/integration/widget/#configuration), but includes a few properties for convenience:
+
+```astro
+---
+import { AltchaForm } from "astro-altcha/components";
+---
+
+<AltchaForm widget={
+  {
+    debug: true,
+    hydrationStrategy: "onload",
+    theme: "cyberpunk",
+  }
+}>
+...
+</AltchaForm>
+````
+
+- the widget's debug mode can be enabled via the `debug` prop on the widget. This will call the widgets `configure` method for you after the widget script has been loaded in your browser
+- the hydration strategy of the widget can be chosen via the `hydrationStrategy` property. By default the widget script is loaded when the page loads. Two other strategies are available: `onvisible` and `onfocus`. `onvisible` uses an `IntersectionObserver` to initialise the widget when the containing form enters the viewport. `onfocus` initialises when the user clicks into the form.
+- the widget's [theme](https://altcha.org/docs/integration/widget/#themes-and-customization) can be set via the `theme` property on the widget. `astro-altcha` takes care of importing the required css files for you.
+
+`AltchaForm` emits an `astro-altcha:init` event which fires right after the altcha widget was initialised and gives access to an instance of the contained `altcha-widget` via the details prop.
+
+```astro
+---
+import { AltchaForm } from "astro-altcha/components";
+---
+
+<AltchaForm name="my-form">...</AltchaForm>
+
+<script>
+const form = document.querySelector("form[name=my-form]") as HTMLFormElement;
+
+form.addEventListener("astro-altcha:init", (event) => {
+  console.log("altcha widget initialised");
+  event.detail.widget.configure({...})
+})
+</script>
+````
+
+#### AltchaObfuscationWidget
+
+The widget can be used in the same way as described in the [obfuscation documentation](https://altcha.org/docs/integration/obfuscation/), with the advantage that `AltchaObfuscationWidget` takes care of obfuscating the data on the server for you. Just pass data via the `data` prop. Note that this follows the same rules as `altcha-widget`, so if you want to obfuscate a link, just pass the plain url; the widget will render it as an `a` element after deobfuscation.
+
+The widget can be themed in the same way as the `AltchaForm` widget. By default its hydration strategy is set to `onvisible` and display to `floating`.
+
+```astro
+---
+import { AltchaObfuscationWidget } from "astro-altcha/components";
+---
+
+<AltchaObfuscationWidget data="https://astro.build" />
+
+<!-- Trigger can be customized -->
+<AltchaObfuscationWidget data="https://astro.build">
+    <button type="button">I am a custom reveal button</button>
+</AltchaObfuscationWidget>
+```
 
 ## Contributing
 
@@ -70,7 +197,7 @@ This package is structured as a monorepo:
 - `playground` contains code for testing the package
 - `package` contains the actual package
 
-Install dependencies using pnpm: 
+Install dependencies using pnpm:
 
 ```bash
 pnpm i --frozen-lockfile
@@ -86,9 +213,8 @@ You can now edit files in `package`. Please note that making changes to those fi
 
 ## Licensing
 
-[MIT Licensed](https://github.com/TODO:/blob/main/LICENSE). Made with ❤️ by [TODO:](https://github.com/TODO:).
+[MIT Licensed](https://codeberg.org/Trombach/astro-altcha/blob/main/LICENSE). Made with ❤️ by [Trombach](https://codeberg.org/Trombach).
 
 ## Acknowledgements
 
 - Created using [astro-integration-template](https://github.com/florian-lefebvre/astro-integration-template).
-- TODO:

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

@@ -1,6 +1,4 @@
 import { Algorithm, ResolvedAstroAltchaConfig } from "../types/index.js";
 import { DeriveKeyFunction } from "altcha/lib";
 import { APIRoute } from "astro";
-//#region src/api/altcha-challenge.d.ts
-export declare function createChallengeHandler(hmacSecret: string, config: ResolvedAstroAltchaConfig<Algorithm>, deriveKeyFunc: DeriveKeyFunction): APIRoute;
-//#endregion
+export declare function createChallengeHandler(hmacSecret: string, { challengeOptions, challengeExpiresAfterMinutes, setCookie }: ResolvedAstroAltchaConfig<Algorithm>, deriveKeyFunc: DeriveKeyFunction): APIRoute;

package/dist/api/altcha-challenge.js

@@ -1,20 +1,23 @@
 import { createChallenge } from "altcha-lib";
 import { deriveHmacKeySecret } from "altcha-lib/frameworks/shared";
 
-//#region src/api/altcha-challenge.ts
-function createChallengeHandler(hmacSecret, config, deriveKeyFunc) {
+// src/api/altcha-challenge.ts
+function createChallengeHandler(hmacSecret, { challengeOptions, challengeExpiresAfterMinutes, setCookie }, deriveKeyFunc) {
 	return (async (context) => {
 		if (context.cache.enabled) context.cache.set(false);
 		const challenge = await createChallenge({
-			...config.challengeOptions,
-			expiresAt: Math.floor(Date.now() / 1e3 + config.challengeExpiresAfterMinutes * 60),
+			...challengeOptions,
+			expiresAt: Math.floor(Date.now() / 1e3 + challengeExpiresAfterMinutes * 60),
 			deriveKey: deriveKeyFunc,
 			hmacSignatureSecret: hmacSecret,
 			hmacKeySignatureSecret: await deriveHmacKeySecret(hmacSecret)
 		});
-		return Response.json(challenge);
+		const body = {
+			configuration: setCookie ? { setCookie } : void 0,
+			...challenge
+		};
+		return Response.json(body, { headers: { "Cache-Control": "no-store" } });
 	});
 }
 
-//#endregion
 export { createChallengeHandler };

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

@@ -1,7 +1,8 @@
+import { Algorithm, ResolvedAstroAltchaConfig } from "../types/index.js";
 import { DeriveKeyFunction } from "altcha-lib";
 import { z } from "astro/zod";
 import { MiddlewareHandler } from "astro";
-//#region src/api/altcha-middleware.d.ts
+import { Store } from "altcha-lib/frameworks/types";
 declare const altchaPayloadSchema: z.ZodObject<{
   challenge: z.ZodObject<{
     parameters: z.ZodObject<{
@@ -23,6 +24,5 @@ declare const altchaPayloadSchema: z.ZodObject<{
   }, z.core.$loose>;
 }, z.core.$loose>;
 export type AltchaPayload = z.infer<typeof altchaPayloadSchema>;
-export declare function createAltchaMiddlewareHandler(hmacSecret: string, deriveKeyFunc: DeriveKeyFunction): MiddlewareHandler;
-//#endregion
+export declare function createAltchaMiddlewareHandler(hmacSecret: string, deriveKeyFunc: DeriveKeyFunction, { setCookie }: ResolvedAstroAltchaConfig<Algorithm>, store: Store): MiddlewareHandler;
 export {};

package/dist/api/altcha-middleware.js

@@ -1,9 +1,8 @@
-import { CappedMap } from "altcha-lib";
 import { deriveHmacKeySecret, verify } from "altcha-lib/frameworks/shared";
 import { z } from "astro/zod";
 import { base64ToString } from "uint8array-extras";
 
-//#region src/api/altcha-middleware.ts
+// src/api/altcha-middleware.ts
 const altchaPayloadSchema = z.looseObject({
 	challenge: z.looseObject({
 		parameters: z.looseObject({
@@ -24,17 +23,19 @@ const altchaPayloadSchema = z.looseObject({
 		time: z.number()
 	})
 });
-const store = new CappedMap({ maxSize: 499 });
 const keyRegexp = /.*astro-altcha.*/;
-function createAltchaMiddlewareHandler(hmacSecret, deriveKeyFunc) {
+function createAltchaMiddlewareHandler(hmacSecret, deriveKeyFunc, { setCookie }, store) {
 	return async (context, next) => {
 		if (context.request.method !== "POST") return next();
-		if (!context.request.headers.get("content-type")?.includes("multipart/form-data") && !context.request.headers.get("content-type")?.includes("application/x-www-form-urlencoded")) return next();
-		const body = Object.fromEntries((await context.request.clone().formData()).entries());
-		const key = Object.keys(body).find((key) => keyRegexp.test(key));
-		if (!key) return next();
-		const altchaBase64 = body?.[key]?.toString();
-		if (!altchaBase64) return next();
+		let altchaBase64 = setCookie?.name ? context.cookies.get(setCookie.name)?.value : void 0;
+		if (!altchaBase64) {
+			if (!context.request.headers.get("content-type")?.includes("multipart/form-data") && !context.request.headers.get("content-type")?.includes("application/x-www-form-urlencoded")) return next();
+			const body = Object.fromEntries((await context.request.clone().formData()).entries());
+			const key = Object.keys(body).find((key) => keyRegexp.test(key));
+			if (!key) return next();
+			altchaBase64 = body?.[key]?.toString();
+			if (!altchaBase64) return next();
+		}
 		let parsed;
 		try {
 			parsed = JSON.parse(base64ToString(altchaBase64));
@@ -48,6 +49,7 @@ function createAltchaMiddlewareHandler(hmacSecret, deriveKeyFunc) {
 			return next();
 		}
 		const result = await verify(altchaPayload, deriveKeyFunc, hmacSecret, await deriveHmacKeySecret(hmacSecret), store);
+		if (setCookie) context.cookies.delete(setCookie.name, { ...setCookie });
 		if (result.error && !result.verification) {
 			context.logger?.error(`Error verifying altcha payload: ${result.error}`);
 			return next();
@@ -57,5 +59,4 @@ function createAltchaMiddlewareHandler(hmacSecret, deriveKeyFunc) {
 	};
 }
 
-//#endregion
 export { createAltchaMiddlewareHandler };

package/dist/api/challenge.d.ts

@@ -1,3 +1 @@
-//#region src/api/challenge.d.ts
-export declare const GET: import("astro").APIRoute;
-//#endregion
+export declare const GET: import("astro").APIRoute;

package/dist/api/challenge.js

@@ -3,10 +3,9 @@ import { pickDeriveKeyFunc } from "./pickDeriveKey.js";
 import { getSecret } from "astro:env/server";
 import { config } from "astro-altcha:config";
 
-//#region src/api/challenge.ts
+// src/api/challenge.ts
 const ALTCHA_HMAC_SIGNATURE = getSecret("ALTCHA_HMAC_SIGNATURE");
 if (!ALTCHA_HMAC_SIGNATURE) throw new Error("ALTCHA_HMAC_SIGNATURE not set");
 const GET = createChallengeHandler(ALTCHA_HMAC_SIGNATURE, config, await pickDeriveKeyFunc(config.challengeOptions.algorithm));
 
-//#endregion
 export { GET };

package/dist/api/middleware.d.ts

@@ -1,3 +1 @@
-//#region src/api/middleware.d.ts
-export declare const onRequest: any;
-//#endregion
+export declare const onRequest: any;

package/dist/api/middleware.js

@@ -3,12 +3,12 @@ import { pickDeriveKeyFunc } from "./pickDeriveKey.js";
 import { getSecret } from "astro:env/server";
 import { config } from "astro-altcha:config";
 import { defineMiddleware } from "astro:middleware";
+import store from "astro-altcha:storage";
 
-//#region src/api/middleware.ts
+// src/api/middleware.ts
 const ALTCHA_HMAC_SIGNATURE = getSecret("ALTCHA_HMAC_SIGNATURE");
 if (!ALTCHA_HMAC_SIGNATURE) throw new Error("ALTCHA_HMAC_SIGNATURE not set");
-const altchaMiddleware = defineMiddleware(createAltchaMiddlewareHandler(ALTCHA_HMAC_SIGNATURE, await pickDeriveKeyFunc(config.challengeOptions.algorithm)));
+const altchaMiddleware = defineMiddleware(createAltchaMiddlewareHandler(ALTCHA_HMAC_SIGNATURE, await pickDeriveKeyFunc(config.challengeOptions.algorithm), config, store));
 const onRequest = altchaMiddleware;
 
-//#endregion
 export { onRequest };

package/dist/api/pickDeriveKey.d.ts

@@ -1,4 +1,2 @@
 import { Algorithm } from "../types/index.js";
-//#region src/api/pickDeriveKey.d.ts
-export declare function pickDeriveKeyFunc(algorithm: Algorithm): Promise<typeof import("altcha-lib/algorithms/pbkdf2").deriveKey>;
-//#endregion
+export declare function pickDeriveKeyFunc(algorithm: Algorithm): Promise<typeof import("altcha-lib/algorithms/pbkdf2").deriveKey>;

package/dist/api/pickDeriveKey.js

@@ -1,4 +1,4 @@
-//#region src/api/pickDeriveKey.ts
+// src/api/pickDeriveKey.ts
 async function pickDeriveKeyFunc(algorithm) {
 	switch (algorithm) {
 		case "PBKDF2/SHA-256":
@@ -12,5 +12,4 @@ async function pickDeriveKeyFunc(algorithm) {
 	}
 }
 
-//#endregion
 export { pickDeriveKeyFunc };

package/dist/components/common.d.ts

@@ -0,0 +1,3 @@
+import { AltchaWidgetTheme, AstroAltchaHydrationStrategy } from "../types/index.js";
+export declare function mountWithStrategy(strategy: AstroAltchaHydrationStrategy, element: HTMLElement, mount: () => void): void;
+export declare function importTheme(theme?: AltchaWidgetTheme | null): Promise<void>;

package/dist/components/common.js

@@ -0,0 +1,46 @@
+// src/components/common.ts
+function mountWithStrategy(strategy, element, mount) {
+	switch (strategy) {
+		case "onload":
+			mount();
+			return;
+		case "onfocus":
+			element.addEventListener("focusin", mount, { once: true });
+			return;
+		case "onvisible":
+			new IntersectionObserver((entries, observer) => {
+				if (!entries.some((entry) => entry.isIntersecting)) return;
+				observer.disconnect();
+				mount();
+			}, { rootMargin: "200px 0px" }).observe(element);
+			return;
+	}
+}
+async function importTheme(theme) {
+	if (!theme) return;
+	switch (theme) {
+		case "aqua":
+			await import("altcha/themes/aqua.min.css");
+			return;
+		case "business":
+			await import("altcha/themes/business.min.css");
+			return;
+		case "caramel":
+			await import("altcha/themes/caramel.min.css");
+			return;
+		case "cupcake":
+			await import("altcha/themes/cupcake.min.css");
+			return;
+		case "cyberpunk":
+			await import("altcha/themes/cyberpunk.min.css");
+			return;
+		case "lime":
+			await import("altcha/themes/lime.min.css");
+			return;
+		case "wireframe":
+			await import("altcha/themes/wireframe.min.css");
+			return;
+	}
+}
+
+export { importTheme, mountWithStrategy };

package/dist/index.d.ts

@@ -1,2 +1,4 @@
 import { integration } from "./integration.js";
+import { Store } from "altcha-lib/frameworks/types";
+export declare function defineStorage<T extends Store>(store: T): T;
 export { integration as default };

package/dist/index.js

@@ -1,7 +1,9 @@
 import { integration } from "./integration.js";
 
-//#region src/index.ts
+// src/index.ts
 var src_default = integration;
+function defineStorage(store) {
+	return store;
+}
 
-//#endregion
-export { src_default as default };
+export { src_default as default, defineStorage };

package/dist/integration.d.ts

@@ -1,39 +1,46 @@
-import { Algorithm, AltchaWidgetName, AstroAltchaConfig } from "./types/index.js";
+import { Algorithm, AstroAltchaConfig } from "./types/index.js";
 import { AstroIntegration } from "astro";
-//#region src/integration.d.ts
 export declare function integration(options?: AstroAltchaConfig): AstroIntegration;
-export declare function mergeDefaultConfig(options?: AstroAltchaConfig): {
+export declare function mergeDefaultConfig(command: "dev" | "build" | "preview" | "sync", options?: AstroAltchaConfig): {
+  readonly setCookie?: {
+    domain?: string;
+    name: string;
+    maxAge: number;
+    path: string;
+    sameSite: "lax" | "strict" | "none";
+    secure: boolean;
+  };
   readonly challengeOptions: {
     readonly algorithm: "PBKDF2/SHA-256";
     readonly cost: number;
     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 defaultName: AltchaWidgetName;
+  readonly storage?: string;
+  readonly defaultName: `${string}astro-altcha${string}`;
   readonly challengePath: string;
   readonly challengeExpiresAfterMinutes: number;
-};
-//#endregion
+};

package/dist/integration.js

@@ -1,16 +1,17 @@
-import plugin from "./vite-plugin.js";
+import plugin from "./vite-plugin-config.js";
+import plugin$1 from "./vite-plugin-storage.js";
 import { randomInt } from "altcha-lib";
 import { envField } from "astro/config";
 
-//#region src/integration.ts
+// src/integration.ts
 function integration(options = {}) {
-	const config = mergeDefaultConfig(options);
 	return {
 		name: "astro-altcha",
 		hooks: {
-			"astro:config:setup": ({ injectRoute, updateConfig, addMiddleware }) => {
+			"astro:config:setup": ({ injectRoute, updateConfig, addMiddleware, command }) => {
+				const config = mergeDefaultConfig(command, options);
 				updateConfig({
-					vite: { plugins: [plugin(config)] },
+					vite: { plugins: [plugin(config), plugin$1(config.storage)] },
 					env: { schema: { ALTCHA_HMAC_SIGNATURE: envField.string({
 						context: "server",
 						access: "secret"
@@ -30,11 +31,9 @@ function integration(options = {}) {
 				injectTypes({
 					filename: "types.d.ts",
 					content: `declare module "astro-altcha:config" {
-	export const config: Required<
-	  import("astro-altcha/types").ResolvedAstroAltchaConfig<
-			import("astro-altcha/types").Algorithm
-	  >
-  >;
+	export const config: import("astro-altcha/types").ResolvedAstroAltchaConfig<
+		import("astro-altcha/types").Algorithm
+  >
 }
 
 declare namespace App {
@@ -74,20 +73,30 @@ export {};
 		}
 	};
 }
-function mergeDefaultConfig(options = {}) {
+function mergeDefaultConfig(command, options = {}) {
+	const defaultName = options.defaultName ?? "astro-altcha";
+	const challengeExpiresAfterMinutes = options.challengeExpiresAfterMinutes ?? 20;
+	const setCookie = !options.setCookie ? void 0 : {
+		name: defaultName,
+		maxAge: challengeExpiresAfterMinutes * 60,
+		path: "/",
+		sameSite: "lax",
+		secure: command !== "dev",
+		...options.setCookie === true ? {} : options.setCookie
+	};
 	return {
-		defaultName: "astro-altcha",
-		challengePath: "/api/altcha/challenge",
-		challengeExpiresAfterMinutes: 20,
-		...options,
+		defaultName,
+		challengePath: options.challengePath ?? "/api/altcha/challenge",
+		challengeExpiresAfterMinutes,
+		...!options.storage ? { storage: options.storage } : {},
 		challengeOptions: {
 			algorithm: "PBKDF2/SHA-256",
 			cost: 5e3,
 			counter: randomInt(5e3, 1e4),
 			...options.challengeOptions
-		}
+		},
+		...setCookie ? { setCookie } : {}
 	};
 }
 
-//#endregion
 export { integration, mergeDefaultConfig };

package/dist/types/index.d.ts

@@ -1,6 +1,6 @@
 import { CreateChallengeOptions } from "altcha-lib/types";
 import { WidgetAttributes } from "altcha/types";
-//#region src/types/index.d.ts
+import { SetCookieOptions } from "altcha/lib";
 export type AltchaWidgetName = `${string}astro-altcha${string}`;
 export type Algorithm = `PBKDF2/${Digest}` | "Argon2id" | "Scrypt" | Digest;
 type Digest = `SHA-${"256" | "384" | "512"}`;
@@ -8,35 +8,50 @@ export type AstroAltchaConfig = {
   /**
    * Default altcha-widget name. Must contain the string `astro-altcha`.
    *
-   * Default: `astro-altcha`
+   * @default astro-altcha
    */
   defaultName?: AltchaWidgetName;
   /**
    *  Path of the challenge API endpoint.
    *
-   * Default: `/api/altcha/challenge`
+   * @default /api/altcha/challenge
    */
   challengePath?: string;
   /**
    * Challenge options for [Challange creation](https://altcha.org/docs/integration/server/#challenge-generation)
    *
-   * Default:
-   * ```
-   * algorithm: "PBKDF2/SHA-256"
-   * cost: 5_000
-   * counter: randomInt(5_000, 10_000)
-   * ```
+   * @default { algorithm: "PBKDF2/SHA-256", cost: 5_000, counter: randomInt(5_000, 10_000) }
+   *
    */
   challengeOptions?: WithOptional<AltchaChallengeOptions<Algorithm>, "cost">;
   /**
    * Challenge expiration in minutes
    *
-   * Default: 20 min
+   * @default 20
    */
   challengeExpiresAfterMinutes?: number;
+  /**
+   * Use cookies instead of an invisible input field
+   *
+   * @default { name: "astro-altcha", maxAge: 1200, path: "/", sameSite: "lax", secure: command !== "dev" }
+   */
+  setCookie?: true | (SetCookieOptions & {
+    sameSite?: "lax" | "strict" | "none";
+  });
+  /**
+   * Path or file URL to the module containing a custom storage adapter.
+   *
+   * @default "./src/astro-altcha/storage.ts"
+   */
+  storage?: string | URL;
 };
-export type ResolvedAstroAltchaConfig<Algo extends Algorithm> = Required<AstroAltchaConfig> & {
+export type ResolvedSetCookieOptions = WithRequired<SetCookieOptions & {
+  sameSite?: "lax" | "strict" | "none";
+}, "name" | "maxAge" | "path" | "sameSite" | "secure">;
+export type ResolvedAstroAltchaConfig<Algo extends Algorithm> = Omit<Required<AstroAltchaConfig>, "setCookie" | "storage" | "challengeOptions"> & {
   challengeOptions: AltchaChallengeOptions<Algo>;
+  setCookie?: ResolvedSetCookieOptions;
+  storage?: string | URL;
 };
 type WithOptional<T, K extends keyof T> = T extends unknown ? Omit<T, K> & Partial<Pick<T, K>> : never;
 type WithRequired<T, K extends keyof T> = T & { [P in K]-?: T[P]; };
@@ -46,23 +61,48 @@ export type AltchaChallengeOptions<Algo extends Algorithm> = Algo extends "Argon
 } : OmitCreateChallengeOptions & {
   algorithm: Exclude<Algorithm, "Argon2id" | "Scrypt">;
 };
-export type AstroAltchaHydrationStrategy = "onfocus" | "onload" | "onhover";
-export type AltchaFormWidgetProps = {
-  /** When the altcha-widget should be hydrated.
-   *
-   * `onfocus` - when the form is first focused
-   *
-   * `onload` - when the page first loads
+export type AstroAltchaHydrationStrategy = "onfocus" | "onload" | "onvisible";
+export type AltchaWidgetProps = {
+  /**
+   * When the altcha-widget should be hydrated.
+   * - onfocus` - when the form is first focused
+   * - `onload` - when the page first loads
+   * - `onvisible` - when the form becomes visible in the viewport (uses IntersectionObserver)
    *
-   * `onhover` - when the form is first hovered
+   * @default onload
    */
   hydrationStrategy?: AstroAltchaHydrationStrategy;
+  /**
+   * Select a theme from https://altcha.org/docs/integration/widget-customization/.
+   */
+  theme?: AltchaWidgetTheme;
+  /**
+   * Enable debug mode for altcha widget.
+   */
   debug?: boolean;
-} & Omit<WidgetAttributes, "name">;
+} & Omit<WidgetAttributes, "name" | "theme">;
+export type AltchaWidgetTheme = "aqua" | "business" | "caramel" | "cupcake" | "cyberpunk" | "lime" | "wireframe";
 export type AltchaFormProps = {
-  widget?: AltchaFormWidgetProps & {
+  widget?: AltchaWidgetProps & {
     name?: AltchaWidgetName;
   };
 } & astroHTML.JSX.FormHTMLAttributes;
-//#endregion
+export type AltchaObfuscationProps = {
+  /**
+   * Plain data to be obfuscated.
+   *
+   * It follows the same rules as a plain altcha-widget, i.e. it recognizes links and automatically
+   * inserts the appropriate element on deobfuscation. You do not need to include markup.
+   *
+   */
+  data: string;
+  /**
+   * When the altcha-widget should be hydrated.
+   * - `onload` - when the page first loads
+   * - `onvisible` - when the widget becomes visible in the viewport (uses IntersectionObserver)
+   *
+   * @default onvisible
+   */
+  hydrationStrategy?: Exclude<AstroAltchaHydrationStrategy, "onfocus">;
+} & Omit<AltchaWidgetProps, "hydrationStrategy">;
 export {};

package/dist/{vite-plugin.d.ts → vite-plugin-config.d.ts}

@@ -1,6 +1,4 @@
 import { Algorithm, ResolvedAstroAltchaConfig } from "./types/index.js";
 import { AstroConfig } from "astro";
-//#region src/vite-plugin.d.ts
 declare const plugin: (config: ResolvedAstroAltchaConfig<Algorithm>) => NonNullable<AstroConfig["vite"]["plugins"]>[number];
-//#endregion
 export { plugin as default };

package/dist/{vite-plugin.js → vite-plugin-config.js}

@@ -1,4 +1,4 @@
-//#region src/vite-plugin.ts
+// src/vite-plugin-config.ts
 const virtualModuleId = "astro-altcha:config";
 const resolvedVirtualModuleId = `\0${virtualModuleId}`;
 const plugin = (config) => {
@@ -14,5 +14,4 @@ ${JSON.stringify(config)}`;
 	};
 };
 
-//#endregion
 export { plugin as default };

package/dist/vite-plugin-storage.d.ts

@@ -0,0 +1,3 @@
+import { AstroConfig } from "astro";
+declare const plugin: (storagePath?: string | URL) => NonNullable<AstroConfig["vite"]["plugins"]>[number];
+export { plugin as default };

package/dist/vite-plugin-storage.js

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/vite-plugin-storage.ts
+const virtualModuleId = "astro-altcha:storage";
+const resolvedVirtualModuleId = `\0${virtualModuleId}`;
+const plugin = (storagePath) => {
+	let root = process.cwd();
+	return {
+		name: "vite-plugin-altcha-storage",
+		configResolved(config) {
+			root = config.root;
+		},
+		resolveId(id) {
+			if (id !== virtualModuleId) return;
+			const found = (storagePath ? [path.resolve(root, storagePath instanceof URL ? fileURLToPath(storagePath) : storagePath)] : [
+				"ts",
+				"js",
+				"mts",
+				"mjs"
+			].map((ext) => path.resolve(root, `./src/astro-altcha/storage.${ext}`))).find((candidate) => fs.existsSync(candidate));
+			if (!found && storagePath) throw new Error(`storage file not found at: ${storagePath}`);
+			return found ?? resolvedVirtualModuleId;
+		},
+		load(id) {
+			if (id === resolvedVirtualModuleId) return `import { CappedMap } from "altcha-lib";
+export default new CappedMap({ maxSize: 499 });
+`;
+		}
+	};
+};
+
+export { plugin as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-altcha",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Altcha integration for Astro",
   "type": "module",
   "sideEffects": false,
@@ -49,8 +49,9 @@
     "astro": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@astrojs/check": "0.9.10",
-    "tsdown": "0.23.1"
+    "@astrojs/check": "0.9.12",
+    "tsdown": "0.23.5",
+    "vite": "^8.3.4"
   },
   "dependencies": {
     "altcha": "^3.2.3",
@@ -60,7 +61,12 @@
   "scripts": {
     "dev": "tsdown --watch",
     "build": "tsdown",
+    "prets:check": "pnpm build",
     "ts:check": "pnpm astro check",
+    "pretest": "pnpm build",
+    "pretest:ci": "pnpm build",
+    "pretest:watch": "pnpm build:",
+    "pretest:update-snapshots": "pnpm build",
     "test": "node --experimental-test-snapshots --experimental-test-module-mocks --test 'test/**/*.test.ts'",
     "test:ci": "node --experimental-test-snapshots --experimental-test-module-mocks --experimental-test-coverage --test 'test/**/*.test.ts'",
     "test:watch": "node --experimental-test-snapshots --experimental-test-module-mocks --watch --test 'test/**/*.test.ts'",

package/src/components/AltchaForm.astro

@@ -29,7 +29,11 @@ const {
 
 <script>
 import type { WidgetAttributes, WidgetMethods } from "altcha/types";
-import type { AstroAltchaHydrationStrategy } from "astro-altcha/types";
+import type {
+	AltchaWidgetTheme,
+	AstroAltchaHydrationStrategy,
+} from "astro-altcha/types";
+import { importTheme, mountWithStrategy } from "./common.ts";
 
 const templates = document.querySelectorAll("template");
 
@@ -49,19 +53,13 @@ for (const template of templates) {
 		continue;
 	}
 
-	const mount = () => mountWidget(form, template, widget, debug === "true");
+	const theme = widget.getAttribute("theme") as AltchaWidgetTheme | null;
 
-	switch (hydrationStrategy as AstroAltchaHydrationStrategy) {
-		case "onload":
-			void mount();
-			break;
-		case "onfocus":
-			form.addEventListener("focusin", mount, { once: true });
-			break;
-		case "onhover":
-			form.addEventListener("mouseenter", mount, { once: true });
-			break;
-	}
+	mountWithStrategy(
+		hydrationStrategy as AstroAltchaHydrationStrategy,
+		form,
+		() => mountWidget(form, template, widget, debug === "true", theme),
+	);
 }
 
 async function mountWidget(
@@ -69,13 +67,15 @@ async function mountWidget(
 	template: HTMLTemplateElement,
 	widget: HTMLElement & WidgetAttributes & WidgetMethods,
 	debug: boolean,
+	theme?: AltchaWidgetTheme | null,
 ) {
-	await import("altcha");
-
 	const widgetReady = new Promise<void>((resolve) =>
 		widget.addEventListener("load", () => resolve(), { once: true }),
 	);
 
+	await importTheme(theme);
+	await import("altcha");
+
 	template.replaceWith(widget);
 	await widgetReady;
 

package/src/components/AltchaObfuscationWidget.astro

@@ -1,21 +1,94 @@
 ---
-import type { WidgetAttributes } from "altcha/types";
 import { obfuscate } from "altcha-lib/obfuscation";
+import type { AltchaObfuscationProps } from "astro-altcha/types";
 
-type Props = {
-	data: string;
-} & WidgetAttributes;
+type Props = AltchaObfuscationProps;
 
-const { data, display = "floating" } = Astro.props;
+const {
+	data,
+	hydrationStrategy = "onvisible",
+	debug,
+	display = "floating",
+	...widgetProps
+} = Astro.props;
 const dataObfuscated = await obfuscate(data);
 ---
 
-<altcha-widget data-obfuscated={dataObfuscated} {display}>
-	<slot name="reveal">
+<template
+	data-astro-altcha="obfuscation-widget"
+	data-hydration-strategy={hydrationStrategy}
+	data-debug={debug}
+>
+	<altcha-widget
+		data-obfuscated={dataObfuscated}
+		{display}
+		{...widgetProps}
+	></altcha-widget>
+</template>
+<span>
+	<slot>
 		<button type="button">Click to reveal</button>
 	</slot>
-</altcha-widget>
+</span>
 
 <script>
-import "altcha/plugins/obfuscation";
+import type { WidgetAttributes, WidgetMethods } from "altcha/lib";
+import type {
+	AltchaWidgetTheme,
+	AstroAltchaHydrationStrategy,
+} from "astro-altcha/types";
+import { importTheme, mountWithStrategy } from "./common.ts";
+
+const templates = document.querySelectorAll("template");
+
+for (const template of templates) {
+	if (template.dataset.astroAltcha !== "obfuscation-widget") {
+		continue;
+	}
+
+	const trigger = template.nextElementSibling;
+	const widget = template.content.querySelector("altcha-widget");
+	if (!(trigger instanceof HTMLElement) || !widget) {
+		continue;
+	}
+
+	const { hydrationStrategy, debug } = template.dataset;
+	const theme = widget.getAttribute("theme") as AltchaWidgetTheme | null;
+
+	mountWithStrategy(
+		hydrationStrategy as AstroAltchaHydrationStrategy,
+		trigger,
+		() => mountWidget(template, trigger, widget, debug === "true", theme),
+	);
+}
+
+async function mountWidget(
+	template: HTMLTemplateElement,
+	trigger: Element,
+	widget: HTMLElement & WidgetAttributes & WidgetMethods,
+	debug: boolean,
+	theme?: AltchaWidgetTheme | null,
+) {
+	const widgetReady = new Promise<void>((resolve) =>
+		widget.addEventListener("load", () => resolve(), { once: true }),
+	);
+
+	await importTheme(theme);
+	await import("altcha/plugins/obfuscation");
+	await import("altcha");
+
+	// move the trigger into the widget
+	widget.append(trigger);
+	template.replaceWith(widget);
+
+	await widgetReady;
+
+	widget.configure({ debug });
+	widget.dispatchEvent(
+		new CustomEvent("astro-altcha:init", {
+			detail: { widget },
+			bubbles: true,
+		}),
+	);
+}
 </script>

package/src/components/common.ts

@@ -0,0 +1,63 @@
+import type {
+	AltchaWidgetTheme,
+	AstroAltchaHydrationStrategy,
+} from "astro-altcha/types";
+
+export function mountWithStrategy(
+	strategy: AstroAltchaHydrationStrategy,
+	element: HTMLElement,
+	mount: () => void,
+) {
+	switch (strategy) {
+		case "onload":
+			void mount();
+			return;
+		case "onfocus":
+			element.addEventListener("focusin", mount, { once: true });
+			return;
+		case "onvisible": {
+			const observer = new IntersectionObserver(
+				(entries, observer) => {
+					if (!entries.some((entry) => entry.isIntersecting)) {
+						return;
+					}
+					observer.disconnect();
+					void mount();
+				},
+				{ rootMargin: "200px 0px" },
+			);
+			observer.observe(element);
+			return;
+		}
+	}
+}
+
+export async function importTheme(theme?: AltchaWidgetTheme | null) {
+	if (!theme) {
+		return;
+	}
+
+	switch (theme) {
+		case "aqua":
+			await import("altcha/themes/aqua.min.css");
+			return;
+		case "business":
+			await import("altcha/themes/business.min.css");
+			return;
+		case "caramel":
+			await import("altcha/themes/caramel.min.css");
+			return;
+		case "cupcake":
+			await import("altcha/themes/cupcake.min.css");
+			return;
+		case "cyberpunk":
+			await import("altcha/themes/cyberpunk.min.css");
+			return;
+		case "lime":
+			await import("altcha/themes/lime.min.css");
+			return;
+		case "wireframe":
+			await import("altcha/themes/wireframe.min.css");
+			return;
+	}
+}