Phase 5: Föderations-Endpunkte — Cards ist föderierter Peer

Endpoints (alle Pfade aus app-manifest.json):
- POST /api/v1/share/receive — User-JWT-Auth, ShareEnvelope-Strict-
  Validation (cross-user-forbidden), Recipient-Match, Type-Accept-
  Lookup über Manifest, Payload-Schema-Validation, Handler-Dispatch
- POST /api/v1/tools/:name — User-JWT, dispatch nach `cards.create`
  und `cards.search` mit Tool-Schemas aus @cards/domain
- GET /api/v1/search — User-JWT, ILIKE auf cards.fields jsonb +
  decks.name, baut SearchResultEnvelope für mana-search-Aggregator
- GET /api/v1/dsgvo/export?user_id=… — Service-Key, voll-Bundle aller
  Cards-Daten des Users (decks, cards, reviews, study_sessions, tags,
  media_refs, import_jobs)
- POST /api/v1/dsgvo/delete — Service-Key, kaskadiert via FK-Cascade
  decks → cards → reviews/media_refs/card_tags/tags/study_sessions
  plus separates Cleanup von import_jobs

Share-Handlers (apps/api/src/share-handlers/):
- create_card_from_quote (mana/quote → front=text, back=source)
- save_link_as_card (mana/url → front=title, back=url+description)
- create_card_from_text (mana/text → front=erste-zeile, back=rest)
Alle landen via ensureInboxDeck() in einem auto-erstellten "Inbox"-Deck
pro User, inklusive automatischer FSRS-Reviews-Init in Transaktion.

Lokales Protocol-Mirror in @cards/domain/src/protocol/ (envelope,
payloads, search): TEMPORARY-Markierung mit Swap-Plan auf
@mana/shared-share-protocol via Verdaccio sobald NPM_AUTH_TOKEN da ist.
Spec-strict — UUID für user_id, ULID für share_id, Crockford-Base32.

Service-Key-Middleware mit constant-time-Compare gegen
process.env.CARDS_DSGVO_SERVICE_KEY (Phase F-1: ersetzt durch
mana-auth.app_service_keys-Lookup).

Tests:
- 70 Vitest-Tests grün (27 cards-domain + 43 apps/api):
  - share.test.ts: Auth-Gate, Cross-User-Sperre, User-Mismatch (403),
    Wrong-Recipient (422), Unknown-Type (422), Invalid-Payload (422),
    Wrapped { envelope, delivery_token }-Body akzeptiert
  - tools.test.ts: Auth, Unknown-Tool (404), cards.create-Validation,
    cards.search-Envelope-Shape
  - search.test.ts: Auth, Missing-Query (422), Query-too-long (422),
    Envelope-Version 0.1 + envelope-Felder
  - dsgvo.test.ts: Service-Key-Gate (401), Missing-User-ID (400),
    Export-Bundle-Shape, Delete-Counts, Key-not-configured (500)
- pnpm run type-check ✅ 4/4 packages
- E2E-Smoke gegen Postgres: Quote-Share→Inbox-Deck→Karte→Search-Hit→
  DSGVO-Export+Delete-Roundtrip clean (alle 3 Tabellen 0 nach delete)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

