safe-formdata 0.0.1 → 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.
Files changed (6) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +160 -27
  3. package/dist/index.d.ts +19 -0
  4. package/dist/index.js +1 -0
  5. package/dist/index.js.map +1 -0
  6. package/package.json +83 -8
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 roottool
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,45 +1,178 @@
1
1
  # safe-formdata
2
2
 
3
- ## ⚠️ IMPORTANT NOTICE ⚠️
3
+ **The strict trust boundary for FormData.**
4
4
 
5
- **This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
5
+ [![npm version](https://img.shields.io/npm/v/safe-formdata)](https://www.npmjs.com/package/safe-formdata)
6
+ [![CI](https://github.com/roottool/safe-formdata/actions/workflows/ci.yml/badge.svg)](https://github.com/roottool/safe-formdata/actions/workflows/ci.yml)
7
+ [![codecov](https://codecov.io/gh/roottool/safe-formdata/graph/badge.svg)](https://codecov.io/gh/roottool/safe-formdata)
6
8
 
7
- This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
9
+ safe-formdata is a **security-focused** parser that establishes a predictable boundary between untrusted input and application logic.
10
+ It enforces strict rules on keys and forbids structural inference by design.
8
11
 
9
- ## Purpose
12
+ ---
13
+
14
+ ## Overview
15
+
16
+ FormData is untyped and unstructured by nature.
17
+ Many parsers attempt to infer structure or semantics from key naming conventions.
18
+
19
+ safe-formdata intentionally does not.
20
+
21
+ It performs only minimal, security-focused parsing and reports
22
+ all structural issues explicitly, without inferring structure, intent, or meaning.
23
+
24
+ ---
10
25
 
11
- This package exists to:
12
- 1. Configure OIDC trusted publishing for the package name `safe-formdata`
13
- 2. Enable secure, token-less publishing from CI/CD workflows
14
- 3. Establish provenance for packages published under this name
26
+ ## Design principles
15
27
 
16
- ## What is OIDC Trusted Publishing?
28
+ - 🧱 **Keys are opaque**
29
+ Key names are never interpreted as structure.
30
+ - 🚫 **No silent fixes**
31
+ Invalid or conflicting input is reported, not corrected.
32
+ - ⚖️ **Parsing is not validation**
33
+ Schema and business logic belong outside the boundary.
34
+ - 🔒️ **Security over convenience**
35
+ Unsafe input is surfaced early and explicitly.
17
36
 
18
- 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.
37
+ ---
19
38
 
20
- ## Setup Instructions
39
+ ## Security scope
21
40
 
22
- To properly configure OIDC trusted publishing for this package:
41
+ safe-formdata defines a **strict trust boundary** between untrusted FormData input
42
+ and application logic.
23
43
 
24
- 1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
25
- 2. Configure the trusted publisher (e.g., GitHub Actions)
26
- 3. Specify the repository and workflow that should be allowed to publish
27
- 4. Use the configured workflow to publish your actual package
44
+ Within this boundary, safe-formdata focuses exclusively on:
28
45
 
29
- ## DO NOT USE THIS PACKAGE
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**
30
50
 
31
- This package is a placeholder for OIDC configuration only. It:
32
- - Contains no executable code
33
- - Provides no functionality
34
- - Should not be installed as a dependency
35
- - Exists only for administrative purposes
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.
36
54
 
37
- ## More Information
55
+ 📘 **Authoritative security guarantees, assumptions, and reporting policy:**
56
+ See [SECURITY.md](./SECURITY.md)
38
57
 
39
- For more details about npm's trusted publishing feature, see:
40
- - [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
41
- - [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
58
+ Security decisions and issue triage are based on the definitions in SECURITY.md.
42
59
 
43
60
  ---
44
61
 
45
- **Maintained for OIDC setup purposes only**
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
+ ## Design decisions (Why not?)
103
+
104
+ safe-formdata intentionally omits several common features.
105
+
106
+ ### Why no structural inference?
107
+
108
+ Keys such as `a[b][c]`, `user.name`, or `items[]`
109
+ are treated as opaque strings, not paths.
110
+
111
+ ```ts
112
+ {
113
+ "a[b][c]": "value"
114
+ }
115
+ ```
116
+
117
+ Inferring structure introduces ambiguity and security risks.
118
+ safe-formdata validates keys, but never constructs objects from them.
119
+
120
+ ### Why no generic type parameters?
121
+
122
+ safe-formdata does not produce typed structural output.
123
+
124
+ Allowing generic types would imply runtime guarantees
125
+ that the library intentionally does not provide.
126
+
127
+ The output type is intentionally flat:
128
+
129
+ ```ts
130
+ Record<string, string | File>;
131
+ ```
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
+
154
+ ### Why no throwing or `parseOrThrow`?
155
+
156
+ FormData is external input.
157
+ Throwing encourages accidental 500 errors and obscures boundary handling.
158
+
159
+ safe-formdata exposes a single, explicit error-handling model:
160
+ inspect issues and decide what to do.
161
+
162
+ ### What is safe-formdata not?
163
+
164
+ - Not a schema validator
165
+ - Not a typed form parser
166
+ - Not a replacement for Zod, Yup, or similar libraries
167
+
168
+ safe-formdata defines a safe boundary.
169
+ Validation and typing belong beyond it.
170
+
171
+ ## Versioning
172
+
173
+ v0.x focuses exclusively on establishing and clarifying the FormData boundary.
174
+ No inference or convenience features will be added within v0.x.
175
+
176
+ ## License
177
+
178
+ MIT
package/dist/index.d.ts ADDED
@@ -0,0 +1,19 @@
1
+ type IssueCode = "invalid_key" | "forbidden_key" | "duplicate_key";
2
+
3
+ interface ParseIssue {
4
+ code: IssueCode;
5
+ path: readonly [];
6
+ key?: unknown;
7
+ }
8
+
9
+ type ParseResult = {
10
+ data: Record<string, string | File>;
11
+ issues: [];
12
+ } | {
13
+ data: null;
14
+ issues: ParseIssue[];
15
+ };
16
+
17
+ declare function parse(formData: FormData): ParseResult;
18
+
19
+ export { type IssueCode, type ParseIssue, type ParseResult, parse };
package/dist/index.js ADDED
@@ -0,0 +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 ADDED
@@ -0,0 +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":[]}
package/package.json CHANGED
@@ -1,10 +1,85 @@
1
1
  {
2
- "name": "safe-formdata",
3
- "version": "0.0.1",
4
- "description": "OIDC trusted publishing setup package for safe-formdata",
5
- "keywords": [
6
- "oidc",
7
- "trusted-publishing",
8
- "setup"
9
- ]
2
+ "name": "safe-formdata",
3
+ "version": "0.1.1",
4
+ "description": "Boundary-focused FormData parser with strict security guarantees",
5
+ "author": "roottool",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/roottool/safe-formdata.git"
9
+ },
10
+ "bugs": {
11
+ "url": "https://github.com/roottool/safe-formdata/issues"
12
+ },
13
+ "homepage": "https://github.com/roottool/safe-formdata#readme",
14
+ "imports": {
15
+ "#*": {
16
+ "types": "./src/*.ts",
17
+ "import": "./src/*.ts",
18
+ "default": "./src/*.ts"
19
+ },
20
+ "#safe-formdata": "./src/index.ts"
21
+ },
22
+ "type": "module",
23
+ "main": "./dist/index.js",
24
+ "module": "./dist/index.js",
25
+ "types": "./dist/index.d.ts",
26
+ "exports": {
27
+ ".": {
28
+ "types": "./dist/index.d.ts",
29
+ "import": "./dist/index.js",
30
+ "default": "./dist/index.js"
31
+ }
32
+ },
33
+ "files": [
34
+ "dist"
35
+ ],
36
+ "scripts": {
37
+ "dev": "tsup --watch",
38
+ "lint": "oxlint . --deny-warnings",
39
+ "lint:fix": "oxlint . --fix-suggestions",
40
+ "format:biome": "biome check --write --assist-enabled true",
41
+ "format:prettier": "prettier --cache --write \"**/*.{md,yml,yaml}\"",
42
+ "format": "npm-run-all2 format:biome format:prettier",
43
+ "fix": "npm-run-all2 lint:fix format",
44
+ "check:biome": "biome check . --assist-enabled true",
45
+ "check:prettier": "prettier --cache --check \"**/*.{md,yml,yaml}\"",
46
+ "check:format": "npm-run-all2 check:biome check:prettier",
47
+ "check:source": "npm-run-all2 lint check:format",
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",
55
+ "test": "vitest run",
56
+ "test:watch": "vitest",
57
+ "test:coverage": "vitest run --coverage",
58
+ "build": "tsup",
59
+ "check:package": "publint && attw --pack . --ignore-rules cjs-resolves-to-esm",
60
+ "prepublishOnly": "bun run check:type:source && bun run test:coverage && bun run build && bun run check:package"
61
+ },
62
+ "devDependencies": {
63
+ "@arethetypeswrong/cli": "0.18.2",
64
+ "@biomejs/biome": "2.3.10",
65
+ "@types/node": "25.0.3",
66
+ "@vitest/coverage-v8": "4.0.16",
67
+ "happy-dom": "20.0.11",
68
+ "npm-run-all2": "8.0.4",
69
+ "oxlint": "1.34.0",
70
+ "prettier": "3.7.4",
71
+ "publint": "0.3.16",
72
+ "terser": "5.44.1",
73
+ "tsup": "8.5.1",
74
+ "typescript": "5.9.3",
75
+ "vitest": "4.0.16"
76
+ },
77
+ "license": "MIT",
78
+ "keywords": [
79
+ "formdata",
80
+ "parser",
81
+ "security",
82
+ "boundary",
83
+ "prototype-pollution"
84
+ ]
10
85
  }