@team-codeme/crud-forge 0.0.0-stage → 1.0.1

package/src/provision/bootstrap.js

@@ -0,0 +1,147 @@
+const colors = require('../utils/colors');
+const { resolveEnv } = require('../config/env-refs');
+const { deriveAuthUrls } = require('../config/auth-config');
+const { fetchPasswordToken } = require('./token');
+const { runAdminServiceBootstrap } = require('./admin-service');
+const { runKeycloakAdminRestBootstrap, deleteTrackedResources } = require('./keycloak-admin-rest');
+const { emptyState, resolveStatePath, readState, writeState } = require('./state');
+
+function desiredFromConfig(auth) {
+  const provision = auth.provision || {};
+  return {
+    clientId: String(provision.clientId || auth.clientId || '').trim(),
+    clientName: provision.clientName || '',
+    publicClient: provision.publicClient !== false,
+    directAccessGrantsEnabled: provision.directAccessGrantsEnabled !== false,
+    redirectUris: Array.isArray(provision.redirectUris) ? provision.redirectUris : [],
+    webOrigins: Array.isArray(provision.webOrigins) ? provision.webOrigins : [],
+    roles: Array.isArray(provision.roles) ? provision.roles.map(String) : [],
+    users: Array.isArray(provision.users) ? provision.users : [],
+  };
+}
+
+function resolveUserPassword(user) {
+  const value = resolveEnv(user.passwordEnv);
+  if (!value) {
+    throw new Error(`passwordEnv "${user.passwordEnv}" for user "${user.username}" is not set.`);
+  }
+  return value;
+}
+
+async function runBootstrap(config, options = {}) {
+  const auth = deriveAuthUrls({ ...(config.auth || {}) });
+  const provision = auth.provision || {};
+  const dryRun = !!(options.dryRun || provision.dryRun);
+  const adapter = String(provision.adapter || 'admin-service').trim();
+  const desired = desiredFromConfig(auth);
+
+  if (!desired.clientId) {
+    throw new Error('auth.provision.clientId or auth.clientId is required for bootstrap.');
+  }
+
+  const username = resolveEnv(provision.adminUsernameEnv);
+  const password = resolveEnv(provision.adminPasswordEnv);
+  const tokenClientId = provision.tokenClientId || 'admin-cli';
+  const forwardedProto = auth.forwardedProto || '';
+
+  console.log(
+    colors.cyan(
+      `🔵 Keycloak bootstrap (${dryRun ? 'dry-run' : 'apply'}) adapter=${adapter} realm=${auth.realm} client=${desired.clientId}`
+    )
+  );
+
+  const token = await fetchPasswordToken({
+    tokenUrl: auth.tokenUrl,
+    clientId: tokenClientId,
+    username,
+    password,
+    forwardedProto,
+  });
+
+  const statePath = resolveStatePath(config, options.cwd || process.cwd());
+  const state = dryRun ? emptyState() : readState(statePath);
+  state.adapter = adapter;
+  state.realm = auth.realm;
+
+  let outcome;
+  if (adapter === 'admin-service') {
+    outcome = await runAdminServiceBootstrap({
+      adminServiceUrl: provision.adminServiceUrl,
+      token,
+      desired,
+      dryRun,
+      resetExistingPasswords: !!provision.resetExistingPasswords,
+      resolveUserPassword,
+    });
+  } else if (adapter === 'keycloak-admin-rest') {
+    outcome = await runKeycloakAdminRestBootstrap({
+      serverUrl: auth.serverUrl,
+      realm: auth.realm,
+      token,
+      forwardedProto,
+      desired,
+      dryRun,
+      resetExistingPasswords: !!provision.resetExistingPasswords,
+      resolveUserPassword,
+      state,
+    });
+  } else {
+    throw new Error(`Unknown auth.provision.adapter "${adapter}".`);
+  }
+
+  (outcome.plan || []).forEach((line) => console.log(`  -> ${line}`));
+
+  if (!dryRun && adapter === 'keycloak-admin-rest') {
+    writeState(statePath, state);
+    console.log(colors.dim(`  -> State written to ${statePath} (cleanup uses this file only)`));
+  }
+
+  if (dryRun) {
+    console.log(colors.yellow('⚠️ Dry run complete. No remote mutations were requested by this CLI beyond the token request.'));
+  } else {
+    console.log(colors.green('✅ Keycloak bootstrap finished.'));
+  }
+
+  return { ...outcome, statePath, dryRun };
+}
+
+async function runCleanup(config, options = {}) {
+  const auth = deriveAuthUrls({ ...(config.auth || {}) });
+  const provision = auth.provision || {};
+  if (String(provision.adapter || '') !== 'keycloak-admin-rest') {
+    throw new Error('Cleanup is only implemented for auth.provision.adapter: keycloak-admin-rest.');
+  }
+  const statePath = resolveStatePath(config, options.cwd || process.cwd());
+  const state = readState(statePath);
+  const hasItems = [...(state.clients || []), ...(state.roles || []), ...(state.users || [])].length > 0;
+  if (!hasItems) {
+    console.log(colors.yellow(`⚠️ No tracked resources in ${statePath}. Nothing to delete.`));
+    return { deleted: [] };
+  }
+
+  const token = await fetchPasswordToken({
+    tokenUrl: auth.tokenUrl,
+    clientId: provision.tokenClientId || 'admin-cli',
+    username: resolveEnv(provision.adminUsernameEnv),
+    password: resolveEnv(provision.adminPasswordEnv),
+    forwardedProto: auth.forwardedProto || '',
+  });
+
+  const deleted = await deleteTrackedResources(
+    {
+      serverUrl: auth.serverUrl,
+      realm: auth.realm,
+      token,
+      forwardedProto: auth.forwardedProto || '',
+    },
+    state
+  );
+  writeState(statePath, emptyState());
+  console.log(colors.green(`✅ Removed ${deleted.length} tracked resource(s).`));
+  return { deleted };
+}
+
+module.exports = {
+  runBootstrap,
+  runCleanup,
+};

