@sasjs/api 0.6.0 → 0.7.0

package/build/esm/routes/generated.js

@@ -142,7 +142,7 @@ export const GENERATED_ROUTES = [
             },
             {
                 status: 401,
-                description: 'The authorization code is invalid, expired, already used, or was issued for another client, or the client id is unknown'
+                description: 'The authorization code is invalid, expired, already used, or was issued for another client, or the client id is unknown. This route is unauthenticated, so an unknown client id is a `401` here where `POST /SASLogon/authorize` (which requires a session) answers `403`'
             }
         ]
     },
@@ -236,6 +236,10 @@ export const GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
             }
         ]
     },
@@ -276,6 +280,14 @@ export const GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
+            },
+            {
+                status: 403,
+                description: 'Client ID already exists.'
             }
         ]
     },
@@ -765,7 +777,7 @@ export const GENERATED_ROUTES = [
             },
             {
                 status: 409,
-                description: 'Folder already exists'
+                description: 'Folder already exists. The body is that message as plain text.'
             }
         ]
     },
@@ -805,7 +817,7 @@ export const GENERATED_ROUTES = [
             },
             {
                 status: 409,
-                description: 'Something already exists at the new path'
+                description: 'Something already exists at the new path. The body is that message as plain text.'
             }
         ]
     },
@@ -855,6 +867,14 @@ export const GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
+            },
+            {
+                status: 409,
+                description: 'Group name already exists.'
             }
         ]
     },
@@ -883,6 +903,22 @@ export const GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 400,
+                description: "Can't add/remove user to 'public' group."
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
+            },
+            {
+                status: 404,
+                description: 'Group not found. / User not found.'
+            },
+            {
+                status: 405,
+                description: "Can't add/remove user to group created by external auth provider."
             }
         ]
     },
@@ -911,6 +947,22 @@ export const GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 400,
+                description: "Can't add/remove user to 'public' group."
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
+            },
+            {
+                status: 404,
+                description: 'Group not found. / User not found.'
+            },
+            {
+                status: 405,
+                description: "Can't add/remove user to group created by external auth provider."
             }
         ]
     },
@@ -933,6 +985,14 @@ export const GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
+            },
+            {
+                status: 404,
+                description: 'Group not found.'
             }
         ]
     },
@@ -955,6 +1015,10 @@ export const GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 404,
+                description: 'Group not found.'
             }
         ]
     },
@@ -977,6 +1041,10 @@ export const GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 404,
+                description: 'Group not found.'
             }
         ]
     },
@@ -1037,6 +1105,14 @@ export const GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Admin account required, or no grant on the route'
+            },
+            {
+                status: 404,
+                description: 'User not found.'
             }
         ]
     },
@@ -1083,6 +1159,22 @@ export const GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 400,
+                description: 'Can not add permission for admin user. / Invalid principal type. Valid types are user or group.'
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
+            },
+            {
+                status: 404,
+                description: 'User not found. / Group not found.'
+            },
+            {
+                status: 409,
+                description: 'Permission already exists with provided Path, Type and User. / Permission already exists with provided Path, Type and Group.'
             }
         ]
     },
@@ -1105,6 +1197,14 @@ export const GENERATED_ROUTES = [
             {
                 status: 204,
                 description: 'No content'
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
+            },
+            {
+                status: 404,
+                description: 'Permission not found.'
             }
         ]
     },
@@ -1133,6 +1233,14 @@ export const GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
+            },
+            {
+                status: 404,
+                description: 'Permission not found.'
             }
         ]
     },
@@ -1397,6 +1505,14 @@ export const GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
+            },
+            {
+                status: 409,
+                description: 'Username already exists.'
             }
         ]
     },
@@ -1425,6 +1541,14 @@ export const GENERATED_ROUTES = [
             {
                 status: 204,
                 description: 'No content'
+            },
+            {
+                status: 401,
+                description: 'Admin account required, or invalid password'
+            },
+            {
+                status: 404,
+                description: 'User is not found.'
             }
         ]
     },
