@sasjs/api 0.6.1 → 0.7.0

package/build/cjs/routes/generated.js

@@ -145,7 +145,7 @@ exports.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`'
             }
         ]
     },
@@ -239,6 +239,10 @@ exports.GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
             }
         ]
     },
@@ -279,6 +283,14 @@ exports.GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
+            },
+            {
+                status: 403,
+                description: 'Client ID already exists.'
             }
         ]
     },
@@ -768,7 +780,7 @@ exports.GENERATED_ROUTES = [
             },
             {
                 status: 409,
-                description: 'Folder already exists'
+                description: 'Folder already exists. The body is that message as plain text.'
             }
         ]
     },
@@ -808,7 +820,7 @@ exports.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.'
             }
         ]
     },
@@ -858,6 +870,14 @@ exports.GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
+            },
+            {
+                status: 409,
+                description: 'Group name already exists.'
             }
         ]
     },
@@ -886,6 +906,22 @@ exports.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."
             }
         ]
     },
@@ -914,6 +950,22 @@ exports.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."
             }
         ]
     },
@@ -936,6 +988,14 @@ exports.GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
+            },
+            {
+                status: 404,
+                description: 'Group not found.'
             }
         ]
     },
@@ -958,6 +1018,10 @@ exports.GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 404,
+                description: 'Group not found.'
             }
         ]
     },
@@ -980,6 +1044,10 @@ exports.GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 404,
+                description: 'Group not found.'
             }
         ]
     },
@@ -1040,6 +1108,14 @@ exports.GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Admin account required, or no grant on the route'
+            },
+            {
+                status: 404,
+                description: 'User not found.'
             }
         ]
     },
@@ -1086,6 +1162,22 @@ exports.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.'
             }
         ]
     },
@@ -1108,6 +1200,14 @@ exports.GENERATED_ROUTES = [
             {
                 status: 204,
                 description: 'No content'
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
+            },
+            {
+                status: 404,
+                description: 'Permission not found.'
             }
         ]
     },
@@ -1136,6 +1236,14 @@ exports.GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
+            },
+            {
+                status: 404,
+                description: 'Permission not found.'
             }
         ]
     },
@@ -1400,6 +1508,14 @@ exports.GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Admin account required'
+            },
+            {
+                status: 409,
+                description: 'Username already exists.'
             }
         ]
     },
@@ -1428,6 +1544,14 @@ exports.GENERATED_ROUTES = [
             {
                 status: 204,
                 description: 'No content'
+            },
+            {
+                status: 401,
+                description: 'Admin account required, or invalid password'
+            },
+            {
+                status: 404,
+                description: 'User is not found.'
             }
         ]
     },
@@ -1450,6 +1574,14 @@ exports.GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Unauthorized'
+            },
+            {
+                status: 404,
+                description: 'User is not found.'
             }
         ]
     },
@@ -1508,6 +1640,22 @@ exports.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.'
             }
         ]
     },
@@ -1536,6 +1684,14 @@ exports.GENERATED_ROUTES = [
             {
                 status: 204,
                 description: 'No content'
+            },
+            {
+                status: 401,
+                description: 'Admin account required, or invalid password'
+            },
+            {
+                status: 404,
+                description: 'User is not found.'
             }
         ]
     },
@@ -1558,6 +1714,14 @@ exports.GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'Unauthorized'
+            },
+            {
+                status: 404,
+                description: 'User is not found.'
             }
         ]
     },
@@ -1616,6 +1780,22 @@ exports.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.'
             }
         ]
     },
@@ -1649,7 +1829,7 @@ exports.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/cjs/routes/overlay.js

@@ -25,7 +25,7 @@ exports.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.";
@@ -80,18 +80,20 @@ exports.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 },
@@ -165,25 +167,13 @@ exports.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': {
@@ -199,16 +189,24 @@ exports.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,
@@ -235,29 +233,26 @@ exports.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. */
 exports.METHODS = ['GET', 'POST', 'PATCH', 'DELETE', 'PUT'];

package/build/esm/corpus/records.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The administration routes' conformance corpus: users, groups, permission rules
+ * and clients, as requests in and answers out.
+ *
+ * Every status the document states for these routes has a case here - that is
+ * what `spec/corpus-parity.spec.ts` enforces in both directions - so a refusal
+ * is part of the contract rather than something a reader has to infer from the
+ * controller.
+ *
+ * The fixtures are small on purpose: one administrator, one restricted user, the
+ * two groups they belong to, three rules, and - for the refusals that only an
+ * externally-managed account can provoke - a provider-managed user and group and
+ * the reserved `public` group.
+ */
+import type { CorpusCase } from './drive.js';
+import { type IdentityFixture } from '../identity/fixture.js';
+/** The default identity, with an administrator and the restricted user signed in. */
+export declare const ADMIN_SIGNED_IN: IdentityFixture;
+/**
+ * The same identity, plus what the provider and public-group refusals need: an
+ * account and a group managed by an external provider, and the reserved group.
+ */
+export declare const PROVIDER_MANAGED: IdentityFixture;
+export declare const RECORD_CORPUS: CorpusCase[];
+//# sourceMappingURL=records.d.ts.map

package/build/esm/corpus/records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../../src/corpus/records.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAA;AAkB/B,qFAAqF;AACrF,eAAO,MAAM,eAAe,EAAE,eAG7B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,eA0C9B,CAAA;AAOD,eAAO,MAAM,aAAa,EAAE,UAAU,EA0oCrC,CAAA"}