@beignet/core 0.0.42 → 0.0.44

package/src/ports/storage.ts

@@ -139,6 +139,126 @@ export interface StoragePort {
   publicUrl(key: string): Promise<string | null>;
 }
 
+/**
+ * Options for prefixing one validated storage key.
+ */
+export interface PrefixStorageKeyOptions {
+  /**
+   * Optional app or environment prefix. Leading and trailing slashes are
+   * removed before it is applied.
+   */
+  keyPrefix?: string;
+  /**
+   * Relative object key to prefix.
+   */
+  key: string;
+}
+
+/**
+ * Options for formatting a public storage URL.
+ */
+export interface CreateStoragePublicUrlOptions {
+  /**
+   * Absolute or app-relative public base URL.
+   */
+  publicBaseUrl: string;
+  /**
+   * Relative object key appended to the public base URL.
+   */
+  key: string;
+}
+
+function hasControlCharacter(value: string): boolean {
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (code <= 31 || code === 127) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Assert that a storage key follows Beignet's provider-neutral key rules.
+ *
+ * Valid keys are non-empty relative object paths. They do not contain control
+ * characters, backslashes, empty path segments, or `.` / `..` segments.
+ * Providers may enforce additional adapter-specific restrictions after this
+ * shared assertion.
+ */
+export function assertValidStorageKey(key: string): void {
+  if (key.length === 0) {
+    throw new Error("Storage key must not be empty.");
+  }
+
+  if (hasControlCharacter(key)) {
+    throw new Error("Storage key must not include control characters.");
+  }
+
+  if (key.startsWith("/")) {
+    throw new Error("Storage key must not start with '/'.");
+  }
+
+  if (key.endsWith("/")) {
+    throw new Error("Storage key must not end with '/'.");
+  }
+
+  if (key.includes("\\")) {
+    throw new Error("Storage key must use '/' separators, not '\\'.");
+  }
+
+  const segments = key.split("/");
+
+  if (segments.some((segment) => segment === "")) {
+    throw new Error("Storage key must not include empty path segments.");
+  }
+
+  if (segments.some((segment) => segment === "." || segment === "..")) {
+    throw new Error("Storage key must not include '.' or '..' segments.");
+  }
+}
+
+/**
+ * Normalize and validate an optional storage key prefix.
+ *
+ * Empty and slash-only prefixes normalize to an empty string.
+ */
+export function normalizeStorageKeyPrefix(prefix: string | undefined): string {
+  if (!prefix) return "";
+  const normalized = prefix.replace(/^\/+|\/+$/g, "");
+  if (!normalized) return "";
+  assertValidStorageKey(normalized);
+  return normalized;
+}
+
+/**
+ * Prefix a storage key with an optional app or environment namespace.
+ */
+export function prefixStorageKey({
+  keyPrefix,
+  key,
+}: PrefixStorageKeyOptions): string {
+  const normalizedPrefix = normalizeStorageKeyPrefix(keyPrefix);
+  assertValidStorageKey(key);
+  return normalizedPrefix ? `${normalizedPrefix}/${key}` : key;
+}
+
+/**
+ * Format an encoded public URL for a validated storage key.
+ */
+export function createStoragePublicUrl({
+  publicBaseUrl,
+  key,
+}: CreateStoragePublicUrlOptions): string {
+  assertValidStorageKey(key);
+  const base = publicBaseUrl.replace(/\/+$/, "");
+  const encodedKey = key
+    .split("/")
+    .map((part) => encodeURIComponent(part))
+    .join("/");
+
+  return `${base}/${encodedKey}`;
+}
+
 /**
  * Options for `createMemoryStorage(...)`.
  */
@@ -271,44 +391,6 @@ function createObjectBody(entry: MemoryStorageEntry): StorageObjectBody {
   };
 }
 
