astro-altcha 0.3.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
 
@@ -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-middleware.d.ts

@@ -2,6 +2,7 @@ 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<{
@@ -23,5 +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, { setCookie }: ResolvedAstroAltchaConfig<Algorithm>): MiddlewareHandler;
+export declare function createAltchaMiddlewareHandler(hmacSecret: string, deriveKeyFunc: DeriveKeyFunction, { setCookie }: ResolvedAstroAltchaConfig<Algorithm>, store: Store): MiddlewareHandler;
 export {};

package/dist/api/altcha-middleware.js

@@ -1,4 +1,3 @@
-import { CappedMap } from "altcha-lib";
 import { deriveHmacKeySecret, verify } from "altcha-lib/frameworks/shared";
 import { z } from "astro/zod";
 import { base64ToString } from "uint8array-extras";
@@ -24,9 +23,8 @@ const altchaPayloadSchema = z.looseObject({
 		time: z.number()
 	})
 });
-const store = new CappedMap({ maxSize: 499 });
 const keyRegexp = /.*astro-altcha.*/;
-function createAltchaMiddlewareHandler(hmacSecret, deriveKeyFunc, { setCookie }) {
+function createAltchaMiddlewareHandler(hmacSecret, deriveKeyFunc, { setCookie }, store) {
 	return async (context, next) => {
 		if (context.request.method !== "POST") return next();
 		let altchaBase64 = setCookie?.name ? context.cookies.get(setCookie.name)?.value : void 0;

package/dist/api/middleware.js

@@ -3,11 +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";
 
 // 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), config));
+const altchaMiddleware = defineMiddleware(createAltchaMiddlewareHandler(ALTCHA_HMAC_SIGNATURE, await pickDeriveKeyFunc(config.challengeOptions.algorithm), config, store));
 const onRequest = altchaMiddleware;
 
 export { onRequest };

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

@@ -2,5 +2,8 @@ import { integration } from "./integration.js";
 
 // src/index.ts
 var src_default = integration;
+function defineStorage(store) {
+	return store;
+}
 
-export { src_default as default };
+export { src_default as default, defineStorage };

package/dist/integration.d.ts

@@ -7,12 +7,9 @@ export declare function mergeDefaultConfig(command: "dev" | "build" | "preview"
     name: string;
     maxAge: number;
     path: string;
-    sameSite: "none" | "strict" | "lax";
+    sameSite: "lax" | "strict" | "none";
     secure: boolean;
   };
-  readonly defaultName: `${string}astro-altcha${string}`;
-  readonly challengePath: string;
-  readonly challengeExpiresAfterMinutes: number;
   readonly challengeOptions: {
     readonly algorithm: "PBKDF2/SHA-256";
     readonly cost: number;
@@ -42,4 +39,8 @@ export declare function mergeDefaultConfig(command: "dev" | "build" | "preview"
     readonly parallelism?: number;
     cost: number;
   };
+  readonly storage?: string;
+  readonly defaultName: `${string}astro-altcha${string}`;
+  readonly challengePath: string;
+  readonly challengeExpiresAfterMinutes: number;
 };

package/dist/integration.js

@@ -1,4 +1,5 @@
-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";
 
@@ -10,7 +11,7 @@ function integration(options = {}) {
 			"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"
@@ -87,6 +88,7 @@ function mergeDefaultConfig(command, options = {}) {
 		defaultName,
 		challengePath: options.challengePath ?? "/api/altcha/challenge",
 		challengeExpiresAfterMinutes,
+		...!options.storage ? { storage: options.storage } : {},
 		challengeOptions: {
 			algorithm: "PBKDF2/SHA-256",
 			cost: 5e3,

package/dist/types/index.d.ts

@@ -38,13 +38,20 @@ export type AstroAltchaConfig = {
   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 ResolvedSetCookieOptions = WithRequired<SetCookieOptions & {
   sameSite?: "lax" | "strict" | "none";
 }, "name" | "maxAge" | "path" | "sameSite" | "secure">;
-export type ResolvedAstroAltchaConfig<Algo extends Algorithm> = Required<Omit<AstroAltchaConfig, "setCookie">> & {
+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]; };

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

@@ -1,4 +1,4 @@
-// src/vite-plugin.ts
+// src/vite-plugin-config.ts
 const virtualModuleId = "astro-altcha:config";
 const resolvedVirtualModuleId = `\0${virtualModuleId}`;
 const plugin = (config) => {

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.3.0",
+  "version": "0.4.0",
   "description": "Altcha integration for Astro",
   "type": "module",
   "sideEffects": false,