> ## Documentation Index
> Fetch the complete documentation index at: https://nestcrate.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Reliability & agents — security notes

> Threat-model notes for NestRS resilience, idempotency, outbox, locks, mail, webhooks, workflows, and AI packages.

Threat-model notes for the reliability / integration / AI packages. Start with the [package hub](https://nestcrate.dev/guides/reliability.md) for install and maps; this page is the security checklist only.

## Idempotency (`nestrs-idempotency`)

* Always **scope** keys by authenticated principal (`IdempotencyOptions.scope`) so tenants cannot replay another user's response.
* Treat in-flight collisions as **409**, not 200 — never execute the handler twice for the same key.
* TTL must bound store growth; defaults to 24h in-memory.

## Webhooks (`nestrs-webhooks`)

* Secrets: prefer `whsec_` Standard Webhooks encoding; never log raw secrets.
* Verify on the **raw body** before JSON parse.
* Outbound URLs from user input are SSRF-sensitive — validate allowlists at the application layer before `dispatch`.

## Outbox (`nestrs-outbox`)

* Poison messages: after `max_attempts`, messages move to DLQ — alert on `list_dead_letters`.
* In-memory store is for tests/dev; production should set `allow_in_memory: false` once a durable adapter is wired.

## AI tools (`nestrs-ai`)

* Agent tools must enforce the **caller's** authz (guards / `Ability`) — never run privileged tools anonymously.
* `FakeModel` is for tests only; never configure it in production binaries.
* `generate_object` fails closed on invalid JSON or missing required schema fields.

## Resilience (`nestrs-resilience`)

* Retry jitter is **on by default** to avoid thundering herds.
* Map `Timeout` → 504 and `CircuitOpen` → 503 + `Retry-After` at the HTTP boundary.

## Mail (`nestrs-mail`)

* Template render must escape HTML by default.
* HTTP providers inherit SSRF rules — pin destinations; do not follow arbitrary redirect targets from user content.

## Locks / workflows (`nestrs-locks`, `nestrs-workflows`)

* Lease TTL must be shorter than the worst-case work you are willing to duplicate after a crash; extend leases on long steps.
* Approval waits are durable state — treat resume tokens as capability secrets (do not log them).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.