apps/api/tests/dsgvo.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { Hono } from 'hono';
+
+import { dsgvoRouter } from '../src/routes/dsgvo.ts';
+import type { CardsDb } from '../src/db/connection.ts';
+
+const ORIG_ENV = process.env.CARDS_DSGVO_SERVICE_KEY;
+const TEST_KEY = 'msk_test_dsgvo_key_42';
+
+beforeEach(() => {
+	process.env.CARDS_DSGVO_SERVICE_KEY = TEST_KEY;
+});
+
+afterEach(() => {
+	if (ORIG_ENV === undefined) {
+		delete process.env.CARDS_DSGVO_SERVICE_KEY;
+	} else {
+		process.env.CARDS_DSGVO_SERVICE_KEY = ORIG_ENV;
+	}
+});
+
+function buildApp() {
+	const stub = {
+		select: () => ({ from: () => ({ where: () => [] as never[] }) }),
+		delete: () => ({ where: () => ({ returning: async () => [] }) }),
+		transaction: async (fn: (tx: unknown) => unknown) =>
+			fn({
+				delete: () => ({ where: () => ({ returning: async () => [] }) }),
+			}),
+	};
+	const app = new Hono();
+	app.route('/api/v1/dsgvo', dsgvoRouter({ db: stub as unknown as CardsDb }));
+	return { app };
+}
+
+describe('dsgvoRouter — Service-Key-Gate', () => {
+	it('GET /export ohne Service-Key ist 401', async () => {
+		const { app } = buildApp();
+		const res = await app.request('/api/v1/dsgvo/export?user_id=u-1');
+		expect(res.status).toBe(401);
+	});
+
+	it('POST /delete mit falschem Key ist 401', async () => {
+		const { app } = buildApp();
+		const res = await app.request('/api/v1/dsgvo/delete', {
+			method: 'POST',
+			headers: { 'X-Service-Key': 'wrong', 'Content-Type': 'application/json' },
+			body: JSON.stringify({ user_id: 'u-1' }),
+		});
+		expect(res.status).toBe(401);
+	});
+
+	it('GET /export mit Key + ohne user_id ist 400', async () => {
+		const { app } = buildApp();
+		const res = await app.request('/api/v1/dsgvo/export', {
+			headers: { 'X-Service-Key': TEST_KEY },
+		});
+		expect(res.status).toBe(400);
+	});
+
+	it('GET /export mit Key + user_id liefert JSON-Bundle', async () => {
+		const { app } = buildApp();
+		const res = await app.request('/api/v1/dsgvo/export?user_id=u-1', {
+			headers: { 'X-Service-Key': TEST_KEY },
+		});
+		expect(res.status).toBe(200);
+		const body = (await res.json()) as {
+			user_id: string;
+			app: string;
+			data: { decks: unknown[]; cards: unknown[]; reviews: unknown[] };
+		};
+		expect(body.user_id).toBe('u-1');
+		expect(body.app).toBe('cards');
+		expect(Array.isArray(body.data.decks)).toBe(true);
+		expect(Array.isArray(body.data.cards)).toBe(true);
+		expect(Array.isArray(body.data.reviews)).toBe(true);
+	});
+
+	it('POST /delete mit Key + user_id liefert counts', async () => {
+		const { app } = buildApp();
+		const res = await app.request('/api/v1/dsgvo/delete', {
+			method: 'POST',
+			headers: { 'X-Service-Key': TEST_KEY, 'Content-Type': 'application/json' },
+			body: JSON.stringify({ user_id: 'u-1' }),
+		});
+		expect(res.status).toBe(200);
+		const body = (await res.json()) as {
+			deleted: boolean;
+			user_id: string;
+			counts: { decks: number; import_jobs: number };
+		};
+		expect(body.deleted).toBe(true);
+		expect(body.user_id).toBe('u-1');
+		expect(body.counts.decks).toBe(0);
+		expect(body.counts.import_jobs).toBe(0);
+	});
+});
+
+describe('dsgvoRouter — Key-not-configured Pfad', () => {
+	it('Wenn ENV fehlt → 500 service_key_not_configured', async () => {
+		delete process.env.CARDS_DSGVO_SERVICE_KEY;
+		const { app } = buildApp();
+		const res = await app.request('/api/v1/dsgvo/export?user_id=u-1', {
+			headers: { 'X-Service-Key': 'whatever' },
+		});
+		expect(res.status).toBe(500);
+		const body = (await res.json()) as { error: string };
+		expect(body.error).toBe('service_key_not_configured');
+	});
+});

apps/api/tests/search.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { Hono } from 'hono';
+
+import { searchRouter } from '../src/routes/search.ts';
+import type { CardsDb } from '../src/db/connection.ts';
+
+function buildApp() {
+	const stub = {
+		select: () => ({
+			from: () => ({
+				innerJoin: () => ({
+					where: () => ({ orderBy: () => ({ limit: () => [] }) }),
+				}),
+			}),
+		}),
+	};
+	const app = new Hono();
+	app.route('/api/v1/search', searchRouter({ db: stub as unknown as CardsDb }));
+	return { app };
+}
+
+describe('searchRouter — Auth-Gate', () => {
+	it('GET ohne X-User-Id ist 401', async () => {
+		const { app } = buildApp();
+		const res = await app.request('/api/v1/search?q=foo');
+		expect(res.status).toBe(401);
+	});
+});
+
+describe('searchRouter — Query-Validation', () => {
+	it('GET ohne q ist 422', async () => {
+		const { app } = buildApp();
+		const res = await app.request('/api/v1/search', {
+			headers: { 'X-User-Id': 'u-1' },
+		});
+		expect(res.status).toBe(422);
+	});
+
+	it('GET mit q über 500 Zeichen ist 422', async () => {
+		const { app } = buildApp();
+		const long = 'x'.repeat(501);
+		const res = await app.request(`/api/v1/search?q=${encodeURIComponent(long)}`, {
+			headers: { 'X-User-Id': 'u-1' },
+		});
+		expect(res.status).toBe(422);
+	});
+
+	it('GET mit gültigem q liefert SearchResultEnvelope', async () => {
+		const { app } = buildApp();
+		const res = await app.request('/api/v1/search?q=Konfuzius', {
+			headers: { 'X-User-Id': 'u-1' },
+		});
+		expect(res.status).toBe(200);
+		const body = (await res.json()) as {
+			envelope_version: string;
+			query: string;
+			app: string;
+			results: unknown[];
+			partial: boolean;
+		};
+		expect(body.envelope_version).toBe('0.1');
+		expect(body.query).toBe('Konfuzius');
+		expect(body.app).toBe('cards');
+		expect(Array.isArray(body.results)).toBe(true);
+		expect(body.partial).toBe(false);
+	});
+});

