@maestro-js/signed-url 1.0.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+import { Iso } from 'iso-fns2';
+
+declare function create(config: SignedUrl.Provider.Config): SignedUrl.SignedUrlService;
+declare function provider(key: SignedUrl.Provider.Key): SignedUrl.SignedUrlService;
+type KeysWithFallback = keyof SignedUrl.Provider.Keys extends never ? {
+    default: unknown;
+} : SignedUrl.Provider.Keys;
+/**
+ * URL signing and verification backed by a hash service.
+ * Call methods directly on the default instance, or use `SignedUrl.Provider.create()` for named instances.
+ */
+declare const SignedUrl: {
+    provider: typeof provider;
+    /** Signs URL search params with an expiration duration (or `null` for never-expiring), returning new params with `_signature` and optionally `_expires` */
+    signURL: (params: URLSearchParams, expiration: Iso.Duration | null) => Promise<URLSearchParams>;
+    /** Checks whether signed URL search params have a valid signature — verifies expiration (if present) and the signature */
+    hasValidSignature: (params: URLSearchParams) => Promise<boolean>;
+    /** Checks whether the signature would be valid if the supplied search params were ignored */
+    hasValidSignatureWhileIgnoring: (params: URLSearchParams, ignoreParams: string[]) => Promise<boolean>;
+    Provider: {
+        create: typeof create;
+        register: (name: SignedUrl.Provider.Key, item: SignedUrl.SignedUrlService) => void;
+    };
+};
+/**
+ * URL signing and verification backed by a hash service.
+ *
+ * Signs URL search params with an HMAC signature and an expiration timestamp,
+ * then verifies them on the receiving end. Accepts the `Hash` facade or any
+ * object that conforms to the `Hash.HashService` interface.
+ *
+ * @example
+ * ```ts
+ * SignedUrl.Provider.register('default', SignedUrl.Provider.create({ driver: Hash }))
+ *
+ * const signed = await SignedUrl.signURL(new URLSearchParams({ token: 'abc' }), 'PT1H')
+ * await SignedUrl.hasValidSignature(signed) // true
+ * ```
+ */
+declare namespace SignedUrl {
+    /** Any object with `hash` and `verify` methods — the `Hash` facade or a `Hash.HashService` instance both satisfy this */
+    type Driver = {
+        hash: (value: string) => Promise<string>;
+        verify: (options: {
+            plaintext: string;
+            hash: string;
+        }) => Promise<boolean>;
+    };
+    namespace Provider {
+        type Key = keyof KeysWithFallback;
+        interface Keys {
+        }
+        interface Config {
+            driver: Driver;
+        }
+    }
+    interface SignedUrlService {
+        /** Signs URL search params with an expiration duration (or `null` for never-expiring), returning new params with `_signature` and optionally `_expires` */
+        signURL: (params: URLSearchParams, expiration: Iso.Duration | null) => Promise<URLSearchParams>;
+        /** Checks whether signed URL search params have a valid signature — verifies expiration (if present) and the signature */
+        hasValidSignature: (params: URLSearchParams) => Promise<boolean>;
+        /** Checks whether the signature would be valid if the supplied search params were ignored */
+        hasValidSignatureWhileIgnoring: (params: URLSearchParams, ignoreParams: string[]) => Promise<boolean>;
+    }
+}
+
+export { SignedUrl };

package/dist/index.js

@@ -0,0 +1,69 @@
+// src/index.ts
+import { ServiceRegistry } from "@maestro-js/service-registry";
+import { instantFns } from "iso-fns2";
+var SIGNATURE_PARAM = "_signature";
+var EXPIRES_PARAM = "_expires";
+function create(config) {
+  async function signURL(params, expiration) {
+    const signed = new URLSearchParams(params);
+    signed.delete(SIGNATURE_PARAM);
+    signed.delete(EXPIRES_PARAM);
+    if (expiration !== null) {
+      const expiresAt = instantFns.add(instantFns.now(), expiration);
+      signed.set(EXPIRES_PARAM, expiresAt);
+    }
+    const canonical = buildCanonicalString(signed);
+    const signature = await config.driver.hash(canonical);
+    signed.set(SIGNATURE_PARAM, signature);
+    return signed;
+  }
+  async function hasValidSignature(params) {
+    const copy = new URLSearchParams(params);
+    const signature = copy.get(SIGNATURE_PARAM);
+    const expires = copy.get(EXPIRES_PARAM);
+    if (!signature) return false;
+    if (expires && instantFns.now() >= expires) return false;
+    copy.delete(SIGNATURE_PARAM);
+    const canonical = buildCanonicalString(copy);
+    return config.driver.verify({ plaintext: canonical, hash: signature });
+  }
+  async function hasValidSignatureWhileIgnoring(params, ignoreParams) {
+    const copy = new URLSearchParams(params);
+    for (const param of ignoreParams) {
+      copy.delete(param);
+    }
+    return hasValidSignature(copy);
+  }
+  function buildCanonicalString(params) {
+    params.sort();
+    return params.toString();
+  }
+  return {
+    signURL,
+    hasValidSignature,
+    hasValidSignatureWhileIgnoring
+  };
+}
+var registry = ServiceRegistry.createRegistry(
+  ServiceRegistry.proxyFunctionsForObject
+);
+var Provider = {
+  create,
+  register: registry.register
+};
+function provider(key) {
+  const service = registry.resolve(key);
+  return {
+    signURL: service.signURL,
+    hasValidSignature: service.hasValidSignature,
+    hasValidSignatureWhileIgnoring: service.hasValidSignatureWhileIgnoring
+  };
+}
+var SignedUrl = {
+  Provider,
+  ...provider("default"),
+  provider
+};
+export {
+  SignedUrl
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@maestro-js/signed-url",
+  "description": "URL signing and verification with pluggable hash drivers for @maestro-js/signed-url. Use when generating tamper-proof signed URLs with expiration (e.g. file download links, email verification) or validating signed URL parameters. Accepts any hash driver compatible with @maestro-js/hash.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "iso-fns2": "npm:iso-fns@2.0.0-alpha.26",
+    "@maestro-js/service-registry": "1.0.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11",
+    "@maestro-js/hash": "1.0.0-alpha.0"
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "beartest ./tests/**/*",
+    "format": "prettier --write src/ tests/",
+    "lint": "prettier --check src/ tests/"
+  }
+}