Sign-in and sessions

auth:
  key: secret:AUTH_KEY            # signs sessions; required in production
  methods: [passkeys, whatsapp]
  passkeys:
    origins: ["https://app.example.com"]

auth:
  key: secret:AUTH_KEY                 # master secret; previous-keys: [secret:OLD_KEY] rotates it
  methods: [passkeys, password, whatsapp, oauth, sso, link]
  signup: open                         # open | closed
  passkeys:
    origins: ["https://app.example.com"]
    user-verification: required        # required | preferred
  whatsapp:
    driver: whatsapp-cloud             # whatsapp-cloud | bird | msg91
    ttl: 5m
    max-tries: 5
    limits: { per-phone: 3, per-ip: 10, window: 10m }
  oauth:
    google: { preset: oidc, issuer: https://accounts.google.com, client-id: "...", key: secret:GOOGLE_SECRET }
  sso: { default-role: member, jit: true }
  session: { ttl: 15m, refresh: 7d }
  recovery: { wait: 24h }
  admin: { roles: [admin, support], require: phishing-resistant }
  orgs:
    invites: { expires: 7d }
    domains: { auto-join: true }
  risk:
    mode: enforce                      # observe | enforce
    step-up: [passkeys, whatsapp]
    breached: { driver: hibp }         # opt in; off unless set

auth:
  methods: [whatsapp, passkeys]

import { auth, problem } from "mainsdk";

export async function DELETE(req: Request) {
  try {
    const session = await auth.require(req, {
      role: "owner",
      aal: "aal2",        // phishing-resistant, or two factors
      fresh: "5m",        // signed in within the last five minutes
    });
    return Response.json({ by: session.user });
  } catch (err) {
    return problem(err);
  }
}

import { auth } from "mainsdk";

export async function POST(req: Request) {
  const { email, password } = (await req.json()) as { email: string; password: string };
  const issued = await auth.passwords.signIn(req, { email, password });
  const res = Response.json({ user: issued.user });
  for (const c of issued.cookies) res.headers.append("set-cookie", c);
  return res;
}

import { auth, type RegistrationResponse } from "mainsdk";

export async function POST(req: Request) {
  const session = await auth.require(req);
  const body = (await req.json()) as Partial<RegistrationResponse>;
  if (!body.challengeId) {
    return Response.json(await auth.passkeys.registerOptions(session, { conditional: false }));
  }
  const passkey = await auth.passkeys.register(session, body as RegistrationResponse);   // { challengeId, response }
  return Response.json({ id: passkey.id });
}

import { auth, type AssertionResponse } from "mainsdk";

export async function GET() {
  return Response.json(await auth.passkeys.signInOptions());      // no credential list: autofill works
}

export async function POST(req: Request) {
  const { challengeId, id, response } = (await req.json()) as AssertionResponse;
  const issued = await auth.passkeys.signIn(req, { challengeId, id, response });
  const res = Response.json({ user: issued.user, aal: issued.aal });   // "aal2"
  for (const c of issued.cookies) res.headers.append("set-cookie", c);
  return res;
}

import { auth } from "mainsdk";

const grant = await auth.device.start({ scope: "cli" });
console.log(`Open ${grant.verificationUri} and enter ${grant.code} (expires in ${grant.expiresIn}s)`);

// the device polls with the secret deviceCode, never with the code the person types
const result = await auth.device.poll(grant.deviceCode);
if (result.status === "approved") console.log("signed in as", result.session.user);

"use server";
import { auth } from "mainsdk";

export async function sendCode(req: Request, phone: string) {
  const { challengeId } = await auth.whatsapp.send(phone, { req });
  return challengeId;
}

export async function verifyCode(req: Request, challengeId: string, code: string) {
  return auth.whatsapp.verify(challengeId, code, { req });   // throws MAIN-AUTH-0006 on reuse, expiry or too many tries
}

import { auth } from "mainsdk";

export async function POST(req: Request) {
  const { email } = (await req.json()) as { email: string };
  const issued = await auth.link.issue({ email }, { req, bind: "browser" });
  const res = new Response(null, { status: 202 });                 // 202 whether or not there is an account
  for (const c of issued?.cookies ?? []) res.headers.append("set-cookie", c);
  // send issued.token to the person by email
  return res;
}

export async function PUT(req: Request) {
  const { token } = (await req.json()) as { token: string };
  const issued = await auth.link.verify(req, token);               // MAIN-AUTH-0046 if used, expired or in another browser
  const res = Response.json({ user: issued.user });
  for (const c of issued.cookies) res.headers.append("set-cookie", c);
  return res;
}

import { auth } from "mainsdk";

export async function GET() {
  const { url, cookies } = await auth.oauth.start("google", { redirectUri: "https://app.example.com/auth/callback" });
  const res = new Response(null, { status: 302, headers: { location: url } });
  for (const c of cookies) res.headers.append("set-cookie", c);
  return res;
}

import { auth } from "mainsdk";

export async function GET(req: Request) {
  const issued = await auth.oauth.callback(req);                    // MAIN-AUTH-0007 on a bad state, nonce or token
  const res = new Response(null, { status: 302, headers: { location: issued.returnTo ?? "/" } });
  for (const c of issued.cookies) res.headers.append("set-cookie", c);
  return res;
}

import { auth, MainError } from "mainsdk";

export async function POST(req: Request) {
  const { email, password } = (await req.json()) as { email: string; password: string };
  try {
    const issued = await auth.passwords.signIn(req, { email, password });
    const res = Response.json({ user: issued.user });
    for (const c of issued.cookies) res.headers.append("set-cookie", c);
    return res;
  } catch (err) {
    if (err instanceof MainError && err.code === "MAIN-AUTH-0050") {
      return Response.json(err.toProblem(), { status: 401 });      // { stepUp, pending, challenge }
    }
    throw err;
  }
}

import { auth } from "mainsdk";

export async function POST(req: Request) {
  const { pending, challenge, challengeId, code } = (await req.json()) as { pending: string; challenge: string; challengeId: string; code: string };
  const issued = await auth.stepUp.complete(req, { pending, challenge, method: "whatsapp", challengeId, code });
  const res = Response.json({ aal: issued.aal });                   // "aal2"
  for (const c of issued.cookies) res.headers.append("set-cookie", c);
  return res;
}

import { auth } from "mainsdk";

export async function GET(req: Request) {
  const session = await auth.require(req);
  return Response.json(await auth.devices(session.user));
}

export async function DELETE(req: Request) {
  const session = await auth.require(req, { fresh: "5m" });
  const { deviceId } = (await req.json()) as { deviceId: string };
  await auth.devices.revoke(session.user, deviceId);   // its sessions end on the next request
  return new Response(null, { status: 204 });
}

import { auth, type Session } from "mainsdk";

export async function recover(req: Request, userId: string, code: string, session: Session) {
  const { challengeId } = await auth.recover(userId, { via: "whatsapp", req });
  const { recovery, notBefore } = await auth.recover.confirm(challengeId, code);   // notBefore is 24 hours out
  await auth.recover.cancel(session);                  // from an existing device, inside the window
  return { back: await auth.recover.complete(req, recovery), notBefore };   // MAIN-AUTH-0019 until the wait has ended
}

import { Hono } from "hono";
import { auth } from "mainsdk";

const app = new Hono();

app.post("/orgs/:org/sso", async (c) => {
  const session = await auth.require(c.req.raw, { role: "owner" });
  const scim = await auth.handle(c.req.raw, async () => {
    await auth.sso.enable({
      protocol: "oidc",
      issuer: "https://idp.pinecart.com",
      clientId: "pinecart-app",
      clientSecret: "secret:PINECART_OIDC_SECRET",     // a secret reference, never the value
      domains: ["pinecart.com"],
    });
    return auth.scim.enable({ groupRoles: { eng: "editor", finance: "viewer" } });
  });
  return c.json({ by: session.user, scimEndpoint: scim.endpoint, scimToken: scim.token });
});

app.post("/sign-in/sso", async (c) => {
  const { email } = (await c.req.raw.json()) as { email: string };
  const { url, cookies } = await auth.sso.signIn({ email }, { redirectUri: "https://app.example.com/auth/sso" });
  const res = new Response(null, { status: 302, headers: { location: url } });
  for (const cookie of cookies) res.headers.append("set-cookie", cookie);
  return res;
});

app.get("/auth/sso", async (c) => {
  const issued = await auth.sso.callback(c.req.raw);   // MAIN-AUTH-0007 on a mismatched state or nonce
  const res = new Response(null, { status: 302, headers: { location: issued.returnTo ?? "/" } });
  for (const cookie of issued.cookies) res.headers.append("set-cookie", cookie);
  return res;
});

export default app;

import { auth } from "mainsdk";

export async function enableSaml(acmeMetadataXml: string) {
  await auth.sso.enable("acme", {
    protocol: "saml",
    metadata: acmeMetadataXml,            // the XML, or an https URL it is read from
    domains: ["acme.com"],
    // entityId: "https://app.example.com/saml/acme"   // defaults to urn:mainsdk:sp:<organisation id>
  });
}

import { Hono } from "hono";
import { auth } from "mainsdk";

const app = new Hono();

// GET /auth/saml/metadata?org=acme: paste this into the IdP (or give it the URL)
app.get("/auth/saml/metadata", async (c) => {
  const org = new URL(c.req.raw.url).searchParams.get("org")!;
  const xml = await auth.sso.saml.metadata(org, { acsUrl: "https://app.example.com/auth/saml/acs" });
  return new Response(xml, { headers: { "content-type": "application/samlmetadata+xml" } });
});

// POST /auth/saml/acs: the IdP posts its response here
app.post("/auth/saml/acs", async (c) => {
  const issued = await auth.sso.saml.acs(c.req.raw);   // MAIN-AUTH-0008, with a `reason`, on any refusal
  const res = new Response(null, { status: 302, headers: { location: issued.returnTo ?? "/" } });
  for (const cookie of issued.cookies) res.headers.append("set-cookie", cookie);
  return res;
});

export default app;

import { auth } from "mainsdk";

export async function POST(req: Request) {
  const { name } = (await req.json()) as { name: string };
  const org = await auth.handle(req, () => auth.orgs.create({ name, region: "eu" }));   // the creator becomes owner
  return Response.json(org);
}

export async function GET(req: Request) {
  return Response.json(await auth.handle(req, () => auth.orgs.list()));   // personal and org tenants this person belongs to
}

export async function PUT(req: Request) {
  const { tenantId } = (await req.json()) as { tenantId: string };
  return Response.json(await auth.orgs.switch(req, tenantId));   // 404 MAIN-TENANT-0002 if not a member
}

import { auth } from "mainsdk";

export async function manage(req: Request, userId: string) {
  await auth.handle(req, async () => {
    const page = await auth.members.list({ limit: 50 });         // { items }
    await auth.members.setRoles(userId, ["admin"]);
    await auth.members.remove(userId);                           // the last owner cannot go: MAIN-AUTH-0043

    const eng = await auth.teams.create("eng");
    await auth.teams.add(eng.id, userId);
    await auth.teams.list();
    await auth.teams.remove(eng.id, userId);
    return page;
  });
}

import { auth } from "mainsdk";

export async function POST(req: Request) {
  const { email } = (await req.json()) as { email: string };
  const invite = await auth.handle(req, () => auth.invites.create({ email, roles: ["member"], expiresIn: "7d" }));
  return Response.json({ id: invite.id, url: invite.url, expiresAt: invite.expiresAt });
}

export async function PUT(req: Request) {
  const token = new URL(req.url).searchParams.get("invite")!;     // the link opens your app with ?invite=<token>
  return Response.json(await auth.invites.accept(req, token));     // the person joins with the invited roles
}

export async function DELETE(req: Request) {
  const { inviteId } = (await req.json()) as { inviteId: string };
  await auth.handle(req, () => auth.invites.revoke(inviteId));
  return new Response(null, { status: 204 });
}

import { auth } from "mainsdk";

export async function verifyDomain(req: Request) {
  await auth.handle(req, async () => {
    const proof = await auth.domains.add("acme.com");                  // { record, value }: publish this TXT record
    await auth.domains.verify("acme.com");                             // MAIN-AUTH-0042 until the record is found
    await auth.domains.autoJoin("acme.com", { role: "member" });       // or false to turn it off
    await auth.sso.require({ except: ["owner"] });                     // others get MAIN-AUTH-0044 without SSO
    return proof;
  });
}

{
  "type": "https://mainsdk.dev/errors/MAIN-AUTH-0001",
  "title": "Not signed in",
  "status": 401,
  "code": "MAIN-AUTH-0001",
  "fix": "Sign in, then retry; the session cookie is missing, expired or revoked",
  "retryable": false,
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";
import { auth, problem } from "mainsdk";

// the handler under test, as in app/api/me/route.ts
async function GET(req: Request) {
  try {
    const session = await auth.require(req);
    return Response.json({ user: session.user });
  } catch (err) {
    return problem(err);
  }
}

describe("GET /api/me", () => {
  it("auth AC1 refuses a request with no session and accepts one", async () => {
    createTestApp({
      yaml: "schema: 1\nproject: shop\nauth:\n  methods: [password]\n",
    });
    const none = await GET(new Request("http://localhost/api/me"));
    assert.equal(none.status, 401);
    assert.equal(((await none.json()) as { code: string }).code, "MAIN-AUTH-0001");

    const issued = await auth.passwords.register(new Request("http://localhost/"), {
      email: "jane@x.com",
      password: "correct horse battery",
    });
    const cookie = issued.cookies.map((c) => c.split(";")[0]).join("; ");
    const ok = await GET(new Request("http://localhost/api/me", { headers: { cookie } }));
    assert.equal(ok.status, 200);
  });
});