chore(thalos-bff): merge contract integration branch

docs/api/identity-edge-api.md

@@ -3,6 +3,7 @@
 ## Active External Protocol
 
 - REST is the active external protocol for this BFF deployment.
+- Internal service calls default to gRPC-adapted contracts.
 
 ## Entrypoints
 
@@ -12,5 +13,7 @@
 ## Boundary Notes
 
 - Endpoint handlers perform edge validation and permission checks.
+- Token issuance and policy evaluation requests are mapped to thalos-service identity contracts.
+- Session refresh requests are mapped through edge contract adapters before downstream calls.
 - Business orchestration remains in thalos-service.
 - Identity abstractions remain owned by Thalos repositories.

docs/architecture/thalos-bff-flow.puml

@@ -8,11 +8,17 @@ package "thalos-bff" {
   interface IRefreshSessionHandler
   class RefreshSessionHandler
   interface IPermissionGuard
+  interface IIdentityEdgeContractAdapter
+  interface IIdentityEdgeGrpcContractAdapter
   interface IThalosServiceClient
+  class IssueIdentityTokenGrpcContract
 
   IssueTokenHandler ..|> IIssueTokenHandler
   RefreshSessionHandler ..|> IRefreshSessionHandler
   IssueTokenHandler --> IPermissionGuard
+  IssueTokenHandler --> IIdentityEdgeContractAdapter
+  RefreshSessionHandler --> IIdentityEdgeContractAdapter
+  IIdentityEdgeGrpcContractAdapter --> IssueIdentityTokenGrpcContract
   IssueTokenHandler --> IThalosServiceClient
   RefreshSessionHandler --> IThalosServiceClient
 }
@@ -23,5 +29,5 @@ package "thalos-service" as ThalosService
 Clients --> Program : REST
 Program --> IIssueTokenHandler
 Program --> IRefreshSessionHandler
-IThalosServiceClient ..> ThalosService : gRPC/internal
+IThalosServiceClient ..> ThalosService : gRPC/internal contracts
 @enduml

docs/security/permission-enforcement-map.md

@@ -2,10 +2,10 @@
 
 ## Enforcement Points
 
-- `identity.token.issue` evaluated at token issuance handler.
+- `identity.token.issue` evaluated via thalos-service policy contract before token issuance.
 - Session refresh guarded by edge session validation policy.
 
 ## Guardrail
 
-- Permission checks happen at BFF entrypoints before downstream calls.
+- Permission checks happen at BFF entrypoints using thalos-service policy responses.
 - Authorization decisions are explicit and traceable at edge boundaries.

src/Thalos.Bff.Application/Adapters/IIdentityEdgeContractAdapter.cs

@@ -0,0 +1,47 @@
+using Thalos.Bff.Application.Contracts;
+using Thalos.Bff.Contracts.Api;
+using Thalos.Service.Identity.Abstractions.Contracts;
+
+namespace Thalos.Bff.Application.Adapters;
+
+/// <summary>
+/// Defines adapter boundary between external edge contracts and thalos-service contracts.
+/// </summary>
+public interface IIdentityEdgeContractAdapter
+{
+    /// <summary>
+    /// Maps API request into identity policy evaluation request.
+    /// </summary>
+    /// <param name="request">External API request.</param>
+    /// <param name="permissionCode">Permission code to evaluate.</param>
+    /// <returns>Identity policy request.</returns>
+    EvaluateIdentityPolicyRequest ToPolicyRequest(IssueTokenApiRequest request, string permissionCode);
+
+    /// <summary>
+    /// Maps API request into identity token issuance request.
+    /// </summary>
+    /// <param name="request">External API request.</param>
+    /// <returns>Identity token issuance request.</returns>
+    IssueIdentityTokenRequest ToIssueTokenRequest(IssueTokenApiRequest request);
+
+    /// <summary>
+    /// Maps identity token issuance response into edge API response.
+    /// </summary>
+    /// <param name="response">Identity token issuance response.</param>
+    /// <returns>External API response.</returns>
+    IssueTokenApiResponse ToIssueTokenApiResponse(IssueIdentityTokenResponse response);
+
+    /// <summary>
+    /// Maps refresh API request into internal refresh contract.
+    /// </summary>
+    /// <param name="request">External refresh API request.</param>
+    /// <returns>Internal refresh request.</returns>
+    RefreshIdentitySessionRequest ToRefreshSessionRequest(RefreshSessionApiRequest request);
+
+    /// <summary>
+    /// Maps internal refresh response into external API response.
+    /// </summary>
+    /// <param name="response">Internal refresh response.</param>
+    /// <returns>External API response.</returns>
+    RefreshSessionApiResponse ToRefreshSessionApiResponse(RefreshIdentitySessionResponse response);
+}

