MANTA-5521 Add optional scope parameter to CreateAccessKey, UpdateAccessKey, and DeleteAccessKey CloudAPI endpoints.

docs/index.md

@@ -15,7 +15,7 @@ markdown2extras: tables, code-friendly
     Copyright 2021 Joyent, Inc.
     Copyright 2021 The University of Queensland
     Copyright 2024 MNX Cloud, Inc.
-    Copyright 2025 Edgecast Cloud LLC.
+    Copyright 2026 Edgecast Cloud LLC.
 -->
 
 
@@ -887,6 +887,11 @@ Note that a `Triton-Datacenter-Name` response header was added in 9.2.0.
 
 The section describes API changes in CloudAPI versions.
 
+## 9.22.0 
+
+- Add an optional bucket-scope parameter when creating an accesskey.
+- `UpdateAccessKey` now returns 200 status code on success instead of 201.
+
 ## 9.21.0
 
 - Add ability to update an AccessKey's `status` and `description` field.
@@ -3362,6 +3367,35 @@ Generates a new access key id and secret.
 ----------- | -------- | ------------------------------------------------------------------
 status      | String   | `Active`, `Inactive`, or `Expired` (optional, default is `Active`)
 description | String   | Description of Access Key (optional)
+scope       | Object.  | Object describing permissions and bucket to which the accesskey will have access. _If_ `null` then the scope is unrestricted. 
+
+The json schema of this optional parameter is the following:
+```json
+  {
+    "type": "object",
+    "required": ["version", "permissions"],
+    "properties": {
+      "version": { "const": 1 },
+      "permissions": {
+        "type": "array",
+        "minItems": 1,
+        "maxItems": 1000,
+        "items": {
+          "type": "object",
+          "required": ["bucket", "level"],
+          "properties": {
+            "bucket": {
+              "type": "string",
+              "maxLength": 63,
+              "pattern": "^(\\*|[a-z0-9][a-z0-9.\\-]*\\*?)$"
+            },
+            "level": { "enum": ["read", "readwrite", "full"] }
+          }
+        }
+      }
+    }
+  }
+```
 
 ### Returns
 

lib/endpoints/accesskeys.js

@@ -6,7 +6,7 @@
 
 /*
  * Copyright 2020 Joyent, Inc.
- * Copyright 2025 Edgecast Cloud LLC.
+ * Copyright 2026 Edgecast Cloud LLC.
  */
 
 
@@ -17,6 +17,7 @@ var assert = require('assert-plus');
 var restify = require('restify');
 
 var resources = require('../resources');
+var scopeSchema = require('mahi').scopeSchema;
 
 
 var sprintf = util.format;
@@ -31,14 +32,38 @@ var InternalError = restify.InternalError;
  */
 var MAX_KEYS = 100;
 
