arclasp 0.1.0b1__tar.gz

arclasp-0.1.0b1/.gitattributes

@@ -0,0 +1,12 @@
+* text=auto
+*.py text eol=lf
+*.md text eol=lf
+*.toml text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary

arclasp-0.1.0b1/.gitignore

@@ -0,0 +1,115 @@
+# ─── Secrets & credentials (NEVER commit) ─────────────────────────────
+# Environment files — covers .env, .env.local, .env.production, etc.
+.env
+.env.*
+!.env.example
+!.env.sample
+!.env.template
+
+# Private keys, certs, credentials
+*.pem
+*.key
+*.cert
+*.crt
+*.pfx
+*.p12
+id_rsa
+id_rsa.*
+id_ecdsa
+id_ecdsa.*
+id_ed25519
+id_ed25519.*
+
+# Common credential directories
+secrets/
+secret/
+credentials/
+private/
+.secrets/
+
+# Backup files (often contain pre-edit copies of env files)
+*.bak
+*.backup
+*.dump
+*.old
+*~
+
+# ─── AI tool artifacts (project-local, never useful in public repo) ──
+.claude/
+.claire/
+.cursor/
+.aider*
+.continue/
+.codex/
+CLAUDE.md
+AGENTS.md
+
+# ─── Python build artifacts ──────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.so
+*.whl
+wheels/
+
+# ─── Python tool caches ──────────────────────────────────────────────
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.nox/
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.pytype/
+.hypothesis/
+
+# ─── Virtual environments ────────────────────────────────────────────
+venv/
+.venv/
+env/
+ENV/
+.python-version
+
+# ─── Local databases & data dumps ────────────────────────────────────
+*.sqlite
+*.sqlite3
+*.db
+*.sql.gz
+*.dump
+
+# ─── IDE / editor ────────────────────────────────────────────────────
+.vscode/
+.idea/
+*.swp
+*.swo
+*.swn
+.DS_Store
+*.sublime-workspace
+*.sublime-project
+
+# ─── OS ──────────────────────────────────────────────────────────────
+Thumbs.db
+ehthumbs.db
+desktop.ini
+
+# ─── Local dev scratch ───────────────────────────────────────────────
+*.log
+local_*
+scratch/
+tmp/
+temp/
+.notes/
+NOTES.md
+TODO.md
+
+# ─── Process artifacts ───────────────────────────────────────────────
+*.pid
+*.sock

