Claude Code × Stripe で作るサブスクリプションSaaSの実装 — Webhook・権限管理・本番ハマりポイントの全記録

// src/app/api/checkout/route.ts
import Stripe from "stripe";
import { getCloudflareContext } from "@opennextjs/cloudflare";
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY\!, {
  apiVersion: "2024-11-20.acacia",
});
 
export async function POST(request: Request) {
  const { locale, planType, articleSlug } = await request.json();
 
  // plan_type を metadata に必ず設定する
  // verify-session での処理分岐（tip/article/pro/premium）に使用するため省略不可
  const metadata: Record<string, string> = {
    plan_type: planType,
    locale,
  };
  if (articleSlug) {
    metadata.article_slug = articleSlug;
  }
 
  const session = await stripe.checkout.sessions.create({
    payment_method_types: ["card"],
    line_items: [
      {
        // price_id だけだと商品説明・画像が Checkout ページに表示されない（Stripe の仕様）
        // price_data + product_data 方式が必須
        price_data: {
          currency: locale === "ja" ? "jpy" : "usd",
          unit_amount: getUnitAmount(planType, locale), // ¥250 なら 250、$1.75 なら 175
          product_data: {
            name: getProductName(planType, locale),
            description: getProductDescription(planType, locale),
            // 画像がないと説明文も表示されにくい（Stripe の未文書化の挙動）
            images: [`${process.env.NEXT_PUBLIC_SITE_URL}/images/stripe-product.png`],
          },
          // Pro プランのみ recurring を追加（これがないと単発課金になる）
          ...(planType === "pro" && {
            recurring: { interval: "month" },
          }),
        },
        quantity: 1,
      },
    ],
    mode: planType === "pro" ? "subscription" : "payment",
    success_url: `${process.env.NEXT_PUBLIC_SITE_URL}/${locale}/api/verify-session?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${process.env.NEXT_PUBLIC_SITE_URL}/${locale}/membership`,
    metadata,
  });
 
  return Response.json({ url: session.url });
}

// src/app/api/webhook/route.ts
import Stripe from "stripe";
import { getCloudflareContext } from "@opennextjs/cloudflare";
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY\!, {
  apiVersion: "2024-11-20.acacia",
});
 
export async function POST(request: Request) {
  const body = await request.text();
  const signature = request.headers.get("stripe-signature")\!;
 
  let event: Stripe.Event;
  try {
    // Cloudflare Workers では constructEventAsync が必須
    // constructEvent（同期版）は Workers 環境の SubtleCrypto API と非互換で動作しない
    event = await stripe.webhooks.constructEventAsync(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET\!,
      undefined,
      Stripe.createSubtleCryptoProvider() // Workers の Web Crypto API を使用
    );
  } catch (err) {
    console.error("Webhook signature verification failed:", err);
    return new Response("Webhook Error", { status: 400 });
  }
 
  // イベント種別に応じた処理
  switch (event.type) {
    case "checkout.session.completed":
      await handleCheckoutComplete(event.data.object as Stripe.Checkout.Session);
      break;
    case "customer.subscription.updated":
      await handleSubscriptionUpdate(event.data.object as Stripe.Subscription);
      break;
    case "customer.subscription.deleted":
      await handleSubscriptionDelete(event.data.object as Stripe.Subscription);
      break;
    default:
      // 処理しないイベントは無視（200 を返す）
      break;
  }
 
  return new Response("OK", { status: 200 });
}
 
