safe-formdata 0.1.3 → 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 +12 -3
- 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)
|
|
@@ -29,6 +30,7 @@ It enforces strict rules on keys and forbids structural inference by design.
|
|
|
29
30
|
- [Result](#result)
|
|
30
31
|
- [Issues](#issues)
|
|
31
32
|
- [Versioning](#versioning)
|
|
33
|
+
- [Contributing](#contributing)
|
|
32
34
|
- [License](#license)
|
|
33
35
|
|
|
34
36
|
---
|
|
@@ -36,7 +38,7 @@ It enforces strict rules on keys and forbids structural inference by design.
|
|
|
36
38
|
## Overview
|
|
37
39
|
|
|
38
40
|
FormData is untyped and unstructured by nature.
|
|
39
|
-
|
|
41
|
+
Parsers often attempt to infer structure or semantics from key naming conventions.
|
|
40
42
|
|
|
41
43
|
safe-formdata intentionally does not.
|
|
42
44
|
|
|
@@ -83,7 +85,7 @@ Security decisions and issue triage are based on the definitions in SECURITY.md.
|
|
|
83
85
|
|
|
84
86
|
## Design decisions (Why not?)
|
|
85
87
|
|
|
86
|
-
safe-formdata intentionally omits
|
|
88
|
+
safe-formdata intentionally omits the following common features.
|
|
87
89
|
|
|
88
90
|
### Why no structural inference?
|
|
89
91
|
|
|
@@ -195,7 +197,7 @@ if (result.data !== null) {
|
|
|
195
197
|
}
|
|
196
198
|
```
|
|
197
199
|
|
|
198
|
-
|
|
200
|
+
### Key points
|
|
199
201
|
|
|
200
202
|
- All values are `string | File` - no automatic type conversion
|
|
201
203
|
- Use `data !== null` to check for success and narrow the type
|
|
@@ -252,6 +254,13 @@ export interface ParseIssue {
|
|
|
252
254
|
v0.x focuses exclusively on establishing and clarifying the FormData boundary.
|
|
253
255
|
No inference or convenience features will be added within v0.x.
|
|
254
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
|
+
|
|
255
264
|
## License
|
|
256
265
|
|
|
257
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
|
}
|