aidr-agent 0.1.0__tar.gz

aidr_agent-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+node_modules/
+# Wrangler / miniflare local state
+.wrangler/
+.env
+# Key material must never reach the repository, even in development.
+*.pem
+*.key
+*.jwk
+secrets/
+
+# Terraform: local state, provider cache, and variable files (which name real accounts).
+.terraform/
+*.tfstate
+*.tfstate.*
+terraform.tfvars
+.terraform.lock.hcl.bak
+
+# Local rehearsal of the staging stack (deploy/staging/rehearsal/rehearse.py): generated keys.
+.rehearsal/
+
+# Evoliv Core Client (client/desktop): Rust build output, Tauri-generated schemas, the web build.
+client/desktop/target/
+client/desktop/src-tauri/gen/
+client/desktop/dist/
+
+# Python packages for PyPI (scripts/build_python_packages.py): staging and output.
+/build/
+/dist/
+
+# The Worker/origin shared secret (edge/cloudflare-worker README, demo runbook).
+edge-secret

aidr_agent-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

aidr_agent-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.5
+Name: aidr-agent
+Version: 0.1.0
+Summary: Give an AI agent a verifiable AIDR identity: enroll from code, sign requests, LangChain tools.
+Project-URL: Homepage, https://aidr.evolivcore.com
+Project-URL: Documentation, https://evolivcore.com/resources
+Author: Evoliv Core
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: ai-agents,aiaf,aidr,identity,langchain,rfc9421
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: aidr-crypto<0.2,>=0.1
+Requires-Dist: httpx>=0.27
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=1.0; extra == 'langchain'
+Provides-Extra: langchain-community
+Requires-Dist: langchain-community>=0.4; extra == 'langchain-community'
+Requires-Dist: requests>=2.31; extra == 'langchain-community'
+Provides-Extra: requests
+Requires-Dist: requests>=2.31; extra == 'requests'
+Description-Content-Type: text/markdown
+
+# aidr-agent (Python)
+
+Give an AI agent a verifiable AIDR identity from its first run. Apache-2.0.
+
+```
+pip install "aidr-agent[requests]"          # add ,langchain for the LangChain tools
+```
+
+```python
+from aidr_agent import Agent
+
+agent = Agent.load_or_enroll("research-01", audiences=["https://shop.example"])
+agent.session().get("https://shop.example/products")   # signed; other sites get anonymous requests
+```
+
+1. An organisation admin issues an **enrollment token** in the console (Organisations → Enrollment tokens).
+2. Put it in `AIDR_ENROLLMENT_TOKEN` where the agent runs. The first run generates the key **on that
+   machine**, enrolls, proves the key and saves the identity; later runs load it. The token is then
+   no longer needed.
+3. Requests to the agent's allowed sites carry an RFC 9421 signature and a short-lived credential.
+   Anything else goes out unsigned, or is refused with `on_unlisted="refuse"`. Plain http is never
+   signed, except to localhost.
+
+Python 3.10+. Extras: `requests` (for `agent.session()` / `agent.auth()`), `langchain` (the tools, on
+`langchain-core`), `langchain-community` (the `RequestsToolkit` wrapper). It installs `aidr-crypto`
+and `aidr-core`, the same signing code the registry runs.
+
+## Where the identity is kept
+
+| Store | Use it for | How |
+| --- | --- | --- |
+| `FileKeyStore` (default) | laptops, VMs, persistent volumes | `~/.aidr/agents/<name>/identity.json`, mode 0600 (`AIDR_AGENT_HOME` moves it) |
+| `EnvKeyStore` | containers, serverless | `python -m aidr_agent enroll --name <name> --print-identity`, then store the line as the secret `AIDR_AGENT_IDENTITY` |
+
+A container that starts with an empty disk would enroll a new agent on every start and spend a use of
+the token each time: use `AIDR_AGENT_IDENTITY` there.
+
+## HTTP clients
+
+- `agent.session()`: a `requests.Session`. `agent.auth()`: for `requests.get(url, auth=…)`.
+- `agent.httpx_auth()`: for `httpx.Client` and `httpx.AsyncClient`.
+- `agent.sign_headers(method, url)`: the headers themselves, for any other client.
+
+## LangChain
+
+```python
+from aidr_agent.langchain import aidr_http_tools
+
+tools = aidr_http_tools(agent)      # http_get, http_post: signed, and limited to the agent's sites
+```
+
+The tools reach only the origins they are given (by default the agent's allowed audiences). An LLM
+choosing URLs is how a prompt-injected agent would present its identity somewhere it should not, or
+reach internal addresses. For code still on `langchain-community`'s `RequestsToolkit`,
+`signed_requests_wrapper(agent)` is a drop-in `TextRequestsWrapper` that signs, sync and async.
+`langchain-community` is being sunset, so new code should use the tools.
+
+## Command line
+
+```
+aidr-agent enroll --name research-01 --audience https://shop.example
+aidr-agent whoami --name research-01
+```
+
+(`python -m aidr_agent …` is the same command.)
+
+The token is read only from `AIDR_ENROLLMENT_TOKEN`, never from the command line.

aidr_agent-0.1.0/README.md

@@ -0,0 +1,67 @@
+# aidr-agent (Python)
+
+Give an AI agent a verifiable AIDR identity from its first run. Apache-2.0.
+
+```
+pip install "aidr-agent[requests]"          # add ,langchain for the LangChain tools
+```
+
+```python
+from aidr_agent import Agent
+
+agent = Agent.load_or_enroll("research-01", audiences=["https://shop.example"])
+agent.session().get("https://shop.example/products")   # signed; other sites get anonymous requests
+```
+
+1. An organisation admin issues an **enrollment token** in the console (Organisations → Enrollment tokens).
+2. Put it in `AIDR_ENROLLMENT_TOKEN` where the agent runs. The first run generates the key **on that
+   machine**, enrolls, proves the key and saves the identity; later runs load it. The token is then
+   no longer needed.
+3. Requests to the agent's allowed sites carry an RFC 9421 signature and a short-lived credential.
+   Anything else goes out unsigned, or is refused with `on_unlisted="refuse"`. Plain http is never
+   signed, except to localhost.
+
+Python 3.10+. Extras: `requests` (for `agent.session()` / `agent.auth()`), `langchain` (the tools, on
+`langchain-core`), `langchain-community` (the `RequestsToolkit` wrapper). It installs `aidr-crypto`
+and `aidr-core`, the same signing code the registry runs.
+
+## Where the identity is kept
+
+| Store | Use it for | How |
+| --- | --- | --- |
+| `FileKeyStore` (default) | laptops, VMs, persistent volumes | `~/.aidr/agents/<name>/identity.json`, mode 0600 (`AIDR_AGENT_HOME` moves it) |
+| `EnvKeyStore` | containers, serverless | `python -m aidr_agent enroll --name <name> --print-identity`, then store the line as the secret `AIDR_AGENT_IDENTITY` |
+
+A container that starts with an empty disk would enroll a new agent on every start and spend a use of
+the token each time: use `AIDR_AGENT_IDENTITY` there.
+
+## HTTP clients
+
+- `agent.session()`: a `requests.Session`. `agent.auth()`: for `requests.get(url, auth=…)`.
+- `agent.httpx_auth()`: for `httpx.Client` and `httpx.AsyncClient`.
+- `agent.sign_headers(method, url)`: the headers themselves, for any other client.
+
+## LangChain
+
+```python
+from aidr_agent.langchain import aidr_http_tools
+
+tools = aidr_http_tools(agent)      # http_get, http_post: signed, and limited to the agent's sites
+```
+
+The tools reach only the origins they are given (by default the agent's allowed audiences). An LLM
+choosing URLs is how a prompt-injected agent would present its identity somewhere it should not, or
+reach internal addresses. For code still on `langchain-community`'s `RequestsToolkit`,
+`signed_requests_wrapper(agent)` is a drop-in `TextRequestsWrapper` that signs, sync and async.
+`langchain-community` is being sunset, so new code should use the tools.
+
+## Command line
+
+```
+aidr-agent enroll --name research-01 --audience https://shop.example
+aidr-agent whoami --name research-01
+```
+
+(`python -m aidr_agent …` is the same command.)
+
+The token is read only from `AIDR_ENROLLMENT_TOKEN`, never from the command line.

aidr_agent-0.1.0/aidr_agent/README.md

@@ -0,0 +1,67 @@
+# aidr-agent (Python)
+
+Give an AI agent a verifiable AIDR identity from its first run. Apache-2.0.
+
+```
+pip install "aidr-agent[requests]"          # add ,langchain for the LangChain tools
+```
+
+```python
+from aidr_agent import Agent
+
+agent = Agent.load_or_enroll("research-01", audiences=["https://shop.example"])
+agent.session().get("https://shop.example/products")   # signed; other sites get anonymous requests
+```
+
+1. An organisation admin issues an **enrollment token** in the console (Organisations → Enrollment tokens).
+2. Put it in `AIDR_ENROLLMENT_TOKEN` where the agent runs. The first run generates the key **on that
+   machine**, enrolls, proves the key and saves the identity; later runs load it. The token is then
+   no longer needed.
+3. Requests to the agent's allowed sites carry an RFC 9421 signature and a short-lived credential.
+   Anything else goes out unsigned, or is refused with `on_unlisted="refuse"`. Plain http is never
+   signed, except to localhost.
+
+Python 3.10+. Extras: `requests` (for `agent.session()` / `agent.auth()`), `langchain` (the tools, on
+`langchain-core`), `langchain-community` (the `RequestsToolkit` wrapper). It installs `aidr-crypto`
+and `aidr-core`, the same signing code the registry runs.
+
+## Where the identity is kept
+
+| Store | Use it for | How |
+| --- | --- | --- |
+| `FileKeyStore` (default) | laptops, VMs, persistent volumes | `~/.aidr/agents/<name>/identity.json`, mode 0600 (`AIDR_AGENT_HOME` moves it) |
+| `EnvKeyStore` | containers, serverless | `python -m aidr_agent enroll --name <name> --print-identity`, then store the line as the secret `AIDR_AGENT_IDENTITY` |
+
+A container that starts with an empty disk would enroll a new agent on every start and spend a use of
+the token each time: use `AIDR_AGENT_IDENTITY` there.
+
+## HTTP clients
+
+- `agent.session()`: a `requests.Session`. `agent.auth()`: for `requests.get(url, auth=…)`.
+- `agent.httpx_auth()`: for `httpx.Client` and `httpx.AsyncClient`.
+- `agent.sign_headers(method, url)`: the headers themselves, for any other client.
+
+## LangChain
+
+```python
+from aidr_agent.langchain import aidr_http_tools
+
+tools = aidr_http_tools(agent)      # http_get, http_post: signed, and limited to the agent's sites
+```
+
+The tools reach only the origins they are given (by default the agent's allowed audiences). An LLM
+choosing URLs is how a prompt-injected agent would present its identity somewhere it should not, or
+reach internal addresses. For code still on `langchain-community`'s `RequestsToolkit`,
+`signed_requests_wrapper(agent)` is a drop-in `TextRequestsWrapper` that signs, sync and async.
+`langchain-community` is being sunset, so new code should use the tools.
+
+## Command line
+
+```
+aidr-agent enroll --name research-01 --audience https://shop.example
+aidr-agent whoami --name research-01
+```
+
+(`python -m aidr_agent …` is the same command.)
+
+The token is read only from `AIDR_ENROLLMENT_TOKEN`, never from the command line.

aidr_agent-0.1.0/aidr_agent/__init__.py

@@ -0,0 +1,22 @@
+"""AIDR agent SDK — give an AI agent a verifiable identity from its first run.
+
+    from aidr_agent import Agent
+
+    agent = Agent.load_or_enroll("research-01", audiences=["https://shop.example"])
+    session = agent.session()                     # requests; or agent.httpx_auth() for httpx
+    session.get("https://shop.example/products")  # signed (RFC 9421) with a short-lived credential
+
+The first run enrolls with the token in AIDR_ENROLLMENT_TOKEN (issued in the AIDR console) and
+keeps the new identity; later runs load it. The private key is generated here and never sent.
+LangChain: ``aidr_agent.langchain``. Command line: ``python -m aidr_agent --help``.
+"""
+
+from .agent import Agent, NotAllowed
+from .identity import AgentIdentity, IdentityError
+from .keystore import EnvKeyStore, FileKeyStore, KeyStore
+from .registry import RegistryError
+
+__version__ = "0.1.0"
+
+__all__ = ["Agent", "AgentIdentity", "EnvKeyStore", "FileKeyStore", "IdentityError", "KeyStore",
+           "NotAllowed", "RegistryError"]

aidr_agent-0.1.0/aidr_agent/__main__.py

@@ -0,0 +1,76 @@
+"""``python -m aidr_agent`` — enroll an agent, or show who it is.
+
+    python -m aidr_agent enroll --name research-01 [--audience https://shop.example] [--print-identity]
+    python -m aidr_agent whoami --name research-01
+
+``enroll`` reads the token from AIDR_ENROLLMENT_TOKEN (never from the command line, where it would
+land in shell history and process listings). ``--print-identity`` prints the whole identity,
+private key included, as one line for AIDR_AGENT_IDENTITY in a container's secret store — and
+saves nothing to disk.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from .agent import REGISTRY_ENV, TOKEN_ENV
+from .identity import DEFAULT_REGISTRY, IdentityError, normalize_origin
+from .keystore import IDENTITY_ENV, EnvKeyStore, FileKeyStore
+from .registry import RegistryError, enroll, token_id
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m aidr_agent", description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    commands = parser.add_subparsers(dest="command", required=True)
+    enroll_cmd = commands.add_parser("enroll", help="enroll a new agent with an enrollment token")
+    enroll_cmd.add_argument("--name", required=True)
+    enroll_cmd.add_argument("--audience", action="append", default=None,
+                            help="an origin the agent may identify to (repeatable)")
+    enroll_cmd.add_argument("--description", default="")
+    enroll_cmd.add_argument("--registry", default=os.environ.get(REGISTRY_ENV) or DEFAULT_REGISTRY)
+    enroll_cmd.add_argument("--print-identity", action="store_true",
+                            help=f"print the identity for {IDENTITY_ENV} instead of saving it")
+    whoami = commands.add_parser("whoami", help="show the saved identity (never the key)")
+    whoami.add_argument("--name", required=True)
+    args = parser.parse_args(argv)
+
+    try:
+        if args.command == "whoami":
+            identity = EnvKeyStore().load(args.name) or FileKeyStore().load(args.name)
+            if identity is None:
+                print(f"agent {args.name!r} is not enrolled here", file=sys.stderr)
+                return 1
+            print(f"aid:       {identity.aid}\nregistry:  {identity.registry}\n"
+                  f"audiences: {', '.join(identity.audiences) or '(unrestricted)'}")
+            return 0
+
+        token = os.environ.get(TOKEN_ENV)
+        if not token:
+            print(f"set {TOKEN_ENV} to the token from the AIDR console", file=sys.stderr)
+            return 2
+        store = FileKeyStore()
+        if not args.print_identity and store.load(args.name) is not None:
+            print(f"agent {args.name!r} is already enrolled here ({store.path(args.name)})", file=sys.stderr)
+            return 1
+        audiences = [normalize_origin(a) for a in args.audience] if args.audience else None
+        print(f"enrolling {args.name} at {args.registry} with token {token_id(token)}…", file=sys.stderr)
+        identity = enroll(token, name=args.name, registry=args.registry, audiences=audiences,
+                          description=args.description)
+        if args.print_identity:
+            print(f"enrolled {identity.aid}. Store this line as the secret {IDENTITY_ENV} "
+                  "(it contains the private key):", file=sys.stderr)
+            print(identity.to_portable())
+        else:
+            store.save(identity)
+            print(f"enrolled {identity.aid}; saved to {store.path(args.name)}", file=sys.stderr)
+        return 0
+    except (RegistryError, IdentityError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

aidr_agent-0.1.0/aidr_agent/agent.py

@@ -0,0 +1,156 @@
+"""The agent: load its identity or enroll once, then sign the requests it is allowed to sign."""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Iterable, Mapping
+from typing import Any, Literal
+
+import httpx
+
+from aidr_crypto.signatures import CREDENTIAL_HEADER, sign_request
+
+from .identity import DEFAULT_REGISTRY, AgentIdentity, normalize_origin
+from .keystore import EnvKeyStore, FileKeyStore, KeyStore
+from .registry import CredentialCache, enroll, token_id
+
+logger = logging.getLogger("aidr_agent")
+
+TOKEN_ENV = "AIDR_ENROLLMENT_TOKEN"  # noqa: S105 - a variable name, not a secret
+REGISTRY_ENV = "AIDR_REGISTRY_URL"
+
+OnUnlisted = Literal["unsigned", "refuse"]
+
+
+class NotAllowed(Exception):
+    """The agent was asked to identify itself to a site it is not allowed to (on_unlisted="refuse")."""
+
+
+class Agent:
+    """An enrolled agent. Build one with :meth:`load_or_enroll`.
+
+    ``sign_for`` — the origins this process presents the identity to — defaults to the
+    audiences the registry allows. An agent without audiences is unrestricted at the registry;
+    this SDK then signs for any https origin. Requests elsewhere go out unsigned (anonymous), or
+    are refused with ``on_unlisted="refuse"``. Plain http is never signed except to localhost: a
+    credential sent in clear text is a credential given away.
+    """
+
+    def __init__(self, identity: AgentIdentity, *, sign_for: Iterable[str] | None = None,
+                 on_unlisted: OnUnlisted = "unsigned", registry_http: httpx.Client | None = None,
+                 registry_async_http: httpx.AsyncClient | None = None) -> None:
+        self.identity = identity
+        allowed = identity.audiences if sign_for is None else [normalize_origin(o) for o in sign_for]
+        if identity.audiences and not set(allowed) <= set(identity.audiences):
+            raise NotAllowed(f"the registry issues credentials only for {identity.audiences}")
+        self.sign_for: frozenset[str] = frozenset(allowed)
+        self.on_unlisted = on_unlisted
+        #: ``registry_http`` / ``registry_async_http``: clients for the registry only (a proxy,
+        #: a private CA). Never the clients the agent's own requests go through.
+        self.credentials = CredentialCache(identity, http=registry_http,
+                                           async_http=registry_async_http)
+
+    # -- construction ----------------------------------------------------------------------------
+
+    @classmethod
+    def load_or_enroll(cls, name: str, *, audiences: list[str] | None = None,
+                       token: str | None = None, registry: str | None = None,
+                       key_store: KeyStore | None = None, description: str = "",
+                       on_unlisted: OnUnlisted = "unsigned",
+                       registry_http: httpx.Client | None = None,
+                       registry_async_http: httpx.AsyncClient | None = None) -> Agent:
+        """The identity saved for ``name``, or — first run only — enroll with the token.
+
+        The token comes from ``token`` or AIDR_ENROLLMENT_TOKEN and is used once; after that the
+        saved identity is enough, and the token can be removed from the environment.
+        """
+        stores: list[KeyStore] = [key_store] if key_store else [EnvKeyStore(), FileKeyStore()]
+        for store in stores:
+            identity = store.load(name)
+            if identity is not None:
+                if token or os.environ.get(TOKEN_ENV):
+                    logger.info("agent %s is already enrolled (%s); %s is no longer needed",
+                                name, identity.aid, TOKEN_ENV)
+                return cls(identity, on_unlisted=on_unlisted, registry_http=registry_http,
+                           registry_async_http=registry_async_http)
+
+        presented = token or os.environ.get(TOKEN_ENV)
+        if not presented:
+            raise LookupError(f"agent {name!r} is not enrolled here and no enrollment token was given "
+                              f"(set {TOKEN_ENV}, or pass token=)")
+        target = registry or os.environ.get(REGISTRY_ENV) or DEFAULT_REGISTRY
+        writable = next((s for s in stores if not isinstance(s, EnvKeyStore)), None)
+        if writable is None:
+            raise LookupError("no writable key store to keep the new identity in")
+        logger.info("enrolling agent %s at %s with token %s", name, target, token_id(presented))
+        identity = enroll(presented, name=name, registry=target,
+                          audiences=[normalize_origin(a) for a in audiences] if audiences else None,
+                          description=description, http=registry_http)
+        writable.save(identity)
+        logger.info("enrolled %s", identity.aid)
+        return cls(identity, on_unlisted=on_unlisted, registry_http=registry_http,
+                   registry_async_http=registry_async_http)
+
+    @property
+    def aid(self) -> str:
+        return self.identity.aid
+
+    # -- the signing decision ------------------------------------------------------------------
+
+    def should_sign(self, url: str) -> bool:
+        origin = normalize_origin(url)
+        scheme = origin.split("://", 1)[0]
+        host = origin.split("://", 1)[1].split(":")[0]
+        if scheme != "https" and not (scheme == "http" and host in ("localhost", "127.0.0.1")):
+            return False
+        return origin in self.sign_for if self.sign_for else True
+
+    def _unlisted(self, url: str) -> None:
+        if self.on_unlisted == "refuse":
+            raise NotAllowed(f"{normalize_origin(url)} is not an origin this agent identifies to")
+
+    def sign_headers(self, method: str, url: str, headers: Mapping[str, str] | None = None,
+                     *, http: httpx.Client | None = None) -> dict[str, str]:
+        """The headers that identify this agent on one request, or ``{}`` when it should not."""
+        if not self.should_sign(url):
+            self._unlisted(url)
+            return {}
+        credential = self.credentials.get(normalize_origin(url), http)
+        signed = sign_request(method=method, url=url, headers=dict(headers or {}),
+                              private_key=self.identity.private_key, keyid=self.identity.aid)
+        signed[CREDENTIAL_HEADER] = credential
+        return signed
+
+    async def asign_headers(self, method: str, url: str, headers: Mapping[str, str] | None = None,
+                            *, http: httpx.AsyncClient | None = None) -> dict[str, str]:
+        if not self.should_sign(url):
+            self._unlisted(url)
+            return {}
+        credential = await self.credentials.aget(normalize_origin(url), http)
+        signed = sign_request(method=method, url=url, headers=dict(headers or {}),
+                              private_key=self.identity.private_key, keyid=self.identity.aid)
+        signed[CREDENTIAL_HEADER] = credential
+        return signed
+
+    # -- adapters -----------------------------------------------------------------------------
+
+    def auth(self) -> Any:
+        """A ``requests`` auth object: ``requests.get(url, auth=agent.auth())``."""
+        from .http import RequestsAuth
+
+        return RequestsAuth(self)
+
+    def session(self) -> Any:
+        """A ``requests.Session`` that identifies the agent where it may."""
+        import requests
+
+        session = requests.Session()
+        session.auth = self.auth()
+        return session
+
+    def httpx_auth(self) -> httpx.Auth:
+        """An ``httpx.Auth`` for ``httpx.Client`` and ``httpx.AsyncClient``."""
+        from .http import HttpxAuth
+
+        return HttpxAuth(self)

aidr_agent-0.1.0/aidr_agent/http.py

@@ -0,0 +1,41 @@
+"""HTTP-library adapters. Each signs a request at the moment it is sent, with a fresh nonce."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Generator
+from typing import TYPE_CHECKING
+
+import httpx
+
+if TYPE_CHECKING:
+    from .agent import Agent
+
+try:
+    from requests.auth import AuthBase as _RequestsAuthBase
+except ImportError:                      # requests is optional
+    _RequestsAuthBase = object           # type: ignore[assignment,misc]
+
+
+class RequestsAuth(_RequestsAuthBase):   # type: ignore[misc,valid-type]
+    def __init__(self, agent: Agent) -> None:
+        self.agent = agent
+
+    def __call__(self, request):  # noqa: ANN001, ANN204 - requests.PreparedRequest
+        request.headers.update(self.agent.sign_headers(request.method, request.url))
+        return request
+
+
+class HttpxAuth(httpx.Auth):
+    """Sync and async. Credentials are fetched with a separate client, never the one being used,
+    so a request to the registry is never itself signed for the site."""
+
+    def __init__(self, agent: Agent) -> None:
+        self.agent = agent
+
+    def sync_auth_flow(self, request: httpx.Request) -> Generator[httpx.Request, httpx.Response, None]:
+        request.headers.update(self.agent.sign_headers(request.method, str(request.url)))
+        yield request
+
+    async def async_auth_flow(self, request: httpx.Request) -> AsyncGenerator[httpx.Request, httpx.Response]:
+        request.headers.update(await self.agent.asign_headers(request.method, str(request.url)))
+        yield request

aidr_agent-0.1.0/aidr_agent/identity.py

@@ -0,0 +1,81 @@
+"""An agent's identity: its identifier, where it is registered, what it may sign for, and its key.
+
+The private key is generated on the machine the agent runs on and never leaves it except where the
+operator puts it (a key file, or the one environment variable a container reads). The registry
+only ever received the public half.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import urlsplit
+
+from aidr_crypto.keys import jwk_to_private_key, private_key_to_jwk, public_key_to_jwk
+
+#: The registry an identity belongs to when nothing else says (AIDR_REGISTRY_URL overrides it).
+DEFAULT_REGISTRY = "https://api.evolivcore.com"
+
+FORMAT = "aidr-agent-identity/1"
+
+
+class IdentityError(Exception):
+    """A stored identity is missing, unreadable, or not safe to use."""
+
+
+@dataclass
+class AgentIdentity:
+    aid: str
+    name: str
+    registry: str
+    private_key: Any = field(repr=False)
+    #: Origins the registry issues credentials for; empty = unrestricted.
+    audiences: list[str] = field(default_factory=list)
+
+    def public_jwk(self) -> dict[str, Any]:
+        return public_key_to_jwk(self.private_key.public_key())
+
+    # -- serialisation ---------------------------------------------------------------------------
+
+    def to_document(self) -> dict[str, Any]:
+        """Everything, private key included. Treat the result as a secret."""
+        return {"format": FORMAT, "aid": self.aid, "name": self.name, "registry": self.registry,
+                "audiences": list(self.audiences), "private_jwk": private_key_to_jwk(self.private_key)}
+
+    @classmethod
+    def from_document(cls, document: dict[str, Any]) -> AgentIdentity:
+        if document.get("format") != FORMAT:
+            raise IdentityError(f"not an {FORMAT} document")
+        try:
+            return cls(aid=document["aid"], name=document["name"], registry=document["registry"],
+                       audiences=list(document.get("audiences") or []),
+                       private_key=jwk_to_private_key(document["private_jwk"]))
+        except (KeyError, ValueError, TypeError) as exc:
+            raise IdentityError(f"malformed identity: {exc}") from exc
+
+    def to_portable(self) -> str:
+        """One line for a secret store: base64url(JSON). A secret — it holds the private key."""
+        raw = json.dumps(self.to_document(), separators=(",", ":")).encode()
+        return base64.urlsafe_b64encode(raw).decode().rstrip("=")
+
+    @classmethod
+    def from_portable(cls, value: str) -> AgentIdentity:
+        value = value.strip()
+        try:
+            raw = base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
+            return cls.from_document(json.loads(raw))
+        except (ValueError, json.JSONDecodeError) as exc:
+            raise IdentityError("AIDR_AGENT_IDENTITY is not a valid identity") from exc
+
+
+def normalize_origin(url: str) -> str:
+    """``https://Shop.Example:443/path`` → ``https://shop.example`` (the registry's normalisation)."""
+    parts = urlsplit(url)
+    if not parts.scheme or not parts.hostname:
+        raise ValueError(f"not a URL: {url!r}")
+    host = parts.hostname.lower().rstrip(".")
+    default = {"https": 443, "http": 80}.get(parts.scheme)
+    port = f":{parts.port}" if parts.port and parts.port != default else ""
+    return f"{parts.scheme}://{host}{port}"

aidr_agent-0.1.0/aidr_agent/keystore.py

@@ -0,0 +1,99 @@
+"""Where an agent's identity (and so its private key) is kept between runs.
+
+FileKeyStore   a laptop, a VM, a persistent volume: ``<home>/<name>/identity.json``, mode 0600.
+EnvKeyStore    a container or a serverless function: the whole identity in AIDR_AGENT_IDENTITY,
+               held by the platform's secret store (``python -m aidr_agent enroll --print-identity``).
+
+An ephemeral container with a FileKeyStore on a throwaway disk enrolls a NEW agent every time it
+starts, and spends a use of the token each time. Use EnvKeyStore there.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import sys
+from pathlib import Path
+from typing import Protocol
+
+from .identity import AgentIdentity, IdentityError
+
+IDENTITY_ENV = "AIDR_AGENT_IDENTITY"
+HOME_ENV = "AIDR_AGENT_HOME"
+
+
+class KeyStore(Protocol):
+    def load(self, name: str) -> AgentIdentity | None: ...
+    def save(self, identity: AgentIdentity) -> None: ...
+
+
+def default_home() -> Path:
+    return Path(os.environ.get(HOME_ENV) or Path.home() / ".aidr" / "agents")
+
+
+class FileKeyStore:
+    def __init__(self, home: str | os.PathLike[str] | None = None) -> None:
+        self.home = Path(home) if home is not None else default_home()
+
+    def path(self, name: str) -> Path:
+        if not name or "/" in name or "\\" in name or name in (".", ".."):
+            raise IdentityError(f"not a usable agent name for a directory: {name!r}")
+        return self.home / name / "identity.json"
+
+    def load(self, name: str) -> AgentIdentity | None:
+        path = self.path(name)
+        if not path.exists():
+            return None
+        _refuse_if_shared(path)
+        try:
+            document = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise IdentityError(f"{path} is unreadable: {exc}") from exc
+        return AgentIdentity.from_document(document)
+
+    def save(self, identity: AgentIdentity) -> None:
+        path = self.path(identity.name)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if sys.platform != "win32":
+            os.chmod(path.parent, 0o700)
+        # Created 0600 from the start, never widened then narrowed: there is no moment at which
+        # another user could read the key.
+        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0)
+        tmp = path.with_suffix(".tmp")
+        if tmp.exists():
+            tmp.unlink()
+        fd = os.open(tmp, flags, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(identity.to_document(), handle, indent=2)
+        os.replace(tmp, path)
+
+
+class EnvKeyStore:
+    """Read-only: the identity is put in the environment by whoever deploys the agent."""
+
+    def __init__(self, variable: str = IDENTITY_ENV) -> None:
+        self.variable = variable
+
+    def load(self, name: str) -> AgentIdentity | None:
+        value = os.environ.get(self.variable)
+        if not value:
+            return None
+        identity = AgentIdentity.from_portable(value)
+        if identity.name != name:
+            raise IdentityError(f"{self.variable} holds agent {identity.name!r}, not {name!r}")
+        return identity
+
+    def save(self, identity: AgentIdentity) -> None:
+        raise IdentityError(f"{self.variable} is read-only; enroll with "
+                            "`python -m aidr_agent enroll --print-identity` and store the output")
+
+
+def _refuse_if_shared(path: Path) -> None:
+    """A key file that other users can read is a key other users may have copied."""
+    if sys.platform == "win32":
+        return          # NTFS ACLs, not mode bits; the profile directory is private by default
+    mode = path.stat().st_mode
+    if mode & (stat.S_IRWXG | stat.S_IRWXO):
+        raise IdentityError(f"{path} is readable by other users (mode {oct(mode & 0o777)}); "
+                            f"run: chmod 600 {path}")

aidr_agent-0.1.0/aidr_agent/langchain.py

@@ -0,0 +1,157 @@
+"""LangChain: give an agent's HTTP tools an AIDR identity.
+
+Built on ``langchain-core`` (``pip install langchain-core``)::
+
+    from aidr_agent import Agent
+    from aidr_agent.langchain import aidr_http_tools
+
+    agent = Agent.load_or_enroll("research-01", audiences=["https://shop.example"])
+    tools = aidr_http_tools(agent)          # http_get and http_post, signed, limited to the audiences
+
+The tools reach only the origins they are given — by default the agent's allowed audiences —
+because an LLM choosing URLs is exactly the prompt-injection path by which an agent would present
+its identity (or fetch internal addresses) somewhere it should not.
+
+``langchain-community`` is being sunset; for code that still uses its ``RequestsToolkit``,
+:func:`signed_requests_wrapper` returns a drop-in ``TextRequestsWrapper`` that signs, sync and async.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from .identity import normalize_origin
+
+if TYPE_CHECKING:
+    from .agent import Agent
+
+DEFAULT_MAX_CHARS = 20_000
+
+
+class OriginNotAllowed(ValueError):
+    pass
+
+
+def _origins(agent: Agent, origins: Iterable[str] | None) -> frozenset[str]:
+    chosen = frozenset(normalize_origin(o) for o in origins) if origins is not None else agent.sign_for
+    if not chosen:
+        raise ValueError("name the origins these tools may reach (origins=[...]): this agent has no "
+                         "allowed audiences to default to")
+    return chosen
+
+
+def _check(url: str, allowed: frozenset[str]) -> None:
+    try:
+        origin = normalize_origin(url)
+    except ValueError as exc:
+        raise OriginNotAllowed(f"not a URL: {url!r}") from exc
+    if origin not in allowed:
+        raise OriginNotAllowed(f"{origin} is not one of the sites this tool may reach: "
+                               f"{', '.join(sorted(allowed))}")
+
+
+def _render(response: httpx.Response, max_chars: int) -> str:
+    text = response.text
+    if len(text) > max_chars:
+        text = text[:max_chars] + f"\n…[truncated, {len(response.text)} characters in all]"
+    return f"HTTP {response.status_code}\n{text}"
+
+
+def aidr_http_tools(agent: Agent, *, origins: Iterable[str] | None = None,
+                    max_chars: int = DEFAULT_MAX_CHARS, timeout: float = 30.0,
+                    methods: Iterable[str] = ("GET", "POST")) -> list[Any]:
+    """``http_get`` / ``http_post`` tools that identify the agent to the sites they reach."""
+    from langchain_core.tools import StructuredTool
+    from pydantic import BaseModel, Field
+
+    allowed = _origins(agent, origins)
+    auth = agent.httpx_auth()
+    sites = ", ".join(sorted(allowed))
+    tools: list[Any] = []
+
+    class GetArgs(BaseModel):
+        url: str = Field(description=f"Absolute URL on one of: {sites}")
+
+    class PostArgs(BaseModel):
+        url: str = Field(description=f"Absolute URL on one of: {sites}")
+        body: dict[str, Any] = Field(default_factory=dict, description="JSON body to send")
+
+    def get(url: str) -> str:
+        _check(url, allowed)
+        with httpx.Client(auth=auth, timeout=timeout, follow_redirects=False) as client:
+            return _render(client.get(url), max_chars)
+
+    async def aget(url: str) -> str:
+        _check(url, allowed)
+        async with httpx.AsyncClient(auth=auth, timeout=timeout, follow_redirects=False) as client:
+            return _render(await client.get(url), max_chars)
+
+    def post(url: str, body: dict[str, Any] | None = None) -> str:
+        _check(url, allowed)
+        with httpx.Client(auth=auth, timeout=timeout, follow_redirects=False) as client:
+            return _render(client.post(url, json=body or {}), max_chars)
+
+    async def apost(url: str, body: dict[str, Any] | None = None) -> str:
+        _check(url, allowed)
+        async with httpx.AsyncClient(auth=auth, timeout=timeout, follow_redirects=False) as client:
+            return _render(await client.post(url, json=body or {}), max_chars)
+
+    wanted = {m.upper() for m in methods}
+    if "GET" in wanted:
+        tools.append(StructuredTool.from_function(
+            func=get, coroutine=aget, name="http_get", args_schema=GetArgs,
+            description=f"Fetch a URL as the verified agent {agent.aid}. Sites: {sites}."))
+    if "POST" in wanted:
+        tools.append(StructuredTool.from_function(
+            func=post, coroutine=apost, name="http_post", args_schema=PostArgs,
+            description=f"POST JSON to a URL as the verified agent {agent.aid}. Sites: {sites}."))
+    return tools
+
+
+def signed_requests_wrapper(agent: Agent, *, json_responses: bool = False) -> Any:
+    """A ``langchain_community`` ``TextRequestsWrapper`` (or ``JsonRequestsWrapper``) that signs.
+
+    Its sync methods go through ``requests`` with the agent's auth; its async ones through aiohttp,
+    which accepts only BasicAuth as ``auth=``, so there the signature is added as headers instead.
+    """
+    from contextlib import asynccontextmanager
+
+    from langchain_community.utilities.requests import (
+        JsonRequestsWrapper,
+        Requests,
+        TextRequestsWrapper,
+    )
+
+    class SignedRequests(Requests):
+        agent: Any = None
+
+        @asynccontextmanager
+        async def _arequest(self, method: str, url: str, **kwargs: Any):  # noqa: ANN202
+            import aiohttp
+
+            headers = {**(self.headers or {}), **await self.agent.asign_headers(method, url)}
+            if self.aiosession is not None:
+                async with self.aiosession.request(method, url, headers=headers, **kwargs) as response:
+                    yield response
+            else:
+                async with aiohttp.ClientSession() as session, \
+                        session.request(method, url, headers=headers, **kwargs) as response:
+                    yield response
+
+    base = JsonRequestsWrapper if json_responses else TextRequestsWrapper
+
+    class SignedRequestsWrapper(base):  # type: ignore[valid-type,misc]
+        agent: Any = None
+
+        @property
+        def requests(self) -> Requests:
+            return SignedRequests(headers=self.headers, aiosession=self.aiosession,
+                                  auth=self.auth, verify=self.verify, agent=self.agent)
+
+    return SignedRequestsWrapper(auth=agent.auth(), agent=agent)
+
+
+__all__ = ["OriginNotAllowed", "aidr_http_tools", "signed_requests_wrapper"]

aidr_agent-0.1.0/aidr_agent/registry.py

@@ -0,0 +1,172 @@
+"""The two conversations an agent has with the registry: enrolling once, and asking for credentials.
+
+Enrolling is authenticated by the enrollment token; asking for a credential by an RFC 9421
+signature with the agent's own key. The token is never needed again after enrollment.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from aidr_crypto.keys import b64url_encode, generate_keypair, public_key_to_jwk, sign_raw
+from aidr_crypto.signatures import sign_request
+
+from .identity import AgentIdentity
+
+POP_CONTEXT = "aiaf-pop-v1"
+TOKEN_PREFIX = "aidr_et_"  # noqa: S105 - a format prefix, not a secret
+
+
+class RegistryError(Exception):
+    """The registry refused, with its own error code (``aidr.…``) where it gave one."""
+
+    def __init__(self, status: int, code: str, message: str) -> None:
+        super().__init__(f"{message} ({code})")
+        self.status = status
+        self.code = code
+
+
+def _refusal(response: httpx.Response) -> RegistryError:
+    try:
+        error = response.json().get("error") or {}
+    except ValueError:
+        error = {}
+    return RegistryError(response.status_code, error.get("code", "aidr.unknown"),
+                         error.get("message", f"the registry answered HTTP {response.status_code}"))
+
+
+def token_id(token: str) -> str:
+    """The non-secret part of a token, for messages and logs: ``etk_…``."""
+    parts = token[len(TOKEN_PREFIX):].split("_", 2) if token.startswith(TOKEN_PREFIX) else []
+    return f"{parts[0]}_{parts[1]}" if len(parts) == 3 else "(not an enrollment token)"
+
+
+def enroll(token: str, *, name: str, registry: str, audiences: list[str] | None = None,
+           description: str = "", http: httpx.Client | None = None,
+           private_key: Any = None) -> AgentIdentity:
+    """Generate a key here, register the agent with the token, and prove the key. Two requests."""
+    if not token.startswith(TOKEN_PREFIX):
+        raise ValueError("that is not an enrollment token (they start with aidr_et_)")
+    if private_key is None:
+        private_key, _ = generate_keypair()
+    base = registry.rstrip("/")
+    headers = {"Authorization": f"AIDR-Enrollment {token}", "AIDR-PoP-Context": POP_CONTEXT}
+    body: dict[str, Any] = {"name": name, "description": description,
+                            "public_key_jwk": public_key_to_jwk(private_key.public_key())}
+    if audiences is not None:
+        body["audiences"] = audiences
+    client = http or httpx.Client(timeout=15)
+    try:
+        started = client.post(f"{base}/v1/enroll", json=body, headers=headers)
+        if started.status_code != 201:
+            raise _refusal(started)
+        registration = started.json()
+        challenge = registration["challenge"]
+        if not challenge["sign_this"].startswith(POP_CONTEXT + ":"):
+            raise RegistryError(0, "aidr.client.bad_challenge",
+                                "the registry asked for a signature this SDK does not make")
+        signature = b64url_encode(sign_raw(private_key, challenge["sign_this"].encode()))
+        aid = registration["agent"]["aid"]
+        proven = client.post(f"{base}/v1/enroll/{aid}/proof", headers=headers,
+                             json={"challenge_id": challenge["challenge_id"], "signature": signature})
+        if proven.status_code != 200:
+            raise _refusal(proven)
+    finally:
+        if http is None:
+            client.close()
+    return AgentIdentity(aid=aid, name=name, registry=base, private_key=private_key,
+                         audiences=list(registration.get("allowed_audiences") or []))
+
+
+@dataclass
+class Credential:
+    token: str
+    renew_at: float        # monotonic clock
+    expires_at: float      # monotonic clock
+
+    def fresh(self, now: float) -> bool:
+        return now < self.renew_at
+
+
+def _credential_request(identity: AgentIdentity, audience: str | None) -> tuple[str, dict, dict]:
+    url = f"{identity.registry}/v1/credentials"
+    headers = sign_request(method="POST", url=url, private_key=identity.private_key, keyid=identity.aid)
+    body = {"aid": identity.aid, **({"audience": audience} if audience else {})}
+    return url, headers, body
+
+
+def _credential_from(response: httpx.Response, now: float) -> Credential:
+    if response.status_code != 200:
+        raise _refusal(response)
+    body = response.json()
+    return Credential(token=body["credential"], renew_at=now + body["renew_after"],
+                      expires_at=now + body["expires_in"])
+
+
+class CredentialCache:
+    """Short-lived credentials (15 minutes or less), one per audience, renewed early.
+
+    Agents with allowed audiences get a credential bound to each site, because the registry
+    issues only those. An unrestricted agent gets one unbound credential (key ``None``): one
+    issuance instead of one per site (credentials issued are what is billed), and accepted by
+    relying parties still on verifiers older than the ones that check a bound credential against
+    the site being visited.
+    """
+
+    def __init__(self, identity: AgentIdentity, *, http: httpx.Client | None = None,
+                 async_http: httpx.AsyncClient | None = None) -> None:
+        self.identity = identity
+        self._http = http
+        self._async_http = async_http
+        self._cache: dict[str | None, Credential] = {}
+        self._lock = threading.Lock()
+
+    def key_for(self, origin: str) -> str | None:
+        return origin if self.identity.audiences else None
+
+    def get(self, origin: str, http: httpx.Client | None = None) -> str:
+        key = self.key_for(origin)
+        with self._lock:
+            cached = self._cache.get(key)
+            if cached and cached.fresh(time.monotonic()):
+                return cached.token
+            url, headers, body = _credential_request(self.identity, key)
+            given = http or self._http
+            client = given or httpx.Client(timeout=15)
+            try:
+                credential = _credential_from(client.post(url, json=body, headers=headers),
+                                              time.monotonic())
+            finally:
+                if given is None:
+                    client.close()
+            self._cache[key] = credential
+            return credential.token
+
+    async def aget(self, origin: str, http: httpx.AsyncClient | None = None) -> str:
+        key = self.key_for(origin)
+        cached = self._cache.get(key)
+        if cached and cached.fresh(time.monotonic()):
+            return cached.token
+        url, headers, body = _credential_request(self.identity, key)
+        given = http or self._async_http
+        if given is None:
+            async with httpx.AsyncClient(timeout=15) as client:
+                response = await client.post(url, json=body, headers=headers)
+        else:
+            response = await given.post(url, json=body, headers=headers)
+        credential = _credential_from(response, time.monotonic())
+        self._cache[key] = credential
+        return credential.token
+
+    def forget(self, origin: str | None = None) -> None:
+        """Drop cached credentials (after a relying party refuses one: it may be revoked)."""
+        with self._lock:
+            if origin is None:
+                self._cache.clear()
+            else:
+                self._cache.pop(self.key_for(origin), None)

aidr_agent-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aidr-agent"
+version = "0.1.0"
+description = "Give an AI agent a verifiable AIDR identity: enroll from code, sign requests, LangChain tools."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Evoliv Core" }]
+keywords = ["ai-agents", "identity", "langchain", "rfc9421", "aiaf", "aidr"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Topic :: Security",
+  "Development Status :: 3 - Alpha",
+]
+dependencies = ["aidr-crypto>=0.1,<0.2", "httpx>=0.27"]
+
+[project.optional-dependencies]
+requests = ["requests>=2.31"]
+langchain = ["langchain-core>=1.0"]
+# For code still on langchain-community's RequestsToolkit (the package is being sunset).
+langchain-community = ["langchain-community>=0.4", "requests>=2.31"]
+
+[project.scripts]
+aidr-agent = "aidr_agent.__main__:main"
+
+[project.urls]
+Homepage = "https://aidr.evolivcore.com"
+Documentation = "https://evolivcore.com/resources"
+
+[tool.hatch.build.targets.wheel]
+packages = ["aidr_agent"]