src/Thalos.Bff.Application/Adapters/IIdentityEdgeGrpcContractAdapter.cs

@@ -0,0 +1,24 @@
+using Thalos.Bff.Application.Grpc;
+using Thalos.Bff.Contracts.Api;
+
+namespace Thalos.Bff.Application.Adapters;
+
+/// <summary>
+/// Defines adapter boundary for gRPC contract translation at the identity edge.
+/// </summary>
+public interface IIdentityEdgeGrpcContractAdapter
+{
+    /// <summary>
+    /// Maps external API request into gRPC contract shape.
+    /// </summary>
+    /// <param name="request">External token issuance request.</param>
+    /// <returns>gRPC token issuance contract.</returns>
+    IssueIdentityTokenGrpcContract ToGrpc(IssueTokenApiRequest request);
+
+    /// <summary>
+    /// Maps gRPC contract shape into external API request.
+    /// </summary>
+    /// <param name="contract">gRPC token issuance contract.</param>
+    /// <returns>External token issuance request.</returns>
+    IssueTokenApiRequest FromGrpc(IssueIdentityTokenGrpcContract contract);
+}

src/Thalos.Bff.Application/Adapters/IThalosServiceClient.cs

@@ -1,4 +1,5 @@
-using Thalos.Bff.Contracts.Api;
+using Thalos.Bff.Application.Contracts;
+using Thalos.Service.Identity.Abstractions.Contracts;
 
 namespace Thalos.Bff.Application.Adapters;
 
@@ -10,14 +11,21 @@ public interface IThalosServiceClient
     /// <summary>
     /// Requests token issuance from thalos-service.
     /// </summary>
-    /// <param name="request">Token issuance request.</param>
+    /// <param name="request">Identity token issuance request.</param>
     /// <returns>Token issuance response.</returns>
-    Task<IssueTokenApiResponse> IssueTokenAsync(IssueTokenApiRequest request);
+    Task<IssueIdentityTokenResponse> IssueTokenAsync(IssueIdentityTokenRequest request);
+
+    /// <summary>
+    /// Requests policy evaluation from thalos-service.
+    /// </summary>
+    /// <param name="request">Identity policy request.</param>
+    /// <returns>Identity policy response.</returns>
+    Task<EvaluateIdentityPolicyResponse> EvaluatePolicyAsync(EvaluateIdentityPolicyRequest request);
 
     /// <summary>
     /// Requests token refresh from thalos-service.
     /// </summary>
     /// <param name="request">Session refresh request.</param>
     /// <returns>Session refresh response.</returns>
-    Task<RefreshSessionApiResponse> RefreshSessionAsync(RefreshSessionApiRequest request);
+    Task<RefreshIdentitySessionResponse> RefreshSessionAsync(RefreshIdentitySessionRequest request);
 }

src/Thalos.Bff.Application/Contracts/RefreshIdentitySessionRequest.cs

@@ -0,0 +1,8 @@
+namespace Thalos.Bff.Application.Contracts;
+
+/// <summary>
+/// Transport-neutral internal request contract for refresh session flow.
+/// </summary>
+/// <param name="RefreshToken">Refresh token value.</param>
+/// <param name="CorrelationId">Request correlation identifier.</param>
+public sealed record RefreshIdentitySessionRequest(string RefreshToken, string CorrelationId);