-function validateStorageKey(key: string): void {
-  if (key.length === 0) {
-    throw new Error("Storage key must not be empty.");
-  }
-
-  if (key.startsWith("/")) {
-    throw new Error("Storage key must not start with '/'.");
-  }
-
-  if (key.endsWith("/")) {
-    throw new Error("Storage key must not end with '/'.");
-  }
-
-  if (key.includes("\\")) {
-    throw new Error("Storage key must use '/' separators, not '\\'.");
-  }
-
-  const segments = key.split("/");
-
-  if (segments.some((segment) => segment === "")) {
-    throw new Error("Storage key must not include empty path segments.");
-  }
-
-  if (segments.some((segment) => segment === "." || segment === "..")) {
-    throw new Error("Storage key must not include '.' or '..' segments.");
-  }
-}
-
-function joinPublicUrl(baseUrl: string, key: string): string {
-  const base = baseUrl.replace(/\/+$/, "");
-  const encodedKey = key
-    .split("/")
-    .map((part) => encodeURIComponent(part))
-    .join("/");
-
-  return `${base}/${encodedKey}`;
-}
-
 /**
  * Create an in-memory object storage adapter for tests, examples, and
  * single-process development.
@@ -326,7 +408,7 @@ export function createMemoryStorage(
 
   return {
     async put(key, body, putOptions) {
-      validateStorageKey(key);
+      assertValidStorageKey(key);
       const bytes = await storageBodyToBytes(body);
       const entry: MemoryStorageEntry = {
         key,
@@ -348,35 +430,38 @@ export function createMemoryStorage(
       return cloneObject(entry);
     },
     async get(key) {
-      validateStorageKey(key);
+      assertValidStorageKey(key);
       const entry = objects.get(key);
       if (!entry) return null;
 
       return createObjectBody(entry);
     },
     async stat(key) {
-      validateStorageKey(key);
+      assertValidStorageKey(key);
       const entry = objects.get(key);
       if (!entry) return null;
 
       return cloneObject(entry);
     },
     async delete(key) {
-      validateStorageKey(key);
+      assertValidStorageKey(key);
       return objects.delete(key);
     },
     async exists(key) {
-      validateStorageKey(key);
+      assertValidStorageKey(key);
       return objects.has(key);
     },
     async publicUrl(key) {
-      validateStorageKey(key);
+      assertValidStorageKey(key);
       const entry = objects.get(key);
-      if (!entry || entry.visibility !== "public" || !options.publicBaseUrl) {
+      if (entry?.visibility !== "public" || !options.publicBaseUrl) {
         return null;
       }
 
-      return joinPublicUrl(options.publicBaseUrl, key);
+      return createStoragePublicUrl({
+        publicBaseUrl: options.publicBaseUrl,
+        key,
+      });
     },
   };
 }

package/src/server/hooks/idempotency.ts

@@ -58,8 +58,9 @@ export interface IdempotencyHooksOptions<Ctx> {
   /**
    * Build the idempotency scope after context exists.
    *
-   * Defaults to a scope derived from `meta.scope`: `"global"` stays global,
-   * `"actor"` scopes by `ctx.actor?.id`, `"tenant"` scopes by `ctx.tenant?.id`,
+   * Defaults to a scope derived from `meta.scope`: omitted metadata scopes by
+   * `ctx.actor?.id` and also `ctx.tenant?.id` when present, `"actor"` scopes by
+   * the actor only, `"global"` stays global, `"tenant"` scopes by the tenant,
    * and `"actor-tenant"` scopes by both.
    */
   scope?: (args: {
@@ -97,7 +98,7 @@ function defaultIdempotencyScope(
   ctx: CtxWithIdempotency,
   meta: IdempotencyMeta,
 ): IdempotencyScope {
-  const mode = meta.scope ?? "global";
+  const mode = meta.scope ?? (ctx.tenant?.id ? "actor-tenant" : "actor");
 
   switch (mode) {
     case "global":

package/src/uploads/index.ts

@@ -1037,63 +1037,69 @@ export function createUploadRouter<Ctx>(
 
       const completed: CompletedUploadFile[] = [];
       const storedKeys: string[] = [];
-      for (const [index, file] of webFiles.entries()) {
-        const intent = intents[index];
-        if (!intent) continue;
-        const verified = await verifyBlobUploadFile(definition, intent, file);
-        const verifiedIntent = {
-          ...intent,
-          ...(verified.checksum ? { checksum: verified.checksum } : {}),
-        };
-        const uploadId = id();
-        await assertAuthorized(definition, {
-          ctx,
-          metadata,
-          file: verifiedIntent,
-          uploadId,
-        });
-        const key = await definition.key({
-          ctx,
-          metadata,
-          file: verifiedIntent,
-          uploadId,
-        });
-        const storageMetadata =
-          (await definition.storageMetadata?.({
+      try {
+        for (const [index, file] of webFiles.entries()) {
+          const intent = intents[index];
+          if (!intent) continue;
+          const uploadId = id();
+          await assertAuthorized(definition, {
+            ctx,
+            metadata,
+            file: intent,
+            uploadId,
+          });
+          const verified = await verifyBlobUploadFile(definition, intent, file);
+          const verifiedIntent = {
+            ...intent,
+            ...(verified.checksum ? { checksum: verified.checksum } : {}),
+          };
+          const key = await definition.key({
             ctx,
             metadata,
             file: verifiedIntent,
             uploadId,
-          })) ?? {};
-        const object = await options.storage.put(key, file, {
-          contentType: verifiedIntent.contentType,
-          ...(definition.file.cacheControl !== undefined
-            ? { cacheControl: definition.file.cacheControl }
-            : {}),
-          metadata: storageMetadata,
-          visibility: definition.file.visibility ?? "private",
-        });
-        storedKeys.push(key);
-        const completedFile = {
-          ...verifiedIntent,
-          uploadId,
-          key,
-          object,
-        };
-        try {
+          });
+          const storageMetadata =
+            (await definition.storageMetadata?.({
+              ctx,
+              metadata,
+              file: verifiedIntent,
+              uploadId,
+            })) ?? {};
+          const object = await options.storage.put(key, file, {
+            contentType: verifiedIntent.contentType,
+            ...(definition.file.cacheControl !== undefined
+              ? { cacheControl: definition.file.cacheControl }
+              : {}),
+            metadata: storageMetadata,
+            visibility: definition.file.visibility ?? "private",
+          });
+          storedKeys.push(key);
+          const completedFile = {
+            ...verifiedIntent,
+            uploadId,
+            key,
+            object,
+          };
           await assertVerifiedFile(definition, {
             ctx,
             metadata,
             file: completedFile,
             storage: options.storage,
           });
-        } catch (error) {
+          completed.push(completedFile);
+        }
+      } catch (error) {
+        if (storedKeys.length > 0) {
           await cleanupRejectedServerUpload(uploadName, storedKeys);
-          throw error;
         }
-        completed.push(completedFile);
+        throw error;
       }
 
+      // Once app-owned completion begins, the app may persist durable references
+      // to these objects. The framework can no longer delete them safely if a
+      // later completion step fails; transaction or compensation belongs to the
+      // app from this point forward.
       const result = await definition.onComplete?.({
         ctx,
         metadata,