@fredlackey/devutils 0.0.18 → 0.1.0

package/src/commands/auth/logout.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const { AUTH_SERVICES, AUTH_DIR, readCredential } = require('./services');
+
+const meta = {
+  description: 'Revoke and remove stored credentials for a service',
+  arguments: [
+    { name: 'service', description: 'Service name to log out from', required: true }
+  ],
+  flags: []
+};
+
+/**
+ * Attempt to revoke an OAuth token by POSTing to the provider's revocation endpoint.
+ * This is best-effort: if revocation fails (network error, token already expired, etc.),
+ * we log a warning but continue with local cleanup.
+ *
+ * @param {string} revokeUrl - The revocation endpoint URL.
+ * @param {string} token - The access token to revoke.
+ * @returns {Promise<boolean>} True if revocation succeeded, false otherwise.
+ */
+function revokeToken(revokeUrl, token) {
+  return new Promise((resolve) => {
+    const postData = new URLSearchParams({ token }).toString();
+    const parsed = new URL(revokeUrl);
+
+    const options = {
+      hostname: parsed.hostname,
+      port: parsed.port || 443,
+      path: parsed.pathname + parsed.search,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'Content-Length': Buffer.byteLength(postData)
+      }
+    };
+
+    const req = https.request(options, (res) => {
+      // Consume the response body so the socket is released
+      res.on('data', () => {});
+      res.on('end', () => {
+        resolve(res.statusCode >= 200 && res.statusCode < 300);
+      });
+    });
+
+    req.on('error', () => {
+      resolve(false);
+    });
+
+    req.write(postData);
+    req.end();
+  });
+}
+
+/**
+ * Run the auth logout command.
+ * Validates the service, attempts token revocation for OAuth services,
+ * and deletes the local credential file.
+ *
+ * @param {object} args - Parsed CLI arguments (positional, flags).
+ * @param {object} context - CLI context (output, prompt, errors).
+ */
+async function run(args, context) {
+  const service = args.positional[0];
+
+  if (!service) {
+    context.errors.throwError(400, 'Missing required argument: <service>. Example: dev auth logout google', 'auth');
+    return;
+  }
+
+  const serviceConfig = AUTH_SERVICES[service];
+  if (!serviceConfig) {
+    const supported = Object.keys(AUTH_SERVICES).join(', ');
+    context.errors.throwError(400, `Unknown service '${service}'. Supported services: ${supported}`, 'auth');
+    return;
+  }
+
+  // Check if credentials exist
+  const credential = readCredential(service);
+  if (!credential) {
+    context.output.info(`Not logged into ${service}.`);
+    return;
+  }
+
+  // Attempt token revocation for OAuth services
+  if (credential.type === 'oauth' && serviceConfig.revokeUrl && credential.accessToken) {
+    context.output.info(`Revoking ${service} token...`);
+    const revoked = await revokeToken(serviceConfig.revokeUrl, credential.accessToken);
+    if (revoked) {
+      context.output.info('Token revoked successfully.');
+    } else {
+      context.output.info('Warning: Token revocation failed. The token may still be valid on the provider side.');
+      context.output.info('Continuing with local cleanup.');
+    }
+  }
+
+  // Delete the credential file
+  const credFile = path.join(AUTH_DIR, `${service}.json`);
+  try {
+    fs.unlinkSync(credFile);
+  } catch {
+    // File may have already been deleted -- not an error
+  }
+
+  context.output.info(`Logged out of ${service}.`);
+}
+
+module.exports = { meta, run };

package/src/commands/auth/refresh.js

