# Storage Backends — Security Model

Three concerns drive the storage abstraction's security design:

1. **Credentials must never live on disk in config.**
2. **Path traversal must be impossible** — agents writing through the adapter cannot escape the configured root.
3. **Concurrent writes must not corrupt files.**

## 1. Credentials are env-var-only

`.aiwg/storage.config` is checked into git on most projects. It would be wrong to put `secret` or `apiKey` there — even one accidental commit pushes the credential into history.

The schema (`https://aiwg.io/schemas/storage.config.v1.json`) **actively rejects** credential-named properties at every nesting depth. The forbidden property names are:

```
token, password, secret, apiKey, api_key,
accessKey, accessKeyId, secretAccessKey
```

Loading a `storage.config` containing any of these throws an error pointing at the offending property path. This catches both the obvious case (`{ "backends": { "memory": { "token": "…" } } }`) and the sneaky case (`{ "backends": { "memory": { "extras": [{ "apiKey": "…" }] } } }`).

`aiwg doctor` runs the same recursive walk on the loaded config as defense-in-depth — schema validation alone can be bypassed by hand-rolled config edits.

### Where credentials *do* come from

Each backend documents its env-var (and optional OS-keychain) requirements:

| Backend        | Env var(s)                                                            |
| -------------- | --------------------------------------------------------------------- |
| `fs`           | none                                                                  |
| `obsidian`     | none (file-system access governed by OS permissions)                  |
| `logseq`       | `LOGSEQ_API_TOKEN` (only when `useApi: true`)                         |
| `notion`       | `NOTION_API_TOKEN` *(planned, #959)*                                  |
| `anythingllm`  | `ANYTHINGLLM_API_KEY` *(planned, #960)*                               |
| `fortemi`      | governed by AIWG MCP server config, not by `storage.config`; legacy storage only, not Fortemi Core index/search |
| `s3`           | AWS default credential chain *(planned, #962)*                        |
| `webdav`       | `AIWG_WEBDAV_USER` + `AIWG_WEBDAV_PASSWORD` or `AIWG_WEBDAV_TOKEN` *(planned, #963)* |

`aiwg storage list-backends` reports each backend's status. `aiwg doctor` does a reachability probe and reports clearly when a required env var is unset.

## 2. Path traversal rejection

Every adapter validates subsystem-relative paths at the boundary. The same five rules apply across `fs`, `obsidian`, and `logseq`:

| Rejected pattern         | Example          | Why                              |
| ------------------------ | ---------------- | -------------------------------- |
| `..` segments            | `../etc/passwd`  | Escapes subsystem root           |
| Leading `/`              | `/etc/passwd`    | Absolute path                    |
| Leading `~`              | `~/secrets.md`   | Home expansion                   |
| Backslashes              | `a\\b.md`        | Windows separator (POSIX bug)    |
| Empty                    | `""`             | Ambiguous                        |

Additionally, file-shaped backends refuse to touch the host application's config directory:
- `obsidian` rejects any path resolving into `<vault>/.obsidian/` — for read, write, delete, AND list (skipped during walk).
- `logseq` rejects any path resolving into `<graph>/logseq/`.

These rejections are tested per-adapter; see `test/unit/storage/{fs,obsidian,logseq}.test.ts`.

## 3. Atomic writes

Three places use atomic write-then-rename (or `O_APPEND`) semantics:

- **`fs` adapter `append()`** — uses Node's `fs.appendFile` which opens with `O_APPEND`. The kernel guarantees atomicity for writes ≤ `PIPE_BUF` (4096 bytes on Linux), which means concurrent appenders interleave at line granularity rather than racing read-then-write. (#976)
- **`aiwg activity-log append`** — prefers `adapter.append` when available; falls back to read-then-write only on backends that don't expose append.
- **`sandbox-registry` identity store** — writes to `<path>.tmp.<pid>` first, then renames onto the live path. SIGINT during save can no longer leave a half-written JSON file. (#969)

Async backends (Notion, AnythingLLM, Fortemi) have their own concurrency models and don't expose `append()`. The read-then-write fallback is harmless on them since they'd serialize requests at the API layer anyway.

## Defense in depth — `aiwg doctor`

`aiwg doctor` runs four checks on `.aiwg/storage.config`:

1. **Schema validation** — JSON Schema v1 conformance.
2. **Credential walk** — recursively rejects any property named in the forbidden list above.
3. **Reachability probe** — best-effort ping per backend (e.g., `obsidian --version`, `GET /api/v1/system` for AnythingLLM, vault existence for `obsidian`).
4. **Roots existence** — checks each `roots.<subsystem>` path actually exists for `fs` backends.

Failures print the property path, the issue, and a remediation hint. Run `aiwg doctor` after every `storage.config` edit and at the start of long sessions.

## What this *does not* protect against

- **An attacker with write access to your `storage.config`** can redirect AIWG writes anywhere on the filesystem (within the configured root rules). Treat `storage.config` like any other build-config file — review changes in PRs.
- **A misconfigured external backend** (wrong vault path, wrong workspace ID) writes to the wrong place. AIWG can't validate semantic correctness — only structural. Run `aiwg storage test <subsystem>` after any config change.
- **Backend-side authentication misconfiguration** (e.g., an Obsidian sync client also writing to the same vault folder) is outside AIWG's scope.

## Reporting issues

Security concerns about the storage system: file an issue at https://git.integrolabs.net/roctinam/aiwg/issues with the `security` label, or follow the project's responsible-disclosure process.