Astro 5 Actions & Server Islands: Lightweight E-Signature Integration (2026)

// astro.config.mjs
import { defineConfig, envField } from "astro/config";
import vercel from "@astrojs/vercel";

export default defineConfig({
  // In Astro 5, static output automatically supports per-route SSR,
  // Astro Actions, and server:defer Server Islands via your adapter
  output: "static",
  adapter: vercel(),
  env: {
    schema: {
      SIGNBEE_API_KEY: envField.string({
        context: "server",
        access: "secret",
      }),
      SIGNBEE_WEBHOOK_SECRET: envField.string({
        context: "server",
        access: "secret",
      }),
      SIGNBEE_SENDER_NAME: envField.string({
        context: "server",
        access: "public",
        default: "Vanguard Digital Studio",
      }),
      SIGNBEE_SENDER_EMAIL: envField.string({
        context: "server",
        access: "public",
        default: "legal@vanguardstudio.io",
      }),
      PUBLIC_PORTAL_URL: envField.string({
        context: "client",
        access: "public",
        default: "https://proposals.vanguardstudio.io",
      }),
    },
  },
});

// src/actions/index.ts
import { defineAction, ActionError } from "astro:actions";
import { z } from "astro:schema";
import {
  SIGNBEE_API_KEY,
  SIGNBEE_SENDER_NAME,
  SIGNBEE_SENDER_EMAIL,
  PUBLIC_PORTAL_URL,
} from "astro:env/server";

export const server = {
  dispatchProposalContract: defineAction({
    accept: "form",
    input: z.object({
      proposalId: z.string().min(3),
      clientOrganization: z.string().min(2, "Organization name is required"),
      signerFullName: z.string().min(2, "Signer full name is required"),
      signerEmail: z.string().email("Valid corporate email is required"),
      projectRetainerUsd: z.coerce.number().min(500).max(500000),
      includeDedicatedSla: z.coerce.boolean().optional().default(false),
    }),
    handler: async (input) => {
      const slaFee = input.includeDedicatedSla ? 2500 : 0;
      const totalValue = input.projectRetainerUsd + slaFee;
      const issueDate = new Date().toISOString().split("T")[0];

      const markdownDocument = [
        `# Statement of Work & Master Retainer — ${input.clientOrganization}`,
        "",
        `**Proposal Reference:** ${input.proposalId} | **Effective Date:** ${issueDate}`,
        "",
        `This Statement of Work ("SOW") is entered into between **${SIGNBEE_SENDER_NAME}** ("Agency") and **${input.clientOrganization}** ("Client").`,
        "",
        "## 1. Deliverable & Fee Schedule",
        "",
        "| Workstream | Scope Description | Fee (USD) |",
        "| :--- | :--- | :--- |",
        `| Core Engineering Retainer | Astro 5 Architecture & Edge Deployment | $${input.projectRetainerUsd.toLocaleString()} |`,
        input.includeDedicatedSla
          ? "| Priority 24/7 SLA Addendum | 15-Minute Incident Response & Dedicated Slack | $2,500 |"
          : "| Standard Support | Business Hours Engineering Support | Included |",
        `| **Total Contract Value** | **Net-15 Electronic Invoicing** | **$${totalValue.toLocaleString()}** |`,
        "",
        "## 2. Intellectual Property & Confidentiality",
        "Upon full settlement of invoices, Agency assigns all right, title, and interest in custom deliverable source code to Client. Both parties agree to maintain strict confidentiality regarding proprietary data.",
        "",
        "## 3. Cryptographic Execution",
        "Executed electronically via Signbee with an immutable SHA-256 audit certificate compliant with ESIGN, UETA, and eIDAS.",
      ].join("\n");

      const response = await fetch("https://signb.ee/api/v1/send", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${SIGNBEE_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          title: `Statement of Work (${input.proposalId}) — ${input.clientOrganization}`,
          markdown: markdownDocument,
          sender_name: SIGNBEE_SENDER_NAME,
          sender_email: SIGNBEE_SENDER_EMAIL,
          recipient_name: input.signerFullName,
          recipient_email: input.signerEmail,
          expires_in_days: 14,
          webhook_url: `${PUBLIC_PORTAL_URL}/api/webhooks/signbee`,
        }),
      });

      if (!response.ok) {
        const errorBody = await response.json().catch(() => ({}));
        throw new ActionError({
          code: "BAD_REQUEST",
          message:
            errorBody.error ||
            "Signbee API rejected the contract dispatch request.",
        });
      }

      const data = await response.json();
      return {
        documentId: data.id as string,
        status: data.status as string,
        verifyUrl: data.verify_url as string,
      };
    },
  }),
};