@@ -0,0 +1,184 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const { AUTH_SERVICES, AUTH_DIR, CLIENTS_DIR, readCredential } = require('./services');
+
+const meta = {
+  description: 'Force a token refresh for an OAuth service without re-authenticating',
+  arguments: [
+    { name: 'service', description: 'Service name to refresh', required: true }
+  ],
+  flags: []
+};
+
+/**
+ * Make an HTTPS POST request with form-encoded data.
+ * Uses Node.js built-in https module (no external dependencies).
+ *
+ * @param {string} targetUrl - The URL to POST to.
+ * @param {Object<string, string>} data - Key/value pairs to send as form data.
+ * @returns {Promise<{ statusCode: number, body: string }>}
+ */
+function httpsPost(targetUrl, data) {
+  return new Promise((resolve, reject) => {
+    const postData = new URLSearchParams(data).toString();
+    const parsed = new URL(targetUrl);
+
+    const options = {
+      hostname: parsed.hostname,
+      port: parsed.port || 443,
+      path: parsed.pathname + parsed.search,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'Content-Length': Buffer.byteLength(postData)
+      }
+    };
+
+    const req = https.request(options, (res) => {
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        resolve({ statusCode: res.statusCode, body });
+      });
+    });
+
+    req.on('error', reject);
+    req.write(postData);
+    req.end();
+  });
+}
+
+/**
+ * Run the auth refresh command.
+ * Exchanges the stored refresh token for a new access token and updates
+ * the credential file. Only works for OAuth services.
+ *
+ * @param {object} args - Parsed CLI arguments (positional, flags).
+ * @param {object} context - CLI context (output, prompt, errors).
+ */
+async function run(args, context) {
+  const service = args.positional[0];
+
+  if (!service) {
+    context.errors.throwError(400, 'Missing required argument: <service>. Example: dev auth refresh google', 'auth');
+    return;
+  }
+
+  const serviceConfig = AUTH_SERVICES[service];
+  if (!serviceConfig) {
+    const supported = Object.keys(AUTH_SERVICES).join(', ');
+    context.errors.throwError(400, `Unknown service '${service}'. Supported services: ${supported}`, 'auth');
+    return;
+  }
+
+  // Read existing credentials
+  const credential = readCredential(service);
+  if (!credential) {
+    context.output.info(`Not authenticated with ${service}. Run "dev auth login ${service}" to authenticate first.`);
+    return;
+  }
+
+  // API key services don't support refresh
+  if (credential.type === 'api-key') {
+    context.output.info('Refresh is not applicable for API key services. API keys don\'t expire through DevUtils.');
+    return;
+  }
+
+  // OAuth services need a refresh token
+  if (credential.type !== 'oauth') {
+    context.output.info(`Unrecognized credential type: ${credential.type}`);
+    return;
+  }
+
+  if (!credential.refreshToken) {
+    context.output.info(`No refresh token available for ${service}. Run "dev auth login ${service}" to re-authenticate.`);
+    return;
+  }
+
+  // Read client credentials
+  if (!serviceConfig.clientFile) {
+    context.errors.throwError(500, `No client credentials file configured for ${service}.`, 'auth');
+    return;
+  }
+
+  const clientFile = path.join(CLIENTS_DIR, serviceConfig.clientFile);
+  if (!fs.existsSync(clientFile)) {
+    context.output.info(`Client credentials not found: ${clientFile}`);
+    context.output.info(`Cannot refresh without client credentials. Run "dev auth login ${service}" to re-authenticate.`);
+    return;
+  }
+
+  let clientCreds;
+  try {
+    clientCreds = JSON.parse(fs.readFileSync(clientFile, 'utf8'));
+  } catch {
+    context.errors.throwError(500, `Invalid client credentials file: ${clientFile}`, 'auth');
+    return;
+  }
+
+  if (!clientCreds.clientId || !clientCreds.clientSecret) {
+    context.errors.throwError(400, 'Client credentials file must contain "clientId" and "clientSecret".', 'auth');
+    return;
+  }
+
+  // Exchange refresh token for new access token
+  context.output.info(`Refreshing ${service} token...`);
+
+  let tokenResponse;
+  try {
+    tokenResponse = await httpsPost(serviceConfig.tokenUrl, {
+      grant_type: 'refresh_token',
+      refresh_token: credential.refreshToken,
+      client_id: clientCreds.clientId,
+      client_secret: clientCreds.clientSecret
+    });
+  } catch (err) {
+    context.errors.throwError(500, `Token refresh failed: ${err.message}`, 'auth');
+    return;
+  }
+
+  let tokenData;
+  try {
+    tokenData = JSON.parse(tokenResponse.body);
+  } catch {
+    context.errors.throwError(500, 'Failed to parse token refresh response.', 'auth');
+    return;
+  }
+
+  if (tokenData.error) {
+    context.errors.throwError(500, `Token refresh error: ${tokenData.error_description || tokenData.error}`, 'auth');
+    return;
+  }
+
+  // Update the credential file with the new token
+  const now = new Date();
+  const expiresAt = tokenData.expires_in
+    ? new Date(now.getTime() + tokenData.expires_in * 1000).toISOString()
+    : credential.expiresAt;
+
+  const updated = {
+    type: 'oauth',
+    accessToken: tokenData.access_token,
+    // Some providers return a new refresh token, some don't.
+    // If a new one is returned, use it. Otherwise, keep the old one.
+    refreshToken: tokenData.refresh_token || credential.refreshToken,
+    expiresAt: expiresAt,
+    scopes: credential.scopes,
+    authenticatedAt: credential.authenticatedAt
+  };
+
+  fs.writeFileSync(
+    path.join(AUTH_DIR, `${service}.json`),
+    JSON.stringify(updated, null, 2) + '\n'
+  );
+
+  context.output.info(`Token refreshed successfully for ${service}.`);
+  if (expiresAt) {
+    context.output.info(`New expiry: ${expiresAt}`);
+  }
+}
+
+module.exports = { meta, run };

