AuthInterface

AuthInterface

Contains all authentication related functionality

Constructor

new AuthInterface()

Source:

Members

registered

Whether or not this is a registered/authenticated session.

Source:
Example
// Assumes SAFEApp interface has been obtained
const isRegistered = app.auth.registered;

Methods

canAccessContainer(name, permissionsopt) → {Promise.<Boolean>}

Whether or not this session has specifc access permission for a given container.

Parameters:
Name Type Attributes Default Description
name String

name of the container, e.g. '_public'
permissions String | Array.<String> <optional>
 ['Read']

permissions to check for
Source:
Example
// Assumes SAFEApp interface has been obtained

const containerPermissions =
{
  _public: ['Read']
};

const asyncFn = async () => {
    try {
        const authReqUri = await app.auth.genAuthUri(
          containerPermissions
        );
        await app.auth.openUri(authReqUri);
        // After URI is opened by SAFE Authenticator and authorised,
        // this snippet assumes that your application has an
        // IPC strategy to receive returned authorisation uri.
        await app.auth.loginFromUri(authUri);
        const container = '_public';
        const permissions = ['Read'];
        const canAccessContainer = await app.auth.canAccessContainer(container, permissions);
    } catch (err) {
        throw err;
    }
};

genAuthUri(permissions, opts) → {Promise.<String>}

Generate an authentication URI for the app with the given permissions and optional parameters.

Parameters:
Name Type Description
permissions Object

mapping the container-names to a list of permissions you want to request
opts Object
Properties
Name Type Attributes Default Description
own_container Boolean <optional>
 false

whether or not to request app's own container to be created
Source:
Example
// Assumes SAFEApp interface has been obtained

const containerPermissions =
{
  _public: [
    'Read',
    'Insert',
    'Update',
    'Delete'
  ],
  _publicNames: [
    'Read',
    'Insert',
    'Update',
    'Delete'
  ]
};
const authorisationOptions = {own_container: true};

const asyncFn = async () => {
    try {
        const authReqUri = await app.auth.genAuthUri(
            containerPermissions,
            authorisationOptions
        );
    } catch (err) {
        throw err;
    }
};

genConnUri() → {Promise.<String>}

Generate an unregistered connection URI for the app, especially for simply browsing and reading data on the network.

Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    const app = await safe.initialiseApp(appInfo);
    try {
        const unRegisteredUri = await app.auth.genConnUri();
    } catch (err) {
        throw err;
    }
};

genContainerAuthUri(containers) → {Promise.<String>}

Generate a safe-auth URI to request further container permissions.

Parameters:
Name Type Description
containers Object

mapping container name to list of permissions
Source:
Example
// Assumes SAFEApp interface has been obtained
const containerPermissions =
{
  _videos: [
    'Insert'
  ]
};

const asyncFn = async () => {
    try {
        const contReqUri = await app.auth.genContainerAuthUri(containerPermissions);
    } catch (err) {
        throw err;
    }
};

genShareMDataUri(permissions) → {Promise.<String>}

Generate a safe-auth URI to request permissions on arbitrary owned MutableData's. Necessary when an authorised app needs access to a MutableData that was created by another application and is also owned by current account.

Parameters:
Name Type Description
permissions Object

mapping the MutableData's XoR names to a list of permissions you want to request
Source:
Example
// Assumes SAFEApp interface has been obtained

const permissions = [
  {
    typeTag: 15001,
    name: mutableDataXorName,
    perms: ['Insert']
  }
];

const asyncFn = async () => {
    try {
        const shareMDataReqUri = await app.auth.genShareMDataUri(permissions);
    } catch (err) {
        throw err;
    }
};

getContainer(name) → {Promise.<MutableData>}

Get interface to MutableData underlying account container.

Parameters:
Name Type Description
name String

name of the container, e.g. '_public'
Source:
Throws:
MISSING_CONTAINER_STRING
Example
// Assumes SAFEApp interface has been obtained

const containerPermissions =
{
  _public: ['Read', 'Insert', 'Update']
};

const asyncFn = async () => {
  try {
    const app = await safe.initialiseApp(appInfo);
    const authReqUri = await app.auth.genAuthUri(containerPermissions);
    await app.auth.openUri(authReqUri);
    // After URI is opened by SAFE Authenticator and authorised,
    // this snippet assumes that your application has an
    // IPC strategy to receive returned authorisation uri.
    await app.auth.loginFromUri(authUri);
    const app = await safe.initialiseApp(appInfo);
    const authReqUri = await app.auth.genAuthUri(
      containerPermissions
    );
    const container = '_public';
    const mutableDataInterface = await app.auth.getContainer(container);
  } catch (err) {
    throw err;
  };
};

