@artilingo/artiframe-cli 1.1.3 → 1.2.0

package/stubs/service/jwt.stub

@@ -0,0 +1,312 @@
+<?php
+
+namespace Auth;
+
+use Firebase\JWT\JWT;
+use Firebase\JWT\Key;
+use Firebase\JWT\ExpiredException;
+use Firebase\JWT\SignatureInvalidException;
+use Firebase\JWT\BeforeValidException;
+
+/**
+ * JWT Authentication Service
+ *
+ * Provides a clean wrapper around firebase/php-jwt for token generation,
+ * verification, refresh, and HTTP middleware integration.
+ *
+ * Required environment variables:
+ *   JWT_SECRET_KEY — Secret key used for signing and verifying tokens
+ *   JWT_ALGORITHM  — Signing algorithm (e.g. HS256, HS384, HS512)
+ *   JWT_EXPIRY     — Default token lifetime in seconds (e.g. 3600)
+ *
+ * @package Auth
+ */
+class JwtAuth
+{
+    /**
+     * Secret key for signing tokens.
+     *
+     * @var string
+     */
+    private string $secretKey;
+
+    /**
+     * Signing algorithm (HS256, HS384, HS512, etc.).
+     *
+     * @var string
+     */
+    private string $algorithm;
+
+    /**
+     * Default token expiry in seconds.
+     *
+     * @var int
+     */
+    private int $expiry;
+
+    /**
+     * Create a new JwtAuth instance.
+     *
+     * Loads the secret key, algorithm, and default expiry from $_ENV.
+     */
+    public function __construct()
+    {
+        $this->secretKey = $_ENV['JWT_SECRET_KEY'];
+        $this->algorithm = $_ENV['JWT_ALGORITHM'] ?? 'HS256';
+        $this->expiry    = (int) ($_ENV['JWT_EXPIRY'] ?? 3600);
+    }
+
+    /**
+     * Generate a signed JWT token.
+     *
+     * Merges the given payload with standard claims (iat, exp) and encodes it.
+     *
+     * @param array    $payload Custom claims to include in the token
+     * @param int|null $expiry  Token lifetime in seconds (null = use default from $_ENV)
+     * @return string Encoded JWT token string
+     */
+    public function generate(array $payload, int $expiry = null): string
+    {
+        $now       = time();
+        $expiresIn = $expiry ?? $this->expiry;
+
+        $tokenPayload = array_merge($payload, [
+            'iat' => $now,
+            'exp' => $now + $expiresIn,
+        ]);
+
+        return JWT::encode($tokenPayload, $this->secretKey, $this->algorithm);
+    }
+
+    /**
+     * Verify and decode a JWT token.
+     *
+     * Returns a standardised response array with the decoded payload on success
+     * or an error message on failure.
+     *
+     * @param string $token The JWT token to verify
+     * @return array {
+     *     @type string $status  'success' or 'error'
+     *     @type string $message Human-readable result description
+     *     @type array  $data    Decoded payload (on success only)
+     * }
+     */
+    public function verify(string $token): array
+    {
+        try {
+            $decoded = JWT::decode($token, new Key($this->secretKey, $this->algorithm));
+            $payload = (array) $decoded;
+
+            return [
+                'status'  => 'success',
+                'message' => 'Token is valid.',
+                'data'    => $payload,
+            ];
+        } catch (ExpiredException $e) {
+            return [
+                'status'  => 'error',
+                'message' => 'Token has expired.',
+                'data'    => [],
+            ];
+        } catch (SignatureInvalidException $e) {
+            return [
+                'status'  => 'error',
+                'message' => 'Invalid token signature.',
+                'data'    => [],
+            ];
+        } catch (BeforeValidException $e) {
+            return [
+                'status'  => 'error',
+                'message' => 'Token is not yet valid.',
+                'data'    => [],
+            ];
+        } catch (\Exception $e) {
+            return [
+                'status'  => 'error',
+                'message' => 'Token verification failed: ' . $e->getMessage(),
+                'data'    => [],
+            ];
+        }
+    }
+
+    /**
+     * Extract the payload from a token without throwing exceptions.
+     *
+     * Useful when you need to inspect claims even if the token might be invalid.
+     * Returns null on any failure instead of throwing.
+     *
+     * @param string $token The JWT token to decode
+     * @return array|null Decoded payload or null on failure
+     */
+    public function payload(string $token): ?array
+    {
+        try {
+            $decoded = JWT::decode($token, new Key($this->secretKey, $this->algorithm));
+            return (array) $decoded;
+        } catch (\Exception $e) {
+            return null;
+        }
+    }
+
+    /**
+     * Refresh a token by generating a new one with the same payload.
+     *
+     * Strips the old iat/exp claims and re-signs with a fresh expiry.
+     * Returns null if the original token cannot be decoded.
+     *
+     * @param string   $token  The current JWT token to refresh
+     * @param int|null $expiry New expiry duration in seconds (null = use default)
+     * @return string|null New JWT token or null on failure
+     */
+    public function refresh(string $token, int $expiry = null): ?string
+    {
+        try {
+            $decoded = JWT::decode($token, new Key($this->secretKey, $this->algorithm));
+            $payload = (array) $decoded;
+
+            // Remove old timing claims so generate() sets fresh ones
+            unset($payload['iat'], $payload['exp'], $payload['nbf']);
+
+            return $this->generate($payload, $expiry);
+        } catch (\Exception $e) {
+            return null;
+        }
+    }
+
+    /**
+     * Check whether a token has expired.
+     *
+     * Attempts to decode the token and catches ExpiredException specifically.
+     * Returns true if expired, false if still valid or on other errors.
+     *
+     * @param string $token The JWT token to check
+     * @return bool True if the token is expired
+     */
+    public function isExpired(string $token): bool
+    {
+        try {
+            JWT::decode($token, new Key($this->secretKey, $this->algorithm));
+            return false;
+        } catch (ExpiredException $e) {
+            return true;
+        } catch (\Exception $e) {
+            // Token is invalid for another reason, not strictly "expired"
+            return false;
+        }
+    }
+
+    /**
+     * Extract the user_id claim from a token.
+     *
+     * A convenience shortcut for the most common payload lookup.
+     *
+     * @param string $token The JWT token
+     * @return mixed The user_id value or null if not present / token invalid
+     */
+    public function getUserId(string $token): mixed
+    {
+        $payload = $this->payload($token);
+
+        if ($payload === null) {
+            return null;
+        }
+
+        return $payload['user_id'] ?? null;
+    }
+
+    /**
+     * Generate a long-lived refresh token.
+     *
+     * Identical to generate() but with a longer default expiry (7 days).
+     * Adds a 'token_type' => 'refresh' claim to distinguish from access tokens.
+     *
+     * @param array $payload Custom claims to include
+     * @param int   $expiry  Lifetime in seconds (default: 604800 = 7 days)
+     * @return string Encoded refresh token
+     */
+    public function generateRefreshToken(array $payload, int $expiry = 604800): string
+    {
+        $payload['token_type'] = 'refresh';
+
+        return $this->generate($payload, $expiry);
+    }
+
+    /**
+     * HTTP middleware that validates the Authorization header.
+     *
+     * Reads the Bearer token from the Authorization header, verifies it, and
+     * sets $_REQUEST['jwt_user'] with the decoded payload on success.
+     * On failure, sends a 401 JSON response via apiResponse() and exits.
+     *
+     * Usage:
+     *   JwtAuth::middleware();
+     *   // If execution reaches here, $_REQUEST['jwt_user'] is available
+     *
+     * @return void
+     */
+    public static function middleware(): void
+    {
+        $instance = new self();
+
+        // Extract Bearer token from Authorization header
+        $authHeader = $_SERVER['HTTP_AUTHORIZATION']
+            ?? $_SERVER['REDIRECT_HTTP_AUTHORIZATION']
+            ?? '';
+
+        if (empty($authHeader)) {
+            if (function_exists('apiResponse')) {
+                apiResponse(401, 'Authorization header is missing.');
+            } else {
+                http_response_code(401);
+                header('Content-Type: application/json');
+                echo json_encode([
+                    'status'  => 'error',
+                    'code'    => 401,
+                    'message' => 'Authorization header is missing.',
+                ]);
+            }
+            exit;
+        }
+
+        // Strip "Bearer " prefix
+        $token = '';
+        if (preg_match('/^Bearer\s+(.+)$/i', $authHeader, $matches)) {
+            $token = $matches[1];
+        }
+
+        if (empty($token)) {
+            if (function_exists('apiResponse')) {
+                apiResponse(401, 'Bearer token is missing.');
+            } else {
+                http_response_code(401);
+                header('Content-Type: application/json');
+                echo json_encode([
+                    'status'  => 'error',
+                    'code'    => 401,
+                    'message' => 'Bearer token is missing.',
+                ]);
+            }
+            exit;
+        }
+
+        $result = $instance->verify($token);
+
+        if ($result['status'] !== 'success') {
+            if (function_exists('apiResponse')) {
+                apiResponse(401, $result['message']);
+            } else {
+                http_response_code(401);
+                header('Content-Type: application/json');
+                echo json_encode([
+                    'status'  => 'error',
+                    'code'    => 401,
+                    'message' => $result['message'],
+                ]);
+            }
+            exit;
+        }
+
+        // Attach decoded user payload to the request superglobal
+        $_REQUEST['jwt_user'] = $result['data'];
+    }
+}

