@sasjs/api 0.2.1 → 0.3.1

package/build/cjs/identity/service.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asSession = exports.createIdentityService = void 0;
+/**
+ * The sign-in flow's decisions: what each route answers, in which order, with
+ * which wording.
+ *
+ * The transport stays with the host - a session cookie and a CSRF token on a
+ * server, whatever the browser build holds - so nothing here reads a request.
+ * A host resolves the caller (a bearer token through `authenticate`, a session
+ * it already has) and passes the subject in; the service decides whether that
+ * is enough for the operation to proceed.
+ */
+const types_js_1 = require("../types.js");
+const unauthorized = () => new types_js_1.ApiError(401, 'Unauthorized');
+/**
+ * The subject, provided the account behind it may still hold a token.
+ *
+ * `authenticate` reads a token on every request and refuses a deactivated
+ * account; an exchange or a refresh that skipped the same check would mint a
+ * fresh pair for exactly that account, so the check sits beside every path that
+ * reaches `store.issue`.
+ */
+const liveSubject = async (store, subject) => {
+    const user = await store.userById(subject.userId);
+    if (!user || !user.isActive)
+        throw unauthorized();
+    return subject;
+};
+const createIdentityService = (store) => ({
+    async authenticate(token) {
+        if (token === undefined)
+            return undefined;
+        const subject = await store.readAccess(token);
+        if (!subject)
+            return undefined;
+        // A token names a user who may since have been deactivated. sasjs/server
+        // checks `isActive` on every request, so a token that outlived the account
+        // must stop resolving here too - otherwise the browser host honours a
+        // caller the server would refuse.
+        const user = await store.userById(subject.userId);
+        return user && user.isActive ? subject : undefined;
+    },
+    async login({ username, password }) {
+        const user = await store.userByName(username);
+        // An unknown username and a wrong password answer with different messages
+        // on purpose: the server's login form tells the caller which one it was,
+        // and the account lockout - the defence against guessing - is the host's.
+        if (!user)
+            throw new types_js_1.ApiError(401, 'Username is not found.');
+        if (!(await store.passwordMatches(user, password)))
+            throw new types_js_1.ApiError(401, 'Invalid Password.');
+        // Checked after the password, so the answer is not a way to learn that an
+        // account exists but is switched off without knowing its password.
+        if (!user.isActive)
+            throw new types_js_1.ApiError(401, 'This account is not active.');
+        return {
+            loggedIn: true,
+            user: {
+                uid: user.uid,
+                username: user.username,
+                displayName: user.displayName,
+                isAdmin: user.isAdmin,
+                needsToUpdatePassword: user.needsToUpdatePassword
+            }
+        };
+    },
+    async authorize(subject, clientId) {
+        // The same answer the server's middleware gives a caller with no token: the
+        // two hosts must not describe the same refusal differently.
+        if (!subject)
+            throw unauthorized();
+        if (!(await store.client(clientId)))
+            throw new types_js_1.ApiError(403, 'Invalid clientId.');
+        // A host resolves the caller once, at sign-in; the account may since have
+        // been deactivated. sasjs/server re-reads the user on every request and
+        // refuses an inactive one, so a session that outlived the account must not
+        // go on buying codes here.
+        const named = await liveSubject(store, subject);
+        return store.issueCode({ userId: named.userId, clientId });
+    },
+    async token({ clientId, code }) {
+        // Read before claiming: a code presented with another client is refused
+        // with the same answer as one that does not verify, and it is not spent, so
+        // the caller can still exchange it for the client it was issued for.
+        const subject = await store.readCode(code);
+        if (!subject || subject.clientId !== clientId)
+            throw new types_js_1.ApiError(401, 'Invalid Auth Code');
+        // The client is read before the code is spent and before an existing pair is
+        // handed back: both the pair and the tokens it would buy belong to the
+        // client, so a client deleted since the code was issued refuses the
+        // exchange - and refuses it without consuming the code.
+        const client = await store.client(clientId);
+        if (!client)
+            throw new types_js_1.ApiError(401, 'Invalid clientId.');
+        const named = await liveSubject(store, subject);
+        if (!(await store.claimCode(code)))
+            throw new types_js_1.ApiError(401, 'Invalid Auth Code');
+        // Re-exchanging a code for the same user and client while a valid pair
+        // exists returns that pair: another tab holding the old tokens must not be
+        // signed out by a second exchange.
+        const existing = await store.pairFor(named);
+        if (existing)
+            return existing;
+        const pair = await store.issue(named, client);
+        await store.savePair(named, pair);
+        return pair;
+    },
+    async refresh(token) {
+        const subject = token === undefined ? undefined : await store.readRefresh(token);
+        if (!subject)
+            throw unauthorized();
+        const client = await store.client(subject.clientId);
+        if (!client)
+            throw new types_js_1.ApiError(401, 'Invalid clientId.');
+        const named = await liveSubject(store, subject);
+        const pair = await store.issue(named, client);
+        await store.savePair(named, pair);
+        return pair;
+    },
+    async logout(subject) {
+        if (!subject)
+            throw unauthorized();
+        // Deliberately no liveness check: the caller is asking for its credential to
+        // be dropped, and refusing would leave a pair in the store that nothing can
+        // use. Every path that READS the account refuses an inactive one, so a
+        // deactivated caller's sign-out is housekeeping rather than access.
+        await store.deletePair(subject);
+    },
+    async logoutSession() {
+        return 'OK!';
+    },
+    async session(subject) {
+        if (!subject)
+            throw unauthorized();
+        // As with `authorize`: the account behind a host's session is re-read here,
+        // because the session outlives the account.
+        const user = await store.userById(subject.userId);
+        if (!user || !user.isActive)
+            throw unauthorized();
+        return (0, exports.asSession)(user);
+    }
+});
+exports.createIdentityService = createIdentityService;
+/** A subject, as the session route reports it. */
+const asSession = (user) => ({
+    uid: user.uid,
+    username: user.username,
+    displayName: user.displayName,
+    isAdmin: user.isAdmin,
+    needsToUpdatePassword: user.needsToUpdatePassword
+});
+exports.asSession = asSession;