src/Thalos.Bff.Application/Contracts/RefreshIdentitySessionResponse.cs

@@ -0,0 +1,8 @@
+namespace Thalos.Bff.Application.Contracts;
+
+/// <summary>
+/// Transport-neutral internal response contract for refresh session flow.
+/// </summary>
+/// <param name="Token">Refreshed token value.</param>
+/// <param name="ExpiresInSeconds">Token expiration in seconds.</param>
+public sealed record RefreshIdentitySessionResponse(string Token, int ExpiresInSeconds);

src/Thalos.Bff.Application/Grpc/IssueIdentityTokenGrpcContract.cs

@@ -0,0 +1,9 @@
+namespace Thalos.Bff.Application.Grpc;
+
+/// <summary>
+/// Defines minimal gRPC contract shape for identity token edge translation.
+/// </summary>
+/// <param name="SubjectId">Identity subject identifier.</param>
+/// <param name="TenantId">Tenant identifier.</param>
+/// <param name="CorrelationId">Request correlation identifier.</param>
+public sealed record IssueIdentityTokenGrpcContract(string SubjectId, string TenantId, string CorrelationId);

src/Thalos.Bff.Application/Handlers/IssueTokenHandler.cs

@@ -7,17 +7,25 @@ namespace Thalos.Bff.Application.Handlers;
 /// <summary>
 /// Default edge handler for token issuance.
 /// </summary>
-public sealed class IssueTokenHandler(IThalosServiceClient serviceClient, IPermissionGuard permissionGuard)
+public sealed class IssueTokenHandler(
+    IThalosServiceClient serviceClient,
+    IIdentityEdgeContractAdapter contractAdapter,
+    IPermissionGuard permissionGuard)
     : IIssueTokenHandler
 {
     /// <inheritdoc />
-    public Task<IssueTokenApiResponse> HandleAsync(IssueTokenApiRequest request)
+    public async Task<IssueTokenApiResponse> HandleAsync(IssueTokenApiRequest request)
     {
-        if (!permissionGuard.CanAccess("identity.token.issue"))
+        var policyRequest = contractAdapter.ToPolicyRequest(request, "identity.token.issue");
+        var policyResponse = await serviceClient.EvaluatePolicyAsync(policyRequest);
+
+        if (!permissionGuard.CanAccess(policyResponse))
         {
             throw new UnauthorizedAccessException("Permission denied.");
         }
 
-        return serviceClient.IssueTokenAsync(request);
+        var issueRequest = contractAdapter.ToIssueTokenRequest(request);
+        var issueResponse = await serviceClient.IssueTokenAsync(issueRequest);
+        return contractAdapter.ToIssueTokenApiResponse(issueResponse);
     }
 }

src/Thalos.Bff.Application/Handlers/RefreshSessionHandler.cs

@@ -6,12 +6,16 @@ namespace Thalos.Bff.Application.Handlers;
 /// <summary>
 /// Default edge handler for refresh session flow.
 /// </summary>
-public sealed class RefreshSessionHandler(IThalosServiceClient serviceClient)
+public sealed class RefreshSessionHandler(
+    IThalosServiceClient serviceClient,
+    IIdentityEdgeContractAdapter contractAdapter)
     : IRefreshSessionHandler
 {
     /// <inheritdoc />
-    public Task<RefreshSessionApiResponse> HandleAsync(RefreshSessionApiRequest request)
+    public async Task<RefreshSessionApiResponse> HandleAsync(RefreshSessionApiRequest request)
     {
-        return serviceClient.RefreshSessionAsync(request);
+        var refreshRequest = contractAdapter.ToRefreshSessionRequest(request);
+        var refreshResponse = await serviceClient.RefreshSessionAsync(refreshRequest);
+        return contractAdapter.ToRefreshSessionApiResponse(refreshResponse);
     }
 }

src/Thalos.Bff.Application/Security/IPermissionGuard.cs

@@ -1,3 +1,5 @@
+using Thalos.Service.Identity.Abstractions.Contracts;
+
 namespace Thalos.Bff.Application.Security;
 
 /// <summary>
