@asafarim/appsafe 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alisafari
+
+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,125 @@
+# @asafarim/appsafe
+
+A small browser-first encryption package built on the Web Crypto API. It encrypts arbitrary bytes or UTF-8 text with AES-256-GCM and derives the key from a user-supplied password with PBKDF2-HMAC-SHA-256. Passwords and plaintext stay in the calling runtime; this package performs no network requests.
+
+## Install
+
+```bash
+pnpm add @asafarim/appsafe
+# or
+npm install @asafarim/appsafe
+```
+
+Requires a runtime that provides `globalThis.crypto.subtle` (all modern browsers, Node 20+, and Deno).
+
+## API
+
+### `encryptBytes(input, password, options?): Promise<Uint8Array>`
+
+Encrypts an `ArrayBuffer` or `Uint8Array` and returns a self-describing binary payload.
+
+### `decryptBytes(input, password): Promise<Uint8Array>`
+
+Decrypts a payload produced by `encryptBytes`. Throws `AppSafeCryptoError` with code `INVALID_PASSWORD_OR_DATA` if the password or payload is wrong.
+
+### `encryptText(input, password, options?): Promise<Uint8Array>`
+
+UTF-8 encodes the string, then calls `encryptBytes`.
+
+### `decryptText(input, password): Promise<string>`
+
+Calls `decryptBytes` and UTF-8 decodes the result. Throws `AppSafeCryptoError` with code `INVALID_TEXT` if the decrypted bytes are not valid UTF-8.
+
+### `isAppSafePayload(input): boolean`
+
+Cheap header check — verifies the `ASAFE` magic and version byte. Useful for validating a file before attempting decryption.
+
+### `DEFAULT_PBKDF2_ITERATIONS`
+
+The default PBKDF2 work factor: `600_000` SHA-256 iterations.
+
+### `EncryptOptions`
+
+```ts
+interface EncryptOptions {
+  iterations?: number; // default 600_000; clamped to [100_000, 2_000_000]
+}
+```
+
+### `AppSafeCryptoError`
+
+Typed error thrown by all functions. Inspect `error.code` to differentiate failure modes:
+
+| Code | Meaning |
+| --- | --- |
+| `EMPTY_PASSWORD` | No password was provided. |
+| `INVALID_OPTIONS` | `iterations` is outside the allowed range. |
+| `INVALID_PAYLOAD` | The input is not a supported AppSafe payload. |
+| `INVALID_PASSWORD_OR_DATA` | AES-GCM authentication failed. |
+| `INVALID_TEXT` | Decrypted bytes are not valid UTF-8. |
+| `UNSUPPORTED_RUNTIME` | The runtime has no Web Crypto `subtle` API. |
+
+## Usage
+
+### Text round-trip
+
+```ts
+import { decryptText, encryptText } from "@asafarim/appsafe";
+
+const encrypted = await encryptText("private note", password);
+const plaintext = await decryptText(encrypted, password);
+```
+
+### File round-trip
+
+```ts
+import { decryptBytes, encryptBytes } from "@asafarim/appsafe";
+
+const input = new Uint8Array(await file.arrayBuffer());
+const payload = await encryptBytes(input, password);
+const original = await decryptBytes(payload, password);
+
+// Persist or download the payload:
+const blob = new Blob([payload], { type: "application/octet-stream" });
+```
+
+### Validate a payload before decrypting
+
+```ts
+import { isAppSafePayload } from "@asafarim/appsafe";
+
+const bytes = new Uint8Array(await file.arrayBuffer());
+if (!isAppSafePayload(bytes)) {
+  throw new Error("Not an AppSafe payload");
+}
+```
+
+### Custom PBKDF2 iterations
+
+```ts
+import { encryptBytes } from "@asafarim/appsafe";
+
+const payload = await encryptBytes(data, password, { iterations: 1_000_000 });
+```
+
+## Payload format
+
+The returned `Uint8Array` is a single binary envelope:
+
+```
+[ magic "ASAFE" (5) ][ version (1) ][ salt (16) ][ iv (12) ][ iterations (4, big-endian) ][ ciphertext + GCM tag ]
+```
+
+The full header is authenticated as AES-GCM additional data, so any modification to the salt, IV, or iteration count causes decryption to fail closed.
+
+## Security notes
+
+- Uses standardized primitives already implemented by modern browsers — no custom crypto.
+- A new random salt and 96-bit nonce are generated for every encryption operation.
+- Wrong passwords and tampered payloads fail closed via AES-GCM authentication.
+- The package never reads files, creates downloads, or makes network requests for you.
+- The default 600,000-iteration PBKDF2 work factor can be raised via `EncryptOptions.iterations` (max 2,000,000) when your product needs a different performance/security balance.
+
+## License
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export declare const DEFAULT_PBKDF2_ITERATIONS = 600000;
+export type ByteSource = ArrayBuffer | Uint8Array;
+export type AppSafeCryptoErrorCode = "EMPTY_PASSWORD" | "INVALID_OPTIONS" | "INVALID_PAYLOAD" | "INVALID_PASSWORD_OR_DATA" | "INVALID_TEXT" | "UNSUPPORTED_RUNTIME";
+export declare class AppSafeCryptoError extends Error {
+    readonly code: AppSafeCryptoErrorCode;
+    constructor(code: AppSafeCryptoErrorCode, message: string);
+}
+export interface EncryptOptions {
+    iterations?: number;
+}
+export declare function isAppSafePayload(input: ByteSource): boolean;
+export declare function encryptBytes(input: ByteSource, password: string, options?: EncryptOptions): Promise<Uint8Array>;
+export declare function decryptBytes(input: ByteSource, password: string): Promise<Uint8Array>;
+export declare function encryptText(input: string, password: string, options?: EncryptOptions): Promise<Uint8Array>;
+export declare function decryptText(input: ByteSource, password: string): Promise<string>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,yBAAyB,SAAU,CAAC;AAEjD,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;AAElD,MAAM,MAAM,sBAAsB,GAC9B,gBAAgB,GAChB,iBAAiB,GACjB,iBAAiB,GACjB,0BAA0B,GAC1B,cAAc,GACd,qBAAqB,CAAC;AAE1B,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IAEtC,YAAY,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,MAAM,EAIxD;CACF;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA2ID,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAO3D;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,CAyBrB;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,CAAC,CA0BrB;AAED,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,CAErB;AAED,wBAAsB,WAAW,CAC/B,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAWjB"}

