Initial Version

shared/lib/Security/Authentication/AuthenticationProviderInterface.php

@@ -0,0 +1,100 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\Security\Authentication;
+
+use KTXF\Resource\Provider\ProviderInterface;
+use KTXF\Security\Authentication\ProviderContext;
+use KTXF\Security\Authentication\ProviderResult;
+
+/**
+ * Unified Authentication Provider Interface
+ */
+interface AuthenticationProviderInterface extends ProviderInterface
+{
+    /** Secret style authentication (e.g. password, TOTP, etc) */
+    public const METHOD_CREDENTIAL = 'credential';
+
+    /** Challenge/response (e.g. SMS code, email code, etc) */
+    public const METHOD_CHALLENGE = 'challenge';
+    
+    /** Redirect-based (e.g. OIDC, SAML, OAuth) */
+    public const METHOD_REDIRECT = 'redirect';
+
+    /**
+     * Provider method - one of the METHOD_* constants
+     */
+    public function method(): string;
+
+    /**
+     * Provider icon
+     */
+    public function icon(): string;
+
+    // =========================================================================
+    // Credential Authentication
+    // =========================================================================
+
+    /**
+     * Authenticate with credentials (username/password style)
+     * 
+     * @param ProviderContext $context Authentication context
+     * @param string $secret Password, PIN, or secret
+     * 
+     * @return ProviderResult
+     */
+    public function verify(ProviderContext $context, string $secret): ProviderResult;
+        
+    // =========================================================================
+    // Challenge/Response Authentication
+    // =========================================================================
+
+    /**
+     * Begin a challenge (send code, prepare for verification)
+     * 
+     * For SMS/Email: Sends the code and returns confirmation
+     * For TOTP: Returns challenge metadata (digits, etc.)
+     * 
+     * @param ProviderContext $context Authentication context
+     * 
+     * @return ProviderResult Contains challenge metadata in clientData
+     */
+    public function beginChallenge(ProviderContext $context): ProviderResult;
+
+    /**
+     * Verify challenge response
+     * 
+     * @param ProviderContext $context Authentication context
+     * @param string $code User's response code
+     * 
+     * @return ProviderResult
+     */
+    public function verifyChallenge(ProviderContext $context, string $code): ProviderResult;
+
+    // =========================================================================
+    // Redirect Authentication (OIDC/SAML)
+    // =========================================================================
+
+    /**
+     * Begin redirect-based authentication
+     * 
+     * @param ProviderContext $context Authentication context (contains config)
+     * @param string $callbackUrl URL to redirect back to
+     * @param string|null $returnUrl Final destination after auth
+     * 
+     * @return ProviderResult Contains redirect_url in clientData, state/nonce in sessionData
+     */
+    public function beginRedirect(ProviderContext $context, string $callbackUrl, ?string $returnUrl = null): ProviderResult;
+
+    /**
+     * Complete redirect-based authentication
+     * 
+     * @param ProviderContext $context Authentication context (contains stored state/nonce in metadata)
+     * @param array $params Callback parameters (code, state, etc.)
+     * 
+     * @return ProviderResult Contains user attributes in identity on success
+     */
+    public function completeRedirect(ProviderContext $context, array $params): ProviderResult;
+
+}