@digibuffer/access 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/catalog.js

@@ -0,0 +1,55 @@
+/**
+ * Every permission a DigiBuffer app checks, and what it means. Workflow draws its role screens from this list;
+ * each app checks its own with can(). A permission is either company-wide ("company") or for one product at a
+ * time ("product": its grant lists the products, by their app name such as "conepic").
+ *
+ * Adding one: add it here, bump the version, publish, then use it in the app. Never rename one in place: add the
+ * new name, move the apps, then remove the old.
+ */
+export const apps = Object.freeze({
+  billing: "Billing",
+  supportdesk: "Supportdesk",
+  digichat: "DigiChat",
+  knowledgehub: "KnowledgeHub",
+  digimail: "DigiMail",
+  digimarket: "DigiMarket",
+  digisender: "DigiSender",
+  preview: "Cloud Preview",
+  agentworkflows: "Agent Workflows",
+});
+
+/** @type {Readonly<Record<string, { app: keyof typeof apps; label: string; description: string; scope: "company" | "product" }>>} */
+export const catalog = Object.freeze({
+  "billing.customers.view": { app: "billing", scope: "product", label: "See customers and payments", description: "Customers, plans, payments, invoices and credits." },
+  "billing.refunds.request": { app: "billing", scope: "product", label: "Request refunds", description: "Ask for a refund; someone who can approve refunds does it." },
+  "billing.refunds.approve": { app: "billing", scope: "product", label: "Approve refunds and change plans", description: "Refund, give or end plans, credits, grants and private offers." },
+  "billing.catalog.manage": { app: "billing", scope: "company", label: "Plans and prices", description: "Plans, prices, products and bundles." },
+  "billing.revenue.view": { app: "billing", scope: "company", label: "Revenue and GST", description: "Revenue, every invoice and the GST documents." },
+
+  "supportdesk.agent": { app: "supportdesk", scope: "product", label: "Support agent", description: "Take, assign and resolve tickets, be in the product's support channel, see the customer panel." },
+  "supportdesk.manage": { app: "supportdesk", scope: "product", label: "Run the support desk", description: "Help pages, chat on or off, the assistant and ticket routing." },
+
+  "digichat.admin": { app: "digichat", scope: "company", label: "DigiChat admin", description: "The admin page and deleting anyone's channel message." },
+  "digichat.channels.create": { app: "digichat", scope: "company", label: "Create channels", description: "Create channels (product and project channels come from Workflow)." },
+
+  "knowledgehub.admin": { app: "knowledgehub", scope: "company", label: "KnowledgeHub admin", description: "Assistants, storage and every space." },
+
+  "digimail.admin": { app: "digimail", scope: "company", label: "DigiMail admin", description: "Domains, backups, setup and shared mailboxes." },
+
+  "digimarket.leads.view": { app: "digimarket", scope: "product", label: "See leads", description: "Leads, events and call tasks." },
+  "digimarket.rules.manage": { app: "digimarket", scope: "product", label: "Manage event rules", description: "Event rules, event keys and Notify support team." },
+
+  "digisender.use": { app: "digisender", scope: "company", label: "Use DigiSender", description: "Sign in and send: campaigns, templates, contacts." },
+  "digisender.admin": { app: "digisender", scope: "company", label: "DigiSender admin", description: "Sending domains, providers, API keys and settings." },
+
+  "preview.use": { app: "preview", scope: "company", label: "Use Cloud Preview", description: "Sign in; previews of the Workflow projects they're on." },
+  "preview.admin": { app: "preview", scope: "company", label: "Cloud Preview admin", description: "Every project's previews, servers, registries and placement." },
+
+  "agentworkflows.use": { app: "agentworkflows", scope: "company", label: "Use Agent Workflows", description: "Sign in and build and run their own workflows." },
+  "agentworkflows.admin": { app: "agentworkflows", scope: "company", label: "Agent Workflows admin", description: "Shared MCP servers, models, API keys and everyone's runs." },
+});
+
+export const isPermission = (name) => typeof name === "string" && Object.prototype.hasOwnProperty.call(catalog, name);
+
+/** The catalog's permissions for one app */
+export const permissionsOf = (app) => Object.keys(catalog).filter((p) => catalog[p].app === app);

package/index.d.ts

