Foil Gate

Developer runs:  npx signup yourproduct
                    ↓
CLI creates ephemeral delivery keypair
                    ↓
CLI opens browser → Consent page (Foil-scored)
                    ↓
User clicks Approve → Gate calls your webhook
                    ↓
Your webhook creates account → Returns encrypted env bundle
                    ↓
Gate adds its own encrypted outputs → CLI decrypts locally
                    ↓
CLI writes to .env → CLI sends receipt ack → Gate purges ciphertext

curl -X POST https://api.usefoil.com/v1/gate/services \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "yourproduct",
    "name": "Your Product",
    "description": "One-line description that appears on the consent screen.",
    "website": "https://yourproduct.com",
    "webhook_endpoint_id": "we_0123456789abcdef0123456789abcdef",
    "docs_url": "https://yourproduct.com/docs",
    "dashboard_login_url": "https://app.yourproduct.com/auth/gate",
    "env_vars": [
      { "name": "Publishable key", "key": "YOURPRODUCT_PUBLISHABLE_KEY", "secret": false },
      { "name": "Secret key",      "key": "YOURPRODUCT_SECRET_KEY",      "secret": true  }
    ],
    "branding": {
      "logo_url": "https://yourproduct.com/logo.svg",
      "primary_color": "#3B7DD8",
      "secondary_color": "#5B9CF5"
    },
    "consent": {
      "terms_url":   "https://yourproduct.com/terms",
      "privacy_url": "https://yourproduct.com/privacy"
    },
    "discoverable": true
  }'

import express from 'express';
import {
  createGateApprovedWebhookResponse,
  parseWebhookEvent,
  validateGateApprovedWebhookPayload,
  verifyGateWebhookSignature,
} from '@abxy/foil-server';

const app = express();

app.use(express.json({
  verify: (req, _res, buf) => {
    (req as express.Request & { rawBody?: string }).rawBody = buf.toString('utf8');
  },
}));

// POST /your-webhook-endpoint
app.post('/v1/gate/webhook', async (req, res) => {
  const rawBody = (req as express.Request & { rawBody?: string }).rawBody;
  const timestamp = req.header('x-foil-timestamp');
  const signature = req.header('x-foil-signature');

  if (!rawBody || !timestamp || !signature || !verifyGateWebhookSignature({
    secret: process.env.FOIL_WEBHOOK_SECRET!,
    timestamp,
    rawBody,
    signature,
  })) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = parseWebhookEvent(rawBody);
  if (event.type !== 'gate.session.approved') {
    return res.status(400).json({ error: 'Unexpected event' });
  }
  const payload = validateGateApprovedWebhookPayload(event.data);
  const {
    gate_session_id,
    gate_account_id,
    service_id,
    account_name,
    metadata,
    delivery,
  } = payload;

  const existing = await findProvisioningByGateSession(gate_session_id);
  if (existing) return res.json(existing);

  // 1. Create the account in your system
  const account = await createAccount(account_name);
  const apiKey = await createApiKey(account.id);

  // 2. Build only the outputs owned by your service.
  //    Gate-owned outputs (for example agent tokens) are added separately by Gate.
  //    service_id lets a multi-service webhook branch if needed.
  if (service_id !== 'yourproduct') {
    return res.status(400).json({ error: 'Unknown service' });
  }

  const { encrypted_delivery } = createGateApprovedWebhookResponse({
    delivery,
    outputs: {
      YOURPRODUCT_PUBLISHABLE_KEY: apiKey.publishableKey,
      YOURPRODUCT_SECRET_KEY: apiKey.secretKey,
    },
  });

  // 3. Persist the exact ciphertext for retries keyed by gate_session_id.
  await saveProvisioningResult(gate_session_id, { encrypted_delivery, gate_account_id, metadata });

  res.json({
    encrypted_delivery,
  });
});

import { Foil } from '@abxy/foil-server';

const foil = new Foil({
  secretKey: process.env.FOIL_SECRET_KEY!,
});

// GET /auth/gate?code=...
app.get('/auth/gate', async (req, res) => {
  const code = req.query.code;

  // Verify the short-lived dashboard login token with Gate
  const data = await foil.gate.loginSessions.consume({
    code: String(code),
  });

  // data.gate_account_id — look up the user in your system
  // Create a session however your auth system works
  // Redirect to your dashboard
});

{
  "id": "wevt_abc123...",
  "object": "webhook_event",
  "type": "gate.session.approved",
  "created": "2026-03-24T20:00:05.000Z",
  "data": {
    "service_id": "foil",
    "gate_session_id": "gate_abc123...",
    "gate_account_id": "gacct_abc123...",
    "account_name": "my-project",
    "metadata": null,
    "delivery": {
      "version": 1,
      "algorithm": "x25519-hkdf-sha256/aes-256-gcm",
      "key_id": "<base64url sha256 of public_key>",
      "public_key": "<base64url raw X25519 public key>"
    },
    "foil": {
      "verdict": "human",
      "score": 0.12
    }
  }
}

{
  "encrypted_delivery": {
    "version": 1,
    "algorithm": "x25519-hkdf-sha256/aes-256-gcm",
    "key_id": "<same key_id>",
    "ephemeral_public_key": "<base64url raw X25519 public key>",
    "salt": "<base64url 32 bytes>",
    "iv": "<base64url 12 bytes>",
    "ciphertext": "<base64url>",
    "tag": "<base64url 16 bytes>"
  }
}

{
  "version": 1,
  "outputs": {
    "FOIL_PUBLISHABLE_KEY": "pk_live_...",
    "FOIL_SECRET_KEY": "sk_live_..."
  }
}