package/src/provision/http.js

@@ -0,0 +1,123 @@
+const http = require('http');
+const https = require('https');
+
+class ProvisionHttpError extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.name = 'ProvisionHttpError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+function summarizeBody(body) {
+  if (body == null) {
+    return '';
+  }
+  if (typeof body === 'string') {
+    return body.slice(0, 400);
+  }
+  try {
+    const copy = JSON.parse(JSON.stringify(body));
+    ['access_token', 'refresh_token', 'password', 'value', 'client_secret', 'secret'].forEach((key) => {
+      if (copy && Object.prototype.hasOwnProperty.call(copy, key)) {
+        copy[key] = '[redacted]';
+      }
+    });
+    return JSON.stringify(copy).slice(0, 400);
+  } catch {
+    return '';
+  }
+}
+
+function request({ method, url, headers = {}, body, json, form, timeout = 20000 }) {
+  return new Promise((resolve, reject) => {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch (err) {
+      reject(new Error(`Invalid URL: ${url}`));
+      return;
+    }
+
+    let payload = null;
+    const reqHeaders = { Accept: 'application/json', ...headers };
+
+    if (form) {
+      payload = Buffer.from(new URLSearchParams(form).toString());
+      reqHeaders['Content-Type'] = 'application/x-www-form-urlencoded';
+      reqHeaders['Content-Length'] = payload.length;
+    } else if (json !== undefined) {
+      payload = Buffer.from(JSON.stringify(json));
+      reqHeaders['Content-Type'] = 'application/json';
+      reqHeaders['Content-Length'] = payload.length;
+    } else if (body != null) {
+      payload = Buffer.isBuffer(body) ? body : Buffer.from(String(body));
+      reqHeaders['Content-Length'] = payload.length;
+    }
+
+    const lib = parsed.protocol === 'https:' ? https : http;
+    const req = lib.request(
+      {
+        protocol: parsed.protocol,
+        hostname: parsed.hostname,
+        port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+        path: `${parsed.pathname}${parsed.search}`,
+        method: method || 'GET',
+        headers: reqHeaders,
+        timeout,
+      },
+      (res) => {
+        const chunks = [];
+        res.on('data', (chunk) => chunks.push(chunk));
+        res.on('end', () => {
+          const text = Buffer.concat(chunks).toString('utf8');
+          let parsedBody = text;
+          if (text) {
+            try {
+              parsedBody = JSON.parse(text);
+            } catch {
+              parsedBody = text;
+            }
+          } else {
+            parsedBody = null;
+          }
+          resolve({
+            status: res.statusCode,
+            headers: res.headers,
+            body: parsedBody,
+            text,
+          });
+        });
+      }
+    );
+
+    req.on('timeout', () => {
+      req.destroy(new Error(`Request timed out: ${method} ${url}`));
+    });
+    req.on('error', reject);
+    if (payload) {
+      req.write(payload);
+    }
+    req.end();
+  });
+}
+
+function assertOk(response, action) {
+  if (response.status >= 200 && response.status < 300) {
+    return response;
+  }
+  const detail = summarizeBody(response.body);
+  throw new ProvisionHttpError(
+    `${action} failed (HTTP ${response.status})${detail ? `: ${detail}` : ''}`,
+    response.status,
+    response.body
+  );
+}
+
+module.exports = {
+  request,
+  assertOk,
+  ProvisionHttpError,
+  summarizeBody,
+};

