UnboxAPI Safety Proxy — Interface Skeleton

⚠ NOT PRODUCTION SAFETY ⚠

This repository contains interface definitions and a trivial reference hook only. It is not a production safety control, does not implement any security rules, and provides no protection against prompt injection, spend abuse, or any other threat. Using this skeleton as a safety layer in a production system would be incorrect and dangerous.

The production safety-proxy runtime — including vetted rule libraries, spend caps, prompt-injection classifiers, EU AI Act disclosure wrappers, and audit-log infrastructure — is proprietary and available at unboxapi.pro.

---

What this is

UnboxAPI-SafetyProxy publishes the interface of the safety-proxy / context-injection layer used inside UnboxAPI's managed runtime. It ships:

• Abstract base classes and Protocol definitions for safety hooks.
• Named hookable points in the call lifecycle (before_call, after_call, on_error).
• A single trivial reference hook (LoggingHook) that logs every call context and unconditionally returns ALLOW. This demonstrates the interface shape; it performs zero security evaluation.

The interface is published as an Apache-2.0 signal artefact to support:

• EU AI Act §6.1 disclosure — a public, hookable disclosure layer demonstrates the architecture of the safety mechanism without revealing the production rule library.
• Ecosystem integration — third parties can write hooks that conform to the same interface and plug into a future public SDK.
• Defensive audit trail — the interface is the moat signal; the rule library is the moat substance, and it stays proprietary.

What this is not

This repository does not ship:

• Any production safety rules or classifiers.
• Prompt-injection detection logic.
• Spend-cap or quantity-cap enforcement.
• EU AI Act disclosure wrappers.
• Audit-log infrastructure.
• Any hook that provides real security guarantees.

Those live in the proprietary UnboxAPI product at https://unboxapi.pro.

---

⚠ Security notice — READ BEFORE USE

The LoggingHook reference implementation always returns ALLOW. It is intentionally incapable of blocking any call. If you register it as the sole hook in a safety proxy and call evaluate_call, every request will proceed regardless of content.

Do not treat "the hook ran" as equivalent to "the call is safe."

See docs/threat-model.md and SECURITY.md for the full threat model covering prompt-injection paths in hook implementations and supply-chain risks.

---

Interfaces

All interfaces are defined in unboxapi_safety_proxy/interfaces.py.

CallContext

Immutable dataclass passed to every hook:

Field	Type	Description
tool_name	str	Name of the tool being called (e.g. order_pizza).
tool_args	dict[str, Any]	Arguments supplied to the tool. Treat as untrusted.
tenant_id	str	Opaque tenant identifier.
request_id	str	Unique request identifier for tracing.
metadata	dict[str, Any]	Extensible bag for additional context.

HookResult

Field	Type	Description
action	HookAction	ALLOW, DENY, or LOG_AND_ALLOW.
reason	str	Human-readable explanation.
metadata	dict[str, Any]	Hook-specific output metadata.

SafetyHook (Protocol)

class SafetyHook(Protocol):
    @property
    def hook_id(self) -> str: ...
    def evaluate(self, context: CallContext) -> HookResult: ...

SafetyProxy (Protocol)

class SafetyProxy(Protocol):
    def register_hook(self, hook: SafetyHook) -> None: ...
    def deregister_hook(self, hook_id: str) -> None: ...
    def evaluate_call(self, context: CallContext) -> HookResult: ...

Reference hook

unboxapi_safety_proxy.hooks.LoggingHook logs every CallContext via Python's standard logging module and returns HookAction.ALLOW unconditionally. It implements no security logic.

from unboxapi_safety_proxy.hooks import LoggingHook
from unboxapi_safety_proxy.interfaces import CallContext

hook = LoggingHook()
ctx  = CallContext(
    tool_name="order_pizza",
    tool_args={"topping": "Pepperoni", "location": "London"},
    tenant_id="tenant-123",
    request_id="req-456",
)
result = hook.evaluate(ctx)
# result.action == HookAction.ALLOW  (always)

Installation

No runtime dependencies. Requires Python ≥ 3.11.

pip install unboxapi-safety-proxy

(PyPI release pending. Install from source for now.)

Status

v0.1.0 — interface-only public release.

• External contributions are not accepted at v0.1.0. Feedback via Issues is welcome. A CLA and contribution guide will be added in a later release.
• The interface shape is considered stable for v0.x. Breaking changes will bump the minor version pre-1.0.

Verifying release artifacts

Releases are signed. To verify a release tarball:

cosign verify-attestation \
  --type slsaprovenance \
  --certificate-identity-regexp '.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  unboxapi-safety-proxy-v0.1.0.tar.gz

A CycloneDX SBOM is attached to every GitHub release.

Threat model

See docs/threat-model.md.

License

Apache License, Version 2.0. See LICENSE and NOTICE.

Maintainers

This repository is maintained by UnboxAPI. The production safety-proxy runtime, vetted rule library, prompt-injection classifiers, EU AI Act compliance tooling, and audit infrastructure are proprietary and available at https://unboxapi.pro.