latchkey-auth

Framework-neutral backend helpers for applications using a Latchkey identity broker.

npm install latchkey-auth

import { createLatchkeyBackend } from "latchkey-auth/server";

const latchkey = createLatchkeyBackend({
  issuer: "https://identity.example",
  redirectUri: "https://app.example/auth/latchkey/callback",
  claims: ["email", "name"],
});

const { authorizationUrl, transaction } = latchkey.beginAuthorization({
  provider: "github",
});

Application callbacks must use HTTPS. Plain HTTP is accepted only for localhost, loopback addresses, and literal 192.168.x.x hosts during local-network development.

To let a person switch Google accounts, opt into Google's standard account chooser for that authorization:

const { authorizationUrl, transaction } = latchkey.beginAuthorization({
  provider: "google",
  prompt: "select_account",
});

Omit prompt for the normal fast returning-user flow.

Keep transaction in server-side session storage. At the callback, pass it to completeAuthorization; the returned identity has already been checked for signature, issuer, audience, expiry, pairwise subject, and nonce.

const { identity, identityToken } = await latchkey.completeAuthorization(
  callbackUrl,
  transaction,
);

Use identity.sub as the application-specific user key, then create an application-owned HttpOnly session. Do not use the Latchkey identity token as a long-lived browser session.

The package also exports createLatchkeyVerifier and extractBearerToken for lower-level integrations. See the Latchkey developer manual for the complete flow.