create-safest-tools 0.6.0 → 0.7.0

package/template/src/participant-access.ts

@@ -0,0 +1,163 @@
+import { canonicalJson } from "./audit";
+import { sha256 } from "./report-crypto";
+import { ApiError } from "./report-http";
+import type { ParticipantAudience } from "./report-types";
+
+export interface ParticipantIdentity {
+  participantId: string; reportId: string; audience: ParticipantAudience;
+  reference: string | null; contactCiphertext: string | null; contactMode: string;
+}
+export interface ParticipantSession extends ParticipantIdentity { tokenHash: string; csrfHash: string; grantId: string; }
+const identityColumns = `p.id AS participantId, p.report_id AS reportId, p.audience,
+  p.reference, p.contact_ciphertext AS contactCiphertext, p.contact_mode AS contactMode`;
+const accessError = () => new ApiError(401, "participant_access_unavailable", "This private link or session is unavailable. Request a new link using the email on your case.");
+const now = () => new Date().toISOString();
+const after = (seconds: number) => new Date(Date.now() + seconds * 1000).toISOString();
+
+export async function participantIdentityFingerprint(identity: ParticipantIdentity): Promise<string> {
+  return sha256(canonicalJson(identity));
+}
+export async function participantGrantToken(secret:string,grantId:string):Promise<string> {
+  return signature(secret,`participant-link-v1:${grantId}`);
+}
+async function signature(secret: string, value: string): Promise<string> {
+  if (new TextEncoder().encode(secret).length < 32) throw new Error("Participant access requires the configured signing secret.");
+  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  return Array.from(new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(value))), b => b.toString(16).padStart(2, "0")).join("");
+}
+function randomSecret(): string {
+  return Array.from(crypto.getRandomValues(new Uint8Array(32)), b => b.toString(16).padStart(2, "0")).join("");
+}
+export async function issueParticipantAccessLink(
+  env: Pick<Env, "DB" | "CONTEXT_SIGNING_SECRET" | "PUBLIC_BASE_URL">,
+  input: { reportId: string; audience: ParticipantAudience; deliveryKey: string; expectedIdentity?: { reference: string | null; contactCiphertext: string | null } },
+): Promise<string> {
+  const base = new URL(env.PUBLIC_BASE_URL);
+  if (base.protocol !== "https:" && !(base.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(base.hostname))) throw new Error("Participant links require a secure public address.");
+  const identity = await env.DB.prepare(`SELECT ${identityColumns} FROM report_participants p WHERE p.report_id = ?1 AND p.audience = ?2 AND p.reference_redacted_at IS NULL`).bind(input.reportId, input.audience).first<ParticipantIdentity>();
+  if (!identity) throw accessError();
+  if (input.expectedIdentity && (identity.reference !== input.expectedIdentity.reference || identity.contactCiphertext !== input.expectedIdentity.contactCiphertext)) throw accessError();
+  const identityFingerprint = await participantIdentityFingerprint(identity);
+  const id = crypto.randomUUID();
+  const token = await participantGrantToken(env.CONTEXT_SIGNING_SECRET,id);
+  await env.DB.prepare(`INSERT OR IGNORE INTO participant_access_grants (id,participant_id,delivery_key,identity_fingerprint,token_hash,created_at,expires_at)
+    SELECT ?1,?2,?3,?4,?5,?6,?7 FROM report_participants WHERE id=?2 AND reference_redacted_at IS NULL AND reference IS ?8 AND contact_ciphertext IS ?9 AND contact_mode=?10`)
+    .bind(id,identity.participantId,input.deliveryKey,identityFingerprint,await sha256(token),now(),after(30*86400),identity.reference,identity.contactCiphertext,identity.contactMode).run();
+  const grant = await env.DB.prepare(`SELECT id,participant_id AS participantId,identity_fingerprint AS fingerprint FROM participant_access_grants WHERE delivery_key=?1`).bind(input.deliveryKey).first<{ id:string; participantId:string; fingerprint:string }>();
+  if (!grant || grant.participantId !== identity.participantId || grant.fingerprint !== identityFingerprint) throw accessError();
+  return `${base.origin}/participant#access=${await participantGrantToken(env.CONTEXT_SIGNING_SECRET,grant.id)}`;
+}
+
+export async function participantCsrf(secret: string, sessionToken: string): Promise<string> {
+  return signature(secret, `participant-csrf-v1:${sessionToken}`);
+}
+
+export async function lookupParticipantAccessLink(
+  env: Pick<Env, "DB" | "CONTEXT_SIGNING_SECRET" | "PUBLIC_BASE_URL">,
+  input: {reportId:string;audience:ParticipantAudience;deliveryKey:string;expectedIdentity:{reference:string|null;contactCiphertext:string|null}},
+): Promise<string|null> {
+  const identity=await env.DB.prepare(`SELECT ${identityColumns} FROM report_participants p WHERE p.report_id=?1 AND p.audience=?2 AND p.reference_redacted_at IS NULL`).bind(input.reportId,input.audience).first<ParticipantIdentity>();
+  if(!identity||identity.reference!==input.expectedIdentity.reference||identity.contactCiphertext!==input.expectedIdentity.contactCiphertext)throw accessError();
+  const grant=await env.DB.prepare(`SELECT id,participant_id AS participantId,identity_fingerprint AS fingerprint FROM participant_access_grants WHERE delivery_key=?1`).bind(input.deliveryKey).first<{id:string;participantId:string;fingerprint:string}>();
+  if(!grant)return null;
+  if(grant.participantId!==identity.participantId||grant.fingerprint!==await participantIdentityFingerprint(identity))throw accessError();
+  return `${new URL(env.PUBLIC_BASE_URL).origin}/participant#access=${await participantGrantToken(env.CONTEXT_SIGNING_SECRET,grant.id)}`;
+}
+
+export async function exchangeParticipantAccess(env: Pick<Env,"DB"|"CONTEXT_SIGNING_SECRET">, token: string, existingSessionToken?:string): Promise<{ sessionToken: string; csrfToken: string }> {
+  if (!/^[0-9a-f]{64}$/u.test(token)) throw accessError();
+  const tokenHash = await sha256(token);
+  const grant = await env.DB.prepare(`SELECT g.id,g.consumed_at AS consumedAt,g.identity_fingerprint AS fingerprint,${identityColumns} FROM participant_access_grants g
+    JOIN report_participants p ON p.id=g.participant_id WHERE g.token_hash=?1 AND g.expires_at>?2 AND g.revoked_at IS NULL AND p.reference_redacted_at IS NULL`).bind(tokenHash,now()).first<ParticipantIdentity & {id:string;fingerprint:string;consumedAt:string|null}>();
+  if (!grant || grant.fingerprint !== await participantIdentityFingerprint({participantId:grant.participantId,reportId:grant.reportId,audience:grant.audience,reference:grant.reference,contactCiphertext:grant.contactCiphertext,contactMode:grant.contactMode})) throw accessError();
+  if(grant.consumedAt){
+    // Reopening a consumed invitation may resume only the exact session that
+    // came from that grant. A different case/audience/grant is never a fallback.
+    if(!existingSessionToken)throw accessError();
+    const existing=await loadParticipantSession(env.DB,existingSessionToken);
+    if(existing.grantId!==grant.id)throw accessError();
+    return{sessionToken:existingSessionToken,csrfToken:await participantCsrf(env.CONTEXT_SIGNING_SECRET,existingSessionToken)};
+  }
+  const sessionToken=randomSecret(); const csrfToken=await participantCsrf(env.CONTEXT_SIGNING_SECRET,sessionToken); const at=now();
+  const result=await env.DB.batch([
+    env.DB.prepare(`UPDATE participant_access_grants SET consumed_at=?2 WHERE id=?1 AND consumed_at IS NULL AND revoked_at IS NULL AND expires_at>?2
+      AND EXISTS (SELECT 1 FROM report_participants p WHERE p.id=participant_access_grants.participant_id AND p.reference_redacted_at IS NULL AND p.reference IS ?3 AND p.contact_ciphertext IS ?4 AND p.contact_mode=?5)`)
+      .bind(grant.id,at,grant.reference,grant.contactCiphertext,grant.contactMode),
+    env.DB.prepare(`INSERT INTO participant_sessions(token_hash,grant_id,csrf_hash,created_at,expires_at) SELECT ?1,?2,?3,?4,?5 WHERE changes()=1`)
+      .bind(await sha256(sessionToken),grant.id,await sha256(csrfToken),at,after(7*86400)),
+  ]);
+  if (result[0]?.meta.changes!==1) throw accessError();
+  return {sessionToken,csrfToken};
+}
+
+export async function loadParticipantSession(db: D1Database, token: string): Promise<ParticipantSession> {
+  if (!/^[0-9a-f]{64}$/u.test(token)) throw accessError();
+  const tokenHash=await sha256(token);
+  const row=await db.prepare(`SELECT s.token_hash AS tokenHash,s.csrf_hash AS csrfHash,s.grant_id AS grantId,g.identity_fingerprint AS fingerprint,${identityColumns}
+    FROM participant_sessions s JOIN participant_access_grants g ON g.id=s.grant_id JOIN report_participants p ON p.id=g.participant_id
+    WHERE s.token_hash=?1 AND s.expires_at>?2 AND s.revoked_at IS NULL AND g.revoked_at IS NULL AND g.expires_at>?2 AND p.reference_redacted_at IS NULL`)
+    .bind(tokenHash,now()).first<ParticipantSession & {fingerprint:string}>();
+  if (!row || row.fingerprint !== await participantIdentityFingerprint({participantId:row.participantId,reportId:row.reportId,audience:row.audience,reference:row.reference,contactCiphertext:row.contactCiphertext,contactMode:row.contactMode})) throw accessError();
+  return row;
+}
+
+/** First statement in every participant write batch. CHECK failure rolls back all effects. */
+export function participantMutationGuard(db:D1Database,session:ParticipantSession,id:string):D1PreparedStatement {
+  return db.prepare(`INSERT INTO participant_mutation_guards(id,authorized) VALUES (?1, EXISTS (
+    SELECT 1 FROM participant_sessions s JOIN participant_access_grants g ON g.id=s.grant_id JOIN report_participants p ON p.id=g.participant_id
+    WHERE s.token_hash=?2 AND s.expires_at>?3 AND s.revoked_at IS NULL AND g.revoked_at IS NULL AND g.expires_at>?3
+      AND p.id=?4 AND p.reference_redacted_at IS NULL AND p.reference IS ?5 AND p.contact_ciphertext IS ?6 AND p.contact_mode=?7))`)
+    .bind(id,session.tokenHash,now(),session.participantId,session.reference,session.contactCiphertext,session.contactMode);
+}
+export async function commitParticipantMutation(db:D1Database,session:ParticipantSession,statements:D1PreparedStatement[]):Promise<D1Result[]> {
+  const id=crypto.randomUUID();
+  try { return await db.batch([participantMutationGuard(db,session,id),...statements,db.prepare(`DELETE FROM participant_mutation_guards WHERE id=?1`).bind(id)]); }
+  catch(error) {
+    if (error instanceof Error && error.message.includes("valid_participant_session")) throw accessError();
+    if (error instanceof Error && (error.message.includes("participant_message_rate") || error.message.includes("participant_appeal_rate"))) {
+      const message=error.message.includes("participant_message_rate");
+      const windowSeconds=message?300:3600;
+      const cutoff=new Date(Date.now()-windowSeconds*1000).toISOString();
+      const earliest=message
+        ? await db.prepare(`SELECT MIN(created_at) AS earliest FROM case_messages WHERE report_id=?1 AND audience=?2 AND sender_id=?3 AND direction='inbound' AND created_at>?4`).bind(session.reportId,session.audience,session.participantId,cutoff).first<{earliest:string|null}>()
+        : await db.prepare(`SELECT MIN(submitted_at) AS earliest FROM appeals WHERE report_id=?1 AND appellant_audience=?2 AND submitted_at>?3`).bind(session.reportId,session.audience,cutoff).first<{earliest:string|null}>();
+      const retryAfterSeconds=Math.max(1,Math.ceil(((earliest?.earliest?new Date(earliest.earliest).valueOf():Date.now())+windowSeconds*1000-Date.now())/1000));
+      throw new ApiError(429,"participant_rate_limited",`You have sent several ${message?"messages":"appeals"} recently. Your text has been kept. Try again in ${retryAfterSeconds<60?`${retryAfterSeconds} seconds`:`${Math.ceil(retryAfterSeconds/60)} minutes`}.`,{retryAfterSeconds});
+    }
+    throw error;
+  }
+}
+export async function revokeParticipantAccess(db:D1Database,participantId:string):Promise<void> {
+  await db.prepare(`UPDATE participant_access_grants SET revoked_at=?2 WHERE participant_id=?1 AND revoked_at IS NULL`).bind(participantId,now()).run();
+}
+
+/** Bounded maintenance. Grant identity survives expiry for immutable delivery retries. */
+export async function pruneParticipantAccess(db:D1Database):Promise<{sessions:number;recoveryBuckets:number;grants:number}> {
+  const at=now();
+  const result=await db.batch([
+    db.prepare(`DELETE FROM participant_sessions WHERE token_hash IN (
+      SELECT s.token_hash FROM participant_sessions s JOIN participant_access_grants g ON g.id=s.grant_id
+      JOIN report_participants p ON p.id=g.participant_id WHERE s.expires_at<=?1 OR s.revoked_at IS NOT NULL
+        OR g.expires_at<=?1 OR g.revoked_at IS NOT NULL OR p.reference_redacted_at IS NOT NULL LIMIT 1000)`).bind(at),
+    db.prepare(`DELETE FROM participant_recovery_limits WHERE key_hash IN (SELECT key_hash FROM participant_recovery_limits WHERE next_allowed_at<=?1 LIMIT 1000)`).bind(at),
+    db.prepare(`DELETE FROM participant_access_grants WHERE id IN (
+      SELECT g.id FROM participant_access_grants g JOIN report_participants p ON p.id=g.participant_id
+      WHERE p.reference_redacted_at IS NOT NULL LIMIT 1000)`),
+  ]);
+  return{sessions:result[0]?.meta.changes??0,recoveryBuckets:result[1]?.meta.changes??0,grants:result[2]?.meta.changes??0};
+}
+
+/** Insert immediately after the new message/appeal, inside its guarded transaction. */
+export function participantRateGuard(db:D1Database,session:ParticipantSession,kind:"message"|"appeal",insertedId:string):D1PreparedStatement[] {
+  const id=crypto.randomUUID();
+  const statement=kind==="message"
+    ? db.prepare(`INSERT INTO participant_rate_guards(id,message_allowed) VALUES(?1,
+        NOT EXISTS(SELECT 1 FROM case_messages WHERE id=?2) OR
+        (SELECT COUNT(*) FROM (SELECT id FROM case_messages WHERE report_id=?3 AND audience=?4 AND sender_id=?5 AND direction='inbound' AND created_at>?6 LIMIT 11))<=10)`)
+      .bind(id,insertedId,session.reportId,session.audience,session.participantId,new Date(Date.now()-300000).toISOString())
+    : db.prepare(`INSERT INTO participant_rate_guards(id,appeal_allowed) VALUES(?1,
+        NOT EXISTS(SELECT 1 FROM appeals WHERE id=?2) OR
+        (SELECT COUNT(*) FROM (SELECT id FROM appeals WHERE report_id=?3 AND appellant_audience=?4 AND submitted_at>?5 LIMIT 4))<=3)`)
+      .bind(id,insertedId,session.reportId,session.audience,new Date(Date.now()-3600000).toISOString());
+  return[statement,db.prepare(`DELETE FROM participant_rate_guards WHERE id=?1`).bind(id)];
+}

