Skip to main content

aac-invoke-auth

Authenticate /invoke pushes from your paired AAC sidecar.

When your agent runs behind an AAC sidecar, the sidecar verifies the cross-organizational authority chain and then POSTs the verified context to your agent's /invoke endpoint. The X-AAC-* headers on that push are your agent's entire view of the verified chain — so your agent must be able to tell a genuine sidecar push from a forged one. This package is that check: the sidecar HMAC-signs every push with a pairing secret shared with exactly one agent, and your agent verifies the signature before trusting anything.

The verification core is standard-library only (hmac, hashlib) and framework-agnostic. FastAPI mounting surfaces ship behind an extra:

pip install aac-invoke-auth[fastapi]

Quick start (FastAPI)

Generate the pairing secret once and share the file with your sidecar (the sidecar's sidecar.agent_invoke_auth.secret_file points at the same file; one secret per sidecar–agent pair, never shared across pairs):

openssl rand -hex 32 > /etc/aac/invoke-auth/invoke-auth.secret

Point your agent at it and mount the middleware:

export AAC_INVOKE_AUTH_SECRET_FILE=/etc/aac/invoke-auth/invoke-auth.secret
from fastapi import FastAPI
from aac_invoke_auth.fastapi import InvokeAuthGuard, InvokeAuthMiddleware

app = FastAPI()
app.add_middleware(
    InvokeAuthMiddleware,
    guard=InvokeAuthGuard.from_env(),
    protected_paths=("/invoke",),   # required, exact-match
)

That's the whole integration. Unsigned, tampered, replayed-stale, or wrong-secret pushes get a 401 with a generic detail and never reach your business logic; your handlers read request.json() unchanged.

Prefer route-scoped protection? The guard is also a plain FastAPI dependency:

from fastapi import Depends

guard = InvokeAuthGuard.from_env()

@app.post("/invoke", dependencies=[Depends(guard)])
async def invoke(request: Request): ...

Both surfaces call the same verifier — pick whichever fits your app.

Fail-fast startup, by design

InvokeAuthGuard.from_env() refuses to start when AAC_INVOKE_AUTH_SECRET_FILE is unset. A missing secret is a security downgrade; it should fail your deployment loudly at boot, not degrade into a log line nobody reads.

The single escape hatch — for extraordinary cases only, such as tenant test/pilot environments or debugging a suspected signing mismatch — is setting

export AAC_INVOKE_AUTH_ALLOW_UNAUTHENTICATED=true

explicitly (only the exact value true; a typo still fails the boot). An opted-out agent accepts every push unverified and logs a prominent warning at startup so the posture is visible in your logs. Never run this in production: the sidecar side has a symmetric dev_mode interlock, and both exist to make "unauthenticated" impossible to reach by accident.

Testing your agent

aac_invoke_auth.testing ships with the package:

from aac_invoke_auth.testing import signing_test_client

client = signing_test_client(app)          # wraps FastAPI's TestClient
response = client.post("/invoke", headers=aac_headers, json=payload)

post() calls to protected paths are signed exactly the way the paired sidecar signs them (secret read from AAC_INVOKE_AUTH_SECRET_FILE); everything else passes through. So your test suite exercises the real production verification path instead of opting out of it.

Wire format

AAC1-HMAC-SHA256 over method, path, timestamp, a SHA-256 body digest, and every X-AAC-* header (derived by rule, so header insertion/removal after signing fails verification). Freshness window ±30s. The canonicalization is frozen behind the algorithm name: a change that alters any signature is a wire-format break and ships under a new algorithm prefix, never as an update to AAC1-HMAC-SHA256.

Ports of this middleware for other stacks (Express, Spring, Go net/http) follow the same model; the core stays standard-library-only in every language precisely to keep those ports mechanical.

Metadata

Release files for aac-invoke-auth 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aac-invoke-auth 0.1.2
File Size Uploaded Provenance Actions
aac_invoke_auth-0.1.2.tar.gz 20.4 kB With provenance Details for aac_invoke_auth-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aac-invoke-auth 0.1.2
File Interpreter ABI Platform Actions
aac_invoke_auth-0.1.2-py3-none-any.whl Python 3 none any Details for aac_invoke_auth-0.1.2-py3-none-any.whl

Total release size: 41.1 kB

Release files / aac_invoke_auth-0.1.2.tar.gz

Download URL aac_invoke_auth-0.1.2.tar.gz
Size 20.4 kB
Tags Source
SHA-256 checksum
How to use checksums
3cd8fb057c007b7de90a9c703329dc4065086d3a247ddb6db187a142590a45a3
BLAKE2b-256 checksum
How to use checksums
e551ad70ddb6962649f16fb8a11deacd85648bea068ec495ddb8134e5e6dff8d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.

Transparency log

Release files / aac_invoke_auth-0.1.2-py3-none-any.whl

Download URL aac_invoke_auth-0.1.2-py3-none-any.whl
Size 20.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1c11b54f129b95c653a73b62ea971fcfbaded471d356dccf41bfa793d171d1ad
BLAKE2b-256 checksum
How to use checksums
944c1b8f3a3dd8234b78724151534b8f3d3bb9bc33b9b42e2a83dc8cfddfaa67
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.

Transparency log

Security for aac-invoke-auth 0.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aac_invoke_auth-0.1.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page