From fea37ffec53aba70f06f448b847fdb9927bae9f0 Mon Sep 17 00:00:00 2001
From: Ralf Lang <ralf.lang@sap.com>
Date: Fri, 25 Sep 2026 10:44:44 +0200
Subject: [PATCH 1/2] feat(oauth): Add necessary interfaces to support
 per-service OAuth

---
 .../ServiceAuthorizationRepositoryFactory.php | 18 +++++
 .../ServiceAuthorizationServiceFactory.php    | 18 +++++
 src/Factory/TokenGrantRepositoryFactory.php   | 18 +++++
 .../Exception/OAuthTokenRefreshException.php  | 30 +++++++-
 src/Service/GrantStrategy.php                 | 22 ++++++
 .../NullServiceAuthorizationRepository.php    | 33 +++++++++
 .../NullServiceAuthorizationService.php       | 53 +++++++++++++
 src/Service/NullTokenGrantRepository.php      | 30 ++++++++
 src/Service/OAuthProviderConfigRepository.php |  2 +-
 src/Service/ServiceAuthorization.php          | 29 ++++++++
 .../ServiceAuthorizationRepository.php        | 26 +++++++
 src/Service/ServiceAuthorizationService.php   | 74 +++++++++++++++++++
 src/Service/ServiceNotAuthorizedException.php | 51 +++++++++++++
 src/Service/ServicePurpose.php                | 50 +++++++++++++
 src/Service/TokenGrant.php                    | 36 +++++++++
 src/Service/TokenGrantRepository.php          | 32 ++++++++
 src/Service/UnsupportedPurposeException.php   | 35 +++++++++
 17 files changed, 555 insertions(+), 2 deletions(-)
 create mode 100644 src/Factory/ServiceAuthorizationRepositoryFactory.php
 create mode 100644 src/Factory/ServiceAuthorizationServiceFactory.php
 create mode 100644 src/Factory/TokenGrantRepositoryFactory.php
 create mode 100644 src/Service/GrantStrategy.php
 create mode 100644 src/Service/NullServiceAuthorizationRepository.php
 create mode 100644 src/Service/NullServiceAuthorizationService.php
 create mode 100644 src/Service/NullTokenGrantRepository.php
 create mode 100644 src/Service/ServiceAuthorization.php
 create mode 100644 src/Service/ServiceAuthorizationRepository.php
 create mode 100644 src/Service/ServiceAuthorizationService.php
 create mode 100644 src/Service/ServiceNotAuthorizedException.php
 create mode 100644 src/Service/ServicePurpose.php
 create mode 100644 src/Service/TokenGrant.php
 create mode 100644 src/Service/TokenGrantRepository.php
 create mode 100644 src/Service/UnsupportedPurposeException.php

diff --git a/src/Factory/ServiceAuthorizationRepositoryFactory.php b/src/Factory/ServiceAuthorizationRepositoryFactory.php
new file mode 100644
index 00000000..71ddee87
--- /dev/null
+++ b/src/Factory/ServiceAuthorizationRepositoryFactory.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Horde\Core\Factory;
+
+use Horde\Core\Service\NullServiceAuthorizationRepository;
+use Horde\Core\Service\ServiceAuthorizationRepository;
+use Horde\Injector\Injector;
+
+/** Factory for ServiceAuthorizationRepository - defaults to NullServiceAuthorizationRepository. */
+class ServiceAuthorizationRepositoryFactory
+{
+    public function create(Injector $injector): ServiceAuthorizationRepository
+    {
+        return new NullServiceAuthorizationRepository();
+    }
+}
diff --git a/src/Factory/ServiceAuthorizationServiceFactory.php b/src/Factory/ServiceAuthorizationServiceFactory.php
new file mode 100644
index 00000000..b437fa8e
--- /dev/null
+++ b/src/Factory/ServiceAuthorizationServiceFactory.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Horde\Core\Factory;
+
+use Horde\Core\Service\NullServiceAuthorizationService;
+use Horde\Core\Service\ServiceAuthorizationService;
+use Horde\Injector\Injector;
+
+/** Factory for ServiceAuthorizationService - defaults to NullServiceAuthorizationService. */
+class ServiceAuthorizationServiceFactory
+{
+    public function create(Injector $injector): ServiceAuthorizationService
+    {
+        return new NullServiceAuthorizationService();
+    }
+}
diff --git a/src/Factory/TokenGrantRepositoryFactory.php b/src/Factory/TokenGrantRepositoryFactory.php
new file mode 100644
index 00000000..60689386
--- /dev/null
+++ b/src/Factory/TokenGrantRepositoryFactory.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Horde\Core\Factory;
+
+use Horde\Core\Service\NullTokenGrantRepository;
+use Horde\Core\Service\TokenGrantRepository;
+use Horde\Injector\Injector;
+
+/** Factory for TokenGrantRepository - defaults to NullTokenGrantRepository. */
+class TokenGrantRepositoryFactory
+{
+    public function create(Injector $injector): TokenGrantRepository
+    {
+        return new NullTokenGrantRepository();
+    }
+}
diff --git a/src/Service/Exception/OAuthTokenRefreshException.php b/src/Service/Exception/OAuthTokenRefreshException.php
index 1b397078..aef7619e 100644
--- a/src/Service/Exception/OAuthTokenRefreshException.php
+++ b/src/Service/Exception/OAuthTokenRefreshException.php
@@ -16,6 +16,7 @@
 
 namespace Horde\Core\Service\Exception;
 
+use Horde\Core\Service\TokenGrant;
 use RuntimeException;
 
 /**
@@ -23,4 +24,31 @@
  *
  * Callers should prompt the user to re-authorize.
  */