getContainersPermissions() → {Promise.<Array>}

Get the names of all containers found and the app's granted permissions for each of them.

Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
        const containerPermissions = await app.auth.getContainersPermissions();
    } catch (err) {
        throw err;
    }
};

getOwnContainer() → {Promise.<MutableData>}

Get the MutableData for the app's root container. When run in tests, this falls back to the randomly generated version

Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
        const authReqUri = await app.auth.genAuthUri({}, { own_container: true });
        await app.auth.openUri(authReqUri);
        // After URI is opened by SAFE Authenticator and authorised,
        // this snippet assumes that your application has an
        // IPC strategy to receive returned authorisation URI.
        await app.auth.loginFromUri(authUri);
        const mutableDataInterface = await app.auth.getOwnContainer();
    } catch (err) {
        throw err;
    }
};

loginForTest() → {Promise.<SAFEApp>}

ONLY AVAILALBE IF RUN in NODE_ENV='test' OR WITH 'forceUseMock' option

Generate a locally registered SAFEApp with the given permissions, or a local unregistered SAFEApp if permissions is null.

Source:

loginFromUri(uri) → {Promise.<SAFEApp>}

Create a new authenticated or unregistered network session using the provided IPC response from SAFE Authenticator.

Parameters:
Name Type Description
uri String

the IPC response string given
Source:
Throws:
MISSING_AUTH_URI
Example
// Assumes SAFEApp interface has been obtained

const asyncFn = async () => {
  try {
    const app = await safe.initialiseApp(appInfo);
    const authReqUri = await app.auth.genAuthUri({});
    await app.auth.openUri(authReqUri);
    // After URI is opened by SAFE Authenticator and authorised,
    // this snippet assumes that your application has an
    // IPC strategy to receive returned authorisation uri.
    await app.auth.loginFromUri(authUri);
  } catch (err) {
    throw err;
  }
};

openUri(uri)

Opens URI with system, using respective registered application.

Parameters:
Name Type Description
uri String

Authententication
Source:
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    const app = await safe.initialiseApp(appInfo);
    try {
        await app.auth.openUri('safe://shouldOpenSafeBrowser');
    } catch (err) {
        throw err;
    }
};

readGrantedPermissions(uri) → {Promise.<Array>}

Read granted containers permissions from an auth URI without the need to connect to the network.

This function appears redundant to app.auth.getContainersPermissions, however the difference is that readGrantedPermissions doesn't require an authorised app connection.

Parameters:
Name Type Description
uri String

the IPC response string given
Source:
Throws:
NON_AUTH_GRANTED_URI
Example
// Assumes SAFEApp interface has been obtained
const asyncFn = async () => {
    try {
        const authReqUri = await app.auth.genAuthUri({});
        await app.auth.openUri(authReqUri);
        const containerPermissions = await app.auth.readGrantedPermissions(
            < returned auth URI from openUri >
        );
    } catch (err) {
        throw err;
    }
};

refreshContainersPermissions() → {Promise}

Refresh the access persmissions from the network. Useful when you just connected or received a response from the authenticator in the IPC protocol.

Source:
Example
// Assumes SAFEApp interface has been obtained
const permissions = {
    _public: ['Read', 'Insert', 'Update', 'Delete', 'ManagePermissions']
};

const asyncFn = async () => {
    try {
        const authReqUri = await app.auth.genAuthUri(permissions, {});
        let authUri = await safe.authorise(authReqUri);
        await app.auth.refreshContainersPermissions();
        const mData = await app.auth.getContainer('_public');
        let permsObject = await app.auth.getContainersPermissions();

        console.log(permsObject);

        const updatePermissions = {
          _publicNames: ['Read', 'Insert', 'Update', 'Delete', 'ManagePermissions']
        }
        let contReqUri = await app.auth.genContainerAuthUri(updatePermissions);
        authUri = await safe.authorise(contReqUri);

        console.log(permsObject);

        await app.auth.refreshContainersPermissions();
        permsObject = await app.auth.getContainersPermissions();

        console.log(permsObject);
    } catch (err) {
       throw err;
    }
};

simulateNetworkDisconnect() → {Promise}

ONLY AVAILALBE IF RUN in NODE_ENV='test' OR WITH 'forceUseMock' option

Simulates a network disconnection event. This can be used to test any logic to be executed by an application when a network diconnection notification is received.

Source:
Throws:
NON_DEV