What does pb-agent protect?
The protected assets are PocketBase superuser tokens, application records, files, schemas, logs, backups, human approval intent, plan integrity, and audit evidence. The local user and installed pb-agent binary are trusted. A compromised operating system or binary is outside the v0.1 threat model.
Why plan before apply?
A mutation plan freezes the operation an agent proposes. pb-agent encrypts the payload locally and binds metadata to the connection, environment, PocketBase instance fingerprint, request hash, and expiration. Apply takes a plan ID, not a second mutable set of write arguments.
What happens if a record changes after review?
Record updates and deletes use optimistic concurrency protection. pb-agent fetches the target again immediately before apply and compares its precondition hash. If the record changed after planning, the mutation stops instead of overwriting newer state.
How are production writes controlled?
Production is read-only by default. Staging and production mutations require a short-lived access grant whose connection, operation, and resource scope match the plan. Creating a plan does not bypass that rule.
Where are credentials stored?
pb-agent uses a dedicated PocketBase _superusers impersonation token.
The token enters through standard input and is stored in the operating system
credential manager. It is not stored in pb-agent.yaml, command output,
plan files, or audit records.
PocketBase warns that superuser impersonation tokens can access and modify anything, so use a dedicated account and the shortest practical duration. Changing that superuser's password invalidates its issued tokens.
Can PocketBase records prompt-inject the agent?
Record values are untrusted data. They are returned as data and never enter pb-agent's policy evaluation. The companion skill also tells agents never to treat record contents as instructions.
What appears in audit logs?
Audit records contain operation metadata, identifiers, field names, and hashes. They do not contain record values or credentials. This provides local evidence without copying application data into another sensitive store.
What is intentionally unavailable?
pb-agent provides no raw SQL or arbitrary HTTP passthrough. Those escape hatches would let an agent bypass the capability policy. Remote MCP transport, unattended production writes in CI, and malicious custom PocketBase extensions are also outside the current scope.
Security checklist
- Use a dedicated PocketBase superuser for pb-agent.
- Generate a nonrenewable impersonation token with the shortest practical duration.
- Start with a development connection and run
doctor. - Review each mutation plan before applying it.
- Keep production read-only unless a specific maintenance task needs a scoped grant.
- Report vulnerabilities privately through the repository's security policy.