-class OAuthTokenRefreshException extends RuntimeException {}
+class OAuthTokenRefreshException extends RuntimeException
+{
+    public function __construct(
+        string $message,
+        private readonly string $userId,
+        private readonly string $providerId,
+        private readonly ?TokenGrant $grant = null,
+        int $code = 0,
+        ?\Throwable $previous = null
+    ) {
+        parent::__construct($message, $code, $previous);
+    }
+
+    public function userId(): string
+    {
+        return $this->userId;
+    }
+
+    public function providerId(): string
+    {
+        return $this->providerId;
+    }
+
+    public function grant(): ?TokenGrant
+    {
+        return $this->grant;
+    }
+}
diff --git a/src/Service/GrantStrategy.php b/src/Service/GrantStrategy.php
new file mode 100644
index 00000000..8c5ae703
--- /dev/null
+++ b/src/Service/GrantStrategy.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+enum GrantStrategy: string
+{
+    /**
+     * Extend an existing shared TokenGrant for this (userId, providerId).
+     * The new required scopes are added to the union.  The updated grant
+     * backs all ServiceAuthorizations for this provider.
+     */
+    case Additive = 'additive';
+
+    /**
+     * Create a new, independent TokenGrant carrying only the scopes
+     * required for this purpose.  No existing grant is modified.
+     * This is the default case.
+     */
+    case Isolated = 'isolated';
+}
diff --git a/src/Service/NullServiceAuthorizationRepository.php b/src/Service/NullServiceAuthorizationRepository.php
new file mode 100644
index 00000000..891b09d8
--- /dev/null
+++ b/src/Service/NullServiceAuthorizationRepository.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+/** Null ServiceAuthorizationRepository - safe default when service authorization is not configured. */
+class NullServiceAuthorizationRepository implements ServiceAuthorizationRepository
+{
+    public function find(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose,
+    ): ?ServiceAuthorization {
+        return null;
+    }
+
+    public function findAll(string $userId, string $providerId): array
+    {
+        return [];
+    }
+
+    public function findAllForUser(string $userId): array
+    {
+        return [];
+    }
+
+    public function save(ServiceAuthorization $authorization): void {}
+
+    public function delete(ServiceAuthorization $authorization): void {}
+
+    public function deleteAll(string $userId, string $providerId): void {}
+}
diff --git a/src/Service/NullServiceAuthorizationService.php b/src/Service/NullServiceAuthorizationService.php
new file mode 100644
index 00000000..674ee08b
--- /dev/null
+++ b/src/Service/NullServiceAuthorizationService.php
@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+use Horde\OAuth\Client\OAuthFlowData;
+use Horde\OAuth\Client\ScopeSet;
+use Psr\Http\Message\UriInterface;
+
+/** Null ServiceAuthorizationService - safe default when service authorization is not configured. */
+class NullServiceAuthorizationService implements ServiceAuthorizationService
+{
+    public function get(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose,
+    ): ServiceAuthorization {
+        throw new ServiceNotAuthorizedException(
+            $userId,
+            $providerId,
+            $purpose,
+            new ScopeSet()
+        );
+    }
+
+    public function initiate(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose,
+        string $returnUrl,
+        ?string $requestingApp = null,
+    ): ?UriInterface {
+        return null;
+    }
+
+    public function handleCallback(string $code, OAuthFlowData $flowData): ServiceAuthorization
+    {
+        throw new \RuntimeException('Service authorization not configured');
+    }
+
+    public function revoke(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose,
+    ): void {}
+
+    public function revokeAll(
+        string $userId,
+        string $providerId,
+        bool $revokeAtProvider = false,
+    ): void {}
+}
diff --git a/src/Service/NullTokenGrantRepository.php b/src/Service/NullTokenGrantRepository.php
new file mode 100644
index 00000000..da71e5b6
--- /dev/null
+++ b/src/Service/NullTokenGrantRepository.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+/** Null TokenGrantRepository - safe default when service authorization is not configured. */
+class NullTokenGrantRepository implements TokenGrantRepository
+{
+    public function findShared(string $userId, string $providerId): ?TokenGrant
+    {
+        return null;
+    }
+
+    public function findById(string $grantId): ?TokenGrant
+    {
+        return null;
+    }
+
+    public function findAll(string $userId, string $providerId): array
+    {
+        return [];
+    }
+
+    public function save(TokenGrant $grant): void {}
+
+    public function update(TokenGrant $grant): void {}
+
+    public function delete(TokenGrant $grant): void {}
+}
diff --git a/src/Service/OAuthProviderConfigRepository.php b/src/Service/OAuthProviderConfigRepository.php
index f1c0cd1d..4189e037 100644
--- a/src/Service/OAuthProviderConfigRepository.php
+++ b/src/Service/OAuthProviderConfigRepository.php
@@ -23,7 +23,7 @@
  * Storage contract for OAuth provider configurations.
  *
  * Providers are keyed by a unique slug (provider_id).
- * Data is returned as plain arrays with snake_case keys matching DB columns,
+ * Data is returned as plain arrays with snake_case keys matching DB columns
  * because the three provider types (oauth2, oidc, service_app) have
  * different shapes.
  *
