Add secretary delegation support with relative namespace UI.

Fix secretary write-access checks and document the feature so delegated accounts can publish on behalf of an owner.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: holycrab13

docs/guides/secretary-guide.md

@@ -0,0 +1,138 @@
+# Secretary Guide
+
+## About this guide
+
+This guide explains how to delegate write access to another Databus account (a **secretary**) and how to publish or edit resources on someone else's behalf.
+
+## What is a secretary?
+
+A secretary is another Databus account that you authorize to write in your namespace. You remain the owner; the secretary authenticates as themselves and tells the server which account they are acting for.
+
+Typical use cases:
+
+- A team member publishes datasets under an organization account
+- A CI pipeline uses its own API key but publishes into a shared account
+- A curator manages resources for multiple accounts they do not own
+
+## Part 1: Declaring secretaries
+
+Only the account owner can edit the secretary list.
+
+### Using the web interface
+
+1. Log in and open your account profile (`/<your-account>`) or **User Settings**.
+2. Find the **Secretaries** section.
+3. Click **Add Secretary**.
+4. Enter the secretary's account name (e.g. `dbpedia`).
+5. Optionally add **Write Access** paths (relative to your account, e.g. `datasets`) to document which parts of your namespace the secretary may use. The UI shows your account base URL as a fixed prefix.
+6. Save the account.
+
+The secretary list is stored in your account metadata as JSON-LD (`databus#secretary`).
+
+### Using the API
+
+Update your account via `POST /api/account/update` (authenticated as the owner):
+
+```http
+POST /api/account/update
+x-api-key: <your-api-key>
+Content-Type: application/json
+
+{
+  "accountName": "myorg",
+  "label": "My Organization",
+  "status": "Publishing open data.",
+  "imageUrl": null,
+  "secretaries": [
+    {
+      "accountName": "alice",
+      "hasWriteAccessTo": [
+        "https://databus.example.org/myorg/datasets"
+      ]
+    }
+  ]
+}
+```
+
+Each secretary entry has:
+
+| Field | Description |
+|-------|-------------|
+| `accountName` | Account name of the secretary |
+| `hasWriteAccessTo` | Optional list of namespace paths, stored as absolute IRIs (metadata only; see note below) |
+
+In the web UI you enter the path relative to your account (e.g. `datasets`). On save it is stored as a full URI (`https://databus.example.org/myorg/datasets`). Via the API, send absolute IRIs directly.
+
+## Part 2: Acting as a secretary
+
+Authenticate as **your own** account (OIDC session or `x-api-key`). Add the `x-on-behalf-of` header with the **full account URI** of the owner:
+
+```http
+x-on-behalf-of: https://databus.example.org/myorg
+```
+
+Replace `https://databus.example.org` with your Databus instance's `DATABUS_RESOURCE_BASE_URL`.
+
+### Publish data on behalf of another account
+
+```http
+POST /api/register
+x-api-key: <your-api-key>
+x-on-behalf-of: https://databus.example.org/myorg
+Content-Type: application/ld+json
+
+{
+  "@context": "https://databus.example.org/context.jsonld",
+  "@graph": [
+    {
+      "@id": "https://databus.example.org/myorg/datasets/example",
+      "@type": "Group",
+      ...
+    }
+  ]
+}
+```
+
+All resource URIs in the payload must live under the delegated account namespace (`/myorg/...`).
+
+### Delete a collection on behalf of another account
+
+```http
+DELETE /myorg/collections/my-collection
+x-api-key: <your-api-key>
+x-on-behalf-of: https://databus.example.org/myorg
+```
+
+### curl example
+
+```bash
+curl -X POST "https://databus.example.org/api/register" \
+  -H "x-api-key: YOUR_API_KEY" \
+  -H "x-on-behalf-of: https://databus.example.org/myorg" \
+  -H "Content-Type: application/ld+json" \
+  -d @publish.jsonld
+```
+
+## How authorization works
+
+When you send `x-on-behalf-of`, the server:
+
+1. Checks whether you already own the target account — if yes, allows the request.
+2. Otherwise fetches the target account's JSON-LD profile.
+3. Reads the `databus#secretary` list and checks whether your authenticated account is listed.
+4. Returns `403` if you are not listed.
+
+You never share your API key or password with the owner. The owner only adds your account name to their secretary list.
+
+## Important notes
+
+- **`x-on-behalf-of` must be the full account URI**, not just the account name. Example: `https://databus.dbpedia.org/dbpedia`, not `dbpedia`.
+- **Write Access namespaces** (`hasWriteAccessTo`) are stored as absolute IRIs. The UI accepts relative paths under your account and expands them on save. Prefix matching is the intended model (a group IRI covers artifacts and versions under it), but the server does not enforce these IRIs yet.
+- **Only owners** can add or remove secretaries via `/api/account/update`.
+- Secretary access applies to write operations that check authorization (e.g. `/api/register`, collection delete). Read access is unchanged.
+
+## Related guides
+
+- [Publish Guide](publish-guide.md)
+- [API usage](../usage/api/README.md)
+- [Account model](../account.md)

