safe-formdata 0.1.2 → 0.1.4
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 +130 -42
- package/dist/index.js.map +1 -1
- package/package.json +26 -33
package/README.md
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
**The strict trust boundary for FormData.**
|
|
4
4
|
|
|
5
|
+
[](https://deepwiki.com/roottool/safe-formdata)
|
|
5
6
|
[](https://www.npmjs.com/package/safe-formdata)
|
|
6
7
|
[](https://github.com/roottool/safe-formdata/actions/workflows/ci.yml)
|
|
7
8
|
[](https://codecov.io/gh/roottool/safe-formdata)
|
|
@@ -9,12 +10,35 @@
|
|
|
9
10
|
safe-formdata is a **security-focused** parser that establishes a predictable boundary between untrusted input and application logic.
|
|
10
11
|
It enforces strict rules on keys and forbids structural inference by design.
|
|
11
12
|
|
|
13
|
+
## Table of Contents
|
|
14
|
+
|
|
15
|
+
- [safe-formdata](#safe-formdata)
|
|
16
|
+
- [Table of Contents](#table-of-contents)
|
|
17
|
+
- [Overview](#overview)
|
|
18
|
+
- [Design principles](#design-principles)
|
|
19
|
+
- [Security scope](#security-scope)
|
|
20
|
+
- [Design decisions (Why not?)](#design-decisions-why-not)
|
|
21
|
+
- [Why no structural inference?](#why-no-structural-inference)
|
|
22
|
+
- [Why no generic type parameters?](#why-no-generic-type-parameters)
|
|
23
|
+
- [Why no multiple values or repeated keys?](#why-no-multiple-values-or-repeated-keys)
|
|
24
|
+
- [Why no throwing or `parseOrThrow`?](#why-no-throwing-or-parseorthrow)
|
|
25
|
+
- [What is safe-formdata not?](#what-is-safe-formdata-not)
|
|
26
|
+
- [Installation](#installation)
|
|
27
|
+
- [Quick Start](#quick-start)
|
|
28
|
+
- [API](#api)
|
|
29
|
+
- [parse(formData): ParseResult](#parseformdata-parseresult)
|
|
30
|
+
- [Result](#result)
|
|
31
|
+
- [Issues](#issues)
|
|
32
|
+
- [Versioning](#versioning)
|
|
33
|
+
- [Contributing](#contributing)
|
|
34
|
+
- [License](#license)
|
|
35
|
+
|
|
12
36
|
---
|
|
13
37
|
|
|
14
38
|
## Overview
|
|
15
39
|
|
|
16
40
|
FormData is untyped and unstructured by nature.
|
|
17
|
-
|
|
41
|
+
Parsers often attempt to infer structure or semantics from key naming conventions.
|
|
18
42
|
|
|
19
43
|
safe-formdata intentionally does not.
|
|
20
44
|
|
|
@@ -59,49 +83,9 @@ Security decisions and issue triage are based on the definitions in SECURITY.md.
|
|
|
59
83
|
|
|
60
84
|
---
|
|
61
85
|
|
|
62
|
-
## API
|
|
63
|
-
|
|
64
|
-
### parse(formData): ParseResult
|
|
65
|
-
|
|
66
|
-
```ts
|
|
67
|
-
import { parse } from "safe-formdata";
|
|
68
|
-
|
|
69
|
-
const { data, issues } = parse(formData);
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
- `data` is `null` if any boundary violations are detected
|
|
73
|
-
- `issues` contains all detected structural issues
|
|
74
|
-
- Partial success is not allowed
|
|
75
|
-
|
|
76
|
-
### Result
|
|
77
|
-
|
|
78
|
-
```ts
|
|
79
|
-
export interface ParseResult {
|
|
80
|
-
data: Record<string, string | File> | null;
|
|
81
|
-
issues: ParseIssue[];
|
|
82
|
-
}
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
- `data` is non-null only when no boundary violations are detected
|
|
86
|
-
- `data` is always a flat object; no structural inference is performed
|
|
87
|
-
- `issues` must always be checked by the caller
|
|
88
|
-
|
|
89
|
-
### Issues
|
|
90
|
-
|
|
91
|
-
```ts
|
|
92
|
-
export interface ParseIssue {
|
|
93
|
-
code: "invalid_key" | "forbidden_key" | "duplicate_key";
|
|
94
|
-
path: string[];
|
|
95
|
-
key?: unknown;
|
|
96
|
-
}
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
- `path` is always empty and exists only for compatibility
|
|
100
|
-
- Issues are informational and are never thrown
|
|
101
|
-
|
|
102
86
|
## Design decisions (Why not?)
|
|
103
87
|
|
|
104
|
-
safe-formdata intentionally omits
|
|
88
|
+
safe-formdata intentionally omits the following common features.
|
|
105
89
|
|
|
106
90
|
### Why no structural inference?
|
|
107
91
|
|
|
@@ -168,11 +152,115 @@ inspect issues and decide what to do.
|
|
|
168
152
|
safe-formdata defines a safe boundary.
|
|
169
153
|
Validation and typing belong beyond it.
|
|
170
154
|
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## Installation
|
|
158
|
+
|
|
159
|
+
Install safe-formdata using your preferred package manager:
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
# npm
|
|
163
|
+
npm install safe-formdata
|
|
164
|
+
|
|
165
|
+
# yarn
|
|
166
|
+
yarn add safe-formdata
|
|
167
|
+
|
|
168
|
+
# pnpm
|
|
169
|
+
pnpm add safe-formdata
|
|
170
|
+
|
|
171
|
+
# bun
|
|
172
|
+
bun add safe-formdata
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
**Requirements**: TypeScript 5.0+ (for discriminated union type narrowing)
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## Quick Start
|
|
180
|
+
|
|
181
|
+
```typescript
|
|
182
|
+
import { parse } from "safe-formdata";
|
|
183
|
+
|
|
184
|
+
const formData = new FormData();
|
|
185
|
+
formData.append("username", "alice");
|
|
186
|
+
formData.append("age", "25");
|
|
187
|
+
|
|
188
|
+
const result = parse(formData);
|
|
189
|
+
|
|
190
|
+
if (result.data !== null) {
|
|
191
|
+
// Success: data is available
|
|
192
|
+
console.log(result.data.username); // 'alice'
|
|
193
|
+
console.log(result.data.age); // '25'
|
|
194
|
+
} else {
|
|
195
|
+
// Failure: validation issues occurred
|
|
196
|
+
console.error(result.issues);
|
|
197
|
+
}
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
### Key points
|
|
201
|
+
|
|
202
|
+
- All values are `string | File` - no automatic type conversion
|
|
203
|
+
- Use `data !== null` to check for success and narrow the type
|
|
204
|
+
- Security boundaries are enforced from the start
|
|
205
|
+
|
|
206
|
+
For complete examples including file uploads and validation patterns, see the [examples/](./examples) directory.
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
## API
|
|
211
|
+
|
|
212
|
+
### parse(formData): ParseResult
|
|
213
|
+
|
|
214
|
+
```ts
|
|
215
|
+
import { parse } from "safe-formdata";
|
|
216
|
+
|
|
217
|
+
const { data, issues } = parse(formData);
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
- `data` is `null` if any boundary violations are detected
|
|
221
|
+
- `issues` contains all detected structural issues
|
|
222
|
+
- Partial success is not allowed
|
|
223
|
+
|
|
224
|
+
### Result
|
|
225
|
+
|
|
226
|
+
```ts
|
|
227
|
+
export interface ParseResult {
|
|
228
|
+
data: Record<string, string | File> | null;
|
|
229
|
+
issues: ParseIssue[];
|
|
230
|
+
}
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
- `data` is non-null only when no boundary violations are detected
|
|
234
|
+
- `data` is always a flat object; no structural inference is performed
|
|
235
|
+
- `issues` must always be checked by the caller
|
|
236
|
+
|
|
237
|
+
### Issues
|
|
238
|
+
|
|
239
|
+
```ts
|
|
240
|
+
export interface ParseIssue {
|
|
241
|
+
code: "invalid_key" | "forbidden_key" | "duplicate_key";
|
|
242
|
+
path: string[];
|
|
243
|
+
key?: unknown;
|
|
244
|
+
}
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
- `path` is always empty and exists only for compatibility
|
|
248
|
+
- Issues are informational and are never thrown
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
171
252
|
## Versioning
|
|
172
253
|
|
|
173
254
|
v0.x focuses exclusively on establishing and clarifying the FormData boundary.
|
|
174
255
|
No inference or convenience features will be added within v0.x.
|
|
175
256
|
|
|
257
|
+
## Contributing
|
|
258
|
+
|
|
259
|
+
Contributions are welcome! Please see:
|
|
260
|
+
|
|
261
|
+
- [CONTRIBUTING.md](CONTRIBUTING.md) - Contributor guide
|
|
262
|
+
- [docs/PUBLISHING.md](docs/PUBLISHING.md) - Publishing guide (for maintainers)
|
|
263
|
+
|
|
176
264
|
## License
|
|
177
265
|
|
|
178
266
|
MIT
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/issues/createIssue.ts","../src/issues/forbiddenKeys.ts","../src/parse.ts"],"sourcesContent":["import type { IssueCode } from \"#types/IssueCode\";\nimport type { ParseIssue } from \"#types/ParseIssue\";\n\n/**\n * Payload for creating a ParseIssue.\n *\n * @property {unknown} key - The problematic key that triggered the issue (for debugging)\n */\ninterface IssuePayload {\n\tkey?: unknown;\n}\n\n/**\n * Creates a ParseIssue with the specified code and optional payload.\n *\n * This is an internal utility function for generating structured issue reports\n * during FormData parsing. All issues have an empty `path` array, as this parser\n * does not infer structural relationships.\n *\n * @param code - The type of issue (invalid_key, forbidden_key, or duplicate_key)\n * @param payload - Optional payload containing the problematic key\n * @returns A ParseIssue object ready to be added to the issues array\n *\n * @internal\n */\nexport function createIssue(code: IssueCode, payload: IssuePayload = {}): ParseIssue {\n\treturn {\n\t\tcode,\n\t\tpath: [],\n\t\t...payload,\n\t};\n}\n","/**\n * Keys explicitly forbidden to prevent prototype pollution attacks.\n *\n * These keys are reserved properties on `Object.prototype` and must never\n * be allowed in parsed FormData, regardless of their values or context.\n *\n * The forbidden keys are
|
|
1
|
+
{"version":3,"sources":["../src/issues/createIssue.ts","../src/issues/forbiddenKeys.ts","../src/parse.ts"],"sourcesContent":["import type { IssueCode } from \"#types/IssueCode\";\nimport type { ParseIssue } from \"#types/ParseIssue\";\n\n/**\n * Payload for creating a ParseIssue.\n *\n * @property {unknown} key - The problematic key that triggered the issue (for debugging)\n */\ninterface IssuePayload {\n\tkey?: unknown;\n}\n\n/**\n * Creates a ParseIssue with the specified code and optional payload.\n *\n * This is an internal utility function for generating structured issue reports\n * during FormData parsing. All issues have an empty `path` array, as this parser\n * does not infer structural relationships.\n *\n * @param code - The type of issue (invalid_key, forbidden_key, or duplicate_key)\n * @param payload - Optional payload containing the problematic key\n * @returns A ParseIssue object ready to be added to the issues array\n *\n * @internal\n */\nexport function createIssue(code: IssueCode, payload: IssuePayload = {}): ParseIssue {\n\treturn {\n\t\tcode,\n\t\tpath: [],\n\t\t...payload,\n\t};\n}\n","/**\n * Keys explicitly forbidden to prevent prototype pollution attacks.\n *\n * These keys are reserved properties on `Object.prototype` and must never\n * be allowed in parsed FormData, regardless of their values or context.\n *\n * The forbidden keys are the following.\n * - `__proto__`: Legacy prototype accessor\n * - `prototype`: Function prototype property\n * - `constructor`: Object constructor reference\n *\n * Any FormData entry containing these keys will trigger a `forbidden_key` issue,\n * causing the parse operation to fail with `data: null`.\n *\n * @see {@link https://github.com/roottool/safe-formdata/blob/main/AGENTS.md#prototype-safety AGENTS.md > Security rules > Prototype safety}\n */\nexport const FORBIDDEN_KEYS = new Set<string>([\n\t\"__proto__\",\n\t\"prototype\",\n\t\"constructor\",\n] as const satisfies readonly string[]);\n","import { createIssue } from \"#issues/createIssue\";\nimport { FORBIDDEN_KEYS } from \"#issues/forbiddenKeys\";\nimport type { ParseResult } from \"#types/ParseResult\";\n\n/**\n * Parses FormData into a flat JavaScript object with strict boundary enforcement.\n *\n * This function establishes a security-focused boundary between untrusted FormData input\n * and application logic by:\n * - Detecting duplicate, forbidden, and invalid keys\n * - Treating keys as opaque strings (no structural inference)\n * - Returning null data if any issues are detected (no partial success)\n *\n * @param formData - The FormData instance to parse\n * @returns ParseResult containing either parsed data or issues (never both)\n *\n * @example\n * ```ts\n * const fd = new FormData()\n * fd.append('name', 'alice')\n * const result = parse(fd)\n *\n * if (result.data) {\n * // Success: result.data is { name: 'alice' }\n * } else {\n * // Failure: result.issues contains detected problems\n * }\n * ```\n *\n * @see {@link https://github.com/roottool/safe-formdata/blob/main/AGENTS.md AGENTS.md} for design rules\n */\nexport function parse(formData: FormData): ParseResult {\n\tconst data = Object.create(null) as Record<string, string | File>;\n\tconst issues = [];\n\tconst seenKeys = new Set<string>();\n\n\tfor (const [key, value] of formData.entries()) {\n\t\tif (typeof key !== \"string\" || key.length === 0) {\n\t\t\tissues.push(createIssue(\"invalid_key\", { key }));\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (FORBIDDEN_KEYS.has(key)) {\n\t\t\tissues.push(createIssue(\"forbidden_key\", { key }));\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (seenKeys.has(key)) {\n\t\t\tissues.push(createIssue(\"duplicate_key\", { key }));\n\t\t\tcontinue;\n\t\t}\n\n\t\tseenKeys.add(key);\n\t\tdata[key] = value;\n\t}\n\n\treturn issues.length > 0\n\t\t? {\n\t\t\t\tdata: null,\n\t\t\t\tissues,\n\t\t\t}\n\t\t: {\n\t\t\t\tdata,\n\t\t\t\tissues: [],\n\t\t\t};\n}\n"],"mappings":";AAyBO,SAAS,YAAY,MAAiB,UAAwB,CAAC,GAAe;AACpF,SAAO;AAAA,IACN;AAAA,IACA,MAAM,CAAC;AAAA,IACP,GAAG;AAAA,EACJ;AACD;;;ACfO,IAAM,iBAAiB,oBAAI,IAAY;AAAA,EAC7C;AAAA,EACA;AAAA,EACA;AACD,CAAsC;;;ACW/B,SAAS,MAAM,UAAiC;AACtD,QAAM,OAAO,uBAAO,OAAO,IAAI;AAC/B,QAAM,SAAS,CAAC;AAChB,QAAM,WAAW,oBAAI,IAAY;AAEjC,aAAW,CAAC,KAAK,KAAK,KAAK,SAAS,QAAQ,GAAG;AAC9C,QAAI,OAAO,QAAQ,YAAY,IAAI,WAAW,GAAG;AAChD,aAAO,KAAK,YAAY,eAAe,EAAE,IAAI,CAAC,CAAC;AAC/C;AAAA,IACD;AAEA,QAAI,eAAe,IAAI,GAAG,GAAG;AAC5B,aAAO,KAAK,YAAY,iBAAiB,EAAE,IAAI,CAAC,CAAC;AACjD;AAAA,IACD;AAEA,QAAI,SAAS,IAAI,GAAG,GAAG;AACtB,aAAO,KAAK,YAAY,iBAAiB,EAAE,IAAI,CAAC,CAAC;AACjD;AAAA,IACD;AAEA,aAAS,IAAI,GAAG;AAChB,SAAK,GAAG,IAAI;AAAA,EACb;AAEA,SAAO,OAAO,SAAS,IACpB;AAAA,IACA,MAAM;AAAA,IACN;AAAA,EACD,IACC;AAAA,IACA;AAAA,IACA,QAAQ,CAAC;AAAA,EACV;AACH;","names":[]}
|
package/package.json
CHANGED
|
@@ -1,16 +1,31 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "safe-formdata",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.4",
|
|
4
4
|
"description": "Boundary-focused FormData parser with strict security guarantees",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"boundary",
|
|
7
|
+
"formdata",
|
|
8
|
+
"parser",
|
|
9
|
+
"prototype-pollution",
|
|
10
|
+
"security"
|
|
11
|
+
],
|
|
12
|
+
"homepage": "https://github.com/roottool/safe-formdata#readme",
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/roottool/safe-formdata/issues"
|
|
15
|
+
},
|
|
16
|
+
"license": "MIT",
|
|
5
17
|
"author": "roottool",
|
|
6
18
|
"repository": {
|
|
7
19
|
"type": "git",
|
|
8
20
|
"url": "git+https://github.com/roottool/safe-formdata.git"
|
|
9
21
|
},
|
|
10
|
-
"
|
|
11
|
-
"
|
|
12
|
-
|
|
13
|
-
"
|
|
22
|
+
"files": [
|
|
23
|
+
"dist"
|
|
24
|
+
],
|
|
25
|
+
"type": "module",
|
|
26
|
+
"main": "./dist/index.js",
|
|
27
|
+
"module": "./dist/index.js",
|
|
28
|
+
"types": "./dist/index.d.ts",
|
|
14
29
|
"imports": {
|
|
15
30
|
"#*": {
|
|
16
31
|
"types": "./src/*.ts",
|
|
@@ -19,10 +34,6 @@
|
|
|
19
34
|
},
|
|
20
35
|
"#safe-formdata": "./src/index.ts"
|
|
21
36
|
},
|
|
22
|
-
"type": "module",
|
|
23
|
-
"main": "./dist/index.js",
|
|
24
|
-
"module": "./dist/index.js",
|
|
25
|
-
"types": "./dist/index.d.ts",
|
|
26
37
|
"exports": {
|
|
27
38
|
".": {
|
|
28
39
|
"types": "./dist/index.d.ts",
|
|
@@ -30,56 +41,38 @@
|
|
|
30
41
|
"default": "./dist/index.js"
|
|
31
42
|
}
|
|
32
43
|
},
|
|
33
|
-
"files": [
|
|
34
|
-
"dist"
|
|
35
|
-
],
|
|
36
44
|
"scripts": {
|
|
37
45
|
"dev": "tsup --watch",
|
|
38
46
|
"lint": "oxlint . --deny-warnings",
|
|
39
47
|
"lint:fix": "oxlint . --fix-suggestions",
|
|
40
|
-
"format
|
|
41
|
-
"format:prettier": "prettier --cache --write \"**/*.{md,yml,yaml}\"",
|
|
42
|
-
"format": "npm-run-all2 format:biome format:prettier",
|
|
48
|
+
"format": "oxfmt",
|
|
43
49
|
"fix": "npm-run-all2 lint:fix format",
|
|
44
|
-
"check:
|
|
45
|
-
"check:prettier": "prettier --cache --check \"**/*.{md,yml,yaml}\"",
|
|
46
|
-
"check:format": "npm-run-all2 check:biome check:prettier",
|
|
50
|
+
"check:format": "oxfmt --check",
|
|
47
51
|
"check:source": "npm-run-all2 lint check:format",
|
|
48
52
|
"check": "bun run check:source",
|
|
49
53
|
"check:type:source": "tsc --noEmit",
|
|
50
54
|
"check:type:example": "tsc --project tsconfig.examples.json --noEmit",
|
|
51
55
|
"check:type": "npm-run-all2 check:type:source check:type:example",
|
|
52
|
-
"check:
|
|
53
|
-
"check:format:ci": "npm-run-all2 check:biome check:prettier:ci",
|
|
54
|
-
"check:source:ci": "npm-run-all2 lint check:format:ci",
|
|
56
|
+
"check:source:ci": "npm-run-all2 lint check:format",
|
|
55
57
|
"test": "vitest run",
|
|
56
58
|
"test:watch": "vitest",
|
|
57
59
|
"test:coverage": "vitest run --coverage",
|
|
58
60
|
"build": "tsup",
|
|
59
61
|
"check:package": "publint && attw --pack . --ignore-rules cjs-resolves-to-esm",
|
|
60
|
-
"
|
|
62
|
+
"prepare:publish": "npm-run-all2 check:type:source test:coverage build check:package"
|
|
61
63
|
},
|
|
62
64
|
"devDependencies": {
|
|
63
65
|
"@arethetypeswrong/cli": "0.18.2",
|
|
64
|
-
"@biomejs/biome": "2.3.10",
|
|
65
66
|
"@types/node": "25.0.3",
|
|
66
67
|
"@vitest/coverage-v8": "4.0.16",
|
|
67
68
|
"happy-dom": "20.0.11",
|
|
68
69
|
"npm-run-all2": "8.0.4",
|
|
70
|
+
"oxfmt": "0.35.0",
|
|
69
71
|
"oxlint": "1.34.0",
|
|
70
|
-
"prettier": "3.7.4",
|
|
71
72
|
"publint": "0.3.16",
|
|
72
73
|
"terser": "5.44.1",
|
|
73
74
|
"tsup": "8.5.1",
|
|
74
75
|
"typescript": "5.9.3",
|
|
75
76
|
"vitest": "4.0.16"
|
|
76
|
-
}
|
|
77
|
-
"license": "MIT",
|
|
78
|
-
"keywords": [
|
|
79
|
-
"formdata",
|
|
80
|
-
"parser",
|
|
81
|
-
"security",
|
|
82
|
-
"boundary",
|
|
83
|
-
"prototype-pollution"
|
|
84
|
-
]
|
|
77
|
+
}
|
|
85
78
|
}
|