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>

packages/cards-domain/src/index.ts

@@ -9,4 +9,5 @@
 
 export * from './schemas/index.ts';
 export * from './fsrs.ts';
+export * from './protocol/index.ts';
 // export * from './cloze.ts';  // Phase 8 oder später: Cloze-Parser

packages/cards-domain/src/protocol/envelope.ts

@@ -0,0 +1,69 @@
+// TEMPORARY MIRROR von @mana/shared-share-protocol/envelope.
+//
+// Solange `pkg.mana.how` für Cards nicht erreichbar ist (NPM_AUTH_TOKEN
+// in `~/.npmrc` fehlt), halten wir die Schemas hier lokal. Sobald
+// Verdaccio offen ist, wird diese Datei gegen einen Re-Export aus
+// `@mana/shared-share-protocol` getauscht — alle Imports sind in der
+// Form `import { ShareEnvelopeSchema } from '@cards/domain'` formuliert,
+// damit der Swap eine reine 1-Liner-Edit-Aufgabe ist.
+//
+// Bei jedem Update der mana-Spec muss diese Datei nachgezogen werden,
+// bis der Swap erfolgt. Stand: 2026-05-08, ENVELOPE_VERSION 0.1.
+
+import { z } from 'zod';
+
+export const ENVELOPE_VERSION = '0.1' as const;
+
+const ULID_REGEX = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+const TYPE_NAME_REGEX = /^mana\/[a-z][a-z0-9-]+$/;
+
+const SignatureSchema = z.object({
+	algorithm: z.literal('eddsa'),
+	key_id: z.string().min(1),
+	signature: z.string().min(1),
+});
+
+export const ShareEnvelopeSchema = z.object({
+	envelope_version: z.literal(ENVELOPE_VERSION),
+	share_id: z.string().regex(ULID_REGEX, 'must be ULID'),
+
+	from: z.object({
+		app: z.string().min(1),
+		app_version: z.string().min(1),
+		user_id: z.string().uuid(),
+		timestamp: z.string().datetime(),
+		instance_id: z.string().max(120).optional(),
+	}),
+
+	to: z.object({
+		app: z.string().min(1),
+		user_id: z.string().uuid(),
+	}),
+
+	type: z.string().regex(TYPE_NAME_REGEX, 'must be "mana/<kind>"'),
+	payload: z.unknown(),
+
+	source_link: z.string().max(2000).optional(),
+	user_note: z.string().max(500).optional(),
+	ttl_seconds: z.number().int().positive().optional(),
+
+	intent: z.enum(['user_action', 'automation', 'agent_tool']).default('user_action'),
+	consent_recorded_at: z.string().datetime(),
+
+	signature: SignatureSchema.optional(),
+});
+
+export type ShareEnvelope = z.infer<typeof ShareEnvelopeSchema>;
+
+/** Strict-Variante: Cross-User-Shares hart verboten. */
+export const ShareEnvelopeStrictSchema = ShareEnvelopeSchema.refine(
+	(env) => env.from.user_id === env.to.user_id,
+	{
+		message: 'cross-user shares forbidden — from.user_id must equal to.user_id',
+		path: ['to', 'user_id'],
+	}
+);
+
+export function parseEnvelope(raw: unknown) {
+	return ShareEnvelopeStrictSchema.safeParse(raw);
+}

packages/cards-domain/src/protocol/index.ts

@@ -0,0 +1,7 @@
+// Public Re-Exports der lokalen Protocol-Mirror.
+// Wenn @mana/shared-share-protocol via Verdaccio verfügbar ist,
+// wird hier auf einen Re-Export aus dem npm-Paket umgestellt.
+
+export * from './envelope.ts';
+export * from './payloads.ts';
+export * from './search.ts';

packages/cards-domain/src/protocol/payloads.ts

