From 0b0a6231466509914db3c213055c093eeafa6f32 Mon Sep 17 00:00:00 2001 From: Chris Portscheller Date: Sun, 15 Nov 2026 21:44:07 -0600 Subject: [PATCH] feat: add inert honey credential instrumentation --- README.md | 26 +++++++ packages/webdecoy/README.md | 18 +++++ packages/webdecoy/src/client.ts | 55 +++++++++++++++ .../webdecoy/src/honey-credential.test.ts | 68 +++++++++++++++++++ packages/webdecoy/src/index.ts | 5 ++ packages/webdecoy/src/sdk.ts | 56 +++++++++++++++ packages/webdecoy/src/types.ts | 34 ++++++++++ 7 files changed, 262 insertions(+) create mode 100644 packages/webdecoy/src/honey-credential.test.ts diff --git a/README.md b/README.md index 37fb9a0..69e1e2a 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/packages/webdecoy/README.md b/packages/webdecoy/README.md index e74fca9..a52ea99 100644 --- a/packages/webdecoy/README.md +++ b/packages/webdecoy/README.md @@ -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. diff --git a/packages/webdecoy/src/client.ts b/packages/webdecoy/src/client.ts index 5df3d58..08d0ce7 100644 --- a/packages/webdecoy/src/client.ts +++ b/packages/webdecoy/src/client.ts @@ -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'; @@ -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 { + 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 { + 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): void { if (response.status === 401) { throw new Error('Invalid API key. Please check your Web Decoy configuration.'); diff --git a/packages/webdecoy/src/honey-credential.test.ts b/packages/webdecoy/src/honey-credential.test.ts new file mode 100644 index 0000000..45c0cd2 --- /dev/null +++ b/packages/webdecoy/src/honey-credential.test.ts @@ -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 }> = []; + global.fetch = jest.fn(async (url: unknown, init: RequestInit) => { + const body = JSON.parse(String(init.body)) as Record; + 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/); + }); +}); diff --git a/packages/webdecoy/src/index.ts b/packages/webdecoy/src/index.ts index 714a5aa..4a9f0b7 100644 --- a/packages/webdecoy/src/index.ts +++ b/packages/webdecoy/src/index.ts @@ -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 diff --git a/packages/webdecoy/src/sdk.ts b/packages/webdecoy/src/sdk.ts index f996105..d45e682 100644 --- a/packages/webdecoy/src/sdk.ts +++ b/packages/webdecoy/src/sdk.ts @@ -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; @@ -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 { + 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 { + 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 { + 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 { + return hmacSha256Hex(this.config.apiKey!, `webdecoy/honey-credential/v1\u0000${tokenId}\u0000${bearer}`); + } + /** * Whether this SDK instance has filter rules that need async enrichment */ diff --git a/packages/webdecoy/src/types.ts b/packages/webdecoy/src/types.ts index 5f534eb..219eec0 100644 --- a/packages/webdecoy/src/types.ts +++ b/packages/webdecoy/src/types.ts @@ -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 */