Audit & security

Imperal Cloud takes audit and tenant isolation seriously. Most of what you need is automatic — your extension gets it for free. This page documents what you get, what you owe, and what to expect from the platform.

What you get for free

The action ledger

Every @chat.function invocation is recorded with a consistent set of fields. Each record captures:

Read access is restricted — admins via Panel, security review via federal protocols.

Retention classes

You don't pick this manually — action_type + your extension's compliance class drive it. action_type="destructive" always lands in federal_7y.

What your extension is responsible for

Always scope state by ctx.user.imperal_id

# ✅ Federal-clean
db.set(f"user:{ctx.user.imperal_id}:notes:{note_id}", note)

# ❌ Cross-tenant leak
db.set(f"notes:{note_id}", note)   # global key — can be overwritten by another user

Tag external calls with the tenant context

# ctx.http does this for free
await ctx.http.post("/external/api", json=...)

# If you have to use a custom client (rare — ctx.http is preferred by
# convention but not enforced by a federal validator):
# pass user_id / tenant_id headers explicitly

Don't log secrets or PII

# ❌ Don't
await ctx.log(f"Auth token={user_token}", level="info")

# ✅ Do
await ctx.log(f"Auth attempt user={ctx.user.imperal_id} success=True", level="info")

ctx.log is an async def coroutine — await ctx.log("message", level="info") — not a logger object with .info/.warn/.error attributes, and it takes only message + level (no structured keyword fields). Build the message string yourself, and keep secrets and PII out of it — write the right thing in the first place.

Honour cancellation

from imperal_sdk import ActionResult
from imperal_sdk.chat import TaskCancelled

async def long_running(ctx, params):
    try:
        for i, batch in enumerate(batches):
            # ctx.progress raises TaskCancelled if the user cancelled
            await ctx.progress(int(100 * i / max(len(batches), 1)), "Processing…")
            await process(batch)
    except TaskCancelled:
        await ctx.log(f"Cancelled after {processed_count} items", level="info")
        return ActionResult.error("Cancelled")
    return ActionResult.success(data={}, summary="Done")

Cancellation is surfaced through ctx.progress(): when the user cancels, the next await ctx.progress(...) call raises TaskCancelled. There is no separate cancellation flag or event object to poll — watch for the TaskCancelled exception instead. Audit rows are written even on cancellation — with status='cancelled'. Don't silently ignore.

Anti-hallucination — what runs before your code

Before your handler is dispatched, the platform pre-screens the request:

You don't have to write any of these — they're enforced by the platform. What you can do is make them less likely to fire — by writing tight Pydantic descriptions and not returning ungrounded text.

When something goes wrong

What you can do for stronger compliance

Where to read more