@guardian/permissions-client 0.0.0 → 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @guardian/permissions-client
+
+## 0.0.1
+
+### Patch Changes
+
+- fbf5e70: Initial release for @guardian/permissions-client

package/LICENSE

@@ -0,0 +1,8 @@
+This software is licensed under the Apache 2 license, quoted below.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with
+the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
+language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,30 @@
+# `@guardian/permissions-client`
+
+Client for reading Guardian user permissions data in Node.js backends
+
+## Installation
+
+```bash
+npm install @guardian/permissions-client
+```
+
+or
+
+```bash
+pnpm add @guardian/permissions-client
+```
+
+(`@aws-sdk/client-s3` and `@aws-sdk/credential-providers` must also be installed)
+
+## Usage
+
+```js
+import { init } from "@guardian/permissions-client";
+
+const { hasPermission } = init({ isRunningLocally: true });
+
+const doesLiamHaveGridAccess = await hasPermission(
+  "grid_access",
+  "liam.duffy@guardian.co.uk",
+);
+```

package/package.json

@@ -1,27 +1,31 @@
 {
-	"name": "@guardian/permissions-client",
-	"version": "0.0.0",
-	"description": "Client for Guardian's permissions service",
-	"scripts": {
-		"build": "tsc",
-		"test": "echo \"Error: no test specified\" && exit 1",
-		"format": "prettier --write \"src/**/*.ts\"",
-		"format:ci": "prettier --check \"src/**/*.ts\"",
-		"lint": "eslint src/** --ext .ts"
-	},
-	"type": "module",
-	"exports": {
-		".": {
-			"import": "./dist/index.js",
-			"types": "./dist/declaration/index.d.ts"
-		}
-	},
-	"devDependencies": {
-		"@aws-sdk/client-s3": "3.1090.0",
-		"@aws-sdk/credential-providers": "^3.1090.0"
-	},
-	"peerDependencies": {
-		"@aws-sdk/client-s3": "^3.1090.0",
-		"@aws-sdk/credential-providers": "^3.1090.0"
-	}
-}
+  "name": "@guardian/permissions-client",
+  "version": "0.0.1",
+  "description": "Client for Guardian's permissions service",
+  "repository": {
+    "url": "https://github.com/guardian/permissions",
+    "directory": "node-client"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/declaration/index.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "3.1090.0",
+    "@aws-sdk/credential-providers": "^3.1090.0"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": "^3.1090.0",
+    "@aws-sdk/credential-providers": "^3.1090.0"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.emit.json",
+    "test": "node --test --experimental-test-module-mocks src/**/*.test.ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:ci": "prettier --check \"src/**/*.ts\"",
+    "lint": "eslint src/** --ext .ts"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,181 @@
+import assert from "node:assert";
+import { randomUUID } from "node:crypto";
+import { mock, test } from "node:test";
+import type * as ClientModule from "./index.ts";
+import type { PermissionsCache } from "./model.ts";
+
+const mockPermissionsCache: PermissionsCache = [
+  {
+    permission: {
+      name: "permission1",
+      app: "app1",
+      defaultValue: false,
+    },
+    overrides: [
+      {
+        userId: "user1",
+        active: true,
+        isCasualNotOnShift: false,
+      },
+      {
+        userId: "user2",
+        active: false,
+        isCasualNotOnShift: true,
+      },
+      {
+        userId: "user3",
+        active: true,
+        isCasualNotOnShift: true,
+      },
+    ],
+  },
+  {
+    permission: {
+      name: "permission2",
+      app: "app1",
+      defaultValue: false,
+    },
+    overrides: [
+      {
+        userId: "user1",
+        active: true,
+        isCasualNotOnShift: false,
+      },
+      {
+        userId: "user2",
+        active: true,
+        isCasualNotOnShift: false,
+      },
+      {
+        userId: "user3",
+        active: false,
+        isCasualNotOnShift: false,
+      },
+    ],
+  },
+];
+
+let currentMockPermissionsCache = mockPermissionsCache;
+
+const originalCredentialProviders =
+  await import("@aws-sdk/credential-providers");
+
+mock.module("@aws-sdk/credential-providers", {
+  exports: {
+    ...originalCredentialProviders,
+    fromNodeProviderChain: () => () => Promise.resolve({}),
+  },
+});
+
+const originalClientS3 = await import("@aws-sdk/client-s3");
+
+mock.module("@aws-sdk/client-s3", {
+  exports: {
+    ...originalClientS3,
+    S3: class {
+      getObject() {
+        return Promise.resolve({
+          Body: {
+            transformToString: () =>
+              Promise.resolve(JSON.stringify(currentMockPermissionsCache)),
+          },
+        });
+      }
+    },
+  },
+});
+
+// This is required to get a fresh instance of the module for each test, with a new cache state.
+const importIndex = () =>
+  import(`./index.ts?cache-bust=${randomUUID()}`) as Promise<
+    typeof ClientModule
+  >;
+
+test("hasPermission() returns true for a user with active: true in overrides", async () => {
+  const { init } = await importIndex();
+  const client = init();
+  const result = await client.hasPermission("permission1", "user1");
+
+  assert.equal(result, true);
+});
+
+test("hasPermission() returns false for a user with active: false in overrides", async () => {
+  const { init } = await importIndex();
+  const client = init();
+  const result = await client.hasPermission("permission1", "user2");
+
+  assert.equal(result, false);
+});
+
+test("hasPermission() returns false for a user who is not present in overrides", async () => {
+  const { init } = await importIndex();
+  const client = init();
+  const result = await client.hasPermission("permission1", "user9001");
+
+  assert.equal(result, false);
+});
+
+test("hasPermission() returns false for a user with active: true but isCasualNotOnShift: true in overrides", async () => {
+  const { init } = await importIndex();
+  const client = init();
+  const result = await client.hasPermission("permission1", "user3");
+
+  assert.equal(result, false);
+});
+
+test("hasPermission() returns the latest permission information when the cache expires", async () => {
+  mock.timers.enable();
+
+  const { init } = await importIndex();
+  const client = init();
+  const result = await client.hasPermission("permission1", "user1");
+  assert.equal(result, true);
+
+  const updatedPermissionsCache: PermissionsCache = [
+    {
+      permission: {
+        name: "permission1",
+        app: "app1",
+        defaultValue: false,
+      },
+      overrides: [
+        {
+          userId: "user1",
+          active: false,
+          isCasualNotOnShift: false,
+        },
+      ],
+    },
+  ];
+
+  currentMockPermissionsCache = updatedPermissionsCache;
+
+  mock.timers.tick(30_000);
+
+  const resultAfter30Seconds = await client.hasPermission(
+    "permission1",
+    "user1",
+  );
+  assert.equal(resultAfter30Seconds, true);
+
+  mock.timers.tick(30_001);
+  const resultAfter60Seconds = await client.hasPermission(
+    "permission1",
+    "user1",
+  );
+  assert.equal(resultAfter60Seconds, false);
+
+  // Reset to original state
+  currentMockPermissionsCache = mockPermissionsCache;
+});
+
+test("listPermissions() returns list of valid permissions for user", async () => {
+  const { init } = await importIndex();
+  const client = init();
+  const user1Result = await client.listPermissions("user1");
+  assert.deepEqual(user1Result, ["permission1", "permission2"]);
+  const user2Result = await client.listPermissions("user2");
+  assert.deepEqual(user2Result, ["permission2"]);
+  const user3Result = await client.listPermissions("user3");
+  assert.deepEqual(user3Result, []);
+});

package/src/index.ts

@@ -1,6 +1,11 @@
 import { S3 } from "@aws-sdk/client-s3";
 import { fromIni, fromNodeProviderChain } from "@aws-sdk/credential-providers";
-import type { PermissionsCache, PermissionWithUsers } from "./model";
+import type {
+  NormalisedPermissionsCache,
+  PermissionsCache,
+  UserEntry,
+} from "./model.ts";
+import { normalisePermissionsCache } from "./normalise.ts";
 
 interface ClientConfig {
   stage?: string;
@@ -13,25 +18,19 @@ interface ClientConfig {
 }
 
 type PermissionsResult = {
-  allPermissions: PermissionsCache;
+  allPermissions: NormalisedPermissionsCache;
   loadTime: number | null;
 };
 
 let permissionsResult: PermissionsResult = {
-  allPermissions: [],
+  allPermissions: {},
   loadTime: null,
 };
 let permissionsRequest: Promise<PermissionsResult> =
   Promise.resolve(permissionsResult);
 
-const permissionValidForUser = (
-  permission: PermissionWithUsers,
-  userId: string,
-) => {
-  const userOverride = permission.overrides.find((o) => o.userId === userId);
-
-  return !!(userOverride?.active && !userOverride.isCasualNotOnShift);
-};
+const permissionValidForUser = (userEntry: UserEntry) =>
+  !!(userEntry.active && !userEntry.isCasualNotOnShift);
 
 export function init({
   stage = "CODE",
@@ -62,16 +61,18 @@ export function init({
     }
 
     const transformedBody = await Body.transformToString();
-    const allPermissions = JSON.parse(transformedBody) as PermissionsCache;
+    const permissionsCache = JSON.parse(transformedBody) as PermissionsCache;
+    const allPermissions = normalisePermissionsCache(permissionsCache);
 
     return { allPermissions, loadTime: Date.now() };
   }
 
   async function getOrRefresh() {
     const latestResult = await permissionsRequest;
-    const cacheExpired = latestResult.loadTime
-      ? Date.now() > latestResult.loadTime + cacheIntervalMs
-      : true;
+    const cacheExpired =
+      latestResult.loadTime !== null
+        ? Date.now() > latestResult.loadTime + cacheIntervalMs
+        : true;
 
     if (cacheExpired) {
       try {
@@ -90,23 +91,16 @@ export function init({
 
   async function hasPermission(permissionName: string, userId: string) {
     const permissionsCache = await getOrRefresh();
-    const permissionData = permissionsCache.find(
-      (p) => p.permission.name === permissionName,
-    );
+    const userEntry = permissionsCache[userId]?.[permissionName];
 
-    if (!permissionData) {
-      throw Error(`Permission data for "${permissionName}" not found`);
-    }
-
-    return permissionValidForUser(permissionData, userId);
+    return userEntry ? permissionValidForUser(userEntry) : false;
   }
 
   async function listPermissions(userId: string) {
     const permissionsCache = await getOrRefresh();
-
-    return permissionsCache
-      .filter((p) => permissionValidForUser(p, userId))
-      .map((p) => p.permission.name);
+    return Object.entries(permissionsCache[userId] ?? {})
+      .filter(([, userEntry]) => permissionValidForUser(userEntry))
+      .flatMap(([permissionName]) => permissionName);
   }
 
   function storeIsEmpty() {

package/src/model.ts

@@ -1,6 +1,5 @@
-// TODO: should we have runtime type checking with zod, or just trust what's coming back from the bucket?
-
-interface UserSetting {
+// Types from S3
+interface UserOverride {
   userId: string;
   active: boolean;
   isCasualNotOnShift: boolean;
@@ -12,9 +11,30 @@ interface PermissionDefinition {
   defaultValue: boolean;
 }
 
-export interface PermissionWithUsers {
+interface PermissionWithOverrides {
   permission: PermissionDefinition;
-  overrides: UserSetting[];
+  overrides: UserOverride[];
+}
+
+export type PermissionsCache = PermissionWithOverrides[];
+
+// Normalised types
+export interface UserEntry {
+  permission: PermissionDefinition;
+  active: boolean;
+  isCasualNotOnShift: boolean;
 }
 
-export type PermissionsCache = PermissionWithUsers[];
+/**
+ * I would find an interface more readable here than a record, but @typescript-eslint/consistent-indexed-object-style says no
+ * Here's what it would look like as an interface, with named types for the keys
+ * interface NormalisedPermissionsCache {
+ *   [userId: string]: {
+ *     [permissionName: string]: UserEntry;
+ *   }
+ * }
+ */
+export type NormalisedPermissionsCache = Record<
+  string,
+  Record<string, UserEntry>
+>;

package/src/normalise.ts

@@ -0,0 +1,20 @@
+import type { NormalisedPermissionsCache, PermissionsCache } from "./model.ts";
+
+// Invert shape of permissions cache, so we can look up permissions data without looping
+export const normalisePermissionsCache = (
+  permissionsCache: PermissionsCache,
+): NormalisedPermissionsCache => {
+  return permissionsCache.reduce<NormalisedPermissionsCache>((acc, p) => {
+    const { permission, overrides } = p;
+    overrides.forEach(({ userId, active, isCasualNotOnShift }) => {
+      acc[userId] ??= {};
+      acc[userId][permission.name] = {
+        permission,
+        active,
+        isCasualNotOnShift,
+      };
+    });
+
+    return acc;
+  }, {});
+};

package/tsconfig.emit.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["src/**/*.test.ts"]
+}

package/tsconfig.json

@@ -2,15 +2,19 @@
   "extends": "@guardian/tsconfig/tsconfig.json",
   "allowImportingTsExtensions": true,
   "compilerOptions": {
-    "module": "esnext",
+    "target": "esnext",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
     "types": [
       "vitest/globals",
       "node"
     ],
-    "declaration": true,
     "rootDir": "./src",
     "outDir": "dist",
+    "declaration": true,
     "declarationDir": "dist/declaration",
+    "rewriteRelativeImportExtensions": true,
+    "erasableSyntaxOnly": true,
   },
   "include": ["src/**/*"],
 }

package/dist/declaration/index.d.ts

@@ -1,16 +0,0 @@
-interface ClientConfig {
-    stage?: string;
-    region?: string;
-    bucket?: string;
-    file?: string;
-    cacheIntervalMs?: number;
-    isRunningLocally?: boolean;
-    localProfile?: string;
-}
-export declare function init({ stage, region, bucket, file, cacheIntervalMs, // 1 minute,
-isRunningLocally, localProfile, }?: ClientConfig): {
-    hasPermission: (permissionName: string, userId: string) => Promise<boolean>;
-    listPermissions: (userId: string) => Promise<string[]>;
-    storeIsEmpty: () => boolean;
-};
-export {};

package/dist/declaration/model.d.ts

@@ -1,16 +0,0 @@
-interface UserSetting {
-    userId: string;
-    active: boolean;
-    isCasualNotOnShift: boolean;
-}
-interface PermissionDefinition {
-    name: string;
-    app: string;
-    defaultValue: boolean;
-}
-export interface PermissionWithUsers {
-    permission: PermissionDefinition;
-    overrides: UserSetting[];
-}
-export type PermissionsCache = PermissionWithUsers[];
-export {};

package/dist/index.js

@@ -1,73 +0,0 @@
-import { S3 } from "@aws-sdk/client-s3";
-import { fromIni, fromNodeProviderChain } from "@aws-sdk/credential-providers";
-let permissionsResult = {
-    allPermissions: [],
-    loadTime: null,
-};
-let permissionsRequest = Promise.resolve(permissionsResult);
-const permissionValidForUser = (permission, userId) => {
-    const userOverride = permission.overrides.find((o) => o.userId === userId);
-    return !!(userOverride?.active && !userOverride.isCasualNotOnShift);
-};
-export function init({ stage = "CODE", region = "eu-west-1", bucket = "permissions-cache", file = "permissions.json", cacheIntervalMs = 60_000, // 1 minute,
-isRunningLocally = false, localProfile = "workflow", } = {}) {
-    const awsConfig = {
-        region,
-        credentials: isRunningLocally
-            ? fromIni({ profile: localProfile })
-            : fromNodeProviderChain(),
-    };
-    const s3 = new S3(awsConfig);
-    async function loadPermissions() {
-        const { Body } = await s3.getObject({
-            Bucket: bucket,
-            Key: `${stage}/${file}`,
-        });
-        if (!Body) {
-            throw Error("Could not fetch permissions");
-        }
-        const transformedBody = await Body.transformToString();
-        const allPermissions = JSON.parse(transformedBody);
-        return { allPermissions, loadTime: Date.now() };
-    }
-    async function getOrRefresh() {
-        const latestResult = await permissionsRequest;
-        const cacheExpired = latestResult.loadTime
-            ? Date.now() > latestResult.loadTime + cacheIntervalMs
-            : true;
-        if (cacheExpired) {
-            try {
-                permissionsRequest = loadPermissions();
-                permissionsResult = await permissionsRequest;
-            }
-            catch (error) {
-                console.error("Refreshing permissions cache failed with error, so keeping stale cache...", error);
-            }
-        }
-        return permissionsResult.allPermissions;
-    }
-    async function hasPermission(permissionName, userId) {
-        const permissionsCache = await getOrRefresh();
-        const permissionData = permissionsCache.find((p) => p.permission.name === permissionName);
-        if (!permissionData) {
-            throw Error(`Permission data for "${permissionName}" not found`);
-        }
-        return permissionValidForUser(permissionData, userId);
-    }
-    async function listPermissions(userId) {
-        const permissionsCache = await getOrRefresh();
-        return permissionsCache
-            .filter((p) => permissionValidForUser(p, userId))
-            .map((p) => p.permission.name);
-    }
-    function storeIsEmpty() {
-        return permissionsResult.loadTime === null;
-    }
-    // Run getOrRefresh() immediately after init so that the cache is populated and ready for use
-    void getOrRefresh();
-    return {
-        hasPermission,
-        listPermissions,
-        storeIsEmpty,
-    };
-}

package/dist/model.js

@@ -1,2 +0,0 @@
-// TODO: should we have runtime type checking with zod, or just trust what's coming back from the bucket?
-export {};