diff --git a/src/Service/ServiceAuthorization.php b/src/Service/ServiceAuthorization.php
new file mode 100644
index 00000000..b4984609
--- /dev/null
+++ b/src/Service/ServiceAuthorization.php
@@ -0,0 +1,29 @@
+<?php
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+/**
+ * Revocation is performed through `ServiceAuthorizationService` rather than through this object.
+ * This avoids the object holding a self-reference to its repository.
+ */
+interface ServiceAuthorization
+{
+    public function userId(): string;
+    public function providerId(): string;
+    public function purpose(): ServicePurpose;
+    public function grant(): TokenGrant;
+
+    /**
+     * True if the backing grant is non-null and covers the scopes required
+     * for this purpose.  Does not perform a network call.
+     */
+    public function isSatisfied(): bool;
+
+    /**
+     * Return a valid access token delegating to grant()->getAccessToken().
+     *
+     * @throws ServiceNotAuthorizedException  when !isSatisfied()
+     * @throws OAuthTokenRefreshException     when the grant refresh fails
+     */
+    public function getAccessToken(): string;
+}
diff --git a/src/Service/ServiceAuthorizationRepository.php b/src/Service/ServiceAuthorizationRepository.php
new file mode 100644
index 00000000..4f3f943a
--- /dev/null
+++ b/src/Service/ServiceAuthorizationRepository.php
@@ -0,0 +1,26 @@
+<?php
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+interface ServiceAuthorizationRepository
+{
+    public function find(
+        string         $userId,
+        string         $providerId,
+        ServicePurpose $purpose,
+    ): ?ServiceAuthorization;
+
+    /** All authorizations for a (userId, providerId) pair. */
+    public function findAll(string $userId, string $providerId): array;
+
+    /** All authorizations for a user across all providers. */
+    public function findAllForUser(string $userId): array;
+
+    public function save(ServiceAuthorization $authorization): void;
+
+    public function delete(ServiceAuthorization $authorization): void;
+
+    /** Remove all authorizations for a (userId, providerId) pair. */
+    public function deleteAll(string $userId, string $providerId): void;
+}
diff --git a/src/Service/ServiceAuthorizationService.php b/src/Service/ServiceAuthorizationService.php
new file mode 100644
index 00000000..bb300c77
--- /dev/null
+++ b/src/Service/ServiceAuthorizationService.php
@@ -0,0 +1,74 @@
+<?php
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+use Psr\Http\Message\UriInterface;
+
+interface ServiceAuthorizationService
+{
+    /**
+     * Return an existing and satisfied ServiceAuthorization.
+     *
+     * @throws ServiceNotAuthorizedException  no authorization or grant does
+     *                                        not cover the required scopes.
+     *                                        The exception carries the purpose
+     *                                        and providerId. The caller can react by calling initiate().
+     */
+    public function get(
+        string         $userId,
+        string         $providerId,
+        ServicePurpose $purpose,
+    ): ServiceAuthorization;
+
+    /**
+     * Initiate an OAuth2 PKCE flow to establish a ServiceAuthorization.
+     *
+     * Additive strategy: if a shared grant already covers the required scopes,
+     * creates the ServiceAuthorization directly and returns null (no redirect).
+     *
+     * Isolated strategy: always starts a new flow. Preferred strategy.
+     *
+     * @throws UnsupportedPurposeException  the provider has no scope mapping
+     *                                      for this purpose.
+     * @return UriInterface|null  provider redirect URI, or null if no flow needed.
+     */
+    public function initiate(
+        string         $userId,
+        string         $providerId,
+        ServicePurpose $purpose,
+        string         $returnUrl,
+        ?string        $requestingApp = null,
+    ): ?UriInterface;
+
+    /**
+     * Handle the provider callback after PKCE state verification.
+     * Creates or updates the TokenGrant and creates the ServiceAuthorization.
+     * Does NOT call IdentityLinkService as that remains the caller's
+     * responsibility for 'login' and 'account_link' purposes.
+     */
+    public function handleCallback(string $code, OAuthFlowData $flowData): ServiceAuthorization;
+
+    /**
+     * Revoke a single ServiceAuthorization.
+     * The backing TokenGrant is not deleted.
+     */
+    public function revoke(
+        string         $userId,
+        string         $providerId,
+        ServicePurpose $purpose,
+    ): void;
+
+    /**
+     * Revoke all ServiceAuthorizations for a provider and delete all backing
+     * TokenGrants.
+     *
+     * @param bool $revokeAtProvider  True: Call the provider's revocation
+     *                                endpoint for each grant before deletion.
+     */
+    public function revokeAll(
+        string $userId,
+        string $providerId,
+        bool   $revokeAtProvider = false,
+    ): void;
+}
diff --git a/src/Service/ServiceNotAuthorizedException.php b/src/Service/ServiceNotAuthorizedException.php
new file mode 100644
index 00000000..c4ad3a69
--- /dev/null
+++ b/src/Service/ServiceNotAuthorizedException.php
@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+use Horde\OAuth\Client\ScopeSet;
+
+final class ServiceNotAuthorizedException extends \RuntimeException
+{
+    public function __construct(
+        private readonly string $userId,
+        private readonly string $providerId,
+        private readonly ServicePurpose $purpose,
+        private readonly ScopeSet $missingScopes,
+        string $message = '',
+        int $code = 0,
+        ?\Throwable $previous = null
+    ) {
+        if ($message === '') {
+            $message = sprintf(
+                "User '%s' is not authorized for purpose '%s' on provider '%s'",
+                $userId,
+                $purpose->identifier(),
+                $providerId
+            );
+        }
+        parent::__construct($message, $code, $previous);
+    }
+
+    public function userId(): string
+    {
+        return $this->userId;
+    }
+
+    public function providerId(): string
+    {
+        return $this->providerId;
+    }
+
+    public function purpose(): ServicePurpose
+    {
+        return $this->purpose;
+    }
+
+    /** Scopes still needed; empty ScopeSet if no grant exists at all. */
+    public function missingScopes(): ScopeSet
+    {
+        return $this->missingScopes;
+    }
+}
diff --git a/src/Service/ServicePurpose.php b/src/Service/ServicePurpose.php
new file mode 100644
index 00000000..006aa196
--- /dev/null
+++ b/src/Service/ServicePurpose.php
@@ -0,0 +1,50 @@
+<?php
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+/**
+ * Represents a specific purpose for which a service is used
+ * This is Horde Apps vocabulary decoupled from specific scopes an IdP provider may use to model the same concept.
+ * I.e. if the Horde identifier is "mail" and the scope in one IdP is "email" and the scope in another IdP is "imap", the ServicePurpose identifier is "mail"
+ * Two service purposes are equal if they have the same identifier even if they have different GrantStrategies.
+ * The default strategy is isolated grants.
+ */
+final class ServicePurpose
+{
+    private function __construct(
+        private readonly string        $identifier,
+        private readonly GrantStrategy $grantStrategy = GrantStrategy::Isolated,
+    ) {}
+
+    public static function of(string $identifier, GrantStrategy $grantStrategy = GrantStrategy::Isolated): self
+    {
+        return new self($identifier, $grantStrategy);
+    }
+
+    public function identifier(): string
+    {
+        return $this->identifier;
+    }
+
+    public function grantStrategy(): GrantStrategy
+    {
+        return $this->grantStrategy;
+    }
+
+    public function equals(self $other): bool
+    {
+        return $this->identifier === $other->identifier;
+    }
+
+    /** Round-trip through OAuthFlowData persistence. */
+    public function serialize(): array
+    {
+        return ['id' => $this->identifier, 'strategy' => $this->grantStrategy->value];
+    }
+
+    public static function deserialize(array $data): self
+    {
+        return new self($data['id'], GrantStrategy::from($data['strategy']));
+    }
+}
diff --git a/src/Service/TokenGrant.php b/src/Service/TokenGrant.php
new file mode 100644
index 00000000..3d1558fe
--- /dev/null
+++ b/src/Service/TokenGrant.php
@@ -0,0 +1,36 @@
+<?php
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+interface TokenGrant
+{
+    /** Stable UUID assigned at creation; used as FK by ServiceAuthorization. */
+    public function grantId(): string;
+
+    public function userId(): string;
+    public function providerId(): string;
+
+    /** The set of OAuth scopes that were granted by the provider. */
+    public function grantedScopes(): ScopeSet;
+
+    /**
+     * Return true if grantedScopes() is a superset of $required.
+     * Does not perform a network call.
+     */
+    public function covers(ScopeSet $required): bool;
+
+    /**
+     * Return a valid access token string.
+     * Refresh transparently if expired.
+     * Persists the refreshed TokenSet via TokenGrantRepository.
+     *
+     * @throws OAuthTokenRefreshException
+     */
+    public function getAccessToken(): string;
+
+    public function isExpired(): bool;
+
+    /** Raw token data */
+    public function tokenSet(): TokenSet;
+}
diff --git a/src/Service/TokenGrantRepository.php b/src/Service/TokenGrantRepository.php
new file mode 100644
index 00000000..26b01525
--- /dev/null
+++ b/src/Service/TokenGrantRepository.php
@@ -0,0 +1,32 @@
+<?php
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+interface TokenGrantRepository
+{
+    /**
+     * Find the shared grant for a "GrantStrategy::Additive" strategy lookup.
+     * Returns the single grant that is not exclusively owned by an Isolated
+     * ServiceAuthorization or null if none exists.
+     */
+    public function findShared(string $userId, string $providerId): ?TokenGrant;
+
+    /** Find any grant by its stable UUID. */
+    public function findById(string $grantId): ?TokenGrant;
+
+    /** Find all grants for a (userId, providerId) pair. */
+    public function findAll(string $userId, string $providerId): array;
+
+    /** Persist a new TokenGrant. */
+    public function save(TokenGrant $grant): void;
+
+    /**
+     * Persist changes to an existing grant (e.g. refreshed access token or
+     * extended scope set after an Additive flow).
+     */
+    public function update(TokenGrant $grant): void;
+
+    /** Delete a grant row. Caller must ensure no ServiceAuthorization references it. */
+    public function delete(TokenGrant $grant): void;
+}
diff --git a/src/Service/UnsupportedPurposeException.php b/src/Service/UnsupportedPurposeException.php
new file mode 100644
index 00000000..091be953
--- /dev/null
+++ b/src/Service/UnsupportedPurposeException.php
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+final class UnsupportedPurposeException extends \RuntimeException
+{
+    public function __construct(
+        private readonly string $providerId,
+        private readonly ServicePurpose $purpose,
+        string $message = '',
+        int $code = 0,
+        ?\Throwable $previous = null
+    ) {
+        if ($message === '') {
+            $message = sprintf(
+                "Provider '%s' does not support purpose '%s'",
+                $providerId,
+                $purpose->identifier()
+            );
+        }
+        parent::__construct($message, $code, $previous);
+    }
+
+    public function providerId(): string
+    {
+        return $this->providerId;
+    }
+
+    public function purpose(): ServicePurpose
+    {
+        return $this->purpose;
+    }
+}

