@nextsparkjs/plugin-social-media-publisher 0.1.0-beta.1

package/entities/audit-logs/audit-logs.config.ts

@@ -0,0 +1,150 @@
+/**
+ * Audit Logs Entity Configuration
+ *
+ * Tracks all actions performed through the social media plugin
+ * For security, compliance, and debugging
+ */
+
+import type { EntityConfig } from '@nextsparkjs/core/lib/entities/types'
+
+export const auditLogsEntityConfig: any = {
+  name: 'audit-logs',
+  label: {
+    en: 'Social Media Audit Logs',
+    es: 'Registros de Auditoría de Redes Sociales'
+  },
+  description: {
+    en: 'Security and audit trail for social media actions',
+    es: 'Pista de auditoría y seguridad para acciones de redes sociales'
+  },
+
+  fields: [
+    {
+      name: 'user_id',
+      label: { en: 'User', es: 'Usuario' },
+      type: 'relation',
+      relation: {
+        entity: 'users',
+        titleField: 'email'
+      },
+      required: true,
+      index: true
+    },
+    {
+      name: 'account_id',
+      label: { en: 'Social Platform Account', es: 'Cuenta de Plataforma Social' },
+      type: 'relation',
+      relation: {
+        entity: 'social-platforms',
+        titleField: 'username'
+      },
+      required: false,
+      index: true
+    },
+    {
+      name: 'action',
+      label: { en: 'Action', es: 'Acción' },
+      type: 'select',
+      options: [
+        { value: 'account_connected', label: 'Account Connected' },
+        { value: 'account_disconnected', label: 'Account Disconnected' },
+        { value: 'post_published', label: 'Post Published' },
+        { value: 'post_failed', label: 'Post Failed' },
+        { value: 'token_refreshed', label: 'Token Refreshed' },
+        { value: 'token_refresh_failed', label: 'Token Refresh Failed' }
+      ],
+      required: true,
+      index: true
+    },
+    {
+      name: 'details',
+      label: { en: 'Details', es: 'Detalles' },
+      type: 'json',
+      default: {},
+      description: {
+        en: 'Action details: platform, success status, error messages, metadata',
+        es: 'Detalles de acción: plataforma, estado de éxito, mensajes de error, metadatos'
+      }
+    },
+    {
+      name: 'ip_address',
+      label: { en: 'IP Address', es: 'Dirección IP' },
+      type: 'string',
+      required: false,
+      description: {
+        en: 'User IP address at time of action',
+        es: 'Dirección IP del usuario al momento de la acción'
+      }
+    },
+    {
+      name: 'user_agent',
+      label: { en: 'User Agent', es: 'Agente de Usuario' },
+      type: 'string',
+      required: false,
+      description: {
+        en: 'Browser/device user agent string',
+        es: 'String de agente de usuario del navegador/dispositivo'
+      }
+    }
+  ],
+
+  // Database indexes for performance
+  indexes: [
+    {
+      fields: ['user_id', 'created_at'],
+      name: 'idx_audit_logs_user_created'
+    },
+    {
+      fields: ['account_id', 'action'],
+      name: 'idx_audit_logs_account_action'
+    },
+    {
+      fields: ['action', 'created_at'],
+      name: 'idx_audit_logs_action_created'
+    },
+    {
+      fields: ['created_at'],
+      name: 'idx_audit_logs_created',
+      order: 'DESC' // Most recent first
+    }
+  ],
+
+  // Row-level security
+  permissions: {
+    actions: [
+      {
+        action: 'create',
+        label: 'Create audit logs',
+        description: 'Can create audit log entries (typically system-only)',
+        defaultRoles: [], // Only system creates logs, no user role has this permission
+      },
+      {
+        action: 'read',
+        label: 'View audit logs',
+        description: 'Can view audit log entries',
+        defaultRoles: ['owner', 'admin'],
+      },
+      {
+        action: 'list',
+        label: 'List audit logs',
+        description: 'Can list audit log entries',
+        defaultRoles: ['owner', 'admin'],
+      },
+      {
+        action: 'update',
+        label: 'Edit audit logs',
+        description: 'Audit logs are immutable - no one can update',
+        defaultRoles: [], // Immutable - empty array
+      },
+      {
+        action: 'delete',
+        label: 'Delete audit logs',
+        description: 'Can delete old audit log entries',
+        defaultRoles: ['owner', 'admin'],
+        dangerous: true,
+      },
+    ],
+  }
+}
+
+export default auditLogsEntityConfig

package/lib/oauth-helper.ts