package/template/src/participant-case.ts

@@ -0,0 +1,87 @@
+import { canonicalJson } from "./audit";
+import { commitParticipantMutation, participantRateGuard, type ParticipantSession } from "./participant-access";
+import { ApiError } from "./report-http";
+
+const stateLabels:Record<string,string>={received:"Report received",human_review:"Under review",ai_review:"Under review",awaiting_reporter:"More information requested",resolved_by_human:"Review completed",resolved_by_ai:"Review completed",human_review_requested:"Further review requested",appealed:"Appeal in progress",closed:"Completed"};
+export interface ParticipantMessage {id:string;body:string;direction:"inbound"|"outbound";createdAt:string;}
+export async function loadParticipantMessages(db:D1Database,session:ParticipantSession,before?:string):Promise<{messages:ParticipantMessage[];olderMessagesCursor:string|null}> {
+  // Cursor IDs are resolved only inside the same participant's audience. An ID
+  // from another case/audience cannot expose either its content or timestamp.
+  const cursor=before?await db.prepare(`SELECT id,created_at AS createdAt FROM case_messages WHERE id=?1 AND report_id=?2 AND audience=?3 AND direction IN ('inbound','outbound')`).bind(before,session.reportId,session.audience).first<{id:string;createdAt:string}>():null;
+  if(before&&!cursor)throw new ApiError(400,"participant_history_cursor_unavailable","This history position is no longer available. Refresh the case to load its available messages.");
+  const result=await db.prepare(`SELECT id,body,direction,created_at AS createdAt FROM case_messages
+    WHERE report_id=?1 AND audience=?2 AND redacted_at IS NULL AND direction IN ('inbound','outbound')
+      AND (?3 IS NULL OR created_at<?3 OR (created_at=?3 AND id<?4)) ORDER BY created_at DESC,id DESC LIMIT 51`)
+    .bind(session.reportId,session.audience,cursor?.createdAt??null,cursor?.id??null).all<ParticipantMessage>();
+  const messages=result.results.slice(0,50).reverse();
+  return{messages,olderMessagesCursor:result.results.length>50?messages[0]!.id:null};
+}
+export async function loadParticipantCase(db:D1Database,session:ParticipantSession):Promise<Record<string,unknown>> {
+  const report=await db.prepare(`SELECT public_reference AS reference,state,submitted_at AS submittedAt FROM reports WHERE id=?1`).bind(session.reportId).first<{reference:string;state:string;submittedAt:string}>();
+  if (!report) throw new ApiError(404,"participant_case_unavailable","This case is no longer available.");
+  // Only explicitly addressed content is projected. Never expose decisions.rationale,
+  // internal messages, operational timelines, identities or the other audience.
+  const [messages,appeals,decision]=await Promise.all([
+    loadParticipantMessages(db,session),
+    db.prepare(`SELECT a.id,a.reason,a.state,a.submitted_at AS submittedAt,ad.completion_state AS completionState
+      FROM appeals a LEFT JOIN appeal_decisions ad ON ad.appeal_id=a.id WHERE a.report_id=?1 AND a.appellant_audience=?2 AND a.reason_redacted_at IS NULL ORDER BY a.submitted_at,a.id`).bind(session.reportId,session.audience).all(),
+    db.prepare(`SELECT d.id FROM decisions d WHERE d.report_id=?1 AND d.sensitive_redacted_at IS NULL ORDER BY d.created_at DESC,d.id DESC LIMIT 1`).bind(session.reportId).first<{id:string}>(),
+  ]);
+  const already=decision ? await db.prepare(`SELECT id FROM appeals WHERE decision_id=?1 AND appellant_audience=?2`).bind(decision.id,session.audience).first() : null;
+  const ownAppealPending=appeals.results.some(a=>a.state==="submitted"||a.state==="human_review"||a.completionState==="waiting");
+  const customerReentry=session.reference?await db.prepare(`SELECT 1 AS available FROM reports r JOIN application_integrations i ON i.id=r.integration_id
+    WHERE r.id=?1 AND i.enabled=1 AND i.channel_mode='contextual' AND EXISTS(SELECT 1 FROM json_each(i.scopes_json) WHERE value='mint_context_tokens')`).bind(session.reportId).first():null;
+  return {reference:report.reference,status:ownAppealPending?"Appeal in progress":report.state==="appealed"?"Under review":stateLabels[report.state]??"Under review",submittedAt:report.submittedAt,audience:session.audience,...messages,appeals:appeals.results,
+    canAppeal:Boolean(decision&&!already),appealDecisionId:decision&&!already?decision.id:null,
+    recoveryAvailable:Boolean(session.contactCiphertext&&session.contactMode==="customer_notification"),customerReentryAvailable:Boolean(customerReentry)};
+}
+function requestText(value:string):string { const text=value.trim();if(text.length<3||text.length>8000)throw new ApiError(400,"participant_text_invalid","Enter between 3 and 8,000 characters.");return text; }
+function requestKey(value:string):string {if(!/^[A-Za-z0-9._:-]{8,160}$/u.test(value))throw new ApiError(400,"participant_request_key_invalid","The request key is invalid. Refresh and try again.");return value;}
+
+export async function addParticipantInformation(db:D1Database,session:ParticipantSession,input:{body:string;idempotencyKey:string}):Promise<{messageId:string;idempotentReplay:boolean}> {
+  const body=requestText(input.body);const key=`participant:${session.participantId}:message:${requestKey(input.idempotencyKey)}`;
+  const existing=await db.prepare(`SELECT id,body FROM case_messages WHERE report_id=?1 AND idempotency_key=?2`).bind(session.reportId,key).first<{id:string;body:string}>();
+  if(existing){if(existing.body!==body)throw new ApiError(409,"idempotency_key_reused","This request key has already been used with different text.");return{messageId:existing.id,idempotentReplay:true};}
+  const id=crypto.randomUUID();const at=new Date().toISOString();
+  const result=await commitParticipantMutation(db,session,[
+    db.prepare(`INSERT OR IGNORE INTO case_messages(id,report_id,audience,direction,sender_type,sender_id,body,automated,delivery_state,created_at,idempotency_key,audience_checked_at)
+      VALUES(?1,?2,?3,'inbound',?3,?4,?5,0,'not_required',?6,?7,?6)`).bind(id,session.reportId,session.audience,session.participantId,body,at,key),
+    ...participantRateGuard(db,session,"message",id),
+    db.prepare(`INSERT INTO report_state_history(id,report_id,from_state,to_state,reason_code,actor_type,actor_id,created_at)
+      SELECT ?1,id,state,CASE WHEN state='awaiting_reporter' THEN 'human_review' ELSE 'human_review_requested' END,'participant_information_received','participant',?3,?4 FROM reports
+      WHERE id=?2 AND state IN ('awaiting_reporter','resolved_by_human','resolved_by_ai','closed') AND EXISTS(SELECT 1 FROM case_messages WHERE id=?5)`).bind(crypto.randomUUID(),session.reportId,session.participantId,at,id),
+    db.prepare(`UPDATE reports SET state=CASE WHEN state='awaiting_reporter' THEN 'human_review' WHEN state IN ('resolved_by_human','resolved_by_ai','closed') THEN 'human_review_requested' ELSE state END,updated_at=?2 WHERE id=?1 AND EXISTS(SELECT 1 FROM case_messages WHERE id=?3)`).bind(session.reportId,at,id),
+    db.prepare(`INSERT INTO audit_events(id,idempotency_key,action,actor_type,actor_id,target_type,target_id,details_json,created_at)
+      SELECT ?1,?2,'report.participant_information_received','participant',?3,'report',?4,?5,?6 WHERE EXISTS(SELECT 1 FROM case_messages WHERE id=?7)`)
+      .bind(crypto.randomUUID(),`audit:${key}`,session.participantId,session.reportId,canonicalJson({audience:session.audience,messageId:id,source:"participant_portal"}),at,id),
+  ]);
+  if(result[1]?.meta.changes!==1)return addParticipantInformation(db,session,input);
+  return {messageId:id,idempotentReplay:false};
+}
+
+export async function submitParticipantAppeal(db:D1Database,session:ParticipantSession,input:{reason:string;decisionId:string;idempotencyKey:string}):Promise<{appealId:string;idempotentReplay:boolean}> {
+  const reason=requestText(input.reason);const key=`participant:${session.participantId}:appeal:${requestKey(input.idempotencyKey)}`;
+  const existing=await db.prepare(`SELECT id,reason,decision_id AS decisionId FROM appeals WHERE report_id=?1 AND idempotency_key=?2 AND appellant_audience=?3`).bind(session.reportId,key,session.audience).first<{id:string;reason:string;decisionId:string}>();
+  if(existing){if(existing.reason!==reason||existing.decisionId!==input.decisionId)throw new ApiError(409,"idempotency_key_reused","This appeal request was already submitted with different details.");return{appealId:existing.id,idempotentReplay:true};}
+  const decision=await db.prepare(`SELECT id FROM decisions WHERE report_id=?1 AND sensitive_redacted_at IS NULL ORDER BY created_at DESC,id DESC LIMIT 1`).bind(session.reportId).first<{id:string}>();
+  if(!decision||decision.id!==input.decisionId)throw new ApiError(409,"appeal_decision_changed","The decision changed. Refresh the case before requesting an appeal.");
+  const queue=await db.prepare(`SELECT q.id FROM queue_definitions q JOIN reports r ON r.installation_id=q.installation_id WHERE r.id=?1 AND q.queue_kind='appeal' AND q.enabled=1 AND q.status='active' ORDER BY q.position,q.id LIMIT 1`).bind(session.reportId).first<{id:string}>();
+  if(!queue)throw new ApiError(409,"appeal_queue_unavailable","Appeal requests are temporarily unavailable. Your text is still here; contact the safety team or try again later.");
+  const id=crypto.randomUUID();const at=new Date().toISOString();
+  await commitParticipantMutation(db,session,[
+    db.prepare(`INSERT OR IGNORE INTO appeals(id,report_id,decision_id,appellant_audience,reason,state,queue_id,submitted_at,idempotency_key)
+      SELECT ?1,?2,?3,?4,?5,'submitted',?6,?7,?8 WHERE ?3=(SELECT id FROM decisions WHERE report_id=?2 AND sensitive_redacted_at IS NULL ORDER BY created_at DESC,id DESC LIMIT 1)
+      AND EXISTS(SELECT 1 FROM queue_definitions WHERE id=?6 AND queue_kind='appeal' AND enabled=1 AND status='active')`).bind(id,session.reportId,decision.id,session.audience,reason,queue.id,at,key),
+    ...participantRateGuard(db,session,"appeal",id),
+    db.prepare(`INSERT INTO report_state_history(id,report_id,from_state,to_state,reason_code,actor_type,actor_id,created_at)
+      SELECT ?1,id,state,'appealed','participant_appeal_submitted','participant',?3,?4 FROM reports WHERE id=?2 AND EXISTS(SELECT 1 FROM appeals WHERE id=?5)`).bind(crypto.randomUUID(),session.reportId,session.participantId,at,id),
+    db.prepare(`UPDATE reports SET state='appealed',updated_at=?2 WHERE id=?1 AND EXISTS(SELECT 1 FROM appeals WHERE id=?3)`).bind(session.reportId,at,id),
+    db.prepare(`INSERT INTO audit_events(id,idempotency_key,action,actor_type,actor_id,target_type,target_id,details_json,created_at)
+      SELECT ?1,?2,'appeal.recorded','participant',?3,'appeal',?4,?5,?6 WHERE EXISTS(SELECT 1 FROM appeals WHERE id=?4)`)
+      .bind(crypto.randomUUID(),`appeal-recorded:${id}`,session.participantId,id,canonicalJson({reportId:session.reportId,decisionId:decision.id,audience:session.audience,source:"participant_portal"}),at),
+  ]);
+  const saved=await db.prepare(`SELECT id,idempotency_key AS key,reason FROM appeals WHERE decision_id=?1 AND appellant_audience=?2`).bind(decision.id,session.audience).first<{id:string;key:string;reason:string}>();
+  if(!saved||saved.key!==key)throw new ApiError(409,"appeal_already_recorded","An appeal already exists for this decision. Refresh to see its progress.");
+  if(saved.reason!==reason)throw new ApiError(409,"idempotency_key_reused","This appeal request was already submitted with different details.");
+  return {appealId:saved.id,idempotentReplay:saved.id!==id};
+}

