@ricsam/isolate-encoding 0.0.1 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @ricsam/isolate-encoding
+
+## 0.1.1
+
+### Patch Changes
+
+- initial release
+- Updated dependencies
+  - @ricsam/isolate-core@0.1.1

package/package.json

@@ -1,10 +1,29 @@
 {
   "name": "@ricsam/isolate-encoding",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @ricsam/isolate-encoding",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+  "version": "0.1.1",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test --experimental-strip-types 'src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ricsam/isolate-core": "*",
+    "isolated-vm": "^6"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "typescript": "^5"
+  },
+  "peerDependencies": {
+    "isolated-vm": "^6"
+  }
 }

package/src/index.ts

@@ -0,0 +1,175 @@
+import type ivm from "isolated-vm";
+
+export interface EncodingHandle {
+  dispose(): void;
+}
+
+const encodingCode = `
+(function() {
+  // Define DOMException if not available
+  if (typeof DOMException === 'undefined') {
+    globalThis.DOMException = class DOMException extends Error {
+      constructor(message, name) {
+        super(message);
+        this.name = name || 'DOMException';
+      }
+    };
+  }
+
+  const base64Chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+  // Build reverse lookup table
+  const base64Lookup = new Map();
+  for (let i = 0; i < base64Chars.length; i++) {
+    base64Lookup.set(base64Chars[i], i);
+  }
+
+  globalThis.btoa = function btoa(str) {
+    if (str === undefined) {
+      throw new TypeError("1 argument required, but only 0 present.");
+    }
+
+    str = String(str);
+
+    // Check for characters outside Latin-1 range
+    for (let i = 0; i < str.length; i++) {
+      if (str.charCodeAt(i) > 255) {
+        throw new DOMException(
+          "The string to be encoded contains characters outside of the Latin1 range.",
+          "InvalidCharacterError"
+        );
+      }
+    }
+
+    if (str.length === 0) {
+      return '';
+    }
+
+    let result = '';
+    let i = 0;
+
+    while (i < str.length) {
+      const a = str.charCodeAt(i++);
+      const bExists = i < str.length;
+      const b = bExists ? str.charCodeAt(i++) : 0;
+      const cExists = i < str.length;
+      const c = cExists ? str.charCodeAt(i++) : 0;
+
+      const triplet = (a << 16) | (b << 8) | c;
+
+      result += base64Chars[(triplet >> 18) & 0x3F];
+      result += base64Chars[(triplet >> 12) & 0x3F];
+      result += bExists ? base64Chars[(triplet >> 6) & 0x3F] : '=';
+      result += cExists ? base64Chars[triplet & 0x3F] : '=';
+    }
+
+    return result;
+  };
+
+  globalThis.atob = function atob(str) {
+    if (str === undefined) {
+      throw new TypeError("1 argument required, but only 0 present.");
+    }
+
+    str = String(str);
+
+    // Remove whitespace
+    str = str.replace(/[\\t\\n\\f\\r ]/g, '');
+
+    // Validate characters and length
+    if (str.length === 0) {
+      return '';
+    }
+
+    // Check for invalid characters (before padding normalization)
+    for (let i = 0; i < str.length; i++) {
+      const c = str[i];
+      if (c !== '=' && !base64Lookup.has(c)) {
+        throw new DOMException(
+          "The string to be decoded is not correctly encoded.",
+          "InvalidCharacterError"
+        );
+      }
+    }
+
+    // Validate padding position (must be at end)
+    const paddingIndex = str.indexOf('=');
+    if (paddingIndex !== -1) {
+      for (let i = paddingIndex; i < str.length; i++) {
+        if (str[i] !== '=') {
+          throw new DOMException(
+            "The string to be decoded is not correctly encoded.",
+            "InvalidCharacterError"
+          );
+        }
+      }
+      const paddingLength = str.length - paddingIndex;
+      if (paddingLength > 2) {
+        throw new DOMException(
+          "The string to be decoded is not correctly encoded.",
+          "InvalidCharacterError"
+        );
+      }
+    }
+
+    // Length without padding must be valid (can't have remainder of 1)
+    const strWithoutPadding = str.replace(/=/g, '');
+    if (strWithoutPadding.length % 4 === 1) {
+      throw new DOMException(
+        "The string to be decoded is not correctly encoded.",
+        "InvalidCharacterError"
+      );
+    }
+
+    // Pad to multiple of 4 if needed (for inputs without explicit padding)
+    while (str.length % 4 !== 0) {
+      str += '=';
+    }
+
+    let result = '';
+    let i = 0;
+
+    while (i < str.length) {
+      const a = base64Lookup.get(str[i++]) ?? 0;
+      const b = base64Lookup.get(str[i++]) ?? 0;
+      const c = base64Lookup.get(str[i++]) ?? 0;
+      const d = base64Lookup.get(str[i++]) ?? 0;
+
+      const triplet = (a << 18) | (b << 12) | (c << 6) | d;
+
+      result += String.fromCharCode((triplet >> 16) & 0xFF);
+      if (str[i - 2] !== '=') {
+        result += String.fromCharCode((triplet >> 8) & 0xFF);
+      }
+      if (str[i - 1] !== '=') {
+        result += String.fromCharCode(triplet & 0xFF);
+      }
+    }
+
+    return result;
+  };
+})();
+`;
+
+/**
+ * Setup encoding APIs in an isolated-vm context
+ *
+ * Injects atob and btoa for Base64 encoding/decoding
+ *
+ * @example
+ * const handle = await setupEncoding(context);
+ * await context.eval(`
+ *   const encoded = btoa("hello");
+ *   const decoded = atob(encoded);
+ * `);
+ */
+export async function setupEncoding(
+  context: ivm.Context
+): Promise<EncodingHandle> {
+  context.evalSync(encodingCode);
+  return {
+    dispose() {
+      // No resources to cleanup for pure JS injection
+    },
+  };
+}

