feat(auth): add ChulaSSO 2.0 login (uni-gated)

ChulaSSO is Chulalongkorn University's SSO — a custom ticket flow, NOT OIDC,
so Kutt's built-in OIDC can't talk to it. This adds a native integration:

- GET /login/chulasso/start -> redirect to ChulaSSO with our callback as `service`
- GET /login/chulasso       -> validate the returned ticket via
  POST /serviceValidation (DeeAppId/DeeAppSecret/DeeTicket), then find-or-create
  a verified user and issue the Kutt session (mirrors the OIDC handler).
- Optional CHULASSO_ALLOWED_ROLES gate (e.g. student,faculty); empty = any Chula account.
- "Login with ChulaSSO" button on the login page; login_disabled exempts ChulaSSO.
- New CHULASSO_* env, documented in .example.env. Pure role-check helper + unit test.

CI: build/push ghcr.io/isd-sgcu/kutt; drop the upstream Docker Hub workflows.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: bankworached

.example.env

@@ -98,3 +98,16 @@ OIDC_CLIENT_ID=
 OIDC_CLIENT_SECRET=
 OIDC_SCOPE=
 OIDC_EMAIL_CLAIM=
+
+# Optional - Login with ChulaSSO 2.0 (Chulalongkorn University; custom ticket flow, not OIDC)
+# Register an app at https://account.it.chula.ac.th to get app_id/app_secret, and add
+# this site's base URL (e.g. https://chula.me/) as an allowed Service URL prefix.
+# Callback is {DEFAULT_DOMAIN}/login/chulasso. First login auto-creates a verified user.
+CHULASSO_ENABLED=false
+CHULASSO_BASE=https://account.it.chula.ac.th
+CHULASSO_APP_ID=
+CHULASSO_APP_SECRET=
+# Comma-separated roles allowed in (e.g. student,faculty). Empty = any Chula account.
+CHULASSO_ALLOWED_ROLES=
+# Display name shown on the ChulaSSO grant screen. Empty = SITE_NAME.
+CHULASSO_SERVICE_NAME=

.github/workflows/docker-build-development.yaml

@@ -0,0 +1,41 @@
+name: Build & push image (ghcr.io/isd-sgcu)
+
+on:
+  push:
+    branches: [main, "feat/**"]
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  image:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/isd-sgcu/kutt
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=sha,format=short
+            type=raw,value=latest,enable={{is_default_branch}}
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/docker-build-latest.yaml

