@progalaxyelabs/ngx-stonescriptphp-client 0.0.10 → 1.0.4

package/dist/ngx-stonescriptphp-client/index.d.ts

@@ -0,0 +1,184 @@
+import * as i0 from '@angular/core';
+import { ModuleWithProviders } from '@angular/core';
+import { BehaviorSubject } from 'rxjs';
+import * as i1 from '@angular/common';
+
+declare class TokenService {
+    private accessToken;
+    private refreshToken;
+    private lsAccessTokenKey;
+    private lsRefreshTokenKey;
+    constructor();
+    setTokens(accessToken: string, refreshToken: string): void;
+    setAccessToken(accessToken: string): void;
+    setRefreshToken(refreshToken: string): void;
+    getAccessToken(): string;
+    getRefreshToken(): string;
+    clear(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<TokenService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<TokenService>;
+}
+
+declare class SigninStatusService {
+    status: BehaviorSubject<boolean>;
+    constructor();
+    signedOut(): void;
+    signedIn(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SigninStatusService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SigninStatusService>;
+}
+
+declare class ApiResponse<DataType> {
+    private status;
+    private data;
+    private message;
+    constructor(status: string, data?: any, message?: string);
+    onOk(callback: (data: DataType) => void): ApiResponse<DataType>;
+    onNotOk(callback: (message: string, data: DataType) => void): ApiResponse<DataType>;
+    onError(callback: () => void): ApiResponse<DataType>;
+    isSuccess(): boolean;
+    isError(): boolean;
+    getData(): DataType | null;
+    getError(): string;
+    getStatus(): string;
+    getMessage(): string;
+}
+
+type AuthMode = 'cookie' | 'body' | 'none';
+interface AuthConfig {
+    /**
+     * Authentication mode:
+     * - 'cookie': Use httpOnly cookies + CSRF tokens (recommended, matches StoneScriptPHP v2.1.x)
+     * - 'body': Send tokens in request body (legacy mode)
+     * - 'none': No automatic token refresh
+     */
+    mode: AuthMode;
+    /**
+     * Token refresh endpoint path
+     * @default '/auth/refresh' for cookie mode, '/user/refresh_access' for body mode
+     */
+    refreshEndpoint?: string;
+    /**
+     * Enable CSRF token support (required for cookie mode)
+     * @default true for cookie mode, false for body mode
+     */
+    useCsrf?: boolean;
+    /**
+     * Cookie name for refresh token
+     * @default 'refresh_token'
+     */
+    refreshTokenCookieName?: string;
+    /**
+     * Cookie name for CSRF token
+     * @default 'csrf_token'
+     */
+    csrfTokenCookieName?: string;
+    /**
+     * CSRF header name
+     * @default 'X-CSRF-Token'
+     */
+    csrfHeaderName?: string;
+}
+declare class MyEnvironmentModel {
+    production: boolean;
+    firebase: {
+        projectId: string;
+        appId: string;
+        databaseURL: string;
+        storageBucket: string;
+        locationId: string;
+        apiKey: string;
+        authDomain: string;
+        messagingSenderId: string;
+        measurementId: string;
+    };
+    apiServer: {
+        host: string;
+    };
+    chatServer: {
+        host: string;
+    };
+    /**
+     * Authentication configuration
+     * @default { mode: 'cookie', refreshEndpoint: '/auth/refresh', useCsrf: true }
+     */
+    auth?: AuthConfig;
+}
+
+/**
+ * CSRF Token Service
+ *
+ * Manages CSRF tokens for cookie-based authentication.
+ * Reads CSRF token from cookies and provides it for request headers.
+ */
+declare class CsrfService {
+    /**
+     * Get CSRF token from cookie
+     */
+    getCsrfToken(cookieName?: string): string | null;
+    /**
+     * Check if CSRF token exists
+     */
+    hasCsrfToken(cookieName?: string): boolean;
+    /**
+     * Clear CSRF token (for logout)
+     * Note: Client-side deletion is limited for httpOnly cookies
+     */
+    clearCsrfToken(cookieName?: string): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CsrfService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CsrfService>;
+}
+
+declare class ApiConnectionService {
+    private tokens;
+    private signinStatus;
+    private environment;
+    private csrf;
+    private host;
+    private accessToken;
+    private authConfig;
+    constructor(tokens: TokenService, signinStatus: SigninStatusService, environment: MyEnvironmentModel, csrf: CsrfService);
+    private request;
+    private handleError;
+    get<DataType>(endpoint: string, queryParamsObj?: any): Promise<ApiResponse<DataType>>;
+    post<DataType>(pathWithQueryParams: string, data: any): Promise<ApiResponse<DataType>>;
+    put<DataType>(pathWithQueryParams: string, data: any): Promise<ApiResponse<DataType>>;
+    patch<DataType>(pathWithQueryParams: string, data: any): Promise<ApiResponse<DataType>>;
+    delete<DataType>(endpoint: string, queryParamsObj?: any): Promise<ApiResponse<DataType>>;
+    private includeAccessToken;
+    private refreshAccessTokenAndRetry;
+    refreshAccessToken(): Promise<boolean>;
+    /**
+     * Refresh access token using cookie-based auth (StoneScriptPHP v2.1.x default)
+     */
+    private refreshAccessTokenCookieMode;
+    /**
+     * Refresh access token using body-based auth (legacy mode)
+     */
+    private refreshAccessTokenBodyMode;
+    buildQueryString(options?: any): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ApiConnectionService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ApiConnectionService>;
+}
+
+declare class AuthService {
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<AuthService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AuthService>;
+}
+
+declare class DbService {
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<DbService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<DbService>;
+}
+
+declare class NgxStoneScriptPhpClientModule {
+    static forRoot(environment: MyEnvironmentModel): ModuleWithProviders<NgxStoneScriptPhpClientModule>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgxStoneScriptPhpClientModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<NgxStoneScriptPhpClientModule, never, [typeof i1.CommonModule], never>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<NgxStoneScriptPhpClientModule>;
+}
+
+export { ApiConnectionService, ApiResponse, AuthService, CsrfService, DbService, MyEnvironmentModel, NgxStoneScriptPhpClientModule, SigninStatusService, TokenService };
+export type { AuthConfig, AuthMode };

package/docs/AUTH_COMPATIBILITY.md

@@ -0,0 +1,310 @@
+# Authentication Compatibility Guide
+
+## StoneScriptPHP Framework vs ngx-stonescriptphp-client
+
+This document outlines the authentication flow compatibility between the Angular client library and StoneScriptPHP backend framework (v2.1.x).
+
+---
+
+## ⚠️ CRITICAL INCOMPATIBILITY FOUND
+
+### Token Refresh Endpoint Mismatch
+
+**CLIENT IMPLEMENTATION** (`api-connection.service.ts:187`):
+```typescript
+const refreshTokenUrl = this.host + 'user/refresh_access'
+await fetch(refreshTokenUrl, {
+    method: 'POST',
+    body: JSON.stringify({
+        access_token: this.accessToken,
+        refresh_token: refreshToken
+    })
+})
+```
+
+**SERVER IMPLEMENTATION** (StoneScriptPHP `RefreshRoute.php`):
+```php
+// Default route: POST /auth/refresh
+// OR custom: AuthRoutes::register($router, ['prefix' => '/api/auth']);
+
+// Expected request:
+// - Refresh token comes from httpOnly cookie (NOT request body)
+// - CSRF token required in X-CSRF-Token header
+// - Does NOT accept tokens in request body for security
+
+// Response:
+{
+    "status": "ok",
+    "data": {
+        "access_token": "eyJ...",
+        "expires_in": 900,
+        "token_type": "Bearer"
+    }
+}
+```
+
+### Issues Identified
+
+#### 1. **Endpoint Path Mismatch**
+- **Client expects**: `/user/refresh_access`
+- **Server provides**: `/auth/refresh` (default) or custom prefix
+
+#### 2. **Token Transmission Mismatch**
+- **Client sends**: Tokens in JSON request body
+- **Server expects**:
+  - Refresh token in httpOnly cookie (named `refresh_token`)
+  - CSRF token in `X-CSRF-Token` header
+  - **Does NOT read tokens from request body**
+
+#### 3. **Security Model Mismatch**
+- **Client**: Stores tokens in localStorage/sessionStorage (via TokenService)
+- **Server**: Uses httpOnly cookies + CSRF protection (XSS-safe)
+
+#### 4. **Response Format Mismatch**
+- **Client expects**: `response.data.access_token`
+- **Server returns**: `ApiResponse` where data is the second parameter:
+  ```php
+  return new ApiResponse('ok', [
+      'access_token' => $token,
+      'expires_in' => 900,
+      'token_type' => 'Bearer'
+  ]);
+  ```
+
+---
+
+## Authentication Flow Analysis
+
+### StoneScriptPHP Framework Auth System
+
+The framework provides **two authentication modes**:
+
+#### Mode 1: Built-in Cookie-Based Auth (Secure, Recommended)
+Located in `/src/Auth/Routes/`:
+- `POST /auth/refresh` - Refresh access token using httpOnly cookies
+- `POST /auth/logout` - Logout and invalidate refresh token
+
+**Security Features**:
+- httpOnly cookies prevent XSS attacks
+- CSRF token protection
+- Refresh token rotation
+- Optional token blacklisting via `TokenStorageInterface`
+
+**Registration**:
+```php
+// In your index.php or bootstrap
+use StoneScriptPHP\Auth\AuthRoutes;
+
+AuthRoutes::register($router, [
+    'prefix' => '/auth',  // or '/api/auth'
+    'token_storage' => $tokenStorage  // optional
+]);
+```
+
+#### Mode 2: Custom Implementation (Templates)
+Located in `/src/Templates/Auth/`:
+- `email-password/LoginRoute.php.template`
+- `email-password/RegisterRoute.php.template`
+- `email-password/PasswordResetRoute.php.template`
+- `mobile-otp/SendOtpRoute.php.template`
+- And more...
+
+**Note**: Templates are **scaffolding code** that developers customize. They show:
+- Example status values: `'success'` vs `'ok'` (inconsistent!)
+- Example token format
+- Database queries
+- But are NOT the actual built-in implementation
+
+---
+
+## Current Client Implementation Analysis
+
+### What Works ✅
+
+1. **HTTP Methods**: All match (GET, POST, PUT, PATCH, DELETE)
+2. **ApiResponse Structure**: Compatible
+   - Client expects: `{ status: string, message: string, data: any }`
+   - Server returns: Same structure
+3. **Bearer Token Authentication**: Client correctly adds `Authorization: Bearer {token}`
+4. **Automatic 401 Retry**: Client attempts token refresh on 401 errors
+
+### What's Broken ❌
+
+1. **Token Refresh Flow**: Completely incompatible
+   - Different endpoint paths
+   - Different token transmission method
+   - Different security model
+
+2. **AuthService**: Empty placeholder (no implementation)
+
+3. **Login/Register Endpoints**: Not standardized
+   - Templates show `/api/auth/login` but customizable
+   - Response format varies (some templates use `'success'` vs `'ok'`)
+
+---
+
+## Compatibility Matrix
+
+| Feature | Client (v0.0.13) | Framework (v2.1.x) | Compatible? |
+|---------|------------------|-------------------|-------------|
+| **HTTP Methods** | GET, POST, PUT, PATCH, DELETE | All supported | ✅ Yes |
+| **ApiResponse Format** | `{status, message, data}` | Same | ✅ Yes |
+| **Bearer Auth** | `Authorization: Bearer {token}` | Same | ✅ Yes |
+| **Token Refresh Endpoint** | `/user/refresh_access` | `/auth/refresh` | ❌ No |
+| **Token Storage** | localStorage | httpOnly cookies | ❌ No |
+| **CSRF Protection** | Not implemented | Required | ❌ No |
+| **Login Endpoint** | Not defined | Custom (templates) | ⚠️ Varies |
+| **Token Format** | JWT in response body | JWT in cookie + body | ⚠️ Partial |
+
+---
+
+## Recommended Solutions
+
+### Option 1: Update Client to Match Framework (Recommended)
+
+**Pros**:
+- Better security (httpOnly cookies)
+- CSRF protection
+- Aligns with framework best practices
+
+**Cons**:
+- Breaking change for existing users
+- Requires cookie handling
+
+**Implementation**:
+1. Update `refreshAccessToken()` to:
+   - Call `POST /auth/refresh` with credentials: 'include'
+   - Send CSRF token from cookie
+   - Don't send tokens in body
+2. Add `CsrfService` to manage CSRF tokens
+3. Update `TokenService` to work with cookies
+4. Add cookie configuration to `MyEnvironmentModel`
+
+### Option 2: Add Server-Side Compatibility Endpoint
+
+**Pros**:
+- No client breaking changes
+- Backward compatible
+
+**Cons**:
+- Less secure (tokens in body)
+- Developers must implement it
+
+**Implementation**:
+Create custom route in StoneScriptPHP project:
+```php
+// src/App/Routes/LegacyRefreshRoute.php
+class LegacyRefreshRoute implements IRouteHandler {
+    public function process(): ApiResponse {
+        // Read tokens from request body
+        $accessToken = request()->input['access_token'] ?? null;
+        $refreshToken = request()->input['refresh_token'] ?? null;
+
+        // Verify and refresh...
+        // Return new access token
+    }
+}
+
+// Register in routes.php
+'POST' => [
+    '/user/refresh_access' => LegacyRefreshRoute::class
+]
+```
+
+### Option 3: Make Client Configurable
+
+**Pros**:
+- Supports both modes
+- Migration path
+
+**Cons**:
+- More complex
+- Maintenance burden
+
+**Implementation**:
+```typescript
+export interface AuthConfig {
+    mode: 'cookie' | 'body';
+    refreshEndpoint: string;
+    useCsrf: boolean;
+}
+```
+
+---
+
+## Migration Path for Existing Apps
+
+For apps currently using the client with custom backends:
+
+### Step 1: Check Your Backend Auth Implementation
+```bash
+# Does your backend match the client's expectations?
+curl -X POST http://localhost:8000/user/refresh_access \
+  -H "Content-Type: application/json" \
+  -d '{"access_token": "...", "refresh_token": "..."}'
+```
+
+### Step 2: Update to StoneScriptPHP v2.1.x Auth
+```php
+// Option A: Use built-in secure auth
+AuthRoutes::register($router, ['prefix' => '/api/auth']);
+
+// Option B: Create legacy compatibility route
+// See Option 2 above
+```
+
+### Step 3: Update Client Configuration
+```typescript
+// Wait for v0.0.14+ with auth config support
+// OR implement custom auth service extending ApiConnectionService
+```
+
+---
+
+## Action Items for Next Release (v0.0.14)
+
+### Must Fix (Breaking Changes Acceptable):
+1. ✅ Add configurable auth endpoints
+2. ✅ Implement cookie-based auth mode
+3. ✅ Add CSRF token support
+4. ✅ Update AuthService with actual implementation
+5. ✅ Document both auth modes
+
+### Should Have:
+1. Add login/register/logout helper methods
+2. Add auth state management (RxJS)
+3. Add auth guards/interceptors examples
+4. Create migration guide with code examples
+
+### Nice to Have:
+1. Social auth helpers (Google, etc.)
+2. Password reset flow helpers
+3. Email verification helpers
+4. Multi-factor auth support
+
+---
+
+## Conclusion
+
+**Current Status**: ❌ **NOT FULLY COMPATIBLE**
+
+The v0.0.13 client library is **compatible for general API calls** (CRUD operations) but **incompatible for authentication flows**.
+
+### For Developers:
+- ✅ Use for: CRUD API calls with manually managed auth
+- ❌ Don't use: Built-in token refresh (broken)
+- ⚠️ Workaround: Implement custom refresh logic or wait for v0.0.14
+
+### For Package Maintainers:
+- 🔴 **Priority**: Fix auth compatibility before promoting package
+- 📝 Add clear warnings in README about auth limitations
+- 🚀 Plan v0.0.14 with breaking changes to align with framework
+
+---
+
+## References
+
+- **StoneScriptPHP Auth**: `/src/Auth/Routes/RefreshRoute.php`
+- **Client Auth**: `/projects/ngx-stonescriptphp-client/src/lib/api-connection.service.ts`
+- **Framework Version**: v2.1.x (on Packagist)
+- **Client Version**: v0.0.13