Masto Auth

A simple library for authenticating against mastodon.

Doesn't provide API access, only verifies who the user is.

Use it to provide OIDC-like auth/login services for mastodon users on your own site.

If you need integration with the mastodon API, try looking at a mastodon API client instead.

import Auth, {UnregisteredClientError} from 'masto-auth';

// Provide a name for your client and the URL to redirect to after the user has authenticated on mastodon.
const clientOptions = {
	client_name: 'My app',
	redirect_uri: 'http://example.com/auth'
}

// Register one or more clients
// Serialise with toJSON and save the details somewhere
// like a database or environment variable
const ms = (await Auth.register('https://mastodon.social', clientOptions)).toJSON();
const kk = (await Auth.register('https://kith.kitchen', clientOptions)).toJSON();

// Create an instance of Auth with a function that retrieves your clients
const auth = new Auth(url => {
	switch(url){
		case: 'https://mastodon.social':
			return ms;
		case: 'https://kith.kitchen':
			return kk;
		default:
			// If no client matches, return null to throw an UnregisteredClientError
			return null;
	}
});

export default async (req, res) => {
	const { pathname } = new URL('file://' + req.url);

	// Get the login URL for each client -
	// here I've hard-coded the instance URLs but
	// you could use a form input to get them from the user
	if(pathname === '/login/kith.kitchen') {
		res.end(await auth.getRedirectUrl('https://kith.kitchen'));
	} else if(pathname === '/login/mastodon.social') {
		res.end(await auth.getRedirectUrl('https://mastodon.social'));

	// This is the auth endpoint we specified in clientOptions - get the user object and do whatever you want with it.
	} else if(pathname === '/auth') {
		res.end(JSON.stringify(await auth.getUserFromCallback(req)))
	}
}

Dependencies

• masto-id-connect: ^1.1.1

masto-auth

• masto-auth
  • .Issuer
  • .Client
  • .default
    • new module.exports(getClient)
    • instance
      • .getRedirectUrl(url) ⇒ string
      • .getUserInfo(url, code) ⇒ Object
      • .getUserFromCallback(req) ⇒ Object
    • static
      • .register(url, options) ⇒ Client
  • .UnregisteredClientError

masto-auth.Issuer

Class representing the mastodon instance

Kind: static class of masto-auth

masto-auth.Client

Class representing an app registration against the instance's API

Kind: static class of masto-auth

masto-auth.default

Manage mastodon authentication

Kind: static class of masto-auth

• .default
  • new module.exports(getClient)
  • instance
    • .getRedirectUrl(url) ⇒ string
    • .getUserInfo(url, code) ⇒ Object
    • .getUserFromCallback(req) ⇒ Object
  • static
    • .register(url, options) ⇒ Client

new module.exports(getClient)

Create a new instance of Auth

| Param | Type | Description | | --- | --- | --- | | getClient | function | Function that returns the serialized client (i.e. the result of calling Client#toJSON) |

default.getRedirectUrl(url) ⇒ string

Get the authentication URL for an issuer

Kind: instance method of default

| Param | Type | Description | | --- | --- | --- | | url | string | URL of issuer |

default.getUserInfo(url, code) ⇒ Object

Get the user info object for a user who has obtained an authentication code

Kind: instance method of default

| Param | Type | Description | | --- | --- | --- | | url | string | The URL of the issuer | | code | string | The code returned from the user auth flow |

default.getUserFromCallback(req) ⇒ Object

Get the user info object from an auth callback request. Parse the issuer url and code from a callback request and call getUserInfo

Kind: instance method of default

| Param | Type | Description | | --- | --- | --- | | req | http.IncommingRequest | Callback request |

default.register(url, options) ⇒ Client

Register with a mastodon instance and return a new instance of Client

Kind: static method of default

| Param | Type | Description | | --- | --- | --- | | url | string | The URL of the mastodon instance (any part other than the origin will be ignored) | | options | Object | Client options | | options.redirectUri | string | The URI to redirect the user to after they have authenticated on their mastodon instance. | | options.clientName | string | The name of your application |

masto-auth.UnregisteredClientError

Error thrown when no client can be found for a given issuer

Kind: static class of masto-auth