# 🛡️ Stanley Shield Python SDK
The official 2026 Python Gatekeeper for the Stanley Shield Bunker. This SDK provides cryptographic audit logging with native support for Regional Data Residency.


### Install the pre-built wheel:
```bash
pip install stanley_shield-1.0.0-py3-none-any.whl

```

## 🔐 Onboarding & Setup
To use the Shield, you must authenticate your server using the Infisical Machine Identity credentials provided by your Stanley Shield administrator.

### 1. Requirements
- Install the Infisical CLI: ``` bash brew install infisical/get-cli/infisical ``` [MacOS] or follow the [official guide](https://infisical.com/docs/cli/overview).

- Obtain your Credentials Pack:

  - INFISICAL_MACHINE_ID

  - INFISICAL_MACHINE_SECRET

  - INFISICAL_PROJECT_ID

  - STANLEY_BUNKER_URL

### 2. Authentication & Execution
Run these commands in your terminal to link your environment to the Bunker. This ensures your STANLEY_HMAC_SECRET is injected directly into memory and never stored on disk.

#### Step A: Authenticate your session
```bash
export INFISICAL_TOKEN=$(infisical login --method=universal-auth \
  --client-id=YOUR_MACHINE_ID \
  --client-secret=YOUR_MACHINE_SECRET \
  --silent --plain)
```
#### Step B: Run your app with injected secrets
```bash
infisical run --path=/apps/fintech-api --env=prod --projectId=YOUR_PROJECT_ID -- python3 main.py
```

# Basic Usage
### Basic Initialization
Once the app is running via the infisical run command, the SDK will automatically detect your configuration.
```bash
Python code 

from stanley_shield import Gatekeeper

# Automatically pulls STANLEY_HMAC_SECRET and STANLEY_CLIENT_ID from Infisical
gk = Gatekeeper(bunker_url="https://bunker.yourdomain.com")

# Log an event
gk.log(
    actor_id="user_99",
    action="CREDIT_CARD_LINKED",
    resource="card_8822",
    residency="NG_LOCAL",  # Routes to Nigerian infrastructure
    metadata={"bank": "GTBank", "currency": "NGN"}
)
```

## Security Features

- HMAC-SHA256 Signing: Every request is signed. The Bunker rejects any payload that has been tampered with in transit.

- Non-Blocking Transporter: Logging happens in a background daemon thread. Your application's performance is never affected by network latency.

- Replay Protection: Includes a 60-second window timestamp to prevent old requests from being re-sent.

## Data Residency Support
- GLOBAL: Default storage in the Global Vault.

- NG_LOCAL: Routes logs to the localized Nigerian infrastructure.

