Skip to content

armgit / dub

Public Imported from GitHub
0

The modern link attribution platform. Loved by world-class engineering teams at Twilio, Zillow, Jobber, Vercel, Raycast, and more.

10.0 KB
Raw Blame
import { WorkspaceRole } from "@prisma/client";
import { PermissionAction } from "../rbac/permissions";
import { ResourceKey } from "../rbac/resources";

export const SCOPES = [
  "links.read",
  "links.write",
  "tags.read",
  "tags.write",
  "folders.read",
  "folders.write",
  "analytics.read",
  "domains.read",
  "domains.write",
  "workspaces.read",
  "workspaces.write",
  "webhooks.read",
  "webhooks.write",
  "customers.read",
  "customers.write",
  "apis.all", // All API scopes
  "apis.read", // All read scopes
] as const;

export type Scope = (typeof SCOPES)[number];

// Scopes available for Workspace API keys
const RESOURCE_SCOPES: {
  scope: Scope;
  roles: WorkspaceRole[];
  permissions: PermissionAction[];
  type?: "read" | "write";
  resource?: ResourceKey;
}[] = [
  {
    scope: "links.read",
    roles: ["owner", "member", "viewer", "billing"],
    permissions: ["links.read"],
    type: "read",
    resource: "links",
  },
  {
    scope: "links.write",
    roles: ["owner", "member"],
    permissions: ["links.write", "links.read"],
    type: "write",
    resource: "links",
  },
  {
    scope: "tags.read",
    roles: ["owner", "member", "viewer", "billing"],
    permissions: ["tags.read"],
    type: "read",
    resource: "tags",
  },
  {
    scope: "tags.write",
    roles: ["owner", "member"],
    permissions: ["tags.write", "tags.read"],
    type: "write",
    resource: "tags",
  },
  {
    scope: "folders.read",
    roles: ["owner", "member", "viewer", "billing"],
    permissions: ["folders.read"],
    type: "read",
    resource: "folders",
  },
  {
    scope: "folders.write",
    roles: ["owner", "member"],
    permissions: ["folders.write", "folders.read"],
    type: "write",
    resource: "folders",
  },
  {
    scope: "domains.read",
    roles: ["owner", "member", "viewer", "billing"],
    permissions: ["domains.read"],
    type: "read",
    resource: "domains",
  },
  {
    scope: "domains.write",
    roles: ["owner"],
    permissions: ["domains.write", "domains.read"],
    type: "write",
    resource: "domains",
  },
  {
    scope: "customers.read",
    roles: ["owner", "member", "viewer", "billing"],
    permissions: ["customers.read"],
    type: "read",
    resource: "customers",
  },
  {
    scope: "customers.write",
    roles: ["owner", "member"],
    permissions: ["customers.write", "customers.read"],
    type: "write",
    resource: "customers",
  },
  {
    scope: "workspaces.read",
    roles: ["owner", "member", "viewer", "billing"],
    permissions: ["workspaces.read"],
    type: "read",
    resource: "workspaces",
  },
  {
    scope: "workspaces.write",
    roles: ["owner"],
    permissions: ["workspaces.write", "workspaces.read"],
    type: "write",
    resource: "workspaces",
  },
  {
    scope: "analytics.read",
    roles: ["owner", "member", "viewer", "billing"],
    permissions: ["analytics.read"],
    type: "read",
    resource: "analytics",
  },
  {
    scope: "webhooks.read",
    roles: ["owner", "member", "viewer", "billing"],
    permissions: ["webhooks.read"],
    type: "read",
    resource: "webhooks",
  },
  {
    scope: "webhooks.write",
    roles: ["owner"],
    permissions: ["webhooks.write", "webhooks.read"],
    type: "write",
    resource: "webhooks",
  },
  {
    scope: "apis.read",
    roles: ["owner", "member", "viewer", "billing"],
    permissions: [
      "links.read",
      "tags.read",
      "folders.read",
      "domains.read",
      "workspaces.read",
      "analytics.read",
      "customers.read",
    ],
  },
  {
    scope: "apis.all",
    roles: ["owner", "member"],
    permissions: [
      "links.read",
      "links.write",
      "tags.read",
      "tags.write",
      "folders.read",
      "folders.write",
      "domains.read",
      "domains.write",
      "workspaces.read",
      "workspaces.write",
      "analytics.read",
      "customers.read",
      "customers.write",
    ],
  },
];

export type LegacyScopeGrant = {
  enforcedAt: Date;
  permissions: readonly PermissionAction[];
};

// Keys and OAuth installations created before this date were made before the
// customer scopes existed.
export const CUSTOMER_SCOPES_ENFORCED_AT = new Date("2026-10-13T18:35:00.000Z");

// Scopes introduced after API keys already existed. A key or OAuth installation
// created before `enforcedAt` keeps these permissions without selecting the scope.
// Keep permissions that share a cutoff in one entry. Add a new entry when a
// scope needs a different cutoff.
export const LEGACY_SCOPE_GRANTS: LegacyScopeGrant[] = [
  {
    enforcedAt: CUSTOMER_SCOPES_ENFORCED_AT,
    permissions: ["customers.read", "customers.write"],
  },
];

// Scope to permissions mapping
const SCOPE_PERMISSIONS_MAP = RESOURCE_SCOPES.reduce((acc, scope) => {
  acc[scope.scope] = scope.permissions;
  return acc;
}, {});

