safe-formdata 0.1.3 → 0.2.0

package/README.md

@@ -2,6 +2,7 @@
 
 **The strict trust boundary for FormData.**
 
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/roottool/safe-formdata)
 [![npm version](https://img.shields.io/npm/v/safe-formdata)](https://www.npmjs.com/package/safe-formdata)
 [![CI](https://github.com/roottool/safe-formdata/actions/workflows/ci.yml/badge.svg)](https://github.com/roottool/safe-formdata/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/roottool/safe-formdata/graph/badge.svg)](https://codecov.io/gh/roottool/safe-formdata)
@@ -29,6 +30,7 @@ It enforces strict rules on keys and forbids structural inference by design.
     - [Result](#result)
     - [Issues](#issues)
   - [Versioning](#versioning)
+  - [Contributing](#contributing)
   - [License](#license)
 
 ---
@@ -36,7 +38,7 @@ It enforces strict rules on keys and forbids structural inference by design.
 ## Overview
 
 FormData is untyped and unstructured by nature.
-Many parsers attempt to infer structure or semantics from key naming conventions.
+Parsers often attempt to infer structure or semantics from key naming conventions.
 
 safe-formdata intentionally does not.
 
@@ -83,7 +85,7 @@ Security decisions and issue triage are based on the definitions in SECURITY.md.
 
 ## Design decisions (Why not?)
 
-safe-formdata intentionally omits several common features.
+safe-formdata intentionally omits the following common features.
 
 ### Why no structural inference?
 
@@ -195,7 +197,7 @@ if (result.data !== null) {
 }
 ```
 
-**Key points**:
+### Key points
 
 - All values are `string | File` - no automatic type conversion
 - Use `data !== null` to check for success and narrow the type
@@ -222,27 +224,25 @@ const { data, issues } = parse(formData);
 ### Result
 
 ```ts
-export interface ParseResult {
-  data: Record<string, string | File> | null;
-  issues: ParseIssue[];
-}
+export type ParseResult =
+  | { data: Record<string, string | File>; issues: [] }
+  | { data: null; issues: [ParseIssue, ...ParseIssue[]] };
 ```
 
 - `data` is non-null only when no boundary violations are detected
 - `data` is always a flat object; no structural inference is performed
-- `issues` must always be checked by the caller
+- Use `data !== null` to narrow the type; `issues` is `[]` on success and non-empty on failure
 
 ### Issues
 
 ```ts
 export interface ParseIssue {
   code: "invalid_key" | "forbidden_key" | "duplicate_key";
-  path: string[];
-  key?: unknown;
+  key: string;
 }
 ```
 
-- `path` is always empty and exists only for compatibility
+- `key` is the original FormData key that caused the issue
 - Issues are informational and are never thrown
 
 ---
@@ -252,6 +252,13 @@ export interface ParseIssue {
 v0.x focuses exclusively on establishing and clarifying the FormData boundary.
 No inference or convenience features will be added within v0.x.
 
+## Contributing
+
+Contributions are welcome! Please see:
+
+- [CONTRIBUTING.md](CONTRIBUTING.md) - Contributor guide
+- [docs/PUBLISHING.md](docs/PUBLISHING.md) - Publishing guide (for maintainers)
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -2,8 +2,7 @@ type IssueCode = "invalid_key" | "forbidden_key" | "duplicate_key";
 
 interface ParseIssue {
     code: IssueCode;
-    path: readonly [];
-    key?: unknown;
+    key: string;
 }
 
 type ParseResult = {
@@ -11,9 +10,16 @@ type ParseResult = {
     issues: [];
 } | {
     data: null;
-    issues: ParseIssue[];
+    issues: [ParseIssue, ...ParseIssue[]];
 };
 
 declare function parse(formData: FormData): ParseResult;
 
-export { type IssueCode, type ParseIssue, type ParseResult, parse };
+type SuccessResult = Extract<ParseResult, {
+    data: Record<string, string | File>;
+}>;
+type FailureResult = Extract<ParseResult, {
+    data: null;
+}>;
+
+export { type FailureResult, type IssueCode, type ParseIssue, type ParseResult, type SuccessResult, parse };

package/dist/index.js

@@ -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
+function e(e,t){return{code:e,key: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",u)):r.has(u)?s.push(e("duplicate_key",u)):(r.add(u),o[u]=a):s.push(e("invalid_key",u));const[u,...a]=s;return void 0!==u?{data:null,issues:[u,...a]}:{data:o,issues:[]}}export{n as parse};//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -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:\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":[]}
+{"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 * Creates a ParseIssue with the specified code and key.\n *\n * This is an internal utility function for generating structured issue reports\n * during FormData parsing.\n *\n * @param code - The type of issue (invalid_key, forbidden_key, or duplicate_key)\n * @param key - The FormData key that caused the issue\n * @returns A ParseIssue object ready to be added to the issues array\n *\n * @internal\n */\nexport function createIssue(code: IssueCode, key: string): ParseIssue {\n\treturn { code, key };\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 { ParseIssue } from \"#types/ParseIssue\";\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 !== null) {\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: Record<string, string | File> = Object.create(null);\n\tconst issues: ParseIssue[] = [];\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\t// Destructure to let TypeScript infer [ParseIssue, ...ParseIssue[]] without a type assertion\n\tconst [firstIssue, ...restIssues] = issues;\n\treturn firstIssue !== undefined\n\t\t? {\n\t\t\t\tdata: null,\n\t\t\t\tissues: [firstIssue, ...restIssues],\n\t\t\t}\n\t\t: {\n\t\t\t\tdata,\n\t\t\t\tissues: [],\n\t\t\t};\n}\n"],"mappings":";AAeO,SAAS,YAAY,MAAiB,KAAyB;AACrE,SAAO,EAAE,MAAM,IAAI;AACpB;;;ACDO,IAAM,iBAAiB,oBAAI,IAAY;AAAA,EAC7C;AAAA,EACA;AAAA,EACA;AACD,CAAsC;;;ACY/B,SAAS,MAAM,UAAiC;AACtD,QAAM,OAAsC,uBAAO,OAAO,IAAI;AAC9D,QAAM,SAAuB,CAAC;AAC9B,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,GAAG,CAAC;AAC3C;AAAA,IACD;AAEA,QAAI,eAAe,IAAI,GAAG,GAAG;AAC5B,aAAO,KAAK,YAAY,iBAAiB,GAAG,CAAC;AAC7C;AAAA,IACD;AAEA,QAAI,SAAS,IAAI,GAAG,GAAG;AACtB,aAAO,KAAK,YAAY,iBAAiB,GAAG,CAAC;AAC7C;AAAA,IACD;AAEA,aAAS,IAAI,GAAG;AAChB,SAAK,GAAG,IAAI;AAAA,EACb;AAGA,QAAM,CAAC,YAAY,GAAG,UAAU,IAAI;AACpC,SAAO,eAAe,SACnB;AAAA,IACA,MAAM;AAAA,IACN,QAAQ,CAAC,YAAY,GAAG,UAAU;AAAA,EACnC,IACC;AAAA,IACA;AAAA,IACA,QAAQ,CAAC;AAAA,EACV;AACH;","names":[]}

package/package.json

@@ -1,16 +1,31 @@
 {
 	"name": "safe-formdata",
-	"version": "0.1.3",
+	"version": "0.2.0",
 	"description": "Boundary-focused FormData parser with strict security guarantees",
+	"keywords": [
+		"boundary",
+		"formdata",
+		"parser",
+		"prototype-pollution",
+		"security"
+	],
+	"homepage": "https://github.com/roottool/safe-formdata#readme",
+	"bugs": {
+		"url": "https://github.com/roottool/safe-formdata/issues"
+	},
+	"license": "MIT",
 	"author": "roottool",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/roottool/safe-formdata.git"
 	},
-	"bugs": {
-		"url": "https://github.com/roottool/safe-formdata/issues"
-	},
-	"homepage": "https://github.com/roottool/safe-formdata#readme",
+	"files": [
+		"dist"
+	],
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
 	"imports": {
 		"#*": {
 			"types": "./src/*.ts",
@@ -19,10 +34,6 @@
 		},
 		"#safe-formdata": "./src/index.ts"
 	},
-	"type": "module",
-	"main": "./dist/index.js",
-	"module": "./dist/index.js",
-	"types": "./dist/index.d.ts",
 	"exports": {
 		".": {
 			"types": "./dist/index.d.ts",
@@ -30,56 +41,38 @@
 			"default": "./dist/index.js"
 		}
 	},
-	"files": [
-		"dist"
-	],
 	"scripts": {
 		"dev": "tsup --watch",
 		"lint": "oxlint . --deny-warnings",
 		"lint:fix": "oxlint . --fix-suggestions",
-		"format:biome": "biome check --write --assist-enabled true",
-		"format:prettier": "prettier --cache --write \"**/*.{md,yml,yaml}\"",
-		"format": "npm-run-all2 format:biome format:prettier",
+		"format": "oxfmt",
 		"fix": "npm-run-all2 lint:fix format",
-		"check:biome": "biome check . --assist-enabled true",
-		"check:prettier": "prettier --cache --check \"**/*.{md,yml,yaml}\"",
-		"check:format": "npm-run-all2 check:biome check:prettier",
+		"check:format": "oxfmt --check",
 		"check:source": "npm-run-all2 lint check:format",
 		"check": "bun run check:source",
 		"check:type:source": "tsc --noEmit",
 		"check:type:example": "tsc --project tsconfig.examples.json --noEmit",
 		"check:type": "npm-run-all2 check:type:source check:type:example",
-		"check:prettier:ci": "prettier --check \"**/*.{md,yml,yaml}\"",
-		"check:format:ci": "npm-run-all2 check:biome check:prettier:ci",
-		"check:source:ci": "npm-run-all2 lint check:format:ci",
+		"check:source:ci": "npm-run-all2 lint check:format",
 		"test": "vitest run",
 		"test:watch": "vitest",
 		"test:coverage": "vitest run --coverage",
 		"build": "tsup",
 		"check:package": "publint && attw --pack . --ignore-rules cjs-resolves-to-esm",
-		"prepublishOnly": "bun run check:type:source && bun run test:coverage && bun run build && bun run check:package"
+		"prepare:publish": "npm-run-all2 check:type:source test:coverage build check:package"
 	},
 	"devDependencies": {
 		"@arethetypeswrong/cli": "0.18.2",
-		"@biomejs/biome": "2.3.10",
 		"@types/node": "25.0.3",
 		"@vitest/coverage-v8": "4.0.16",
 		"happy-dom": "20.0.11",
 		"npm-run-all2": "8.0.4",
+		"oxfmt": "0.35.0",
 		"oxlint": "1.34.0",
-		"prettier": "3.7.4",
 		"publint": "0.3.16",
 		"terser": "5.44.1",
 		"tsup": "8.5.1",
 		"typescript": "5.9.3",
 		"vitest": "4.0.16"
-	},
-	"license": "MIT",
-	"keywords": [
-		"formdata",
-		"parser",
-		"security",
-		"boundary",
-		"prototype-pollution"
-	]
+	}
 }