---
// src/components/ContractStatusIsland.astro
import { SIGNBEE_API_KEY } from "astro:env/server";

interface Props {
  documentId: string;
}

const { documentId } = Astro.props;

const res = await fetch(`https://signb.ee/api/v1/documents/${documentId}`, {
  headers: {
    Authorization: `Bearer ${SIGNBEE_API_KEY}`,
  },
});

const doc = res.ok ? await res.json() : null;
---

{doc ? (
  <div class="p-5 rounded-xl bg-zinc-900 border border-zinc-800 flex items-center justify-between">
    <div>
      <p class="text-xs font-mono text-zinc-400">
        Document ID: {doc.id} • Recipient: {doc.recipient_email}
      </p>
      <p class="text-base font-bold text-zinc-100 mt-1">
        Status: <span class={doc.status === "signed" ? "text-emerald-400" : "text-amber-400"}>
          {doc.status.toUpperCase()}
        </span>
      </p>
    </div>
    {doc.status === "signed" && (
      <a
        href={doc.verify_url}
        target="_blank"
        rel="noopener noreferrer"
        class="px-4 py-2 rounded-lg bg-emerald-500/10 text-emerald-400 border border-emerald-500/30 text-xs font-mono"
      >
        Verify SHA-256 Certificate
      </a>
    )}
  </div>
) : (
  <div class="p-4 rounded-xl bg-zinc-900/60 border border-zinc-800 text-xs text-zinc-400">
    Awaiting contract dispatch...
  </div>
)}

<!-- Usage inside src/pages/proposals/[slug].astro (Statically Cached Page) -->
<!--
<ContractStatusIsland server:defer documentId={proposal.signbeeDocumentId}>
  <div slot="fallback" class="p-5 rounded-xl bg-zinc-900/40 border border-zinc-800 animate-pulse text-xs text-zinc-500">
    Checking live cryptographic signature status...
  </div>
</ContractStatusIsland>
-->

// src/pages/api/webhooks/signbee.ts
export const prerender = false;

import type { APIRoute } from "astro";
import { createHmac, timingSafeEqual } from "node:crypto";
import { SIGNBEE_WEBHOOK_SECRET } from "astro:env/server";

export const POST: APIRoute = async ({ request }) => {
  const signature = request.headers.get("x-signbee-signature");
  if (!signature) {
    return new Response(
      JSON.stringify({ error: "Missing X-Signbee-Signature header" }),
      { status: 401, headers: { "Content-Type": "application/json" } }
    );
  }

  // Read exact raw request body text before JSON parsing
  const rawBody = await request.text();

  const expectedDigest = createHmac("sha256", SIGNBEE_WEBHOOK_SECRET)
    .update(rawBody, "utf8")
    .digest("hex");

  const cleanProvided = signature.replace(/^sha256=/, "");
  const providedBuf = Buffer.from(cleanProvided, "hex");
  const expectedBuf = Buffer.from(expectedDigest, "hex");

  if (
    providedBuf.length !== expectedBuf.length ||
    !timingSafeEqual(providedBuf, expectedBuf)
  ) {
    return new Response(
      JSON.stringify({ error: "Invalid cryptographic webhook signature" }),
      { status: 401, headers: { "Content-Type": "application/json" } }
    );
  }

  const eventPayload = JSON.parse(rawBody);

  if (eventPayload.event === "document.signed") {
    // Trigger Astro DB / Turso update, unlock client portal, or notify Slack
    console.info(
      `[Astro Signbee Webhook] Contract ${eventPayload.document_id} signed. SHA-256: ${eventPayload.sha256_hash}`
    );
  }

  return new Response(
    JSON.stringify({ ok: true, documentId: eventPayload.document_id }),
    { status: 200, headers: { "Content-Type": "application/json" } }
  );
};