@lamalibre/create-lamaste 4.0.0

package/vendor/serverd/src/lib/totp.js

@@ -0,0 +1,76 @@
+import crypto from 'node:crypto';
+import { base32Decode, generateTotpSecret } from './authelia.js';
+
+/**
+ * Generate a 6-digit TOTP code for a given secret and time step (RFC 6238 / RFC 4226).
+ *
+ * @param {string} secretBase32 - Base32-encoded secret
+ * @param {number} timeStep - The time step counter value
+ * @returns {string} 6-digit zero-padded code
+ */
+export function generateCode(secretBase32, timeStep) {
+  const key = base32Decode(secretBase32);
+  const timeBuffer = Buffer.alloc(8);
+  // Write 64-bit big-endian counter
+  timeBuffer.writeUInt32BE(Math.floor(timeStep / 0x100000000), 0);
+  timeBuffer.writeUInt32BE(timeStep >>> 0, 4);
+
+  const hmac = crypto.createHmac('sha1', key).update(timeBuffer).digest();
+  const offset = hmac[hmac.length - 1] & 0x0f;
+  const code =
+    ((hmac[offset] & 0x7f) << 24) |
+    ((hmac[offset + 1] & 0xff) << 16) |
+    ((hmac[offset + 2] & 0xff) << 8) |
+    (hmac[offset + 3] & 0xff);
+
+  return String(code % 1000000).padStart(6, '0');
+}
+
+// Replay protection: track recently used codes per RFC 6238 Section 5.2.
+// Key = "code:timeStep", purged after 90s (covers the full +/- 1 step window).
+const usedCodes = new Map();
+const USED_CODE_TTL_MS = 90_000;
+
+function pruneUsedCodes() {
+  const now = Date.now();
+  for (const [key, ts] of usedCodes) {
+    if (now - ts > USED_CODE_TTL_MS) usedCodes.delete(key);
+  }
+}
+
+/**
+ * Verify a TOTP code against the secret, allowing +/- 1 time step (30s each = 60s window).
+ * Each code can only be used once (replay protection per RFC 6238 Section 5.2).
+ *
+ * @param {string} secretBase32 - Base32-encoded secret
+ * @param {string} code - The 6-digit code to verify
+ * @returns {boolean}
+ */
+export function verifyTotp(secretBase32, code) {
+  const now = Math.floor(Date.now() / 1000);
+  const period = 30;
+  const currentStep = Math.floor(now / period);
+
+  for (let i = -1; i <= 1; i++) {
+    const step = currentStep + i;
+    if (generateCode(secretBase32, step) === code) {
+      const replayKey = `${code}:${step}`;
+      if (usedCodes.has(replayKey)) {
+        return false;
+      }
+      usedCodes.set(replayKey, Date.now());
+      pruneUsedCodes();
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Generate a TOTP secret and otpauth URI for the admin panel.
+ *
+ * @returns {{ secret: string, uri: string }}
+ */
+export function generateAdminTotpSecret() {
+  return generateTotpSecret('admin', { issuer: 'Lamaste Panel' });
+}

package/vendor/serverd/src/lib/tunnel-deps.js

@@ -0,0 +1,41 @@
+/**
+ * The dependency objects the core tunnel workflows take
+ * (`@lamalibre/lamaste/server` createTunnel, updateTunnel, ...), wired to the
+ * daemon's nginx, certbot, chisel and state modules. Shared by the tunnel
+ * routes and by agent revocation.
+ */
+
+import {
+  writePublicVhost,
+  writeAuthenticatedVhost,
+  writeRestrictedVhost,
+  removeAppVhost,
+  enableAppVhost,
+  disableAppVhost,
+  writeAgentPanelVhost,
+  removeAgentPanelVhost,
+  enableAgentPanelVhost,
+  disableAgentPanelVhost,
+} from './nginx.js';
+import { issueTunnelCert } from './certbot.js';
+import { syncChisel } from './chisel.js';
+import { readTunnels, writeTunnels } from './state.js';
+
+export const tunnelNginxDeps = Object.freeze({
+  writePublicVhost,
+  writeAuthenticatedVhost,
+  writeRestrictedVhost,
+  writeAgentPanelVhost,
+  removeAppVhost,
+  removeAgentPanelVhost,
+  enableAppVhost,
+  disableAppVhost,
+  enableAgentPanelVhost,
+  disableAgentPanelVhost,
+});
+
+export const tunnelCertbotDeps = Object.freeze({ issueTunnelCert });
+
+export const tunnelChiselDeps = Object.freeze({ syncChisel });
+
+export const tunnelStateDeps = Object.freeze({ readTunnels, writeTunnels });

package/vendor/serverd/src/lib/user-access-session.js

@@ -0,0 +1,142 @@
+import crypto from 'node:crypto';
+
+const SESSION_MAX_AGE = 12 * 60 * 60; // 12 hours in seconds
+const INACTIVITY_TIMEOUT = 2 * 60 * 60; // 2 hours in seconds
+const REFRESH_THRESHOLD = 60; // Only re-sign if lastActivity is older than 60s
+
+export { SESSION_MAX_AGE, INACTIVITY_TIMEOUT, REFRESH_THRESHOLD };
+
+/**
+ * HMAC-sign a base64url payload string.
+ *
+ * @param {string} payloadB64 - Base64url-encoded payload
+ * @param {string} secretHex - Hex-encoded secret
+ * @returns {string} Base64url-encoded HMAC signature
+ */
+function signPayload(payloadB64, secretHex) {
+  return crypto
+    .createHmac('sha256', Buffer.from(secretHex, 'hex'))
+    .update(payloadB64)
+    .digest('base64url');
+}
+
+/**
+ * Create a signed user-access session token.
+ *
+ * @param {string} sessionSecret - Hex-encoded session secret
+ * @param {string} username - Authelia username to bind the session to
+ * @returns {{ value: string, maxAge: number, expiresAt: string }}
+ */
+export function createUserSession(sessionSecret, username) {
+  const now = Math.floor(Date.now() / 1000);
+  const payload = {
+    iat: now,
+    exp: now + SESSION_MAX_AGE,
+    lastActivity: now,
+    username,
+    type: 'user-access',
+  };
+  const payloadB64 = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  const sig = signPayload(payloadB64, sessionSecret);
+
+  return {
+    value: `${payloadB64}.${sig}`,
+    maxAge: SESSION_MAX_AGE,
+    expiresAt: new Date((now + SESSION_MAX_AGE) * 1000).toISOString(),
+  };
+}
+
+/**
+ * Validate a user-access session token.
+ *
+ * @param {string} tokenValue - The token (payload.sig)
+ * @param {string} sessionSecret - Hex-encoded session secret
+ * @param {{ userEpochs?: Record<string, number> }} [options]
+ *   userEpochs maps username → Unix-second epoch. If the session's `iat`
+ *   is older than the user's epoch, the session is rejected as revoked.
+ *   This is how Authelia user deletions invalidate live sessions whose
+ *   HMAC signature is otherwise still valid.
+ * @returns {{ valid: boolean, payload?: object, reason?: string }}
+ */
+export function validateUserSession(tokenValue, sessionSecret, options = {}) {
+  if (!tokenValue || typeof tokenValue !== 'string') {
+    return { valid: false, reason: 'missing' };
+  }
+
+  const dotIndex = tokenValue.indexOf('.');
+  if (dotIndex === -1) {
+    return { valid: false, reason: 'malformed' };
+  }
+
+  const payloadB64 = tokenValue.slice(0, dotIndex);
+  const sig = tokenValue.slice(dotIndex + 1);
+
+  const expectedSig = signPayload(payloadB64, sessionSecret);
+
+  // Timing-safe comparison
+  const sigBuf = Buffer.from(sig);
+  const expectedBuf = Buffer.from(expectedSig);
+  if (sigBuf.length !== expectedBuf.length || !crypto.timingSafeEqual(sigBuf, expectedBuf)) {
+    return { valid: false, reason: 'invalid_signature' };
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString());
+  } catch {
+    return { valid: false, reason: 'parse_error' };
+  }
+
+  // Must be a user-access session (not a 2FA session)
+  if (payload.type !== 'user-access') {
+    return { valid: false, reason: 'wrong_type' };
+  }
+
+  if (!payload.username) {
+    return { valid: false, reason: 'missing_username' };
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+
+  if (payload.exp && now > payload.exp) {
+    return { valid: false, reason: 'expired' };
+  }
+
+  if (payload.lastActivity && now - payload.lastActivity > INACTIVITY_TIMEOUT) {
+    return { valid: false, reason: 'inactive' };
+  }
+
+  // Per-user invalidation epoch (set when a user is deleted from Authelia).
+  // Reject sessions issued before that epoch — they belong to a user who no
+  // longer exists, even if a same-named user is later re-created.
+  const userEpochs = options.userEpochs;
+  if (userEpochs && typeof userEpochs === 'object') {
+    const epoch = userEpochs[payload.username];
+    if (typeof epoch === 'number' && typeof payload.iat === 'number' && payload.iat < epoch) {
+      return { valid: false, reason: 'revoked' };
+    }
+  }
+
+  return { valid: true, payload };
+}
+
+/**
+ * Refresh a user-access session by updating lastActivity and re-signing.
+ *
+ * @param {object} payload - The existing session payload
+ * @param {string} sessionSecret - Hex-encoded session secret
+ * @returns {{ value: string, maxAge: number }}
+ */
+export function refreshUserSession(payload, sessionSecret) {
+  const now = Math.floor(Date.now() / 1000);
+  const updated = { ...payload, lastActivity: now };
+  const payloadB64 = Buffer.from(JSON.stringify(updated)).toString('base64url');
+  const sig = signPayload(payloadB64, sessionSecret);
+
+  const remaining = Math.max(0, updated.exp - now);
+
+  return {
+    value: `${payloadB64}.${sig}`,
+    maxAge: remaining,
+  };
+}

package/vendor/serverd/src/lib/user-access.js

@@ -0,0 +1,52 @@
+/**
+ * Shim — user-access grant + OTP management now lives in
+ * `@lamalibre/lamaste/server`. This file resolves the dataDir from env
+ * and forwards to the core library, preserving the daemon-local API.
+ */
+
+import {
+  createGrant as createGrantCore,
+  listGrants as listGrantsCore,
+  listGrantsForUser as listGrantsForUserCore,
+  revokeGrant as revokeGrantCore,
+  removeGrantsForUser as removeGrantsForUserCore,
+  consumeGrant as consumeGrantCore,
+  createOTP as createOTPCore,
+  validateAndConsumeOTP as validateAndConsumeOTPCore,
+} from '@lamalibre/lamaste/server';
+
+function dataDir() {
+  return process.env.LAMALIBRE_LAMASTE_DATA_DIR || '/etc/lamalibre/lamaste';
+}
+
+export function createGrant(username, pluginName, logger, options = {}) {
+  return createGrantCore(dataDir(), username, pluginName, logger, options);
+}
+
+export function listGrants() {
+  return listGrantsCore(dataDir());
+}
+
+export function listGrantsForUser(username) {
+  return listGrantsForUserCore(dataDir(), username);
+}
+
+export function revokeGrant(grantId, logger) {
+  return revokeGrantCore(dataDir(), grantId, logger);
+}
+
+export function removeGrantsForUser(username, logger) {
+  return removeGrantsForUserCore(dataDir(), username, logger);
+}
+
+export function consumeGrant(grantId, username, logger) {
+  return consumeGrantCore(dataDir(), grantId, username, logger);
+}
+
+export function createOTP(username, input, logger) {
+  return createOTPCore(dataDir(), username, input, logger);
+}
+
+export function validateAndConsumeOTP(token, verifier) {
+  return validateAndConsumeOTPCore(dataDir(), token, verifier);
+}

package/vendor/serverd/src/middleware/errors.js

@@ -0,0 +1,63 @@
+import fp from 'fastify-plugin';
+
+/**
+ * Global error handler plugin for Fastify.
+ *
+ * Every error response follows this contract:
+ *
+ *   {
+ *     error: string;          // Always present. Human-readable error summary.
+ *     details?: object;       // Optional. Additional structured information.
+ *   }
+ *
+ * Wrapped with fastify-plugin to break encapsulation — the handler applies
+ * to all routes, not just those registered in the same plugin context.
+ */
+async function errorHandlerPlugin(fastify, _opts) {
+  fastify.setErrorHandler((error, request, reply) => {
+    request.log.error(error);
+
+    const isDev = !process.env.NODE_ENV || process.env.NODE_ENV === 'development';
+
+    // Zod validation errors
+    if (error.name === 'ZodError' || Array.isArray(error.issues)) {
+      const issues = error.issues.map((issue) => ({
+        path: issue.path,
+        message: issue.message,
+      }));
+
+      return reply.code(400).send({
+        error: 'Validation failed',
+        details: { issues },
+      });
+    }
+
+    // Operational errors (AppError)
+    if (error.isOperational === true) {
+      const body = { error: error.message };
+      if (error.details !== null && error.details !== undefined) {
+        body.details = error.details;
+      }
+      return reply.code(error.statusCode).send(body);
+    }
+
+    // Fastify built-in errors (malformed JSON, missing content-type, etc.)
+    if (error.statusCode && error.statusCode >= 400 && error.statusCode < 500) {
+      return reply.code(error.statusCode).send({
+        error: error.message,
+      });
+    }
+
+    // Unexpected errors — never leak internals in production
+    const body = { error: 'Internal server error' };
+    if (isDev) {
+      body.details = {
+        message: error.message,
+        stack: error.stack,
+      };
+    }
+    return reply.code(500).send(body);
+  });
+}
+
+export default fp(errorHandlerPlugin);

package/vendor/serverd/src/middleware/mtls.js

@@ -0,0 +1,120 @@
+import fp from 'fastify-plugin';
+import { isRevoked } from '../lib/revocation.js';
+import { getAgentCapabilities, getAgentAllowedSites, PLUGIN_AGENT_CN_PREFIX } from '../lib/mtls.js';
+
+let devWarningLogged = false;
+
+async function mtlsPlugin(fastify, _opts) {
+  fastify.addHook('onRequest', async (request, reply) => {
+    // Health check endpoint is always accessible without mTLS
+    // (used by systemd, load balancers, and internal provisioning checks)
+    if (request.url === '/api/health') {
+      request.certRole = 'admin';
+      request.certLabel = null;
+      request.certCapabilities = null;
+      request.certAllowedSites = null;
+      return;
+    }
+
+    const isDev = process.env.NODE_ENV === 'development';
+
+    if (isDev) {
+      if (!devWarningLogged) {
+        request.log.warn('mTLS verification bypassed — running in development mode');
+        devWarningLogged = true;
+      }
+      request.certRole = 'admin';
+      request.certLabel = null;
+      request.certCapabilities = null;
+      request.certAllowedSites = null;
+      return;
+    }
+
+    const clientVerify = request.headers['x-ssl-client-verify'];
+
+    if (clientVerify !== 'SUCCESS') {
+      return reply.code(403).send({
+        error: 'mTLS certificate required',
+        details: {
+          hint: 'Access to the Lamaste panel requires a valid client certificate.',
+        },
+      });
+    }
+
+    // Check certificate serial against revocation list
+    const serial = request.headers['x-ssl-client-serial'];
+    if (serial && (await isRevoked(serial))) {
+      return reply.code(403).send({
+        error: 'Certificate has been revoked',
+      });
+    }
+
+    // Parse the certificate DN to extract role
+    const dn = request.headers['x-ssl-client-dn'] || '';
+    const cnMatch = dn.match(/CN=([^,]+)/);
+    const cn = cnMatch ? cnMatch[1] : '';
+
+    if (cn.startsWith(PLUGIN_AGENT_CN_PREFIX)) {
+      // Plugin-agent: CN = plugin-agent:<delegatingLabel>:<pluginAgentLabel>
+      // certLabel includes the full CN so it matches the registry label
+      request.certRole = 'plugin-agent';
+      request.certLabel = cn;
+      // Extract the delegating agent label
+      const afterPrefix = cn.slice(PLUGIN_AGENT_CN_PREFIX.length);
+      const colonIndex = afterPrefix.indexOf(':');
+      request.certDelegatedBy = colonIndex !== -1 ? afterPrefix.slice(0, colonIndex) : afterPrefix;
+      try {
+        request.certCapabilities = await getAgentCapabilities(cn);
+      } catch (err) {
+        request.log.warn(
+          { err, label: cn },
+          'Failed to load plugin-agent capabilities, using defaults',
+        );
+        request.certCapabilities = [];
+      }
+      try {
+        request.certAllowedSites = await getAgentAllowedSites(cn);
+      } catch (err) {
+        request.log.warn(
+          { err, label: cn },
+          'Failed to load plugin-agent allowed sites, using defaults',
+        );
+        request.certAllowedSites = [];
+      }
+    } else if (cn.startsWith('agent:')) {
+      request.certRole = 'agent';
+      request.certLabel = cn.slice('agent:'.length);
+      try {
+        request.certCapabilities = await getAgentCapabilities(request.certLabel);
+      } catch (err) {
+        request.log.warn(
+          { err, label: request.certLabel },
+          'Failed to load agent capabilities, using defaults',
+        );
+        request.certCapabilities = ['tunnels:read'];
+      }
+      try {
+        request.certAllowedSites = await getAgentAllowedSites(request.certLabel);
+      } catch (err) {
+        request.log.warn(
+          { err, label: request.certLabel },
+          'Failed to load agent allowed sites, using defaults',
+        );
+        request.certAllowedSites = [];
+      }
+    } else if (cn === 'admin') {
+      request.certRole = 'admin';
+      request.certLabel = null;
+      request.certCapabilities = null;
+      request.certAllowedSites = null;
+    } else {
+      // Defense-in-depth: nginx is the primary gate, but never grant any role
+      // for an unrecognized CN (formerly defaulted to admin — privilege-escalation
+      // hazard if nginx config drifts).
+      request.log.warn({ cn, dn }, 'Rejecting unrecognized CN');
+      return reply.code(403).send({ error: 'Unrecognized client certificate' });
+    }
+  });
+}
+
+export default fp(mtlsPlugin);

package/vendor/serverd/src/middleware/onboarding-guard.js

@@ -0,0 +1,30 @@
+import { getConfig } from '../lib/config.js';
+
+/**
+ * Fastify onRequest hook that blocks access when onboarding is already completed.
+ * Used to protect onboarding routes.
+ */
+export function onboardingOnly() {
+  return async function onboardingOnlyHook(_request, reply) {
+    const config = getConfig();
+    if (config.onboarding.status === 'COMPLETED') {
+      return reply.code(410).send({ error: 'Onboarding already completed' });
+    }
+  };
+}
+
+/**
+ * Fastify onRequest hook that blocks access when onboarding is not yet completed.
+ * Used to protect management routes.
+ */
+export function managementOnly() {
+  return async function managementOnlyHook(_request, reply) {
+    const config = getConfig();
+    if (config.onboarding.status !== 'COMPLETED') {
+      return reply.code(503).send({
+        error: 'Onboarding not complete',
+        onboardingStatus: config.onboarding.status,
+      });
+    }
+  };
+}

package/vendor/serverd/src/middleware/role-guard.js

@@ -0,0 +1,58 @@
+import fp from 'fastify-plugin';
+
+/**
+ * Role guard plugin — decorates fastify with `requireRole(allowedRoles, opts)`.
+ *
+ * Returns a preHandler function that checks `request.certRole` against
+ * the provided allowedRoles array. For agent roles, optionally checks
+ * `request.certCapabilities` for a required capability.
+ *
+ * Usage:
+ *   fastify.requireRole(['admin'])                                    — admin only
+ *   fastify.requireRole(['admin', 'agent'])                           — admin + any agent
+ *   fastify.requireRole(['admin', 'agent'], { capability: 'tunnels:write' }) — admin + agents with capability
+ */
+function roleGuard(fastify, _opts, done) {
+  fastify.decorate('requireRole', function (allowedRoles, opts) {
+    const { capability } = opts || {};
+
+    return async function (request, reply) {
+      const role = request.certRole || 'unknown';
+
+      // Admin always passes — no capability check needed
+      if (role === 'admin') return;
+
+      // plugin-agent is a subset of agent — accept it wherever agent is accepted
+      const effectiveRole =
+        role === 'plugin-agent' && allowedRoles.includes('agent') ? 'agent' : role;
+
+      // Check if the role is in the allowed list
+      if (!allowedRoles.includes(effectiveRole)) {
+        return reply.code(403).send({
+          error: 'Insufficient certificate scope',
+          details: {
+            required: allowedRoles,
+            current: role,
+          },
+        });
+      }
+
+      // If a capability is required, check the agent (or plugin-agent) has it
+      if (capability && (effectiveRole === 'agent' || role === 'plugin-agent')) {
+        const caps = request.certCapabilities || [];
+        if (!caps.includes(capability)) {
+          return reply.code(403).send({
+            error: 'Insufficient certificate capability',
+            details: {
+              required: capability,
+              granted: caps,
+            },
+          });
+        }
+      }
+    };
+  });
+  done();
+}
+
+export default fp(roleGuard, { name: 'role-guard' });

package/vendor/serverd/src/middleware/twofa-session.js

@@ -0,0 +1,65 @@
+import fp from 'fastify-plugin';
+import { getConfig } from '../lib/config.js';
+import {
+  COOKIE_NAME,
+  COOKIE_OPTIONS,
+  REFRESH_THRESHOLD,
+  validateSession,
+  refreshSession,
+} from '../lib/session.js';
+
+/**
+ * Exempt paths that must remain accessible without a 2FA session.
+ * These include the health check, the 2FA status endpoint, and the verify endpoint.
+ */
+const EXEMPT_PATHS = new Set(['/api/health', '/api/settings/2fa', '/api/settings/2fa/verify']);
+
+async function twofaSessionPlugin(fastify, _opts) {
+  fastify.addHook('onRequest', async (request, reply) => {
+    const config = getConfig();
+
+    // 2FA not enabled — skip entirely
+    if (!config.panel2fa || !config.panel2fa.enabled) {
+      return;
+    }
+
+    // Agents bypass 2FA — both regular agent certs and plugin-agent certs
+    // (plugin-agents are automated callers; only humans need the second factor)
+    if (request.certRole === 'agent' || request.certRole === 'plugin-agent') {
+      return;
+    }
+
+    // Exempt paths
+    if (EXEMPT_PATHS.has(request.url) || EXEMPT_PATHS.has(request.url.split('?')[0])) {
+      return;
+    }
+
+    // Admin must have a valid 2FA session
+    if (request.certRole === 'admin') {
+      const sessionSecret = config.sessionSecret;
+      if (!sessionSecret) {
+        return reply.code(401).send({ error: '2fa_required' });
+      }
+
+      const cookieValue = request.cookies?.[COOKIE_NAME];
+      const certSerial = request.headers['x-ssl-client-serial'] || undefined;
+      const result = validateSession(cookieValue, sessionSecret, certSerial);
+
+      if (!result.valid) {
+        return reply.code(401).send({ error: '2fa_required' });
+      }
+
+      // Throttle refresh: only re-sign if lastActivity is stale (>60s)
+      const now = Math.floor(Date.now() / 1000);
+      if (now - result.payload.lastActivity >= REFRESH_THRESHOLD) {
+        const refreshed = refreshSession(result.payload, sessionSecret);
+        reply.setCookie(COOKIE_NAME, refreshed.value, {
+          ...COOKIE_OPTIONS,
+          maxAge: refreshed.maxAge,
+        });
+      }
+    }
+  });
+}
+
+export default fp(twofaSessionPlugin, { name: 'twofa-session' });