Federation ACL Test Design

Two new peer services in docker-compose.test.yml

Service	Ports	DB	Seed vault
app-peer2	20093 / 20094	test-peer2.sqlite3	testdata/seedvault2/
app-peer3	20095 / 20096	test-peer3.sqlite3	testdata/seedvault3/

Each peer has its own JWT secret, cookie name, and minio prefix to prevent session bleed. Both share the same embedding and minio services (same pattern as app-peer).

Seed notes (one per peer, free: true, unique strings for assertion)

testdata/seedvault2/peer2-note.md

---
title: Peer2 Note
free: true
---
Semi-private peer2 content for federation ACL testing.

testdata/seedvault3/peer3-note.md

---
title: Peer3 Note
free: true
---
Admin-only peer3 content for federation ACL testing.

Three KB-notes on hub (docs/demo/)

File	Frontmatter	Tier	kb_id	Points to
federation_kb.md (existing)	free: true	Open	peer	peer (20091)
federation_kb_semi.md (new)	subgraphs: federation-test	Semi-private	peer2	peer2 (20093)
federation_kb_private.md (new)	(none — no free, no subgraphs)	Admin-only	peer3	peer3 (20095)

federation_kb_private.md has no free: and no subgraphs: — readable only by admin. This is the strictest tier.

---

Why non-admin user, not a scoped admin token

Personal tokens inherit the full access of the creating user — there is no per-token subgraph scoping (confirmed in personal-tokens.spec.js). The only way to get a token with restricted subgraph access is to create a non-admin user and assign subgraphs via createUserSubgraphAccess. This is the same pattern used in tests 8/9 of personal-tokens.spec.js.

Scoped user setup (in beforeAll)

1. Create subgraph "federation-test" on hub → get subgraphId
2. Create non-admin user on hub (random email)
3. createUserSubgraphAccess(userId, [subgraphId])
4. graphqlSignIn(user) → isolatedCtx
5. createPersonalToken(user) → scopedToken

---

Setup

beforeAll:
  - sign into hub admin (hubRequest)
  - sign into peer2 admin (peer2Request)
  - sign into peer3 admin (peer3Request)
  - create federation-test subgraph on hub → subgraphId
  - create non-admin user on hub → assign federation-test subgraph → scopedToken
  - create admin personal token on hub → adminToken
  - create inbound secrets on peer2 and peer3
  - create outbound secrets on hub for peer2 and peer3
  - store outbound IDs for cleanup

afterAll:
  - revoke all created tokens and secrets
  - dispose all request contexts

All MCP calls use mcpCallFresh (fresh cookie-free context) so session cookies do not interfere with Bearer auth.

---

Group 1: search visibility (what KB-notes appear in local search results)

These tests call search on the hub and assert which KB-notes are (or are not) present in the result list by note path.

Test	Principal	Asserts
1.1	Anonymous	sees federation_kb (open), does NOT see federation_kb_semi or federation_kb_private
1.2	Scoped user	sees federation_kb and federation_kb_semi, does NOT see federation_kb_private
1.3	Admin	sees all three KB-notes

Assertion detail for 1.1 (privacy guarantee):

expect(text).not.toContain('federation_kb_semi');
expect(text).not.toContain('federation_kb_private');

The note path must not appear at all — not even as a "you don't have access" message.

---

Group 2: targeted routing (federated_search with explicit kb_id)

These tests assert what happens when a specific kb_id is requested by each principal.

Test	Principal	kb_id	Asserts
2.1	Anonymous	peer2	response matches /not.*(found|configured)/i
2.2	Anonymous	peer3	response matches /not.*(found|configured)/i
2.3	Scoped user	peer2	returns results containing peer2-note content
2.4	Scoped user	peer3	response matches /not.*(found|configured)/i
2.5	Admin	peer2	returns results containing peer2-note content
2.6	Admin	peer3	returns results containing peer3-note content

Critical assertion for 2.1 and 2.2 (existence must not leak):

// Must be "not configured", NOT "access denied" or "401"
expect(text.toLowerCase()).toMatch(/not.*(found|configured)/);
expect(text.toLowerCase()).not.toMatch(/access.denied|unauthorized|forbidden/);

A "permission denied" response reveals the node exists. "Not configured" is the correct response for any kb_id that the caller cannot access — indistinguishable from a kb_id that simply does not exist.

---

Group 3: fan-out (federated_search without kb_id)

Fan-out must only call peers whose KB-notes are accessible to the caller. This is enforced by accessibleKBNotes running before fanout() — the restricted peers never receive an HTTP call.

Test	Principal	Asserts
3.1	Anonymous	result does NOT contain peer2-note or peer3-note unique strings
3.2	Scoped user	result contains peer2-note content, does NOT contain peer3-note content
3.3	Admin	result contains peer2-note and peer3-note content

Assertion for 3.1 (no content leak via fan-out):

expect(text).not.toContain('Semi-private peer2 content');
expect(text).not.toContain('Admin-only peer3 content');

---

Group 4: revocation + ACL decoupling

This group tests that revoking an outbound secret and hiding a KB-note are independent operations. Revoking a secret does not affect who can see the KB-note in search — it only affects whether federation calls succeed.

Setup: start with admin access to peer2 (from Group 2 setup).

Test	Action	Asserts
4.1	Revoke outbound secret for peer2	federated_search(kb_id="peer2") by admin no longer returns peer2-note content
4.2	After revocation, admin searches hub	federation_kb_semi still appears in search results (ACL unchanged)
4.3	After revocation, scoped user searches hub	federation_kb_semi still appears in search results for scoped user

Why this matters: if a developer accidentally couples secret revocation to KB-note visibility (e.g. filtering accessibleKBNotes by whether a valid outbound secret exists), tests 4.2 and 4.3 will fail. The two concepts must stay independent.

Exact behavior after revocation (confirmed from cmd/server/main.go:FederationClient):

FederationClient checks HasFederationSecretForKBURL — if a secret was ever configured for that URL but is now revoked, it returns an explicit error rather than silently downgrading to anonymous:

"no active federation secret for kb_id %q; the configured secret may be revoked"

This is intentional: the hub refuses to silently downgrade a configured-private peer to anonymous access. The error is surfaced as an internal error response.

Test 4.1 assertion:

// response is an error or isError=true
const text = result.result?.content?.[0]?.text ?? result.error?.message ?? '';
expect(text.toLowerCase()).toMatch(/revoked|no active|secret/);
// NOT "not configured" — that would mean KB-note is inaccessible, but admin can still see it
expect(text.toLowerCase()).not.toMatch(/not.*(found|configured)/);

This also tests the important corollary: the "not configured" response and the "revoked secret" error are distinguishable to authorized callers (admin/scoped-user), but both look identical to anonymous callers (who see "not configured" in both cases because the KB-note itself is inaccessible to them).

---

New files

• testdata/seedvault2/peer2-note.md
• testdata/seedvault3/peer3-note.md
• docs/demo/federation_kb_semi.md
• docs/demo/federation_kb_private.md
• e2e/federation-acl.spec.js

Modified files

• docker-compose.test.yml — add app-peer2 and app-peer3 services

Existing files (unchanged)

• e2e/federation.spec.js — existing tests remain, no modifications
• e2e/personal-tokens.spec.js — existing tests remain, no modifications
• All Go source files — no backend changes needed; the ACL logic already exists

---