@guardian/permissions-client 0.0.0-canary-20260722094505

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @guardian/permissions-client
+
+## 0.0.0-canary-20260722094505
+
+### 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/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@guardian/permissions-client",
+  "version": "0.0.0-canary-20260722094505",
+  "description": "Client for Guardian's permissions service",
+  "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",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:ci": "prettier --check \"src/**/*.ts\"",
+    "lint": "eslint src/** --ext .ts"
+  }
+}

package/src/index.ts

@@ -0,0 +1,124 @@
+import { S3 } from "@aws-sdk/client-s3";
+import { fromIni, fromNodeProviderChain } from "@aws-sdk/credential-providers";
+import type { PermissionsCache, PermissionWithUsers } from "./model";
+
+interface ClientConfig {
+  stage?: string;
+  region?: string;
+  bucket?: string;
+  file?: string;
+  cacheIntervalMs?: number;
+  isRunningLocally?: boolean;
+  localProfile?: string;
+}
+
+type PermissionsResult = {
+  allPermissions: PermissionsCache;
+  loadTime: number | null;
+};
+
+let permissionsResult: PermissionsResult = {
+  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);
+};
+
+export function init({
+  stage = "CODE",
+  region = "eu-west-1",
+  bucket = "permissions-cache",
+  file = "permissions.json",
+  cacheIntervalMs = 60_000, // 1 minute,
+  isRunningLocally = false,
+  localProfile = "workflow",
+}: ClientConfig = {}) {
+  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) as PermissionsCache;
+
+    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: string, userId: string) {
+    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: string) {
+    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/src/model.ts

@@ -0,0 +1,20 @@
+// TODO: should we have runtime type checking with zod, or just trust what's coming back from the bucket?
+
+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[];

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "@guardian/tsconfig/tsconfig.json",
+  "allowImportingTsExtensions": true,
+  "compilerOptions": {
+    "module": "esnext",
+    "types": [
+      "vitest/globals",
+      "node"
+    ],
+    "declaration": true,
+    "rootDir": "./src",
+    "outDir": "dist",
+    "declarationDir": "dist/declaration",
+  },
+  "include": ["src/**/*"],
+}