package/src/provision/keycloak-admin-rest.js

@@ -0,0 +1,335 @@
+const { request, assertOk } = require('./http');
+
+const OWNED_ATTRIBUTE = 'crudforge.owned';
+
+function realmAdminUrl(serverUrl, realm) {
+  return `${String(serverUrl).replace(/\/+$/, '')}/admin/realms/${encodeURIComponent(realm)}`;
+}
+
+function headers(token, forwardedProto) {
+  const next = { Authorization: `Bearer ${token}` };
+  if (forwardedProto) {
+    next['X-Forwarded-Proto'] = forwardedProto;
+  }
+  return next;
+}
+
+async function kcRequest({ serverUrl, realm, token, forwardedProto, method, path, json }) {
+  return request({
+    method,
+    url: `${realmAdminUrl(serverUrl, realm)}${path}`,
+    headers: headers(token, forwardedProto),
+    json,
+  });
+}
+
+function isOwnedClient(client) {
+  const attrs = client && client.attributes ? client.attributes : {};
+  const value = attrs[OWNED_ATTRIBUTE];
+  if (Array.isArray(value)) {
+    return value.map(String).includes('true');
+  }
+  return String(value || '') === 'true';
+}
+
+async function findClient(ctx, clientId) {
+  const response = await kcRequest({ ...ctx, method: 'GET', path: `/clients?clientId=${encodeURIComponent(clientId)}` });
+  assertOk(response, `List clients matching ${clientId}`);
+  const list = Array.isArray(response.body) ? response.body : [];
+  return list.find((client) => client.clientId === clientId) || null;
+}
+
+async function findRole(ctx, name) {
+  const response = await kcRequest({ ...ctx, method: 'GET', path: `/roles/${encodeURIComponent(name)}` });
+  if (response.status === 404) {
+    return null;
+  }
+  assertOk(response, `Read realm role ${name}`);
+  return response.body;
+}
+
+async function findUserByUsername(ctx, username) {
+  const response = await kcRequest({
+    ...ctx,
+    method: 'GET',
+    path: `/users?username=${encodeURIComponent(username)}&exact=true`,
+  });
+  assertOk(response, `Search user ${username}`);
+  const list = Array.isArray(response.body) ? response.body : [];
+  return list.find((user) => user.username === username) || list[0] || null;
+}
+
+async function ensureClient(ctx, desired, dryRun, state) {
+  const existing = await findClient(ctx, desired.clientId);
+  if (existing) {
+    if (!isOwnedClient(existing)) {
+      // Use the existing client for the app; never mutate unmanaged clients.
+      return { client: existing, created: false, unmanaged: true };
+    }
+    return { client: existing, created: false };
+  }
+
+  const representation = {
+    clientId: desired.clientId,
+    name: desired.clientName || desired.clientId,
+    enabled: true,
+    publicClient: desired.publicClient !== false,
+    protocol: 'openid-connect',
+    standardFlowEnabled: true,
+    directAccessGrantsEnabled: desired.directAccessGrantsEnabled !== false,
+    redirectUris: desired.redirectUris.length ? desired.redirectUris : ['http://127.0.0.1:*', 'http://localhost:*'],
+    webOrigins: desired.webOrigins.length ? desired.webOrigins : ['+'],
+    attributes: { [OWNED_ATTRIBUTE]: 'true' },
+  };
+
+  if (dryRun) {
+    return { client: representation, created: true, dryRun: true };
+  }
+
+  const created = await kcRequest({ ...ctx, method: 'POST', path: '/clients', json: representation });
+  if (created.status !== 201 && created.status !== 204 && created.status !== 200) {
+    assertOk(created, `Create client ${desired.clientId}`);
+  }
+  const next = await findClient(ctx, desired.clientId);
+  if (next && state) {
+    state.clients.push({ id: next.id, clientId: next.clientId });
+  }
+  return { client: next || representation, created: true };
+}
+
+async function ensureRole(ctx, name, dryRun, state) {
+  const existing = await findRole(ctx, name);
+  if (existing) {
+    return { role: existing, created: false };
+  }
+  if (dryRun) {
+    return { role: { name }, created: true, dryRun: true };
+  }
+  const created = await kcRequest({
+    ...ctx,
+    method: 'POST',
+    path: '/roles',
+    json: { name, description: `CRUDForge bootstrap role ${name}` },
+  });
+  if (created.status !== 201 && created.status !== 204 && created.status !== 200) {
+    assertOk(created, `Create realm role ${name}`);
+  }
+  const next = await findRole(ctx, name);
+  if (next && state) {
+    state.roles.push({ name: next.name, id: next.id });
+  }
+  return { role: next || { name }, created: true };
+}
+
+async function ensureUser(ctx, user, resolvePassword, { dryRun, resetExistingPasswords, state }) {
+  const existing = await findUserByUsername(ctx, user.username);
+  if (existing) {
+    if (resetExistingPasswords) {
+      if (!dryRun) {
+        const reset = await kcRequest({
+          ...ctx,
+          method: 'PUT',
+          path: `/users/${existing.id}/reset-password`,
+          json: {
+            type: 'password',
+            value: resolvePassword(user),
+            temporary: !!user.temporaryPassword,
+          },
+        });
+        assertOk(reset, `Reset password for ${user.username}`);
+      }
+      return { user: existing, created: false, passwordReset: true };
+    }
+    return { user: existing, created: false, passwordReset: false };
+  }
+
+  const representation = {
+    username: user.username,
+    enabled: user.enabled !== false,
+    email: user.email || undefined,
+    firstName: user.firstName || undefined,
+    lastName: user.lastName || undefined,
+    emailVerified: false,
+    credentials: [
+      {
+        type: 'password',
+        value: resolvePassword(user),
+        temporary: !!user.temporaryPassword,
+      },
+    ],
+    attributes: { [OWNED_ATTRIBUTE]: ['true'] },
+  };
+
+  if (dryRun) {
+    return { user: { username: user.username }, created: true, dryRun: true };
+  }
+
+  const created = await kcRequest({ ...ctx, method: 'POST', path: '/users', json: representation });
+  if (created.status !== 201 && created.status !== 204 && created.status !== 200) {
+    assertOk(created, `Create user ${user.username}`);
+  }
+  const next = await findUserByUsername(ctx, user.username);
+  if (next && state) {
+    state.users.push({ id: next.id, username: next.username });
+  }
+  return { user: next || { username: user.username }, created: true };
+}
+
+async function ensureRealmRoleOnUser(ctx, userId, role, dryRun, state) {
+  const mapped = await kcRequest({ ...ctx, method: 'GET', path: `/users/${userId}/role-mappings/realm` });
+  assertOk(mapped, `List realm roles for user ${userId}`);
+  const already = (Array.isArray(mapped.body) ? mapped.body : []).some((entry) => entry.name === role.name);
+  if (already) {
+    return { assigned: false };
+  }
+  if (dryRun) {
+    return { assigned: true, dryRun: true };
+  }
+  const assign = await kcRequest({
+    ...ctx,
+    method: 'POST',
+    path: `/users/${userId}/role-mappings/realm`,
+    json: [{ id: role.id, name: role.name }],
+  });
+  assertOk(assign, `Assign role ${role.name} to user ${userId}`);
+  if (state) {
+    state.assignments.push({ userId, role: role.name });
+  }
+  return { assigned: true };
+}
+
+async function runKeycloakAdminRestBootstrap({
+  serverUrl,
+  realm,
+  token,
+  forwardedProto,
+  desired,
+  dryRun,
+  resetExistingPasswords,
+  resolveUserPassword,
+  state,
+}) {
+  const ctx = { serverUrl, realm, token, forwardedProto };
+  const plan = [];
+  const result = { adapter: 'keycloak-admin-rest', created: [], skipped: [] };
+
+  const clientOutcome = await ensureClient(ctx, desired, dryRun, state);
+  if (clientOutcome.unmanaged) {
+    plan.push(
+      `Client ${desired.clientId} already exists (unmanaged); using as-is without modifications`
+    );
+  } else {
+    plan.push(
+      clientOutcome.created
+        ? `${dryRun ? 'Would create' : 'Created'} client ${desired.clientId}`
+        : `Client ${desired.clientId} already exists (owned); skipped create`
+    );
+  }
+  result[clientOutcome.created ? 'created' : 'skipped'].push({
+    type: 'client',
+    id: desired.clientId,
+    unmanaged: !!clientOutcome.unmanaged,
+  });
+
+  const roleRecords = {};
+  for (const roleName of desired.roles) {
+    const outcome = await ensureRole(ctx, roleName, dryRun, state);
+    roleRecords[roleName] = outcome.role;
+    plan.push(
+      outcome.created
+        ? `${dryRun ? 'Would create' : 'Created'} role ${roleName}`
+        : `Role ${roleName} already exists; skipped create`
+    );
+    result[outcome.created ? 'created' : 'skipped'].push({ type: 'role', id: roleName });
+  }
+
+  for (const user of desired.users) {
+    const outcome = await ensureUser(ctx, user, resolveUserPassword, {
+      dryRun,
+      resetExistingPasswords,
+      state,
+    });
+    plan.push(
+      outcome.created
+        ? `${dryRun ? 'Would create' : 'Created'} user ${user.username}`
+        : `User ${user.username} already exists; ${
+            outcome.passwordReset ? 'password reset requested' : 'password left unchanged'
+          }`
+    );
+    result[outcome.created ? 'created' : 'skipped'].push({ type: 'user', id: user.username });
+
+    const userId = outcome.user && outcome.user.id;
+    const roleNames = Array.isArray(user.roles) ? user.roles : [];
+    for (const roleName of roleNames) {
+      let role = roleRecords[roleName];
+      if (!role || !role.id) {
+        const ensured = await ensureRole(ctx, roleName, dryRun, state);
+        role = ensured.role;
+        roleRecords[roleName] = role;
+      }
+      if (!userId || !role || !role.id) {
+        if (dryRun) {
+          plan.push(`Would assign role ${roleName} to ${user.username}`);
+        }
+        continue;
+      }
+      const assigned = await ensureRealmRoleOnUser(ctx, userId, role, dryRun, state);
+      plan.push(
+        assigned.assigned
+          ? `${dryRun ? 'Would assign' : 'Assigned'} role ${roleName} to ${user.username}`
+          : `Role ${roleName} already on ${user.username}`
+      );
+    }
+  }
+
+  return { plan, result };
+}
+
+async function deleteTrackedResources(ctx, state) {
+  const deleted = [];
+  for (const user of [...(state.users || [])].reverse()) {
+    if (!user.id) continue;
+    const response = await kcRequest({ ...ctx, method: 'DELETE', path: `/users/${user.id}` });
+    if (response.status === 204 || response.status === 200 || response.status === 404) {
+      deleted.push({ type: 'user', id: user.username || user.id });
+    } else {
+      assertOk(response, `Delete user ${user.username || user.id}`);
+    }
+  }
+  for (const role of [...(state.roles || [])].reverse()) {
+    if (!role.name) continue;
+    const response = await kcRequest({ ...ctx, method: 'DELETE', path: `/roles/${encodeURIComponent(role.name)}` });
+    if (response.status === 204 || response.status === 200 || response.status === 404) {
+      deleted.push({ type: 'role', id: role.name });
+    } else {
+      assertOk(response, `Delete role ${role.name}`);
+    }
+  }
+  for (const client of [...(state.clients || [])].reverse()) {
+    if (!client.id) continue;
+    const live = await kcRequest({ ...ctx, method: 'GET', path: `/clients/${client.id}` });
+    if (live.status === 404) {
+      deleted.push({ type: 'client', id: client.clientId || client.id });
+      continue;
+    }
+    assertOk(live, `Read tracked client ${client.clientId}`);
+    if (!isOwnedClient(live.body)) {
+      throw new Error(`Refusing to delete unmanaged client ${client.clientId}.`);
+    }
+    const response = await kcRequest({ ...ctx, method: 'DELETE', path: `/clients/${client.id}` });
+    if (response.status === 204 || response.status === 200 || response.status === 404) {
+      deleted.push({ type: 'client', id: client.clientId || client.id });
+    } else {
+      assertOk(response, `Delete client ${client.clientId}`);
+    }
+  }
+  return deleted;
+}
+
+module.exports = {
+  runKeycloakAdminRestBootstrap,
+  deleteTrackedResources,
+  findClient,
+  OWNED_ATTRIBUTE,
+  realmAdminUrl,
+};

