Starter Kit

Complete end-to-end flow: activate two identities, send a sealed envelope between them, and verify the delivery. Uses native fetch — no dependencies required.

// ═══════════════════════════════════════════════════
// Arcform DID.comms — Node.js Starter Kit
// ═══════════════════════════════════════════════════
// 1. Save this file as index.js
// 2. Run: node index.js
// 3. Your identity activates, sends a message, and verifies it
// ═══════════════════════════════════════════════════

const API_BASE = "https://arcform-api.com";

// ── Step 1: Activate a sovereign identity ──────────
async function activate(label) {
  const res = await fetch(API_BASE + "/v1/did/activate", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ label }),
  });
  const data = await res.json();
  console.log("✓ Identity activated");
  console.log("  DID:", data.did);
  console.log("  API Key:", data.api_key_id);
  console.log("  Fingerprint:", data.fingerprint);
  return data;
}

// ── Step 2: Send a sealed envelope ─────────────────
async function send(apiKeyId, token, recipientKey, message) {
  const res = await fetch(API_BASE + "/v1/channel/send", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer " + token,
      "X-DID-API-Key": apiKeyId,
    },
    body: JSON.stringify({ to: recipientKey, message }),
  });
  const data = await res.json();
  console.log("✓ Envelope sent");
  console.log("  Hash:", data.envelope_hash);
  console.log("  Encryption:", data.encryption?.status);
  console.log("  Hops:", data.routing?.hops);
  return data;
}

// ── Step 3: Verify delivery ────────────────────────
async function verify(envelopeHash) {
  const res = await fetch(API_BASE + "/v1/verify", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ envelope_hash: envelopeHash }),
  });
  const data = await res.json();
  console.log("✓ Verification complete");
  console.log("  Status:", data.status);
  console.log("  Identity Verdict:", data.identity?.identity_verdict);
  console.log("  Checksum Valid:", data.integrity?.proof_checksum_valid);
  return data;
}

// ── Step 4: Check usage ────────────────────────────
async function status(apiKeyId, token) {
  const res = await fetch(API_BASE + "/v1/did/status", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer " + token,
      "X-DID-API-Key": apiKeyId,
    },
  });
  const data = await res.json();
  console.log("✓ Status check");
  console.log("  Messages sent:", data.usage?.messages_sent);
  console.log("  Remaining:", data.usage?.messages_remaining);
  console.log("  Plan:", data.plan);
  return data;
}

// ── Run the full flow ──────────────────────────────
async function main() {
  console.log("\n══ Arcform DID.comms Starter Kit ══\n");

  // Activate two identities
  const alice = await activate("Alice — Starter Kit");
  const bob = await activate("Bob — Starter Kit");

  console.log("\n── Sending sealed envelope ──\n");

  // Alice sends to Bob (use your session token)
  // For this demo, we use a placeholder token
  const receipt = await send(
    alice.api_key_id,
    "YOUR_SESSION_TOKEN",
    bob.api_key_id,
    "Hello from Alice — first sovereign message"
  );

  console.log("\n── Verifying delivery ──\n");
  await verify(receipt.envelope_hash);

  console.log("\n══ Done. Your sovereign channel is live. ══\n");
}

main().catch(console.error);

Same full flow in Python — activate, send, verify. Install requests with pip, paste your session token, and run.

# ═══════════════════════════════════════════════════
# Arcform DID.comms — Python Starter Kit
# ═══════════════════════════════════════════════════
# 1. Save this file as starter.py
# 2. pip install requests
# 3. Run: python starter.py
# ═══════════════════════════════════════════════════

import requests

API_BASE = "https://arcform-api.com"


# ── Step 1: Activate a sovereign identity ──────────
def activate(label: str) -> dict:
    res = requests.post(
        f"{API_BASE}/v1/did/activate",
        json={"label": label},
    )
    data = res.json()
    print(f"✓ Identity activated")
    print(f"  DID: {data['did']}")
    print(f"  API Key: {data['api_key_id']}")
    print(f"  Fingerprint: {data['fingerprint']}")
    return data