@@ -8,7 +10,7 @@ public interface IPermissionGuard
     /// <summary>
     /// Evaluates whether a permission is satisfied for the current request context.
     /// </summary>
-    /// <param name="permissionCode">Permission code to evaluate.</param>
+    /// <param name="policyResponse">Policy evaluation response.</param>
     /// <returns>True when access is allowed.</returns>
-    bool CanAccess(string permissionCode);
+    bool CanAccess(EvaluateIdentityPolicyResponse policyResponse);
 }

src/Thalos.Bff.Application/Thalos.Bff.Application.csproj

@@ -6,5 +6,6 @@
   </PropertyGroup>
   <ItemGroup>
     <ProjectReference Include="..\Thalos.Bff.Contracts\Thalos.Bff.Contracts.csproj" />
+    <ProjectReference Include="..\..\..\thalos-service\src\Thalos.Service.Identity.Abstractions\Thalos.Service.Identity.Abstractions.csproj" />
   </ItemGroup>
 </Project>

src/Thalos.Bff.Contracts/Api/IssueTokenApiRequest.cs

@@ -5,4 +5,5 @@ namespace Thalos.Bff.Contracts.Api;
 /// </summary>
 /// <param name="SubjectId">Identity subject identifier.</param>
 /// <param name="TenantId">Tenant identifier.</param>
-public sealed record IssueTokenApiRequest(string SubjectId, string TenantId);
+/// <param name="CorrelationId">Request correlation identifier.</param>
+public sealed record IssueTokenApiRequest(string SubjectId, string TenantId, string CorrelationId = "");

src/Thalos.Bff.Contracts/Api/RefreshSessionApiRequest.cs

@@ -4,4 +4,5 @@ namespace Thalos.Bff.Contracts.Api;
 /// External API request for refresh token session flow.
 /// </summary>
 /// <param name="RefreshToken">Refresh token value.</param>
-public sealed record RefreshSessionApiRequest(string RefreshToken);
+/// <param name="CorrelationId">Request correlation identifier.</param>
+public sealed record RefreshSessionApiRequest(string RefreshToken, string CorrelationId = "");

src/Thalos.Bff.Contracts/Conventions/ThalosBffPackageContract.cs

@@ -0,0 +1,15 @@
+using Core.Blueprint.Common.Contracts;
+
+namespace Thalos.Bff.Contracts.Conventions;
+
+/// <summary>
+/// Defines package descriptor metadata for thalos bff edge contracts.
+/// </summary>
+public sealed class ThalosBffPackageContract : IBlueprintPackageContract
+{
+    /// <inheritdoc />
+    public BlueprintPackageDescriptor Descriptor { get; } = new(
+        "Thalos.Bff.Contracts",
+        PackageVersionPolicy.Minor,
+        ["Core.Blueprint.Common", "Thalos.Service.Identity.Abstractions"]);
+}

src/Thalos.Bff.Contracts/Thalos.Bff.Contracts.csproj

@@ -4,4 +4,7 @@
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
   </PropertyGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\blueprint-platform\src\Core.Blueprint.Common\Core.Blueprint.Common.csproj" />
+  </ItemGroup>
 </Project>

tests/Thalos.Bff.Application.UnitTests/ContractShapeTests.cs

@@ -0,0 +1,29 @@
+using Core.Blueprint.Common.Contracts;
+using Thalos.Bff.Contracts.Api;
+using Thalos.Bff.Contracts.Conventions;
+
+namespace Thalos.Bff.Application.UnitTests;
+
+public class ContractShapeTests
+{
+    [Fact]
+    public void IssueTokenApiRequest_WhenCreated_StoresCorrelationId()
+    {
+        var request = new IssueTokenApiRequest("user-1", "tenant-1", "corr-123");
+
+        Assert.Equal("user-1", request.SubjectId);
+        Assert.Equal("tenant-1", request.TenantId);
+        Assert.Equal("corr-123", request.CorrelationId);
+    }
+
+    [Fact]
+    public void ThalosBffPackageContract_WhenCreated_UsesBlueprintDescriptorContract()
+    {
+        IBlueprintPackageContract contract = new ThalosBffPackageContract();
+
+        Assert.Equal("Thalos.Bff.Contracts", contract.Descriptor.PackageId);
+        Assert.Equal(PackageVersionPolicy.Minor, contract.Descriptor.VersionPolicy);
+        Assert.Contains("Core.Blueprint.Common", contract.Descriptor.DependencyPackageIds);
+        Assert.Contains("Thalos.Service.Identity.Abstractions", contract.Descriptor.DependencyPackageIds);
+    }
+}

