@maestro-js/sign 1.0.0-alpha.30

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+interface SignDriver {
+    sign(value: string): string;
+    verify(options: {
+        value: string;
+        signature: string;
+    }): boolean;
+}
+
+interface HmacSha256DriverConfig {
+    /** The base64-encoded signing key used to produce new signatures. Decoded to its raw bytes for HMAC. */
+    key: string;
+    /** Retired base64-encoded keys still accepted on verify, so signatures survive key rotation. @default `[]` */
+    previousKeys?: string[];
+}
+declare function hmacSha256SignDriver(config: HmacSha256DriverConfig): SignDriver;
+
+interface Ed25519DriverConfig {
+    /** PEM-encoded (PKCS#8) private key used to produce signatures. Omit for a verify-only instance. */
+    privateKey?: string;
+    /**
+     * PEM-encoded (SPKI) public keys accepted on verify — for verify-only instances and rotated-out
+     * keys. The configured private key's own public key is always accepted, so signers don't repeat it.
+     * @default `[]`
+     */
+    publicKeys?: string[];
+}
+declare function ed25519SignDriver(config: Ed25519DriverConfig): SignDriver;
+
+declare function create(driver: Sign.Driver): Sign.SignService;
+declare function provider(key: Sign.Provider.Key): Sign.SignService;
+type KeysWithFallback = keyof Sign.Provider.Keys extends never ? {
+    default: unknown;
+} : Sign.Provider.Keys;
+/**
+ * Pluggable signing and verification with driver-based algorithms.
+ * Call methods directly on the default instance, or use `Sign.Provider.create()` for named instances.
+ */
+declare const Sign: {
+    provider: typeof provider;
+    drivers: {
+        hmacSha256: typeof hmacSha256SignDriver;
+        ed25519: typeof ed25519SignDriver;
+    };
+    /** Signs a value, returning a bare base64url signature */
+    sign: (value: string) => string;
+    /** Verifies that the signature was produced by {@link sign} for the value, trying every configured key */
+    verify: (options: {
+        value: string;
+        signature: string;
+    }) => boolean;
+    Provider: {
+        create: typeof create;
+        register: (name: Sign.Provider.Key, item: Sign.SignService) => void;
+    };
+};
+/**
+ * Pluggable signing and verification with driver-based algorithms.
+ *
+ * Signs a value with a secret and verifies the signature later. Signatures are **bare, standard**
+ * base64url — no key id or other proprietary framing — so another party can verify your signed
+ * content with stock crypto and no `@maestro-js` dependency. For the `hmacSha256` driver (whose key
+ * is base64-encoded, decoded to its raw bytes before signing):
+ *
+ * ```js
+ * const expected = crypto.createHmac('sha256', Buffer.from(key, 'base64')).update(value).digest('base64url')
+ * crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(theirSignature))
+ * ```
+ *
+ * Key rotation is handled on the verifying side: there is deliberately no key id embedded in the
+ * signature — that keeps it standard and externally verifiable — so {@link SignService.verify} tries
+ * the current key and every retired key still configured (negligible for a small rotation window).
+ *
+ * The `ed25519` driver signs with a PEM private key and verifies with public keys. Omit the private
+ * key for a verify-only instance — one that checks another party's signatures but can never produce
+ * its own ({@link SignService.sign} throws).
+ *
+ * This is signing (a MAC or digital signature), distinct from one-way password hashing
+ * (`@maestro-js/hash`) and from reversible encryption (`@maestro-js/crypt`).
+ *
+ * @example
+ * ```ts
+ * Sign.Provider.register('default', Sign.Provider.create(Sign.drivers.hmacSha256({ key: process.env.SIGNING_KEY! })))
+ *
+ * const signature = Sign.sign('order.completed:ord_8k2Xp')
+ * Sign.verify({ value: 'order.completed:ord_8k2Xp', signature }) // true
+ *
+ * // Verify-only Ed25519 instance for a vendor's webhooks
+ * Sign.Provider.register('webhooks', Sign.Provider.create(Sign.drivers.ed25519({ publicKeys: [vendorPublicKey] })))
+ * ```
+ */
+declare namespace Sign {
+    /** Pluggable signing algorithm — see `Sign.drivers` for built-in options */
+    type Driver = SignDriver;
+    namespace Provider {
+        type Key = keyof KeysWithFallback;
+        interface Keys {
+        }
+    }
+    interface SignService {
+        /** Signs a value, returning a bare base64url signature */
+        sign: (value: string) => string;
+        /** Verifies that the signature was produced by {@link sign} for the value, trying every configured key */
+        verify: (options: {
+            value: string;
+            signature: string;
+        }) => boolean;
+    }
+}
+
+export { Sign };