@@ -1447,6 +1571,14 @@ export const GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Unauthorized'
+            },
+            {
+                status: 404,
+                description: 'User is not found.'
             }
         ]
     },
@@ -1505,6 +1637,22 @@ export const GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
+            },
+            {
+                status: 404,
+                description: 'Unable to find user with <id>'
+            },
+            {
+                status: 405,
+                description: 'Can not update username of user that is created by an external auth provider. / Can not update display name of user that is created by an external auth provider.'
+            },
+            {
+                status: 409,
+                description: 'Username already exists.'
             }
         ]
     },
@@ -1533,6 +1681,14 @@ export const GENERATED_ROUTES = [
             {
                 status: 204,
                 description: 'No content'
+            },
+            {
+                status: 401,
+                description: 'Admin account required, or invalid password'
+            },
+            {
+                status: 404,
+                description: 'User is not found.'
             }
         ]
     },
@@ -1555,6 +1711,14 @@ export const GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Unauthorized'
+            },
+            {
+                status: 404,
+                description: 'User is not found.'
             }
         ]
     },
@@ -1613,6 +1777,22 @@ export const GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
+            },
+            {
+                status: 404,
+                description: 'Unable to find user with <username>'
+            },
+            {
+                status: 405,
+                description: 'Can not update username of user that is created by an external auth provider. / Can not update display name of user that is created by an external auth provider.'
+            },
+            {
+                status: 409,
+                description: 'Username already exists.'
             }
         ]
     },
@@ -1646,7 +1826,7 @@ export const GENERATED_ROUTES = [
             },
             {
                 status: 403,
-                description: 'The client id is unknown'
+                description: 'The client id is unknown. This route runs under a signed-in session, so the caller is authenticated and an unknown client is refused as forbidden; the unauthenticated `POST /SASjsApi/auth/token` answers `401` for the same condition'
             }
         ]
     },

package/build/esm/routes/overlay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../../src/routes/overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGzD,yDAAyD;AACzD,UAAU,aAAa;IACrB,YAAY,CAAC,EAAE,UAAU,EAAE,CAAA;IAC3B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACpC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,aAAa,GACtC,CAAC;IAAE,WAAW,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,WAAW,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAElE,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAczD,CAAA;AAiDD,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAmOhD,CAAA;AAED,wEAAwE;AACxE,eAAO,MAAM,OAAO,EAAE,UAAU,EAA8C,CAAA"}
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../../src/routes/overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGzD,yDAAyD;AACzD,UAAU,aAAa;IACrB,YAAY,CAAC,EAAE,UAAU,EAAE,CAAA;IAC3B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACpC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,aAAa,GACtC,CAAC;IAAE,WAAW,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,WAAW,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAElE,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAczD,CAAA;AAiDD,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CA8NhD,CAAA;AAED,wEAAwE;AACxE,eAAO,MAAM,OAAO,EAAE,UAAU,EAA8C,CAAA"}

package/build/esm/routes/overlay.js