From 351357b57075d8feaa30e8df32c1c5a33c39fd74 Mon Sep 17 00:00:00 2001
From: Ralf Lang <ralf.lang@sap.com>
Date: Mon, 28 Sep 2026 11:04:31 +0200
Subject: [PATCH 2/2] feat: Interfaces for Password-like Service Credentials
 handling

---
 src/DefaultInjectorBindings.php               | 12 ++++
 src/Service/AcquisitionAction.php             | 18 +++++
 src/Service/CredentialAcquisitionResult.php   | 19 +++++
 .../CredentialProvisioningStrategy.php        | 24 +++++++
 src/Service/CredentialStore.php               | 68 ++++++++++++++++++
 src/Service/CredentialType.php                | 16 +++++
 .../CredentialProvisioningStrategyFactory.php | 22 ++++++
 .../Factory/CredentialStoreFactory.php        | 22 ++++++
 ...wordServiceAuthorizationServiceFactory.php | 22 ++++++
 .../ServiceCredentialManagerFactory.php       | 22 ++++++
 .../NullCredentialProvisioningStrategy.php    | 23 ++++++
 src/Service/NullCredentialStore.php           | 62 ++++++++++++++++
 ...ullPasswordServiceAuthorizationService.php | 61 ++++++++++++++++
 src/Service/NullServiceCredentialManager.php  | 40 +++++++++++
 src/Service/PasswordCredential.php            | 47 ++++++++++++
 .../PasswordCredentialNotFoundException.php   | 47 ++++++++++++
 .../PasswordServiceAuthorizationService.php   | 72 +++++++++++++++++++
 src/Service/ProvisioningAction.php            | 18 +++++
 src/Service/ProvisioningResult.php            | 19 +++++
 src/Service/ServiceCredentialManager.php      | 43 +++++++++++
 src/Service/ServiceCredentialResult.php       | 38 ++++++++++
 21 files changed, 715 insertions(+)
 create mode 100644 src/Service/AcquisitionAction.php
 create mode 100644 src/Service/CredentialAcquisitionResult.php
 create mode 100644 src/Service/CredentialProvisioningStrategy.php
 create mode 100644 src/Service/CredentialStore.php
 create mode 100644 src/Service/CredentialType.php
 create mode 100644 src/Service/Factory/CredentialProvisioningStrategyFactory.php
 create mode 100644 src/Service/Factory/CredentialStoreFactory.php
 create mode 100644 src/Service/Factory/PasswordServiceAuthorizationServiceFactory.php
 create mode 100644 src/Service/Factory/ServiceCredentialManagerFactory.php
 create mode 100644 src/Service/NullCredentialProvisioningStrategy.php
 create mode 100644 src/Service/NullCredentialStore.php
 create mode 100644 src/Service/NullPasswordServiceAuthorizationService.php
 create mode 100644 src/Service/NullServiceCredentialManager.php
 create mode 100644 src/Service/PasswordCredential.php
 create mode 100644 src/Service/PasswordCredentialNotFoundException.php
 create mode 100644 src/Service/PasswordServiceAuthorizationService.php
 create mode 100644 src/Service/ProvisioningAction.php
 create mode 100644 src/Service/ProvisioningResult.php
 create mode 100644 src/Service/ServiceCredentialManager.php
 create mode 100644 src/Service/ServiceCredentialResult.php

