v1.0.2 — Add Permission Mapping Contracts for Module-Level Authorization

Release title

✨ Release Overview

This release introduces neutral permission mapping contracts to Maatify SharedCommon, providing a clean and framework-agnostic way for independent modules to expose their route-to-permission requirements.

The goal of this addition is to keep modules fully decoupled from AdminKernel while still allowing the consuming application or kernel layer to collect permission maps and convert them into its own authorization model.

---

✅ What’s New

• Permission Mapping Contracts

  • Added contracts under the Maatify\SharedCommon\Contracts\Security namespace
  • Allows modules to define permission requirements without depending on AdminKernel

• Permission Requirement Definition

  • Added PermissionRequirementDefinition
  • Supports:
    • single permission requirements
    • anyOf permission groups
    • allOf permission groups
    • compound anyOf + allOf requirements

• Permission Map Provider

  • Added PermissionMapProviderInterface
  • Enables modules to expose route-to-permission maps in a consistent and type-safe way

• Package-Level Permission Provider Discovery

  • Added ProvidesPermissionMapsInterface
  • Allows module/package entry points to expose one or more permission map providers

---

🏗 Why This Matters

Authorization mapping is a cross-cutting concern, but independent modules should not depend directly on application-specific or kernel-specific security implementations.

By introducing these contracts in SharedCommon, this release provides:

• a neutral dependency point for permission definitions
• cleaner separation between modules and AdminKernel
• safer module-level permission registration
• easier aggregation of permission maps at the application or kernel layer
• better support for reusable and independently packaged modules

---

📦 Installation

composer require maatify/shared-common

---

🔧 Requirements

• PHP 8.2+

---

📚 Documentation

This release is documented in:

• README.md
• CHANGELOG.md

The new contracts can be used by independent modules to expose permission requirements, while the consuming application or kernel layer remains responsible for collecting providers and converting the neutral definitions into its own authorization objects.

---

🔒 Security

If you discover a security issue, please review the project's
Security Policy.

---

📜 License

MIT License.

v1.0.1 — Add AppPaths Utility for Common Directory Resolution

✨ Release Overview

This release introduces AppPaths to Maatify SharedCommon, providing a
centralized and reusable utility for resolving common application directories.

The goal of this addition is to reduce duplicated path-building logic across
projects, improve consistency, and provide a clearer foundation for filesystem
and configuration access in a framework-agnostic way.

---

✅ What’s New

• Application Paths Utility

  • Added AppPaths under the Maatify\SharedCommon\Path namespace
  • Centralizes access to commonly used project directories

• Built-in Path Helpers

  • root()
  • publicPath()
  • publicImages()
  • storage()
  • config()
  • logs()

• Nested Storage Resolver

  • Added storagePath(string $subfolder) for consistent generation of
    subpaths inside the storage directory

---

🏗 Why This Matters

Applications often repeat filesystem path construction in multiple places,
which can lead to inconsistency and harder maintenance.

By introducing AppPaths, this release provides:

• a single source of truth for common directory resolution
• improved readability when accessing project paths
• easier reuse across modules and applications
• safer and clearer path handling in shared infrastructure code

---

📦 Installation

composer require maatify/shared-common

---

🔧 Requirements

• PHP 8.2+

---

📚 Documentation

This release is documented in:

• CHANGELOG.md

The new utility can be used directly in application and infrastructure layers
where centralized path resolution is needed.

---

🔒 Security

If you discover a security issue, please review the project's
Security Policy.

---

📜 License

MIT License.

v1.0.0 — Initial Stable Release of Maatify SharedCommon

🎉 Initial Stable Release

This is the first stable release of Maatify SharedCommon, a foundational
library providing shared contracts and abstractions used across the Maatify
ecosystem.

The goal of this package is to standardize common cross-cutting concerns such as
time handling, telemetry context, and security event context while keeping
modules framework-agnostic and easily testable.

---

✨ Key Features

• Clock Abstraction

  • ClockInterface for deterministic time handling
  • Default implementation: SystemClock
  • Improves testability by removing direct usage of time() and date()

• Telemetry Context Contract

  • Unified interface for propagating telemetry metadata across modules

• Security Event Context

  • Standardized structure for security-related event information

• Framework-Agnostic Design

  • No dependency on frameworks
  • Can be integrated with any DI container

• Dependency Injection Bindings

  • SharedCommonBindings helper for registering default implementations

---

🏗 Architecture

The module is intentionally minimal and focuses only on shared contracts used
by other Maatify components such as:

• AdminKernel
• Verification
• future infrastructure modules

This ensures consistent behavior across the entire ecosystem.

---

📦 Installation

composer require maatify/shared-common

---

🔧 Requirements

• PHP 8.2+

---

📚 Documentation

Full documentation is available in the project documentation book:

• Architecture overview
• Clock abstraction design
• Integration patterns
• Extension points

See the docs/book directory for details.

---

🔒 Security

If you discover a security issue, please review the project's
Security Policy.

---

📜 License

MIT License.