@gocelestial/indieauth v3.0.2

@gocelestial/indieauth

An Express.js middleware for spec-compliant IndieAuth implementation.

Versioning notes

All tags from v1.0.0 to v1.0.8 are unstable or not functional. Core functionality works post v1.1.0. Production usage is recommended at and after v3.0.0.

Semantic versioning has been followed since v1.1.0, although it wasn't strictly followed until this milestone -- therefore, any previous tags are not considered production-ready.

Usage

session key must be available on the Express request object i.e. you must have a session set up.

Install from the npm registry:

npm i @gocelestial/indieauth

const express = require("express");
const indieauth = require("@gocelestial/indieauth");

const app = express();
indieauth.initialize(indieauthConfig);
app.use("/indieauth", indieauth.router());

Configuration

const indieauthConfig = {
	namespace: {
		/* the keys to take up on req.session: req.session.org.module. */
		org: "gocelestial",
		module: "indieauth",
	},
	routes: {
		/* the prefix you specify in your express app without any slashes, preceding or trailing. */
		prefix: "login",
		redirect: {
			success: "/app"
		}
	},
	auth: {
		/* configuration related to IndieAuth itself */
		/* please note scope is used as-is and must match against the requirements listed under https://indieauth.spec.indieweb.org/#authorization-request */
		scope: 'create',
		/* your domain name, optionally with the port number */
		host: 'http://localhost:5000'
	},
	paths: {
		/* where to find the secret set by your csrfMiddleware. */
		csrfSecret: "req.session.csrfSecret",
	},
	middleware: {
		/* you've probably defined this elsewhere. just pass a reference. */
		csrf: csrfMiddleware,
	},
};

The module redirects to /app on success by default. This is configurable under the routes.redirects.success key.

Form suggestion

<form
	action="/${prefix}/try/"
	method="post"
	enctype="application/x-www-form-urlencoded"
	class="form form--login login-form"
>
	<fieldset>
		<legend>Login</legend>
		<div class="field-group">
			<label for="url">Web Address:</label>
			<p class="field-group__description" id="field-group__description--url">
				If the web address you enter redirects elsewhere, we will follow the
				redirect up to one redirect before calling off our search.
			</p>
			<input
				name="me"
				type="url"
				placeholder="https://yourdomain.com"
				autocomplete="on"
				autofocus
				aria-describedby="field-group__description--url"
				class="login-form__web-address"
				id="url"
			/>
		</div>
	</fieldset>

	<button type="submit">Sign In</button>

	<input name="_csrf" type="hidden" value="{{ csrfToken }}" />
</form>

In particular, you'll need a me input field, a _csrf token field. The form must make a POST url-encoded request to the ${prefix}/try/ route.

Session data

A successful authorization will set the following data on req.session.gocelestial.indieauth:

user: {
	profileUrl: string;
	discoveryUrl: string;
	microformats: {
		name: string;
		photo: string;
	}
},
indieauth: {
	token_type: string;
	scope: string;
	access_token: string;
},
endpoints: {
	micropub: string;
	token: string;
	authorization: string;
}