Metadata-Version: 2.4
Name: aw-appservice-custom-ai-middleware-extension
Version: 0.3.7
Summary: Building blocks for agents hosted behind an EasyAuth-fronted App Service.
Requires-Python: >=3.11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Provides-Extra: deferred
Provides-Extra: dev
Provides-Extra: functions
Provides-Extra: hosted-skills
Provides-Extra: sar
Provides-Extra: teams
Requires-Dist: azure-functions (>=1.21) ; extra == "functions"
Requires-Dist: azure-identity (>=1.15) ; extra == "deferred"
Requires-Dist: azure-identity (>=1.15) ; extra == "teams"
Requires-Dist: azure-storage-blob (>=12.19) ; extra == "deferred"
Requires-Dist: azurefunctions-agents-runtime (>=0.1.0b16,<0.1.0b17) ; extra == "hosted-skills"
Requires-Dist: azurefunctions-agents-runtime (>=0.1.0b16,<0.1.0b17) ; extra == "sar"
Requires-Dist: pytest (>=8.0) ; extra == "dev"
Requires-Dist: pytest-asyncio (>=0.23) ; extra == "dev"
Requires-Dist: starlette (>=0.37) ; extra == "dev"
Description-Content-Type: text/markdown

# App Service Custom AI Middleware

Python middleware and tools for AI agents hosted behind Azure App Service
Authentication and App Service Hooks.

## Install

```bash
pip install aw-appservice-custom-ai-middleware-extension
```

The distribution name is `aw-appservice-custom-ai-middleware-extension`. The
stable Python import remains:

```python
import app_service_extensions as ase
```

For Azure Functions:

```bash
pip install "aw-appservice-custom-ai-middleware-extension[functions]"
```

For Azure Functions hosted skills:

```bash
pip install "aw-appservice-custom-ai-middleware-extension[hosted-skills]"
```

The hosted-skills integration patches runtime seams that are not yet public API.
Its dependency range is intentionally narrow and is expanded only after the
integration suite passes against a new runtime release.

## Azure Functions

Configure the middleware before creating the hosted-skills app, then attach it
to the generated Function app:

```python
import app_service_extensions as ase
from azure_functions_agents import create_function_app

ase.configure()
app = create_function_app()
ase.configure(app)
```

Or use the convenience factory, which runs that same sequence internally:

```python
import app_service_extensions as ase

app = ase.create_function_app()
```

Both initialization styles remain supported. Choose one style for an app rather
than combining them.

The package preserves the opaque `X-MS-Hook-Invocation` recursion chain for
same-site callbacks. Caller identity forwarding requires the explicit opt-in
described below. Neither credential is sent to third-party MCP servers.

`ase.current_request().request.origin` exposes the proxy-aware, client-facing
site origin supplied by App Service Hooks for callbacks to the originating site.

## Application identity and acting as the user

By default, the SDK ignores `X-MS-CONTEXT-TOKEN` and leaves outbound authentication
to the application's configured credentials. Authenticated MCP connections retain
the Hosted Skills runtime's managed-identity default; an anonymous MCP connection
remains anonymous. The SDK does not infer or inject `auth.type: "obo"`.

To explicitly opt into acting as the user:

```python
app = ase.create_function_app(act_as_user=True)
```

For the two-step initialization style, set the policy before creating the runtime:

```python
ase.configure(act_as_user=True)
app = create_function_app()
ase.configure(app)
```

This is an SDK-wide caller-context policy, not an MCP server authentication type
or an OAuth on-behalf-of token exchange. Keep the MCP connection's transport
authentication in `mcp.json`; setting its `auth.type` does not opt into SDK
user-context forwarding.

Acting as the user requires a context token supplied by the web app's middleware.
The option does not mint a token or derive one from a browser cookie. If it is
enabled but no context token arrives, same-site user-context MCP tools are withheld
rather than silently falling back to the application's permissions. With a caller,
application-identity MCP tools are withheld instead. Context tokens are forwarded
only to the originating web app, never to an external MCP server.

`ase.configure()` and `ase.configure(app)` preserve a previous `act_as_user` choice
when the option is omitted. Pass `act_as_user=False` to explicitly return to
application mode. The convenience factory defaults to `False`.

## Publish to PyPI

Publishing is manual because this repository does not have an Actions runner.
PyPI does not allow replacing an existing release, so first update the version
in both `pyproject.toml` and `src\app_service_extensions\__init__.py`.

Save the token once from the repository root in PowerShell:

```powershell
.\scripts\publish-pypi.ps1 -SaveToken
```

This prompts for the token, stores it outside the repository at
`$env:LOCALAPPDATA\AppExtensionsLibrary\pypi-token.dpapi`, encrypted by Windows
DPAPI for the current user and machine, and exits without publishing.

To publish, run:

```powershell
.\scripts\publish-pypi.ps1
```

The publish command verifies that both version declarations match, installs
the build tools, runs the tests, rebuilds a clean `dist` directory, validates
the artifacts, and uploads them using the saved token.

Remove the saved token with:

```powershell
.\scripts\publish-pypi.ps1 -ForgetToken
```

The script exposes the decrypted value only to the `twine` child process and
restores the process environment afterward. Do not save the plaintext token in
the script, commit it, or include it in an issue, pull request, or chat.

After the upload succeeds, tag the exact commit that produced the package:

```powershell
$version = python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])"
git tag "v$version"
git push origin "v$version"
```

