Nodarx/server
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

resource provider and service improvements

Browse Source
This commit is contained in:
root
2026-01-03 13:18:04 -05:00
parent 74f9278749
commit 8f35442335
36 changed files with 1447 additions and 1086 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
shared/lib/Files/Provider/IProviderBase.php
View File

@@ -9,88 +9,8 @@ declare(strict_types=1);
namespace KTXF\Files\Provider;
use JsonSerializable;
use KTXF\Files\Service\IServiceBase;
use KTXF\Resource\Provider\ResourceProviderInterface;
interface IProviderBase extends JsonSerializable {
public const CAPABILITY_SERVICE_LIST = 'ServiceList';
public const CAPABILITY_SERVICE_FETCH = 'ServiceFetch';
public const CAPABILITY_SERVICE_EXTANT = 'ServiceExtant';
public const JSON_TYPE = 'files.provider';
public const JSON_PROPERTY_TYPE = '@type';
public const JSON_PROPERTY_ID = 'id';
public const JSON_PROPERTY_LABEL = 'label';
public const JSON_PROPERTY_CAPABILITIES = 'capabilities';
/**
* Confirms if specific capability is supported (e.g. 'ServiceList')
*
* @since 2025.11.01
*/
public function capable(string $value): bool;
/**
* Lists all supported capabilities
*
* @since 2025.11.01
*
* @return array<string,bool>
*/
public function capabilities(): array;
/**
* An arbitrary unique text string identifying this provider (e.g. UUID or 'system' or anything else)
*
* @since 2025.11.01
*/
public function id(): string;
/**
* The localized human friendly name of this provider (e.g. System File Provider)
*
* @since 2025.11.01
*/
public function label(): string;
/**
* Retrieve collection of services for a specific user
*
* @since 2025.11.01
*
* @param string $tenantId tenant identifier
* @param string $userId user identifier
* @param array $filter filter criteria
*
* @return array<string,IServiceBase> collection of service objects
*/
public function serviceList(string $tenantId, string $userId, array $filter): array;
/**
* Determine if any services are configured for a specific user
*
* @since 2025.11.01
*
* @param string $tenantId tenant identifier
* @param string $userId user identifier
* @param int|string ...$identifiers variadic collection of service identifiers
*
* @return array<string,bool> collection of service identifiers with boolean values indicating if the service is available
*/
public function serviceExtant(string $tenantId, string $userId, int|string ...$identifiers): array;
/**
* Retrieve a service with a specific identifier
*
* @since 2025.11.01
*
* @param string $tenantId tenant identifier
* @param string $userId user identifier
* @param string|int $identifier service identifier
*
* @return IServiceBase|null returns service object or null if non found
*/
public function serviceFetch(string $tenantId, string $userId, string|int $identifier): ?IServiceBase;
interface IProviderBase extends ResourceProviderInterface {
}

132
shared/lib/Mail/Provider/IProviderBase.php
View File

@@ -1,132 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Provider;
use JsonSerializable;
use KTXF\Mail\Selector\ServiceSelector;
use KTXF\Mail\Service\IServiceBase;
/**
* Mail Provider Base Interface
*
* Core interface for mail providers with context-aware service discovery.
*
* @since 2025.05.01
*/
interface IProviderBase extends JsonSerializable {
public const CAPABILITY_SERVICE_LIST = 'ServiceList';
public const CAPABILITY_SERVICE_FETCH = 'ServiceFetch';
public const CAPABILITY_SERVICE_EXTANT = 'ServiceExtant';
public const CAPABILITY_SERVICE_FIND_BY_ADDRESS = 'ServiceFindByAddress';
public const JSON_TYPE = 'mail.provider';
public const JSON_PROPERTY_TYPE = '@type';
public const JSON_PROPERTY_ID = 'id';
public const JSON_PROPERTY_LABEL = 'label';
public const JSON_PROPERTY_CAPABILITIES = 'capabilities';
/**
* Confirms if a specific capability is supported
*
* @since 2025.05.01
*
* @param string $value Required capability e.g. 'ServiceList'
*
* @return bool
*/
public function capable(string $value): bool;
/**
* Lists all supported capabilities
*
* @since 2025.05.01
*
* @return array<string,bool>
*/
public function capabilities(): array;
/**
* Gets the unique identifier for this provider
*
* @since 2025.05.01
*
* @return string Provider ID (e.g., 'smtp', 'imap', 'jmap')
*/
public function id(): string;
/**
* Gets the localized human-friendly name of this provider
*
* @since 2025.05.01
*
* @return string Provider label (e.g., 'SMTP Mail Provider')
*/
public function label(): string;
/**
* Lists services for a tenant, optionally filtered by user context
*
* When userId is null, returns only System-scoped services.
* When userId is provided, returns System-scoped services plus
* User-scoped services owned by that user.
*
* @since 2025.05.01
*
* @param string $tenantId Tenant identifier
* @param string|null $userId User identifier for context (null = system only)
* @param ServiceSelector|null $selector Optional filter criteria
*
* @return array<string|int, IServiceBase>
*/
public function serviceList(string $tenantId, ?string $userId = null, ?ServiceSelector $selector = null): array;
/**
* Checks if specific services exist
*
* @since 2025.05.01
*
* @param string $tenantId Tenant identifier
* @param string|null $userId User identifier for context
* @param string|int ...$identifiers Service identifiers to check
*
* @return array<string|int, bool> Identifier => exists
*/
public function serviceExtant(string $tenantId, ?string $userId, string|int ...$identifiers): array;
/**
* Fetches a specific service by identifier
*
* @since 2025.05.01
*
* @param string $tenantId Tenant identifier
* @param string|null $userId User identifier for context
* @param string|int $identifier Service identifier
*
* @return IServiceBase|null
*/
public function serviceFetch(string $tenantId, ?string $userId, string|int $identifier): ?IServiceBase;
/**
* Finds a service that handles a specific email address
*
* Searches within the appropriate scope based on userId context.
*
* @since 2025.05.01
*
* @param string $tenantId Tenant identifier
* @param string|null $userId User identifier for context
* @param string $address Email address to find service for
*
* @return IServiceBase|null Service handling the address, or null
*/
public function serviceFindByAddress(string $tenantId, ?string $userId, string $address): ?IServiceBase;
}

77
shared/lib/Mail/Provider/IProviderServiceMutate.php
View File

@@ -1,77 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Provider;
use KTXF\Json\JsonDeserializable;
use KTXF\Mail\Service\IServiceBase;
/**
* Mail Provider Service Mutate Interface
*
* Optional interface for providers that support service CRUD operations.
*
* @since 2025.05.01
*/
interface IProviderServiceMutate extends JsonDeserializable {
public const CAPABILITY_SERVICE_FRESH = 'ServiceFresh';
public const CAPABILITY_SERVICE_CREATE = 'ServiceCreate';
public const CAPABILITY_SERVICE_MODIFY = 'ServiceModify';
public const CAPABILITY_SERVICE_DESTROY = 'ServiceDestroy';
/**
* Creates a new blank service instance for configuration
*
* @since 2025.05.01
*
* @return IServiceBase Fresh service object
*/
public function serviceFresh(): IServiceBase;
/**
* Creates a new service configuration
*
* @since 2025.05.01
*
* @param string $tenantId Tenant identifier
* @param string|null $userId Owner user ID (null for system services)
* @param IServiceBase $service Service configuration to create
*
* @return string|int Created service identifier
*/
public function serviceCreate(string $tenantId, ?string $userId, IServiceBase $service): string|int;
/**
* Modifies an existing service configuration
*
* @since 2025.05.01
*
* @param string $tenantId Tenant identifier
* @param string|null $userId User identifier for authorization context
* @param IServiceBase $service Service configuration to update
*
* @return string|int Updated service identifier
*/
public function serviceModify(string $tenantId, ?string $userId, IServiceBase $service): string|int;
/**
* Destroys a service configuration
*
* @since 2025.05.01
*
* @param string $tenantId Tenant identifier
* @param string|null $userId User identifier for authorization context
* @param IServiceBase $service Service to destroy
*
* @return bool True if destroyed, false if not found
*/
public function serviceDestroy(string $tenantId, ?string $userId, IServiceBase $service): bool;
}

41
shared/lib/Mail/Provider/ProviderBaseInterface.php Normal file
View File

@@ -0,0 +1,41 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Provider;
use KTXF\Mail\Service\ServiceBaseInterface;
use KTXF\Resource\Provider\ResourceProviderBaseInterface;
/**
* Mail Provider Base Interface
*
* Core interface for mail providers with context-aware service discovery.
*
* @since 2025.05.01
*/
interface ProviderBaseInterface extends ResourceProviderBaseInterface{
public const JSON_TYPE = 'mail.provider';
/**
* Finds a service that handles a specific email address
*
* Searches within the appropriate scope based on userId context.
*
* @since 2025.05.01
*
* @param string $tenantId Tenant identifier
* @param string|null $userId User identifier for context
* @param string $address Email address to find service for
*
* @return IServiceBase|null Service handling the address, or null
*/
public function serviceFindByAddress(string $tenantId, ?string $userId, string $address): ?ServiceBaseInterface;
}

67
shared/lib/Mail/Provider/ProviderServiceDiscoverInterface.php Normal file
View File

@@ -0,0 +1,67 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Provider;
/**
* Mail Provider Autodiscovery Interface
*
* Optional interface for mail providers that support automatic service discovery
* from email addresses or domains. Providers implementing this interface can
* discover mail service configurations using various methods specific to their
* protocol or provider type.
*
* Examples:
* - IMAP/SMTP providers: Mozilla Autoconfig, DNS SRV, well-known URIs
* - JMAP providers: Well-known JMAP endpoint discovery
* - Provider-specific: Gmail, Outlook, etc. with known configurations
*
* @since 2025.05.01
*/
interface ProviderServiceDiscoverInterface extends ProviderBaseInterface {
public const CAPABILITY_SERVICE_DISCOVER = 'ServiceDiscover';
/**
* Discover service configuration
*
* Attempts to discover service configuration using provider-specific methods.
* Each provider may use different discovery mechanisms:
* - IMAP/SMTP: config database, DNS SRV, well-known URIs, common patterns
* - JMAP: Well-known JMAP session discovery
* - Provider-specific: Known configurations for popular providers
*
* @since 2025.05.01
*
* @param string $identity Identity to discover configuration for
* @param array $options Provider-specific options (e.g., preferred protocols, timeout)
*
* @return array Discovery results in the format:
* [
* 'domain' => 'example.com',
* 'provider' => 'gmail|outlook|generic|etc', // Optional detected provider
* 'results' => [
* [
* 'protocol' => 'imap|smtp|jmap|etc',
* 'host' => 'imap.example.com',
* 'port' => 993,
* 'security' => 'ssl|tls|starttls|none',
* 'authentication' => ['plain', 'login', 'oauth2'], // Supported auth methods
* 'confidence' => 'high|medium|low',
* 'source' => 'mozilla|srv|wellknown|common|verified', // Discovery method used
* ],
* // ... more protocol results
* ]
* ]
*
* Returns empty results array if no configuration could be discovered.
*/
public function serviceDiscover(string $identity, array $options = []): array;
}

33
shared/lib/Mail/Provider/ProviderServiceMutateInterface.php Normal file
View File

@@ -0,0 +1,33 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Provider;
use KTXF\Resource\Provider\ResourceProviderServiceMutateInterface;
/**
* Mail Provider Service Mutate Interface
*
* Optional interface for providers that support service CRUD operations.
*
* Implementations return ServiceMutableInterface instances (which extend ResourceServiceMutateInterface).
*
* @since 2025.05.01
*
* @method ServiceMutableInterface serviceFresh() Construct a new blank mail service instance
* @method string serviceCreate(string $tenantId, ?string $userId, ServiceMutableInterface $service) Create a mail service configuration
* @method string serviceModify(string $tenantId, ?string $userId, ServiceMutableInterface $service) Modify a mail service configuration
* @method bool serviceDestroy(string $tenantId, ?string $userId, ServiceMutableInterface $service) Delete a mail service configuration
*/
interface ProviderServiceMutateInterface extends ProviderBaseInterface, ResourceProviderServiceMutateInterface {
// Methods inherited from ResourceProviderServiceMutateInterface
// Implementations should return/accept ServiceMutableInterface instances
}

79
shared/lib/Mail/Provider/ProviderServiceTestInterface.php Normal file
View File

@@ -0,0 +1,79 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Provider;
use KTXF\Mail\Service\ServiceBaseInterface;
/**
* Mail Provider Service Test Interface
*
* Optional interface for mail providers that support testing service connections.
* Providers implementing this interface can validate connection parameters,
* test authentication, and verify service availability before creating a
* persistent service configuration.
*
* Supports two testing modes:
* 1. Testing an existing service (validate current configuration)
* 2. Testing a fresh configuration (validate before saving)
*
* @since 2025.05.01
*/
interface ProviderServiceTestInterface extends ProviderBaseInterface {
public const CAPABILITY_SERVICE_TEST = 'ServiceTest';
/**
* Test a service connection
*
* Tests connectivity, authentication, and capabilities of a service.
*
* For new services: use serviceFresh() to create a service, configure it with
* setters, then pass it to this method for testing before persisting.
*
* For existing services: fetch the service and pass it directly.
*
* @since 2025.05.01
*
* @param ServiceBaseInterface $service Service to test (can be fresh/unsaved or existing)
* @param array $options Provider-specific test options:
* - 'timeout' => int (seconds, default: 10)
* - 'verify_ssl' => bool (default: true)
* - 'test_send' => bool (attempt test send if capable, default: false)
* - 'test_receive' => bool (attempt mailbox access if capable, default: true)
*
* @return array Test results in the format:
* [
* 'success' => bool,
* 'message' => 'Connection successful' | 'Error message',
* 'details' => [
* 'connected' => bool, // Socket/HTTP connection succeeded
* 'authenticated' => bool, // Authentication succeeded
* 'capabilities' => ['IMAP4rev1', ...], // Server capabilities (if applicable)
* 'serverInfo' => 'Server version/banner',
* 'latency' => 123, // Connection time in milliseconds
* 'protocols' => [
* 'inbound' => [
* 'connected' => bool,
* 'authenticated' => bool,
* 'error' => 'error message if failed'
* ],
* 'outbound' => [ // For split-socket (IMAP+SMTP)
* 'connected' => bool,
* 'authenticated' => bool,
* 'error' => 'error message if failed'
* ]
* ],
* 'errors' => ['Error 1', 'Error 2'], // List of errors encountered
* ]
* ]
*/
public function serviceTest(ServiceBaseInterface $service, array $options = []): array;
}

36
shared/lib/Mail/Service/IServiceIdentity.php
View File

@@ -1,36 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Service;
use JsonSerializable;
/**
* Mail Service Identity Interface
*
* Base interface for authentication credentials used by mail services.
*
* @since 2025.05.01
*/
interface IServiceIdentity extends JsonSerializable {
public const TYPE_BASIC = 'basic';
public const TYPE_OAUTH = 'oauth';
public const TYPE_APIKEY = 'apikey';
/**
* Gets the identity/authentication type
*
* @since 2025.05.01
*
* @return string One of: 'basic', 'oauth', 'apikey'
*/
public function getType(): string;
}

39
shared/lib/Mail/Service/IServiceIdentityApiKey.php
View File

@@ -1,39 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Service;
/**
* Mail Service API Key Identity Interface
*
* API key authentication for transactional mail services (SendGrid, Mailgun, etc.)
*
* @since 2025.05.01
*/
interface IServiceIdentityApiKey extends IServiceIdentity {
/**
* Gets the API key
*
* @since 2025.05.01
*
* @return string
*/
public function getApiKey(): string;
/**
* Gets the optional API key identifier/name
*
* @since 2025.05.01
*
* @return string|null
*/
public function getApiKeyId(): ?string;
}

39
shared/lib/Mail/Service/IServiceIdentityBasic.php
View File

@@ -1,39 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Service;
/**
* Mail Service Basic Authentication Identity Interface
*
* Username/password authentication for traditional mail services.
*
* @since 2025.05.01
*/
interface IServiceIdentityBasic extends IServiceIdentity {
/**
* Gets the username/login identifier
*
* @since 2025.05.01
*
* @return string
*/
public function getUsername(): string;
/**
* Gets the password/secret
*
* @since 2025.05.01
*
* @return string
*/
public function getPassword(): string;
}

68
shared/lib/Mail/Service/IServiceIdentityOAuth.php
View File

@@ -1,68 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Service;
use DateTimeImmutable;
/**
* Mail Service OAuth Identity Interface
*
* OAuth2 token-based authentication for modern mail APIs.
*
* @since 2025.05.01
*/
interface IServiceIdentityOAuth extends IServiceIdentity {
/**
* Gets the OAuth access token
*
* @since 2025.05.01
*
* @return string
*/
public function getAccessToken(): string;
/**
* Gets the OAuth refresh token
*
* @since 2025.05.01
*
* @return string|null
*/
public function getRefreshToken(): ?string;
/**
* Gets the token expiration time
*
* @since 2025.05.01
*
* @return DateTimeImmutable|null
*/
public function getExpiresAt(): ?DateTimeImmutable;
/**
* Gets the granted OAuth scopes
*
* @since 2025.05.01
*
* @return array<string>
*/
public function getScopes(): array;
/**
* Checks if the access token has expired
*
* @since 2025.05.01
*
* @return bool
*/
public function isExpired(): bool;
}

105
shared/lib/Mail/Service/IServiceLocation.php
View File

@@ -1,105 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Service;
use JsonSerializable;
/**
* Mail Service Location Interface
*
* Unified interface supporting both URI-based (API services) and socket-based
* (traditional IMAP/SMTP) connection configurations.
*
* @since 2025.05.01
*/
interface IServiceLocation extends JsonSerializable {
public const TYPE_URI = 'uri';
public const TYPE_SOCKET_SINGLE = 'socket-single';
public const TYPE_SOCKET_SPLIT = 'socket-split';
public const SECURITY_NONE = 'none';
public const SECURITY_SSL = 'ssl';
public const SECURITY_TLS = 'tls';
public const SECURITY_STARTTLS = 'starttls';
/**
* Gets the location type
*
* @since 2025.05.01
*
* @return string One of: 'uri', 'socket-single', 'socket-split'
*/
public function getType(): string;
/**
* Gets the URI for API-based services (JMAP, EWS, Graph API, HTTP relay)
*
* @since 2025.05.01
*
* @return string|null URI or null if not URI-based
*/
public function getUri(): ?string;
/**
* Gets the inbound/primary host for socket-based services
*
* @since 2025.05.01
*
* @return string|null Hostname or null if URI-based
*/
public function getInboundHost(): ?string;
/**
* Gets the inbound/primary port for socket-based services
*
* @since 2025.05.01
*
* @return int|null Port number or null if URI-based
*/
public function getInboundPort(): ?int;
/**
* Gets the inbound/primary security mode
*
* @since 2025.05.01
*
* @return string|null One of: 'none', 'ssl', 'tls', 'starttls'
*/
public function getInboundSecurity(): ?string;
/**
* Gets the outbound host for split-socket services (e.g., SMTP separate from IMAP)
*
* @since 2025.05.01
*
* @return string|null Hostname or null if not split-socket
*/
public function getOutboundHost(): ?string;
/**
* Gets the outbound port for split-socket services
*
* @since 2025.05.01
*
* @return int|null Port number or null if not split-socket
*/
public function getOutboundPort(): ?int;
/**
* Gets the outbound security mode for split-socket services
*
* @since 2025.05.01
*
* @return string|null One of: 'none', 'ssl', 'tls', 'starttls'
*/
public function getOutboundSecurity(): ?string;
}

102
shared/lib/Mail/Service/IServiceBase.php → shared/lib/Mail/Service/ServiceBaseInterface.php
View File

@@ -9,11 +9,11 @@ declare(strict_types=1);
namespace KTXF\Mail\Service;
use JsonSerializable;
use KTXF\Mail\Collection\ICollectionBase;
use KTXF\Mail\Entity\IAddress;
use KTXF\Mail\Entity\IMessageBase;
use KTXF\Resource\Filter\IFilter;
use KTXF\Resource\Provider\ResourceServiceBaseInterface;
use KTXF\Resource\Range\IRange;
use KTXF\Resource\Range\RangeType;
use KTXF\Resource\Sort\ISort;
@@ -26,7 +26,7 @@ use KTXF\Resource\Sort\ISort;
*
* @since 2025.05.01
*/
interface IServiceBase extends JsonSerializable {
interface ServiceBaseInterface extends ResourceServiceBaseInterface {
// Collection capabilities
public const CAPABILITY_COLLECTION_LIST = 'CollectionList';
@@ -43,7 +43,6 @@ interface IServiceBase extends JsonSerializable {
public const CAPABILITY_MESSAGE_DELTA = 'MessageDelta';
public const CAPABILITY_MESSAGE_EXTANT = 'MessageExtant';
public const CAPABILITY_MESSAGE_FETCH = 'MessageFetch';
public const CAPABILITY_MESSAGE_SEARCH = 'MessageSearch';
// Filter capabilities
public const CAPABILITY_FILTER_ID = 'FilterId';
@@ -62,91 +61,9 @@ interface IServiceBase extends JsonSerializable {
public const CAPABILITY_SORT_SIZE = 'SortSize';
public const JSON_TYPE = 'mail.service';
public const JSON_PROPERTY_TYPE = '@type';
public const JSON_PROPERTY_PROVIDER = 'provider';
public const JSON_PROPERTY_ID = 'id';
public const JSON_PROPERTY_LABEL = 'label';
public const JSON_PROPERTY_SCOPE = 'scope';
public const JSON_PROPERTY_OWNER = 'owner';
public const JSON_PROPERTY_ENABLED = 'enabled';
public const JSON_PROPERTY_CAPABILITIES = 'capabilities';
public const JSON_PROPERTY_PRIMARY_ADDRESS = 'primaryAddress';
public const JSON_PROPERTY_SECONDARY_ADDRESSES = 'secondaryAddresses';
/**
* Confirms if a specific capability is supported
*
* @since 2025.05.01
*
* @param string $value Required capability e.g. 'Send'
*
* @return bool
*/
public function capable(string $value): bool;
/**
* Lists all supported capabilities
*
* @since 2025.05.01
*
* @return array<string,bool>
*/
public function capabilities(): array;
/**
* Gets the unique identifier of the provider this service belongs to
*
* @since 2025.05.01
*
* @return string
*/
public function in(): string;
/**
* Gets the unique identifier for this service
*
* @since 2025.05.01
*
* @return string|int
*/
public function id(): string|int;
/**
* Gets the localized human-friendly name of this service
*
* @since 2025.05.01
*
* @return string
*/
public function getLabel(): string;
/**
* Gets the scope of this service (System or User)
*
* @since 2025.05.01
*
* @return ServiceScope
*/
public function getScope(): ServiceScope;
/**
* Gets the owner user ID for User-scoped services
*
* @since 2025.05.01
*
* @return string|null User ID or null for System scope
*/
public function getOwner(): ?string;
/**
* Gets whether this service is enabled
*
* @since 2025.05.01
*
* @return bool
*/
public function getEnabled(): bool;
/**
* Gets the primary mailing address for this service
*
@@ -309,19 +226,4 @@ interface IServiceBase extends JsonSerializable {
*/
public function messageFetch(string|int $collection, string|int ...$identifiers): array;
/**
* Searches messages across collections
*
* @since 2025.05.01
*
* @param string $query Search query (syntax depends on protocol)
* @param array|null $collections Collection IDs to search (null = all)
* @param IFilter|null $filter Additional filter criteria
* @param ISort|null $sort Optional sort order
* @param IRange|null $range Optional pagination
*
* @return array<string|int,IMessageBase> Matching messages
*/
public function messageSearch(string $query, ?array $collections = null, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null): array;
}

2
shared/lib/Mail/Service/IServiceCollectionMutable.php → shared/lib/Mail/Service/ServiceCollectionMutableInterface.php
View File

@@ -20,7 +20,7 @@ use KTXF\Mail\Collection\ICollectionMutable;
*
* @since 2025.05.01
*/
interface IServiceCollectionMutable extends IServiceBase {
interface ServiceCollectionMutableInterface extends ServiceBaseInterface {
public const CAPABILITY_COLLECTION_CREATE = 'CollectionCreate';
public const CAPABILITY_COLLECTION_MODIFY = 'CollectionModify';

78
shared/lib/Mail/Service/ServiceIdentityApiKey.php
View File

@@ -1,78 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Service;
/**
* Mail Service API Key Identity Implementation
*
* API key authentication for transactional mail services.
*
* @since 2025.05.01
*/
class ServiceIdentityApiKey implements IServiceIdentityApiKey {
/**
* @param string $apiKey API key
* @param string|null $apiKeyId Optional API key identifier
*/
public function __construct(
private string $apiKey,
private ?string $apiKeyId = null,
) {}
/**
* Creates from array data
*
* @since 2025.05.01
*
* @param array $data
*
* @return self
*/
public static function fromArray(array $data): self {
return new self(
$data['apiKey'] ?? '',
$data['apiKeyId'] ?? null,
);
}
/**
* @inheritDoc
*/
public function getType(): string {
return self::TYPE_APIKEY;
}
/**
* @inheritDoc
*/
public function getApiKey(): string {
return $this->apiKey;
}
/**
* @inheritDoc
*/
public function getApiKeyId(): ?string {
return $this->apiKeyId;
}
/**
* @inheritDoc
*/
public function jsonSerialize(): array {
return array_filter([
'type' => self::TYPE_APIKEY,
'apiKeyId' => $this->apiKeyId,
// API key intentionally omitted from serialization for security
], fn($v) => $v !== null);
}
}

78
shared/lib/Mail/Service/ServiceIdentityBasic.php
View File

@@ -1,78 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Service;
/**
* Mail Service Basic Identity Implementation
*
* Username/password authentication credentials.
*
* @since 2025.05.01
*/
class ServiceIdentityBasic implements IServiceIdentityBasic {
/**
* @param string $username Login username
* @param string $password Login password
*/
public function __construct(
private string $username,
private string $password,
) {}
/**
* Creates from array data
*
* @since 2025.05.01
*
* @param array $data
*
* @return self
*/
public static function fromArray(array $data): self {
return new self(
$data['username'] ?? '',
$data['password'] ?? '',
);
}
/**
* @inheritDoc
*/
public function getType(): string {
return self::TYPE_BASIC;
}
/**
* @inheritDoc
*/
public function getUsername(): string {
return $this->username;
}
/**
* @inheritDoc
*/
public function getPassword(): string {
return $this->password;
}
/**
* @inheritDoc
*/
public function jsonSerialize(): array {
return [
'type' => self::TYPE_BASIC,
'username' => $this->username,
// Password intentionally omitted from serialization for security
];
}
}

211
shared/lib/Mail/Service/ServiceLocation.php
View File

@@ -1,211 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Service;
/**
* Mail Service Location Implementation
*
* Unified implementation supporting URI-based and socket-based connections.
*
* @since 2025.05.01
*/
class ServiceLocation implements IServiceLocation {
/**
* @param string $type Location type (uri, socket-single, socket-split)
* @param string|null $uri URI for API-based services
* @param string|null $inboundHost Inbound/primary host
* @param int|null $inboundPort Inbound/primary port
* @param string|null $inboundSecurity Inbound security (none, ssl, tls, starttls)
* @param string|null $outboundHost Outbound host (for split-socket)
* @param int|null $outboundPort Outbound port (for split-socket)
* @param string|null $outboundSecurity Outbound security (for split-socket)
*/
public function __construct(
private string $type,
private ?string $uri = null,
private ?string $inboundHost = null,
private ?int $inboundPort = null,
private ?string $inboundSecurity = null,
private ?string $outboundHost = null,
private ?int $outboundPort = null,
private ?string $outboundSecurity = null,
) {}
/**
* Creates a URI-based location (for API services)
*
* @since 2025.05.01
*
* @param string $uri
*
* @return self
*/
public static function uri(string $uri): self {
return new self(self::TYPE_URI, $uri);
}
/**
* Creates a single-socket location (e.g., SMTP only)
*
* @since 2025.05.01
*
* @param string $host
* @param int $port
* @param string $security
*
* @return self
*/
public static function socket(string $host, int $port, string $security = self::SECURITY_TLS): self {
return new self(
self::TYPE_SOCKET_SINGLE,
null,
$host,
$port,
$security
);
}
/**
* Creates a split-socket location (IMAP + SMTP)
*
* @since 2025.05.01
*
* @param string $inboundHost IMAP host
* @param int $inboundPort IMAP port
* @param string $inboundSecurity IMAP security
* @param string $outboundHost SMTP host
* @param int $outboundPort SMTP port
* @param string $outboundSecurity SMTP security
*
* @return self
*/
public static function splitSocket(
string $inboundHost,
int $inboundPort,
string $inboundSecurity,
string $outboundHost,
int $outboundPort,
string $outboundSecurity
): self {
return new self(
self::TYPE_SOCKET_SPLIT,
null,
$inboundHost,
$inboundPort,
$inboundSecurity,
$outboundHost,
$outboundPort,
$outboundSecurity
);
}
/**
* Creates from array data
*
* @since 2025.05.01
*
* @param array $data
*
* @return self
*/
public static function fromArray(array $data): self {
return new self(
$data['type'] ?? self::TYPE_SOCKET_SINGLE,
$data['uri'] ?? null,
$data['inboundHost'] ?? $data['host'] ?? null,
$data['inboundPort'] ?? $data['port'] ?? null,
$data['inboundSecurity'] ?? $data['security'] ?? null,
$data['outboundHost'] ?? null,
$data['outboundPort'] ?? null,
$data['outboundSecurity'] ?? null,
);
}
/**
* @inheritDoc
*/
public function getType(): string {
return $this->type;
}
/**
* @inheritDoc
*/
public function getUri(): ?string {
return $this->uri;
}
/**
* @inheritDoc
*/
public function getInboundHost(): ?string {
return $this->inboundHost;
}
/**
* @inheritDoc
*/
public function getInboundPort(): ?int {
return $this->inboundPort;
}
/**
* @inheritDoc
*/
public function getInboundSecurity(): ?string {
return $this->inboundSecurity;
}
/**
* @inheritDoc
*/
public function getOutboundHost(): ?string {
return $this->outboundHost ?? $this->inboundHost;
}
/**
* @inheritDoc
*/
public function getOutboundPort(): ?int {
return $this->outboundPort ?? $this->inboundPort;
}
/**
* @inheritDoc
*/
public function getOutboundSecurity(): ?string {
return $this->outboundSecurity ?? $this->inboundSecurity;
}
/**
* @inheritDoc
*/
public function jsonSerialize(): array {
$data = ['type' => $this->type];
if ($this->type === self::TYPE_URI) {
$data['uri'] = $this->uri;
} else {
$data['inboundHost'] = $this->inboundHost;
$data['inboundPort'] = $this->inboundPort;
$data['inboundSecurity'] = $this->inboundSecurity;
if ($this->type === self::TYPE_SOCKET_SPLIT) {
$data['outboundHost'] = $this->outboundHost;
$data['outboundPort'] = $this->outboundPort;
$data['outboundSecurity'] = $this->outboundSecurity;
}
}
return array_filter($data, fn($v) => $v !== null);
}
}

2
shared/lib/Mail/Service/IServiceMessageMutable.php → shared/lib/Mail/Service/ServiceMessageMutableInterface.php
View File

@@ -20,7 +20,7 @@ use KTXF\Mail\Entity\IMessageMutable;
*
* @since 2025.05.01
*/
interface IServiceMessageMutable extends IServiceBase {
interface ServiceMessageMutableInterface extends ServiceBaseInterface {
public const CAPABILITY_MESSAGE_CREATE = 'MessageCreate';
public const CAPABILITY_MESSAGE_MODIFY = 'MessageModify';

2
shared/lib/Mail/Service/IServiceSend.php → shared/lib/Mail/Service/ServiceMessageSendInterface.php
View File

@@ -20,7 +20,7 @@ use KTXF\Mail\Exception\SendException;
*
* @since 2025.05.01
*/
interface IServiceSend extends IServiceBase {
interface ServiceMessageSendInterface extends ServiceBaseInterface {
public const CAPABILITY_SEND = 'Send';

46
shared/lib/Mail/Service/ServiceMutableInterface.php Normal file
View File

@@ -0,0 +1,46 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Service;
use KTXF\Mail\Entity\IAddress;
/**
* Mail Service Mutable Interface
*
* Extends base service interface with setter methods for mutable properties.
* Used for service configuration and updates.
*
* @since 2025.05.01
*/
interface ServiceMutableInterface extends ServiceBaseInterface {
/**
* Sets the primary mailing address for this service
*
* @since 2025.05.01
*
* @param IAddress $value Primary email address
*
* @return self
*/
public function setPrimaryAddress(IAddress $value): self;
/**
* Sets the secondary mailing addresses (aliases) for this service
*
* @since 2025.05.01
*
* @param array<int, IAddress> $value Array of secondary addresses
*
* @return self
*/
public function setSecondaryAddresses(array $value): self;
}

37
shared/lib/Mail/Service/ServiceScope.php
View File

@@ -1,37 +0,0 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Mail\Service;
use JsonSerializable;
/**
* Defines the scope/context of a mail service
*
* @since 2025.05.01
*/
enum ServiceScope: string implements JsonSerializable {
/**
* System-level service for tenant-wide communications
* (e.g., notifications@, reports@, noreply@)
*/
case System = 'system';
/**
* User-level service for personal mail accounts
* (e.g., user's own IMAP/SMTP accounts)
*/
case User = 'user';
public function jsonSerialize(): string {
return $this->value;
}
}

79
shared/lib/Resource/Provider/ResourceProviderBaseInterface.php Normal file
View File

@@ -0,0 +1,79 @@
<?php
declare(strict_types=1);
namespace KTXF\Resource\Provider;
use KTXF\Json\JsonSerializable;
/**
* Resource Provider Interface
*/
interface ResourceProviderBaseInterface extends ProviderInterface, JsonSerializable
{
public const CAPABILITY_SERVICE_LIST = 'ServiceList';
public const CAPABILITY_SERVICE_FETCH = 'ServiceFetch';
public const CAPABILITY_SERVICE_EXTANT = 'ServiceExtant';
public const JSON_TYPE = 'resource.provider';
public const JSON_PROPERTY_TYPE = '@type';
public const JSON_PROPERTY_ID = 'id';
public const JSON_PROPERTY_LABEL = 'label';
public const JSON_PROPERTY_CAPABILITIES = 'capabilities';
/**
* Confirms if specific capability is supported (e.g. 'ServiceList')
*
* @since 2025.11.01
*/
public function capable(string $value): bool;
/**
* Lists all supported capabilities
*
* @since 2025.11.01
*
* @return array<string,bool>
*/
public function capabilities(): array;
/**
* Retrieve collection of services for a specific user
*
* @since 2025.11.01
*
* @param string $tenantId tenant identifier
* @param string $userId user identifier
* @param array $filter filter criteria
*
* @return array<string,ResourceServiceBaseInterface> collection of service objects
*/
public function serviceList(string $tenantId, string $userId, array $filter): array;
/**
* Determine if any services are configured for a specific user
*
* @since 2025.11.01
*
* @param string $tenantId tenant identifier
* @param string $userId user identifier
* @param int|string ...$identifiers variadic collection of service identifiers
*
* @return array<string,bool> collection of service identifiers with boolean values indicating if the service is available
*/
public function serviceExtant(string $tenantId, string $userId, int|string ...$identifiers): array;
/**
* Retrieve a service with a specific identifier
*
* @since 2025.11.01
*
* @param string $tenantId tenant identifier
* @param string $userId user identifier
* @param string|int $identifier service identifier
*
* @return ResourceServiceBaseInterface|null returns service object or null if non found
*/
public function serviceFetch(string $tenantId, string $userId, string|int $identifier): ?ResourceServiceBaseInterface;
}

49
shared/lib/Resource/Provider/ResourceProviderServiceMutateInterface.php Normal file
View File

@@ -0,0 +1,49 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Resource\Provider;
use KTXF\Json\JsonDeserializable;
interface ResourceProviderServiceMutateInterface extends ResourceProviderBaseInterface, JsonDeserializable {
public const CAPABILITY_SERVICE_FRESH = 'ServiceFresh';
public const CAPABILITY_SERVICE_CREATE = 'ServiceCreate';
public const CAPABILITY_SERVICE_UPDATE = 'ServiceUpdate';
public const CAPABILITY_SERVICE_DESTROY = 'ServiceDestroy';
/**
* construct and new blank service instance
*
* @since 2025.05.01
*/
public function serviceFresh(string $tenantId, ?string $userId): ResourceServiceMutateInterface;
/**
* create a service configuration for a specific user
*
* @since 2025.05.01
*/
public function serviceCreate(string $tenantId, ?string $userId, ResourceServiceMutateInterface $service): string;
/**
* modify a service configuration for a specific user
*
* @since 2025.05.01
*/
public function serviceModify(string $tenantId, ?string $userId, ResourceServiceMutateInterface $service): string;
/**
* delete a service configuration for a specific user
*
* @since 2025.05.01
*/
public function serviceDestroy(string $tenantId, ?string $userId, ResourceServiceMutateInterface $service): bool;
}

86
shared/lib/Resource/Provider/ResourceServiceBaseInterface.php Normal file
View File

@@ -0,0 +1,86 @@
<?php
declare(strict_types=1);
namespace KTXF\Resource\Provider;
use KTXF\Json\JsonSerializable;
interface ResourceServiceBaseInterface extends JsonSerializable {
// JSON Constants
public const JSON_TYPE = 'resource.service';
public const JSON_PROPERTY_TYPE = '@type';
public const JSON_PROPERTY_PROVIDER = 'provider';
public const JSON_PROPERTY_ID = 'id';
public const JSON_PROPERTY_LABEL = 'label';
public const JSON_PROPERTY_ENABLED = 'enabled';
public const JSON_PROPERTY_CAPABILITIES = 'capabilities';
/**
* Confirms if specific capability is supported
*
* @since 2025.11.01
*
* @param string $value required ability e.g. 'EntityList'
*
* @return bool
*/
public function capable(string $value): bool;
/**
* Lists all supported capabilities
*
* @since 2025.11.01
*
* @return array<string,bool>
*/
public function capabilities(): array;
/**
* Unique identifier of the provider this service belongs to
*
* @since 2025.11.01
*/
public function in(): string;
/**
* Unique arbitrary text string identifying this service (e.g. 1 or service1 or anything else)
*
* @since 2025.11.01
*/
public function id(): string|int;
/**
* Gets the localized human friendly name of this service (e.g. ACME Company File Service)
*
* @since 2025.11.01
*/
public function getLabel(): string;
/**
* Gets the active status of this service
*
* @since 2025.11.01
*/
public function getEnabled(): bool;
/**
* Gets the location information of this service
*
* @since 2025.05.01
*
* @return ResourceServiceLocationInterface
*/
public function getLocation(): ResourceServiceLocationInterface;
/**
* Gets the identity information of this service
*
* @since 2025.05.01
*
* @return ResourceServiceIdentityInterface
*/
public function getIdentity(): ResourceServiceIdentityInterface;
}

44
shared/lib/Resource/Provider/ResourceServiceConfigureInterface.php Normal file
View File

@@ -0,0 +1,44 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Resource\Provider;
/**
* Resource Service Configurable Interface
*
* Extends base service interface with setter methods for mutable properties.
* Used for service configuration and updates.
*
* @since 2025.05.01
*/
interface ResourceServiceConfigureInterface extends ResourceServiceMutateInterface {
/**
* Sets the location/configuration of this service
*
* @since 2025.05.01
*
* @param ResourceServiceLocationInterface $value Service location/configuration
*
* @return self
*/
public function setLocation(ResourceServiceLocationInterface $value): self;
/**
* Sets the identity used for this service
*
* @since 2025.05.01
*
* @param ResourceServiceIdentityInterface $value Service identity
*
* @return self
*/
public function setIdentity(ResourceServiceIdentityInterface $value): self;
}

61
shared/lib/Resource/Provider/ResourceServiceIdentityBasic.php Normal file
View File

@@ -0,0 +1,61 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Resource\Provider;
/**
* Resource Service Identity Basic
*
* Basic authentication (username/password) credentials for resource services.
*
* @since 2025.05.01
*/
interface ResourceServiceIdentityBasic extends ResourceServiceIdentityInterface {
/**
* Gets the identity/username
*
* @since 2025.05.01
*
* @return string
*/
public function getIdentity(): string;
/**
* Sets the identity/username
*
* @since 2025.05.01
*
* @param string $value
*
* @return void
*/
public function setIdentity(string $value): void;
/**
* Gets the secret/password
*
* @since 2025.05.01
*
* @return string
*/
public function getSecret(): string;
/**
* Sets the secret/password
*
* @since 2025.05.01
*
* @param string $value
*
* @return void
*/
public function setSecret(string $value): void;
}

41
shared/lib/Resource/Provider/ResourceServiceIdentityBearer.php Normal file
View File

@@ -0,0 +1,41 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Resource\Provider;
/**
* Resource Service Identity Bearer
*
* Bearer token authentication credentials for resource services.
*
* @since 2025.05.01
*/
interface ResourceServiceIdentityBearer extends ResourceServiceIdentityInterface {
/**
* Gets the bearer token
*
* @since 2025.05.01
*
* @return string
*/
public function getToken(): string;
/**
* Sets the bearer token
*
* @since 2025.05.01
*
* @param string $value
*
* @return void
*/
public function setToken(string $value): void;
}

37
shared/lib/Resource/Provider/ResourceServiceIdentityInterface.php Normal file
View File

@@ -0,0 +1,37 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Resource\Provider;
use KTXF\Json\JsonSerializable;
/**
* Resource Service Identity Interface
*
* Base interface for authentication credentials used by resource services.
*
* @since 2025.05.01
*/
interface ResourceServiceIdentityInterface extends JsonSerializable {
public const TYPE_NONE = 'NA';
public const TYPE_BASIC = 'BA';
public const TYPE_BEARER = 'BR';
public const TYPE_OAUTH = 'OA';
/**
* Gets the identity/authentication type
*
* @since 2025.05.01
*
* @return string One of: TYPE_NONE, TYPE_BASIC, TYPE_BEARER, TYPE_OAUTH
*/
public function type(): string;
}

121
shared/lib/Resource/Provider/ResourceServiceIdentityOAuth.php Normal file
View File

@@ -0,0 +1,121 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Resource\Provider;
/**
* Resource Service Identity OAuth
*
* OAuth authentication credentials for resource services, including token management.
*
* @since 2025.05.01
*/
interface ResourceServiceIdentityOAuth extends ResourceServiceIdentityInterface {
/**
* Gets the access token
*
* @since 2025.05.01
*
* @return string
*/
public function getAccessToken(): string;
/**
* Sets the access token
*
* @since 2025.05.01
*
* @param string $value
*
* @return void
*/
public function setAccessToken(string $value): void;
/**
* Gets the access token scope
*
* @since 2025.05.01
*
* @return array
*/
public function getAccessScope(): array;
/**
* Sets the access token scope
*
* @since 2025.05.01
*
* @param array $value
*
* @return void
*/
public function setAccessScope(array $value): void;
/**
* Gets the access token expiry timestamp
*
* @since 2025.05.01
*
* @return int Unix timestamp
*/
public function getAccessExpiry(): int;
/**
* Sets the access token expiry timestamp
*
* @since 2025.05.01
*
* @param int $value Unix timestamp
*
* @return void
*/
public function setAccessExpiry(int $value): void;
/**
* Gets the refresh token
*
* @since 2025.05.01
*
* @return string
*/
public function getRefreshToken(): string;
/**
* Sets the refresh token
*
* @since 2025.05.01
*
* @param string $value
*
* @return void
*/
public function setRefreshToken(string $value): void;
/**
* Gets the token refresh location/endpoint
*
* @since 2025.05.01
*
* @return string
*/
public function getRefreshLocation(): string;
/**
* Sets the token refresh location/endpoint
*
* @since 2025.05.01
*
* @param string $value
*
* @return void
*/
public function setRefreshLocation(string $value): void;
}

51
shared/lib/Resource/Provider/ResourceServiceLocationFile.php Normal file
View File

@@ -0,0 +1,51 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Resource\Provider;
/**
* Resource Service Location File
*
* File-based service location for services using local or network file paths
* (e.g., maildir, mbox, local storage).
*
* @since 2025.05.01
*/
interface ResourceServiceLocationFile extends ResourceServiceLocationInterface {
/**
* Gets the complete file location path
*
* @since 2025.05.01
*
* @return string File path (e.g., "/var/mail/user" or "\\server\share\mail")
*/
public function location(): string;
/**
* Gets the file location path
*
* @since 2025.05.01
*
* @return string File path
*/
public function getLocation(): string;
/**
* Sets the file location path
*
* @since 2025.05.01
*
* @param string $value
*
* @return void
*/
public function setLocation(string $value): void;
}

37
shared/lib/Resource/Provider/ResourceServiceLocationInterface.php Normal file
View File

@@ -0,0 +1,37 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Resource\Provider;
use JsonSerializable;
/**
* Resource Service Location Interface
*
* Unified interface supporting both URI-based (API services) and socket-based
* (traditional IMAP/SMTP) connection configurations.
*
* @since 2025.05.01
*/
interface ResourceServiceLocationInterface extends JsonSerializable {
public const TYPE_URI = 'URI';
public const TYPE_SOCKET_SOLE = 'SOCKET_SOLE';
public const TYPE_SOCKET_SPLIT = 'SOCKET_SPLIT';
public const TYPE_FILE = 'FILE';
/**
* Gets the service location type
*
* @since 2025.05.01
*
* @return string One of: TYPE_URI, TYPE_SOCKET_SOLE, TYPE_SOCKET_SPLIT, TYPE_FILE
*/
public function type(): string;
}

131
shared/lib/Resource/Provider/ResourceServiceLocationSocketSole.php Normal file
View File

@@ -0,0 +1,131 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Resource\Provider;
/**
* Resource Service Location Socket Sole
*
* Single socket-based service location for services using a single host/port combination
* (e.g., JMAP, unified mail servers).
*
* @since 2025.05.01
*/
interface ResourceServiceLocationSocketSole extends ResourceServiceLocationInterface {
/**
* Gets the complete location string
*
* @since 2025.05.01
*
* @return string Location (e.g., "mail.example.com:993")
*/
public function location(): string;
/**
* Gets the host
*
* @since 2025.05.01
*
* @return string Host (e.g., "mail.example.com")
*/
public function getHost(): string;
/**
* Sets the host
*
* @since 2025.05.01
*
* @param string $value
*
* @return void
*/
public function setHost(string $value): void;
/**
* Gets the port
*
* @since 2025.05.01
*
* @return int Port number
*/
public function getPort(): int;
/**
* Sets the port
*
* @since 2025.05.01
*
* @param int $value
*
* @return void
*/
public function setPort(int $value): void;
/**
* Gets the encryption/security mode
*
* @since 2025.12.01
*
* @return string One of: 'none', 'ssl', 'tls', 'starttls'
*/
public function getEncryption(): string;
/**
* Sets the encryption/security mode
*
* @since 2025.12.01
*
* @param string $value One of: 'none', 'ssl', 'tls', 'starttls'
*
* @return void
*/
public function setEncryption(string $value): void;
/**
* Gets whether to verify SSL/TLS peer certificate
*
* @since 2025.12.01
*
* @return bool
*/
public function getVerifyPeer(): bool;
/**
* Sets whether to verify SSL/TLS peer certificate
*
* @since 2025.12.01
*
* @param bool $value
*
* @return void
*/
public function setVerifyPeer(bool $value): void;
/**
* Gets whether to verify SSL/TLS certificate host
*
* @since 2025.12.01
*
* @return bool
*/
public function getVerifyHost(): bool;
/**
* Sets whether to verify SSL/TLS certificate host
*
* @since 2025.12.01
*
* @param bool $value
*
* @return void
*/
public function setVerifyHost(bool $value): void;
}

240
shared/lib/Resource/Provider/ResourceServiceLocationSocketSplit.php Normal file
View File

@@ -0,0 +1,240 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Resource\Provider;
/**
* Resource Service Location Socket Split
*
* Split socket-based service location for services using separate inbound/outbound servers
* (e.g., traditional IMAP/SMTP configurations).
*
* @since 2025.05.01
*/
interface ResourceServiceLocationSocketSplit extends ResourceServiceLocationInterface {
/**
* Gets the complete inbound location string
*
* @since 2025.05.01
*
* @return string Inbound location (e.g., "imap.example.com:993")
*/
public function locationInbound(): string;
/**
* Gets the complete outbound location string
*
* @since 2025.05.01
*
* @return string Outbound location (e.g., "smtp.example.com:465")
*/
public function locationOutbound(): string;
/**
* Gets the inbound host
*
* @since 2025.05.01
*
* @return string Inbound host (e.g., "imap.example.com")
*/
public function getInboundHost(): string;
/**
* Sets the inbound host
*
* @since 2025.05.01
*
* @param string $value
*
* @return void
*/
public function setInboundHost(string $value): void;
/**
* Gets the outbound host
*
* @since 2025.05.01
*
* @return string Outbound host (e.g., "smtp.example.com")
*/
public function getOutboundHost(): string;
/**
* Sets the outbound host
*
* @since 2025.05.01
*
* @param string $value
*
* @return void
*/
public function setOutboundHost(string $value): void;
/**
* Gets the inbound port
*
* @since 2025.05.01
*
* @return int Inbound port number
*/
public function getInboundPort(): int;
/**
* Sets the inbound port
*
* @since 2025.05.01
*
* @param int $value
*
* @return void
*/
public function setInboundPort(int $value): void;
/**
* Gets the outbound port
*
* @since 2025.05.01
*
* @return int Outbound port number
*/
public function getOutboundPort(): int;
/**
* Sets the outbound port
*
* @since 2025.05.01
*
* @param int $value
*
* @return void
*/
public function setOutboundPort(int $value): void;
/**
* Gets the inbound encryption/security mode
*
* @since 2025.12.01
*
* @return string One of: 'none', 'ssl', 'tls', 'starttls'
*/
public function getInboundEncryption(): string;
/**
* Sets the inbound encryption/security mode
*
* @since 2025.12.01
*
* @param string $value One of: 'none', 'ssl', 'tls', 'starttls'
*
* @return void
*/
public function setInboundEncryption(string $value): void;
/**
* Gets the outbound encryption/security mode
*
* @since 2025.12.01
*
* @return string One of: 'none', 'ssl', 'tls', 'starttls'
*/
public function getOutboundEncryption(): string;
/**
* Sets the outbound encryption/security mode
*
* @since 2025.12.01
*
* @param string $value One of: 'none', 'ssl', 'tls', 'starttls'
*
* @return void
*/
public function setOutboundEncryption(string $value): void;
/**
* Gets whether to verify inbound SSL/TLS peer certificate
*
* @since 2025.12.01
*
* @return bool
*/
public function getInboundVerifyPeer(): bool;
/**
* Sets whether to verify inbound SSL/TLS peer certificate
*
* @since 2025.12.01
*
* @param bool $value
*
* @return void
*/
public function setInboundVerifyPeer(bool $value): void;
/**
* Gets whether to verify inbound SSL/TLS certificate host
*
* @since 2025.12.01
*
* @return bool
*/
public function getInboundVerifyHost(): bool;
/**
* Sets whether to verify inbound SSL/TLS certificate host
*
* @since 2025.12.01
*
* @param bool $value
*
* @return void
*/
public function setInboundVerifyHost(bool $value): void;
/**
* Gets whether to verify outbound SSL/TLS peer certificate
*
* @since 2025.12.01
*
* @return bool
*/
public function getOutboundVerifyPeer(): bool;
/**
* Sets whether to verify outbound SSL/TLS peer certificate
*
* @since 2025.12.01
*
* @param bool $value
*
* @return void
*/
public function setOutboundVerifyPeer(bool $value): void;
/**
* Gets whether to verify outbound SSL/TLS certificate host
*
* @since 2025.12.01
*
* @return bool
*/
public function getOutboundVerifyHost(): bool;
/**
* Sets whether to verify outbound SSL/TLS certificate host
*
* @since 2025.12.01
*
* @param bool $value
*
* @return void
*/
public function setOutboundVerifyHost(bool $value): void;
}

150
shared/lib/Resource/Provider/ResourceServiceLocationUri.php Normal file
View File

@@ -0,0 +1,150 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Resource\Provider;
/**
* Resource Service Location Uri
*
* URI-based service location for API and web services (e.g., https://api.example.com:443/v1/endpoint).
*
* @since 2025.05.01
*/
interface ResourceServiceLocationUri extends ResourceServiceLocationInterface {
/**
* Gets the complete location URI
*
* @since 2025.05.01
*
* @return string Complete URI (e.g., "https://api.example.com:443/v1")
*/
public function location(): string;
/**
* Gets the URI scheme
*
* @since 2025.05.01
*
* @return string Scheme (e.g., "https", "http")
*/
public function getScheme(): string;
/**
* Sets the URI scheme
*
* @since 2025.05.01
*
* @param string $value
*
* @return void
*/
public function setScheme(string $value): void;
/**
* Gets the host
*
* @since 2025.05.01
*
* @return string Host (e.g., "api.example.com")
*/
public function getHost(): string;
/**
* Sets the host
*
* @since 2025.05.01
*
* @param string $value
*
* @return void
*/
public function setHost(string $value): void;
/**
* Gets the port
*
* @since 2025.05.01
*
* @return int Port number
*/
public function getPort(): int;
/**
* Sets the port
*
* @since 2025.05.01
*
* @param int $value
*
* @return void
*/
public function setPort(int $value): void;
/**
* Gets the path
*
* @since 2025.05.01
*
* @return string Path (e.g., "/v1/api")
*/
public function getPath(): string;
/**
* Sets the path
*
* @since 2025.05.01
*
* @param string $value
*
* @return void
*/
public function setPath(string $value): void;
/**
* Gets whether to verify SSL/TLS peer certificate
*
* @since 2025.12.01
*
* @return bool
*/
public function getVerifyPeer(): bool;
/**
* Sets whether to verify SSL/TLS peer certificate
*
* @since 2025.12.01
*
* @param bool $value
*
* @return void
*/
public function setVerifyPeer(bool $value): void;
/**
* Gets whether to verify SSL/TLS certificate host
*
* @since 2025.12.01
*
* @return bool
*/
public function getVerifyHost(): bool;
/**
* Sets whether to verify SSL/TLS certificate host
*
* @since 2025.12.01
*
* @param bool $value
*
* @return void
*/
public function setVerifyHost(bool $value): void;
}

46
shared/lib/Resource/Provider/ResourceServiceMutateInterface.php Normal file
View File

@@ -0,0 +1,46 @@
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace KTXF\Resource\Provider;
use KTXF\Json\JsonDeserializable;
/**
* Resource Service Configurable Interface
*
* Extends base service interface with setter methods for mutable properties.
* Used for service configuration and updates.
*
* @since 2025.05.01
*/
interface ResourceServiceMutateInterface extends ResourceServiceBaseInterface, JsonDeserializable {
/**
* Sets the localized human-friendly name of this service (e.g. ACME Company Mail Service)
*
* @since 2025.05.01
*
* @param string $value Service label
*
* @return self
*/
public function setLabel(string $value): self;
/**
* Sets the active status of this service
*
* @since 2025.05.01
*
* @param bool $value True to enable, false to disable
*
* @return self
*/
public function setEnabled(bool $value): self;
}

2
shared/lib/Security/Crypto.php
View File

@@ -137,7 +137,7 @@ class Crypto
private function tenantSecret(): ?string
{
$config = $this->sessionTenant->configuration();
return $config['security']['code'] ?? null;
return $config->security()->code();
}
// =========================================================================