@@ -68,6 +68,13 @@ const spec = {
   OIDC_CLIENT_SECRET: str({ default: "" }),
   OIDC_SCOPE: str({ default: "openid profile email" }),
   OIDC_EMAIL_CLAIM: str({ default: "email" }),
+  // ChulaSSO 2.0 (custom ticket flow — not OIDC). See server/handlers/chulasso.handler.js
+  CHULASSO_ENABLED: bool({ default: false }),
+  CHULASSO_BASE: str({ default: "https://account.it.chula.ac.th" }),
+  CHULASSO_APP_ID: str({ default: "" }),
+  CHULASSO_APP_SECRET: str({ default: "" }),
+  CHULASSO_ALLOWED_ROLES: str({ default: "" }),   // csv e.g. "student,faculty"; empty = any Chula account
+  CHULASSO_SERVICE_NAME: str({ default: "" }),     // grant-screen name; defaults to SITE_NAME
   ENABLE_RATE_LIMIT: bool({ default: false }),
   REPORT_EMAIL: str({ default: "" }),
   CONTACT_EMAIL: str({ default: "" }),

.github/workflows/docker-build-release.yaml

@@ -0,0 +1,81 @@
+// ChulaSSO 2.0 authentication (custom ticket flow — NOT OIDC).
+// Docs: https://account.it.chula.ac.th/html/docs
+//   1. Redirect the browser to {BASE}/login?service={callback}&app_id={id}
+//   2. ChulaSSO redirects back to {callback}?ticket={id}
+//   3. Validate server-side: POST {BASE}/serviceValidation with headers
+//      DeeAppId / DeeAppSecret / DeeTicket -> JSON profile { email, roles, ... }
+// On success we find-or-create a verified Kutt user (mirrors the OIDC handler
+// in passport.js) and issue the normal Kutt session cookie.
+const bcrypt = require("bcryptjs");
+
+const { roleAllowed } = require("./chulasso.util");
+const query = require("../queries");
+const utils = require("../utils");
+const env = require("../env");
+
+const CustomError = utils.CustomError;
+
+// Step 1 — send the browser to ChulaSSO with our callback as `service`.
+async function start(req, res) {
+  const params = new URLSearchParams({
+    service: utils.getSiteURL() + "/login/chulasso",
+    app_id: env.CHULASSO_APP_ID,
+    serviceName: env.CHULASSO_SERVICE_NAME || env.SITE_NAME,
+  });
+  res.redirect(`${env.CHULASSO_BASE}/login?${params.toString()}`);
+}
+
+// Step 3 — validate the returned ticket and log the user in.
+async function callback(req, res) {
+  const ticket = req.query.ticket;
+  if (!ticket) {
+    throw new CustomError("ChulaSSO did not return a ticket.", 400);
+  }
+
+  const response = await fetch(`${env.CHULASSO_BASE}/serviceValidation`, {
+    method: "POST",
+    headers: {
+      DeeAppId: env.CHULASSO_APP_ID,
+      DeeAppSecret: env.CHULASSO_APP_SECRET,
+      DeeTicket: String(ticket),
+    },
+  });
+
+  if (!response.ok) {
+    throw new CustomError("ChulaSSO ticket validation failed.", 401);
+  }
+
+  const profile = await response.json();
+  const email = profile && profile.email;
+  if (!email) {
+    throw new CustomError("ChulaSSO profile did not include an email.", 400);
+  }
+
+  if (!roleAllowed(profile.roles, env.CHULASSO_ALLOWED_ROLES)) {
+    throw new CustomError("Your Chula account is not permitted to use this service.", 403);
+  }
+
+  let user = await query.user.find({ email });
+
+  // First login for this account: create it, pre-verified (no email/password flow).
+  if (!user) {
+    const salt = await bcrypt.genSalt(12);
+    const password = await bcrypt.hash(utils.generateRandomPassword(), salt);
+    const created = await query.user.add({ email, password });
+    user = await query.user.update(created, {
+      verified: true,
+      verification_token: null,
+      verification_expires: null,
+    });
+  }
+
+  if (user.banned) {
+    throw new CustomError("You're banned from using this website.", 403);
+  }
+
+  const token = utils.signToken(user);
+  utils.setToken(res, token);
+  res.redirect("/");
+}
+
+module.exports = { start, callback, roleAllowed };

.github/workflows/ghcr-isd.yaml

@@ -0,0 +1,17 @@
+// Pure, dependency-free helpers for the ChulaSSO integration so they can be
+// unit-tested without loading env/db. See chulasso.util.test.js.
+
+// Does the authenticated user's roles satisfy the allow-list?
+// allowedCsv blank/empty => any authenticated Chula account is allowed.
+function roleAllowed(roles, allowedCsv) {
+  const allow = String(allowedCsv || "")
+    .split(",")
+    .map(r => r.trim().toLowerCase())
+    .filter(Boolean);
+  if (allow.length === 0) return true;
+  const have = (Array.isArray(roles) ? roles : [])
+    .map(r => String(r).trim().toLowerCase());
+  return have.some(r => allow.includes(r));
+}
+
+module.exports = { roleAllowed };

server/env.js

@@ -0,0 +1,21 @@
+// Run: node server/handlers/chulasso.util.test.js
+const assert = require("node:assert");
+const { roleAllowed } = require("./chulasso.util");
+
+// empty allow-list => any authenticated account is allowed
+assert.strictEqual(roleAllowed(["student"], ""), true);
+assert.strictEqual(roleAllowed([], ""), true);
+assert.strictEqual(roleAllowed(undefined, ""), true);
+
+// allow-list set => must intersect
+assert.strictEqual(roleAllowed(["student"], "student,faculty"), true);
+assert.strictEqual(roleAllowed(["faculty"], "student,faculty"), true);
+assert.strictEqual(roleAllowed(["alumni"], "student,faculty"), false);
+assert.strictEqual(roleAllowed([], "student"), false);
+assert.strictEqual(roleAllowed(undefined, "student"), false);
+
+// case + whitespace tolerant
+assert.strictEqual(roleAllowed(["Student"], " student "), true);
+assert.strictEqual(roleAllowed(["STUDENT"], "student"), true);
+
+console.log("chulasso.util ok");

server/handlers/chulasso.handler.js

@@ -28,8 +28,9 @@ function config(req, res, next) {
   res.locals.server_cname_address = env.SERVER_CNAME_ADDRESS;
   res.locals.disallow_registration = env.DISALLOW_REGISTRATION;
   res.locals.disallow_login_form = env.DISALLOW_LOGIN_FORM;
-  res.locals.login_disabled = env.DISALLOW_LOGIN_FORM && !env.OIDC_ENABLED;
+  res.locals.login_disabled = env.DISALLOW_LOGIN_FORM && !env.OIDC_ENABLED && !env.CHULASSO_ENABLED;
   res.locals.oidc_enabled = env.OIDC_ENABLED;
+  res.locals.chulasso_enabled = env.CHULASSO_ENABLED;
   res.locals.mail_enabled = env.MAIL_ENABLED;
   res.locals.report_email = env.REPORT_EMAIL;
   res.locals.custom_styles = utils.getCustomCSSFileNames();