category: spec

tags: [security, logging, owasp, plan]

last_updated: 2026-03-18

Addresses OWASP A09 finding: "No audit trail for auth events, ACL changes, wiki deletions."

| Event | Route / Location | Fields |

|---|---|---|

| `login.initiated` | `POST /auth/login` (after PAR submit) | actor=handle, ip |

| `login.success` | `oauth_callback()` after JWT issued | actor=did, handle, ip |

| `login.new_user` | `oauth_callback()` → redirect to signup | actor=did, ip |

| `signup.success` | `signup()` after `user_model.create()` | actor=did, username, ip |

| `consent.granted` | `_handle_consent_post()` action=approve | actor=did, wiki_slug, client_id, ip |

| `consent.denied` | `_handle_consent_post()` action=deny | actor=did, wiki_slug, client_id, ip |

| `logout` | `oauth_logout()` | actor=did, ip |

| `rate_limit.hit` | `ratelimit_handler()` (429) | ip, path |

| Event | Method | Fields |

|---|---|---|

| `wiki.created` | `_create_wiki()` return 201 | actor=did, slug |

| `wiki.deleted` | `_delete_wiki()` return 200 | actor=did, slug |

| `token.regenerated` | `_regenerate_token()` return 200 | actor=did, slug |

| `rate_limit.hit` | 429 block in `__call__()` | ip, method, path |

| Event | Location | Fields |

|---|---|---|

| `auth.bearer_invalid` | `_resolve_bearer_token()` raises AuthError 401 | ip, wiki_slug |

| `auth.bearer_mismatch` | `_resolve_bearer_token()` raises AuthError 403 | ip, wiki_slug |

| `rate_limit.hit` | 429 block in `__call__()` | ip, wiki_slug |

**Not logged:** ACL flag changes (allow_read, allow_write, is_admin, is_approved). These happen inside otterwiki's admin UI with no current hook point. Deferred — track as a follow-on once otterwiki lifecycle hooks or the per-wiki DB plan is in place.

Structured JSON, one object per line, emitted via Python stdlib `logging` to stdout → systemd journal (already configured). No new log file or rotation needed — journal handles retention (30-day, 500MB cap per `robot-journald.conf`).

Fields:

- `ts` — UTC ISO-8601

- `event` — dot-namespaced string (see tables above)

- `actor_did` — DID of the acting user, or null for anonymous/system

- `actor_handle` — AT Protocol handle, or null

- `wiki_slug` — target wiki, or null for platform-level events

- `client_id` — OAuth client_id for consent events, else null

- `outcome` — `"success"` | `"failure"` | `"blocked"`

- `ip` — client IP (from `request.remote_addr` in Flask, or `get_client_ip(environ)` in WSGI middleware)

**PII note:** IP addresses are PII. They are logged for security purposes (rate limit forensics, abuse investigation). Journal retention is 30 days — no change needed. Do not log full handles in combination with IPs in any external/forwarded log sink.

A thin wrapper around stdlib logging. No new dependencies.

import logging, json

from datetime import datetime, timezone

_audit = logging.getLogger("robot.audit")

def log(event: str, *, actor_did=None, actor_handle=None,

wiki_slug=None, client_id=None, outcome="success", ip=None):

_audit.info(json.dumps({

"ts": datetime.now(timezone.utc).isoformat(),

"event": event,

"actor_did": actor_did,

"actor_handle": actor_handle,

"wiki_slug": wiki_slug,

"client_id": client_id,

"outcome": outcome,

"ip": ip,

}))

The logger name `robot.audit` lets operators filter with `journalctl -u robot-auth SYSLOG_IDENTIFIER=robot-auth | grep robot.audit` or similar.

**`app/auth_server.py`** — add `from app import audit` (or `from app.audit import log as audit_log`) and call `audit_log(...)` at the points noted in the events table. Most insertions are single lines immediately after the decision that determines the outcome. The `ratelimit_handler()` at the bottom of `create_app()` is the single place to cover all rate limit hits on the auth server.

**`app/management/routes.py`** — `ManagementMiddleware.__call__()` already has the 429 path. `_create_wiki()` and `_delete_wiki()` return tuples — log immediately before `return`. `actor_did` comes from `user.user_did`, `ip` from `get_client_ip(environ)` (already imported).

**`app/resolver.py`** — `TenantResolver._resolve_bearer_token()` raises `AuthError` on invalid/mismatched tokens — log before raising. The 429 block in `__call__()` already has `client_ip`. No logging in `_permissions_for_user()` — permission derivation is not itself an audit event.

- Flask routes: `request.remote_addr` (ProxyFix is already wired in `create_app()`)

- WSGI middleware: `get_client_ip(environ)` from `app.rate_limit` (already imported in both `routes.py` and `resolver.py`)

Cross-service correlation (e.g., tracing a consent grant through auth → resolver → MCP) would require propagating a request ID header. Deferred — the audit events are service-scoped and the `actor_did` + `ts` + `wiki_slug` triple is sufficient for forensics at this scale.

1. **No new service file changes needed.** All services already emit stdout to the journal (`StandardOutput=journal`). The `robot.audit` logger will appear in the same journal unit as the service that emits it.

2. **Log level configuration.** Add `AUDIT_LOG_LEVEL=INFO` to `ansible/roles/deploy/templates/robot.env.j2` and wire it in `app/audit.py` (`logging.basicConfig` or the app's existing logging setup). The default `INFO` level is correct; `DEBUG` should never emit audit records.

3. **No logrotate role needed.** `ansible/roles/logging/` already configures journald with 30-day retention and 500MB cap — sufficient.

4. **Future:** if a SIEM or external log forwarder is added, `journalctl -o json -u robot-auth -u robot-api -u robot-mcp` can be tailed. No Ansible change required at that point beyond a forwarding role.

- ACL flag changes via otterwiki admin UI — needs lifecycle hook or per-wiki DB plan

- Token issuance/refresh events for the ATProto OAuth session — currently no post-refresh hook; low priority since the platform JWT (24h) is the user-facing credential

- Feeding into a monitoring dashboard — tracked separately

- Structured log querying / alerting — revisit when user base grows beyond single-digit wikis