# Diagnostics, privacy and support bundles

ForgeFlow v0.3.2 records development-oriented diagnostics locally so failures
can be investigated without requesting the user's Gitea token, SSH key or
server password.

## Storage

Diagnostic events are stored beneath the Electron application-data directory in:

```text
diagnostics/forgeflow-YYYY-MM-DD.jsonl
```

The Diagnostics page displays an aliased path such as `<HOME>` rather than the
Windows account name. Files use restrictive permissions where the operating
system supports them.

Defaults:

- enabled;
- minimum level `info`;
- 14-day retention;
- 8 MB maximum per log segment;
- daily filenames with numbered rotation;
- ordered asynchronous writes;
- no application crash when diagnostic storage itself fails.

These values can be changed in **Diagnostics -> Recording policy**.

## What an event can contain

Useful fields include:

- UTC timestamp;
- level and stable event name;
- per-launch session identifier;
- operation or deployment request identifier;
- Git/Gitea operation outcome;
- HTTP status, duration and endpoint path without request headers;
- repository state and branch/SHA metadata;
- preflight result;
- sanitized exception name, code, message and stack;
- renderer crash or unhandled-rejection metadata.

ForgeFlow does not log IPC payloads, request authorization headers or Gitea
response bodies merely because a request was made.

## Redaction

Every event passes through a recursive sanitizer before it is written.
Redaction covers:

- the currently active Gitea token;
- token, password, authorization, credential, API-key, client-secret and
  encrypted-token object fields, including camelCase variants;
- bearer/token/basic authorization values in strings;
- common token query parameters;
- credentials embedded in URLs;
- PEM private-key blocks;
- known Gitea/Git hosting token patterns;
- Windows, macOS and Linux home-directory paths;
- application source path aliases;
- circular data structures and oversized strings.

Credential values are replaced with `[REDACTED]`; user paths use aliases such as
`<HOME>`.

## Support bundle

**Create diagnostic ZIP** exports a local archive containing:

```text
manifest.json
safety-audit.json
README.txt
system.json
diagnostics-status.json
configuration-sanitized.json
repositories-sanitized.json
operations-sanitized.json
preflight.json
context.json
logs/*.jsonl
```

The application returns the SHA-256 of the generated archive so a shared file
can be identified exactly.

### Excluded data

The bundle intentionally excludes:

- plaintext Gitea access tokens;
- Electron `safeStorage` encrypted-token blobs;
- request authorization headers;
- passwords and private keys;
- raw Gitea runner logs;
- arbitrary environment-variable dumps;
- full local file contents and Git diffs.

ForgeFlow does not automatically ingest or persist raw runner output. Job names,
statuses and safe operation summaries are stored locally; full runner output remains
available only in the trusted Gitea Actions interface when deeper server-side
investigation is necessary.

## Privacy modes

### Standard

Preserves repository names and user-facing identifiers. Local home paths and
credentials are still redacted. Use when the recipient already knows the
project context.

### Strict

Additionally replaces repository and user identifiers with deterministic
SHA-256-based aliases. Related events remain correlatable without revealing the
original names.

## Fail-closed bundle audit

Immediately before writing the archive, ForgeFlow scans every prepared entry
for:

- the known active runtime secret values;
- private-key begin markers;
- unredacted credentials embedded in HTTP(S) URLs.

The result is stored as `safety-audit.json`. When a finding remains, archive
creation is aborted and the unsafe ZIP is not written.

## Practical limitation

No generic logger can mathematically identify every unknown secret if a third-
party process prints an arbitrary value without a label or recognizable format.
ForgeFlow reduces this risk by not including raw runner logs, not recording IPC
payloads and applying both structured and textual redaction. Always inspect a
support bundle before sharing it, particularly when custom integrations have
been added.

## Development workflow after a failure

1. Reproduce the issue once when safe.
2. Note the approximate time and repository/environment.
3. Run the relevant preflight.
4. Export a Strict diagnostic bundle.
5. Keep the returned SHA-256 with the bug report.
6. Describe the visible action that failed.
7. Share no separate token, key or password.