🔒 CapConnect

A privacy-first, zero-knowledge data connector for the cookieless era.

Clean → Hash (SHA-256) → Forward. First-party customer data is normalized and irreversibly hashed in memory before it is relayed to Meta Conversions API and Google Ads Enhanced Conversions. No raw PII ever touches a disk, a log, or a database.

Why CapConnect exists

Third-party cookies are gone. To keep measuring conversions, advertisers must send first-party data server-to-server. But doing that safely is the hard part: the moment raw emails and phone numbers leave your perimeter, your legal and security teams own a new liability.

CapConnect is the safe middle layer. It accepts your raw events, normalizes and SHA-256 hashes every personal field the instant it arrives, and forwards only those one-way digests to the ad platforms — exactly the way Meta and Google specify. Because the plaintext exists only transiently in process memory and is never persisted, there is nothing to leak from CapConnect's storage. There is no storage.

For CTOs & Legal: CapConnect is a stateless relay. It holds no datastore, writes no PII to disk, and emits no PII in logs. The only personal data it transmits is already a non-reversible SHA-256 hash, sent over TLS to Meta/Google — the same hashing the platforms' own SDKs perform client-side.

✨ Features

Zero-knowledge by construction — plaintext PII lives only on the call stack during a single request; it is GC-eligible the moment the response is returned.
Spec-accurate normalization — email lower/trim, phone → E.164 (auto-prepends the country code, e.g. 81 for Japan), names/city/state/zip/DOB/gender all formatted per the official Meta & Google guidelines.
SHA-256 hashing with idempotent pass-through for upstream-pre-hashed inputs.
Meta Conversions API with deduplication event_id support to pair with the browser Pixel.
Google Ads Enhanced Conversions via uploadClickConversions with userIdentifiers.
Concurrent, fault-isolated dispatch — one platform failing never blocks the other.
Automatic retries with exponential backoff + jitter on transient errors (network / 429 / 5xx).
Automatic Google OAuth refresh (optional) — refresh-token exchange, in-memory caching, concurrent-refresh coalescing; nothing persisted.
Single & batch webhook endpoints (/v1/collect, /v1/collect/batch).
Hardened Express server — shared-secret auth (constant-time compare), body-size caps, x-powered-by disabled, graceful shutdown.
Strict TypeScript end to end (exactOptionalPropertyTypes, noUncheckedIndexedAccess, …).
80 unit/integration tests (Vitest + Supertest), ESLint type-checked rules, multi-stage Docker image, and GitHub Actions CI.

🛡 The Zero-Knowledge Guarantee

flowchart LR
A["Upstream source<br/>(Webhook / CSV parse)"] -->|HTTPS + shared secret| B["CapConnect<br/>/v1/collect"]
subgraph MEM["⏱ In-memory only — never persisted, never logged"]
direction TB
C["Validate contract"] --> D["Normalize<br/>email · phone · name · address"]
D --> E["SHA-256 hash<br/>(irreversible, one-way)"]
E --> F["Build provider payloads<br/>(hashed digests only)"]
end
B --> C
F -->|TLS| G["Meta Conversions API<br/>(event_id dedup)"]
F -->|TLS| H["Google Ads API<br/>Enhanced Conversions"]
G --> I["Structured, PII-free<br/>dispatch report"]
H --> I
I -->|JSON response| A
classDef mem fill:#0b3d2e,stroke:#10b981,color:#e6fffa;
class MEM,C,D,E,F mem;

What crosses each boundary:

Boundary	Data in transit	Form
Upstream → CapConnect	Raw identifiers + event metadata	Plaintext over TLS (you control this hop)
Inside CapConnect	Identifiers	Normalized then SHA-256 hashed, in memory only
CapConnect → Meta/Google	Identifiers	SHA-256 hex digests + un-hashed match-support fields (fbc/fbp/IP/UA/gclid) per platform spec
CapConnect → Upstream	Dispatch outcome	No PII — only `event_id`, status, provider trace ids

🏗 Architecture

flowchart TD
subgraph SRC["src/"]
SV["server.ts<br/>Express app · auth · validation · routing"]
NM["utils/normalizer.ts<br/>normalize + SHA-256 (pure functions)"]
CP["services/capi.ts<br/>Meta + Google payload build & POST"]
TY["types/index.ts<br/>strict shared types"]
end
SV -->|"normalizeAndHash()"| NM
SV -->|"dispatchToAllProviders()"| CP
NM --- TY
CP --- TY
SV --- TY

File	Responsibility
`src/types/index.ts`	Single source of truth for every shape: raw input, hashed IR, provider payloads, responses, config.
`src/utils/normalizer.ts`	Field-by-field normalization (Meta/Google spec) + SHA-256. Pure, no I/O, no logging.
`src/utils/retry.ts`	Exponential-backoff retry helper; retries transient errors only.
`src/services/capi.ts`	Builds & POSTs Meta CAPI and Google Ads payloads concurrently; PII-free error reporting.
`src/services/googleAuth.ts`	Google OAuth token providers (static + auto-refreshing).
`src/server.ts`	Hardened Express server, config loading/validation, webhook endpoints, graceful shutdown.
`tests/`	Vitest unit + Supertest integration suites (80 tests).

🚀 Quick start

# 1. Install
npm install
# 2. Configure
cp .env.example .env
# …then edit .env with your Pixel id, access tokens, etc.# Generate a webhook secret: openssl rand -hex 32# 3. Develop (hot reload)
npm run dev
# 4. Production build & run
npm run build
npm start

Health check

curl -s http://localhost:3000/healthz | jq

{ "status": "ok", "service": "capconnect", "providers": { "meta": true, "google": true } }

📡 API

`POST /v1/collect`

Authenticated with the x-capconnect-token header (must equal WEBHOOK_SECRET).

Request

curl -s -X POST http://localhost:3000/v1/collect \
-H "Content-Type: application/json" \
-H "x-capconnect-token: $WEBHOOK_SECRET" \
-d '{ "customer": { "email": " John.Doe@Example.COM ", "phone": "090-1234-5678", "firstName": "John", "lastName": "Doe", "country": "JP", "city": "Tokyo", "zip": "100-0001", "externalId": "user_42" }, "event": { "eventName": "Purchase", "eventId": "order-2025-0001", "value": 4980, "currency": "JPY", "orderId": "order-2025-0001", "actionSource": "website", "eventSourceUrl": "https://shop.example.com/thank-you", "fbc": "fb.1.1700000000000.IwAR...", "gclid": "Cj0KCQ..." } }'

The phone above is normalized to 819012345678 (leading 0 dropped, 81 prepended) and then SHA-256 hashed before it ever leaves the process.

Response (200 if at least one provider accepted; 422 if none did)

{
"eventId": "order-2025-0001",
"accepted": true,
"results": [
{ "provider": "meta", "status": "sent", "httpStatus": 200, "detail": "events_received=1 fbtrace_id=Aa...", "reference": "order-2025-0001" },
{ "provider": "google", "status": "sent", "httpStatus": 200, "detail": "results=1", "reference": "order-2025-0001" }
]
}

`POST /v1/collect/batch`

Same auth. Body is a JSON array of { customer, event } objects (max 1000). Each item is processed independently; invalid items are reported in validationErrors without failing the rest.

curl -s -X POST http://localhost:3000/v1/collect/batch \
-H "Content-Type: application/json" \
-H "x-capconnect-token: $WEBHOOK_SECRET" \
-d '[ { "customer": { "email": "a@example.com" }, "event": { "eventName": "Lead" } } ]'

`GET /healthz`

Unauthenticated liveness/readiness probe. Returns no PII.

⚙️ Configuration

All configuration is via environment variables (see .env.example). The process fails fast at boot if an enabled provider is missing required secrets.

Server

Variable	Required	Default	Description
`PORT`	no	`3000`	HTTP listen port.
`WEBHOOK_SECRET`	yes	—	Shared secret required in the `x-capconnect-token` header.
`DEFAULT_COUNTRY_CODE`	no	`81`	Digits-only calling code auto-prepended to non-international phones.
`DEFAULT_CURRENCY`	no	`JPY`	ISO-4217 currency applied when an event omits one.
`HTTP_TIMEOUT_MS`	no	`10000`	Outbound request timeout for both providers.
`RETRY_MAX_ATTEMPTS`	no	`3`	Max attempts per provider call (incl. the first).
`RETRY_BASE_DELAY_MS`	no	`300`	Base backoff delay; doubles each retry, full-jittered.
`RETRY_MAX_DELAY_MS`	no	`5000`	Hard cap on any single backoff delay.

Meta Conversions API

Variable	Required	Default	Description
`META_ENABLED`	no	`true`	Toggle Meta dispatch.
`META_PIXEL_ID`	if enabled	—	Your Pixel / dataset id.
`META_ACCESS_TOKEN`	if enabled	—	System-user access token.
`META_API_VERSION`	no	`v20.0`	Graph API version.
`META_TEST_EVENT_CODE`	no	—	Enables Meta's Test Events tool when set.

Google Ads API (Enhanced Conversions)

Variable	Required	Default	Description
`GOOGLE_ENABLED`	no	`true`	Toggle Google dispatch.
`GOOGLE_CUSTOMER_ID`	if enabled	—	Account id owning the conversion action (digits, no dashes).
`GOOGLE_CONVERSION_ACTION_ID`	if enabled	—	Numeric conversion action id.
`GOOGLE_DEVELOPER_TOKEN`	if enabled	—	Google Ads API developer token.
`GOOGLE_OAUTH_ACCESS_TOKEN`	auth A	—	Pre-issued OAuth2 Bearer token (you refresh).
`GOOGLE_OAUTH_CLIENT_ID`	auth B	—	OAuth client id for automatic refresh.
`GOOGLE_OAUTH_CLIENT_SECRET`	auth B	—	OAuth client secret for automatic refresh.
`GOOGLE_OAUTH_REFRESH_TOKEN`	auth B	—	OAuth refresh token (held in memory only).
`GOOGLE_OAUTH_TOKEN_URI`	no	`https://oauth2.googleapis.com/token`	Token endpoint.
`GOOGLE_LOGIN_CUSTOMER_ID`	no	—	MCC / manager id for `login-customer-id`.
`GOOGLE_API_VERSION`	no	`v17`	Google Ads API version.
`GOOGLE_VALIDATE_ONLY`	no	`false`	Validate without recording a conversion.

OAuth — two strategies (provide exactly one):(A) Inject a short-lived GOOGLE_OAUTH_ACCESS_TOKEN from your own secret manager and handle refresh externally; or (B) provide GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET + GOOGLE_OAUTH_REFRESH_TOKEN and CapConnect refreshes access tokens automatically — caching them in memory, coalescing concurrent refreshes, and renewing ~60s before expiry. The refresh token is never persisted or logged. Boot fails fast if neither strategy is fully configured while Google is enabled.

Resilience

Automatic retries with exponential backoff + full jitter on transient failures only (network errors, HTTP 429, HTTP 5xx). Deterministic 4xx errors are never retried. Tune via RETRY_*.
Fault isolation — a Meta failure never blocks Google (and vice-versa); a Google token-refresh failure is reported as a Google-only auth: error while Meta still dispatches.

🔐 Normalization rules (Meta/Google compliant)

Field	Rule	Example → normalized
Email (`em`)	trim, lowercase (no dot-stripping)	`A.B@Ex.COM` → `a.b@ex.com`
Phone (`ph`)	digits only → E.164 (drop trunk `0`, prepend country code)	`090-1234-5678` → `819012345678`
First/Last name (`fn`/`ln`)	lowercase, strip punctuation, collapse spaces	`O'Brien` → `obrien`
City (`ct`)	lowercase, remove all whitespace & punctuation	`New York` → `newyork`
State (`st`)	lowercase, letters only	`CA` → `ca`
Zip (`zp`)	lowercase, strip spaces, drop `+4`, US→first 5	`100-0001` → `100`
Country (`country`)	ISO alpha-2, lowercase	`Japan`→ first 2 letters
DOB (`db`)	parse → `YYYYMMDD`	`1990/01/02` → `19900102`
Gender (`ge`)	→ `m` / `f`	`Male` → `m`

Every normalized value is then SHA-256 hashed to lowercase hex before dispatch. Empty/unusable values are dropped (never hashed to the all-empty digest).

🧪 Local verification

npm run typecheck # strict TS, no emit
npm run lint # ESLint (type-checked rules)
npm run build # compile to dist/
npm test# run the Vitest suite (80 tests)
npm run test:coverage # tests + coverage report
npm run ci # typecheck + lint + build + test (what CI runs)

You can exercise the pipeline safely against Meta's Test Events tool by setting META_TEST_EVENT_CODE, and against Google by setting GOOGLE_VALIDATE_ONLY=true.

🐳 Docker

# Build & run with compose (reads your .env)
cp .env.example .env # then fill in secrets
docker compose up --build
# …or build the image directly
docker build -t capconnect:latest .
docker run --rm -p 3000:3000 --env-file .env capconnect:latest

The image is a multi-stage build that ships only production dependencies and the compiled dist/, runs as the non-root node user, exposes a HEALTHCHECK against /healthz, and (via compose) runs read-only with dropped capabilities and no-new-privileges.

🔁 CI

.github/workflows/ci.yml runs on every push/PR: typecheck → lint → build → test across Node 18/20/22, a coverage job, and a Docker build job.

🤝 Operational guidance

Terminate TLS in front of CapConnect (reverse proxy / load balancer) and keep the upstream hop encrypted.
Rotate WEBHOOK_SECRET and provider tokens via your secret manager; never bake them into images.
Do not enable request-body logging at the proxy for /v1/collect* — that would defeat the zero-knowledge property outside the app.
Scale horizontally — the service is stateless, so run as many replicas as you need behind a load balancer.

📄 License

CapConnect is distributed under the Business Source License 1.1 (BSL-1.1).