package/template/src/participant-customer-access.ts

@@ -0,0 +1,93 @@
+import {canonicalJson} from "./audit";
+import {requireIntegration} from "./report-auth";
+import {secretsEqual,sha256} from "./report-crypto";
+import {ApiError,apiErrorResponse,json,methodNotAllowed,readJsonObject} from "./report-http";
+import {lookupParticipantAccessLink,participantGrantToken,participantIdentityFingerprint,type ParticipantIdentity} from "./participant-access";
+
+const unavailable=()=>new ApiError(403,"participant_access_unavailable","This participant cannot access that case through this integration.");
+const conflict=()=>new ApiError(409,"idempotency_key_reused","This request key was already used for a different participant or case.");
+function field(input:Record<string,unknown>,name:string,maximum:number):string {
+  const value=input[name];
+  if(typeof value!=="string"||!value.trim()||value.length>maximum)throw new ApiError(400,"participant_access_input_invalid",`${name} is required and must contain at most ${maximum} characters.`);
+  return value.trim();
+}
+
+/** Customer-server endpoint. The customer derives participant_reference from its own authenticated session. */
+export async function handleCustomerParticipantAccess(request:Request,env:Env):Promise<Response> {
+  try{
+    if(request.method!=="POST")return methodNotAllowed(["POST"]);
+    const integration=await requireIntegration(request,env);
+    if(!integration.scopes.includes("mint_context_tokens"))throw new ApiError(403,"integration_scope_denied","The integration cannot mint participant access links.");
+    if(integration.channelMode!=="contextual")throw new ApiError(403,"integration_mode_denied","This reporting channel does not accept authenticated participant identity.");
+    let base:URL;
+    try{base=new URL(env.PUBLIC_BASE_URL);}catch{throw new ApiError(503,"participant_public_url_invalid","The private case address is not configured correctly.");}
+    if(base.protocol!=="https:"&&!(base.protocol==="http:"&&["localhost","127.0.0.1","[::1]"].includes(base.hostname)))throw new ApiError(503,"participant_public_url_invalid","The private case address must use HTTPS.");
+    const input=await readJsonObject(request,4096);
+    if(Object.keys(input).some(key=>!["report_reference","audience","participant_reference"].includes(key)))throw new ApiError(400,"participant_access_input_invalid","Only report_reference, audience and participant_reference are accepted.");
+    const reportReference=field(input,"report_reference",100);const participantReference=field(input,"participant_reference",500);
+    if(input.audience!=="reporter"&&input.audience!=="affected_user")throw new ApiError(400,"participant_access_input_invalid","audience must be reporter or affected_user.");
+    const audience=input.audience;
+    const requestKey=request.headers.get("idempotency-key")?.trim()??"";
+    if(!/^[A-Za-z0-9._:-]{8,160}$/u.test(requestKey))throw new ApiError(400,"participant_request_key_invalid","Provide an Idempotency-Key containing 8–160 letters, digits, periods, underscores, colons or hyphens.");
+    const identity=await env.DB.prepare(`SELECT p.id AS participantId,p.report_id AS reportId,p.audience,p.reference,p.contact_ciphertext AS contactCiphertext,p.contact_mode AS contactMode
+      FROM report_participants p JOIN reports r ON r.id=p.report_id WHERE r.public_reference=?1 AND r.integration_id=?2 AND p.audience=?3 AND p.reference=?4 AND p.reference_redacted_at IS NULL`)
+      .bind(reportReference,integration.id,audience,participantReference).first<ParticipantIdentity>();
+    if(!identity)throw unavailable();
+    const fingerprint=await participantIdentityFingerprint(identity);
+    const deliveryKey=`customer-access:${integration.id}:${requestKey}`;
+    const existing=await env.DB.prepare(`SELECT participant_id AS participantId,identity_fingerprint AS fingerprint FROM participant_access_grants WHERE delivery_key=?1`).bind(deliveryKey).first<{participantId:string;fingerprint:string}>();
+    if(existing&&(existing.participantId!==identity.participantId||existing.fingerprint!==fingerprint))throw conflict();
+
+    // Capture how the existing authenticator accepted this credential. At commit,
+    // recheck current managed-key status or the same deployment key ID as well as
+    // integration mode, enabled state, scope and exact case/participant identity.
+    const keyRow=await env.DB.prepare(`SELECT key_id AS keyId FROM application_integrations WHERE id=?1`).bind(integration.id).first<{keyId:string}>();
+    if(!keyRow)throw unavailable();
+    const suppliedKey=/^Bearer\s+([^\s]+)$/iu.exec(request.headers.get("authorization")??"")?.[1]??"";
+    let environmentKey:unknown;
+    try{const configured:unknown=JSON.parse(env.INTEGRATION_API_KEYS_JSON??"{}");if(configured&&typeof configured==="object"&&!Array.isArray(configured))environmentKey=(configured as Record<string,unknown>)[keyRow.keyId];}catch{/* managed keys remain supported */}
+    const environmentValid=typeof environmentKey==="string"&&environmentKey.length>=16&&await secretsEqual(environmentKey,suppliedKey);
+    const suppliedHash=await sha256(`integration-key-v1:${suppliedKey}`);
+    const id=crypto.randomUUID();const guardId=crypto.randomUUID();const at=new Date().toISOString();const token=await participantGrantToken(env.CONTEXT_SIGNING_SECRET,id);
+    const cutoff=new Date(Date.now()-600000).toISOString();
+    try{
+      await env.DB.batch([
+        env.DB.prepare(`INSERT INTO participant_mutation_guards(id,authorized) VALUES(?1,EXISTS(
+          SELECT 1 FROM report_participants p JOIN reports r ON r.id=p.report_id JOIN application_integrations i ON i.id=r.integration_id
+          WHERE p.id=?2 AND r.public_reference=?3 AND r.integration_id=?4 AND p.audience=?5 AND p.reference=?6
+            AND p.reference_redacted_at IS NULL AND p.contact_ciphertext IS ?7 AND p.contact_mode=?8
+            AND i.enabled=1 AND i.channel_mode='contextual' AND EXISTS(SELECT 1 FROM json_each(i.scopes_json) WHERE value='mint_context_tokens')
+            AND ((?9=1 AND i.key_id=?10) OR EXISTS(SELECT 1 FROM integration_api_keys k WHERE k.integration_id=i.id AND k.key_hash=?11
+              AND k.status='active' AND k.valid_from<=?12 AND (k.expires_at IS NULL OR k.expires_at>?12)))))`)
+          .bind(guardId,identity.participantId,reportReference,integration.id,audience,participantReference,identity.contactCiphertext,identity.contactMode,environmentValid?1:0,keyRow.keyId,suppliedHash,at),
+        env.DB.prepare(`INSERT OR IGNORE INTO participant_access_grants(id,participant_id,delivery_key,identity_fingerprint,token_hash,created_at,expires_at) VALUES(?1,?2,?3,?4,?5,?6,?7)`)
+          .bind(id,identity.participantId,deliveryKey,fingerprint,await sha256(token),at,new Date(Date.now()+30*86400000).toISOString()),
+        env.DB.prepare(`INSERT INTO participant_rate_guards(id,message_allowed) VALUES(?1,NOT EXISTS(SELECT 1 FROM participant_access_grants WHERE id=?2) OR
+          (SELECT COUNT(*) FROM (SELECT id FROM participant_access_grants WHERE participant_id=?3 AND delivery_key LIKE 'customer-access:%' AND created_at>?4 LIMIT 11))<=10)`)
+          .bind(guardId,id,identity.participantId,cutoff),
+        env.DB.prepare(`INSERT INTO audit_events(id,idempotency_key,action,actor_type,actor_id,target_type,target_id,details_json,created_at)
+          SELECT ?1,?2,'participant_access.customer_link_issued','integration',?3,'report',?4,?5,?6 WHERE EXISTS(SELECT 1 FROM participant_access_grants WHERE id=?7)`)
+          .bind(crypto.randomUUID(),`participant-customer-access:${id}`,integration.id,identity.reportId,canonicalJson({participantId:identity.participantId,audience,grantId:id}),at,id),
+        env.DB.prepare(`DELETE FROM participant_rate_guards WHERE id=?1`).bind(guardId),
+        env.DB.prepare(`DELETE FROM participant_mutation_guards WHERE id=?1`).bind(guardId),
+      ]);
+    }catch(error){
+      if(error instanceof Error&&error.message.includes("valid_participant_session"))throw unavailable();
+      if(error instanceof Error&&error.message.includes("participant_message_rate")){
+        const row=await env.DB.prepare(`SELECT MIN(created_at) AS earliest FROM participant_access_grants WHERE participant_id=?1 AND delivery_key LIKE 'customer-access:%' AND created_at>?2`).bind(identity.participantId,cutoff).first<{earliest:string|null}>();
+        const seconds=Math.max(1,Math.ceil(((row?.earliest?new Date(row.earliest).valueOf():Date.now())+600000-Date.now())/1000));
+        throw new ApiError(429,"participant_access_throttled",`Several private links were requested recently. Try again in ${Math.ceil(seconds/60)} minutes.`,{retryAfterSeconds:seconds});
+      }
+      throw error;
+    }
+    const saved=await env.DB.prepare(`SELECT participant_id AS participantId,identity_fingerprint AS fingerprint FROM participant_access_grants WHERE delivery_key=?1`).bind(deliveryKey).first<{participantId:string;fingerprint:string}>();
+    if(!saved||saved.participantId!==identity.participantId||saved.fingerprint!==fingerprint)throw conflict();
+    const participantUrl=await lookupParticipantAccessLink(env,{reportId:identity.reportId,audience,deliveryKey,expectedIdentity:{reference:identity.reference,contactCiphertext:identity.contactCiphertext}});
+    if(!participantUrl)throw unavailable();
+    return json({participant_url:participantUrl});
+  }catch(error){
+    const response=apiErrorResponse(error);
+    if(error instanceof ApiError&&error.status===429&&typeof error.details?.retryAfterSeconds==="number")response.headers.set("retry-after",String(error.details.retryAfterSeconds));
+    return response;
+  }
+}

