apairon
4020ad62c5
- Implemented `resolveApiAssetUrl` function to normalize asset URLs based on API base. - Updated `MedialibImage` component to utilize new asset URL resolution and added support for alt text and class properties. - Enhanced image loading behavior with improved width measurement and focal point handling. - Added placeholder image handling and improved accessibility with alt text. - Introduced new test script for auditing broken links in skill documentation. - Expanded seeded test content to include medialib entries and updated related tests for pagebuilder previews. - Improved global setup and teardown logging for clarity on seeded content management.
207 lines
6.0 KiB
Markdown
207 lines
6.0 KiB
Markdown
---
|
|
name: audit-and-compliance
|
|
description: Configure and verify audit logging for tibi website projects. Covers server-level audit config, collection audit actions, audit.return filtering, TTL/retention, source semantics, and what later agents must check before relying on audit trails.
|
|
---
|
|
|
|
# audit-and-compliance
|
|
|
|
## When to use this skill
|
|
|
|
Use this skill when:
|
|
|
|
- a project needs auditable create/update/delete activity
|
|
- operators or stakeholders need a trace of who changed content and how
|
|
- hooks, jobs, or actions mutate important collections and that history matters
|
|
- sensitive data could land in audit snapshots and must be filtered safely
|
|
|
|
## Goal
|
|
|
|
Give later agents a concrete workflow for deciding, configuring, and validating audit logging on this stack.
|
|
|
|
Audit is not just “turn it on”. A usable audit setup must answer:
|
|
|
|
- what is logged
|
|
- how long it is kept
|
|
- who can read it
|
|
- which sensitive fields must be stripped
|
|
- how hook/job/action side effects appear in the audit trail
|
|
|
|
## Source of truth
|
|
|
|
Use these sources when implementing or reviewing audit behavior:
|
|
|
|
- `tibi-server/docs/10-audit.md`
|
|
- `tibi-server/docs/06-hooks.md`
|
|
- `tibi-server/docs/11-jobs.md`
|
|
- `tibi-server/docs/19-actions.md`
|
|
- active server/project config
|
|
|
|
## Core audit model
|
|
|
|
Audit requires an explicit server-level decision:
|
|
|
|
```yaml
|
|
audit:
|
|
enabled: true
|
|
defaultTTL: "720h"
|
|
defaultLimit: 50
|
|
maxLimit: 10000
|
|
```
|
|
|
|
At collection level, audit is controlled separately:
|
|
|
|
```yaml
|
|
name: content
|
|
audit:
|
|
enabled: true
|
|
actions:
|
|
- create
|
|
- update
|
|
- delete
|
|
```
|
|
|
|
Default audited collection actions are `create`, `update`, and `delete`.
|
|
|
|
Important:
|
|
|
|
- `get` can also be audited when needed
|
|
- system actions such as `login`, `reload`, and `shutdown` are controlled by server-level audit enablement
|
|
- bulk API mutations are still audited even though the internal action naming differs (`bulkCreate`, `bulkUpdate`, `bulkDelete`)
|
|
|
|
## Source semantics matter
|
|
|
|
Audit entries are not all equal. The `source.type` tells you where the mutation came from:
|
|
|
|
- `controller` — direct API CRUD request
|
|
- `hook` — database mutation performed from a hook
|
|
- `job` — database mutation performed from a scheduled job
|
|
- `system` — internal system operation
|
|
|
|
For website projects this matters because content can change through:
|
|
|
|
- direct editor CRUD
|
|
- action-triggered persistence
|
|
- hook-side side effects
|
|
- cleanup or synchronization jobs
|
|
|
|
If a project relies on audit trails for governance or debugging, later agents must understand these source types instead of assuming every change came from an editor UI save.
|
|
|
|
## Authentication context in audit entries
|
|
|
|
Audit also records how a request was authenticated.
|
|
|
|
Relevant fields include:
|
|
|
|
- `authMethod`
|
|
- `tokenLabel`
|
|
- `tokenPrefix`
|
|
- `userId`
|
|
- `username`
|
|
- `ip`
|
|
|
|
Practical implication:
|
|
|
|
- use labeled admin tokens for operator workflows so audit output stays readable
|
|
- do not treat all token-based writes as anonymous noise
|
|
|
|
## Snapshot exposure and `audit.return`
|
|
|
|
Audit snapshots can contain more than a normal API read would expose.
|
|
|
|
That means fields that are stripped by normal read hooks can still appear in audit snapshots unless you filter them explicitly.
|
|
|
|
Use `audit.return` hooks when a collection may contain:
|
|
|
|
- passwords
|
|
- API keys
|
|
- internal secrets
|
|
- sensitive operator-only notes
|
|
|
|
Example shape:
|
|
|
|
```yaml
|
|
hooks:
|
|
audit:
|
|
return:
|
|
type: javascript
|
|
file: hooks/users/audit_return.js
|
|
```
|
|
|
|
Use this hook to delete or suppress sensitive `snapshot` and `changes` data before the audit response is returned.
|
|
|
|
## Retention and limits
|
|
|
|
Audit is an operator/compliance concern, not just a developer concern.
|
|
|
|
Decide deliberately:
|
|
|
|
- whether audit is enabled at all
|
|
- how long audit logs should be retained (`defaultTTL`)
|
|
- what read limits make sense (`defaultLimit`, `maxLimit`)
|
|
- whether the target environment expects short-term diagnostics or longer retention
|
|
|
|
Do not enable audit and leave retention undefined by habit.
|
|
|
|
## Recommended patterns for website projects
|
|
|
|
### Content governance
|
|
|
|
Recommended shape:
|
|
|
|
- audit enabled for collections whose changes affect public output or editorial accountability
|
|
- clear retention decision with operations
|
|
- readable token labels for automation or deploy-related writes
|
|
|
|
### Hook-heavy workflows
|
|
|
|
Recommended shape:
|
|
|
|
- understand which hook-side writes will appear as `source.type: "hook"`
|
|
- do not assume audit trails point only to controller actions
|
|
- document important side effects when hooks fan out into multiple writes
|
|
|
|
### Jobs and automation
|
|
|
|
Recommended shape:
|
|
|
|
- know that job-side DB mutations appear as `source.type: "job"`
|
|
- if job behavior matters operationally, make that visible in the job design and ops notes
|
|
|
|
### Sensitive collections
|
|
|
|
Recommended shape:
|
|
|
|
- explicit `audit.return` filtering
|
|
- do not expose raw snapshots just because admins technically can read the endpoint
|
|
|
|
## Anti-patterns
|
|
|
|
- enabling audit without deciding retention
|
|
- treating audit as equivalent to normal collection reads
|
|
- forgetting that hooks and jobs create their own audit source types
|
|
- relying on unlabeled tokens for important automated writes
|
|
- storing sensitive data in snapshots without `audit.return` filtering
|
|
|
|
## Verification checklist
|
|
|
|
After audit-related changes, verify all of these:
|
|
|
|
1. server-level audit settings are deliberate
|
|
2. collection-level audited actions match the actual governance need
|
|
3. a representative write produces the expected audit entry
|
|
4. hook/job/action side effects produce understandable source metadata
|
|
5. sensitive fields are filtered from audit output where required
|
|
6. read visibility and retention expectations are documented
|
|
|
|
## What an LLM should inspect first
|
|
|
|
When asked to design or review audit behavior on this starter, inspect in this order:
|
|
|
|
1. `tibi-server/docs/10-audit.md`
|
|
2. active server audit config
|
|
3. collection-level `audit:` sections
|
|
4. any hook/job/action workflow that mutates important collections
|
|
5. whether `audit.return` filtering is needed
|
|
|
|
This prevents “audit enabled” setups that are technically on but operationally weak.
|