arclasp-0.1.0b1/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Changelog
+
+All notable changes to Arclasp (formerly ProofRail) will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0b1] - 2026-09-05
+
+Public beta release candidate for the first public Arclasp SDK publication.
+
+### Changed
+
+- **Breaking:** the Python import namespace is now `arclasp` (previously `proofrail`). `import arclasp`, `from arclasp import Chain`, `from arclasp.exceptions import ...` replace the old `proofrail` imports. The PyPI distribution name (`arclasp`) is unchanged from the prior prerelease. Exception classes `ProofRailPolicyError`, `ProofRailVerificationError`, and `ProofRailKillSwitchError` are renamed to `ArclaspPolicyError`, `ArclaspVerificationError`, and `ArclaspKillSwitchError`. There is no `proofrail` compatibility shim — the project has no external customers on the prior namespace yet.
+- Governed SDK execution now requires backend authority for every public Chain action. The deprecated `enable_local_fast_path=True` setting no longer produces local allow decisions, and backend unavailability raises `BackendUnavailableError` even when legacy `fail_mode="allow"` compatibility settings are supplied.
+- Finalized the first public Arclasp Python namespace before PyPI publication: removed dead local-governance compatibility APIs, exposed `ArclaspPolicyError` at top level, kept legacy receipt verification under `arclasp.client`, and kept backend/wire verification contracts unchanged.
+- Updated package metadata, security contacts, and public documentation links for the Arclasp public beta.
+
+## [0.1.0a10] — 2026-08-19
+
+Pre-release repository hygiene pass ahead of first public GitHub/PyPI release.
+
+### Changed
+
+- Repository renamed to `TOAAiV/Arclasp`; all project URLs, issue templates,
+  and in-repo documentation links now point at the current repository instead
+  of the prior `proofrail` name.
+- Fixed inconsistent documentation domain: exception remediation links now
+  consistently use `docs.proofrail.dev`.
+- Removed internal engineering/audit working documents and a private-backend
+  end-to-end test from the public repository; they do not affect the public
+  SDK's behavior or test coverage.
+- Removed a Windows-only development workaround from the production demo
+  scripts that disabled TLS certificate verification; production examples now
+  use normal certificate-verified HTTPS only.
+- Demo scripts no longer hardcode a personal notification address; they read
+  the approver email from an `ARCLASP_APPROVER_EMAIL` environment variable.
+- Package metadata classifier corrected to `Alpha` to match the `a10`
+  pre-release version string.
+
+## [0.1.0] — 2026-06-17
+
+Initial public release.
+
+### Added
+
+**Core governance**
+- Chain-level governance with cumulative metrics across an entire agent workflow
+  (financial exposure, external communications, records modified, privileged actions,
+  tokens used, external domains contacted).
+- Open-source reference policy engine in `proofrail/policies.py`, verified for parity
+  against the backend policy engine on every test run.
+- Blocking human approval gate with configurable timeouts and fallback approvers.
+  Returns a fully-resolved `PolicyDecision` to the caller after the approver responds.
+- Local fast-path evaluation for sub-5ms decisions on obviously-safe actions,
+  with asynchronous backend logging so the dashboard and audit trail stay accurate.
+- Policy shadow mode for testing new policies against real traffic in observe-only
+  mode before flipping them to enforce.
+- Per-action-class fail modes for backend-unreachable scenarios (e.g., deny financial
+  actions, allow reads).
+- Time-boxed policy exceptions with explicit scope and expiration.
+- Org-wide kill switch raising `ProofRailKillSwitchError` distinct from regular
+  policy denials.
+
+**Audit and trust**
+- HMAC-SHA256 signed audit receipts, hash-chained across an organization so
+  tampering with any single receipt breaks the chain publicly.
+- Public receipt verification endpoint requiring no authentication.
+- Append-only admin audit log capturing before/after diffs for every dashboard
+  mutation.
+- Agent registry with risk tiers; unregistered agents are flagged but not blocked.
+
+**Framework adapters**
+- LangGraph adapter via `astream_events` (preferred) with `AsyncCallbackHandler`
+  fallback.
+- LangChain adapter via `AsyncCallbackHandler` for tool calls and LLM invocations.
+- CrewAI adapter with both native callback (Strategy A) and `execute_task`
+  monkey-patch (Strategy B) instrumentation paths.
+- MCP adapter for instrumenting MCP server tool handlers.
+
+**Reliability and safety**
+- Payload sanitization with default patterns for API keys, passwords, credit cards,
+  SSNs, private keys, and common token formats (OpenAI, Stripe, GitHub,
+  Hugging Face, AWS, JWT). Raw payloads are never persisted.
+- Offline buffer with idempotency keys to prevent duplicate audit events on
+  network retry.
+- Cost tracking and monthly budgets: recorded LLM token usage and estimated
+  dollar cost, with dashboard-configured UTC calendar month budgets. A governed
+  chain requires approval only after a newly recorded total is greater than the
+  configured budget; unknown model pricing is not counted as zero.
+- Cross-organization isolation enforced on every UUID-bearing endpoint, with a
+  dedicated test suite verifying one organization's API key cannot reach
+  another organization's data.
+
+### Security
+
+This release ships after a 15-finding security audit of the SDK. All findings
+have been resolved:
+
+- Metadata sanitization applied at chain start to prevent unsanitized payloads
+  from reaching the backend.
+- API keys stored as `pydantic.SecretStr` to prevent accidental logging.
+- HTTP-to-production warnings switched to logger output and extended to all
+  non-localhost URLs.
+- Additional sensitive-value patterns added (JWT prefixes, AWS access keys,
+  ProofRail API key prefix).
+- Bytes-type payload handling added to the sanitizer.
+- Action name truncation hardened against oversized inputs.
+- Log sanitization helper applied across all framework adapter log sites.
+- Fast-path cumulative metrics propagation fixed (the financial threshold gate
+  was previously not updating local metrics from fast-path decisions).
+- Documented kill-switch limitation in fast-path; full enforcement is on the
+  post-launch backlog.
+- Unused `cryptography` dependency removed.
+
+Full security policy and disclosure process in [SECURITY.md](SECURITY.md).
+
+### Fixed
+
+- **Audit event duplication on retry** — events sent during a network blip
+  could be recorded twice. Fixed via idempotency keys on every event POST
+  and deduplication on the backend.
+- **Infinite retry on permanent errors** — the offline buffer drain treated
+  all HTTP errors as transient, looping forever on 4xx responses. Now
+  classifies 400, 401, 403, 404, 422 as permanent (discard and continue) and
+  429, 5xx as transient.
+- **Silent event loss on slow backends** — fixed-duration drain timeout could
+  abandon events when backend latency was high. Drain timeout now scales with
+  buffered event count.
+- **Network errors propagated as bare exceptions** — `httpx.ReadError` and
+  `httpx.WriteError` (raised by load balancer terminations, backend crashes,
+  cellular handoffs) were not retried. Now caught alongside `ConnectError`.
+
+### Known limitations
+
+- Single region. Backend runs in US-East. European and APAC users may see
+  100-150ms additional latency. Multi-region is on the roadmap.
+- CrewAI deny decisions cannot halt mid-task execution due to CrewAI's
+  synchronous task architecture. Governance events are still recorded; the
+  decision surfaces as `ActionDeniedError` on the next event loop cycle.
+- Approval notifications are email-only. Slack and Teams integrations are
+  planned but not shipped.
+- No SSO beyond what Clerk provides out of the box.
+
+[0.1.0]: https://github.com/TOAAiV/Arclasp/releases/tag/v0.1.0