You may use, copy, modify, and self-host CapConnect freely, including internally at your company.
The Additional Use Grant permits production use except offering CapConnect (or a substantially similar service) to third parties as a hosted/managed commercial "conversion-relay" product.
On the Change Date (four years after each version's release), that version automatically converts to the Apache License 2.0.

Licensed under the Business Source License 1.1 (the "License");
you may not use this file except in compliance with the License.
Change License: Apache License, Version 2.0
Change Date: four (4) years from the date of each release.
Additional Use Grant: You may use the Licensed Work in production, except to
provide it to third parties as a hosted or managed commercial conversion-relay
service that competes with the Licensor's offering.
THE LICENSED WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

Prefer a copyleft model instead? CapConnect is also available under the GNU AGPL-3.0 on request — contact the maintainers. Choose BSL-1.1 for permissive self-hosting with a commercial-SaaS carve-out, or AGPL-3.0 if you want network-use copyleft obligations.

_{Built for the cookieless era. Your customers' data stays your customers'.}

🔒 CapConnect

A privacy-first, zero-knowledge data connector for the cookieless era.

Clean → Hash (SHA-256) → Forward. First-party customer data is normalized and irreversibly hashed in memory before it is relayed to Meta Conversions API and Google Ads Enhanced Conversions. No raw PII ever touches a disk, a log, or a database.

Why CapConnect exists

Third-party cookies are gone. To keep measuring conversions, advertisers must send first-party data server-to-server. But doing that safely is the hard part: the moment raw emails and phone numbers leave your perimeter, your legal and security teams own a new liability.

CapConnect is the safe middle layer. It accepts your raw events, normalizes and SHA-256 hashes every personal field the instant it arrives, and forwards only those one-way digests to the ad platforms — exactly the way Meta and Google specify. Because the plaintext exists only transiently in process memory and is never persisted, there is nothing to leak from CapConnect's storage. There is no storage.

For CTOs & Legal: CapConnect is a stateless relay. It holds no datastore, writes no PII to disk, and emits no PII in logs. The only personal data it transmits is already a non-reversible SHA-256 hash, sent over TLS to Meta/Google — the same hashing the platforms' own SDKs perform client-side.

✨ Features

Zero-knowledge by construction — plaintext PII lives only on the call stack during a single request; it is GC-eligible the moment the response is returned.
Spec-accurate normalization — email lower/trim, phone → E.164 (auto-prepends the country code, e.g. 81 for Japan), names/city/state/zip/DOB/gender all formatted per the official Meta & Google guidelines.
SHA-256 hashing with idempotent pass-through for upstream-pre-hashed inputs.
Meta Conversions API with deduplication event_id support to pair with the browser Pixel.
Google Ads Enhanced Conversions via uploadClickConversions with userIdentifiers.
Concurrent, fault-isolated dispatch — one platform failing never blocks the other.
Automatic retries with exponential backoff + jitter on transient errors (network / 429 / 5xx).
Automatic Google OAuth refresh (optional) — refresh-token exchange, in-memory caching, concurrent-refresh coalescing; nothing persisted.
Single & batch webhook endpoints (/v1/collect, /v1/collect/batch).
Hardened Express server — shared-secret auth (constant-time compare), body-size caps, x-powered-by disabled, graceful shutdown.
Strict TypeScript end to end (exactOptionalPropertyTypes, noUncheckedIndexedAccess, …).
80 unit/integration tests (Vitest + Supertest), ESLint type-checked rules, multi-stage Docker image, and GitHub Actions CI.

🛡 The Zero-Knowledge Guarantee

flowchart LR
A["Upstream source<br/>(Webhook / CSV parse)"] -->|HTTPS + shared secret| B["CapConnect<br/>/v1/collect"]
subgraph MEM["⏱ In-memory only — never persisted, never logged"]
direction TB
C["Validate contract"] --> D["Normalize<br/>email · phone · name · address"]
D --> E["SHA-256 hash<br/>(irreversible, one-way)"]
E --> F["Build provider payloads<br/>(hashed digests only)"]
end
B --> C
F -->|TLS| G["Meta Conversions API<br/>(event_id dedup)"]
F -->|TLS| H["Google Ads API<br/>Enhanced Conversions"]
G --> I["Structured, PII-free<br/>dispatch report"]
H --> I
I -->|JSON response| A
classDef mem fill:#0b3d2e,stroke:#10b981,color:#e6fffa;
class MEM,C,D,E,F mem;

What crosses each boundary:

Boundary	Data in transit	Form
Upstream → CapConnect	Raw identifiers + event metadata	Plaintext over TLS (you control this hop)
Inside CapConnect	Identifiers	Normalized then SHA-256 hashed, in memory only
CapConnect → Meta/Google	Identifiers	SHA-256 hex digests + un-hashed match-support fields (fbc/fbp/IP/UA/gclid) per platform spec
CapConnect → Upstream	Dispatch outcome	No PII — only `event_id`, status, provider trace ids

🏗 Architecture

flowchart TD
subgraph SRC["src/"]
SV["server.ts<br/>Express app · auth · validation · routing"]
NM["utils/normalizer.ts<br/>normalize + SHA-256 (pure functions)"]
CP["services/capi.ts<br/>Meta + Google payload build & POST"]
TY["types/index.ts<br/>strict shared types"]
end
SV -->|"normalizeAndHash()"| NM
SV -->|"dispatchToAllProviders()"| CP
NM --- TY
CP --- TY
SV --- TY

File	Responsibility
`src/types/index.ts`	Single source of truth for every shape: raw input, hashed IR, provider payloads, responses, config.
`src/utils/normalizer.ts`	Field-by-field normalization (Meta/Google spec) + SHA-256. Pure, no I/O, no logging.
`src/utils/retry.ts`	Exponential-backoff retry helper; retries transient errors only.
`src/services/capi.ts`	Builds & POSTs Meta CAPI and Google Ads payloads concurrently; PII-free error reporting.
`src/services/googleAuth.ts`	Google OAuth token providers (static + auto-refreshing).
`src/server.ts`	Hardened Express server, config loading/validation, webhook endpoints, graceful shutdown.
`tests/`	Vitest unit + Supertest integration suites (80 tests).

🚀 Quick start

# 1. Install
npm install
# 2. Configure
cp .env.example .env
# …then edit .env with your Pixel id, access tokens, etc.# Generate a webhook secret: openssl rand -hex 32# 3. Develop (hot reload)
npm run dev
# 4. Production build & run
npm run build
npm start

Health check

curl -s http://localhost:3000/healthz | jq

{ "status": "ok", "service": "capconnect", "providers": { "meta": true, "google": true } }

📡 API

`POST /v1/collect`

Authenticated with the x-capconnect-token header (must equal WEBHOOK_SECRET).

Request

curl -s -X POST http://localhost:3000/v1/collect \
-H "Content-Type: application/json" \
-H "x-capconnect-token: $WEBHOOK_SECRET" \
-d '{ "customer": { "email": " John.Doe@Example.COM ", "phone": "090-1234-5678", "firstName": "John", "lastName": "Doe", "country": "JP", "city": "Tokyo", "zip": "100-0001", "externalId": "user_42" }, "event": { "eventName": "Purchase", "eventId": "order-2025-0001", "value": 4980, "currency": "JPY", "orderId": "order-2025-0001", "actionSource": "website", "eventSourceUrl": "https://shop.example.com/thank-you", "fbc": "fb.1.1700000000000.IwAR...", "gclid": "Cj0KCQ..." } }'

The phone above is normalized to 819012345678 (leading 0 dropped, 81 prepended) and then SHA-256 hashed before it ever leaves the process.

Response (200 if at least one provider accepted; 422 if none did)

{
"eventId": "order-2025-0001",
"accepted": true,
"results": [
{ "provider": "meta", "status": "sent", "httpStatus": 200, "detail": "events_received=1 fbtrace_id=Aa...", "reference": "order-2025-0001" },
{ "provider": "google", "status": "sent", "httpStatus": 200, "detail": "results=1", "reference": "order-2025-0001" }
]
}

`POST /v1/collect/batch`

Same auth. Body is a JSON array of { customer, event } objects (max 1000). Each item is processed independently; invalid items are reported in validationErrors without failing the rest.

curl -s -X POST http://localhost:3000/v1/collect/batch \
-H "Content-Type: application/json" \
-H "x-capconnect-token: $WEBHOOK_SECRET" \
-d '[ { "customer": { "email": "a@example.com" }, "event": { "eventName": "Lead" } } ]'

`GET /healthz`

Unauthenticated liveness/readiness probe. Returns no PII.

⚙️ Configuration

All configuration is via environment variables (see .env.example). The process fails fast at boot if an enabled provider is missing required secrets.

Server

Variable	Required	Default	Description
`PORT`	no	`3000`	HTTP listen port.
`WEBHOOK_SECRET`	yes	—	Shared secret required in the `x-capconnect-token` header.
`DEFAULT_COUNTRY_CODE`	no	`81`	Digits-only calling code auto-prepended to non-international phones.
`DEFAULT_CURRENCY`	no	`JPY`	ISO-4217 currency applied when an event omits one.
`HTTP_TIMEOUT_MS`	no	`10000`	Outbound request timeout for both providers.
`RETRY_MAX_ATTEMPTS`	no	`3`	Max attempts per provider call (incl. the first).
`RETRY_BASE_DELAY_MS`	no	`300`	Base backoff delay; doubles each retry, full-jittered.
`RETRY_MAX_DELAY_MS`	no	`5000`	Hard cap on any single backoff delay.

Meta Conversions API

Variable	Required	Default	Description
`META_ENABLED`	no	`true`	Toggle Meta dispatch.
`META_PIXEL_ID`	if enabled	—	Your Pixel / dataset id.
`META_ACCESS_TOKEN`	if enabled	—	System-user access token.
`META_API_VERSION`	no	`v20.0`	Graph API version.
`META_TEST_EVENT_CODE`	no	—	Enables Meta's Test Events tool when set.

Google Ads API (Enhanced Conversions)

Variable	Required	Default	Description
`GOOGLE_ENABLED`	no	`true`	Toggle Google dispatch.
`GOOGLE_CUSTOMER_ID`	if enabled	—	Account id owning the conversion action (digits, no dashes).
`GOOGLE_CONVERSION_ACTION_ID`	if enabled	—	Numeric conversion action id.
`GOOGLE_DEVELOPER_TOKEN`	if enabled	—	Google Ads API developer token.
`GOOGLE_OAUTH_ACCESS_TOKEN`	auth A	—	Pre-issued OAuth2 Bearer token (you refresh).
`GOOGLE_OAUTH_CLIENT_ID`	auth B	—	OAuth client id for automatic refresh.
`GOOGLE_OAUTH_CLIENT_SECRET`	auth B	—	OAuth client secret for automatic refresh.
`GOOGLE_OAUTH_REFRESH_TOKEN`	auth B	—	OAuth refresh token (held in memory only).
`GOOGLE_OAUTH_TOKEN_URI`	no	`https://oauth2.googleapis.com/token`	Token endpoint.
`GOOGLE_LOGIN_CUSTOMER_ID`	no	—	MCC / manager id for `login-customer-id`.
`GOOGLE_API_VERSION`	no	`v17`	Google Ads API version.
`GOOGLE_VALIDATE_ONLY`	no	`false`	Validate without recording a conversion.

OAuth — two strategies (provide exactly one):(A) Inject a short-lived GOOGLE_OAUTH_ACCESS_TOKEN from your own secret manager and handle refresh externally; or (B) provide GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET + GOOGLE_OAUTH_REFRESH_TOKEN and CapConnect refreshes access tokens automatically — caching them in memory, coalescing concurrent refreshes, and renewing ~60s before expiry. The refresh token is never persisted or logged. Boot fails fast if neither strategy is fully configured while Google is enabled.

Resilience

Automatic retries with exponential backoff + full jitter on transient failures only (network errors, HTTP 429, HTTP 5xx). Deterministic 4xx errors are never retried. Tune via RETRY_*.
Fault isolation — a Meta failure never blocks Google (and vice-versa); a Google token-refresh failure is reported as a Google-only auth: error while Meta still dispatches.

🔐 Normalization rules (Meta/Google compliant)

Field	Rule	Example → normalized
Email (`em`)	trim, lowercase (no dot-stripping)	`A.B@Ex.COM` → `a.b@ex.com`
Phone (`ph`)	digits only → E.164 (drop trunk `0`, prepend country code)	`090-1234-5678` → `819012345678`
First/Last name (`fn`/`ln`)	lowercase, strip punctuation, collapse spaces	`O'Brien` → `obrien`
City (`ct`)	lowercase, remove all whitespace & punctuation	`New York` → `newyork`
State (`st`)	lowercase, letters only	`CA` → `ca`
Zip (`zp`)	lowercase, strip spaces, drop `+4`, US→first 5	`100-0001` → `100`
Country (`country`)	ISO alpha-2, lowercase	`Japan`→ first 2 letters
DOB (`db`)	parse → `YYYYMMDD`	`1990/01/02` → `19900102`
Gender (`ge`)	→ `m` / `f`	`Male` → `m`

Every normalized value is then SHA-256 hashed to lowercase hex before dispatch. Empty/unusable values are dropped (never hashed to the all-empty digest).

🧪 Local verification

npm run typecheck # strict TS, no emit
npm run lint # ESLint (type-checked rules)
npm run build # compile to dist/
npm test# run the Vitest suite (80 tests)
npm run test:coverage # tests + coverage report
npm run ci # typecheck + lint + build + test (what CI runs)

You can exercise the pipeline safely against Meta's Test Events tool by setting META_TEST_EVENT_CODE, and against Google by setting GOOGLE_VALIDATE_ONLY=true.

🐳 Docker

# Build & run with compose (reads your .env)
cp .env.example .env # then fill in secrets
docker compose up --build
# …or build the image directly
docker build -t capconnect:latest .
docker run --rm -p 3000:3000 --env-file .env capconnect:latest

The image is a multi-stage build that ships only production dependencies and the compiled dist/, runs as the non-root node user, exposes a HEALTHCHECK against /healthz, and (via compose) runs read-only with dropped capabilities and no-new-privileges.

🔁 CI

.github/workflows/ci.yml runs on every push/PR: typecheck → lint → build → test across Node 18/20/22, a coverage job, and a Docker build job.

🤝 Operational guidance

Terminate TLS in front of CapConnect (reverse proxy / load balancer) and keep the upstream hop encrypted.
Rotate WEBHOOK_SECRET and provider tokens via your secret manager; never bake them into images.
Do not enable request-body logging at the proxy for /v1/collect* — that would defeat the zero-knowledge property outside the app.
Scale horizontally — the service is stateless, so run as many replicas as you need behind a load balancer.

📄 License

CapConnect is distributed under the Business Source License 1.1 (BSL-1.1).

You may use, copy, modify, and self-host CapConnect freely, including internally at your company.
The Additional Use Grant permits production use except offering CapConnect (or a substantially similar service) to third parties as a hosted/managed commercial "conversion-relay" product.
On the Change Date (four years after each version's release), that version automatically converts to the Apache License 2.0.

Licensed under the Business Source License 1.1 (the "License");
you may not use this file except in compliance with the License.
Change License: Apache License, Version 2.0
Change Date: four (4) years from the date of each release.
Additional Use Grant: You may use the Licensed Work in production, except to
provide it to third parties as a hosted or managed commercial conversion-relay
service that competes with the Licensor's offering.
THE LICENSED WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

Prefer a copyleft model instead? CapConnect is also available under the GNU AGPL-3.0 on request — contact the maintainers. Choose BSL-1.1 for permissive self-hosting with a commercial-SaaS carve-out, or AGPL-3.0 if you want network-use copyleft obligations.

_{Built for the cookieless era. Your customers' data stays your customers'.}

🔒 CapConnect

A privacy-first, zero-knowledge data connector for the cookieless era.

Clean → Hash (SHA-256) → Forward. First-party customer data is normalized and irreversibly hashed in memory before it is relayed to Meta Conversions API and Google Ads Enhanced Conversions. No raw PII ever touches a disk, a log, or a database.

Why CapConnect exists

Third-party cookies are gone. To keep measuring conversions, advertisers must send first-party data server-to-server. But doing that safely is the hard part: the moment raw emails and phone numbers leave your perimeter, your legal and security teams own a new liability.

CapConnect is the safe middle layer. It accepts your raw events, normalizes and SHA-256 hashes every personal field the instant it arrives, and forwards only those one-way digests to the ad platforms — exactly the way Meta and Google specify. Because the plaintext exists only transiently in process memory and is never persisted, there is nothing to leak from CapConnect's storage. There is no storage.

For CTOs & Legal: CapConnect is a stateless relay. It holds no datastore, writes no PII to disk, and emits no PII in logs. The only personal data it transmits is already a non-reversible SHA-256 hash, sent over TLS to Meta/Google — the same hashing the platforms' own SDKs perform client-side.

✨ Features

Zero-knowledge by construction — plaintext PII lives only on the call stack during a single request; it is GC-eligible the moment the response is returned.
Spec-accurate normalization — email lower/trim, phone → E.164 (auto-prepends the country code, e.g. 81 for Japan), names/city/state/zip/DOB/gender all formatted per the official Meta & Google guidelines.
SHA-256 hashing with idempotent pass-through for upstream-pre-hashed inputs.
Meta Conversions API with deduplication event_id support to pair with the browser Pixel.
Google Ads Enhanced Conversions via uploadClickConversions with userIdentifiers.
Concurrent, fault-isolated dispatch — one platform failing never blocks the other.
Automatic retries with exponential backoff + jitter on transient errors (network / 429 / 5xx).
Automatic Google OAuth refresh (optional) — refresh-token exchange, in-memory caching, concurrent-refresh coalescing; nothing persisted.
Single & batch webhook endpoints (/v1/collect, /v1/collect/batch).
Hardened Express server — shared-secret auth (constant-time compare), body-size caps, x-powered-by disabled, graceful shutdown.
Strict TypeScript end to end (exactOptionalPropertyTypes, noUncheckedIndexedAccess, …).
80 unit/integration tests (Vitest + Supertest), ESLint type-checked rules, multi-stage Docker image, and GitHub Actions CI.

🛡 The Zero-Knowledge Guarantee

flowchart LR
A["Upstream source<br/>(Webhook / CSV parse)"] -->|HTTPS + shared secret| B["CapConnect<br/>/v1/collect"]
subgraph MEM["⏱ In-memory only — never persisted, never logged"]
direction TB
C["Validate contract"] --> D["Normalize<br/>email · phone · name · address"]
D --> E["SHA-256 hash<br/>(irreversible, one-way)"]
E --> F["Build provider payloads<br/>(hashed digests only)"]
end
B --> C
F -->|TLS| G["Meta Conversions API<br/>(event_id dedup)"]
F -->|TLS| H["Google Ads API<br/>Enhanced Conversions"]
G --> I["Structured, PII-free<br/>dispatch report"]
H --> I
I -->|JSON response| A
classDef mem fill:#0b3d2e,stroke:#10b981,color:#e6fffa;
class MEM,C,D,E,F mem;

What crosses each boundary:

Boundary	Data in transit	Form
Upstream → CapConnect	Raw identifiers + event metadata	Plaintext over TLS (you control this hop)
Inside CapConnect	Identifiers	Normalized then SHA-256 hashed, in memory only
CapConnect → Meta/Google	Identifiers	SHA-256 hex digests + un-hashed match-support fields (fbc/fbp/IP/UA/gclid) per platform spec
CapConnect → Upstream	Dispatch outcome	No PII — only `event_id`, status, provider trace ids

🏗 Architecture

flowchart TD
subgraph SRC["src/"]
SV["server.ts<br/>Express app · auth · validation · routing"]
NM["utils/normalizer.ts<br/>normalize + SHA-256 (pure functions)"]
CP["services/capi.ts<br/>Meta + Google payload build & POST"]
TY["types/index.ts<br/>strict shared types"]
end
SV -->|"normalizeAndHash()"| NM
SV -->|"dispatchToAllProviders()"| CP
NM --- TY
CP --- TY
SV --- TY

File	Responsibility
`src/types/index.ts`	Single source of truth for every shape: raw input, hashed IR, provider payloads, responses, config.
`src/utils/normalizer.ts`	Field-by-field normalization (Meta/Google spec) + SHA-256. Pure, no I/O, no logging.
`src/utils/retry.ts`	Exponential-backoff retry helper; retries transient errors only.
`src/services/capi.ts`	Builds & POSTs Meta CAPI and Google Ads payloads concurrently; PII-free error reporting.
`src/services/googleAuth.ts`	Google OAuth token providers (static + auto-refreshing).
`src/server.ts`	Hardened Express server, config loading/validation, webhook endpoints, graceful shutdown.
`tests/`	Vitest unit + Supertest integration suites (80 tests).

🚀 Quick start

# 1. Install
npm install
# 2. Configure
cp .env.example .env
# …then edit .env with your Pixel id, access tokens, etc.# Generate a webhook secret: openssl rand -hex 32# 3. Develop (hot reload)
npm run dev
# 4. Production build & run
npm run build
npm start

Health check

curl -s http://localhost:3000/healthz | jq

{ "status": "ok", "service": "capconnect", "providers": { "meta": true, "google": true } }

📡 API

`POST /v1/collect`

Authenticated with the x-capconnect-token header (must equal WEBHOOK_SECRET).

Request

curl -s -X POST http://localhost:3000/v1/collect \
-H "Content-Type: application/json" \
-H "x-capconnect-token: $WEBHOOK_SECRET" \
-d '{ "customer": { "email": " John.Doe@Example.COM ", "phone": "090-1234-5678", "firstName": "John", "lastName": "Doe", "country": "JP", "city": "Tokyo", "zip": "100-0001", "externalId": "user_42" }, "event": { "eventName": "Purchase", "eventId": "order-2025-0001", "value": 4980, "currency": "JPY", "orderId": "order-2025-0001", "actionSource": "website", "eventSourceUrl": "https://shop.example.com/thank-you", "fbc": "fb.1.1700000000000.IwAR...", "gclid": "Cj0KCQ..." } }'

The phone above is normalized to 819012345678 (leading 0 dropped, 81 prepended) and then SHA-256 hashed before it ever leaves the process.

Response (200 if at least one provider accepted; 422 if none did)

{
"eventId": "order-2025-0001",
"accepted": true,
"results": [
{ "provider": "meta", "status": "sent", "httpStatus": 200, "detail": "events_received=1 fbtrace_id=Aa...", "reference": "order-2025-0001" },
{ "provider": "google", "status": "sent", "httpStatus": 200, "detail": "results=1", "reference": "order-2025-0001" }
]
}

`POST /v1/collect/batch`

Same auth. Body is a JSON array of { customer, event } objects (max 1000). Each item is processed independently; invalid items are reported in validationErrors without failing the rest.

curl -s -X POST http://localhost:3000/v1/collect/batch \
-H "Content-Type: application/json" \
-H "x-capconnect-token: $WEBHOOK_SECRET" \
-d '[ { "customer": { "email": "a@example.com" }, "event": { "eventName": "Lead" } } ]'

`GET /healthz`

Unauthenticated liveness/readiness probe. Returns no PII.

⚙️ Configuration

All configuration is via environment variables (see .env.example). The process fails fast at boot if an enabled provider is missing required secrets.

Server

Variable	Required	Default	Description
`PORT`	no	`3000`	HTTP listen port.
`WEBHOOK_SECRET`	yes	—	Shared secret required in the `x-capconnect-token` header.
`DEFAULT_COUNTRY_CODE`	no	`81`	Digits-only calling code auto-prepended to non-international phones.
`DEFAULT_CURRENCY`	no	`JPY`	ISO-4217 currency applied when an event omits one.
`HTTP_TIMEOUT_MS`	no	`10000`	Outbound request timeout for both providers.
`RETRY_MAX_ATTEMPTS`	no	`3`	Max attempts per provider call (incl. the first).
`RETRY_BASE_DELAY_MS`	no	`300`	Base backoff delay; doubles each retry, full-jittered.
`RETRY_MAX_DELAY_MS`	no	`5000`	Hard cap on any single backoff delay.

Meta Conversions API

Variable	Required	Default	Description
`META_ENABLED`	no	`true`	Toggle Meta dispatch.
`META_PIXEL_ID`	if enabled	—	Your Pixel / dataset id.
`META_ACCESS_TOKEN`	if enabled	—	System-user access token.
`META_API_VERSION`	no	`v20.0`	Graph API version.
`META_TEST_EVENT_CODE`	no	—	Enables Meta's Test Events tool when set.

Google Ads API (Enhanced Conversions)

Variable	Required	Default	Description
`GOOGLE_ENABLED`	no	`true`	Toggle Google dispatch.
`GOOGLE_CUSTOMER_ID`	if enabled	—	Account id owning the conversion action (digits, no dashes).
`GOOGLE_CONVERSION_ACTION_ID`	if enabled	—	Numeric conversion action id.
`GOOGLE_DEVELOPER_TOKEN`	if enabled	—	Google Ads API developer token.
`GOOGLE_OAUTH_ACCESS_TOKEN`	auth A	—	Pre-issued OAuth2 Bearer token (you refresh).
`GOOGLE_OAUTH_CLIENT_ID`	auth B	—	OAuth client id for automatic refresh.
`GOOGLE_OAUTH_CLIENT_SECRET`	auth B	—	OAuth client secret for automatic refresh.
`GOOGLE_OAUTH_REFRESH_TOKEN`	auth B	—	OAuth refresh token (held in memory only).
`GOOGLE_OAUTH_TOKEN_URI`	no	`https://oauth2.googleapis.com/token`	Token endpoint.
`GOOGLE_LOGIN_CUSTOMER_ID`	no	—	MCC / manager id for `login-customer-id`.
`GOOGLE_API_VERSION`	no	`v17`	Google Ads API version.
`GOOGLE_VALIDATE_ONLY`	no	`false`	Validate without recording a conversion.

OAuth — two strategies (provide exactly one):(A) Inject a short-lived GOOGLE_OAUTH_ACCESS_TOKEN from your own secret manager and handle refresh externally; or (B) provide GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET + GOOGLE_OAUTH_REFRESH_TOKEN and CapConnect refreshes access tokens automatically — caching them in memory, coalescing concurrent refreshes, and renewing ~60s before expiry. The refresh token is never persisted or logged. Boot fails fast if neither strategy is fully configured while Google is enabled.

Resilience

Automatic retries with exponential backoff + full jitter on transient failures only (network errors, HTTP 429, HTTP 5xx). Deterministic 4xx errors are never retried. Tune via RETRY_*.
Fault isolation — a Meta failure never blocks Google (and vice-versa); a Google token-refresh failure is reported as a Google-only auth: error while Meta still dispatches.

🔐 Normalization rules (Meta/Google compliant)

Field	Rule	Example → normalized
Email (`em`)	trim, lowercase (no dot-stripping)	`A.B@Ex.COM` → `a.b@ex.com`
Phone (`ph`)	digits only → E.164 (drop trunk `0`, prepend country code)	`090-1234-5678` → `819012345678`
First/Last name (`fn`/`ln`)	lowercase, strip punctuation, collapse spaces	`O'Brien` → `obrien`
City (`ct`)	lowercase, remove all whitespace & punctuation	`New York` → `newyork`
State (`st`)	lowercase, letters only	`CA` → `ca`
Zip (`zp`)	lowercase, strip spaces, drop `+4`, US→first 5	`100-0001` → `100`
Country (`country`)	ISO alpha-2, lowercase	`Japan`→ first 2 letters
DOB (`db`)	parse → `YYYYMMDD`	`1990/01/02` → `19900102`
Gender (`ge`)	→ `m` / `f`	`Male` → `m`

Every normalized value is then SHA-256 hashed to lowercase hex before dispatch. Empty/unusable values are dropped (never hashed to the all-empty digest).

🧪 Local verification

npm run typecheck # strict TS, no emit
npm run lint # ESLint (type-checked rules)
npm run build # compile to dist/
npm test# run the Vitest suite (80 tests)
npm run test:coverage # tests + coverage report
npm run ci # typecheck + lint + build + test (what CI runs)

You can exercise the pipeline safely against Meta's Test Events tool by setting META_TEST_EVENT_CODE, and against Google by setting GOOGLE_VALIDATE_ONLY=true.

🐳 Docker

# Build & run with compose (reads your .env)
cp .env.example .env # then fill in secrets
docker compose up --build
# …or build the image directly
docker build -t capconnect:latest .
docker run --rm -p 3000:3000 --env-file .env capconnect:latest

The image is a multi-stage build that ships only production dependencies and the compiled dist/, runs as the non-root node user, exposes a HEALTHCHECK against /healthz, and (via compose) runs read-only with dropped capabilities and no-new-privileges.

🔁 CI

.github/workflows/ci.yml runs on every push/PR: typecheck → lint → build → test across Node 18/20/22, a coverage job, and a Docker build job.

🤝 Operational guidance

Terminate TLS in front of CapConnect (reverse proxy / load balancer) and keep the upstream hop encrypted.
Rotate WEBHOOK_SECRET and provider tokens via your secret manager; never bake them into images.
Do not enable request-body logging at the proxy for /v1/collect* — that would defeat the zero-knowledge property outside the app.
Scale horizontally — the service is stateless, so run as many replicas as you need behind a load balancer.

📄 License

CapConnect is distributed under the Business Source License 1.1 (BSL-1.1).

You may use, copy, modify, and self-host CapConnect freely, including internally at your company.
The Additional Use Grant permits production use except offering CapConnect (or a substantially similar service) to third parties as a hosted/managed commercial "conversion-relay" product.
On the Change Date (four years after each version's release), that version automatically converts to the Apache License 2.0.

Licensed under the Business Source License 1.1 (the "License");
you may not use this file except in compliance with the License.
Change License: Apache License, Version 2.0
Change Date: four (4) years from the date of each release.
Additional Use Grant: You may use the Licensed Work in production, except to
provide it to third parties as a hosted or managed commercial conversion-relay
service that competes with the Licensor's offering.
THE LICENSED WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

Prefer a copyleft model instead? CapConnect is also available under the GNU AGPL-3.0 on request — contact the maintainers. Choose BSL-1.1 for permissive self-hosting with a commercial-SaaS carve-out, or AGPL-3.0 if you want network-use copyleft obligations.

_{Built for the cookieless era. Your customers' data stays your customers'.}

🔒 CapConnect

A privacy-first, zero-knowledge data connector for the cookieless era.

Clean → Hash (SHA-256) → Forward. First-party customer data is normalized and irreversibly hashed in memory before it is relayed to Meta Conversions API and Google Ads Enhanced Conversions. No raw PII ever touches a disk, a log, or a database.

Why CapConnect exists

Third-party cookies are gone. To keep measuring conversions, advertisers must send first-party data server-to-server. But doing that safely is the hard part: the moment raw emails and phone numbers leave your perimeter, your legal and security teams own a new liability.

CapConnect is the safe middle layer. It accepts your raw events, normalizes and SHA-256 hashes every personal field the instant it arrives, and forwards only those one-way digests to the ad platforms — exactly the way Meta and Google specify. Because the plaintext exists only transiently in process memory and is never persisted, there is nothing to leak from CapConnect's storage. There is no storage.

For CTOs & Legal: CapConnect is a stateless relay. It holds no datastore, writes no PII to disk, and emits no PII in logs. The only personal data it transmits is already a non-reversible SHA-256 hash, sent over TLS to Meta/Google — the same hashing the platforms' own SDKs perform client-side.

✨ Features

Zero-knowledge by construction — plaintext PII lives only on the call stack during a single request; it is GC-eligible the moment the response is returned.
Spec-accurate normalization — email lower/trim, phone → E.164 (auto-prepends the country code, e.g. 81 for Japan), names/city/state/zip/DOB/gender all formatted per the official Meta & Google guidelines.
SHA-256 hashing with idempotent pass-through for upstream-pre-hashed inputs.
Meta Conversions API with deduplication event_id support to pair with the browser Pixel.
Google Ads Enhanced Conversions via uploadClickConversions with userIdentifiers.
Concurrent, fault-isolated dispatch — one platform failing never blocks the other.
Automatic retries with exponential backoff + jitter on transient errors (network / 429 / 5xx).
Automatic Google OAuth refresh (optional) — refresh-token exchange, in-memory caching, concurrent-refresh coalescing; nothing persisted.
Single & batch webhook endpoints (/v1/collect, /v1/collect/batch).
Hardened Express server — shared-secret auth (constant-time compare), body-size caps, x-powered-by disabled, graceful shutdown.
Strict TypeScript end to end (exactOptionalPropertyTypes, noUncheckedIndexedAccess, …).
80 unit/integration tests (Vitest + Supertest), ESLint type-checked rules, multi-stage Docker image, and GitHub Actions CI.

🛡 The Zero-Knowledge Guarantee

flowchart LR
A["Upstream source<br/>(Webhook / CSV parse)"] -->|HTTPS + shared secret| B["CapConnect<br/>/v1/collect"]
subgraph MEM["⏱ In-memory only — never persisted, never logged"]
direction TB
C["Validate contract"] --> D["Normalize<br/>email · phone · name · address"]
D --> E["SHA-256 hash<br/>(irreversible, one-way)"]
E --> F["Build provider payloads<br/>(hashed digests only)"]
end
B --> C
F -->|TLS| G["Meta Conversions API<br/>(event_id dedup)"]
F -->|TLS| H["Google Ads API<br/>Enhanced Conversions"]
G --> I["Structured, PII-free<br/>dispatch report"]
H --> I
I -->|JSON response| A
classDef mem fill:#0b3d2e,stroke:#10b981,color:#e6fffa;
class MEM,C,D,E,F mem;

What crosses each boundary:

Boundary	Data in transit	Form
Upstream → CapConnect	Raw identifiers + event metadata	Plaintext over TLS (you control this hop)
Inside CapConnect	Identifiers	Normalized then SHA-256 hashed, in memory only
CapConnect → Meta/Google	Identifiers	SHA-256 hex digests + un-hashed match-support fields (fbc/fbp/IP/UA/gclid) per platform spec
CapConnect → Upstream	Dispatch outcome	No PII — only `event_id`, status, provider trace ids

🏗 Architecture

flowchart TD
subgraph SRC["src/"]
SV["server.ts<br/>Express app · auth · validation · routing"]
NM["utils/normalizer.ts<br/>normalize + SHA-256 (pure functions)"]
CP["services/capi.ts<br/>Meta + Google payload build & POST"]
TY["types/index.ts<br/>strict shared types"]
end
SV -->|"normalizeAndHash()"| NM
SV -->|"dispatchToAllProviders()"| CP
NM --- TY
CP --- TY
SV --- TY

File	Responsibility
`src/types/index.ts`	Single source of truth for every shape: raw input, hashed IR, provider payloads, responses, config.
`src/utils/normalizer.ts`	Field-by-field normalization (Meta/Google spec) + SHA-256. Pure, no I/O, no logging.
`src/utils/retry.ts`	Exponential-backoff retry helper; retries transient errors only.
`src/services/capi.ts`	Builds & POSTs Meta CAPI and Google Ads payloads concurrently; PII-free error reporting.
`src/services/googleAuth.ts`	Google OAuth token providers (static + auto-refreshing).
`src/server.ts`	Hardened Express server, config loading/validation, webhook endpoints, graceful shutdown.
`tests/`	Vitest unit + Supertest integration suites (80 tests).

🚀 Quick start

# 1. Install
npm install
# 2. Configure
cp .env.example .env
# …then edit .env with your Pixel id, access tokens, etc.# Generate a webhook secret: openssl rand -hex 32# 3. Develop (hot reload)
npm run dev
# 4. Production build & run
npm run build
npm start

Health check

curl -s http://localhost:3000/healthz | jq

{ "status": "ok", "service": "capconnect", "providers": { "meta": true, "google": true } }

📡 API

`POST /v1/collect`

Authenticated with the x-capconnect-token header (must equal WEBHOOK_SECRET).

Request

curl -s -X POST http://localhost:3000/v1/collect \
-H "Content-Type: application/json" \
-H "x-capconnect-token: $WEBHOOK_SECRET" \
-d '{ "customer": { "email": " John.Doe@Example.COM ", "phone": "090-1234-5678", "firstName": "John", "lastName": "Doe", "country": "JP", "city": "Tokyo", "zip": "100-0001", "externalId": "user_42" }, "event": { "eventName": "Purchase", "eventId": "order-2025-0001", "value": 4980, "currency": "JPY", "orderId": "order-2025-0001", "actionSource": "website", "eventSourceUrl": "https://shop.example.com/thank-you", "fbc": "fb.1.1700000000000.IwAR...", "gclid": "Cj0KCQ..." } }'

The phone above is normalized to 819012345678 (leading 0 dropped, 81 prepended) and then SHA-256 hashed before it ever leaves the process.

Response (200 if at least one provider accepted; 422 if none did)

{
"eventId": "order-2025-0001",
"accepted": true,
"results": [
{ "provider": "meta", "status": "sent", "httpStatus": 200, "detail": "events_received=1 fbtrace_id=Aa...", "reference": "order-2025-0001" },
{ "provider": "google", "status": "sent", "httpStatus": 200, "detail": "results=1", "reference": "order-2025-0001" }
]
}

`POST /v1/collect/batch`

Same auth. Body is a JSON array of { customer, event } objects (max 1000). Each item is processed independently; invalid items are reported in validationErrors without failing the rest.

curl -s -X POST http://localhost:3000/v1/collect/batch \
-H "Content-Type: application/json" \
-H "x-capconnect-token: $WEBHOOK_SECRET" \
-d '[ { "customer": { "email": "a@example.com" }, "event": { "eventName": "Lead" } } ]'

`GET /healthz`

Unauthenticated liveness/readiness probe. Returns no PII.

⚙️ Configuration

All configuration is via environment variables (see .env.example). The process fails fast at boot if an enabled provider is missing required secrets.

Server

Variable	Required	Default	Description
`PORT`	no	`3000`	HTTP listen port.
`WEBHOOK_SECRET`	yes	—	Shared secret required in the `x-capconnect-token` header.
`DEFAULT_COUNTRY_CODE`	no	`81`	Digits-only calling code auto-prepended to non-international phones.
`DEFAULT_CURRENCY`	no	`JPY`	ISO-4217 currency applied when an event omits one.
`HTTP_TIMEOUT_MS`	no	`10000`	Outbound request timeout for both providers.
`RETRY_MAX_ATTEMPTS`	no	`3`	Max attempts per provider call (incl. the first).
`RETRY_BASE_DELAY_MS`	no	`300`	Base backoff delay; doubles each retry, full-jittered.
`RETRY_MAX_DELAY_MS`	no	`5000`	Hard cap on any single backoff delay.

Meta Conversions API

Variable	Required	Default	Description
`META_ENABLED`	no	`true`	Toggle Meta dispatch.
`META_PIXEL_ID`	if enabled	—	Your Pixel / dataset id.
`META_ACCESS_TOKEN`	if enabled	—	System-user access token.
`META_API_VERSION`	no	`v20.0`	Graph API version.
`META_TEST_EVENT_CODE`	no	—	Enables Meta's Test Events tool when set.

Google Ads API (Enhanced Conversions)

Variable	Required	Default	Description
`GOOGLE_ENABLED`	no	`true`	Toggle Google dispatch.
`GOOGLE_CUSTOMER_ID`	if enabled	—	Account id owning the conversion action (digits, no dashes).
`GOOGLE_CONVERSION_ACTION_ID`	if enabled	—	Numeric conversion action id.
`GOOGLE_DEVELOPER_TOKEN`	if enabled	—	Google Ads API developer token.
`GOOGLE_OAUTH_ACCESS_TOKEN`	auth A	—	Pre-issued OAuth2 Bearer token (you refresh).
`GOOGLE_OAUTH_CLIENT_ID`	auth B	—	OAuth client id for automatic refresh.
`GOOGLE_OAUTH_CLIENT_SECRET`	auth B	—	OAuth client secret for automatic refresh.
`GOOGLE_OAUTH_REFRESH_TOKEN`	auth B	—	OAuth refresh token (held in memory only).
`GOOGLE_OAUTH_TOKEN_URI`	no	`https://oauth2.googleapis.com/token`	Token endpoint.
`GOOGLE_LOGIN_CUSTOMER_ID`	no	—	MCC / manager id for `login-customer-id`.
`GOOGLE_API_VERSION`	no	`v17`	Google Ads API version.
`GOOGLE_VALIDATE_ONLY`	no	`false`	Validate without recording a conversion.

OAuth — two strategies (provide exactly one):(A) Inject a short-lived GOOGLE_OAUTH_ACCESS_TOKEN from your own secret manager and handle refresh externally; or (B) provide GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET + GOOGLE_OAUTH_REFRESH_TOKEN and CapConnect refreshes access tokens automatically — caching them in memory, coalescing concurrent refreshes, and renewing ~60s before expiry. The refresh token is never persisted or logged. Boot fails fast if neither strategy is fully configured while Google is enabled.

Resilience

Automatic retries with exponential backoff + full jitter on transient failures only (network errors, HTTP 429, HTTP 5xx). Deterministic 4xx errors are never retried. Tune via RETRY_*.
Fault isolation — a Meta failure never blocks Google (and vice-versa); a Google token-refresh failure is reported as a Google-only auth: error while Meta still dispatches.

🔐 Normalization rules (Meta/Google compliant)

Field	Rule	Example → normalized
Email (`em`)	trim, lowercase (no dot-stripping)	`A.B@Ex.COM` → `a.b@ex.com`
Phone (`ph`)	digits only → E.164 (drop trunk `0`, prepend country code)	`090-1234-5678` → `819012345678`
First/Last name (`fn`/`ln`)	lowercase, strip punctuation, collapse spaces	`O'Brien` → `obrien`
City (`ct`)	lowercase, remove all whitespace & punctuation	`New York` → `newyork`
State (`st`)	lowercase, letters only	`CA` → `ca`
Zip (`zp`)	lowercase, strip spaces, drop `+4`, US→first 5	`100-0001` → `100`
Country (`country`)	ISO alpha-2, lowercase	`Japan`→ first 2 letters
DOB (`db`)	parse → `YYYYMMDD`	`1990/01/02` → `19900102`
Gender (`ge`)	→ `m` / `f`	`Male` → `m`

Every normalized value is then SHA-256 hashed to lowercase hex before dispatch. Empty/unusable values are dropped (never hashed to the all-empty digest).

🧪 Local verification

npm run typecheck # strict TS, no emit
npm run lint # ESLint (type-checked rules)
npm run build # compile to dist/
npm test# run the Vitest suite (80 tests)
npm run test:coverage # tests + coverage report
npm run ci # typecheck + lint + build + test (what CI runs)

You can exercise the pipeline safely against Meta's Test Events tool by setting META_TEST_EVENT_CODE, and against Google by setting GOOGLE_VALIDATE_ONLY=true.

🐳 Docker

# Build & run with compose (reads your .env)
cp .env.example .env # then fill in secrets
docker compose up --build
# …or build the image directly
docker build -t capconnect:latest .
docker run --rm -p 3000:3000 --env-file .env capconnect:latest

The image is a multi-stage build that ships only production dependencies and the compiled dist/, runs as the non-root node user, exposes a HEALTHCHECK against /healthz, and (via compose) runs read-only with dropped capabilities and no-new-privileges.

🔁 CI

.github/workflows/ci.yml runs on every push/PR: typecheck → lint → build → test across Node 18/20/22, a coverage job, and a Docker build job.

🤝 Operational guidance

Terminate TLS in front of CapConnect (reverse proxy / load balancer) and keep the upstream hop encrypted.
Rotate WEBHOOK_SECRET and provider tokens via your secret manager; never bake them into images.
Do not enable request-body logging at the proxy for /v1/collect* — that would defeat the zero-knowledge property outside the app.
Scale horizontally — the service is stateless, so run as many replicas as you need behind a load balancer.

📄 License

CapConnect is distributed under the Business Source License 1.1 (BSL-1.1).

You may use, copy, modify, and self-host CapConnect freely, including internally at your company.
The Additional Use Grant permits production use except offering CapConnect (or a substantially similar service) to third parties as a hosted/managed commercial "conversion-relay" product.
On the Change Date (four years after each version's release), that version automatically converts to the Apache License 2.0.

Licensed under the Business Source License 1.1 (the "License");
you may not use this file except in compliance with the License.
Change License: Apache License, Version 2.0
Change Date: four (4) years from the date of each release.
Additional Use Grant: You may use the Licensed Work in production, except to
provide it to third parties as a hosted or managed commercial conversion-relay
service that competes with the Licensor's offering.
THE LICENSED WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

Prefer a copyleft model instead? CapConnect is also available under the GNU AGPL-3.0 on request — contact the maintainers. Choose BSL-1.1 for permissive self-hosting with a commercial-SaaS carve-out, or AGPL-3.0 if you want network-use copyleft obligations.

_{Built for the cookieless era. Your customers' data stays your customers'.}

🔒 CapConnect

A privacy-first, zero-knowledge data connector for the cookieless era.

Clean → Hash (SHA-256) → Forward. First-party customer data is normalized and irreversibly hashed in memory before it is relayed to Meta Conversions API and Google Ads Enhanced Conversions. No raw PII ever touches a disk, a log, or a database.

Why CapConnect exists

Third-party cookies are gone. To keep measuring conversions, advertisers must send first-party data server-to-server. But doing that safely is the hard part: the moment raw emails and phone numbers leave your perimeter, your legal and security teams own a new liability.

CapConnect is the safe middle layer. It accepts your raw events, normalizes and SHA-256 hashes every personal field the instant it arrives, and forwards only those one-way digests to the ad platforms — exactly the way Meta and Google specify. Because the plaintext exists only transiently in process memory and is never persisted, there is nothing to leak from CapConnect's storage. There is no storage.

For CTOs & Legal: CapConnect is a stateless relay. It holds no datastore, writes no PII to disk, and emits no PII in logs. The only personal data it transmits is already a non-reversible SHA-256 hash, sent over TLS to Meta/Google — the same hashing the platforms' own SDKs perform client-side.

✨ Features

Zero-knowledge by construction — plaintext PII lives only on the call stack during a single request; it is GC-eligible the moment the response is returned.
Spec-accurate normalization — email lower/trim, phone → E.164 (auto-prepends the country code, e.g. 81 for Japan), names/city/state/zip/DOB/gender all formatted per the official Meta & Google guidelines.
SHA-256 hashing with idempotent pass-through for upstream-pre-hashed inputs.
Meta Conversions API with deduplication event_id support to pair with the browser Pixel.
Google Ads Enhanced Conversions via uploadClickConversions with userIdentifiers.
Concurrent, fault-isolated dispatch — one platform failing never blocks the other.
Automatic retries with exponential backoff + jitter on transient errors (network / 429 / 5xx).
Automatic Google OAuth refresh (optional) — refresh-token exchange, in-memory caching, concurrent-refresh coalescing; nothing persisted.
Single & batch webhook endpoints (/v1/collect, /v1/collect/batch).
Hardened Express server — shared-secret auth (constant-time compare), body-size caps, x-powered-by disabled, graceful shutdown.
Strict TypeScript end to end (exactOptionalPropertyTypes, noUncheckedIndexedAccess, …).
80 unit/integration tests (Vitest + Supertest), ESLint type-checked rules, multi-stage Docker image, and GitHub Actions CI.

🛡 The Zero-Knowledge Guarantee

flowchart LR
A["Upstream source<br/>(Webhook / CSV parse)"] -->|HTTPS + shared secret| B["CapConnect<br/>/v1/collect"]
subgraph MEM["⏱ In-memory only — never persisted, never logged"]
direction TB
C["Validate contract"] --> D["Normalize<br/>email · phone · name · address"]
D --> E["SHA-256 hash<br/>(irreversible, one-way)"]
E --> F["Build provider payloads<br/>(hashed digests only)"]
end
B --> C
F -->|TLS| G["Meta Conversions API<br/>(event_id dedup)"]
F -->|TLS| H["Google Ads API<br/>Enhanced Conversions"]
G --> I["Structured, PII-free<br/>dispatch report"]
H --> I
I -->|JSON response| A
classDef mem fill:#0b3d2e,stroke:#10b981,color:#e6fffa;
class MEM,C,D,E,F mem;

What crosses each boundary:

Boundary	Data in transit	Form
Upstream → CapConnect	Raw identifiers + event metadata	Plaintext over TLS (you control this hop)
Inside CapConnect	Identifiers	Normalized then SHA-256 hashed, in memory only
CapConnect → Meta/Google	Identifiers	SHA-256 hex digests + un-hashed match-support fields (fbc/fbp/IP/UA/gclid) per platform spec
CapConnect → Upstream	Dispatch outcome	No PII — only `event_id`, status, provider trace ids

🏗 Architecture

flowchart TD
subgraph SRC["src/"]
SV["server.ts<br/>Express app · auth · validation · routing"]
NM["utils/normalizer.ts<br/>normalize + SHA-256 (pure functions)"]
CP["services/capi.ts<br/>Meta + Google payload build & POST"]
TY["types/index.ts<br/>strict shared types"]
end
SV -->|"normalizeAndHash()"| NM
SV -->|"dispatchToAllProviders()"| CP
NM --- TY
CP --- TY
SV --- TY

File	Responsibility
`src/types/index.ts`	Single source of truth for every shape: raw input, hashed IR, provider payloads, responses, config.
`src/utils/normalizer.ts`	Field-by-field normalization (Meta/Google spec) + SHA-256. Pure, no I/O, no logging.
`src/utils/retry.ts`	Exponential-backoff retry helper; retries transient errors only.
`src/services/capi.ts`	Builds & POSTs Meta CAPI and Google Ads payloads concurrently; PII-free error reporting.
`src/services/googleAuth.ts`	Google OAuth token providers (static + auto-refreshing).
`src/server.ts`	Hardened Express server, config loading/validation, webhook endpoints, graceful shutdown.
`tests/`	Vitest unit + Supertest integration suites (80 tests).

🚀 Quick start

# 1. Install
npm install
# 2. Configure
cp .env.example .env
# …then edit .env with your Pixel id, access tokens, etc.# Generate a webhook secret: openssl rand -hex 32# 3. Develop (hot reload)
npm run dev
# 4. Production build & run
npm run build
npm start

Health check

curl -s http://localhost:3000/healthz | jq

{ "status": "ok", "service": "capconnect", "providers": { "meta": true, "google": true } }

📡 API

`POST /v1/collect`

Authenticated with the x-capconnect-token header (must equal WEBHOOK_SECRET).

Request

curl -s -X POST http://localhost:3000/v1/collect \
-H "Content-Type: application/json" \
-H "x-capconnect-token: $WEBHOOK_SECRET" \
-d '{ "customer": { "email": " John.Doe@Example.COM ", "phone": "090-1234-5678", "firstName": "John", "lastName": "Doe", "country": "JP", "city": "Tokyo", "zip": "100-0001", "externalId": "user_42" }, "event": { "eventName": "Purchase", "eventId": "order-2025-0001", "value": 4980, "currency": "JPY", "orderId": "order-2025-0001", "actionSource": "website", "eventSourceUrl": "https://shop.example.com/thank-you", "fbc": "fb.1.1700000000000.IwAR...", "gclid": "Cj0KCQ..." } }'

The phone above is normalized to 819012345678 (leading 0 dropped, 81 prepended) and then SHA-256 hashed before it ever leaves the process.

Response (200 if at least one provider accepted; 422 if none did)

{
"eventId": "order-2025-0001",
"accepted": true,
"results": [
{ "provider": "meta", "status": "sent", "httpStatus": 200, "detail": "events_received=1 fbtrace_id=Aa...", "reference": "order-2025-0001" },
{ "provider": "google", "status": "sent", "httpStatus": 200, "detail": "results=1", "reference": "order-2025-0001" }
]
}

`POST /v1/collect/batch`

Same auth. Body is a JSON array of { customer, event } objects (max 1000). Each item is processed independently; invalid items are reported in validationErrors without failing the rest.

curl -s -X POST http://localhost:3000/v1/collect/batch \
-H "Content-Type: application/json" \
-H "x-capconnect-token: $WEBHOOK_SECRET" \
-d '[ { "customer": { "email": "a@example.com" }, "event": { "eventName": "Lead" } } ]'

`GET /healthz`

Unauthenticated liveness/readiness probe. Returns no PII.

⚙️ Configuration

All configuration is via environment variables (see .env.example). The process fails fast at boot if an enabled provider is missing required secrets.

Server

Variable	Required	Default	Description
`PORT`	no	`3000`	HTTP listen port.
`WEBHOOK_SECRET`	yes	—	Shared secret required in the `x-capconnect-token` header.
`DEFAULT_COUNTRY_CODE`	no	`81`	Digits-only calling code auto-prepended to non-international phones.
`DEFAULT_CURRENCY`	no	`JPY`	ISO-4217 currency applied when an event omits one.
`HTTP_TIMEOUT_MS`	no	`10000`	Outbound request timeout for both providers.
`RETRY_MAX_ATTEMPTS`	no	`3`	Max attempts per provider call (incl. the first).
`RETRY_BASE_DELAY_MS`	no	`300`	Base backoff delay; doubles each retry, full-jittered.
`RETRY_MAX_DELAY_MS`	no	`5000`	Hard cap on any single backoff delay.

Meta Conversions API

Variable	Required	Default	Description
`META_ENABLED`	no	`true`	Toggle Meta dispatch.
`META_PIXEL_ID`	if enabled	—	Your Pixel / dataset id.
`META_ACCESS_TOKEN`	if enabled	—	System-user access token.
`META_API_VERSION`	no	`v20.0`	Graph API version.
`META_TEST_EVENT_CODE`	no	—	Enables Meta's Test Events tool when set.

Google Ads API (Enhanced Conversions)

Variable	Required	Default	Description
`GOOGLE_ENABLED`	no	`true`	Toggle Google dispatch.
`GOOGLE_CUSTOMER_ID`	if enabled	—	Account id owning the conversion action (digits, no dashes).
`GOOGLE_CONVERSION_ACTION_ID`	if enabled	—	Numeric conversion action id.
`GOOGLE_DEVELOPER_TOKEN`	if enabled	—	Google Ads API developer token.
`GOOGLE_OAUTH_ACCESS_TOKEN`	auth A	—	Pre-issued OAuth2 Bearer token (you refresh).
`GOOGLE_OAUTH_CLIENT_ID`	auth B	—	OAuth client id for automatic refresh.
`GOOGLE_OAUTH_CLIENT_SECRET`	auth B	—	OAuth client secret for automatic refresh.
`GOOGLE_OAUTH_REFRESH_TOKEN`	auth B	—	OAuth refresh token (held in memory only).
`GOOGLE_OAUTH_TOKEN_URI`	no	`https://oauth2.googleapis.com/token`	Token endpoint.
`GOOGLE_LOGIN_CUSTOMER_ID`	no	—	MCC / manager id for `login-customer-id`.
`GOOGLE_API_VERSION`	no	`v17`	Google Ads API version.
`GOOGLE_VALIDATE_ONLY`	no	`false`	Validate without recording a conversion.

OAuth — two strategies (provide exactly one):(A) Inject a short-lived GOOGLE_OAUTH_ACCESS_TOKEN from your own secret manager and handle refresh externally; or (B) provide GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET + GOOGLE_OAUTH_REFRESH_TOKEN and CapConnect refreshes access tokens automatically — caching them in memory, coalescing concurrent refreshes, and renewing ~60s before expiry. The refresh token is never persisted or logged. Boot fails fast if neither strategy is fully configured while Google is enabled.

Resilience

Automatic retries with exponential backoff + full jitter on transient failures only (network errors, HTTP 429, HTTP 5xx). Deterministic 4xx errors are never retried. Tune via RETRY_*.
Fault isolation — a Meta failure never blocks Google (and vice-versa); a Google token-refresh failure is reported as a Google-only auth: error while Meta still dispatches.

🔐 Normalization rules (Meta/Google compliant)

Field	Rule	Example → normalized
Email (`em`)	trim, lowercase (no dot-stripping)	`A.B@Ex.COM` → `a.b@ex.com`
Phone (`ph`)	digits only → E.164 (drop trunk `0`, prepend country code)	`090-1234-5678` → `819012345678`
First/Last name (`fn`/`ln`)	lowercase, strip punctuation, collapse spaces	`O'Brien` → `obrien`
City (`ct`)	lowercase, remove all whitespace & punctuation	`New York` → `newyork`
State (`st`)	lowercase, letters only	`CA` → `ca`
Zip (`zp`)	lowercase, strip spaces, drop `+4`, US→first 5	`100-0001` → `100`
Country (`country`)	ISO alpha-2, lowercase	`Japan`→ first 2 letters
DOB (`db`)	parse → `YYYYMMDD`	`1990/01/02` → `19900102`
Gender (`ge`)	→ `m` / `f`	`Male` → `m`

Every normalized value is then SHA-256 hashed to lowercase hex before dispatch. Empty/unusable values are dropped (never hashed to the all-empty digest).

🧪 Local verification

npm run typecheck # strict TS, no emit
npm run lint # ESLint (type-checked rules)
npm run build # compile to dist/
npm test# run the Vitest suite (80 tests)
npm run test:coverage # tests + coverage report
npm run ci # typecheck + lint + build + test (what CI runs)

You can exercise the pipeline safely against Meta's Test Events tool by setting META_TEST_EVENT_CODE, and against Google by setting GOOGLE_VALIDATE_ONLY=true.

🐳 Docker

# Build & run with compose (reads your .env)
cp .env.example .env # then fill in secrets
docker compose up --build
# …or build the image directly
docker build -t capconnect:latest .
docker run --rm -p 3000:3000 --env-file .env capconnect:latest

The image is a multi-stage build that ships only production dependencies and the compiled dist/, runs as the non-root node user, exposes a HEALTHCHECK against /healthz, and (via compose) runs read-only with dropped capabilities and no-new-privileges.

🔁 CI

.github/workflows/ci.yml runs on every push/PR: typecheck → lint → build → test across Node 18/20/22, a coverage job, and a Docker build job.

🤝 Operational guidance

Terminate TLS in front of CapConnect (reverse proxy / load balancer) and keep the upstream hop encrypted.
Rotate WEBHOOK_SECRET and provider tokens via your secret manager; never bake them into images.
Do not enable request-body logging at the proxy for /v1/collect* — that would defeat the zero-knowledge property outside the app.
Scale horizontally — the service is stateless, so run as many replicas as you need behind a load balancer.

📄 License

CapConnect is distributed under the Business Source License 1.1 (BSL-1.1).

You may use, copy, modify, and self-host CapConnect freely, including internally at your company.
The Additional Use Grant permits production use except offering CapConnect (or a substantially similar service) to third parties as a hosted/managed commercial "conversion-relay" product.
On the Change Date (four years after each version's release), that version automatically converts to the Apache License 2.0.

Licensed under the Business Source License 1.1 (the "License");
you may not use this file except in compliance with the License.
Change License: Apache License, Version 2.0
Change Date: four (4) years from the date of each release.
Additional Use Grant: You may use the Licensed Work in production, except to
provide it to third parties as a hosted or managed commercial conversion-relay
service that competes with the Licensor's offering.
THE LICENSED WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

Prefer a copyleft model instead? CapConnect is also available under the GNU AGPL-3.0 on request — contact the maintainers. Choose BSL-1.1 for permissive self-hosting with a commercial-SaaS carve-out, or AGPL-3.0 if you want network-use copyleft obligations.

_{Built for the cookieless era. Your customers' data stays your customers'.}

🔒 CapConnect

A privacy-first, zero-knowledge data connector for the cookieless era.

Clean → Hash (SHA-256) → Forward. First-party customer data is normalized and irreversibly hashed in memory before it is relayed to Meta Conversions API and Google Ads Enhanced Conversions. No raw PII ever touches a disk, a log, or a database.

Why CapConnect exists

Third-party cookies are gone. To keep measuring conversions, advertisers must send first-party data server-to-server. But doing that safely is the hard part: the moment raw emails and phone numbers leave your perimeter, your legal and security teams own a new liability.

CapConnect is the safe middle layer. It accepts your raw events, normalizes and SHA-256 hashes every personal field the instant it arrives, and forwards only those one-way digests to the ad platforms — exactly the way Meta and Google specify. Because the plaintext exists only transiently in process memory and is never persisted, there is nothing to leak from CapConnect's storage. There is no storage.

For CTOs & Legal: CapConnect is a stateless relay. It holds no datastore, writes no PII to disk, and emits no PII in logs. The only personal data it transmits is already a non-reversible SHA-256 hash, sent over TLS to Meta/Google — the same hashing the platforms' own SDKs perform client-side.

✨ Features

Zero-knowledge by construction — plaintext PII lives only on the call stack during a single request; it is GC-eligible the moment the response is returned.
Spec-accurate normalization — email lower/trim, phone → E.164 (auto-prepends the country code, e.g. 81 for Japan), names/city/state/zip/DOB/gender all formatted per the official Meta & Google guidelines.
SHA-256 hashing with idempotent pass-through for upstream-pre-hashed inputs.
Meta Conversions API with deduplication event_id support to pair with the browser Pixel.
Google Ads Enhanced Conversions via uploadClickConversions with userIdentifiers.
Concurrent, fault-isolated dispatch — one platform failing never blocks the other.
Automatic retries with exponential backoff + jitter on transient errors (network / 429 / 5xx).
Automatic Google OAuth refresh (optional) — refresh-token exchange, in-memory caching, concurrent-refresh coalescing; nothing persisted.
Single & batch webhook endpoints (/v1/collect, /v1/collect/batch).
Hardened Express server — shared-secret auth (constant-time compare), body-size caps, x-powered-by disabled, graceful shutdown.
Strict TypeScript end to end (exactOptionalPropertyTypes, noUncheckedIndexedAccess, …).
80 unit/integration tests (Vitest + Supertest), ESLint type-checked rules, multi-stage Docker image, and GitHub Actions CI.

🛡 The Zero-Knowledge Guarantee

flowchart LR
A["Upstream source<br/>(Webhook / CSV parse)"] -->|HTTPS + shared secret| B["CapConnect<br/>/v1/collect"]
subgraph MEM["⏱ In-memory only — never persisted, never logged"]
direction TB
C["Validate contract"] --> D["Normalize<br/>email · phone · name · address"]
D --> E["SHA-256 hash<br/>(irreversible, one-way)"]
E --> F["Build provider payloads<br/>(hashed digests only)"]
end
B --> C
F -->|TLS| G["Meta Conversions API<br/>(event_id dedup)"]
F -->|TLS| H["Google Ads API<br/>Enhanced Conversions"]
G --> I["Structured, PII-free<br/>dispatch report"]
H --> I
I -->|JSON response| A
classDef mem fill:#0b3d2e,stroke:#10b981,color:#e6fffa;
class MEM,C,D,E,F mem;

What crosses each boundary:

Boundary	Data in transit	Form
Upstream → CapConnect	Raw identifiers + event metadata	Plaintext over TLS (you control this hop)
Inside CapConnect	Identifiers	Normalized then SHA-256 hashed, in memory only
CapConnect → Meta/Google	Identifiers	SHA-256 hex digests + un-hashed match-support fields (fbc/fbp/IP/UA/gclid) per platform spec
CapConnect → Upstream	Dispatch outcome	No PII — only `event_id`, status, provider trace ids

🏗 Architecture

flowchart TD
subgraph SRC["src/"]
SV["server.ts<br/>Express app · auth · validation · routing"]
NM["utils/normalizer.ts<br/>normalize + SHA-256 (pure functions)"]
CP["services/capi.ts<br/>Meta + Google payload build & POST"]
TY["types/index.ts<br/>strict shared types"]
end
SV -->|"normalizeAndHash()"| NM
SV -->|"dispatchToAllProviders()"| CP
NM --- TY
CP --- TY
SV --- TY

File	Responsibility
`src/types/index.ts`	Single source of truth for every shape: raw input, hashed IR, provider payloads, responses, config.
`src/utils/normalizer.ts`	Field-by-field normalization (Meta/Google spec) + SHA-256. Pure, no I/O, no logging.
`src/utils/retry.ts`	Exponential-backoff retry helper; retries transient errors only.
`src/services/capi.ts`	Builds & POSTs Meta CAPI and Google Ads payloads concurrently; PII-free error reporting.
`src/services/googleAuth.ts`	Google OAuth token providers (static + auto-refreshing).
`src/server.ts`	Hardened Express server, config loading/validation, webhook endpoints, graceful shutdown.
`tests/`	Vitest unit + Supertest integration suites (80 tests).

🚀 Quick start

# 1. Install
npm install
# 2. Configure
cp .env.example .env
# …then edit .env with your Pixel id, access tokens, etc.# Generate a webhook secret: openssl rand -hex 32# 3. Develop (hot reload)
npm run dev
# 4. Production build & run
npm run build
npm start

Health check

curl -s http://localhost:3000/healthz | jq

{ "status": "ok", "service": "capconnect", "providers": { "meta": true, "google": true } }

📡 API

`POST /v1/collect`

Authenticated with the x-capconnect-token header (must equal WEBHOOK_SECRET).

Request

curl -s -X POST http://localhost:3000/v1/collect \
-H "Content-Type: application/json" \
-H "x-capconnect-token: $WEBHOOK_SECRET" \
-d '{ "customer": { "email": " John.Doe@Example.COM ", "phone": "090-1234-5678", "firstName": "John", "lastName": "Doe", "country": "JP", "city": "Tokyo", "zip": "100-0001", "externalId": "user_42" }, "event": { "eventName": "Purchase", "eventId": "order-2025-0001", "value": 4980, "currency": "JPY", "orderId": "order-2025-0001", "actionSource": "website", "eventSourceUrl": "https://shop.example.com/thank-you", "fbc": "fb.1.1700000000000.IwAR...", "gclid": "Cj0KCQ..." } }'

The phone above is normalized to 819012345678 (leading 0 dropped, 81 prepended) and then SHA-256 hashed before it ever leaves the process.

Response (200 if at least one provider accepted; 422 if none did)

{
"eventId": "order-2025-0001",
"accepted": true,
"results": [
{ "provider": "meta", "status": "sent", "httpStatus": 200, "detail": "events_received=1 fbtrace_id=Aa...", "reference": "order-2025-0001" },
{ "provider": "google", "status": "sent", "httpStatus": 200, "detail": "results=1", "reference": "order-2025-0001" }
]
}

`POST /v1/collect/batch`

Same auth. Body is a JSON array of { customer, event } objects (max 1000). Each item is processed independently; invalid items are reported in validationErrors without failing the rest.

curl -s -X POST http://localhost:3000/v1/collect/batch \
-H "Content-Type: application/json" \
-H "x-capconnect-token: $WEBHOOK_SECRET" \
-d '[ { "customer": { "email": "a@example.com" }, "event": { "eventName": "Lead" } } ]'

`GET /healthz`

Unauthenticated liveness/readiness probe. Returns no PII.

⚙️ Configuration

All configuration is via environment variables (see .env.example). The process fails fast at boot if an enabled provider is missing required secrets.

Server

Variable	Required	Default	Description
`PORT`	no	`3000`	HTTP listen port.
`WEBHOOK_SECRET`	yes	—	Shared secret required in the `x-capconnect-token` header.
`DEFAULT_COUNTRY_CODE`	no	`81`	Digits-only calling code auto-prepended to non-international phones.
`DEFAULT_CURRENCY`	no	`JPY`	ISO-4217 currency applied when an event omits one.
`HTTP_TIMEOUT_MS`	no	`10000`	Outbound request timeout for both providers.
`RETRY_MAX_ATTEMPTS`	no	`3`	Max attempts per provider call (incl. the first).
`RETRY_BASE_DELAY_MS`	no	`300`	Base backoff delay; doubles each retry, full-jittered.
`RETRY_MAX_DELAY_MS`	no	`5000`	Hard cap on any single backoff delay.

Meta Conversions API

Variable	Required	Default	Description
`META_ENABLED`	no	`true`	Toggle Meta dispatch.
`META_PIXEL_ID`	if enabled	—	Your Pixel / dataset id.
`META_ACCESS_TOKEN`	if enabled	—	System-user access token.
`META_API_VERSION`	no	`v20.0`	Graph API version.
`META_TEST_EVENT_CODE`	no	—	Enables Meta's Test Events tool when set.

Google Ads API (Enhanced Conversions)

Variable	Required	Default	Description
`GOOGLE_ENABLED`	no	`true`	Toggle Google dispatch.
`GOOGLE_CUSTOMER_ID`	if enabled	—	Account id owning the conversion action (digits, no dashes).
`GOOGLE_CONVERSION_ACTION_ID`	if enabled	—	Numeric conversion action id.
`GOOGLE_DEVELOPER_TOKEN`	if enabled	—	Google Ads API developer token.
`GOOGLE_OAUTH_ACCESS_TOKEN`	auth A	—	Pre-issued OAuth2 Bearer token (you refresh).
`GOOGLE_OAUTH_CLIENT_ID`	auth B	—	OAuth client id for automatic refresh.
`GOOGLE_OAUTH_CLIENT_SECRET`	auth B	—	OAuth client secret for automatic refresh.
`GOOGLE_OAUTH_REFRESH_TOKEN`	auth B	—	OAuth refresh token (held in memory only).
`GOOGLE_OAUTH_TOKEN_URI`	no	`https://oauth2.googleapis.com/token`	Token endpoint.
`GOOGLE_LOGIN_CUSTOMER_ID`	no	—	MCC / manager id for `login-customer-id`.
`GOOGLE_API_VERSION`	no	`v17`	Google Ads API version.
`GOOGLE_VALIDATE_ONLY`	no	`false`	Validate without recording a conversion.

OAuth — two strategies (provide exactly one):(A) Inject a short-lived GOOGLE_OAUTH_ACCESS_TOKEN from your own secret manager and handle refresh externally; or (B) provide GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET + GOOGLE_OAUTH_REFRESH_TOKEN and CapConnect refreshes access tokens automatically — caching them in memory, coalescing concurrent refreshes, and renewing ~60s before expiry. The refresh token is never persisted or logged. Boot fails fast if neither strategy is fully configured while Google is enabled.

Resilience

Automatic retries with exponential backoff + full jitter on transient failures only (network errors, HTTP 429, HTTP 5xx). Deterministic 4xx errors are never retried. Tune via RETRY_*.
Fault isolation — a Meta failure never blocks Google (and vice-versa); a Google token-refresh failure is reported as a Google-only auth: error while Meta still dispatches.

🔐 Normalization rules (Meta/Google compliant)

Field	Rule	Example → normalized
Email (`em`)	trim, lowercase (no dot-stripping)	`A.B@Ex.COM` → `a.b@ex.com`
Phone (`ph`)	digits only → E.164 (drop trunk `0`, prepend country code)	`090-1234-5678` → `819012345678`
First/Last name (`fn`/`ln`)	lowercase, strip punctuation, collapse spaces	`O'Brien` → `obrien`
City (`ct`)	lowercase, remove all whitespace & punctuation	`New York` → `newyork`
State (`st`)	lowercase, letters only	`CA` → `ca`
Zip (`zp`)	lowercase, strip spaces, drop `+4`, US→first 5	`100-0001` → `100`
Country (`country`)	ISO alpha-2, lowercase	`Japan`→ first 2 letters
DOB (`db`)	parse → `YYYYMMDD`	`1990/01/02` → `19900102`
Gender (`ge`)	→ `m` / `f`	`Male` → `m`

Every normalized value is then SHA-256 hashed to lowercase hex before dispatch. Empty/unusable values are dropped (never hashed to the all-empty digest).

🧪 Local verification

npm run typecheck # strict TS, no emit
npm run lint # ESLint (type-checked rules)
npm run build # compile to dist/
npm test# run the Vitest suite (80 tests)
npm run test:coverage # tests + coverage report
npm run ci # typecheck + lint + build + test (what CI runs)

You can exercise the pipeline safely against Meta's Test Events tool by setting META_TEST_EVENT_CODE, and against Google by setting GOOGLE_VALIDATE_ONLY=true.

🐳 Docker

# Build & run with compose (reads your .env)
cp .env.example .env # then fill in secrets
docker compose up --build
# …or build the image directly
docker build -t capconnect:latest .
docker run --rm -p 3000:3000 --env-file .env capconnect:latest

The image is a multi-stage build that ships only production dependencies and the compiled dist/, runs as the non-root node user, exposes a HEALTHCHECK against /healthz, and (via compose) runs read-only with dropped capabilities and no-new-privileges.

🔁 CI

.github/workflows/ci.yml runs on every push/PR: typecheck → lint → build → test across Node 18/20/22, a coverage job, and a Docker build job.

🤝 Operational guidance

Terminate TLS in front of CapConnect (reverse proxy / load balancer) and keep the upstream hop encrypted.
Rotate WEBHOOK_SECRET and provider tokens via your secret manager; never bake them into images.
Do not enable request-body logging at the proxy for /v1/collect* — that would defeat the zero-knowledge property outside the app.
Scale horizontally — the service is stateless, so run as many replicas as you need behind a load balancer.

📄 License

CapConnect is distributed under the Business Source License 1.1 (BSL-1.1).

You may use, copy, modify, and self-host CapConnect freely, including internally at your company.
The Additional Use Grant permits production use except offering CapConnect (or a substantially similar service) to third parties as a hosted/managed commercial "conversion-relay" product.
On the Change Date (four years after each version's release), that version automatically converts to the Apache License 2.0.

Licensed under the Business Source License 1.1 (the "License");
you may not use this file except in compliance with the License.
Change License: Apache License, Version 2.0
Change Date: four (4) years from the date of each release.
Additional Use Grant: You may use the Licensed Work in production, except to
provide it to third parties as a hosted or managed commercial conversion-relay
service that competes with the Licensor's offering.
THE LICENSED WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

Prefer a copyleft model instead? CapConnect is also available under the GNU AGPL-3.0 on request — contact the maintainers. Choose BSL-1.1 for permissive self-hosting with a commercial-SaaS carve-out, or AGPL-3.0 if you want network-use copyleft obligations.

_{Built for the cookieless era. Your customers' data stays your customers'.}

🔒 CapConnect

A privacy-first, zero-knowledge data connector for the cookieless era.

Clean → Hash (SHA-256) → Forward. First-party customer data is normalized and irreversibly hashed in memory before it is relayed to Meta Conversions API and Google Ads Enhanced Conversions. No raw PII ever touches a disk, a log, or a database.

Why CapConnect exists

Third-party cookies are gone. To keep measuring conversions, advertisers must send first-party data server-to-server. But doing that safely is the hard part: the moment raw emails and phone numbers leave your perimeter, your legal and security teams own a new liability.

CapConnect is the safe middle layer. It accepts your raw events, normalizes and SHA-256 hashes every personal field the instant it arrives, and forwards only those one-way digests to the ad platforms — exactly the way Meta and Google specify. Because the plaintext exists only transiently in process memory and is never persisted, there is nothing to leak from CapConnect's storage. There is no storage.

For CTOs & Legal: CapConnect is a stateless relay. It holds no datastore, writes no PII to disk, and emits no PII in logs. The only personal data it transmits is already a non-reversible SHA-256 hash, sent over TLS to Meta/Google — the same hashing the platforms' own SDKs perform client-side.

✨ Features

Zero-knowledge by construction — plaintext PII lives only on the call stack during a single request; it is GC-eligible the moment the response is returned.
Spec-accurate normalization — email lower/trim, phone → E.164 (auto-prepends the country code, e.g. 81 for Japan), names/city/state/zip/DOB/gender all formatted per the official Meta & Google guidelines.
SHA-256 hashing with idempotent pass-through for upstream-pre-hashed inputs.
Meta Conversions API with deduplication event_id support to pair with the browser Pixel.
Google Ads Enhanced Conversions via uploadClickConversions with userIdentifiers.
Concurrent, fault-isolated dispatch — one platform failing never blocks the other.
Automatic retries with exponential backoff + jitter on transient errors (network / 429 / 5xx).
Automatic Google OAuth refresh (optional) — refresh-token exchange, in-memory caching, concurrent-refresh coalescing; nothing persisted.
Single & batch webhook endpoints (/v1/collect, /v1/collect/batch).
Hardened Express server — shared-secret auth (constant-time compare), body-size caps, x-powered-by disabled, graceful shutdown.
Strict TypeScript end to end (exactOptionalPropertyTypes, noUncheckedIndexedAccess, …).
80 unit/integration tests (Vitest + Supertest), ESLint type-checked rules, multi-stage Docker image, and GitHub Actions CI.

🛡 The Zero-Knowledge Guarantee

flowchart LR
A["Upstream source<br/>(Webhook / CSV parse)"] -->|HTTPS + shared secret| B["CapConnect<br/>/v1/collect"]
subgraph MEM["⏱ In-memory only — never persisted, never logged"]
direction TB
C["Validate contract"] --> D["Normalize<br/>email · phone · name · address"]
D --> E["SHA-256 hash<br/>(irreversible, one-way)"]
E --> F["Build provider payloads<br/>(hashed digests only)"]
end
B --> C
F -->|TLS| G["Meta Conversions API<br/>(event_id dedup)"]
F -->|TLS| H["Google Ads API<br/>Enhanced Conversions"]
G --> I["Structured, PII-free<br/>dispatch report"]
H --> I
I -->|JSON response| A
classDef mem fill:#0b3d2e,stroke:#10b981,color:#e6fffa;
class MEM,C,D,E,F mem;

What crosses each boundary:

Boundary	Data in transit	Form
Upstream → CapConnect	Raw identifiers + event metadata	Plaintext over TLS (you control this hop)
Inside CapConnect	Identifiers	Normalized then SHA-256 hashed, in memory only
CapConnect → Meta/Google	Identifiers	SHA-256 hex digests + un-hashed match-support fields (fbc/fbp/IP/UA/gclid) per platform spec
CapConnect → Upstream	Dispatch outcome	No PII — only `event_id`, status, provider trace ids

🏗 Architecture

flowchart TD
subgraph SRC["src/"]
SV["server.ts<br/>Express app · auth · validation · routing"]
NM["utils/normalizer.ts<br/>normalize + SHA-256 (pure functions)"]
CP["services/capi.ts<br/>Meta + Google payload build & POST"]
TY["types/index.ts<br/>strict shared types"]
end
SV -->|"normalizeAndHash()"| NM
SV -->|"dispatchToAllProviders()"| CP
NM --- TY
CP --- TY
SV --- TY

File	Responsibility
`src/types/index.ts`	Single source of truth for every shape: raw input, hashed IR, provider payloads, responses, config.
`src/utils/normalizer.ts`	Field-by-field normalization (Meta/Google spec) + SHA-256. Pure, no I/O, no logging.
`src/utils/retry.ts`	Exponential-backoff retry helper; retries transient errors only.
`src/services/capi.ts`	Builds & POSTs Meta CAPI and Google Ads payloads concurrently; PII-free error reporting.
`src/services/googleAuth.ts`	Google OAuth token providers (static + auto-refreshing).
`src/server.ts`	Hardened Express server, config loading/validation, webhook endpoints, graceful shutdown.
`tests/`	Vitest unit + Supertest integration suites (80 tests).

🚀 Quick start

# 1. Install
npm install
# 2. Configure
cp .env.example .env
# …then edit .env with your Pixel id, access tokens, etc.# Generate a webhook secret: openssl rand -hex 32# 3. Develop (hot reload)
npm run dev
# 4. Production build & run
npm run build
npm start

Health check

curl -s http://localhost:3000/healthz | jq

{ "status": "ok", "service": "capconnect", "providers": { "meta": true, "google": true } }

📡 API

`POST /v1/collect`

Authenticated with the x-capconnect-token header (must equal WEBHOOK_SECRET).

Request

curl -s -X POST http://localhost:3000/v1/collect \
-H "Content-Type: application/json" \
-H "x-capconnect-token: $WEBHOOK_SECRET" \
-d '{ "customer": { "email": " John.Doe@Example.COM ", "phone": "090-1234-5678", "firstName": "John", "lastName": "Doe", "country": "JP", "city": "Tokyo", "zip": "100-0001", "externalId": "user_42" }, "event": { "eventName": "Purchase", "eventId": "order-2025-0001", "value": 4980, "currency": "JPY", "orderId": "order-2025-0001", "actionSource": "website", "eventSourceUrl": "https://shop.example.com/thank-you", "fbc": "fb.1.1700000000000.IwAR...", "gclid": "Cj0KCQ..." } }'

The phone above is normalized to 819012345678 (leading 0 dropped, 81 prepended) and then SHA-256 hashed before it ever leaves the process.

Response (200 if at least one provider accepted; 422 if none did)

{
"eventId": "order-2025-0001",
"accepted": true,
"results": [
{ "provider": "meta", "status": "sent", "httpStatus": 200, "detail": "events_received=1 fbtrace_id=Aa...", "reference": "order-2025-0001" },
{ "provider": "google", "status": "sent", "httpStatus": 200, "detail": "results=1", "reference": "order-2025-0001" }
]
}

`POST /v1/collect/batch`

Same auth. Body is a JSON array of { customer, event } objects (max 1000). Each item is processed independently; invalid items are reported in validationErrors without failing the rest.

curl -s -X POST http://localhost:3000/v1/collect/batch \
-H "Content-Type: application/json" \
-H "x-capconnect-token: $WEBHOOK_SECRET" \
-d '[ { "customer": { "email": "a@example.com" }, "event": { "eventName": "Lead" } } ]'

`GET /healthz`

Unauthenticated liveness/readiness probe. Returns no PII.

⚙️ Configuration

All configuration is via environment variables (see .env.example). The process fails fast at boot if an enabled provider is missing required secrets.

Server

Variable	Required	Default	Description
`PORT`	no	`3000`	HTTP listen port.
`WEBHOOK_SECRET`	yes	—	Shared secret required in the `x-capconnect-token` header.
`DEFAULT_COUNTRY_CODE`	no	`81`	Digits-only calling code auto-prepended to non-international phones.
`DEFAULT_CURRENCY`	no	`JPY`	ISO-4217 currency applied when an event omits one.
`HTTP_TIMEOUT_MS`	no	`10000`	Outbound request timeout for both providers.
`RETRY_MAX_ATTEMPTS`	no	`3`	Max attempts per provider call (incl. the first).
`RETRY_BASE_DELAY_MS`	no	`300`	Base backoff delay; doubles each retry, full-jittered.
`RETRY_MAX_DELAY_MS`	no	`5000`	Hard cap on any single backoff delay.

Meta Conversions API

Variable	Required	Default	Description
`META_ENABLED`	no	`true`	Toggle Meta dispatch.
`META_PIXEL_ID`	if enabled	—	Your Pixel / dataset id.
`META_ACCESS_TOKEN`	if enabled	—	System-user access token.
`META_API_VERSION`	no	`v20.0`	Graph API version.
`META_TEST_EVENT_CODE`	no	—	Enables Meta's Test Events tool when set.

Google Ads API (Enhanced Conversions)

Variable	Required	Default	Description
`GOOGLE_ENABLED`	no	`true`	Toggle Google dispatch.
`GOOGLE_CUSTOMER_ID`	if enabled	—	Account id owning the conversion action (digits, no dashes).
`GOOGLE_CONVERSION_ACTION_ID`	if enabled	—	Numeric conversion action id.
`GOOGLE_DEVELOPER_TOKEN`	if enabled	—	Google Ads API developer token.
`GOOGLE_OAUTH_ACCESS_TOKEN`	auth A	—	Pre-issued OAuth2 Bearer token (you refresh).
`GOOGLE_OAUTH_CLIENT_ID`	auth B	—	OAuth client id for automatic refresh.
`GOOGLE_OAUTH_CLIENT_SECRET`	auth B	—	OAuth client secret for automatic refresh.
`GOOGLE_OAUTH_REFRESH_TOKEN`	auth B	—	OAuth refresh token (held in memory only).
`GOOGLE_OAUTH_TOKEN_URI`	no	`https://oauth2.googleapis.com/token`	Token endpoint.
`GOOGLE_LOGIN_CUSTOMER_ID`	no	—	MCC / manager id for `login-customer-id`.
`GOOGLE_API_VERSION`	no	`v17`	Google Ads API version.
`GOOGLE_VALIDATE_ONLY`	no	`false`	Validate without recording a conversion.

OAuth — two strategies (provide exactly one):(A) Inject a short-lived GOOGLE_OAUTH_ACCESS_TOKEN from your own secret manager and handle refresh externally; or (B) provide GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET + GOOGLE_OAUTH_REFRESH_TOKEN and CapConnect refreshes access tokens automatically — caching them in memory, coalescing concurrent refreshes, and renewing ~60s before expiry. The refresh token is never persisted or logged. Boot fails fast if neither strategy is fully configured while Google is enabled.

Resilience

Automatic retries with exponential backoff + full jitter on transient failures only (network errors, HTTP 429, HTTP 5xx). Deterministic 4xx errors are never retried. Tune via RETRY_*.
Fault isolation — a Meta failure never blocks Google (and vice-versa); a Google token-refresh failure is reported as a Google-only auth: error while Meta still dispatches.

🔐 Normalization rules (Meta/Google compliant)

Field	Rule	Example → normalized
Email (`em`)	trim, lowercase (no dot-stripping)	`A.B@Ex.COM` → `a.b@ex.com`
Phone (`ph`)	digits only → E.164 (drop trunk `0`, prepend country code)	`090-1234-5678` → `819012345678`
First/Last name (`fn`/`ln`)	lowercase, strip punctuation, collapse spaces	`O'Brien` → `obrien`
City (`ct`)	lowercase, remove all whitespace & punctuation	`New York` → `newyork`
State (`st`)	lowercase, letters only	`CA` → `ca`
Zip (`zp`)	lowercase, strip spaces, drop `+4`, US→first 5	`100-0001` → `100`
Country (`country`)	ISO alpha-2, lowercase	`Japan`→ first 2 letters
DOB (`db`)	parse → `YYYYMMDD`	`1990/01/02` → `19900102`
Gender (`ge`)	→ `m` / `f`	`Male` → `m`

Every normalized value is then SHA-256 hashed to lowercase hex before dispatch. Empty/unusable values are dropped (never hashed to the all-empty digest).

🧪 Local verification

npm run typecheck # strict TS, no emit
npm run lint # ESLint (type-checked rules)
npm run build # compile to dist/
npm test# run the Vitest suite (80 tests)
npm run test:coverage # tests + coverage report
npm run ci # typecheck + lint + build + test (what CI runs)

You can exercise the pipeline safely against Meta's Test Events tool by setting META_TEST_EVENT_CODE, and against Google by setting GOOGLE_VALIDATE_ONLY=true.

🐳 Docker

# Build & run with compose (reads your .env)
cp .env.example .env # then fill in secrets
docker compose up --build
# …or build the image directly
docker build -t capconnect:latest .
docker run --rm -p 3000:3000 --env-file .env capconnect:latest

The image is a multi-stage build that ships only production dependencies and the compiled dist/, runs as the non-root node user, exposes a HEALTHCHECK against /healthz, and (via compose) runs read-only with dropped capabilities and no-new-privileges.

🔁 CI

.github/workflows/ci.yml runs on every push/PR: typecheck → lint → build → test across Node 18/20/22, a coverage job, and a Docker build job.

🤝 Operational guidance

Terminate TLS in front of CapConnect (reverse proxy / load balancer) and keep the upstream hop encrypted.
Rotate WEBHOOK_SECRET and provider tokens via your secret manager; never bake them into images.
Do not enable request-body logging at the proxy for /v1/collect* — that would defeat the zero-knowledge property outside the app.
Scale horizontally — the service is stateless, so run as many replicas as you need behind a load balancer.

📄 License

CapConnect is distributed under the Business Source License 1.1 (BSL-1.1).

You may use, copy, modify, and self-host CapConnect freely, including internally at your company.
The Additional Use Grant permits production use except offering CapConnect (or a substantially similar service) to third parties as a hosted/managed commercial "conversion-relay" product.
On the Change Date (four years after each version's release), that version automatically converts to the Apache License 2.0.

Licensed under the Business Source License 1.1 (the "License");
you may not use this file except in compliance with the License.
Change License: Apache License, Version 2.0
Change Date: four (4) years from the date of each release.
Additional Use Grant: You may use the Licensed Work in production, except to
provide it to third parties as a hosted or managed commercial conversion-relay
service that competes with the Licensor's offering.
THE LICENSED WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

Prefer a copyleft model instead? CapConnect is also available under the GNU AGPL-3.0 on request — contact the maintainers. Choose BSL-1.1 for permissive self-hosting with a commercial-SaaS carve-out, or AGPL-3.0 if you want network-use copyleft obligations.

_{Built for the cookieless era. Your customers' data stays your customers'.}

🔒 CapConnect

A privacy-first, zero-knowledge data connector for the cookieless era.

Clean → Hash (SHA-256) → Forward. First-party customer data is normalized and irreversibly hashed in memory before it is relayed to Meta Conversions API and Google Ads Enhanced Conversions. No raw PII ever touches a disk, a log, or a database.

Why CapConnect exists

Third-party cookies are gone. To keep measuring conversions, advertisers must send first-party data server-to-server. But doing that safely is the hard part: the moment raw emails and phone numbers leave your perimeter, your legal and security teams own a new liability.

CapConnect is the safe middle layer. It accepts your raw events, normalizes and SHA-256 hashes every personal field the instant it arrives, and forwards only those one-way digests to the ad platforms — exactly the way Meta and Google specify. Because the plaintext exists only transiently in process memory and is never persisted, there is nothing to leak from CapConnect's storage. There is no storage.

For CTOs & Legal: CapConnect is a stateless relay. It holds no datastore, writes no PII to disk, and emits no PII in logs. The only personal data it transmits is already a non-reversible SHA-256 hash, sent over TLS to Meta/Google — the same hashing the platforms' own SDKs perform client-side.

✨ Features

Zero-knowledge by construction — plaintext PII lives only on the call stack during a single request; it is GC-eligible the moment the response is returned.
Spec-accurate normalization — email lower/trim, phone → E.164 (auto-prepends the country code, e.g. 81 for Japan), names/city/state/zip/DOB/gender all formatted per the official Meta & Google guidelines.
SHA-256 hashing with idempotent pass-through for upstream-pre-hashed inputs.
Meta Conversions API with deduplication event_id support to pair with the browser Pixel.
Google Ads Enhanced Conversions via uploadClickConversions with userIdentifiers.
Concurrent, fault-isolated dispatch — one platform failing never blocks the other.
Automatic retries with exponential backoff + jitter on transient errors (network / 429 / 5xx).
Automatic Google OAuth refresh (optional) — refresh-token exchange, in-memory caching, concurrent-refresh coalescing; nothing persisted.
Single & batch webhook endpoints (/v1/collect, /v1/collect/batch).
Hardened Express server — shared-secret auth (constant-time compare), body-size caps, x-powered-by disabled, graceful shutdown.
Strict TypeScript end to end (exactOptionalPropertyTypes, noUncheckedIndexedAccess, …).
80 unit/integration tests (Vitest + Supertest), ESLint type-checked rules, multi-stage Docker image, and GitHub Actions CI.

🛡 The Zero-Knowledge Guarantee

flowchart LR
A["Upstream source<br/>(Webhook / CSV parse)"] -->|HTTPS + shared secret| B["CapConnect<br/>/v1/collect"]
subgraph MEM["⏱ In-memory only — never persisted, never logged"]
direction TB
C["Validate contract"] --> D["Normalize<br/>email · phone · name · address"]
D --> E["SHA-256 hash<br/>(irreversible, one-way)"]
E --> F["Build provider payloads<br/>(hashed digests only)"]
end
B --> C
F -->|TLS| G["Meta Conversions API<br/>(event_id dedup)"]
F -->|TLS| H["Google Ads API<br/>Enhanced Conversions"]
G --> I["Structured, PII-free<br/>dispatch report"]
H --> I
I -->|JSON response| A
classDef mem fill:#0b3d2e,stroke:#10b981,color:#e6fffa;
class MEM,C,D,E,F mem;

What crosses each boundary:

Boundary	Data in transit	Form
Upstream → CapConnect	Raw identifiers + event metadata	Plaintext over TLS (you control this hop)
Inside CapConnect	Identifiers	Normalized then SHA-256 hashed, in memory only
CapConnect → Meta/Google	Identifiers	SHA-256 hex digests + un-hashed match-support fields (fbc/fbp/IP/UA/gclid) per platform spec
CapConnect → Upstream	Dispatch outcome	No PII — only `event_id`, status, provider trace ids

🏗 Architecture

flowchart TD
subgraph SRC["src/"]
SV["server.ts<br/>Express app · auth · validation · routing"]
NM["utils/normalizer.ts<br/>normalize + SHA-256 (pure functions)"]
CP["services/capi.ts<br/>Meta + Google payload build & POST"]
TY["types/index.ts<br/>strict shared types"]
end
SV -->|"normalizeAndHash()"| NM
SV -->|"dispatchToAllProviders()"| CP
NM --- TY
CP --- TY
SV --- TY

File	Responsibility
`src/types/index.ts`	Single source of truth for every shape: raw input, hashed IR, provider payloads, responses, config.
`src/utils/normalizer.ts`	Field-by-field normalization (Meta/Google spec) + SHA-256. Pure, no I/O, no logging.
`src/utils/retry.ts`	Exponential-backoff retry helper; retries transient errors only.
`src/services/capi.ts`	Builds & POSTs Meta CAPI and Google Ads payloads concurrently; PII-free error reporting.
`src/services/googleAuth.ts`	Google OAuth token providers (static + auto-refreshing).
`src/server.ts`	Hardened Express server, config loading/validation, webhook endpoints, graceful shutdown.
`tests/`	Vitest unit + Supertest integration suites (80 tests).

🚀 Quick start

# 1. Install
npm install
# 2. Configure
cp .env.example .env
# …then edit .env with your Pixel id, access tokens, etc.# Generate a webhook secret: openssl rand -hex 32# 3. Develop (hot reload)
npm run dev
# 4. Production build & run
npm run build
npm start

Health check

curl -s http://localhost:3000/healthz | jq

{ "status": "ok", "service": "capconnect", "providers": { "meta": true, "google": true } }

📡 API

`POST /v1/collect`

Authenticated with the x-capconnect-token header (must equal WEBHOOK_SECRET).

Request

curl -s -X POST http://localhost:3000/v1/collect \
-H "Content-Type: application/json" \
-H "x-capconnect-token: $WEBHOOK_SECRET" \
-d '{ "customer": { "email": " John.Doe@Example.COM ", "phone": "090-1234-5678", "firstName": "John", "lastName": "Doe", "country": "JP", "city": "Tokyo", "zip": "100-0001", "externalId": "user_42" }, "event": { "eventName": "Purchase", "eventId": "order-2025-0001", "value": 4980, "currency": "JPY", "orderId": "order-2025-0001", "actionSource": "website", "eventSourceUrl": "https://shop.example.com/thank-you", "fbc": "fb.1.1700000000000.IwAR...", "gclid": "Cj0KCQ..." } }'

The phone above is normalized to 819012345678 (leading 0 dropped, 81 prepended) and then SHA-256 hashed before it ever leaves the process.

Response (200 if at least one provider accepted; 422 if none did)

{
"eventId": "order-2025-0001",
"accepted": true,
"results": [
{ "provider": "meta", "status": "sent", "httpStatus": 200, "detail": "events_received=1 fbtrace_id=Aa...", "reference": "order-2025-0001" },
{ "provider": "google", "status": "sent", "httpStatus": 200, "detail": "results=1", "reference": "order-2025-0001" }
]
}

`POST /v1/collect/batch`

Same auth. Body is a JSON array of { customer, event } objects (max 1000). Each item is processed independently; invalid items are reported in validationErrors without failing the rest.

curl -s -X POST http://localhost:3000/v1/collect/batch \
-H "Content-Type: application/json" \
-H "x-capconnect-token: $WEBHOOK_SECRET" \
-d '[ { "customer": { "email": "a@example.com" }, "event": { "eventName": "Lead" } } ]'

`GET /healthz`

Unauthenticated liveness/readiness probe. Returns no PII.

⚙️ Configuration

All configuration is via environment variables (see .env.example). The process fails fast at boot if an enabled provider is missing required secrets.

Server

Variable	Required	Default	Description
`PORT`	no	`3000`	HTTP listen port.
`WEBHOOK_SECRET`	yes	—	Shared secret required in the `x-capconnect-token` header.
`DEFAULT_COUNTRY_CODE`	no	`81`	Digits-only calling code auto-prepended to non-international phones.
`DEFAULT_CURRENCY`	no	`JPY`	ISO-4217 currency applied when an event omits one.
`HTTP_TIMEOUT_MS`	no	`10000`	Outbound request timeout for both providers.
`RETRY_MAX_ATTEMPTS`	no	`3`	Max attempts per provider call (incl. the first).
`RETRY_BASE_DELAY_MS`	no	`300`	Base backoff delay; doubles each retry, full-jittered.
`RETRY_MAX_DELAY_MS`	no	`5000`	Hard cap on any single backoff delay.

Meta Conversions API

Variable	Required	Default	Description
`META_ENABLED`	no	`true`	Toggle Meta dispatch.
`META_PIXEL_ID`	if enabled	—	Your Pixel / dataset id.
`META_ACCESS_TOKEN`	if enabled	—	System-user access token.
`META_API_VERSION`	no	`v20.0`	Graph API version.
`META_TEST_EVENT_CODE`	no	—	Enables Meta's Test Events tool when set.

Google Ads API (Enhanced Conversions)

Variable	Required	Default	Description
`GOOGLE_ENABLED`	no	`true`	Toggle Google dispatch.
`GOOGLE_CUSTOMER_ID`	if enabled	—	Account id owning the conversion action (digits, no dashes).
`GOOGLE_CONVERSION_ACTION_ID`	if enabled	—	Numeric conversion action id.
`GOOGLE_DEVELOPER_TOKEN`	if enabled	—	Google Ads API developer token.
`GOOGLE_OAUTH_ACCESS_TOKEN`	auth A	—	Pre-issued OAuth2 Bearer token (you refresh).
`GOOGLE_OAUTH_CLIENT_ID`	auth B	—	OAuth client id for automatic refresh.
`GOOGLE_OAUTH_CLIENT_SECRET`	auth B	—	OAuth client secret for automatic refresh.
`GOOGLE_OAUTH_REFRESH_TOKEN`	auth B	—	OAuth refresh token (held in memory only).
`GOOGLE_OAUTH_TOKEN_URI`	no	`https://oauth2.googleapis.com/token`	Token endpoint.
`GOOGLE_LOGIN_CUSTOMER_ID`	no	—	MCC / manager id for `login-customer-id`.
`GOOGLE_API_VERSION`	no	`v17`	Google Ads API version.
`GOOGLE_VALIDATE_ONLY`	no	`false`	Validate without recording a conversion.

OAuth — two strategies (provide exactly one):(A) Inject a short-lived GOOGLE_OAUTH_ACCESS_TOKEN from your own secret manager and handle refresh externally; or (B) provide GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET + GOOGLE_OAUTH_REFRESH_TOKEN and CapConnect refreshes access tokens automatically — caching them in memory, coalescing concurrent refreshes, and renewing ~60s before expiry. The refresh token is never persisted or logged. Boot fails fast if neither strategy is fully configured while Google is enabled.

Resilience

Automatic retries with exponential backoff + full jitter on transient failures only (network errors, HTTP 429, HTTP 5xx). Deterministic 4xx errors are never retried. Tune via RETRY_*.
Fault isolation — a Meta failure never blocks Google (and vice-versa); a Google token-refresh failure is reported as a Google-only auth: error while Meta still dispatches.

🔐 Normalization rules (Meta/Google compliant)

Field	Rule	Example → normalized
Email (`em`)	trim, lowercase (no dot-stripping)	`A.B@Ex.COM` → `a.b@ex.com`
Phone (`ph`)	digits only → E.164 (drop trunk `0`, prepend country code)	`090-1234-5678` → `819012345678`
First/Last name (`fn`/`ln`)	lowercase, strip punctuation, collapse spaces	`O'Brien` → `obrien`
City (`ct`)	lowercase, remove all whitespace & punctuation	`New York` → `newyork`
State (`st`)	lowercase, letters only	`CA` → `ca`
Zip (`zp`)	lowercase, strip spaces, drop `+4`, US→first 5	`100-0001` → `100`
Country (`country`)	ISO alpha-2, lowercase	`Japan`→ first 2 letters
DOB (`db`)	parse → `YYYYMMDD`	`1990/01/02` → `19900102`
Gender (`ge`)	→ `m` / `f`	`Male` → `m`

Every normalized value is then SHA-256 hashed to lowercase hex before dispatch. Empty/unusable values are dropped (never hashed to the all-empty digest).

🧪 Local verification

npm run typecheck # strict TS, no emit
npm run lint # ESLint (type-checked rules)
npm run build # compile to dist/
npm test# run the Vitest suite (80 tests)
npm run test:coverage # tests + coverage report
npm run ci # typecheck + lint + build + test (what CI runs)

You can exercise the pipeline safely against Meta's Test Events tool by setting META_TEST_EVENT_CODE, and against Google by setting GOOGLE_VALIDATE_ONLY=true.

🐳 Docker

# Build & run with compose (reads your .env)
cp .env.example .env # then fill in secrets
docker compose up --build
# …or build the image directly
docker build -t capconnect:latest .
docker run --rm -p 3000:3000 --env-file .env capconnect:latest

The image is a multi-stage build that ships only production dependencies and the compiled dist/, runs as the non-root node user, exposes a HEALTHCHECK against /healthz, and (via compose) runs read-only with dropped capabilities and no-new-privileges.

🔁 CI

.github/workflows/ci.yml runs on every push/PR: typecheck → lint → build → test across Node 18/20/22, a coverage job, and a Docker build job.

🤝 Operational guidance

Terminate TLS in front of CapConnect (reverse proxy / load balancer) and keep the upstream hop encrypted.
Rotate WEBHOOK_SECRET and provider tokens via your secret manager; never bake them into images.
Do not enable request-body logging at the proxy for /v1/collect* — that would defeat the zero-knowledge property outside the app.
Scale horizontally — the service is stateless, so run as many replicas as you need behind a load balancer.

📄 License

CapConnect is distributed under the Business Source License 1.1 (BSL-1.1).

You may use, copy, modify, and self-host CapConnect freely, including internally at your company.
The Additional Use Grant permits production use except offering CapConnect (or a substantially similar service) to third parties as a hosted/managed commercial "conversion-relay" product.
On the Change Date (four years after each version's release), that version automatically converts to the Apache License 2.0.

Licensed under the Business Source License 1.1 (the "License");
you may not use this file except in compliance with the License.
Change License: Apache License, Version 2.0
Change Date: four (4) years from the date of each release.
Additional Use Grant: You may use the Licensed Work in production, except to
provide it to third parties as a hosted or managed commercial conversion-relay
service that competes with the Licensor's offering.
THE LICENSED WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

Prefer a copyleft model instead? CapConnect is also available under the GNU AGPL-3.0 on request — contact the maintainers. Choose BSL-1.1 for permissive self-hosting with a commercial-SaaS carve-out, or AGPL-3.0 if you want network-use copyleft obligations.

_{Built for the cookieless era. Your customers' data stays your customers'.}

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
bin		bin
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
bin		bin
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
bin		bin
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
bin		bin
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
bin		bin
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

🔒 CapConnect

A privacy-first, zero-knowledge data connector for the cookieless era.

Why CapConnect exists

✨ Features

🛡 The Zero-Knowledge Guarantee

🏗 Architecture

🚀 Quick start

Health check

📡 API

POST /v1/collect

POST /v1/collect/batch

GET /healthz

⚙️ Configuration

Server

Meta Conversions API

Google Ads API (Enhanced Conversions)

Resilience

🔐 Normalization rules (Meta/Google compliant)

🧪 Local verification

🐳 Docker

🔁 CI

🤝 Operational guidance

📄 License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🔒 CapConnect

A privacy-first, zero-knowledge data connector for the cookieless era.

Why CapConnect exists

✨ Features

🛡 The Zero-Knowledge Guarantee

🏗 Architecture

🚀 Quick start

Health check

📡 API

POST /v1/collect

POST /v1/collect/batch

GET /healthz

⚙️ Configuration

Server

Meta Conversions API

Google Ads API (Enhanced Conversions)

Resilience

🔐 Normalization rules (Meta/Google compliant)

🧪 Local verification

🐳 Docker

🔁 CI

🤝 Operational guidance

📄 License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🔒 CapConnect

A privacy-first, zero-knowledge data connector for the cookieless era.

`POST /v1/collect`

`POST /v1/collect/batch`

`GET /healthz`

`POST /v1/collect`

`POST /v1/collect/batch`

`GET /healthz`

`POST /v1/collect`

`POST /v1/collect/batch`

`GET /healthz`

`POST /v1/collect`

`POST /v1/collect/batch`

`GET /healthz`