Metaloot Auth

Drop-in Metaloot auth adapters for browser games.

The package owns the OAuth callback and game session so a game does not need to hand-roll code exchange, signed cookies, session JSON, or sign-in UI state.

On HTTPS, auth cookies default to SameSite=None; Secure so games embedded in the Metaloot portal can establish and read their game session inside an iframe. Local HTTP development keeps SameSite=Lax. Override with cookieSameSite or cookieSecure only when your host requires a custom policy.

Install

npm install @metaloot/auth

Environment

METALOOT_CLIENT_ID=mtl_client_...
METALOOT_CLIENT_SECRET=mtl_secret_...
METALOOT_SESSION_SECRET=replace-with-a-long-random-secret

Register this callback URL in Metaloot:

https://your-game.com/auth/metaloot/callback

Static Node or Express Game

import express from "express";
import { metalootAuth } from "@metaloot/auth/node";

const app = express();

app.use(
  metalootAuth({
    clientId: process.env.METALOOT_CLIENT_ID,
    clientSecret: process.env.METALOOT_CLIENT_SECRET,
    sessionSecret: process.env.METALOOT_SESSION_SECRET,
    redirectUri: "https://your-game.com/auth/metaloot/callback",
  })
);

app.use(
  "/vendor/@metaloot/auth",
  express.static("node_modules/@metaloot/auth/dist")
);
app.use(express.static("public"));
app.listen(process.env.PORT || 3000);

Add the button to the game:

<div id="metaloot-auth"></div>
<script type="module">
  import { mountMetalootAuth } from "/vendor/@metaloot/auth/browser.js";

  mountMetalootAuth("#metaloot-auth", {
    gameName: "Your Game"
  });
</script>

The middleware provides:

GET /auth/metaloot/start
GET /auth/metaloot/callback
GET /auth/metaloot/session
GET /auth/metaloot/logout
POST /auth/metaloot/logout

Next.js App Router

Create app/api/auth/metaloot/[...metaloot]/route.ts:

import { createMetalootRouteHandlers } from "@metaloot/auth/next";

export const { GET, POST } = createMetalootRouteHandlers({
  clientId: process.env.METALOOT_CLIENT_ID!,
  clientSecret: process.env.METALOOT_CLIENT_SECRET!,
  sessionSecret: process.env.METALOOT_SESSION_SECRET!,
  redirectUri: "https://your-game.com/auth/metaloot/callback",
  startPath: "/api/auth/metaloot/start",
  callbackPath: "/api/auth/metaloot/callback",
  sessionPath: "/api/auth/metaloot/session",
  logoutPath: "/api/auth/metaloot/logout",
});

Register the matching callback URL for this example:

https://your-game.com/api/auth/metaloot/callback

Mount the browser button from a client component:

"use client";

import { useEffect, useRef } from "react";
import { mountMetalootAuth } from "@metaloot/auth/browser";

export function MetalootSignIn() {
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!ref.current) return;
    mountMetalootAuth(ref.current, {
      gameName: "Your Game",
      startUrl: "/api/auth/metaloot/start",
      sessionUrl: "/api/auth/metaloot/session",
      logoutUrl: "/api/auth/metaloot/logout",
    });
  }, []);

  return <div ref={ref} />;
}

Read the Session

Browser code can check the current player:

const session = await fetch("/auth/metaloot/session").then((res) => res.json());

if (session.signedIn) {
  console.log(session.user.id, session.user.name);
}

Server code can read a signed session from cookies:

import { getMetalootSessionFromCookieHeader } from "@metaloot/auth/server";

const session = getMetalootSessionFromCookieHeader(request.headers.get("cookie"), {
  clientId: process.env.METALOOT_CLIENT_ID!,
  clientSecret: process.env.METALOOT_CLIENT_SECRET!,
  sessionSecret: process.env.METALOOT_SESSION_SECRET!,
  redirectUri: "https://your-game.com/auth/metaloot/callback",
});

Agent Prompt

Use this when asking an implementation agent to add Metaloot auth:

Install @metaloot/auth and wire Metaloot sign-in.

Do not implement OAuth by hand.

Requirements:
1. Add the Metaloot server adapter for this stack.
2. Configure METALOOT_CLIENT_ID, METALOOT_CLIENT_SECRET, and METALOOT_SESSION_SECRET on the server only.
3. Use /auth/metaloot/start, /auth/metaloot/callback, /auth/metaloot/session, and /auth/metaloot/logout.
4. Mount the browser sign-in button with mountMetalootAuth.
5. On game boot, call the session endpoint and treat signedIn:true as the player being authenticated.
6. Hide or replace any old guest-login, #mlt token, or vendored Metaloot SDK logic.
7. Verify locally and in production that /auth/metaloot/session returns signedIn:true after login.

Publishing

npm login
npm publish --access public

If the @metaloot npm scope is not available on your account, change the package name in package.json before publishing.