Add content overwrite support (#415)

# Add Content Overwrite Support for Attachments

### New Feature

✨ Introduces configurable content overwrite behavior for the
`@cap-js/attachments` plugin. By default, attachment content is
protected from being overwritten (returning a `409 Conflict` error).
Users can now opt-in to allow content overwrites on a per-composition
basis using the
`@Capabilities.UpdateRestrictions.NonUpdateableProperties` annotation.

### Changes

* `db/index.cds`: Added default annotation
`@Capabilities.UpdateRestrictions.NonUpdateableProperties: [content]` to
the `Attachments` aspect, preventing content overwrites out of the box.

* `srv/basic.js`: Introduced the `_isContentUpdateRestricted()` helper
method that inspects the
`@Capabilities.UpdateRestrictions.NonUpdateableProperties` annotation on
an attachment entity. The existing 409-conflict check in `put()` is now
gated behind this helper, so the restriction is only enforced when the
annotation includes `content`.

* `srv/aws-s3.js`, `srv/azure-blob-storage.js`, `srv/gcp.js`: Updated
the `put()` upload guard in all three storage backends to call
`_isContentUpdateRestricted()` before checking for an existing file,
enabling overwrite behavior when the annotation allows it.

* `tests/incidents-app/db/attachments.cds`: Added a new
`overwritableAttachments` composition annotated with
`@Capabilities.UpdateRestrictions.NonUpdateableProperties: []` for
testing the opt-in overwrite scenario.

* `tests/integration/attachments-non-draft.test.js`: Added an
integration test that verifies content can be successfully overwritten
when the annotation is set to an empty array.

* `README.md`: Added a new **Allow Overwriting Attachment Content**
section documenting the feature, including a CDS example and a note
about runtime evaluation across storage backends. Also updated the Table
of Contents.

* `CHANGELOG.md`: Documented the new feature under version `3.11.0`.

* `package.json`: Bumped version from `3.10.0` to `3.11.0`.

- [ ] 🔄 Regenerate and Update Summary


---
📬 [Subscribe to the Hyperspace PR Bot DL](https://url.sap/451kgs) to get
the latest announcements and pilot features!


<details>
<summary>PR Bot Information</summary>

**Version:** `1.19.15` | 📖 [Documentation](https://url.sap/dy9ocn) | 🚨
[Create Incident](https://url.sap/budnv9) | 💬
[Feedback](https://url.sap/my4dn3)

- Output Template: [Default
Template](https://github.tools.sap/intelligent-insights/i2-pull-request/blob/main/src/services/llm/prompts/summary_default_output_template.md)
- Summary Prompt: [Default
Prompt](https://github.tools.sap/intelligent-insights/i2-pull-request/blob/main/src/services/llm/prompts/summary_instructions_prompt.md)
- File Content Strategy: Full file content
- LLM: `anthropic--claude-4.6-sonnet`
- Correlation ID: `5ade5400-2e74-11f1-9f6b-5a4534e5aad0`
- Event Trigger: `pull_request.opened`
</details>

---------

Co-authored-by: Marten Schiwek <marten.schiwek@sap.com>

Author: KoblerS

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
+## Version 3.11.0
+
+### Added
+
+- Support for controlling content overwrite behavior via `@Capabilities.UpdateRestrictions.NonUpdateableProperties`. By default, `content` is listed as non-updateable, preventing overwrites with a `409` error. Setting the annotation to an empty array (`[]`) on a specific attachment composition allows content to be overwritten.
+
+### Fixed
+
 ## Version 3.10.0
 
 ### Added

README.md

@@ -17,15 +17,18 @@ The `@cap-js/attachments` package is a [CDS plugin](https://cap.cloud.sap/docs/n
     - [Storage Targets](#storage-targets)
     - [Malware Scanner](#malware-scanner)
       - [Automatic file rescanning](#automatic-file-rescanning)
+    - [Audit logging](#audit-logging)
     - [Visibility Control for Attachments UI Facet Generation](#visibility-control-for-attachments-ui-facet-generation)
       - [Example Usage](#example-usage)
-    - [Non-Draft Upload](#non-draft-upload)
     - [Copying Attachments](#copying-attachments)
+      - [Examples](#examples)
+    - [Non-Draft Upload](#non-draft-upload)
     - [Specify the maximum file size](#specify-the-maximum-file-size)
     - [Restrict allowed MIME types](#restrict-allowed-mime-types)
     - [Minimum and Maximum Number of Attachments](#minimum-and-maximum-number-of-attachments)
       - [Limit to a Maximum of 2 Attachments](#limit-to-a-maximum-of-2-attachments)
       - [Require a Minimum of 2 Attachments](#require-a-minimum-of-2-attachments)
+    - [Allow Overwriting Attachment Content](#allow-overwriting-attachment-content)
   - [Releases](#releases)
   - [Minimum UI5 and CAP NodeJS Version](#minimum-ui5-and-cap-nodejs-version)
   - [Architecture Overview](#architecture-overview)
@@ -446,6 +449,30 @@ entity Incidents {
 }
 ```
 
+### Allow Overwriting Attachment Content
+
+By default, the `Attachments` aspect annotates the entity with `@Capabilities.UpdateRestrictions.NonUpdateableProperties: [content]`, which prevents overwriting the content of an existing attachment. Any attempt to upload new content to an attachment that already has content will be rejected with a `409 Conflict` error.
+
+To allow overwriting attachment content, override the annotation with an empty array on the specific attachment composition:
+
+```cds
+using { Attachments } from '@cap-js/attachments';
+
+entity Incidents {
+  ...
+  attachments: Composition of many Attachments;
+}
+
+// Allow content to be overwritten
+annotate Incidents.attachments with
+  @Capabilities.UpdateRestrictions.NonUpdateableProperties: [] {};
+```
+
+With this annotation in place, uploading new content via `PUT` to an attachment that already has content will overwrite the existing content instead of returning a `409` error.
+
+> [!NOTE]
+> This annotation is evaluated at runtime by all storage backends. When content overwrite is allowed, uploading to an existing attachment replaces the stored file.
+
 ## Releases
 
 - The plugin is released to [NPM Registry](https://www.npmjs.com/package/@cap-js/attachments).

db/index.cds

@@ -38,6 +38,10 @@ context sap.attachments {
     note : String  @title: '{i18n>Note}'  @UI.MultiLineText;
   }
 
+  annotate Attachments with @Capabilities.UpdateRestrictions.NonUpdateableProperties : [
+    content
+  ];
+
 
   // -- Fiori Annotations ----------------------------------------------------------
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cap-js/attachments",
   "description": "CAP cds-plugin providing image and attachment storing out-of-the-box.",
-  "version": "3.10.0",
+  "version": "3.11.0",
   "repository": "cap-js/attachments",
   "author": "SAP SE (https://www.sap.com)",
   "homepage": "https://cap.cloud.sap/",

srv/aws-s3.js

@@ -171,7 +171,10 @@ module.exports = class AWSAttachmentsService extends require("./object-store") {
         return
       }
 
-      if (await this.exists(Key)) {
+      if (
+        this._isContentUpdateRestricted(attachments) &&
+        (await this.exists(Key))
+      ) {
         const error = new Error("Attachment already exists")
         error.status = 409
         throw error

srv/azure-blob-storage.js

@@ -156,7 +156,10 @@ module.exports = class AzureAttachmentsService extends (
 
       const blobClient = containerClient.getBlockBlobClient(blobName)
 
-      if (await this.exists(blobName)) {
+      if (
+        this._isContentUpdateRestricted(attachments) &&
+        (await this.exists(blobName))
+      ) {
         const error = new Error("Attachment already exists")
         error.status = 409
         throw error

srv/basic.js

@@ -70,6 +70,28 @@ class AttachmentsService extends cds.Service {
     return super.init()
   }
 
+  /**
+   * Checks whether content updates are restricted for the given attachment entity.
+   * Returns true if `content` is listed in @Capabilities.UpdateRestrictions.NonUpdateableProperties,
+   * meaning overwriting existing content is NOT allowed.
+   * Returns false if the annotation is missing, is an empty array, or does not include `content`.
+   * @param {import('@sap/cds').Entity} attachments - Attachments entity definition
+   * @returns {boolean}
+   */
+  _isContentUpdateRestricted(attachments) {
+    const nonUpdateable =
+      attachments["@Capabilities.UpdateRestrictions.NonUpdateableProperties"]
+    // If annotation is not set, allow content overwrite by default
+    if (!nonUpdateable) return false
+    // If it's an array, check if 'content' is listed
+    if (Array.isArray(nonUpdateable)) {
+      return nonUpdateable.some(
+        (prop) => prop === "content" || prop?.["="] === "content",
+      )
+    }
+    return false
+  }
+
   /**
    * Uploads attachments to the database and initiates malware scans for database-stored files
    * @param {import('@sap/cds').Entity} attachments - Attachments entity definition
@@ -81,14 +103,16 @@ class AttachmentsService extends cds.Service {
       data = [data]
     }
 
-    // Check if an attachment with this ID already has content
-    const existing = await SELECT.one
-      .from(attachments)
-      .where({ ID: { in: data.map((d) => d.ID) }, content: { "!=": null } })
-    if (existing) {
-      const error = new Error("Attachment already exists")
-      error.status = 409
-      throw error
+    // Check if an attachment with this ID already has content (only if content is non-updateable)
+    if (this._isContentUpdateRestricted(attachments)) {
+      const existing = await SELECT.one
+        .from(attachments)
+        .where({ ID: { in: data.map((d) => d.ID) }, content: { "!=": null } })
+      if (existing) {
+        const error = new Error("Attachment already exists")
+        error.status = 409
+        throw error
+      }
     }
 
     LOG.debug("Starting database attachment upload", {

srv/gcp.js

@@ -162,7 +162,10 @@ module.exports = class GoogleAttachmentsService extends (
 
       const file = bucket.file(blobName)
 
-      if (await this.exists(blobName)) {
+      if (
+        this._isContentUpdateRestricted(attachments) &&
+        (await this.exists(blobName))
+      ) {
         const error = new Error("Attachment already exists")
         error.status = 409
         throw error

tests/incidents-app/db/attachments.cds

@@ -16,6 +16,9 @@ extend my.Incidents with {
 
   @UI.Hidden
   maximumSizeAttachments : Composition of many Attachments;
+
+  @UI.Hidden
+  overwritableAttachments : Composition of many Attachments;
 }
 
 annotate my.Incidents.maximumSizeAttachments with {
@@ -26,6 +29,9 @@ annotate my.Incidents.mediaTypeAttachments with {
   content @Core.AcceptableMediaTypes: ['image/jpeg'];
 }
 
+// Allow overwriting content for overwritableAttachments by setting empty NonUpdateableProperties
+annotate my.Incidents.overwritableAttachments with @Capabilities.UpdateRestrictions.NonUpdateableProperties: [];
+
 @UI.Facets: [{
   $Type : 'UI.ReferenceFacet',
   Target: 'attachments/@UI.LineItem',

tests/integration/attachments-non-draft.test.js

@@ -224,6 +224,51 @@ describe("Tests for uploading/deleting and fetching attachments through API call
     )
   })
 
+  it("should ALLOW overwriting content when @Capabilities.UpdateRestrictions.NonUpdateableProperties is empty", async () => {
+    const incidentID = await newIncident(POST, "admin")
+
+    // Create attachment metadata on overwritableAttachments
+    const createRes = await POST(
+      `/odata/v4/admin/Incidents(${incidentID})/overwritableAttachments`,
+      { filename: "sample.pdf" },
+      { headers: { "Content-Type": "application/json" } },
+    )
+    const attachmentID = createRes.data.ID
+    expect(attachmentID).toBeDefined()
+
+    // Upload initial file content
+    const fileContent = readFileSync(
+      join(__dirname, "..", "integration", "content/sample.pdf"),
+    )
+    const uploadRes = await PUT(
+      `/odata/v4/admin/Incidents(${incidentID})/overwritableAttachments(up__ID=${incidentID},ID=${attachmentID})/content`,
+      fileContent,
+      {
+        headers: {
+          "Content-Type": "application/pdf",
+          "Content-Length": fileContent.length,
+        },
+      },
+    )
+    expect(uploadRes.status).toBe(204)
+
+    // Overwrite with different content - this should succeed
+    const newFileContent = readFileSync(
+      join(__dirname, "..", "integration", "content/test.pdf"),
+    )
+    const overwriteRes = await PUT(
+      `/odata/v4/admin/Incidents(${incidentID})/overwritableAttachments(up__ID=${incidentID},ID=${attachmentID})/content`,
+      newFileContent,
+      {
+        headers: {
+          "Content-Type": "application/pdf",
+          "Content-Length": newFileContent.length,
+        },
+      },
+    )
+    expect(overwriteRes.status).toBe(204)
+  })
+
   it("should add and fetch attachments for both NonDraftTest and SingleTestDetails in non-draft mode", async () => {
     const testID = cds.utils.uuid()
     const detailsID = cds.utils.uuid()