package/build/cjs/identity/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * The identity the API works over, as a host supplies it.
+ *
+ * A server holds users in a database, verifies a bcrypt hash and signs JWTs; a
+ * browser build holds a seeded fixture, compares a plain-text demo password and
+ * mints opaque strings. Those differences are the host's, so they live behind
+ * this port - the statuses, the messages and the order of the checks are the
+ * service's, and both hosts run the same corpus over them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/cjs/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.servicesFor = exports.runCase = exports.DRIVE_CORPUS = exports.HANDLED_ROUTES = exports.dispatch = exports.TAG_CAPABILITIES = exports.OVERLAY = exports.findRoute = exports.routeById = exports.ROUTES = exports.MemoryDriveStore = exports.createDriveService = exports.isRoot = exports.basename = exports.dirname = exports.hasBlockedExtension = exports.normaliseDrivePath = void 0;
+exports.servicesFor = exports.runCase = exports.IDENTITY_CORPUS = exports.DRIVE_CORPUS = exports.parseIdentity = exports.IDENTITY_FORMAT = exports.DEFAULT_IDENTITY = exports.MemoryIdentityStore = exports.createIdentityService = exports.HANDLED_ROUTES = exports.dispatch = exports.TAG_CAPABILITIES = exports.OVERLAY = exports.findRoute = exports.routeById = exports.ROUTES = exports.MemoryDriveStore = exports.createDriveService = exports.isRoot = exports.basename = exports.dirname = exports.hasBlockedExtension = exports.normaliseDrivePath = void 0;
 /**
  * `@sasjs/api` - the SASjs Server API described once.
  *
@@ -51,8 +51,18 @@ Object.defineProperty(exports, "TAG_CAPABILITIES", { enumerable: true, get: func
 var dispatch_js_1 = require("./host/dispatch.js");
 Object.defineProperty(exports, "dispatch", { enumerable: true, get: function () { return dispatch_js_1.dispatch; } });
 Object.defineProperty(exports, "HANDLED_ROUTES", { enumerable: true, get: function () { return dispatch_js_1.HANDLED_ROUTES; } });
+var service_js_2 = require("./identity/service.js");
+Object.defineProperty(exports, "createIdentityService", { enumerable: true, get: function () { return service_js_2.createIdentityService; } });
+var memory_store_js_2 = require("./identity/memory-store.js");
+Object.defineProperty(exports, "MemoryIdentityStore", { enumerable: true, get: function () { return memory_store_js_2.MemoryIdentityStore; } });
+var fixture_js_1 = require("./identity/fixture.js");
+Object.defineProperty(exports, "DEFAULT_IDENTITY", { enumerable: true, get: function () { return fixture_js_1.DEFAULT_IDENTITY; } });
+Object.defineProperty(exports, "IDENTITY_FORMAT", { enumerable: true, get: function () { return fixture_js_1.IDENTITY_FORMAT; } });
+Object.defineProperty(exports, "parseIdentity", { enumerable: true, get: function () { return fixture_js_1.parseIdentity; } });
 var drive_js_1 = require("./corpus/drive.js");
 Object.defineProperty(exports, "DRIVE_CORPUS", { enumerable: true, get: function () { return drive_js_1.DRIVE_CORPUS; } });
+var identity_js_1 = require("./corpus/identity.js");
+Object.defineProperty(exports, "IDENTITY_CORPUS", { enumerable: true, get: function () { return identity_js_1.IDENTITY_CORPUS; } });
 var runner_js_1 = require("./corpus/runner.js");
 Object.defineProperty(exports, "runCase", { enumerable: true, get: function () { return runner_js_1.runCase; } });
 Object.defineProperty(exports, "servicesFor", { enumerable: true, get: function () { return runner_js_1.servicesFor; } });

package/build/cjs/routes/generated.js

@@ -87,6 +87,10 @@ exports.GENERATED_ROUTES = [
             {
                 status: 204,
                 description: 'No content'
+            },
+            {
+                status: 401,
+                description: 'No valid access token was supplied'
             }
         ]
     },
@@ -102,6 +106,10 @@ exports.GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'The refresh token is missing, invalid or expired, or the client id is unknown'
             }
         ]
     },
@@ -130,6 +138,14 @@ exports.GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 400,
+                description: 'The request body is missing `clientId` or `code`'
+            },
+            {
+                status: 401,
+                description: 'The authorization code is invalid, expired, already used, or was issued for another client, or the client id is unknown'
             }
         ]
     },
@@ -158,6 +174,26 @@ exports.GENERATED_ROUTES = [
             {
                 status: 204,
                 description: 'No content'
+            },
+            {
+                status: 400,
+                description: 'The request body is missing `currentPassword` or `newPassword`'
+            },
+            {
+                status: 401,
+                description: 'No valid access token was supplied'
+            },
+            {
+                status: 403,
+                description: 'The current password is incorrect'
+            },
+            {
+                status: 404,
+                description: 'The authenticated user no longer exists'
+            },
+            {
+                status: 405,
+                description: 'The account authenticates through an external provider, which holds its password'
             }
         ]
     },
@@ -1071,6 +1107,10 @@ exports.GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 401,
+                description: 'No valid access token or session was supplied'
             }
         ]
     },
@@ -1554,6 +1594,18 @@ exports.GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 400,
+                description: 'The request body is missing `clientId`, or the CSRF token is missing or invalid'
+            },
+            {
+                status: 401,
+                description: 'No signed-in session'
+            },
+            {
+                status: 403,
+                description: 'The client id is unknown'
             }
         ]
     },
@@ -1582,6 +1634,22 @@ exports.GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 400,
+                description: 'The request body is missing `username` or `password`'
+            },
+            {
+                status: 401,
+                description: 'The credentials are not valid, or password sign-in is disabled for local accounts'
+            },
+            {
+                status: 429,
+                description: 'Too many failed attempts for this account'
+            },
+            {
+                status: 500,
+                description: 'An unexpected error occurred while signing in'
             }
         ]
     },
@@ -1597,6 +1665,10 @@ exports.GENERATED_ROUTES = [
             {
                 status: 200,
                 description: 'Ok'
+            },
+            {
+                status: 500,
+                description: 'The session store failed to replace the session'
             }
         ]
     }

package/build/cjs/routes/index.js

@@ -36,9 +36,15 @@ const merge = (generated) => {
             ...(body === undefined ? {} : { body })
         };
     });
+    // A host-only status has to be one the document states: the annotation marks
+    // where a status is answered, it does not add one.
+    for (const status of overlay.hostResponses || [])
+        if (!documented.has(status))
+            throw new Error(`src/routes/overlay.ts marks status ${status} of ${generated.id} as host-only, and the OpenAPI document does not state it. Correct the document in sasjs/server and re-vendor spec/swagger.yaml, or drop the annotation.`);
     return {
         ...generated,
         responses,
+        hostResponses: overlay.hostResponses || [],
         capabilities: overlay.capabilities || overlay_js_1.TAG_CAPABILITIES[generated.tag] || [],
         implemented: overlay.implemented === true
     };

package/build/cjs/routes/overlay.js

@@ -18,6 +18,13 @@ exports.TAG_CAPABILITIES = {
     Web: ['identity']
 };
 const success = { status: 'success' };
+const user = {
+    uid: '',
+    username: '',
+    displayName: '',
+    isAdmin: false,
+    needsToUpdatePassword: false
+};
 exports.OVERLAY = {
     // the route inventory reports what the CALLER may use, so it needs an identity
     // even though the rest of the Info tag needs nothing
@@ -69,6 +76,37 @@ exports.OVERLAY = {
     },
     'POST /SASjsApi/drive/deploy/upload': {
         implemented: false
+    },
+    // The lockout and the provider failure are answered before the package is
+    // consulted (routes/web/web.ts in sasjs/server).
+    'POST /SASLogon/login': {
+        implemented: true,
+        hostResponses: [429, 500],
+        responses: { 200: { loggedIn: true, user } }
+    },
+    // The sign-in flow. The statuses are the document's; these entries state the
+    // body a client keys on, and that this package answers the operation.
+    'POST /SASjsApi/auth/token': {
+        implemented: true,
+        responses: { 200: { accessToken: '', refreshToken: '' } }
+    },
+    'POST /SASjsApi/auth/refresh': {
+        implemented: true,
+        responses: { 200: { accessToken: '', refreshToken: '' } }
+    },
+    'POST /SASjsApi/auth/logout': { implemented: true },
+    'POST /SASLogon/authorize': {
+        implemented: true,
+        responses: { 200: { code: '' } }
+    },
+    'GET /SASLogon/logout': {
+        implemented: true,
+        hostResponses: [500],
+        responses: { 200: 'OK!' }
+    },
+    'GET /SASjsApi/session': {
+        implemented: true,
+        responses: { 200: user }
     }
 };
 /** Every method the table may state, in the order a diff reads best. */

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