package/template/src/participant-recovery.ts

@@ -0,0 +1,43 @@
+import { sha256, decryptReportContact, secretsEqual } from "./report-crypto";
+import { reporterEmailConfigured } from "./report-email";
+import { ApiError } from "./report-http";
+import type { ParticipantIdentity } from "./participant-access";
+
+/** Generic responses prevent case/contact enumeration. The throttle hashes include a secret pepper. */
+export async function requestParticipantRecovery(env:Env,input:{reference:string;email:string;clientAddress:string}):Promise<void> {
+  const at=new Date().toISOString();const next=new Date(Date.now()+10*60000).toISOString();
+  const email=input.email.trim().toLowerCase();const reference=input.reference.trim();
+  const clientKey=await sha256(`participant-recovery-client:${env.RATE_LIMIT_PEPPER}:${input.clientAddress}`);
+  const client=await env.DB.prepare(`INSERT INTO participant_recovery_limits(key_hash,next_allowed_at) VALUES(?1,?2)
+    ON CONFLICT(key_hash) DO UPDATE SET next_allowed_at=excluded.next_allowed_at WHERE participant_recovery_limits.next_allowed_at<=?3`)
+    .bind(clientKey,new Date(Date.now()+30000).toISOString(),at).run();
+  if(client.meta.changes!==1)throw new ApiError(429,"participant_recovery_throttled","Please wait a moment before requesting another link.");
+  if(!/^[^\s@]+@[^\s@]+\.[^\s@]+$/u.test(email)||reference.length>100||!reporterEmailConfigured(env))return;
+  const key=await sha256(`participant-recovery:${env.RATE_LIMIT_PEPPER}:${reference}:${email}`);
+  const claimed=await env.DB.prepare(`INSERT INTO participant_recovery_limits(key_hash,next_allowed_at) VALUES(?1,?2)
+    ON CONFLICT(key_hash) DO UPDATE SET next_allowed_at=excluded.next_allowed_at WHERE participant_recovery_limits.next_allowed_at<=?3`).bind(key,next,at).run();
+  if(claimed.meta.changes!==1)return;
+  const rows=await env.DB.prepare(`SELECT p.id AS participantId,p.report_id AS reportId,p.audience,p.reference,p.contact_ciphertext AS contactCiphertext,p.contact_mode AS contactMode,r.installation_id AS installationId
+    FROM report_participants p JOIN reports r ON r.id=p.report_id WHERE r.public_reference=?1 AND p.reference_redacted_at IS NULL
+    AND p.contact_mode='customer_notification' AND p.contact_ciphertext IS NOT NULL`).bind(reference).all<ParticipantIdentity & {installationId:string}>();
+  for(const identity of rows.results){
+    let storedEmail:string;
+    try{storedEmail=(await decryptReportContact(env.CREDENTIAL_ENCRYPTION_KEY,identity.contactCiphertext!,identity.reportId,identity.audience)).trim().toLowerCase();}catch{continue;}
+    if(!await secretsEqual(email,storedEmail))continue;
+    const id=crypto.randomUUID();const deliveryId=crypto.randomUUID();
+    const recipientHash=`sha256:${await sha256(`email-recipient-v1:${env.RATE_LIMIT_PEPPER}:${storedEmail}`)}`;
+    const result=await env.DB.batch([
+      env.DB.prepare(`INSERT INTO case_messages(id,report_id,audience,direction,sender_type,sender_id,body,automated,delivery_state,created_at,idempotency_key,audience_checked_at)
+        SELECT ?1,report_id,audience,'outbound','system','participant-access','You requested a private link to this case. Use the Open your case button in this email. If you did not request it, you can ignore this message.',1,'queued',?3,?4,?3
+        FROM report_participants WHERE id=?2 AND reference_redacted_at IS NULL AND reference IS ?5 AND contact_ciphertext IS ?6 AND contact_mode='customer_notification'`)
+        .bind(id,identity.participantId,at,`participant-recovery:${id}`,identity.reference,identity.contactCiphertext),
+      env.DB.prepare(`INSERT INTO email_deliveries(id,installation_id,message_id,audience,recipient_hash,provider,state,created_at,updated_at)
+        SELECT ?1,?2,?3,?4,?5,'cloudflare_email','pending',?6,?6 WHERE EXISTS(SELECT 1 FROM case_messages WHERE id=?3)`)
+        .bind(deliveryId,identity.installationId,id,identity.audience,recipientHash,at),
+    ]);
+    if(result[0]?.meta.changes===1){
+      // The outbox is authoritative. Scheduled reconciliation retries a lost wake-up.
+      try{await env.DELIVERY_JOBS.send({version:1,jobId:`email:${deliveryId}`,type:"deliver_email",outboxId:deliveryId});}catch{/* durable outbox remains pending */}
+    }
+  }
+}

