README

This is a Laravel implementation for the server-side of Altcha, a proof-of-work captcha that does not require any third-party service.

Installation

You can install the package via composer:

composer require grantholle/laravel-altcha

Optionally, publish the config file with:

php artisan vendor:publish --tag="altcha-config"

Usage

In .env (or published config file), set the following variables:

# Required, sort of like a password
ALTCHA_HMAC_KEY=
# Optional, defaults to SHA-256. Can be SHA-1 or SHA-512
# ALTCHA_ALGORITHM="SHA-256"

Out of the box, the package registers a /altcha-challenge endpoint to use you on your frontend.

Frontend

Following the frontend integration, use the following snippet to get a challenge:

<altcha-widget challengeurl="/altcha-challenge"></altcha-widget>

Implementation will be different given your frontend, but here's an example Vue component to use:

<template>
  <altcha-widget challengeurl="/altcha-challenge" @statechange="stateChanged"></altcha-widget>
</template>

<script setup>
import 'altcha'

const emit = defineEmits(['update:modelValue'])
const stateChanged = ev => {
  if (ev.detail.state === 'verified') {
    emit('update:modelValue', ev.detail.payload)
  }
}
</script>

In an Inertja.js form, you could use this component like so:

<template>
  <form @submit.prevent="form.post('/login')">
    <label for="email">Email</label>
    <input type="email" name="email" v-model="form.email">
    
    <label for="password">Password</label>
    <input type="password" name="password" v-model="form.password">
    
    <Altcha v-model="form.token" />
    
    <button type="submit">Submit</button>
  </form>
</template>

<script setup>
import { useForm } from '@inertiajs/inertia-vue3'
// This is the component we made above
import Altcha from '@/components/forms/Altcha.vue'

const form = useForm({
  email: null,
  password: null,
  token: null,
})
</script>

Backend validation

To validate the frontend-generated token/payload, there's a ValidAltcha rule you can use, assuming the token is passed as token in the request:

use GrantHolle\Altcha\Rules\ValidAltcha;

$request->validate([
    'email' => ['required', 'email'],
    'password' => ['required'],
    'token' => ['required', new ValidAltcha],
]);

Bypass validation in tests

To successfully test routes protected by Altcha you can optionally set a testing_bypass value in config/altcha.php, or dynmaclly set it in applicable tests. For example a typical setup might be:

<!-- phpunit.xml -->

<!-- (optionally set a value for all tests) -->
<env name="ALTCHA_TESTING_BYPASS" value="valid"/>

// tests/demoTest.php

it('validates Altcha challenge', function() {
  
    // a "valid" value passes
    $this->post('store-something', [
      'altcha' => config('altcha.testing_bypass')
    ])->assertSessionHasNoErrors();
    
    // but an "invalid" value fails
    $this->post('store-something', [
        'altcha' => 'not valid'
    ])->assertSessionHasErrors('altcha');
    
    // or dynamically set a value for specific tests
    config(['altcha.testing_bypass' => null]);
    
    // still fails because we removed the bypass
    $this->post('store-something', [
        'altcha' => 'valid'
    ])->assertSessionHasErrors('altcha');

});

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

grantholle / laravel-altcha

Maintainers

Details