package/dist/index.js

@@ -0,0 +1,145 @@
+const MAGIC = new Uint8Array([0x41, 0x53, 0x41, 0x46, 0x45]);
+const VERSION = 1;
+const SALT_LENGTH = 16;
+const IV_LENGTH = 12;
+const HEADER_LENGTH = MAGIC.length + 1 + SALT_LENGTH + IV_LENGTH + 4;
+const AUTH_TAG_LENGTH = 16;
+const MIN_ITERATIONS = 100_000;
+const MAX_ITERATIONS = 2_000_000;
+export const DEFAULT_PBKDF2_ITERATIONS = 600_000;
+export class AppSafeCryptoError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "AppSafeCryptoError";
+        this.code = code;
+    }
+}
+function getWebCrypto() {
+    if (typeof globalThis.crypto === "undefined" || !globalThis.crypto.subtle) {
+        throw new AppSafeCryptoError("UNSUPPORTED_RUNTIME", "This runtime does not provide the Web Crypto API.");
+    }
+    return globalThis.crypto;
+}
+function toBytes(input) {
+    if (input instanceof ArrayBuffer) {
+        return new Uint8Array(input.slice(0));
+    }
+    return new Uint8Array(input);
+}
+function asBufferSource(bytes) {
+    return bytes;
+}
+function assertPassword(password) {
+    if (typeof password !== "string" || password.length === 0) {
+        throw new AppSafeCryptoError("EMPTY_PASSWORD", "An encryption password is required.");
+    }
+}
+function getIterations(options) {
+    const iterations = options?.iterations ?? DEFAULT_PBKDF2_ITERATIONS;
+    if (!Number.isSafeInteger(iterations) ||
+        iterations < MIN_ITERATIONS ||
+        iterations > MAX_ITERATIONS) {
+        throw new AppSafeCryptoError("INVALID_OPTIONS", `PBKDF2 iterations must be between ${MIN_ITERATIONS} and ${MAX_ITERATIONS}.`);
+    }
+    return iterations;
+}
+function randomBytes(length, cryptoApi) {
+    const bytes = new Uint8Array(length);
+    cryptoApi.getRandomValues(bytes);
+    return bytes;
+}
+function createHeader(salt, iv, iterations) {
+    const header = new Uint8Array(HEADER_LENGTH);
+    header.set(MAGIC, 0);
+    header[5] = VERSION;
+    header.set(salt, 6);
+    header.set(iv, 6 + SALT_LENGTH);
+    new DataView(header.buffer).setUint32(HEADER_LENGTH - 4, iterations);
+    return header;
+}
+function readHeader(encrypted) {
+    if (encrypted.length < HEADER_LENGTH + AUTH_TAG_LENGTH) {
+        throw new AppSafeCryptoError("INVALID_PAYLOAD", "The encrypted data is incomplete.");
+    }
+    const header = encrypted.slice(0, HEADER_LENGTH);
+    const hasMagic = MAGIC.every((byte, index) => header[index] === byte);
+    if (!hasMagic || header[5] !== VERSION) {
+        throw new AppSafeCryptoError("INVALID_PAYLOAD", "The data is not a supported AppSafe payload.");
+    }
+    const iterations = new DataView(header.buffer).getUint32(HEADER_LENGTH - 4);
+    if (iterations < MIN_ITERATIONS || iterations > MAX_ITERATIONS) {
+        throw new AppSafeCryptoError("INVALID_PAYLOAD", "The encrypted data has an invalid key-derivation setting.");
+    }
+    return {
+        header,
+        salt: header.slice(6, 6 + SALT_LENGTH),
+        iv: header.slice(6 + SALT_LENGTH, 6 + SALT_LENGTH + IV_LENGTH),
+        iterations,
+    };
+}
+async function deriveKey(password, salt, iterations, cryptoApi) {
+    const passwordKey = await cryptoApi.subtle.importKey("raw", asBufferSource(new TextEncoder().encode(password)), { name: "PBKDF2" }, false, ["deriveKey"]);
+    return cryptoApi.subtle.deriveKey({
+        name: "PBKDF2",
+        salt: asBufferSource(salt),
+        iterations,
+        hash: "SHA-256",
+    }, passwordKey, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+}
+export function isAppSafePayload(input) {
+    const bytes = toBytes(input);
+    return (bytes.length >= HEADER_LENGTH + AUTH_TAG_LENGTH &&
+        MAGIC.every((byte, index) => bytes[index] === byte) &&
+        bytes[5] === VERSION);
+}
+export async function encryptBytes(input, password, options) {
+    assertPassword(password);
+    const iterations = getIterations(options);
+    const cryptoApi = getWebCrypto();
+    const plaintext = toBytes(input);
+    const salt = randomBytes(SALT_LENGTH, cryptoApi);
+    const iv = randomBytes(IV_LENGTH, cryptoApi);
+    const header = createHeader(salt, iv, iterations);
+    const key = await deriveKey(password, salt, iterations, cryptoApi);
+    const ciphertext = new Uint8Array(await cryptoApi.subtle.encrypt({
+        name: "AES-GCM",
+        iv: asBufferSource(iv),
+        additionalData: asBufferSource(header),
+        tagLength: 128,
+    }, key, asBufferSource(plaintext)));
+    const payload = new Uint8Array(header.length + ciphertext.length);
+    payload.set(header, 0);
+    payload.set(ciphertext, header.length);
+    return payload;
+}
+export async function decryptBytes(input, password) {
+    assertPassword(password);
+    const cryptoApi = getWebCrypto();
+    const encrypted = toBytes(input);
+    const { header, salt, iv, iterations } = readHeader(encrypted);
+    const key = await deriveKey(password, salt, iterations, cryptoApi);
+    try {
+        return new Uint8Array(await cryptoApi.subtle.decrypt({
+            name: "AES-GCM",
+            iv: asBufferSource(iv),
+            additionalData: asBufferSource(header),
+            tagLength: 128,
+        }, key, asBufferSource(encrypted.slice(HEADER_LENGTH))));
+    }
+    catch {
+        throw new AppSafeCryptoError("INVALID_PASSWORD_OR_DATA", "The password or encrypted data is invalid.");
+    }
+}
+export async function encryptText(input, password, options) {
+    return encryptBytes(new TextEncoder().encode(input), password, options);
+}
+export async function decryptText(input, password) {
+    const plaintext = await decryptBytes(input, password);
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(plaintext);
+    }
+    catch {
+        throw new AppSafeCryptoError("INVALID_TEXT", "The decrypted data is not valid UTF-8 text.");
+    }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@asafarim/appsafe",
+  "version": "0.1.0",
+  "description": "Browser-native password-based AES-256-GCM encryption for files and data",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "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"
+    }
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsx": "4.23.12",
+    "typescript": "7.0.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "test": "tsx --test test/*.test.ts"
+  }
+}