arclasp-0.1.0b1/CONTRIBUTING.md

@@ -0,0 +1,232 @@
+# Contributing to Arclasp
+
+Thanks for considering a contribution to Arclasp.
+
+This repository contains the public Python SDK, supported framework integrations, tests, examples, verification material, and release metadata for Arclasp. The hosted governance backend and dashboard are separate Arclasp infrastructure; opening an issue or pull request here does not imply that every server-side feature is implemented in this repository.
+
+The best contributions are focused, reproducible, and easy to review.
+
+## Before you start
+
+For a small bug fix, documentation correction, or test improvement, you can open a pull request directly.
+
+For a large behavioral change, a new public API, a new framework integration, or anything that changes governance semantics, open an issue first. That gives us a chance to agree on the boundary before substantial implementation work begins.
+
+Security vulnerabilities should **not** be discussed in a public issue. Follow `SECURITY.md` and report them privately to **security@arclasp.com**.
+
+## Development setup
+
+Arclasp supports Python 3.10 and newer. Python 3.11 is a good default for local development because it is also used in release validation.
+
+Clone the repository and create a virtual environment:
+
+```bash
+python -m venv .venv
+```
+
+Activate it.
+
+On macOS or Linux:
+
+```bash
+source .venv/bin/activate
+```
+
+On Windows PowerShell:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+Upgrade pip and install the SDK with development dependencies and the supported optional integrations:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev,all]"
+```
+
+If you are working only on the framework-agnostic SDK, you can install a smaller dependency set. If you modify a framework adapter, install the corresponding extra and run its integration tests.
+
+## Run the tests
+
+Run the public test suite before submitting a pull request:
+
+```bash
+python -m pytest -q
+```
+
+Some tests are intentionally environment-dependent and may skip when an optional external runtime or private service is unavailable. A skip should be explainable; do not turn a failing regression test into a skip simply to make CI green.
+
+Run lint checks as well:
+
+```bash
+python -m ruff check .
+```
+
+If your change affects packaging, release metadata, imports, or optional dependencies, also build the distributions locally:
+
+```bash
+python -m pip install build twine
+python -m build
+python -m twine check --strict dist/*
+```
+
+The release pipeline performs additional clean-environment and artifact checks before publication.
+
+## Keep changes narrow
+
+A pull request should solve one understandable problem.
+
+Please avoid mixing a behavior change with broad formatting, unrelated refactors, dependency churn, and documentation rewrites in the same PR. Narrow changes are easier to review and safer in a governance SDK where small control-flow differences can change runtime behavior.
+
+If a refactor is necessary to support the change, explain why in the pull request.
+
+## Preserve the governance boundary
+
+Arclasp is not a normal convenience wrapper. Some implementation choices are security and product semantics.
+
+Changes must preserve these principles unless the project explicitly decides to change them:
+
+**Backend authority.** A governed operation that requires backend authority must not silently acquire a local allow path.
+
+**Fail-closed behavior.** Backend uncertainty must not quietly become permission for governed execution.
+
+**Customer-side execution.** Arclasp governs configured actions; the customer application still performs the real tool call or side effect after governance permits it.
+
+**Scoped evidence.** Do not broaden what public verification, logs, errors, examples, or artifacts expose without reviewing the privacy and security impact.
+
+**Precise claims.** Do not change documentation to claim tamper-proof records, guaranteed compliance, legal admissibility, universal exactly-once execution, universal result capture, mature enterprise SSO/custom RBAC, mature self-hosting, or other capabilities that are not part of the current product contract.
+
+## Public API changes
+
+The supported top-level API is intentionally small.
+
+Before adding a new exported symbol, changing an exception contract, or altering the normal `init` / `Chain` / `record_agent_action` path, explain why the change belongs in the public API instead of an internal module or framework-specific surface.
+
+Public API changes should include:
+
+- tests covering the new behavior
+- documentation updates
+- changelog notes when user-visible
+- compatibility analysis for existing integrations
+
+Do not globally rename compatibility identifiers such as the current `prail_` API-key prefix without a deliberate migration plan.
+
+## Framework integrations
+
+Arclasp currently supports custom Python workflows and integration surfaces for LangChain, LangGraph, CrewAI, and MCP.
+
+When changing an adapter:
+
+- test against the real framework dependency where the test is intended to verify real framework behavior
+- preserve existing callbacks or configuration instead of replacing customer state unnecessarily
+- make sure governance exceptions are not swallowed by framework callback machinery
+- restore temporary monkey patches or hooks even when execution fails
+- be explicit about whether the adapter observes invocation, result, error, or only a subset of those events
+- do not claim universal tool-result capture where the adapter cannot provide it
+
+A framework upgrade that changes callback or execution behavior should come with a regression test for the affected path.
+
+## Tests should prove behavior
+
+Prefer tests that assert externally meaningful behavior rather than implementation details.
+
+Good tests answer questions such as:
+
+- Did the governed action stop on deny?
+- Did a required approval block until resolution?
+- Did backend unavailability fail closed?
+- Did the Chain preserve cumulative state?
+- Did the adapter let the governance exception escape?
+- Did sanitization remove the supported sensitive value from a covered event-payload or chain-metadata path?
+- Did the package expose only the intended public contract?
+
+Avoid tests that depend on timing luck, real customer data, or mutable production state.
+
+## Documentation changes
+
+Documentation is part of the product contract.
+
+When editing public copy:
+
+- use **Arclasp** as the current product name
+- use canonical public domains such as `arclasp.com`, `docs.arclasp.com`, `app.arclasp.com`, and `api.arclasp.com`
+- keep intentional compatibility identifiers when the product still uses them
+- distinguish tamper-evident evidence from tamper-proof claims
+- distinguish recorded LLM cost governance from provider billing
+- state that customer applications execute their own tools
+- keep public-beta limitations accurate
+
+If behavior and documentation disagree, do not paper over the mismatch with wording. Fix the behavior, fix the documentation, or raise the discrepancy explicitly.
+
+## Examples and test data
+
+Examples must use synthetic data.
+
+Do not commit:
+
+- real API keys or tokens
+- private keys or certificates
+- customer payloads
+- personal email addresses used as live recipients
+- production database URLs
+- internal service credentials
+- copied production logs containing identifiers or secrets
+
+Use obviously synthetic values such as `finance@example.com` and test-only keys.
+
+Before committing a new artifact or fixture, ask whether it is necessary for a public SDK repository and whether it reveals anything that a user needs in order to understand or verify the SDK.
+
+## Pull request checklist
+
+Before opening a pull request, make sure:
+
+- the change has a clear purpose
+- relevant tests were added or updated
+- `python -m pytest -q` passes in the intended development environment
+- `python -m ruff check .` passes
+- user-facing behavior is documented
+- the changelog is updated when the change is release-noteworthy
+- no secrets, customer data, or machine-specific paths were added
+- new dependencies are justified and appropriately bounded
+- public API changes are deliberate
+- security-sensitive behavior has not been weakened accidentally
+
+In the pull request description, explain **what changed, why it changed, and how you verified it**.
+
+## Bug reports
+
+A useful bug report usually includes:
+
+- Arclasp version
+- Python version
+- operating system
+- framework and framework version, if relevant
+- a minimal reproduction
+- expected behavior
+- actual behavior
+- sanitized error output or traceback
+
+Please remove API keys, tokens, customer data, and other secrets before posting.
+
+## Feature requests
+
+Feature requests are welcome, especially when they describe the workflow problem rather than only a proposed API shape.
+
+Useful context includes:
+
+- what the agent is allowed to do
+- where the consequential side effect occurs
+- what decision should happen before execution
+- what workflow state the decision depends on
+- whether a human reviewer is involved
+- what evidence needs to exist afterward
+- which framework or runtime is involved
+
+That context helps determine whether the request belongs in the SDK, the hosted governance service, an integration, or documentation.
+
+## License
+
+Arclasp's public Python SDK is licensed under the Apache License 2.0.
+
+By contributing code or documentation that is accepted into this repository, you agree that the contribution may be distributed under the repository's Apache-2.0 license.