@tpsdev-ai/flair 0.20.1 → 0.21.0

package/README.md

@@ -100,6 +100,8 @@ Flair fixes that with three primitives:
 
 Built on [Harper](https://harper.fast). Single process. No sidecars. Zero external API calls for embeddings. **[Supply-chain policy](docs/supply-chain-policy.md)** documents the bake-time + dep-pinning we run to keep this honest.
 
+See **[DESIGN.md](DESIGN.md)** for the design invariants behind these three primitives — why they're shaped the way they are.
+
 ## How It Works
 
 Flair is a native [Harper v5](https://harper.fast) application. Harper handles HTTP, persistence (RocksDB), and application logic in a single process.
@@ -152,7 +154,7 @@ Entity-to-entity triples with temporal bounds. Model structured knowledge — "A
 Subscribe to memory or soul changes via WebSocket/SSE. Useful for dashboards, cross-agent sync, or audit trails.
 
 ### Multi-Agent
-One Flair instance serves any number of agents. Each agent has its own keys, memories, and soul. Agents can't read each other's data without explicit access grants.
+One Flair instance serves any number of agents. Each agent has its own keys, memories, and soul. Reads are open within the org: any agent can read any other agent's non-private memory, no grant required — `private` is the one owner-only exception. See [DESIGN.md](DESIGN.md#access-model-open-within-the-org-closed-at-the-federation-edge) for the full model.
 
 ### OAuth 2.1 Authorization Server
 Built-in OAuth 2.1 server with PKCE, dynamic client registration, and a standards-compliant token endpoint. Agents and services can delegate auth to Flair without a separate IdP.
@@ -238,6 +240,29 @@ flair uninstall     # Remove the service (keeps data)
 flair uninstall --purge  # Remove everything including data and keys
 ```
 
+### Upgrading
+
+`flair status` and `flair doctor` both check your installed version against the latest published release (cached, offline-tolerant — this never blocks or fails either command) and print a nudge when you're behind:
+
+```
+⚠ flair 0.16.1 is behind — latest is 0.20.1 (4 releases behind). Upgrade: npm i -g @tpsdev-ai/flair@latest
+```
+
+To upgrade:
+
+```bash
+npm install -g @tpsdev-ai/flair@latest
+
+# Or check what's outdated across the whole toolchain (flair, flair-mcp, the
+# openclaw-flair plugin) without installing anything:
+flair upgrade --check
+
+# Then apply:
+flair upgrade
+```
+
+`flair upgrade` also restarts the running instance for you with `--restart`. If you deployed Flair to a Harper Fabric cluster (rather than running it locally), use `flair upgrade --target <fabric-url>` instead — see `flair upgrade --help`.
+
 ### Advanced / manual setup
 
 Prefer to drive each step yourself, or scripting an unattended setup? Run `flair init --no-mcp` to bootstrap the instance + agent without wiring any MCP clients, then drive each step on its own:
@@ -457,10 +482,10 @@ See [SECURITY.md](SECURITY.md) for the full security model, threat analysis, and
 
 **Key points:**
 - Ed25519 cryptographic identity — agents sign every request
-- Collection-level data isolation — agents can't read each other's memories
+- Reads are open within the org — any agent can read any other agent's non-private memory, no grant required; `private` is the one owner-only exception (see [DESIGN.md](DESIGN.md))
 - Admin password auto-generated on init, stored at `~/.flair/admin-pass` (mode 0600)
 - Key rotation via `flair agent rotate-key`
-- Cross-agent access requires explicit grants
+- Writes are always agent-scoped — an agent can only write its own records
 
 ## Development
 
@@ -479,7 +504,7 @@ Integration tests spin up a real Harper instance on a random port, run the test
 | Category | Tests | What's covered |
 |----------|-------|----------------|
 | **Auth & Identity** | auth-middleware, auth-scoping, key-paths-and-rotation | Ed25519 signature verification, agent isolation, key rotation |
-| **Memory** | data-scoping, backup-restore, agent-remove-and-grants | Cross-agent access denied, data durability, grant lifecycle |
+| **Memory** | data-scoping, backup-restore, agent-remove-and-grants | Private-memory exclusion, open within-org read scoping, data durability, grant lifecycle |
 | **Content Safety** | content-safety | Prompt injection detection, identity hijacking, format injection, exfiltration patterns |
 | **Search** | temporal-scoring, embeddings | Temporal decay, relevance scoring, embedding generation |
 | **Rate Limiting** | rate-limiter | Per-agent rate limiting, bucket isolation |

package/SECURITY.md

@@ -2,8 +2,10 @@
 
 ## Overview
 
-Flair uses cryptographic identity (Ed25519) for agent authentication and
-collection-level scoping to enforce data isolation between agents.
+Flair uses cryptographic identity (Ed25519) for agent authentication. Within
+an org, memory reads are open — agents see each other's non-private memories —
+while writes are isolated per agent and private memories stay strictly
+owner-only. The hard access boundary is the federation edge (cross-instance).
 
 ## Authentication
 
@@ -37,25 +39,29 @@ at Harper startup. **It is never stored on the filesystem by Flair.**
 
 ## Data Scoping
 
-### Memory Isolation
+### Memory Read/Write Model
 
-Each agent can only read and write its own memories. This is enforced at
-the database layer (Harper resource `search()` override), not application
-logic:
+Reads are open **within an org**; writes are isolated per agent. Enforced at
+the database layer (Harper resource `search()` override via a single
+centralized read-scope rule), not application logic:
 
-- `GET /Memory/` — returns only the authenticated agent's memories
-- `POST /Memory` — writes with the authenticated agent's ID
-- `POST /MemorySearch` — searches only the authenticated agent's memories
+- `GET /Memory/` — returns the authenticated agent's own memories (any
+  visibility) plus every **non-private** memory in the org
+- `POST /MemorySearch` — same read scope: own memories plus all non-private
+- `POST /Memory` — writes are attributed to the authenticated agent; an
+  agent cannot write as another (write isolation)
 
-### Cross-Agent Access
+**Private memories are strictly owner-only** — a memory written with
+`visibility: private` is returned only to its author, never to another agent.
 
-Explicit grants allow one agent to read another's memories:
+### Cross-Agent Access (within an org)
 
-```
-MemoryGrant { fromAgentId, toAgentId, scope: "read" }
-```
-
-Grants are created by admin or by the granting agent.
+Within an org, an agent reads every non-private memory directly — no grant
+required. This is deliberate: the goal is relevance (surface what's useful to
+the org) over secrecy. A writer keeps something private by marking it
+`visibility: private`, which keeps it strictly owner-only. The access boundary
+that stays hard is the **federation edge** (cross-instance / cross-org), not
+within-org reads.
 
 ### Admin Bypass
 
@@ -88,8 +94,12 @@ public key in Flair, and backs up the old key as `<agentId>.key.bak`.
 
 - **Agent impersonation:** Ed25519 signatures prevent one agent from
   acting as another without possessing the private key.
-- **Cross-agent data leakage:** Collection-level scoping ensures agents
-  can only query their own data.
+- **Private-memory leakage:** memories marked `visibility: private` are
+  strictly owner-only and never returned to another agent. Non-private
+  memories are intentionally readable within the org (by design, not
+  leakage); the cross-instance boundary is the federation edge.
+- **Write forgery:** writes are attributed to the authenticated agent —
+  an agent cannot write memories as another.
 - **Replay attacks:** 30-second window + nonce deduplication.
 - **Privilege escalation via SQL:** SQL and GraphQL endpoints blocked
   for non-admin agents.