package/src/setup.test.ts

@@ -0,0 +1,134 @@
+import { test, describe, beforeEach, afterEach } from "node:test";
+import assert from "node:assert";
+import ivm from "isolated-vm";
+import { setupEncoding } from "./index.ts";
+
+describe("@ricsam/isolate-encoding", () => {
+  let isolate: ivm.Isolate;
+  let context: ivm.Context;
+
+  beforeEach(async () => {
+    isolate = new ivm.Isolate();
+    context = await isolate.createContext();
+  });
+
+  afterEach(() => {
+    context.release();
+    isolate.dispose();
+  });
+
+  describe("btoa", () => {
+    test("encodes string to base64", async () => {
+      await setupEncoding(context);
+      const result = await context.eval(`btoa("hello")`);
+      assert.strictEqual(result, "aGVsbG8=");
+    });
+
+    test("handles empty string", async () => {
+      await setupEncoding(context);
+      const result = await context.eval(`btoa("")`);
+      assert.strictEqual(result, "");
+    });
+
+    test("handles Latin-1 characters", async () => {
+      await setupEncoding(context);
+      // Test with Latin-1 extended characters (char codes 128-255)
+      const result = await context.eval(`btoa("café")`);
+      // café uses é which is Latin-1 (char code 233)
+      assert.strictEqual(result, "Y2Fm6Q==");
+    });
+
+    test("throws on characters outside Latin-1 range", async () => {
+      await setupEncoding(context);
+      await assert.rejects(
+        async () => {
+          await context.eval(`btoa("hello 世界")`);
+        },
+        {
+          name: "InvalidCharacterError",
+        }
+      );
+    });
+
+    test("converts non-string arguments to string", async () => {
+      await setupEncoding(context);
+      const result = await context.eval(`btoa(123)`);
+      assert.strictEqual(result, "MTIz");
+    });
+  });
+
+  describe("atob", () => {
+    test("decodes base64 to string", async () => {
+      await setupEncoding(context);
+      const result = await context.eval(`atob("aGVsbG8=")`);
+      assert.strictEqual(result, "hello");
+    });
+
+    test("handles empty string", async () => {
+      await setupEncoding(context);
+      const result = await context.eval(`atob("")`);
+      assert.strictEqual(result, "");
+    });
+
+    test("throws on invalid base64", async () => {
+      await setupEncoding(context);
+      await assert.rejects(
+        async () => {
+          await context.eval(`atob("not valid base64!@#")`);
+        },
+        {
+          name: "InvalidCharacterError",
+        }
+      );
+    });
+
+    test("handles input without padding", async () => {
+      await setupEncoding(context);
+      // "aGVsbG8" is "hello" without the = padding
+      const result = await context.eval(`atob("aGVsbG8")`);
+      assert.strictEqual(result, "hello");
+    });
+
+    test("ignores whitespace in input", async () => {
+      await setupEncoding(context);
+      const result = await context.eval(`atob("aGVs bG8=")`);
+      assert.strictEqual(result, "hello");
+    });
+  });
+
+  describe("roundtrip", () => {
+    test("btoa and atob are inverse operations", async () => {
+      await setupEncoding(context);
+      const testStrings = [
+        "hello",
+        "Hello World!",
+        "test123",
+        "a",
+        "ab",
+        "abc",
+        "",
+      ];
+
+      for (const str of testStrings) {
+        const result = await context.eval(
+          `atob(btoa(${JSON.stringify(str)}))`
+        );
+        assert.strictEqual(result, str, `Roundtrip failed for: ${str}`);
+      }
+    });
+
+    test("handles binary data roundtrip", async () => {
+      await setupEncoding(context);
+      // Create a string with all Latin-1 bytes
+      const result = await context.eval(`
+        const bytes = [];
+        for (let i = 0; i < 256; i++) {
+          bytes.push(String.fromCharCode(i));
+        }
+        const str = bytes.join('');
+        atob(btoa(str)) === str;
+      `);
+      assert.strictEqual(result, true);
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/README.md

@@ -1,45 +0,0 @@
-# @ricsam/isolate-encoding
-
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@ricsam/isolate-encoding`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-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.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-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
-
-## DO NOT USE THIS PACKAGE
-
-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
-
-## More Information
-
-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)
-
----
-
-**Maintained for OIDC setup purposes only**