tests/Thalos.Bff.Application.UnitTests/IssueTokenHandlerTests.cs

@@ -1,7 +1,9 @@
+using Thalos.Bff.Application.Contracts;
 using Thalos.Bff.Application.Adapters;
 using Thalos.Bff.Application.Handlers;
 using Thalos.Bff.Application.Security;
 using Thalos.Bff.Contracts.Api;
+using Thalos.Service.Identity.Abstractions.Contracts;
 
 namespace Thalos.Bff.Application.UnitTests;
 
@@ -10,9 +12,12 @@ public class IssueTokenHandlerTests
     [Fact]
     public async Task HandleAsync_WhenPermissionAllowed_DelegatesToServiceClient()
     {
-        var handler = new IssueTokenHandler(new FakeThalosServiceClient(), new AllowPermissionGuard());
+        var handler = new IssueTokenHandler(
+            new FakeThalosServiceClient(),
+            new FakeIdentityEdgeContractAdapter(),
+            new AllowPermissionGuard());
 
-        var response = await handler.HandleAsync(new IssueTokenApiRequest("user-1", "tenant-1"));
+        var response = await handler.HandleAsync(new IssueTokenApiRequest("user-1", "tenant-1", "corr-123"));
 
         Assert.Equal("token-xyz", response.AccessToken);
         Assert.Equal(1800, response.ExpiresInSeconds);
@@ -20,19 +25,52 @@ public class IssueTokenHandlerTests
 
     private sealed class FakeThalosServiceClient : IThalosServiceClient
     {
-        public Task<IssueTokenApiResponse> IssueTokenAsync(IssueTokenApiRequest request)
+        public Task<IssueIdentityTokenResponse> IssueTokenAsync(IssueIdentityTokenRequest request)
         {
-            return Task.FromResult(new IssueTokenApiResponse("token-xyz", 1800));
+            return Task.FromResult(new IssueIdentityTokenResponse("token-xyz", 1800));
         }
 
-        public Task<RefreshSessionApiResponse> RefreshSessionAsync(RefreshSessionApiRequest request)
+        public Task<EvaluateIdentityPolicyResponse> EvaluatePolicyAsync(EvaluateIdentityPolicyRequest request)
         {
-            return Task.FromResult(new RefreshSessionApiResponse("token-refreshed", 1800));
+            return Task.FromResult(new EvaluateIdentityPolicyResponse(request.SubjectId, request.PermissionCode, true));
+        }
+
+        public Task<RefreshIdentitySessionResponse> RefreshSessionAsync(RefreshIdentitySessionRequest request)
+        {
+            return Task.FromResult(new RefreshIdentitySessionResponse("token-refreshed", 1800));
+        }
+    }
+
+    private sealed class FakeIdentityEdgeContractAdapter : IIdentityEdgeContractAdapter
+    {
+        public EvaluateIdentityPolicyRequest ToPolicyRequest(IssueTokenApiRequest request, string permissionCode)
+        {
+            return new EvaluateIdentityPolicyRequest(request.SubjectId, request.TenantId, permissionCode);
+        }
+
+        public IssueIdentityTokenRequest ToIssueTokenRequest(IssueTokenApiRequest request)
+        {
+            return new IssueIdentityTokenRequest(request.SubjectId, request.TenantId);
+        }
+
+        public IssueTokenApiResponse ToIssueTokenApiResponse(IssueIdentityTokenResponse response)
+        {
+            return new IssueTokenApiResponse(response.Token, response.ExpiresInSeconds);
+        }
+
+        public RefreshIdentitySessionRequest ToRefreshSessionRequest(RefreshSessionApiRequest request)
+        {
+            return new RefreshIdentitySessionRequest(request.RefreshToken, request.CorrelationId);
+        }
+
+        public RefreshSessionApiResponse ToRefreshSessionApiResponse(RefreshIdentitySessionResponse response)
+        {
+            return new RefreshSessionApiResponse(response.Token, response.ExpiresInSeconds);
         }
     }
 
     private sealed class AllowPermissionGuard : IPermissionGuard
     {
-        public bool CanAccess(string permissionCode) => true;
+        public bool CanAccess(EvaluateIdentityPolicyResponse policyResponse) => policyResponse.IsAllowed;
     }
 }