package/src/commands/auth/services.js

@@ -0,0 +1,169 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const AUTH_DIR = path.join(os.homedir(), '.devutils', 'auth');
+const CLIENTS_DIR = path.join(AUTH_DIR, 'clients');
+
+/**
+ * Registry of all supported authentication services.
+ * Each entry describes how the service authenticates and what credentials it needs.
+ *
+ * - OAuth services use a browser-based consent flow (e.g., Google).
+ * - API key services prompt the user for static credentials (e.g., AWS, Cloudflare).
+ *
+ * This object is the single source of truth for all auth commands (login, logout,
+ * list, status, refresh). Add new services here -- all commands will pick them up.
+ */
+const AUTH_SERVICES = {
+  google: {
+    type: 'oauth',
+    authUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+    tokenUrl: 'https://oauth2.googleapis.com/token',
+    revokeUrl: 'https://oauth2.googleapis.com/revoke',
+    defaultScopes: ['openid', 'email', 'profile'],
+    clientFile: 'google.json'
+  },
+  aws: {
+    type: 'api-key',
+    fields: ['accessKeyId', 'secretAccessKey', 'region'],
+    fieldLabels: ['AWS Access Key ID', 'AWS Secret Access Key', 'Default Region']
+  },
+  cloudflare: {
+    type: 'api-key',
+    fields: ['apiToken'],
+    fieldLabels: ['Cloudflare API Token']
+  },
+  dokploy: {
+    type: 'api-key',
+    fields: ['apiUrl', 'apiToken'],
+    fieldLabels: ['Dokploy API URL', 'Dokploy API Token']
+  },
+  namecheap: {
+    type: 'api-key',
+    fields: ['apiUser', 'apiKey', 'clientIp'],
+    fieldLabels: ['Namecheap API User', 'API Key', 'Whitelisted Client IP']
+  },
+  flowroute: {
+    type: 'api-key',
+    fields: ['accessKey', 'secretKey'],
+    fieldLabels: ['Flowroute Access Key', 'Secret Key']
+  },
+  mailu: {
+    type: 'api-key',
+    fields: ['apiUrl', 'apiKey'],
+    fieldLabels: ['Mailu API URL', 'API Key']
+  }
+};
+
+/**
+ * Read a credential file from ~/.devutils/auth/<service>.json.
+ * Returns the parsed JSON content, or null if the file is missing or invalid.
+ *
+ * @param {string} service - The service name (e.g., 'google', 'aws').
+ * @returns {object|null} The parsed credential data, or null.
+ */
+function readCredential(service) {
+  const filePath = path.join(AUTH_DIR, `${service}.json`);
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Determine the status of a credential.
+ * - 'missing' means no credential file exists.
+ * - 'valid' means the credential exists and (for OAuth) is not expired.
+ * - 'expired' means the OAuth token's expiresAt is in the past.
+ * - 'unknown' means the credential exists but can't be evaluated.
+ *
+ * @param {object|null} credential - The parsed credential data from readCredential().
+ * @returns {string} One of 'missing', 'valid', 'expired', 'unknown'.
+ */
+function getTokenStatus(credential) {
+  if (!credential) return 'missing';
+  if (credential.type === 'api-key') return 'valid';
+  if (credential.type === 'oauth') {
+    if (!credential.expiresAt) return 'unknown';
+    return new Date(credential.expiresAt) > new Date() ? 'valid' : 'expired';
+  }
+  return 'unknown';
+}
+
+/**
+ * Check if a field name looks like it holds sensitive data.
+ * Fields with "secret", "key", "token", or "password" in the name
+ * should be masked in output and use password-style input.
+ *
+ * @param {string} fieldName - The field name to check.
+ * @returns {boolean} True if the field is sensitive.
+ */
+function isSensitiveField(fieldName) {
+  const lower = fieldName.toLowerCase();
+  return lower.includes('secret') ||
+    lower.includes('key') ||
+    lower.includes('token') ||
+    lower.includes('password');
+}
+
+/**
+ * Mask a sensitive value for display.
+ * Shows the first 4 and last 3 characters for partially-sensitive values,
+ * or '****' for fully-sensitive ones.
+ *
+ * @param {string} value - The value to mask.
+ * @param {boolean} fullMask - If true, mask the entire value with '****'.
+ * @returns {string} The masked value.
+ */
+function maskValue(value, fullMask) {
+  if (!value || typeof value !== 'string') return '****';
+  if (fullMask) return '****';
+  if (value.length <= 8) return '****';
+  return value.substring(0, 4) + '...' + value.substring(value.length - 3);
+}
+
+/**
+ * Format a time difference as a human-readable string.
+ * Handles both future ("47 minutes") and past ("expired 12 minutes ago") times.
+ *
+ * @param {Date} target - The target time (e.g., expiresAt).
+ * @param {Date} now - The current time.
+ * @returns {string} Human-readable duration string.
+ */
+function formatTimeDiff(target, now) {
+  const diffMs = target.getTime() - now.getTime();
+  const absDiffMs = Math.abs(diffMs);
+  const isPast = diffMs < 0;
+
+  let value;
+  if (absDiffMs < 60000) {
+    value = 'less than a minute';
+  } else if (absDiffMs < 3600000) {
+    const mins = Math.floor(absDiffMs / 60000);
+    value = `${mins} minute${mins === 1 ? '' : 's'}`;
+  } else if (absDiffMs < 86400000) {
+    const hours = Math.floor(absDiffMs / 3600000);
+    value = `${hours} hour${hours === 1 ? '' : 's'}`;
+  } else {
+    const days = Math.floor(absDiffMs / 86400000);
+    value = `${days} day${days === 1 ? '' : 's'}`;
+  }
+
+  return isPast ? `expired ${value} ago` : value;
+}
+
+module.exports = {
+  AUTH_SERVICES,
+  AUTH_DIR,
+  CLIENTS_DIR,
+  readCredential,
+  getTokenStatus,
+  isSensitiveField,
+  maskValue,
+  formatTimeDiff
+};

package/src/commands/auth/status.js

@@ -0,0 +1,104 @@
+'use strict';
+
+const {
+  AUTH_SERVICES,
+  readCredential,
+  getTokenStatus,
+  isSensitiveField,
+  maskValue,
+  formatTimeDiff
+} = require('./services');
+
+const meta = {
+  description: 'Show detailed auth state for one service',
+  arguments: [
+    { name: 'service', description: 'Service name to check', required: true }
+  ],
+  flags: []
+};
+
+/**
+ * Run the auth status command.
+ * Shows detailed credential information for a single service, including
+ * scopes and expiry for OAuth, or masked field values for API key services.
+ *
+ * @param {object} args - Parsed CLI arguments (positional, flags).
+ * @param {object} context - CLI context (output, prompt, errors).
+ */
+async function run(args, context) {
+  const service = args.positional[0];
+
+  if (!service) {
+    context.errors.throwError(400, 'Missing required argument: <service>. Example: dev auth status google', 'auth');
+    return;
+  }
+
+  const serviceConfig = AUTH_SERVICES[service];
+  if (!serviceConfig) {
+    const supported = Object.keys(AUTH_SERVICES).join(', ');
+    context.errors.throwError(400, `Unknown service '${service}'. Supported services: ${supported}`, 'auth');
+    return;
+  }
+
+  const credential = readCredential(service);
+  if (!credential) {
+    context.output.info(`Not authenticated with ${service}. Run "dev auth login ${service}" to connect.`);
+    return;
+  }
+
+  const status = getTokenStatus(credential);
+
+  if (credential.type === 'oauth') {
+    // Build detailed OAuth status
+    const now = new Date();
+    let expiresIn = null;
+
+    if (credential.expiresAt) {
+      expiresIn = formatTimeDiff(new Date(credential.expiresAt), now);
+    }
+
+    const result = {
+      service: service,
+      type: 'oauth',
+      status: status,
+      scopes: credential.scopes || [],
+      expiresAt: credential.expiresAt || '-',
+      expiresIn: expiresIn || '-',
+      authenticatedAt: credential.authenticatedAt || '-',
+      hasRefreshToken: !!credential.refreshToken
+    };
+
+    context.output.out(result);
+  } else if (credential.type === 'api-key') {
+    // Build detailed API key status with masked values
+    const fields = credential.credentials ? Object.keys(credential.credentials) : [];
+    const maskedValues = {};
+
+    for (const field of fields) {
+      const val = credential.credentials[field];
+      if (isSensitiveField(field)) {
+        // Fully mask sensitive fields
+        maskedValues[field] = maskValue(val, true);
+      } else {
+        // Show non-sensitive values in full (like region)
+        maskedValues[field] = val;
+      }
+    }
+
+    const result = {
+      service: service,
+      type: 'api-key',
+      status: status,
+      fields: fields,
+      maskedValues: maskedValues,
+      authenticatedAt: credential.authenticatedAt || '-'
+    };
+
+    context.output.out(result);
+  } else {
+    // Unknown credential type
+    context.output.info(`Credential file exists for ${service} but has an unrecognized type: ${credential.type}`);
+  }
+}
+
+module.exports = { meta, run };