@@ -0,0 +1,26 @@
+export type AppKey = "billing" | "supportdesk" | "digichat" | "knowledgehub" | "digimail" | "digimarket" | "digisender" | "preview" | "agentworkflows";
+export type Permission =
+  | "billing.customers.view" | "billing.refunds.request" | "billing.refunds.approve" | "billing.catalog.manage" | "billing.revenue.view"
+  | "supportdesk.agent" | "supportdesk.manage"
+  | "digichat.admin" | "digichat.channels.create"
+  | "knowledgehub.admin"
+  | "digimail.admin"
+  | "digimarket.leads.view" | "digimarket.rules.manage"
+  | "digisender.use" | "digisender.admin"
+  | "preview.use" | "preview.admin"
+  | "agentworkflows.use" | "agentworkflows.admin";
+
+export interface PermissionInfo { app: AppKey; label: string; description: string; scope: "company" | "product" }
+/** Permission → products ("*" for all) */
+export type Access = Partial<Record<Permission, string[]>>;
+
+export declare const ALL: "*";
+export declare const apps: Readonly<Record<AppKey, string>>;
+export declare const catalog: Readonly<Record<Permission, PermissionInfo>>;
+export declare function isPermission(name: unknown): name is Permission;
+export declare function permissionsOf(app: AppKey): Permission[];
+export declare function parseAccess(claim: unknown): Access;
+export declare function can(who: { access?: Access | null } | Access | null | undefined, permission: Permission, product?: string): boolean;
+export declare function productsWith(who: { access?: Access | null } | Access | null | undefined, permission: Permission): "*" | string[];
+export declare function forApp(access: unknown, app: AppKey): Access;
+export declare function isReduced(before: unknown, after: unknown): boolean;

package/index.js

@@ -0,0 +1,84 @@
+import { catalog, isPermission } from "./catalog.js";
+
+export { apps, catalog, isPermission, permissionsOf } from "./catalog.js";
+
+/** Every product: a company-wide permission is granted as ["*"] */
+export const ALL = "*";
+
+const SLUG = /^[a-z0-9][a-z0-9-]{0,62}$/;
+
+/**
+ * The access claim as an app received it from BufferID, made safe to keep in a session: only known permissions,
+ * each with a list of product names (or "*"). Anything else is dropped. Never throws.
+ * @param {unknown} claim
+ * @returns {Record<string, string[]>}
+ */
+export function parseAccess(claim) {
+  /** @type {Record<string, string[]>} */
+  const out = {};
+  if (!claim || typeof claim !== "object" || Array.isArray(claim)) return out;
+  for (const [name, value] of Object.entries(claim)) {
+    if (!isPermission(name) || !Array.isArray(value)) continue;
+    const products = [...new Set(value.filter((v) => typeof v === "string" && (v === ALL || SLUG.test(v))))];
+    if (!products.length) continue;
+    out[name] = products.includes(ALL) ? [ALL] : products.sort();
+  }
+  return out;
+}
+
+/**
+ * May they? Nothing unless granted: an unknown permission, a missing grant or an empty session is no.
+ * A product permission needs the product (or "*"); a company permission needs "*".
+ * @param {{ access?: Record<string, string[]> | null } | Record<string, string[]> | null | undefined} who  a session holding `access`, or the access itself
+ * @param {string} permission
+ * @param {string} [product]
+ */
+export function can(who, permission, product) {
+  if (!isPermission(permission)) return false;
+  const access = accessOf(who);
+  const granted = access?.[permission];
+  if (!Array.isArray(granted) || !granted.length) return false;
+  if (granted.includes(ALL)) return true;
+  if (catalog[permission].scope === "company") return false;
+  return typeof product === "string" && product !== ALL && granted.includes(product);
+}
+
+/**
+ * The products they have a permission for: "*" for all, else the names (empty: none).
+ * @returns {"*" | string[]}
+ */
+export function productsWith(who, permission) {
+  if (!isPermission(permission)) return [];
+  const granted = accessOf(who)?.[permission];
+  if (!Array.isArray(granted)) return [];
+  return granted.includes(ALL) ? ALL : [...granted];
+}
+
+/** Only one app's permissions (what BufferID hands that app) */
+export function forApp(access, app) {
+  const all = parseAccess(access);
+  return Object.fromEntries(Object.entries(all).filter(([p]) => catalog[p].app === app));
+}
+
+/**
+ * Did they lose anything between two grants? (A permission gone, or a product gone from one.) Then they're signed
+ * out; additions wait for the next sign-in.
+ */
+export function isReduced(before, after) {
+  const a = parseAccess(before);
+  const b = parseAccess(after);
+  for (const [p, products] of Object.entries(a)) {
+    const now = b[p];
+    if (!now) return true;
+    if (now.includes(ALL)) continue;
+    if (products.includes(ALL)) return true;
+    if (products.some((x) => !now.includes(x))) return true;
+  }
+  return false;
+}
+
+function accessOf(who) {
+  if (!who || typeof who !== "object") return null;
+  if ("access" in who) return /** @type {any} */ (who).access ?? null;
+  return /** @type {Record<string, string[]>} */ (who);
+}

package/package.json

@@ -1,6 +1,18 @@
 {
   "name": "@digibuffer/access",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "DigiBuffer staff permissions: the catalog every app shares and the can() check. Holds no secrets and no list of who has what.",
+  "version": "0.2.0",
+  "type": "module",
+  "files": ["index.js", "index.d.ts", "catalog.js", "README.md"],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": { "types": "./index.d.ts", "import": "./index.js", "default": "./index.js" }
+  },
+  "sideEffects": false,
+  "scripts": { "test": "node --test test/*.test.js" },
+  "keywords": ["digibuffer", "permissions", "access"],
+  "license": "UNLICENSED",
+  "author": "Dilip",
+  "repository": { "type": "git", "url": "git+https://github.com/Digibuffer/upload-lib.git", "directory": "packages/access" },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" }
+}