apps/api/tests/share.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect } from 'vitest';
+import { Hono } from 'hono';
+
+import { shareRouter } from '../src/routes/share.ts';
+import type { CardsDb } from '../src/db/connection.ts';
+
+function buildApp() {
+	const stub = {} as CardsDb;
+	const app = new Hono();
+	app.route('/api/v1/share', shareRouter({ db: stub }));
+	return { app };
+}
+
+const userA = '00000000-0000-0000-0000-00000000aaaa';
+const userB = '00000000-0000-0000-0000-00000000bbbb';
+
+function envelope(overrides: Record<string, unknown> = {}) {
+	return {
+		envelope_version: '0.1',
+		share_id: '01HZ0EJW6V6N4SM3X5RHKR8B5T', // ULID-Pattern
+		from: {
+			app: 'zitate',
+			app_version: '1.0.0',
+			user_id: userA,
+			timestamp: new Date().toISOString(),
+		},
+		to: {
+			app: 'cards',
+			user_id: userA,
+		},
+		type: 'mana/quote',
+		payload: { text: 'Lernen ohne Nachdenken ist verlorene Mühe', source: 'Konfuzius' },
+		intent: 'user_action',
+		consent_recorded_at: new Date().toISOString(),
+		...overrides,
+	};
+}
+
+describe('shareRouter — Auth-Gate', () => {
+	it('POST /receive ohne X-User-Id ist 401', async () => {
+		const { app } = buildApp();
+		const res = await app.request('/api/v1/share/receive', {
+			method: 'POST',
+			body: JSON.stringify(envelope()),
+		});
+		expect(res.status).toBe(401);
+	});
+});
+
+describe('shareRouter — Envelope-Validation', () => {
+	it('Body kein JSON → 400', async () => {
+		const { app } = buildApp();
+		const res = await app.request('/api/v1/share/receive', {
+			method: 'POST',
+			headers: { 'X-User-Id': userA, 'Content-Type': 'application/json' },
+			body: 'not-json',
+		});
+		expect(res.status).toBe(400);
+	});
+
+	it('Cross-User-Share ist 422 (envelope_invalid)', async () => {
+		const { app } = buildApp();
+		const env = envelope({
+			to: { app: 'cards', user_id: userB }, // anderer User → Cross-User
+		});
+		const res = await app.request('/api/v1/share/receive', {
+			method: 'POST',
+			headers: { 'X-User-Id': userA, 'Content-Type': 'application/json' },
+			body: JSON.stringify(env),
+		});
+		expect(res.status).toBe(422);
+		const body = (await res.json()) as { reason: string };
+		expect(body.reason).toBe('envelope_invalid');
+	});
+
+	it('User-Mismatch (envelope.to.user_id != X-User-Id) ist 403', async () => {
+		const { app } = buildApp();
+		const env = envelope({
+			from: { ...envelope().from, user_id: userB },
+			to: { app: 'cards', user_id: userB },
+		});
+		const res = await app.request('/api/v1/share/receive', {
+			method: 'POST',
+			headers: { 'X-User-Id': userA, 'Content-Type': 'application/json' },
+			body: JSON.stringify(env),
+		});
+		expect(res.status).toBe(403);
+		const body = (await res.json()) as { reason: string };
+		expect(body.reason).toBe('user_id_mismatch');
+	});
+
+	it('Wrong-Recipient (to.app != cards) ist 422', async () => {
+		const { app } = buildApp();
+		const env = envelope({ to: { app: 'memoro', user_id: userA } });
+		const res = await app.request('/api/v1/share/receive', {
+			method: 'POST',
+			headers: { 'X-User-Id': userA, 'Content-Type': 'application/json' },
+			body: JSON.stringify(env),
+		});
+		expect(res.status).toBe(422);
+		const body = (await res.json()) as { reason: string };
+		expect(body.reason).toBe('wrong_recipient');
+	});
+
+	it('Unbekannter Type ist 422', async () => {
+		const { app } = buildApp();
+		const env = envelope({ type: 'mana/unknown-thing', payload: {} });
+		const res = await app.request('/api/v1/share/receive', {
+			method: 'POST',
+			headers: { 'X-User-Id': userA, 'Content-Type': 'application/json' },
+			body: JSON.stringify(env),
+		});
+		expect(res.status).toBe(422);
+		const body = (await res.json()) as { reason: string };
+		expect(body.reason).toBe('type_not_accepted');
+	});
+
+	it('Quote-Payload ohne text ist 422', async () => {
+		const { app } = buildApp();
+		const env = envelope({ payload: { source: 'X' } });
+		const res = await app.request('/api/v1/share/receive', {
+			method: 'POST',
+			headers: { 'X-User-Id': userA, 'Content-Type': 'application/json' },
+			body: JSON.stringify(env),
+		});
+		expect(res.status).toBe(422);
+		const body = (await res.json()) as { reason: string };
+		expect(body.reason).toBe('invalid_payload');
+	});
+
+	it('Wrapped Body { envelope, delivery_token } akzeptiert', async () => {
+		const { app } = buildApp();
+		const env = envelope({ to: { app: 'memoro', user_id: userA } });
+		const res = await app.request('/api/v1/share/receive', {
+			method: 'POST',
+			headers: { 'X-User-Id': userA, 'Content-Type': 'application/json' },
+			body: JSON.stringify({ envelope: env, delivery_token: 'tok_xyz' }),
+		});
+		// Wrong-Recipient nicht 422 → Wrapper wurde korrekt unwrapped (sonst wäre es envelope_invalid)
+		expect(res.status).toBe(422);
+		const body = (await res.json()) as { reason: string };
+		expect(body.reason).toBe('wrong_recipient');
+	});
+});

