@peac/jwks-cache 0.12.5 → 0.12.6
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 +56 -3
- package/package.json +11 -7
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @peac/jwks-cache
|
|
2
2
|
|
|
3
|
-
Edge-safe JWKS fetch and cache with SSRF protection
|
|
3
|
+
Edge-safe JWKS fetch and cache with SSRF protection for PEAC receipt verification.
|
|
4
4
|
|
|
5
5
|
## Installation
|
|
6
6
|
|
|
@@ -8,9 +8,62 @@ Edge-safe JWKS fetch and cache with SSRF protection
|
|
|
8
8
|
pnpm add @peac/jwks-cache
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## What It Does
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
`@peac/jwks-cache` provides a secure JWKS (JSON Web Key Set) resolver with built-in SSRF prevention, in-memory caching with Cache-Control awareness, and Ed25519 key import. It validates URLs against metadata IP ranges before fetching and caches resolved keys to minimize network requests during receipt verification.
|
|
14
|
+
|
|
15
|
+
## How Do I Use It?
|
|
16
|
+
|
|
17
|
+
### Create a JWKS resolver and look up a key
|
|
18
|
+
|
|
19
|
+
```typescript
|
|
20
|
+
import { createResolver, resolveKey } from '@peac/jwks-cache';
|
|
21
|
+
|
|
22
|
+
const resolver = createResolver({
|
|
23
|
+
cacheTtlMs: 300_000, // 5 minutes
|
|
24
|
+
});
|
|
25
|
+
|
|
26
|
+
const key = await resolveKey(resolver, {
|
|
27
|
+
jwksUri: 'https://issuer.example.com/.well-known/jwks.json',
|
|
28
|
+
kid: 'key-2026-03',
|
|
29
|
+
});
|
|
30
|
+
|
|
31
|
+
console.log(key.algorithm); // 'Ed25519'
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### Validate a URL for SSRF safety
|
|
35
|
+
|
|
36
|
+
```typescript
|
|
37
|
+
import { validateUrl, isMetadataIp } from '@peac/jwks-cache';
|
|
38
|
+
|
|
39
|
+
validateUrl('https://issuer.example.com/.well-known/jwks.json'); // passes
|
|
40
|
+
validateUrl('http://169.254.169.254/latest/meta-data'); // throws: metadata IP
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### Use the in-memory cache directly
|
|
44
|
+
|
|
45
|
+
```typescript
|
|
46
|
+
import { InMemoryCache, buildJwksCacheKey } from '@peac/jwks-cache';
|
|
47
|
+
|
|
48
|
+
const cache = new InMemoryCache({ maxEntries: 100 });
|
|
49
|
+
|
|
50
|
+
const cacheKey = buildJwksCacheKey('https://issuer.example.com/.well-known/jwks.json', 'key-1');
|
|
51
|
+
await cache.set(cacheKey, { jwk, expiresAt: Date.now() + 300_000 });
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Integrates With
|
|
55
|
+
|
|
56
|
+
- `@peac/http-signatures`: Key resolution for RFC 9421 signature verification
|
|
57
|
+
- `@peac/protocol` (Layer 3): Receipt verification with remote key resolution
|
|
58
|
+
- `@peac/server` (Layer 5): Verification server JWKS fetching with circuit breaker
|
|
59
|
+
|
|
60
|
+
## For Agent Developers
|
|
61
|
+
|
|
62
|
+
If you are building an AI agent or MCP server that needs evidence receipts:
|
|
63
|
+
|
|
64
|
+
- Start with [`@peac/mcp-server`](https://www.npmjs.com/package/@peac/mcp-server) for a ready-to-use MCP tool server
|
|
65
|
+
- Use `@peac/protocol` for programmatic receipt issuance and verification
|
|
66
|
+
- See the [llms.txt](https://github.com/peacprotocol/peac/blob/main/llms.txt) for a concise overview
|
|
14
67
|
|
|
15
68
|
## License
|
|
16
69
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@peac/jwks-cache",
|
|
3
|
-
"version": "0.12.
|
|
3
|
+
"version": "0.12.6",
|
|
4
4
|
"description": "Edge-safe JWKS fetch and cache with SSRF protection",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.cjs",
|
|
@@ -18,19 +18,23 @@
|
|
|
18
18
|
"dist"
|
|
19
19
|
],
|
|
20
20
|
"keywords": [
|
|
21
|
+
"peac",
|
|
22
|
+
"peacprotocol",
|
|
23
|
+
"interaction-records",
|
|
24
|
+
"signed-records",
|
|
25
|
+
"receipts",
|
|
26
|
+
"originary",
|
|
21
27
|
"jwks",
|
|
28
|
+
"key-resolution",
|
|
22
29
|
"cache",
|
|
23
|
-
"
|
|
24
|
-
"ssrf",
|
|
25
|
-
"edge",
|
|
26
|
-
"peac"
|
|
30
|
+
"ssrf-safe"
|
|
27
31
|
],
|
|
28
32
|
"author": "PEAC Protocol Contributors",
|
|
29
33
|
"license": "Apache-2.0",
|
|
30
34
|
"bugs": {
|
|
31
35
|
"url": "https://github.com/peacprotocol/peac/issues"
|
|
32
36
|
},
|
|
33
|
-
"homepage": "https://
|
|
37
|
+
"homepage": "https://github.com/peacprotocol/peac#readme",
|
|
34
38
|
"repository": {
|
|
35
39
|
"type": "git",
|
|
36
40
|
"url": "git+https://github.com/peacprotocol/peac.git",
|
|
@@ -40,7 +44,7 @@
|
|
|
40
44
|
"access": "public"
|
|
41
45
|
},
|
|
42
46
|
"dependencies": {
|
|
43
|
-
"@peac/http-signatures": "0.12.
|
|
47
|
+
"@peac/http-signatures": "0.12.6"
|
|
44
48
|
},
|
|
45
49
|
"devDependencies": {
|
|
46
50
|
"typescript": "^5.3.0",
|