diff --git a/src/DefaultInjectorBindings.php b/src/DefaultInjectorBindings.php
index 5f9da666..e87385f0 100644
--- a/src/DefaultInjectorBindings.php
+++ b/src/DefaultInjectorBindings.php
@@ -78,6 +78,10 @@
 use Horde\Core\Factory\OAuthFlowStoreFactory;
 use Horde\Core\Factory\PermissionServiceFactory;
 use Horde\Core\Factory\PrefsServiceFactory;
+use Horde\Core\Service\Factory\CredentialStoreFactory;
+use Horde\Core\Service\Factory\CredentialProvisioningStrategyFactory;
+use Horde\Core\Service\Factory\PasswordServiceAuthorizationServiceFactory;
+use Horde\Core\Service\Factory\ServiceCredentialManagerFactory;
 use Horde\Core\Factory\RegistryConfigLoaderFactory;
 use Horde\Core\Factory\RouteUrlWriterFactory;
 use Horde\Core\Factory\RuntimeRoutesProviderFactory;
@@ -94,6 +98,8 @@
 use Horde\Core\Middleware\ErrorFilter;
 use Horde\Core\Middleware\OAuthConsentMiddleware;
 use Horde\Core\Service\ApplicationService;
+use Horde\Core\Service\CredentialStore;
+use Horde\Core\Service\CredentialProvisioningStrategy;
 use Horde\Core\Service\GroupService;
 use Horde\Core\Service\HordeDbService;
 use Horde\Core\Service\HordeLdapService;
@@ -101,8 +107,10 @@
 use Horde\Core\Service\OAuthHttpClientService;
 use Horde\Core\Service\OAuthProviderConfigRepository;
 use Horde\Core\Service\OAuthTokenService;
+use Horde\Core\Service\PasswordServiceAuthorizationService;
 use Horde\Core\Service\PermissionService;
 use Horde\Core\Service\PrefsService;
+use Horde\Core\Service\ServiceCredentialManager;
 use Horde\Core\Service\VersionCheck\VersionService;
 use Horde\Core\Uri\RegistryRouteMapperProvider;
 use Horde\Core\Uri\RouteMapperProvider;
@@ -288,6 +296,10 @@ public function register(Injector $injector): void
             HordeLdapService::class => HordeLdapServiceFactory::class,
             PermissionService::class => PermissionServiceFactory::class,
             VersionService::class => VersionServiceFactory::class,
+            CredentialStore::class => CredentialStoreFactory::class,
+            CredentialProvisioningStrategy::class => CredentialProvisioningStrategyFactory::class,
+            PasswordServiceAuthorizationService::class => PasswordServiceAuthorizationServiceFactory::class,
+            ServiceCredentialManager::class => ServiceCredentialManagerFactory::class,
             Tinymce::class => TinymceFactory::class,
             TinymcePageBinder::class => TinymcePageBinderFactory::class,
             EventDispatcherInterface::class => [EventDispatcherFactory::class, 'create'],