apps/api/tests/tools.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest';
+import { Hono } from 'hono';
+
+import { toolsRouter } from '../src/routes/tools.ts';
+import type { CardsDb } from '../src/db/connection.ts';
+
+function buildApp() {
+	const stub = {
+		select: () => ({
+			from: () => ({
+				where: () => ({ limit: () => [] }),
+				innerJoin: () => ({
+					where: () => ({ orderBy: () => ({ limit: () => [] }) }),
+				}),
+			}),
+		}),
+	};
+	const app = new Hono();
+	app.route('/api/v1/tools', toolsRouter({ db: stub as unknown as CardsDb }));
+	return { app };
+}
+
+describe('toolsRouter — Auth-Gate', () => {
+	it('POST /:name ohne X-User-Id ist 401', async () => {
+		const { app } = buildApp();
+		const res = await app.request('/api/v1/tools/cards.create', {
+			method: 'POST',
+			body: '{}',
+		});
+		expect(res.status).toBe(401);
+	});
+});
+
+describe('toolsRouter — Tool-Dispatch', () => {
+	it('Unbekanntes Tool ist 404', async () => {
+		const { app } = buildApp();
+		const res = await app.request('/api/v1/tools/cards.unknown', {
+			method: 'POST',
+			headers: { 'X-User-Id': 'u-1', 'Content-Type': 'application/json' },
+			body: '{}',
+		});
+		expect(res.status).toBe(404);
+		const body = (await res.json()) as { error: string };
+		expect(body.error).toBe('unknown_tool');
+	});
+
+	it('cards.create mit invalid input ist 422', async () => {
+		const { app } = buildApp();
+		const res = await app.request('/api/v1/tools/cards.create', {
+			method: 'POST',
+			headers: { 'X-User-Id': 'u-1', 'Content-Type': 'application/json' },
+			body: '{}',
+		});
+		expect(res.status).toBe(422);
+	});
+
+	it('cards.create mit gültigem Input erreicht Deck-Lookup (404 bei stub)', async () => {
+		const { app } = buildApp();
+		const res = await app.request('/api/v1/tools/cards.create', {
+			method: 'POST',
+			headers: { 'X-User-Id': 'u-1', 'Content-Type': 'application/json' },
+			body: JSON.stringify({
+				deck_id: 'd-1',
+				type: 'basic',
+				fields: { front: 'Q', back: 'A' },
+			}),
+		});
+		expect(res.status).toBe(404);
+		const body = (await res.json()) as { error: string };
+		expect(body.error).toBe('deck_not_found');
+	});
+
+	it('cards.search ohne query ist 422', async () => {
+		const { app } = buildApp();
+		const res = await app.request('/api/v1/tools/cards.search', {
+			method: 'POST',
+			headers: { 'X-User-Id': 'u-1', 'Content-Type': 'application/json' },
+			body: '{}',
+		});
+		expect(res.status).toBe(422);
+	});
+
+	it('cards.search mit gültigem query → 200 mit envelope-Shape', async () => {
+		const { app } = buildApp();
+		const res = await app.request('/api/v1/tools/cards.search', {
+			method: 'POST',
+			headers: { 'X-User-Id': 'u-1', 'Content-Type': 'application/json' },
+			body: JSON.stringify({ query: 'Konfuzius' }),
+		});
+		expect(res.status).toBe(200);
+		const body = (await res.json()) as { query: string; results: unknown[]; app: string };
+		expect(body.query).toBe('Konfuzius');
+		expect(Array.isArray(body.results)).toBe(true);
+		expect(body.app).toBe('cards');
+	});
+});