tests/Thalos.Bff.Application.UnitTests/RefreshSessionHandlerTests.cs

@@ -0,0 +1,67 @@
+using Thalos.Bff.Application.Adapters;
+using Thalos.Bff.Application.Contracts;
+using Thalos.Bff.Application.Handlers;
+using Thalos.Bff.Contracts.Api;
+using Thalos.Service.Identity.Abstractions.Contracts;
+
+namespace Thalos.Bff.Application.UnitTests;
+
+public class RefreshSessionHandlerTests
+{
+    [Fact]
+    public async Task HandleAsync_WhenCalled_MapsThroughContractAdapter()
+    {
+        var handler = new RefreshSessionHandler(new FakeThalosServiceClient(), new FakeIdentityEdgeContractAdapter());
+
+        var response = await handler.HandleAsync(new RefreshSessionApiRequest("refresh-123", "corr-123"));
+
+        Assert.Equal("token-refreshed", response.AccessToken);
+        Assert.Equal(1800, response.ExpiresInSeconds);
+    }
+
+    private sealed class FakeThalosServiceClient : IThalosServiceClient
+    {
+        public Task<IssueIdentityTokenResponse> IssueTokenAsync(IssueIdentityTokenRequest request)
+        {
+            return Task.FromResult(new IssueIdentityTokenResponse("token-xyz", 1800));
+        }
+
+        public Task<EvaluateIdentityPolicyResponse> EvaluatePolicyAsync(EvaluateIdentityPolicyRequest request)
+        {
+            return Task.FromResult(new EvaluateIdentityPolicyResponse(request.SubjectId, request.PermissionCode, true));
+        }
+
+        public Task<RefreshIdentitySessionResponse> RefreshSessionAsync(RefreshIdentitySessionRequest request)
+        {
+            return Task.FromResult(new RefreshIdentitySessionResponse("token-refreshed", 1800));
+        }
+    }
+
+    private sealed class FakeIdentityEdgeContractAdapter : IIdentityEdgeContractAdapter
+    {
+        public EvaluateIdentityPolicyRequest ToPolicyRequest(IssueTokenApiRequest request, string permissionCode)
+        {
+            return new EvaluateIdentityPolicyRequest(request.SubjectId, request.TenantId, permissionCode);
+        }
+
+        public IssueIdentityTokenRequest ToIssueTokenRequest(IssueTokenApiRequest request)
+        {
+            return new IssueIdentityTokenRequest(request.SubjectId, request.TenantId);
+        }
+
+        public IssueTokenApiResponse ToIssueTokenApiResponse(IssueIdentityTokenResponse response)
+        {
+            return new IssueTokenApiResponse(response.Token, response.ExpiresInSeconds);
+        }
+
+        public RefreshIdentitySessionRequest ToRefreshSessionRequest(RefreshSessionApiRequest request)
+        {
+            return new RefreshIdentitySessionRequest(request.RefreshToken, request.CorrelationId);
+        }
+
+        public RefreshSessionApiResponse ToRefreshSessionApiResponse(RefreshIdentitySessionResponse response)
+        {
+            return new RefreshSessionApiResponse(response.Token, response.ExpiresInSeconds);
+        }
+    }
+}