@@ -12,6 +12,7 @@
  * records each place the two disagree.
  */
 import type { ApiRequest } from '../host/dispatch.js';
+import type { IdentityFixture } from '../identity/fixture.js';
 export interface CorpusCase {
     /** Stable name, used as the test's title. */
     id: string;
@@ -20,6 +21,8 @@ export interface CorpusCase {
     description: string;
     /** Files the case starts from. */
     seed?: Record<string, string | Uint8Array>;
+    /** The identity the case starts from; the default fixture when omitted. */
+    identity?: IdentityFixture;
     request: ApiRequest;
     expect: {
         status: number;
@@ -27,6 +30,17 @@ export interface CorpusCase {
         contents?: string | Uint8Array;
         /** The refusal's message, where the case expects one. */
         error?: string;
+        /**
+         * The properties a body must carry, where the host mints the rest - a user's
+         * `uid` is the host's identifier, so a case pinning one would be pinning a
+         * fixture value into the contract.
+         */
+        partial?: Record<string, unknown>;
+        /**
+         * The properties a body must carry, where the values are the host's - a
+         * minted token is not a value a case can state.
+         */
+        keys?: string[];
     };
 }
 export declare const DRIVE_CORPUS: CorpusCase[];

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

@@ -1 +1 @@
-{"version":3,"file":"drive.d.ts","sourceRoot":"","sources":["../../../src/corpus/drive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAErD,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAA;IACV,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,CAAA;IAC1C,OAAO,EAAE,UAAU,CAAA;IACnB,MAAM,EAAE;QACN,MAAM,EAAE,MAAM,CAAA;QACd,IAAI,CAAC,EAAE,OAAO,CAAA;QACd,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;QAC9B,yDAAyD;QACzD,KAAK,CAAC,EAAE,MAAM,CAAA;KACf,CAAA;CACF;AAWD,eAAO,MAAM,YAAY,EAAE,UAAU,EA8SpC,CAAA"}
+{"version":3,"file":"drive.d.ts","sourceRoot":"","sources":["../../../src/corpus/drive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE7D,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAA;IACV,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,CAAA;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,eAAe,CAAA;IAC1B,OAAO,EAAE,UAAU,CAAA;IACnB,MAAM,EAAE;QACN,MAAM,EAAE,MAAM,CAAA;QACd,IAAI,CAAC,EAAE,OAAO,CAAA;QACd,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;QAC9B,yDAAyD;QACzD,KAAK,CAAC,EAAE,MAAM,CAAA;QACd;;;;WAIG;QACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACjC;;;WAGG;QACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAChB,CAAA;CACF;AAWD,eAAO,MAAM,YAAY,EAAE,UAAU,EA8SpC,CAAA"}

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

@@ -0,0 +1,17 @@
+/**
+ * The sign-in flow's conformance corpus.
+ *
+ * A case names an operation, the request a client would make, the identity the
+ * host starts from, and the answer the caller expects. Where the answer carries
+ * a value the host mints - a token, a code - the case states the properties
+ * instead, because the value is the host's and asserting it would pin one host's
+ * cryptography into the contract.
+ */
+import type { CorpusCase } from './drive.js';
+import { type IdentityFixture } from '../identity/fixture.js';
+/** The default fixture, plus a caller that is already signed in. */
+export declare const SIGNED_IN: IdentityFixture;
+/** The same identity, with the restricted user switched off. */
+export declare const DEACTIVATED: IdentityFixture;
+export declare const IDENTITY_CORPUS: CorpusCase[];
+//# sourceMappingURL=identity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../../src/corpus/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE/E,oEAAoE;AACpE,eAAO,MAAM,SAAS,EAAE,eA2BvB,CAAA;AAED,gEAAgE;AAChE,eAAO,MAAM,WAAW,EAAE,eAKzB,CAAA;AAUD,eAAO,MAAM,eAAe,EAAE,UAAU,EAkOvC,CAAA"}