@@ -0,0 +1,167 @@
+/**
+ * OAuth Helper for Social Media Publishing
+ *
+ * Handles OAuth flow for connecting social accounts (NOT for authentication)
+ * This is separate from Better Auth providers which are for user login
+ *
+ * Supports:
+ * - Facebook OAuth (for Facebook Pages)
+ * - Instagram Graph API (via Facebook Pages - requires Instagram Business Account linked to Page)
+ */
+
+// Facebook OAuth endpoints (for Facebook Page + Instagram Graph API publishing)
+const FACEBOOK_OAUTH_URL = 'https://www.facebook.com/v18.0/dialog/oauth'
+const FACEBOOK_TOKEN_URL = 'https://graph.facebook.com/v18.0/oauth/access_token'
+
+export interface OAuthConfig {
+  // Facebook OAuth credentials (used for both Facebook Pages and Instagram Graph API)
+  facebookClientId: string
+  facebookClientSecret: string
+  // Shared redirect URI
+  redirectUri: string
+}
+
+/**
+ * Generate OAuth authorization URL for Facebook/Instagram publishing
+ *
+ * Both facebook_page and instagram_business use Facebook OAuth
+ * Instagram Graph API requires Facebook Pages with Instagram Business Account linked
+ *
+ * @param platform - 'facebook_page' or 'instagram_business'
+ * @param config - OAuth configuration
+ * @param state - CSRF protection state (store in session)
+ * @returns Authorization URL to redirect user to
+ */
+export function generateAuthorizationUrl(
+  platform: 'facebook_page' | 'instagram_business',
+  config: OAuthConfig,
+  state: string
+): string {
+  // Both platforms use Facebook OAuth
+  // instagram_business requires additional Instagram scopes
+  const scopes = [
+    'pages_show_list',
+    'pages_manage_posts',
+    'pages_read_engagement',
+    'read_insights',
+    'business_management', // Required to read instagram_business_account field from Pages
+  ]
+
+  // Add Instagram scopes for Instagram Graph API
+  if (platform === 'instagram_business') {
+    scopes.push(
+      'instagram_basic',
+      'instagram_content_publish',
+      'instagram_manage_comments'
+    )
+  }
+
+  const params = new URLSearchParams({
+    client_id: config.facebookClientId,
+    redirect_uri: config.redirectUri,
+    state,
+    scope: scopes.join(','),
+    response_type: 'code',
+  })
+
+  return `${FACEBOOK_OAUTH_URL}?${params.toString()}`
+}
+
+/**
+ * Exchange authorization code for access token
+ *
+ * Both facebook_page and instagram_business use Facebook OAuth endpoint
+ *
+ * @param code - Authorization code from callback
+ * @param config - OAuth configuration
+ * @param platform - Platform type (both use same endpoint now)
+ * @returns Access token data
+ */
+export async function exchangeCodeForToken(
+  code: string,
+  config: OAuthConfig,
+  platform: 'facebook_page' | 'instagram_business'
+): Promise<{
+  accessToken: string
+  expiresIn: number
+  tokenType: string
+  userId?: string
+}> {
+  // Both platforms use Facebook OAuth - GET with query params
+  const params = new URLSearchParams({
+    client_id: config.facebookClientId,
+    client_secret: config.facebookClientSecret,
+    redirect_uri: config.redirectUri,
+    code,
+  })
+
+  const response = await fetch(`${FACEBOOK_TOKEN_URL}?${params.toString()}`)
+
+  if (!response.ok) {
+    const errorText = await response.text()
+    throw new Error(`Facebook token exchange failed: ${errorText}`)
+  }
+
+  const data = await response.json()
+
+  if (data.error) {
+    throw new Error(
+      `Facebook OAuth error: ${data.error.message || data.error_description || data.error}`
+    )
+  }
+
+  return {
+    accessToken: data.access_token,
+    expiresIn: data.expires_in || 3600,
+    tokenType: data.token_type || 'Bearer',
+  }
+}
+
+/**
+ * Get OAuth configuration from environment
+ *
+ * Only requires Facebook credentials as Instagram Graph API uses same app
+ */
+export function getOAuthConfig(): OAuthConfig {
+  const facebookClientId = process.env.FACEBOOK_CLIENT_ID?.trim() || process.env.FACEBOOK_APP_ID?.trim()
+  const facebookClientSecret = process.env.FACEBOOK_CLIENT_SECRET?.trim() || process.env.FACEBOOK_APP_SECRET?.trim()
+  const baseUrl = (process.env.NEXT_PUBLIC_APP_URL || 'http://localhost:5173').trim()
+
+  if (!facebookClientId || !facebookClientSecret) {
+    throw new Error(
+      'FACEBOOK_CLIENT_ID (or FACEBOOK_APP_ID) and FACEBOOK_CLIENT_SECRET (or FACEBOOK_APP_SECRET) environment variables are required'
+    )
+  }
+
+  return {
+    facebookClientId,
+    facebookClientSecret,
+    redirectUri: `${baseUrl}/api/v1/plugin/social-media-publisher/social/connect/callback`,
+  }
+}
+
+/**
+ * Generate secure random state for CSRF protection
+ */
+export function generateState(): string {
+  return Array.from(crypto.getRandomValues(new Uint8Array(32)))
+    .map(b => b.toString(16).padStart(2, '0'))
+    .join('')
+}
+
+/**
+ * Validate state parameter to prevent CSRF attacks
+ * State should be stored in session and compared here
+ *
+ * @param receivedState - State from OAuth callback
+ * @param sessionState - State stored in session
+ * @returns true if states match
+ */
+export function validateState(receivedState: string, sessionState?: string): boolean {
+  if (!sessionState) {
+    console.warn('[oauth-helper] No session state found for validation')
+    return false
+  }
+
+  return receivedState === sessionState
+}