Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -338,6 +338,32 @@ both the trusted initiation and the matching single-use callback within 15
minutes; either edge alone is not confirmed SSRF. Open the callback detection
in WebDecoy to see its **Correlated activity** evidence.

### Correlate an inert decoy credential

Create a credential that grants no access, place its bearer in a decoy, and
keep only the safe handle after placement:

```typescript
const created = await wd.createHoneyCredential({ test: true });
await putInDecoyConfig(created.bearer);

// Call from the decoy's delivery hook, only when that decoy is actually read.
await wd.reportHoneyCredentialRetrieval(created.handle, '/decoy/config');

// Run only after your application has parsed a credential candidate.
const result = await wd.observeHoneyCredentialPresentation(
candidate,
created.handle,
'/login',
);
```

The bearer and every non-matching candidate remain local. WebDecoy receives
only the property-scoped token ID and keyed fingerprint, and the presentation
event is sent only after an exact constant-time local match. Retrieval alone
does not create a reuse finding. The SDK never authorizes this token, applies a
block, or gives it access to a provider or financial account.

### Getting an API key

1. Sign up at [app.webdecoy.com](https://app.webdecoy.com)
Expand Down
18 changes: 18 additions & 0 deletions packages/webdecoy/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,24 @@ WebDecoy never fetches a supplied URL; a finding is created only after the
matching callback arrives. Use `test: true` for controlled validation so it is
kept out of production threat metrics.

### Correlate an inert decoy credential

```ts
const created = await wd.createHoneyCredential({ test: true });
await putInDecoyConfig(created.bearer);

// Call from the decoy's delivery hook, only when that decoy is actually read.
await wd.reportHoneyCredentialRetrieval(created.handle, '/decoy/config');

const result = await wd.observeHoneyCredentialPresentation(candidate, created.handle, '/login');
```

Discard `created.bearer` after placing it in the decoy and retain only the
handle. A keyed fingerprint is registered; neither the bearer nor a candidate
credential is sent. A presentation request is made only when the candidate is
an exact local match for the inert token. Retrieval alone remains an ordinary
decoy event, and this API never blocks or grants access.

### Monitor first

`protect()` only returns a decision. It never writes a response, so nothing is blocked until your code acts on `decision.allowed`. The framework adapters and `createFetchGuard()` follow the same rule: they start in **monitor mode** (`mode: 'monitor'`), record the decision and serve every request. Set `mode: 'enforce'` only after you have reviewed what would have been blocked.
Expand Down
55 changes: 55 additions & 0 deletions packages/webdecoy/src/client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,9 @@ import {
SSRFCanary,
SSRFCanaryOptions,
SSRFInitiationReceipt,
HoneyCredentialHandle,
HoneyCredentialOptions,
HoneyCredentialReceipt,
} from './types';
import { reportableHeaders } from './report-headers';
import type { ViolationEvent, IPEnrichmentData } from './rules/types';
Expand Down Expand Up @@ -258,6 +261,58 @@ export class WebDecoyClient {
return { detectionId: data.detection_id, markerId: data.marker_id, test: data.test === true };
}

async registerHoneyCredential(
tokenId: string,
keyedFingerprint: string,
options: HoneyCredentialOptions,
): Promise<HoneyCredentialHandle> {
const response = await this.request<{
token_id: string;
expires_at: string;
test: boolean;
} & ApiErrorBody>('POST', '/api/v1/sdk/honey-credentials', {
property_id: options.propertyId,
token_id: tokenId,
keyed_fingerprint: keyedFingerprint,
test: options.test === true,
});
this.requireSuccess(response);
const data = response.data!;
if (!data.token_id || !data.expires_at) {
throw new Error('WebDecoy returned an invalid honey credential handle');
}
return {
tokenId: data.token_id,
keyedFingerprint,
propertyId: options.propertyId,
expiresAt: data.expires_at,
test: data.test === true,
};
}

async reportHoneyCredentialEvent(
event: 'retrieval' | 'presentation',
handle: HoneyCredentialHandle,
routeTemplate: string,
): Promise<HoneyCredentialReceipt> {
const response = await this.request<{
detection_id: string;
token_id: string;
test: boolean;
} & ApiErrorBody>('POST', `/api/v1/sdk/honey-credentials/${event}`, {
property_id: handle.propertyId,
token_id: handle.tokenId,
keyed_fingerprint: handle.keyedFingerprint,
route_template: routeTemplate,
});
this.requireSuccess(response);
const data = response.data!;
if (!data.detection_id || !data.token_id) {
throw new Error('WebDecoy returned an invalid honey credential receipt');
}
return { detectionId: data.detection_id, tokenId: data.token_id, test: data.test === true };
}

private requireSuccess(response: ApiResponse<ApiErrorBody>): void {
if (response.status === 401) {
throw new Error('Invalid API key. Please check your Web Decoy configuration.');
Expand Down
68 changes: 68 additions & 0 deletions packages/webdecoy/src/honey-credential.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
import { WebDecoy } from './sdk';

describe('honey credential correlation', () => {
const realFetch = global.fetch;

afterEach(() => {
global.fetch = realFetch;
});

it('never sends the bearer or a mismatched presented credential', async () => {
const calls: Array<{ url: string; body: Record<string, unknown> }> = [];
global.fetch = jest.fn(async (url: unknown, init: RequestInit) => {
const body = JSON.parse(String(init.body)) as Record<string, unknown>;
calls.push({ url: String(url), body });
if (String(url).endsWith('/honey-credentials')) {
return new Response(
JSON.stringify({
token_id: body.token_id,
expires_at: '2026-12-15T21:00:00Z',
test: true,
}),
{ status: 201 }
);
}
return new Response(
JSON.stringify({
detection_id: crypto.randomUUID(),
token_id: body.token_id,
test: true,
}),
{ status: 201 }
);
}) as jest.Mock;

const sdk = new WebDecoy({ apiKey: 'sk_test_honey', apiUrl: 'https://ingest.example' });
const created = await sdk.createHoneyCredential({
propertyId: '8c6459a9-6219-4f61-ad88-b0e4f1774249',
test: true,
});
await sdk.reportHoneyCredentialRetrieval(created.handle, '/decoy/config');

const realCredential = 'prod-secret-that-must-stay-local';
await expect(
sdk.observeHoneyCredentialPresentation(realCredential, created.handle, '/login')
).resolves.toEqual({ matched: false });
expect(calls).toHaveLength(2);

const matched = await sdk.observeHoneyCredentialPresentation(
created.bearer,
created.handle,
'/login'
);
expect(matched.matched).toBe(true);
expect(calls).toHaveLength(3);
expect(calls[2].url).toBe('https://ingest.example/api/v1/sdk/honey-credentials/presentation');

const wire = JSON.stringify(calls);
expect(wire).not.toContain(created.bearer);
expect(wire).not.toContain(realCredential);
expect(wire).not.toContain('authorization');
expect(wire).not.toContain('request_body');
});

it('requires hosted reporting', async () => {
const sdk = new WebDecoy();
await expect(sdk.createHoneyCredential()).rejects.toThrow(/apiKey/);
});
});
5 changes: 5 additions & 0 deletions packages/webdecoy/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,11 @@ export type {
SSRFCanary,
SSRFCanaryOptions,
SSRFInitiationReceipt,
CreatedHoneyCredential,
HoneyCredentialHandle,
HoneyCredentialOptions,
HoneyCredentialPresentationResult,
HoneyCredentialReceipt,
} from './types';

// The decision `protect()` returns. Exported as a value because the class
Expand Down
56 changes: 56 additions & 0 deletions packages/webdecoy/src/sdk.ts
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,13 @@ import {
SSRFCanary,
SSRFCanaryOptions,
SSRFInitiationReceipt,
CreatedHoneyCredential,
HoneyCredentialHandle,
HoneyCredentialOptions,
HoneyCredentialPresentationResult,
HoneyCredentialReceipt,
} from './types';
import { hmacSha256Hex, randomHex, timingSafeEqualStr } from './webcrypto';

export class WebDecoy {
private client: WebDecoyClient | null;
Expand Down Expand Up @@ -348,6 +354,56 @@ export class WebDecoy {
return this.client.reportSSRFInitiation(canary);
}

/**
* Create an inert decoy bearer. WebDecoy receives only a tenant-scoped ID
* and keyed fingerprint; the bearer is returned locally exactly once.
*/
async createHoneyCredential(options: HoneyCredentialOptions = {}): Promise<CreatedHoneyCredential> {
if (!this.client || !this.config.apiKey) {
throw new Error('An apiKey is required to create a honey credential');
}
const tokenId = crypto.randomUUID();
const bearer = `wd_hc_v1_${randomHex(32)}`;
const keyedFingerprint = await this.honeyCredentialFingerprint(tokenId, bearer);
const handle = await this.client.registerHoneyCredential(tokenId, keyedFingerprint, options);
return { bearer, handle };
}

/** Report that the inert credential was exposed by a decoy route. */
async reportHoneyCredentialRetrieval(
handle: HoneyCredentialHandle,
routeTemplate: string,
): Promise<HoneyCredentialReceipt> {
if (!this.client) {
throw new Error('An apiKey is required to report a honey credential retrieval');
}
return this.client.reportHoneyCredentialEvent('retrieval', handle, routeTemplate);
}

/**
* Compare a presented value locally. A mismatch—including a real
* credential—never leaves the process and creates no WebDecoy request.
*/
async observeHoneyCredentialPresentation(
candidate: string,
handle: HoneyCredentialHandle,
routeTemplate: string,
): Promise<HoneyCredentialPresentationResult> {
if (!this.client || !this.config.apiKey) {
throw new Error('An apiKey is required to observe a honey credential presentation');
}
const candidateFingerprint = await this.honeyCredentialFingerprint(handle.tokenId, candidate);
if (!timingSafeEqualStr(candidateFingerprint, handle.keyedFingerprint)) {
return { matched: false };
}
const receipt = await this.client.reportHoneyCredentialEvent('presentation', handle, routeTemplate);
return { matched: true, receipt };
}

private honeyCredentialFingerprint(tokenId: string, bearer: string): Promise<string> {
return hmacSha256Hex(this.config.apiKey!, `webdecoy/honey-credential/v1\u0000${tokenId}\u0000${bearer}`);
}

/**
* Whether this SDK instance has filter rules that need async enrichment
*/
Expand Down
34 changes: 34 additions & 0 deletions packages/webdecoy/src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,40 @@ export interface SSRFInitiationReceipt {
test: boolean;
}

/** Options for an inert, property-scoped decoy credential. */
export interface HoneyCredentialOptions {
/** Required only when an organization-wide API key is used. */
propertyId?: string;
/** Keep a controlled validation out of production threat metrics. */
test?: boolean;
}

/** Safe material retained after the bearer has been placed in a decoy. */
export interface HoneyCredentialHandle {
tokenId: string;
keyedFingerprint: string;
propertyId?: string;
expiresAt: string;
test: boolean;
}

/** The bearer is returned only at creation and is never sent to WebDecoy. */
export interface CreatedHoneyCredential {
bearer: string;
handle: HoneyCredentialHandle;
}

export interface HoneyCredentialReceipt {
detectionId: string;
tokenId: string;
test: boolean;
}

export interface HoneyCredentialPresentationResult {
matched: boolean;
receipt?: HoneyCredentialReceipt;
}

/**
* TLS connection information from the request
*/
Expand Down
Loading