Local Enforcement

The SDK provides local enforcement primitives that let your app react to threats instantly, without waiting for a Cloud round-trip.

Mental Model

Layer	Role	Scope
SDK	Enforcement: deny, flag, emit	Local, per-instance
Cloud	Policy: revoke, thresholds, coordination	Global, authoritative

The SDK can block a key immediately on the current instance. Cloud handles global revocation across all instances.

⚠️

The SDK never implements temporal or aggregate policy logic. No thresholds. No "N violations in X minutes." That logic lives exclusively in Cloud.

Deny a key locally

Block a key on the current instance. Takes effect immediately. No DB or Cloud call needed.

Node (TypeScript)

import { denyKeyLocally, isKeyDenied } from '@bissap/sdk'
 
// Block a key instantly
denyKeyLocally('key-uuid-here', 'suspicious activity')
 
// Check if denied
isKeyDenied('key-uuid-here') // true
 
// All subsequent /bissap/agent/run calls with this key → 401

Python

from bissap_sdk import deny_key_locally, is_key_denied
 
deny_key_locally("key-uuid-here", reason="suspicious activity")
 
is_key_denied("key-uuid-here")  # True

💡

denyKeyLocally() is instance-scoped. In multi-instance deployments, other instances won't see this denial. Use Cloud's revokeKey() for global revocation.

Flag a key

Mark a key for review. Flags are stored in memory and reported to Cloud (if configured).

Node (TypeScript)

import { flagKey } from '@bissap/sdk'
 
flagKey('key-uuid-here', 'unusual request pattern', 'warning')
// Severity: 'info' | 'warning' | 'severe'

Python

from bissap_sdk import flag_key
 
flag_key("key-uuid-here", "unusual request pattern", severity="warning")

Automatic enforcement

The SDK automatically:

Checks the local denylist before every /bissap/agent/run request. Denied keys get an instant 401
Flags keys when violations are detected (forbidden scope, validation errors)
Reports violations to Cloud (fire-and-forget) when Cloud mode is configured
Respects Cloud revocation state when configured in hybrid or cloud mode

Naming conventions

Term	Meaning
deny	Local, instance-scoped, in-memory block
flag	Mark for review + emit event
revoke	Global, persistent, Cloud-authoritative

revoke is reserved for Cloud. The SDK uses deny and flag.

When to use what

Deny locally → you detected something bad and want to block immediately on this instance
Flag → something looks suspicious, you want to record it and let Cloud decide
Revoke (Cloud) → permanent, global revocation across all instances

In standalone (local) mode, denyKeyLocally() is your only option. With Cloud configured, violations are reported and Cloud can handle global revocation.

Violations & auto-revoke Security