@@ -0,0 +1,83 @@
+// TEMPORARY MIRROR — siehe envelope.ts.
+//
+// Payload-Schemas für die `accepts[]` aus dem Cards-Manifest:
+// `mana/quote`, `mana/url`, `mana/text`. Andere known types
+// (`mana/transcript`, `mana/link`, `mana/note`, etc.) werden wir
+// erst ergänzen, wenn Cards sie aktiv akzeptiert.
+
+import { z } from 'zod';
+
+export const MANA_TYPE_QUOTE = 'mana/quote' as const;
+export const MANA_TYPE_URL = 'mana/url' as const;
+export const MANA_TYPE_TEXT = 'mana/text' as const;
+
+export const QuotePayloadSchema = z
+	.object({
+		text: z.string().min(1).max(8000),
+		source: z.string().max(500).optional(),
+		source_url: z.string().url().optional(),
+		source_kind: z
+			.enum(['book', 'article', 'talk', 'conversation', 'transcript', 'link', 'manual', 'other'])
+			.optional(),
+		language: z
+			.string()
+			.regex(/^[a-z]{2}(-[A-Z]{2})?$/)
+			.optional(),
+		tags: z.array(z.string().max(64)).max(50).optional(),
+	})
+	.strict();
+export type QuotePayload = z.infer<typeof QuotePayloadSchema>;
+
+/**
+ * `mana/url` — externe Web-Adresse mit optionalen OG-Metadaten.
+ * (Mana-Spec nennt dies `mana/link`. Wir akzeptieren dieselben
+ * Felder, aber unter unserem deklarierten Type-Namen `mana/url`.)
+ */
+export const UrlPayloadSchema = z
+	.object({
+		url: z.string().url(),
+		title: z.string().max(500).optional(),
+		description: z.string().max(2000).optional(),
+		snippet: z.string().max(2000).optional(),
+		image_url: z.string().url().optional(),
+		site_name: z.string().max(200).optional(),
+		favicon_url: z.string().url().optional(),
+	})
+	.strict();
+export type UrlPayload = z.infer<typeof UrlPayloadSchema>;
+
+export const TextPayloadSchema = z
+	.object({
+		text: z.string().min(1).max(50000),
+		format: z.enum(['plain', 'markdown', 'html']).default('plain'),
+		source: z.string().max(500).optional(),
+		source_url: z.string().url().optional(),
+	})
+	.strict();
+export type TextPayload = z.infer<typeof TextPayloadSchema>;
+
+/** Map vom Type-String zum Payload-Schema. */
+export const PAYLOAD_SCHEMAS = {
+	[MANA_TYPE_QUOTE]: QuotePayloadSchema,
+	[MANA_TYPE_URL]: UrlPayloadSchema,
+	[MANA_TYPE_TEXT]: TextPayloadSchema,
+} as const;
+
+export type AcceptedShareType = keyof typeof PAYLOAD_SCHEMAS;
+
+export function validatePayloadForType(
+	type: string,
+	payload: unknown
+): { success: true; data: unknown } | { success: false; error: 'unknown_type' | 'invalid_payload'; issues?: string[] } {
+	const schema = PAYLOAD_SCHEMAS[type as AcceptedShareType];
+	if (!schema) return { success: false, error: 'unknown_type' };
+	const r = schema.safeParse(payload);
+	if (!r.success) {
+		return {
+			success: false,
+			error: 'invalid_payload',
+			issues: r.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`),
+		};
+	}
+	return { success: true, data: r.data };
+}

packages/cards-domain/src/protocol/search.ts

@@ -0,0 +1,39 @@
+// TEMPORARY MIRROR — siehe envelope.ts.
+
+import { z } from 'zod';
+
+export const SEARCH_ENVELOPE_VERSION = '0.1' as const;
+
+export const SearchHitSchema = z.object({
+	id: z.string().min(1),
+	type: z.string().min(1),
+	title: z.string().min(1).max(300),
+	snippet: z.string().max(1000).optional(),
+	link: z.string().min(1),
+	score: z.number().min(0).max(1),
+	highlights: z
+		.array(
+			z.object({
+				field: z.string().max(80),
+				fragment: z.string().max(500),
+			})
+		)
+		.max(10)
+		.optional(),
+	meta: z.record(z.string(), z.unknown()).optional(),
+	created_at: z.string().datetime().optional(),
+	updated_at: z.string().datetime().optional(),
+});
+export type SearchHit = z.infer<typeof SearchHitSchema>;
+
+export const SearchResultEnvelopeSchema = z.object({
+	envelope_version: z.literal(SEARCH_ENVELOPE_VERSION),
+	query: z.string().min(1).max(500),
+	app: z.string().min(1),
+	app_version: z.string().min(1),
+	results: z.array(SearchHitSchema).max(200),
+	total: z.number().int().nonnegative(),
+	partial: z.boolean(),
+	took_ms: z.number().int().nonnegative(),
+});
+export type SearchResultEnvelope = z.infer<typeof SearchResultEnvelopeSchema>;