IRMA core
This package contains the state machine for implementing IRMA flows. irma-core
itself does not provide any real functionality. Plugins can be registered at
the state machine and the plugins then provide the functionality depending on
the state the state machine is in. The plugins can also request state modifications
to the state machine.
IRMA core can be initialized in the following way:
const IrmaCore = require('@privacybydesign/irma-core');
const irma = new IrmaCore(/* options */);
irma.use(/* Plugin A */);
irma.use(/* Plugin B */);
irma.start();You can pass an options object to the constructor, which will be passed on to each plugin that you register. Each plugin can choose which of your options to use or ignore.
const irma = new IrmaCore({
debugging: true, // Used by state machine and multiple plugins
element: '#irma-web-form' // Used by `irma-web` plugin
});Documentation
More elaborate documentation on how to use this module can be found in the IRMA documentation. You can also find here how to design your own plugin.
API
use method
With the use method, new plugins can be added to the IRMA core instance.
This method takes care of instantiating the plugin. You simply pass the
plugin class as an argument to this function; you must not instantiate
the plugin yourself.
irma.use(/* Plugin A */);
irma.use(/* Plugin B */);
start method
The start method starts the state machine and returns a Promise. Whatever
parameters you pass to the start method get passed to the start method of
the plugins too, but no plugins currently make use of that.
irma.start()
.then(result => console.log("Successful disclosure! 🎉", result))
.catch(error => console.error("Couldn't do what you asked 😢", error));The returned Promise only resolves when the state machine reaches the Success state
and only rejects when the machine reaches a state with a final transaction.
The end states BrowserNotSupported and Aborted always lead to a reject.
The other possible end states are Cancelled, Timeout and Error.
In case none of the plugins supplied a return value via its
close() method (which is the case for all our plugins in the /plugin directory),
the return value on resolve will be the payload of the 'succeed' transition.
In case of reject, the return value indicates in what state the state machine stopped,
so: BrowserNotSupported, Cancelled, Timeout, Error or Aborted.
In case one or more plugins return a value on close(), the return value will be
an array containing the irma-core return value (as described above) as first item
and the return values of the plugins as subsequent items. The order of the
subsequent items is determined by the order in which the plugins were
added with 'use'. Plugins that did not return a value, have the result
undefined then.
irma.start()
.then(result => console.log("Successful disclosure! 🎉", result))
.catch(error => {
if (error === 'Aborted') {
console.log('We closed it ourselves, so no problem 😅');
return;
}
console.error("Couldn't do what you asked 😢", error);
});In the reject case, plugins may already inform the user of this issue, so please test if you need to catch the state yourself. You may wish to fall back to another authentication method automatically by catching the rejection and redirecting the user.
abort method
The abort method forces an irma-core instance to abort the session and
all associated plugins should stop making changes. In this way you can stop
the instance from being active when it is not relevant anymore. The promise
returned by the start method will be rejected with a Aborted message
when abort is called. When start has not been called yet or when the
start promise has already finished, then calling abort has no effect.
irma.abort();