package/template/src/participant-routes.ts

@@ -0,0 +1,67 @@
+import { apiErrorResponse, ApiError, json, methodNotAllowed, readJsonObject } from "./report-http";
+import { sha256, secretsEqual } from "./report-crypto";
+import { exchangeParticipantAccess, loadParticipantSession, participantCsrf } from "./participant-access";
+import { addParticipantInformation, loadParticipantCase, loadParticipantMessages, submitParticipantAppeal } from "./participant-case";
+import { requestParticipantRecovery } from "./participant-recovery";
+
+const cookieName="safest_participant";
+const secureHeaders={"cache-control":"no-store","referrer-policy":"no-referrer","x-content-type-options":"nosniff","x-frame-options":"DENY","content-security-policy":"default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'self'"};
+function protect(response:Response):Response {const headers=new Headers(response.headers);for(const[k,v]of Object.entries(secureHeaders))headers.set(k,v);return new Response(response.body,{status:response.status,headers});}
+function sessionToken(request:Request):string {return request.headers.get("cookie")?.split(";").map(v=>v.trim()).find(v=>v.startsWith(`${cookieName}=`))?.slice(cookieName.length+1)??"";}
+function cookie(request:Request,token:string,maxAge:number):string {return `${cookieName}=${token}; Path=/v1/participant; HttpOnly; SameSite=Strict; Max-Age=${maxAge}${new URL(request.url).protocol==="https:"?"; Secure":""}`;}
+function requireOrigin(request:Request,env:Env):void {
+  if(request.headers.get("origin")!==new URL(env.PUBLIC_BASE_URL).origin||new URL(request.url).origin!==new URL(env.PUBLIC_BASE_URL).origin)throw new ApiError(403,"participant_origin_denied","Open the case using its original private link.");
+}
+function text(input:Record<string,unknown>,key:string):string {return typeof input[key]==="string"?input[key]:"";}
+
+export async function handleParticipantRequest(request:Request,env:Env,onChanged?:(reportId:string)=>void):Promise<Response|null> {
+  const path=new URL(request.url).pathname;
+  if(path!=="/participant"&&path!=="/participant.html"&&!path.startsWith("/v1/participant/"))return null;
+  try{
+    if(path==="/participant"||path==="/participant.html"){
+      if(!["GET","HEAD"].includes(request.method))return protect(methodNotAllowed(["GET","HEAD"]));
+      // Assets' automatic HTML handling serves participant.html at the clean path;
+      // requesting the .html name can redirect back here indefinitely.
+      return protect(await env.ASSETS.fetch(new Request(new URL("/participant",request.url),request)));
+    }
+    if(!["GET","POST","DELETE"].includes(request.method))return protect(methodNotAllowed(["GET","POST","DELETE"]));
+    if(request.method!=="GET")requireOrigin(request,env);
+    if(path==="/v1/participant/exchange"&&request.method==="POST"){
+      const input=await readJsonObject(request,2048);const exchanged=await exchangeParticipantAccess(env,text(input,"token"),sessionToken(request));
+      return protect(json({csrfToken:exchanged.csrfToken},{headers:{"set-cookie":cookie(request,exchanged.sessionToken,7*86400)}}));
+    }
+    if(path==="/v1/participant/recovery"&&request.method==="POST"){
+      const input=await readJsonObject(request,2048);
+      await requestParticipantRecovery(env,{reference:text(input,"reference"),email:text(input,"email"),clientAddress:request.headers.get("cf-connecting-ip")??"local"});
+      return protect(json({message:"If those details match an available case and email delivery is configured, a new private link will be sent to the email already on the case. If it does not arrive, contact the service where you reported the issue."},{status:202}));
+    }
+    const token=sessionToken(request);const session=await loadParticipantSession(env.DB,token);
+    if(request.method!=="GET"){
+      const supplied=request.headers.get("x-csrf-token")??"";
+      if(!await secretsEqual(await sha256(supplied),session.csrfHash))throw new ApiError(403,"participant_csrf_denied","Your session changed. Refresh the case and try again.");
+    }
+    if(path==="/v1/participant/session"&&request.method==="DELETE"){
+      await env.DB.prepare(`UPDATE participant_sessions SET revoked_at=?2 WHERE token_hash=?1`).bind(session.tokenHash,new Date().toISOString()).run();
+      return protect(json({signedOut:true},{headers:{"set-cookie":cookie(request,"",0)}}));
+    }
+    if(path==="/v1/participant/case"&&request.method==="GET")return protect(json({case:await loadParticipantCase(env.DB,session),csrfToken:await participantCsrf(env.CONTEXT_SIGNING_SECRET,token)}));
+    if(path==="/v1/participant/messages"&&request.method==="GET"){
+      const before=new URL(request.url).searchParams.get("before")??undefined;
+      if(before&&before.length>200)throw new ApiError(400,"participant_history_cursor_invalid","The history position is invalid. Refresh the case.");
+      return protect(json(await loadParticipantMessages(env.DB,session,before)));
+    }
+    if(path==="/v1/participant/messages"&&request.method==="POST"){
+      const input=await readJsonObject(request,36*1024);const result=await addParticipantInformation(env.DB,session,{body:text(input,"body"),idempotencyKey:request.headers.get("idempotency-key")??""});
+      onChanged?.(session.reportId);return protect(json(result,{status:result.idempotentReplay?200:201}));
+    }
+    if(path==="/v1/participant/appeals"&&request.method==="POST"){
+      const input=await readJsonObject(request,36*1024);const result=await submitParticipantAppeal(env.DB,session,{reason:text(input,"reason"),decisionId:text(input,"decisionId"),idempotencyKey:request.headers.get("idempotency-key")??""});
+      onChanged?.(session.reportId);return protect(json(result,{status:result.idempotentReplay?200:201}));
+    }
+    return protect(json({error:{code:"not_found",message:"This page does not exist."}},{status:404}));
+  }catch(error){
+    const response=apiErrorResponse(error);
+    if(error instanceof ApiError&&error.status===429&&typeof error.details?.retryAfterSeconds==="number")response.headers.set("retry-after",String(error.details.retryAfterSeconds));
+    return protect(response);
+  }
+}