diff --git a/src/Service/AcquisitionAction.php b/src/Service/AcquisitionAction.php
new file mode 100644
index 00000000..9df58b12
--- /dev/null
+++ b/src/Service/AcquisitionAction.php
@@ -0,0 +1,18 @@
+<?php
+/**
+ * Actions that can result from credential acquisition attempt.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+enum AcquisitionAction
+{
+    case Redirect;      // OAuth flow
+    case ShowForm;      // Password entry
+    case AlreadyExists; // No action needed
+    case Unavailable;   // Cannot acquire
+}
diff --git a/src/Service/CredentialAcquisitionResult.php b/src/Service/CredentialAcquisitionResult.php
new file mode 100644
index 00000000..e4312a6d
--- /dev/null
+++ b/src/Service/CredentialAcquisitionResult.php
@@ -0,0 +1,19 @@
+<?php
+/**
+ * Result of credential acquisition attempt.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+final class CredentialAcquisitionResult
+{
+    public function __construct(
+        public readonly AcquisitionAction $action,
+        public readonly ?string $redirectUri = null,
+        public readonly ?array $formFields = null,
+    ) {}
+}
diff --git a/src/Service/CredentialProvisioningStrategy.php b/src/Service/CredentialProvisioningStrategy.php
new file mode 100644
index 00000000..64a2fd49
--- /dev/null
+++ b/src/Service/CredentialProvisioningStrategy.php
@@ -0,0 +1,24 @@
+<?php
+/**
+ * Strategy interface for credential provisioning.
+ *
+ * Defines how credentials get into the system initially.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+interface CredentialProvisioningStrategy
+{
+    /**
+     * Attempt to provision credentials for given context.
+     */
+    public function provision(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose
+    ): ProvisioningResult;
+}
diff --git a/src/Service/CredentialStore.php b/src/Service/CredentialStore.php
new file mode 100644
index 00000000..fe0ec23d
--- /dev/null
+++ b/src/Service/CredentialStore.php
@@ -0,0 +1,68 @@
+<?php
+/**
+ * Repository interface for password credential storage.
+ *
+ * Abstracts storage/retrieval from service logic. Implementations handle
+ * encryption/decryption internally and return fully-decrypted credentials.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+interface CredentialStore
+{
+    /**
+     * Find credential for specific user/provider/purpose.
+     */
+    public function find(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose
+    ): ?PasswordCredential;
+
+    /**
+     * Find all credentials for a user.
+     *
+     * @return PasswordCredential[]
+     */
+    public function findAll(string $userId): array;
+
+    /**
+     * Find all credentials for a user+provider.
+     *
+     * @return PasswordCredential[]
+     */
+    public function findAllForProvider(
+        string $userId,
+        string $providerId
+    ): array;
+
+    /**
+     * Store new credential.
+     *
+     * @param array|string $credential Array for structured {'username','password'}, string for opaque
+     */
+    public function store(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose,
+        array|string $credential
+    ): PasswordCredential;
+
+    /**
+     * Update existing credential.
+     *
+     * @param array|string $credential Array for structured, string for opaque
+     */
+    public function update(
+        string $credentialId,
+        array|string $credential
+    ): PasswordCredential;
+
+    public function delete(string $credentialId): void;
+
+    public function deleteAll(string $userId, string $providerId): void;
+}
diff --git a/src/Service/CredentialType.php b/src/Service/CredentialType.php
new file mode 100644
index 00000000..b721a40e
--- /dev/null
+++ b/src/Service/CredentialType.php
@@ -0,0 +1,16 @@
+<?php
+/**
+ * Credential types supported by unified manager.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+enum CredentialType
+{
+    case OAuth;
+    case Password;
+}
diff --git a/src/Service/Factory/CredentialProvisioningStrategyFactory.php b/src/Service/Factory/CredentialProvisioningStrategyFactory.php
new file mode 100644
index 00000000..c4d85911
--- /dev/null
+++ b/src/Service/Factory/CredentialProvisioningStrategyFactory.php
@@ -0,0 +1,22 @@
+<?php
+/**
+ * Factory for CredentialProvisioningStrategy.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service\Factory;
+
+use Horde\Core\Service\CredentialProvisioningStrategy;
+use Horde\Core\Service\NullCredentialProvisioningStrategy;
+use Horde_Injector;
+
+class CredentialProvisioningStrategyFactory
+{
+    public function create(Horde_Injector $injector): CredentialProvisioningStrategy
+    {
+        return new NullCredentialProvisioningStrategy();
+    }
+}
diff --git a/src/Service/Factory/CredentialStoreFactory.php b/src/Service/Factory/CredentialStoreFactory.php
new file mode 100644
index 00000000..5eab810f
--- /dev/null
+++ b/src/Service/Factory/CredentialStoreFactory.php
@@ -0,0 +1,22 @@
+<?php
+/**
+ * Factory for CredentialStore.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service\Factory;
+
+use Horde\Core\Service\CredentialStore;
+use Horde\Core\Service\NullCredentialStore;
+use Horde_Injector;
+
+class CredentialStoreFactory
+{
+    public function create(Horde_Injector $injector): CredentialStore
+    {
+        return new NullCredentialStore();
+    }
+}
diff --git a/src/Service/Factory/PasswordServiceAuthorizationServiceFactory.php b/src/Service/Factory/PasswordServiceAuthorizationServiceFactory.php
new file mode 100644
index 00000000..3432359b
--- /dev/null
+++ b/src/Service/Factory/PasswordServiceAuthorizationServiceFactory.php
@@ -0,0 +1,22 @@
+<?php
+/**
+ * Factory for PasswordServiceAuthorizationService.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service\Factory;
+
+use Horde\Core\Service\NullPasswordServiceAuthorizationService;
+use Horde\Core\Service\PasswordServiceAuthorizationService;
+use Horde_Injector;
+
+class PasswordServiceAuthorizationServiceFactory
+{
+    public function create(Horde_Injector $injector): PasswordServiceAuthorizationService
+    {
+        return new NullPasswordServiceAuthorizationService();
+    }
+}
diff --git a/src/Service/Factory/ServiceCredentialManagerFactory.php b/src/Service/Factory/ServiceCredentialManagerFactory.php
new file mode 100644
index 00000000..d28e5bc9
--- /dev/null
+++ b/src/Service/Factory/ServiceCredentialManagerFactory.php
@@ -0,0 +1,22 @@
+<?php
+/**
+ * Factory for ServiceCredentialManager.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service\Factory;
+
+use Horde\Core\Service\NullServiceCredentialManager;
+use Horde\Core\Service\ServiceCredentialManager;
+use Horde_Injector;
+
+class ServiceCredentialManagerFactory
+{
+    public function create(Horde_Injector $injector): ServiceCredentialManager
+    {
+        return new NullServiceCredentialManager();
+    }
+}
diff --git a/src/Service/NullCredentialProvisioningStrategy.php b/src/Service/NullCredentialProvisioningStrategy.php
new file mode 100644
index 00000000..8f518d26
--- /dev/null
+++ b/src/Service/NullCredentialProvisioningStrategy.php
@@ -0,0 +1,23 @@
+<?php
+/**
+ * Null implementation of CredentialProvisioningStrategy.
+ *
+ * Always returns Unavailable action.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+final class NullCredentialProvisioningStrategy implements CredentialProvisioningStrategy
+{
+    public function provision(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose
+    ): ProvisioningResult {
+        return new ProvisioningResult(ProvisioningAction::Unavailable);
+    }
+}
diff --git a/src/Service/NullCredentialStore.php b/src/Service/NullCredentialStore.php
new file mode 100644
index 00000000..09deab2a
--- /dev/null
+++ b/src/Service/NullCredentialStore.php
@@ -0,0 +1,62 @@
+<?php
+/**
+ * Null implementation of CredentialStore.
+ *
+ * Returns null/empty for all find operations, no-ops for mutations.
+ * Used when password credential system is not configured.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+final class NullCredentialStore implements CredentialStore
+{
+    public function find(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose
+    ): ?PasswordCredential {
+        return null;
+    }
+
+    public function findAll(string $userId): array
+    {
+        return [];
+    }
+
+    public function findAllForProvider(
+        string $userId,
+        string $providerId
+    ): array {
+        return [];
+    }
+
+    public function store(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose,
+        array|string $credential
+    ): PasswordCredential {
+        throw new \RuntimeException('Password credential storage not available');
+    }
+
+    public function update(
+        string $credentialId,
+        array|string $credential
+    ): PasswordCredential {
+        throw new \RuntimeException('Password credential storage not available');
+    }
+
+    public function delete(string $credentialId): void
+    {
+        // No-op
+    }
+
+    public function deleteAll(string $userId, string $providerId): void
+    {
+        // No-op
+    }
+}
diff --git a/src/Service/NullPasswordServiceAuthorizationService.php b/src/Service/NullPasswordServiceAuthorizationService.php
new file mode 100644
index 00000000..21a8ca57
--- /dev/null
+++ b/src/Service/NullPasswordServiceAuthorizationService.php
@@ -0,0 +1,61 @@
+<?php
+/**
+ * Null implementation of PasswordServiceAuthorizationService.
+ *
+ * Throws exceptions for retrieval, returns unavailable for provisioning.
+ * Used when password credential system is not configured.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+final class NullPasswordServiceAuthorizationService implements PasswordServiceAuthorizationService
+{
+    public function get(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose
+    ): PasswordCredential {
+        throw new PasswordCredentialNotFoundException($userId, $providerId, $purpose);
+    }
+
+    public function initiate(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose
+    ): ProvisioningResult {
+        return new ProvisioningResult(ProvisioningAction::Unavailable);
+    }
+
+    public function store(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose,
+        array|string $credential
+    ): PasswordCredential {
+        throw new \RuntimeException('Password credential service not available');
+    }
+
+    public function update(
+        string $credentialId,
+        array|string $credential
+    ): PasswordCredential {
+        throw new \RuntimeException('Password credential service not available');
+    }
+
+    public function revoke(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose
+    ): void {
+        // No-op
+    }
+
+    public function revokeAll(string $userId, string $providerId): void
+    {
+        // No-op
+    }
+}
diff --git a/src/Service/NullServiceCredentialManager.php b/src/Service/NullServiceCredentialManager.php
new file mode 100644
index 00000000..4515e117
--- /dev/null
+++ b/src/Service/NullServiceCredentialManager.php
@@ -0,0 +1,40 @@
+<?php
+/**
+ * Null implementation of ServiceCredentialManager.
+ *
+ * Throws exceptions for all operations.
+ * Used when unified credential system is not configured.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+final class NullServiceCredentialManager implements ServiceCredentialManager
+{
+    public function get(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose
+    ): ServiceCredentialResult {
+        throw new \RuntimeException('Service credential manager not available');
+    }
+
+    public function initiate(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose
+    ): CredentialAcquisitionResult {
+        return new CredentialAcquisitionResult(AcquisitionAction::Unavailable);
+    }
+
+    public function revoke(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose
+    ): void {
+        // No-op
+    }
+}
diff --git a/src/Service/PasswordCredential.php b/src/Service/PasswordCredential.php
new file mode 100644
index 00000000..7066da02
--- /dev/null
+++ b/src/Service/PasswordCredential.php
@@ -0,0 +1,47 @@
+<?php
+/**
+ * Password-based credential value object.
+ *
+ * Represents retrieved credentials for password-based authentication systems.
+ * Supports both structured (username/password) and opaque (bearer token) formats.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+interface PasswordCredential
+{
+    public function credentialId(): string;
+    public function userId(): string;
+    public function providerId(): string;
+    public function purpose(): ServicePurpose;
+
+    /**
+     * Returns credential as structured array.
+     * Typically ['username' => '...', 'password' => '...']
+     */
+    public function asStructured(): array;
+
+    /**
+     * Returns credential as opaque string.
+     * For bearer tokens, API keys, or encoded strings.
+     */
+    public function asOpaque(): string;
+
+    /**
+     * Convenience method for HTTP Bearer header value.
+     */
+    public function asBearerToken(): string;
+
+    /**
+     * Convenience method for HTTP Basic Auth header value.
+     * Returns base64-encoded "username:password"
+     */
+    public function asBasicAuth(): string;
+
+    public function createdAt(): int;
+    public function updatedAt(): int;
+}
diff --git a/src/Service/PasswordCredentialNotFoundException.php b/src/Service/PasswordCredentialNotFoundException.php
new file mode 100644
index 00000000..d06d64f0
--- /dev/null
+++ b/src/Service/PasswordCredentialNotFoundException.php
@@ -0,0 +1,47 @@
+<?php
+/**
+ * Exception thrown when password credential is not found.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+class PasswordCredentialNotFoundException extends \RuntimeException
+{
+    public function __construct(
+        private readonly string $userId,
+        private readonly string $providerId,
+        private readonly ServicePurpose $purpose,
+        string $message = '',
+        int $code = 0,
+        ?\Throwable $previous = null
+    ) {
+        if ($message === '') {
+            $message = sprintf(
+                'Password credential not found for user "%s", provider "%s", purpose "%s"',
+                $userId,
+                $providerId,
+                $purpose->identifier()
+            );
+        }
+        parent::__construct($message, $code, $previous);
+    }
+
+    public function getUserId(): string
+    {
+        return $this->userId;
+    }
+
+    public function getProviderId(): string
+    {
+        return $this->providerId;
+    }
+
+    public function getPurpose(): ServicePurpose
+    {
+        return $this->purpose;
+    }
+}
diff --git a/src/Service/PasswordServiceAuthorizationService.php b/src/Service/PasswordServiceAuthorizationService.php
new file mode 100644
index 00000000..be18accf
--- /dev/null
+++ b/src/Service/PasswordServiceAuthorizationService.php
@@ -0,0 +1,72 @@
+<?php
+/**
+ * Service interface for password-based authorization.
+ *
+ * Coordinates credential retrieval and provisioning for password-based
+ * authentication systems (username/password, API keys, bearer tokens).
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+interface PasswordServiceAuthorizationService
+{
+    /**
+     * Retrieve existing credential.
+     *
+     * @throws PasswordCredentialNotFoundException
+     */
+    public function get(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose
+    ): PasswordCredential;
+
+    /**
+     * Initiate provisioning if credential doesn't exist.
+     */
+    public function initiate(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose
+    ): ProvisioningResult;
+
+    /**
+     * Store credential (from form submission).
+     *
+     * @param array|string $credential Array for structured, string for opaque
+     */
+    public function store(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose,
+        array|string $credential
+    ): PasswordCredential;
+
+    /**
+     * Update existing credential.
+     *
+     * @param array|string $credential Array for structured, string for opaque
+     */
+    public function update(
+        string $credentialId,
+        array|string $credential
+    ): PasswordCredential;
+
+    /**
+     * Delete credential for specific purpose.
+     */
+    public function revoke(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose
+    ): void;
+
+    /**
+     * Delete all credentials for provider.
+     */
+    public function revokeAll(string $userId, string $providerId): void;
+}
diff --git a/src/Service/ProvisioningAction.php b/src/Service/ProvisioningAction.php
new file mode 100644
index 00000000..6ddb6bda
--- /dev/null
+++ b/src/Service/ProvisioningAction.php
@@ -0,0 +1,18 @@
+<?php
+/**
+ * Actions that can result from provisioning attempt.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+enum ProvisioningAction
+{
+    case Redirect;      // OAuth flow
+    case ShowForm;      // Password entry form
+    case UseSession;    // Already provisioned in session
+    case Unavailable;   // Cannot provision
+}
diff --git a/src/Service/ProvisioningResult.php b/src/Service/ProvisioningResult.php
new file mode 100644
index 00000000..f8f45d35
--- /dev/null
+++ b/src/Service/ProvisioningResult.php
@@ -0,0 +1,19 @@
+<?php
+/**
+ * Result of credential provisioning attempt.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+final class ProvisioningResult
+{
+    public function __construct(
+        public readonly ProvisioningAction $action,
+        public readonly ?string $redirectUri = null,
+        public readonly ?array $formFields = null,
+    ) {}
+}
diff --git a/src/Service/ServiceCredentialManager.php b/src/Service/ServiceCredentialManager.php
new file mode 100644
index 00000000..43af23ef
--- /dev/null
+++ b/src/Service/ServiceCredentialManager.php
@@ -0,0 +1,43 @@
+<?php
+/**
+ * Unified credential manager (Entry Point B).
+ *
+ * Abstraction that dispatches to OAuth or Password subsystem transparently
+ * based on provider configuration.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+interface ServiceCredentialManager
+{
+    /**
+     * Retrieve credential for a purpose (agnostic to underlying system).
+     */
+    public function get(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose
+    ): ServiceCredentialResult;
+
+    /**
+     * Initiate acquisition if credential doesn't exist.
+     */
+    public function initiate(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose
+    ): CredentialAcquisitionResult;
+
+    /**
+     * Revoke credential.
+     */
+    public function revoke(
+        string $userId,
+        string $providerId,
+        ServicePurpose $purpose
+    ): void;
+}
diff --git a/src/Service/ServiceCredentialResult.php b/src/Service/ServiceCredentialResult.php
new file mode 100644
index 00000000..c113bfef
--- /dev/null
+++ b/src/Service/ServiceCredentialResult.php
@@ -0,0 +1,38 @@
+<?php
+/**
+ * Result of unified credential retrieval.
+ *
+ * @package Horde_Core
+ */
+
+declare(strict_types=1);
+
+namespace Horde\Core\Service;
+
+final class ServiceCredentialResult
+{
+    public function __construct(
+        public readonly CredentialType $type,
+        public readonly TokenGrant|PasswordCredential $credential,
+    ) {}
+
+    /**
+     * Convenience accessor for OAuth token.
+     */
+    public function asOAuthToken(): ?string
+    {
+        return $this->type === CredentialType::OAuth
+            ? $this->credential->getAccessToken()
+            : null;
+    }
+
+    /**
+     * Convenience accessor for password credential.
+     */
+    public function asPassword(): ?PasswordCredential
+    {
+        return $this->type === CredentialType::Password
+            ? $this->credential
+            : null;
+    }
+}