public/css/website.css

@@ -1356,6 +1356,16 @@ databus-icon {
   border-radius: 4px 0px 0px 4px;
 }
 
+.databus-uri-prefix.button.is-static {
+  max-width: 55%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: hsl(0, 0%, 62%);
+  font-family: monospace;
+  font-size: 0.9em;
+}
+
 .error-notification-box {
   background-color: #fdf2f2; /* very light red/pink background */
   border-left: 3px solid #f14668; /* Bulma 'danger' color */

public/css/website.css.map

@@ -288,7 +288,10 @@ function ProfileController($scope, $http) {
     account.label = $scope.editData.label;
     account.status = $scope.editData.about;
     account.imageUrl = $scope.editData.imageUrl;
-    account.secretaries = $scope.editData.secretaries;
+    account.secretaries = DatabusUtils.secretariesForSave(
+      $scope.editData.secretaries,
+      account.accountName
+    );
 
 
     try {
@@ -312,11 +315,20 @@ function ProfileController($scope, $http) {
   $scope.modsSettings.searchExtensionURI = "";
   $scope.modsSettings.searchExtensionAdapter = $scope.adapters[0];
 
+  $scope.getWriteAccessPrefix = function (accountName) {
+    return DatabusUtils.getAccountNamespacePrefix(accountName);
+  };
+
+  function initEditData() {
+    var copy = DatabusUtils.createCleanCopy($scope.account);
+    copy.secretaries = DatabusUtils.secretariesForEdit(copy.secretaries, copy.accountName);
+    return copy;
+  }
 
-  $scope.editData = DatabusUtils.createCleanCopy($scope.account);
+  $scope.editData = initEditData();
 
   $scope.resetEdits = function () {
-    $scope.editData = DatabusUtils.createCleanCopy($scope.account);
+    $scope.editData = initEditData();
   }
 
 }

public/css/website.scss

@@ -76,6 +76,8 @@ function UserSettingsController($scope, $http, $sce, $location) {
           account.secretaries.push(secretary);
         }
 
+        account.secretaries = DatabusUtils.secretariesForEdit(account.secretaries, account.accountName);
+
       })
       .catch(function (error) {
         // Handle error and set loading to false
@@ -111,7 +113,9 @@ function UserSettingsController($scope, $http, $sce, $location) {
   // Button click handler to save account
   $scope.saveAccount = async function (account) {
     try {
-      await $http.post(`/api/account/update`, account);
+      var payload = DatabusUtils.createCleanCopy(account);
+      payload.secretaries = DatabusUtils.secretariesForSave(payload.secretaries, account.accountName);
+      await $http.post(`/api/account/update`, payload);
       DatabusAlert.alert($scope, true, "Account saved.");
 
     } catch (err) {
@@ -121,6 +125,10 @@ function UserSettingsController($scope, $http, $sce, $location) {
 
   };
 
+  $scope.getWriteAccessPrefix = function (accountName) {
+    return DatabusUtils.getAccountNamespacePrefix(accountName);
+  };
+
   // Button click handler to delete account
   $scope.deleteAccount = async function (account) {
     try {

public/dist/main.js

@@ -275,6 +275,87 @@ class DatabusUtils {
     return data;
   }
 
+  static getAccountNamespacePrefix(accountName) {
+    return `${DATABUS_RESOURCE_BASE_URL}/${accountName}/`;
+  }
+
+  static toRelativeWriteAccessUri(absoluteUri, accountName) {
+    if (absoluteUri == null || absoluteUri === '') {
+      return '';
+    }
+
+    const prefix = DatabusUtils.getAccountNamespacePrefix(accountName);
+    if (absoluteUri.startsWith(prefix)) {
+      return absoluteUri.slice(prefix.length);
+    }
+
+    const accountUri = `${DATABUS_RESOURCE_BASE_URL}/${accountName}`;
+    if (absoluteUri === accountUri) {
+      return '';
+    }
+
+    const basePrefix = `${DATABUS_RESOURCE_BASE_URL}/`;
+    if (absoluteUri.startsWith(basePrefix)) {
+      const remainder = absoluteUri.slice(basePrefix.length);
+      const accountPrefix = `${accountName}/`;
+      if (remainder.startsWith(accountPrefix)) {
+        return remainder.slice(accountPrefix.length);
+      }
+      if (remainder === accountName) {
+        return '';
+      }
+    }
+
+    return absoluteUri;
+  }
+
+  static toAbsoluteWriteAccessUri(relativeUri, accountName) {
+    if (relativeUri == null) {
+      return null;
+    }
+
+    const trimmed = relativeUri.trim();
+    if (trimmed === '') {
+      return null;
+    }
+
+    return DatabusUtils.getAccountNamespacePrefix(accountName) + trimmed.replace(/^\/+/, '');
+  }
+
+  static secretariesForEdit(secretaries, accountName) {
+    if (secretaries == null) {
+      return [];
+    }
+
+    return secretaries.map(function (secretary) {
+      return {
+        accountName: secretary.accountName,
+        hasWriteAccessTo: (secretary.hasWriteAccessTo || []).map(function (uri) {
+          return DatabusUtils.toRelativeWriteAccessUri(uri, accountName);
+        })
+      };
+    });
+  }
+
+  static secretariesForSave(secretaries, accountName) {
+    if (secretaries == null) {
+      return [];
+    }
+
+    return secretaries.map(function (secretary) {
+      return {
+        accountName: secretary.accountName,
+        hasWriteAccessTo: (secretary.hasWriteAccessTo || [])
+          .map(function (uri) {
+            return DatabusUtils.toAbsoluteWriteAccessUri(uri, accountName);
+          })
+          .filter(function (uri) {
+            return uri != null;
+          })
+      };
+    });
+  }
+
   static lineCount(text) {
     return (text.match(/^\s*\S/gm) || "").length
   }
@@ -531,4 +612,14 @@ class DatabusUtils {
 
 }
 
+if (typeof process !== 'undefined' && require.main === module) {
+  global.DATABUS_RESOURCE_BASE_URL = 'https://databus.example.org';
+  console.assert(
+    DatabusUtils.toRelativeWriteAccessUri('https://databus.example.org/myorg/datasets', 'myorg') === 'datasets'
+  );
+  console.assert(
+    DatabusUtils.toAbsoluteWriteAccessUri('datasets', 'myorg') === 'https://databus.example.org/myorg/datasets'
+  );
+}
+
 module.exports = DatabusUtils;

public/js/page-controller/profile-controller.js

@@ -60,13 +60,13 @@
               No secretaries defined.
             </div>
 
-            <div ng-repeat="secretary in editData.secretaries track by $index" class="settings-entity">
+            <div ng-repeat="(secIndex, secretary) in editData.secretaries track by secIndex" class="settings-entity">
               <div style="width: 100%;">
                 <div class="field">
                   <div
                     style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 0.5em;">
                     <label class="label">Secretary</label>
-                    <a ng-click="removeSecretary(account, $index)" class="button is-error">
+                    <a ng-click="removeSecretary(account, secIndex)" class="button is-error">
                       Delete
                     </a>
                   </div>
@@ -78,19 +78,22 @@
 
                 <div class="field" style="margin-bottom: 0.5em;">
                   <label class="label">Write Access</label>
-                  <div ng-repeat="ns in secretary.hasWriteAccessTo track by $index" class="field has-addons mb-2">
+                  <div ng-repeat="(nsIndex, ns) in secretary.hasWriteAccessTo track by nsIndex" class="field has-addons mb-2">
+                    <div class="control">
+                      <span class="button is-static databus-uri-prefix">{{ getWriteAccessPrefix(editData.accountName) }}</span>
+                    </div>
                     <div class="control is-expanded">
-                      <input class="input" type="text" placeholder="Namespace IRI"
-                        ng-model="secretary.hasWriteAccessTo[$index]">
+                      <input class="input" type="text" placeholder="e.g. datasets"
+                        ng-model="secretary.hasWriteAccessTo[nsIndex]">
                     </div>
                     <div class="control">
-                      <button class="button is-danger" ng-click="removeNamespace(account, $index, $index)">
+                      <button class="button is-danger" ng-click="removeNamespace(account, secIndex, nsIndex)">
                         <span class="icon"><i class="fas fa-times"></i></span>
                       </button>
                     </div>
                   </div>
 
-                  <button class="button" ng-click="addNamespace(account, $index)">
+                  <button class="button" ng-click="addNamespace(account, secIndex)">
                     <span class="icon"><i class="fas fa-plus"></i></span>
                     <span>Add Namespace</span>
                   </button>