package/template/src/platform-registry-validation.ts

@@ -69,8 +69,28 @@ const methodSet = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]);
 const connectionKinds = new Set<ConnectionKind>(["webhook", "external_api", "customer_worker", "ai_provider", "notification", "email"]);
 const credentialStrategies = new Set<CredentialStrategy>(["none", "static_header", "bearer", "hmac", "oauth2_client_credentials", "oauth2_authorization_code", "mutual_tls", "service_binding"]);
 const componentKinds = new Set<ComponentKind>(["built_in", "webhook_enrichment", "api_enrichment", "workers_ai", "specialist_agent", "action", "message"]);
+const customerComponentKinds = new Set<ComponentKind>(["webhook_enrichment", "api_enrichment", "workers_ai", "action"]);
 const implementationKinds = new Set<ComponentVersionInput["implementationKind"]>(["built_in", "webhook", "external_api", "workers_ai", "specialist_agent", "message_template"]);
 
+const implementationsByComponentKind: Record<ComponentKind, ReadonlySet<ComponentVersionInput["implementationKind"]>> = {
+  built_in: new Set(["built_in"]),
+  webhook_enrichment: new Set(["webhook"]),
+  api_enrichment: new Set(["external_api"]),
+  workers_ai: new Set(["workers_ai"]),
+  specialist_agent: new Set(["specialist_agent"]),
+  action: new Set(["webhook", "external_api"]),
+  message: new Set(["message_template"]),
+};
+
+export function assertComponentRuntimeMatchesKind(
+  kind: ComponentKind,
+  implementationKind: ComponentVersionInput["implementationKind"],
+): void {
+  if (!implementationsByComponentKind[kind].has(implementationKind)) {
+    throw new ApiError(400, "component_implementation_kind_mismatch", "The component implementation does not match its declared kind.");
+  }
+}
+
 function object(value: unknown, name: string): Record<string, unknown> {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new ApiError(400, "invalid_registry_configuration", `${name} must be an object.`);
   return value as Record<string, unknown>;
@@ -345,10 +365,13 @@ export function parseComponentCreate(value: unknown): ComponentCreateInput {
   const key = text(input.key, "component.key", 2, 100);
   if (!keyPattern.test(key)) throw new ApiError(400, "invalid_component_key", "component.key must be lower-case kebab-case.");
   if (typeof input.kind !== "string" || !componentKinds.has(input.kind as ComponentKind)) throw new ApiError(400, "invalid_registry_configuration", "component.kind is unsupported.");
+  if (!customerComponentKinds.has(input.kind as ComponentKind)) throw new ApiError(400, "component_kind_reserved", "This component kind is reserved for product-installed capabilities.");
   if (input.effect_class !== "read_only" && input.effect_class !== "side_effecting") throw new ApiError(400, "invalid_registry_configuration", "effect_class is unsupported.");
-  if (input.owner_kind !== "safest" && input.owner_kind !== "customer") throw new ApiError(400, "invalid_registry_configuration", "owner_kind is unsupported.");
+  if (input.owner_kind !== "customer") throw new ApiError(400, "component_owner_kind_reserved", "Customer-created components must use customer ownership.");
   if (input.kind === "action" && input.effect_class !== "side_effecting") throw new ApiError(400, "action_effect_class_required", "Action components must be side_effecting.");
   if (input.kind !== "action" && input.effect_class === "side_effecting") throw new ApiError(400, "component_effect_mismatch", "Only action components may be side_effecting.");
+  const version = parseComponentVersion(input.version, input.effect_class);
+  assertComponentRuntimeMatchesKind(input.kind as ComponentKind, version.implementationKind);
   return {
     key,
     name: text(input.name, "component.name", 2, 160),
@@ -356,7 +379,7 @@ export function parseComponentCreate(value: unknown): ComponentCreateInput {
     kind: input.kind as ComponentKind,
     effectClass: input.effect_class,
     ownerKind: input.owner_kind,
-    version: parseComponentVersion(input.version, input.effect_class),
+    version,
   };
 }
 

package/template/src/platform-registry.ts

@@ -3,11 +3,13 @@ import { ApiError } from "./report-http";
 import type { OperatorSession } from "./report-types";
 import { validateJsonSchemaValue } from "./workflow-expressions";
 import type { JsonObject, JsonValue } from "./workflow-platform-types";
-import type {
-  ComponentCreateInput,
-  ComponentVersionInput,
-  ConnectionCreateInput,
-  ConnectionVersionInput,
+import {
+  assertComponentRuntimeMatchesKind,
+  type ComponentKind,
+  type ComponentCreateInput,
+  type ComponentVersionInput,
+  type ConnectionCreateInput,
+  type ConnectionVersionInput,
 } from "./platform-registry-validation";
 
 interface MutationRow {
@@ -615,10 +617,11 @@ export async function publishComponentVersion(
     componentId: String(existingMutation.componentId), versionId: String(existingMutation.versionId),
     version: Number(existingMutation.version), idempotentReplay: true,
   };
-  const definition = await db.prepare(`SELECT status, effect_class FROM component_definitions WHERE id = ?1`)
-    .bind(componentId).first<{ status: string; effect_class: string }>();
+  const definition = await db.prepare(`SELECT status, effect_class, component_kind FROM component_definitions WHERE id = ?1`)
+    .bind(componentId).first<{ status: string; effect_class: string; component_kind: ComponentKind }>();
   if (!definition) throw new ApiError(404, "component_not_found", "The component does not exist.");
   if (definition.status === "archived") throw new ApiError(409, "component_archived", "Archived components cannot receive versions.");
+  assertComponentRuntimeMatchesKind(definition.component_kind, input.implementationKind);
   if (!fixtureEvidence(input)) throw new ApiError(409, "component_fixture_gate_not_met", "Passing fixture evidence is required before component publication.");
   if (definition.effect_class === "side_effecting" && !["human", "bounded_auto"].includes(String(input.approvalPolicy.mode))) throw new ApiError(409, "action_approval_policy_required", "A side-effecting version must preserve its approval policy.");
   await requireComponentConnection(db, input);