package/src/provision/state.js

@@ -0,0 +1,51 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+function emptyState() {
+  return {
+    createdAt: new Date().toISOString(),
+    adapter: '',
+    realm: '',
+    clients: [],
+    roles: [],
+    users: [],
+    assignments: [],
+  };
+}
+
+function resolveStatePath(config, cwd = process.cwd()) {
+  const relative = config.auth?.provision?.stateFile || '.crudforge/provision-state.json';
+  return path.isAbsolute(relative) ? relative : path.join(cwd, relative);
+}
+
+function readState(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return emptyState();
+  }
+  return { ...emptyState(), ...fs.readJsonSync(filePath) };
+}
+
+function writeState(filePath, state) {
+  fs.ensureDirSync(path.dirname(filePath));
+  const next = { ...state, updatedAt: new Date().toISOString() };
+  fs.writeJsonSync(filePath, next, { spaces: 2 });
+  return next;
+}
+
+function track(state, collection, item, key = 'id') {
+  const list = Array.isArray(state[collection]) ? state[collection] : [];
+  const exists = list.some((entry) => entry && item && entry[key] && entry[key] === item[key]);
+  if (!exists) {
+    list.push(item);
+  }
+  state[collection] = list;
+  return state;
+}
+
+module.exports = {
+  emptyState,
+  resolveStatePath,
+  readState,
+  writeState,
+  track,
+};