async function handleCheckoutComplete(session: Stripe.Checkout.Session) {
  const { plan_type } = session.metadata ?? {};
  const email = session.customer_details?.email;
 
  if (\!email) {
    console.error("Checkout complete: no email in session");
    return;
  }
 
  const { env } = await getCloudflareContext();
 
  switch (plan_type) {
    case "premium":
      // 永久ライセンス — TTL を 100年に設定（実質期限なし）
      await env.KV.put(
        `site:claudelab:premium:${email}`,
        JSON.stringify({ plan: "premium", grantedAt: Date.now() }),
        { expirationTtl: 60 * 60 * 24 * 365 * 100 }
      );
      break;
 
    case "pro":
      // 月額プラン — subscription.updated イベントで TTL を管理するため
      // ここでは current_period_end まで有効な KV エントリを作成
      const periodEnd = (session as any).subscription_details?.metadata?.period_end
        ?? Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 31; // フォールバック: +31日
      await env.KV.put(
        `site:claudelab:pro:${email}`,
        JSON.stringify({ plan: "pro", periodEnd }),
        { expirationTtl: periodEnd - Math.floor(Date.now() / 1000) + 86400 }
      );
      break;
 
    case "article":
      // 記事単体購入 — 購入済みスラッグリストに追加（べき等性: 重複追加を防ぐ）
      const slug = session.metadata?.article_slug;
      if (slug) {
        const existing = await env.KV.get(
          `site:claudelab:article:${email}`,
          "json"
        ) as { slugs: string[] } | null;
 
        const slugs = existing?.slugs ?? [];
        if (\!slugs.includes(slug)) slugs.push(slug);
 
        await env.KV.put(
          `site:claudelab:article:${email}`,
          JSON.stringify({ email, slugs }),
          { expirationTtl: 60 * 60 * 24 * 365 * 10 } // 10年
        );
      }
      break;
 
    case "tip":
      // チップは権限付与なし — ログのみ
      console.log(`Tip received from ${email} at ${new Date().toISOString()}`);
      break;
  }
}

// src/lib/premium.ts
 
export async function canViewPremium(request: Request): Promise<boolean> {
  const cookieHeader = request.headers.get("cookie") ?? "";
  const token = parseCookie(cookieHeader, "premium_token");
  if (\!token) return false;
 
  try {
    const { email } = JSON.parse(atob(token));
    const { env } = await getCloudflareContext();
 
    // Tier 1: KV から直接確認（最も信頼性が高い）
    const premiumData = await env.KV.get(`site:claudelab:premium:${email}`);
    if (premiumData) return true;
 
    // Pro プランも確認
    const proData = await env.KV.get(`site:claudelab:pro:${email}`, "json") as { periodEnd?: number } | null;
    if (proData?.periodEnd && proData.periodEnd > Math.floor(Date.now() / 1000)) {
      return true;
    }
 
    return false;
  } catch {
    return false;
  }
}
 
export async function getArticleAccess(slug: string, request: Request): Promise<boolean> {
  const cookieHeader = request.headers.get("cookie") ?? "";
  const purchases = parseCookie(cookieHeader, "article_purchases");
  if (\!purchases) return false;
 
  try {
    const { email, slugs: cookieSlugs } = JSON.parse(atob(purchases)) as {
      email: string;
      slugs: string[];
    };
 
    const { env } = await getCloudflareContext();
 
    // Tier 1: KV 確認（最新の購入記録）
    const kvData = await env.KV.get(
      `site:claudelab:article:${email}`,
      "json"
    ) as { slugs: string[] } | null;
    if (kvData?.slugs?.includes(slug)) return true;
 
    // Tier 2: Cookie のスラッグリストで確認（KV 障害時のフォールバック）
    if (cookieSlugs?.includes(slug)) return true;
 
    // ⚠️ deny-by-default: 必ず false を返す（return true は絶対禁止）
    // KV にも Cookie にも記録がなければアクセス拒否
    return false;
  } catch {
    return false;
  }
}

// src/app/api/verify-session/route.ts 内での Cookie 発行
 
// article_purchases Cookie: 購入済みスラッグリストを蓄積
const existingPurchases = parseCookie(cookieHeader, "article_purchases");
let currentSlugs: string[] = [];
if (existingPurchases) {
  try {
    const parsed = JSON.parse(atob(existingPurchases));
    currentSlugs = parsed.slugs ?? [];
  } catch {}
}
if (slug && \!currentSlugs.includes(slug)) {
  currentSlugs.push(slug);
}
 
const cookieValue = btoa(JSON.stringify({ email, slugs: currentSlugs }));
 