+/**
+ * @brief Validate a scope parameter from the request
+ *
+ * Delegates to the canonical scope schema module in node-mahi. Accepts only the
+ * canonical envelope: {"version":1,"permissions":[{bucket,level},...]}
+ *
+ * @param {Object} input - Scope envelope object
+ * @return {Object} {valid: bool, scope: string|null,
+ *   error: string|null}
+ */
+function validateScope(input) {
+    return scopeSchema.validateScope(input);
+}
+
+
+/**
+ * @brief Translate UFDS access key to API response format
+ *
+ * Maps internal UFDS attributes to the external API representation. Includes
+ * the accesskeyscope field as a parsed JSON object when present.
+ *
+ * @param {Object} accesskey - UFDS access key entry
+ * @return {Object} Translated access key for response
+ */
 function translateAccessKey(accesskey) {
     if (!accesskey) {
         return {};
     }
 
     var translated = {
-       accesskeyid: accesskey.accesskeyid,
-       credentialtype: accesskey.credentialtype || 'permanent'
+        accesskeyid: accesskey.accesskeyid,
+        credentialtype: accesskey.credentialtype || 'permanent'
     };
 
     if (accesskey.status) {
@@ -65,6 +90,20 @@ function translateAccessKey(accesskey) {
         translated.expiration = null;
     }
 
+    /*
+     * Return bucket scope as a parsed JSON object so callers can inspect
+     * permissions directly. When absent the key is unrestricted.
+     */
+    if (accesskey.accesskeyscope) {
+        try {
+            translated.scope = JSON.parse(accesskey.accesskeyscope);
+        } catch (_e) {
+            translated.scope = null;
+        }
+    } else {
+        translated.scope = null;
+    }
+
     return translated;
 }
 
@@ -107,6 +146,22 @@ function create(req, res, next) {
         return;
     }
 
+    /*
+     * Per-bucket access key scoping. Scope must be the canonical envelope:
+     * {"version":1,"permissions":[{bucket,level},...]}
+     *
+     * Absent/null scope means unrestricted.
+     */
+    if (req.params.scope !== undefined &&
+        req.params.scope !== null) {
+        var result = validateScope(req.params.scope);
+        if (!result.valid) {
+            next(new InvalidArgumentError(result.error));
+            return;
+        }
+        params.accesskeyscope = result.scope;
+    }
+
     try {
         vasync.waterfall([
 
@@ -155,6 +210,16 @@ function create(req, res, next) {
 
                     var accesskeysecret = accesskey.accesskeysecret;
 
+                    /*
+                     * UFDS is authoritative. On a Redis miss, the
+                     * mahi sigv4 read-through resolves the new key
+                     * directly from UFDS on every authcache
+                     * instance — that is what makes the new key
+                     * usable on the first signed request without
+                     * waiting for the replicator. We do not write
+                     * to mahi from here.
+                     */
+
                     accesskey = translateAccessKey(accesskey);
 
                     // Only return the accesskeysecret on creation
@@ -178,7 +243,7 @@ function create(req, res, next) {
                         // we've just created, not the collection URI:
                         req.resourcename = req.resourcename + '/' +
                             accesskey.accesskeyid;
-                       req.resource = {
+                        req.resource = {
                             name: req.resourcename,
                             account: req.account.uuid,
                             roles: []
@@ -317,9 +382,24 @@ function del(req, res, next) {
                 return;
             }
 
+            /*
+             * UFDS is authoritative. Each authcache instance has
+             * its own mahi-replicator that polls UFDS and applies
+             * the deletion to local Redis on its own schedule. On
+             * a Redis miss the sigv4 read-through resolves the
+             * current state from UFDS directly. We do not call
+             * mahi from here: per-instance cache mutation from
+             * cloudapi was a misleading optimisation — it only
+             * ever reached the single mahi instance cloudapi
+             * could resolve by name, never the Manta authcache
+             * pool that serves the S3 data plane. The replicator
+             * is the consistency mechanism for every Redis
+             * holding this key.
+             */
             log.debug('DELETE %s -> ok', req.path());
             res.send(204);
             next();
+            return;
         });
     } catch (e) {
         log.error({err: e}, 'delete accesskey exception');
@@ -354,6 +434,26 @@ function update(req, res, next) {
         params.description = req.params.description;
     }
 
+    /*
+     * Update bucket scope. An empty string or null removes the scope (makes
+     * the key unrestricted again). A non-empty value replaces the scope.
+     */
+    if (req.params.scope !== undefined) {
+        if (req.params.scope === '' ||
+            req.params.scope === null) {
+            /* Remove scope: set null so UFDS deletes attr */
+            params.accesskeyscope = null;
+        } else {
+            var scopeResult = validateScope(req.params.scope);
+            if (!scopeResult.valid) {
+                next(new InvalidArgumentError(
+                    scopeResult.error));
+                return;
+            }
+            params.accesskeyscope = scopeResult.scope;
+        }
+    }
+
     // Make it clear that credential type and expiration cannot be changed.
     if (req.params.credentialtype) {
         next(new ForbiddenError('credentialtype cannot be set via CloudAPI'));
@@ -374,35 +474,45 @@ function update(req, res, next) {
                 return;
             }
 
+            /*
+             * UFDS is authoritative. Each authcache instance has
+             * its own mahi-replicator that polls UFDS and
+             * applies the update to local Redis on its own
+             * schedule. We do not call mahi from here — see the
+             * matching comment in del() above.
+             */
             accesskey = translateAccessKey(accesskey);
 
             if (account) {
                 res.header('Location',
-                    sprintf('/%s/users/%s/accesskeys/%s',
-                        login,
+                    sprintf('/%s/users/%s/accesskeys/%s', login,
                         user,
-                        encodeURIComponent(accesskey.accesskeyid)));
+                        encodeURIComponent(
+                            accesskey.accesskeyid)));
             } else {
                 res.header('Location',
-                    sprintf('/%s/accesskeys/%s',
-                        login,
-                        encodeURIComponent(accesskey.accesskeyid)));
+                    sprintf('/%s/accesskeys/%s', login,
+                        encodeURIComponent(
+                            accesskey.accesskeyid)));
             }
 
             if (req.headers['role-tag'] || req.activeRoles) {
-                // The resource we want to save is the individual one we've
-                // just created, not the collection URI:
+                /*
+                 * The resource we want to save is the
+                 * individual one we've just updated, not the
+                 * collection URI.
+                 */
                 req.resourcename = req.resourcename + '/' +
                     accesskey.accesskeyid;
-               req.resource = {
+                req.resource = {
                     name: req.resourcename,
                     account: req.account.uuid,
                     roles: []
                 };
             }
 
             log.debug('POST %s => %j', req.path(), accesskey);
-            res.send(201, accesskey);
+            res.send(200, accesskey);
             next();
             return;
         });