# ── Step 2: Send a sealed envelope ─────────────────
def send(api_key_id: str, token: str, recipient_key: str, message: str) -> dict:
    res = requests.post(
        f"{API_BASE}/v1/channel/send",
        headers={
            "Authorization": f"Bearer {token}",
            "X-DID-API-Key": api_key_id,
        },
        json={"to": recipient_key, "message": message},
    )
    data = res.json()
    print(f"✓ Envelope sent")
    print(f"  Hash: {data['envelope_hash']}")
    print(f"  Encryption: {data['encryption']['status']}")
    print(f"  Hops: {data['routing']['hops']}")
    return data


# ── Step 3: Verify delivery ────────────────────────
def verify(envelope_hash: str) -> dict:
    res = requests.post(
        f"{API_BASE}/v1/verify",
        json={"envelope_hash": envelope_hash},
    )
    data = res.json()
    print(f"✓ Verification complete")
    print(f"  Status: {data['status']}")
    print(f"  Identity Verdict: {data['identity']['identity_verdict']}")
    print(f"  Checksum Valid: {data['integrity']['proof_checksum_valid']}")
    return data


# ── Step 4: Check usage ────────────────────────────
def get_status(api_key_id: str, token: str) -> dict:
    res = requests.post(
        f"{API_BASE}/v1/did/status",
        headers={
            "Authorization": f"Bearer {token}",
            "X-DID-API-Key": api_key_id,
        },
    )
    data = res.json()
    print(f"✓ Status check")
    print(f"  Messages sent: {data['usage']['messages_sent']}")
    print(f"  Remaining: {data['usage']['messages_remaining']}")
    print(f"  Plan: {data['plan']}")
    return data


# ── Run the full flow ──────────────────────────────
if __name__ == "__main__":
    print("\n══ Arcform DID.comms Starter Kit ══\n")

    # Activate two identities
    alice = activate("Alice — Starter Kit")
    bob = activate("Bob — Starter Kit")

    print("\n── Sending sealed envelope ──\n")

    # Alice sends to Bob (use your session token)
    receipt = send(
        alice["api_key_id"],
        "YOUR_SESSION_TOKEN",
        bob["api_key_id"],
        "Hello from Alice — first sovereign message",
    )

    print("\n── Verifying delivery ──\n")
    verify(receipt["envelope_hash"])

    print("\n══ Done. Your sovereign channel is live. ══\n")

Production-ready webhook receiver with HMAC-SHA256 signature verification. Expose with ngrok for local development, then register the URL via /v1/webhooks/register.

// ═══════════════════════════════════════════════════
// Arcform DID.comms — Webhook Handler (Express.js)
// ═══════════════════════════════════════════════════
// 1. npm install express crypto
// 2. node webhook-handler.js
// 3. Expose via ngrok: ngrok http 3001
// 4. Register the URL: POST /v1/webhooks/register
// ═══════════════════════════════════════════════════

const express = require("express");
const crypto = require("crypto");

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.DIDCOMMS_WEBHOOK_SECRET || "whsec_your_secret";

// ── Signature verification ─────────────────────────
function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(payload))
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expected, "hex")
  );
}

// ── Webhook endpoint ───────────────────────────────
app.post("/webhooks/didcomms", (req, res) => {
  const signature = req.headers["x-didcomms-signature"];

  if (!signature || !verifySignature(req.body, signature, WEBHOOK_SECRET)) {
    console.error("✗ Invalid webhook signature");
    return res.status(401).json({ error: "Bad signature" });
  }

  const { event, envelope_id, sender, encryption } = req.body;

  console.log("✓ Webhook received");
  console.log("  Event:", event);
  console.log("  Envelope:", envelope_id);
  console.log("  Sender:", sender);
  console.log("  Encrypted:", encryption?.status);

  // Process the sealed envelope here
  // e.g. store in database, trigger notification, etc.

  res.status(200).json({ received: true });
});

app.listen(3001, () => {
  console.log("Webhook handler listening on http://localhost:3001");
  console.log("Expose via: ngrok http 3001");
});