import * as lcc from "@distilled.cloud/cloudflare/leaked-credential-checks";
import { Unowned } from "alchemy/AdoptPolicy";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import { listAllZones } from "../Zone/lookup.ts";
const TypeId = "Cloudflare.LeakedCredentialCheck.Detection" as const;
type TypeId = typeof TypeId;
export interface LeakedCredentialDetectionProps {
/**
* Zone the custom detection belongs to. Stable — moving a detection
* between zones triggers a replacement.
*/
zoneId: string;
/**
* Ruleset expression locating the username in the request, e.g.
* `lookup_json_string(http.request.body.raw, "user")`. Mutable —
* updated in place via PUT. At least one of `username`/`password`
* should be set.
*/
username?: string;
/**
* Ruleset expression locating the password in the request, e.g.
* `lookup_json_string(http.request.body.raw, "secret")`. This is an
* expression over the request (not a secret value). Mutable — updated
* in place via PUT.
*/
password?: string;
}
export interface LeakedCredentialDetectionAttributes {
/** Cloudflare-assigned identifier of the custom detection. */
detectionId: string;
/** Zone the detection belongs to. */
zoneId: string;
/** The username-locating ruleset expression, if set. */
username: string | undefined;
/** The password-locating ruleset expression, if set. */
password: string | undefined;
}
export type LeakedCredentialDetection = Resource<
TypeId,
LeakedCredentialDetectionProps,
LeakedCredentialDetectionAttributes,
never,
Providers
>;
/**
* A custom detection location for Cloudflare Leaked Credential Checks
* (`/zones/{zone_id}/leaked-credential-checks/detections`) — a pair of
* ruleset expressions telling the WAF where to find the username and
* password in your application's login requests, so credentials submitted
* in non-standard payloads can still be checked against breach data.
*
* Requires Leaked Credential Checks to be **enabled** on the zone (see
* {@link LeakedCredentialCheck}) — every detection operation fails with the
* typed `LeakedCredentialChecksDisabled` error otherwise. The number of
* custom detections is plan-gated — a zone over its quota fails creation
* with the typed `DetectionQuotaExceeded` error. Each username/password
* expression pair may exist only once per zone (`DetectionAlreadyExists`).
*
* Safety: detections carry no ownership markers. When there is no prior
* state, `read` scans the zone for an existing detection with the same
* expressions and reports it as `Unowned`, so the engine refuses to take
* it over unless `--adopt` (or `adopt(true)`) is set.
* ### Custom detection locations
* **Example:** Detect credentials in a JSON login body
* ```typescript
* const check = yield* Cloudflare.LeakedCredentialCheck.LeakedCredentialCheck("Lcc", {
* zoneId: zone.zoneId,
* });
*
* yield* Cloudflare.LeakedCredentialCheck.LeakedCredentialDetection("LoginBody", {
* // Reference the check's zoneId so the toggle deploys first.
* zoneId: check.zoneId,
* username: 'lookup_json_string(http.request.body.raw, "user")',
* password: 'lookup_json_string(http.request.body.raw, "secret")',
* });
* ```
*
* **Example:** Username-only detection
* ```typescript
* yield* Cloudflare.LeakedCredentialCheck.LeakedCredentialDetection("UsernameHeader", {
* zoneId: check.zoneId,
* username: 'http.request.headers["x-username"][0]',
* });
* ```
*
* @see https://developers.cloudflare.com/waf/detections/leaked-credentials/#custom-detection-locations
*
* @resource
* @product Leaked Credential Checks
* @category Application Security
*/
export const LeakedCredentialDetection = Resource<LeakedCredentialDetection>(TypeId);
/**
* Creating a detection failed with `DetectionAlreadyExists`, but no detection
* with the same username/password expressions could be found on the zone.
*/
export class DetectionConflictUnresolved extends Data.TaggedError("DetectionConflictUnresolved")<{
readonly zoneId: string;
}> {
override get message() {
return `Leaked credential detection reported as existing on zone ${this.zoneId} but was not found`;
}
}
/**
* Returns true if the given value is a LeakedCredentialDetection resource.
*/
export const isLeakedCredentialDetection = (value: unknown): value is LeakedCredentialDetection =>
Predicate.hasProperty(value, "Type") && value.Type === TypeId;
export const LeakedCredentialDetectionProvider = () =>
Provider.succeed(LeakedCredentialDetection, {
stables: ["detectionId", "zoneId"],
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
// Detections live inside a zone (`/zones/{id}/.../detections`) with
// no account-wide enumeration API — fan out across every zone and
// exhaustively paginate the per-zone list.
const zones = yield* listAllZones(accountId);
const rows = yield* Effect.forEach(
zones,
(zone) =>
lcc.listDetections.pages({ zoneId: zone.id }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.result ?? []).map((d): LeakedCredentialDetectionAttributes =>
toAttributes(zone.id, d),
),
),
),
// Zones without the LCC toggle on refuse all detection reads;
// a freshly-minted scoped token can also 403 mid edge-
// propagation. Either way the zone contributes nothing.
Effect.catchTags({
LeakedCredentialChecksDisabled: (): Effect.Effect<
LeakedCredentialDetectionAttributes[]
> => Effect.succeed([]),
Forbidden: (): Effect.Effect<LeakedCredentialDetectionAttributes[]> =>
Effect.succeed([]),
}),
),
{ concurrency: 10 },
);
return rows.flat();
}),
diff: Effect.fn(function* ({ olds = {}, news, output }) {
const o = olds as LeakedCredentialDetectionProps;
const n = news as LeakedCredentialDetectionProps;
// zoneId is Input<string>; compare only once both sides are concrete.
const oldZoneId = output?.zoneId ?? (typeof o.zoneId === "string" ? o.zoneId : undefined);
if (oldZoneId !== undefined && typeof n.zoneId === "string" && oldZoneId !== n.zoneId) {
return { action: "replace" } as const;
}
return undefined;
}),
read: Effect.fn(function* ({ output, olds }) {
const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
if (!zoneId) return undefined;
// Owned path: refresh by our persisted detection id.
if (output?.detectionId) {
const observed = yield* getDetection(zoneId, output.detectionId);
if (observed) return toAttributes(zoneId, observed);
}
// Adoption path: a detection with these expressions may already
// exist on the zone. Detections carry no ownership markers, so we
// cannot prove we created it — brand it `Unowned` so the engine
// refuses to take over unless `adopt` is set.
const username = output?.username ?? olds?.username;
const password = output?.password ?? olds?.password;
if (username !== undefined || password !== undefined) {
const observed = yield* findByExpressions(zoneId, username, password);
if (observed) return Unowned(toAttributes(zoneId, observed));
}
return undefined;
}),
reconcile: Effect.fn(function* ({ news, output }) {
// Inputs have been resolved to concrete strings by Plan.
const zoneId = news.zoneId as string;
// 1. Observe — the detection id cached on `output` is a hint, not
// a guarantee: a missing detection falls through to the
// expression scan and then to create.
let observed = output?.detectionId
? yield* getDetection(zoneId, output.detectionId)
: undefined;
// 2. Fall back to scanning the zone for an expression match.
// Ownership has already been verified upstream — `read` reports
// existing detections as `Unowned` and the engine gates takeover
// behind the adopt policy before reconcile ever runs.
if (!observed) {
observed = yield* findByExpressions(zoneId, news.username, news.password);
}
// 3. Ensure — create when missing. Requires the zone's Leaked
// Credential Checks toggle to be on; otherwise this fails with
// the typed `LeakedCredentialChecksDisabled` error.
// A concurrent create of the same expression pair races us to
// the typed `DetectionAlreadyExists` — re-observe and continue.
if (!observed) {
observed = yield* lcc
.createDetection({
zoneId,
username: news.username,
password: news.password,
})
.pipe(
Effect.map((d): ObservedDetection | undefined => d),
Effect.catchTag("DetectionAlreadyExists", () =>
findByExpressions(zoneId, news.username, news.password),
),
);
if (!observed) {
return yield* new DetectionConflictUnresolved({ zoneId });
}
}
// 4. Sync — PUT only when the observed expressions differ.
const dirty =
(observed.username ?? undefined) !== news.username ||
(observed.password ?? undefined) !== news.password;
if (dirty) {
observed = yield* lcc.updateDetection({
zoneId,
detectionId: observed.id ?? "",
username: news.username,
password: news.password,
});
}
return toAttributes(zoneId, observed);
}),
delete: Effect.fn(function* ({ output }) {
yield* lcc
.deleteDetection({
zoneId: output.zoneId,
detectionId: output.detectionId,
})
.pipe(
// Already gone — idempotent re-delete after a crashed run.
Effect.catchTags({
DetectionNotFound: () => Effect.void,
// The zone's toggle was switched off out-of-band; the API
// refuses all detection operations then. The detection is
// unreachable either way — treat as converged.
LeakedCredentialChecksDisabled: () => Effect.void,
}),
);
}),
});
// ---------------------------------------------------------------------------
// API helpers
// ---------------------------------------------------------------------------
type ObservedDetection = {
id?: string | null;
username?: string | null;
password?: string | null;
};
/**
* Read a detection by id, mapping "gone" (`DetectionNotFound`, Cloudflare
* error code 11002) and "product off" (`LeakedCredentialChecksDisabled`,
* code 11001 — the API refuses all detection reads while the zone toggle is
* off) to `undefined`.
*/
const getDetection = (zoneId: string, detectionId: string) =>
lcc.getDetection({ zoneId, detectionId }).pipe(
Effect.map((d): ObservedDetection | undefined => d),
Effect.catchTags({
DetectionNotFound: () => Effect.undefined,
LeakedCredentialChecksDisabled: () => Effect.undefined,
}),
);
/**
* Find a detection by exact username+password expression pair within the
* zone. Used for cold reads (state lost) and as the create fallback.
*/
const findByExpressions = (
zoneId: string,
username: string | undefined,
password: string | undefined,
) =>
lcc.listDetections.items({ zoneId }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).find(
(d): d is ObservedDetection =>
(d.username ?? undefined) === username && (d.password ?? undefined) === password,
),
),
Effect.catchTag("LeakedCredentialChecksDisabled", () => Effect.undefined),
);
const toAttributes = (
zoneId: string,
detection: ObservedDetection,
): LeakedCredentialDetectionAttributes => ({
detectionId: detection.id ?? "",
zoneId,
username: detection.username ?? undefined,
password: detection.password ?? undefined,
});