Metadata-Version: 2.4
Name: anyaccess
Version: 0.3.0
Summary: A modular Flask base for User Access Management with MariaDB, Valkey, and Google OAuth
Author-email: Philipglo Joshua Opulencia <opulence@khazu.net>
License: GPL-3.0-only
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flask
Requires-Dist: flask-bcrypt
Requires-Dist: flask-cors
Requires-Dist: flask_login
Requires-Dist: flask-mail
Requires-Dist: flask_restful
Requires-Dist: flask-session
Requires-Dist: flask_sqlalchemy
Requires-Dist: mysqlclient
Requires-Dist: python-dotenv
Requires-Dist: redis
Requires-Dist: requests
Requires-Dist: google-auth
Requires-Dist: google-auth-oauthlib
Requires-Dist: waitress
Dynamic: license-file

# AnyAccess

A modular Flask backend for User Access Management. This package provides a pre-configured architecture using **MariaDB** for data, **Valkey** (Redis) for session management, and **Google OAuth2** for authentication.

## 🛠 Prerequisites

For fedora-minimal, Ensure the system can handle mariadb:

```bash
sudo dnf install python3 mariadb-connector-c
```

## ⚙️ Configuration (.env)
For development, create a .env file in your project root with the following variables
For production, make sure these environment variables exist in you environment intead of a .env file

```bash
# File:Function to run the app
ANYACCESS_APP=main:serve_app 

# Database & Cache
MARIA_KEY=mysql://user:password@localhost/dbname
VALKEY_HOST=localhost

# Flask Security
FLASK_SECRET_KEY=your_secure_random_string
GLOBAL_SESSION_VERSION=1

# Google OAuth Credentials
GOOGLE_CLIENT_ID=your_id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_secret_key
CURRENT_URL=http://localhost:5000
GOOGLE_RETURN_FRONTEND=http://localhost:3000

# CORS Settings
ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000,http://192.168.128.35:3000,https://anyreact.khazu.net
```

## 🚀 Implementation Guide
A typical implementation involves two main files using the anyflask package.

1. init.py
This file initializes the core Flask application and its services.
```python
from flask import Flask, session
from anyaccess import AnyInit as AI

app = Flask(__name__)

# Modular Service Initialization
AI.initCORS(app)
AI.initValkey(app)
AI.initMariaDB(app)
AI.initAPILogin(app)

@app.before_request
def check_session_version():
  if session.get('ver') != AI.SESSION_VERSION:
    session.clear()
    session['ver'] = AI.SESSION_VERSION

def anyaccess_initcall():
  # Optional hook for custom initialization logic
  # will trigger when first user is created
  return True
```

2. main.py
This file handles the API routing and serves the application.
```python
from flask_restful import Api, Resource, reqparse
from init import app
from anyaccess import Account, Journal, AccountType, GoogleAuth, Authenticate

# Custom local resource example
class Test(Resource):
  test_data = reqparse.RequestParser()
  test_data.add_argument('test', required=True)

  def get(self):
    return {'status':'success'}

# API Registration
api = Api(app)
api.add_resource(Account, '/api/access/user')
api.add_resource(Journal, '/api/access/logs')
api.add_resource(AccountType, '/api/access/usertype')
api.add_resource(Authenticate, '/api/access/authenticate')
api.add_resource(GoogleAuth, '/api/access/google')
api.add_resource(Test, '/api/access/')

def serve_app():
  return app
```
## 🚀 Running AnyAccess

AnyAccess comes with a built-in CLI tool called `axs` to manage your server environments.

### Commands

| Command | Description | Example |
| :--- | :--- | :--- |
| **dev** | Runs the application in **Development Mode** (Flask). | `axs dev` |
| **prod** | Runs the application in **Production Mode** (Waitress). | `axs prod` |
| **version** | Displays version info for AnyAccess, Flask, and Waitress. | `axs version` |

### Configuration & Flags

#### Port Selection
Changes the listening port. If not specified, it **defaults to port 80**.
* **Example:** `axs prod --port=8000`

#### Environment Variables
You can customize the application behavior using environment variables:

* **`ANYACCESS_APP`**: Changes which function to execute.
  * **Default:** `main:serve_app`
  * **Example:** `ANYACCESS_APP=main:serve_app axs prod`

---

### Quick Examples

**Start a development server on 0.0.0.0:**
```bash
axs dev
```

## 🛠️ Database Initialization

Required to create the first user after running it for the first time to create database schema
* **Running the first user**:
```bash
curl --location 'http://127.0.0.1:5000/api/access/user' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username":"superaccess",
    "password":"strongpassword",
    "name":"Example User",
    "email":"example@example.com",
    "mobilenumber":"",
    "usertype":"superuser"
}'
```

AnyAccess features **Automatic Schema Generation**. 

* **How it works**: When the first user is created (via the `Account` resource), the system detects if the database is empty and runs `db.create_all()`.
* **Requirement**: Ensure your `MARIA_KEY` is set in your environment or `.env` file before starting.


## 🔐 Authentication Flow
First User: The first user registered via /api/access/user POST MUST be a superuser. This triggers the automatic initialization of the UserType table.

Google Login: Users can authenticate via Google. Accounts are automatically created with a google- prefix using the Google sub ID.

---

## 🗄️ Database Schema

AnyAccess automatically manages three core tables. Each table includes built-in `jsonify` methods to format data (like converting statuses and calculating relative "last activity" times).

### 1. Users (`access_user`)
Stores core account information and activity tracking.
* **Fields:** `userid`, `username`, `name`, `usertype`, `email`, `mobilenumber`, `status`, `last_activity`, `date_created`
* **Features:** Automatic relative time calculation (e.g., "active 5 mins ago").

### 2. User Types (`access_usertype`)
Defines roles and permissions via tags.
* **Fields:** `usertype`, `tags`, `status`, `date_created`
* **Features:** Automatic tag formatting for clean API responses.

### 3. Logs (`access_logs`)
Audit trails for system and user actions.
* **Fields:** `service`, `logtype`, `action_by`, `log`, `date_created`
* **Features:** Defaults to "access" service tracking.

---

