my-notes-viewer/.agents/skills/audit-and-compliance/SKILL.md

name, description

name	description
audit-and-compliance	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:

audit:
    enabled: true
    defaultTTL: "720h"
    defaultLimit: 50
    maxLimit: 10000

At collection level, audit is controlled separately:

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:

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.