safe-formdata 0.1.0 → 0.1.1
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 +39 -12
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/package.json +12 -9
package/README.md
CHANGED
|
@@ -2,6 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
**The strict trust boundary for FormData.**
|
|
4
4
|
|
|
5
|
+
[](https://www.npmjs.com/package/safe-formdata)
|
|
6
|
+
[](https://github.com/roottool/safe-formdata/actions/workflows/ci.yml)
|
|
7
|
+
[](https://codecov.io/gh/roottool/safe-formdata)
|
|
8
|
+
|
|
5
9
|
safe-formdata is a **security-focused** parser that establishes a predictable boundary between untrusted input and application logic.
|
|
6
10
|
It enforces strict rules on keys and forbids structural inference by design.
|
|
7
11
|
|
|
@@ -34,22 +38,24 @@ all structural issues explicitly, without inferring structure, intent, or meanin
|
|
|
34
38
|
|
|
35
39
|
## Security scope
|
|
36
40
|
|
|
37
|
-
|
|
41
|
+
safe-formdata defines a **strict trust boundary** between untrusted FormData input
|
|
42
|
+
and application logic.
|
|
43
|
+
|
|
44
|
+
Within this boundary, safe-formdata focuses exclusively on:
|
|
38
45
|
|
|
39
|
-
-
|
|
40
|
-
-
|
|
41
|
-
-
|
|
42
|
-
-
|
|
46
|
+
- Preventing **prototype pollution**
|
|
47
|
+
- Detecting **forbidden, invalid, and duplicate keys**
|
|
48
|
+
- Ensuring **explicit issue reporting** with no silent correction
|
|
49
|
+
- Providing **predictable, non-inferential parsing behavior**
|
|
43
50
|
|
|
44
|
-
|
|
51
|
+
Anything beyond this boundary — including value validation, schema enforcement,
|
|
52
|
+
framework conventions, authentication, or denial-of-service protection —
|
|
53
|
+
is **out of scope** and must be handled by the application.
|
|
45
54
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
- Denial-of-service protection
|
|
49
|
-
- Framework-specific behavior
|
|
55
|
+
📘 **Authoritative security guarantees, assumptions, and reporting policy:**
|
|
56
|
+
See [SECURITY.md](./SECURITY.md)
|
|
50
57
|
|
|
51
|
-
|
|
52
|
-
to preserve the integrity of the FormData boundary.
|
|
58
|
+
Security decisions and issue triage are based on the definitions in SECURITY.md.
|
|
53
59
|
|
|
54
60
|
---
|
|
55
61
|
|
|
@@ -124,6 +130,27 @@ The output type is intentionally flat:
|
|
|
124
130
|
Record<string, string | File>;
|
|
125
131
|
```
|
|
126
132
|
|
|
133
|
+
### Why no multiple values or repeated keys?
|
|
134
|
+
|
|
135
|
+
HTML FormData allows the same key to appear multiple times
|
|
136
|
+
(e.g. multi-select inputs or repeated checkboxes).
|
|
137
|
+
|
|
138
|
+
safe-formdata intentionally treats repeated keys as a boundary violation
|
|
139
|
+
and reports them as `duplicate_key` issues.
|
|
140
|
+
|
|
141
|
+
While multiple values may be semantically valid in application logic,
|
|
142
|
+
their interpretation necessarily implies structure
|
|
143
|
+
(e.g. arrays, sets, ordering, or merging rules).
|
|
144
|
+
|
|
145
|
+
Defining or inferring such structure is outside the scope of safe-formdata.
|
|
146
|
+
|
|
147
|
+
safe-formdata establishes a strict, non-inferential boundary:
|
|
148
|
+
each key must map to exactly one value (`string` or `File`),
|
|
149
|
+
or the input is rejected.
|
|
150
|
+
|
|
151
|
+
If multiple values are required, they must be normalized
|
|
152
|
+
before or outside this boundary.
|
|
153
|
+
|
|
127
154
|
### Why no throwing or `parseOrThrow`?
|
|
128
155
|
|
|
129
156
|
FormData is external input.
|
package/dist/index.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
function e(e,t={}){return{code:e,path:[],...t}}var t=new Set(["__proto__","prototype","constructor"]);function n(n){const o=Object.create(null),s=[],r=new Set;for(const[u,a]of n.entries())"string"==typeof u&&0!==u.length?t.has(u)?s.push(e("forbidden_key",{key:u})):r.has(u)?s.push(e("duplicate_key",{key:u})):(r.add(u),o[u]=a):s.push(e("invalid_key",{key:u}));return s.length>0?{data:null,issues:s}:{data:o,issues:[]}}export{n as parse};//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/issues/
|
|
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:\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,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "safe-formdata",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Boundary-focused FormData parser with strict security guarantees",
|
|
5
5
|
"author": "roottool",
|
|
6
6
|
"repository": {
|
|
@@ -16,7 +16,8 @@
|
|
|
16
16
|
"types": "./src/*.ts",
|
|
17
17
|
"import": "./src/*.ts",
|
|
18
18
|
"default": "./src/*.ts"
|
|
19
|
-
}
|
|
19
|
+
},
|
|
20
|
+
"#safe-formdata": "./src/index.ts"
|
|
20
21
|
},
|
|
21
22
|
"type": "module",
|
|
22
23
|
"main": "./dist/index.js",
|
|
@@ -36,25 +37,27 @@
|
|
|
36
37
|
"dev": "tsup --watch",
|
|
37
38
|
"lint": "oxlint . --deny-warnings",
|
|
38
39
|
"lint:fix": "oxlint . --fix-suggestions",
|
|
39
|
-
"
|
|
40
|
-
"format:biome": "biome format --write",
|
|
40
|
+
"format:biome": "biome check --write --assist-enabled true",
|
|
41
41
|
"format:prettier": "prettier --cache --write \"**/*.{md,yml,yaml}\"",
|
|
42
42
|
"format": "npm-run-all2 format:biome format:prettier",
|
|
43
43
|
"fix": "npm-run-all2 lint:fix format",
|
|
44
|
-
"check:biome": "biome
|
|
44
|
+
"check:biome": "biome check . --assist-enabled true",
|
|
45
45
|
"check:prettier": "prettier --cache --check \"**/*.{md,yml,yaml}\"",
|
|
46
46
|
"check:format": "npm-run-all2 check:biome check:prettier",
|
|
47
47
|
"check:source": "npm-run-all2 lint check:format",
|
|
48
48
|
"check": "bun run check:source",
|
|
49
|
+
"check:type:source": "tsc --noEmit",
|
|
50
|
+
"check:type:example": "tsc --project tsconfig.examples.json --noEmit",
|
|
51
|
+
"check:type": "npm-run-all2 check:type:source check:type:example",
|
|
52
|
+
"check:prettier:ci": "prettier --check \"**/*.{md,yml,yaml}\"",
|
|
53
|
+
"check:format:ci": "npm-run-all2 check:biome check:prettier:ci",
|
|
54
|
+
"check:source:ci": "npm-run-all2 lint check:format:ci",
|
|
49
55
|
"test": "vitest run",
|
|
50
56
|
"test:watch": "vitest",
|
|
51
57
|
"test:coverage": "vitest run --coverage",
|
|
52
58
|
"build": "tsup",
|
|
53
59
|
"check:package": "publint && attw --pack . --ignore-rules cjs-resolves-to-esm",
|
|
54
|
-
"prepublishOnly": "bun run check:type && bun run test:coverage && bun run build && bun run check:package"
|
|
55
|
-
},
|
|
56
|
-
"engines": {
|
|
57
|
-
"node": "^20.19.0 || >= 22.12.0"
|
|
60
|
+
"prepublishOnly": "bun run check:type:source && bun run test:coverage && bun run build && bun run check:package"
|
|
58
61
|
},
|
|
59
62
|
"devDependencies": {
|
|
60
63
|
"@arethetypeswrong/cli": "0.18.2",
|