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/src/lib/inbox-deck.ts

@@ -0,0 +1,40 @@
+import { and, eq } from 'drizzle-orm';
+
+import type { CardsDb } from '../db/connection.ts';
+import { decks } from '../db/schema/index.ts';
+import { ulid } from './ulid.ts';
+
+/** Stabiler Name des Inbox-Decks pro User. Auto-Created bei erstem Share. */
+export const INBOX_DECK_NAME = 'Inbox';
+
+/**
+ * Holt das Inbox-Deck eines Users oder legt es neu an.
+ * Wird von allen Share-Receive-Handlern benutzt — eingehende
+ * Shares landen immer in der Inbox, der User kann sie später
+ * in andere Decks umsortieren.
+ */
+export async function ensureInboxDeck(db: CardsDb, userId: string) {
+	const [existing] = await db
+		.select()
+		.from(decks)
+		.where(and(eq(decks.userId, userId), eq(decks.name, INBOX_DECK_NAME)))
+		.limit(1);
+	if (existing) return existing;
+
+	const now = new Date();
+	const [created] = await db
+		.insert(decks)
+		.values({
+			id: ulid(),
+			userId,
+			name: INBOX_DECK_NAME,
+			description: 'Eingehende Shares aus anderen Apps. Sortiere sie in eigene Decks um.',
+			color: '#888888',
+			visibility: 'private',
+			fsrsSettings: {},
+			createdAt: now,
+			updatedAt: now,
+		})
+		.returning();
+	return created;
+}

apps/api/src/lib/search.ts

@@ -0,0 +1,76 @@
+import { and, eq, sql } from 'drizzle-orm';
+
+import type { CardsDb } from '../db/connection.ts';
+import { cards, decks } from '../db/schema/index.ts';
+
+const APP_BASE_URL = process.env.CARDS_PUBLIC_URL ?? 'https://cardecky.mana.how';
+
+export type SearchHit = {
+	id: string;
+	type: 'card';
+	title: string;
+	snippet?: string;
+	link: string;
+	score: number;
+	created_at?: string;
+	updated_at?: string;
+};
+
+/**
+ * MVP-Suche: case-insensitive ILIKE auf der `fields` JSONB-Spalte
+ * und auf Deck-Name. Vector-/Trigram-Suche kommt später (eigener
+ * Index, separate Phase).
+ *
+ * Score-Heuristik MVP: 1.0 für Treffer (kein Ranking), absteigend
+ * sortiert nach updated_at. Echtes Scoring wenn pg_trgm/vector
+ * eingerichtet sind.
+ */
+export async function searchUserCards(
+	db: CardsDb,
+	userId: string,
+	query: string,
+	maxResults = 30
+): Promise<{ hits: SearchHit[]; tookMs: number }> {
+	const t0 = Date.now();
+	const pattern = `%${query.replace(/[%_]/g, '\\$&')}%`;
+
+	const rows = await db
+		.select({
+			id: cards.id,
+			deckId: cards.deckId,
+			fields: cards.fields,
+			createdAt: cards.createdAt,
+			updatedAt: cards.updatedAt,
+			deckName: decks.name,
+		})
+		.from(cards)
+		.innerJoin(decks, eq(decks.id, cards.deckId))
+		.where(
+			and(
+				eq(cards.userId, userId),
+				sql`(${cards.fields}::text ILIKE ${pattern} OR ${decks.name} ILIKE ${pattern})`
+			)
+		)
+		.orderBy(sql`${cards.updatedAt} DESC`)
+		.limit(Math.min(maxResults, 200));
+
+	const hits = rows.map((r): SearchHit => {
+		const fields = r.fields as Record<string, string>;
+		const front = fields.front ?? '';
+		const back = fields.back ?? '';
+		const title = front.split('\n')[0]?.slice(0, 200) ?? r.deckName;
+		const snippet = back.slice(0, 200) || undefined;
+		return {
+			id: r.id,
+			type: 'card',
+			title: title || '(leer)',
+			snippet,
+			link: `${APP_BASE_URL}/c/${r.id}`,
+			score: 1.0,
+			created_at: r.createdAt.toISOString(),
+			updated_at: r.updatedAt.toISOString(),
+		};
+	});
+
+	return { hits, tookMs: Date.now() - t0 };
+}