package/dist/index.js

@@ -0,0 +1,86 @@
+// src/index.ts
+import { ServiceRegistry } from "@maestro-js/service-registry";
+
+// src/hmac-sha256-sign-driver.ts
+import assert from "assert";
+import { createHmac, timingSafeEqual } from "crypto";
+function hmacSha256SignDriver(config) {
+  assert.ok(config.key, "hmacSha256 driver: a signing key is required");
+  const keys = [config.key, ...config.previousKeys ?? []].filter(Boolean).map((key) => {
+    const decoded = Buffer.from(key, "base64");
+    assert.ok(decoded.length > 0, `hmacSha256 driver: invalid base64 signing key: ${key}`);
+    return decoded;
+  });
+  function sign(value) {
+    return hmacSign(keys[0], value);
+  }
+  function verify(options) {
+    const provided = Buffer.from(options.signature);
+    return keys.some((key) => {
+      const expected = Buffer.from(hmacSign(key, options.value));
+      return expected.length === provided.length && timingSafeEqual(expected, provided);
+    });
+  }
+  return { sign, verify };
+}
+function hmacSign(key, value) {
+  return createHmac("sha256", key).update(value).digest("base64url");
+}
+
+// src/ed25519-sign-driver.ts
+import assert2 from "assert";
+import crypto from "crypto";
+function ed25519SignDriver(config) {
+  assert2.ok(config.privateKey || config.publicKeys?.length, "Ed25519 driver requires a privateKey and/or publicKeys");
+  const verifyKeys = [
+    ...config.privateKey ? [crypto.createPublicKey(config.privateKey)] : [],
+    ...(config.publicKeys ?? []).map((publicKey) => crypto.createPublicKey(publicKey))
+  ];
+  function sign(value) {
+    assert2.ok(config.privateKey, "This signer is verify-only \u2014 configure a privateKey to sign");
+    return crypto.sign(null, Buffer.from(value), config.privateKey).toString("base64url");
+  }
+  function verify(options) {
+    const provided = Buffer.from(options.signature, "base64url");
+    return verifyKeys.some((publicKey) => {
+      try {
+        return crypto.verify(null, Buffer.from(options.value), publicKey, provided);
+      } catch {
+        return false;
+      }
+    });
+  }
+  return { sign, verify };
+}
+
+// src/index.ts
+function create(driver) {
+  return {
+    sign: (value) => driver.sign(value),
+    verify: (options) => driver.verify(options)
+  };
+}
+var registry = ServiceRegistry.createRegistry(ServiceRegistry.proxyFunctionsForObject);
+var Provider = {
+  create,
+  register: registry.register
+};
+function provider(key) {
+  const service = registry.resolve(key);
+  return {
+    sign: service.sign,
+    verify: service.verify
+  };
+}
+var Sign = {
+  Provider,
+  ...provider("default"),
+  provider,
+  drivers: {
+    hmacSha256: hmacSha256SignDriver,
+    ed25519: ed25519SignDriver
+  }
+};
+export {
+  Sign
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@maestro-js/sign",
+  "description": "Signing and verification with driver-based algorithms (HMAC-SHA256, Ed25519) and key rotation for the maestro-js framework. Use when signing and verifying high-entropy values (token verifiers, signed URLs, webhook payloads, signed content another party must verify), rotating signing keys, or verifying a third party's Ed25519 signatures with a verify-only instance. Produces a bare, standard base64url signature — no key id or proprietary framing — that anyone can reproduce with stock crypto (e.g. `crypto.createHmac('sha256', Buffer.from(key, 'base64')).update(msg).digest('base64url')`). Key rotation via try-all-keys verification. This is signing (MAC / digital signature), distinct from password hashing (@maestro-js/hash) and encryption (@maestro-js/crypt).",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@maestro-js/service-registry": "1.0.0-alpha.30"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11"
+  },
+  "version": "1.0.0-alpha.30",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "beartest ./tests/**/*",
+    "format": "prettier --write src/ tests/",
+    "lint": "prettier --check src/ tests/"
+  }
+}