@@ -22,7 +22,7 @@ export const TAG_CAPABILITIES = {
  * operation waits on, and thirty copies of the same sentence would say the same
  * thing thirty times.
  */
-const IDENTITY_RECORDS = 'The identity service answers the sign-in flow. User, group, permission rule, client and provider records need read and write methods on the same store, which this package does not have yet.';
+const DIRECTORY = 'Synchronising with an external auth provider needs a directory port, which this package does not have: a host decides which directory it holds accounts in, and answers this itself.';
 const EDITOR = 'Linting and formatting come from @sasjs/lint, which this package does not depend on. They land with the code routes so an editor has one wiring.';
 const RUNTIME = 'Starting a program needs a runtime port, which this package does not have: a host decides which languages it holds, and answers this itself until then.';
 const SESSION_RECORD = "A triggered session's record, log, output and state belong to the runtime that ran the program, and this package has no runtime port.";
@@ -77,18 +77,20 @@ export const OVERLAY = {
     },
     'POST /SASjsApi/auth/logout': { implemented: true },
     'PATCH /SASjsApi/auth/updatePassword': {
-        implemented: false,
-        reason: IDENTITY_RECORDS
+        implemented: true,
+        // As with the permission list: the document's 404 is a caller whose record
+        // has gone, which a host's store can see and this package cannot.
+        hostResponses: [404]
     },
     // Auth Config - the providers a host was started with, and an LDAP import
     'GET /SASjsApi/authConfig': { implemented: false, reason: HOST_CONFIG },
     'POST /SASjsApi/authConfig/synchroniseWithLDAP': {
         implemented: false,
-        reason: IDENTITY_RECORDS
+        reason: DIRECTORY
     },
     // Client - the OAuth clients the identity store already holds for sign-in
-    'GET /SASjsApi/client': { implemented: false, reason: IDENTITY_RECORDS },
-    'POST /SASjsApi/client': { implemented: false, reason: IDENTITY_RECORDS },
+    'GET /SASjsApi/client': { implemented: true },
+    'POST /SASjsApi/client': { implemented: true },
     // Code - the editor's three calls, and the runtime one
     'POST /SASjsApi/code/execute': { implemented: false, reason: RUNTIME },
     'POST /SASjsApi/code/trigger': { implemented: false, reason: RUNTIME },
@@ -162,25 +164,13 @@ export const OVERLAY = {
         reason: UNPUBLISH
     },
     // Group - members and the groups themselves
-    'GET /SASjsApi/group': { implemented: false, reason: IDENTITY_RECORDS },
-    'GET /SASjsApi/group/{uid}': { implemented: false, reason: IDENTITY_RECORDS },
-    'GET /SASjsApi/group/by/groupname/{name}': {
-        implemented: false,
-        reason: IDENTITY_RECORDS
-    },
-    'POST /SASjsApi/group': { implemented: false, reason: IDENTITY_RECORDS },
-    'POST /SASjsApi/group/{groupUid}/{userUid}': {
-        implemented: false,
-        reason: IDENTITY_RECORDS
-    },
-    'DELETE /SASjsApi/group/{groupUid}/{userUid}': {
-        implemented: false,
-        reason: IDENTITY_RECORDS
-    },
-    'DELETE /SASjsApi/group/{uid}': {
-        implemented: false,
-        reason: IDENTITY_RECORDS
-    },
+    'GET /SASjsApi/group': { implemented: true },
+    'GET /SASjsApi/group/{uid}': { implemented: true },
+    'GET /SASjsApi/group/by/groupname/{name}': { implemented: true },
+    'POST /SASjsApi/group': { implemented: true },
+    'POST /SASjsApi/group/{groupUid}/{userUid}': { implemented: true },
+    'DELETE /SASjsApi/group/{groupUid}/{userUid}': { implemented: true },
+    'DELETE /SASjsApi/group/{uid}': { implemented: true },
     // Info - what the host is, and what this caller may use
     'GET /SASjsApi/info': { implemented: false, reason: HOST_CONFIG },
     'GET /SASjsApi/info/authorizedRoutes': {
@@ -196,16 +186,24 @@ export const OVERLAY = {
         reason: PERMISSIONS
     },
     // Permission - the rules the inventory above is derived from
-    'GET /SASjsApi/permission': { implemented: false, reason: IDENTITY_RECORDS },
-    'POST /SASjsApi/permission': { implemented: false, reason: IDENTITY_RECORDS },
-    'PATCH /SASjsApi/permission/{uid}': {
-        implemented: false,
-        reason: IDENTITY_RECORDS
-    },
-    'DELETE /SASjsApi/permission/{uid}': {
-        implemented: false,
-        reason: IDENTITY_RECORDS
-    },
+    'GET /SASjsApi/permission': {
+        implemented: true,
+        // The document states 404 for a caller whose record has gone - a token that
+        // outlived its account. Here a token stops resolving when the account does,
+        // so this package answers 401 before it gets that far; the host's own store
+        // is what can still see the difference.
+        hostResponses: [404]
+    },
+    'POST /SASjsApi/permission': { implemented: true },
+    'PATCH /SASjsApi/permission/{uid}': { implemented: true },
+    // The three deletes answer 204 here and 200 on the wire: the server's route
+    // handlers send `res.status(200).send('Account Deleted!')` and
+    // `'Permission Deleted!'`, while tsoa emitted 204 for a void handler, so the
+    // document understates the status. Correcting it is a decorator in
+    // sasjs/server (`@SuccessResponse('200', ...)`), and this package follows the
+    // document until that release lands - a local 200 would fail the schema check
+    // that keeps this table honest.
+    'DELETE /SASjsApi/permission/{uid}': { implemented: true },
     // Session - the caller's own session, then the record behind a triggered one
     'GET /SASjsApi/session': {
         implemented: true,
@@ -232,29 +230,26 @@ export const OVERLAY = {
     'POST /SASjsApi/stp/execute': { implemented: false, reason: RUNTIME },
     'POST /SASjsApi/stp/trigger': { implemented: false, reason: RUNTIME },
     // User - the accounts the identity store already holds for sign-in
-    'GET /SASjsApi/user': { implemented: false, reason: IDENTITY_RECORDS },
-    'GET /SASjsApi/user/{uid}': { implemented: false, reason: IDENTITY_RECORDS },
-    'GET /SASjsApi/user/by/username/{username}': {
-        implemented: false,
-        reason: IDENTITY_RECORDS
-    },
-    'POST /SASjsApi/user': { implemented: false, reason: IDENTITY_RECORDS },
-    'PATCH /SASjsApi/user/{uid}': {
-        implemented: false,
-        reason: IDENTITY_RECORDS
-    },
-    'PATCH /SASjsApi/user/by/username/{username}': {
-        implemented: false,
-        reason: IDENTITY_RECORDS
-    },
-    'DELETE /SASjsApi/user/{uid}': {
-        implemented: false,
-        reason: IDENTITY_RECORDS
-    },
-    'DELETE /SASjsApi/user/by/username/{username}': {
-        implemented: false,
-        reason: IDENTITY_RECORDS
-    }
+    // Reading accounts is open to any authenticated caller, which is what
+    // sasjs/server's routes do (`authenticateAccessToken` only): the document once
+    // said `Admin account required` here, and sasjs/server#551 corrected it to
+    // `Unauthorized` because that is the refusal a caller actually receives. The
+    // breadth is the server's behaviour, copied deliberately - the auto-exec code
+    // is the one field withheld from anyone but an administrator or the account
+    // itself.
+    'GET /SASjsApi/user': { implemented: true },
+    'GET /SASjsApi/user/{uid}': { implemented: true },
+    'GET /SASjsApi/user/by/username/{username}': { implemented: true },
+    'POST /SASjsApi/user': { implemented: true },
+    'PATCH /SASjsApi/user/{uid}': { implemented: true },
+    'PATCH /SASjsApi/user/by/username/{username}': { implemented: true },
+    // The document also marks `password` optional on these deletes, while the
+    // server's schema requires it for anyone who is not an administrator, and for
+    // an account deleting itself. A host should treat a passwordless delete from a
+    // non-admin as the refusal it is; this package answers 401 `Invalid password.`
+    // where the server's schema answers 400 `"password" is required`.
+    'DELETE /SASjsApi/user/{uid}': { implemented: true },
+    'DELETE /SASjsApi/user/by/username/{username}': { implemented: true }
 };
 /** Every method the table may state, in the order a diff reads best. */
 export const METHODS = ['GET', 'POST', 'PATCH', 'DELETE', 'PUT'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sasjs/api",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The SASjs Server API, described once - a generated route table, the services behind it, and the conformance corpus both hosts run",
   "license": "MIT",
   "author": "SASjs",