@suzukihayate/safe-html 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hayate Suzuki (鈴木颯)
+
+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

@@ -0,0 +1,58 @@
+# safe-html
+
+A tiny, **zero-dependency** tagged-template that **auto-escapes by context** (HTML text / attribute / URL). Build HTML strings safely without a framework.
+
+文脈（テキスト・属性・URL）を理解して**自動でエスケープ**する、依存ゼロのタグ付きテンプレートです。フレームワークなしでXSSを防げます。
+
+- Text position → HTML-escaped
+- Attribute value → attribute-escaped
+- URL attributes (`href`, `src`, …) → dangerous schemes like `javascript:` are neutralized
+- `SafeString` values are **not double-escaped**, so fragments compose
+- Interpolating into a tag name or attribute name is **rejected** (safety)
+- Zero dependencies, typed, ESM — works in Node / Deno / Bun / browser
+
+## Install
+```bash
+npm install @suzukihayate/safe-html
+```
+
+## Usage
+```js
+import { html, raw } from '@suzukihayate/safe-html';
+
+html`<p>${'<script>alert(1)</script>'}</p>`.toString();
+// "<p>&lt;script&gt;alert(1)&lt;/script&gt;</p>"
+
+html`<a href="${'javascript:alert(1)'}">x</a>`.toString();
+// '<a href="#">x</a>'   (neutralized)
+
+html`<a href="${'https://example.com/?a=1&b=2'}">ok</a>`.toString();
+// '<a href="https://example.com/?a=1&amp;b=2">ok</a>'
+
+// Compose fragments without double-escaping
+const items = ['a<', 'b&'].map((t) => html`<li>${t}</li>`);
+html`<ul>${items}</ul>`.toString();
+// '<ul><li>a&lt;</li><li>b&amp;</li></ul>'
+
+// Opt-in raw (trusted strings only)
+html`<p>${raw('<br>')}</p>`.toString(); // '<p><br></p>'
+```
+
+## API
+- `` html`...` `` — context-aware auto-escaping tagged template, returns a `SafeString`
+- `raw(str)` — wrap a trusted string (no escaping)
+- `escapeHtml(str)` / `safeUrl(str)` — the underlying helpers
+- `SafeString` — branded safe-HTML wrapper (`.toString()`)
+
+## Why
+Most escaping helpers escape the same way everywhere, so developers must remember which context they are in (and `href="javascript:..."` slips through plain HTML escaping). `safe-html` tracks the parsing context across the static template parts and escapes each interpolation correctly — including neutralizing dangerous URL schemes — in a few hundred bytes.
+
+> Note: assumes reasonably well-formed templates (double/single-quoted or unquoted attribute values). For full untrusted-HTML sanitization, use a dedicated sanitizer.
+
+## Test
+```bash
+node --test
+```
+
+## License
+MIT © 2026 Hayate Suzuki

package/index.d.ts

@@ -0,0 +1,27 @@
+/** 安全と分かっている HTML 文字列のラッパー。 */
+export class SafeString {
+  constructor(value: string);
+  value: string;
+  toString(): string;
+}
+
+/** HTML テキストのエスケープ。 */
+export function escapeHtml(s: string): string;
+
+/** URL として危険なスキーム（javascript: 等）を無害化する。 */
+export function safeUrl(value: string): string;
+
+/** 文脈（テキスト / 属性 / URL）に応じて自動エスケープするタグ付きテンプレート。 */
+export function html(strings: TemplateStringsArray, ...values: unknown[]): SafeString;
+
+/** エスケープせずそのまま埋め込む（信頼できる文字列のみ）。 */
+export function raw(value: string): SafeString;
+
+declare const _default: {
+  html: typeof html;
+  raw: typeof raw;
+  SafeString: typeof SafeString;
+  escapeHtml: typeof escapeHtml;
+  safeUrl: typeof safeUrl;
+};
+export default _default;

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@suzukihayate/safe-html",
+  "version": "0.1.0",
+  "description": "文脈（HTML/属性/URL）を理解して自動エスケープする、依存ゼロのタグ付きテンプレート。フレームワーク不要でXSSを防ぐ。",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "files": ["index.js", "index.d.ts", "README.md", "LICENSE"],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": ["html", "escape", "xss", "template-literal", "tagged-template", "sanitize", "security", "contextual", "zero-dependency"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HaYaTedonn/safe-html.git"
+  },
+  "author": "Hayate Suzuki",
+  "license": "MIT",
+  "engines": { "node": ">=18" },
+  "sideEffects": false
+}