@streetjs/storage 1.0.0

package/dist/search.js

@@ -0,0 +1,172 @@
+/**
+ * @streetjs/storage — attribute search / filtering over the flat key space
+ * (task 18.1).
+ *
+ * Object stores expose only a flat key space plus per-object metadata, so
+ * search is implemented as a provider-agnostic filter over the two mandatory
+ * driver primitives {@link StorageDriver.list} and {@link StorageDriver.stat}:
+ *
+ * 1. Enumerate candidate keys with `driver.list(prefix)` (the prefix filter is
+ *    pushed down to the driver; an absent prefix lists the whole key space).
+ * 2. For each candidate, read its typed metadata with `driver.stat(key)`.
+ * 3. Keep the object only when it satisfies **every** supplied filter
+ *    (conjunctive / AND semantics — Requirement 16.2); when no object satisfies
+ *    the filters the result is the empty set (Requirement 16.3).
+ *
+ * The supported filters mirror {@link SearchFilters} (Requirement 16.1):
+ *
+ * - `prefix`         — key begins with the prefix (pushed to `driver.list`).
+ * - `contentType`    — exact content-type match.
+ * - `owner`          — exact owner match.
+ * - `tenant`         — exact tenant match.
+ * - `minSize`        — size ≥ minSize (inclusive lower bound).
+ * - `maxSize`        — size ≤ maxSize (inclusive upper bound).
+ * - `updatedAfter`   — updatedAt ≥ updatedAfter (inclusive lower time bound).
+ * - `updatedBefore`  — updatedAt ≤ updatedBefore (inclusive upper time bound).
+ * - `metadata`       — every supplied custom field deep-equals the object's
+ *                      corresponding `custom` field.
+ *
+ * Reserved internal key spaces used by the cross-cutting layers
+ * (`.versions/`, `.multipart/`, `.resumable/`, `.archive/`) are excluded from
+ * results unless the supplied `prefix` explicitly targets one of them, so a
+ * broad search returns only user-visible objects and never leaks framework
+ * bookkeeping keys.
+ *
+ * The result preserves the {@link StorageListItem} shape returned by
+ * `driver.list`, so `search` composes with the rest of the facade surface.
+ *
+ * _Requirements: 16.1, 16.2, 16.3_
+ */
+/**
+ * Reserved key prefixes that hold framework bookkeeping (version snapshots,
+ * multipart parts, resumable session bytes, archived copies). These are hidden
+ * from search results unless the caller explicitly searches within one of them.
+ */
+const RESERVED_KEY_PREFIXES = [
+    ".versions/",
+    ".multipart/",
+    ".resumable/",
+    ".archive/",
+];
+/**
+ * Return the stored objects that satisfy **every** supplied filter, evaluated
+ * over `driver.list` + `driver.stat`.
+ *
+ * The prefix filter is delegated to `driver.list`; the remaining filters are
+ * applied against each candidate's metadata. Objects whose metadata cannot be
+ * read (e.g. removed concurrently between `list` and `stat`) are skipped. When
+ * no object satisfies the filters, an empty array is returned (Requirement
+ * 16.3).
+ *
+ * @param driver  The storage driver to search over.
+ * @param filters The conjunctive set of {@link SearchFilters} to apply.
+ * @returns The matching objects as {@link StorageListItem}s.
+ */
+export async function searchObjects(driver, filters = {}) {
+    const prefix = filters.prefix ?? "";
+    const candidates = await driver.list(prefix);
+    const matches = [];
+    for (const item of candidates) {
+        // Defensive re-filter: never surface keys outside the requested prefix even
+        // if a driver interprets `list` loosely.
+        if (prefix !== "" && !item.key.startsWith(prefix)) {
+            continue;
+        }
+        // Hide reserved bookkeeping keys unless the search explicitly targets them.
+        if (isReservedKey(item.key) && !prefixTargetsReserved(prefix)) {
+            continue;
+        }
+        const metadata = await driver.stat(item.key);
+        if (metadata === null) {
+            // Object vanished between list and stat, or has no metadata — not a match.
+            continue;
+        }
+        if (matchesFilters(metadata, filters)) {
+            matches.push(item);
+        }
+    }
+    return matches;
+}
+/** Whether `key` lives in one of the reserved internal key spaces. */
+function isReservedKey(key) {
+    return RESERVED_KEY_PREFIXES.some((reserved) => key.startsWith(reserved));
+}
+/** Whether the requested `prefix` explicitly targets a reserved key space. */
+function prefixTargetsReserved(prefix) {
+    return RESERVED_KEY_PREFIXES.some((reserved) => prefix.startsWith(reserved));
+}
+/**
+ * Return true only when `metadata` satisfies every supplied filter (AND
+ * semantics). Absent filter fields impose no constraint.
+ */
+function matchesFilters(metadata, filters) {
+    if (filters.contentType !== undefined && metadata.contentType !== filters.contentType) {
+        return false;
+    }
+    if (filters.owner !== undefined && metadata.owner !== filters.owner) {
+        return false;
+    }
+    if (filters.tenant !== undefined && metadata.tenant !== filters.tenant) {
+        return false;
+    }
+    if (filters.minSize !== undefined && metadata.size < filters.minSize) {
+        return false;
+    }
+    if (filters.maxSize !== undefined && metadata.size > filters.maxSize) {
+        return false;
+    }
+    if (filters.updatedAfter !== undefined && metadata.updatedAt < filters.updatedAfter) {
+        return false;
+    }
+    if (filters.updatedBefore !== undefined && metadata.updatedAt > filters.updatedBefore) {
+        return false;
+    }
+    if (filters.metadata !== undefined && !matchesCustomMetadata(metadata.custom, filters.metadata)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Return true when every field required by `required` is present in the
+ * object's `custom` metadata and deep-equals the required value.
+ */
+function matchesCustomMetadata(custom, required) {
+    if (custom === null || typeof custom !== "object") {
+        return Object.keys(required).length === 0;
+    }
+    const source = custom;
+    for (const [field, value] of Object.entries(required)) {
+        if (!deepEqual(source[field], value)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Structural deep-equality used to compare custom metadata values. Handles
+ * primitives, arrays, and plain objects so nested custom fields compare by
+ * value rather than reference.
+ */
+function deepEqual(a, b) {
+    if (Object.is(a, b)) {
+        return true;
+    }
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) {
+        return false;
+    }
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
+            return false;
+        }
+        return a.every((element, index) => deepEqual(element, b[index]));
+    }
+    const aObj = a;
+    const bObj = b;
+    const aKeys = Object.keys(aObj);
+    const bKeys = Object.keys(bObj);
+    if (aKeys.length !== bKeys.length) {
+        return false;
+    }
+    return aKeys.every((key) => Object.prototype.hasOwnProperty.call(bObj, key) && deepEqual(aObj[key], bObj[key]));
+}
+//# sourceMappingURL=search.js.map

package/dist/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}

package/dist/signed-url.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @streetjs/storage — the signed URL service.
+ *
+ * A {@link Signed_URL} authorizes a single object operation (GET, PUT, or
+ * DELETE) on a single key until an expiry instant, letting clients act directly
+ * against storage without proxying through the application server
+ * (Requirement 8). {@link SignedUrlService} provides this capability in a
+ * **provider-agnostic** way:
+ *
+ * - When the backing {@link StorageDriver} implements the optional native
+ *   `signedUrl` capability, the service delegates minting and verification to
+ *   the driver so a provider with first-class signed-URL support (e.g. S3) is
+ *   used directly.
+ * - Otherwise the service **simulates** signed URLs with an HMAC computed over
+ *   the `(key, op, expiry)` tuple (plus the accepted options) using
+ *   `config.signingSecret` (`node:crypto` HMAC-SHA256), mirroring the zero-
+ *   dependency scheme described in the design. Verification recomputes the HMAC
+ *   and checks the expiry against an injected {@link Clock} (default
+ *   `systemClock`), so time is deterministic in tests (Requirement 8.3, 8.4).
+ *
+ * Semantics (Requirement 8):
+ * - {@link SignedUrlService.sign} mints a URL authorizing **exactly** the
+ *   requested operation on the given key (Requirement 8.1) and accepts options
+ *   for expiration, request headers, content type, maximum size, and custom
+ *   metadata (Requirement 8.2).
+ * - {@link SignedUrlService.verify} returns a {@link SignedUrlVerification}
+ *   whose `valid` flag is `true` only when the URL is well-formed, its signature
+ *   matches, its authorized operation matches the operation being attempted, and
+ *   it is used strictly before its expiry (Requirements 8.3, 8.4). Otherwise
+ *   `valid` is `false` with a `reason` of `'expired'`, `'operation-mismatch'`,
+ *   `'signature-mismatch'`, or `'malformed'`.
+ *
+ * The module depends only on the driver contract, the shared type surface, the
+ * error hierarchy, and `node:crypto`, keeping the dependency direction acyclic.
+ *
+ * _Requirements: 8.1, 8.2, 8.3, 8.4_
+ */
+import { type Clock } from "streetjs";
+import type { StorageDriver } from "./driver.js";
+import type { SignedOperation, SignedUrlOptions, SignedUrlVerification } from "./types.js";
+/** Options for constructing a {@link SignedUrlService}. */
+export interface SignedUrlServiceOptions {
+    /**
+     * The HMAC key used to sign and verify simulated URLs. Required for the
+     * simulated path; minting throws a {@link StorageConfigError} when it is
+     * absent and the driver has no native `signedUrl` capability.
+     */
+    readonly signingSecret?: string;
+    /** Injected clock for deterministic expiry checks in tests. Default `systemClock`. */
+    readonly clock?: Clock;
+    /**
+     * The backing driver. When it exposes a native `signedUrl` capability, minting
+     * and verification delegate to it instead of using the HMAC simulation.
+     */
+    readonly driver?: StorageDriver;
+}
+/**
+ * Provider-agnostic signed URL service built on the driver contract and an HMAC
+ * simulation.
+ *
+ * A single instance is held by the facade and bound to one {@link StorageDriver}
+ * for its lifetime, so the native-vs-simulated decision (based on whether the
+ * driver exposes a `signedUrl` capability) is stable across every call.
+ */
+export declare class SignedUrlService {
+    /** The HMAC signing secret for the simulated path, when configured. */
+    private readonly signingSecret?;
+    /** Injected clock used to stamp and check expiry. */
+    private readonly clock;
+    /** The driver's native signed-URL capability, when present. */
+    private readonly native?;
+    constructor(options?: SignedUrlServiceOptions);
+    /**
+     * Mint a URL authorizing **exactly** the operation `op` on `key`
+     * (Requirement 8.1). The URL carries the accepted options — expiration,
+     * request headers, content type, maximum size, and custom metadata
+     * (Requirement 8.2) — and, for the simulated path, an HMAC over the whole
+     * payload so its `(key, op, expiry)` tuple and options are tamper-evident.
+     *
+     * The expiry instant is computed from the injected clock plus
+     * `options.expiresInMs` (default {@link DEFAULT_EXPIRES_IN_MS}).
+     *
+     * @throws StorageConfigError when no native capability is available and no
+     *   `signingSecret` was configured, since a URL cannot be signed without a key.
+     */
+    sign(key: string, op: SignedOperation, options?: SignedUrlOptions): Promise<string>;
+    /**
+     * Verify a signed `url` for the operation being attempted, returning a
+     * {@link SignedUrlVerification}.
+     *
+     * `valid` is `true` only when the URL is well-formed, its signature matches,
+     * its authorized operation equals `expectedOp` (when supplied), and it is used
+     * strictly before its expiry relative to `now` (Requirements 8.3, 8.4). When
+     * `expectedOp` is omitted the operation check is skipped and only signature and
+     * expiry are enforced. `now` defaults to the injected clock so tests can drive
+     * expiry deterministically.
+     *
+     * Failure reasons are reported precisely: `'malformed'` for an unparseable
+     * URL, `'signature-mismatch'` for a tampered/incorrectly signed URL,
+     * `'operation-mismatch'` when the authorized op differs from `expectedOp`, and
+     * `'expired'` when `now` is at or after the expiry.
+     */
+    verify(url: string, expectedOp?: SignedOperation, now?: number): SignedUrlVerification;
+    /**
+     * Resolve the signing secret or throw a descriptive {@link StorageConfigError}.
+     * Used only on the simulated minting path, where a secret is mandatory.
+     */
+    private requireSigningSecret;
+}
+//# sourceMappingURL=signed-url.d.ts.map

package/dist/signed-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signed-url.d.ts","sourceRoot":"","sources":["../src/signed-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAKH,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,UAAU,CAAC;AAEnD,OAAO,KAAK,EAAuB,aAAa,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAoB3F,2DAA2D;AAC3D,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,sFAAsF;IACtF,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;CACjC;AA2BD;;;;;;;GAOG;AACH,qBAAa,gBAAgB;IAC3B,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAS;IAExC,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAE9B,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAsB;gBAElC,OAAO,GAAE,uBAA4B;IAMjD;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,eAAe,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC;IAyB7F;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,eAAe,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,qBAAqB;IA6CtF;;;OAGG;IACH,OAAO,CAAC,oBAAoB;CAS7B"}

package/dist/signed-url.js

@@ -0,0 +1,237 @@
+/**
+ * @streetjs/storage — the signed URL service.
+ *
+ * A {@link Signed_URL} authorizes a single object operation (GET, PUT, or
+ * DELETE) on a single key until an expiry instant, letting clients act directly
+ * against storage without proxying through the application server
+ * (Requirement 8). {@link SignedUrlService} provides this capability in a
+ * **provider-agnostic** way:
+ *
+ * - When the backing {@link StorageDriver} implements the optional native
+ *   `signedUrl` capability, the service delegates minting and verification to
+ *   the driver so a provider with first-class signed-URL support (e.g. S3) is
+ *   used directly.
+ * - Otherwise the service **simulates** signed URLs with an HMAC computed over
+ *   the `(key, op, expiry)` tuple (plus the accepted options) using
+ *   `config.signingSecret` (`node:crypto` HMAC-SHA256), mirroring the zero-
+ *   dependency scheme described in the design. Verification recomputes the HMAC
+ *   and checks the expiry against an injected {@link Clock} (default
+ *   `systemClock`), so time is deterministic in tests (Requirement 8.3, 8.4).
+ *
+ * Semantics (Requirement 8):
+ * - {@link SignedUrlService.sign} mints a URL authorizing **exactly** the
+ *   requested operation on the given key (Requirement 8.1) and accepts options
+ *   for expiration, request headers, content type, maximum size, and custom
+ *   metadata (Requirement 8.2).
+ * - {@link SignedUrlService.verify} returns a {@link SignedUrlVerification}
+ *   whose `valid` flag is `true` only when the URL is well-formed, its signature
+ *   matches, its authorized operation matches the operation being attempted, and
+ *   it is used strictly before its expiry (Requirements 8.3, 8.4). Otherwise
+ *   `valid` is `false` with a `reason` of `'expired'`, `'operation-mismatch'`,
+ *   `'signature-mismatch'`, or `'malformed'`.
+ *
+ * The module depends only on the driver contract, the shared type surface, the
+ * error hierarchy, and `node:crypto`, keeping the dependency direction acyclic.
+ *
+ * _Requirements: 8.1, 8.2, 8.3, 8.4_
+ */
+import { Buffer } from "node:buffer";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { systemClock } from "streetjs";
+import { StorageConfigError } from "./errors.js";
+/**
+ * The scheme prefix of a simulated signed URL. The remainder of the URL is
+ * `<base64url(payload)>.<hmacHex>`, where neither component can contain a `.`
+ * (base64url has no `.`; a hex digest has no `.`), so the last `.` is an
+ * unambiguous separator.
+ */
+const SIGNED_URL_SCHEME = "streetjs-signed://";
+/** The HMAC digest algorithm used to sign simulated URLs. */
+const HMAC_ALGORITHM = "sha256";
+/**
+ * The default validity window for a minted URL when `options.expiresInMs` is
+ * omitted (15 minutes). Chosen to be short-lived by default so an accidentally
+ * leaked URL is only briefly usable.
+ */
+const DEFAULT_EXPIRES_IN_MS = 15 * 60 * 1000;
+/**
+ * Provider-agnostic signed URL service built on the driver contract and an HMAC
+ * simulation.
+ *
+ * A single instance is held by the facade and bound to one {@link StorageDriver}
+ * for its lifetime, so the native-vs-simulated decision (based on whether the
+ * driver exposes a `signedUrl` capability) is stable across every call.
+ */
+export class SignedUrlService {
+    /** The HMAC signing secret for the simulated path, when configured. */
+    signingSecret;
+    /** Injected clock used to stamp and check expiry. */
+    clock;
+    /** The driver's native signed-URL capability, when present. */
+    native;
+    constructor(options = {}) {
+        this.signingSecret = options.signingSecret;
+        this.clock = options.clock ?? systemClock;
+        this.native = options.driver?.signedUrl;
+    }
+    /**
+     * Mint a URL authorizing **exactly** the operation `op` on `key`
+     * (Requirement 8.1). The URL carries the accepted options — expiration,
+     * request headers, content type, maximum size, and custom metadata
+     * (Requirement 8.2) — and, for the simulated path, an HMAC over the whole
+     * payload so its `(key, op, expiry)` tuple and options are tamper-evident.
+     *
+     * The expiry instant is computed from the injected clock plus
+     * `options.expiresInMs` (default {@link DEFAULT_EXPIRES_IN_MS}).
+     *
+     * @throws StorageConfigError when no native capability is available and no
+     *   `signingSecret` was configured, since a URL cannot be signed without a key.
+     */
+    async sign(key, op, options = {}) {
+        if (this.native !== undefined) {
+            return this.native.sign(key, op, options);
+        }
+        const secret = this.requireSigningSecret();
+        const expiresInMs = options.expiresInMs ?? DEFAULT_EXPIRES_IN_MS;
+        const expiry = this.clock() + expiresInMs;
+        const payload = {
+            v: 1,
+            key,
+            op,
+            expiry,
+            ...(options.headers !== undefined ? { headers: options.headers } : {}),
+            ...(options.contentType !== undefined ? { contentType: options.contentType } : {}),
+            ...(options.maxSize !== undefined ? { maxSize: options.maxSize } : {}),
+            ...(options.metadata !== undefined ? { metadata: options.metadata } : {}),
+        };
+        const encoded = encodePayload(payload);
+        const signature = hmacHex(secret, encoded);
+        return `${SIGNED_URL_SCHEME}${encoded}.${signature}`;
+    }
+    /**
+     * Verify a signed `url` for the operation being attempted, returning a
+     * {@link SignedUrlVerification}.
+     *
+     * `valid` is `true` only when the URL is well-formed, its signature matches,
+     * its authorized operation equals `expectedOp` (when supplied), and it is used
+     * strictly before its expiry relative to `now` (Requirements 8.3, 8.4). When
+     * `expectedOp` is omitted the operation check is skipped and only signature and
+     * expiry are enforced. `now` defaults to the injected clock so tests can drive
+     * expiry deterministically.
+     *
+     * Failure reasons are reported precisely: `'malformed'` for an unparseable
+     * URL, `'signature-mismatch'` for a tampered/incorrectly signed URL,
+     * `'operation-mismatch'` when the authorized op differs from `expectedOp`, and
+     * `'expired'` when `now` is at or after the expiry.
+     */
+    verify(url, expectedOp, now) {
+        if (this.native !== undefined) {
+            return this.native.verify(url, now ?? this.clock());
+        }
+        const secret = this.signingSecret;
+        if (secret === undefined) {
+            // Without a secret no simulated URL could have been minted, so any URL is
+            // treated as unverifiable rather than silently valid.
+            return { valid: false, reason: "malformed" };
+        }
+        const parsed = parseSignedUrl(url);
+        if (parsed === undefined) {
+            return { valid: false, reason: "malformed" };
+        }
+        const { encoded, signature } = parsed;
+        const expected = hmacHex(secret, encoded);
+        if (!timingSafeEqualHex(signature, expected)) {
+            return { valid: false, reason: "signature-mismatch" };
+        }
+        const payload = decodePayload(encoded);
+        if (payload === undefined) {
+            return { valid: false, reason: "malformed" };
+        }
+        if (expectedOp !== undefined && payload.op !== expectedOp) {
+            return {
+                valid: false,
+                reason: "operation-mismatch",
+                key: payload.key,
+                op: payload.op,
+            };
+        }
+        const at = now ?? this.clock();
+        if (at >= payload.expiry) {
+            return { valid: false, reason: "expired", key: payload.key, op: payload.op };
+        }
+        return { valid: true, key: payload.key, op: payload.op };
+    }
+    /**
+     * Resolve the signing secret or throw a descriptive {@link StorageConfigError}.
+     * Used only on the simulated minting path, where a secret is mandatory.
+     */
+    requireSigningSecret() {
+        if (this.signingSecret === undefined || this.signingSecret === "") {
+            throw new StorageConfigError("Signed URLs require a non-empty \"signingSecret\" in the storage configuration " +
+                "when the driver has no native signed-URL capability.");
+        }
+        return this.signingSecret;
+    }
+}
+/** Encode a payload as a compact base64url JSON string. */
+function encodePayload(payload) {
+    return Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+}
+/** Decode a base64url JSON payload, returning `undefined` when it is malformed. */
+function decodePayload(encoded) {
+    try {
+        const json = Buffer.from(encoded, "base64url").toString("utf8");
+        const value = JSON.parse(json);
+        if (!isSignedPayload(value)) {
+            return undefined;
+        }
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Structural guard that a decoded value carries the required payload fields. */
+function isSignedPayload(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return (candidate.v === 1 &&
+        typeof candidate.key === "string" &&
+        (candidate.op === "GET" || candidate.op === "PUT" || candidate.op === "DELETE") &&
+        typeof candidate.expiry === "number" &&
+        Number.isFinite(candidate.expiry));
+}
+/**
+ * Parse a simulated signed URL into its encoded payload and signature, returning
+ * `undefined` when the scheme is wrong or the separator is missing.
+ */
+function parseSignedUrl(url) {
+    if (typeof url !== "string" || !url.startsWith(SIGNED_URL_SCHEME)) {
+        return undefined;
+    }
+    const body = url.slice(SIGNED_URL_SCHEME.length);
+    const separator = body.lastIndexOf(".");
+    if (separator <= 0 || separator >= body.length - 1) {
+        return undefined;
+    }
+    return { encoded: body.slice(0, separator), signature: body.slice(separator + 1) };
+}
+/** Compute the lowercase HMAC-SHA256 hex digest of `data` under `secret`. */
+function hmacHex(secret, data) {
+    return createHmac(HMAC_ALGORITHM, secret).update(data).digest("hex");
+}
+/**
+ * Constant-time comparison of two hex signature strings. Falls back to `false`
+ * for length mismatches (which `timingSafeEqual` would otherwise throw on).
+ */
+function timingSafeEqualHex(a, b) {
+    const bufferA = Buffer.from(a, "utf8");
+    const bufferB = Buffer.from(b, "utf8");
+    if (bufferA.length !== bufferB.length) {
+        return false;
+    }
+    return timingSafeEqual(bufferA, bufferB);
+}
+//# sourceMappingURL=signed-url.js.map

package/dist/signed-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signed-url.js","sourceRoot":"","sources":["../src/signed-url.ts"],"names":[],"mappings":"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"}