package/stubs/service/phpmailer.stub

@@ -0,0 +1,143 @@
+<?php
+namespace App\Service;
+
+use PHPMailer\PHPMailer\PHPMailer;
+use PHPMailer\PHPMailer\Exception;
+
+/**
+ * ArtiFrame Mailer Wrapper for PHPMailer
+ * 
+ * Provides a clean, fluent API on top of the battle-tested PHPMailer library.
+ * Handles complex RFC standards, TLS handshakes, and CRLF injections automatically.
+ */
+class Mailer
+{
+    private PHPMailer $mail;
+
+    public function __construct()
+    {
+        $this->mail = new PHPMailer(true);
+        
+        // SMTP Configuration from .env
+        $this->mail->isSMTP();
+        $this->mail->Host       = $_ENV['MAIL_HOST'] ?? 'localhost';
+        $this->mail->SMTPAuth   = !empty($_ENV['MAIL_USERNAME']);
+        $this->mail->Username   = $_ENV['MAIL_USERNAME'] ?? '';
+        $this->mail->Password   = $_ENV['MAIL_PASSWORD'] ?? '';
+        
+        $encryption = strtolower($_ENV['MAIL_ENCRYPTION'] ?? '');
+        if ($encryption === 'tls') {
+            $this->mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
+        } elseif ($encryption === 'ssl') {
+            $this->mail->SMTPSecure = PHPMailer::ENCRYPTION_SMTPS;
+        }
+
+        $this->mail->Port       = $_ENV['MAIL_PORT'] ?? 25;
+        
+        // Security & Formatting Defaults
+        $this->mail->CharSet    = 'UTF-8';
+        $this->mail->Encoding   = 'base64';
+
+        $this->mail->setFrom(
+            $_ENV['MAIL_FROM_ADDRESS'] ?? 'hello@example.com',
+            $_ENV['MAIL_FROM_NAME'] ?? 'ArtiFrame'
+        );
+    }
+
+    /**
+     * Instantiates a new Mailer instance for fluent chaining.
+     */
+    public static function create(): self
+    {
+        return new self();
+    }
+
+    /**
+     * Add a primary recipient.
+     */
+    public function to(string $email, string $name = ''): self
+    {
+        $this->mail->addAddress($email, $name);
+        return $this;
+    }
+
+    /**
+     * Add a Carbon Copy (CC) recipient.
+     */
+    public function cc(string $email, string $name = ''): self
+    {
+        $this->mail->addCC($email, $name);
+        return $this;
+    }
+
+    /**
+     * Add a Blind Carbon Copy (BCC) recipient.
+     */
+    public function bcc(string $email, string $name = ''): self
+    {
+        $this->mail->addBCC($email, $name);
+        return $this;
+    }
+
+    /**
+     * Set the email subject.
+     */
+    public function subject(string $subject): self
+    {
+        $this->mail->Subject = $subject;
+        return $this;
+    }
+
+    /**
+     * Set the body format to HTML. Automatically generates an AltBody (Plain Text) version.
+     */
+    public function html(string $html, ?string $altText = null): self
+    {
+        $this->mail->isHTML(true);
+        $this->mail->Body = $html;
+        $this->mail->AltBody = $altText ?? strip_tags(str_replace(['<br>', '<br/>'], "\n", $html));
+        return $this;
+    }
+
+    /**
+     * Set the body format to strict Plain Text.
+     */
+    public function text(string $text): self
+    {
+        $this->mail->isHTML(false);
+        $this->mail->Body = $text;
+        return $this;
+    }
+
+    /**
+     * Attach a file (PDF, DOCX, ZIP, etc.)
+     */
+    public function attach(string $path, string $name = ''): self
+    {
+        $this->mail->addAttachment($path, $name);
+        return $this;
+    }
+
+    /**
+     * Embed an inline image for HTML rendering (e.g., logo).
+     * Usage in HTML: <img src="cid:YOUR_CID">
+     */
+    public function embedImage(string $path, string $cid, string $name = ''): self
+    {
+        $this->mail->addEmbeddedImage($path, $cid, $name);
+        return $this;
+    }
+
+    /**
+     * Execute the SMTP transmission.
+     * @throws \Exception
+     */
+    public function send(): bool
+    {
+        try {
+            return $this->mail->send();
+        } catch (Exception $e) {
+            throw new \Exception("SMTP Mailer Error: " . $this->mail->ErrorInfo);
+        }
+    }
+}