// WorkspaceRole to scopes mapping
const ROLE_SCOPES_MAP = RESOURCE_SCOPES.reduce((acc, scope) => {
  scope.roles.forEach((role) => {
    if (!acc[role]) {
      acc[role] = [];
    }

    acc[role].push(scope.scope);
  });

  return acc;
}, {});

// For each scope, get the permissions it grants access to and return array of permissions
export const mapScopesToPermissions = (scopes: Scope[]) => {
  const permissions: PermissionAction[] = [];

  scopes.forEach((scope) => {
    if (SCOPE_PERMISSIONS_MAP[scope]) {
      permissions.push(...SCOPE_PERMISSIONS_MAP[scope]);
    }
  });

  return permissions;
};

// Grants permissions from `grants` when the key or installation predates the
// grant's cutoff. A missing date is treated as legacy so cached tokens from
// before this field existed keep working. Routes can pass extra grants that
// apply only to that route.
export const grantLegacyScopePermissions = ({
  permissions,
  createdAt,
  grants = LEGACY_SCOPE_GRANTS,
}: {
  permissions: PermissionAction[];
  createdAt?: Date | string | null;
  grants?: readonly LegacyScopeGrant[];
}): PermissionAction[] => {
  const createdAtMs = createdAt == null ? null : new Date(createdAt).getTime();

  const legacyPermissions = grants.flatMap((grant) =>
    createdAtMs != null && createdAtMs >= grant.enforcedAt.getTime()
      ? []
      : grant.permissions,
  );

  if (legacyPermissions.length === 0) {
    return permissions;
  }

  return [...new Set<PermissionAction>([...permissions, ...legacyPermissions])];
};

// Get SCOPES_BY_RESOURCE based on user role in a workspace
export const getScopesByResourceForRole = (role: WorkspaceRole) => {
  const groupedByResource = {};

  const allowedScopes = RESOURCE_SCOPES.map((scope) => {
    if (scope.roles.includes(role)) {
      return scope;
    }
  }).filter(Boolean);

  allowedScopes.forEach((scope) => {
    if (scope && scope.resource) {
      if (!groupedByResource[scope.resource]) {
        groupedByResource[scope.resource] = [];
      }

      groupedByResource[scope.resource].push(scope);
    }
  });

  return groupedByResource;
};

export const scopePresets = [
  {
    value: "all_access",
    label: "All",
    description: "full access to all resources",
  },
  {
    value: "read_only",
    label: "Read Only",
    description: "read-only access to all resources",
  },
  {
    value: "restricted",
    label: "Restricted",
    description: "restricted access to some resources",
  },
];

export const scopesToName = (scopes: string[]) => {
  if (scopes.includes("apis.all")) {
    return {
      name: "All access",
      description: "full access to all resources",
    };
  }

  if (scopes.includes("apis.read")) {
    return {
      name: "Read-only",
      description: "read-only access to all resources",
    };
  }

  return {
    name: "Restricted",
    description: "restricted access to some resources",
  };
};

export const validateScopesForRole = (scopes: Scope[], role: WorkspaceRole) => {
  const allowedScopes = ROLE_SCOPES_MAP[role];
  const invalidScopes = scopes.filter(
    (scope) => !allowedScopes.includes(scope),
  );

  return !(invalidScopes.length > 0);
};

// Get the scopes for a role
const getScopesForRole = (role: WorkspaceRole) => {
  return ROLE_SCOPES_MAP[role];
};

// Consolidate scopes to avoid duplication and show only the most permissive scope
const consolidateScopes = (scopes: string[]) => {
  const consolidated = new Set();

  scopes.forEach((scope) => {
    const [resource, action] = scope.split(".");

    if (action === "write") {
      consolidated.add(`${resource}.write`);
    } else if (action === "read" && !consolidated.has(`${resource}.write`)) {
      consolidated.add(`${resource}.read`);
    }
  });

  return Array.from(consolidated) as string[];
};

const isScopeGrantedForRole = ({
  scope,
  role,
}: {
  scope: string;
  role: WorkspaceRole;
}) => {
  const scopesForRole: string[] = getScopesForRole(role) ?? [];

  return scope === "user.read" || scopesForRole.includes(scope);
};

// Scopes that can be granted for the given role (intersection with requested)
export const getGrantedScopesForRole = ({
  scopes,
  role,
}: {
  scopes: string[];
  role: WorkspaceRole;
}) => {
  return scopes.filter((scope) =>
    isScopeGrantedForRole({
      scope,
      role,
    }),
  );
};

// Requested scopes the role cannot grant (raw intersection, same basis as grant)
export const getMissingScopesForRole = ({
  scopes,
  role,
}: {
  scopes: string[];
  role: WorkspaceRole;
}) => {
  return scopes.filter((scope) => !isScopeGrantedForRole({ scope, role }));
};

// Consent rows: consolidate granted and missing separately so a granted
// `{resource}.read` is still shown when `{resource}.write` is denied.
export const getDisplayedScopesForRole = ({
  scopes,
  role,
}: {
  scopes: string[];
  role: WorkspaceRole;
}) => {
  const grantedScopes = consolidateScopes(
    getGrantedScopesForRole({ scopes, role }),
  );

  const missingScopes = consolidateScopes(
    getMissingScopesForRole({ scopes, role }),
  );

  const order = new Map(scopes.map((scope, index) => [scope, index]));

  return [
    ...grantedScopes.map((scope) => ({ scope, missing: false })),
    ...missingScopes.map((scope) => ({ scope, missing: true })),
  ].sort(
    (a, b) =>
      (order.get(a.scope) ?? Infinity) - (order.get(b.scope) ?? Infinity),
  );
};