# ToolAuthorizationContract

> Tracon documentation. Tracon is a .NET package family that adds a control
> plane on Microsoft Agent Framework, published as NuGet packages that run
> inside your own ASP.NET Core application.
>
> Page: https://tracon.dev/api/tracon.testing.contracts.tools.toolauthorizationcontract/
> Summary: ToolAuthorizationContract: Behavior tests for the consumer's own IToolAuthorizationHandler.

<div class="api-provenance">Namespace Tracon.Testing.Contracts.Tools · Assembly <code>Tracon.Testing.Contracts.Xunit.dll</code></div>

Behavior tests for the consumer's own [IToolAuthorizationHandler](/api/tracon.itoolauthorizationhandler/).

```csharp
public abstract class ToolAuthorizationContract : IAsyncLifetime, IAsyncDisposable
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← <a href="/api/tracon.testing.contracts.tools.toolauthorizationcontract/">ToolAuthorizationContract</a></dd><dt>Implements</dt><dd>IAsyncLifetime, <a href="https://learn.microsoft.com/dotnet/api/system.iasyncdisposable">IAsyncDisposable</a></dd><dt>Inherited Members</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object.gettype">object.GetType()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.memberwiseclone">object.MemberwiseClone()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.tostring">object.ToString()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object)">object.Equals(object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object)">object.Equals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.referenceequals">object.ReferenceEquals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.gethashcode">object.GetHashCode()</a></dd></dl>

## Remarks

Unlike argument validation, a call's authorization outcome has no
schema-derived ground truth — whether a given tenant, tool, or permission
combination is allowed is entirely the consumer's own business policy.
This contract asks for that ground truth directly: [ToolAuthorizationContract.DeniedRequest](/api/tracon.testing.contracts.tools.toolauthorizationcontract/#Tracon_Testing_Contracts_Tools_ToolAuthorizationContract_DeniedRequest)
is a call the derived class declares its own [ToolAuthorizationContract.Handler](/api/tracon.testing.contracts.tools.toolauthorizationcontract/#Tracon_Testing_Contracts_Tools_ToolAuthorizationContract_Handler) denies,
the same way `CustomToolContract.ExpectedResultText` supplies the
ground truth for a custom tool's own result.

[IToolAuthorizationHandler](/api/tracon.itoolauthorizationhandler/) promises fail-closed behavior: if
the handler throws, the call must still end up denied. Tracon tests
its own fail-closed wrapper against synthetic handlers; this contract tests whether the **consumer's**
handler actually reaches a denial for [ToolAuthorizationContract.DeniedRequest](/api/tracon.testing.contracts.tools.toolauthorizationcontract/#Tracon_Testing_Contracts_Tools_ToolAuthorizationContract_DeniedRequest) — whether
it returns [ToolAuthorizationResult.Deny](/api/tracon.toolauthorizationresult/#Tracon_ToolAuthorizationResult_Deny_System_String_) directly, or
throws and lets the fail-closed wrapper deny it.

## Constructors

### <a id="Tracon_Testing_Contracts_Tools_ToolAuthorizationContract__ctor"></a> ToolAuthorizationContract\(\)

```csharp
protected ToolAuthorizationContract()
```

## Properties

### <a id="Tracon_Testing_Contracts_Tools_ToolAuthorizationContract_AllowedRequest"></a> AllowedRequest

A call this handler's own policy allows — the counterpart to
[ToolAuthorizationContract.DeniedRequest](/api/tracon.testing.contracts.tools.toolauthorizationcontract/#Tracon_Testing_Contracts_Tools_ToolAuthorizationContract_DeniedRequest). Needed so a handler that ignores its
input and returns the same decision for every call (allow-all or
deny-all) cannot pass this contract by accident.

```csharp
protected abstract ToolAuthorizationRequest AllowedRequest { get; }
```

#### Property Value

 [ToolAuthorizationRequest](/api/tracon.toolauthorizationrequest/)

### <a id="Tracon_Testing_Contracts_Tools_ToolAuthorizationContract_DeniedRequest"></a> DeniedRequest

A call this handler's own policy denies — for example, a caller
missing the tool's required permission. There is no schema-driven way
to derive an "invalid" authorization request the way
[ToolArgumentValidationContract](/api/tracon.testing.contracts.tools.toolargumentvalidationcontract/) derives one from JSON
Schema; authorization is the consumer's own business policy, so the
consumer states it.

```csharp
protected abstract ToolAuthorizationRequest DeniedRequest { get; }
```

#### Property Value

 [ToolAuthorizationRequest](/api/tracon.toolauthorizationrequest/)

### <a id="Tracon_Testing_Contracts_Tools_ToolAuthorizationContract_Handler"></a> Handler

The authorization policy under test.

```csharp
protected IToolAuthorizationHandler Handler { get; }
```

#### Property Value

 [IToolAuthorizationHandler](/api/tracon.itoolauthorizationhandler/)

## Methods

### <a id="Tracon_Testing_Contracts_Tools_ToolAuthorizationContract_CreateHandlerAsync"></a> CreateHandlerAsync\(\)

Creates the handler under test.

```csharp
protected abstract ValueTask<IToolAuthorizationHandler> CreateHandlerAsync()
```

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[IToolAuthorizationHandler](/api/tracon.itoolauthorizationhandler/)\>

### <a id="Tracon_Testing_Contracts_Tools_ToolAuthorizationContract_Denied_call_never_runs_the_tool_body"></a> Denied\_call\_never\_runs\_the\_tool\_body\(\)

```csharp
[Fact]
public Task Denied_call_never_runs_the_tool_body()
```

#### Returns

 [Task](https://learn.microsoft.com/dotnet/api/system.threading.tasks.task)

### <a id="Tracon_Testing_Contracts_Tools_ToolAuthorizationContract_DisposeAsync"></a> DisposeAsync\(\)

```csharp
public ValueTask DisposeAsync()
```

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask)

### <a id="Tracon_Testing_Contracts_Tools_ToolAuthorizationContract_Handler_receives_the_calling_tenant"></a> Handler\_receives\_the\_calling\_tenant\(\)

```csharp
[Fact]
public Task Handler_receives_the_calling_tenant()
```

#### Returns

 [Task](https://learn.microsoft.com/dotnet/api/system.threading.tasks.task)

### <a id="Tracon_Testing_Contracts_Tools_ToolAuthorizationContract_InitializeAsync"></a> InitializeAsync\(\)

Called immediately after the class has been created, before it is used.

```csharp
public ValueTask InitializeAsync()
```

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask)

### <a id="Tracon_Testing_Contracts_Tools_ToolAuthorizationContract_Throwing_handler_denies_the_call"></a> Throwing\_handler\_denies\_the\_call\(\)

```csharp
[Fact]
public Task Throwing_handler_denies_the_call()
```

#### Returns

 [Task](https://learn.microsoft.com/dotnet/api/system.threading.tasks.task)