---

name: juicebox-security-basics description: 'Apply Juicebox security best practices.

Trigger: "juicebox security", "juicebox api key security".

' allowed-tools: Read, Write, Grep version: 1.16.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• recruiting
• juicebox compatibility: Designed for Claude Code

---

Juicebox Security Basics

Overview

Juicebox provides AI-powered people search and analysis, processing datasets containing professional profiles, contact enrichment data, and query results. Security concerns include API key protection, GDPR/CCPA compliance for candidate and contact data, data retention policy enforcement, and ensuring enriched contact information (emails, phone numbers) is not leaked through logs or unencrypted storage. A compromised API key grants access to people search and enrichment capabilities.

API Key Management

function createJuiceboxClient(): { apiKey: string; baseUrl: string } {
  const apiKey = process.env.JUICEBOX_API_KEY;
  if (!apiKey) {
    throw new Error("Missing JUICEBOX_API_KEY — store in secrets manager, never in code");
  }
  // Juicebox keys access people data — treat as PII-adjacent
  console.log("Juicebox client initialized (key suffix:", apiKey.slice(-4), ")");
  return { apiKey, baseUrl: "https://api.juicebox.ai/v1" };
}

Webhook Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyJuiceboxWebhook(req: Request, res: Response, next: NextFunction): void {
  const signature = req.headers["x-juicebox-signature"] as string;
  const secret = process.env.JUICEBOX_WEBHOOK_SECRET!;
  const expected = crypto.createHmac("sha256", secret).update(req.body).digest("hex");
  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    res.status(401).send("Invalid signature");
    return;
  }
  next();
}

Input Validation

import { z } from "zod";

const PeopleSearchSchema = z.object({
  query: z.string().min(1).max(500),
  filters: z.object({
    location: z.string().optional(),
    company: z.string().optional(),
    title: z.string().optional(),
    industry: z.string().optional(),
  }).optional(),
  max_results: z.number().int().min(1).max(100).default(25),
  enrich_contacts: z.boolean().default(false),
});

function validateSearchQuery(data: unknown) {
  return PeopleSearchSchema.parse(data);
}

Data Protection

const JUICEBOX_PII_FIELDS = ["personal_email", "phone_number", "social_profiles", "home_address", "enrichment_data"];

function redactJuiceboxLog(record: Record<string, unknown>): Record<string, unknown> {
  const redacted = { ...record };
  for (const field of JUICEBOX_PII_FIELDS) {
    if (field in redacted) redacted[field] = "[REDACTED]";
  }
  return redacted;
}

Security Checklist

• API keys stored in secrets manager, separate keys per environment
• Enriched contact data encrypted at rest
• GDPR consent documented for EU candidate data
• CCPA opt-out mechanism implemented for California residents
• Data retention policy enforced (auto-delete after defined period)
• Contact enrichment results never logged in plaintext
• Search queries redacted in application logs
• Pre-commit hook blocks jb_live_* credential patterns

Error Handling

Vulnerability	Risk	Mitigation
Leaked API key	Unauthorized people search and enrichment	Secrets manager + key rotation
Contact data in logs	PII exposure violating GDPR/CCPA	Field-level redaction pipeline
Missing data retention	Stale candidate data accumulates	Automated retention enforcement
Enrichment without consent	Privacy regulation violation	Consent gate before enrichment calls
Unencrypted contact storage	Bulk PII breach from database leak	Encryption at rest + access controls

Prerequisites

• A data classification, approved lawful-use basis, synthetic test fixture, secrets-manager references, least-privilege roles, and an incident owner with a tested revocation path.

Instructions

1. Run the security checks only against a sandbox fixture and reject literal credentials, unapproved sources, or unapproved destinations.
2. Verify suppression, encryption, access scope, audit-log redaction, retention, and contacts_exported=0 before approving a release.
3. Use staged canaries; halt on any policy, scope, or retention drift and revoke temporary access before rollback.
4. Preserve only aggregate, redacted evidence and delete test records according to the approved retention window.

Output

Record a security receipt with environment, fixture classification, access review, suppression/encryption/redaction results, no-export assertion, owner approval, retention/deletion proof, and rollback reference. Exclude identities, enrichment values, and secrets.

Examples

env=staging; fixture=synthetic; rbac=least-privilege; suppression=pass; encryption=pass; contacts_exported=0; cleanup=verified is an acceptable release-gate record.

Resources

• Juicebox Privacy
• OWASP API Security Top 10

Next Steps

See juicebox-prod-checklist.