@request-shield/core 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +6 -4
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/turnstile.d.ts +26 -0
- package/dist/turnstile.d.ts.map +1 -0
- package/dist/turnstile.js +106 -0
- package/dist/turnstile.js.map +1 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -3,16 +3,18 @@
|
|
|
3
3
|
Signs your API requests with a **non-exportable WebCrypto key** so they can't be replayed, tampered with,
|
|
4
4
|
or forged from cURL/Postman. Framework-agnostic: includes a signed `fetch` and an axios adapter.
|
|
5
5
|
|
|
6
|
+
**[Live demo](https://karammm.github.io/request-shield/)**: copy a signed request into cURL and watch it get rejected.
|
|
7
|
+
|
|
6
8
|
```bash
|
|
7
9
|
npm install @request-shield/core
|
|
8
10
|
```
|
|
9
11
|
|
|
10
12
|
```ts
|
|
11
|
-
import { ShieldClient, createShieldFetch, attachShieldToAxios } from '@request-shield/core';
|
|
13
|
+
import { ShieldClient, createShieldFetch, attachShieldToAxios, createTurnstileTokenProvider } from '@request-shield/core';
|
|
12
14
|
|
|
13
15
|
const shield = new ShieldClient({
|
|
14
16
|
apiBase: 'https://api.example.com',
|
|
15
|
-
getAttestationToken: (
|
|
17
|
+
getAttestationToken: createTurnstileTokenProvider({ siteKey: '0x4AAAA…' }), // invisible bot check
|
|
16
18
|
});
|
|
17
19
|
|
|
18
20
|
// fetch
|
|
@@ -25,8 +27,8 @@ const api = axios.create({ baseURL: 'https://api.example.com' });
|
|
|
25
27
|
attachShieldToAxios(api, shield, axios.getAdapter);
|
|
26
28
|
```
|
|
27
29
|
|
|
28
|
-
Your server must verify the signatures
|
|
29
|
-
`go get github.com/karammm/request-shield/server/go`.
|
|
30
|
+
Your server must verify the signatures: [`@request-shield/server`](https://www.npmjs.com/package/@request-shield/server)
|
|
31
|
+
for Node/Express/Bun/Deno/Workers, or the Go middleware `go get github.com/karammm/request-shield/server/go@latest`.
|
|
30
32
|
|
|
31
33
|
Using a framework? See [`@request-shield/angular`](https://www.npmjs.com/package/@request-shield/angular) and
|
|
32
34
|
[`@request-shield/react`](https://www.npmjs.com/package/@request-shield/react).
|
package/dist/index.d.ts
CHANGED
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC"}
|
package/dist/index.js
CHANGED
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC"}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Cloudflare Turnstile helper for `getAttestationToken`.
|
|
3
|
+
*
|
|
4
|
+
* new ShieldClient({
|
|
5
|
+
* apiBase: 'https://api.example.com',
|
|
6
|
+
* getAttestationToken: createTurnstileTokenProvider({ siteKey: '0x4AAAAAAA...' }),
|
|
7
|
+
* });
|
|
8
|
+
*
|
|
9
|
+
* Loads the Turnstile script once, renders one invisible widget, and returns a fresh token per call
|
|
10
|
+
* (tokens are single-use). Visitors only see a challenge if Cloudflare decides it needs interaction.
|
|
11
|
+
*/
|
|
12
|
+
export interface TurnstileOptions {
|
|
13
|
+
/** Your Turnstile site key (public). */
|
|
14
|
+
siteKey: string;
|
|
15
|
+
/** Optional action name; verify it server-side with `action`. */
|
|
16
|
+
action?: string;
|
|
17
|
+
/** Element (or CSS selector) to render into. Default: a small fixed container at the bottom-right. */
|
|
18
|
+
container?: HTMLElement | string;
|
|
19
|
+
/** Default "interaction-only": invisible unless a challenge is needed. */
|
|
20
|
+
appearance?: 'always' | 'execute' | 'interaction-only';
|
|
21
|
+
/** Reject if no token arrives in time. Default 30s. */
|
|
22
|
+
timeoutMs?: number;
|
|
23
|
+
scriptUrl?: string;
|
|
24
|
+
}
|
|
25
|
+
export declare function createTurnstileTokenProvider(options: TurnstileOptions): () => Promise<string>;
|
|
26
|
+
//# sourceMappingURL=turnstile.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"turnstile.d.ts","sourceRoot":"","sources":["../src/turnstile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sGAAsG;IACtG,SAAS,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;IACjC,0EAA0E;IAC1E,UAAU,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,kBAAkB,CAAC;IACvD,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA8BD,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,CAkE7F"}
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Cloudflare Turnstile helper for `getAttestationToken`.
|
|
3
|
+
*
|
|
4
|
+
* new ShieldClient({
|
|
5
|
+
* apiBase: 'https://api.example.com',
|
|
6
|
+
* getAttestationToken: createTurnstileTokenProvider({ siteKey: '0x4AAAAAAA...' }),
|
|
7
|
+
* });
|
|
8
|
+
*
|
|
9
|
+
* Loads the Turnstile script once, renders one invisible widget, and returns a fresh token per call
|
|
10
|
+
* (tokens are single-use). Visitors only see a challenge if Cloudflare decides it needs interaction.
|
|
11
|
+
*/
|
|
12
|
+
const SCRIPT_URL = 'https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit';
|
|
13
|
+
let scriptPromise = null;
|
|
14
|
+
function turnstileGlobal() {
|
|
15
|
+
return globalThis.turnstile;
|
|
16
|
+
}
|
|
17
|
+
function loadTurnstile(url) {
|
|
18
|
+
const existing = turnstileGlobal();
|
|
19
|
+
if (existing)
|
|
20
|
+
return Promise.resolve(existing);
|
|
21
|
+
scriptPromise ??= new Promise((resolve, reject) => {
|
|
22
|
+
const s = document.createElement('script');
|
|
23
|
+
s.src = url;
|
|
24
|
+
s.async = true;
|
|
25
|
+
s.onload = () => {
|
|
26
|
+
const t = turnstileGlobal();
|
|
27
|
+
if (t)
|
|
28
|
+
resolve(t);
|
|
29
|
+
else
|
|
30
|
+
reject(new Error('request-shield: Turnstile script loaded but window.turnstile is missing'));
|
|
31
|
+
};
|
|
32
|
+
s.onerror = () => {
|
|
33
|
+
scriptPromise = null;
|
|
34
|
+
reject(new Error('request-shield: failed to load the Turnstile script (blocked by CSP or an ad blocker?)'));
|
|
35
|
+
};
|
|
36
|
+
document.head.appendChild(s);
|
|
37
|
+
});
|
|
38
|
+
return scriptPromise;
|
|
39
|
+
}
|
|
40
|
+
export function createTurnstileTokenProvider(options) {
|
|
41
|
+
let widgetId;
|
|
42
|
+
let container;
|
|
43
|
+
let pending = null;
|
|
44
|
+
let queue = Promise.resolve();
|
|
45
|
+
const settle = (fn) => {
|
|
46
|
+
const p = pending;
|
|
47
|
+
pending = null;
|
|
48
|
+
if (p)
|
|
49
|
+
fn(p);
|
|
50
|
+
};
|
|
51
|
+
const getContainer = () => {
|
|
52
|
+
if (options.container)
|
|
53
|
+
return options.container;
|
|
54
|
+
const el = document.createElement('div');
|
|
55
|
+
el.setAttribute('data-request-shield-turnstile', '');
|
|
56
|
+
el.style.cssText = 'position:fixed;right:16px;bottom:16px;z-index:2147483647';
|
|
57
|
+
document.body.appendChild(el);
|
|
58
|
+
return el;
|
|
59
|
+
};
|
|
60
|
+
const getToken = async () => {
|
|
61
|
+
const turnstile = await loadTurnstile(options.scriptUrl ?? SCRIPT_URL);
|
|
62
|
+
const token = new Promise((resolve, reject) => {
|
|
63
|
+
pending = { resolve, reject };
|
|
64
|
+
});
|
|
65
|
+
if (widgetId === undefined) {
|
|
66
|
+
container = getContainer();
|
|
67
|
+
widgetId = turnstile.render(container, {
|
|
68
|
+
sitekey: options.siteKey,
|
|
69
|
+
action: options.action,
|
|
70
|
+
appearance: options.appearance ?? 'interaction-only',
|
|
71
|
+
execution: 'execute',
|
|
72
|
+
callback: (t) => settle((p) => p.resolve(t)),
|
|
73
|
+
'error-callback': (code) => {
|
|
74
|
+
settle((p) => p.reject(new Error(`request-shield: Turnstile error ${code ?? ''}`.trim())));
|
|
75
|
+
return true; // we handle it; suppress Turnstile's console error
|
|
76
|
+
},
|
|
77
|
+
'expired-callback': () => { },
|
|
78
|
+
});
|
|
79
|
+
}
|
|
80
|
+
else {
|
|
81
|
+
turnstile.reset(widgetId);
|
|
82
|
+
}
|
|
83
|
+
turnstile.execute(widgetId ?? container);
|
|
84
|
+
const timeoutMs = options.timeoutMs ?? 30_000;
|
|
85
|
+
let timer;
|
|
86
|
+
const timeout = new Promise((_, reject) => {
|
|
87
|
+
timer = setTimeout(() => {
|
|
88
|
+
settle(() => { });
|
|
89
|
+
reject(new Error('request-shield: Turnstile timed out'));
|
|
90
|
+
}, timeoutMs);
|
|
91
|
+
});
|
|
92
|
+
try {
|
|
93
|
+
return await Promise.race([token, timeout]);
|
|
94
|
+
}
|
|
95
|
+
finally {
|
|
96
|
+
clearTimeout(timer);
|
|
97
|
+
}
|
|
98
|
+
};
|
|
99
|
+
// One widget, so serialize concurrent callers.
|
|
100
|
+
return () => {
|
|
101
|
+
const next = queue.then(getToken, getToken);
|
|
102
|
+
queue = next.catch(() => { });
|
|
103
|
+
return next;
|
|
104
|
+
};
|
|
105
|
+
}
|
|
106
|
+
//# sourceMappingURL=turnstile.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"turnstile.js","sourceRoot":"","sources":["../src/turnstile.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@request-shield/core",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "Stop API requests from being replayed or forged with cURL/Postman: signs every request with a browser key that cannot be exported. Works with fetch and axios.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"webcrypto",
|
|
7
7
|
"request-signing",
|