safe-formdata 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 roottool
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,151 @@
 # safe-formdata
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+**The strict trust boundary for FormData.**
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+safe-formdata is a **security-focused** parser that establishes a predictable boundary between untrusted input and application logic.
+It enforces strict rules on keys and forbids structural inference by design.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+---
+
+## Overview
+
+FormData is untyped and unstructured by nature.
+Many parsers attempt to infer structure or semantics from key naming conventions.
 
-## Purpose
+safe-formdata intentionally does not.
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `safe-formdata`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+It performs only minimal, security-focused parsing and reports
+all structural issues explicitly, without inferring structure, intent, or meaning.
+
+---
 
-## What is OIDC Trusted Publishing?
+## Design principles
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+- 🧱 **Keys are opaque**  
+  Key names are never interpreted as structure.
+- 🚫 **No silent fixes**  
+  Invalid or conflicting input is reported, not corrected.
+- ⚖️ **Parsing is not validation**  
+  Schema and business logic belong outside the boundary.
+- 🔒️ **Security over convenience**  
+  Unsafe input is surfaced early and explicitly.
 
-## Setup Instructions
+---
 
-To properly configure OIDC trusted publishing for this package:
+## Security scope
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+### In scope
 
-## DO NOT USE THIS PACKAGE
+- Forbidden keys (e.g. prototype pollution)
+- Duplicate keys
+- Structurally invalid keys
+- Explicit reporting of all issues
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+### Out of scope
 
-## More Information
+- Value validation or coercion
+- Authentication or authorization
+- Denial-of-service protection
+- Framework-specific behavior
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+safe-formdata reports issues instead of throwing,
+to preserve the integrity of the FormData boundary.
 
 ---
 
-**Maintained for OIDC setup purposes only**
+## API
+
+### parse(formData): ParseResult
+
+```ts
+import { parse } from "safe-formdata";
+
+const { data, issues } = parse(formData);
+```
+
+- `data` is `null` if any boundary violations are detected
+- `issues` contains all detected structural issues
+- Partial success is not allowed
+
+### Result
+
+```ts
+export interface ParseResult {
+  data: Record<string, string | File> | null;
+  issues: 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
+
+### Issues
+
+```ts
+export interface ParseIssue {
+  code: "invalid_key" | "forbidden_key" | "duplicate_key";
+  path: string[];
+  key?: unknown;
+}
+```
+
+- `path` is always empty and exists only for compatibility
+- Issues are informational and are never thrown
+
+## Design decisions (Why not?)
+
+safe-formdata intentionally omits several common features.
+
+### Why no structural inference?
+
+Keys such as `a[b][c]`, `user.name`, or `items[]`
+are treated as opaque strings, not paths.
+
+```ts
+{
+  "a[b][c]": "value"
+}
+```
+
+Inferring structure introduces ambiguity and security risks.
+safe-formdata validates keys, but never constructs objects from them.
+
+### Why no generic type parameters?
+
+safe-formdata does not produce typed structural output.
+
+Allowing generic types would imply runtime guarantees
+that the library intentionally does not provide.
+
+The output type is intentionally flat:
+
+```ts
+Record<string, string | File>;
+```
+
+### Why no throwing or `parseOrThrow`?
+
+FormData is external input.
+Throwing encourages accidental 500 errors and obscures boundary handling.
+
+safe-formdata exposes a single, explicit error-handling model:
+inspect issues and decide what to do.
+
+### What is safe-formdata not?
+
+- Not a schema validator
+- Not a typed form parser
+- Not a replacement for Zod, Yup, or similar libraries
+
+safe-formdata defines a safe boundary.
+Validation and typing belong beyond it.
+
+## Versioning
+
+v0.x focuses exclusively on establishing and clarifying the FormData boundary.
+No inference or convenience features will be added within v0.x.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+type IssueCode = "invalid_key" | "forbidden_key" | "duplicate_key";
+
+interface ParseIssue {
+    code: IssueCode;
+    path: readonly [];
+    key?: unknown;
+}
+
+type ParseResult = {
+    data: Record<string, string | File>;
+    issues: [];
+} | {
+    data: null;
+    issues: ParseIssue[];
+};
+
+declare function parse(formData: FormData): ParseResult;
+
+export { type IssueCode, type ParseIssue, type ParseResult, parse };

package/dist/index.js

@@ -0,0 +1 @@
+var e=new Set(["__proto__","prototype","constructor"]);function t(e,t={}){return{code:e,path:[],...t}}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?e.has(u)?s.push(t("forbidden_key",{key:u})):r.has(u)?s.push(t("duplicate_key",{key:u})):(r.add(u),o[u]=a):s.push(t("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

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/issues/forbiddenKeys.ts","../src/issues/createIssue.ts","../src/parse.ts"],"sourcesContent":["/**\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 type { ParseIssue } from \"#types/ParseIssue\";\nimport type { IssueCode } from \"#types/IssueCode\";\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","import { FORBIDDEN_KEYS } from \"#issues/forbiddenKeys\";\nimport { createIssue } from \"#issues/createIssue\";\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\tif (issues.length > 0) {\n\t\treturn {\n\t\t\tdata: null,\n\t\t\tissues,\n\t\t};\n\t}\n\n\treturn {\n\t\tdata,\n\t\tissues: [],\n\t};\n}\n"],"mappings":";AAgBO,IAAM,iBAAiB,oBAAI,IAAY;AAAA,EAC7C;AAAA,EACA;AAAA,EACA;AACD,CAAsC;;;ACK/B,SAAS,YAAY,MAAiB,UAAwB,CAAC,GAAe;AACpF,SAAO;AAAA,IACN;AAAA,IACA,MAAM,CAAC;AAAA,IACP,GAAG;AAAA,EACJ;AACD;;;ACAO,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,MAAI,OAAO,SAAS,GAAG;AACtB,WAAO;AAAA,MACN,MAAM;AAAA,MACN;AAAA,IACD;AAAA,EACD;AAEA,SAAO;AAAA,IACN;AAAA,IACA,QAAQ,CAAC;AAAA,EACV;AACD;","names":[]}

package/package.json

@@ -1,10 +1,82 @@
 {
-  "name": "safe-formdata",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for safe-formdata",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+	"name": "safe-formdata",
+	"version": "0.1.0",
+	"description": "Boundary-focused FormData parser with strict security guarantees",
+	"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",
+	"imports": {
+		"#*": {
+			"types": "./src/*.ts",
+			"import": "./src/*.ts",
+			"default": "./src/*.ts"
+		}
+	},
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"dev": "tsup --watch",
+		"lint": "oxlint . --deny-warnings",
+		"lint:fix": "oxlint . --fix-suggestions",
+		"check:type": "tsc --noEmit",
+		"format:biome": "biome format --write",
+		"format:prettier": "prettier --cache --write \"**/*.{md,yml,yaml}\"",
+		"format": "npm-run-all2 format:biome format:prettier",
+		"fix": "npm-run-all2 lint:fix format",
+		"check:biome": "biome format .",
+		"check:prettier": "prettier --cache --check \"**/*.{md,yml,yaml}\"",
+		"check:format": "npm-run-all2 check:biome check:prettier",
+		"check:source": "npm-run-all2 lint check:format",
+		"check": "bun run check:source",
+		"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 && bun run test:coverage && bun run build && bun run check:package"
+	},
+	"engines": {
+		"node": "^20.19.0 || >= 22.12.0"
+	},
+	"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",
+		"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"
+	]
 }