// セキュリティ設定を必ず付ける
const cookieOptions = [
  `article_purchases=${cookieValue}`,
  "Max-Age=315360000", // 10年
  "Path=/",
  "HttpOnly",  // JavaScript からのアクセスを禁止
  "Secure",    // HTTPS のみ
  "SameSite=Lax",
].join("; ");

async function handleSubscriptionUpdate(subscription: Stripe.Subscription) {
  const email = await getEmailFromCustomer(subscription.customer as string);
  if (\!email) return;
 
  const { env } = await getCloudflareContext();
 
  if (subscription.status === "active") {
    // 次回更新日 + 1日の猶予期間まで TTL を延長
    const periodEnd = subscription.current_period_end;
    const ttl = periodEnd - Math.floor(Date.now() / 1000) + 86400; // +1日の猶予
 
    await env.KV.put(
      `site:claudelab:pro:${email}`,
      JSON.stringify({ plan: "pro", periodEnd, updatedAt: Date.now() }),
      { expirationTtl: Math.max(ttl, 86400) } // 最低1日は保持
    );
  } else if (["past_due", "canceled", "unpaid"].includes(subscription.status)) {
    // 支払い失敗・解約 — KV エントリを削除してアクセスを即座に無効化
    await env.KV.delete(`site:claudelab:pro:${email}`);
    console.log(`Subscription revoked for ${email}: status=${subscription.status}`);
  }
}
 
async function handleSubscriptionDelete(subscription: Stripe.Subscription) {
  const email = await getEmailFromCustomer(subscription.customer as string);
  if (email) {
    const { env } = await getCloudflareContext();
    await env.KV.delete(`site:claudelab:pro:${email}`);
  }
}
 
// Stripe Customer から email を取得するヘルパー
async function getEmailFromCustomer(customerId: string): Promise<string | null> {
  try {
    const customer = await stripe.customers.retrieve(customerId);
    if (customer.deleted) return null;
    return (customer as Stripe.Customer).email;
  } catch (err) {
    console.error("Failed to retrieve customer:", err);
    return null;
  }
}

// 購入ボタンコンポーネントでの対処
import { useEffect, useState } from "react";
 
export function PurchaseButton({ planType }: { planType: string }) {
  const [isLoading, setIsLoading] = useState(false);
 
  useEffect(() => {
    // bfcache からの復元時にローディング状態をリセット
    const handlePageShow = (e: PageTransitionEvent) => {
      if (e.persisted) {
        setIsLoading(false);
      }
    };
    window.addEventListener("pageshow", handlePageShow);
    return () => window.removeEventListener("pageshow", handlePageShow);
  }, []);
 
  const handleCheckout = async () => {
    setIsLoading(true);
    try {
      const res = await fetch("/api/checkout", {
        method: "POST",
        body: JSON.stringify({ planType }),
        headers: { "Content-Type": "application/json" },
      });
      const { url } = await res.json();
      window.location.href = url; // ← Stripe Checkout へリダイレクト
    } catch {
      setIsLoading(false);
    }
  };
 
  // ⚠️ <a> タグではなく <button> を使う（2クリック問題を防ぐ）
  return (
    <button onClick={handleCheckout} disabled={isLoading}>
      {isLoading ? "処理中..." : "購入する"}
    </button>
  );
}

export async function POST(request: Request, { waitUntil }: { waitUntil: (promise: Promise<any>) => void }) {
  // ... イベント検証 ...
 
  // まず Stripe に 200 を返す（タイムアウト防止）
  waitUntil(processWebhookAsync(event)); // バックグラウンドで処理継続
  return new Response("OK", { status: 200 });
}

// イベントの到着順に依存しない merge 書き込み
async function upsertMembership(kv: KVNamespace, email: string, patch: Record<string, unknown>) {
  const key = `site:claudelab:member:${email}`;
  const current = JSON.parse((await kv.get(key)) ?? "{}");
  const merged = { ...current, ...patch, updatedAt: Date.now() };
  await kv.put(key, JSON.stringify(merged));
  return merged;
}