package/src/provision/token.js

@@ -0,0 +1,52 @@
+const { request, assertOk } = require('./http');
+
+async function fetchPasswordToken({
+  tokenUrl,
+  clientId,
+  username,
+  password,
+  forwardedProto,
+}) {
+  if (!tokenUrl) {
+    throw new Error('Token URL is missing. Set auth.serverUrl/auth.tokenUrl or derive them from realm.');
+  }
+
+  const headers = {};
+  if (forwardedProto) {
+    headers['X-Forwarded-Proto'] = forwardedProto;
+  }
+
+  const response = await request({
+    method: 'POST',
+    url: tokenUrl,
+    headers,
+    form: {
+      grant_type: 'password',
+      client_id: clientId,
+      username,
+      password,
+      scope: 'openid',
+    },
+  });
+
+  if (response.status === 401 || response.status === 403) {
+    const desc =
+      response.body && typeof response.body === 'object'
+        ? response.body.error_description || response.body.error
+        : '';
+    throw new Error(
+      `Provisioning login failed against ${tokenUrl} using token client "${clientId}" (HTTP ${response.status})${
+        desc ? `: ${desc}` : ''
+      }. Check KEYCLOAK_ADMIN_USERNAME / KEYCLOAK_ADMIN_PASSWORD and that the token client allows direct access grants.`
+    );
+  }
+
+  assertOk(response, `Request access token from ${tokenUrl}`);
+  const token = response.body && response.body.access_token;
+  if (!token) {
+    throw new Error(`Token response from ${tokenUrl} did not include access_token.`);
+  }
+  return token;
+}
+
+module.exports = { fetchPasswordToken };