gdpr-guard

gdpr-guard

Simple GDPR manager

This library helps you build a GPDR compliant system by providing you easy to manipulate interfaces.

If you need any help, you're more than welcome on my official Discord server dedicated to my open-source projects.

How to import

Using ES6-style imports:

import {
    //most useful
    GdprStorage,
    GdprManagerBuilder,
    GdprDeserializer,

    //helpers
    makeGuard,
    GdprGuardGroup,
    GdprManager,
    GdprSerializer,
    GdprSaviorAdapter,
} from "gdpr-guard"

Using node style require:

const {
    //most useful
    GdprStorage,
    GdprManagerBuilder,
    GdprDeserializer,

    //helpers
    makeGuard,
    GdprGuardGroup,
    GdprManager,
    GdprSerializer,
    GdprSaviorAdapter,
} = require("gdpr-guard");

Directly from your browser:

const {
    //most useful
    GdprStorage,
    GdprManagerBuilder,
    GdprDeserializer,

    //helpers
    makeGuard,
    GdprGuardGroup,
    GdprManager,
    GdprSerializer,
    GdprSaviorAdapter,
} = gdprGuard;

What are the essential design choices to keep in mind

The name used for guards and groups must be unique! This is the identifier/key that binds it.

The wide concept of guard is that a guard is an entity that can be toggled to allow/deny some functionalities.

What is provided?

You can check the documentations here

GdprStorage

This is an enum-like type that lists the available storage options, these include:

• None
• Cookie
• LocalStorage
• SessionStorage
• IndexedDb
• FileSystem
• ServerStorage
• All

GdprManagerBuilder

GdprManagerBuilder provides a nice and easy to write/read way to create a GdprManager object from the groun up.

For instance you can use it like this:

const manager = GdprManagerBuilder.make()
.startRequiredGroup(GdprStorage.Cookie, "Functionalities", "Information purely used for the user's experience")
// This is a group that by default uses cookies for storage, every option and the group itself is required
    .withEnabledGuard("PHP_SESSID", "Server session identifier")
    .startGuard()
        .withName("theme")
        .withDescription("User's current colors' theme")
        .storedIn(GdprStorage.LocalStorage)
    .endGuard()
.endGroup()
.startGroup(GdprStorage.Cookie, "Advertisement", "Tracking-based avertisement informations")
    .startGroup(GdprStorage.Cookie, "Advertisement : Local", "Sitewide advertisement informations")
        // [...]
    .endGroup()
    .startGroup(GdprStorage.Cookie, "Advertisement : 3rd-party", "3rd-party advertisement informations")
        // [...]
    .endGroup()
.build();

console.log(manager.raw()); // inspect useful information

GdprDeserializer

GdprDeserializer allows you to retrieve a gdpr object from its raw representation.

import { GdprManagerBuilder, GdprDeserializer } from "gdpr-guard"

// [...]

const manager = GdprManagerBuilder.make()
	// [...]
.build();

const raw = manager.raw();
//store in local storage

const raw = //get from local storage
const manager = GdprDeserializer.manager(raw);
if(manager === null){ //failed deserialization
    //handle error
    return;
}

// here, both managers are equivalent

GdprManager

A GdprManager manages a list of GdprGuardGroup. You can :

• get its most useful representation (raw())
• add or create groups (respectively addGroup(guardGroup) and createGroup(name, description))
• determine whether or not there is a specific guard (hasGuard(name))
• retrieve a specific guard (getGuard(name))
• determine whether or not there is a specific group (hasGroup(name))
• get a specific group (getGroup(name))
• determine if a guard/group is enabled (isEnabled(name))
• enable everything except required (enable())
• disable everything except required (disable())
• toggle state, i.e. either enable all or disable all (toggle())
• enable everything for a given storage (enableForStorage(gdprStorage))
• disable everything for a given storage (disableForStorage(gdprStorage))
• toggle state for a given storage (toggleForStorage(gdprStorage))

GdprGuardGroup

A GdprGuardGroup manages a list of GdprGuard (which includes raw guards, GdprGuardGroup and GdprManager although one would not recommend to put managers inside managers).

You can:

• mark it as required, with every of its guards (makeRequired())
• get its most useful representation (raw())
• determine whether or not there is a specific guard (hasGuard(name))
• retrieve a specific guard (getGuard(name))
• determine if a guard/group is enabled (isEnabled(name))
• enable everything except required (enable())
• disable everything except required (disable())
• toggle state, i.e. either enable all or disable all (toggle())
• enable everything for a given storage (enableForStorage(gdprStorage))
• disable everything for a given storage (disableForStorage(gdprStorage))
• toggle state for a given storage (toggleForStorage(gdprStorage))

makeGuard

makeGuard is a function that creates the simplest guard possible, it has the following signature:

declare function makeGuard(name: string, description: string, storage?: GdprStorage, required?: boolean, enabled?: boolean | null): GdprGuard;

GdprSaviorAdapter

A class that implements most of the behavior for the Savior API.

abstract class GdprSaviorAdapter implements GdprSavior{
	public abstract restore(shouldUpdate?: boolean): Promise<GdprManager|null>;
	public abstract store(manager: GdprManagerRaw): Promise<boolean>;
	public abstract updateSharedManager(manager: GdprManager): Promise<void>;
}

Savior API

This API helps saving and restoring the manager state. It is exposed mainly for library authors as it helps creating various bindings for frameworks.

This is the interface:

interface GdprSavior{
	restore(shouldUpdate?: boolean): Promise<GdprManager|null>;
	exists(shouldUpdate?: boolean): Promise<boolean>;
	restoreOrCreate(factory: GdprManagerFactory): Promise<GdprManager>;
	store(manager: GdprManagerRaw): Promise<boolean>;
	storeIfNotExists(manager: GdprManagerRaw): Promise<boolean>;
	updateSharedManager(manager: GdprManager): Promise<void>;
	check(): Promise<void>;
}