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.