package/stubs/service/pusher.stub

@@ -0,0 +1,232 @@
+<?php
+
+namespace Service;
+
+use Pusher\Pusher;
+
+/**
+ * Pusher Realtime Service
+ *
+ * Provides a clean interface for Pusher Channels — broadcasting events,
+ * authenticating private/presence channels, and querying channel state.
+ * Uses the pusher/pusher-php-server SDK. All configuration from $_ENV.
+ *
+ * Required environment variables:
+ *   PUSHER_APP_ID     — Your Pusher application ID
+ *   PUSHER_APP_KEY    — Your Pusher application key
+ *   PUSHER_APP_SECRET — Your Pusher application secret
+ *   PUSHER_CLUSTER    — Pusher cluster region (e.g., 'eu', 'us2', 'ap1')
+ *
+ * @package Service
+ */
+class PusherService
+{
+    /**
+     * The Pusher SDK client instance.
+     *
+     * @var \Pusher\Pusher
+     */
+    private Pusher $pusher;
+
+    /**
+     * Create a new PusherService instance.
+     *
+     * Initializes the Pusher SDK client using credentials
+     * and cluster configuration from environment variables.
+     *
+     * @throws \Pusher\PusherException If credentials are invalid or missing
+     */
+    public function __construct()
+    {
+        $this->pusher = new Pusher(
+            $_ENV['PUSHER_APP_KEY'],
+            $_ENV['PUSHER_APP_SECRET'],
+            $_ENV['PUSHER_APP_ID'],
+            [
+                'cluster'   => $_ENV['PUSHER_CLUSTER'] ?? 'mt1',
+                'useTLS'    => true,
+                'encrypted' => true,
+            ]
+        );
+    }
+
+    /**
+     * Broadcast an event to a single channel.
+     *
+     * Triggers an event on the specified channel, delivering
+     * the given data payload to all subscribers of that channel.
+     *
+     * Channel naming conventions:
+     *   - Public channels: 'my-channel'
+     *   - Private channels: 'private-my-channel'
+     *   - Presence channels: 'presence-my-channel'
+     *
+     * @param  string $channel The channel name to broadcast on
+     * @param  string $event   The event name to trigger
+     * @param  array  $data    The event payload data
+     * @return bool            True on success, false on failure
+     */
+    public function broadcast(string $channel, string $event, array $data): bool
+    {
+        try {
+            $response = $this->pusher->trigger($channel, $event, $data);
+
+            return (bool) $response;
+        } catch (\Exception $e) {
+            return false;
+        }
+    }
+
+    /**
+     * Broadcast an event to multiple channels simultaneously.
+     *
+     * Triggers the same event with the same payload across
+     * multiple channels in a single API call. Pusher limits
+     * this to a maximum of 100 channels per call.
+     *
+     * @param  array  $channels List of channel names (max 100)
+     * @param  string $event    The event name to trigger
+     * @param  array  $data     The event payload data
+     * @return bool             True on success, false on failure
+     */
+    public function broadcastToMany(array $channels, string $event, array $data): bool
+    {
+        try {
+            $response = $this->pusher->trigger($channels, $event, $data);
+
+            return (bool) $response;
+        } catch (\Exception $e) {
+            return false;
+        }
+    }
+
+    /**
+     * Send an event to a specific user via their user channel.
+     *
+     * Uses Pusher's user event feature to deliver a message directly
+     * to a single authenticated user, regardless of which channels
+     * they are subscribed to. The user must have been authenticated
+     * with a user ID on the client side.
+     *
+     * @param  string $userId The target user's unique identifier
+     * @param  string $event  The event name to trigger
+     * @param  array  $data   The event payload data
+     * @return bool           True on success, false on failure
+     */
+    public function toUser(string $userId, string $event, array $data): bool
+    {
+        try {
+            $response = $this->pusher->sendToUser($userId, $event, $data);
+
+            return (bool) $response;
+        } catch (\Exception $e) {
+            return false;
+        }
+    }
+
+    /**
+     * Get information about a specific channel.
+     *
+     * Returns metadata about the channel including whether it is
+     * currently occupied and, for presence channels, the user count.
+     *
+     * @param  string $channel The channel name to query
+     * @return array           Channel info ['occupied' => bool, 'user_count' => int|null]
+     *                         Returns empty array on failure
+     */
+    public function channelInfo(string $channel): array
+    {
+        try {
+            $info = $this->pusher->getChannelInfo($channel, [
+                'info' => 'user_count,subscription_count',
+            ]);
+
+            return [
+                'occupied'           => $info->occupied ?? false,
+                'user_count'         => $info->user_count ?? null,
+                'subscription_count' => $info->subscription_count ?? null,
+            ];
+        } catch (\Exception $e) {
+            return [];
+        }
+    }
+
+    /**
+     * List all active (occupied) channels.
+     *
+     * Optionally filters channels by a name prefix. For example,
+     * passing 'presence-' will return only active presence channels.
+     *
+     * @param  string $prefix Optional channel name prefix filter
+     * @return array          List of active channel names
+     */
+    public function channels(string $prefix = ''): array
+    {
+        try {
+            $params = [];
+
+            if ($prefix !== '') {
+                $params['filter_by_prefix'] = $prefix;
+            }
+
+            $result = $this->pusher->getChannels($params);
+
+            if (isset($result->channels)) {
+                return array_keys((array) $result->channels);
+            }
+
+            return [];
+        } catch (\Exception $e) {
+            return [];
+        }
+    }
+
+    /**
+     * Authenticate a private or presence channel subscription.
+     *
+     * This method should be called from your authentication endpoint
+     * when a client attempts to subscribe to a private or presence channel.
+     * Returns the authentication signature string that the client SDK expects.
+     *
+     * For presence channels, use presenceAuth() instead to include user data.
+     *
+     * @param  string $channelName The channel being subscribed to
+     * @param  string $socketId    The connecting socket's ID
+     * @return string              JSON-encoded authentication response
+     */
+    public function auth(string $channelName, string $socketId): string
+    {
+        try {
+            return $this->pusher->authorizeChannel($channelName, $socketId);
+        } catch (\Exception $e) {
+            return json_encode(['error' => $e->getMessage()]);
+        }
+    }
+
+    /**
+     * Authenticate a presence channel subscription with user data.
+     *
+     * Similar to auth() but also attaches user identity and optional
+     * metadata to the presence channel. This allows other subscribers
+     * to see who is present in the channel.
+     *
+     * @param  string $channelName The presence channel being subscribed to
+     * @param  string $socketId    The connecting socket's ID
+     * @param  string $userId      The unique identifier for the subscribing user
+     * @param  array  $userInfo    Optional additional user metadata (e.g., name, avatar)
+     * @return string              JSON-encoded authentication response with user data
+     */
+    public function presenceAuth(string $channelName, string $socketId, string $userId, array $userInfo = []): string
+    {
+        try {
+            $presenceData = [
+                'user_id'   => $userId,
+                'user_info' => $userInfo,
+            ];
+
+            return $this->pusher->authorizePresenceChannel($channelName, $socketId, $userId, $userInfo);
+        } catch (\Exception $e) {
+            return json_encode(['error' => $e->getMessage()]);
+        }
+    }
+}